@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/_lib/provenance_verify.ts

@@ -1,31 +1,12 @@
 /**
- * Tie a published version's provenance attestation to THIS package's OIDC
- * publish workflow.
+ * Which workflow, in which repository, a legitimate release of this package is
+ * built by — and the check that a SIGNED provenance payload names them.
  *
- * The gate this replaces read `dist.attestations.provenance.predicateType` out
- * of the packument and accepted anything starting with the SLSA provenance
- * URL. That is a presence check wearing a verification's clothes: any workflow
- * in any repository with `id-token: write` produces a document that passes it,
- * so an attacker who can publish from their own CI already satisfies it. The
- * step that opened this file (`road-to-an-update-that-installs-itself-only-when-it-is-safe`
- * 2.1) named exactly that gap — *"does not verify the attestation's signature
- * or tie it to `publish-npm.yml`"* — and this module closes the second half.
- *
- * **The first half is only partly closed here, and the distinction is
- * load-bearing.** `provenance_matches_publish` parses an UNSIGNED reading of
- * the DSSE payload. `verify_attestation_signature` below checks the envelope's
- * signature against the certificate the bundle carries, and requires the
- * payload it verified to name the same workflow — but checks no trust root
- * (see its own note). The registry-key half is `npm audit signatures`, which
- * verifies against npm's own trusted keys and is run by the caller as a
- * separate step; these functions are only meaningful WITH it, and the caller
- * says so where it composes them.
- *
- * Why not verify the signature in-process: it needs a sigstore/cosign
- * verification path, which is a dependency this package does not carry and
- * which the hook and pack byte budgets would both have to absorb. Shelling out
- * to the npm client — already a hard dependency of an upgrade — buys the same
- * property for nothing.
+ * Signatures, trust roots and the tie to the tarball are verified in
+ * `sigstore_provenance.ts`; this module only reads a payload that has already
+ * been verified there. It used to carry a certificate-bound signature check of
+ * its own, which checked no issuer and so passed a self-signed certificate
+ * carrying the expected SAN; that check is gone rather than kept as a fallback.
  */
 
 /**
@@ -44,65 +25,16 @@ function asRecord(v: unknown): Record<string, unknown> | null {
     return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
 }
 
-/** Decode the DSSE payload of the first attestation; `null` when unreadable. */
-function decode_payload(doc: unknown): Record<string, unknown> | null {
-    const list = asRecord(doc)?.['attestations'];
-    if (!Array.isArray(list) || list.length === 0) return null;
-    for (const entry of list) {
-        const payload = asRecord(asRecord(asRecord(entry)?.['bundle'])?.['dsseEnvelope'])?.['payload'];
-        if (typeof payload !== 'string' || payload === '') continue;
-        try {
-            const parsed: unknown = JSON.parse(Buffer.from(payload, 'base64').toString('utf8'));
-            const rec = asRecord(parsed);
-            if (rec !== null) return rec;
-        } catch {
-            // A payload that is not base64 JSON is not evidence of anything.
-            // Keep looking: npm may serve several attestations and only one of
-            // them has to be the provenance statement.
-        }
-    }
-    return null;
-}
-
-function external_workflow(doc: unknown): Record<string, unknown> | null {
-    const payload = decode_payload(doc);
-    if (payload === null) return null;
-    const predicate = asRecord(payload['predicate']);
-    const external = asRecord(asRecord(predicate?.['buildDefinition'])?.['externalParameters']);
-    return asRecord(external?.['workflow']);
-}
-
-/**
- * The workflow path named by the attestation, or `null` when the document
- * carries none that can be read.
- */
-export function attestation_workflow_ref(doc: unknown): string | null {
-    const path_value = external_workflow(doc)?.['path'];
-    return typeof path_value === 'string' && path_value !== '' ? path_value : null;
-}
-
-/** The repository named by the attestation, or `null`. */
-export function attestation_repository(doc: unknown): string | null {
-    const repo = external_workflow(doc)?.['repository'];
-    return typeof repo === 'string' && repo !== '' ? repo : null;
-}
-
 /**
- * Does this attestation say the tarball was built by this package's publish
- * workflow, in this package's repository?
+ * Does this provenance payload say the tarball was built by this package's
+ * publish workflow, in this package's repository?
  *
- * Both halves are required and both reject on absence: a document that names
- * no workflow is not a document that names the right one. Repository is
- * compared with the trailing `.git` and any trailing slash removed, because
- * the same remote is written both ways and neither spelling is an attacker
- * signal.
+ * Both halves are required and both reject on absence: a payload that names no
+ * workflow is not one that names the right one. Repository is compared with
+ * the trailing `.git` and any trailing slash removed, because the same remote
+ * is written both ways and neither spelling is an attacker signal.
  */
