@deftai/directive-core 0.87.0 → 0.89.0

package/dist/authz/origin.js

@@ -0,0 +1,64 @@
+/**
+ * Human-origin provenance predicates (#2944).
+ * Self-authored lifecycle / dispatch / xBRIEF state never counts as approval.
+ */
+import { HUMAN_ORIGIN_KINDS, REJECTED_ORIGIN_KINDS, } from "./types.js";
+const HUMAN_SET = new Set(HUMAN_ORIGIN_KINDS);
+const REJECTED_SET = new Set(REJECTED_ORIGIN_KINDS);
+/** True when origin.kind is an accepted human-origin kind. */
+export function isHumanOriginKind(kind) {
+    if (kind === null || kind === undefined)
+        return false;
+    return HUMAN_SET.has(kind.trim().toLowerCase());
+}
+/** True when origin.kind is explicitly agent/self-authored (always reject). */
+export function isRejectedOriginKind(kind) {
+    if (kind === null || kind === undefined)
+        return false;
+    return REJECTED_SET.has(kind.trim().toLowerCase());
+}
+/**
+ * Structural human-origin check for a grant record.
+ * Rejects missing kind, rejected kinds, empty actor, and agent-like actors.
+ */
+export function isHumanOriginGrant(grant) {
+    if (grant === null || grant === undefined)
+        return false;
+    return isHumanOrigin(grant.origin);
+}
+export function isHumanOrigin(origin) {
+    if (origin === null || origin === undefined)
+        return false;
+    const kind = (origin.kind ?? "").trim().toLowerCase();
+    if (kind.length === 0)
+        return false;
+    if (isRejectedOriginKind(kind))
+        return false;
+    if (!isHumanOriginKind(kind))
+        return false;
+    const actor = (origin.actor ?? "").trim().toLowerCase();
+    if (actor.length === 0)
+        return false;
+    // Agent-shaped actor strings are not human provenance even with a human kind stamp.
+    if (actor === "agent" || actor.startsWith("agent:") || actor === "self")
+        return false;
+    return true;
+}
+/**
+ * Reject evidence shapes agents commonly invent as consent:
+ * allocation_context free-text, xBRIEF status, lifecycle flags, dispatch envelopes.
+ * These never independently satisfy an implementation-approval gate.
+ */
+export function evidenceSatisfiesImplementationApproval(evidence) {
+    // Only a validated human-origin grant counts.
+    if (evidence.grant !== undefined && evidence.grant !== null) {
+        return isHumanOriginGrant(evidence.grant);
+    }
+    // Explicit non-grant evidence channels always fail closed for implement gates.
+    void evidence.xbriefStatus;
+    void evidence.allocationContext;
+    void evidence.dispatchEnvelope;
+    void evidence.lifecycleAdvancedBy;
+    return false;
+}
+//# sourceMappingURL=origin.js.map

package/dist/authz/paths.d.ts

