Move docs/ package mirror into document-navigator plugin

Relocate the ~6k-file docs tree from the repo root into
plugins/document-navigator/docs/ so the plugin is self-contained and
portable. docs/superpowers/ (specs and plans) stays at the repo root.

Moved via cp+rm rather than git mv because directory rename() fails with
EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the
identical-content files at commit time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-30 01:10:00 +01:00
parent fe3fedf42e
commit 9bf56a806b
6022 changed files with 12437 additions and 0 deletions

View File

@@ -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.