slsa-error

(no submodules)

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

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

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

Usage: Advanced Example

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.

3.2 KiB Raw Blame History