@agentproto/secrets 0.1.0-alpha.0

package/dist/provision/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @agentproto/secrets/provision — seal a secret and install it into a remote
+ * vault, carrying only ciphertext.
+ *
+ * The flow is: resolve a credential → fetch the target's sealing public key →
+ * seal to it → hand the sealed blob to the target's install. The plaintext
+ * exists only on the origin machine and, transiently, inside the target's
+ * unseal boundary — never in whatever drives this (an agent, a relay, a log).
+ *
+ * The target is an INJECTED PORT: this module knows nothing about any specific
+ * server. A caller provides a `SealedInstallTarget` — `httpTarget()` builds a
+ * generic one from a seal-key URL + install URL + headers; a host-specific
+ * caller (e.g. a product that knows its own server's paths and auth) injects
+ * its own. No vendor names leak into this package.
+ */
+/** Public sealing material a target advertises so a sender can seal to it. */
+interface SealKeyInfo {
+    keyId: string;
+    alg: string;
+    publicKey: string;
+}
+/** The sealed payload handed to a target's install. `value` is already a
+ *  sealed envelope (opaque); `keyId` lets the target reject a value sealed
+ *  against a rotated key. */
+interface SealedInstallInput {
+    provider: string;
+    methodId: string;
+    value: string;
+    keyId: string;
+    label?: string;
+}
+/**
+ * A server that can receive a sealed credential. The two halves a provision
+ * needs: advertise the sealing key, and accept the sealed install. Implement
+ * this for any concrete server; the provision flow is agnostic to how.
+ */
+interface SealedInstallTarget {
+    fetchSealKey(): Promise<SealKeyInfo>;
+    installSealed(input: SealedInstallInput): Promise<{
+        secretId?: string;
+    }>;
+}
+interface ProvisionSealedInput {
+    target: SealedInstallTarget;
+    provider: string;
+    methodId: string;
+    /** The plaintext credential. Resolve it (e.g. via `resolveCredential`) right
+     *  before calling so it lives as briefly as possible; it is sealed here and
+     *  never returned or logged. */
+    credential: string;
+    label?: string;
+}
+/**
+ * Seal `credential` to the target's current key and install it. Returns the
+ * target's result plus the keyId used. The plaintext is consumed here and
+ * never leaves.
+ */
+declare function provisionSealed(input: ProvisionSealedInput): Promise<{
+    secretId?: string;
+    keyId: string;
+}>;
+/**
+ * Build a generic HTTP target from a seal-key URL, an install URL, and
+ * optional headers (auth). Vendor-neutral — the URLs and headers are the
+ * caller's to supply. The install POSTs `{ ...input, sealed: true }` as JSON.
+ */
+declare function httpTarget(config: {
+    sealKeyUrl: string;
+    installUrl: string;
+    headers?: Record<string, string>;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}): SealedInstallTarget;
+interface CredentialSource {
+    /** Read from this process env var. */
+    fromEnv?: string;
+    /** Read from this file path (`~` expands to the home dir). */
+    fromFile?: string;
+    /** Dot-path to extract a string from the file's JSON (else whole file). */
+    jsonPath?: string;
+}
+declare function extractJsonPath(raw: string, path: string): string;
+/**
+ * Resolve a plaintext credential from a local source. Sensitive — callers
+ * seal the result immediately and never print it. Uses a dynamic `fs` import
+ * so the module has no hard Node filesystem dependency at import time.
+ */
+declare function resolveCredential(source: CredentialSource): Promise<string>;
+
+export { type CredentialSource, type ProvisionSealedInput, type SealKeyInfo, type SealedInstallInput, type SealedInstallTarget, extractJsonPath, httpTarget, provisionSealed, resolveCredential };

package/dist/provision/index.mjs

@@ -0,0 +1,4 @@
+export { extractJsonPath, httpTarget, provisionSealed, resolveCredential } from '../chunk-NLZ5HXGO.mjs';
+import '../chunk-MVHOJPML.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/provision/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/provision/recipe/index.d.ts

@@ -0,0 +1,242 @@
+import { z } from 'zod';
+
+/**
+ * Provision-recipe doctype — types.
+ *
+ * A recipe declares, for one credential provider (claude-code-oauth, codex,
+ * gemini, …), WHERE its credential lives on an origin machine and WHICH auth
+ * method id it installs as. It is the manifest the `provision` flow resolves
+ * against so a caller writes `--provider codex` instead of hand-passing
+ * `--from-file / --json-path / --method`.
+ *
+ * A recipe holds LOCATIONS, never VALUES — the schema forbids a `value` field
+ * so nobody can stuff a live secret into a recipe. The plaintext is read only
+ * at provision time, sealed immediately, and never printed.
+ *
+ * Hand-written (not scaffold-aip-generated): a recipe is AIP-19-adjacent
+ * config, not yet a numbered spec artifact. If it earns its own AIP later,
+ * promote `schema.ts` to a generated frontmatter schema then.
+ */
+/**
+ * Where a method's credential is read on the origin machine. Discriminated by
+ * the present key; exactly one of file / env / keychain / prompt.
+ *
+ *  - file     read a file (`~` expands); optionally extract a JSON string field.
+ *  - env      read a process env var.
+ *  - keychain read the macOS login Keychain (`security find-generic-password`)
+ *             by service name; optionally extract a JSON string field. macOS
+ *             CLIs (e.g. Claude Code) store their OAuth token here, not on disk.
+ *  - prompt   read interactively (e.g. a website password for a remote browser);
+ *             never on disk, never logged. Needs an injected prompt impl.
+ */
+type CredentialSourceSpec = {
+    file: string;
+    jsonPath?: string;
+} | {
+    env: string;
+} | {
+    keychain: string;
+    account?: string;
+    jsonPath?: string;
+} | {
+    prompt: string;
+};
+/** One installable flavor of a provider's credential. The first method in a
+ *  recipe is the default when `--method` is omitted. */
+interface RecipeMethod {
+    /** Auth-method id this flavor installs as (e.g. "subscription-token",
+     *  "api-key"). Becomes the vault connector's methodId. */
+    id: string;
+    /** Human label for this flavor; falls back to the recipe label. */
+    label?: string;
+    /** Where to read the credential for this flavor. An array is an ordered
+     *  fallback chain — the first source that resolves wins (e.g. macOS Keychain,
+     *  then a file, so one recipe spans platforms). */
+    source: CredentialSourceSpec | CredentialSourceSpec[];
+}
+interface ProvisionRecipeDefinition {
+    /** Provider id — kebab/dot, 2–80 chars (the cross-AIP id pattern). */
+    id: string;
+    /** LLM/human-facing prose; ≤2000 chars. */
+    description: string;
+    /** Installable flavors; ≥1, first = default. */
+    methods: [RecipeMethod, ...RecipeMethod[]];
+    /** Default connector label; a method's own label overrides. */
+    label?: string;
+}
+type ProvisionRecipe = Readonly<ProvisionRecipeDefinition>;
+
+/**
+ * Provision-recipe frontmatter / literal zod schema.
+ *
+ * Single source of truth for both authoring paths: `defineProvisionRecipe`
+ * (TS literal) and `parseRecipeManifest` (.md) run this same schema, so a
+ * malformed literal and a malformed manifest fail identically — mirrors how
+ * `secretsFrontmatterSchema` backs both `defineSecrets` and
+ * `parseSecretsManifest`.
+ *
+ * Hand-written rather than scaffold-aip-generated: a recipe is not yet a
+ * numbered-AIP artifact. Promote to a generated schema if it gets its own spec.
+ */
+
+/** Exactly one of file / env / keychain / prompt. `value` is explicitly
+ *  forbidden — a recipe carries locations, never secrets. */
+declare const credentialSourceSpecSchema: z.ZodUnion<readonly [z.ZodObject<{
+    file: z.ZodString;
+    jsonPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    env: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    keychain: z.ZodString;
+    account: z.ZodOptional<z.ZodString>;
+    jsonPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    prompt: z.ZodString;
+}, z.core.$strict>]>;
+declare const recipeMethodSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    source: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+        file: z.ZodString;
+        jsonPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        keychain: z.ZodString;
+        account: z.ZodOptional<z.ZodString>;
+        jsonPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        prompt: z.ZodString;
+    }, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        file: z.ZodString;
+        jsonPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        keychain: z.ZodString;
+        account: z.ZodOptional<z.ZodString>;
+        jsonPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        prompt: z.ZodString;
+    }, z.core.$strict>]>>]>;
+}, z.core.$strict>;
+declare const provisionRecipeFrontmatterSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    methods: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        source: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+            file: z.ZodString;
+            jsonPath: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            keychain: z.ZodString;
+            account: z.ZodOptional<z.ZodString>;
+            jsonPath: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            prompt: z.ZodString;
+        }, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            file: z.ZodString;
+            jsonPath: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            keychain: z.ZodString;
+            account: z.ZodOptional<z.ZodString>;
+            jsonPath: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            prompt: z.ZodString;
+        }, z.core.$strict>]>>]>;
+    }, z.core.$strict>>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type ProvisionRecipeFrontmatter = z.infer<typeof provisionRecipeFrontmatterSchema>;
+
+/**
+ * `defineProvisionRecipe` — the TS-literal authoring path for a recipe.
+ *
+ * Built on `createDoctype` so a recipe gets the same cross-AIP invariants as
+ * every other doctype: id-pattern check, ≤2000-char description, frozen handle,
+ * canonical "defineProvisionRecipe (AIP-19): …" error prefix. Field-level
+ * validation runs the shared zod from `./schema.ts`, so a malformed literal
+ * fails with the same diagnostic as a malformed `.md`.
+ */
+
+declare const defineProvisionRecipe: (def: ProvisionRecipeDefinition) => Readonly<ProvisionRecipeDefinition>;
+
+/**
+ * `.md` authoring path for a provision recipe — parse a frontmatter manifest
+ * into a frozen handle. Mirrors `parseSecretsManifest`: gray-matter splits the
+ * frontmatter, the shared zod validates it, `defineProvisionRecipe` builds the
+ * handle so the `.md` and TS-literal paths converge on one validated shape.
+ *
+ * The package ships its builtin recipes as TS literals (they bundle with zero
+ * fs); this parser is for a HOST that reads its own external `.md` recipes and
+ * registers them — the extension seam.
+ */
+
+interface ProvisionRecipeManifest {
+    frontmatter: ProvisionRecipeFrontmatter;
+    body: string;
+}
+declare function parseRecipeManifestRaw(source: string): ProvisionRecipeManifest;
+/** Parse a recipe `.md` straight to a frozen handle (frontmatter →
+ *  `defineProvisionRecipe`). */
+declare function parseRecipeManifest(source: string): ProvisionRecipe;
+
+/** Claude Code subscription OAuth token. macOS stores it in the login Keychain;
+ *  Linux writes it to ~/.claude/.credentials.json. Try the Keychain first, fall
+ *  back to the file, so one recipe spans both. */
+declare const claudeCodeOauthRecipe: Readonly<ProvisionRecipeDefinition>;
+/** Codex CLI — two flavors: the subscription OAuth token, or a raw API key. */
+declare const codexRecipe: Readonly<ProvisionRecipeDefinition>;
+/** Gemini CLI OAuth token written by the local CLI. */
+declare const geminiRecipe: Readonly<ProvisionRecipeDefinition>;
+declare const BUILTIN_RECIPES: readonly ProvisionRecipe[];
+
+/**
+ * Provision-recipe registry — id → recipe lookup, pre-seeded with the builtins.
+ *
+ * Mirrors the host-side OAuth-provider registry shape: a module-level Map a
+ * caller resolves by id at provision time, plus a `registerRecipe` seam so a
+ * host can add recipes parsed from its own `.md` (`parseRecipeManifest`)
+ * without editing this package. Re-registering an id overrides it — last write
+ * wins, so a host can shadow a builtin.
+ */
+
+declare function registerRecipe(recipe: ProvisionRecipe): void;
+declare function getRecipe(id: string): ProvisionRecipe | undefined;
+declare function listRecipes(): ProvisionRecipe[];
+declare function listRecipeIds(): string[];
+/**
+ * Resolve a recipe + one of its methods. `methodId` selects among the recipe's
+ * flavors; omitted picks the first (default). Throws a caller-friendly error
+ * naming the available methods when the id is unknown or ambiguous.
+ */
+declare function resolveRecipeMethod(id: string, methodId?: string): {
+    recipe: ProvisionRecipe;
+    method: RecipeMethod;
+};
+
+/**
+ * Resolve a recipe method's source to plaintext.
+ *
+ * A source is a single `CredentialSourceSpec` or an ordered fallback chain
+ * (array) — the first that resolves wins, so one recipe spans platforms
+ * (macOS Keychain → file). Bridges onto `resolveCredential` (file / env), the
+ * macOS `security` Keychain, and an injected prompt impl (interactive, e.g. a
+ * website password for a remote browser). The prompt impl is INJECTED — no
+ * hard TTY dependency at import, same discipline as `fetchImpl` on
+ * `httpTarget`. The result is sensitive: seal it immediately, never print it.
+ */
+
+interface ResolveSourceOptions {
+    /** Asked for a `{ prompt }` source. Receives the prompt text, returns the
+     *  entered value. Required only when a method uses a prompt source. */
+    promptImpl?: (prompt: string) => Promise<string>;
+}
+declare function resolveSourceSpec(source: CredentialSourceSpec | CredentialSourceSpec[], opts?: ResolveSourceOptions): Promise<string>;
+
+export { BUILTIN_RECIPES, type CredentialSourceSpec, type ProvisionRecipe, type ProvisionRecipeDefinition, type ProvisionRecipeFrontmatter, type ProvisionRecipeManifest, type RecipeMethod, type ResolveSourceOptions, claudeCodeOauthRecipe, codexRecipe, credentialSourceSpecSchema, defineProvisionRecipe, geminiRecipe, getRecipe, listRecipeIds, listRecipes, parseRecipeManifest, parseRecipeManifestRaw, provisionRecipeFrontmatterSchema, recipeMethodSchema, registerRecipe, resolveRecipeMethod, resolveSourceSpec };

