Initial Commit

packages/security-stack/security/slsa/src/schemas/parse.md

@@ -0,0 +1,67 @@
+# parse
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Runtime-safe entry points that turn untrusted JSON or objects into strongly
+typed, schema-validated SLSA artifacts. Every other module in the package
+treats its inputs as already valid — these two helpers (`parseProvenance`,
+`parseSbom`) are the boundary between "unvalidated wire input" and the rest of
+the codebase. Both throw structured `SlsaError` subclasses with a
+`context.issues` array of path-formatted Zod messages so callers can surface
+precise validation feedback without parsing Zod internals.
+
+## Features
+
+- Accepts either a JSON string or a pre-parsed object.
+- Validates against the canonical Zod schemas for in-toto/SLSA provenance and
+  CycloneDX 1.5 SBOMs.
+- Structured error output: `err.code === "SLSA.INVALID_PROVENANCE"` /
+  `"SLSA.INVALID_SBOM"`.
+- Captures the JSON parse error as `err.cause` when input is a malformed
+  string.
+
+## Usage: Basic Example
+
+```ts
+import { parseProvenance } from "@suaveplan/slsa";
+
+const statement = parseProvenance(wireJson);
+console.log(statement.predicate.runDetails.builder.id);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { parseSbom, SlsaError, SLSA_CODES } from "@suaveplan/slsa";
+
+try {
+  const sbom = parseSbom(await fs.readFile("sbom.json", "utf8"));
+  audit.record({ serial: sbom.serialNumber, components: sbom.components.length });
+} catch (err) {
+  if (err instanceof SlsaError && err.code === SLSA_CODES.INVALID_SBOM) {
+    log.warn({ issues: err.context?.issues }, "SBOM rejected");
+    return Response.json({ error: "invalid sbom" }, { status: 400 });
+  }
+  throw err;
+}
+```
+
+## API Reference
+
+- `parseProvenance(input: string | unknown): ProvenanceStatement` — validates
+  against `ProvenanceStatementSchema`. Throws `InvalidProvenanceError` on any
+  failure (malformed JSON, wrong `_type`, missing digests, etc.).
+- `parseSbom(input: string | unknown): Sbom` — validates against `SbomSchema`.
+  Throws `InvalidSbomError`.
+
+## Implementation Notes
+
+JSON parsing and schema validation are kept distinct so that a malformed JSON
+string surfaces a separate error (with the `SyntaxError` attached as `cause`)
+from a structurally valid but schema-invalid document. Zod's `safeParse` is
+used — we never throw a `ZodError` out of the public API. Issues are flattened
+to `path: message` strings because consumers often log `context.issues`
+directly and a JSON-stringified Zod issue tree is unfriendly in log pipelines.