Docs / Security

The security model

Six invariants hold from the first commit and never relax. Everything else — policy, approvals, BYOK — is built on top of them.

Invariants

#	Invariant
1	Raw upstream secrets are never returned over the API and never written to logs.
2	Secrets are envelope-encrypted at rest; the master key lives in a KMS in production.
3	Every issued credential is scoped and time-boxed (default 5 minutes).
4	Allow and deny are both audited, append-only.
5	The SDK/client is open-source and auditable.
6	Master keys and signing secrets are never committed.

Delegation & chain binding

Credentials carry RFC 8693 claims: sub = the human, act = the agent, nested for multi-agent chains. A chain only extends from a verified prior Keyward credential, and each extension signs in a chain_binding — the SHA-256 of the exact prior token — plus a depth counter capped at 5. That closes the chain-splicing weakness the IETF notes for bare actor claims: you cannot recombine two legitimate chains into a forged one.

Signing & verification

Credentials are RS256-signed JWTs with a kid header. The keypair is generated on first boot; the private half is stored envelope-encrypted in the database, the public half is served at /v1/jwks. Resource servers verify offline — no shared secret with the broker.

Secret storage & BYOK

Each secret is sealed with its own data key, which is wrapped by the master key (envelope encryption). In production the wrap goes through AWS KMS; an enterprise org can bring its own key — POST /v1/orgs/:id/kms — after which that org's secrets are wrapped by its key, not the global vault.

Agent identity (“secret zero”)

Agents don't get long-lived Keyward keys. An attested agent presents a workload-identity OIDC token (GitHub Actions, Kubernetes, cloud instance identity) that the broker verifies against the configured issuer — and fails closed if it can't. Revoking an agent takes effect on its next request.

Policy, approvals, environments

Policy is deny-by-default: a request is allowed only if the most specific matching rule says so (deny breaks specificity ties). A rule can instead demand a human: require_approval parks the request in the approvals queue and the agent's retry consumes a one-time, time-boxed approval. Secrets and policies are isolated per environment (dev / staging / prod), and the issued credential + audit row are stamped with the environment they came from.

Audit & detection

Every decision is an append-only row tied to the human, the agent chain, the provider:scope, and the outcome. Rows stream in real time to a SIEM webhook if configured; a denial-spike detector raises anomaly alerts per org + agent. Retention is configurable and pruning is explicit.