@taskforcehq/taskforce 0.3.329 → 0.3.332

package/dist/services/executorPhaseAIssuerCore.js

@@ -0,0 +1,402 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { canonicalizeExecutorPhaseAJson, } from '../shared/executorPhaseAApprovalReceipt.js';
+import { executorPhaseAIssuerProofSignedBytes, executorPhaseAIssuerRedemptionAuditSha256, executorPhaseAIssuerRedemptionIntentSha256, EXECUTOR_PHASE_A_ISSUER_PROOF_PAYLOAD_SCHEMA, EXECUTOR_PHASE_A_ISSUER_PROOF_SCHEMA, EXECUTOR_PHASE_A_ISSUER_PROOF_TYPE, EXECUTOR_PHASE_A_ISSUER_REDEMPTION_PATH, EXECUTOR_PHASE_A_ISSUER_REDEMPTION_REQUEST_SCHEMA, } from '../shared/executorPhaseAIssuerContracts.js';
+import { executorPhaseASourceIdentity, verifyExecutorPhaseARunCapabilityArtifact, verifyExecutorPhaseAWorkloadGrantBundle, } from '../shared/executorPhaseARunAuthorization.js';
+import { assertExecutorPhaseASchema } from '../shared/executorPhaseASchemaValidation.js';
+import { EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS } from '../shared/executorPhaseATiming.js';
+const JWT_TTL_SECONDS = 120;
+const RETIRING_KEY_OVERLAP_MS = 15 * 60 * 1000;
+export const EXECUTOR_PHASE_A_OIDC_PUBLIC_CACHE_MAX_AGE_SECONDS = 300;
+const TRANSITIVE_TAG_KEYS = [
+    'TaskforceRun',
+    'TaskforceReceipt',
+    'TaskforcePhase',
+    'TaskforceWorkspaceHash',
+    'TaskforceSource',
+];
+const verifiedWorkloadJwtClaimsBrand = Symbol('verifiedExecutorPhaseAWorkloadJwtClaims');
+const verifiedWorkloadJwtClaims = new WeakSet();
+function timestamp(value, field) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        throw new TypeError(`${field} is invalid.`);
+    return parsed;
+}
+function sha256(value) {
+    return createHash('sha256').update(canonicalizeExecutorPhaseAJson(value)).digest('hex');
+}
+function assertRsa2048(publicKey) {
+    if (publicKey.asymmetricKeyType !== 'rsa')
+        throw new TypeError('The OIDC signing key must be RSA.');
+    const details = publicKey.asymmetricKeyDetails;
+    if (details?.modulusLength !== 2048)
+        throw new TypeError('The OIDC signing key must be RSA-2048.');
+    const jwk = publicKey.export({ format: 'jwk' });
+    if (jwk.kty !== 'RSA' || !jwk.n || !jwk.e || jwk.d)
+        throw new TypeError('The OIDC public key is not a public RSA JWK.');
+    return jwk;
+}
+export function buildExecutorPhaseAOidcJwks(keys, now = new Date()) {
+    const nowMs = now.getTime();
+    const active = keys.filter((key) => key.status === 'active');
+    const disabled = keys.filter((key) => key.status === 'disabled');
+    if (active.length !== 1
+        || disabled.length > 1
+        || timestamp(active[0].validFrom, 'key.validFrom') > nowMs
+        || nowMs >= timestamp(active[0].validUntil, 'key.validUntil')
+        || new Set(keys.map((key) => key.keyId)).size !== keys.length) {
+        throw new TypeError('The OIDC keyring must contain exactly one current active key, at most one disabled staging key, and no key-ID reuse.');
+    }
+    for (const key of keys) {
+        if (key.status === 'retiring') {
+            if (!key.lastIssuedAt || !key.publishUntil
+                || timestamp(key.validFrom, 'key.validFrom') > nowMs
+                || timestamp(key.publishUntil, 'key.publishUntil') < timestamp(key.lastIssuedAt, 'key.lastIssuedAt') + RETIRING_KEY_OVERLAP_MS) {
+                throw new TypeError('A retiring OIDC key must retain the required publication overlap.');
+            }
+        }
+        if (key.status === 'removed' && key.lastIssuedAt
+            && (!key.publishUntil || timestamp(key.publishUntil, 'key.publishUntil') < timestamp(key.lastIssuedAt, 'key.lastIssuedAt') + RETIRING_KEY_OVERLAP_MS)) {
+            throw new TypeError('A removed OIDC key did not retain the required publication overlap.');
+        }
+    }
+    const staging = keys.filter((key) => key.status === 'disabled'
+        && key.lastIssuedAt === null
+        && key.publishUntil !== null
+        && nowMs < timestamp(key.publishUntil, 'key.publishUntil')
+        && nowMs < timestamp(key.validUntil, 'key.validUntil'));
+    const retiring = keys.filter((key) => key.status === 'retiring'
+        && nowMs < timestamp(key.publishUntil, 'key.publishUntil'));
+    if (staging.length + retiring.length > 1) {
+        throw new TypeError('JWKS may publish only one disabled staging or retiring secondary key.');
+    }
+    const published = [active[0], ...staging, ...retiring];
+    if (published.length > 2)
+        throw new TypeError('JWKS must publish one active key and at most one secondary key.');
+    return {
+        keys: published.map((key) => {
+            const jwk = assertRsa2048(key.publicKey);
+            return { kty: 'RSA', n: jwk.n, e: jwk.e, use: 'sig', alg: 'RS256', kid: key.keyId };
+        }),
+    };
+}
+export function buildExecutorPhaseAOidcDiscovery(issuer) {
+    const origin = new URL(issuer);
+    if (origin.protocol !== 'https:' || origin.origin !== issuer)
+        throw new TypeError('The OIDC issuer must be an HTTPS origin.');
+    return {
+        issuer,
+        jwks_uri: `${issuer}/.well-known/jwks.json`,
+        response_types_supported: ['id_token'],
+        subject_types_supported: ['public'],
+        id_token_signing_alg_values_supported: ['RS256'],
+    };
+}
+export function buildExecutorPhaseAWorkloadJwtClaims(bundle, issuer, audience, tokenId, now) {
+    if (!/^token-[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/.test(tokenId))
+        throw new TypeError('The workload token ID is invalid.');
+    const capability = bundle.capability.payload;
+    const grant = bundle.grant.payload;
+    if (issuer !== capability.oidcIssuer || audience !== capability.oidcAudience) {
+        throw new TypeError('The JWT authority differs from the verified capability.');
+    }
+    const issuedAt = Math.floor(now.getTime() / 1000);
+    const deadline = Math.floor(Math.min(timestamp(grant.expiresAt, 'grant.expiresAt'), timestamp(grant.phase === 'cleanup' ? capability.cleanupDeadline : capability.mutationDeadline, 'phaseDeadline')) / 1000);
+    const expiresAt = Math.min(issuedAt + JWT_TTL_SECONDS, deadline);
+    if (expiresAt <= issuedAt)
+        throw new TypeError('The workload JWT has no remaining authorized lifetime.');
+    const runDigest = createHash('sha256').update(capability.runId, 'utf8').digest('base64url');
+    const claims = {
+        iss: issuer,
+        aud: audience,
+        sub: `tfr:${runDigest}:${grant.phase}`,
+        iat: issuedAt,
+        nbf: issuedAt,
+        exp: expiresAt,
+        jti: tokenId,
+        'https://aws.amazon.com/source_identity': executorPhaseASourceIdentity(capability.runId, grant.phase),
+        'https://aws.amazon.com/tags': {
+            principal_tags: {
+                TaskforceRun: [grant.sessionTags.TaskforceRun],
+                TaskforceReceipt: [grant.sessionTags.TaskforceReceipt],
+                TaskforcePhase: [grant.sessionTags.TaskforcePhase],
+                TaskforceWorkspaceHash: [grant.sessionTags.TaskforceWorkspaceHash],
+                TaskforceSource: [grant.sessionTags.TaskforceSource],
+            },
+            transitive_tag_keys: TRANSITIVE_TAG_KEYS,
+        },
+        taskforce: {
+            schema: 'taskforce.executor-phase-a-workload-jwt-claims/v1',
+            receiptId: capability.receiptId,
+            receiptSha256: capability.receiptSha256,
+            workspaceId: capability.workspaceId,
+            taskId: capability.taskId,
+            runId: capability.runId,
+            sourceCommit: capability.sourceCommit,
+            accountId: capability.accountId,
+            region: capability.region,
+            availabilityZone: capability.availabilityZone,
+            logicalEnvelopeSha256: capability.logicalEnvelopeSha256,
+            budgetsSha256: capability.budgetsSha256,
+            roleArn: grant.roleArn,
+            brokerKeyFingerprint: capability.brokerKeyFingerprint,
+            grantId: grant.grantId,
+            grantSha256: bundle.grantSha256,
+            senderProofSha256: bundle.senderProofSha256,
+        },
+    };
+    assertExecutorPhaseASchema('workloadJwtClaims', claims);
+    return claims;
+}
+export async function signExecutorPhaseAWorkloadJwt(claims, signer) {
+    assertExecutorPhaseASchema('workloadJwtClaims', claims);
+    const header = { alg: 'RS256', kid: signer.keyId, typ: 'JWT' };
+    const signingInput = `${canonicalizeExecutorPhaseAJson(header).toString('base64url')}.${canonicalizeExecutorPhaseAJson(claims).toString('base64url')}`;
+    const signature = await signer.sign(Buffer.from(signingInput, 'ascii'));
+    if (signature.length !== 256)
+        throw new TypeError('The OIDC signer returned a non-RSA-2048 signature.');
+    return `${signingInput}.${signature.toString('base64url')}`;
+}
+function decodeCanonicalJwtSegment(segment, field) {
+    if (!/^[A-Za-z0-9_-]+$/.test(segment))
+        throw new TypeError(`The workload JWT ${field} is not base64url.`);
+    const bytes = Buffer.from(segment, 'base64url');
+    if (bytes.toString('base64url') !== segment)
+        throw new TypeError(`The workload JWT ${field} is not canonical base64url.`);
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new TypeError(`The workload JWT ${field} is not valid JSON.`);
+    }
+    if (canonicalizeExecutorPhaseAJson(value).toString('base64url') !== segment) {
+        throw new TypeError(`The workload JWT ${field} is not canonical JSON.`);
+    }
+    return value;
+}
+export function verifyExecutorPhaseAWorkloadJwt(jwt, bundle, keys, now = new Date()) {
+    if (jwt.length > 16_384)
+        throw new TypeError('The workload JWT exceeds the maximum size.');
+    const segments = jwt.split('.');
+    if (segments.length !== 3)
+        throw new TypeError('The workload JWT must contain exactly three segments.');
+    const [headerSegment, payloadSegment, signatureSegment] = segments;
+    const header = decodeCanonicalJwtSegment(headerSegment, 'header');
+    if (!header || typeof header !== 'object' || Array.isArray(header)
+        || Object.keys(header).sort().join(',') !== 'alg,kid,typ'
+        || header.alg !== 'RS256'
+        || header.typ !== 'JWT'
+        || typeof header.kid !== 'string') {
+        throw new TypeError('The workload JWT header is invalid.');
+    }
+    const key = keys.find((candidate) => candidate.keyId === header.kid);
+    const signature = Buffer.from(signatureSegment, 'base64url');
+    const nowMs = now.getTime();
+    if (new Set(keys.map((candidate) => candidate.keyId)).size !== keys.length
+        || !key || (key.status !== 'active' && key.status !== 'retiring')
+        || nowMs < timestamp(key.validFrom, 'key.validFrom')
+        || nowMs >= timestamp(key.validUntil, 'key.validUntil') || key.publicKey.asymmetricKeyType !== 'rsa'
+        || key.publicKey.asymmetricKeyDetails?.modulusLength !== 2048
+        || !/^[A-Za-z0-9_-]+$/.test(signatureSegment)
+        || signature.length !== 256 || signature.toString('base64url') !== signatureSegment
+        || !verify('RSA-SHA256', Buffer.from(`${headerSegment}.${payloadSegment}`, 'ascii'), key.publicKey, signature)) {
+        throw new TypeError('The workload JWT signature or signing key is invalid.');
+    }
+    const claims = decodeCanonicalJwtSegment(payloadSegment, 'payload');
+    assertExecutorPhaseASchema('workloadJwtClaims', claims);
+    const capability = bundle.capability.payload;
+    const grant = bundle.grant.payload;
+    const nowSeconds = Math.floor(now.getTime() / 1000);
+    const skewSeconds = EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS / 1000;
+    const grantIssuedAt = Math.floor(timestamp(grant.issuedAt, 'grant.issuedAt') / 1000);
+    const grantExpiresAt = Math.floor(timestamp(grant.expiresAt, 'grant.expiresAt') / 1000);
+    const phaseDeadline = Math.floor(timestamp(grant.phase === 'cleanup' ? capability.cleanupDeadline : capability.mutationDeadline, 'phaseDeadline') / 1000);
+    const runDigest = createHash('sha256').update(capability.runId, 'utf8').digest('base64url');
+    const tags = claims['https://aws.amazon.com/tags'];
+    const expectedTags = grant.sessionTags;
+    if (claims.iss !== capability.oidcIssuer || claims.aud !== capability.oidcAudience
+        || claims.sub !== `tfr:${runDigest}:${grant.phase}`
+        || claims['https://aws.amazon.com/source_identity'] !== executorPhaseASourceIdentity(capability.runId, grant.phase)
+        || claims.iat < grantIssuedAt - skewSeconds || claims.iat > nowSeconds + skewSeconds
+        || claims.nbf !== claims.iat
+        || nowSeconds >= claims.exp + skewSeconds || claims.exp <= claims.iat || claims.exp - claims.iat > JWT_TTL_SECONDS
+        || claims.exp > grantExpiresAt || claims.exp > phaseDeadline
+        || tags.principal_tags.TaskforceRun[0] !== expectedTags.TaskforceRun
+        || tags.principal_tags.TaskforceReceipt[0] !== expectedTags.TaskforceReceipt
+        || tags.principal_tags.TaskforcePhase[0] !== expectedTags.TaskforcePhase
+        || tags.principal_tags.TaskforceWorkspaceHash[0] !== expectedTags.TaskforceWorkspaceHash
+        || tags.principal_tags.TaskforceSource[0] !== expectedTags.TaskforceSource
+        || claims.taskforce.receiptId !== capability.receiptId
+        || claims.taskforce.receiptSha256 !== capability.receiptSha256
+        || claims.taskforce.workspaceId !== capability.workspaceId
+        || claims.taskforce.taskId !== capability.taskId
+        || claims.taskforce.runId !== capability.runId
+        || claims.taskforce.sourceCommit !== capability.sourceCommit
+        || claims.taskforce.accountId !== capability.accountId
+        || claims.taskforce.region !== capability.region
+        || claims.taskforce.availabilityZone !== capability.availabilityZone
+        || claims.taskforce.logicalEnvelopeSha256 !== capability.logicalEnvelopeSha256
+        || claims.taskforce.budgetsSha256 !== capability.budgetsSha256
+        || claims.taskforce.roleArn !== grant.roleArn
+        || claims.taskforce.brokerKeyFingerprint !== capability.brokerKeyFingerprint
+        || claims.taskforce.grantId !== grant.grantId
+        || claims.taskforce.grantSha256 !== bundle.grantSha256
+        || claims.taskforce.senderProofSha256 !== bundle.senderProofSha256) {
+        throw new TypeError('The workload JWT claims differ from the verified grant.');
+    }
+    const verified = structuredClone(claims);
+    const freeze = (value) => {
+        if (!value || typeof value !== 'object' || Object.isFrozen(value))
+            return;
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    };
+    freeze(verified);
+    verifiedWorkloadJwtClaims.add(verified);
+    return verified;
+}
+export function assertVerifiedExecutorPhaseAWorkloadJwtClaims(claims) {
+    if (!claims || typeof claims !== 'object' || !verifiedWorkloadJwtClaims.has(claims)) {
+        throw new TypeError('The broker requires runtime-verified workload JWT claims.');
+    }
+}
+function verifyRedemptionResponse(response, request, cloudKeys, now) {
+    assertExecutorPhaseASchema('issuerRedemptionResponse', response);
+    const trustedKey = cloudKeys.find((key) => key.keyId === response.envelope.keyId && key.status !== 'disabled');
+    if (!trustedKey || trustedKey.publicKey.asymmetricKeyType !== 'ed25519') {
+        throw new TypeError('Taskforce Cloud used an untrusted redemption-response key.');
+    }
+    const payloadBytes = canonicalizeExecutorPhaseAJson(response.payload);
+    const signature = Buffer.from(response.envelope.signature, 'base64url');
+    const redeemedAt = timestamp(response.payload.redeemedAt, 'response.redeemedAt');
+    const proofIssuedAt = timestamp(request.issuerProof.payload.issuedAt, 'issuerProof.issuedAt');
+    const proofExpiresAt = timestamp(request.issuerProof.payload.expiresAt, 'issuerProof.expiresAt');
+    if (response.payload.requestId !== request.requestId
+        || response.payload.grantId !== request.workloadGrant.payload.grantId
+        || response.payload.grantSha256 !== sha256(request.workloadGrant)
+        || response.payload.senderProofSha256 !== sha256(request.senderProof)
+        || response.payload.auditSha256 !== executorPhaseAIssuerRedemptionAuditSha256({
+            requestId: response.payload.requestId,
+            grantId: response.payload.grantId,
+            grantSha256: response.payload.grantSha256,
+            senderProofSha256: response.payload.senderProofSha256,
+            redeemedAt: response.payload.redeemedAt,
+        })
+        || redeemedAt < proofIssuedAt - EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS
+        || redeemedAt > now.getTime() + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS
+        || redeemedAt >= proofExpiresAt + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS
+        || response.envelope.payloadSha256 !== createHash('sha256').update(payloadBytes).digest('hex')
+        || signature.length !== 64 || !verify(null, payloadBytes, trustedKey.publicKey, signature)) {
+        throw new TypeError('Taskforce Cloud returned an invalid issuer redemption decision.');
+    }
+}
+export class ExecutorPhaseAIssuerCore {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async issue(input) {
+        const now = this.options.now?.() || new Date();
+        let grantId = input.workloadGrant.payload.grantId;
+        let acquired = false;
+        let redemptionConfirmed = false;
+        try {
+            const verifiedCapability = verifyExecutorPhaseARunCapabilityArtifact(input.runCapability, input.approvalReceipt, this.options.cloudArtifactPublicKey, now);
+            const brokerPublicKey = createPublicKey({
+                key: Buffer.from(verifiedCapability.payload.brokerPublicKeySpkiBase64, 'base64'),
+                format: 'der',
+                type: 'spki',
+            });
+            const intentShape = {
+                ...input,
+                issuerProof: {},
+                schema: EXECUTOR_PHASE_A_ISSUER_REDEMPTION_REQUEST_SCHEMA,
+            };
+            const requestSha256 = executorPhaseAIssuerRedemptionIntentSha256(intentShape);
+            const bundle = verifyExecutorPhaseAWorkloadGrantBundle(input.workloadGrant, verifiedCapability, input.senderProof, input.brokerRequestSha256, input.expectedPolicySha256, this.options.cloudArtifactPublicKey, brokerPublicKey, now);
+            const tokenId = this.options.randomId('token');
+            const claims = buildExecutorPhaseAWorkloadJwtClaims(bundle, this.options.issuer, this.options.audience, tokenId, now);
+            const acquireResult = await this.options.stateStore.acquire({
+                grantId,
+                grantSha256: bundle.grantSha256,
+                senderProofSha256: bundle.senderProofSha256,
+                requestId: input.requestId,
+                createdAt: now.toISOString(),
+            });
+            if (acquireResult !== 'acquired')
+                throw new TypeError('The workload grant already has terminal issuer state.');
+            acquired = true;
+            const proofPayload = {
+                schema: EXECUTOR_PHASE_A_ISSUER_PROOF_PAYLOAD_SCHEMA,
+                method: 'POST',
+                path: EXECUTOR_PHASE_A_ISSUER_REDEMPTION_PATH,
+                requestSha256,
+                grantId,
+                grantSha256: bundle.grantSha256,
+                senderProofSha256: bundle.senderProofSha256,
+                requestId: input.requestId,
+                issuedAt: now.toISOString(),
+                expiresAt: new Date(now.getTime() + 60_000).toISOString(),
+            };
+            const signedProofBytes = executorPhaseAIssuerProofSignedBytes(proofPayload);
+            const proofSignature = await this.options.issuerProofSigner.sign(signedProofBytes);
+            if (proofSignature.length !== 256)
+                throw new TypeError('The issuer proof signer returned a non-RSA-2048 signature.');
+            const request = {
+                schema: EXECUTOR_PHASE_A_ISSUER_REDEMPTION_REQUEST_SCHEMA,
+                requestId: input.requestId,
+                approvalReceipt: input.approvalReceipt,
+                runCapability: input.runCapability,
+                workloadGrant: input.workloadGrant,
+                senderProof: input.senderProof,
+                brokerRequestSha256: input.brokerRequestSha256,
+                expectedPolicySha256: input.expectedPolicySha256,
+                issuerProof: {
+                    payload: proofPayload,
+                    envelope: {
+                        schema: EXECUTOR_PHASE_A_ISSUER_PROOF_SCHEMA,
+                        typ: EXECUTOR_PHASE_A_ISSUER_PROOF_TYPE,
+                        algorithm: 'RS256',
+                        keyId: this.options.issuerProofSigner.keyId,
+                        payloadSha256: createHash('sha256').update(signedProofBytes).digest('hex'),
+                        signature: proofSignature.toString('base64url'),
+                    },
+                },
+            };
+            assertExecutorPhaseASchema('issuerRedemptionRequest', request);
+            const response = await this.options.redeem(request);
+            verifyRedemptionResponse(response, request, this.options.cloudResponseKeys, this.options.now?.() || now);
+            redemptionConfirmed = true;
+            const jwt = await signExecutorPhaseAWorkloadJwt(claims, this.options.oidcSigner);
+            await this.options.stateStore.markSigned({
+                grantId,
+                tokenId,
+                kmsKeyId: this.options.oidcSigner.keyId,
+                updatedAt: (this.options.now?.() || now).toISOString(),
+            });
+            return jwt;
+        }
+        catch (error) {
+            if (acquired) {
+                const updatedAt = (this.options.now?.() || now).toISOString();
+                if (redemptionConfirmed) {
+                    await this.options.stateStore.markFailed({
+                        grantId,
+                        errorCategory: error instanceof TypeError ? 'invalid_artifact' : 'issuer_failure',
+                        updatedAt,
+                    }).catch(() => undefined);
+                }
+                else {
+                    await this.options.stateStore.releasePending({
+                        grantId,
+                        requestId: input.requestId,
+                        updatedAt,
+                    }).catch(() => undefined);
+                }
+            }
+            throw error;
+        }
+    }
+}

