Credentials and rotation

Identity uses several unrelated secrets. Rotate each through its own owner and validation path. Human logout does not revoke every machine credential or signing key.

• OIDC client secret: Used by a confidential application backend. Keep one client per environment in a server-side secret manager, with reviewed rotation.
• OIDC signing key: Used by the Go issuer. Store an owner-only RSA private file of at least 3072 bits, and publish the matching JWKS key ID. Multi-key rotation is a release gate.
• TOTP encryption and provider crypto keys: Used by the Go issuer. Keep distinct 32-byte keys outside source control.
• Passkey encryption key: Used by the Go issuer when enabled. Keep a separate 32-byte key and exact HTTPS relying-party origin.
• Lifecycle signing key: Used by the Management publisher. Keep it separate from OIDC signing. Consumers pin its ID and verify signed events and receipts.
• Lifecycle or attestation service identity: Used by a product backend. Use reviewed, project-scoped, renewed access. General issuance on the owned engine is still gated.
• Mail API key: Used by the Management worker. Use a dedicated Identity machine credential scoped to sending and the approved sender.

Controlled handoff for the owned issuer

The owned issuer uses an operator-controlled credential delivery tool. Its qualified Linux implementation verifies a signed custody intent and receipt, writes the credential to a protected owner-only file, confirms durability, and acknowledges the handoff. It keeps credential material out of browser responses and command output.

An uncertain acknowledgement requires fresh signed readback before deciding the outcome.

Connected delivery has passed a Linux acceptance run joining the actual Management intent API, Go delivery command and private writer over verified TLS and PostgreSQL. It verified audited intent creation and private retrieval, durable credential handoff and acknowledgement, fresh signed readback, credential leakage checks and completed application shutdown.

The owner and sponsorship facts were synthetic test fixtures, so this does not prove genuine human admission.

Reviewed installation and activation still require completion. A completed custody handoff alone does not enable project sign-in. See client registration for the separate review and release requirements.

Request a credential intent

The development API accepts POST /v1/projects/{project_id}/owned-clients/credential-intents from a current project owner with approved sponsorship and recent strong authentication. See the typed custody API. Send a bearer token for taifa-management, a unique Idempotency-Key, and this exact request shape:

{
  "client_id": "project-app",
  "client_version": 1,
  "destination_runtime": "owner-runtime",
  "reason": "Prepare the credential for the reviewed application deployment"
}

The operator must already have configured that runtime for the project. The request cannot choose a filesystem path or another custodian. A successful response contains only the server-generated intent UUID and custody_status: "pending". It contains no credential or signed intent.

The intent lasts at most 120 seconds. Keep the same idempotency key and exact body after an uncertain response; retrying does not extend the deadline.

Expired or revoked intent replays return 410. A new delivery attempt requires a new audited intent.

During private retrieval, Management rechecks the captured owner, membership, project, audit evidence and configured destination. The delivery tool independently verifies the returned signed intent and exact binding. An earlier approval or response cannot restore revoked authority.

Only the controlled owner runtime receives the credential file. A pending intent, a successful handoff and a reviewed client policy are separate facts. None alone establishes an installed, effective client. The complete registration and production rollout remain gated.

Retain a preparation reference

The Linux delivery tool can opt in to a protected checkpoint before creating the credential or acknowledging handoff. This retains the verified intent and initial receipt so a later process can identify the preparation without repeating prepare.

The credential file still contains only its original 43-byte secret. Neither command prints a secret, signed receipt, preparation ID or filesystem path.

An operator provisions the existing complete delivery configuration and this separate descriptor outside the repository. Configuration and evidence files must be process-owned regular files with mode 0600; the custody root and private parents use 0700.

Both relative evidence destinations must differ from the credential destination and each other. Missing parents, symlinks, hard links, unsafe permissions and existing output files refuse.

{
  "schema": 1,
  "enabled": true,
  "delivery_config_file": "/srv/taifa-identity/private/delivery.json",
  "relative_checkpoint": "credential.checkpoint.json",
  "relative_proof": "credential.proof.json"
}

The absolute configuration path above is illustrative. The operator binds the real project, owner, issuer, runtime, keys, TLS roots and credential destination in the protected delivery configuration. The descriptor cannot replace those bindings. The tools remain restricted to the isolated development deployment.

Both commands require AUTH_DEV_INSECURE_LOOPBACK=1 and the complete protected development configuration.

1. Run auth-client-credential with no arguments, selecting the existing configuration through AUTH_CLIENT_CREDENTIAL_CONFIG_FILE and the descriptor through AUTH_CLIENT_CREDENTIAL_CHECKPOINT_CONFIG_FILE. The successful output remains controlled credential handoff complete. Without the checkpoint variable, delivery retains its existing behavior. A checkpoint failure prevents credential creation and handoff acknowledgement.

2. After a successful handoff, run auth-client-custody-proof with no arguments and AUTH_CLIENT_CUSTODY_PROOF_CONFIG_FILE selecting the same descriptor. It verifies the retained checkpoint, exact credential bytes and a fresh signed private Go readback, then exclusively writes the configured proof. Success prints only credential custody proof exported. The original preparation must still be unconsumed and in handoff_complete state, before its original 24-hour deadline. It checks expiry after destination traversal and again after file durability checks. A later failure retains its artifact and reports failure.

The proof contains the public preparation ID, exact client version as a decimal string, binding fingerprint, signed observation correlation and original deadlines. Its verification field is server_readback_required. It contains no secret, signed envelope, first secret hash, raw challenge or private path.

The owner then supplies the preparation UUID as credential_preparation_id in the development client-policy proposal.

Management independently obtains a fresh signed private readback for both proposal and approval. It does not accept the proof as current authorization or extend the original preparation deadline.

This attachment implementation is undergoing combined qualification; installation and activation remain separate pending work.

Historical completed deliveries without a checkpoint cannot recover their preparation ID automatically through this command. A missing, changed or conflicting checkpoint refuses. Repeating prepare is not an identifier lookup.

Preserve failed artifacts for controlled investigation; do not overwrite them to force a retry.

Legacy environment reveal and rotation

The retained environment API has a one-time credential handoff for migration and rollback. A secret can be revealed only during its 15-minute window, then the encrypted copy is removed. An owner can request rotation with an approved overlap of at most 24 hours. Capture the new secret into deployment configuration immediately, switch traffic, and verify old credential refusal after overlap. The Go issuer does not use this legacy reveal or rotation path.

Protect holder material

Never log passwords, TOTP seeds, passkey records, recovery evidence, client secrets, access tokens, signed receipts, or invitation links. Keep private material in a dedicated secret store and make key IDs explicit in configuration. Back up encrypted state and old decryption keys while outstanding outbox work still needs them. If a key is compromised, contain affected sessions and clients, record the rotation, and recheck product acknowledgement rather than assuming a human logout covers machine access.