@taskforcehq/taskforce 0.3.328 → 0.3.330

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 };
+}

package/dist/services/githubReviewEvidenceService.d.ts

@@ -0,0 +1,93 @@
+import type { GitHubReviewEvidenceInstallationBinding } from '../storage/githubReviewEvidenceInstallationStore.js';
+export type GitHubReviewEvidenceErrorCode = 'github_app_not_configured' | 'github_installation_not_bound' | 'github_installation_unavailable' | 'github_installation_revoked' | 'github_permission_denied' | 'github_rate_limited' | 'github_repository_unavailable' | 'github_evidence_mismatch' | 'github_pull_request_not_reviewable' | 'github_request_timed_out';
+export declare class GitHubReviewEvidenceError extends Error {
+    readonly code: GitHubReviewEvidenceErrorCode;
+    readonly statusCode: number;
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, code: GitHubReviewEvidenceErrorCode, statusCode: number, retryAfterSeconds?: number | null);
+}
+export interface GitHubReviewAppConfig {
+    appId: string;
+    privateKey: string;
+}
+export interface GitHubInstallationInspection {
+    installationId: string;
+    accountId: string;
+    accountLogin: string;
+    accountType: string;
+    repositorySelection: string;
+}
+export interface GitHubReviewEvidenceRequest {
+    workspaceId: string;
+    repositoryFullName: string;
+    commitSha: string;
+    pullRequestNumber: number;
+    expectedBaseRef?: string | null;
+    expectedHeadRef?: string | null;
+    integrationBranch?: string | null;
+}
+export interface VerifiedGitHubReviewEvidence {
+    repository: {
+        id: string;
+        fullName: string;
+        private: boolean;
+        defaultBranch: string;
+    };
+    commit: {
+        sha: string;
+    };
+    pullRequest: {
+        number: number;
+        state: string;
+        merged: boolean;
+        mergeCommitSha: string | null;
+        head: {
+            ref: string;
+            sha: string;
+        };
+        base: {
+            ref: string;
+            sha: string;
+        };
+    };
+    integration: {
+        branch: string;
+        comparisonStatus: 'ahead' | 'identical';
+        containsCommit: true;
+    } | null;
+    verifiedAt: string;
+}
+export interface GitHubReviewEvidenceVerifier {
+    verify(request: GitHubReviewEvidenceRequest): Promise<VerifiedGitHubReviewEvidence>;
+}
+interface GitHubReviewEvidenceServiceOptions {
+    config: GitHubReviewAppConfig | null;
+    getBinding: (workspaceId: string) => GitHubReviewEvidenceInstallationBinding | null;
+    fetchImpl?: typeof fetch;
+    apiBaseUrl?: string;
+    timeoutMs?: number;
+    now?: () => Date;
+    audit?: (event: {
+        action: 'github.review-evidence.verify.succeeded' | 'github.review-evidence.verify.failed';
+        workspaceId: string;
+        repositoryFullName: string;
+        commitSha: string;
+        pullRequestNumber: number;
+        code?: GitHubReviewEvidenceErrorCode;
+    }) => void;
+}
+export declare function resolveGitHubReviewAppConfig(env?: NodeJS.ProcessEnv): GitHubReviewAppConfig | null;
+export declare class GitHubReviewEvidenceService implements GitHubReviewEvidenceVerifier {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly apiBaseUrl;
+    private readonly timeoutMs;
+    private readonly now;
+    constructor(options: GitHubReviewEvidenceServiceOptions);
+    private requireConfig;
+    private requestJson;
+    inspectInstallation(installationId: string): Promise<GitHubInstallationInspection>;
+    private mintRepositoryToken;
+    verify(request: GitHubReviewEvidenceRequest): Promise<VerifiedGitHubReviewEvidence>;
+}
+export {};

package/dist/services/githubReviewEvidenceService.js

