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

Zod schemas

(no submodules)

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

import { Argon2idParamsSchema } from "@suaveplan/crypto-vault/schemas/schemas";

const params = Argon2idParamsSchema.parse({
    memoryKB: 65536,
    iterations: 3,
    parallelism: 4,
    outputLength: 32,
});

Usage: Advanced Example

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 Uint8Arrays (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.