@deftai/directive-core 0.99.0 → 0.101.0

package/dist/authz/decompose-apply.js

@@ -0,0 +1,377 @@
+/**
+ * Human-origin structural apply gate for scope:decompose (#3239 / epic #3237 Q2).
+ *
+ * Apply requires a human-origin grant bound to:
+ *   project root identity (worktree and/or repo), parent path, draft/target path,
+ *   SHA-256 of exact draft bytes, and op scope.decompose.apply.structural.
+ *
+ * --check stays ungated (caller responsibility). Missing / expired / mismatched /
+ * agent-origin grants fail closed before any child story writes.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { mintHumanOriginGrant } from "./actions.js";
+import { evidenceSatisfiesImplementationApproval, isHumanOriginGrant, isRejectedOriginKind, } from "./origin.js";
+import { listGrants } from "./store.js";
+import { SCOPE_DECOMPOSE_APPLY_STRUCTURAL, } from "./types.js";
+/** SHA-256 hex of a buffer or utf8 string. */
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/** SHA-256 hex of file bytes at path (exact on-disk digest). */
+export function sha256FileHex(path) {
+    return sha256Hex(readFileSync(path));
+}
+/**
+ * Quote a CLI token for operator copy-paste when it has whitespace or shell
+ * metacharacters (Greptile #3291 / PR #3300). Safe bare tokens stay unquoted
+ * so deny-reason mint hints match the common path shape.
+ *
+ * Single quotes keep `$()`, backticks, and `!` inert. Apostrophe escape differs
+ * by shell: POSIX uses `'\''`; PowerShell uses `''`. Callers that need both
+ * pass dialect `"posix"` or `"pwsh"`. Does not rewrite path bytes (no newline
+ * flattening) — callers must refuse control chars before quoting.
+ */
+function shellQuoteCliArg(value, dialect) {
+    // Allowlist: alnum + common path/repo chars without whitespace or shell meta.
+    if (value.length > 0 && /^[A-Za-z0-9_./:@+=,-]+$/.test(value)) {
+        return value;
+    }
+    if (dialect === "pwsh") {
+        // PowerShell single-quoted string: only ' is special, doubled as ''.
+        return `'${value.replace(/'/g, "''")}'`;
+    }
+    // POSIX single-quote; only ' needs escaping as '\''
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function mintCommandWithDialect(parent, draft, repo, dialect) {
+    return (`deft authz:grant -- --parent ${shellQuoteCliArg(parent, dialect)} --draft ${shellQuoteCliArg(draft, dialect)}` +
+        (repo ? ` --repo ${shellQuoteCliArg(repo, dialect)}` : "") +
+        " --confirm");
+}
+/** True when a path/repo token cannot be represented as an exact shell mint arg. */
+function hasUnsafeMintControlChars(value) {
+    return /[\r\n\0]/.test(value);
+}
+/**
+ * Exact operator CLI mint command for a structural decompose apply grant (#3291).
+ * Paths are project-relative POSIX when inside projectRoot; otherwise as provided.
+ * Parent / draft / repo tokens are shell-quoted when they contain whitespace or
+ * shell metacharacters. When POSIX and PowerShell apostrophe escapes differ,
+ * both forms are emitted on separate labeled lines (`bash:` / `pwsh:`) so each
+ * is independently copy-pasteable. Paths containing newline or NUL are refused
+ * (no rewritten fake path) so the operator renames before minting. Does not
+ * include agent/CI/TTY gates — those remain on the CLI multi-factor path.
+ */
+export function formatDecomposeStructuralMintCommand(parentPath, draftPath, options) {
+    let parent = parentPath.replace(/\\/g, "/");
+    let draft = draftPath.replace(/\\/g, "/");
+    const root = options?.projectRoot;
+    if (root) {
+        parent = toProjectRelativePosix(root, parentPath) ?? parent;
+        draft = toProjectRelativePosix(root, draftPath) ?? draft;
+    }
+    const repo = (options?.repo ?? "").trim();
+    if (hasUnsafeMintControlChars(parent) ||
+        hasUnsafeMintControlChars(draft) ||
+        hasUnsafeMintControlChars(repo)) {
+        return ("rename parent/draft/repo to remove newline or NUL characters, then run: " +
+            "deft authz:grant -- --parent <parent.xbrief.json> --draft <draft.json> [--repo owner/name] --confirm");
+    }
+    const posix = mintCommandWithDialect(parent, draft, repo, "posix");
+    const pwsh = mintCommandWithDialect(parent, draft, repo, "pwsh");
+    // Labels on their own lines so the executable command is independently pasteable.
+    if (posix === pwsh)
+        return posix;
+    return `bash:\n${posix}\npwsh:\n${pwsh}`;
+}
+/**
+ * Normalize a path to project-relative POSIX form for grant binding compare.
+ * Returns null when the path escapes the project root.
+ */
+export function toProjectRelativePosix(projectRoot, path) {
+    const root = resolve(projectRoot);
+    const abs = isAbsolute(path) ? resolve(path) : resolve(root, path);
+    const rel = relative(root, abs);
+    if (rel.startsWith("..") || rel === "..")
+        return null;
+    // Windows absolute on different drive yields absolute rel — treat as escape.
+    if (isAbsolute(rel))
+        return null;
+    return rel.split(sep).join("/");
+}
+function normalizeDigest(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const t = raw.trim().toLowerCase();
+    if (t.length === 0)
+        return null;
+    // Accept optional sha256: prefix.
+    return t.startsWith("sha256:") ? t.slice("sha256:".length) : t;
+}
+/**
+ * Exact path equality for grant binding (POSIX separators only).
+ * Case-sensitive: case-variant paths are distinct on case-sensitive filesystems
+ * (#3239 Greptile P1). Windows operators mint with the same relative form
+ * produce via toProjectRelativePosix.
+ */
+function pathsEqual(a, b) {
+    return a.replace(/\\/g, "/") === b.replace(/\\/g, "/");
+}
+function grantValidity(grant, now, mintHint) {
+    if (!isHumanOriginGrant(grant)) {
+        const kind = grant.origin.kind;
+        if (isRejectedOriginKind(kind)) {
+            return {
+                ok: false,
+                code: "authz-grant-origin-reject",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} origin.kind=${kind} is ` +
+                    "agent/self-authored and cannot approve a decomposition draft. " +
+                    `Human action required: \`${mintHint}\`.`,
+            };
+        }
+        return {
+            ok: false,
+            code: "authz-grant-origin-reject",
+            reason: `Directive denied scope:decompose apply: grant ${grant.id} lacks human-origin provenance. ` +
+                `Human action required: \`${mintHint}\`.`,
+        };
+    }
+    if (grant.semantics.revokedAt !== null) {
+        return {
+            ok: false,
+            code: "authz-grant-revoked",
+            reason: `Directive denied scope:decompose apply: grant ${grant.id} was revoked at ${grant.semantics.revokedAt}.`,
+        };
+    }
+    if (grant.semantics.singleUse && grant.semantics.usedAt !== null) {
+        return {
+            ok: false,
+            code: "authz-grant-single-use-spent",
+            reason: `Directive denied scope:decompose apply: single-use grant ${grant.id} already spent at ${grant.semantics.usedAt}. ` +
+                `Human action required: \`${mintHint}\`.`,
+        };
+    }
+    if (grant.semantics.expiresAt !== null) {
+        const exp = Date.parse(grant.semantics.expiresAt);
+        if (!Number.isNaN(exp) && exp <= now.getTime()) {
+            return {
+                ok: false,
+                code: "authz-grant-expired",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} expired at ${grant.semantics.expiresAt}. ` +
+                    `Human action required: \`${mintHint}\`.`,
+            };
+        }
+    }
+    return { ok: true };
+}
+function grantHasStructuralOp(grant) {
+    return grant.scope.operations.includes(SCOPE_DECOMPOSE_APPLY_STRUCTURAL);
+}
+/**
+ * Evaluate whether a human-origin grant covers structural decompose apply for
+ * the exact draft digest + parent + target + project identity.
+ */
+export function evaluateDecomposeStructuralApply(input) {
+    const now = input.now ?? new Date();
+    const digest = normalizeDigest(input.draftDigest) ?? "";
+    const parentRel = toProjectRelativePosix(input.projectRoot, input.parentPath);
+    const targetRel = toProjectRelativePosix(input.projectRoot, input.draftPath);
+    const projectAbs = resolve(input.projectRoot);
+    const grants = input.grants ?? listGrants(input.projectRoot);
+    const mintHint = formatDecomposeStructuralMintCommand(input.parentPath, input.draftPath, {
+        projectRoot: input.projectRoot,
+        repo: input.repo,
+    });
+    if (parentRel === null || targetRel === null) {
+        return {
+            allowed: false,
+            code: "authz-grant-scope-deny",
+            reason: "Directive denied scope:decompose apply: parent or draft path is outside the project root. " +
+                `Human action required: \`${mintHint}\` with paths inside the project root.`,
+            humanApprovalRef: null,
+            draftDigest: digest,
+        };
+    }
+    let lastReject = null;
+    for (const grant of grants) {
+        if (!evidenceSatisfiesImplementationApproval({ grant })) {
+            const validity = grantValidity(grant, now, mintHint);
+            if (!validity.ok) {
+                lastReject = { code: validity.code, reason: validity.reason, grantId: grant.id };
+                continue;
+            }
+            lastReject = {
+                code: "authz-grant-origin-reject",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} does not satisfy ` +
+                    `human-origin implementation approval. Human action required: \`${mintHint}\`.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        const validity = grantValidity(grant, now, mintHint);
+        if (!validity.ok) {
+            lastReject = { code: validity.code, reason: validity.reason, grantId: grant.id };
+            continue;
+        }
+        if (!grantHasStructuralOp(grant)) {
+            lastReject = {
+                code: "authz-grant-scope-deny",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} does not include operation ` +
+                    `'${SCOPE_DECOMPOSE_APPLY_STRUCTURAL}'. Human action required: \`${mintHint}\`.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        const boundDigest = normalizeDigest(grant.scope.contentDigest ?? null);
+        const boundParent = grant.scope.parentPath?.trim() ?? "";
+        const boundTarget = grant.scope.targetPath?.trim() ?? "";
+        const boundRepo = grant.scope.repo?.trim() ?? "";
+        const boundWorktree = grant.scope.worktree?.trim() ?? "";
+        if (boundDigest === null || boundParent.length === 0 || boundTarget.length === 0) {
+            lastReject = {
+                code: "authz-grant-binding-incomplete",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} is missing required ` +
+                    "structural bindings (contentDigest, parentPath, targetPath). " +
+                    `Human action required: \`${mintHint}\`.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        if (boundRepo.length === 0 && boundWorktree.length === 0) {
+            lastReject = {
+                code: "authz-grant-binding-incomplete",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} does not bind project ` +
+                    "identity (repo and/or worktree). " +
+                    `Human action required: \`${mintHint}\`.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        if (boundDigest !== digest) {
+            lastReject = {
+                code: "authz-grant-digest-mismatch",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to draft digest ` +
+                    `${boundDigest.slice(0, 12)}… but the draft bytes hash to ${digest.slice(0, 12)}…. ` +
+                    "Any content change after approval invalidates the grant. " +
+                    `Human action required: \`${mintHint}\`.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        if (!pathsEqual(boundParent, parentRel)) {
+            lastReject = {
+                code: "authz-grant-parent-mismatch",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to parent ` +
+                    `'${boundParent}' but apply targets '${parentRel}'. ` +
+                    `Human action required: \`${mintHint}\`.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        if (!pathsEqual(boundTarget, targetRel)) {
+            lastReject = {
+                code: "authz-grant-target-mismatch",
+                reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to draft path ` +
+                    `'${boundTarget}' but apply uses '${targetRel}'. ` +
+                    `Human action required: \`${mintHint}\`.`,
+                grantId: grant.id,
+            };
+            continue;
+        }
+        // Project identity: when grant pins repo and/or worktree, attempt must match.
+        if (boundRepo.length > 0) {
+            const attemptRepo = (input.repo ?? "").trim();
+            if (attemptRepo.length === 0 || attemptRepo.toLowerCase() !== boundRepo.toLowerCase()) {
+                lastReject = {
+                    code: "authz-grant-project-mismatch",
+                    reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to repo ` +
+                        `'${boundRepo}' which does not match the apply context. ` +
+                        `Human action required: \`${mintHint}\`.`,
+                    grantId: grant.id,
+                };
+                continue;
+            }
+        }
+        if (boundWorktree.length > 0) {
+            const grantWt = resolve(boundWorktree);
+            // Worktree compare is path-normalize only (resolve); keep exact string match of
+            // resolved absolute paths without case-folding (same rule as parent/target paths).
+            if (grantWt !== projectAbs) {
+                lastReject = {
+                    code: "authz-grant-project-mismatch",
+                    reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to worktree ` +
+                        `'${boundWorktree}' which does not match project root '${projectAbs}'. ` +
+                        `Human action required: \`${mintHint}\`.`,
+                    grantId: grant.id,
+                };
+                continue;
+            }
+        }
+        return {
+            allowed: true,
+            code: "authz-allow",
+            reason: `Directive allowed scope:decompose apply via human-origin grant ${grant.id} ` +
+                `bound to draft digest ${digest.slice(0, 12)}….`,
+            humanApprovalRef: grant.id,
+            draftDigest: digest,
+        };
+    }
+    if (lastReject !== null) {
+        return {
+            allowed: false,
+            code: lastReject.code,
+            reason: lastReject.reason,
+            humanApprovalRef: lastReject.grantId,
+            draftDigest: digest,
+        };
+    }
+    return {
+        allowed: false,
+        code: "authz-grant-missing",
+        reason: "Directive denied scope:decompose apply: no human-origin grant covers " +
+            `'${SCOPE_DECOMPOSE_APPLY_STRUCTURAL}' for this draft digest. ` +
+            `Human action required: \`${mintHint}\` ` +
+            "(self-authored lifecycle/dispatch tokens do not count). --check remains ungated.",
+        humanApprovalRef: null,
+        draftDigest: digest,
+    };
+}
+/**
+ * Operator mint helper: human-origin grant bound to exact draft bytes + paths.
+ * Sole mint path remains mintHumanOriginGrant (operator-cli origin).
+ */
+export function mintDecomposeStructuralApplyGrant(input) {
+    const parentRel = toProjectRelativePosix(input.projectRoot, input.parentPath);
+    const targetRel = toProjectRelativePosix(input.projectRoot, input.draftPath);
+    if (parentRel === null || targetRel === null) {
+        throw new Error("mintDecomposeStructuralApplyGrant: parentPath and draftPath must resolve inside projectRoot");
+    }
+    const digest = input.contentDigest !== undefined
+        ? (normalizeDigest(input.contentDigest) ?? "")
+        : sha256FileHex(isAbsolute(input.draftPath)
+            ? input.draftPath
+            : resolve(input.projectRoot, input.draftPath));
+    if (digest.length === 0) {
+        throw new Error("mintDecomposeStructuralApplyGrant: contentDigest must be non-empty");
+    }
+    const mintInput = {
+        projectRoot: input.projectRoot,
+        actor: input.actor,
+        operations: [SCOPE_DECOMPOSE_APPLY_STRUCTURAL],
+        contentDigest: digest,
+        parentPath: parentRel,
+        targetPath: targetRel,
+        worktree: resolve(input.projectRoot),
+        repo: input.repo ?? null,
+        expiresAt: input.expiresAt ?? null,
+        singleUse: input.singleUse === true,
+        grantId: input.grantId,
+        now: input.now,
+        pinActive: input.pinActive,
+        eventRef: input.eventRef ?? null,
+    };
+    return mintHumanOriginGrant(mintInput);
+}
+//# sourceMappingURL=decompose-apply.js.map

