@vibesdotdev/secrets 0.0.2 → 1.0.0-rc.3

package/docs/contracts.md

@@ -0,0 +1,94 @@
+# Detailed secrets contracts
+
+These are required behaviors, not a verification receipt. See [SPEC](../SPEC.md) for ownership and check commands.
+
+## Catalogue
+
+Each piece, its contract, its home and the test that fails when the promise is
+broken. A key is 1 to 128 characters with no control character, `/` or `\\`, and is
+never `__proto__`, `constructor` or `prototype` (`assertSecretKey`, `./kinds/secret-key`);
+`env-file` additionally needs an environment-variable shape
+(`assertEnvironmentSecretKey`), `mounted-files` a plain file name. A store answers by own property
+only. Every host API but HTTP (fs, path, child process, stdio, environment) is
+reached through the handed runtime (`filesystem/adapter`, `runtime/process`,
+`runtime/execution`, `runtime/stdio`, `runtime/environment`), never imported by
+this package outside tests.
+
+HTTP transports accept an injectable fetch boundary where documented and apply bounded reads, origin policy, and deadlines. The platform-api rows below describe the integration-owned bridge, not a backend implemented in this package.
+
+| Piece | Contract | Home | Proof |
+|---|---|---|---|
+| `secrets/store` kind and resolver (`./kinds`, `resolveSecretsStore`) | One store per (runtime, tier, reference): highest priority wins; a tie is `INVALID_INPUT store-ambiguous` in every resolver (`resolveSecretsStore` and the CLI tier pick included, never a silent first). Descriptors are parsed (a malformed one is `INVALID_INPUT store-descriptor-invalid`, never skipped). The one pick is `pickTierSecretsStore` (`./kinds`), used by the kind, `resolveSecretsStore` and every CLI command (`cli/shared/store-selection.ts`); a command may narrow the candidates by its own policy (`set` writes to local stores by default), the pick and its tie rule stay the kind's. A forged operation context is `INVALID_INPUT store-context-invalid` and a bootstrap cycle `INVALID_INPUT store-recursion`. | here | `kinds/__tests__/store-kind.test.ts`, `__tests__/runtime-resolver.test.ts` |
+| Store interface (`./kinds/store.interface`) | `list`, `get`, `set`, `unset`, `getAll`, `setAll`. Absence is `undefined`; a failure is typed; a key `assertSecretKey` refuses is `INVALID_INPUT secret-key-invalid` before any read or write; the error never carries the key. | here | `backends/__tests__/hostile-keys.test.ts` (every backend) |
+| Environment tier (`resolveSecretsEnvironment`, `./cli/environment`) | The tier from the runtime scope, or typed `tier-undeclared` / `scope-invalid`. One tier list (the schema's). One re-export path (`./cli/environment`, over `src/support/environment.ts`). The signature is `(runtime, environmentOverride?)`; the former `(runtime, reporter, override)` form (the reporter was never called) remains a `@deprecated` overload until its three `infra-deploy` callers drop the argument. | here | `__tests__/secrets-environment.test.ts` |
+| Schemas (`./schemas`, `./vault/secret-record`, svelte runtime) | One wire record (`secretWireRecordSchema`) and one wire envelope (`secretCollectionEnvelopeSchema` `{ results }` / `secretItemEnvelopeSchema` `{ result }`, the shape platform-web's `/api/secrets` serves beside its legacy `{ secrets }` / `{ secret }`) shared by the vault record, the managed client, the platform-api store and the Svelte client; inputs and responses are parsed, never `as`-cast. | here | `domain/client/__tests__/client-strict.test.ts`, `surfaces/svelte/__tests__/runtime.test.ts` |
+| Transport (`src/transport/*`, `./transport`) | The one place the network-facing code parses a target and bounds I/O, re-exported for provider backends composing this package: `parseSecureUrl` (`https`, or loopback `http` only when `runtime.scope.qualifiers.dev`, no userinfo), `redactUrlForDisplay` / `scrubUrlFromText` (scheme, host and path only in any line; the query and a username-only userinfo are scrubbed too), `isSendableHeaderValue` / `setHeaderValue` (a header value is bytes: no code unit above U+00FF, no control character but a tab; the runtime's `Headers`/`fetch` `TypeError` quotes the value, so every credential-bearing header is checked by shape first, and a throw from `Headers` becomes an outcome, never the quoting message), `readBoundedText` (a body read in bytes, stopped at the cap, never mid-character), `parseJsonBody` (a body parsed with a schema, the parser's error returned as data, never quoted), `readHostTextFile` (a host file through the filesystem adapter, size-bounded by the adapter's own bounded read, `readFileVersioned` with `maxBytes`, never a stat followed by an unbounded read, so a file that grows or a FIFO cannot outrun the cap; typed `host-file-missing` / `host-file-unreadable` / `host-file-too-large`, and `filesystem-versioned-file-unavailable` for an adapter that cannot bound a read). | here | `transport/__tests__/transport.test.ts`, `transport/__tests__/host-file-bounded.test.ts` |
+| Manifest (`./manifest`) | An import manifest whose every entry names a declared source. The one `.env` grammar lives here (`parseDotenv`, `dotenvValues`, `formatDotenvEntry`, `serializeDotenv`; `src/domain/manifest/dotenv.ts`): `KEY=value` and `export KEY=value` lines, `'literal'`, `"escaped"` (`\\` and `\"`, nothing else) and bare values (a whitespace-then-`#` comment ends a bare value), a repeated key last-wins, nothing expanded (`$` is text, `\n` is a backslash and an `n`); a write refuses a value with a line break, `\r` or NUL (`INVALID_INPUT secret-value-invalid`) and a key that is not environment-variable shaped, writes plain values bare, single-quotes any other value without a `'`, else double-quotes it; what it writes it reads back exactly. `import`, `export` and `env-file` all use it. | here | `manifest/__tests__/import-manifest.test.ts`, `manifest/__tests__/dotenv.test.ts` |
+| Private publish (`src/support/private-file.ts`, `publishPrivateFile(adapter, path, bytes)`) | Every secret-bearing file this package writes (vault, `.env.<tier>`, export, drift index) is published through the adapter's `writeFilePrivate`: same-directory temporary file, 0600, renamed over the target, so a reader sees the old or the new bytes; a symlink, a non-regular entry or an adapter without `owner-private` is the adapter's typed refusal. A target an earlier plain write left accessible to others (every real vault is 0644) is HEALED without the path ever being absent: the new bytes are published 0600 under a same-directory sibling name (`.vibes-heal-<uuid>`, through `writeFilePrivate`) and then renamed over the target. A rename over an existing file is atomic, so the path names the complete old file until the instant it names the complete new one; no step removes it, the old bytes are never read or held, and a reader (or a crash) between any two steps finds a whole vault, never `ENOENT` (an empty vault whose next `set` would write a one-key vault). If any step fails the old file is still at the path, the sibling is removed, and the failure is rethrown typed (`UNAVAILABLE private-file-unwritable`, cause kept); a sibling that cannot be removed is named in `details.temporaryFile`, so nothing is left unaccounted. A parent directory others can write is NOT healed: it is `PERMISSION_DENIED filesystem-private-parent-shared` with a recovery hint to remove group and other write on the directory, and nothing is written. Same-process writers of one file are serialized (`src/support/path-queue.ts`); separate processes are not coordinated. | here | `__tests__/private-file.test.ts` |
+| Client (`./client`) | `SecretsClient`, `EnvSecretsHandle`, `ManagedSecretsHandle`; no backend for a tier is `UNAVAILABLE secrets-store-unavailable` and no cloud-api adapter `UNAVAILABLE storage-cloud-api-unregistered`; a create or update is parsed with `createSecretInputSchema` / `updateSecretInputSchema` (`INVALID_INPUT managed-secret-input-invalid`, with a fixed value-free diagnostic and no input-derived details; an update cannot carry a scope); every record is parsed with the wire schema and a missing required, unparseable, or out-of-range date is `INTERNAL secret-record-date-invalid`; other malformed fields are `INTERNAL managed-secret-record-invalid`; `list` passes `where: { scope, scopeId }` to the store (the cloud-api record adapter still lists the whole collection and filters in the adapter: a storage-owned limit) and still checks every row it gets back. | here | `domain/client/__tests__/client-strict.test.ts`, `domain/client/__tests__/managed-handle*.test.ts` |
+| Plugin (`./plugin`) | Registers the kind, docs, vault transform and client once; the attestation kind, descriptor and loader are registered by `./attestation` only (the plugin composes it, idempotently). One CLI plugin id (`@vibesdotdev/secrets/cli`). | here | `__tests__/plugin.test.ts` |
+| Attestation (`./attestation`) | As the Hard rules: private claim file through the filesystem adapter; typed refusals; `claimPath` parsed on create and read (typed `INVALID_INPUT local-attestation-claim-path-invalid`); a failed `dispose` can be retried; on `win32` the temporary file is removed when its write or rename fails (a removal that fails is `UNAVAILABLE local-attestation-claim-unwritable`, the write failure its cause) and a non-text read is a typed invalid claim. | here (token class: `@vibesdotdev/kernel`) | `domain/attestation/__tests__/attestation-hardening.test.ts` |
+| Exec (`./exec`) | Kernel-composed replace env; options parsed; a null or malformed lease is `INVALID_INPUT credential-lease-invalid`; one audit line per attempt including a refusal before spawn; options and every lease are parsed (`INVALID_INPUT spawn-options-invalid`) from one read of the caller's object, and an options object whose getter throws or whose Proxy traps ends as that same typed, audited refusal, never an escape; the audit line is written to the handed runtime's `runtime/stdio` stderr (`writeLeverageAudit`), a refusal carrying its typed `reason`; redaction covers the exact value and its base64 (padded or not), base64url, URL-encoded, form-encoded and hex (either case) forms, in one left-to-right pass that takes the longest form at each position (a value that contains another is replaced whole, a marker is never rescanned, and a stream decides a position only once every form that could start there is in view, so the result is the same at every chunk split), minimum value length 4 (`MIN_REDACTABLE_VALUE_LENGTH`: a 1-3 character credential is `INVALID_INPUT secret-value-invalid` where it is admitted, never redacted as ordinary text); a stdin write is bounded by `stdinTimeoutMs` (default 10 s: the child is killed and the spawn is `TIMEOUT stdin-write-timeout`). | here (the one redactor: pm, infra-deploy, forge, cloudflare and forge-ci-worker copies move onto it) | `exec/__tests__/*` |
+| Requirements resolver (`./requirements`) | Reads descriptors from the runtime registry; the directory walk and the config import go through the handed runtime's `runtime/loader` (`listDirectory`, `stat`, `joinPath`, `importModule`; no `node:` module is imported, no cache-busting query string); a config that fails to load, mismatches its schema or declares no app id is a named `failures` entry with a typed `reason` (`requirements-config-load-failed`, `-config-invalid`, `-appid-missing`), never counted as loaded and never an empty success; a host with no usable loader is `requirements-loader-unavailable`; descriptors from `assets()` are parsed (`requirements-descriptor-invalid`); depth (6) is capped silently, breadth is capped and named (`requirements-walk-capped`: 5000 entries per directory, 20000 directories, 1000 configs). | here (host loading: the runtime module loader) | `domain/requirements/__tests__/resolver-hardening.test.ts`, `__tests__/resolver.test.ts` |
+| Backend `encrypted-local` | Tiers local/dev/staging. The environment is a tier name (`INVALID_INPUT scope-invalid`). The decrypted vault is parsed with a schema and held as Maps: a document that is not a vault (not JSON, wrong shape or version, a `__proto__` name) is `INTERNAL encrypted-local-corrupt`, a ciphertext that does not decrypt (wrong key, truncated) is `INTERNAL secrets-vault-undecryptable`; entries are looked up by own entry only (`get('local', 'toString')` is `undefined`); a key `assertSecretKey` refuses (`__proto__`, `constructor`, `../x`, a newline, empty, over-long) and a value that is not a string or over 1 MiB are refused before any read or write, and `setAll` lands all entries or none; the file is published through `publishPrivateFile` (0600, atomic, an old 0644 vault healed); concurrent writers in one process are serialized (20 concurrent sets all land); `unset` of an absent key writes nothing; a read failure other than absence is `UNAVAILABLE encrypted-local-unreadable` with its cause. | here | `backends/encrypted-local/__tests__/*` |
+| Backend `env-file` | `.env.<tier>` under the declared directory, read and written through the host's filesystem adapter (`binding: false`) with the one `./manifest` grammar. The environment is validated against the tier list before a path is built (`../` is `INVALID_INPUT scope-invalid`, nothing written outside); keys are environment-variable shaped (`assertEnvironmentSecretKey`); a value with a newline, `\r` or NUL is `INVALID_INPUT secret-value-invalid`, any other value is quoted so that `set` then `get` returns it exactly; comments, blank lines, order and untouched entries are written back as they were; a write that would leave the file as it is (`unset` of an absent key, the same value again) writes nothing, and the line of a key set to the value it already holds is left exactly as written (`export KEY=v # comment` keeps its `export` and its comment); `getAll` surfaces the file's keys as written (a `__proto__` key stays an own key and pollutes nothing); the file is published through `publishPrivateFile`; same-process writers are serialized; a read failure other than absence is `UNAVAILABLE env-file-unreadable` with its cause. | here | `backends/env-file/__tests__/*` |
+| Backend `mounted-files` | As the Hard rules text: read-only, typed, through the host's filesystem adapter (`binding: false`; the app that composes it registers one). `list` names the credential files and never opens them (`hasValue` is the listing's non-empty size; a symlinked entry, as a Kubernetes volume projects, is not followed and reads as set), so one unreadable file cannot fail it, and a name the store would refuse (`__proto__`, a control character) is not listed; `get` and `getAll` read at most 64 KiB through the adapter's bounded `readFileVersioned` (`INVALID_INPUT mounted-file-too-large`, the file never read whole; an adapter without `versioned-file` is `UNAVAILABLE filesystem-versioned-file-unavailable`, never read around); an unreadable file is `UNAVAILABLE mounted-file-unreadable` (errno kept) where it is read, and `getAll` does not hide it; no error carries the key. | here | `backends/mounted-files/__tests__/*` |
+| Backend `host-credentials` | As the Hard rules text; the manifest is read from the captured snapshot and parsed on every call (a changed, replaced, stale or removed manifest is seen by the next read); a key `assertSecretKey` refuses is `INVALID_INPUT secret-key-invalid` before the manifest is read, lookups are own-property of the snapshot; a pid publisher on a runtime whose process provider cannot read a start time is `UNAVAILABLE process-start-unsupported`, on a runtime with no process provider `process-unavailable`, before the value is read. | here (grammar: `@vibesdotdev/kernel`) | `backends/host-credentials/__tests__/*` |
+| Every file-backed and host-backed store (hostile keys) | `__proto__`, `constructor`, `prototype`, `../x`, `/abs`, `..\x`, a newline, a NUL, empty and 4 MB keys on `get`, `set`, `unset` and `setAll` of `encrypted-local`, `env-file`, `mounted-files` and `host-credentials`: refused (`INVALID_INPUT`, or `store-read-only` for a write to a read-only store), the error never carries the key, no file created or changed, `Object.prototype` untouched. | here | `backends/__tests__/hostile-keys.test.ts` |
+| Backend `platform-api` (moved: `@vibesdotdev/integrations-vibes/secrets/platform-api`) | By-id bridge to `/api/secrets`: the origin must parse as `https` (loopback `http` only when the runtime scope is a development host, `qualifiers.dev`; no userinfo, query or fragment) or the store is refused `INVALID_INPUT platform-origin-invalid` before any request, so the bearer is never sent; a configured scope is parsed (`platform-scope-invalid`); responses are parsed with the shared wire schema (`{ results }`, `{ result }`, `{ id, value }`; a body that is not that is `INTERNAL platform-api-response-invalid`); 401 is `AUTH_REQUIRED platform-api-unauthenticated`, 403 `PERMISSION_DENIED platform-api-forbidden` (never absence), 5xx a retryable `UNAVAILABLE platform-api-unavailable`, and a 404 is `undefined` only for a reveal; lists page (100 a page, at most 100 pages) until exhausted so `set` never creates a duplicate, and a server that repeats a page is `platform-api-pagination-stalled`; every request has a deadline (`PLATFORM_API_REQUEST_TIMEOUT_MS`, 15 s; `UNAVAILABLE platform-api-timeout`, retryable, as is `platform-api-unreachable`), follows no redirect (`platform-api-unexpected-redirect`) and has its response read in bounded bytes; an unconfigured store is `UNAVAILABLE platform-api-unconfigured` (not retryable); a keychain that cannot be read, whatever the store's own failure, is `UNAVAILABLE platform-api-keychain-unreadable` carrying that failure as the cause, not "unconfigured"; a bearer no header can carry is `INVALID_INPUT platform-api-token-invalid` before any request, never quoted; keys through `assertSecretKey`, values through `assertSecretValue`; error text never echoes a response body. | here | `integrations-vibes/secrets/platform-api/__tests__/*` (`platform-api.wire.test.ts`) |
+| Backend `vault` (client, impl) | KV v2, by id: every failure is a typed `CapabilityError`; a KV 404 is `NOT_FOUND vault-path-absent` carrying `details.kind: 'secrets/vault'` and the path, so `isAbsenceOf(error, 'secrets/vault', path)` matches and `get`, `list`, `getAll` skip a missing path while `set` creates it; 401 `AUTH_REQUIRED vault-unauthenticated`, 403 `PERMISSION_DENIED vault-forbidden`, 5xx `UNAVAILABLE vault-unavailable`, a redirect `vault-unexpected-redirect` (the error never echoes where the `Location` pointed, only whether it points back at the same address); the address (the value the descriptor's `addressCredentialKey` resolves to through the credential stores, which takes precedence, else the descriptor's `address`, and every unseal-source address; the Kubernetes role likewise from `k8sRoleCredentialKey` when `k8sRole` is not declared, and the token from `tokenCredentialKey`/`tokenEnvVar`; the backend reads no ambient environment and names no default key) is parsed with `parseSecureUrl` BEFORE any request or credential read: `https`, or loopback `http` only when the runtime is a development host, with no userinfo, query or fragment, else `INVALID_INPUT vault-address-invalid` and nothing is sent (no token, service-account JWT or unseal key crosses plain `http`); a token no header can carry is `INVALID_INPUT vault-token-invalid` before it is sent, never quoted; bodies are parsed with schemas (`INTERNAL vault-response-invalid`) and never echoed; `listKVPaths` (`GET ?list=true`: Bun's fetch rewrites the `LIST` verb to `GET`) is `[]` only for a missing path and fails typed otherwise; lookups are own-property and `get`/`set`/`unset` refuse a key `assertSecretKey` refuses; the descriptor's `paths` (comma-separated, required: `INVALID_INPUT vault-paths-undeclared`) order reads (first holder wins) and `writePath` (else the first path) takes new keys, so no stale copy returns; an address neither the descriptor's credential key resolves nor its `address` declares is `UNAVAILABLE vault-address-unconfigured` (not retryable); `staging` and `production` use their own mounts and `local` and `dev` are refused `INVALID_INPUT vault-environment-unsupported` unless the descriptor declares `config['mount.local']` / `config['mount.dev']`; every request has a deadline (`VAULT_REQUEST_TIMEOUT_MS`, 15 s; `vault-timeout`, `vault-unreachable`); the Kubernetes service-account token is read through the filesystem adapter (no token and no readable file is `AUTH_REQUIRED vault-unauthenticated`, never a `file://` fetch); unseal keys (`VAULT_UNSEAL_KEY_1`…`_10`, `VAULT_UNSEAL_KEYS_JSON`) and the unseal-sources JSON the descriptor names (`unsealSourcesCredentialKey`/`unsealSourcesEnvVar`) are read only through the non-Vault credential stores, never ambient environment; a sealed Vault is `UNAVAILABLE vault-sealed`, and an unseal source that could not be read rides as the cause. | here | `backends/vault/__tests__/*` (`vault.wire.test.ts`) |
+| CLI `list` | Descriptors only. `--format json` carries `backendFailures`; one failing backend (even one that cannot be resolved) is a partial result, and only when no store could list is the command a failure; a refusal carries a reason; `--category` and `--scope` were parsed and ignored, and are removed. | here | `surfaces/cli/commands/__tests__/secrets-list-honesty.test.ts` |
+| CLI `set`, `unset`, `reveal` | The key is validated; the store is the resolver's pick (typed ambiguity, an explicit `--backend` must name a registered `secrets/store`); a stdin read is the handed runtime's `getRuntimeStdin(runtime).readStdin({ maxBytes: 64 KiB })` (bounded in the read itself; over the cap is `INVALID_INPUT secret-value-invalid` with the host's `stdio-stdin-too-large` as the cause; one trailing newline trimmed here, never by the host; a host without the read refuses `UNAVAILABLE stdio-stdin-unavailable`); `reveal` prints only to a terminal or with `--force` and asks through the terminal toolkit (`cli/ui` `confirm`), never by consuming stdin; a raw backend failure is `UNAVAILABLE store-read-failed` / `store-write-failed`; `set` reports a drift fingerprint it could not record (stderr and the JSON `fingerprint` member) with the value stored; `unset` drops the key's drift fingerprint when the index holds it (a failure to update the index is reported, the removal stands); stdin/TTY facts are the handed runtime's captured terminal facts (`localEnvironment.terminal()`: `stdinIsTerminal`, `stderrIsTerminal`, `stdinCanHideInput`), read in one place (`cli/shared/terminal-facts.ts`), never `process.stdin`/`process.stderr`; a fact the host did not observe reads as not a terminal (no prompt is offered, `reveal` refuses without `--force`). The hidden password prompt itself still reads the terminal toolkit's own stdin until the later `runtime/prompt` capability (runtime SPEC, stdin census class 3). | here | `surfaces/cli/__tests__/workflows/cli.test.ts`, `set.command.impl.test.ts`, `reveal.command.impl.test.ts` |
+| CLI `exec` | A thin wrapper over `spawnWithCredentials`; options parse to a typed `INVALID_INPUT command-options-invalid`; usage (`exec-command-missing`, `exec-keys-missing`), a missing key (`NOT_FOUND credential-not-set`) and a repeated `--with` (`exec-with-repeated`; the CLI surface refuses a second occurrence of a non-collect option, the command no longer scrapes argv) are typed like the lease path; every refusal before spawn, usage and option parsing included, is one audited failure line with its typed reason, naming only what was validated before the refusal (a rejected key, chain or pass name is never in the line); child output goes through `runtime/stdio`. | here | `surfaces/cli/__tests__/leverage/leverage-commands.test.ts`, `exec-host-credentials.test.ts`, `surfaces/cli/commands/__tests__/exec-refusal-audit.test.ts` |
+| CLI `request` | Only `https` (loopback `http` when the runtime is a development host); `file:` and every other scheme, and userinfo, are `INVALID_INPUT request-url-invalid` before any secret is read or any request built; redirects are handled explicitly (`redirect: 'manual'`): a same-origin one is followed up to 5 hops (`UNAVAILABLE request-redirect-limit`), one to another origin or scheme is `PERMISSION_DENIED request-redirect-cross-origin` and nothing is sent there; the URL is logged, warned and audited as scheme, host and path only (a fetch error's text is scrubbed of it); the response body is read in bytes up to `--max-body` (a cut never prints a prefix of 4 or more characters of a secret, or of its base64, base64url, URL-encoded, form-encoded or hex form: such a tail is trimmed; a shorter fragment is innocent output and is kept) within one deadline; a header name or value (or a secret value) that is not valid, including any code unit above U+00FF or a control character, is `INVALID_INPUT request-header-invalid` before the headers are built, never quoting it (the runtime's own `TypeError` quotes the value, so a throw from `Headers` is mapped to the same refusal without its message), and the exchange is audited as a failure; a response body that stalls past `--timeout` is `UNAVAILABLE request-timeout` (retryable, any other unreadable body `request-body-unreadable`), read BEFORE the exchange is audited, so it is audited as a failure and never as a success followed by a throw; every printed line, a transport failure's text included, is redacted by value across all resolved secrets, longest first; a bad method `request-method-invalid`, a body on GET/HEAD `request-body-not-allowed`; `--body-file` is read through the filesystem adapter (`host-file-missing`, `filesystem-adapter-not-registered`), never `file://` or the working directory; unusable options are `command-options-invalid`; output goes through `runtime/stdio`. | here | `surfaces/cli/commands/__tests__/request.command.test.ts` |
+| CLI `oauth-client mint` | `--url`, `--bearer`, `--client-id-key` and `--client-secret-key` are required (no default endpoint or key names; each absent one exits 1 naming it, sending nothing). The URL must be `https` (loopback `http` when the runtime is a development host) or it is `INVALID_INPUT mint-url-invalid` before any secret is read or any request sent; no redirect is followed with the bearer; the target store is chosen and the previous client id read BEFORE the client is minted, and a failure of any of those steps or of the pair write, once the bearer has resolved, is audited as a failure with its typed reason (one `[AUDIT]` line per attempt, like exec); the id and secret are written as a pair: if the secret cannot be stored the id is put back to what it held (or removed) and the failure is `UNAVAILABLE oauth-client-store-write-failed` naming the minted client id (never the secret) and whether the rollback also failed; a missing bearer is `AUTH_REQUIRED oauth-client-bearer-missing` (no empty-string bearer), and a bearer no Authorization header can carry (a control character, a code unit above U+00FF) is `INVALID_INPUT oauth-client-bearer-invalid` before any request, never quoted; the target store is the kind's own pick over the tier's local stores (`env-file`, `encrypted-local`) or the named `--backend` (`store-ambiguous` on a priority tie, `secrets-store-unavailable` when none), never a sorted first; every failure line (a transport error, the status line, the first 200 characters of an error body) is redacted by VALUE (`redactForPrint`) before it is cut, so a server that echoes the bearer cannot leak it; `--timeout` must be a positive whole number of milliseconds (`INVALID_INPUT command-options-invalid`, never silently 30000); a fetch error and the printed target are scrubbed of the URL's query and userinfo; output goes through `runtime/stdio`. | here | `surfaces/cli/commands/oauth-client/__tests__/mint.test.ts` |
+| CLI `check`, `pull`, `push`, `import`, `export` | `check` as the Hard rules (a bad `--store-timeout-ms` is `INVALID_INPUT store-timeout-invalid`; the unknown-app JSON error is the `CapabilityError` envelope, `INVALID_INPUT unknown-secret-requirement-app`; availability is evidence from every scope store serving the tier, not one pick); `pull` and `push` hard-code no backend id: `--from`/`--to` name a registered store, else the one store serving the tier (`pull`: the environment's tier, destination the `local` tier; `push`: destination the environment's tier, source the `--source-env` tier, default `local`), a source that lists keys it cannot return is `UNAVAILABLE secret-write-only`, a store onto itself is `INVALID_INPUT store-source-equals-target`, `--key` values are validated; `push --app` with an unknown target is `INVALID_INPUT` like `check`; `import --source` must name a declared source of the manifest by own entry (`constructor`, `toString` and `__proto__` are an unknown source, refused before any file is read); `import --to` is the named store, or `encrypted-local` when not given, and it must be a registered `secrets/store` (`INVALID_INPUT store-unknown`, never a silent other store); descriptors are parsed, not cast; `import` reads its sources through the handed runtime's `filesystem/adapter` (the host's own files, not a workspace-rooted view): an absent source contributes nothing, any other read failure is `UNAVAILABLE import-source-unreadable` with its cause, and a runtime with no adapter refuses; the `.env` parser is the one `./manifest` parser and reads back every value `export` writes (quotes, `$`, backslash, whitespace); `import`, `pull` and `push` record drift fingerprints like `set` (a drift index that cannot take them is reported on stderr, the import has landed); `export` resolves `--out` and the adapter before any secret is read, refuses a key a `.env` file cannot hold and a value with a line break (`secret-value-invalid`, no file written), writes the file through `publishPrivateFile` (0600, a same-directory temporary file the adapter removes if the write fails; an existing file is replaced, healing a 0644 one), and audits after the write: `success` only once the file is published, `failure` with the refusal's reason otherwise; `--force` skips the bulk-reveal confirmation and nothing else (the prompt, through `cli/ui`, says when it replaces a file). | here | `surfaces/cli/__tests__/transfer/import-export.test.ts`, `surfaces/cli/commands/maintenance/check/secrets.check.drift-refused-key.test.ts` |
+| CLI output (`surfaces/cli/shared/output/command-output.ts`) | `set`, `list`, `reveal`, `request`, `exec` and `oauth-client mint` write through the handed runtime's `runtime/stdio` (`openCommandOutput`), never the process console: a result is a stdout line, a diagnostic (usage, refusal, skipped backend, not-set notice) a stderr line. A host with no text output refuses `UNAVAILABLE stdio-unavailable` before the command does any work. Exit status stays `requestCLIExit`'s. | here | `surfaces/cli/shared/__tests__/command-output.test.ts`, `surfaces/cli/__tests__/set/set.command.impl.test.ts`, `surfaces/cli/commands/__tests__/secrets-list-honesty.test.ts` |
+| CLI `pre-commit-check` | `--workspace` resolves against the host's captured cwd with the runtime's path mechanics (`paths/runtime-path`); a host with no cwd refuses `UNAVAILABLE cwd-unavailable` first. Scans staged blobs (`git diff --cached -z --diff-filter=ACMR`, renames included, submodule pointers excluded; git runs through the handed runtime's `runtime/execution`); a git failure is a thrown `UNAVAILABLE pre-commit-git-failed` (non-zero), never a pass; a finding prints the signature, path, line and match length, never any of the credential. One signature table (`SECRET_PATTERNS`, `scanTextForSecretPatterns`: `src/support/credential-signatures.ts`, exported from `.`) for `security` and `internal-checks`, whose own copies move onto it. | here | `surfaces/cli/__tests__/precommit/pre-commit.test.ts`, `surfaces/cli/commands/maintenance/hooks/__tests__/pre-commit-secrets.test.ts` |
+| Drift fingerprints | HMAC-SHA256 (Web Crypto) index under `<activeHome>/secrets` through the filesystem adapter (`driftFingerprintHome(runtime)` is asynchronous and every function that touches the files takes the resulting `DriftHome`); the checker key (32 bytes) is created through the adapter's `createFileExclusive` (descriptor and method checked: `UNAVAILABLE filesystem-exclusive-create-unavailable` otherwise; of 10 concurrent creators one wins and all read its key), is read only while owner-private, and a wrong-sized key is `INTERNAL data-corrupt`; the index is published through `publishPrivateFile` (a 0644 index is healed), same-process read-modify-writes are serialized (20 concurrent records all land); a key `assertSecretKey` refuses, or an environment or backend name with a refused segment, is `INVALID_INPUT secret-key-invalid` and writes nothing; lookups are own-property in every direction (a backend named `toString` is data; a key named `toString` or `valueOf` is held only by the stores that recorded it, never read through a table's prototype into a false match or divergence); a key a store lists but refuses by its key rule (`secret-key-invalid`) is that key's `unknown` in `check --drift` (row status `unknown`, `drift.unreadableKeys`, drift status `unknown`, non-zero exit), never the whole store's: the store's other keys are still read and compared, while a deadline or other failure still marks the store unknown; a corrupt index is `INTERNAL data-corrupt`, an unreadable one `UNAVAILABLE drift-index-unreadable`, never an empty index. | here | `surfaces/cli/shared/__tests__/drift-fingerprints.test.ts` |
+| Svelte (`./svelte`) | The browser client and state for `/api/secrets`, reading the one wire envelope (`{ results }` / `{ result }`; rotate is the rotate route then a `get`, because the route acknowledges `{ success: true }`); there is no module-global state: a state belongs to a runtime scope (`secretsStateFor(scope)`, reached by components through `getSecretsState()`, owned by the request's runtime Svelte store before activation, then by the resolved surface client; a server render with no enclosing scope is `UNAVAILABLE secrets-state-no-scope`, a browser document owns a compatibility adapter cleared on pagehide; runtime-backed state and transport belong to the secrets.svelte runtime/client) and `createSecretsState()` makes an independent one; `init` records its in-flight promise before its first await so concurrent callers issue one request; the loader's `throwOnError` is removed and a failing fetcher propagates (an empty list that hides a failure was the alternative); a server message is control-stripped and bounded to 200 characters, a non-JSON body is never echoed; the account origin is the runtime's (host origin, else config; neither is `INVALID_INPUT account-origin-undeclared`), never a caller stylesheet URL (`themeStylesheetUrl` is removed), and must be `https` (loopback `http` on a development host) or `INVALID_INPUT account-origin-invalid`; every request has a deadline (`account-secrets-timeout`, `account-secrets-unreachable`) and is sent with `redirect: 'error'` (a redirect would carry the credential), and a token no header can carry is `INVALID_INPUT account-token-invalid` before a client exists; an uninitialized state is `UNAVAILABLE secrets-state-uninitialized`; disposed state is `UNAVAILABLE secrets-state-disposed`. Late completions cannot repopulate disposed state. State and component failures use fixed messages and logs use value-free operation facts, never identifiers, caught messages or patch metadata. Component event, mount, and clipboard timer callbacks handle failures without rethrowing into unhandled-rejection reporting; awaited programmatic APIs retain failure propagation. | here (opt-in subpath) | `surfaces/svelte/__tests__/*` |
+| TUI (`./tui`) | `/secrets` inspector; no silent tier default; one failing backend is a partial result like the CLI. | here | `surfaces/tui/__tests__/*.test.tsx` |
+| Docs descriptors | Topics state `resolve()` (not `first()`), and name each backend truthfully (`env-file` is plaintext). | here | `__tests__/docs-topics.test.ts` |
+
+## Managed projections
+
+The registered secrets client and browser account client share the managed create transport schema: editor `id` is omitted, `description` merges into metadata, and scope identity comes from the managed handle. Create and update reject before transport with `INVALID_INPUT managed-secret-input-invalid`, the fixed message `The managed secret input is invalid.`, and no input-derived details.
+
+Managed record and storage-row projection schemas validate dates while producing public summaries. Missing required dates, unparseable dates, and out-of-range epochs refuse `INTERNAL secret-record-date-invalid`. Optional absent dates become null. Other malformed fields refuse `INTERNAL managed-secret-record-invalid`. Projections exclude plaintext values, encrypted values, and creator identity. Composed coverage resolves the registered secrets client and real cloud-api adapter, faking the remote service only.
+
+## Inputs
+
+TRUSTED: the runtime handed in; descriptors the host composed; package
+constants; the kernel's credential grammar.
+
+| Entry point | Untrusted input | How it is read | Test |
+|---|---|---|---|
+| Every store method | key, value | key through `assertSecretKey` and own-property only; value a string with a size cap | `backends/__tests__/hostile-keys.test.ts` (`__proto__`, `constructor`, `../`, newline, empty, 4 MB) |
+| `encrypted-local` file | the vault file bytes | decrypted, then parsed with a schema; a document that is not a vault (including a `__proto__` name) is `encrypted-local-corrupt`; a ciphertext that does not decrypt (wrong key, truncated) is `secrets-vault-undecryptable` | `encrypted-local/__tests__/` (truncated, wrong key, `__proto__` JSON) |
+| `env-file` | tier, the `.env` file | tier from the tier list (`scope-invalid`); the file parsed by the one parser | `env-file/__tests__/` |
+| `mounted-files` | file names and sizes in the mount | key a plain name; size-bounded read | `mounted-files/__tests__/` |
+| `platform-api` (in `integrations-vibes`) | the origin, response bodies, status codes | origin parsed and `https` (loopback `http` on a development host) before any request; body read in bounded bytes and parsed with the response schema; status mapped to a typed refusal, a body never echoed | `integrations-vibes/secrets/platform-api/__tests__/platform-api.wire.test.ts` |
+| `vault` | token file, response bodies, KV paths, the environment | token via the filesystem adapter; bodies parsed; paths from a fixed list and keys from `assertSecretKey`; the environment mapped to a mount or refused | `vault/__tests__/vault.wire.test.ts` |
+| Attestation | `claimPath`, claim bytes | `claimPath` parsed; bytes at most 1024 and a secret token | `domain/attestation/__tests__/` |
+| Exec | `--with` keys, leases, child output | keys validated; leases parsed; output redacted before it is written | `exec/__tests__/` |
+| Requirements | descriptors, workspace config modules | registry descriptors parsed; a config load failure named | `domain/requirements/__tests__/` |
+| `request`, `mint` | URL, headers, method, body file, redirects, response, options | URL parsed and scheme-checked before any secret is read; headers and method validated; body file through the filesystem adapter, size-bounded; response read in bounded bytes; no redirect to another origin; options parsed to `command-options-invalid` | `surfaces/cli/commands/__tests__/request.command.test.ts`, `surfaces/cli/commands/oauth-client/__tests__/mint.test.ts` |
+| `import`, `export` | `.env` text, destination path | one parser; destination written owner-private | `surfaces/cli/__tests__/` |
+| `pre-commit-check` | staged paths and blobs | `git ... -z`; a git failure is fatal | `surfaces/cli/__tests__/precommit/pre-commit.test.ts` |
+| Svelte client | the account origin, `/api/secrets` bodies, server messages | origin from the runtime and `https`; body bounded and parsed with the wire schema; message control-stripped and bounded | `surfaces/svelte/__tests__/` |
+| Environment variables | none read here | the runtime's declared environment (`VIBES_SECRETS_MOUNT_DIR`, host credentials manifest) | existing |
+
+## Refusals
+
+| Code | Reason | When |
+|---|---|---|
+| `INVALID_INPUT` | `secret-key-invalid`, `secret-value-invalid`, `scope-invalid` (an environment that is not a tier), `mounted-key-invalid`, `mounted-file-too-large`, `backend-chain-unsupported`, `store-ambiguous`, `store-descriptor-invalid`, `store-context-invalid`, `store-recursion`, `store-unknown`, `store-source-equals-target`, `command-options-invalid`, `spawn-options-invalid`, `store-timeout-invalid`, `unknown-secret-requirement-app`, `exec-command-missing`, `exec-keys-missing`, `exec-with-repeated`, `local-attestation-claim-path-invalid`, `credential-lease-invalid`, `request-url-invalid`, `request-header-invalid`, `request-method-invalid`, `request-body-not-allowed`, `mint-url-invalid`, `command-options-invalid`, `platform-origin-invalid`, `platform-scope-invalid`, `platform-api-scope-id-missing`, `platform-api-rejected`, `vault-environment-unsupported`, `vault-paths-undeclared` (no descriptor `paths`), `vault-unseal-sources-invalid`, `vault-unseal-keys-invalid`, `vault-rejected`, `vault-address-invalid` (a Vault, or unseal-source, address that is not `https` or development-host loopback `http`, or carries userinfo, a query or a fragment), `vault-token-invalid` (a token no header can carry), `platform-api-token-invalid` (a bearer no header can carry), `account-token-invalid`, `account-origin-invalid`, `account-origin-undeclared` (neither host nor config names one), `managed-secret-input-invalid`, `host-file-too-large`, `backend-invalid` (an empty `--backend`), `pass-name-invalid` and `pass-name-reserved` (`exec --pass`), `lease-name-conflict` (a caller-held lease named like a credential or pass), `manifest-invalid` (the host-credentials manifest absent from the captured environment), `oauth-client-bearer-invalid` (a bearer no Authorization header can carry) | an input fails its parse or a bound |
+| `NOT_FOUND` | `credential-not-set`, `vault-path-absent` (carries `details.kind: 'secrets/vault'` and the path), `platform-api-not-found`, `host-file-missing` | the kernel's absent-credential answer, or a confirmed absent path or file |
+| `AUTH_REQUIRED` | `host-credentials-stale`, `platform-api-unauthenticated`, `oauth-client-bearer-missing`, `vault-unauthenticated`, `not-signed-in` | the credential holder is gone or absent |
+| `PERMISSION_DENIED` | `store-read-only`, `filesystem-private-parent-shared` (a directory others can write; the adapter's other `filesystem-private-*` refusals pass through unchanged), `local-attestation-claim-insecure`, `platform-api-forbidden`, `vault-forbidden`, `request-redirect-cross-origin`, `principal-key-reserved` (`exec --with VIBES_AUTH_TOKEN` or `--pass VIBES_AUTH_TOKEN`: the operator's bearer is never read from a store; `host-credentials` refuses the same key) | the contract refuses |
+| `RATE_LIMITED` | `platform-api-rate-limited`, `vault-rate-limited` | the service asked the caller to slow down; retryable |
+| `TIMEOUT` | `stdin-write-timeout` (a child that never reads its stdin), `wait-timeout` (a bounded store probe) | a declared deadline passed |
+| `UNAVAILABLE` | `process-start-unsupported`, `process-unavailable`, `local-attestation-claim-missing`, `mounted-file-unreadable`, `encrypted-local-unreadable`, `env-file-unreadable`, `import-source-unreadable`, `drift-index-unreadable`, `private-file-unwritable`, `filesystem-versioned-file-unavailable`, `filesystem-exclusive-create-unavailable`, `filesystem-private-unavailable`, `platform-api-unconfigured` (not retryable), `platform-api-timeout`, `platform-api-unreachable`, `platform-api-unavailable`, `platform-api-unexpected-redirect`, `platform-api-keychain-unreadable`, `platform-api-origin-unresolved`, `vault-unreachable`, `vault-timeout`, `vault-unavailable`, `vault-address-unconfigured` (not retryable), `vault-sealed`, `vault-not-initialized`, `vault-unexpected-redirect`, `request-redirect-limit`, `request-timeout` (the response body of `request` did not finish within `--timeout`; retryable), `oauth-client-store-write-failed`, `account-secrets-timeout`, `account-secrets-unreachable`, `secrets-state-uninitialized`, `secrets-state-no-scope`, `secrets-store-unavailable`, `secrets-store-unregistered`, `storage-cloud-api-unregistered`, `host-file-unreadable`, `filesystem-adapter-not-registered`, `stdio-unavailable`, `execution-unavailable`, `store-read-failed`, `store-write-failed`, `secret-write-only`, `pre-commit-git-failed`, `requirements-loader-unavailable`, `local-attestation-claim-unwritable`, `cwd-unavailable` (a host with no captured working directory), `filesystem-adapter-unavailable` (the adapter query resolved nothing), `lease-expired` (a caller-held lease past its `expiresAt`), `request-body-unreadable` (the response body of `request` could not be read) | a precondition is absent; retryable only where the code says (a timeout and an unreachable service are) |
+| `INTERNAL` | `encrypted-local-corrupt`, `secrets-vault-undecryptable`, `data-corrupt` (a drift index or checker key that is not what this package wrote), `local-attestation-claim-invalid`, `platform-api-response-invalid`, `platform-api-response-too-large`, `platform-api-pagination-stalled`, `platform-api-list-too-large`, `vault-response-invalid`, `vault-response-too-large`, `managed-secret-record-invalid`, `oauth-client-response-too-large`, `tier-undeclared` (the runtime scope declares no environment tier), `runtime-unavailable` (the host-credentials plugin handed no runtime), `secret-record-date-invalid` (a managed row with a date that is not a date), `secrets-vault-unwritable` (the encrypted-local vault could not be encrypted or saved; cause kept), `stdin-unavailable` (an execution provider gave no stdin pipe for a child that was to receive stdin), `secret-stdin-read-failed` (`secrets set` read stdin through the host and the host failed untyped; the failure is the cause, never the message) | stored content, or a service's answer, is not what this package expects |
+| (a `failures` entry, not thrown) | `requirements-loader-unavailable`, `requirements-config-load-failed`, `requirements-config-invalid`, `requirements-appid-missing`, `requirements-descriptor-invalid`, `requirements-walk-capped`, `requirements-walk-unreadable` | requirements discovery names what it could not read in `discovery.failures` (value-free, with the path) instead of throwing, so one bad config never hides the rest |
+