---
name: private-password-storage
description: Store or update a private password or credential in the device-local macOS Keychain through a native secure popup, and check presence without retrieval. Use when a user asks to save, store, update, or verify a private credential securely on a Mac.
---

# Private Password Storage

Use the bundled helper so the credential enters only through a native
`NSSecureTextField` and goes directly to Security.framework.

## Choose The Right Authentication Route

Prefer the provider's supported credential manager or login flow when one
exists. Keychain storage does not authenticate an application and cannot
satisfy OAuth, OTP, passkeys, browser sessions, or `gcloud` login by itself.

Never ask the user to paste a credential into chat.

## Store Or Update

Run `--store` only after the user asks to open the secure popup:

```bash
.agents/skills/private-password-storage/scripts/private-password-storage \
  --service "com.example.application" \
  --account "operator@example.invalid" \
  --label "Example application password" \
  --store
```

The popup accepts normal typing, Cmd+V, and right-click Paste. Empty input
stays in the popup and is rejected. A successful write prints only `stored`.
The item is stored as `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` with
synchronization disabled.

## Check Presence

```bash
.agents/skills/private-password-storage/scripts/private-password-storage \
  --service "com.example.application" \
  --account "operator@example.invalid" \
  --status
```

Status prints only `present` or `absent`. It never returns the credential.

## Safety Contract

- Keep the credential out of process arguments, shell variables, files,
  logs, screenshots, terminal output, clipboard writes, and proof artifacts.
- Do not add retrieval, reveal, echo, export, or fingerprint modes.
- Do not use AppleScript, `osascript`, System Events, `pbcopy`, or the
  `security add-generic-password` CLI.
- Treat service, account, and label as non-secret metadata; do not print them.
- Report only the helper status and whether a native popup was used.

## Sanitized Canary

Use only a generated fake value and a service beginning with
`dev.codex.private-password-storage.canary.` plus an account beginning with
`canary-`. The test-only `--delete-test-item` action is prefix-guarded and
deletes only that exact service/account pair. Verify `present`, delete the
exact item, then verify `absent`. Do not retain the fake value anywhere.