@agentproto/secrets

AIP-19 SECRETS.md reference implementation. A workspace-level manifest format for declaring secret slugs, their purpose, access grants, and audit metadata — without ever storing the values themselves. Hosts resolve slugs against a real vault at reveal time.

Status: 0.1.0-alpha. Generated by scripts/scaffold-aip.mjs — build() and validate() bodies are TODOs.

Spec: https://agentproto.sh/docs/aip-19

Usage

import { defineSecrets } from "@agentproto/secrets"

const x = defineSecrets({
  id: "my-secrets",
  description: "Short purpose.",
  // ...
})

capture — vault a CLI's own OAuth login locally

agentproto-secrets capture [--provider <recipe>] [--vault-dir <dir>] reads a coding CLI's subscription OAuth login through its builtin recipe's oauth field map (the full AIP-19 oauth shape {accessToken, refreshToken, expiresAt}), seals it to the vault's own local keypair (<dir>/key.json, 0600, minted on first run), and writes entries/<provider>.json (0600). It prints a capability pointer (agentproto-secrets://vault/<provider>?method=…&key=…) — the token values are never printed, logged, or written in the clear. If the CLI has no local login yet (claude login / codex login not run), the command exits 1 and says to run the CLI's own login first; it never spawns a second login client.

Trust boundary: the vault keypair lives in plaintext at <dir>/key.json (0600) next to the sealed entries, so at-rest confidentiality rests on filesystem permissions — any read of the vault dir (backup, sync, a compromised local account) yields key and ciphertext together. This is a LOCAL vault only: for sending the credential to a server without exposing the plaintext, use provision (seal to the target's own key first).

Exposure surface (@agentproto/secrets/exposure)

The manifest says which secrets exist; an exposure says how a resolved secret reaches a runtime. SecretExposure is a discriminated union — one kind per delivery mechanism, so consumers filter with the isExposureKind guard and handle each with one switch case:

import { isExposureKind, type SecretExposure } from "@agentproto/secrets/exposure"

const headerExposures = exposures.filter(e => isExposureKind(e, "mcp-header"))

mcp-header — brokered MCP auth

interface McpHeaderExposure {
  kind: "mcp-header"
  credentialPath: string   // broker path: "<providerId>" or "<providerId>/<account>"
  server?: string          // optional upstream override, forwarded to the broker
}

resolveMcpHeaderExposure(exposure, resolver, { signal }) turns that path into a ready-to-use header map. The resolver is a structural McpHeaderResolver (resolveHeaders({ path, server?, signal? })) — the CredentialBroker from @agentproto/auth satisfies it with no adapter, so this package stays dependency-free of auth while still driving it.

Every resolved header value is run through assertSafeSecretValue before return — a value containing CR/LF/NUL is rejected, closing off header-injection (a smuggled newline can't append extra header lines onto the transport).

import { resolveMcpHeaderExposure } from "@agentproto/secrets/exposure"
import { CredentialBroker } from "@agentproto/auth"

const headers = await resolveMcpHeaderExposure(exposure, broker, { signal })
// → { Authorization: "Bearer …" }, guarded

The same guard (assertSafeSecretValue) and the $$SECRET[NAME]$$ engine (substituteSecrets, SECRET_PLACEHOLDER_PATTERN, formatPlaceholder) are exported from this subpath for the egress-substitute path.

License

MIT — see LICENSE.