package/dist/services/executorPhaseAIssuerRedemptionService.d.ts

@@ -0,0 +1,34 @@
+import { type KeyObject } from 'node:crypto';
+import { type ExecutorPhaseAApprovalTrustPolicy } from '../shared/executorPhaseAApprovalReceipt.js';
+import { type ExecutorPhaseAIssuerProofTrustKey, type ExecutorPhaseAIssuerRedemptionRequest } from '../shared/executorPhaseAIssuerContracts.js';
+import { type ExecutorPhaseARunAuthorizationStore } from '../storage/executorPhaseARunAuthorizationStore.js';
+export declare class ExecutorPhaseAIssuerRedemptionError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(message: string, statusCode?: number, code?: string);
+}
+export interface ExecutorPhaseAIssuerRedemptionCloudKey {
+    keyId: string;
+    publicKey: KeyObject;
+    status: 'active' | 'retiring' | 'disabled';
+}
+export interface ExecutorPhaseAIssuerRedemptionSigningConfig {
+    keyId: string;
+    privateKey: KeyObject;
+}
+export declare class ExecutorPhaseAIssuerRedemptionService {
+    private readonly options;
+    constructor(options: {
+        store: ExecutorPhaseARunAuthorizationStore;
+        responseKeys: readonly ExecutorPhaseAIssuerRedemptionCloudKey[];
+        issuerProofKeys: readonly ExecutorPhaseAIssuerProofTrustKey[];
+        responseSigning: ExecutorPhaseAIssuerRedemptionSigningConfig;
+        approvalPolicy: ExecutorPhaseAApprovalTrustPolicy;
+        now?: () => Date;
+    });
+    redeem(request: ExecutorPhaseAIssuerRedemptionRequest): {
+        bytes: Buffer;
+        digest: string;
+        created: boolean;
+    };
+}

