# slsa-error

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Provides the structured error substrate for the `@suaveplan/slsa` package. Every
failure raised by provenance generation, verification, SBOM emission, DSSE
wrapping, Rekor transparency-log operations, and policy evaluation flows
through a `SlsaError` subclass carrying a stable, namespaced error code drawn
from `SLSA_CODES`. This makes it safe to pattern-match on `err.code` in
consumer code and to redact / serialise errors with the rest of the Suaveplan
observability pipeline.

## Features

- Namespaced, frozen registry built via `@suaveplan/error`'s `defineCodes`.
- One domain-specific subclass per code (`InvalidProvenanceError`,
  `VerificationFailedError`, `RekorUploadError`, `RekorInclusionError`,
  `PolicyViolationError`, `AttestationInvalidError`,
  `EnvironmentUnsupportedError`, `InvalidSbomError`).
- `instanceof SlsaError` narrows to the full SLSA code union.
- `cause`, `context`, `traceId` fields inherited from `SuaveplanError`.

## Usage: Basic Example

```ts
import { InvalidProvenanceError } from "@suaveplan/slsa";

throw new InvalidProvenanceError("error.slsa.invalid_provenance", {
  context: { missingField: "builderId" },
});
```

## Usage: Advanced Example

```ts
import { RekorInclusionError, SLSA_CODES, SlsaError } from "@suaveplan/slsa";

try {
  await client.verifyInclusionProof(entry);
} catch (cause) {
  throw new RekorInclusionError("error.slsa.rekor.inclusion_failed", {
    cause: cause as Error,
    context: { uuid: entry.uuid, logIndex: entry.logIndex },
    traceId: currentSpan?.spanContext().traceId,
  });
}

// Downstream handler
if (err instanceof SlsaError && err.code === SLSA_CODES.REKOR_INCLUSION_FAILED) {
  metrics.rekorInclusionFailures.add(1);
}
```

## API Reference

- `SLSA_CODES` — frozen registry of stable error-code strings.
- `SlsaCode` — union type of all SLSA error codes.
- `SlsaError` — base class; extends `SuaveplanError<SlsaCode>`.
- `InvalidProvenanceError(messageKey, options?)` — schema / shape failure.
- `InvalidSbomError(messageKey, options?)` — SBOM schema failure.
- `VerificationFailedError(messageKey, options?)` — provenance verification rejected.
- `PolicyViolationError(messageKey, options?)` — policy evaluator rejection.
- `RekorUploadError(messageKey, options?)` — transparency-log HTTP / protocol failure.
- `RekorInclusionError(messageKey, options?)` — merkle proof failed verification.
- `AttestationInvalidError(messageKey, options?)` — DSSE envelope / signature invalid.
- `EnvironmentUnsupportedError(messageKey, options?)` — runtime lacks capability.

All constructors accept `SuaveplanErrorOptions` (`{ cause?, context?, traceId?, clock? }`).

## Implementation Notes

Subclasses are thin wrappers that bind a specific `SLSA_CODES` value, so
`new InvalidProvenanceError(...)` and `new SlsaError(SLSA_CODES.INVALID_PROVENANCE, ...)`
are behaviourally identical. Message keys are strings — resolution to a human
message happens through `@suaveplan/error`'s i18n resolver so catalogs can be
localised without touching throw sites. The class name is preserved in
`err.name` via the `SuaveplanError` base constructor, which makes stack-trace
capture correct even under V8's `captureStackTrace`.