-export function provenance_matches_publish(doc: unknown): boolean {
-    return payload_names_publish(decode_payload(doc));
-}
-
-/** The workflow and repository check, over one already-decoded payload. */
-function payload_names_publish(payload: Record<string, unknown> | null): boolean {
+export function payload_names_publish(payload: Record<string, unknown> | null): boolean {
     const predicate = asRecord(payload?.['predicate']);
     const workflow = asRecord(asRecord(asRecord(predicate?.['buildDefinition'])?.['externalParameters'])?.['workflow']);
     if (workflow?.['path'] !== EXPECTED_WORKFLOW_REF) return false;
@@ -110,163 +42,3 @@ function payload_names_publish(payload: Record<string, unknown> | null): boolean
     if (typeof repo !== 'string' || repo === '') return false;
     return repo.replace(/\.git$/, '').replace(/\/$/, '') === EXPECTED_REPOSITORY;
 }
-
-/**
- * Does the certificate's SAN carry the workflow identity as a whole URI entry?
- * Anchored: the entry is the expected workflow followed by `@<ref>`, never a
- * SAN that merely contains the string.
- */
-function san_names_workflow(san: string): boolean {
-    return san.split(/,\s*/).some((e) => e.startsWith(`URI:${SAN_WORKFLOW_MARKER}@`));
-}
-
-// --- the signature half -------------------------------------------------------
-
-/**
- * What the clauses below do and do not establish.
- *
- * The header above says the signature half is not closed here. It is now
- * HALF-closed, and the half that is missing is stated first so nothing below
- * reads as more than it is.
- *
- * **Closed:** the DSSE envelope's signature is verified against the public key
- * of the certificate the bundle itself carries, over the DSSE
- * pre-authentication encoding — so a payload edited after signing is caught,
- * and a bundle whose signature does not belong to its own certificate is
- * caught. And the certificate's own SAN is required to name the expected
- * workflow, so a bundle whose PAYLOAD claims `publish-npm.yml` while its
- * certificate was issued to some other identity is caught. Before this, both
- * were a base64 decode and a string compare.
- *
- * **Not closed, and this is the residue:** there is no trust root. Nothing
- * here checks that the certificate was issued by Fulcio, and nothing checks a
- * Rekor inclusion proof. An attacker who can serve a registry response can mint
- * a self-signed certificate carrying the expected SAN, sign their own payload
- * with it, and pass every check in this file. Closing that needs a sigstore
- * verification path with pinned roots — a dependency decision, not a line in
- * this function, and it is registered as the `dsse-trust-root` blocker on
- * `road-to-an-update-that-installs-itself-only-when-it-is-safe`.
- *
- * So the honest statement of what the provenance gate is worth today: it
- * defeats a partial compromise — a mis-scoped workflow, an edited payload, a
- * bundle reused from another build — and it does not defeat a forged bundle
- * from someone who already controls what the install reads.
- */
-
-/** Why the signature does not verify, or `null` when it does. */
-export type SignatureVerdict = string | null;
-
-/** The SAN extension OID the Fulcio leaf carries the workflow identity in. */
-const SAN_WORKFLOW_MARKER = `${EXPECTED_REPOSITORY}/${EXPECTED_WORKFLOW_REF}`;
-
-/**
- * The DSSE pre-authentication encoding — the exact bytes a DSSE signature is
- * taken over.
- *
- * `DSSEv1 SP len(payloadType) SP payloadType SP len(payload) SP payload`, with
- * both lengths in BYTES rather than characters. Built as a Buffer throughout
- * because the payload is arbitrary bytes and a string round-trip would mangle
- * any that are not valid UTF-8.
- */
-export function dssePae(payloadType: string, payload: Buffer): Buffer {
-    const type = Buffer.from(payloadType, 'utf8');
-    return Buffer.concat([
-        Buffer.from(`DSSEv1 ${String(type.length)} `, 'utf8'),
-        type,
-        Buffer.from(` ${String(payload.length)} `, 'utf8'),
-        payload,
-    ]);
-}
-
-interface Envelope {
-    readonly payloadType: string;
-    readonly payload: Buffer;
-    readonly sig: Buffer;
-    readonly certDer: Buffer;
-}
-
-function readEnvelope(entry: unknown): Envelope | null {
-    const bundle = asRecord(asRecord(entry)?.['bundle']);
-    const dsse = asRecord(bundle?.['dsseEnvelope']);
-    if (dsse === null) return null;
-    const payloadB64 = dsse['payload'];
-    const payloadType = dsse['payloadType'];
-    const sigs = dsse['signatures'];
-    if (typeof payloadB64 !== 'string' || typeof payloadType !== 'string' || !Array.isArray(sigs) || sigs.length === 0) return null;
-    const sigB64 = asRecord(sigs[0])?.['sig'];
-    if (typeof sigB64 !== 'string' || sigB64 === '') return null;
-
-    const material = asRecord(bundle?.['verificationMaterial']);
-    // Both shapes sigstore has used: a single certificate, and a chain.
-    const single = asRecord(material?.['certificate'])?.['rawBytes'];
-    const chain = asRecord(material?.['x509CertificateChain'])?.['certificates'];
-    const first = Array.isArray(chain) ? asRecord(chain[0])?.['rawBytes'] : undefined;
-    const certB64 = typeof single === 'string' ? single : typeof first === 'string' ? first : null;
-    if (certB64 === null || certB64 === '') return null;
-
-    return {
-        payloadType,
-        payload: Buffer.from(payloadB64, 'base64'),
-        sig: Buffer.from(sigB64, 'base64'),
-        certDer: Buffer.from(certB64, 'base64'),
-    };
-}
-
-/**
- * Verify the first readable attestation's DSSE signature against its own
- * certificate, and require that certificate to name this package's workflow.
- *
- * Returns a reason on every failure rather than a boolean, because the caller
- * prints it: a refusal a user cannot act on is a refusal they route around.
- * `crypto` is imported lazily so a caller that never verifies a signature does
- * not pay for the module — this runs on an install path, never in a hook.
- */
-export async function verify_attestation_signature(doc: unknown): Promise<SignatureVerdict> {
-    const list = asRecord(doc)?.['attestations'];
-    if (!Array.isArray(list) || list.length === 0) return 'the attestation bundle carries no attestations';
-    const crypto = await import('node:crypto');
-
-    let lastReason = 'no attestation carried a readable DSSE envelope';
-    for (const entry of list) {
-        const env = readEnvelope(entry);
-        if (env === null) continue;
-        let cert: InstanceType<typeof crypto.X509Certificate>;
-        try {
-            cert = new crypto.X509Certificate(env.certDer);
-        } catch {
-            lastReason = 'the signing certificate could not be parsed';
-            continue;
-        }
-        // The certificate's own identity, not the payload's claim about it.
-        const san = cert.subjectAltName ?? '';
-        if (!san_names_workflow(san)) {
-            lastReason = `the signing certificate names ${san === '' ? 'no identity' : san}, not ${SAN_WORKFLOW_MARKER}`;
-            continue;
-        }
-        let ok = false;
-        try {
-            ok = crypto.verify(null, dssePae(env.payloadType, env.payload), cert.publicKey, env.sig);
-        } catch {
-            ok = false;
-        }
-        if (!ok) {
-            lastReason = 'the DSSE signature does not verify against the certificate in the bundle';
-            continue;
-        }
-        // The payload this signature covers must itself name the workflow:
-        // otherwise a valid signature on one entry vouches for a claim made in
-        // another, which is all the unsigned check reads.
-        let verified: Record<string, unknown> | null = null;
-        try {
-            verified = asRecord(JSON.parse(env.payload.toString('utf8')));
-        } catch {
-            verified = null;
-        }
-        if (!payload_names_publish(verified)) {
-            lastReason = 'the signed payload does not name this package\'s publish workflow';
-            continue;
-        }
-        return null;
-    }
-    return lastReason;
-}

package/src/scripts/_lib/sigstore_provenance.ts

@@ -0,0 +1,177 @@
+/**
+ * Verify a release's two attestations against pinned sigstore trust material,
+ * and bind both to the exact tarball bytes that will be installed.
+ *
+ * WHY THIS REPLACES THE CERTIFICATE-BOUND CHECK. `provenance_verify.ts` checked
+ * the DSSE signature against the certificate a bundle carries and that
+ * certificate's SAN — and nothing about who issued it, so anyone who could
+ * serve the registry answer could mint a self-signed certificate with the
+ * expected SAN and pass. Pinned roots close that; a root fetched at run time
+ * would let the same attacker choose what the bundle is checked against.
+ *
+ * WHAT IS VERIFIED, both attestations required:
+ * - the SLSA provenance bundle: Fulcio chain to the pinned root, the signing
+ *   certificate's validity at the time the transparency log recorded it, a
+ *   Rekor entry and an SCT checked against the pinned logs, the DSSE signature,
+ *   and an identity policy — issuer `token.actions.githubusercontent.com` and a
+ *   SAN that is exactly this repository's `publish-npm.yml` at the tag of the
+ *   version being installed;
+ * - the npm publish attestation: its signature against npm's pinned
+ *   `npm:attestations` keys, and its Rekor entry — a second trust domain,
+ *   verified separately;
+ * - in both payloads, exactly one subject naming this package at this version,
+ *   whose sha512 equals the sha512 of the bytes about to be installed.
+ *
+ * WHAT IT NEVER DOES: fetch trust material (the files are read from the
+ * installed package and their digests checked against the recorded ones), fall
+ * back to the old check or to `npm audit signatures`, or pass anything it could
+ * not verify. Every failure is a reason string, because the caller prints it.
+ *
+ * The sigstore modules are imported lazily: this runs on the unattended upgrade
+ * path only, and nothing else should pay for loading them.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { resolvePackageRoot } from './package_root.js';
+import { EXPECTED_REPOSITORY, EXPECTED_WORKFLOW_REF, payload_names_publish } from './provenance_verify.js';
+
+export const SLSA_PROVENANCE_V1 = 'https://slsa.dev/provenance/v1';
+export const NPM_PUBLISH_V01 = 'https://github.com/npm/attestation/tree/main/specs/publish/v0.1';
+export const GITHUB_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
+export const PACKAGE_PURL_BASE = 'pkg:npm/%40event4u/agent-config';
+
+/** Why verification refused, or `null` when everything held. */
+export type ProvenanceVerdict = string | null;
+
+function asRecord(v: unknown): Record<string, unknown> | null {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+function escapeRegExp(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+}
+
+/**
+ * The only SAN accepted: this repository's publish workflow at the release tag
+ * of exactly the version being installed. Anchored at both ends — the library
+ * treats the policy as a pattern, and an unanchored one would accept any SAN
+ * that merely contains it.
+ */
+export function expectedSan(version: string): RegExp {
+    return new RegExp(`^${escapeRegExp(`${EXPECTED_REPOSITORY}/${EXPECTED_WORKFLOW_REF}@refs/tags/${version}`)}$`);
+}
+
+export interface TrustFiles {
+    readonly trustedRoot: unknown;
+    readonly npmKeys: unknown;
+}
+
+/**
+ * Read the pinned trust material and refuse when a file's digest differs from
+ * the recorded one — a release can only be checked against the material it
+ * shipped with, as it shipped.
+ */
+export function readTrustFiles(packageRoot: string = resolvePackageRoot(import.meta.url)): TrustFiles | string {
+    const dir = path.join(packageRoot, 'src', 'config', 'sigstore');
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'trust-material.json'), 'utf-8')) as {
+            files?: Record<string, string>;
+        };
+        const read = (name: string): unknown => {
+            const bytes = fs.readFileSync(path.join(dir, name));
+            const want = manifest.files?.[name];
+            const got = createHash('sha256').update(bytes).digest('hex');
+            if (want !== got) throw new Error(`${name} has sha256 ${got}, the recorded one is ${String(want)}`);
+            return JSON.parse(bytes.toString('utf-8')) as unknown;
+        };
+        return { trustedRoot: read('trusted_root.json'), npmKeys: read('npm_keys.json') };
+    } catch (err) {
+        return `the pinned sigstore trust material is unusable: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+
+/** Exactly one subject, naming this package at this version, with this sha512. */
+function subjectMatches(payload: Record<string, unknown> | null, version: string, sha512Hex: string): string | null {
+    const subjects = payload?.['subject'];
+    if (!Array.isArray(subjects) || subjects.length !== 1) return 'it does not name exactly one subject';
+    const subject = asRecord(subjects[0]);
+    if (subject?.['name'] !== `${PACKAGE_PURL_BASE}@${version}`) return `its subject is ${String(subject?.['name'])}, not ${version}`;
+    const digest = asRecord(subject['digest'])?.['sha512'];
+    if (typeof digest !== 'string' || digest.toLowerCase() !== sha512Hex.toLowerCase()) {
+        return 'its subject digest does not match the tarball about to be installed';
+    }
+    return null;
+}
+
+export interface ReleaseToVerify {
+    readonly version: string;
+    /** sha512 of the exact tarball bytes that will be installed, lower-case hex. */
+    readonly tarballSha512Hex: string;
+    /** The registry's attestation document for this version. */
+    readonly attestations: unknown;
+}
+
+export async function verify_release_provenance(
+    release: ReleaseToVerify,
+    trust: TrustFiles | string = readTrustFiles(),
+): Promise<ProvenanceVerdict> {
+    if (typeof trust === 'string') return trust;
+    const list = asRecord(release.attestations)?.['attestations'];
+    if (!Array.isArray(list)) return 'the attestation document carries no attestations';
+    const byType = new Map<string, unknown>();
+    for (const entry of list) {
+        const type = asRecord(entry)?.['predicateType'];
+        if (typeof type === 'string' && !byType.has(type)) byType.set(type, asRecord(entry)?.['bundle']);
+    }
+    for (const type of [SLSA_PROVENANCE_V1, NPM_PUBLISH_V01]) {
+        if (!byType.has(type)) return `the release carries no ${type} attestation`;
+    }
+
+    const { Verifier, toSignedEntity, toTrustMaterial } = await import('@sigstore/verify');
+    const { bundleFromJSON } = await import('@sigstore/bundle');
+    const { PublicKey, TrustedRoot } = await import('@sigstore/protobuf-specs');
+
+    let material: ReturnType<typeof toTrustMaterial>;
+    try {
+        const keys: Record<string, ReturnType<typeof PublicKey.fromJSON>> = {};
+        const listed = asRecord(trust.npmKeys)?.['keys'];
+        for (const k of Array.isArray(listed) ? listed : []) {
+            const key = asRecord(k);
+            if (key?.['keyUsage'] === 'npm:attestations' && typeof key['keyId'] === 'string') {
+                keys[key['keyId']] = PublicKey.fromJSON(key['publicKey']);
+            }
+        }
+        material = toTrustMaterial(TrustedRoot.fromJSON(trust.trustedRoot), keys);
+    } catch (err) {
+        return `the pinned sigstore trust material could not be loaded: ${err instanceof Error ? err.message : String(err)}`;
+    }
+
+    for (const type of [SLSA_PROVENANCE_V1, NPM_PUBLISH_V01]) {
+        let payload: Record<string, unknown> | null;
+        try {
+            const bundle = bundleFromJSON(byType.get(type));
+            const verifier = new Verifier(material, { tlogThreshold: 1, ctlogThreshold: 1, timestampThreshold: 1 });
+            const policy =
+                type === SLSA_PROVENANCE_V1
+                    ? { subjectAlternativeName: expectedSan(release.version), extensions: { issuer: GITHUB_OIDC_ISSUER } }
+                    : undefined;
+            verifier.verify(toSignedEntity(bundle), policy);
+            if (bundle.content.$case !== 'dsseEnvelope') return `the ${type} attestation is not a DSSE envelope`;
+            payload = asRecord(JSON.parse(bundle.content.dsseEnvelope.payload.toString('utf-8')));
+        } catch (err) {
+            const code = asRecord(err)?.['code'];
+            return `the ${type} attestation does not verify${typeof code === 'string' ? ` (${code})` : ''}: ${
+                err instanceof Error ? err.message : String(err)
+            }`;
+        }
+        if (payload?.['predicateType'] !== type) return `the ${type} attestation's statement names another predicate type`;
+        const subject = subjectMatches(payload, release.version, release.tarballSha512Hex);
+        if (subject !== null) return `the ${type} attestation is not for this tarball: ${subject}`;
+        if (type === SLSA_PROVENANCE_V1 && !payload_names_publish(payload)) {
+            return `the signed provenance does not name ${EXPECTED_WORKFLOW_REF} in ${EXPECTED_REPOSITORY}`;
+        }
+    }
+    return null;
+}

