@taskforcehq/taskforce 0.3.329 → 0.3.332

package/dist/shared/executorPhaseAIssuerContracts.d.ts

@@ -0,0 +1,75 @@
+import { type KeyObject } from 'node:crypto';
+import { type ExecutorPhaseAApprovalReceipt } from './executorPhaseAApprovalReceipt.js';
+import { type ExecutorPhaseARunCapability, type ExecutorPhaseASenderProof, type ExecutorPhaseAWorkloadGrant } from './executorPhaseARunAuthorization.js';
+export declare const EXECUTOR_PHASE_A_ISSUER_REDEMPTION_PATH: "/api/taskforce/internal/executor/phase-a/redemptions";
+export declare const EXECUTOR_PHASE_A_ISSUER_REDEMPTION_REQUEST_SCHEMA: "taskforce.executor-phase-a-issuer-redemption-request/v1";
+export declare const EXECUTOR_PHASE_A_ISSUER_PROOF_PAYLOAD_SCHEMA: "taskforce.executor-phase-a-issuer-proof-payload/v1";
+export declare const EXECUTOR_PHASE_A_ISSUER_PROOF_SCHEMA: "taskforce.executor-phase-a-issuer-proof/v1";
+export declare const EXECUTOR_PHASE_A_ISSUER_PROOF_TYPE: "TF-ISSUER-PROOF";
+export declare const EXECUTOR_PHASE_A_ISSUER_REDEMPTION_RESPONSE_PAYLOAD_SCHEMA: "taskforce.executor-phase-a-issuer-redemption-response-payload/v1";
+export declare const EXECUTOR_PHASE_A_ISSUER_PROOF_DOMAIN: Buffer<ArrayBuffer>;
+export declare const EXECUTOR_PHASE_A_ISSUER_PROOF_TTL_MS = 60000;
+export interface ExecutorPhaseAIssuerProofPayload {
+    schema: typeof EXECUTOR_PHASE_A_ISSUER_PROOF_PAYLOAD_SCHEMA;
+    method: 'POST';
+    path: typeof EXECUTOR_PHASE_A_ISSUER_REDEMPTION_PATH;
+    requestSha256: string;
+    grantId: string;
+    grantSha256: string;
+    senderProofSha256: string;
+    requestId: string;
+    issuedAt: string;
+    expiresAt: string;
+}
+export interface ExecutorPhaseAIssuerProof {
+    payload: ExecutorPhaseAIssuerProofPayload;
+    envelope: {
+        schema: typeof EXECUTOR_PHASE_A_ISSUER_PROOF_SCHEMA;
+        typ: typeof EXECUTOR_PHASE_A_ISSUER_PROOF_TYPE;
+        algorithm: 'RS256';
+        keyId: string;
+        payloadSha256: string;
+        signature: string;
+    };
+}
+export interface ExecutorPhaseAIssuerRedemptionRequest {
+    schema: typeof EXECUTOR_PHASE_A_ISSUER_REDEMPTION_REQUEST_SCHEMA;
+    requestId: string;
+    approvalReceipt: ExecutorPhaseAApprovalReceipt;
+    runCapability: ExecutorPhaseARunCapability;
+    workloadGrant: ExecutorPhaseAWorkloadGrant;
+    senderProof: ExecutorPhaseASenderProof;
+    brokerRequestSha256: string;
+    expectedPolicySha256: string;
+    issuerProof: ExecutorPhaseAIssuerProof;
+}
+export interface ExecutorPhaseAIssuerRedemptionResponsePayload {
+    schema: typeof EXECUTOR_PHASE_A_ISSUER_REDEMPTION_RESPONSE_PAYLOAD_SCHEMA;
+    decision: 'redeemed';
+    requestId: string;
+    grantId: string;
+    grantSha256: string;
+    senderProofSha256: string;
+    auditSha256: string;
+    redeemedAt: string;
+}
+export interface ExecutorPhaseAIssuerRedemptionResponse {
+    payload: ExecutorPhaseAIssuerRedemptionResponsePayload;
+    envelope: {
+        algorithm: 'Ed25519';
+        keyId: string;
+        payloadSha256: string;
+        signature: string;
+    };
+}
+export interface ExecutorPhaseAIssuerProofTrustKey {
+    keyId: string;
+    publicKeySpkiBase64: string;
+    status: 'active' | 'retiring' | 'disabled';
+    validFrom: string;
+    validUntil: string;
+}
+export declare function executorPhaseAIssuerRedemptionIntentSha256(request: Pick<ExecutorPhaseAIssuerRedemptionRequest, 'requestId' | 'approvalReceipt' | 'runCapability' | 'workloadGrant' | 'senderProof' | 'brokerRequestSha256' | 'expectedPolicySha256'>): string;
+export declare function executorPhaseAIssuerProofSignedBytes(payload: ExecutorPhaseAIssuerProofPayload): Buffer;
+export declare function verifyExecutorPhaseAIssuerProof(request: ExecutorPhaseAIssuerRedemptionRequest, trustedKeys: readonly ExecutorPhaseAIssuerProofTrustKey[], now?: Date): KeyObject;
+export declare function executorPhaseAIssuerRedemptionAuditSha256(payload: Omit<ExecutorPhaseAIssuerRedemptionResponsePayload, 'schema' | 'decision' | 'auditSha256'>): string;