package/dist/services/executorPhaseAIssuerRedemptionService.js

@@ -0,0 +1,158 @@
+import { createHash, createPublicKey, sign } from 'node:crypto';
+import { canonicalizeExecutorPhaseAJson, } from '../shared/executorPhaseAApprovalReceipt.js';
+import { executorPhaseAIssuerRedemptionAuditSha256, executorPhaseAIssuerRedemptionIntentSha256, verifyExecutorPhaseAIssuerProof, EXECUTOR_PHASE_A_ISSUER_REDEMPTION_RESPONSE_PAYLOAD_SCHEMA, } from '../shared/executorPhaseAIssuerContracts.js';
+import { verifyExecutorPhaseARunCapabilityArtifact, verifyExecutorPhaseAWorkloadGrantBundle, } from '../shared/executorPhaseARunAuthorization.js';
+import { assertExecutorPhaseASchema } from '../shared/executorPhaseASchemaValidation.js';
+import { ExecutorPhaseARunAuthorizationError, } from '../storage/executorPhaseARunAuthorizationStore.js';
+export class ExecutorPhaseAIssuerRedemptionError extends Error {
+    statusCode;
+    code;
+    constructor(message, statusCode = 400, code = 'executor_phase_a_issuer_redemption_invalid') {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.name = 'ExecutorPhaseAIssuerRedemptionError';
+    }
+}
+function publicKeyFingerprint(publicKey) {
+    return createHash('sha256').update(publicKey.export({ format: 'der', type: 'spki' })).digest('hex');
+}
+function parseArtifactPublicKey(trusted) {
+    const validFrom = Date.parse(trusted.validFrom);
+    const validUntil = Date.parse(trusted.validUntil);
+    if (!Number.isFinite(validFrom) || !Number.isFinite(validUntil) || validUntil <= validFrom) {
+        throw new ExecutorPhaseAIssuerRedemptionError('The Cloud authorization artifact key lifetime is invalid.', 403);
+    }
+    const encoded = Buffer.from(trusted.publicKeySpkiBase64, 'base64');
+    if (encoded.toString('base64') !== trusted.publicKeySpkiBase64) {
+        throw new ExecutorPhaseAIssuerRedemptionError('The Cloud authorization artifact key is not canonical.', 403);
+    }
+    const publicKey = createPublicKey({ key: encoded, format: 'der', type: 'spki' });
+    if (publicKey.asymmetricKeyType !== 'ed25519') {
+        throw new ExecutorPhaseAIssuerRedemptionError('The Cloud authorization artifact key is not Ed25519.', 403);
+    }
+    return publicKey;
+}
+function resolveArtifactKey(keys, keyId, now) {
+    const trusted = keys.find((key) => key.keyId === keyId);
+    const validFrom = trusted ? Date.parse(trusted.validFrom) : Number.NaN;
+    const validUntil = trusted ? Date.parse(trusted.validUntil) : Number.NaN;
+    if (!trusted || trusted.status === 'disabled'
+        || validFrom > now.getTime() || now.getTime() >= validUntil) {
+        throw new ExecutorPhaseAIssuerRedemptionError('The Cloud authorization artifact key is not trusted.', 403);
+    }
+    return parseArtifactPublicKey(trusted);
+}
+function brokerPublicKey(encoded) {
+    try {
+        const key = createPublicKey({ key: Buffer.from(encoded, 'base64'), format: 'der', type: 'spki' });
+        if (key.asymmetricKeyType !== 'ed25519')
+            throw new Error('wrong key type');
+        return key;
+    }
+    catch {
+        throw new ExecutorPhaseAIssuerRedemptionError('The capability broker key is invalid.', 403);
+    }
+}
+export class ExecutorPhaseAIssuerRedemptionService {
+    options;
+    constructor(options) {
+        this.options = options;
+        if (options.responseSigning.privateKey.asymmetricKeyType !== 'ed25519') {
+            throw new Error('The issuer redemption response key must be Ed25519.');
+        }
+        const artifactKeyIds = new Set();
+        const artifactFingerprints = new Set();
+        for (const key of options.approvalPolicy.keys) {
+            if (artifactKeyIds.has(key.keyId))
+                throw new Error('The Phase A artifact trust policy contains a duplicate key ID.');
+            artifactKeyIds.add(key.keyId);
+            const publicKey = parseArtifactPublicKey(key);
+            artifactFingerprints.add(publicKeyFingerprint(publicKey));
+        }
+        const responseKeyIds = new Set();
+        const responseFingerprints = new Set();
+        for (const key of options.responseKeys) {
+            if (key.publicKey.asymmetricKeyType !== 'ed25519') {
+                throw new Error('The issuer redemption response trust keys must be unique Ed25519 keys.');
+            }
+            const fingerprint = publicKeyFingerprint(key.publicKey);
+            if (responseKeyIds.has(key.keyId) || responseFingerprints.has(fingerprint)) {
+                throw new Error('The issuer redemption response trust keys must be unique Ed25519 keys.');
+            }
+            responseKeyIds.add(key.keyId);
+            responseFingerprints.add(fingerprint);
+        }
+        if ([...responseKeyIds].some((keyId) => artifactKeyIds.has(keyId))
+            || [...responseFingerprints].some((fingerprint) => artifactFingerprints.has(fingerprint))) {
+            throw new Error('Phase A artifact and redemption-response trust keys must be disjoint.');
+        }
+        const publicKey = createPublicKey(options.responseSigning.privateKey);
+        const trusted = options.responseKeys.find((key) => key.keyId === options.responseSigning.keyId && key.status === 'active');
+        if (!trusted || !publicKey.equals(trusted.publicKey)) {
+            throw new Error('The issuer redemption response key must match one active Cloud trust key.');
+        }
+    }
+    redeem(request) {
+        const now = this.options.now?.() || new Date();
+        try {
+            assertExecutorPhaseASchema('issuerRedemptionRequest', request);
+            verifyExecutorPhaseAIssuerProof(request, this.options.issuerProofKeys, now);
+            const artifactKeyIds = [
+                request.approvalReceipt.envelope.keyId,
+                request.runCapability.envelope.keyId,
+                request.workloadGrant.envelope.keyId,
+            ];
+            if (new Set(artifactKeyIds).size !== 1) {
+                throw new TypeError('The Cloud authorization artifacts use different trust keys.');
+            }
+            const cloudPublicKey = resolveArtifactKey(this.options.approvalPolicy.keys, artifactKeyIds[0], now);
+            const verifiedCapability = verifyExecutorPhaseARunCapabilityArtifact(request.runCapability, request.approvalReceipt, cloudPublicKey, now);
+            if (request.approvalReceipt.payload.issuer !== this.options.approvalPolicy.issuer
+                || request.approvalReceipt.payload.audience !== this.options.approvalPolicy.audience
+                || request.approvalReceipt.payload.environment !== this.options.approvalPolicy.environment
+                || request.approvalReceipt.payload.workspaceId !== this.options.approvalPolicy.workspaceId
+                || request.approvalReceipt.payload.taskId !== this.options.approvalPolicy.taskId) {
+                throw new TypeError('The approval receipt is outside the frozen Phase A authority.');
+            }
+            const verifiedBundle = verifyExecutorPhaseAWorkloadGrantBundle(request.workloadGrant, verifiedCapability, request.senderProof, request.brokerRequestSha256, request.expectedPolicySha256, cloudPublicKey, brokerPublicKey(verifiedCapability.payload.brokerPublicKeySpkiBase64), now);
+            const redeemedAt = now.toISOString();
+            const auditInput = {
+                requestId: request.requestId,
+                grantId: verifiedBundle.grant.payload.grantId,
+                grantSha256: verifiedBundle.grantSha256,
+                senderProofSha256: verifiedBundle.senderProofSha256,
+                redeemedAt,
+            };
+            const payload = {
+                schema: EXECUTOR_PHASE_A_ISSUER_REDEMPTION_RESPONSE_PAYLOAD_SCHEMA,
+                decision: 'redeemed',
+                ...auditInput,
+                auditSha256: executorPhaseAIssuerRedemptionAuditSha256(auditInput),
+            };
+            const payloadBytes = canonicalizeExecutorPhaseAJson(payload);
+            const response = {
+                payload,
+                envelope: {
+                    algorithm: 'Ed25519',
+                    keyId: this.options.responseSigning.keyId,
+                    payloadSha256: createHash('sha256').update(payloadBytes).digest('hex'),
+                    signature: sign(null, payloadBytes, this.options.responseSigning.privateKey).toString('base64url'),
+                },
+            };
+            assertExecutorPhaseASchema('issuerRedemptionResponse', response);
+            const responseBytes = canonicalizeExecutorPhaseAJson(response);
+            const responseSha256 = createHash('sha256').update(responseBytes).digest('hex');
+            const persisted = this.options.store.redeemVerifiedGrant(verifiedBundle, request.requestId, executorPhaseAIssuerRedemptionIntentSha256(request), responseBytes, responseSha256, redeemedAt);
+            return { bytes: persisted.bytes, digest: persisted.digest, created: persisted.created };
+        }
+        catch (error) {
+            if (error instanceof ExecutorPhaseAIssuerRedemptionError)
+                throw error;
+            const statusCode = error instanceof TypeError || error instanceof ExecutorPhaseARunAuthorizationError
+                ? 403
+                : Number(error?.statusCode) || 500;
+            throw new ExecutorPhaseAIssuerRedemptionError(statusCode >= 500 ? 'Issuer redemption failed internally.' : String(error?.message || 'Issuer redemption failed.'), statusCode, statusCode >= 500 ? 'executor_phase_a_issuer_redemption_internal' : 'executor_phase_a_issuer_redemption_denied');
+        }
+    }
+}

