# `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.