package/dist/authz/index.d.ts

@@ -1,10 +1,12 @@
 /**
  * Human-origin approval grants + UAT mutation lease (#2944 Wave 1)
- * + closed-verb release gates / AFK templates (#1095 Wave 4).
+ * + closed-verb release gates / AFK templates (#1095 Wave 4)
+ * + structural scope:decompose apply digest gate (#3239).
  */
 export * from "./actions.js";
 export * from "./classify.js";
 export * from "./closed-verb.js";
+export * from "./decompose-apply.js";
 export * from "./evaluate.js";
 export * from "./origin.js";
 export * from "./paths.js";

package/dist/authz/index.js

@@ -1,10 +1,12 @@
 /**
  * Human-origin approval grants + UAT mutation lease (#2944 Wave 1)
- * + closed-verb release gates / AFK templates (#1095 Wave 4).
+ * + closed-verb release gates / AFK templates (#1095 Wave 4)
+ * + structural scope:decompose apply digest gate (#3239).
  */
 export * from "./actions.js";
 export * from "./classify.js";
 export * from "./closed-verb.js";
+export * from "./decompose-apply.js";
 export * from "./evaluate.js";
 export * from "./origin.js";
 export * from "./paths.js";

package/dist/authz/store.d.ts

@@ -25,6 +25,59 @@ export declare function loadAuthzStateResult(projectRoot: string): AuthzStateLoa
 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;