package/dist/provision/recipe/index.mjs

@@ -0,0 +1,5 @@
+export { BUILTIN_RECIPES, claudeCodeOauthRecipe, codexRecipe, credentialSourceSpecSchema, defineProvisionRecipe, geminiRecipe, getRecipe, listRecipeIds, listRecipes, parseRecipeManifest, parseRecipeManifestRaw, provisionRecipeFrontmatterSchema, recipeMethodSchema, registerRecipe, resolveRecipeMethod, resolveSourceSpec } from '../../chunk-NEGXQWE5.mjs';
+import '../../chunk-NLZ5HXGO.mjs';
+import '../../chunk-MVHOJPML.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/provision/recipe/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/seal/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @agentproto/secrets/seal — anonymous public-key sealing for secret values.
+ *
+ * A "sealed box": encrypt a secret TO a recipient's public key such that only
+ * the holder of the matching private key can open it. The sender needs only
+ * the public key, and the sealed envelope reveals nothing about the sender.
+ *
+ * The point is custody. A secret value (a CLI subscription token, an API key)
+ * can be sealed on the machine that holds it, then handed to ANY intermediary
+ * — a relay, an agent, a log — as opaque ciphertext, because only the server's
+ * private key can recover the plaintext. The plaintext never has to exist
+ * anywhere but the origin machine and, transiently, inside the recipient's
+ * unseal boundary.
+ *
+ * Construction (ECIES, Node built-ins only — no native dep):
+ *   - X25519 ephemeral key agreement with the recipient's public key
+ *   - HKDF-SHA256 over the shared secret, salted by both public keys
+ *   - AES-256-GCM AEAD for the payload (authenticated; tampering fails closed)
+ *
+ * This is the same shape as libsodium's `crypto_box_seal`, expressed in terms
+ * of Node's `crypto` so the package keeps its zero-native-dependency footprint.
+ *
+ * Sealing (confidentiality) is NOT signing (authenticity): this hides the
+ * value, it does not prove who sent it. Bind the sender separately (e.g. an
+ * authenticated transport) when provenance matters.
+ */
+/** Versioned algorithm tag embedded in every envelope so the format can
+ *  evolve without ambiguity at the unseal site. */
+declare const SEAL_ALG: "x25519-hkdf-sha256-aes256gcm";
+declare const SEAL_VERSION: 1;
+/** Raised for every seal/unseal failure. The message is safe to surface —
+ *  it never contains key material or plaintext. */
+declare class SealError extends Error {
+    constructor(message: string);
+}
+/** An X25519 keypair for sealing. Both halves are base64-encoded DER so they
+ *  travel as plain strings (env vars, JSON, config). The public half is safe
+ *  to publish; the private half must stay with the unseal boundary. */
+interface SealKeyPair {
+    /** base64 DER (SPKI) X25519 public key — publishable. */
+    publicKey: string;
+    /** base64 DER (PKCS8) X25519 private key — secret. */
+    privateKey: string;
+}
+/**
+ * Mint a fresh sealing keypair. The recipient (e.g. a server) generates this
+ * once, stores `privateKey` in its own secret store, and publishes
+ * `publicKey` for senders to seal against.
+ */
+declare function generateSealKeyPair(): SealKeyPair;
+/**
+ * Derive the publishable public key from a stored private key. Lets a
+ * recipient hold only the private half (one secret) and serve the public
+ * half on demand — the seal-key a sender needs.
+ */
+declare function sealingPublicKey(privateKey: string): string;
+/**
+ * Stable short identifier for a sealing key, derived from the public key.
+ * Lets the seal-key endpoint and the sealed envelope name which key was used
+ * so rotation is unambiguous. Not a secret.
+ */
+declare function sealKeyId(publicKey: string): string;
+/**
+ * Seal a plaintext value to a recipient's public key. Returns a single
+ * base64 string (the envelope) that only the matching private key can open.
+ * The sender needs nothing but the public key.
+ */
+declare function seal(plaintext: string | Uint8Array, recipientPublicKey: string): string;
+/**
+ * Open a sealed envelope with the recipient's private key, returning the
+ * original UTF-8 plaintext. Throws `SealError` on a malformed envelope, an
+ * unsupported version/alg, the wrong key, or any tampering (the AEAD tag
+ * fails closed — a modified ciphertext never decrypts to garbage, it throws).
+ */
+declare function unseal(sealed: string, privateKey: string): string;
+
+export { SEAL_ALG, SEAL_VERSION, SealError, type SealKeyPair, generateSealKeyPair, seal, sealKeyId, sealingPublicKey, unseal };

