@connexum/ai-governance 1.0.0-beta.11

package/dist/governance/approval-channel-adapters.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Production transports for the ApprovalChannelDispatcher (W1.10).
+ *
+ * Provides concrete EmailSender + SmsSender implementations wired against
+ * real production APIs:
+ *   - Email: Resend (https://resend.com/docs/api-reference/emails/send-email)
+ *   - SMS:   Twilio (https://www.twilio.com/docs/messaging/send-messages)
+ *
+ * Both adapters accept an injectable `transport` so they can be unit-tested
+ * without hitting the network. In production the default transport uses
+ * node:https directly with no external SDK dependency.
+ *
+ * @connexum/ai-governance  F-NEW-PRODUCT-APPROVAL-CHANNEL-EMAIL-SMS (production wiring)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeHttpsTransport = void 0;
+exports.createResendEmailSender = createResendEmailSender;
+exports.createTwilioSmsSender = createTwilioSmsSender;
+const https = __importStar(require("node:https"));
+const nodeHttpsTransport = (req) => new Promise((resolve, reject) => {
+    const r = https.request({
+        method: req.method,
+        hostname: req.hostname,
+        path: req.path,
+        headers: req.headers,
+    }, (res) => {
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => resolve({
+            status: res.statusCode ?? 0,
+            bodyText: Buffer.concat(chunks).toString('utf8'),
+        }));
+        res.on('error', reject);
+    });
+    r.on('error', reject);
+    if (req.body !== undefined)
+        r.write(req.body);
+    r.end();
+});
+exports.nodeHttpsTransport = nodeHttpsTransport;
+function createResendEmailSender(options) {
+    if (!options.apiKey || options.apiKey.trim() === '') {
+        throw new Error('createResendEmailSender: apiKey is required');
+    }
+    const fromAddress = options.fromAddress ?? 'governance@my-cc.io';
+    const transport = options.transport ?? exports.nodeHttpsTransport;
+    return {
+        async send(params) {
+            const body = JSON.stringify({
+                from: fromAddress,
+                to: [params.to],
+                subject: params.subject,
+                html: params.html,
+                text: params.text,
+            });
+            try {
+                const res = await transport({
+                    method: 'POST',
+                    hostname: 'api.resend.com',
+                    path: '/emails',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${options.apiKey}`,
+                        'content-length': Buffer.byteLength(body).toString(),
+                    },
+                    body,
+                });
+                if (res.status >= 200 && res.status < 300) {
+                    let messageId;
+                    try {
+                        const parsed = JSON.parse(res.bodyText);
+                        messageId = parsed.id;
+                    }
+                    catch {
+                        // Some upstreams return an empty body on success.
+                    }
+                    return { ok: true, messageId };
+                }
+                return {
+                    ok: false,
+                    error: `resend status=${res.status} body=${res.bodyText.slice(0, 256)}`,
+                };
+            }
+            catch (err) {
+                return { ok: false, error: `resend transport error: ${err.message}` };
+            }
+        },
+    };
+}
+function createTwilioSmsSender(options) {
+    if (!options.accountSid || !options.authToken || !options.from) {
+        throw new Error('createTwilioSmsSender: accountSid, authToken, and from are required');
+    }
+    const transport = options.transport ?? exports.nodeHttpsTransport;
+    const basicAuth = Buffer.from(`${options.accountSid}:${options.authToken}`).toString('base64');
+    return {
+        async send(params) {
+            // Twilio expects application/x-www-form-urlencoded.
+            const fromKey = options.from.startsWith('MG') ? 'MessagingServiceSid' : 'From';
+            const formBody = new URLSearchParams({
+                [fromKey]: options.from,
+                To: params.to,
+                Body: params.body,
+            }).toString();
+            try {
+                const res = await transport({
+                    method: 'POST',
+                    hostname: 'api.twilio.com',
+                    path: `/2010-04-01/Accounts/${encodeURIComponent(options.accountSid)}/Messages.json`,
+                    headers: {
+                        'content-type': 'application/x-www-form-urlencoded',
+                        authorization: `Basic ${basicAuth}`,
+                        'content-length': Buffer.byteLength(formBody).toString(),
+                    },
+                    body: formBody,
+                });
+                if (res.status >= 200 && res.status < 300) {
+                    let messageId;
+                    try {
+                        const parsed = JSON.parse(res.bodyText);
+                        messageId = parsed.sid;
+                    }
+                    catch {
+                        // Tolerate non-JSON success bodies.
+                    }
+                    return { ok: true, messageId };
+                }
+                return {
+                    ok: false,
+                    error: `twilio status=${res.status} body=${res.bodyText.slice(0, 256)}`,
+                };
+            }
+            catch (err) {
+                return { ok: false, error: `twilio transport error: ${err.message}` };
+            }
+        },
+    };
+}
+//# sourceMappingURL=approval-channel-adapters.js.map

package/dist/governance/approval-channel-adapters.js.map

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

package/dist/governance/approval-channel-adapters.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * RED-GREEN tests for the production Resend + Twilio adapters (W1.10).
+ *
+ * @connexum/ai-governance  F-NEW-PRODUCT-APPROVAL-CHANNEL-EMAIL-SMS
+ */
+export {};
+//# sourceMappingURL=approval-channel-adapters.test.d.ts.map

package/dist/governance/approval-channel-adapters.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-channel-adapters.test.d.ts","sourceRoot":"","sources":["../../src/governance/approval-channel-adapters.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/governance/approval-channel-adapters.test.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * RED-GREEN tests for the production Resend + Twilio adapters (W1.10).
+ *
+ * @connexum/ai-governance  F-NEW-PRODUCT-APPROVAL-CHANNEL-EMAIL-SMS
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const assert = __importStar(require("node:assert/strict"));
+const approval_channel_adapters_1 = require("./approval-channel-adapters");
+function recordingTransport(response = { status: 200, bodyText: '{"id":"msg_1"}' }) {
+    const calls = [];
+    return {
+        calls,
+        transport: async (req) => {
+            calls.push(req);
+            return response;
+        },
+    };
+}
+(0, node_test_1.describe)('Resend email adapter (W1.10 production wiring)', () => {
+    (0, node_test_1.it)('sends a POST to api.resend.com/emails with the right headers + body', async () => {
+        const t = recordingTransport();
+        const sender = (0, approval_channel_adapters_1.createResendEmailSender)({ apiKey: 're_sk_test', transport: t.transport });
+        const res = await sender.send({
+            to: 'reviewer@example.com',
+            subject: 'Approval needed',
+            html: '<p>Hi</p>',
+            text: 'Hi',
+        });
+        assert.equal(res.ok, true);
+        assert.equal(res.messageId, 'msg_1');
+        assert.equal(t.calls.length, 1);
+        const call = t.calls[0];
+        assert.equal(call.method, 'POST');
+        assert.equal(call.hostname, 'api.resend.com');
+        assert.equal(call.path, '/emails');
+        assert.equal(call.headers['authorization'], 'Bearer re_sk_test');
+        assert.equal(call.headers['content-type'], 'application/json');
+        const body = JSON.parse(call.body ?? '{}');
+        assert.deepEqual(body.to, ['reviewer@example.com']);
+        assert.equal(body.subject, 'Approval needed');
+        assert.equal(body.html, '<p>Hi</p>');
+    });
+    (0, node_test_1.it)('non-2xx response surfaces as delivered=false with status + body in error', async () => {
+        const t = recordingTransport({ status: 401, bodyText: '{"error":"Unauthorized"}' });
+        const sender = (0, approval_channel_adapters_1.createResendEmailSender)({ apiKey: 're_sk_bad', transport: t.transport });
+        const res = await sender.send({ to: 'r@e.com', subject: 's', html: '', text: '' });
+        assert.equal(res.ok, false);
+        assert.match(res.error ?? '', /status=401/);
+    });
+    (0, node_test_1.it)('transport throw surfaces as delivered=false with error message', async () => {
+        const sender = (0, approval_channel_adapters_1.createResendEmailSender)({
+            apiKey: 're_sk_test',
+            transport: async () => {
+                throw new Error('network down');
+            },
+        });
+        const res = await sender.send({ to: 'r@e.com', subject: 's', html: '', text: '' });
+        assert.equal(res.ok, false);
+        assert.match(res.error ?? '', /network down/);
+    });
+    (0, node_test_1.it)('honors fromAddress override', async () => {
+        const t = recordingTransport();
+        const sender = (0, approval_channel_adapters_1.createResendEmailSender)({
+            apiKey: 're_sk_test',
+            transport: t.transport,
+            fromAddress: 'compliance@acme.com',
+        });
+        await sender.send({ to: 'r@e.com', subject: 's', html: 'x', text: 'x' });
+        const body = JSON.parse(t.calls[0].body ?? '{}');
+        assert.equal(body.from, 'compliance@acme.com');
+    });
+    (0, node_test_1.it)('missing apiKey throws on construction', () => {
+        assert.throws(() => (0, approval_channel_adapters_1.createResendEmailSender)({ apiKey: '' }), /apiKey is required/);
+    });
+});
+(0, node_test_1.describe)('Twilio SMS adapter (W1.10 production wiring)', () => {
+    (0, node_test_1.it)('sends a POST to Twilio Messages endpoint with basic auth + form body', async () => {
+        const t = recordingTransport({
+            status: 201,
+            bodyText: '{"sid":"SM123","status":"queued"}',
+        });
+        const sender = (0, approval_channel_adapters_1.createTwilioSmsSender)({
+            accountSid: 'AC123',
+            authToken: 'tok',
+            from: '+15551112222',
+            transport: t.transport,
+        });
+        const res = await sender.send({ to: '+15553334444', body: 'Approve: https://x' });
+        assert.equal(res.ok, true);
+        assert.equal(res.messageId, 'SM123');
+        const call = t.calls[0];
+        assert.equal(call.method, 'POST');
+        assert.equal(call.hostname, 'api.twilio.com');
+        assert.equal(call.path, '/2010-04-01/Accounts/AC123/Messages.json');
+        assert.match(call.headers['authorization'], /^Basic /);
+        assert.equal(call.headers['content-type'], 'application/x-www-form-urlencoded');
+        const form = new URLSearchParams(call.body ?? '');
+        assert.equal(form.get('From'), '+15551112222');
+        assert.equal(form.get('To'), '+15553334444');
+        assert.equal(form.get('Body'), 'Approve: https://x');
+    });
+    (0, node_test_1.it)('uses MessagingServiceSid when from starts with MG', async () => {
+        const t = recordingTransport({ status: 201, bodyText: '{"sid":"SM2"}' });
+        const sender = (0, approval_channel_adapters_1.createTwilioSmsSender)({
+            accountSid: 'AC123',
+            authToken: 'tok',
+            from: 'MGabc123',
+            transport: t.transport,
+        });
+        await sender.send({ to: '+15553334444', body: 'x' });
+        const form = new URLSearchParams(t.calls[0].body ?? '');
+        assert.equal(form.get('MessagingServiceSid'), 'MGabc123');
+        assert.equal(form.get('From'), null);
+    });
+    (0, node_test_1.it)('non-2xx response surfaces as delivered=false with status + body', async () => {
+        const t = recordingTransport({ status: 400, bodyText: '{"code":21211}' });
+        const sender = (0, approval_channel_adapters_1.createTwilioSmsSender)({
+            accountSid: 'AC123',
+            authToken: 'tok',
+            from: '+15551112222',
+            transport: t.transport,
+        });
+        const res = await sender.send({ to: 'bad', body: 'x' });
+        assert.equal(res.ok, false);
+        assert.match(res.error ?? '', /status=400/);
+    });
+    (0, node_test_1.it)('missing accountSid / authToken / from throws on construction', () => {
+        assert.throws(() => (0, approval_channel_adapters_1.createTwilioSmsSender)({ accountSid: '', authToken: 't', from: '+1' }), /accountSid.*required/i);
+        assert.throws(() => (0, approval_channel_adapters_1.createTwilioSmsSender)({ accountSid: 'AC', authToken: '', from: '+1' }), /authToken.*required/i);
+        assert.throws(() => (0, approval_channel_adapters_1.createTwilioSmsSender)({ accountSid: 'AC', authToken: 't', from: '' }), /from.*required/i);
+    });
+});
+(0, node_test_1.describe)('Adapters integrate with ApprovalChannelDispatcher', () => {
+    (0, node_test_1.it)('end-to-end: dispatcher -> Resend adapter -> outcome.delivered=true', async () => {
+        const { ApprovalChannelDispatcher } = await Promise.resolve().then(() => __importStar(require('./approval-notifications.js')));
+        const t = recordingTransport();
+        const dispatcher = new ApprovalChannelDispatcher({
+            emailSender: (0, approval_channel_adapters_1.createResendEmailSender)({ apiKey: 're_sk', transport: t.transport }),
+        });
+        const outcomes = await dispatcher.dispatch({
+            ticketId: 'tic-1',
+            orgId: 'org-x',
+            agentId: 'agent-1',
+            toolName: 'Bash',
+            riskLevel: 'high',
+            summary: 'destructive shell call',
+            approveUrl: 'https://my-cc.io/approve/tic-1',
+            denyUrl: 'https://my-cc.io/deny/tic-1',
+            slaDeadline: '2026-05-12T15:00:00.000Z',
+        }, [
+            {
+                reviewerId: 'r1',
+                name: 'Reviewer',
+                email: 'r1@example.com',
+                channels: ['email'],
+            },
+        ]);
+        assert.equal(outcomes[0].delivered, true);
+        assert.equal(outcomes[0].providerMessageId, 'msg_1');
+        assert.equal(t.calls.length, 1);
+    });
+});
+//# sourceMappingURL=approval-channel-adapters.test.js.map

package/dist/governance/approval-channel-adapters.test.js.map

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

package/dist/governance/approval-gate-enforcer.d.ts

@@ -0,0 +1,224 @@
+/**
+ * ApprovalGateEnforcer -- Mandatory approval gates with per-class policy.
+ *
+ * Categorises actions into six explicit approval classes (destructive,
+ * irreversible, financial, data-export, network-egress, secret-rotation),
+ * applies per-class disposition policy (requires-approval /
+ * auto-approve-low-risk / always-deny), and blocks synchronously until a
+ * human approves, rejects, or the configured timeout elapses.
+ *
+ * RELATIONSHIP TO PR #24 (feat/p3-t1-autonomy-spectrum):
+ *   PR #24 ships AutonomySpectrumEnforcer (Level 0-4). At Level 4 certain
+ *   action classes are routed to an approval queue via `guardAction()` which
+ *   returns `{ decision: 'approval-required', approvalRequestId }`. The
+ *   Level 4 gate intentionally does NOT own the queue lifecycle -- it only
+ *   names the classes that need gating.
+ *
+ *   THIS MODULE owns the gate lifecycle:
+ *     - Explicit class definitions with rationale (action-classes.ts)
+ *     - Per-class disposition config (ClassPolicyMap)
+ *     - Synchronous blocking via Promise + polling (no busy-spin)
+ *     - Audit chain writes on every decision
+ *     - Replay protection in the store (PT-APPROVAL-3)
+ *     - Empty packBinding[] guard (PT-APPROVAL-1)
+ *     - Config validation at construction (PT-APPROVAL-2)
+ *     - Authorised-approver list enforcement (PT-APPROVAL-4)
+ *
+ * HOOK POSITION:
+ *   The gate should fire AFTER blast-radius enforcement (PR #42) but BEFORE
+ *   action-isolation (PR #29). Rationale: blast-radius has already confirmed
+ *   the action is within scope; the gate then checks whether it needs human
+ *   sign-off before it executes. Action-isolation runs post-approval to
+ *   sandbox the approved execution. As of main HEAD, PRs #42 and #29 are
+ *   not yet merged, so this ordering is documented here but has no direct
+ *   code coupling to either module.
+ *
+ * TIMEOUT SEMANTICS:
+ *   On timeout, the safe default is DENY. Operators may override per-class
+ *   via `ActionClassPolicy.timeoutMs`. There is no "allow on timeout" option.
+ *
+ * COMPLIANCE BINDINGS:
+ *   HIPAA 164.308(a)(1): Security management process
+ *   HIPAA 164.308(a)(3): Workforce authorisation and supervision
+ *   HIPAA 164.312(a)(1): Access controls
+ *   SOC 2 CC6.1: Logical access restrictions
+ *   GDPR Art. 22: Automated decision-making
+ *   PCI DSS Req 7: Restrict access by business need
+ *   NIST 800-53 AC-3: Access enforcement
+ *   ISO 27001 A.9.4.1: Information access restriction
+ *
+ * @connexum/ai-governance P3-T2
+ */
+import { ActionClass, ActionClassPolicy, ClassPolicyMap, ConfigValidationError } from './action-classes';
+import { ApprovalQueueStore, PendingApproval } from './approval-queue-store';
+export { ActionClass, ConfigValidationError };
+export type { ActionClassPolicy, ClassPolicyMap };
+export type { PendingApproval };
+/** Context describing the action that triggered the gate. */
+export interface ActionContext {
+    /** The action class governing this action. */
+    actionClass: ActionClass;
+    /** Human-readable description of what the action does. */
+    description: string;
+    /** Agent ID or context identifier initiating the action. */
+    initiator: string;
+    /**
+     * Compliance pack IDs governing this action.
+     * Must be non-empty (PT-APPROVAL-1).
+     */
+    packBinding: string[];
+    /**
+     * Optional tenant ID for multi-tenant audit entries.
+     * Used in audit log entries but not in enforcement logic.
+     */
+    tenantId?: string;
+}
+/** Result returned by `enforce()`. */
+export interface EnforcementResult {
+    /** Whether the action is permitted to proceed. */
+    allowed: boolean;
+    /**
+     * How the gate reached its decision:
+     *   approved             -- A human approved in time.
+     *   rejected             -- A human or policy denied the action.
+     *   timed-out            -- No decision before the class timeout; default deny.
+     *   auto-approved        -- Class disposition is auto-approve-low-risk.
+     *   always-denied        -- Class disposition is always-deny.
+     *   unauthorized-approver -- The approver is not in allowedApprovers.
+     */
+    outcome: 'approved' | 'rejected' | 'timed-out' | 'auto-approved' | 'always-denied' | 'unauthorized-approver';
+    /** The approvalId assigned, when a queue entry was created. */
+    approvalId?: string;
+    /** The approver identity, when a human decision was made. */
+    approverId?: string;
+    /** The human-supplied reason for the decision. */
+    reason?: string;
+    /** ISO timestamp of the gate decision. */
+    decidedAt: string;
+}
+export interface ApprovalGateEnforcerConfig {
+    /**
+     * Per-class policy map. Defaults to `buildDefaultClassPolicies()`
+     * (all classes require-approval) when omitted.
+     *
+     * PT-APPROVAL-2: validated at construction; throws ConfigValidationError
+     * on invalid timeout, unknown disposition, or missing class.
+     */
+    classPolicies?: Partial<ClassPolicyMap>;
+    /**
+     * Enforcer-level default timeout in ms when a class policy does not
+     * specify one. Defaults to 600_000 (10 minutes).
+     */
+    defaultTimeoutMs?: number;
+    /**
+     * Polling interval in ms used by the synchronous-blocking `enforce()`
+     * call to check for a decision. Defaults to 200 ms.
+     *
+     * Lower values reduce latency but increase CPU usage. In tests, use
+     * values as low as 10 ms for responsiveness.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Optional ApprovalQueueStore implementation.
+     * Defaults to InMemoryApprovalQueueStore.
+     */
+    store?: ApprovalQueueStore;
+    /**
+     * Optional audit log directory. When set, every gate decision is
+     * appended to `<auditDir>/approval-gate-audit.jsonl` in addition to
+     * whatever event-bus is wired.
+     */
+    auditDir?: string;
+}
+export declare class ApprovalGateEnforcer {
+    private readonly cfg;
+    /**
+     * PT-APPROVAL-2: constructor validates the class policy map.
+     * Throws ConfigValidationError immediately on invalid configuration.
+     */
+    constructor(config?: ApprovalGateEnforcerConfig);
+    /**
+     * Enforce the approval gate for a given action.
+     *
+     * Behaviour by disposition:
+     *   auto-approve-low-risk  -- Returns immediately with allowed=true.
+     *   always-deny            -- Returns immediately with allowed=false.
+     *   requires-approval      -- Blocks (polls) until approved/rejected/timeout.
+     *
+     * PT-APPROVAL-1: empty packBinding throws UnboundDataError before any
+     * queue insertion.
+     *
+     * @param actionContext  Describes the action and its governance context.
+     * @returns EnforcementResult promise that resolves when a decision is made.
+     */
+    enforce(actionContext: ActionContext): Promise<EnforcementResult>;
+    /**
+     * Submit an approval decision for a pending gate.
+     *
+     * PT-APPROVAL-3: If the approvalId has already been decided, this call
+     * is a silent no-op (the store's replay protection handles it).
+     *
+     * PT-APPROVAL-4: If the class policy specifies `allowedApprovers` and
+     * `approverId` is not in that list, the approval is rejected and an
+     * APPROVAL_GATE_UNAUTHORIZED_APPROVER audit entry is written.
+     *
+     * @param approvalId  The ID returned by `enforce()`.
+     * @param approverId  Identity of the human approver.
+     * @param reason      Optional human-readable reason.
+     */
+    submitApproval(approvalId: string, approverId: string, reason?: string): void;
+    /**
+     * Submit a rejection decision for a pending gate.
+     *
+     * PT-APPROVAL-3: If the approvalId has already been decided, this call
+     * is a silent no-op.
+     *
+     * @param approvalId  The ID returned by `enforce()`.
+     * @param approverId  Identity of the rejecting human.
+     * @param reason      Optional human-readable reason.
+     */
+    submitRejection(approvalId: string, approverId: string, reason?: string): void;
+    /**
+     * Return all currently pending approvals.
+     * Optionally filter by action class or initiator.
+     * Used by the dashboard / UI to display the approval queue.
+     */
+    getPendingApprovals(filter?: {
+        actionClass?: ActionClass;
+        initiator?: string;
+    }): PendingApproval[];
+    /**
+     * Return a snapshot of all approvals (pending and decided).
+     * Useful for audit queries.
+     */
+    getAllApprovals(): PendingApproval[];
+    /**
+     * Retrieve a single approval by ID.
+     */
+    getApproval(approvalId: string): PendingApproval | null;
+    /**
+     * Poll the store until the approval is no longer 'pending' or timeout elapses.
+     *
+     * Uses setInterval-based polling (no busy-spin per AIAG-013).
+     * On timeout, calls `store.timeout()` to mark the record, then resolves.
+     */
+    private waitForDecision;
+    /**
+     * PT-APPROVAL-4: Returns true if the approverId is permitted to approve
+     * for the given action class. Always returns true when no allowedApprovers
+     * constraint is configured for that class.
+     */
+    private isAuthorizedApprover;
+    /**
+     * Append an audit entry to the JSONL file when auditDir is configured.
+     * Errors are logged to stderr but never thrown -- the gate must not fail
+     * because the audit writer has a transient I/O error.
+     */
+    private writeAudit;
+}
+/**
+ * Generate a unique approval ID in the same format used by the enforcer.
+ * Exposed for testing and integration code that needs to pre-generate IDs.
+ */
+export declare function generateApprovalId(): string;
+//# sourceMappingURL=approval-gate-enforcer.d.ts.map

package/dist/governance/approval-gate-enforcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-gate-enforcer.d.ts","sourceRoot":"","sources":["../../src/governance/approval-gate-enforcer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAMH,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,cAAc,EAGd,qBAAqB,EACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAElB,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,CAAC;AAMhC,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,WAAW,EAAE,WAAW,CAAC;IACzB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;;;OAQG;IACH,OAAO,EACH,UAAU,GACV,UAAU,GACV,WAAW,GACX,eAAe,GACf,eAAe,GACf,uBAAuB,CAAC;IAC5B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,0BAA0B;IACzC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAExC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAsCD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IAErC;;;OAGG;gBACS,MAAM,GAAE,0BAA+B;IA0CnD;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqJvE;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IA6B7E;;;;;;;;;OASG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAU9E;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,eAAe,EAAE;IAIlG;;;OAGG;IACH,eAAe,IAAI,eAAe,EAAE;IAIpC;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAQvD;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA0CvB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAWnB;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}