vgxness 1.20.3 → 1.20.5

package/dist/permissions/explicit-request-authorization.js

@@ -0,0 +1,126 @@
+import { isAbsolute, resolve } from 'node:path';
+export function evaluateExplicitRequestAuthorization(input) {
+    const explicit = input.request.explicitRequest;
+    if (explicit === undefined)
+        return evaluation(input, 'ask', 'missing-context', ['explicit_request_missing']);
+    if (explicit.actor.type !== 'human')
+        return evaluation(input, 'ask', 'actor-mismatch', ['explicit_request_actor_mismatch']);
+    if (!validIsoTimestamp(explicit.request.requestedAt))
+        return evaluation(input, 'ask', 'timestamp-invalid', ['explicit_request_timestamp_invalid']);
+    if (explicit.request.runId !== undefined && input.request.runId !== undefined && explicit.request.runId !== input.request.runId)
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (explicit.parser.exact !== true || explicit.parser.confidence === 'medium' || explicit.parser.confidence === 'low' || hasItems(explicit.parser.ambiguityReasons))
+        return evaluation(input, 'ask', 'ambiguous-request', ['explicit_request_ambiguous']);
+    if (hasItems(explicit.parser.expansionReasons))
+        return evaluation(input, 'ask', 'scope-expanded', ['explicit_request_scope_expanded']);
+    if (isSddAcceptanceAttempt(input.request))
+        return evaluation(input, 'deny', 'hard-stop', ['sdd_human_acceptance_required']);
+    if (input.request.category === 'secrets' || input.risk.reasonCodes.includes('secret_access') || explicit.riskAttributes.secrets === true)
+        return evaluation(input, 'deny', 'hard-stop', ['explicit_request_secret_access']);
+    if (explicit.requestedOperation.category !== input.request.category)
+        return evaluation(input, 'ask', 'category-mismatch', ['explicit_request_category_mismatch']);
+    if (normalizeOperation(explicit.requestedOperation.operation) !== normalizeOperation(input.request.operation))
+        return evaluation(input, 'ask', 'operation-mismatch', ['explicit_request_operation_mismatch']);
+    if (!optionalExact(explicit.requestedOperation.commandId, input.request.commandId))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (!optionalExact(explicit.requestedOperation.providerToolName, input.request.providerToolName))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (!optionalPathExact(explicit.requestedOperation.workspaceRoot, input.request.workspaceRoot, input.request.workspaceRoot))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (!optionalPathExact(explicit.requestedOperation.cwd, input.request.cwd, input.request.workspaceRoot))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (!targetSetMatches(input.request, explicit.requestedOperation))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    const riskMismatch = riskMismatchReasons(input.request, input.risk, explicit.riskAttributes);
+    if (riskMismatch.length > 0)
+        return evaluation(input, 'ask', 'risk-attribute-mismatch', riskMismatch);
+    return evaluation(input, 'allow', 'exact-match', ['explicit_request_exact_match']);
+}
+function evaluation(input, decision, matchStatus, reasonCodes) {
+    const explicit = input.request.explicitRequest;
+    return {
+        decision,
+        audit: {
+            authorization: 'explicit-request',
+            matched: decision === 'allow',
+            matchStatus,
+            ...(explicit?.request.id === undefined ? {} : { requestRef: explicit.request.id }),
+            ...(explicit?.actor === undefined ? {} : { actor: explicit.actor }),
+            ...(explicit?.request.requestedAt === undefined ? {} : { requestedAt: explicit.request.requestedAt }),
+            evaluatedAt: input.evaluatedAt,
+            runId: input.request.runId ?? explicit?.request.runId ?? '',
+            category: input.request.category,
+            operation: input.request.operation,
+            scopeSummary: explicit?.requestedOperation.scopeSummary ?? '',
+            riskAttributes: explicitRiskAttributes(explicit?.riskAttributes),
+            reasonCodes,
+        },
+    };
+}
+function riskMismatchReasons(request, risk, explicit) {
+    const reasons = [];
+    if (request.destructive === true && explicit.destructive !== true)
+        reasons.push('explicit_request_destructive_not_explicit');
+    if (request.privileged === true && explicit.privileged !== true)
+        reasons.push('explicit_request_privileged_not_explicit');
+    if ((request.external === true || risk.reasonCodes.includes('external_operation')) && explicit.external !== true && explicit.network !== true && explicit.install !== true)
+        reasons.push('explicit_request_external_not_explicit');
+    if (request.ambiguous === true && explicit.ambiguous !== true)
+        reasons.push('explicit_request_ambiguous');
+    if (request.globalConfigMutation === true && explicit.globalConfigMutation !== true)
+        reasons.push('explicit_request_global_config_not_explicit');
+    if (request.providerConfigMutation === true && explicit.providerConfigMutation !== true)
+        reasons.push('explicit_request_provider_config_not_explicit');
+    if (request.providerConfigMutation !== true && request.globalConfigMutation !== true && risk.reasonCodes.includes('provider_config_write') && explicit.providerConfigMutation !== true)
+        reasons.push('explicit_request_provider_config_not_explicit');
+    if (request.category === 'network' && explicit.network !== true)
+        reasons.push('explicit_request_risk_mismatch');
+    if (request.category === 'install' && explicit.install !== true)
+        reasons.push('explicit_request_risk_mismatch');
+    return [...new Set(reasons)];
+}
+function targetSetMatches(request, explicit) {
+    const requested = targetSet(request.targetPath, request.targetPaths, request.workspaceRoot);
+    const authorized = targetSet(explicit.targetPath, explicit.targetPaths, request.workspaceRoot ?? explicit.workspaceRoot);
+    if (requested.length === 0 && authorized.length === 0)
+        return true;
+    if (requested.length === 0 || authorized.length === 0)
+        return false;
+    if (requested.length !== authorized.length)
+        return false;
+    return requested.every((value, index) => value === authorized[index]);
+}
+function targetSet(targetPath, targetPaths, workspaceRoot) {
+    return [...new Set([...(targetPath === undefined ? [] : [targetPath]), ...(targetPaths ?? [])].map((path) => normalizePath(path, workspaceRoot)))].sort();
+}
+function optionalExact(explicit, actual) {
+    return actual === undefined ? explicit === undefined : explicit === actual;
+}
+function optionalPathExact(explicit, actual, workspaceRoot) {
+    return actual === undefined ? explicit === undefined : explicit !== undefined && normalizePath(explicit, workspaceRoot) === normalizePath(actual, workspaceRoot);
+}
+function normalizePath(path, workspaceRoot) {
+    const base = workspaceRoot === undefined ? undefined : resolve(workspaceRoot);
+    return resolve(isAbsolute(path) || base === undefined ? path : resolve(base, path));
+}
+function normalizeOperation(value) {
+    return value.trim().replace(/\s+/g, ' ');
+}
+function hasItems(values) {
+    return values !== undefined && values.length > 0;
+}
+function validIsoTimestamp(value) {
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value && timestamp <= Date.now() + 60_000;
+}
+function explicitRiskAttributes(value) {
+    const output = {};
+    for (const key of ['destructive', 'privileged', 'external', 'ambiguous', 'secrets', 'providerConfigMutation', 'globalConfigMutation', 'network', 'install']) {
+        output[key] = value?.[key] === true;
+    }
+    return output;
+}
+function isSddAcceptanceAttempt(request) {
+    const text = `${request.category} ${request.operation} ${request.providerToolName ?? ''}`.toLowerCase();
+    return /vgxness_sdd_accept_artifact|sdd_accept_artifact|artifact acceptance|accept artifact|acceptedby/.test(text);
+}

