@de-otio/repo-aegis-core 0.2.0

package/dist/schemas.js

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+// Single source of truth for on-disk schema definitions.
+//
+// All YAML configuration files repo-aegis reads at runtime — the
+// engagement registry, the per-repo `.repo-aegis.yml` override, the
+// classify rules file, the scanner queries file — flow through one of
+// the schemas below. The `parse-and-narrow` helpers wrap zod's parse
+// with the canonical CLI error type (RegistryParseError /
+// RepoOverrideError / ad-hoc) so callers don't have to translate
+// ZodError shape themselves.
+//
+// Why centralise here: previously each callsite hand-rolled a series of
+// `typeof obj.foo !== "string"` checks. Adding a field meant editing
+// the parser, the type, and the validator separately and hoping they
+// stayed in sync. With zod, the schema *is* the type *is* the
+// validator.
+import { z } from "zod";
+/**
+ * Format a ZodError into the multi-line "human-readable" string we used
+ * to build by hand in the per-callsite validators. The output preserves
+ * the substrings that existing tests pin on (e.g. "must be", "missing",
+ * "reserved").
+ *
+ * For deeply nested issues we render `engagements[3].markers: ...`
+ * style paths — matches what the previous bespoke loops emitted.
+ */
+export function formatZodError(err, kind) {
+    const lines = [];
+    for (const issue of err.issues) {
+        const path = issue.path
+            .map((seg, i) => {
+            if (typeof seg === "number")
+                return `[${seg}]`;
+            return i === 0 ? String(seg) : `.${String(seg)}`;
+        })
+            .join("");
+        const where = path === "" ? kind : path;
+        lines.push(`${where}: ${issue.message}`);
+    }
+    return lines.length === 1 ? lines[0] : lines.join("; ");
+}
+// ---------------------------------------------------------------------------
+// Engagement registry (~/.config/repo-aegis/engagements.yaml)
+// ---------------------------------------------------------------------------
+const ALWAYS_BLOCK_RESERVED_ID_LITERAL = "_always";
+/**
+ * Allowed shape for a GitHub org name, used in `personalOrgs` and
+ * `engagements[*].githubOrgs`. Mirrors GitHub's own org-name constraint:
+ * lowercase alphanumerics and hyphens, starting with an alphanumeric.
+ *
+ * Schema rejects uppercase. Callers writing into the registry (e.g.
+ * `engagements add --github-org`) must lowercase input before persisting;
+ * the gate-time read path trusts the schema (no runtime case-folding).
+ */
+export const ORG_NAME_REGEX = /^[a-z0-9][a-z0-9-]*$/;
+const orgNameSchema = z
+    .string()
+    .min(1, "org name must be non-empty")
+    .regex(ORG_NAME_REGEX, {
+    message: "org name must be lowercase, start with [a-z0-9], and contain only [a-z0-9-]",
+});
+const engagementSchema = z
+    .object({
+    id: z
+        .string()
+        .min(1, "missing or empty 'id'")
+        .refine(v => v !== ALWAYS_BLOCK_RESERVED_ID_LITERAL, {
+        message: `engagement id "${ALWAYS_BLOCK_RESERVED_ID_LITERAL}" is reserved; ` +
+            `use the top-level 'always_block:' field for org-wide markers`,
+    }),
+    name: z.string({ message: "missing string 'name'" }),
+    started: z.string().nullable().optional(),
+    ended: z.string().nullable().optional(),
+    reposActive: z.array(z.string()).optional(),
+    markers: z.array(z.string(), { message: "missing 'markers' list" }),
+    notes: z.string().optional(),
+    /**
+     * GitHub orgs that map to this engagement. Phase 1 of the zero-config
+     * onboarding work: a repo whose origin's org appears here is auto-
+     * classified as `customer-coupled` with this engagement attached.
+     * Schema-level constraints: each entry must match {@link ORG_NAME_REGEX};
+     * cross-engagement uniqueness and disjointness with `personalOrgs` are
+     * enforced by the registry-level superRefine.
+     */
+    githubOrgs: z.array(orgNameSchema).optional(),
+})
+    .passthrough(); // Forward-compat: unknown sibling fields are kept, not rejected.
+export const registryFileSchema = z
+    .object({
+    schemaVersion: z
+        .number({ message: "'schemaVersion' must be a number" })
+        .optional(),
+    always_block: z
+        .array(z.string({ message: "'always_block' entries must be strings" }), {
+        message: "'always_block' must be a list of patterns",
+    })
+        .optional(),
+    /**
+     * Top-level orgs the user owns / treats as public. A repo whose
+     * origin's org is here is auto-classified as `public-eligible`.
+     * Disjoint from any engagement's `githubOrgs`.
+     */
+    personalOrgs: z.array(orgNameSchema).optional(),
+    engagements: z.array(engagementSchema, { message: "'engagements' must be a list" }),
+})
+    .passthrough()
+    // Cross-field validation: org names must be unique across the
+    // (personalOrgs ∪ Σ engagements[*].githubOrgs) union, and within
+    // personalOrgs itself. Same-string overlap is a fail-closed parse error.
+    .superRefine((data, ctx) => {
+    const personalOrgs = data.personalOrgs ?? [];
+    // 1. personalOrgs internal duplicates.
+    const personalSeen = new Map();
+    for (let i = 0; i < personalOrgs.length; i++) {
+        const org = personalOrgs[i];
+        if (org === undefined)
+            continue;
+        const prev = personalSeen.get(org);
+        if (prev !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["personalOrgs", i],
+                message: `duplicate org "${org}" (also at personalOrgs[${prev}])`,
+            });
+        }
+        else {
+            personalSeen.set(org, i);
+        }
+    }
+    const personalSet = new Set(personalOrgs);
+    // 2. cross-engagement uniqueness + disjointness with personalOrgs.
+    const orgToEng = new Map();
+    for (let i = 0; i < data.engagements.length; i++) {
+        const eng = data.engagements[i];
+        if (eng === undefined)
+            continue;
+        const orgs = eng.githubOrgs ?? [];
+        for (let j = 0; j < orgs.length; j++) {
+            const org = orgs[j];
+            if (org === undefined)
+                continue;
+            if (personalSet.has(org)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["engagements", i, "githubOrgs", j],
+                    message: `org "${org}" appears in personalOrgs and ` +
+                        `engagements[${i}=${eng.id}].githubOrgs; ` +
+                        `the two are mutually exclusive`,
+                });
+            }
+            const prev = orgToEng.get(org);
+            if (prev !== undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["engagements", i, "githubOrgs", j],
+                    message: `org "${org}" is also in ` +
+                        `engagements[${prev.engIdx}=${prev.engId}].githubOrgs; ` +
+                        `an org maps to at most one engagement`,
+                });
+            }
+            else {
+                orgToEng.set(org, { engIdx: i, engId: eng.id, orgIdx: j });
+            }
+        }
+    }
+});
+// ---------------------------------------------------------------------------
+// Per-repo override (.repo-aegis.yml)
+// ---------------------------------------------------------------------------
+export const REPO_CLASSES = [
+    "public-eligible",
+    "private-strict",
+    "customer-coupled",
+    "scratch",
+];
+export const repoOverrideSchema = z
+    .object({
+    class: z.enum(REPO_CLASSES).optional(),
+    engagements: z
+        .array(z.string().min(1, "'engagements' entries must be non-empty strings"))
+        .optional(),
+})
+    .passthrough();
+// Note: schemas for files only loaded by `cli` (classify rules) or
+// `scan` (query files) live in those packages, not here. They use the
+// shared `formatZodError` helper exported above for consistent error
+// rendering, but the schemas themselves are package-private — moving
+// them here would inflate core's public surface for no gain.
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}

