Dynamic secrets

Dynamic secrets let an authorized workload ask Hikyo for a short-lived PostgreSQL credential. Hikyo mints a login role at the database, hands the password back exactly once, and durably renews or revokes the lease. The password is never stored, not even hashed: after the single disclosure the only record is the role name and the lease’s status.

This is deliberately not Vault. The provider boundary is a closed set (today, just PostgreSQL), there is no PKI, SSH-certificate or encryption-as-a-service surface, and every lifecycle step is a small, auditable transition.

How it composes

• No agent. Renewal is an explicit call (hikyo lease renew) or the workload’s own loop. hikyo run -- gets no resident renewer.
• Expiry is enforced by PostgreSQL. Every minted role carries VALID UNTIL the lease expiry, so a lease expires on time even if Hikyo is down.
• Multi-node safe. Lease transitions are claimed under a per-row lease fence (owner + expiry, SELECT ... FOR UPDATE SKIP LOCKED, a per-org cap), so under HA each transition has exactly one current owner and a stale worker’s writes affect zero rows.
• Uncertain outcomes fail loud. If a provider call’s result is ambiguous the lease enters unknown and is never reported as success; hikyo lease settle (or the worker) re-probes and settles it.

Configure a provider

Provider and lease management is CLI/API only today; the browser’s Machine access page shows leases read-only. Management in the browser is tracked in #595.

A provider is project-scoped standing authority. Its admin credential is write-only: it is sealed at rest and no read ever returns it.

# The admin credential is read with terminal echo disabled, from --stdin, or
# from --value-file. It never appears on argv.
hikyo dynamic-provider create \
  --provider postgres \
  --origin postgres://hikyo_admin@db.internal:5432/app \
  --grant-role app_reader

--grant-role is the parent role every minted lease role inherits (IN ROLE), so a lease role has exactly the access the operator granted that role and no more. Creating a provider connects once to verify reachability and the admin credential before the row is recorded; a provider that cannot be reached is refused rather than stored as usable.

The admin role Hikyo authenticates as needs CREATEROLE and membership of app_reader (so it can grant it). Rotate the admin credential with hikyo dynamic-provider credential set; revoke custody with hikyo dynamic-provider credential revoke (renewal and revocation then wait until a new credential is set).

Reaching a private database

The default-deny egress policy refuses a private address. Allow your database’s address explicitly with an operator policy file, keyed by the exact origin:

{ "postgres://hikyo_admin@db.internal:5432/app": ["10.0.0.0/8"] }

Point HIKYO_DYNAMIC_EGRESS_POLICY_FILE at it. Connections are always TLS verify-full.

Lease a credential

# Discloses the credential exactly once, through the print triad.
hikyo lease mint --provider <provider> --env production --ttl 1h \
  --output-file ./db.pass

A machine principal mints under the project’s machine-reveal opt-in; a human operator minting for testing completes the mint reauthentication ceremony first. A retry mints a new lease with a new secret — the old secret is never returned again.

hikyo lease list --env production           # status and metadata, never the secret
hikyo lease renew <lease> --env production  # extend, bounded by the max TTL
hikyo lease revoke <lease> --env production # drop the role (idempotent)
hikyo lease settle <lease> --env production  # settle an `unknown` lease

Deleting a provider refuses while it still has live leases unless you pass --revoke-all, which queues every live lease for revocation first.

Observability

• hikyo_dynamic_leases_active and hikyo_dynamic_effects_unknown are label-free gauges on /metrics. A non-zero hikyo_dynamic_effects_unknown is the signal that a transition is stuck in an uncertain state; the same leases show unknown in hikyo lease list and are settled by hikyo lease settle.
• Every transition writes an audit trail: the provider lifecycle, one intent and one outcome per lease transition, and a single disclosure record per mint. No provider credential or minted password ever appears in an audit payload.