@irisrun/auth 0.1.0

package/dist/approval.d.ts

@@ -0,0 +1,22 @@
+import type { Principal, GovernedAction } from "./identity.js";
+import type { ApprovalPolicy } from "./policy.js";
+export type RawApproval = {
+    principal: Principal;
+    intent: "approve" | "deny";
+};
+export type GovernedApproval = {
+    approved: boolean;
+    intent: "approve" | "deny";
+    authorized: boolean;
+    principal: Principal;
+    action: GovernedAction;
+    reason: string;
+};
+/** Combine a human decision with the policy. Pure. Tool runs only on
+ *  approve + authorized; an unauthorized "approve" yields approved:false. */
+export declare function decideApproval(input: {
+    policy: ApprovalPolicy;
+    principal: Principal;
+    intent: "approve" | "deny";
+    action: GovernedAction;
+}): GovernedApproval;

package/dist/approval.js

@@ -0,0 +1,20 @@
+import { authorize } from "./policy.js";
+/** Combine a human decision with the policy. Pure. Tool runs only on
+ *  approve + authorized; an unauthorized "approve" yields approved:false. */
+export function decideApproval(input) {
+    const { policy, principal, intent, action } = input;
+    const auth = authorize(policy, principal, action);
+    const authorized = auth.permit;
+    const approved = intent === "approve" && authorized;
+    let reason;
+    if (intent === "deny") {
+        reason = `denied by '${principal.id}'`;
+    }
+    else if (authorized) {
+        reason = `approved by '${principal.id}' (${auth.reason})`;
+    }
+    else {
+        reason = `unauthorized: ${auth.reason}`;
+    }
+    return { approved, intent, authorized, principal, action, reason };
+}

package/dist/audit.d.ts

@@ -0,0 +1,25 @@
+import type { SessionInspection } from "@irisrun/inspect";
+import type { StateStore } from "@irisrun/core";
+import type { Principal } from "./identity.js";
+export type ApprovalAuditEntry = {
+    seq: number;
+    ts: number;
+    callId: string;
+    tool: string | null;
+    principal: Principal | null;
+    intent: "approve" | "deny" | null;
+    approved: boolean;
+    authorized: boolean | null;
+    reason: string | null;
+};
+/** Project the approval trail from an already-inspected session. NOTE: an inspection
+ *  covers only the post-snapshot tail (see the RETENTION CONTRACT above); for a
+ *  complete trail prefer `auditApprovals`. Pure. */
+export declare function approvalAudit(inspection: SessionInspection): ApprovalAuditEntry[];
+/** Read the FULL retained journal (from seq 0) and project the approval trail. This
+ *  is the complete-trail entry point: it sees every approval still retained, including
+ *  ones before a snapshot boundary (which `inspectSession` would omit). Completeness
+ *  across truncation requires retained history (see the RETENTION CONTRACT above). */
+export declare function auditApprovals(store: StateStore, sessionId: string): Promise<ApprovalAuditEntry[]>;
+/** Deterministic one-line-per-entry rendering of an approval trail. */
+export declare function renderApprovalAudit(entries: ApprovalAuditEntry[]): string;

package/dist/audit.js