package/dist/secret-markers.d.ts

@@ -0,0 +1,34 @@
+export type SecretMarkerKind = "PEM_HEADER" | "PEM_AS_HEX" | "JWT" | "GITHUB_TOKEN";
+export interface SecretMarkerHit {
+    /** Which family of secret was detected. */
+    kind: SecretMarkerKind;
+    /** Byte offset of the match within the scanned text. */
+    offset: number;
+    /** Length of the match in bytes. */
+    length: number;
+}
+/**
+ * Scan a single string for any secret-shaped pattern. Returns one hit
+ * per match (a single PEM that's also matched as PEM-as-hex via
+ * pre-encoding will produce two hits — that's fine; the hook
+ * deduplicates by kind on output).
+ *
+ * The scanned input is bounded by the caller (the Bash-output hook
+ * caps at a few MB). This function does not enforce its own size cap
+ * because callers vary in tolerance.
+ *
+ * The function NEVER returns the matched substring — only the kind,
+ * offset, and length. By construction, a hit cannot leak the secret
+ * back through the result type.
+ */
+export declare function scanForSecrets(text: string): SecretMarkerHit[];
+/**
+ * Summarise hits as a redacted preview suitable for echoing back to
+ * the user / agent. Returns the kinds present and the total count;
+ * never includes any byte of matched content.
+ */
+export declare function summariseHits(hits: SecretMarkerHit[]): {
+    kinds: SecretMarkerKind[];
+    count: number;
+};
+//# sourceMappingURL=secret-markers.d.ts.map