package/dist/permissions/path-boundaries.js

@@ -0,0 +1,87 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, resolve, sep } from 'node:path';
+export function canonicalizeExistingPath(path) {
+    try {
+        return realpathSync.native(resolve(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isPathInside(path, root) {
+    return path === root || path.startsWith(`${root}${sep}`);
+}
+export function resolveCanonicalContainedPath(input) {
+    const root = canonicalizeExistingPath(input.root);
+    if (root === undefined)
+        return { ok: false, reason: 'root-not-found' };
+    const requested = resolve(root, input.requestedPath);
+    const existing = canonicalizeExistingPath(requested);
+    if (existing !== undefined) {
+        if (!isPathInside(existing, root))
+            return { ok: false, reason: 'path-escapes-root' };
+        return { ok: true, value: { root, path: existing } };
+    }
+    if (!input.allowNonexistentLeaf)
+        return { ok: false, reason: 'path-not-found' };
+    const nearest = nearestExistingAncestor(requested);
+    if (nearest === undefined)
+        return { ok: false, reason: 'path-ancestor-not-found' };
+    const canonicalAncestor = canonicalizeExistingPath(nearest);
+    if (canonicalAncestor === undefined)
+        return { ok: false, reason: 'path-ancestor-not-found' };
+    if (!isPathInside(canonicalAncestor, root))
+        return { ok: false, reason: 'path-escapes-root' };
+    const suffix = requested.slice(nearest.length).replace(/^[/\\]+/u, '').split(/[\\/]+/u).filter(Boolean);
+    const canonicalPath = resolve(canonicalAncestor, ...suffix);
+    if (!isPathInside(canonicalPath, root))
+        return { ok: false, reason: 'path-escapes-root' };
+    return { ok: true, value: { root, path: canonicalPath } };
+}
+export function validateSafeGrantRoot(rootPath) {
+    if (!isAbsolute(rootPath))
+        return { ok: false, reason: 'grant-root-relative' };
+    const canonicalRoot = canonicalizeExistingPath(rootPath);
+    if (canonicalRoot === undefined)
+        return { ok: false, reason: 'grant-root-not-found' };
+    const home = canonicalizeExistingPath(homedir()) ?? resolve(homedir());
+    if (canonicalRoot === resolve(sep))
+        return { ok: false, reason: 'grant-root-filesystem-root' };
+    if (canonicalRoot === home)
+        return { ok: false, reason: 'grant-root-home-directory' };
+    if (basename(canonicalRoot) === '.opencode' || basename(canonicalRoot) === '.claude')
+        return { ok: false, reason: 'grant-root-provider-config' };
+    if (basename(canonicalRoot) === 'opencode.json' || basename(canonicalRoot) === 'opencode.jsonc')
+        return { ok: false, reason: 'grant-root-provider-config' };
+    if (isProviderConfigPath(canonicalRoot, process.cwd()))
+        return { ok: false, reason: 'grant-root-provider-config' };
+    return { ok: true, value: { canonicalRoot } };
+}
+export function isUnsafeGrantRoot(rootPath) {
+    return !validateSafeGrantRoot(rootPath).ok;
+}
+export function isProviderConfigPath(path, workspaceRoot) {
+    const workspace = resolve(workspaceRoot);
+    const absolutePath = isAbsolute(path) ? resolve(path) : resolve(workspace, path);
+    const projectOpenCodeDirectory = resolve(workspace, '.opencode');
+    if (absolutePath === projectOpenCodeDirectory || isPathInside(absolutePath, projectOpenCodeDirectory))
+        return true;
+    if (absolutePath === resolve(workspace, 'opencode.json') || absolutePath === resolve(workspace, 'opencode.jsonc'))
+        return true;
+    const userOpenCodeDirectory = resolve(homedir(), '.config', 'opencode');
+    if (absolutePath === userOpenCodeDirectory || isPathInside(absolutePath, userOpenCodeDirectory))
+        return true;
+    const userClaudeDirectory = resolve(homedir(), '.claude');
+    return absolutePath === userClaudeDirectory || isPathInside(absolutePath, userClaudeDirectory);
+}
+function nearestExistingAncestor(path) {
+    let current = resolve(path);
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return current;
+}

package/dist/permissions/policy-evaluator.js

@@ -3,6 +3,7 @@ import { dirname, isAbsolute, resolve, sep } from 'node:path';
 import { classifyOperationRisk } from '../governance/risk-classifier.js';
 import { isSddPhase, sddPhases } from '../sdd/schema.js';
 import { commandAllowlistIds } from '../workflows/command-allowlist-adapter.js';
+import { evaluateExplicitRequestAuthorization } from './explicit-request-authorization.js';
 export { isRiskyPermissionCategory, permissionCategories, riskyPermissionCategories } from './schema.js';
 export const permissionDecisions = ['allow', 'ask', 'deny'];
 export const permissionModes = ['allow', 'audit', 'require-preflight', 'deny'];
@@ -85,30 +86,30 @@ const filesystemCategories = new Set([
 export function evaluatePermission(request, policy = defaultPermissionPolicy) {
     const risk = classifyOperationRisk(request);
     if (request.category === 'secrets')
-        return result(request, 'deny', 'secret_access', 'Secret access is denied by default.', {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, 'deny', 'secret_access', 'Secret access is denied by default.', {}, risk), risk);
     if (request.category === 'external-directory') {
-        return result(request, 'deny', 'workspace_boundary', 'External directory access is denied by the foundation policy.', {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, 'deny', 'workspace_boundary', 'External directory access is denied by the foundation policy.', {}, risk), risk);
     }
     const hardRisk = hardRiskDecision(request, risk);
     if (hardRisk !== undefined)
-        return hardRisk;
+        return withExplicitRequestAuthorization(request, hardRisk, risk);
     const workspaceEscape = workspaceEscapeDecision(request);
     if (workspaceEscape !== undefined)
-        return workspaceEscape;
+        return withExplicitRequestAuthorization(request, workspaceEscape, risk);
     const verifyAllowlistedCommand = verifyAllowlistedCommandDecision(request, risk);
     if (verifyAllowlistedCommand !== undefined)
         return verifyAllowlistedCommand;
     const sddPhaseDecision = phaseMatrixDecision(request);
     if (sddPhaseDecision !== undefined && sddPhaseDecision.mode !== 'allow' && sddPhaseDecision.mode !== 'audit')
-        return sddPhaseDecision;
+        return withExplicitRequestAuthorization(request, sddPhaseDecision, risk);
     const explicitValidation = explicitValidationDecision(request, risk);
     if (explicitValidation !== undefined)
-        return explicitValidation;
+        return withExplicitRequestAuthorization(request, explicitValidation, risk);
     if (sddPhaseDecision !== undefined)
         return sddPhaseDecision;
     const boundary = workspaceBoundaryDecision(request);
     if (boundary !== undefined)
-        return boundary;
+        return withExplicitRequestAuthorization(request, boundary, risk);
     const agentDecision = request.agent?.permissions[request.category];
     const baseRule = policy.rules.find((rule) => rule.category === request.category);
     const baseDecision = agentDecision ?? baseRule?.decision ?? 'ask';
@@ -118,7 +119,7 @@ export function evaluatePermission(request, policy = defaultPermissionPolicy) {
         : (baseRule?.reason ?? `No explicit rule exists for ${request.category}; ask by default.`);
     const flagRisk = riskDecision(request);
     if (flagRisk !== undefined && isLessRestrictive(baseDecision, flagRisk.decision)) {
-        return result(request, flagRisk.decision, flagRisk.reason, flagRisk.message, {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, flagRisk.decision, flagRisk.reason, flagRisk.message, {}, risk), risk);
     }
     if (risk.defaultDecision === 'audit' && baseDecision !== 'deny') {
         return result(request, 'allow', risk.reasonCodes.includes('provider_readonly_audit') ? 'provider_readonly_audit' : risk.reasonCodes.includes('allowlisted_verification') ? 'allowlisted_command' : baseReason, baseMessage, {
@@ -127,7 +128,39 @@ export function evaluatePermission(request, policy = defaultPermissionPolicy) {
             warnings: risk.reasonCodes.includes('provider_readonly_audit') ? ['provider-readonly-audit-only'] : ['audit-only'],
         }, risk);
     }
-    return result(request, baseDecision, baseReason, baseMessage, {}, risk);
+    return withExplicitRequestAuthorization(request, result(request, baseDecision, baseReason, baseMessage, {}, risk), risk);
+}
+function withExplicitRequestAuthorization(request, decision, risk) {
+    if (request.explicitRequest === undefined)
+        return decision;
+    const explicit = evaluateExplicitRequestAuthorization({ request, risk, evaluatedAt: new Date().toISOString() });
+    if (decision.decision !== 'ask') {
+        return { ...decision, explicitRequestAudit: explicit.audit, auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`] };
+    }
+    if (explicit.decision === 'allow') {
+        return {
+            ...decision,
+            decision: 'allow',
+            reason: 'explicit_request_authorization',
+            message: 'Explicit human request authorizes this exact one-off operation.',
+            explicitRequestAudit: explicit.audit,
+            authorizationMode: 'explicit-request',
+            auditEvidence: [...(decision.auditEvidence ?? []), 'explicitRequest:exact-match'],
+        };
+    }
+    if (explicit.decision === 'deny') {
+        return {
+            ...decision,
+            decision: 'deny',
+            reason: explicit.audit.reasonCodes.includes('sdd_human_acceptance_required') ? 'sdd_phase_policy' : 'risk_tier_policy',
+            message: explicit.audit.reasonCodes.includes('sdd_human_acceptance_required')
+                ? 'SDD artifact acceptance is human-only and cannot be inferred from explicit-request preflight.'
+                : 'Explicit request contains a hard-stop condition and cannot authorize this operation.',
+            explicitRequestAudit: explicit.audit,
+            auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`],
+        };
+    }
+    return { ...decision, explicitRequestAudit: explicit.audit, auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`] };
 }
 export function isPathInsideWorkspace(workspaceRoot, targetPath) {
     const root = resolve(workspaceRoot);

package/dist/permissions/task-scoped-command-grant-matcher.js

@@ -0,0 +1,117 @@
+import { canonicalizeExistingPath, isPathInside, isProviderConfigPath, resolveCanonicalContainedPath } from './path-boundaries.js';
+const grantableCategories = new Set(['shell', 'test-run', 'git']);
+export function matchTaskScopedCommandGrant(input) {
+    const known = new Set(input.knownAllowlistIds);
+    const commandId = input.request.commandId ?? commandIdFromOperation(input.request.operation);
+    const hardMissReasons = hardRequestMissReasons(input.request, commandId, known);
+    const candidateEvidence = input.candidates.map((grant) => evaluateCandidate({ ...input, commandId, hardMissReasons, grant }));
+    const matched = candidateEvidence.filter((candidate) => candidate.matched);
+    const sorted = [...matched].sort((left, right) => compareMatchedCandidates(left.grantId, right.grantId, input.candidates));
+    const selectedGrantId = sorted[0]?.grantId;
+    const candidates = candidateEvidence.map((candidate) => ({ ...candidate, selected: candidate.grantId === selectedGrantId }));
+    const selected = candidates.find((candidate) => candidate.selected);
+    const result = {
+        matchedGrantIds: matched.map((candidate) => candidate.grantId).sort(),
+        selectedOrder: sorted.map((candidate) => candidate.grantId),
+        missReasons: collectMissReasons(candidates),
+        candidates,
+    };
+    if (selectedGrantId !== undefined)
+        result.selectedGrantId = selectedGrantId;
+    if (selected?.canonicalCwd !== undefined)
+        result.canonicalCwd = selected.canonicalCwd;
+    if (selected?.matchedExternalRoot !== undefined)
+        result.matchedExternalRoot = selected.matchedExternalRoot;
+    if (commandId !== undefined)
+        result.commandId = commandId;
+    return result;
+}
+function evaluateCandidate(input) {
+    const missReasons = [...input.hardMissReasons];
+    const grant = input.grant;
+    if (grant.status !== 'active')
+        missReasons.push(`${grant.status}-grant`);
+    if (Date.parse(grant.expiresAt) <= input.now.getTime())
+        missReasons.push('expired');
+    if (grant.usedCount >= grant.maxUses)
+        missReasons.push('exhausted');
+    if (grant.runId !== input.request.runId)
+        missReasons.push('run-mismatch');
+    if (grant.agentId !== input.request.agentId)
+        missReasons.push('agent-mismatch');
+    if (grant.taskFingerprint !== input.request.taskFingerprint)
+        missReasons.push('task-fingerprint-mismatch');
+    if (!grant.categories.some((category) => category === input.request.category))
+        missReasons.push('category-mismatch');
+    if (input.commandId === undefined || !grant.commandPolicy.ids.includes(input.commandId))
+        missReasons.push('command-mismatch');
+    const rootMatch = matchRootForRequest(grant.canonicalExternalRoots, input.request.cwd, input.request.targetPaths ?? [], input.workspaceRoot);
+    if (!rootMatch.ok)
+        missReasons.push(rootMatch.reason);
+    const evidence = {
+        grantId: grant.id,
+        matched: missReasons.length === 0,
+        selected: false,
+        missReasons,
+    };
+    if (rootMatch.ok) {
+        evidence.canonicalCwd = rootMatch.value.canonicalCwd;
+        evidence.matchedExternalRoot = rootMatch.value.matchedExternalRoot;
+    }
+    if (input.commandId !== undefined)
+        evidence.commandId = input.commandId;
+    return evidence;
+}
+function hardRequestMissReasons(request, commandId, knownAllowlistIds) {
+    const reasons = [];
+    if (!grantableCategories.has(request.category))
+        reasons.push('unsupported-category');
+    if (request.destructive === true)
+        reasons.push('destructive-operation');
+    if (request.privileged === true)
+        reasons.push('privileged-operation');
+    if (request.ambiguous === true)
+        reasons.push('ambiguous-operation');
+    if (commandId === undefined)
+        reasons.push('missing-command-id');
+    else if (!knownAllowlistIds.has(commandId))
+        reasons.push('unknown-command-id');
+    return reasons;
+}
+function matchRootForRequest(canonicalRoots, cwd, targetPaths, workspaceRoot) {
+    if (isProviderConfigPath(cwd, workspaceRoot))
+        return { ok: false, reason: 'provider-config-path-blocked' };
+    const canonicalCwd = canonicalizeExistingPath(cwd);
+    if (canonicalCwd === undefined)
+        return { ok: false, reason: 'cwd-not-found' };
+    if (isProviderConfigPath(canonicalCwd, workspaceRoot))
+        return { ok: false, reason: 'provider-config-path-blocked' };
+    const matchedRoot = canonicalRoots.find((root) => isPathInside(canonicalCwd, root));
+    if (matchedRoot === undefined)
+        return { ok: false, reason: 'cwd-root-mismatch' };
+    for (const targetPath of targetPaths) {
+        if (isProviderConfigPath(targetPath, workspaceRoot))
+            return { ok: false, reason: 'provider-config-path-blocked' };
+        const resolved = resolveCanonicalContainedPath({ root: matchedRoot, requestedPath: targetPath, allowNonexistentLeaf: true });
+        if (!resolved.ok)
+            return { ok: false, reason: 'target-root-mismatch' };
+        if (isProviderConfigPath(resolved.value.path, workspaceRoot))
+            return { ok: false, reason: 'provider-config-path-blocked' };
+    }
+    return { ok: true, value: { canonicalCwd, matchedExternalRoot: matchedRoot } };
+}
+function compareMatchedCandidates(leftId, rightId, grants) {
+    const left = grants.find((grant) => grant.id === leftId);
+    const right = grants.find((grant) => grant.id === rightId);
+    if (left === undefined || right === undefined)
+        return leftId.localeCompare(rightId);
+    return Date.parse(left.expiresAt) - Date.parse(right.expiresAt) || Date.parse(left.createdAt) - Date.parse(right.createdAt) || left.id.localeCompare(right.id);
+}
+function collectMissReasons(candidates) {
+    if (candidates.length === 0)
+        return ['no-candidates'];
+    return [...new Set(candidates.flatMap((candidate) => candidate.missReasons))].sort();
+}
+function commandIdFromOperation(operation) {
+    return /^command-allowlist:([A-Za-z0-9._/-]+)$/u.exec(operation)?.[1];
+}

package/dist/permissions/task-scoped-command-grant-validation.js

@@ -0,0 +1,135 @@
+import { validateSafeGrantRoot } from './path-boundaries.js';
+const grantableCategories = new Set(['shell', 'test-run', 'git']);
+const rejectedCategories = new Set([
+    'secrets',
+    'external-directory',
+    'provider-tool',
+    'edit',
+    'implementation-edit',
+    'git-write',
+    'memory-write',
+    'install',
+    'network',
+]);
+const maxExpiryMs = 24 * 60 * 60 * 1000;
+export function validateTaskScopedCommandGrantCreationInput(input, options) {
+    if (!input.runId.trim())
+        return validationFailure('Grant runId is required');
+    if (!input.agentId.trim())
+        return validationFailure('Grant agentId is required');
+    if (!input.taskFingerprint.trim())
+        return validationFailure('Grant taskFingerprint is required');
+    if (input.createdBy.type !== 'human')
+        return validationFailure('Grant creator must be a human actor');
+    if (!input.createdBy.id.trim())
+        return validationFailure('Grant creator id is required');
+    const categories = validateCategories(input.categories);
+    if (!categories.ok)
+        return categories;
+    const commandPolicy = validateCommandPolicy(input.commandPolicy, options.knownAllowlistIds);
+    if (!commandPolicy.ok)
+        return commandPolicy;
+    const cwdPatterns = validateOptionalStringList(input.cwdPatterns, 'Grant cwdPatterns');
+    if (!cwdPatterns.ok)
+        return cwdPatterns;
+    const expiry = validateExpiry(input.expiresAt, options.now);
+    if (!expiry.ok)
+        return expiry;
+    if (!Number.isInteger(input.maxUses) || input.maxUses < 1)
+        return validationFailure('Grant maxUses must be a positive integer');
+    if (!input.audit.creationReason.trim())
+        return validationFailure('Grant audit creationReason is required');
+    if (!input.audit.approvedScopeSummary.trim())
+        return validationFailure('Grant audit approvedScopeSummary is required');
+    if (input.externalRoots.length === 0)
+        return validationFailure('Grant externalRoots are required');
+    const canonicalExternalRoots = [];
+    for (const root of input.externalRoots) {
+        const safe = validateSafeGrantRoot(root);
+        if (!safe.ok)
+            return validationFailure(`Grant external root is unsafe: ${safe.reason}`);
+        canonicalExternalRoots.push(safe.value.canonicalRoot);
+    }
+    if (new Set(canonicalExternalRoots).size !== canonicalExternalRoots.length)
+        return validationFailure('Grant external roots must be unique');
+    const createdBy = { type: 'human', id: input.createdBy.id.trim() };
+    const validated = {
+        runId: input.runId,
+        agentId: input.agentId,
+        taskFingerprint: input.taskFingerprint,
+        categories: categories.value,
+        externalRoots: input.externalRoots,
+        canonicalExternalRoots,
+        commandPolicy: commandPolicy.value,
+        expiresAt: input.expiresAt,
+        maxUses: input.maxUses,
+        createdBy,
+        audit: input.audit,
+    };
+    if (cwdPatterns.value !== undefined)
+        validated.cwdPatterns = cwdPatterns.value;
+    if (input.createdBy.displayName !== undefined)
+        validated.createdBy.displayName = input.createdBy.displayName;
+    return ok(validated);
+}
+function validateCategories(categories) {
+    if (!Array.isArray(categories) || categories.length === 0)
+        return validationFailure('Grant categories are required');
+    if (new Set(categories).size !== categories.length)
+        return validationFailure('Grant categories must be unique');
+    for (const category of categories) {
+        if (rejectedCategories.has(category))
+            return validationFailure(`Unsupported grant category: ${category}`);
+        if (!grantableCategories.has(category))
+            return validationFailure(`Unsupported grant category: ${category}`);
+    }
+    return ok(categories);
+}
+function validateCommandPolicy(policy, knownAllowlistIds) {
+    if (!isRecord(policy))
+        return validationFailure('Grant command policy is required');
+    if (policy.kind !== 'allowlisted-command-ids')
+        return validationFailure('Grant command policy must use allowlisted command ids');
+    if (!Array.isArray(policy.ids) || policy.ids.length === 0)
+        return validationFailure('Grant command policy ids are required');
+    if (!policy.ids.every((id) => typeof id === 'string' && id.trim().length > 0))
+        return validationFailure('Grant command policy ids must be non-empty strings');
+    if (new Set(policy.ids).size !== policy.ids.length)
+        return validationFailure('Grant command policy ids must be unique');
+    const known = new Set(knownAllowlistIds);
+    for (const id of policy.ids)
+        if (!known.has(id))
+            return validationFailure(`Unknown allowlisted command id: ${id}`);
+    return ok({ kind: 'allowlisted-command-ids', ids: policy.ids });
+}
+function validateOptionalStringList(values, label) {
+    if (values === undefined)
+        return ok(undefined);
+    if (!Array.isArray(values))
+        return validationFailure(`${label} must be an array when provided`);
+    if (!values.every((value) => typeof value === 'string' && value.trim().length > 0))
+        return validationFailure(`${label} must contain non-empty strings`);
+    if (new Set(values).size !== values.length)
+        return validationFailure(`${label} must be unique`);
+    return ok(values);
+}
+function validateExpiry(expiresAt, now) {
+    const timestamp = Date.parse(expiresAt);
+    if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== expiresAt)
+        return validationFailure('Grant expiresAt must be a valid ISO date');
+    const delta = timestamp - now.getTime();
+    if (delta <= 0)
+        return validationFailure('Grant expiresAt must be in the future');
+    if (delta > maxExpiryMs)
+        return validationFailure('Grant expiresAt must be within 24 hours');
+    return ok(undefined);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}