@@ -0,0 +1,101 @@
+// The journaled approval audit trail (roadmap P1-5, done-when #2). Pure read over a
+// recorded session: every governed (or legacy) approval is already a journaled
+// `signal_recv` effect result, so the audit is a projection of the journal — nothing
+// new is stored.
+//
+// RETENTION CONTRACT (important): the trail is only as complete as the RETAINED
+// journal. The engine snapshots and TRUNCATES the journal past each snapshot unless a
+// turn runs with `keepHistory: true` (@irisrun/core engine.ts). So:
+//   • `auditApprovals` reads the FULL retained journal (from seq 0) — it sees every
+//     approval still on disk, INCLUDING ones before a snapshot boundary. For a
+//     COMPLETE compliance trail across a long session, retain history (run governed
+//     turns with keepHistory — see the CLI `keepHistory` option); a session that
+//     truncates keeps only the surviving tail, and truncated approvals are gone.
+//   • `approvalAudit(inspection)` projects whatever inspection it is given. Note that
+//     `inspectSession` reads only the POST-snapshot tail, so it OMITS approvals before
+//     the snapshot boundary even when history is retained — prefer `auditApprovals`
+//     for a complete trail.
+import { inspectSession } from "@irisrun/inspect";
+import { decode } from "@irisrun/core";
+const HITL_PREFIX = "hitl:";
+function asObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+}
+function asPrincipal(v) {
+    const o = v === undefined ? null : asObject(v);
+    return o && typeof o.id === "string" ? o : null;
+}
+/** Project an ordered approval trail from a set of journal rows. Pure. */
+function projectApprovals(rows) {
+    // 1) hitl signal_recv intents → callId, keyed by effectId for the result join.
+    const callIdByEffect = new Map();
+    for (const r of rows) {
+        if (r.kind !== "effect_intent")
+            continue;
+        const p = asObject(r.detail);
+        if (!p || p.effectKind !== "signal_recv" || typeof p.effectId !== "string")
+            continue;
+        const req = asObject(p.request);
+        const name = req && typeof req.name === "string" ? req.name : null;
+        if (name && name.startsWith(HITL_PREFIX))
+            callIdByEffect.set(p.effectId, name.slice(HITL_PREFIX.length));
+    }
+    // 2) project each matching effect_result's value (governed OR legacy bare {approved}).
+    const entries = [];
+    for (const r of rows) {
+        if (r.kind !== "effect_result")
+            continue;
+        const p = asObject(r.detail);
+        if (!p || typeof p.effectId !== "string" || !callIdByEffect.has(p.effectId))
+            continue;
+        const callId = callIdByEffect.get(p.effectId);
+        const outcome = asObject(p.outcome);
+        const ok = outcome ? outcome.ok === true : false;
+        const v = ok && outcome ? asObject(outcome.value) : null;
+        const action = v ? asObject(v.action) : null;
+        entries.push({
+            seq: r.seq,
+            ts: r.ts,
+            callId,
+            tool: action && typeof action.name === "string" ? action.name : null,
+            principal: v ? asPrincipal(v.principal) : null,
+            intent: v && (v.intent === "approve" || v.intent === "deny") ? v.intent : null,
+            approved: v ? v.approved === true : false,
+            authorized: v && typeof v.authorized === "boolean" ? v.authorized : null,
+            reason: v && typeof v.reason === "string" ? v.reason : ok ? null : "effect failed",
+        });
+    }
+    // Records arrive in journal order; sort defensively so the trail is seq-ordered.
+    entries.sort((a, b) => a.seq - b.seq);
+    return entries;
+}
+/** Project the approval trail from an already-inspected session. NOTE: an inspection
+ *  covers only the post-snapshot tail (see the RETENTION CONTRACT above); for a
+ *  complete trail prefer `auditApprovals`. Pure. */
+export function approvalAudit(inspection) {
+    return projectApprovals(inspection.records);
+}
+/** Read the FULL retained journal (from seq 0) and project the approval trail. This
+ *  is the complete-trail entry point: it sees every approval still retained, including
+ *  ones before a snapshot boundary (which `inspectSession` would omit). Completeness
+ *  across truncation requires retained history (see the RETENTION CONTRACT above). */
+export async function auditApprovals(store, sessionId) {
+    const rows = await store.readJournal(sessionId, 0);
+    const records = rows.map((row) => {
+        const rec = decode(row.bytes);
+        return { seq: rec.seq, ts: rec.ts, kind: rec.kind, detail: rec.payload };
+    });
+    return projectApprovals(records);
+}
+/** Deterministic one-line-per-entry rendering of an approval trail. */
+export function renderApprovalAudit(entries) {
+    if (entries.length === 0)
+        return "no approvals recorded";
+    return entries
+        .map((e) => {
+        const who = e.principal ? e.principal.id : "—";
+        const verdict = e.approved ? "APPROVED" : "skipped";
+        return `#${e.seq} ${e.callId} ${e.tool ?? "?"} — ${verdict} by ${who} (intent:${e.intent ?? "?"}, authorized:${e.authorized ?? "?"})`;
+    })
+        .join("\n");
+}