package/dist/shared/executorPhaseAIssuerContracts.js

@@ -0,0 +1,90 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { canonicalizeExecutorPhaseAJson, } from './executorPhaseAApprovalReceipt.js';
+import { assertExecutorPhaseASchema } from './executorPhaseASchemaValidation.js';
+import { EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS } from './executorPhaseATiming.js';
+export const EXECUTOR_PHASE_A_ISSUER_REDEMPTION_PATH = '/api/taskforce/internal/executor/phase-a/redemptions';
+export const EXECUTOR_PHASE_A_ISSUER_REDEMPTION_REQUEST_SCHEMA = 'taskforce.executor-phase-a-issuer-redemption-request/v1';
+export const EXECUTOR_PHASE_A_ISSUER_PROOF_PAYLOAD_SCHEMA = 'taskforce.executor-phase-a-issuer-proof-payload/v1';
+export const EXECUTOR_PHASE_A_ISSUER_PROOF_SCHEMA = 'taskforce.executor-phase-a-issuer-proof/v1';
+export const EXECUTOR_PHASE_A_ISSUER_PROOF_TYPE = 'TF-ISSUER-PROOF';
+export const EXECUTOR_PHASE_A_ISSUER_REDEMPTION_RESPONSE_PAYLOAD_SCHEMA = 'taskforce.executor-phase-a-issuer-redemption-response-payload/v1';
+export const EXECUTOR_PHASE_A_ISSUER_PROOF_DOMAIN = Buffer.from('taskforce.phase-a.issuer-proof.v1\n', 'ascii');
+export const EXECUTOR_PHASE_A_ISSUER_PROOF_TTL_MS = 60_000;
+function artifactSha256(value) {
+    return createHash('sha256').update(canonicalizeExecutorPhaseAJson(value)).digest('hex');
+}
+function timestamp(value, field) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        throw new TypeError(`${field} is invalid.`);
+    return parsed;
+}
+export function executorPhaseAIssuerRedemptionIntentSha256(request) {
+    return artifactSha256({
+        schema: 'taskforce.executor-phase-a-issuer-redemption-intent/v1',
+        requestId: request.requestId,
+        receiptSha256: artifactSha256(request.approvalReceipt),
+        capabilityId: request.runCapability.payload.capabilityId,
+        capabilitySha256: artifactSha256(request.runCapability),
+        grantId: request.workloadGrant.payload.grantId,
+        grantSha256: artifactSha256(request.workloadGrant),
+        senderProofSha256: artifactSha256(request.senderProof),
+        brokerRequestSha256: request.brokerRequestSha256,
+        phase: request.workloadGrant.payload.phase,
+        policySha256: request.expectedPolicySha256,
+    });
+}
+export function executorPhaseAIssuerProofSignedBytes(payload) {
+    return Buffer.concat([EXECUTOR_PHASE_A_ISSUER_PROOF_DOMAIN, canonicalizeExecutorPhaseAJson(payload)]);
+}
+export function verifyExecutorPhaseAIssuerProof(request, trustedKeys, now = new Date()) {
+    assertExecutorPhaseASchema('issuerRedemptionRequest', request);
+    const proof = request.issuerProof;
+    const key = trustedKeys.find((candidate) => candidate.keyId === proof.envelope.keyId);
+    const nowMs = now.getTime();
+    if (!key || key.status === 'disabled' || nowMs < timestamp(key.validFrom, 'key.validFrom')
+        || nowMs >= timestamp(key.validUntil, 'key.validUntil')) {
+        throw new TypeError('The issuer proof key is not trusted at redemption time.');
+    }
+    const publicKeyDer = Buffer.from(key.publicKeySpkiBase64, 'base64');
+    if (publicKeyDer.toString('base64') !== key.publicKeySpkiBase64) {
+        throw new TypeError('The issuer proof key must use canonical base64 SPKI.');
+    }
+    const publicKey = createPublicKey({
+        key: publicKeyDer,
+        format: 'der',
+        type: 'spki',
+    });
+    if (publicKey.asymmetricKeyType !== 'rsa' || publicKey.asymmetricKeyDetails?.modulusLength !== 2048) {
+        throw new TypeError('The issuer proof key must be RSA-2048.');
+    }
+    const signedBytes = executorPhaseAIssuerProofSignedBytes(proof.payload);
+    const signature = Buffer.from(proof.envelope.signature, 'base64url');
+    const issuedAt = timestamp(proof.payload.issuedAt, 'issuerProof.issuedAt');
+    const expiresAt = timestamp(proof.payload.expiresAt, 'issuerProof.expiresAt');
+    const requestSha256 = executorPhaseAIssuerRedemptionIntentSha256(request);
+    const grantSha256 = artifactSha256(request.workloadGrant);
+    const senderProofSha256 = artifactSha256(request.senderProof);
+    if (proof.payload.requestId !== request.requestId
+        || proof.payload.requestSha256 !== requestSha256
+        || proof.payload.grantId !== request.workloadGrant.payload.grantId
+        || proof.payload.grantSha256 !== grantSha256
+        || proof.payload.senderProofSha256 !== senderProofSha256
+        || request.senderProof.payload.requestSha256 !== request.brokerRequestSha256
+        || proof.envelope.payloadSha256 !== createHash('sha256').update(signedBytes).digest('hex')
+        || signature.length !== 256 || signature.toString('base64url') !== proof.envelope.signature
+        || issuedAt > nowMs + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS
+        || nowMs >= expiresAt + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS
+        || expiresAt <= issuedAt
+        || expiresAt - issuedAt > EXECUTOR_PHASE_A_ISSUER_PROOF_TTL_MS
+        || !verify('RSA-SHA256', signedBytes, publicKey, signature)) {
+        throw new TypeError('The issuer proof is stale, forged, replay-shaped, or bound to different redemption bytes.');
+    }
+    return publicKey;
+}
+export function executorPhaseAIssuerRedemptionAuditSha256(payload) {
+    return artifactSha256({
+        schema: 'taskforce.executor-phase-a-issuer-redemption-audit/v1',
+        ...payload,
+    });
+}

