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), and every lifecycle step is a small, auditable transition. Short-lived SSH access and X.509 certificates are separate, narrow, in-process features: see SSH certificates and private PKI. Encryption as a service is the separate, equally bounded transit surface.

How it composesCopy Anchor Link

• No agent. Renewal is an explicit call (hikyo lease renew) or the workload’s own loop. hikyo run -- gets no resident renewer.
• Login expiry is enforced by PostgreSQL. Every minted role carries VALID UNTIL the lease expiry, so after the deadline the database refuses new password logins as that role even if Hikyo is down. VALID UNTIL is a password expiry, not a session deadline: a connection opened before the deadline keeps running. Existing sessions end only when revocation drops the role while Hikyo is up, and even DROP ROLE does not terminate backends that are already connected; they end through the database’s own session controls (pg_terminate_backend, idle and statement timeouts, a pooler’s connection lifetime). If you need a hard access deadline that holds while Hikyo is offline, set it on the database or proxy side; Hikyo does not provide one.
• 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 providerCopy Anchor Link

Provider and lease management is available in the CLI, API and browser. Open Machine access → Providers to create providers, replace or revoke their write-only credentials and remove providers. Leases supports minting, renewing, revoking and settling leases. Minted passwords use the same display-once disclosure boundary as machine credentials.

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 databaseCopy Anchor Link

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 credentialCopy Anchor Link

# 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.

ObservabilityCopy Anchor Link

• 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.