package/dist/identity.d.ts

@@ -0,0 +1,8 @@
+export type Principal = {
+    id: string;
+    roles?: string[];
+};
+export type GovernedAction = {
+    name: string;
+    callId: string;
+};

package/dist/identity.js

@@ -0,0 +1,5 @@
+// Domain nouns for governance. Json-rideable → `type` aliases, NOT interfaces:
+// these values ride a journaled `Json` (the signal_recv approval value), and an
+// interface does not get the implicit `[k: string]: Json` index signature an object
+// literal needs to be assignable to Json (convention: @irisrun/core harness/seams.ts:1-11).
+export {};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export declare const PACKAGE = "@irisrun/auth";
+export type { Principal, GovernedAction } from "./identity.js";
+export { authorize } from "./policy.js";
+export type { ApprovalPolicy, ApprovalRule, AuthDecision } from "./policy.js";
+export { decideApproval } from "./approval.js";
+export type { RawApproval, GovernedApproval } from "./approval.js";
+export { createApprovalInbox, makeGovernedApprovalPerformer } from "./performer.js";
+export type { ApprovalInbox } from "./performer.js";
+export { approvalAudit, auditApprovals, renderApprovalAudit } from "./audit.js";
+export type { ApprovalAuditEntry } from "./audit.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+// @irisrun/auth — the governance layer (roadmap P1-5). Identity + a declarative
+// who-may-approve authorization policy on the existing HITL approval gate, plus a
+// journaled, queryable approval audit trail. Pure: the governed decision rides the
+// existing journaled `signal_recv` effect result (the kernel's `foldApproval` reads
+// only `approved===true`), so governance enriches that value with ZERO kernel change.
+export const PACKAGE = "@irisrun/auth";
+// policy.ts — who-may-approve authorization (done-when #1)
+export { authorize } from "./policy.js";
+// approval.ts — combine human intent + policy into the journaled value
+export { decideApproval } from "./approval.js";
+// performer.ts — the first real governed signal_recv performer + the approval inbox
+export { createApprovalInbox, makeGovernedApprovalPerformer } from "./performer.js";
+// audit.ts — the journaled, queryable approval trail (done-when #2)
+export { approvalAudit, auditApprovals, renderApprovalAudit } from "./audit.js";

package/dist/performer.d.ts

@@ -0,0 +1,17 @@
+import type { Performer } from "@irisrun/core";
+import type { GovernedAction } from "./identity.js";
+import type { RawApproval } from "./approval.js";
+import type { ApprovalPolicy } from "./policy.js";
+export interface ApprovalInbox {
+    submit(action: GovernedAction, decision: RawApproval): void;
+    get(callId: string): {
+        action: GovernedAction;
+        decision: RawApproval;
+    } | undefined;
+}
+export declare function createApprovalInbox(): ApprovalInbox;
+/** Build the governed `signal_recv` performer for a policy + inbox. */
+export declare function makeGovernedApprovalPerformer(opts: {
+    policy: ApprovalPolicy;
+    inbox: ApprovalInbox;
+}): Performer;

package/dist/performer.js

