@taskforcehq/taskforce 0.3.329 → 0.3.330

package/dist/storage/executorPhaseARunAuthorizationStore.js

@@ -0,0 +1,492 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeExecutorPhaseAJson } from '../shared/executorPhaseAApprovalReceipt.js';
+import { EXECUTOR_PHASE_A_CLEANUP_CAPABILITY_TTL_MS, EXECUTOR_PHASE_A_MAIN_CAPABILITY_TTL_MS, } from '../shared/executorPhaseARunAuthorization.js';
+const verifiedCapabilityRecordBrand = Symbol('verifiedExecutorPhaseACapabilityRecord');
+const verifiedGrantRecordBrand = Symbol('verifiedExecutorPhaseAGrantRecord');
+function sha256(value) {
+    return createHash('sha256').update(canonicalizeExecutorPhaseAJson(value)).digest('hex');
+}
+export function executorPhaseACapabilityRecordFromVerified(artifact) {
+    const payload = artifact.payload;
+    return {
+        capabilityId: payload.capabilityId,
+        workspaceId: payload.workspaceId,
+        taskId: payload.taskId,
+        runId: payload.runId,
+        receiptId: payload.receiptId,
+        receiptSha256: payload.receiptSha256,
+        capabilityKind: payload.capabilityKind,
+        originalCapabilityId: payload.originalCapabilityId,
+        residualInventorySha256: payload.residualInventorySha256,
+        actorUserId: payload.actorUserId,
+        accountId: payload.accountId,
+        region: payload.region,
+        availabilityZone: payload.availabilityZone,
+        readPrincipalArn: payload.readPrincipalArn,
+        brokerKeyFingerprint: payload.brokerKeyFingerprint,
+        capabilitySha256: sha256(artifact),
+        preflightSha256: payload.preflightSha256,
+        logicalEnvelopeSha256: payload.logicalEnvelopeSha256,
+        sourceCommit: payload.sourceCommit,
+        roleMapSha256: payload.roleMapSha256,
+        oidcAudienceSha256: sha256(payload.oidcAudience),
+        issuedAt: payload.issuedAt,
+        expiresAt: payload.expiresAt,
+        mutationDeadline: payload.mutationDeadline,
+        cleanupDeadline: payload.cleanupDeadline,
+        status: 'active',
+        hardStoppedAt: null,
+        createdAt: payload.issuedAt,
+        updatedAt: payload.issuedAt,
+        [verifiedCapabilityRecordBrand]: true,
+    };
+}
+export function executorPhaseAGrantRecordFromVerified(bundle, tokenId) {
+    const payload = bundle.grant.payload;
+    if (!/^token-[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/.test(tokenId)) {
+        throw new ExecutorPhaseARunAuthorizationError('The workload token ID is invalid.');
+    }
+    return {
+        grantId: payload.grantId,
+        capabilityId: payload.capabilityId,
+        workspaceId: payload.workspaceId,
+        taskId: payload.taskId,
+        runId: payload.runId,
+        receiptId: payload.receiptId,
+        phase: payload.phase,
+        roleArn: payload.roleArn,
+        grantSha256: bundle.grantSha256,
+        tokenId,
+        nonceId: payload.nonceId,
+        senderProofSha256: bundle.senderProofSha256,
+        brokerKeyFingerprint: payload.brokerKeyFingerprint,
+        sourceIdentity: payload.sourceIdentity,
+        sessionTagsSha256: sha256(payload.sessionTags),
+        policySha256: payload.policySha256,
+        issuedAt: payload.issuedAt,
+        expiresAt: payload.expiresAt,
+        usedAt: null,
+        status: 'issued',
+        createdAt: payload.issuedAt,
+        updatedAt: payload.issuedAt,
+        [verifiedGrantRecordBrand]: true,
+    };
+}
+export class ExecutorPhaseARunAuthorizationError extends Error {
+    code = 'executor_phase_a_run_authorization_invalid';
+    constructor(message) {
+        super(message);
+        this.name = 'ExecutorPhaseARunAuthorizationError';
+    }
+}
+function timestamp(value, field) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        throw new ExecutorPhaseARunAuthorizationError(`${field} is invalid.`);
+    return parsed;
+}
+function isUniqueConstraintError(error) {
+    const code = error && typeof error === 'object' && typeof error.code === 'string'
+        ? String(error.code)
+        : '';
+    return code === '23505'
+        || code === 'SQLITE_CONSTRAINT_UNIQUE'
+        || code === 'SQLITE_CONSTRAINT_PRIMARYKEY';
+}
+function capabilityFromRow(row) {
+    return {
+        capabilityId: String(row.capability_id),
+        workspaceId: String(row.workspace_id),
+        taskId: String(row.task_id),
+        runId: String(row.run_id),
+        receiptId: String(row.receipt_id),
+        receiptSha256: String(row.receipt_sha256),
+        capabilityKind: String(row.capability_kind),
+        originalCapabilityId: row.original_capability_id == null ? null : String(row.original_capability_id),
+        residualInventorySha256: row.residual_inventory_sha256 == null ? null : String(row.residual_inventory_sha256),
+        actorUserId: String(row.actor_user_id),
+        accountId: String(row.account_id),
+        region: String(row.region),
+        availabilityZone: String(row.availability_zone),
+        readPrincipalArn: String(row.read_principal_arn),
+        brokerKeyFingerprint: String(row.broker_key_fingerprint),
+        capabilitySha256: String(row.capability_sha256),
+        preflightSha256: String(row.preflight_sha256),
+        logicalEnvelopeSha256: String(row.logical_envelope_sha256),
+        sourceCommit: String(row.source_commit),
+        roleMapSha256: String(row.role_map_sha256),
+        oidcAudienceSha256: String(row.oidc_audience_sha256),
+        issuedAt: String(row.issued_at),
+        expiresAt: String(row.expires_at),
+        mutationDeadline: String(row.mutation_deadline),
+        cleanupDeadline: String(row.cleanup_deadline),
+        status: String(row.status),
+        hardStoppedAt: row.hard_stopped_at == null ? null : String(row.hard_stopped_at),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+    };
+}
+function grantFromRow(row) {
+    return {
+        grantId: String(row.grant_id),
+        capabilityId: String(row.capability_id),
+        workspaceId: String(row.workspace_id),
+        taskId: String(row.task_id),
+        runId: String(row.run_id),
+        receiptId: String(row.receipt_id),
+        phase: String(row.phase),
+        roleArn: String(row.role_arn),
+        grantSha256: String(row.grant_sha256),
+        tokenId: String(row.token_id),
+        nonceId: String(row.nonce_id),
+        senderProofSha256: String(row.sender_proof_sha256),
+        brokerKeyFingerprint: String(row.broker_key_fingerprint),
+        sourceIdentity: String(row.source_identity),
+        sessionTagsSha256: String(row.session_tags_sha256),
+        policySha256: String(row.policy_sha256),
+        issuedAt: String(row.issued_at),
+        expiresAt: String(row.expires_at),
+        usedAt: row.used_at == null ? null : String(row.used_at),
+        status: String(row.status),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+    };
+}
+function nonceFromRow(row) {
+    return {
+        nonceId: String(row.nonce_id),
+        capabilityId: String(row.capability_id),
+        requestSha256: String(row.request_sha256),
+        phase: String(row.phase),
+        issuedAt: String(row.issued_at),
+        expiresAt: String(row.expires_at),
+        consumedAt: row.consumed_at == null ? null : String(row.consumed_at),
+        status: String(row.status),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+    };
+}
+export class ExecutorPhaseARunAuthorizationStore {
+    db;
+    tenantId;
+    constructor(db, tenantId) {
+        this.db = db;
+        this.tenantId = tenantId;
+    }
+    findCapability(capabilityId) {
+        const row = this.db.prepare(`
+            SELECT * FROM executor_phase_a_run_capabilities
+            WHERE tenant_id = ? AND capability_id = ?
+            LIMIT 1
+        `).get(this.tenantId, capabilityId);
+        return row ? capabilityFromRow(row) : null;
+    }
+    persistCapability(candidate) {
+        this.assertCapability(candidate);
+        try {
+            this.db.prepare(`
+                INSERT INTO executor_phase_a_run_capabilities (
+                    capability_id, tenant_id, workspace_id, task_id, run_id, receipt_id, receipt_sha256,
+                    capability_kind, original_capability_id, residual_inventory_sha256, actor_user_id,
+                    account_id, region, availability_zone, read_principal_arn, broker_key_fingerprint,
+                    capability_sha256, preflight_sha256, logical_envelope_sha256, source_commit,
+                    role_map_sha256, oidc_audience_sha256, issued_at, expires_at, mutation_deadline,
+                    cleanup_deadline, status, hard_stopped_at, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `).run(candidate.capabilityId, this.tenantId, candidate.workspaceId, candidate.taskId, candidate.runId, candidate.receiptId, candidate.receiptSha256, candidate.capabilityKind, candidate.originalCapabilityId, candidate.residualInventorySha256, candidate.actorUserId, candidate.accountId, candidate.region, candidate.availabilityZone, candidate.readPrincipalArn, candidate.brokerKeyFingerprint, candidate.capabilitySha256, candidate.preflightSha256, candidate.logicalEnvelopeSha256, candidate.sourceCommit, candidate.roleMapSha256, candidate.oidcAudienceSha256, candidate.issuedAt, candidate.expiresAt, candidate.mutationDeadline, candidate.cleanupDeadline, candidate.status, candidate.hardStoppedAt, candidate.createdAt, candidate.updatedAt);
+        }
+        catch (error) {
+            if (!isUniqueConstraintError(error))
+                throw error;
+            throw new ExecutorPhaseARunAuthorizationError('The receipt, broker key, or capability is already bound to a Phase A run.');
+        }
+        return this.findCapability(candidate.capabilityId);
+    }
+    hardStop(capabilityId, stoppedAt) {
+        timestamp(stoppedAt, 'hardStoppedAt');
+        const stop = this.db.transaction(() => {
+            const result = this.db.prepare(`
+                UPDATE executor_phase_a_run_capabilities
+                SET status = 'awaiting-cleanup-approval', hard_stopped_at = ?, updated_at = ?
+                WHERE tenant_id = ? AND capability_id = ? AND capability_kind = 'main' AND status = 'active'
+            `).run(stoppedAt, stoppedAt, this.tenantId, capabilityId);
+            if (Number(result.changes ?? result.rowCount ?? 0) !== 1) {
+                throw new ExecutorPhaseARunAuthorizationError('Only one active main capability can be hard-stopped.');
+            }
+            this.db.prepare(`
+                UPDATE executor_phase_a_sender_nonces
+                SET status = 'revoked', updated_at = ?
+                WHERE tenant_id = ? AND capability_id = ? AND status = 'issued'
+            `).run(stoppedAt, this.tenantId, capabilityId);
+            this.db.prepare(`
+                UPDATE executor_phase_a_workload_grants
+                SET status = 'revoked', updated_at = ?
+                WHERE tenant_id = ? AND capability_id = ? AND status = 'issued'
+            `).run(stoppedAt, this.tenantId, capabilityId);
+            return this.findCapability(capabilityId);
+        });
+        return stop();
+    }
+    issueNonce(candidate) {
+        const issue = this.db.transaction(() => {
+            const capability = this.findCapability(candidate.capabilityId);
+            const issuedAt = timestamp(candidate.issuedAt, 'issuedAt');
+            const expiresAt = timestamp(candidate.expiresAt, 'expiresAt');
+            if (!capability || capability.status !== 'active') {
+                throw new ExecutorPhaseARunAuthorizationError('The sender nonce is not valid for an active capability.');
+            }
+            const phaseDeadline = timestamp(candidate.phase === 'cleanup' ? capability.cleanupDeadline : capability.mutationDeadline, candidate.phase === 'cleanup' ? 'cleanupDeadline' : 'mutationDeadline');
+            if (candidate.status !== 'issued' || candidate.consumedAt !== null
+                || expiresAt <= issuedAt || expiresAt - issuedAt > 2 * 60 * 1000
+                || issuedAt >= phaseDeadline || expiresAt > phaseDeadline
+                || !/^[a-f0-9]{64}$/.test(candidate.requestSha256)
+                || (capability.capabilityKind === 'cleanup-only' && candidate.phase !== 'cleanup')) {
+                throw new ExecutorPhaseARunAuthorizationError('The sender nonce is not valid for an active capability.');
+            }
+            const guard = this.db.prepare(`
+                UPDATE executor_phase_a_run_capabilities
+                SET updated_at = updated_at
+                WHERE tenant_id = ? AND capability_id = ? AND status = 'active'
+            `).run(this.tenantId, candidate.capabilityId);
+            if (Number(guard.changes ?? guard.rowCount ?? 0) !== 1) {
+                throw new ExecutorPhaseARunAuthorizationError('The run capability was revoked before nonce issuance.');
+            }
+            try {
+                this.db.prepare(`
+                    INSERT INTO executor_phase_a_sender_nonces (
+                        nonce_id, tenant_id, capability_id, request_sha256, phase, issued_at, expires_at,
+                        consumed_at, status, created_at, updated_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                `).run(candidate.nonceId, this.tenantId, candidate.capabilityId, candidate.requestSha256, candidate.phase, candidate.issuedAt, candidate.expiresAt, candidate.consumedAt, candidate.status, candidate.createdAt, candidate.updatedAt);
+            }
+            catch (error) {
+                if (!isUniqueConstraintError(error))
+                    throw error;
+                throw new ExecutorPhaseARunAuthorizationError('The sender nonce is already registered.');
+            }
+            const row = this.db.prepare(`
+                SELECT * FROM executor_phase_a_sender_nonces WHERE tenant_id = ? AND nonce_id = ?
+            `).get(this.tenantId, candidate.nonceId);
+            return nonceFromRow(row);
+        });
+        return issue();
+    }
+    persistGrant(candidate, now) {
+        const persist = this.db.transaction(() => {
+            const capability = this.findCapability(candidate.capabilityId);
+            if (!capability || capability.status !== 'active') {
+                throw new ExecutorPhaseARunAuthorizationError('The run capability is unavailable or revoked.');
+            }
+            if (candidate.status !== 'issued' || candidate.usedAt !== null) {
+                throw new ExecutorPhaseARunAuthorizationError('A new workload grant must begin issued and unused.');
+            }
+            if (candidate.workspaceId !== capability.workspaceId || candidate.taskId !== capability.taskId
+                || candidate.runId !== capability.runId || candidate.receiptId !== capability.receiptId
+                || candidate.brokerKeyFingerprint !== capability.brokerKeyFingerprint) {
+                throw new ExecutorPhaseARunAuthorizationError('The workload grant scope differs from its run capability.');
+            }
+            const nowMs = timestamp(now, 'now');
+            const issuedAt = timestamp(candidate.issuedAt, 'issuedAt');
+            const expiresAt = timestamp(candidate.expiresAt, 'expiresAt');
+            if (issuedAt !== nowMs || expiresAt <= issuedAt || expiresAt - issuedAt > 2 * 60 * 1000) {
+                throw new ExecutorPhaseARunAuthorizationError('The workload grant lifetime is invalid.');
+            }
+            if (capability.capabilityKind === 'cleanup-only' && candidate.phase !== 'cleanup') {
+                throw new ExecutorPhaseARunAuthorizationError('A cleanup-only capability cannot issue a mutation grant.');
+            }
+            const deadline = candidate.phase === 'cleanup'
+                ? timestamp(capability.cleanupDeadline, 'cleanupDeadline')
+                : timestamp(capability.mutationDeadline, 'mutationDeadline');
+            if (nowMs >= deadline || expiresAt > deadline) {
+                throw new ExecutorPhaseARunAuthorizationError('The workload grant exceeds the approved phase deadline.');
+            }
+            const guard = this.db.prepare(`
+                UPDATE executor_phase_a_run_capabilities
+                SET updated_at = updated_at
+                WHERE tenant_id = ? AND capability_id = ? AND status = 'active'
+            `).run(this.tenantId, candidate.capabilityId);
+            if (Number(guard.changes ?? guard.rowCount ?? 0) !== 1) {
+                throw new ExecutorPhaseARunAuthorizationError('The run capability was revoked before grant issuance.');
+            }
+            const nonce = this.db.prepare(`
+                SELECT * FROM executor_phase_a_sender_nonces
+                WHERE tenant_id = ? AND capability_id = ? AND nonce_id = ?
+            `).get(this.tenantId, candidate.capabilityId, candidate.nonceId);
+            if (!nonce || nonce.status !== 'issued' || nonce.phase !== candidate.phase
+                || timestamp(String(nonce.expires_at), 'nonceExpiresAt') <= nowMs) {
+                throw new ExecutorPhaseARunAuthorizationError('The sender nonce is missing, expired, consumed, or bound to another phase.');
+            }
+            const consumed = this.db.prepare(`
+                UPDATE executor_phase_a_sender_nonces
+                SET status = 'consumed', consumed_at = ?, updated_at = ?
+                WHERE tenant_id = ? AND capability_id = ? AND nonce_id = ? AND status = 'issued'
+            `).run(now, now, this.tenantId, candidate.capabilityId, candidate.nonceId);
+            if (Number(consumed.changes ?? consumed.rowCount ?? 0) !== 1) {
+                throw new ExecutorPhaseARunAuthorizationError('The sender nonce was already consumed.');
+            }
+            try {
+                this.db.prepare(`
+                    INSERT INTO executor_phase_a_workload_grants (
+                        grant_id, tenant_id, capability_id, workspace_id, task_id, run_id, receipt_id,
+                        phase, role_arn, grant_sha256, token_id, nonce_id, sender_proof_sha256, broker_key_fingerprint,
+                        source_identity, session_tags_sha256, policy_sha256, issued_at, expires_at,
+                        used_at, status, created_at, updated_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                `).run(candidate.grantId, this.tenantId, candidate.capabilityId, candidate.workspaceId, candidate.taskId, candidate.runId, candidate.receiptId, candidate.phase, candidate.roleArn, candidate.grantSha256, candidate.tokenId, candidate.nonceId, candidate.senderProofSha256, candidate.brokerKeyFingerprint, candidate.sourceIdentity, candidate.sessionTagsSha256, candidate.policySha256, candidate.issuedAt, candidate.expiresAt, candidate.usedAt, candidate.status, candidate.createdAt, candidate.updatedAt);
+            }
+            catch (error) {
+                if (!isUniqueConstraintError(error))
+                    throw error;
+                throw new ExecutorPhaseARunAuthorizationError('The workload grant token or sender proof was already used.');
+            }
+            const row = this.db.prepare(`
+                SELECT * FROM executor_phase_a_workload_grants
+                WHERE tenant_id = ? AND grant_id = ?
+            `).get(this.tenantId, candidate.grantId);
+            return grantFromRow(row);
+        });
+        return persist();
+    }
+    redeemVerifiedGrant(bundle, requestId, requestSha256, canonicalResponseBytes, responseSha256, usedAt) {
+        if (!/^issuer-request-[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/.test(requestId)
+            || !/^[a-f0-9]{64}$/.test(requestSha256)
+            || createHash('sha256').update(canonicalResponseBytes).digest('hex') !== responseSha256) {
+            throw new ExecutorPhaseARunAuthorizationError('The issuer redemption record is invalid.');
+        }
+        timestamp(usedAt, 'usedAt');
+        const use = this.db.transaction(() => {
+            const readExisting = () => {
+                const existing = this.db.prepare(`
+                    SELECT grant_id, grant_sha256, sender_proof_sha256, request_sha256,
+                        canonical_response_bytes, response_sha256
+                    FROM executor_phase_a_issuer_redemptions
+                    WHERE tenant_id = ? AND request_id = ?
+                `).get(this.tenantId, requestId);
+                if (!existing)
+                    return null;
+                if (String(existing.grant_id) !== bundle.grant.payload.grantId
+                    || String(existing.grant_sha256) !== bundle.grantSha256
+                    || String(existing.sender_proof_sha256) !== bundle.senderProofSha256
+                    || String(existing.request_sha256) !== requestSha256) {
+                    throw new ExecutorPhaseARunAuthorizationError('The issuer request ID was already used for different redemption bytes.');
+                }
+                return {
+                    bytes: Buffer.from(existing.canonical_response_bytes),
+                    digest: String(existing.response_sha256),
+                    created: false,
+                    status: 'used',
+                };
+            };
+            const existing = readExisting();
+            if (existing)
+                return existing;
+            const grantId = bundle.grant.payload.grantId;
+            const row = this.db.prepare(`
+                SELECT capability_id, phase, expires_at FROM executor_phase_a_workload_grants
+                WHERE tenant_id = ? AND grant_id = ? AND status = 'issued'
+                    AND grant_sha256 = ? AND sender_proof_sha256 = ?
+            `).get(this.tenantId, grantId, bundle.grantSha256, bundle.senderProofSha256);
+            const capability = row?.capability_id ? this.findCapability(row.capability_id) : null;
+            const usedAtMs = timestamp(usedAt, 'usedAt');
+            const phaseDeadline = capability && row?.phase
+                ? timestamp(row.phase === 'cleanup' ? capability.cleanupDeadline : capability.mutationDeadline, 'phaseDeadline')
+                : Number.NaN;
+            if (!row?.capability_id || !row.phase || !row.expires_at || !capability || capability.status !== 'active'
+                || usedAtMs >= timestamp(row.expires_at, 'grantExpiresAt') || usedAtMs >= phaseDeadline) {
+                const retry = readExisting();
+                if (retry)
+                    return retry;
+                throw new ExecutorPhaseARunAuthorizationError('The workload grant is unavailable or revoked.');
+            }
+            const guard = this.db.prepare(`
+                UPDATE executor_phase_a_run_capabilities
+                SET updated_at = updated_at
+                WHERE tenant_id = ? AND capability_id = ? AND status = 'active'
+            `).run(this.tenantId, row.capability_id);
+            if (Number(guard.changes ?? guard.rowCount ?? 0) !== 1) {
+                throw new ExecutorPhaseARunAuthorizationError('The workload grant capability was hard-stopped before redemption.');
+            }
+            const result = this.db.prepare(`
+                UPDATE executor_phase_a_workload_grants
+                SET status = 'used', used_at = ?, updated_at = ?
+                WHERE tenant_id = ? AND grant_id = ? AND status = 'issued'
+            `).run(usedAt, usedAt, this.tenantId, grantId);
+            if (Number(result.changes ?? result.rowCount ?? 0) !== 1) {
+                const retry = readExisting();
+                if (retry)
+                    return retry;
+                throw new ExecutorPhaseARunAuthorizationError('The workload grant was already consumed or revoked.');
+            }
+            const inserted = this.db.prepare(`
+                INSERT INTO executor_phase_a_issuer_redemptions (
+                    request_id, tenant_id, grant_id, grant_sha256, sender_proof_sha256,
+                    request_sha256, canonical_response_bytes, response_sha256, redeemed_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT DO NOTHING
+            `).run(requestId, this.tenantId, grantId, bundle.grantSha256, bundle.senderProofSha256, requestSha256, canonicalResponseBytes, responseSha256, usedAt);
+            if (Number(inserted.changes ?? inserted.rowCount ?? 0) !== 1) {
+                const retry = readExisting();
+                if (retry)
+                    return retry;
+                throw new ExecutorPhaseARunAuthorizationError('The workload grant or issuer request was already redeemed.');
+            }
+            return { bytes: canonicalResponseBytes, digest: responseSha256, created: true, status: 'used' };
+        });
+        return use();
+    }
+    assertCapability(candidate) {
+        if (candidate.status !== 'active' || candidate.hardStoppedAt !== null) {
+            throw new ExecutorPhaseARunAuthorizationError('A new run capability must begin active and not hard-stopped.');
+        }
+        const issuedAt = timestamp(candidate.issuedAt, 'issuedAt');
+        const expiresAt = timestamp(candidate.expiresAt, 'expiresAt');
+        const mutationDeadline = timestamp(candidate.mutationDeadline, 'mutationDeadline');
+        const cleanupDeadline = timestamp(candidate.cleanupDeadline, 'cleanupDeadline');
+        const receipt = this.db.prepare(`
+            SELECT receipt_kind, original_capability_id, residual_inventory_sha256,
+                receipt_sha256, approved_at, expires_at
+            FROM executor_phase_a_approval_receipts
+            WHERE tenant_id = ? AND receipt_id = ?
+            LIMIT 1
+        `).get(this.tenantId, candidate.receiptId);
+        const receiptApprovedAt = receipt ? timestamp(String(receipt.approved_at), 'receipt.approvedAt') : NaN;
+        const receiptExpiresAt = receipt ? timestamp(String(receipt.expires_at), 'receipt.expiresAt') : NaN;
+        if (!receipt || String(receipt.receipt_sha256) !== candidate.receiptSha256
+            || String(receipt.receipt_kind) !== candidate.capabilityKind
+            || (receipt.original_capability_id == null ? null : String(receipt.original_capability_id)) !== candidate.originalCapabilityId
+            || (receipt.residual_inventory_sha256 == null ? null : String(receipt.residual_inventory_sha256)) !== candidate.residualInventorySha256
+            || issuedAt < receiptApprovedAt || issuedAt >= receiptExpiresAt || issuedAt >= cleanupDeadline) {
+            throw new ExecutorPhaseARunAuthorizationError('The run capability is not bound to a durable approval receipt.');
+        }
+        if (candidate.capabilityKind === 'main') {
+            if (candidate.originalCapabilityId !== null || candidate.residualInventorySha256 !== null
+                || mutationDeadline !== receiptApprovedAt + 8 * 60 * 60 * 1000
+                || cleanupDeadline !== receiptApprovedAt + EXECUTOR_PHASE_A_MAIN_CAPABILITY_TTL_MS
+                || expiresAt !== cleanupDeadline) {
+                throw new ExecutorPhaseARunAuthorizationError('The main capability lifetime or ancestry is invalid.');
+            }
+            return;
+        }
+        const original = candidate.originalCapabilityId
+            ? this.findCapability(candidate.originalCapabilityId)
+            : null;
+        if (!original || original.capabilityKind !== 'main' || original.status !== 'awaiting-cleanup-approval'
+            || !candidate.residualInventorySha256 || !/^[a-f0-9]{64}$/.test(candidate.residualInventorySha256)
+            || original.workspaceId !== candidate.workspaceId || original.taskId !== candidate.taskId
+            || original.runId !== candidate.runId
+            || original.accountId !== candidate.accountId || original.region !== candidate.region
+            || original.availabilityZone !== candidate.availabilityZone
+            || original.readPrincipalArn !== candidate.readPrincipalArn
+            || original.brokerKeyFingerprint !== candidate.brokerKeyFingerprint
+            || original.preflightSha256 !== candidate.preflightSha256
+            || original.logicalEnvelopeSha256 !== candidate.logicalEnvelopeSha256
+            || original.sourceCommit !== candidate.sourceCommit
+            || original.roleMapSha256 !== candidate.roleMapSha256
+            || original.oidcAudienceSha256 !== candidate.oidcAudienceSha256
+            || original.receiptId === candidate.receiptId
+            || mutationDeadline !== receiptApprovedAt || cleanupDeadline !== expiresAt
+            || cleanupDeadline !== receiptApprovedAt + EXECUTOR_PHASE_A_CLEANUP_CAPABILITY_TTL_MS) {
+            throw new ExecutorPhaseARunAuthorizationError('The cleanup capability requires a hard-stopped main run and a distinct bounded receipt.');
+        }
+    }
+}

package/dist/storage/githubReviewEvidenceInstallationStore.d.ts

@@ -0,0 +1,26 @@
+import type { DatabaseAdapter } from './databaseAdapter.js';
+export interface GitHubReviewEvidenceInstallationBinding {
+    workspaceId: string;
+    installationId: string;
+    accountId: string;
+    accountLogin: string;
+    accountType: string;
+    repositorySelection: string;
+    boundByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare class GitHubReviewEvidenceInstallationConflictError extends Error {
+    readonly code = "github_installation_already_bound";
+    readonly statusCode = 409;
+    constructor();
+}
+export declare class GitHubReviewEvidenceInstallationStore {
+    private readonly db;
+    private readonly tenantId;
+    private readonly now;
+    constructor(db: DatabaseAdapter, tenantId: string, now?: () => Date);
+    get(workspaceId: string): GitHubReviewEvidenceInstallationBinding | null;
+    put(input: Omit<GitHubReviewEvidenceInstallationBinding, 'createdAt' | 'updatedAt'>): GitHubReviewEvidenceInstallationBinding;
+    delete(workspaceId: string): boolean;
+}

package/dist/storage/githubReviewEvidenceInstallationStore.js

@@ -0,0 +1,89 @@
+export class GitHubReviewEvidenceInstallationConflictError extends Error {
+    code = 'github_installation_already_bound';
+    statusCode = 409;
+    constructor() {
+        super('This GitHub App installation is already bound to another workspace.');
+        this.name = 'GitHubReviewEvidenceInstallationConflictError';
+    }
+}
+export class GitHubReviewEvidenceInstallationStore {
+    db;
+    tenantId;
+    now;
+    constructor(db, tenantId, now = () => new Date()) {
+        this.db = db;
+        this.tenantId = tenantId;
+        this.now = now;
+    }
+    get(workspaceId) {
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedWorkspaceId)
+            return null;
+        const row = this.db.prepare(`
+            SELECT *
+            FROM github_review_evidence_installation_bindings
+            WHERE tenant_id = ? AND workspace_id = ?
+            LIMIT 1
+        `).get(this.tenantId, normalizedWorkspaceId);
+        if (!row)
+            return null;
+        return {
+            workspaceId: String(row.workspace_id || ''),
+            installationId: String(row.installation_id || ''),
+            accountId: String(row.account_id || ''),
+            accountLogin: String(row.account_login || ''),
+            accountType: String(row.account_type || ''),
+            repositorySelection: String(row.repository_selection || ''),
+            boundByUserId: String(row.bound_by_user_id || ''),
+            createdAt: String(row.created_at || ''),
+            updatedAt: String(row.updated_at || ''),
+        };
+    }
+    put(input) {
+        const workspaceId = String(input.workspaceId || '').trim();
+        if (!workspaceId)
+            throw new Error('workspaceId is required.');
+        const installationId = String(input.installationId || '').trim();
+        const accountId = String(input.accountId || '').trim();
+        const accountLogin = String(input.accountLogin || '').trim();
+        const boundByUserId = String(input.boundByUserId || '').trim();
+        if (!installationId || !accountId || !accountLogin || !boundByUserId) {
+            throw new Error('Installation, account, and binding actor are required.');
+        }
+        const now = this.now().toISOString();
+        try {
+            this.db.prepare(`
+                INSERT INTO github_review_evidence_installation_bindings (
+                    tenant_id, workspace_id, installation_id, account_id, account_login,
+                    account_type, repository_selection, bound_by_user_id, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
+                    installation_id = EXCLUDED.installation_id,
+                    account_id = EXCLUDED.account_id,
+                    account_login = EXCLUDED.account_login,
+                    account_type = EXCLUDED.account_type,
+                    repository_selection = EXCLUDED.repository_selection,
+                    bound_by_user_id = EXCLUDED.bound_by_user_id,
+                    updated_at = EXCLUDED.updated_at
+            `).run(this.tenantId, workspaceId, installationId, accountId, accountLogin, String(input.accountType || 'unknown').trim() || 'unknown', String(input.repositorySelection || 'selected').trim() || 'selected', boundByUserId, now, now);
+        }
+        catch (error) {
+            const message = String(error?.message || '').toLowerCase();
+            if (message.includes('unique') || message.includes('duplicate')) {
+                throw new GitHubReviewEvidenceInstallationConflictError();
+            }
+            throw error;
+        }
+        return this.get(workspaceId);
+    }
+    delete(workspaceId) {
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedWorkspaceId)
+            return false;
+        const result = this.db.prepare(`
+            DELETE FROM github_review_evidence_installation_bindings
+            WHERE tenant_id = ? AND workspace_id = ?
+        `).run(this.tenantId, normalizedWorkspaceId);
+        return Number(result?.changes || 0) > 0;
+    }
+}