@@ -0,0 +1,6 @@
+export declare function authzDir(projectRoot: string): string;
+export declare function authzStatePath(projectRoot: string): string;
+export declare function authzGrantsDir(projectRoot: string): string;
+export declare function authzGrantPath(projectRoot: string, grantId: string): string;
+export declare function authzAuditPath(projectRoot: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/authz/paths.js

@@ -0,0 +1,19 @@
+import { join } from "node:path";
+import { AUTHZ_AUDIT_FILE, AUTHZ_DIR, AUTHZ_GRANTS_DIR, AUTHZ_STATE_FILE } from "./types.js";
+export function authzDir(projectRoot) {
+    return join(projectRoot, ...AUTHZ_DIR.split("/"));
+}
+export function authzStatePath(projectRoot) {
+    return join(authzDir(projectRoot), AUTHZ_STATE_FILE);
+}
+export function authzGrantsDir(projectRoot) {
+    return join(authzDir(projectRoot), AUTHZ_GRANTS_DIR);
+}
+export function authzGrantPath(projectRoot, grantId) {
+    const safe = grantId.replace(/[^a-zA-Z0-9._-]/g, "_");
+    return join(authzGrantsDir(projectRoot), `${safe}.json`);
+}
+export function authzAuditPath(projectRoot) {
+    return join(authzDir(projectRoot), AUTHZ_AUDIT_FILE);
+}
+//# sourceMappingURL=paths.js.map

package/dist/authz/store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Disk store for authz state + grants under `.deft/authz/` (#2944).
+ */
+import { type AuthzAuditRecord, type AuthzState, type GrantOrigin, type HumanOriginGrant, type UatLease } from "./types.js";
+declare function utcIso(now?: Date): string;
+/** Parse a grant JSON object; returns null when structurally unusable. */
+export declare function parseGrant(raw: unknown): HumanOriginGrant | null;
+export declare function parseUatLease(raw: unknown): UatLease | null;
+export declare function parseAuthzState(raw: unknown): AuthzState;
+/**
+ * Load result distinguishes missing state (inactive) from corrupt state
+ * (fail-closed deny-all under UAT posture — #2944 Greptile/SLizard).
+ */
+export type AuthzStateLoad = {
+    readonly ok: true;
+    readonly state: AuthzState;
+    readonly corrupt: false;
+} | {
+    readonly ok: false;
+    readonly state: AuthzState;
+    readonly corrupt: true;
+    readonly reason: string;
+};
+export declare function loadAuthzStateResult(projectRoot: string): AuthzStateLoad;
+export declare function loadAuthzState(projectRoot: string): AuthzState;
+/** Persist single-use grant consumption after an allow decision (#2944). */
+export declare function markGrantUsed(projectRoot: string, grantId: string, now?: Date): HumanOriginGrant | null;
+export declare function saveAuthzState(projectRoot: string, state: AuthzState): void;
+export declare function loadGrant(projectRoot: string, grantId: string): HumanOriginGrant | null;
+export declare function saveGrant(projectRoot: string, grant: HumanOriginGrant): void;
+export declare function listGrants(projectRoot: string): HumanOriginGrant[];
+/**
+ * Active grants: non-revoked, optionally filtered by state.activeGrantIds,
+ * human-origin only (self-authored records stay on disk but do not activate).
+ */
+export declare function listActiveHumanGrants(projectRoot: string, state?: AuthzState, now?: Date): HumanOriginGrant[];
+export declare function appendAuthzAudit(projectRoot: string, record: AuthzAuditRecord): void;
+export declare function mintOperatorOrigin(actor: string, mintedVia: string, now?: Date, eventRef?: string | null): GrantOrigin;
+export { utcIso };
+//# sourceMappingURL=store.d.ts.map

package/dist/authz/store.js

@@ -0,0 +1,317 @@
+/**
+ * Disk store for authz state + grants under `.deft/authz/` (#2944).
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { isHumanOrigin } from "./origin.js";
+import { authzAuditPath, authzGrantPath, authzGrantsDir, authzStatePath } from "./paths.js";
+import { AUTHZ_OPERATIONS, } from "./types.js";
+function utcIso(now) {
+    const dt = now ?? new Date();
+    return dt.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Contained atomic JSON write for authz state/grants (#2980 / Greptile P1).
+ * Containment root is projectRoot (not dirname(target)) so parent-symlink escape fails closed.
+ * Unique random temp names avoid PID-reuse collisions; rename is the atomic publish step.
+ */
+function writeJsonContained(projectRoot, targetPath, payload) {
+    const root = resolve(projectRoot);
+    const abs = resolve(targetPath);
+    // Refuse leaf/parent symlinks on the final path before temp+rename publish.
+    assertWriteTargetSafe(root, abs);
+    const dir = dirname(abs);
+    const tmpBase = `.${basename(abs)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    const tmp = join(dir, tmpBase);
+    try {
+        containedWrite({
+            root,
+            target: tmp,
+            data: `${JSON.stringify(payload, null, 2)}\n`,
+            mode: "create",
+        });
+        renameSync(tmp, abs);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}
+function readString(rec, key) {
+    const v = rec[key];
+    return typeof v === "string" && v.trim().length > 0 ? v.trim() : null;
+}
+function readStringArray(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((x) => typeof x === "string" && x.trim().length > 0);
+}
+function readNumberArray(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((x) => typeof x === "number" && Number.isFinite(x));
+}
+function parseOrigin(raw) {
+    const rec = record(raw);
+    if (rec === null)
+        return null;
+    const kind = readString(rec, "kind");
+    const actor = readString(rec, "actor");
+    const mintedAt = readString(rec, "mintedAt") ?? readString(rec, "minted_at");
+    const mintedVia = readString(rec, "mintedVia") ?? readString(rec, "minted_via") ?? "unknown";
+    if (kind === null || actor === null || mintedAt === null)
+        return null;
+    const eventRef = readString(rec, "eventRef") ?? readString(rec, "event_ref");
+    return { kind, actor, mintedAt, mintedVia, eventRef };
+}
+function parseOperations(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const allowed = new Set(AUTHZ_OPERATIONS);
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== "string")
+            continue;
+        const op = item.trim().toLowerCase();
+        if (allowed.has(op))
+            out.push(op);
+    }
+    return out;
+}
+function parseScope(raw) {
+    const rec = record(raw);
+    if (rec === null)
+        return null;
+    return {
+        planRef: readString(rec, "planRef") ?? readString(rec, "plan_ref") ?? readString(rec, "planHash"),
+        repo: readString(rec, "repo"),
+        branch: readString(rec, "branch"),
+        worktree: readString(rec, "worktree"),
+        surfaces: readStringArray(rec.surfaces),
+        operations: parseOperations(rec.operations),
+        storyIds: readStringArray(rec.storyIds ?? rec.story_ids),
+        issueIds: readNumberArray(rec.issueIds ?? rec.issue_ids),
+        cohortId: readString(rec, "cohortId") ?? readString(rec, "cohort_id"),
+    };
+}
+function parseSemantics(raw) {
+    const rec = record(raw);
+    if (rec === null) {
+        return { expiresAt: null, singleUse: false, usedAt: null, revokedAt: null };
+    }
+    return {
+        expiresAt: readString(rec, "expiresAt") ?? readString(rec, "expires_at"),
+        singleUse: rec.singleUse === true || rec.single_use === true,
+        usedAt: readString(rec, "usedAt") ?? readString(rec, "used_at"),
+        revokedAt: readString(rec, "revokedAt") ?? readString(rec, "revoked_at"),
+    };
+}
+/** Parse a grant JSON object; returns null when structurally unusable. */
+export function parseGrant(raw) {
+    const rec = record(raw);
+    if (rec === null)
+        return null;
+    const id = readString(rec, "id");
+    const origin = parseOrigin(rec.origin);
+    const scope = parseScope(rec.scope);
+    if (id === null || origin === null || scope === null)
+        return null;
+    return {
+        schemaVersion: 1,
+        id,
+        origin,
+        scope,
+        semantics: parseSemantics(rec.semantics),
+    };
+}
+export function parseUatLease(raw) {
+    const rec = record(raw);
+    if (rec === null)
+        return null;
+    const campaignId = readString(rec, "campaignId") ?? readString(rec, "campaign_id");
+    const startedAt = readString(rec, "startedAt") ?? readString(rec, "started_at");
+    const startedBy = parseOrigin(rec.startedBy ?? rec.started_by);
+    if (campaignId === null || startedAt === null || startedBy === null)
+        return null;
+    const active = rec.active === true;
+    return {
+        active,
+        campaignId,
+        startedAt,
+        startedBy,
+        suspendedAt: readString(rec, "suspendedAt") ?? readString(rec, "suspended_at"),
+        note: readString(rec, "note"),
+    };
+}
+export function parseAuthzState(raw) {
+    const rec = record(raw);
+    if (rec === null) {
+        return { schemaVersion: 1, uat: null, activeGrantIds: [] };
+    }
+    const uat = "uat" in rec ? parseUatLease(rec.uat) : null;
+    return {
+        schemaVersion: 1,
+        uat,
+        activeGrantIds: readStringArray(rec.activeGrantIds ?? rec.active_grant_ids),
+    };
+}
+/** Synthetic fail-closed state: active UAT with no human origin (evaluate treats corrupt separately). */
+function corruptFailClosedState() {
+    return {
+        schemaVersion: 1,
+        uat: {
+            active: true,
+            campaignId: "__corrupt_authz_state__",
+            startedAt: "1970-01-01T00:00:00Z",
+            startedBy: {
+                kind: "operator-cli",
+                actor: "system",
+                mintedAt: "1970-01-01T00:00:00Z",
+                mintedVia: "corrupt-state-fail-closed",
+                eventRef: null,
+            },
+            suspendedAt: null,
+            note: "authz state unreadable — fail closed",
+        },
+        activeGrantIds: [],
+    };
+}
+export function loadAuthzStateResult(projectRoot) {
+    const path = authzStatePath(projectRoot);
+    if (!existsSync(path)) {
+        return {
+            ok: true,
+            corrupt: false,
+            state: { schemaVersion: 1, uat: null, activeGrantIds: [] },
+        };
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return { ok: true, corrupt: false, state: parseAuthzState(raw) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            corrupt: true,
+            reason: `authz state unreadable at ${path}: ${String(err)}`,
+            state: corruptFailClosedState(),
+        };
+    }
+}
+export function loadAuthzState(projectRoot) {
+    return loadAuthzStateResult(projectRoot).state;
+}
+/** Persist single-use grant consumption after an allow decision (#2944). */
+export function markGrantUsed(projectRoot, grantId, now = new Date()) {
+    const grant = loadGrant(projectRoot, grantId);
+    if (grant === null)
+        return null;
+    if (!grant.semantics.singleUse)
+        return grant;
+    if (grant.semantics.usedAt !== null)
+        return grant;
+    const used = {
+        ...grant,
+        semantics: {
+            ...grant.semantics,
+            usedAt: utcIso(now),
+        },
+    };
+    saveGrant(projectRoot, used);
+    return used;
+}
+export function saveAuthzState(projectRoot, state) {
+    writeJsonContained(projectRoot, authzStatePath(projectRoot), state);
+}
+export function loadGrant(projectRoot, grantId) {
+    const path = authzGrantPath(projectRoot, grantId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return parseGrant(JSON.parse(readFileSync(path, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveGrant(projectRoot, grant) {
+    writeJsonContained(projectRoot, authzGrantPath(projectRoot, grant.id), grant);
+}
+export function listGrants(projectRoot) {
+    const dir = authzGrantsDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const grant = parseGrant(JSON.parse(readFileSync(join(dir, name), "utf8")));
+            if (grant !== null)
+                out.push(grant);
+        }
+        catch {
+            // skip corrupt grant files
+        }
+    }
+    return out;
+}
+/**
+ * Active grants: non-revoked, optionally filtered by state.activeGrantIds,
+ * human-origin only (self-authored records stay on disk but do not activate).
+ */
+export function listActiveHumanGrants(projectRoot, state = loadAuthzState(projectRoot), now = new Date()) {
+    const all = listGrants(projectRoot);
+    const pin = state.activeGrantIds;
+    const pinSet = pin.length > 0 ? new Set(pin) : null;
+    const nowMs = now.getTime();
+    return all.filter((g) => {
+        if (pinSet !== null && !pinSet.has(g.id))
+            return false;
+        if (g.semantics.revokedAt !== null)
+            return false;
+        if (g.semantics.singleUse && g.semantics.usedAt !== null)
+            return false;
+        if (g.semantics.expiresAt !== null) {
+            const exp = Date.parse(g.semantics.expiresAt);
+            if (!Number.isNaN(exp) && exp <= nowMs)
+                return false;
+        }
+        return isHumanOrigin(g.origin);
+    });
+}
+export function appendAuthzAudit(projectRoot, record) {
+    const root = resolve(projectRoot);
+    const path = authzAuditPath(projectRoot);
+    // #2980 wave B: product write sink routes through containedWrite.
+    containedWrite({
+        root,
+        target: path,
+        data: `${JSON.stringify(record)}\n`,
+        mode: "append",
+    });
+}
+export function mintOperatorOrigin(actor, mintedVia, now, eventRef = null) {
+    return {
+        kind: "operator-cli",
+        actor: actor.trim().length > 0 ? actor.trim() : "operator",
+        mintedAt: utcIso(now),
+        mintedVia,
+        eventRef,
+    };
+}
+export { utcIso };
+//# sourceMappingURL=store.js.map

package/dist/authz/templates.d.ts

@@ -0,0 +1,139 @@
+/**
+ * AFK grant templates (#1095 Wave 4 + #871 Wave 5).
+ *
+ * Templates are **presets** on the Wave 1 mint path only:
+ * they call mintHumanOriginGrant / operator-cli origin.
+ *
+ * ⊗ Do not invent a second authorization SoT under ~/.deft/session-auth
+ *   that agents can self-mint as alternate permission.
+ */
+import type { AuthzOperation, HumanOriginGrant } from "./types.js";
+import { type VerbClassificationTable } from "./verb-classification.js";
+/** Canonical AFK template names for Wave 4 release-class closed verbs. */
+export declare const CLOSED_VERB_TEMPLATE_NAMES: readonly ["release-cut", "release-publish", "release-rollback"];
+export type ClosedVerbTemplateName = (typeof CLOSED_VERB_TEMPLATE_NAMES)[number];
+/** Walk-away finish-loop template (#871 Wave 5) — not a release closed-verb. */
+export declare const FINISH_LOOP_TEMPLATE_NAME: "finish-loop";
+/** All AFK templates accepted by `authz:grant --template`. */
+export declare const AFK_TEMPLATE_NAMES: readonly ["release-cut", "release-publish", "release-rollback", "finish-loop"];
+export type AfkTemplateName = (typeof AFK_TEMPLATE_NAMES)[number];
+/**
+ * AuthzOperation set covered by the finish-loop template.
+ * Release-class ops are explicitly carved out (operator must mint a release-* grant).
+ */
+export declare const FINISH_LOOP_OPERATIONS: readonly AuthzOperation[];
+/** Default AFK window for finish-loop (matches issue #871 walk-away notes). */
+export declare const FINISH_LOOP_DEFAULT_EXPIRY_HOURS = 8;
+export declare function isClosedVerbTemplateName(name: string): name is ClosedVerbTemplateName;
+export declare function isFinishLoopTemplateName(name: string): boolean;
+export declare function isAfkTemplateName(name: string): name is AfkTemplateName;
+export interface MintClosedVerbTemplateInput {
+    readonly projectRoot: string;
+    readonly template: string;
+    /** Version / tag target the template binds into grant.surfaces. */
+    readonly target: string;
+    readonly actor?: string;
+    readonly expiresAt?: string | null;
+    readonly singleUse?: boolean;
+    readonly planRef?: string | null;
+    readonly repo?: string | null;
+    readonly branch?: string | null;
+    readonly now?: Date;
+    readonly classification?: VerbClassificationTable;
+    /** Optional extra mint fields forwarded to mintHumanOriginGrant. */
+    readonly pinActive?: boolean;
+    readonly eventRef?: string | null;
+}
+export interface MintFinishLoopTemplateInput {
+    readonly projectRoot: string;
+    readonly actor?: string;
+    readonly expiresAt?: string | null;
+    readonly singleUse?: boolean;
+    readonly planRef?: string | null;
+    readonly repo?: string | null;
+    readonly branch?: string | null;
+    readonly surfaces?: readonly string[];
+    readonly storyIds?: readonly string[];
+    readonly issueIds?: readonly number[];
+    readonly cohortId?: string | null;
+    readonly now?: Date;
+    readonly pinActive?: boolean;
+    readonly eventRef?: string | null;
+    /** Duration hours when expiresAt omitted (default 8). */
+    readonly durationHours?: number;
+}
+/**
+ * Resolve template → mint input (operations + surfaces). Pure; no I/O.
+ * Always routes operations through Wave 1 AuthzOperation names.
+ */
+export declare function resolveClosedVerbTemplate(input: {
+    readonly template: string;
+    readonly target: string;
+    readonly now?: Date;
+    readonly expiresAt?: string | null;
+    readonly classification?: VerbClassificationTable;
+}): {
+    operations: AuthzOperation[];
+    surfaces: string[];
+    expiresAt: string | null;
+    template: ClosedVerbTemplateName;
+};
+/**
+ * Resolve finish-loop AFK template → mint ops (edit/push/pr/merge). Pure; no I/O.
+ * Does not mint release-class operations.
+ */
+export declare function resolveFinishLoopTemplate(input: {
+    readonly now?: Date;
+    readonly expiresAt?: string | null;
+    readonly durationHours?: number;
+    readonly surfaces?: readonly string[];
+}): {
+    operations: AuthzOperation[];
+    surfaces: string[];
+    expiresAt: string | null;
+    template: typeof FINISH_LOOP_TEMPLATE_NAME;
+};
+/**
+ * Mint a human-origin grant for an AFK closed-verb template.
+ * **Sole mint path:** mintHumanOriginGrant (operator-cli). No session-auth SoT.
+ */
+export declare function mintClosedVerbTemplateGrant(input: MintClosedVerbTemplateInput): HumanOriginGrant;
+/**
+ * Mint a human-origin grant for the walk-away finish-loop template (#871).
+ * Covers edit/push/pr/merge only — never release-cut / release-publish / release-rollback.
+ * **Sole mint path:** mintHumanOriginGrant (operator-cli).
+ */
+export declare function mintFinishLoopTemplateGrant(input: MintFinishLoopTemplateInput): HumanOriginGrant;
+/**
+ * Dispatch AFK template mint by name. Closed-verb templates require target;
+ * finish-loop does not.
+ */
+export declare function mintAfkTemplateGrant(input: {
+    readonly projectRoot: string;
+    readonly template: string;
+    readonly target?: string | null;
+    readonly actor?: string;
+    readonly expiresAt?: string | null;
+    readonly singleUse?: boolean;
+    readonly planRef?: string | null;
+    readonly repo?: string | null;
+    readonly branch?: string | null;
+    readonly surfaces?: readonly string[];
+    readonly storyIds?: readonly string[];
+    readonly issueIds?: readonly number[];
+    readonly cohortId?: string | null;
+    readonly now?: Date;
+    readonly classification?: VerbClassificationTable;
+    readonly pinActive?: boolean;
+    readonly eventRef?: string | null;
+    readonly durationHours?: number;
+}): HumanOriginGrant;
+/**
+ * Assert that authorization for closed verbs must not use an independent
+ * session-auth mint engine. Used by unit tests as a dual-mint guard.
+ */
+export declare function assertNoIndependentSessionAuthMint(): {
+    mintPath: "mintHumanOriginGrant";
+    sessionAuthIsAuthority: false;
+};
+//# sourceMappingURL=templates.d.ts.map