@@ -0,0 +1,336 @@
+import { sign } from 'crypto';
+const DEFAULT_API_BASE_URL = 'https://api.github.com';
+const API_VERSION = '2026-03-10';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_GITHUB_RESPONSE_BYTES = 2 * 1024 * 1024;
+export class GitHubReviewEvidenceError extends Error {
+    code;
+    statusCode;
+    retryAfterSeconds;
+    constructor(message, code, statusCode, retryAfterSeconds = null) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'GitHubReviewEvidenceError';
+    }
+}
+export function resolveGitHubReviewAppConfig(env = process.env) {
+    const appId = String(env.TASKFORCE_GITHUB_REVIEW_APP_ID || '').trim();
+    const encodedPrivateKey = String(env.TASKFORCE_GITHUB_REVIEW_APP_PRIVATE_KEY_BASE64 || '').trim();
+    const privateKey = encodedPrivateKey ? Buffer.from(encodedPrivateKey, 'base64').toString('utf8') : '';
+    return appId && privateKey ? { appId, privateKey } : null;
+}
+function createAppJwt(config, now) {
+    const issuedAt = Math.floor(now.getTime() / 1_000) - 60;
+    const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify({
+        iat: issuedAt,
+        exp: issuedAt + 9 * 60,
+        iss: config.appId,
+    })).toString('base64url');
+    const signingInput = `${header}.${payload}`;
+    try {
+        const signature = sign('RSA-SHA256', Buffer.from(signingInput), config.privateKey).toString('base64url');
+        return `${signingInput}.${signature}`;
+    }
+    catch {
+        throw new GitHubReviewEvidenceError('GitHub review verification is not configured correctly.', 'github_app_not_configured', 503);
+    }
+}
+function requiredString(value, label, maxLength = 255) {
+    const normalized = String(value || '').trim();
+    if (!normalized || normalized.length > maxLength || /[\u0000-\u001f\u007f]/.test(normalized)) {
+        throw new GitHubReviewEvidenceError(`${label} is invalid.`, 'github_evidence_mismatch', 400);
+    }
+    return normalized;
+}
+function normalizeRepositoryFullName(value) {
+    const fullName = requiredString(value, 'repositoryFullName', 201);
+    const parts = fullName.split('/');
+    if (parts.length !== 2 || !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(parts[0]) || !/^[A-Za-z0-9._-]{1,100}$/.test(parts[1])) {
+        throw new GitHubReviewEvidenceError('repositoryFullName is invalid.', 'github_evidence_mismatch', 400);
+    }
+    return { owner: parts[0], name: parts[1], fullName };
+}
+function normalizeSha(value) {
+    const sha = String(value || '').trim().toLowerCase();
+    if (!/^[0-9a-f]{40}$/.test(sha)) {
+        throw new GitHubReviewEvidenceError('commitSha must be a full 40-character SHA.', 'github_evidence_mismatch', 400);
+    }
+    return sha;
+}
+function retryAfterSeconds(response) {
+    const raw = Number(response.headers.get('retry-after'));
+    if (Number.isFinite(raw) && raw > 0)
+        return Math.ceil(raw);
+    const reset = Number(response.headers.get('x-ratelimit-reset'));
+    if (Number.isFinite(reset) && reset > 0)
+        return Math.max(1, Math.ceil(reset - Date.now() / 1_000));
+    return null;
+}
+function mapGitHubHttpError(response, installationRequest) {
+    if (response.status === 401) {
+        return new GitHubReviewEvidenceError('The GitHub App installation is no longer authorized.', 'github_installation_revoked', 503);
+    }
+    if (response.status === 429
+        || (response.status === 403 && (response.headers.get('x-ratelimit-remaining') === '0'
+            || response.headers.has('retry-after')))) {
+        return new GitHubReviewEvidenceError('GitHub verification is temporarily rate limited.', 'github_rate_limited', 503, retryAfterSeconds(response));
+    }
+    if (response.status === 403) {
+        return new GitHubReviewEvidenceError('The GitHub App installation lacks a required read permission.', 'github_permission_denied', 503);
+    }
+    if (response.status === 404) {
+        if (installationRequest) {
+            return new GitHubReviewEvidenceError('The GitHub App installation is no longer authorized.', 'github_installation_revoked', 503);
+        }
+        return new GitHubReviewEvidenceError('The repository or evidence is unavailable to this GitHub App installation.', 'github_repository_unavailable', 422);
+    }
+    if (response.status === 422) {
+        return new GitHubReviewEvidenceError('The repository or evidence is unavailable to this GitHub App installation.', 'github_repository_unavailable', 422);
+    }
+    return new GitHubReviewEvidenceError('GitHub verification is temporarily unavailable.', 'github_installation_unavailable', 503);
+}
+async function readBoundedJson(response) {
+    const contentLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(contentLength) && contentLength > MAX_GITHUB_RESPONSE_BYTES) {
+        throw new GitHubReviewEvidenceError('GitHub returned an invalid verification response.', 'github_installation_unavailable', 503);
+    }
+    if (!response.body) {
+        throw new GitHubReviewEvidenceError('GitHub returned an invalid verification response.', 'github_installation_unavailable', 503);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            size += value.byteLength;
+            if (size > MAX_GITHUB_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new GitHubReviewEvidenceError('GitHub returned an invalid verification response.', 'github_installation_unavailable', 503);
+            }
+            chunks.push(value);
+        }
+        const body = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString('utf8');
+        return JSON.parse(body);
+    }
+    catch (error) {
+        if (error instanceof GitHubReviewEvidenceError)
+            throw error;
+        throw new GitHubReviewEvidenceError('GitHub returned an invalid verification response.', 'github_installation_unavailable', 503);
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+export class GitHubReviewEvidenceService {
+    options;
+    fetchImpl;
+    apiBaseUrl;
+    timeoutMs;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl || fetch;
+        this.apiBaseUrl = String(options.apiBaseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, '');
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.now = options.now || (() => new Date());
+    }
+    requireConfig() {
+        if (!this.options.config) {
+            throw new GitHubReviewEvidenceError('GitHub review verification is not configured.', 'github_app_not_configured', 503);
+        }
+        return this.options.config;
+    }
+    async requestJson(path, init, installationRequest = false) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchImpl(`${this.apiBaseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+                headers: {
+                    Accept: 'application/vnd.github+json',
+                    'X-GitHub-Api-Version': API_VERSION,
+                    'User-Agent': 'taskforce-review-evidence',
+                    ...(init.headers || {}),
+                },
+            });
+            if (!response.ok)
+                throw mapGitHubHttpError(response, installationRequest);
+            return await readBoundedJson(response);
+        }
+        catch (error) {
+            if (error instanceof GitHubReviewEvidenceError)
+                throw error;
+            if (error?.name === 'AbortError') {
+                throw new GitHubReviewEvidenceError('GitHub verification timed out.', 'github_request_timed_out', 503);
+            }
+            throw new GitHubReviewEvidenceError('GitHub verification is temporarily unavailable.', 'github_installation_unavailable', 503);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async inspectInstallation(installationId) {
+        const config = this.requireConfig();
+        const normalizedInstallationId = String(installationId || '').trim();
+        if (!/^\d+$/.test(normalizedInstallationId)) {
+            throw new GitHubReviewEvidenceError('installationId must be a numeric GitHub installation ID.', 'github_evidence_mismatch', 400);
+        }
+        const response = await this.requestJson(`/app/installations/${normalizedInstallationId}`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${createAppJwt(config, this.now())}` },
+        }, true);
+        if (response.suspended_at) {
+            throw new GitHubReviewEvidenceError('The GitHub App installation is suspended.', 'github_installation_revoked', 503);
+        }
+        const permissions = response.permissions || {};
+        if (permissions.contents !== 'read' || permissions.pull_requests !== 'read' || permissions.metadata !== 'read') {
+            throw new GitHubReviewEvidenceError('The GitHub App installation lacks required read permissions.', 'github_permission_denied', 503);
+        }
+        const accountId = String(response.account?.id || '').trim();
+        const accountLogin = String(response.account?.login || '').trim();
+        if (!accountId || !accountLogin) {
+            throw new GitHubReviewEvidenceError('The GitHub App installation metadata is incomplete.', 'github_installation_unavailable', 503);
+        }
+        return {
+            installationId: String(response.id || normalizedInstallationId),
+            accountId,
+            accountLogin,
+            accountType: String(response.account?.type || 'unknown'),
+            repositorySelection: String(response.repository_selection || 'selected'),
+        };
+    }
+    async mintRepositoryToken(binding, repositoryName) {
+        const config = this.requireConfig();
+        const response = await this.requestJson(`/app/installations/${binding.installationId}/access_tokens`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${createAppJwt(config, this.now())}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                repositories: [repositoryName],
+                permissions: { metadata: 'read', contents: 'read', pull_requests: 'read' },
+            }),
+        }, true);
+        const token = String(response.token || '').trim();
+        if (!token) {
+            throw new GitHubReviewEvidenceError('GitHub did not issue an installation token.', 'github_installation_unavailable', 503);
+        }
+        return token;
+    }
+    async verify(request) {
+        const workspaceId = requiredString(request.workspaceId, 'workspaceId');
+        const repository = normalizeRepositoryFullName(request.repositoryFullName);
+        const commitSha = normalizeSha(request.commitSha);
+        const pullRequestNumber = Number(request.pullRequestNumber);
+        if (!Number.isSafeInteger(pullRequestNumber) || pullRequestNumber < 1) {
+            throw new GitHubReviewEvidenceError('pullRequestNumber must be a positive integer.', 'github_evidence_mismatch', 400);
+        }
+        try {
+            const binding = this.options.getBinding(workspaceId);
+            if (!binding) {
+                throw new GitHubReviewEvidenceError('This workspace has no GitHub App installation binding.', 'github_installation_not_bound', 409);
+            }
+            const token = await this.mintRepositoryToken(binding, repository.name);
+            const authorization = { Authorization: `Bearer ${token}` };
+            const repoPath = `/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.name)}`;
+            const [repo, commit, pullRequest] = await Promise.all([
+                this.requestJson(repoPath, { method: 'GET', headers: authorization }),
+                this.requestJson(`${repoPath}/commits/${commitSha}`, { method: 'GET', headers: authorization }),
+                this.requestJson(`${repoPath}/pulls/${pullRequestNumber}`, { method: 'GET', headers: authorization }),
+            ]);
+            const actualRepo = String(repo.full_name || '').trim();
+            const actualCommitSha = String(commit.sha || '').trim().toLowerCase();
+            const headSha = String(pullRequest.head?.sha || '').trim().toLowerCase();
+            const headRef = String(pullRequest.head?.ref || '').trim();
+            const baseRef = String(pullRequest.base?.ref || '').trim();
+            const baseSha = String(pullRequest.base?.sha || '').trim().toLowerCase();
+            const headRepo = String(pullRequest.head?.repo?.full_name || '').trim();
+            const baseRepo = String(pullRequest.base?.repo?.full_name || '').trim();
+            if (actualRepo.toLowerCase() !== repository.fullName.toLowerCase()
+                || actualCommitSha !== commitSha
+                || Number(pullRequest.number) !== pullRequestNumber
+                || headSha !== commitSha
+                || headRepo.toLowerCase() !== repository.fullName.toLowerCase()
+                || baseRepo.toLowerCase() !== repository.fullName.toLowerCase()
+                || !/^[0-9a-f]{40}$/.test(baseSha)) {
+                throw new GitHubReviewEvidenceError('GitHub repository, commit, or pull-request evidence does not match the requested immutable identity.', 'github_evidence_mismatch', 422);
+            }
+            if (request.expectedHeadRef && headRef !== requiredString(request.expectedHeadRef, 'expectedHeadRef')) {
+                throw new GitHubReviewEvidenceError('The pull-request head branch does not match the expected branch.', 'github_evidence_mismatch', 422);
+            }
+            if (request.expectedBaseRef && baseRef !== requiredString(request.expectedBaseRef, 'expectedBaseRef')) {
+                throw new GitHubReviewEvidenceError('The pull-request base branch does not match the expected branch.', 'github_evidence_mismatch', 422);
+            }
+            const state = String(pullRequest.state || '').trim().toLowerCase();
+            const merged = pullRequest.merged === true;
+            if (state === 'closed' && !merged) {
+                throw new GitHubReviewEvidenceError('A closed, unmerged pull request is not valid review evidence.', 'github_pull_request_not_reviewable', 422);
+            }
+            let integration = null;
+            if (request.integrationBranch) {
+                const branch = requiredString(request.integrationBranch, 'integrationBranch');
+                const comparison = await this.requestJson(`${repoPath}/compare/${commitSha}...${encodeURIComponent(branch)}`, { method: 'GET', headers: authorization });
+                const comparisonStatus = String(comparison.status || '').trim().toLowerCase();
+                if (comparisonStatus !== 'ahead' && comparisonStatus !== 'identical') {
+                    throw new GitHubReviewEvidenceError('The requested commit is not reachable from the integration branch.', 'github_evidence_mismatch', 422);
+                }
+                integration = {
+                    branch,
+                    comparisonStatus,
+                    containsCommit: true,
+                };
+            }
+            const result = {
+                repository: {
+                    id: String(repo.id || ''),
+                    fullName: actualRepo,
+                    private: repo.private === true,
+                    defaultBranch: String(repo.default_branch || ''),
+                },
+                commit: { sha: actualCommitSha },
+                pullRequest: {
+                    number: Number(pullRequest.number || pullRequestNumber),
+                    state,
+                    merged,
+                    mergeCommitSha: pullRequest.merge_commit_sha ? String(pullRequest.merge_commit_sha).toLowerCase() : null,
+                    head: { ref: headRef, sha: headSha },
+                    base: { ref: baseRef, sha: baseSha },
+                },
+                integration,
+                verifiedAt: this.now().toISOString(),
+            };
+            this.options.audit?.({
+                action: 'github.review-evidence.verify.succeeded',
+                workspaceId,
+                repositoryFullName: repository.fullName,
+                commitSha,
+                pullRequestNumber,
+            });
+            return result;
+        }
+        catch (error) {
+            const normalized = error instanceof GitHubReviewEvidenceError
+                ? error
+                : new GitHubReviewEvidenceError('GitHub verification is temporarily unavailable.', 'github_installation_unavailable', 503);
+            this.options.audit?.({
+                action: 'github.review-evidence.verify.failed',
+                workspaceId,
+                repositoryFullName: repository.fullName,
+                commitSha,
+                pullRequestNumber,
+                code: normalized.code,
+            });
+            throw normalized;
+        }
+    }
+}

package/dist/services/modelGateway.d.ts

@@ -11,6 +11,7 @@ export interface ModelGatewaySelection {
     actorUserId?: string | null;
     connectionScope?: TaskforceAgentConnectionScope;
     connectionId?: string | null;
+    connectionOwnerUserId?: string | null;
 }
 export interface ModelProviderCredentialResolution {
     source: TaskforceAgentModelSource;
@@ -76,6 +77,12 @@ export interface ModelGatewayGenerateResult {
     stopReason?: string;
     usage?: ModelGatewayUsage;
     latencyMs?: number;
+    sourceMetadata?: {
+        modelSource: TaskforceAgentModelSource;
+        connectionScope?: TaskforceAgentConnectionScope;
+        providerKey: string;
+        billable: boolean;
+    };
 }
 export interface ModelGateway {
     generate(input: ModelGatewayGenerateInput): Promise<ModelGatewayGenerateResult>;