@@ -0,0 +1,52 @@
+import { decideApproval } from "./approval.js";
+const HITL_PREFIX = "hitl:";
+export function createApprovalInbox() {
+    const decisions = new Map();
+    return {
+        submit(action, decision) {
+            decisions.set(action.callId, { action, decision });
+        },
+        get(callId) {
+            return decisions.get(callId);
+        },
+    };
+}
+/** Build the governed `signal_recv` performer for a policy + inbox. */
+export function makeGovernedApprovalPerformer(opts) {
+    const { policy, inbox } = opts;
+    return async (request) => {
+        // Outer guard: this performer is folded in `recv_hitl`, a phase with NO failure
+        // handler — ANY throw or {ok:false} is journaled and re-throws forever on replay
+        // (poisons the session). So even an OPERATOR misconfiguration (e.g. a malformed
+        // `policy`) must fail safe, not loud. Per-request input is guarded below; this
+        // catch is the last-resort backstop that keeps the {ok:true} contract absolute.
+        try {
+            // Guard the boundary: the kernel hands `{ name: "hitl:<callId>" }`. Anything else
+            // (a malformed request, a non-HITL signal) fails SAFE, never loud.
+            const name = request !== null && typeof request === "object" && !Array.isArray(request)
+                ? request.name
+                : undefined;
+            if (typeof name !== "string" || !name.startsWith(HITL_PREFIX)) {
+                return { ok: true, value: { approved: false, reason: `governed approval: not a hitl signal (${JSON.stringify(name ?? null)})` } };
+            }
+            const callId = name.slice(HITL_PREFIX.length);
+            const recorded = inbox.get(callId);
+            if (!recorded) {
+                // The decision must be submitted before the resume signal; absent is a wiring
+                // gap, not an error — skip the tool with a clear reason rather than poison.
+                return { ok: true, value: { approved: false, reason: `no approval decision recorded for '${callId}'` } };
+            }
+            const governed = decideApproval({
+                policy,
+                principal: recorded.decision.principal,
+                intent: recorded.decision.intent,
+                action: recorded.action,
+            });
+            return { ok: true, value: governed };
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return { ok: true, value: { approved: false, reason: `governance error (denied for safety): ${message}` } };
+        }
+    };
+}

package/dist/policy.d.ts

@@ -0,0 +1,16 @@
+import type { Principal, GovernedAction } from "./identity.js";
+export type ApprovalRule = {
+    tool?: string;
+    anyOfRoles?: string[];
+    principals?: string[];
+};
+export type ApprovalPolicy = {
+    rules: ApprovalRule[];
+    default?: "deny" | "permit";
+};
+export type AuthDecision = {
+    permit: boolean;
+    reason: string;
+};
+/** Does `principal` may-approve `action` under `policy`? Pure. */
+export declare function authorize(policy: ApprovalPolicy, principal: Principal, action: GovernedAction): AuthDecision;

package/dist/policy.js

@@ -0,0 +1,23 @@
+function toolMatches(rule, action) {
+    return rule.tool === undefined || rule.tool === "*" || rule.tool === action.name;
+}
+/** Does `principal` may-approve `action` under `policy`? Pure. */
+export function authorize(policy, principal, action) {
+    const roles = principal.roles ?? [];
+    for (const rule of policy.rules) {
+        if (!toolMatches(rule, action))
+            continue;
+        const byRole = (rule.anyOfRoles ?? []).some((r) => roles.includes(r));
+        const byId = (rule.principals ?? []).includes(principal.id);
+        if (byRole || byId) {
+            return {
+                permit: true,
+                reason: `granted: '${principal.id}' satisfies a rule for '${action.name}' (by ${byRole ? "role" : "principal id"})`,
+            };
+        }
+    }
+    const fallback = policy.default ?? "deny";
+    return fallback === "permit"
+        ? { permit: true, reason: `default permit: no rule matched '${action.name}'` }
+        : { permit: false, reason: `denied: no rule grants '${principal.id}' approval of '${action.name}'` };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@irisrun/auth",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Iris governance layer — identity + a declarative who-may-approve authorization policy on the existing HITL gate, plus a journaled, queryable approval audit trail. Pure: enriches the journaled signal_recv approval value (zero kernel change). Deps @irisrun/core + @irisrun/inspect only.",
+  "exports": {
+    ".": {
+      "iris-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@irisrun/core": "^0.1.0",
+    "@irisrun/inspect": "^0.1.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xoai/iris.git",
+    "directory": "packages/auth"
+  },
+  "homepage": "https://github.com/xoai/iris#readme",
+  "files": [
+    "dist"
+  ]
+}