package/dist/secret-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-markers.d.ts","sourceRoot":"","sources":["../src/secret-markers.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,YAAY,GACZ,KAAK,GACL,cAAc,CAAC;AAEnB,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,IAAI,EAAE,gBAAgB,CAAC;IACvB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAsDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CAyB9D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG;IACtD,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf,CAGA"}

package/dist/secret-markers.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+//
+// Universal secret-shaped patterns. Unlike the engagement-scoped deny
+// set in `deny-set.ts`, these patterns are not configurable: they cover
+// shapes that should never appear in Bash tool output regardless of
+// which customer the developer is engaged with.
+//
+// Detection is deliberately conservative — false-positive risk on
+// generic strings is acceptable because the consequence (a hook
+// flagging a tool result so the agent can surface it for rotation) is
+// cheap. False *negatives* are expensive (a real secret reaches the
+// transcript). When in doubt, add another pattern.
+//
+// What we deliberately do NOT match:
+//   - Hostnames or IP addresses (out of scope; not "secrets" by shape).
+//   - High-entropy generic blobs (UUIDs, base64-encoded data) — too
+//     much noise; rely on shape-specific patterns instead.
+//   - Customer-specific identifiers — those belong in the per-engagement
+//     deny set, not here.
+//
+// Pattern hardening: every regex is anchored to a recognisable shape
+// (a literal prefix and a length-bounded body). No greedy `.*` quantifiers
+// over potentially unbounded input. We compile once at module load.
+// Limit single-pattern body lengths to defend against pathological
+// input. 16 KB is generous for any real PEM / token / JWT shape.
+const MAX_BODY = 16 * 1024;
+const PATTERNS = [
+    // PEM headers in any common form: RSA, DSA, EC, ED25519, generic
+    // "PRIVATE KEY", and the corresponding ENCRYPTED variant. The
+    // closing dashes anchor the match without needing to capture the
+    // body, so a partial PEM (truncated by `head`/`tail`) still trips.
+    {
+        kind: "PEM_HEADER",
+        re: /-----BEGIN (?:RSA |DSA |EC |OPENSSH |ENCRYPTED |PGP )?PRIVATE KEY-----/g,
+    },
+    // PEM-as-ASCII-hex. The macOS keychain returns
+    // `security find-generic-password -w` as hex when the value contains
+    // newlines, so any PEM round-trips as a long hex string. Match the
+    // hex of `-----BEGIN ` (the prefix common to every PEM header):
+    // `-----BEGIN ` => `2D2D2D2D2D424547494E20` (case-insensitive on hex).
+    {
+        kind: "PEM_AS_HEX",
+        re: /(?:2D){5}424547494E20/gi,
+    },
+    // JWT shape. Three URL-safe-base64 segments separated by dots, each
+    // at least 8 chars. The first segment must start with `eyJ` (the
+    // unencrypted base64 of `{"`), which is the universal JWT header
+    // prefix. Bounded body length per segment to defend against
+    // catastrophic backtracking (although the inner class is bounded
+    // already).
+    {
+        kind: "JWT",
+        re: /\beyJ[A-Za-z0-9_-]{8,4096}\.eyJ[A-Za-z0-9_-]{8,4096}\.[A-Za-z0-9_-]{8,4096}/g,
+    },
+    // GitHub token shapes: PAT (`ghp_`), OAuth (`gho_`), App user
+    // (`ghu_`), App installation (`ghs_`), refresh (`ghr_`), and the
+    // newer fine-grained PAT prefix `github_pat_`. All use a fixed
+    // suffix character class plus length range. Tokens shorter than 36
+    // chars after the prefix are unlikely to be live tokens but still
+    // worth flagging — false positives here cost nothing.
+    {
+        kind: "GITHUB_TOKEN",
+        re: /\b(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{20,255})\b/g,
+    },
+];
+/**
+ * Scan a single string for any secret-shaped pattern. Returns one hit
+ * per match (a single PEM that's also matched as PEM-as-hex via
+ * pre-encoding will produce two hits — that's fine; the hook
+ * deduplicates by kind on output).
+ *
+ * The scanned input is bounded by the caller (the Bash-output hook
+ * caps at a few MB). This function does not enforce its own size cap
+ * because callers vary in tolerance.
+ *
+ * The function NEVER returns the matched substring — only the kind,
+ * offset, and length. By construction, a hit cannot leak the secret
+ * back through the result type.
+ */
+export function scanForSecrets(text) {
+    const hits = [];
+    for (const { kind, re } of PATTERNS) {
+        // RegExp objects with /g flag are stateful via lastIndex; reset
+        // before each scan so concurrent callers don't trip over each
+        // other (we use a fresh exec loop per call, not iterators).
+        re.lastIndex = 0;
+        let m;
+        let iter = 0;
+        while ((m = re.exec(text)) !== null) {
+            const matched = m[0];
+            // Defensive: cap match length tracked. If a single match somehow
+            // exceeds MAX_BODY, record only the first MAX_BODY bytes' worth
+            // and advance lastIndex past it.
+            const length = Math.min(matched.length, MAX_BODY);
+            hits.push({ kind, offset: m.index, length });
+            if (matched.length === 0)
+                re.lastIndex++; // safety against zero-width
+            // Bail out of pathological-input loops: 1000 hits of the same
+            // pattern is far more than any legitimate output produces.
+            if (++iter > 1000)
+                break;
+        }
+    }
+    // Sort by offset so the caller can report hits in source order.
+    hits.sort((a, b) => a.offset - b.offset);
+    return hits;
+}
+/**
+ * Summarise hits as a redacted preview suitable for echoing back to
+ * the user / agent. Returns the kinds present and the total count;
+ * never includes any byte of matched content.
+ */
+export function summariseHits(hits) {
+    const kinds = Array.from(new Set(hits.map(h => h.kind))).sort();
+    return { kinds, count: hits.length };
+}
+//# sourceMappingURL=secret-markers.js.map

