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

schemas/schemas — Zod boundary schemas

(no submodules)

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

import { ValidateChainOptionsSchema } from "@suaveplan/x509";

const parsed = ValidateChainOptionsSchema.parse({
    leaf: someCert,
    intermediates: [],
    trustAnchors: [root],
});

Usage: Advanced Example

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.