first commit

docs/security-stack/security/slsa/src/errors/slsa-error.md

@@ -0,0 +1,81 @@
+# 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`.