@ai-sdlc/orchestrator 0.5.0 → 0.9.0

package/dist/runtime/attestations.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Cryptographic review attestations (AISDLC-74).
+ *
+ * `/ai-sdlc execute` runs three reviewer subagents (code/test/security) locally
+ * before pushing. CI then re-ran the same reviewers via `Post Review Results` —
+ * burning tokens on duplicate work.
+ *
+ * This module provides the primitives `/ai-sdlc execute` and the
+ * `verify-attestation.yml` workflow share to skip CI review when a valid local
+ * attestation exists. The shape is a DSSE envelope (in-toto / SLSA pattern)
+ * carrying a versioned predicate that commits to the commit SHA, diff hash,
+ * policy hash, and reviewer agent file hashes — so CI can reject envelopes
+ * after force-push, after a policy edit, or after a reviewer agent change.
+ *
+ * ## Threat model (in-scope)
+ *
+ *  - Lazy contributor faking attestation         → signature mismatch
+ *  - Copy-pasted attestation from another PR     → subject digest mismatch
+ *  - Replay after diff changed (force-push)      → diffHash mismatch
+ *  - Attestation issued before a policy edit     → policyHash mismatch
+ *  - Stale reviewer-agent attestation            → agentFileHash mismatch
+ *  - Schema drift / forward-compat smuggling     → schemaVersion enforcement
+ *
+ * Out of scope: compromised dev machine, compromised CI runner, collusion.
+ *
+ * ## Why ed25519 + Node's built-in crypto (no Sigstore)
+ *
+ * The keys are project-controlled, committed in `.ai-sdlc/trusted-reviewers.yaml`,
+ * and small (32-byte). Sigstore would add Fulcio + Rekor + transparency log
+ * infrastructure for no benefit at this scale. ed25519 is what `ssh-keygen
+ * -t ed25519` and `git commit -S` already use; Node's `crypto.sign(null, ...)`
+ * supports it natively.
+ */
+/**
+ * The currently-accepted predicate schema versions. CI rejects any envelope
+ * whose `payload.schemaVersion` is not in this allowlist — this is the
+ * forward-compatibility hatch (we add a new version here when we change the
+ * predicate shape, and CI keeps accepting v1 until we explicitly remove it).
+ *
+ * Exported so the `verify-attestation` workflow can `import`/inline it.
+ */
+export declare const ACCEPTED_SCHEMA_VERSIONS: readonly ["v1"];
+export type SchemaVersion = (typeof ACCEPTED_SCHEMA_VERSIONS)[number];
+/**
+ * The DSSE PAE payload type for our predicate. DSSE spec mandates a payload
+ * type URI — we use a project-controlled vendor URI rather than the
+ * in-toto Statement format (which would force us to shape the predicate
+ * around `_type` + `subject` at the envelope layer instead of the predicate).
+ */
+export declare const DSSE_PAYLOAD_TYPE = "application/vnd.ai-sdlc.attestation+json";
+/** SHA-1 commit digest (40 hex chars) for the subject of an attestation. */
+export interface SubjectDigest {
+    /** sha1 of the git commit being attested (40 hex chars). */
+    sha1: string;
+}
+/** A single reviewer's contribution to the predicate. */
+export interface ReviewerEntry {
+    /** Agent identifier — matches the `name` field of the agent .md file. */
+    agentId: string;
+    /** sha256 of the reviewer agent's `.md` file at the time of review. */
+    agentFileHash: string;
+    /** Harness used for the review (e.g. `codex`, `claude-code`). */
+    harness: string;
+    /** Verdict — true if the reviewer approved, false otherwise. */
+    approved: boolean;
+    /**
+     * Findings counts by severity. We commit to *counts only* (not the full
+     * verdict JSON) to keep attestations small (~1-2KB). The full verdicts
+     * live in the PR body for human review; CI doesn't need them.
+     */
+    findings: {
+        critical: number;
+        major: number;
+        minor: number;
+        suggestion: number;
+    };
+}
+/** The signed payload — what the predicate actually attests. */
+export interface AttestationPredicate {
+    /** Schema version — mandatory, enforced at verify time. */
+    schemaVersion: SchemaVersion;
+    /** The commit being attested. */
+    subject: {
+        digest: SubjectDigest;
+    };
+    /** sha256 of `git diff origin/main...HEAD` at attestation time. */
+    diffHash: string;
+    /** sha256 of `.ai-sdlc/review-policy.md` at attestation time. */
+    policyHash: string;
+    /** Reviewer entries — typically 3 (code/test/security). */
+    reviewers: ReviewerEntry[];
+    /** Plugin version from `ai-sdlc-plugin/plugin.json`. */
+    pluginVersion: string;
+    /** Iteration count — how many dev rounds the work went through. */
+    iterationCount: number;
+    /**
+     * Free-form harness note — empty string when independence was enforced,
+     * `'⚠ INDEPENDENCE NOT ENFORCED (codex unavailable, fell back to ...)'`
+     * when not. Surfaced in PR body so the reviewer-of-the-reviewer sees it.
+     */
+    harnessNote: string;
+    /** ISO 8601 timestamp at signing. */
+    signedAt: string;
+}
+/**
+ * DSSE envelope (https://github.com/secure-systems-lab/dsse).
+ *
+ * `payload` is base64-encoded JSON of the predicate. `signatures[]` lets us
+ * carry multi-sig if we ever need it (today: 1 signer = the dev who ran
+ * `/ai-sdlc execute`).
+ */
+export interface DsseEnvelope {
+    payloadType: typeof DSSE_PAYLOAD_TYPE;
+    /** base64-encoded JSON of the predicate. */
+    payload: string;
+    signatures: DsseSignature[];
+}
+export interface DsseSignature {
+    /**
+     * Identifier of the public key that produced this signature. Used to
+     * look up the trusted-reviewer entry. Free-form — typically `<identity>:
+     * <machine>` (e.g. `dominique@reliablegenius.io:laptop-2025`).
+     */
+    keyid: string;
+    /** base64-encoded raw ed25519 signature (64 bytes → 88 chars b64). */
+    sig: string;
+}
+/** Trusted-reviewers.yaml entry shape. */
+export interface TrustedReviewer {
+    /** Free-form contributor identifier (typically email or GitHub handle). */
+    identity: string;
+    /** Free-form machine label — lets one identity register multiple keys. */
+    machine: string;
+    /** PEM-encoded ed25519 public key. */
+    pubkey: string;
+    /** ISO 8601 date the entry was added. */
+    addedAt: string;
+    /** GitHub handle of the reviewer who approved the entry's PR. */
+    addedBy: string;
+}
+/** Result of verifying an attestation. */
+export type VerifyResult = {
+    valid: true;
+    predicate: AttestationPredicate;
+    trustedReviewer: TrustedReviewer;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Validate a parsed predicate against the v1 schema regex patterns.
+ *
+ * Returns `null` when the predicate is shape-valid; otherwise returns
+ * a static failure reason that does NOT embed any user-controlled
+ * value (just the field path). This is the load-bearing property:
+ * the malicious value never reaches the `reason` string, so it can't
+ * propagate to GITHUB_OUTPUT or commit-status descriptions.
+ */
+export declare function validatePredicateShape(parsed: unknown): string | null;
+/**
+ * The set of reviewer agent IDs the verifier expects to see in every
+ * attestation. Exported so callers (verify-attestation.mjs) can
+ * cross-check that all three reviewers are present + match.
+ *
+ * Frozen to discourage callers from mutating it.
+ */
+export declare const REQUIRED_REVIEWER_AGENT_IDS: readonly string[];
+/** Inputs for building an attestation predicate. */
+export interface BuildPredicateInputs {
+    commitSha: string;
+    diff: string | Buffer;
+    policy: string | Buffer;
+    reviewers: Array<{
+        agentId: string;
+        agentFileContent: string | Buffer;
+        harness: string;
+        approved: boolean;
+        findings: ReviewerEntry['findings'];
+    }>;
+    pluginVersion: string;
+    iterationCount: number;
+    harnessNote: string;
+    /** Override `signedAt` for deterministic tests. */
+    signedAt?: string;
+}
+/**
+ * Compute a sha256 hex digest. Single source of truth for the hashing
+ * algorithm — every predicate field that ends in `Hash` flows through here.
+ */
+export declare function sha256Hex(input: string | Buffer): string;
+/** Compute a sha1 hex digest (used for git commit SHAs in the subject). */
+export declare function sha1Hex(input: string | Buffer): string;
+/**
+ * Build the predicate payload from raw inputs. Pure function — no I/O,
+ * no signing. The caller (`/ai-sdlc execute` Step 10) reads files and git
+ * output, then hands them here.
+ */
+export declare function buildPredicate(inputs: BuildPredicateInputs): AttestationPredicate;
+/**
+ * DSSE Pre-Authentication Encoding. Per the spec
+ * (https://github.com/secure-systems-lab/dsse/blob/master/protocol.md):
+ *
+ *   PAE(type, body) = "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
+ *
+ * Lengths are decimal ASCII byte-counts of the UTF-8 encoding. Signing the
+ * PAE — not the raw payload — is what gives DSSE its domain separation:
+ * a signature over a payload of one `payloadType` cannot be replayed onto
+ * a payload of a different type.
+ */
+export declare function paeEncode(payloadType: string, payload: Buffer): Buffer;
+/** Generate a fresh ed25519 keypair as PEM strings (for `/ai-sdlc init-signing-key`). */
+export declare function generateSigningKeyPair(): {
+    privateKeyPem: string;
+    publicKeyPem: string;
+};
+/** Sign options. `keyid` is required — verifiers use it to look up the pubkey. */
+export interface SignOptions {
+    predicate: AttestationPredicate;
+    privateKeyPem: string;
+    keyid: string;
+}
+/**
+ * Sign a predicate, producing a DSSE envelope.
+ *
+ * Throws if `predicate.schemaVersion` is not in `ACCEPTED_SCHEMA_VERSIONS` —
+ * we don't want to issue an envelope that we'd reject ourselves.
+ */
+export declare function signAttestation(opts: SignOptions): DsseEnvelope;
+/** Verify options. `expected` lets the caller bind verification to a specific PR state. */
+export interface VerifyOptions {
+    envelope: DsseEnvelope;
+    /**
+     * Trusted reviewers from `.ai-sdlc/trusted-reviewers.yaml`. The verifier
+     * tries each pubkey against each signature ("any-of-N") and accepts on
+     * the first match.
+     */
+    trustedReviewers: TrustedReviewer[];
+    /**
+     * What the predicate's `subject.digest.sha1`, `diffHash`, `policyHash`,
+     * and `reviewers[].agentFileHash` MUST equal. Mismatch = invalid.
+     *
+     * `expectedAgentFileHashes` is a map from agentId to its sha256 — we
+     * tolerate the predicate listing fewer or more reviewers than the map,
+     * but every reviewer entry whose agentId IS in the map must hash-match.
+     */
+    expected: {
+        commitSha: string;
+        diffHash: string;
+        policyHash: string;
+        expectedAgentFileHashes: Record<string, string>;
+    };
+    /**
+     * Override the accepted-schema-versions allowlist (for tests). Defaults
+     * to `ACCEPTED_SCHEMA_VERSIONS`.
+     */
+    acceptedSchemaVersions?: readonly string[];
+}
+/**
+ * Verify a DSSE envelope. Returns a discriminated union — `{ valid: true }`
+ * with the parsed predicate + matched trusted reviewer, or `{ valid: false }`
+ * with a single human-readable reason string.
+ *
+ * The reason string is what gets posted to the commit status
+ * (`ai-sdlc/attestation: invalid (<reason>)`), so keep it short and specific.
+ */
+export declare function verifyAttestation(opts: VerifyOptions): VerifyResult;
+/**
+ * Validate the shape of a parsed `.ai-sdlc/trusted-reviewers.yaml` document.
+ * Throws on malformed input with a specific reason. Acceptance criterion #4.
+ *
+ * Accepts the parsed YAML (as `unknown`) and returns the typed array.
+ */
+export declare function validateTrustedReviewers(parsed: unknown): TrustedReviewer[];
+//# sourceMappingURL=attestations.d.ts.map