1Password secrets

Reckon uses one selected 1Password vault for every org. Each connection gets one API Credential item, titled <org> / <connection>, with a field for each saved credential. The nested tag reckon/<org>/<environment> organizes items in the 1Password apps. Connections spanning environments use reckon/<org>/shared.

Items are visible and editable in the normal 1Password UI. Reckon saves IDs in its local references, so renaming an item or editing its tags does not change which secret a connection uses. Moving an item to another vault requires relinking it. Tags organize items; they do not grant or restrict access.

Set up access to one vaultCopy Anchor Link

Install 1Password CLI version 2.41.0 or newer. On macOS:

brew install 1password-cli

Create a dedicated vault named Reckon in your 1Password account. Create two service accounts:

For both accounts, disable vault creation, grant no access to 1Password Environments, and omit sharing permissions. These permissions are chosen when creating the account and cannot be changed later. A replacement requires setup again. The built-in Personal, Private, Employee, and default Shared vaults cannot be used with service accounts.

Keep service-account token backups outside the Reckon vault. In particular, a writer-token item in that vault would be readable by the reader account. If you save a backup in 1Password, select a separate administrative vault that neither service account can access.

Save the tokens in your OS credential store. Never paste a token into chat or include it in command arguments. On macOS, these commands prompt privately because -w is the last option:

security add-generic-password -s reckon-1password-reader -a "$USER" -w
security add-generic-password -s reckon-1password-writer -a "$USER" -w

On Linux, use Secret Service and secret-tool:

secret-tool store --label='Reckon 1Password reader' service reckon-1password-reader
secret-tool store --label='Reckon 1Password writer' service reckon-1password-writer

Then configure Reckon with the vault's ID and the credential-store references:

reckon secrets setup --vault <vault-id> \
  --reader keychain:reckon-1password-reader \
  --writer keychain:reckon-1password-writer
reckon secrets status

Use --op /path/to/op if the CLI is not on PATH. Omit --writer for a read-only installation; adding it later requires setup with both references again. Setup checks that each token can see exactly the selected vault before saving configuration. It validates vault visibility; choose the item permissions and disable vault creation and Environment access in 1Password as described above.

The service account selects its own 1Password account. Reckon never uses desktop authentication, inherited OP_SESSION_*, Connect credentials, or an account selected in your shell as a fallback. Vault IDs also pin the account containing that vault.

Restart existing reckon open sessions after upgrading to refresh their generated permissions and remove inherited OP_* variables from the agent.

Save or update a credentialCopy Anchor Link

Create a normal connection and set its credentials:

reckon connect jenkins-prod --org acme --provider jenkins --for-env prod
reckon secrets set jenkins-prod JENKINS_USER --org acme --env prod
reckon secrets set jenkins-prod JENKINS_TOKEN --org acme --env prod

Each set shows the destination and asks for confirmation, then prompts for the value without echoing it. Production and shared connections require typing the org name. Other connections require yes. These commands run in your own terminal and are refused inside pinned agent sessions.

The first save creates acme / jenkins-prod in the selected vault with tag reckon/acme/prod. Later saves update the same item and preserve unrelated fields. Values travel to op as JSON through stdin, never in arguments or plaintext temporary files. Reckon reads back the remote fields before replacing local values with references:

JENKINS_URL=https://jenkins.acme.com
JENKINS_USER=op://<vault-id>/<item-id>/<field-id>
JENKINS_TOKEN=op://<vault-id>/<item-id>/<field-id>

Ordinary settings such as service URLs can stay local. Updating the saved token does not rotate the token at Jenkins or any other upstream service.

Link an existing itemCopy Anchor Link

reckon secrets link jenkins-prod JENKINS_TOKEN --org acme --env prod \
  --item <item-id> --field <field-id-or-label>

The existing item must be in the Reckon vault. Use section/field for a field inside a section. Reckon validates and canonicalizes the reference without renaming or retagging the item.

