first commit

docs/security-stack/security/password-generator/src/schemas/schemas.md

@@ -0,0 +1,60 @@
+# `schemas`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Owns the Zod boundary schemas that every public generator function uses to validate its `opts` argument. Schema mismatch throws `PwgenError(PWGEN.INVALID_OPTIONS)` with the original `ZodError` attached as `cause`, so callers can introspect the failing field path while keeping the typed error code stable for logging.
+
+Strict-mode schemas reject unknown fields rather than silently dropping them — typos like `requrieDigits` (with a transposed `i`) surface immediately instead of being ignored at runtime. Three schemas are exported: `GeneratePasswordOptionsSchema`, `GeneratePassphraseOptionsSchema`, and `EntropyOptionsSchema`.
+
+## Features
+
+- Strict-object schemas reject unknown fields.
+- Positive-integer guards on `length`-shaped fields.
+- Discriminated `wordlist` accepts `"long"`, `"short"`, an inline `string[]`, or any registry name.
+- All three schemas are invoked from at least one production call site (the conformance script verifies this).
+
+## Usage: Basic Example
+
+```ts
+import { GeneratePasswordOptionsSchema } from "@suaveplan/password-generator/schemas";
+
+const result = GeneratePasswordOptionsSchema.safeParse({ length: 16 });
+if (!result.success) throw result.error;
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+ EntropyOptionsSchema,
+ GeneratePassphraseOptionsSchema,
+} from "@suaveplan/password-generator/schemas";
+
+// Pre-validate user-supplied JSON before forwarding to the generator
+function fromJson(raw: unknown) {
+ const parsed = GeneratePassphraseOptionsSchema.parse(raw);
+ return parsed;
+}
+
+// Compose with downstream schemas
+import z from "zod";
+const apiBody = z.object({
+ mode: z.literal("passphrase"),
+ opts: GeneratePassphraseOptionsSchema,
+});
+```
+
+## API Reference
+
+- `GeneratePasswordOptionsSchema` — strict object mirroring `GeneratePasswordOptions`.
+- `GeneratePassphraseOptionsSchema` — strict object mirroring `GeneratePassphraseOptions`. `length` is optional in the schema (the generator applies the default `6`).
+- `EntropyOptionsSchema` — strict object mirroring `EntropyOptions`.
+
+## Implementation Notes
+
+The schemas live in a single feature module to keep the conformance script's `src/schemas/` discovery simple — the script walks that directory and verifies every exported `*Schema` is invoked via `.parse(` or `.safeParse(` somewhere outside the directory. This pattern also matches the layout the `cbor`, `validation`, and `vault` packages already use, so reviewers don't need to context-switch.
+
+Strict-object semantics are non-negotiable for boundary surfaces — Zod's default `passthrough` would let typos silently pass through to the generator and corrupt observability (a `requireDigit` typo with a missing `s` would not enable required-digit quotas but `recordError` would never fire). The trade-off — slightly more verbose error messages when adding new options forces a schema update in the same commit — is the entire point of the gate.