instar 1.3.269 → 1.3.270

package/dist/server/routes.js

@@ -4123,6 +4123,261 @@ export function createRoutes(ctx) {
             samples: ctx.resourceLedger.recentSamples({ sinceMs, limit, source }),
         });
     });
+    // ── Approval-as-Data (docs/specs/AUTONOMOUS-OPERATION-JUDGMENT-AND-APPROVAL-AS-DATA-SPEC.md, Part B / Phase 2) ──
+    // Durable, signed record of every operator approval decision, and the per-class
+    // agreement ratios computed from it. Tracks approvals WHEREVER they occur (a spec
+    // sign-off, a decision approved in chat, …) — operator extension 2026-06-05.
+    //
+    // AUTHORITY INVARIANT: `mode` + `divergences` MUST reflect an EXPLICIT operator
+    // statement (the approve control, or words like "go with your picks" = as-is vs
+    // "change X because Y" = with-change). The agent must NOT infer/self-classify the
+    // operator's intent; an ambiguous/silent decision is NOT recorded. Any row is
+    // operator-correctable (append a row with `corrects` set). Read paths never gate.
+    // Record an approval decision. The caller passes operator-sourced mode+divergences.
+    router.post('/approvals', (req, res) => {
+        if (!ctx.approvalLedger) {
+            res.status(503).json({ error: 'approval ledger unavailable (no stateDir or init failed)' });
+            return;
+        }
+        const b = req.body ?? {};
+        if (typeof b.subject !== 'string' || !b.subject.trim()) {
+            res.status(400).json({ error: 'subject is required' });
+            return;
+        }
+        if (typeof b.decisionClass !== 'string' || !b.decisionClass.trim()) {
+            res.status(400).json({ error: 'decisionClass is required' });
+            return;
+        }
+        try {
+            const row = ctx.approvalLedger.recordApproval({
+                subject: b.subject,
+                decisionClass: b.decisionClass,
+                surface: b.surface ?? 'chat',
+                approver: typeof b.approver === 'string' && b.approver ? b.approver : 'justin',
+                mode: b.mode,
+                divergences: Array.isArray(b.divergences) ? b.divergences : undefined,
+                reviewIterations: typeof b.reviewIterations === 'number' ? b.reviewIterations : undefined,
+                commitSha: typeof b.commitSha === 'string' ? b.commitSha : undefined,
+                evidenceRef: typeof b.evidenceRef === 'string' ? b.evidenceRef : undefined,
+                corrects: typeof b.corrects === 'string' ? b.corrects : undefined,
+                decidedAt: typeof b.decidedAt === 'string' ? b.decidedAt : undefined,
+            });
+            res.status(201).json({ recorded: true, row });
+        }
+        catch (err) {
+            // The store throws on an internally-inconsistent row (e.g. as-is WITH a
+            // divergence, or a change WITHOUT one) — that's a 400, not a 500.
+            res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    // Per-class agreement summary + an overall surface breakdown. Read-only; never gates.
+    router.get('/approvals/summary', (_req, res) => {
+        if (!ctx.approvalLedger) {
+            res.status(503).json({ error: 'approval ledger unavailable (no stateDir or init failed)' });
+            return;
+        }
+        const classes = ctx.approvalLedger.summarize();
+        const rows = ctx.approvalLedger.all();
+        const bySurface = {};
+        for (const r of rows) {
+            const s = (bySurface[r.surface] ??= { total: 0, approvedAsIs: 0 });
+            s.total++;
+            if (r.mode === 'approved-as-is')
+                s.approvedAsIs++;
+        }
+        res.json({
+            total: rows.length,
+            classes,
+            bySurface,
+            note: 'Read-only. The ratio is a SIGNAL; auto-approval (Phase 3) routes through a full-context authority, not the arithmetic.',
+        });
+    });
+    // List recorded rows, newest-first (paginated; ?limit= / ?decisionClass= / ?surface=).
+    router.get('/approvals', (req, res) => {
+        if (!ctx.approvalLedger) {
+            res.status(503).json({ error: 'approval ledger unavailable (no stateDir or init failed)' });
+            return;
+        }
+        let limit = 100;
+        if (typeof req.query.limit === 'string' && /^\d+$/.test(req.query.limit)) {
+            const n = Number(req.query.limit);
+            if (n > 0 && n <= 1000)
+                limit = n;
+        }
+        const decisionClass = typeof req.query.decisionClass === 'string' ? req.query.decisionClass : undefined;
+        const surface = typeof req.query.surface === 'string' ? req.query.surface : undefined;
+        let rows = ctx.approvalLedger.all();
+        if (decisionClass)
+            rows = rows.filter((r) => r.decisionClass === decisionClass);
+        if (surface)
+            rows = rows.filter((r) => r.surface === surface);
+        const recent = rows.slice(-limit).reverse();
+        res.json({ count: recent.length, total: rows.length, rows: recent });
+    });
+    // ── Coordination Mandate (docs/specs/coordination-mandate.md §4) ──
+    // Deny-by-default enforcement for autonomous A2A authority. The mandate (a
+    // human-authored, signed policy) is the AUTHORIZER — never the agent. Justin's
+    // resolved decisions (A/A/B, 2026-06-05): issuance + revocation are PIN-gated
+    // (the human-authenticated dashboard surface — an agent's Bearer token CANNOT
+    // issue/revoke); the first mandate carries only exchange-read-credential +
+    // sign-code-review; execute-cutover is not delegated (the flip stays human).
+    //
+    // PIN verification mirrors /dashboard/unlock: sha256 + timingSafeEqual + a
+    // per-IP attempt limit. Read paths + /mandate/evaluate are Bearer-gated.
+    const mandatePinAttempts = new Map();
+    const MANDATE_PIN_MAX_ATTEMPTS = 5;
+    const MANDATE_PIN_WINDOW_MS = 5 * 60 * 1000;
+    /** Verify the operator PIN for mandate issuance/revocation. Returns an error
+     *  string (already sent) or null when the PIN is valid. */
+    function checkMandatePin(req, res) {
+        if (!ctx.config.dashboardPin) {
+            res.status(503).json({ error: 'PIN authentication not available (no dashboardPin configured)' });
+            return false;
+        }
+        const ip = req.ip || req.socket?.remoteAddress || 'unknown';
+        const now = Date.now();
+        let entry = mandatePinAttempts.get(ip);
+        if (entry && now > entry.resetAt) {
+            mandatePinAttempts.delete(ip);
+            entry = undefined;
+        }
+        if (entry && entry.count >= MANDATE_PIN_MAX_ATTEMPTS) {
+            res.status(429).json({ error: 'Too many attempts. Try again later.' });
+            return false;
+        }
+        const pin = (req.body ?? {}).pin;
+        if (!pin || typeof pin !== 'string') {
+            res.status(403).json({ error: 'Operator PIN required — mandate issuance/revocation is a human action, not an agent action' });
+            return false;
+        }
+        const ha = createHash('sha256').update(pin).digest();
+        const hb = createHash('sha256').update(ctx.config.dashboardPin).digest();
+        if (ha.length !== hb.length || !timingSafeEqual(ha, hb)) {
+            if (!entry) {
+                entry = { count: 0, resetAt: now + MANDATE_PIN_WINDOW_MS };
+                mandatePinAttempts.set(ip, entry);
+            }
+            entry.count++;
+            res.status(403).json({ error: 'Incorrect PIN', attemptsRemaining: MANDATE_PIN_MAX_ATTEMPTS - entry.count });
+            return false;
+        }
+        return true;
+    }
+    // Evaluate an action against a mandate (the enforcement consumption point).
+    // Every call — allow AND deny — lands in the hash-chained audit.
+    router.post('/mandate/evaluate', (req, res) => {
+        if (!ctx.coordination) {
+            res.status(503).json({ error: 'coordination mandate engine unavailable (no stateDir or init failed)' });
+            return;
+        }
+        const b = req.body ?? {};
+        if (typeof b.action !== 'string' || !b.action || typeof b.agentFp !== 'string' || !b.agentFp || typeof b.mandateId !== 'string' || !b.mandateId) {
+            res.status(400).json({ error: 'action, agentFp, and mandateId are required' });
+            return;
+        }
+        const result = ctx.coordination.gate.evaluate({
+            action: b.action,
+            params: (b.params && typeof b.params === 'object') ? b.params : {},
+            agentFp: b.agentFp,
+            mandateId: b.mandateId,
+        });
+        res.json({ decision: result.decision, reason: result.reason, conditionResult: result.conditionResult });
+    });
+    // Read-only audit trail + chain integrity. MUST be registered before /mandate/:id.
+    router.get('/mandate/audit', (req, res) => {
+        if (!ctx.coordination) {
+            res.status(503).json({ error: 'coordination mandate engine unavailable (no stateDir or init failed)' });
+            return;
+        }
+        let limit = 100;
+        if (typeof req.query.limit === 'string' && /^\d+$/.test(req.query.limit)) {
+            const n = Number(req.query.limit);
+            if (n > 0 && n <= 1000)
+                limit = n;
+        }
+        const all = ctx.coordination.audit.all();
+        res.json({
+            total: all.length,
+            chain: ctx.coordination.audit.verifyChain(),
+            headHash: ctx.coordination.audit.headHash(),
+            entries: all.slice(-limit).reverse(),
+        });
+    });
+    // List mandates (each with its live authorship-verification status). Read-only.
+    router.get('/mandate', (_req, res) => {
+        if (!ctx.coordination) {
+            res.status(503).json({ error: 'coordination mandate engine unavailable (no stateDir or init failed)' });
+            return;
+        }
+        const { store } = ctx.coordination;
+        res.json({
+            mandates: store.list().map((m) => ({ ...m, authorshipValid: store.verifyAuthorship(m) })),
+        });
+    });
+    // One mandate + its verification status. Read-only.
+    router.get('/mandate/:id', (req, res) => {
+        if (!ctx.coordination) {
+            res.status(503).json({ error: 'coordination mandate engine unavailable (no stateDir or init failed)' });
+            return;
+        }
+        const m = ctx.coordination.store.get(req.params.id);
+        if (!m) {
+            res.status(404).json({ error: `mandate "${req.params.id}" not found` });
+            return;
+        }
+        res.json({ mandate: { ...m, authorshipValid: ctx.coordination.store.verifyAuthorship(m) } });
+    });
+    // Issue a mandate — PIN-GATED (decision 2A: the human-authenticated surface).
+    router.post('/mandate/issue', (req, res) => {
+        if (!ctx.coordination) {
+            res.status(503).json({ error: 'coordination mandate engine unavailable (no stateDir or init failed)' });
+            return;
+        }
+        if (!checkMandatePin(req, res))
+            return;
+        const b = req.body ?? {};
+        if (typeof b.scope !== 'string' || !b.scope.trim()) {
+            res.status(400).json({ error: 'scope is required' });
+            return;
+        }
+        if (!Array.isArray(b.agents) || b.agents.length !== 2 || b.agents.some((a) => typeof a !== 'string' || !a)) {
+            res.status(400).json({ error: 'agents must be a pair of two agent fingerprints' });
+            return;
+        }
+        if (!Array.isArray(b.authorities) || b.authorities.length === 0
+            || b.authorities.some((a) => typeof a?.action !== 'string' || !a.action || typeof a?.bounds !== 'object' || a.bounds === null)) {
+            res.status(400).json({ error: 'authorities must be a non-empty array of { action, bounds, requiresCondition? }' });
+            return;
+        }
+        if (typeof b.expiresAt !== 'string' || isNaN(Date.parse(b.expiresAt)) || Date.parse(b.expiresAt) <= Date.now()) {
+            res.status(400).json({ error: 'expiresAt must be a future ISO timestamp (mandates always expire)' });
+            return;
+        }
+        const mandate = ctx.coordination.store.issue({
+            scope: b.scope,
+            agents: [b.agents[0], b.agents[1]],
+            authorities: b.authorities,
+            author: typeof b.author === 'string' && b.author ? b.author : 'justin',
+            expiresAt: b.expiresAt,
+        });
+        res.status(201).json({ issued: true, mandate });
+    });
+    // Revoke a mandate — PIN-GATED (the operator kill switch; checked on every action).
+    router.post('/mandate/:id/revoke', (req, res) => {
+        if (!ctx.coordination) {
+            res.status(503).json({ error: 'coordination mandate engine unavailable (no stateDir or init failed)' });
+            return;
+        }
+        if (!checkMandatePin(req, res))
+            return;
+        const reason = typeof (req.body ?? {}).reason === 'string' && req.body.reason ? req.body.reason : 'operator revocation';
+        const m = ctx.coordination.store.revoke(req.params.id, reason);
+        if (!m) {
+            res.status(404).json({ error: `mandate "${req.params.id}" not found` });
+            return;
+        }
+        res.json({ revoked: true, mandate: m });
+    });
     // ── Parallel-Work Awareness (docs/specs/parallel-activity-coherence.md, Phase A) ──
     // Read-only cross-topic index: every topic with intent state + its current focus +
     // high-specificity tags + whether a session is live on it. Signal-only; never gates.