policy

(no submodules)

Purpose

evaluatePolicy is the composition point that layers every other verification capability into a single decision: given a provenance statement, its optional DSSE envelope, its optional Rekor entry, and a VerificationPolicy, return one VerificationResult with every relevant rule reported. Where verifyProvenance only runs structural rules and doesn't know about signatures or transparency logs, evaluatePolicy ties the full chain of trust together and is what release-gate scripts should call.

Features

Runs the baseline verifyProvenance suite first, then appends:
- DSSE signature verification against policy.trustedPublicKeys.
- Rekor inclusion-proof presence (when policy.requireRekorInclusion).
- Minimum-level assertion against an explicit pipelineLevel.
OTel slsa.policy.violation event emitted on any failure, with violation count and required level attached.
Returns structured VerificationResult — never throws on policy failure.

Usage: Basic Example

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

const result = evaluatePolicy(
  statement,
  envelope,
  rekorEntry,
  {
    trustedBuilders: ["https://gitlab.fq.io/suaveplan/project/-/runners/*"],
    trustedPublicKeys: [releaseKey],
    requireRekorInclusion: true,
    minSlsaLevel: "L2",
  },
  { pipelineLevel: "L3" }
);

Usage: Advanced Example

import {
  createSlsaOtelAdapter,
  evaluatePolicy,
  RekorClient,
} from "@suaveplan/slsa";

const otel = createSlsaOtelAdapter();
const client = new RekorClient({ otel });
const rekorEntry = await client.uploadIntoto(envelope);
const result = evaluatePolicy(statement, envelope, rekorEntry, policy, {
  otel,
  clock: () => Date.now(),
  pipelineLevel: "L2",
});

if (!result.valid) {
  for (const c of result.checks.filter((c) => !c.passed)) {
    log.warn({ rule: c.name, message: c.message }, "policy violation");
  }
  process.exit(1);
}

API Reference

evaluatePolicy(statement, envelope | null, rekorEntry | null, policy, opts?) — returns VerificationResult. opts.pipelineLevel must be supplied when policy.minSlsaLevel is set; otherwise the check fails with a self-describing message.
EvaluatePolicyOptions { otel?, clock?, pipelineLevel? } — all optional.

Implementation Notes

The extra checks are appended, never interleaved, so existing consumers that match on checks[i].name stay stable. checkDsseSignatures builds TrustedEd25519Key records without keyid by default — if keyids are required for scoping, call verifyDsseEnvelope directly and feed the derived checks in. minSlsaLevel uses an ordinal comparison (L0 < L1 < L2 < L3) rather than string equality so "L3" satisfies minSlsaLevel: "L2" without additional policy tweaks.

2.8 KiB Raw Blame History