@taskforcehq/taskforce 0.3.329 → 0.3.332

package/dist/services/executorPhaseAApprovalService.js

@@ -0,0 +1,609 @@
+import { createPrivateKey, createPublicKey, randomUUID, sign, verify } from 'crypto';
+import trustPolicyJson from '../shared/executorPhaseAApprovalTrustPolicy.json' with { type: 'json' };
+import { EXECUTOR_PHASE_A_MAX_PREFLIGHT_AGE_MS, EXECUTOR_PHASE_A_MAX_PREFLIGHT_BYTES, EXECUTOR_PHASE_A_MUTATION_TTL_MS, EXECUTOR_PHASE_A_ORDINARY_CLEANUP_TTL_MS, EXECUTOR_PHASE_A_PREFLIGHT_SCHEMA, EXECUTOR_PHASE_A_RECEIPT_PAYLOAD_SCHEMA, EXECUTOR_PHASE_A_RECEIPT_TTL_MS, EXECUTOR_PHASE_A_TRUST_POLICY_SCHEMA, canonicalizeExecutorPhaseAJson, sha256ExecutorPhaseABytes, } from '../shared/executorPhaseAApprovalReceipt.js';
+import { assertExecutorPhaseAAccountAuthorities, executorPhaseABrokerKeyFingerprint, executorPhaseARoleMapSha256, } from '../shared/executorPhaseARunAuthorization.js';
+import { assertExecutorPhaseASchema } from '../shared/executorPhaseASchemaValidation.js';
+const PREFLIGHT_KEYS = [
+    'approvalContext', 'authorities', 'baseAmi', 'budgets', 'collectedAt', 'expiresAt', 'failures',
+    'immutableInputs', 'logicalEnvelope', 'logicalEnvelopeSha256', 'pricing', 'quotas', 'requestSha256',
+    'runId', 'schema', 'secretNameScan', 'source', 'status', 'target',
+].sort();
+const FROZEN_PHASE_A_WORKSPACE_ID = 'workspace-019c771a-b6d7-7bc8-b837-c1133f3ba7a2';
+const FROZEN_PHASE_A_TASK_ID = 'task-62fecb296bbe07ca535b6e6630fc458f';
+const ISO_UTC_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+export class ExecutorPhaseAApprovalError extends Error {
+    statusCode;
+    code;
+    constructor(message, statusCode = 400, code = 'executor_phase_a_approval_invalid') {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.name = 'ExecutorPhaseAApprovalError';
+    }
+}
+export function assertExecutorPhaseAApprovalTrustPolicy(policy) {
+    if (policy.schema !== EXECUTOR_PHASE_A_TRUST_POLICY_SCHEMA
+        || policy.issuer !== 'https://performance-app.taskforcehq.ai'
+        || policy.audience !== 'taskforce-agent-executor-phase-a'
+        || policy.environment !== 'performance'
+        || policy.workspaceId !== FROZEN_PHASE_A_WORKSPACE_ID
+        || policy.taskId !== FROZEN_PHASE_A_TASK_ID
+        || policy.taskReference !== 'T-1653'
+        || !Array.isArray(policy.keys)) {
+        throw new Error('The committed Phase A approval trust policy has an invalid frozen authority contract.');
+    }
+    const keyIds = new Set();
+    for (const key of policy.keys) {
+        const validFrom = ISO_UTC_TIMESTAMP.test(key.validFrom) ? Date.parse(key.validFrom) : Number.NaN;
+        const validUntil = ISO_UTC_TIMESTAMP.test(key.validUntil) ? Date.parse(key.validUntil) : Number.NaN;
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(key.keyId) || keyIds.has(key.keyId)
+            || !['active', 'retired', 'disabled'].includes(key.status)
+            || !Number.isFinite(validFrom) || !Number.isFinite(validUntil)
+            || validFrom >= validUntil) {
+            throw new Error('The committed Phase A approval trust policy contains an invalid or duplicate key entry.');
+        }
+        keyIds.add(key.keyId);
+        try {
+            const encoded = String(key.publicKeySpkiBase64 || '');
+            const der = Buffer.from(encoded, 'base64');
+            const publicKey = createPublicKey({ key: der, format: 'der', type: 'spki' });
+            if (publicKey.asymmetricKeyType !== 'ed25519' || der.toString('base64') !== encoded)
+                throw new Error('invalid');
+        }
+        catch {
+            throw new Error(`The committed Phase A approval trust key ${key.keyId} is not canonical Ed25519 SPKI.`);
+        }
+    }
+}
+export function resolveExecutorPhaseAApprovalTrustKey(policy, keyId, signedAt, usage) {
+    const timestamp = Date.parse(signedAt);
+    if (!Number.isFinite(timestamp))
+        return null;
+    const key = policy.keys.find((candidate) => candidate.keyId === keyId);
+    if (!key || key.status === 'disabled')
+        return null;
+    if (usage === 'sign' && key.status !== 'active')
+        return null;
+    const validFrom = Date.parse(key.validFrom);
+    const validUntil = Date.parse(key.validUntil);
+    if (!Number.isFinite(validFrom) || timestamp < validFrom
+        || !Number.isFinite(validUntil) || timestamp >= validUntil)
+        return null;
+    return key;
+}
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function parseIso(value, field) {
+    if (typeof value !== 'string' || !ISO_UTC_TIMESTAMP.test(value)) {
+        throw new ExecutorPhaseAApprovalError(`${field} must be an ISO 8601 UTC timestamp.`);
+    }
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        throw new ExecutorPhaseAApprovalError(`${field} is invalid.`);
+    return timestamp;
+}
+function boundedMoney(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0 || value > 1_000_000_000_000) {
+        throw new ExecutorPhaseAApprovalError(`${field} must be a positive bounded safe integer.`);
+    }
+    return value;
+}
+function assertIJson(value, path = '$') {
+    if (typeof value === 'number' && Number.isInteger(value) && !Number.isSafeInteger(value)) {
+        throw new ExecutorPhaseAApprovalError(`Preflight contains an unsafe I-JSON integer at ${path}.`);
+    }
+    if (typeof value === 'string' && /[\uD800-\uDFFF]/u.test(value.replace(/[\uD800-\uDBFF][\uDC00-\uDFFF]/gu, ''))) {
+        throw new ExecutorPhaseAApprovalError(`Preflight contains invalid Unicode at ${path}.`);
+    }
+    if (Array.isArray(value))
+        value.forEach((item, index) => assertIJson(item, `${path}[${index}]`));
+    else if (value && typeof value === 'object') {
+        for (const [key, child] of Object.entries(value))
+            assertIJson(child, `${path}.${key}`);
+    }
+}
+export function parseCanonicalExecutorPhaseAPreflight(bytes, policy, now = new Date()) {
+    assertExecutorPhaseAApprovalTrustPolicy(policy);
+    if (bytes.length === 0 || bytes.length > EXECUTOR_PHASE_A_MAX_PREFLIGHT_BYTES) {
+        throw new ExecutorPhaseAApprovalError('Preflight size is outside the allowed bounds.', 413);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new ExecutorPhaseAApprovalError('Preflight must be valid UTF-8 JSON.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ExecutorPhaseAApprovalError('Preflight must be a JSON object.');
+    }
+    const input = parsed;
+    assertIJson(input);
+    if (!exactKeys(input, PREFLIGHT_KEYS))
+        throw new ExecutorPhaseAApprovalError('Preflight fields do not match the Phase A schema.');
+    const canonical = canonicalizeExecutorPhaseAJson(input);
+    if (!canonical.equals(bytes))
+        throw new ExecutorPhaseAApprovalError('Preflight bytes must be RFC 8785 canonical JSON.');
+    try {
+        assertExecutorPhaseASchema('report', input);
+    }
+    catch {
+        throw new ExecutorPhaseAApprovalError('Preflight fields do not match the Phase A schema.');
+    }
+    if (input.schema !== EXECUTOR_PHASE_A_PREFLIGHT_SCHEMA || input.status !== 'pass') {
+        throw new ExecutorPhaseAApprovalError('Preflight is not a passing Phase A v3 preflight.');
+    }
+    if (!Array.isArray(input.failures) || input.failures.length !== 0) {
+        throw new ExecutorPhaseAApprovalError('Preflight contains failures.');
+    }
+    const approvalContext = input.approvalContext;
+    const target = input.target;
+    const source = input.source;
+    const budgets = input.budgets;
+    if (!approvalContext || Array.isArray(approvalContext) || !target || Array.isArray(target)
+        || !source || Array.isArray(source) || !budgets || Array.isArray(budgets)) {
+        throw new ExecutorPhaseAApprovalError('Preflight binding objects are invalid.');
+    }
+    if (approvalContext.workspaceId !== policy.workspaceId
+        || approvalContext.taskId !== policy.taskId
+        || approvalContext.taskReference !== policy.taskReference
+        || approvalContext.environment !== policy.environment
+        || target.region !== 'us-west-2') {
+        throw new ExecutorPhaseAApprovalError('Preflight authority or deployment scope is not approved.');
+    }
+    if (typeof input.runId !== 'string' || !/^phase-a-[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(input.runId)) {
+        throw new ExecutorPhaseAApprovalError('runId is invalid.');
+    }
+    if (typeof source.commit !== 'string' || !/^[a-f0-9]{40}$/.test(source.commit) || source.clean !== true) {
+        throw new ExecutorPhaseAApprovalError('Preflight source must be clean and use a full lowercase Git hash.');
+    }
+    if (typeof input.logicalEnvelopeSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(input.logicalEnvelopeSha256)) {
+        throw new ExecutorPhaseAApprovalError('logicalEnvelopeSha256 is invalid.');
+    }
+    const computedLogicalEnvelopeSha256 = sha256ExecutorPhaseABytes(canonicalizeExecutorPhaseAJson(input.logicalEnvelope));
+    if (input.logicalEnvelopeSha256 !== computedLogicalEnvelopeSha256) {
+        throw new ExecutorPhaseAApprovalError('logicalEnvelopeSha256 does not match the canonical logical envelope.');
+    }
+    if (typeof target.accountId !== 'string' || !/^\d{12}$/.test(target.accountId)) {
+        throw new ExecutorPhaseAApprovalError('Preflight target accountId is invalid.');
+    }
+    if (typeof target.readPrincipalArn !== 'string' || !/^arn:aws:(?:iam::\d{12}:(?:user|role)\/[A-Za-z0-9+=,.@_\/-]+|sts::\d{12}:assumed-role\/[A-Za-z0-9+=,.@_\/-]+)$/.test(target.readPrincipalArn)) {
+        throw new ExecutorPhaseAApprovalError('Preflight target readPrincipalArn is invalid.');
+    }
+    try {
+        assertExecutorPhaseAAccountAuthorities(String(target.accountId), String(target.readPrincipalArn), target.mutationRoles);
+        if (executorPhaseABrokerKeyFingerprint(String(target.brokerPublicKeySpkiBase64 || '')) !== target.brokerKeyFingerprint) {
+            throw new TypeError('fingerprint mismatch');
+        }
+    }
+    catch {
+        throw new ExecutorPhaseAApprovalError('Preflight mutation roles or broker public-key binding is invalid.');
+    }
+    if (typeof target.availabilityZone !== 'string' || !/^us-west-2[a-z]$/.test(target.availabilityZone)) {
+        throw new ExecutorPhaseAApprovalError('availabilityZone must be one us-west-2 Availability Zone.');
+    }
+    const temporaryBudgetUsdMicros = boundedMoney(budgets.temporaryUsdMicros, 'temporaryUsdMicros');
+    const alarmUsdMicros = boundedMoney(budgets.alarmUsdMicros, 'alarmUsdMicros');
+    boundedMoney(budgets.foundationMonthlyCeilingUsdMicros, 'foundationMonthlyCeilingUsdMicros');
+    if (alarmUsdMicros > temporaryBudgetUsdMicros) {
+        throw new ExecutorPhaseAApprovalError('alarmUsdMicros cannot exceed temporaryUsdMicros.');
+    }
+    const collectedAt = parseIso(input.collectedAt, 'collectedAt');
+    const expiresAt = parseIso(input.expiresAt, 'expiresAt');
+    const nowMs = now.getTime();
+    if (collectedAt > nowMs || collectedAt < nowMs - EXECUTOR_PHASE_A_MAX_PREFLIGHT_AGE_MS) {
+        throw new ExecutorPhaseAApprovalError('Preflight is stale or from the future.');
+    }
+    if (expiresAt <= nowMs || expiresAt > collectedAt + EXECUTOR_PHASE_A_MAX_PREFLIGHT_AGE_MS) {
+        throw new ExecutorPhaseAApprovalError('Preflight expiry is invalid or has elapsed.');
+    }
+    return input;
+}
+function durableRecordInvalid(message) {
+    throw new ExecutorPhaseAApprovalError(`The durable Phase A approval winner is unusable: ${message}`, 500, 'executor_phase_a_approval_durable_record_invalid');
+}
+function assertUsableDurableWinner(record, preflight, canonicalPreflightBytes, policy, now) {
+    let receipt;
+    try {
+        const parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(record.canonicalReceiptBytes));
+        assertIJson(parsed);
+        assertExecutorPhaseASchema('approvalReceipt', parsed);
+        if (!canonicalizeExecutorPhaseAJson(parsed).equals(record.canonicalReceiptBytes))
+            durableRecordInvalid('receipt bytes are not canonical JSON.');
+        receipt = parsed;
+    }
+    catch (error) {
+        if (error instanceof ExecutorPhaseAApprovalError)
+            throw error;
+        durableRecordInvalid('receipt bytes do not satisfy the approval receipt contract.');
+    }
+    const payloadBytes = canonicalizeExecutorPhaseAJson(receipt.payload);
+    const preflightSha256 = sha256ExecutorPhaseABytes(canonicalPreflightBytes);
+    const receiptSha256 = sha256ExecutorPhaseABytes(record.canonicalReceiptBytes);
+    if (!record.canonicalPreflightBytes.equals(canonicalPreflightBytes)
+        || record.preflightSha256 !== preflightSha256
+        || record.logicalEnvelopeSha256 !== preflight.logicalEnvelopeSha256
+        || record.receiptSha256 !== receiptSha256) {
+        durableRecordInvalid('stored hashes or canonical preflight bytes are inconsistent.');
+    }
+    const payload = receipt.payload;
+    const approvedAt = Date.parse(payload.approvedAt);
+    const expiresAt = Date.parse(payload.expiresAt);
+    if (payload.receiptId !== record.receiptId
+        || record.receiptKind !== 'main'
+        || record.originalCapabilityId !== null
+        || record.residualInventorySha256 !== null
+        || payload.receiptKind !== 'main'
+        || payload.originalCapabilityId !== null
+        || payload.residualInventorySha256 !== null
+        || payload.issuer !== policy.issuer
+        || payload.audience !== policy.audience
+        || payload.environment !== policy.environment
+        || payload.workspaceId !== record.workspaceId
+        || payload.taskId !== record.taskId
+        || payload.taskReference !== record.taskReference
+        || payload.actorUserId !== record.actorUserId
+        || payload.runId !== record.runId
+        || payload.preflightSha256 !== record.preflightSha256
+        || payload.logicalEnvelopeSha256 !== record.logicalEnvelopeSha256
+        || payload.accountId !== preflight.target.accountId
+        || payload.readPrincipalArn !== preflight.target.readPrincipalArn
+        || !canonicalizeExecutorPhaseAJson(payload.mutationRoles).equals(canonicalizeExecutorPhaseAJson(preflight.target.mutationRoles))
+        || payload.roleMapSha256 !== executorPhaseARoleMapSha256(preflight.target.mutationRoles)
+        || payload.oidcIssuer !== preflight.target.oidcIssuer
+        || payload.oidcAudience !== preflight.target.oidcAudience
+        || payload.brokerPublicKeySpkiBase64 !== preflight.target.brokerPublicKeySpkiBase64
+        || payload.brokerKeyFingerprint !== preflight.target.brokerKeyFingerprint
+        || payload.region !== preflight.target.region
+        || payload.availabilityZone !== preflight.target.availabilityZone
+        || !canonicalizeExecutorPhaseAJson(payload.budgets).equals(canonicalizeExecutorPhaseAJson(preflight.budgets))
+        || payload.sourceCommit !== preflight.source.commit
+        || payload.approvedAt !== record.approvedAt
+        || payload.expiresAt !== record.expiresAt
+        || payload.mutationDeadline !== new Date(approvedAt + EXECUTOR_PHASE_A_MUTATION_TTL_MS).toISOString()
+        || payload.cleanupDeadline !== new Date(approvedAt + EXECUTOR_PHASE_A_ORDINARY_CLEANUP_TTL_MS).toISOString()
+        || receipt.envelope.keyId !== record.keyId
+        || receipt.envelope.payloadSha256 !== sha256ExecutorPhaseABytes(payloadBytes)) {
+        durableRecordInvalid('receipt bindings do not match the durable record and preflight.');
+    }
+    if (!Number.isFinite(approvedAt) || approvedAt > now.getTime()
+        || !Number.isFinite(expiresAt) || expiresAt <= now.getTime()
+        || expiresAt > Date.parse(preflight.expiresAt)) {
+        durableRecordInvalid('receipt validity interval cannot be used.');
+    }
+    const trustKey = resolveExecutorPhaseAApprovalTrustKey(policy, receipt.envelope.keyId, payload.approvedAt, 'verify');
+    if (!trustKey)
+        durableRecordInvalid('receipt signing key is not trusted for its approval time.');
+    const signature = Buffer.from(receipt.envelope.signature, 'base64url');
+    if (signature.length !== 64 || signature.toString('base64url') !== receipt.envelope.signature) {
+        durableRecordInvalid('receipt signature encoding is not canonical.');
+    }
+    const publicKey = createPublicKey({ key: Buffer.from(trustKey.publicKeySpkiBase64, 'base64'), format: 'der', type: 'spki' });
+    if (!verify(null, payloadBytes, publicKey, signature))
+        durableRecordInvalid('receipt signature is invalid.');
+}
+function assertUsableCleanupWinner(record, originalCapabilityId, residualInventorySha256, preflight, policy, now) {
+    let receipt;
+    try {
+        const parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(record.canonicalReceiptBytes));
+        assertIJson(parsed);
+        assertExecutorPhaseASchema('approvalReceipt', parsed);
+        if (!canonicalizeExecutorPhaseAJson(parsed).equals(record.canonicalReceiptBytes)) {
+            durableRecordInvalid('cleanup receipt bytes are not canonical JSON.');
+        }
+        receipt = parsed;
+    }
+    catch (error) {
+        if (error instanceof ExecutorPhaseAApprovalError)
+            throw error;
+        durableRecordInvalid('cleanup receipt bytes do not satisfy the approval receipt contract.');
+    }
+    const payload = receipt.payload;
+    const payloadBytes = canonicalizeExecutorPhaseAJson(payload);
+    const approvedAt = Date.parse(payload.approvedAt);
+    const expiresAt = Date.parse(payload.expiresAt);
+    const cleanupDeadline = Date.parse(payload.cleanupDeadline);
+    if (record.receiptKind !== 'cleanup-only'
+        || record.originalCapabilityId !== originalCapabilityId
+        || record.residualInventorySha256 !== residualInventorySha256
+        || payload.receiptId !== record.receiptId
+        || payload.receiptKind !== 'cleanup-only'
+        || payload.originalCapabilityId !== originalCapabilityId
+        || payload.residualInventorySha256 !== residualInventorySha256
+        || payload.issuer !== policy.issuer || payload.audience !== policy.audience
+        || payload.environment !== policy.environment
+        || payload.workspaceId !== record.workspaceId || payload.taskId !== record.taskId
+        || payload.taskReference !== record.taskReference || payload.actorUserId !== record.actorUserId
+        || payload.runId !== record.runId || payload.preflightSha256 !== record.preflightSha256
+        || payload.logicalEnvelopeSha256 !== record.logicalEnvelopeSha256
+        || payload.accountId !== preflight.target.accountId
+        || payload.readPrincipalArn !== preflight.target.readPrincipalArn
+        || !canonicalizeExecutorPhaseAJson(payload.mutationRoles).equals(canonicalizeExecutorPhaseAJson(preflight.target.mutationRoles))
+        || payload.roleMapSha256 !== executorPhaseARoleMapSha256(preflight.target.mutationRoles)
+        || payload.oidcIssuer !== preflight.target.oidcIssuer || payload.oidcAudience !== preflight.target.oidcAudience
+        || payload.brokerPublicKeySpkiBase64 !== preflight.target.brokerPublicKeySpkiBase64
+        || payload.brokerKeyFingerprint !== preflight.target.brokerKeyFingerprint
+        || payload.region !== preflight.target.region || payload.availabilityZone !== preflight.target.availabilityZone
+        || !canonicalizeExecutorPhaseAJson(payload.budgets).equals(canonicalizeExecutorPhaseAJson(preflight.budgets))
+        || payload.sourceCommit !== preflight.source.commit
+        || payload.approvedAt !== record.approvedAt || payload.expiresAt !== record.expiresAt
+        || payload.mutationDeadline !== payload.approvedAt
+        || !Number.isFinite(approvedAt) || approvedAt > now.getTime()
+        || !Number.isFinite(expiresAt) || expiresAt <= now.getTime()
+        || expiresAt > approvedAt + EXECUTOR_PHASE_A_RECEIPT_TTL_MS
+        || !Number.isFinite(cleanupDeadline) || cleanupDeadline <= approvedAt
+        || cleanupDeadline > approvedAt + 2 * 60 * 60 * 1000
+        || receipt.envelope.keyId !== record.keyId
+        || receipt.envelope.payloadSha256 !== sha256ExecutorPhaseABytes(payloadBytes)
+        || record.receiptSha256 !== sha256ExecutorPhaseABytes(record.canonicalReceiptBytes)) {
+        durableRecordInvalid('cleanup receipt bindings do not match the hard-stopped run.');
+    }
+    const trustKey = resolveExecutorPhaseAApprovalTrustKey(policy, receipt.envelope.keyId, payload.approvedAt, 'verify');
+    if (!trustKey)
+        durableRecordInvalid('cleanup receipt signing key is not trusted for its approval time.');
+    const signature = Buffer.from(receipt.envelope.signature, 'base64url');
+    if (signature.length !== 64 || signature.toString('base64url') !== receipt.envelope.signature) {
+        durableRecordInvalid('cleanup receipt signature encoding is not canonical.');
+    }
+    const publicKey = createPublicKey({ key: Buffer.from(trustKey.publicKeySpkiBase64, 'base64'), format: 'der', type: 'spki' });
+    if (!verify(null, payloadBytes, publicKey, signature))
+        durableRecordInvalid('cleanup receipt signature is invalid.');
+}
+export function resolveExecutorPhaseAApprovalSigningConfig(env = process.env, policy = trustPolicyJson) {
+    assertExecutorPhaseAApprovalTrustPolicy(policy);
+    const enabledRaw = String(env.TASKFORCE_PHASE_A_APPROVAL_ISSUER_ENABLED || 'false').trim().toLowerCase();
+    if (!['true', 'false', '1', '0', 'yes', 'no', 'on', 'off'].includes(enabledRaw)) {
+        throw new Error('TASKFORCE_PHASE_A_APPROVAL_ISSUER_ENABLED must be a boolean.');
+    }
+    const enabled = ['true', '1', 'yes', 'on'].includes(enabledRaw);
+    const keyId = String(env.TASKFORCE_PHASE_A_APPROVAL_SIGNING_KEY_ID || '').trim();
+    const encoded = String(env.TASKFORCE_PHASE_A_APPROVAL_SIGNING_PRIVATE_KEY_PKCS8_BASE64 || '').trim();
+    if (!keyId && !encoded) {
+        if (enabled)
+            throw new Error('Phase A approval signing key configuration is required when the issuer is enabled.');
+        return null;
+    }
+    if (!keyId || !encoded)
+        throw new Error('TASKFORCE_PHASE_A_APPROVAL_SIGNING_KEY_ID and TASKFORCE_PHASE_A_APPROVAL_SIGNING_PRIVATE_KEY_PKCS8_BASE64 must be configured together.');
+    let privateKey;
+    try {
+        const der = Buffer.from(encoded, 'base64');
+        if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || der.toString('base64') !== encoded)
+            throw new Error('invalid');
+        privateKey = createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+    }
+    catch {
+        throw new Error('TASKFORCE_PHASE_A_APPROVAL_SIGNING_PRIVATE_KEY_PKCS8_BASE64 must contain a base64-encoded PKCS#8 private key.');
+    }
+    if (privateKey.asymmetricKeyType !== 'ed25519')
+        throw new Error('The Phase A approval private key must be Ed25519.');
+    const now = Date.now();
+    const trusted = policy.keys.find((key) => key.keyId === keyId && key.status === 'active'
+        && Date.parse(key.validFrom) <= now && now < Date.parse(key.validUntil));
+    if (!trusted)
+        throw new Error(`The Phase A approval key ID ${keyId} is not an active in-validity key in the committed trust policy.`);
+    const derivedSpki = createPublicKey(privateKey).export({ format: 'der', type: 'spki' }).toString('base64');
+    if (derivedSpki !== trusted.publicKeySpkiBase64)
+        throw new Error('The Phase A approval private key does not match its committed trust-policy public key.');
+    return enabled ? { keyId, privateKey } : null;
+}
+export class ExecutorPhaseAApprovalService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    issue(canonicalPreflightBytes, actorUserId) {
+        const policy = this.options.policy || trustPolicyJson;
+        const now = this.options.now?.() || new Date();
+        const preflight = parseCanonicalExecutorPhaseAPreflight(canonicalPreflightBytes, policy, now);
+        if (!/^user-[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/.test(actorUserId)) {
+            throw new ExecutorPhaseAApprovalError('The approval actor must be an authenticated Taskforce human user.', 403);
+        }
+        const preflightSha256 = sha256ExecutorPhaseABytes(canonicalPreflightBytes);
+        const existing = this.options.store.findRun(preflight.approvalContext.workspaceId, preflight.approvalContext.taskId, preflight.runId);
+        if (existing) {
+            const retry = this.options.store.persist({
+                ...existing,
+                actorUserId,
+                preflightSha256,
+                logicalEnvelopeSha256: preflight.logicalEnvelopeSha256,
+                canonicalPreflightBytes,
+            });
+            assertUsableDurableWinner(retry.record, preflight, canonicalPreflightBytes, policy, now);
+            return { bytes: retry.record.canonicalReceiptBytes, receiptId: retry.record.receiptId, digest: retry.record.receiptSha256, created: false };
+        }
+        const approvedAt = now.toISOString();
+        const receiptExpiresAt = new Date(Math.min(Date.parse(preflight.expiresAt), now.getTime() + EXECUTOR_PHASE_A_RECEIPT_TTL_MS)).toISOString();
+        const signingTrustKey = resolveExecutorPhaseAApprovalTrustKey(policy, this.options.signing.keyId, approvedAt, 'sign');
+        const signingPublicKey = createPublicKey(this.options.signing.privateKey).export({ format: 'der', type: 'spki' }).toString('base64');
+        if (!signingTrustKey || signingPublicKey !== signingTrustKey.publicKeySpkiBase64) {
+            throw new ExecutorPhaseAApprovalError('The Phase A approval signing key is no longer active and trusted.', 503, 'executor_phase_a_approval_signer_unavailable');
+        }
+        const receiptId = this.options.randomId?.() || `approval-receipt-${randomUUID()}`;
+        if (!/^(?:approval-receipt|taskforce-approval)-[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/.test(receiptId)) {
+            throw new Error('The Phase A approval receipt ID generator returned an invalid identifier.');
+        }
+        const payload = {
+            schema: EXECUTOR_PHASE_A_RECEIPT_PAYLOAD_SCHEMA,
+            receiptId,
+            receiptKind: 'main',
+            originalCapabilityId: null,
+            residualInventorySha256: null,
+            issuer: policy.issuer,
+            audience: policy.audience,
+            environment: policy.environment,
+            workspaceId: preflight.approvalContext.workspaceId,
+            taskId: preflight.approvalContext.taskId,
+            taskReference: preflight.approvalContext.taskReference,
+            actorUserId,
+            runId: preflight.runId,
+            preflightSha256,
+            logicalEnvelopeSha256: preflight.logicalEnvelopeSha256,
+            accountId: preflight.target.accountId,
+            readPrincipalArn: preflight.target.readPrincipalArn,
+            mutationRoles: structuredClone(preflight.target.mutationRoles),
+            roleMapSha256: executorPhaseARoleMapSha256(preflight.target.mutationRoles),
+            oidcIssuer: preflight.target.oidcIssuer,
+            oidcAudience: preflight.target.oidcAudience,
+            brokerPublicKeySpkiBase64: preflight.target.brokerPublicKeySpkiBase64,
+            brokerKeyFingerprint: preflight.target.brokerKeyFingerprint,
+            region: preflight.target.region,
+            availabilityZone: preflight.target.availabilityZone,
+            budgets: structuredClone(preflight.budgets),
+            sourceCommit: preflight.source.commit,
+            approvedAt,
+            expiresAt: receiptExpiresAt,
+            mutationDeadline: new Date(now.getTime() + EXECUTOR_PHASE_A_MUTATION_TTL_MS).toISOString(),
+            cleanupDeadline: new Date(now.getTime() + EXECUTOR_PHASE_A_ORDINARY_CLEANUP_TTL_MS).toISOString(),
+        };
+        const payloadBytes = canonicalizeExecutorPhaseAJson(payload);
+        const receipt = {
+            payload,
+            envelope: {
+                algorithm: 'Ed25519',
+                keyId: this.options.signing.keyId,
+                payloadSha256: sha256ExecutorPhaseABytes(payloadBytes),
+                signature: sign(null, payloadBytes, this.options.signing.privateKey).toString('base64url'),
+            },
+        };
+        const receiptBytes = canonicalizeExecutorPhaseAJson(receipt);
+        const receiptSha256 = sha256ExecutorPhaseABytes(receiptBytes);
+        const persisted = this.options.store.persist({
+            receiptId: payload.receiptId,
+            workspaceId: payload.workspaceId,
+            taskId: payload.taskId,
+            taskReference: payload.taskReference,
+            runId: payload.runId,
+            receiptKind: payload.receiptKind,
+            originalCapabilityId: payload.originalCapabilityId,
+            residualInventorySha256: payload.residualInventorySha256,
+            actorUserId,
+            preflightSha256,
+            logicalEnvelopeSha256: payload.logicalEnvelopeSha256,
+            canonicalPreflightBytes,
+            canonicalReceiptBytes: receiptBytes,
+            receiptSha256,
+            keyId: this.options.signing.keyId,
+            approvedAt,
+            expiresAt: receiptExpiresAt,
+            createdAt: approvedAt,
+        });
+        assertUsableDurableWinner(persisted.record, preflight, canonicalPreflightBytes, policy, now);
+        return {
+            bytes: persisted.record.canonicalReceiptBytes,
+            receiptId: persisted.record.receiptId,
+            digest: persisted.record.receiptSha256,
+            created: persisted.created,
+        };
+    }
+    issueCleanup(originalCapabilityId, residualInventorySha256, actorUserId) {
+        const policy = this.options.policy || trustPolicyJson;
+        const now = this.options.now?.() || new Date();
+        if (!/^user-[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/.test(actorUserId)) {
+            throw new ExecutorPhaseAApprovalError('The cleanup approval actor must be an authenticated Taskforce human user.', 403);
+        }
+        if (!/^run-capability-[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/.test(originalCapabilityId)
+            || !/^[a-f0-9]{64}$/.test(residualInventorySha256)) {
+            throw new ExecutorPhaseAApprovalError('Cleanup approval requires an original capability and residual-inventory digest.');
+        }
+        const original = this.options.runAuthorizationStore?.findCapability(originalCapabilityId);
+        if (!original || original.capabilityKind !== 'main' || original.status !== 'awaiting-cleanup-approval') {
+            throw new ExecutorPhaseAApprovalError('Cleanup approval requires the exact hard-stopped main capability.', 409);
+        }
+        const mainRecord = this.options.store.findRun(original.workspaceId, original.taskId, original.runId, 'main');
+        if (!mainRecord || mainRecord.receiptId !== original.receiptId
+            || mainRecord.receiptSha256 !== original.receiptSha256
+            || mainRecord.preflightSha256 !== original.preflightSha256
+            || mainRecord.logicalEnvelopeSha256 !== original.logicalEnvelopeSha256) {
+            throw new ExecutorPhaseAApprovalError('The original capability has no matching durable main approval.', 409);
+        }
+        const originalIssuedAt = new Date(original.issuedAt);
+        const preflight = parseCanonicalExecutorPhaseAPreflight(mainRecord.canonicalPreflightBytes, policy, originalIssuedAt);
+        assertUsableDurableWinner(mainRecord, preflight, mainRecord.canonicalPreflightBytes, policy, originalIssuedAt);
+        const approvedAt = now.toISOString();
+        const signingTrustKey = resolveExecutorPhaseAApprovalTrustKey(policy, this.options.signing.keyId, approvedAt, 'sign');
+        const signingPublicKey = createPublicKey(this.options.signing.privateKey).export({ format: 'der', type: 'spki' }).toString('base64');
+        if (!signingTrustKey || signingPublicKey !== signingTrustKey.publicKeySpkiBase64) {
+            throw new ExecutorPhaseAApprovalError('The Phase A approval signing key is no longer active and trusted.', 503, 'executor_phase_a_approval_signer_unavailable');
+        }
+        const receiptId = this.options.randomId?.() || `approval-receipt-${randomUUID()}`;
+        if (!/^(?:approval-receipt|taskforce-approval)-[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/.test(receiptId)
+            || receiptId === original.receiptId) {
+            throw new Error('The Phase A cleanup receipt ID generator returned an invalid or reused identifier.');
+        }
+        const payload = {
+            schema: EXECUTOR_PHASE_A_RECEIPT_PAYLOAD_SCHEMA,
+            receiptId,
+            receiptKind: 'cleanup-only',
+            originalCapabilityId,
+            residualInventorySha256,
+            issuer: policy.issuer,
+            audience: policy.audience,
+            environment: policy.environment,
+            workspaceId: preflight.approvalContext.workspaceId,
+            taskId: preflight.approvalContext.taskId,
+            taskReference: preflight.approvalContext.taskReference,
+            actorUserId,
+            runId: preflight.runId,
+            preflightSha256: mainRecord.preflightSha256,
+            logicalEnvelopeSha256: preflight.logicalEnvelopeSha256,
+            accountId: preflight.target.accountId,
+            readPrincipalArn: preflight.target.readPrincipalArn,
+            mutationRoles: structuredClone(preflight.target.mutationRoles),
+            roleMapSha256: executorPhaseARoleMapSha256(preflight.target.mutationRoles),
+            oidcIssuer: preflight.target.oidcIssuer,
+            oidcAudience: preflight.target.oidcAudience,
+            brokerPublicKeySpkiBase64: preflight.target.brokerPublicKeySpkiBase64,
+            brokerKeyFingerprint: preflight.target.brokerKeyFingerprint,
+            region: preflight.target.region,
+            availabilityZone: preflight.target.availabilityZone,
+            budgets: structuredClone(preflight.budgets),
+            sourceCommit: preflight.source.commit,
+            approvedAt,
+            expiresAt: new Date(now.getTime() + EXECUTOR_PHASE_A_RECEIPT_TTL_MS).toISOString(),
+            mutationDeadline: approvedAt,
+            cleanupDeadline: new Date(now.getTime() + 2 * 60 * 60 * 1000).toISOString(),
+        };
+        const payloadBytes = canonicalizeExecutorPhaseAJson(payload);
+        const receipt = {
+            payload,
+            envelope: {
+                algorithm: 'Ed25519',
+                keyId: this.options.signing.keyId,
+                payloadSha256: sha256ExecutorPhaseABytes(payloadBytes),
+                signature: sign(null, payloadBytes, this.options.signing.privateKey).toString('base64url'),
+            },
+        };
+        const receiptBytes = canonicalizeExecutorPhaseAJson(receipt);
+        const receiptSha256 = sha256ExecutorPhaseABytes(receiptBytes);
+        const persisted = this.options.store.persist({
+            receiptId,
+            workspaceId: original.workspaceId,
+            taskId: original.taskId,
+            taskReference: preflight.approvalContext.taskReference,
+            runId: original.runId,
+            receiptKind: 'cleanup-only',
+            originalCapabilityId,
+            residualInventorySha256,
+            actorUserId,
+            preflightSha256: mainRecord.preflightSha256,
+            logicalEnvelopeSha256: mainRecord.logicalEnvelopeSha256,
+            canonicalPreflightBytes: mainRecord.canonicalPreflightBytes,
+            canonicalReceiptBytes: receiptBytes,
+            receiptSha256,
+            keyId: this.options.signing.keyId,
+            approvedAt,
+            expiresAt: payload.expiresAt,
+            createdAt: approvedAt,
+        });
+        assertUsableCleanupWinner(persisted.record, originalCapabilityId, residualInventorySha256, preflight, policy, now);
+        return {
+            bytes: persisted.record.canonicalReceiptBytes,
+            receiptId: persisted.record.receiptId,
+            digest: persisted.record.receiptSha256,
+            created: persisted.created,
+        };
+    }
+}