package/dist/services/githubReviewEvidenceRuntime.d.ts

@@ -0,0 +1,14 @@
+import type { TaskforceCore } from '../core/Taskforce.js';
+import { GitHubReviewEvidenceInstallationStore } from '../storage/githubReviewEvidenceInstallationStore.js';
+import { GitHubReviewEvidenceService, type GitHubReviewAppConfig } from './githubReviewEvidenceService.js';
+export declare function createGitHubReviewEvidenceRuntime(core: TaskforceCore, options?: {
+    config?: GitHubReviewAppConfig | null;
+    fetchImpl?: typeof fetch;
+    apiBaseUrl?: string;
+    timeoutMs?: number;
+    now?: () => Date;
+}): {
+    configured: boolean;
+    store: GitHubReviewEvidenceInstallationStore;
+    verifier: GitHubReviewEvidenceService;
+};

package/dist/services/githubReviewEvidenceRuntime.js

@@ -0,0 +1,30 @@
+import { GitHubReviewEvidenceInstallationStore } from '../storage/githubReviewEvidenceInstallationStore.js';
+import { GitHubReviewEvidenceService, resolveGitHubReviewAppConfig, } from './githubReviewEvidenceService.js';
+export function createGitHubReviewEvidenceRuntime(core, options = {}) {
+    const store = new GitHubReviewEvidenceInstallationStore(core.getDatabaseAdapter(), core.getTenantId(), options.now);
+    const config = options.config === undefined ? resolveGitHubReviewAppConfig() : options.config;
+    const verifier = new GitHubReviewEvidenceService({
+        config,
+        getBinding: (workspaceId) => store.get(workspaceId),
+        fetchImpl: options.fetchImpl,
+        apiBaseUrl: options.apiBaseUrl,
+        timeoutMs: options.timeoutMs,
+        now: options.now,
+        audit: (event) => {
+            try {
+                const { action, workspaceId, ...details } = event;
+                core.addAdminAuditLog({
+                    action,
+                    actorUserId: 'system',
+                    actorRole: 'system',
+                    workspaceId,
+                    details,
+                });
+            }
+            catch {
+                // Verification must not change outcome when audit persistence is unavailable.
+            }
+        },
+    });
+    return { configured: config !== null, store, verifier };
+}