@axtary/actionpass 0.0.1 → 0.2.0

package/dist/caep.js

@@ -0,0 +1,258 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createRemoteJWKSet, decodeProtectedHeader, jwtVerify, } from "jose";
+import { lock } from "proper-lockfile";
+import { z } from "zod";
+export const SSF_SET_TYP = "secevent+jwt";
+export const CAEP_SESSION_REVOKED_EVENT = "https://schemas.openid.net/secevent/caep/event-type/session-revoked";
+export const CAEP_MAPPING_STORE_VERSION = "axtary.caep_mapping_store.v0";
+export const SSF_REPLAY_STORE_VERSION = "axtary.ssf_replay_store.v0";
+const JsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema),
+]));
+export const SsfSubjectIdentifierSchema = z
+    .object({
+    format: z.string().min(1),
+})
+    .catchall(JsonValueSchema);
+export const CaepSessionRevokedClaimsSchema = z.object({
+    iss: z.string().url(),
+    aud: z.union([z.string().min(1), z.array(z.string().min(1))]),
+    iat: z.number().int().positive(),
+    jti: z.string().min(1),
+    txn: z.string().min(1).optional(),
+    sub_id: SsfSubjectIdentifierSchema,
+    events: z.record(z.string(), z.record(z.string(), JsonValueSchema)),
+});
+export const CaepMappingSchema = z.object({
+    transmitterIssuer: z.string().url(),
+    subjectKey: z.string().min(1),
+    rootPassIds: z.array(z.string().min(1)).min(1),
+    createdAt: z.string().datetime(),
+});
+export const CaepMappingStoreSchema = z.object({
+    schemaVersion: z.literal(CAEP_MAPPING_STORE_VERSION),
+    mappings: z.array(CaepMappingSchema),
+});
+const SsfReplayEntrySchema = z.object({
+    issuer: z.string().url(),
+    eventId: z.string().min(1),
+    expiresAt: z.string().datetime(),
+});
+const SsfReplayStoreSchema = z.object({
+    schemaVersion: z.literal(SSF_REPLAY_STORE_VERSION),
+    entries: z.array(SsfReplayEntrySchema),
+});
+export function ssfSubjectKey(subjectInput) {
+    return stableStringify(SsfSubjectIdentifierSchema.parse(subjectInput));
+}
+export async function verifyCaepSessionRevoked(input) {
+    const header = decodeProtectedHeader(input.token);
+    if (header.typ !== SSF_SET_TYP) {
+        throw new Error("ssf_set_type_invalid");
+    }
+    const localKey = input.jwksUri
+        ? undefined
+        : await resolveKey(input.verificationKeys, header.kid);
+    if (!input.jwksUri && !localKey) {
+        throw new Error(header.kid
+            ? `ssf_verification_key_not_found:${header.kid}`
+            : "ssf_verification_key_id_required");
+    }
+    const currentDate = input.currentDate ?? new Date();
+    const verifyOptions = {
+        issuer: input.issuer,
+        audience: input.audience,
+        algorithms: ["ES256"],
+        currentDate,
+    };
+    const { payload } = input.jwksUri
+        ? await jwtVerify(input.token, createRemoteJWKSet(new URL(input.jwksUri)), verifyOptions)
+        : await jwtVerify(input.token, localKey, verifyOptions);
+    const claims = CaepSessionRevokedClaimsSchema.parse(payload);
+    const ageSeconds = Math.floor(currentDate.getTime() / 1000) - claims.iat;
+    if (ageSeconds < -5 || ageSeconds > (input.maxAgeSeconds ?? 300)) {
+        throw new Error("ssf_set_outside_accepted_window");
+    }
+    const eventKeys = Object.keys(claims.events);
+    if (eventKeys.length !== 1 ||
+        eventKeys[0] !== CAEP_SESSION_REVOKED_EVENT) {
+        throw new Error("caep_event_type_unsupported");
+    }
+    return claims;
+}
+export class LocalCaepMappingStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async read() {
+        try {
+            return CaepMappingStoreSchema.parse(JSON.parse(await readFile(this.filePath, "utf8")));
+        }
+        catch (error) {
+            if (isEnoent(error)) {
+                return { schemaVersion: CAEP_MAPPING_STORE_VERSION, mappings: [] };
+            }
+            throw error;
+        }
+    }
+    async put(input) {
+        const mapping = CaepMappingSchema.parse({
+            transmitterIssuer: input.transmitterIssuer,
+            subjectKey: ssfSubjectKey(input.subject),
+            rootPassIds: [...new Set(input.rootPassIds)].sort(),
+            createdAt: (input.createdAt ?? new Date()).toISOString(),
+        });
+        await withFileLock(this.filePath, async () => {
+            const data = await this.read();
+            await writePrivateJson(this.filePath, {
+                ...data,
+                mappings: [
+                    ...data.mappings.filter((entry) => !(entry.transmitterIssuer === mapping.transmitterIssuer &&
+                        entry.subjectKey === mapping.subjectKey)),
+                    mapping,
+                ].sort((left, right) => `${left.transmitterIssuer}:${left.subjectKey}`.localeCompare(`${right.transmitterIssuer}:${right.subjectKey}`)),
+            });
+        });
+        return mapping;
+    }
+    async rootsFor(transmitterIssuer, subject) {
+        const key = ssfSubjectKey(subject);
+        return ((await this.read()).mappings.find((entry) => entry.transmitterIssuer === transmitterIssuer &&
+            entry.subjectKey === key)?.rootPassIds ?? []);
+    }
+}
+export class LocalSsfReplayStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async consume(issuer, eventId, now = new Date(), retentionSeconds = 86_400) {
+        return (await this.processOnce(issuer, eventId, async () => undefined, now, retentionSeconds)).processed;
+    }
+    async processOnce(issuer, eventId, operation, now = new Date(), retentionSeconds = 86_400) {
+        return withFileLock(this.filePath, async () => {
+            let data;
+            try {
+                data = SsfReplayStoreSchema.parse(JSON.parse(await readFile(this.filePath, "utf8")));
+            }
+            catch (error) {
+                if (!isEnoent(error))
+                    throw error;
+                data = { schemaVersion: SSF_REPLAY_STORE_VERSION, entries: [] };
+            }
+            const live = data.entries.filter((entry) => Date.parse(entry.expiresAt) > now.getTime());
+            if (live.some((entry) => entry.issuer === issuer && entry.eventId === eventId)) {
+                return { processed: false };
+            }
+            const result = await operation();
+            live.push({
+                issuer,
+                eventId,
+                expiresAt: new Date(now.getTime() + retentionSeconds * 1000).toISOString(),
+            });
+            await writePrivateJson(this.filePath, {
+                schemaVersion: SSF_REPLAY_STORE_VERSION,
+                entries: live,
+            });
+            return { processed: true, result };
+        });
+    }
+}
+export async function processCaepSessionRevoked(input) {
+    const claims = await verifyCaepSessionRevoked(input);
+    const processed = await input.replayStore.processOnce(claims.iss, claims.jti, async () => {
+        const rootPassIds = await input.mappingStore.rootsFor(claims.iss, claims.sub_id);
+        for (const rootPassId of rootPassIds) {
+            await input.revoke(rootPassId, claims);
+        }
+        return rootPassIds;
+    }, input.currentDate);
+    if (!processed.processed) {
+        return {
+            eventId: claims.jti,
+            subjectKey: ssfSubjectKey(claims.sub_id),
+            rootPassIds: [],
+            status: "replayed",
+        };
+    }
+    const rootPassIds = processed.result;
+    return {
+        eventId: claims.jti,
+        subjectKey: ssfSubjectKey(claims.sub_id),
+        rootPassIds,
+        status: rootPassIds.length > 0 ? "applied" : "unmapped",
+    };
+}
+async function resolveKey(keys, kid) {
+    if (!keys)
+        return undefined;
+    return typeof keys === "function" ? keys(kid) : kid ? keys[kid] : undefined;
+}
+async function writePrivateJson(filePath, value) {
+    await mkdir(dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    let renamed = false;
+    try {
+        const handle = await open(tmpPath, "wx", 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tmpPath, filePath);
+        renamed = true;
+    }
+    finally {
+        if (!renamed)
+            await rm(tmpPath, { force: true });
+    }
+}
+async function withFileLock(filePath, operation) {
+    await mkdir(dirname(filePath), { recursive: true });
+    const release = await lock(filePath, {
+        realpath: false,
+        lockfilePath: `${filePath}.lock`,
+        stale: 10_000,
+        update: 5_000,
+        retries: {
+            retries: 100,
+            factor: 1.2,
+            minTimeout: 10,
+            maxTimeout: 100,
+        },
+    });
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function isEnoent(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+//# sourceMappingURL=caep.js.map

package/dist/caep.js.map

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

package/dist/dev-key.d.ts

@@ -0,0 +1,50 @@
+import { type JWK, type KeyObject } from "jose";
+/** Env var holding an ES256 private key (PEM, or base64-encoded PEM). */
+export declare const AXTARY_DEV_SIGNING_KEY_ENV = "AXTARY_DEV_SIGNING_KEY";
+/** Optional env var overriding the dev key id (`kid`). */
+export declare const AXTARY_DEV_KEY_ID_ENV = "AXTARY_DEV_KEY_ID";
+/** Env var pointing the local keyring at a directory other than ./.axtary. */
+export declare const AXTARY_HOME_ENV = "AXTARY_HOME";
+/** Filename of the file-backed dev keyring inside the resolved home dir. */
+export declare const AXTARY_DEV_KEYRING_FILENAME = "sdk-dev-keyring.json";
+/** Default `kid` for an env-backed dev key when none is supplied. */
+export declare const AXTARY_DEFAULT_DEV_KEY_ID = "axtary-dev";
+export type DevKeypairSource = "env" | "file";
+export type DevKeypair = {
+    /** ES256 private key, ready to pass to createAxtary({ signingKey }). */
+    signingKey: KeyObject;
+    /** Matching public JWK, used by verify(). */
+    verificationKey: JWK;
+    /** Key id stamped into issued passes (`kid`). */
+    signingKeyId: string;
+    algorithm: "ES256";
+    /** Where the key came from: an env var or the local keyring file. */
+    source: DevKeypairSource;
+    /** Keyring file path when source === "file"; omitted for env-backed keys. */
+    path?: string;
+};
+export type DevKeypairOptions = {
+    /** Override the keyring file path (file-backed source). */
+    path?: string;
+    /** Environment to read; defaults to process.env. */
+    env?: Record<string, string | undefined>;
+};
+/**
+ * Resolve the file-backed dev keyring path: an explicit override, else
+ * `$AXTARY_HOME/sdk-dev-keyring.json`, else project-local
+ * `.axtary/sdk-dev-keyring.json`.
+ */
+export declare function resolveDevKeyringPath(options?: DevKeypairOptions): string;
+/**
+ * Resolve a stable, persistent ES256 dev keypair with zero manual JWK code.
+ * Resolution order: AXTARY_DEV_SIGNING_KEY (env-backed, shared across
+ * processes) → a local keyring file (default `.axtary/sdk-dev-keyring.json`,
+ * `0600`, gitignored). Both verify across process restarts. Pass the result
+ * straight to the SDK: `createAxtary(await devKeypair())`.
+ *
+ * This is a development convenience. For production use a real issuer key or a
+ * hosted issuer; the file-backed key never leaves the machine and the env-backed
+ * key is whatever the operator provisions.
+ */
+export declare function devKeypair(options?: DevKeypairOptions): Promise<DevKeypair>;
+//# sourceMappingURL=dev-key.d.ts.map

package/dist/dev-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-key.d.ts","sourceRoot":"","sources":["../src/dev-key.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAa,KAAK,GAAG,EAAE,KAAK,SAAS,EAAE,MAAM,MAAM,CAAC;AAG3D,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,2BAA2B,CAAC;AACnE,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,8EAA8E;AAC9E,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,yBAAyB,CAAC;AAClE,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,eAAe,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG;IACvB,wEAAwE;IACxE,UAAU,EAAE,SAAS,CAAC;IACtB,6CAA6C;IAC7C,eAAe,EAAE,GAAG,CAAC;IACrB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,MAAM,EAAE,gBAAgB,CAAC;IACzB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAU7E;AAgCD;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAkBrB"}

package/dist/dev-key.js

@@ -0,0 +1,103 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Dev keypair helper (PRD §8.2 developer experience; mega-plan M8.2)
+//
+// The SDK facade signs ActionPasses with an issuer key. In production a
+// developer supplies their own key (or a hosted issuer); for local development
+// we want zero manual JWK plumbing while still producing passes that verify
+// across process restarts (an ephemeral per-process key cannot).
+//
+// `devKeypair()` resolves a stable ES256 keypair with no key code:
+//   1. AXTARY_DEV_SIGNING_KEY  — env-backed, shared across processes/CI/containers
+//   2. a local keyring file    — default .axtary/sdk-dev-keyring.json (0600, gitignored)
+// Both survive restarts. Spread the result directly into createAxtary():
+//   const sdk = createAxtary(await devKeypair());
+//
+// This adds no new authorization or token/ledger/policy shape; it only produces
+// the same { signingKey, verificationKey } the facade already accepts, reusing
+// the existing persistent issuer-keyring primitive (status-list.ts).
+// ─────────────────────────────────────────────────────────────────────────────
+import { createPrivateKey, createPublicKey } from "node:crypto";
+import { join } from "node:path";
+import { exportJWK } from "jose";
+import { issuerSigningKey, loadOrCreateIssuerKeyring } from "./status-list.js";
+/** Env var holding an ES256 private key (PEM, or base64-encoded PEM). */
+export const AXTARY_DEV_SIGNING_KEY_ENV = "AXTARY_DEV_SIGNING_KEY";
+/** Optional env var overriding the dev key id (`kid`). */
+export const AXTARY_DEV_KEY_ID_ENV = "AXTARY_DEV_KEY_ID";
+/** Env var pointing the local keyring at a directory other than ./.axtary. */
+export const AXTARY_HOME_ENV = "AXTARY_HOME";
+/** Filename of the file-backed dev keyring inside the resolved home dir. */
+export const AXTARY_DEV_KEYRING_FILENAME = "sdk-dev-keyring.json";
+/** Default `kid` for an env-backed dev key when none is supplied. */
+export const AXTARY_DEFAULT_DEV_KEY_ID = "axtary-dev";
+/**
+ * Resolve the file-backed dev keyring path: an explicit override, else
+ * `$AXTARY_HOME/sdk-dev-keyring.json`, else project-local
+ * `.axtary/sdk-dev-keyring.json`.
+ */
+export function resolveDevKeyringPath(options = {}) {
+    if (options.path) {
+        return options.path;
+    }
+    const env = options.env ?? process.env;
+    const home = env[AXTARY_HOME_ENV];
+    if (home && home.trim().length > 0) {
+        return join(home, AXTARY_DEV_KEYRING_FILENAME);
+    }
+    return join(".axtary", AXTARY_DEV_KEYRING_FILENAME);
+}
+function pemFromEnvValue(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.includes("-----BEGIN")) {
+        return trimmed;
+    }
+    // Single-line base64 / base64url-encoded PEM (env-var friendly).
+    return Buffer.from(trimmed, "base64").toString("utf8");
+}
+async function envBackedKey(env) {
+    const raw = env[AXTARY_DEV_SIGNING_KEY_ENV];
+    if (!raw || raw.trim().length === 0) {
+        return null;
+    }
+    const signingKey = createPrivateKey(pemFromEnvValue(raw));
+    const verificationKey = await exportJWK(createPublicKey(signingKey));
+    verificationKey.alg = "ES256";
+    const keyId = env[AXTARY_DEV_KEY_ID_ENV];
+    return {
+        signingKey,
+        verificationKey,
+        signingKeyId: keyId && keyId.trim().length > 0 ? keyId : AXTARY_DEFAULT_DEV_KEY_ID,
+        algorithm: "ES256",
+        source: "env",
+    };
+}
+/**
+ * Resolve a stable, persistent ES256 dev keypair with zero manual JWK code.
+ * Resolution order: AXTARY_DEV_SIGNING_KEY (env-backed, shared across
+ * processes) → a local keyring file (default `.axtary/sdk-dev-keyring.json`,
+ * `0600`, gitignored). Both verify across process restarts. Pass the result
+ * straight to the SDK: `createAxtary(await devKeypair())`.
+ *
+ * This is a development convenience. For production use a real issuer key or a
+ * hosted issuer; the file-backed key never leaves the machine and the env-backed
+ * key is whatever the operator provisions.
+ */
+export async function devKeypair(options = {}) {
+    const env = options.env ?? process.env;
+    const fromEnv = await envBackedKey(env);
+    if (fromEnv) {
+        return fromEnv;
+    }
+    const path = resolveDevKeyringPath(options);
+    const keyring = await loadOrCreateIssuerKeyring(path);
+    const signer = issuerSigningKey(keyring);
+    return {
+        signingKey: signer.privateKey,
+        verificationKey: { ...signer.publicJwk, alg: "ES256" },
+        signingKeyId: signer.kid,
+        algorithm: "ES256",
+        source: "file",
+        path,
+    };
+}
+//# sourceMappingURL=dev-key.js.map

package/dist/dev-key.js.map

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

package/dist/explain.d.ts

@@ -0,0 +1,12 @@
+import type { PolicyDecision } from "./index.js";
+export type PolicyDecisionExplanation = {
+    label: string;
+    summary: string;
+    reviewerAction: "none" | "block" | "approval_required";
+    reasonDetails: Array<{
+        reason: string;
+        detail: string;
+    }>;
+};
+export declare function explainDecision(decisionInput: PolicyDecision): PolicyDecisionExplanation;
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,yBAAyB,GAAG;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,GAAG,OAAO,GAAG,mBAAmB,CAAC;IACvD,aAAa,EAAE,KAAK,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;CACJ,CAAC;AAEF,wBAAgB,eAAe,CAC7B,aAAa,EAAE,cAAc,GAC5B,yBAAyB,CAqB3B"}

package/dist/explain.js

@@ -0,0 +1,147 @@
+// Deterministic, human-readable explanation of a policy decision.
+//
+// This is the canonical reason→prose map for Axtary. It lives in the base
+// `@axtary/actionpass` package so both the SDK facade (`axtary.explain`) and the
+// policy/CLI surfaces share one source of truth instead of duplicating prose.
+// `@axtary/policy` re-exports `explainPolicyDecision` from here for backward
+// compatibility. It is intentionally deterministic — no model call — so the same
+// decision always produces the same explanation.
+export function explainDecision(decisionInput) {
+    const reviewerAction = decisionInput.decision === "allow"
+        ? "none"
+        : decisionInput.decision === "step_up"
+            ? "approval_required"
+            : "block";
+    const label = decisionInput.decision === "allow"
+        ? "Allowed"
+        : decisionInput.decision === "step_up"
+            ? "Step-up required"
+            : "Denied";
+    return {
+        label,
+        reviewerAction,
+        summary: decisionSummary(decisionInput),
+        reasonDetails: decisionInput.reasons.map((reason) => ({
+            reason,
+            detail: reasonDetail(reason),
+        })),
+    };
+}
+function decisionSummary(decisionInput) {
+    if (decisionInput.decision === "allow") {
+        return "The normalized action is inside the active policy and can proceed through ActionPass issuance.";
+    }
+    if (decisionInput.decision === "step_up") {
+        return "The normalized action is in scope only after exact payload-bound reviewer approval.";
+    }
+    return "The normalized action is outside the active policy and must not execute.";
+}
+function reasonDetail(reason) {
+    if (reason === "github_pr_inside_policy") {
+        return "Base branch, changed paths, file count, and test evidence satisfy the GitHub PR rule.";
+    }
+    if (reason === "github_content_write_inside_policy") {
+        return "The write path and branch are inside the configured repository guardrails.";
+    }
+    if (reason === "github_review_protected_path_step_up") {
+        return "The inline review targets a protected path and requires exact payload-bound approval.";
+    }
+    if (reason === "github_review_comment_inside_policy") {
+        return "The inline review target and exact comment body satisfy the repository guardrails.";
+    }
+    if (reason === "github_check_run_inside_policy") {
+        return "The check name, commit SHA, state, conclusion, and output are structurally valid and payload-bound.";
+    }
+    if (reason === "github_issue_comment_inside_policy") {
+        return "The issue number and exact outbound comment body are structurally valid and payload-bound.";
+    }
+    if (reason === "postgres_select_inside_policy") {
+        return "The parameterized SELECT, database, tables, functions, predicate, and row cap are inside the configured read scope.";
+    }
+    if (reason === "postgres_unpredicated_scan_step_up") {
+        return "The SELECT has no row predicate and requires exact payload-bound approval before the adapter can connect.";
+    }
+    if (reason === "postgres_select_only") {
+        return "Only one parsed SELECT statement is executable through the Postgres connector.";
+    }
+    if (reason === "postgres_table_not_allowed") {
+        return "At least one referenced table is outside the configured Postgres allowlist.";
+    }
+    if (reason === "github_branch_inside_policy") {
+        return "The branch creation request is tied to the configured base branch.";
+    }
+    if (reason === "content_read_denied_path") {
+        return "The requested file path matches a protected content-read prefix.";
+    }
+    if (reason === "payload_touches_denied_path") {
+        return "The payload touches a path prefix that policy blocks outright.";
+    }
+    if (reason === "payload_touches_step_up_path") {
+        return "The payload touches a protected path prefix that requires exact review.";
+    }
+    if (reason === "payload_touches_protected_path") {
+        return "The payload touches a protected path prefix and requires exact review.";
+    }
+    if (reason === "file_count_exceeds_policy_limit") {
+        return "The PR changes more files than the active policy allows without review.";
+    }
+    if (reason === "tests_required_before_pr") {
+        return "The PR payload does not include passing test evidence required by policy.";
+    }
+    if (reason === "payload_declares_production_impact") {
+        return "The action declares production impact, so reviewer approval is required.";
+    }
+    if (reason === "slack_channel_not_allowed") {
+        return "The Slack channel is not in the configured allowlist.";
+    }
+    if (reason === "slack_external_recipient_step_up") {
+        return "The message reaches external recipients and must be reviewed exactly.";
+    }
+    if (reason === "provenance_unknown_egress") {
+        return "A covered outbound field has no authority-stamped source lineage, so policy fails closed.";
+    }
+    if (reason === "provenance_untrusted_egress") {
+        return "A covered outbound field derives from untrusted document or tool output and requires exact review.";
+    }
+    if (reason === "linear_status_requires_step_up") {
+        return "The Linear status transition targets a configured protected status.";
+    }
+    if (reason === "jira_status_requires_step_up") {
+        return "The Jira status transition targets a configured protected status.";
+    }
+    if (reason.endsWith("_project_not_allowed")) {
+        return "The issue project key is outside the configured tracker allowlist.";
+    }
+    if (reason === "docs_search_inside_policy") {
+        return "The document search request stays inside the configured workspace and result limit.";
+    }
+    if (reason === "docs_read_inside_policy") {
+        return "The document path and requested byte limit are inside the configured documentation scope.";
+    }
+    if (reason === "docs_workspace_not_allowed") {
+        return "The document workspace is outside the configured allowlist.";
+    }
+    if (reason === "docs_path_denied") {
+        return "The requested document path matches a protected documentation prefix.";
+    }
+    if (reason === "docs_path_not_allowed") {
+        return "The requested document path is outside the configured documentation prefixes.";
+    }
+    if (reason === "docs_result_limit_exceeds_policy") {
+        return "The search request asks for more document results than policy allows.";
+    }
+    if (reason === "docs_read_bytes_exceeds_policy") {
+        return "The read request asks for more document bytes than policy allows.";
+    }
+    if (reason === "payload_is_inside_current_actionpass_constraints") {
+        return "The payload is inside the constraints carried by the current ActionPass.";
+    }
+    if (reason.startsWith("unsupported_tool:")) {
+        return "The tool is not supported by the native policy evaluator and fails closed.";
+    }
+    if (reason.startsWith("base_branch_mismatch:")) {
+        return "The requested base branch differs from the configured branch and needs review.";
+    }
+    return "The active native policy emitted this reason for the normalized action.";
+}
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

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