first commit

docs/security-stack/crypto/crypto-vault/src/schemas/schemas.md

@@ -0,0 +1,86 @@
+# Zod schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`schemas.ts` exposes Zod schemas for every public-surface shape that
+`@suaveplan/crypto-vault` accepts or returns. Schemas are the runtime
+counterpart to the TypeScript types in `types/types.ts` — consumers can
+parse caller-supplied JSON, configuration, or RPC payloads through these
+schemas to get the same safety guarantees the package's own validation
+provides.
+
+## Features
+
+- `Argon2idParamsSchema` — pinned to the OWASP minimums and the
+  package-internal hard ceilings for `memoryKB` and `outputLength`.
+- `AukSchema` — refines `Uint8Array` to exactly 32 bytes.
+- `HierarchyKeySchema` — same shape, used for personal-keyset slots and
+  vault/item keys.
+- `PersonalKeysetSchema` — strict object schema for the three-key bundle.
+- `Bip39StrengthSchema` — `128 | 256` literal union.
+
+## Usage: Basic Example
+
+```ts
+import { Argon2idParamsSchema } from "@suaveplan/crypto-vault/schemas/schemas";
+
+const params = Argon2idParamsSchema.parse({
+    memoryKB: 65536,
+    iterations: 3,
+    parallelism: 4,
+    outputLength: 32,
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    AukSchema,
+    PersonalKeysetSchema,
+} from "@suaveplan/crypto-vault/schemas/schemas";
+
+function importPersonalKeyset(json: unknown) {
+    const ks = PersonalKeysetSchema.parse(json);
+    AukSchema.parse(ks.encryptKey); // also valid as an AUK shape (32 bytes)
+    return ks;
+}
+```
+
+## API Reference
+
+### `Argon2idParamsSchema`
+
+Strict object schema enforcing:
+
+- `memoryKB ∈ [OWASP_MIN_MEMORY_KB, ARGON2ID_MAX_MEMORY_KB]` (integer).
+- `iterations ≥ OWASP_MIN_ITERATIONS` (integer).
+- `parallelism ≥ OWASP_MIN_PARALLELISM` (integer).
+- `outputLength ∈ (0, ARGON2ID_MAX_OUTPUT_LENGTH]` (integer).
+
+### `AukSchema`, `HierarchyKeySchema`
+
+Instance-of `Uint8Array` refined to exactly 32 bytes.
+
+### `PersonalKeysetSchema`
+
+Strict object with three `HierarchyKeySchema` fields.
+
+### `Bip39StrengthSchema`
+
+`z.union([z.literal(128), z.literal(256)])`.
+
+## Implementation Notes
+
+- The schemas import the same constants used by the runtime validators so
+  the two paths cannot drift. Adjusting an OWASP minimum updates both at
+  once.
+- `z.instanceof(Uint8Array)` is used so cross-realm `Uint8Array`s (e.g.
+  from a worker) parse correctly even though their prototype chain is
+  different — Zod's instanceof check is structural via `instanceof`.
+- Strict mode is enabled on object schemas to reject unknown keys; this
+  is intentional, as crypto-vault has zero forward-compatible padding
+  fields.