first commit

docs/security-stack/security/vault/src/errors/codes.md

@@ -0,0 +1,55 @@
+# vault error codes
+
+## Purpose
+
+`codes.ts` defines the stable error-code registry for `@suaveplan/vault`. Every failure raised by the orchestration layer — locked-state rejections, bad-credential unlocks, manifest tampering, item validation, attachment / share / sync failures, and opaque-handle violations — carries one of these literal codes. The codes are frozen at module-load via `defineCodes("VAULT", [...])` so consumer code can assert on the exact strings without depending on JavaScript identifier ordering or import-time side effects.
+
+The codes form the discriminated-union narrowing surface for `VaultError`. Together with the `VaultError` class they form the complete error contract: callers `import { VAULT_CODES, VaultError, type VaultErrorCode } from "@suaveplan/vault/errors"`, branch on `err.code`, and let TypeScript exhaustively check the switch.
+
+## Features
+
+- Two-level namespacing — `VAULT.LOCKED` for top-level lifecycle errors, `VAULT.ITEM.NOT_FOUND` for module-scoped errors. The dot-separated form is searchable and groups related failures (`ITEM.*`, `ATTACHMENT.*`, `SHARE.*`, `SYNC.*`).
+- Every code is a literal string in the `VaultErrorCode` union — no enum cost, no value coupling.
+- Hard-frozen registry — `defineCodes` returns a frozen object so consumers cannot accidentally mutate or extend the registry at runtime.
+
+## Usage: Basic Example
+
+```ts
+import { VAULT_CODES, VaultError } from "@suaveplan/vault/errors";
+
+throw new VaultError(VAULT_CODES.LOCKED, "error.vault.locked");
+```
+
+## Usage: Advanced Example
+
+```ts
+import { VAULT_CODES, VaultError, type VaultErrorCode } from "@suaveplan/vault/errors";
+
+function describe(err: VaultError): string {
+    const code: VaultErrorCode = err.code;
+    switch (code) {
+        case VAULT_CODES.LOCKED:
+            return "Vault is locked — call unlock() first.";
+        case VAULT_CODES.INVALID_CREDENTIALS:
+            return "Wrong password or secret key.";
+        case VAULT_CODES["ITEM.NOT_FOUND"]:
+            return "Item does not exist in this vault.";
+        case VAULT_CODES["ITEM.VERSION_CONFLICT"]:
+            return "Item was modified concurrently — refetch and retry.";
+        // ... exhaustive
+        default:
+            return "Unknown vault error.";
+    }
+}
+```
+
+## API Reference
+
+- `VAULT_CODES` — frozen `Record<string, "VAULT.X.Y">` literal registry.
+- `VaultErrorCode` — union of every value in `VAULT_CODES`.
+
+## Implementation Notes
+
+- The registry is intentionally fixed in source — adding a code is a public-API change requiring an OpenSpec proposal and a coordinated release with consumers.
+- `defineCodes("VAULT", [...])` automatically prefixes each entry with `VAULT.`; the source array contains the unqualified suffix so visual scanning stays compact.
+- Sub-namespaces (`ITEM`, `ATTACHMENT`, `SHARE`, `SYNC`) match the file layout under `src/` so locating a code's emission site is mechanical.