package/dist/shared/executorPhaseARunAuthorization.d.ts

@@ -0,0 +1,120 @@
+import { type KeyObject } from 'crypto';
+import { type ExecutorPhaseAApprovalReceipt, type ExecutorPhaseAPhase, type ExecutorPhaseARoleMap } from './executorPhaseAApprovalReceipt.js';
+export declare const EXECUTOR_PHASE_A_RUN_CAPABILITY_PAYLOAD_SCHEMA: "taskforce.executor-phase-a-run-capability-payload/v1";
+export declare const EXECUTOR_PHASE_A_SENDER_PROOF_PAYLOAD_SCHEMA: "taskforce.executor-phase-a-sender-proof-payload/v1";
+export declare const EXECUTOR_PHASE_A_WORKLOAD_GRANT_PAYLOAD_SCHEMA: "taskforce.executor-phase-a-workload-grant-payload/v1";
+export declare const EXECUTOR_PHASE_A_MAIN_CAPABILITY_TTL_MS: number;
+export declare const EXECUTOR_PHASE_A_CLEANUP_CAPABILITY_TTL_MS: number;
+export declare const EXECUTOR_PHASE_A_SENDER_PROOF_TTL_MS: number;
+export declare const EXECUTOR_PHASE_A_WORKLOAD_GRANT_TTL_MS: number;
+export type ExecutorPhaseARunCapabilityKind = 'main' | 'cleanup-only';
+export type ExecutorPhaseARunAuthorizationStatus = 'active' | 'awaiting-cleanup-approval' | 'completed' | 'cleanup-failed' | 'expired';
+export interface ExecutorPhaseASignatureEnvelope {
+    algorithm: 'Ed25519';
+    keyId: string;
+    payloadSha256: string;
+    signature: string;
+}
+export interface ExecutorPhaseARunCapabilityPayload {
+    schema: typeof EXECUTOR_PHASE_A_RUN_CAPABILITY_PAYLOAD_SCHEMA;
+    capabilityId: string;
+    capabilityKind: ExecutorPhaseARunCapabilityKind;
+    originalCapabilityId: string | null;
+    residualInventorySha256: string | null;
+    receiptId: string;
+    receiptSha256: string;
+    workspaceId: string;
+    taskId: string;
+    actorUserId: string;
+    runId: string;
+    accountId: string;
+    region: 'us-west-2';
+    availabilityZone: string;
+    sourceCommit: string;
+    preflightSha256: string;
+    logicalEnvelopeSha256: string;
+    budgetsSha256: string;
+    readPrincipalArn: string;
+    mutationRoles: ExecutorPhaseARoleMap;
+    roleMapSha256: string;
+    oidcIssuer: string;
+    oidcAudience: string;
+    brokerPublicKeySpkiBase64: string;
+    brokerKeyFingerprint: string;
+    allowedPhases: ExecutorPhaseAPhase[];
+    issuedAt: string;
+    expiresAt: string;
+    mutationDeadline: string;
+    cleanupDeadline: string;
+}
+export interface ExecutorPhaseARunCapability {
+    payload: ExecutorPhaseARunCapabilityPayload;
+    envelope: ExecutorPhaseASignatureEnvelope;
+}
+export interface ExecutorPhaseASenderProofPayload {
+    schema: typeof EXECUTOR_PHASE_A_SENDER_PROOF_PAYLOAD_SCHEMA;
+    capabilityId: string;
+    nonceId: string;
+    requestSha256: string;
+    phase: ExecutorPhaseAPhase;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface ExecutorPhaseASenderProof {
+    payload: ExecutorPhaseASenderProofPayload;
+    envelope: ExecutorPhaseASignatureEnvelope & {
+        brokerKeyFingerprint: string;
+    };
+}
+export interface ExecutorPhaseAWorkloadGrantPayload {
+    schema: typeof EXECUTOR_PHASE_A_WORKLOAD_GRANT_PAYLOAD_SCHEMA;
+    grantId: string;
+    capabilityId: string;
+    capabilitySha256: string;
+    receiptId: string;
+    receiptSha256: string;
+    workspaceId: string;
+    taskId: string;
+    actorUserId: string;
+    runId: string;
+    phase: ExecutorPhaseAPhase;
+    roleArn: string;
+    accountId: string;
+    region: 'us-west-2';
+    sourceIdentity: string;
+    sessionTags: Record<'TaskforceRun' | 'TaskforceReceipt' | 'TaskforcePhase' | 'TaskforceWorkspaceHash' | 'TaskforceSource', string>;
+    brokerKeyFingerprint: string;
+    nonceId: string;
+    senderProofSha256: string;
+    policySha256: string;
+    issuedAt: string;
+    expiresAt: string;
+}
+export interface ExecutorPhaseAWorkloadGrant {
+    payload: ExecutorPhaseAWorkloadGrantPayload;
+    envelope: ExecutorPhaseASignatureEnvelope;
+}
+declare const verifiedRunCapabilityBrand: unique symbol;
+declare const verifiedWorkloadGrantBundleBrand: unique symbol;
+export type VerifiedExecutorPhaseARunCapability = ExecutorPhaseARunCapability & {
+    readonly [verifiedRunCapabilityBrand]: true;
+};
+export interface VerifiedExecutorPhaseAWorkloadGrantBundle {
+    readonly capability: VerifiedExecutorPhaseARunCapability;
+    readonly grant: ExecutorPhaseAWorkloadGrant;
+    readonly senderProof: ExecutorPhaseASenderProof;
+    readonly grantSha256: string;
+    readonly senderProofSha256: string;
+    readonly [verifiedWorkloadGrantBundleBrand]: true;
+}
+export declare function executorPhaseARoleMapSha256(roleMap: ExecutorPhaseARoleMap): string;
+export declare function executorPhaseABrokerKeyFingerprint(publicKeySpkiBase64: string): string;
+export declare function executorPhaseASourceIdentity(runId: string, phase: ExecutorPhaseAPhase): string;
+export declare function assertExecutorPhaseARoleMap(roleMap: ExecutorPhaseARoleMap): void;
+export declare function assertExecutorPhaseAAccountAuthorities(accountId: string, readPrincipalArn: string, roleMap: ExecutorPhaseARoleMap): void;
+export declare function assertExecutorPhaseARunCapabilitySemantics(payload: ExecutorPhaseARunCapabilityPayload, receipt: ExecutorPhaseAApprovalReceipt): void;
+export declare function assertExecutorPhaseASenderProofSemantics(payload: ExecutorPhaseASenderProofPayload, now: Date): void;
+export declare function assertExecutorPhaseAWorkloadGrantSemantics(payload: ExecutorPhaseAWorkloadGrantPayload, capabilityArtifact: ExecutorPhaseARunCapability, senderProof: ExecutorPhaseASenderProof, expectedRequestSha256: string, expectedPolicySha256: string, cloudPublicKey: KeyObject, brokerPublicKey: KeyObject): void;
+export declare function verifyExecutorPhaseARunCapabilityArtifact(artifact: ExecutorPhaseARunCapability, receipt: ExecutorPhaseAApprovalReceipt, cloudPublicKey: KeyObject, now?: Date): VerifiedExecutorPhaseARunCapability;
+export declare function verifyExecutorPhaseAWorkloadGrantBundle(grant: ExecutorPhaseAWorkloadGrant, capability: VerifiedExecutorPhaseARunCapability, senderProof: ExecutorPhaseASenderProof, expectedRequestSha256: string, expectedPolicySha256: string, cloudPublicKey: KeyObject, brokerPublicKey: KeyObject, now?: Date): VerifiedExecutorPhaseAWorkloadGrantBundle;
+export {};

package/dist/shared/executorPhaseARunAuthorization.js

@@ -0,0 +1,232 @@
+import { createHash, createPublicKey, verify } from 'crypto';
+import { EXECUTOR_PHASE_A_PHASES, canonicalizeExecutorPhaseAJson, } from './executorPhaseAApprovalReceipt.js';
+import { assertExecutorPhaseASchema } from './executorPhaseASchemaValidation.js';
+import { EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS } from './executorPhaseATiming.js';
+export const EXECUTOR_PHASE_A_RUN_CAPABILITY_PAYLOAD_SCHEMA = 'taskforce.executor-phase-a-run-capability-payload/v1';
+export const EXECUTOR_PHASE_A_SENDER_PROOF_PAYLOAD_SCHEMA = 'taskforce.executor-phase-a-sender-proof-payload/v1';
+export const EXECUTOR_PHASE_A_WORKLOAD_GRANT_PAYLOAD_SCHEMA = 'taskforce.executor-phase-a-workload-grant-payload/v1';
+export const EXECUTOR_PHASE_A_MAIN_CAPABILITY_TTL_MS = 10 * 60 * 60 * 1000;
+export const EXECUTOR_PHASE_A_CLEANUP_CAPABILITY_TTL_MS = 2 * 60 * 60 * 1000;
+export const EXECUTOR_PHASE_A_SENDER_PROOF_TTL_MS = 2 * 60 * 1000;
+export const EXECUTOR_PHASE_A_WORKLOAD_GRANT_TTL_MS = 2 * 60 * 1000;
+const verifiedRunCapabilityBrand = Symbol('verifiedExecutorPhaseARunCapability');
+const verifiedWorkloadGrantBundleBrand = Symbol('verifiedExecutorPhaseAWorkloadGrantBundle');
+export function executorPhaseARoleMapSha256(roleMap) {
+    return createHash('sha256').update(canonicalizeExecutorPhaseAJson(roleMap)).digest('hex');
+}
+export function executorPhaseABrokerKeyFingerprint(publicKeySpkiBase64) {
+    const der = Buffer.from(publicKeySpkiBase64, 'base64');
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(publicKeySpkiBase64) || der.toString('base64') !== publicKeySpkiBase64) {
+        throw new TypeError('The broker public key must be canonical base64-encoded SPKI.');
+    }
+    const key = createPublicKey({ key: der, format: 'der', type: 'spki' });
+    if (key.asymmetricKeyType !== 'ed25519' || der.length !== 44) {
+        throw new TypeError('The broker public key must be Ed25519 SPKI.');
+    }
+    return createHash('sha256').update(der).digest('hex');
+}
+export function executorPhaseASourceIdentity(runId, phase) {
+    if (!/^phase-a-[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(runId)
+        || !EXECUTOR_PHASE_A_PHASES.includes(phase)) {
+        throw new TypeError('The Phase A SourceIdentity inputs are invalid.');
+    }
+    const runDigest = createHash('sha256').update(runId, 'utf8').digest('base64url');
+    const sourceIdentity = `tfr.${runDigest}.${phase}`;
+    if (sourceIdentity.length > 64 || !/^[\w+=,.@-]+$/.test(sourceIdentity)) {
+        throw new TypeError('The Phase A SourceIdentity is not accepted by AWS STS.');
+    }
+    return sourceIdentity;
+}
+export function assertExecutorPhaseARoleMap(roleMap) {
+    const keys = Object.keys(roleMap).sort();
+    if (keys.length !== EXECUTOR_PHASE_A_PHASES.length
+        || !EXECUTOR_PHASE_A_PHASES.every((phase) => keys.includes(phase))) {
+        throw new TypeError('The Phase A role map must contain every fixed phase exactly once.');
+    }
+    for (const [phase, arn] of Object.entries(roleMap)) {
+        if (!/^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/.test(arn)) {
+            throw new TypeError(`The ${phase} Phase A role ARN is invalid.`);
+        }
+    }
+}
+function arnAccountId(arn) {
+    return /^arn:aws:(?:iam|sts)::([0-9]{12}):/.exec(arn)?.[1] ?? null;
+}
+export function assertExecutorPhaseAAccountAuthorities(accountId, readPrincipalArn, roleMap) {
+    assertExecutorPhaseARoleMap(roleMap);
+    if (arnAccountId(readPrincipalArn) !== accountId
+        || Object.values(roleMap).some((roleArn) => arnAccountId(roleArn) !== accountId)) {
+        throw new TypeError('Every Phase A authority must belong to the approved AWS account.');
+    }
+}
+function exactTimestamp(value, field) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        throw new TypeError(`${field} is invalid.`);
+    return parsed;
+}
+function assertExecutorPhaseAEd25519Artifact(artifact, publicKey) {
+    if (publicKey.asymmetricKeyType !== 'ed25519' || artifact.envelope.algorithm !== 'Ed25519') {
+        throw new TypeError('The signed authorization artifact uses an untrusted algorithm or key type.');
+    }
+    const payloadBytes = canonicalizeExecutorPhaseAJson(artifact.payload);
+    const signature = Buffer.from(artifact.envelope.signature, 'base64url');
+    if (artifact.envelope.payloadSha256 !== createHash('sha256').update(payloadBytes).digest('hex')
+        || signature.length !== 64 || signature.toString('base64url') !== artifact.envelope.signature
+        || !verify(null, payloadBytes, publicKey, signature)) {
+        throw new TypeError('The signed authorization artifact is not authentic.');
+    }
+}
+export function assertExecutorPhaseARunCapabilitySemantics(payload, receipt) {
+    assertExecutorPhaseAAccountAuthorities(payload.accountId, payload.readPrincipalArn, payload.mutationRoles);
+    if (executorPhaseARoleMapSha256(payload.mutationRoles) !== payload.roleMapSha256
+        || executorPhaseABrokerKeyFingerprint(payload.brokerPublicKeySpkiBase64) !== payload.brokerKeyFingerprint) {
+        throw new TypeError('The run capability role map or broker-key digest is invalid.');
+    }
+    const issuedAt = exactTimestamp(payload.issuedAt, 'issuedAt');
+    const expiresAt = exactTimestamp(payload.expiresAt, 'expiresAt');
+    const mutationDeadline = exactTimestamp(payload.mutationDeadline, 'mutationDeadline');
+    const cleanupDeadline = exactTimestamp(payload.cleanupDeadline, 'cleanupDeadline');
+    const approvedAt = exactTimestamp(receipt.payload.approvedAt, 'receipt.approvedAt');
+    const receiptExpiresAt = exactTimestamp(receipt.payload.expiresAt, 'receipt.expiresAt');
+    const receiptSha256 = createHash('sha256').update(canonicalizeExecutorPhaseAJson(receipt)).digest('hex');
+    const budgetsSha256 = createHash('sha256').update(canonicalizeExecutorPhaseAJson(receipt.payload.budgets)).digest('hex');
+    if (payload.receiptId !== receipt.payload.receiptId || payload.receiptSha256 !== receiptSha256
+        || payload.capabilityKind !== receipt.payload.receiptKind
+        || payload.originalCapabilityId !== receipt.payload.originalCapabilityId
+        || payload.residualInventorySha256 !== receipt.payload.residualInventorySha256
+        || payload.workspaceId !== receipt.payload.workspaceId || payload.taskId !== receipt.payload.taskId
+        || payload.actorUserId !== receipt.payload.actorUserId || payload.runId !== receipt.payload.runId
+        || payload.accountId !== receipt.payload.accountId || payload.region !== receipt.payload.region
+        || payload.availabilityZone !== receipt.payload.availabilityZone
+        || payload.sourceCommit !== receipt.payload.sourceCommit
+        || payload.preflightSha256 !== receipt.payload.preflightSha256
+        || payload.logicalEnvelopeSha256 !== receipt.payload.logicalEnvelopeSha256
+        || payload.budgetsSha256 !== budgetsSha256
+        || payload.readPrincipalArn !== receipt.payload.readPrincipalArn
+        || payload.roleMapSha256 !== receipt.payload.roleMapSha256
+        || payload.oidcIssuer !== receipt.payload.oidcIssuer || payload.oidcAudience !== receipt.payload.oidcAudience
+        || payload.brokerPublicKeySpkiBase64 !== receipt.payload.brokerPublicKeySpkiBase64
+        || payload.brokerKeyFingerprint !== receipt.payload.brokerKeyFingerprint
+        || mutationDeadline !== exactTimestamp(receipt.payload.mutationDeadline, 'receipt.mutationDeadline')
+        || cleanupDeadline !== exactTimestamp(receipt.payload.cleanupDeadline, 'receipt.cleanupDeadline')
+        || issuedAt < approvedAt || issuedAt >= receiptExpiresAt || issuedAt >= cleanupDeadline) {
+        throw new TypeError('The run capability is not bound to the exact signed approval receipt.');
+    }
+    if (payload.capabilityKind === 'main') {
+        if (payload.originalCapabilityId !== null
+            || payload.residualInventorySha256 !== null
+            || mutationDeadline !== approvedAt + 8 * 60 * 60 * 1000
+            || cleanupDeadline !== approvedAt + EXECUTOR_PHASE_A_MAIN_CAPABILITY_TTL_MS
+            || expiresAt !== cleanupDeadline
+            || payload.allowedPhases.length !== EXECUTOR_PHASE_A_PHASES.length
+            || !EXECUTOR_PHASE_A_PHASES.every((phase) => payload.allowedPhases.includes(phase))) {
+            throw new TypeError('The main run capability lifetime, ancestry, or phase set is invalid.');
+        }
+        return;
+    }
+    if (!payload.originalCapabilityId || !payload.residualInventorySha256
+        || !/^[a-f0-9]{64}$/.test(payload.residualInventorySha256)
+        || payload.allowedPhases.length !== 1 || payload.allowedPhases[0] !== 'cleanup'
+        || mutationDeadline !== approvedAt || expiresAt !== cleanupDeadline
+        || cleanupDeadline !== approvedAt + EXECUTOR_PHASE_A_CLEANUP_CAPABILITY_TTL_MS) {
+        throw new TypeError('The cleanup-only run capability lifetime, ancestry, or phase set is invalid.');
+    }
+}
+export function assertExecutorPhaseASenderProofSemantics(payload, now) {
+    const createdAt = exactTimestamp(payload.createdAt, 'createdAt');
+    const expiresAt = exactTimestamp(payload.expiresAt, 'expiresAt');
+    const nowMs = now.getTime();
+    if (createdAt > nowMs + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS
+        || nowMs >= expiresAt + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS
+        || expiresAt <= createdAt
+        || expiresAt - createdAt > EXECUTOR_PHASE_A_SENDER_PROOF_TTL_MS) {
+        throw new TypeError('The sender proof is future-dated, expired, or exceeds two minutes.');
+    }
+}
+export function assertExecutorPhaseAWorkloadGrantSemantics(payload, capabilityArtifact, senderProof, expectedRequestSha256, expectedPolicySha256, cloudPublicKey, brokerPublicKey) {
+    const capability = capabilityArtifact.payload;
+    assertExecutorPhaseAEd25519Artifact(capabilityArtifact, cloudPublicKey);
+    assertExecutorPhaseAEd25519Artifact(senderProof, brokerPublicKey);
+    const brokerDer = brokerPublicKey.export({ format: 'der', type: 'spki' });
+    if (createHash('sha256').update(brokerDer).digest('hex') !== capability.brokerKeyFingerprint) {
+        throw new TypeError('The sender-proof key differs from the capability broker key.');
+    }
+    const issuedAt = exactTimestamp(payload.issuedAt, 'issuedAt');
+    const expiresAt = exactTimestamp(payload.expiresAt, 'expiresAt');
+    const capabilitySha256 = createHash('sha256').update(canonicalizeExecutorPhaseAJson(capabilityArtifact)).digest('hex');
+    const senderProofSha256 = createHash('sha256').update(canonicalizeExecutorPhaseAJson(senderProof)).digest('hex');
+    if (expiresAt <= issuedAt || expiresAt - issuedAt > EXECUTOR_PHASE_A_WORKLOAD_GRANT_TTL_MS
+        || payload.capabilityId !== capability.capabilityId
+        || payload.capabilitySha256 !== capabilitySha256
+        || payload.receiptId !== capability.receiptId || payload.receiptSha256 !== capability.receiptSha256
+        || payload.workspaceId !== capability.workspaceId || payload.taskId !== capability.taskId
+        || payload.actorUserId !== capability.actorUserId || payload.runId !== capability.runId
+        || payload.accountId !== capability.accountId || payload.region !== capability.region
+        || payload.brokerKeyFingerprint !== capability.brokerKeyFingerprint
+        || payload.roleArn !== capability.mutationRoles[payload.phase]
+        || !capability.allowedPhases.includes(payload.phase)
+        || payload.nonceId !== senderProof.payload.nonceId
+        || payload.senderProofSha256 !== senderProofSha256
+        || senderProof.payload.capabilityId !== capability.capabilityId
+        || senderProof.payload.phase !== payload.phase
+        || senderProof.payload.requestSha256 !== expectedRequestSha256
+        || senderProof.envelope.brokerKeyFingerprint !== capability.brokerKeyFingerprint
+        || payload.policySha256 !== expectedPolicySha256
+        || payload.sourceIdentity !== executorPhaseASourceIdentity(capability.runId, payload.phase)
+        || payload.sessionTags.TaskforceRun !== capability.runId
+        || payload.sessionTags.TaskforceReceipt !== capability.receiptId
+        || payload.sessionTags.TaskforcePhase !== payload.phase
+        || payload.sessionTags.TaskforceWorkspaceHash !== createHash('sha256')
+            .update(canonicalizeExecutorPhaseAJson(capability.workspaceId)).digest('hex')
+        || payload.sessionTags.TaskforceSource !== capability.sourceCommit) {
+        throw new TypeError('The workload grant lifetime or capability binding is invalid.');
+    }
+    assertExecutorPhaseASenderProofSemantics(senderProof.payload, new Date(issuedAt));
+    const deadline = exactTimestamp(payload.phase === 'cleanup' ? capability.cleanupDeadline : capability.mutationDeadline, payload.phase === 'cleanup' ? 'cleanupDeadline' : 'mutationDeadline');
+    if (issuedAt >= deadline || expiresAt > deadline) {
+        throw new TypeError('The workload grant exceeds its approved phase deadline.');
+    }
+}
+export function verifyExecutorPhaseARunCapabilityArtifact(artifact, receipt, cloudPublicKey, now = new Date()) {
+    assertExecutorPhaseASchema('approvalReceipt', receipt);
+    assertExecutorPhaseASchema('runCapability', artifact);
+    if (receipt.envelope.keyId !== artifact.envelope.keyId) {
+        throw new TypeError('The receipt and run capability use different Cloud trust keys.');
+    }
+    assertExecutorPhaseAEd25519Artifact(receipt, cloudPublicKey);
+    assertExecutorPhaseAEd25519Artifact(artifact, cloudPublicKey);
+    assertExecutorPhaseARunCapabilitySemantics(artifact.payload, receipt);
+    const nowMs = now.getTime();
+    const issuedAt = exactTimestamp(artifact.payload.issuedAt, 'issuedAt');
+    const expiresAt = exactTimestamp(artifact.payload.expiresAt, 'expiresAt');
+    if (nowMs + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS < issuedAt
+        || nowMs >= expiresAt + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS) {
+        throw new TypeError('The run capability is future-dated or expired.');
+    }
+    return Object.assign(structuredClone(artifact), { [verifiedRunCapabilityBrand]: true });
+}
+export function verifyExecutorPhaseAWorkloadGrantBundle(grant, capability, senderProof, expectedRequestSha256, expectedPolicySha256, cloudPublicKey, brokerPublicKey, now = new Date()) {
+    assertExecutorPhaseASchema('workloadGrant', grant);
+    assertExecutorPhaseASchema('senderProof', senderProof);
+    if (grant.envelope.keyId !== capability.envelope.keyId) {
+        throw new TypeError('The workload grant and run capability use different Cloud trust keys.');
+    }
+    assertExecutorPhaseAEd25519Artifact(grant, cloudPublicKey);
+    assertExecutorPhaseAWorkloadGrantSemantics(grant.payload, capability, senderProof, expectedRequestSha256, expectedPolicySha256, cloudPublicKey, brokerPublicKey);
+    const nowMs = now.getTime();
+    if (nowMs + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS < exactTimestamp(grant.payload.issuedAt, 'grant.issuedAt')
+        || nowMs >= exactTimestamp(grant.payload.expiresAt, 'grant.expiresAt')
+            + EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS) {
+        throw new TypeError('The workload grant is future-dated or expired.');
+    }
+    assertExecutorPhaseASenderProofSemantics(senderProof.payload, now);
+    return {
+        capability,
+        grant: structuredClone(grant),
+        senderProof: structuredClone(senderProof),
+        grantSha256: createHash('sha256').update(canonicalizeExecutorPhaseAJson(grant)).digest('hex'),
+        senderProofSha256: createHash('sha256').update(canonicalizeExecutorPhaseAJson(senderProof)).digest('hex'),
+        [verifiedWorkloadGrantBundleBrand]: true,
+    };
+}