To overwrite a field in an externally managed API Credential item, use secrets set ... --update-linked and review the destination. Edit other item categories in the 1Password app; Reckon avoids JSON updates to Login items that may contain passkeys. Plain field references are fetched together. Derived references, such as ?attribute=otp, use a scoped op read and are edited in 1Password.

Check and runCopy Anchor Link

reckon secrets status --org acme
reckon secrets check jenkins-prod --org acme --env prod
reckon verify jenkins-prod --org acme --env prod
reckon run jenkins-prod --org acme --env prod -- job list

status inspects local configuration only. check retrieves the connection's referenced fields without printing values or contacting Jenkins. verify retrieves credentials and performs the provider's normal live check.

Each execution loads the reader token from the OS credential store and passes it only to the isolated op subprocess. Fields in one item use one item read per invocation. The resulting values go only into the connected tool's subprocess; captured output is redacted before display or storage. The agent and tool never inherit 1Password tokens, sessions, or Connect credentials. Approved writes use the same reader path for their connection credentials; the 1Password writer is used only by operator secret-management commands.

Reckon does not keep its own persistent plaintext secret cache. The CLI's native cache and configuration live under $RECKON_HOME/onepassword/runtime. Token fingerprints pin the scope validated during setup, so replacing an OS credential entry requires setup again. There is no vault-list request on every run.

Service accounts also work for scheduled routines. The OS credential store must be available to the account running the job. Expired tokens, a locked credential store, network failure, missing fields, and denied access stop execution without trying another credential source.

Measure lookup latencyCopy Anchor Link

To compare per-field lookups with batched item reads, use a test connection whose references point to a dummy item in the configured store:

reckon secrets benchmark jenkins-test --org acme --env dev --samples 5 --json

The native benchmark reports initial and subsequent lookup timings, median, p95, and CLI invocation counts. Both paths include OS credential-store lookups and use the configured reader only. The benchmark prints no values, refuses a token that can see more than the configured vault, and accepts 1–50 samples. Plain text and concealed fields are supported; derived references are excluded. Automated tests use a fake CLI and synthetic credentials. Their timings are not measurements of the live 1Password service.

Migrate plaintext settingsCopy Anchor Link

reckon secrets import jenkins-prod --org acme --env prod --dry-run
reckon secrets import jenkins-prod --org acme --env prod

The preview lists field names only. By default, import selects credential keys such as tokens and passwords. Use repeated --key options to include other settings, for example --key JENKINS_USER --key JENKINS_TOKEN.

Import saves fields, reads them back, and atomically replaces plaintext with references. It leaves the original file intact until verification succeeds and does not create additional plaintext backups. If local settings change during the operation, Reckon retains the remote item and stops before overwriting those edits. Existing Keychain references remain unchanged.

Existing op:// references now require this restricted-store setup. References outside the selected vault are refused. Names in older references are accepted within the configured vault; newly saved and linked references use IDs.

Recover interrupted operationsCopy Anchor Link

If a create request fails or is interrupted, Reckon records that it may have succeeded and refuses another automatic create. Run:

reckon secrets recover jenkins-prod --org acme --env prod

Reckon looks for the original title and tag inside its vault. If one item matches, you confirm its ID, then retry the original save or import command. If several match, inspect them in 1Password and use secrets link --item <id> to choose explicitly. If none match, recovery requires typing retry before permitting another create; an earlier timed-out request could still complete later.

If an item was saved but the local reference could not be written, retry against the recorded item or link the item ID reported by Reckon. Removing a connection never deletes its 1Password item. Token revocation, upstream rotation, and item deletion remain explicit operator actions in their respective services.

The vault is the 1Password permission boundary. Both service accounts can access all orgs stored there. Reckon's org/environment checks prevent accidental use of another connection; they are not an isolation boundary against a hostile process running as your OS user. Output redaction is best effort for transformed values.