package/dist/seal/index.mjs

@@ -0,0 +1,3 @@
+export { SEAL_ALG, SEAL_VERSION, SealError, generateSealKeyPair, seal, sealKeyId, sealingPublicKey, unseal } from '../chunk-MVHOJPML.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/seal/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/types-C2dZDHn7.d.ts

@@ -0,0 +1,97 @@
+/**
+ * SecretExposure — describes HOW a secret value reaches the runtime
+ * that needs it (env var, config file, egress placeholder, future
+ * MCP-header injection, future HTTP-bearer routing, …).
+ *
+ * Distinct from `SecretEntry` (AIP-19), which describes the secret's
+ * *declaration* (slug, kind, access policy). Exposure is a *runtime*
+ * concern — same secret might be exposed multiple ways across hosts.
+ *
+ * Discriminated union by `kind` so each new mechanism slots in as one
+ * variant rather than another top-level field on whatever catalog the
+ * host uses to map secrets onto agent runtimes.
+ *
+ * # Why this lives here (not in @agentproto/egress)
+ * The substitution sigil + the "what surfaces does this secret have"
+ * vocabulary are properties of the secret itself — they describe its
+ * exposure surface independent of WHO consumes it. Egress is one
+ * consumer; future ones (MCP servers, HTTP relays) are others.
+ *
+ * The egress *gating* (mode registry, proxy core) lives in
+ * @agentproto/egress because that's a different concern (network-
+ * boundary control). Egress imports from here.
+ */
+/** Function applied to the seed value before write. Receives the raw
+ *  secret value (or empty string when `field` is omitted) plus an
+ *  optional context bag the host populates. Returns the file body. */
+type SecretExposureWrap = (value: string, ctx?: SecretExposureWrapContext) => string;
+/** Generic context passed to `wrap` callbacks. Hosts populate fields
+ *  they have; wraps that don't care ignore the second arg entirely.
+ *  Kept open-ended (string-keyed) so hosts can attach app-specific
+ *  data without forcing a schema change here. */
+interface SecretExposureWrapContext {
+    [key: string]: unknown;
+}
+/** Inject the secret value as a process env var inside the runtime. */
+interface EnvExposure {
+    kind: "env";
+    /** Env var name as the runtime sees it. */
+    name: string;
+    /** Field on the secret/connector settings whose value seeds the env.
+     *  Required for env exposures — env vars don't have a `wrap` path. */
+    field: string;
+}
+/** Drop a file inside the runtime's filesystem before any process
+ *  starts. Path uses `~` expansion against the runtime's exec user
+ *  home (host-resolved). */
+interface FileExposure {
+    kind: "file";
+    /** Absolute path or `~`-relative path inside the runtime sandbox. */
+    path: string;
+    /** Field on the secret/connector settings whose value seeds the file
+     *  body. Omit when `wrap` produces synthetic content (e.g. claude's
+     *  `.claude.json` migration flags don't depend on a token). */
+    field?: string;
+    /** POSIX file mode. Default `0o600`. */
+    mode?: number;
+    /** Transform applied before write — see SecretExposureWrap. */
+    wrap?: SecretExposureWrap;
+}
+/**
+ * Mark this secret as eligible for substitution at the egress proxy.
+ * Agents see only `$$SECRET[<placeholderName>]$$` placeholders; the
+ * proxy substitutes the real value at the network boundary.
+ *
+ * The actual proxy + sigil regex + substitution engine live in
+ * `@agentproto/egress` — this exposure variant just declares the
+ * intent + the per-secret defaults the host install handler stamps.
+ */
+interface EgressSubstituteExposure {
+    kind: "egress-substitute";
+    /** The token agents reference in `$$SECRET[NAME]$$`. By convention
+     *  this matches the env-exposure name on the same secret, but it
+     *  doesn't have to — placeholders and env vars are independent. */
+    placeholderName: string;
+    /** Default value for the per-secret allowlist flag stamped at install
+     *  time. UI may offer a per-install override. When false, the secret
+     *  is declared egress-aware but rejected by the resolver until an
+     *  admin opts in. */
+    allowedByDefault: boolean;
+    /** Audit / UX hint — the providers this secret is *meant* for. NOT
+     *  enforced at egress (proxy substitutes any matching placeholder
+     *  regardless of upstream); the field exists so UIs can surface
+     *  "this secret is for OpenAI" without parsing the slug. */
+    intendedProviders?: string[];
+}
+/**
+ * Discriminated union of all exposure mechanisms. Add new variants here
+ * as new exposure surfaces are added (MCP-header, HTTP-bearer, etc.) —
+ * each adds one variant, one switch case in consumers.
+ */
+type SecretExposure = EnvExposure | FileExposure | EgressSubstituteExposure;
+/** Type guard — convenient for filtering an exposures array by kind. */
+declare function isExposureKind<K extends SecretExposure["kind"]>(exposure: SecretExposure, kind: K): exposure is Extract<SecretExposure, {
+    kind: K;
+}>;
+
+export { type EgressSubstituteExposure as E, type FileExposure as F, type SecretExposure as S, type EnvExposure as a, type SecretExposureWrap as b, type SecretExposureWrapContext as c, isExposureKind as i };