package/dist/secret-markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-markers.js","sourceRoot":"","sources":["../src/secret-markers.ts"],"names":[],"mappings":"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"}

package/dist/secret-markers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=secret-markers.test.d.ts.map

package/dist/secret-markers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-markers.test.d.ts","sourceRoot":"","sources":["../src/secret-markers.test.ts"],"names":[],"mappings":""}

package/dist/secret-markers.test.js

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { scanForSecrets, summariseHits, } from "./secret-markers.js";
+// Test fixtures intentionally do NOT contain real secrets — these are
+// shape-matching strings that any plausible regex would also match.
+// Keep them well-known dummies so accidentally publishing the test
+// fixtures stays harmless.
+const DUMMY_PEM_HEADER = "-----BEGIN RSA PRIVATE KEY-----";
+const DUMMY_PEM_OPENSSH = "-----BEGIN OPENSSH PRIVATE KEY-----";
+const DUMMY_PEM_GENERIC = "-----BEGIN PRIVATE KEY-----";
+const DUMMY_PEM_AS_HEX = "2D2D2D2D2D424547494E2052534120505249564154"; // hex of "-----BEGIN RSA PRIVAT" (truncated)
+const DUMMY_GHS = "ghs_" + "A".repeat(36);
+const DUMMY_GHP = "ghp_" + "z".repeat(40);
+const DUMMY_GHO = "gho_" + "1".repeat(36);
+const DUMMY_GHU = "ghu_" + "9".repeat(36);
+const DUMMY_GHR = "ghr_" + "x".repeat(36);
+const DUMMY_GH_PAT = "github_pat_" + "Z".repeat(40);
+// Three-segment URL-safe base64, header starts with "eyJ"
+const DUMMY_JWT = "eyJ" + "Q".repeat(20) + "." +
+    "eyJ" + "R".repeat(20) + "." +
+    "S".repeat(40);
+describe("scanForSecrets — PEM headers", () => {
+    it("matches RSA private key header", () => {
+        const hits = scanForSecrets(`prefix ${DUMMY_PEM_HEADER} suffix`);
+        assert.equal(hits.length, 1);
+        assert.equal(hits[0].kind, "PEM_HEADER");
+    });
+    it("matches OPENSSH variant", () => {
+        const hits = scanForSecrets(DUMMY_PEM_OPENSSH);
+        assert.equal(hits.length, 1);
+        assert.equal(hits[0].kind, "PEM_HEADER");
+    });
+    it("matches generic PRIVATE KEY (no algorithm prefix)", () => {
+        const hits = scanForSecrets(DUMMY_PEM_GENERIC);
+        assert.equal(hits.length, 1);
+        assert.equal(hits[0].kind, "PEM_HEADER");
+    });
+    it("matches multiple headers in one input", () => {
+        const text = `${DUMMY_PEM_HEADER}\nbody\n-----END RSA PRIVATE KEY-----\n${DUMMY_PEM_HEADER}`;
+        const hits = scanForSecrets(text);
+        const headerHits = hits.filter(h => h.kind === "PEM_HEADER");
+        assert.equal(headerHits.length, 2);
+    });
+    it("does not match the matching END marker (only BEGIN)", () => {
+        const hits = scanForSecrets("-----END RSA PRIVATE KEY-----");
+        assert.equal(hits.length, 0);
+    });
+});
+describe("scanForSecrets — PEM as ASCII hex", () => {
+    it("matches the hex of '-----BEGIN '", () => {
+        const hits = scanForSecrets(DUMMY_PEM_AS_HEX);
+        const hexHits = hits.filter(h => h.kind === "PEM_AS_HEX");
+        assert.equal(hexHits.length, 1);
+    });
+    it("is case-insensitive on hex digits", () => {
+        const upper = DUMMY_PEM_AS_HEX.toUpperCase();
+        const lower = DUMMY_PEM_AS_HEX.toLowerCase();
+        assert.equal(scanForSecrets(upper).filter(h => h.kind === "PEM_AS_HEX").length, 1);
+        assert.equal(scanForSecrets(lower).filter(h => h.kind === "PEM_AS_HEX").length, 1);
+    });
+    it("ignores arbitrary hex strings that are not PEM headers", () => {
+        const hits = scanForSecrets("deadbeef".repeat(50));
+        assert.equal(hits.filter(h => h.kind === "PEM_AS_HEX").length, 0);
+    });
+});
+describe("scanForSecrets — GitHub tokens", () => {
+    for (const [label, dummy] of [
+        ["ghs_", DUMMY_GHS],
+        ["ghp_", DUMMY_GHP],
+        ["gho_", DUMMY_GHO],
+        ["ghu_", DUMMY_GHU],
+        ["ghr_", DUMMY_GHR],
+        ["github_pat_", DUMMY_GH_PAT],
+    ]) {
+        it(`matches ${label} prefix`, () => {
+            const hits = scanForSecrets(`auth: ${dummy}`);
+            assert.equal(hits.length, 1, `expected one hit for ${label}`);
+            assert.equal(hits[0].kind, "GITHUB_TOKEN");
+        });
+    }
+    it("does not match short prefix-only fragments", () => {
+        assert.equal(scanForSecrets("ghs_short").length, 0);
+        assert.equal(scanForSecrets("ghp_").length, 0);
+    });
+    it("does not match unrelated `gh` strings", () => {
+        assert.equal(scanForSecrets("github.com").length, 0);
+        assert.equal(scanForSecrets("ghosts").length, 0);
+    });
+});
+describe("scanForSecrets — JWT shape", () => {
+    it("matches a 3-segment JWT", () => {
+        const hits = scanForSecrets(`Authorization: Bearer ${DUMMY_JWT}`);
+        assert.equal(hits.filter(h => h.kind === "JWT").length, 1);
+    });
+    it("does not match a 2-segment string", () => {
+        const twoSeg = "eyJabc.eyJdef";
+        assert.equal(scanForSecrets(twoSeg).filter(h => h.kind === "JWT").length, 0);
+    });
+    it("does not match base64 blobs without the eyJ prefix", () => {
+        const fake = "abcdef.ghijkl.mnopqr";
+        assert.equal(scanForSecrets(fake).filter(h => h.kind === "JWT").length, 0);
+    });
+});
+describe("scanForSecrets — clean inputs", () => {
+    it("returns no hits on empty string", () => {
+        assert.deepEqual(scanForSecrets(""), []);
+    });
+    it("returns no hits on plain prose", () => {
+        const text = "This is a normal log message about installing the GitHub App " +
+            "for engagement acme. The app slug is acme-alice-bot. No secrets here.";
+        assert.deepEqual(scanForSecrets(text), []);
+    });
+    it("returns no hits on a public key (only private)", () => {
+        const text = "-----BEGIN PUBLIC KEY-----\nblah\n-----END PUBLIC KEY-----";
+        assert.deepEqual(scanForSecrets(text), []);
+    });
+});
+describe("scanForSecrets — never returns matched bytes", () => {
+    it("hit objects only carry kind/offset/length", () => {
+        const hits = scanForSecrets(`${DUMMY_PEM_HEADER} ${DUMMY_GHS}`);
+        for (const h of hits) {
+            const keys = Object.keys(h).sort();
+            assert.deepEqual(keys, ["kind", "length", "offset"]);
+        }
+    });
+});
+describe("scanForSecrets — multiple kinds in one input", () => {
+    it("reports one hit per pattern, sorted by offset", () => {
+        const text = `start ${DUMMY_PEM_HEADER} middle ${DUMMY_GHS} end ${DUMMY_JWT}`;
+        const hits = scanForSecrets(text);
+        assert.ok(hits.length >= 3);
+        for (let i = 1; i < hits.length; i++) {
+            assert.ok(hits[i].offset >= hits[i - 1].offset, "hits must be sorted by offset");
+        }
+    });
+});
+describe("summariseHits", () => {
+    it("returns kinds + count, never bytes", () => {
+        const hits = [
+            { kind: "PEM_HEADER", offset: 0, length: 30 },
+            { kind: "GITHUB_TOKEN", offset: 50, length: 40 },
+            { kind: "PEM_HEADER", offset: 100, length: 30 },
+        ];
+        const s = summariseHits(hits);
+        assert.deepEqual(s.kinds, ["GITHUB_TOKEN", "PEM_HEADER"]);
+        assert.equal(s.count, 3);
+    });
+    it("handles empty input", () => {
+        assert.deepEqual(summariseHits([]), { kinds: [], count: 0 });
+    });
+});
+//# sourceMappingURL=secret-markers.test.js.map