+/** Exclusive claim lock body under `.deft/authz/locks/<id>.lock` (#3239). */
+export interface GrantClaimLockRecord {
+    readonly pid: number;
+    readonly startedAt: string;
+    readonly token: string;
+}
+/**
+ * Whether a claim lock may be reclaimed after a crashed holder (#3239).
+ * Live owner PIDs are never reclaimed (no mtime-only steal of a live critical section).
+ * Corrupt / unreadable records are reclaimable; PID-reuse residual needs manual delete.
+ */
+export declare function isGrantClaimLockReclaimable(rec: GrantClaimLockRecord | null): boolean;
+export interface ClaimSingleUseGrantOptions {
+    readonly now?: Date;
+    /**
+     * Re-check grant after exclusive lock (revocation/expiry/origin/bindings).
+     * Called before protected apply / single-use mark so an invalidated grant cannot authorize writes.
+     */
+    readonly revalidate?: (grant: HumanOriginGrant) => {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /**
+     * Protected work under the exclusive claim (#3239 residual).
+     * Order: lock → revalidate → mark single-use usedAt → apply → release lock.
+     * If apply throws, usedAt is rolled back (grant reusable) and the lock is released.
+     * Concurrent claimants fail closed while the lock is held.
+     */
+    readonly apply?: (grant: HumanOriginGrant) => void;
+}
+/**
+ * Claim a single-use grant for structural apply (#3239).
+ *
+ * Concurrent-safe + failure-safe order when `apply` is provided:
+ *   exclusive lock → re-load → revalidate → mark single-use usedAt → apply (writes)
+ *   → on apply throw: rollback usedAt + release lock (grant reusable for retry).
+ * Multi-use grants run apply (if any) without mutating usedAt.
+ * Without `apply`, single-use is marked under the lock (claim-only / test path).
+ *
+ * Crash after mark + before rollback: grant stays spent (no double-apply); operator remints.
+ * Dead-PID / corrupt locks reclaim via **rename-away** of the old lock path (only one
+ * renamer wins) then exclusive create — never blind rmSync of a live winner's lock.
+ * Live PIDs are never reclaimed. PID-reuse residual: operator deletes the lock file.
+ */
+export declare function claimSingleUseGrantForApply(projectRoot: string, grantId: string, options?: ClaimSingleUseGrantOptions | Date): {
+    ok: true;
+    grant: HumanOriginGrant;
+} | {
+    ok: false;
+    reason: string;
+};
 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;