first commit

docs/security-stack/security/x509/src/schemas/schemas.md

@@ -0,0 +1,56 @@
+# `schemas/schemas` — Zod boundary schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Defines Zod schemas for every public option-bundle and value-object type exposed by `@suaveplan/x509`. The most important boundary is `ValidateChainOptionsSchema`, which `validateChain` uses to refuse malformed caller input — passing `null` for `leaf`, an array of non-certificate values for `intermediates`, or a non-`AbortSignal` for `signal` is rejected before any work happens, with the original Zod issue list preserved as `cause` on the `X509Error(CERTIFICATE_MALFORMED)` it wraps with.
+
+Schemas for the extension result types (`BasicConstraintsSchema`, `KeyUsageSchema`, `ExtendedKeyUsageSchema`, `GeneralNameSchema`, `NameConstraintsSchema`, `AuthorityKeyIdentifierSchema`, `SubjectKeyIdentifierSchema`, `CrlDistributionPointSchema`) pin the structural shape so tests can assert via `safeParse` on synthetic inputs and so callers serialising through JSON can validate before consuming.
+
+## Features
+
+- Strict objects (`.strict()`) on option types so unknown keys are rejected.
+- Pass-through objects on value-object types where the runtime carries extra raw-bytes fields the schema doesn't enumerate.
+- `instanceof Uint8Array` refinements on byte-typed fields.
+- `instanceof AbortSignal` refinement on the optional cancellation signal.
+- Reuse of the same `GeneralNameSchema` across every extension that references one.
+
+## Usage: Basic Example
+
+```ts
+import { ValidateChainOptionsSchema } from "@suaveplan/x509";
+
+const parsed = ValidateChainOptionsSchema.parse({
+    leaf: someCert,
+    intermediates: [],
+    trustAnchors: [root],
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { BasicConstraintsSchema } from "@suaveplan/x509";
+
+const result = BasicConstraintsSchema.safeParse({
+    cA: true,
+    pathLenConstraint: 3,
+});
+if (!result.success) {
+    throw new Error("invariant violated");
+}
+```
+
+## API Reference
+
+- `ValidateChainOptionsSchema` — pins the `validateChain` boundary shape.
+- `X509CertificateLikeSchema` — pass-through certificate shape carrying `tbs`, `signatureAlgorithm`, `signatureValue`, `tbsCertificateBytes`, `raw`.
+- `BasicConstraintsSchema`, `KeyUsageSchema`, `ExtendedKeyUsageSchema`, `GeneralNameSchema`, `NameConstraintsSchema`, `AuthorityKeyIdentifierSchema`, `SubjectKeyIdentifierSchema`, `CrlDistributionPointSchema` — extension value shapes.
+
+## Implementation Notes
+
+- `validateChain` runs the options through Zod first; this is what produces the typed refusal of `{ leaf: null }` documented in the spec. The Zod issue is preserved as `cause` so consumers can inspect it programmatically.
+- `X509CertificateLikeSchema` is intentionally loose — the schema doesn't reproduce the full TBSCertificate Zod hierarchy. The runtime validator inside `validateChain` does the real structural work; the schema is a guard against gross caller bugs.
+- Schemas use `instanceof` refinements (`Uint8Array`, `AbortSignal`) so the runtime check matches the static type. A plain `{ buffer: ArrayBuffer }` would type-check but fail the `instanceof` predicate at runtime — exactly what the boundary is there to catch.