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