package/dist/types-Clav8IDA.d.ts

@@ -0,0 +1,141 @@
+import { S as SecretExposure } from './types-C2dZDHn7.js';
+
+/**
+ * AIP-19 SecretsDefinition + SecretsHandle.
+ *
+ * `SecretsDefinition` was generated from
+ * `resources/aip-19/draft/SECRETS.schema.json` via json-schema-to-typescript.
+ * `SecretsHandle` is the readonly view of the same shape; tighten it
+ * by hand for fields that get defaults applied in build().
+ *
+ * The `exposures` field on each entry was added by hand (not regen'd
+ * yet) — runtime exposure descriptors live in `./exposure/types.ts` so
+ * they can be consumed independently by hosts that don't need the
+ * full SECRETS.md doctype machinery (Guilde's connector registry,
+ * @agentproto/egress's proxy core).
+ */
+
+type SecretEntry = {
+    [k: string]: unknown;
+} & {
+    /**
+     * Machine identifier. Lowercase, digits, dashes; optional <namespace>/ prefix. 2–80 chars total. Unique within the workspace inventory.
+     */
+    slug: string;
+    name: string;
+    description: string;
+    /**
+     * Value shape. 'opaque' = single string. 'oauth' = { accessToken, refreshToken, expiresAt }. 'keypair' = { public, private }. 'json' = arbitrary structured.
+     */
+    kind?: "opaque" | "oauth" | "keypair" | "json";
+    /**
+     * Vault URI (optional). Default: host-resolved by slug. Setting it explicitly exposes infra topology and SHOULD be reviewer-audited.
+     */
+    backend?: string;
+    access?: AccessGrants;
+    audit?: AuditConfig;
+    tags?: string[];
+    metadata?: {
+        [k: string]: unknown;
+    };
+    /**
+     * How this secret is exposed to the runtime that consumes it (env,
+     * file, egress placeholder, future MCP-header / HTTP-bearer / etc.).
+     * Optional — hosts MAY honor or remap based on their own catalog.
+     * Discriminated by `kind`; consumers ignore unknown kinds.
+     *
+     * See `@agentproto/secrets/exposure` for the variant types.
+     */
+    exposures?: SecretExposure[];
+} & {
+    /**
+     * Machine identifier. Lowercase, digits, dashes; optional <namespace>/ prefix. 2–80 chars total. Unique within the workspace inventory.
+     */
+    slug: string;
+    name: string;
+    description: string;
+    /**
+     * Value shape. 'opaque' = single string. 'oauth' = { accessToken, refreshToken, expiresAt }. 'keypair' = { public, private }. 'json' = arbitrary structured.
+     */
+    kind?: "opaque" | "oauth" | "keypair" | "json";
+    /**
+     * Vault URI (optional). Default: host-resolved by slug. Setting it explicitly exposes infra topology and SHOULD be reviewer-audited.
+     */
+    backend?: string;
+    access?: AccessGrants;
+    audit?: AuditConfig;
+    tags?: string[];
+    metadata?: {
+        [k: string]: unknown;
+    };
+    /**
+     * How this secret is exposed to the runtime that consumes it (env,
+     * file, egress placeholder, future MCP-header / HTTP-bearer / etc.).
+     * Optional — hosts MAY honor or remap based on their own catalog.
+     * Discriminated by `kind`; consumers ignore unknown kinds.
+     *
+     * See `@agentproto/secrets/exposure` for the variant types.
+     */
+    exposures?: SecretExposure[];
+};
+/**
+ * A single access-grant entry. Exactly ONE of role/userId/cap/tool/workflow.
+ */
+type AccessEntry = {
+    role?: string;
+    userId?: string;
+    cap?: string;
+    tool?: string;
+    workflow?: string;
+} & AccessEntry1 & {
+    role?: string;
+    userId?: string;
+    cap?: string;
+    tool?: string;
+    workflow?: string;
+} & AccessEntry1 & {
+    role?: string;
+    userId?: string;
+    cap?: string;
+    tool?: string;
+    workflow?: string;
+} & AccessEntry1;
+type AccessEntry1 = {
+    [k: string]: unknown;
+} | {
+    [k: string]: unknown;
+} | {
+    [k: string]: unknown;
+} | {
+    [k: string]: unknown;
+} | {
+    [k: string]: unknown;
+};
+/**
+ * Validates the YAML frontmatter portion of an AIP-19 SECRETS.md manifest. The manifest declares secret slugs + access policy + audit metadata. Values are NEVER stored in the manifest.
+ */
+interface SecretsDefinition {
+    /**
+     * @minItems 1
+     */
+    secrets: [SecretEntry, ...SecretEntry[]];
+}
+interface AccessGrants {
+    reveal?: AccessEntry[];
+    bind?: AccessEntry[];
+    /**
+     * Reserved for a future rotation AIP. Hosts MAY ignore.
+     */
+    rotate?: AccessEntry[];
+}
+interface AuditConfig {
+    /**
+     * ISO 8601 duration ('P7Y') or shorthand ('7y', '90d').
+     */
+    retention?: string;
+    pii?: boolean;
+    classification?: string[];
+}
+type SecretsHandle = Readonly<SecretsDefinition>;
+
+export type { SecretsDefinition as S, SecretsHandle as a };