package/src/scripts/_lib/source_id.ts

@@ -0,0 +1,48 @@
+/**
+ * Stable, keyed source ids — `src_` plus 10 hex of an HMAC over the canonical identity.
+ *
+ * `ENC1` tokens are salted per call, so two tokens for one source never compare
+ * equal; a round-scoped `S1…` code is renumbered every round. Neither can key a
+ * ledger. This id can: it is stable across rounds and URL spellings, and keyed
+ * with `secrets.link_encryption_key`, so nobody without the key can confirm a
+ * guessed source by hashing its URL. Without a key there is no id — callers
+ * refuse rather than mint an unkeyed one.
+ */
+
+import * as crypto from 'node:crypto';
+
+import { canonicalize } from '../harvest_reference_tokens.js';
+
+export const SOURCE_ID_PREFIX = 'src_';
+export const SOURCE_ID_RE = /^src_[0-9a-f]{10}$/;
+// Domain-separates this HMAC from any other use of the same key.
+const ID_CONTEXT = 'agent-config/source-id/v1\0';
+
+/**
+ * Repository URLs collapse through `canonicalize`; anything else (an article,
+ * a video, a paper) keeps host, path and query with scheme, credentials,
+ * fragment and a trailing slash dropped. A string that is not a URL is used
+ * trimmed, as written — an opaque reference names itself.
+ */
+export function canonicalSourceIdentity(raw: string): string {
+    const repo = canonicalize(raw);
+    if (repo !== null) return repo;
+    const s = raw.trim();
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(s)) return s;
+    let u: URL;
+    try {
+        u = new URL(s);
+    } catch {
+        return s;
+    }
+    const host = u.hostname.toLowerCase().replace(/^www\./, '');
+    const port = u.port === '' ? '' : `:${u.port}`;
+    const pathname = u.pathname.replace(/\/+$/, '');
+    return `${host}${port}${pathname}${u.search}`;
+}
+
+export function sourceId(identity: string, key: string): string {
+    if (!key) throw new Error('no link_encryption_key — a source id is never minted without the key');
+    const mac = crypto.createHmac('sha256', key).update(ID_CONTEXT + canonicalSourceIdentity(identity)).digest('hex');
+    return SOURCE_ID_PREFIX + mac.slice(0, 10);
+}

