Scoped secret broker

Scoped secret broker

The secret broker lets providers, connectors, workflows, and one-shot
processes use credentials without putting raw values in prompts, provider
files, agent manifests, transcripts, logs, or ordinary API responses. Outside
the trusted injection boundary, a credential is only:

secretref:v1:8f517a4a-27b9-4d0c-8b4c-68bb996e2417

Initialize encrypted local state before creating a
local broker entry.

Create a usage policy

Policies are default-deny. Every allowed operation names the exact principal,
run, tool, destination, purpose, and injection mode:

{
  "bindings": [
    {
      "principal": "user:alice",
      "run_id": "run-2026-07-25",
      "tool": "provider.openai",
      "destination": "https://api.openai.com",
      "purpose": "support-chat"
    }
  ],
  "injection_modes": ["provider"],
  "max_lease_seconds": 60,
  "max_uses": 1,
  "approval_required": false,
  "expires_at": null
}

Supported modes are provider, http_header, http_field, environment,
mounted_file, stdin, signing, and brokered_request. A target is also
bound to the lease, such as openai, Authorization, or SERVICE_TOKEN.

Create and reference a credential

Pass a value only through a named environment variable. It is never accepted
as a command argument:

$env:HOLARYN_NEW_OPENAI_KEY = "<value>"
holaryn secret create openai-production `
  --value-env HOLARYN_NEW_OPENAI_KEY `
  --scope-kind project `
  --scope-id holaryn `
  --policy .\openai-secret-policy.json `
  --dependency provider/openai
Remove-Item Env:HOLARYN_NEW_OPENAI_KEY

Copy the returned ref into a provider connection's Broker SecretRef field
or an agent/workflow secret_refs mapping. The Settings System → Scoped
secret broker panel shows authenticated metadata and health, never values or
lease handles.

Request and test an exact lease

holaryn secret request <secretref> `
  --principal user:alice `
  --run run-2026-07-25 `
  --tool provider.openai `
  --destination https://api.openai.com `
  --purpose support-chat `
  --mode provider `
  --target openai `
  --seconds 30

The output contains an opaque bearer handle for a trusted adapter. It does not
contain the credential. Do not put the handle in prompts, logs, or long-lived
configuration. There is deliberately no CLI resolve command.

Use the same exact arguments with holaryn secret test to exercise backend
access and lease authorization without disclosing the value. If a policy has
approval_required: true, an operator approves the pending lease with:

holaryn secret --actor user:reviewer approve <lease-id>

Rotation, rollback, and revocation

Review dependencies first, then stage and cut over:

holaryn secret rotate-plan <secretref>
$env:HOLARYN_ROTATED_KEY = "<new-value>"
holaryn secret rotate-stage <secretref> --value-env HOLARYN_ROTATED_KEY
Remove-Item Env:HOLARYN_ROTATED_KEY
holaryn secret rotate-cutover <secretref>

The prior version remains available for holaryn secret rotate-rollback <secretref>. After verification, holaryn secret rotate-retire <secretref>
deletes it. Cutover and rollback revoke leases bound to the version being
deactivated.

Revoke one lease or the whole credential:

holaryn secret revoke --lease-id <lease-id> --reason "run cancelled"
holaryn secret revoke --ref <secretref> --reason "integration retired"

Permanent deletion requires prior revocation and exact alias confirmation:

holaryn secret delete <secretref> --confirm "DELETE openai-production"

holaryn secret audit shows aliases, outcomes, actors, timestamps, and bounded
operation metadata. It never contains values.

Break-glass

Break-glass is for an attended incident only. It requires distinct actor and
reviewer identities, a reason, exact operation binding, and exact confirmation:

holaryn secret --actor user:alice break-glass <secretref> <binding-and-injection-options> \
  --reviewer user:bob --reason "provider outage" \
  --confirm "BREAK-GLASS openai-production"

The emergency lease is one-use and at most five minutes.

Troubleshooting and recovery

• Broker requires encrypted state: run holaryn encryption enable while the
  host is stopped, then retry.
• Locked metadata: restore access to the configured OS key provider or set
  HOLARYN_ENCRYPTION_PASSWORD for a recovery-password installation. Do not
  delete the manifest or catalog.
• Policy denied: compare every binding and injection target exactly;
  prefix and wildcard matching are intentionally unsupported.
• Lease expired/exhausted/revoked: request a new lease. Handles cannot be
  renewed or redirected.
• Backend version missing: restore the external manager/version or roll
  back. The failed access does not consume a lease use.

Redaction covers registered raw, URL/form, base64, JSON-escaped, and bounded
split-output forms. It cannot reverse arbitrary exfiltration after a trusted
adapter discloses a value. See
docs/scoped-secret-broker-adr.md for
the complete threat model, metadata leakage, and lifecycle.