package/dist/shared/executorPhaseASchemaValidation.d.ts

@@ -0,0 +1,7 @@
+import { type ErrorObject } from 'ajv/dist/2020.js';
+export type ExecutorPhaseASchemaName = 'approvalReceipt' | 'driftAttestation' | 'driftRequest' | 'foundationManifest' | 'issuerAuditRecord' | 'issuerProof' | 'issuerRedemptionRequest' | 'issuerRedemptionResponse' | 'report' | 'runCapability' | 'senderProof' | 'workloadGrant' | 'workloadJwtClaims';
+export declare class ExecutorPhaseASchemaValidationError extends TypeError {
+    readonly schemaName: ExecutorPhaseASchemaName;
+    constructor(schemaName: ExecutorPhaseASchemaName, errors: ErrorObject[] | null | undefined);
+}
+export declare function assertExecutorPhaseASchema(name: ExecutorPhaseASchemaName, value: unknown): void;

package/dist/shared/executorPhaseASchemaValidation.js

@@ -0,0 +1,53 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import approvalReceiptSchema from './executorPhaseASchemas/approval-receipt.schema.json' with { type: 'json' };
+import driftAttestationSchema from './executorPhaseASchemas/drift-attestation.schema.json' with { type: 'json' };
+import driftRequestSchema from './executorPhaseASchemas/drift-request.schema.json' with { type: 'json' };
+import foundationManifestSchema from './executorPhaseASchemas/foundation-manifest.schema.json' with { type: 'json' };
+import issuerAuditRecordSchema from './executorPhaseASchemas/issuer-audit-record.schema.json' with { type: 'json' };
+import issuerProofSchema from './executorPhaseASchemas/issuer-proof.schema.json' with { type: 'json' };
+import issuerRedemptionRequestSchema from './executorPhaseASchemas/issuer-redemption-request.schema.json' with { type: 'json' };
+import issuerRedemptionResponseSchema from './executorPhaseASchemas/issuer-redemption-response.schema.json' with { type: 'json' };
+import logicalEnvelopeSchema from './executorPhaseASchemas/logical-envelope.schema.json' with { type: 'json' };
+import preflightReportSchema from './executorPhaseASchemas/preflight-report.schema.json' with { type: 'json' };
+import runCapabilitySchema from './executorPhaseASchemas/run-capability.schema.json' with { type: 'json' };
+import senderProofSchema from './executorPhaseASchemas/sender-proof.schema.json' with { type: 'json' };
+import workloadGrantSchema from './executorPhaseASchemas/workload-grant.schema.json' with { type: 'json' };
+import workloadJwtClaimsSchema from './executorPhaseASchemas/workload-jwt-claims.schema.json' with { type: 'json' };
+const ajv = new Ajv2020({ strict: true, strictRequired: false, allErrors: true });
+ajv.addSchema(logicalEnvelopeSchema);
+ajv.addSchema(approvalReceiptSchema);
+ajv.addSchema(runCapabilitySchema);
+ajv.addSchema(senderProofSchema);
+ajv.addSchema(workloadGrantSchema);
+ajv.addSchema(issuerProofSchema);
+const validators = {
+    approvalReceipt: ajv.getSchema(approvalReceiptSchema.$id),
+    driftAttestation: ajv.compile(driftAttestationSchema),
+    driftRequest: ajv.compile(driftRequestSchema),
+    foundationManifest: ajv.compile(foundationManifestSchema),
+    issuerAuditRecord: ajv.compile(issuerAuditRecordSchema),
+    issuerProof: ajv.getSchema(issuerProofSchema.$id),
+    issuerRedemptionRequest: ajv.compile(issuerRedemptionRequestSchema),
+    issuerRedemptionResponse: ajv.compile(issuerRedemptionResponseSchema),
+    report: ajv.compile(preflightReportSchema),
+    runCapability: ajv.getSchema(runCapabilitySchema.$id),
+    senderProof: ajv.getSchema(senderProofSchema.$id),
+    workloadGrant: ajv.getSchema(workloadGrantSchema.$id),
+    workloadJwtClaims: ajv.compile(workloadJwtClaimsSchema),
+};
+function formatErrors(errors) {
+    return ajv.errorsText(errors, { separator: '; ' });
+}
+export class ExecutorPhaseASchemaValidationError extends TypeError {
+    schemaName;
+    constructor(schemaName, errors) {
+        super(`${schemaName} schema validation failed: ${formatErrors(errors)}`);
+        this.schemaName = schemaName;
+        this.name = 'ExecutorPhaseASchemaValidationError';
+    }
+}
+export function assertExecutorPhaseASchema(name, value) {
+    const validator = validators[name];
+    if (!validator(value))
+        throw new ExecutorPhaseASchemaValidationError(name, validator.errors);
+}