package/src/scripts/_lib/source_shape.ts

@@ -155,6 +155,10 @@ const ALLOWED_OWNERS: readonly string[] = [
     // looked; this is the answer. Fixing them here rather than by widening the
     // dedup rule is what keeps that rule strict.
     'someone', 'o',
+    // `someone-else/<repo>` is the wrong-repository fixture of the provenance
+    // tests; a committed council prompt quoting those tests verbatim was the
+    // measured false positive (2026-10-24). Same shape as the two above.
+    'someone-else',
     // Vendors whose tools this suite integrates or recommends (rule carve-out).
     'anthropics', 'anthropic', 'microsoft', 'github', 'modelcontextprotocol',
     'cloudflare', 'openai', 'nodejs', 'vitest-dev', 'vercel', 'tailwindlabs',

package/src/scripts/_lib/unattended_gates.ts

@@ -30,9 +30,12 @@ export interface RegistryCandidate {
      * workflow produced the document. Tying it to this package's publish
      * workflow needs the bundle itself, which the packument only points at —
      * so the pointer travels with the candidate and the caller fetches it
-     * (`provenance_verify.provenance_matches_publish`).
+     * (`sigstore_provenance.verify_release_provenance`).
      */
     readonly attestationsUrl: string | null;
+    /** Where npm serves this version's tarball, and the integrity it records for it. */
+    readonly tarballUrl: string | null;
+    readonly integrity: string | null;
 }
 
 function asRecord(v: unknown): Record<string, unknown> | null {
@@ -58,6 +61,8 @@ export function read_candidate(packument: unknown): RegistryCandidate | null {
         provenance: typeof predicate === 'string' && predicate.startsWith('https://slsa.dev/provenance/'),
         impactMap: asRecord(manifest['agentConfig'])?.['impact'] ?? null,
         attestationsUrl: typeof attestations?.['url'] === 'string' ? (attestations['url'] as string) : null,
+        tarballUrl: typeof asRecord(manifest['dist'])?.['tarball'] === 'string' ? (asRecord(manifest['dist'])?.['tarball'] as string) : null,
+        integrity: typeof asRecord(manifest['dist'])?.['integrity'] === 'string' ? (asRecord(manifest['dist'])?.['integrity'] as string) : null,
     };
 }
 

package/src/scripts/advisories.ts

@@ -63,6 +63,7 @@ import {
     emptyLedger,
     validateAcceptance,
 } from './_lib/advisory_verdicts.js';
+import { readRegistry, recordProject } from './_lib/project_registry.js';
 import { event4u_root } from './_lib/user_global_paths.js';
 import {
     advance,
@@ -363,25 +364,40 @@ export function markOwnActionsPrivate<T extends { entries: Array<{ ecosystem: st
     return inv;
 }
 
-/** The user-global index of project roots — roots and fingerprints only (5.4). */
+/**
+ * The project list is the shared user-global registry (`_lib/project_registry`,
+ * ADR-299): a sibling of the advisories machine dir, so an injected dir keeps
+ * its registry beside it. Roots and fingerprints only (5.4).
+ */
+function registryDirFor(mdir: string): string {
+    return path.join(path.dirname(mdir), 'projects');
+}
+
 function recordProjects(mdir: string, rows: Array<{ root: string; fingerprint: string }>, now: Date): void {
+    for (const r of rows) recordProject(r.root, { fingerprint: r.fingerprint }, { dir: registryDirFor(mdir), now });
+}
+
+/** The pre-registry `projects.json`, imported once and then moved aside. */
+function migrateLegacyProjects(mdir: string): void {
     const file = path.join(mdir, 'projects.json');
-    let doc: Record<string, { fingerprint: string; at: string }> = {};
+    let doc: Record<string, { fingerprint?: string; at?: string }>;
     try {
         doc = JSON.parse(fs.readFileSync(file, 'utf-8'));
     } catch {
-        doc = {};
+        return;
+    }
+    for (const [root, e] of Object.entries(doc ?? {})) {
+        const at = typeof e?.at === 'string' && !Number.isNaN(Date.parse(e.at)) ? new Date(e.at) : new Date();
+        recordProject(root, { fingerprint: typeof e?.fingerprint === 'string' ? e.fingerprint : null }, { dir: registryDirFor(mdir), now: at });
     }
-    for (const r of rows) doc[r.root] = { fingerprint: r.fingerprint, at: now.toISOString() };
-    writeJson(file, doc);
+    fs.renameSync(file, `${file}.migrated`);
 }
 
 export function knownProjects(mdir: string = machineDir()): string[] {
-    try {
-        return Object.keys(JSON.parse(fs.readFileSync(path.join(mdir, 'projects.json'), 'utf-8'))).filter((r) => fs.existsSync(r));
-    } catch {
-        return [];
-    }
+    migrateLegacyProjects(mdir);
+    return Object.values(readRegistry({ dir: registryDirFor(mdir) }).projects)
+        .map((e) => e.root)
+        .filter((r) => fs.existsSync(r));
 }
 
 // ---------------------------------------------------------------------------

package/src/scripts/ai_council/council_egress.ts

@@ -17,8 +17,8 @@
  * decision D8, which this module does not take.
  */
 
+import { detectNormalized, detectWithExtent } from '../_lib/egress_normalize.js';
 import {
-    detect,
     EGRESS_RULES,
     type EgressRule,
     type EgressSpan,
@@ -26,8 +26,6 @@ import {
     prefixesOf,
     rawKeyPrefixPattern,
     replaceSpans,
-    resolveOverlaps,
-    findSpans,
     REVIEW_CREDENTIAL_ROWS,
 } from '../_lib/egress_rules.js';
 import { parseTokens, TokenScope } from '../_lib/egress_token.js';
@@ -88,9 +86,10 @@ export class CouncilEgress {
      * proven is replaced through the nearest END marker, as the line masks did.
      */
     replace(text: string): string {
-        const spans = resolveOverlaps(findSpans(text, BUNDLE_RULES))
+        const at = detectWithExtent(text, BUNDLE_RULES);
+        const spans = at.spans
             .filter((s) => s.class === 'credential' || this.opts.identifiers)
-            .map((s) => ({ ...s, end: maskingEnd(text, s) }));
+            .map((s) => ({ ...s, end: at.end(s, maskingEnd) ?? s.end }));
         spans.sort((a, b) => a.start - b.start);
         const merged: EgressSpan[] = [];
         for (const s of spans) {
@@ -124,7 +123,7 @@ export class CouncilEgress {
         for (const value of this.replaced) {
             if (body.includes(value)) return { reason: 'replaced-value-present', what: 'value replaced in this run' };
         }
-        for (const s of detect(body)) {
+        for (const s of detectNormalized(body)) {
             const high = s.class === 'credential' ? s.rule !== 'generic-assignment' : s.validated && this.opts.identifiers;
             if (high) return { reason: 'high-confidence-finding', what: s.rule };
         }