package/dist/secret-markers.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-markers.test.js","sourceRoot":"","sources":["../src/secret-markers.test.ts"],"names":[],"mappings":"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"}

package/dist/trust-boundary.d.ts

@@ -0,0 +1,33 @@
+import { type RepoClass } from "./repo.js";
+import { type Registry } from "./registry.js";
+export interface TrustBoundary {
+    /** Set of GitHub orgs that span this repo's trust boundary. */
+    orgs: Set<string>;
+    /**
+     * True when `orgs` came from the git remote because no
+     * classification could supply orgs. The hook surfaces this as
+     * `DEST_UNCLASSIFIED` when the destination tree is in this state.
+     */
+    fromRemoteFallback: boolean;
+    /** The repo's resolved class (private-strict if unclassified). */
+    class: RepoClass;
+    /** True if class came from explicit git config / `.repo-aegis.yml`. */
+    classExplicit: boolean;
+}
+/**
+ * Compute the trust boundary for a working tree against a registry.
+ *
+ * Reads `git config repo-aegis.class` / `.repo-aegis.yml` for the
+ * working tree (via {@link readRepoConfig}), pulls the relevant
+ * `githubOrgs` arrays out of the registry, and falls back to the
+ * remote URL only when the classification supplies no orgs.
+ */
+export declare function computeTrustBoundary(workingTree: string, registry: Registry): TrustBoundary;
+/**
+ * Two trust boundaries overlap iff their org sets share at least one
+ * element. Two empty sets do NOT overlap — that's the "neither side
+ * has any signal" case, which the policy layer treats as
+ * "scan-with-warning" rather than silently allowing.
+ */
+export declare function trustBoundariesOverlap(a: TrustBoundary, b: TrustBoundary): boolean;
+//# sourceMappingURL=trust-boundary.d.ts.map

package/dist/trust-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-boundary.d.ts","sourceRoot":"","sources":["../src/trust-boundary.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,KAAK,EAAE,SAAS,CAAC;IACjB,uEAAuE;IACvE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,QAAQ,GACjB,aAAa,CAqCf;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAIlF"}

package/dist/trust-boundary.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+//
+// Trust-boundary computation for the path-aware PostToolUse hook.
+//
+// Two working trees are in the same trust boundary if their derived
+// org sets overlap. The org set for a working tree is:
+//
+//   (engagements[*].githubOrgs of every engagement the repo is
+//    allow'd into)
+//   ∪ (personalOrgs, if class === public-eligible)
+//   ∪ (remote-origin org, if the above is empty)
+//
+// The classification is the source of truth (per design open question
+// #3): a fork's remote may belong to one org while the classification
+// declares the canonical engagement-org mapping. The remote is only
+// consulted as a last-resort fallback for completely unclassified repos.
+import { readRepoConfig } from "./repo.js";
+import { getRemoteOrg } from "./working-tree.js";
+/**
+ * Compute the trust boundary for a working tree against a registry.
+ *
+ * Reads `git config repo-aegis.class` / `.repo-aegis.yml` for the
+ * working tree (via {@link readRepoConfig}), pulls the relevant
+ * `githubOrgs` arrays out of the registry, and falls back to the
+ * remote URL only when the classification supplies no orgs.
+ */
+export function computeTrustBoundary(workingTree, registry) {
+    const repo = readRepoConfig(workingTree);
+    const orgs = new Set();
+    // Engagement-derived orgs.
+    for (const engId of repo.engagements) {
+        const eng = registry.engagements.find(e => e.id === engId);
+        if (!eng)
+            continue;
+        for (const org of eng.githubOrgs ?? []) {
+            orgs.add(org.toLowerCase());
+        }
+    }
+    // public-eligible repos sit on every personal org. The model says
+    // "this repo is not customer-coupled, so anything in personalOrgs
+    // is its peer."
+    if (repo.class === "public-eligible") {
+        for (const org of registry.personalOrgs ?? []) {
+            orgs.add(org.toLowerCase());
+        }
+    }
+    let fromRemoteFallback = false;
+    if (orgs.size === 0) {
+        const remoteOrg = getRemoteOrg(workingTree);
+        if (remoteOrg !== null) {
+            orgs.add(remoteOrg);
+            fromRemoteFallback = true;
+        }
+    }
+    return {
+        orgs,
+        fromRemoteFallback,
+        class: repo.class,
+        classExplicit: repo.classExplicit,
+    };
+}
+/**
+ * Two trust boundaries overlap iff their org sets share at least one
+ * element. Two empty sets do NOT overlap — that's the "neither side
+ * has any signal" case, which the policy layer treats as
+ * "scan-with-warning" rather than silently allowing.
+ */
+export function trustBoundariesOverlap(a, b) {
+    if (a.orgs.size === 0 || b.orgs.size === 0)
+        return false;
+    for (const o of a.orgs)
+        if (b.orgs.has(o))
+            return true;
+    return false;
+}
+//# sourceMappingURL=trust-boundary.js.map