@voyant-travel/apps 0.7.0 → 0.8.0

package/dist/app-api-routes.js

@@ -1,9 +1,8 @@
 import { ApiHttpError, parseJsonBody, parseQuery, RequestValidationError, } from "@voyant-travel/hono";
 import { Hono } from "hono";
 import { z } from "zod";
-import { appApiAuditQuerySchema, appApiCustomFieldDefinitionCreateSchema, appApiCustomFieldDefinitionListQuerySchema, appApiCustomFieldDefinitionUpdateSchema, appApiCustomFieldValueListQuerySchema, appApiCustomFieldValueUpsertSchema, appApiEntityReadQuerySchema, appApiFinanceActionSchema, appApiFinanceDocumentQuerySchema, appApiFinanceExternalReferenceUpsertSchema, appApiTokenExchangeSchema, appApiVersionHeader, appApiWebhookReplaySchema, } from "./app-api-contracts.js";
+import { appApiAuditQuerySchema, appApiCustomFieldDefinitionCreateSchema, appApiCustomFieldDefinitionListQuerySchema, appApiCustomFieldDefinitionUpdateSchema, appApiCustomFieldValueListQuerySchema, appApiCustomFieldValueUpsertSchema, appApiEntityReadQuerySchema, appApiFinanceActionSchema, appApiFinanceDocumentQuerySchema, appApiFinanceExternalLifecycleStateSchema, appApiFinanceExternalReferenceUpsertSchema, appApiFinanceExternalSyncStateSchema, appApiFinancePdfArtifactHeadersSchema, appApiFinanceSettlementObservationSchema, appApiVersionHeader, appApiWebhookReplaySchema, } from "./app-api-contracts.js";
 import { createAppApiService, withAppApiDeadline, } from "./app-api-service.js";
-import { createAppOAuthService } from "./oauth-service.js";
 import { replayAppWebhookDelivery } from "./webhook-delivery.js";
 /** Absolute mount prefix for the versioned App API surface. */
 export const APP_API_BASE_PATH = "/v1/app";
@@ -24,8 +23,8 @@ const definitionUpdateBodySchema = z
 export function createAppsAppApiRoutes(options = {}) {
     const routes = new Hono();
     const service = createAppApiService(options);
-    const oauth = options.oauth ? createAppOAuthService(options.oauth) : null;
     const maxPayloadBytes = options.maxPayloadBytes ?? 256 * 1024;
+    const maxFinanceArtifactBytes = options.maxFinanceArtifactBytes ?? 10 * 1024 * 1024;
     routes.use("*", async (c, next) => {
         if (c.get("callerType") !== "app") {
             throw new ApiHttpError("App API requires an app access token.", {
@@ -33,12 +32,26 @@ export function createAppsAppApiRoutes(options = {}) {
                 code: "app_api_token_required",
             });
         }
-        const length = Number(c.req.header("content-length") ?? "0");
-        if (Number.isFinite(length) && length > maxPayloadBytes) {
+        const requestLimit = isFinancePdfArtifactRequest(c) ? maxFinanceArtifactBytes : maxPayloadBytes;
+        const declaredLength = c.req.header("content-length");
+        if (declaredLength !== undefined && !/^(0|[1-9][0-9]*)$/.test(declaredLength)) {
+            throw new ApiHttpError("App API Content-Length is invalid.", {
+                status: 400,
+                code: "app_api_content_length_invalid",
+            });
+        }
+        const length = Number(declaredLength ?? "0");
+        if (!Number.isSafeInteger(length)) {
+            throw new ApiHttpError("App API Content-Length is invalid.", {
+                status: 400,
+                code: "app_api_content_length_invalid",
+            });
+        }
+        if (length > requestLimit) {
             throw new ApiHttpError("App API payload is too large.", {
                 status: 413,
                 code: "app_api_payload_too_large",
-                details: { maxPayloadBytes },
+                details: { maxPayloadBytes: requestLimit },
             });
         }
         return next();
@@ -63,6 +76,54 @@ export function createAppsAppApiRoutes(options = {}) {
         const body = await parseJsonBody(c, appApiFinanceExternalReferenceUpsertSchema);
         return run(c, service.upsertFinanceExternalReference(c.get("db"), appContext(c), id, body), options.deadlineMs);
     });
+    routes.put("/finance/documents/:id/artifacts/provider-pdf", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        if (c.req.header("content-type")?.toLowerCase() !== "application/pdf") {
+            throw new ApiHttpError("Finance document artifact must be an application/pdf body.", {
+                status: 415,
+                code: "app_api_finance_artifact_media_type_unsupported",
+            });
+        }
+        const headers = parseArtifactHeaders(c);
+        const bytes = await readBoundedArtifactBody(c, maxFinanceArtifactBytes);
+        if (!hasPdfSignature(bytes)) {
+            throw new ApiHttpError("Finance document artifact is not a PDF.", {
+                status: 415,
+                code: "app_api_finance_artifact_invalid_pdf",
+            });
+        }
+        const result = await withAppApiDeadline(service.attachFinancePdfArtifact(c.get("db"), appContext(c), id, c.env, headers, bytes), options.deadlineMs);
+        return c.json({
+            data: {
+                outcome: result.data.outcome,
+                artifact: {
+                    id: result.data.artifact.id,
+                    documentId: result.data.artifact.documentId,
+                    provider: result.data.artifact.provider,
+                    fileName: result.data.artifact.fileName,
+                    byteSize: result.data.artifact.byteSize,
+                    checksum: result.data.artifact.checksum,
+                    createdAt: result.data.artifact.createdAt,
+                    documentUrl: financeArtifactDocumentUrl(c, result.data.artifact.id),
+                },
+            },
+        });
+    });
+    routes.put("/finance/documents/:id/external-sync-state", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, appApiFinanceExternalSyncStateSchema);
+        return run(c, service.updateFinanceExternalSyncState(c.get("db"), appContext(c), id, body), options.deadlineMs);
+    });
+    routes.put("/finance/documents/:id/external-lifecycle-state", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, appApiFinanceExternalLifecycleStateSchema);
+        return run(c, service.updateFinanceExternalLifecycleState(c.get("db"), appContext(c), id, body), options.deadlineMs);
+    });
+    routes.post("/finance/documents/:id/settlement-observations", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, appApiFinanceSettlementObservationSchema);
+        return run(c, service.recordFinanceSettlementObservation(c.get("db"), appContext(c), id, body), options.deadlineMs, 201);
+    });
     routes.post("/finance/actions", async (c) => {
         const body = await parseJsonBody(c, appApiFinanceActionSchema);
         return run(c, service.executeFinanceAction(c.get("db"), appContext(c), body), options.deadlineMs);
@@ -94,22 +155,6 @@ export function createAppsAppApiRoutes(options = {}) {
         }), options.deadlineMs, 202);
     });
     routes.get("/audit", (c) => run(c, service.listAuditHistory(c.get("db"), appContext(c), parseQuery(c, appApiAuditQuerySchema)), options.deadlineMs));
-    routes.post("/oauth/token-exchange", async (c) => {
-        if (!oauth)
-            return c.json({ error: "App OAuth is not configured" }, 501);
-        const context = appContext(c);
-        await service.requireAccess(c.get("db"), context, ["online-token:exchange"]);
-        const body = await parseJsonBody(c, appApiTokenExchangeSchema);
-        return run(c, oauth.token(c.get("db"), {
-            grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
-            installationId: context.installationId,
-            viewerId: body.viewer_id,
-            viewerScopes: body.viewer_scopes,
-            contextualScopes: body.contextual_scopes,
-            clientId: body.client_id,
-            clientSecret: body.client_secret,
-        }), options.deadlineMs);
-    });
     // Lazy route families forward the original absolute URL, so the loaded
     // sub-app must expose absolute paths. Mount the relative handlers under the
     // App API prefix; the matchers in api-runtime install `/v1/app` and
@@ -132,6 +177,7 @@ function appContext(c) {
         releaseId,
         tokenMode,
         viewerId: c.get("appViewerId"),
+        contextConstraint: c.get("appContextConstraint"),
         scopes: c.get("scopes") ?? [],
         apiVersion: c.req.header(appApiVersionHeader) ?? undefined,
     };
@@ -148,6 +194,69 @@ function parseEntityParams(input) {
         throw new RequestValidationError("Invalid route parameters");
     return parsed.data;
 }
+function parseArtifactHeaders(c) {
+    const parsed = appApiFinancePdfArtifactHeadersSchema.safeParse({
+        idempotencyKey: c.req.header("idempotency-key"),
+        fileName: c.req.header("x-voyant-artifact-name"),
+    });
+    if (!parsed.success)
+        throw new RequestValidationError("Invalid artifact request headers");
+    return parsed.data;
+}
+function isFinancePdfArtifactRequest(c) {
+    return (c.req.method === "PUT" &&
+        /^\/v1\/app\/finance\/documents\/[^/]+\/artifacts\/provider-pdf$/.test(c.req.path));
+}
+function hasPdfSignature(bytes) {
+    return (bytes.byteLength >= 5 &&
+        bytes[0] === 0x25 &&
+        bytes[1] === 0x50 &&
+        bytes[2] === 0x44 &&
+        bytes[3] === 0x46 &&
+        bytes[4] === 0x2d);
+}
+async function readBoundedArtifactBody(c, maxBytes) {
+    const body = c.req.raw.body;
+    if (!body)
+        return new Uint8Array();
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            total += next.value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel("Finance document artifact exceeded limit");
+                throw new ApiHttpError("Finance document artifact is too large.", {
+                    status: 413,
+                    code: "app_api_payload_too_large",
+                    details: { maxPayloadBytes: maxBytes },
+                });
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function financeArtifactDocumentUrl(c, artifactId) {
+    const path = `/v1/admin/finance/invoice-renditions/${encodeURIComponent(artifactId)}/download`;
+    const configuredApiBaseUrl = c.env.API_BASE_URL?.trim().replace(/\/+$/, "");
+    return configuredApiBaseUrl
+        ? `${configuredApiBaseUrl}${path}`
+        : new URL(path, c.req.url).toString();
+}
 async function run(c, promise, deadlineMs, status = 200) {
     const data = await withAppApiDeadline(promise, deadlineMs);
     return c.json(data, status);

package/dist/app-api-service.d.ts

@@ -1,14 +1,16 @@
+import type { VoyantAppContextConstraint } from "@voyant-travel/core";
 import type { CustomFieldValueLifecycleRuntime, CustomFieldValueOperationsRuntime } from "@voyant-travel/core/runtime-port";
 import { type CustomFieldDefinitionOwner, createCustomFieldsService } from "@voyant-travel/custom-fields";
 import { type FinanceAppApiRuntime } from "@voyant-travel/finance-contracts/app-api";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import type { AppApiAuditQuery, AppApiEntityReadQuery, AppApiFinanceActionInput, AppApiFinanceDocumentQuery, AppApiFinanceExternalReferenceUpsertInput } from "./app-api-contracts.js";
+import type { AppApiAuditQuery, AppApiEntityReadQuery, AppApiFinanceActionInput, AppApiFinanceDocumentQuery, AppApiFinanceExternalLifecycleStateInput, AppApiFinanceExternalReferenceUpsertInput, AppApiFinanceExternalSyncStateInput, AppApiFinancePdfArtifactHeaders, AppApiFinanceSettlementObservationInput } from "./app-api-contracts.js";
 export interface AppApiAccessContext {
     appId: string;
     installationId: string;
     releaseId: string;
     tokenMode: "offline" | "online";
     viewerId?: string;
+    contextConstraint?: VoyantAppContextConstraint;
     scopes: readonly string[];
     apiVersion?: string;
 }
@@ -81,6 +83,34 @@ export declare function createAppApiService(options?: AppApiServiceOptions): {
             allocationOutcome: "not_requested" | "applied" | "already_applied";
         };
     }>;
+    attachFinancePdfArtifact: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, environment: unknown, headers: AppApiFinancePdfArtifactHeaders, bytes: Uint8Array) => Promise<{
+        data: {
+            status: "ok";
+            outcome: "created" | "unchanged";
+            artifact: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiPdfArtifact;
+        };
+    }>;
+    updateFinanceExternalSyncState: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, input: AppApiFinanceExternalSyncStateInput) => Promise<{
+        data: {
+            status: "ok";
+            outcome: "created" | "updated" | "unchanged";
+            sync: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiExternalSyncState;
+        };
+    }>;
+    updateFinanceExternalLifecycleState: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, input: AppApiFinanceExternalLifecycleStateInput) => Promise<{
+        data: {
+            status: "ok";
+            outcome: "created" | "unchanged";
+            lifecycle: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiExternalLifecycleObservation;
+        };
+    }>;
+    recordFinanceSettlementObservation: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, input: AppApiFinanceSettlementObservationInput) => Promise<{
+        data: {
+            status: "ok";
+            outcome: "created" | "unchanged";
+            observation: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiSettlementObservation;
+        };
+    }>;
     listCustomFieldDefinitions: (db: PostgresJsDatabase, context: AppApiAccessContext, query: Parameters<NonNullable<{
         list(db: PostgresJsDatabase, query: import("@voyant-travel/custom-fields").CustomFieldDefinitionListQuery): Promise<{
             data: {

package/dist/app-api-service.js

@@ -51,6 +51,7 @@ export function createAppApiService(options = {}) {
         return { data: await reader.list(db, query) };
     }
     async function listFinanceDocuments(db, context, query) {
+        assertUnconstrainedFinanceContext(context);
         await requireAccess(db, context, ["finance-documents:read"]);
         if (!options.finance)
             throw notSupported("Finance App API runtime is not configured.");
@@ -59,6 +60,7 @@ export function createAppApiService(options = {}) {
         return { data: await options.finance.listDocuments(db, query) };
     }
     async function getFinanceIssuanceDocument(db, context, documentId) {
+        assertFinanceDocumentContext(context, documentId);
         await requireAccess(db, context, ["finance-documents:read"]);
         const getDocument = options.finance?.getIssuanceDocument;
         if (!getDocument)
@@ -69,6 +71,7 @@ export function createAppApiService(options = {}) {
         return { data };
     }
     async function executeFinanceAction(db, context, input) {
+        assertFinanceDocumentContext(context, input.invoiceId);
         await requireAccess(db, context, [`finance-actions:${input.action}`]);
         if (!options.finance)
             throw notSupported("Finance App API runtime is not configured.");
@@ -83,6 +86,7 @@ export function createAppApiService(options = {}) {
         return { data: await options.finance.executeAction(db, input) };
     }
     async function getFinanceExternalReference(db, context, documentId) {
+        assertFinanceDocumentContext(context, documentId);
         await requireAccess(db, context, ["finance-external-references:read"]);
         const getReference = options.finance?.getExternalReference;
         if (!getReference)
@@ -93,6 +97,7 @@ export function createAppApiService(options = {}) {
         return { data };
     }
     async function upsertFinanceExternalReference(db, context, documentId, input) {
+        assertFinanceDocumentContext(context, documentId);
         const scopes = ["finance-external-references:write"];
         if (input.allocation)
             scopes.push("finance-external-allocation:write");
@@ -138,6 +143,140 @@ export function createAppApiService(options = {}) {
         }
         return { data: result };
     }
+    async function attachFinancePdfArtifact(db, context, documentId, environment, headers, bytes) {
+        assertFinanceDocumentContext(context, documentId);
+        const access = await requireAccess(db, context, ["finance-document-artifacts:write"]);
+        const attachArtifact = options.finance?.attachPdfArtifact;
+        if (!attachArtifact)
+            throw notSupported("Finance document artifact writes are unavailable.");
+        const result = await attachArtifact(db, environment, documentId, context.appId, {
+            bytes,
+            contentType: "application/pdf",
+            fileName: headers.fileName,
+            idempotencyKey: headers.idempotencyKey,
+        });
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "not_configured") {
+            throw new ApiHttpError("Finance document storage is unavailable.", {
+                status: 503,
+                code: "app_api_finance_artifact_storage_unavailable",
+            });
+        }
+        if (result.status === "conflict") {
+            throw new ApiHttpError("Artifact idempotency key was reused with different content.", {
+                status: 409,
+                code: "app_api_finance_artifact_idempotency_conflict",
+            });
+        }
+        await audit(db, access.installation, `app:${context.appId}`, "reconciliation", "finance.document-artifact.attached", {
+            documentId,
+            provider: context.appId,
+            artifactId: result.artifact.id,
+            outcome: result.outcome,
+            releaseId: context.releaseId,
+            tokenMode: context.tokenMode,
+        });
+        return { data: result };
+    }
+    async function updateFinanceExternalSyncState(db, context, documentId, input) {
+        assertFinanceDocumentContext(context, documentId);
+        const access = await requireAccess(db, context, ["finance-external-sync:write"]);
+        const updateSyncState = options.finance?.updateExternalSyncState;
+        if (!updateSyncState)
+            throw notSupported("Finance external sync writes are unavailable.");
+        const result = await db.transaction(async (tx) => {
+            const mutation = await updateSyncState(tx, documentId, context.appId, input);
+            if (mutation.status === "ok") {
+                await audit(tx, access.installation, `app:${context.appId}`, "reconciliation", "finance.external-sync.updated", {
+                    documentId,
+                    provider: context.appId,
+                    operationId: input.operationId,
+                    syncStatus: input.status,
+                    outcome: mutation.outcome,
+                    releaseId: context.releaseId,
+                    tokenMode: context.tokenMode,
+                });
+            }
+            return mutation;
+        });
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "conflict") {
+            throw new ApiHttpError("External sync state conflicts with the current observation.", {
+                status: 409,
+                code: `app_api_finance_external_sync_${result.reason}`,
+                details: result,
+            });
+        }
+        return { data: result };
+    }
+    async function updateFinanceExternalLifecycleState(db, context, documentId, input) {
+        assertFinanceDocumentContext(context, documentId);
+        const access = await requireAccess(db, context, ["finance-external-lifecycle:write"]);
+        const updateLifecycleState = options.finance?.updateExternalLifecycleState;
+        if (!updateLifecycleState) {
+            throw notSupported("Finance external lifecycle writes are unavailable.");
+        }
+        const result = await db.transaction(async (tx) => {
+            const mutation = await updateLifecycleState(tx, documentId, context.appId, input);
+            if (mutation.status === "ok") {
+                await audit(tx, access.installation, `app:${context.appId}`, "reconciliation", "finance.external-lifecycle.updated", {
+                    documentId,
+                    provider: context.appId,
+                    operationId: input.operationId,
+                    lifecycleState: input.state,
+                    outcome: mutation.outcome,
+                    releaseId: context.releaseId,
+                    tokenMode: context.tokenMode,
+                });
+            }
+            return mutation;
+        });
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "conflict") {
+            throw new ApiHttpError("External lifecycle state conflicts with the current document.", {
+                status: 409,
+                code: `app_api_finance_external_lifecycle_${result.reason}`,
+                details: result,
+            });
+        }
+        return { data: result };
+    }
+    async function recordFinanceSettlementObservation(db, context, documentId, input) {
+        assertFinanceDocumentContext(context, documentId);
+        const access = await requireAccess(db, context, ["finance-settlement-observations:write"]);
+        const recordObservation = options.finance?.recordSettlementObservation;
+        if (!recordObservation) {
+            throw notSupported("Finance settlement observations are unavailable.");
+        }
+        const result = await db.transaction(async (tx) => {
+            const mutation = await recordObservation(tx, documentId, context.appId, input);
+            if (mutation.status === "ok") {
+                await audit(tx, access.installation, `app:${context.appId}`, "reconciliation", "finance.settlement-observation.recorded", {
+                    documentId,
+                    provider: context.appId,
+                    operationId: input.operationId,
+                    settlementStatus: input.status,
+                    outcome: mutation.outcome,
+                    releaseId: context.releaseId,
+                    tokenMode: context.tokenMode,
+                });
+            }
+            return mutation;
+        });
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "conflict") {
+            throw new ApiHttpError("Settlement observation conflicts with the current document.", {
+                status: 409,
+                code: `app_api_finance_settlement_observation_${result.reason}`,
+                details: result,
+            });
+        }
+        return { data: result };
+    }
     async function listCustomFieldDefinitions(db, context, query) {
         const access = await requireAccess(db, context, ["custom-field-definitions:read"]);
         return customFieldsRequired().listForOwner(db, owner(access), query);
@@ -196,6 +335,10 @@ export function createAppApiService(options = {}) {
         executeFinanceAction,
         getFinanceExternalReference,
         upsertFinanceExternalReference,
+        attachFinancePdfArtifact,
+        updateFinanceExternalSyncState,
+        updateFinanceExternalLifecycleState,
+        recordFinanceSettlementObservation,
         listCustomFieldDefinitions,
         createCustomFieldDefinition,
         updateCustomFieldDefinition,
@@ -293,6 +436,25 @@ export function assertCompatibleVersion(requested, range) {
         });
     }
 }
+function assertFinanceDocumentContext(context, documentId) {
+    const constraint = context.contextConstraint;
+    if (!constraint)
+        return;
+    if (constraint.entity?.type !== "invoice" || !documentId || constraint.entity.id !== documentId) {
+        throw new ApiHttpError("Online app token is not bound to this finance document.", {
+            status: 403,
+            code: "app_api_entity_context_mismatch",
+        });
+    }
+}
+function assertUnconstrainedFinanceContext(context) {
+    if (!context.contextConstraint)
+        return;
+    throw new ApiHttpError("Entity-bound online app tokens cannot list finance documents.", {
+        status: 403,
+        code: "app_api_entity_context_mismatch",
+    });
+}
 export async function withAppApiDeadline(promise, timeoutMs = 5_000) {
     let timeout;
     try {

package/dist/consent.d.ts

@@ -13,3 +13,4 @@ export interface ComputedConsent {
     deniedOptionalScopes: string[];
 }
 export declare function computeAppConsent(input: ConsentComputationInput): ComputedConsent;
+export declare function grantableRemoteAppScopes(catalog: AccessCatalog): Set<string>;

package/dist/consent.js

@@ -1,7 +1,7 @@
 import { ApiHttpError } from "@voyant-travel/hono";
 export function computeAppConsent(input) {
     const normalized = parseReleaseScopes(input.release.normalizedRecord);
-    const remoteSafe = remoteSafeScopes(input.accessCatalog);
+    const remoteSafe = grantableRemoteAppScopes(input.accessCatalog);
     const operatorGranted = new Set(input.operatorGrantedScopes);
     const optionalGrantRequest = new Set(input.grantedOptionalScopes ?? []);
     const requiredScopes = normalized.requestedScopes.filter((scope) => canGrantScope(scope, remoteSafe, operatorGranted));
@@ -27,7 +27,7 @@ export function computeAppConsent(input) {
 function canGrantScope(scope, remoteSafe, operatorGranted) {
     return remoteSafe.has(scope) && operatorGranted.has(scope);
 }
-function remoteSafeScopes(catalog) {
+export function grantableRemoteAppScopes(catalog) {
     const catalogScopes = new Set(catalog.resources.flatMap((resource) => resource.actions.map((action) => `${resource.resource}:${action.action}`)));
     const remoteSafe = new Set();
     // A scope is remote-safe when its owning resource is flagged remoteSafe, or

package/dist/contracts.d.ts

@@ -222,7 +222,7 @@ export declare const appOAuthAuthorizeQuerySchema: z.ZodObject<{
     state: z.ZodString;
     code_challenge: z.ZodString;
     code_challenge_method: z.ZodLiteral<"S256">;
-    actor_id: z.ZodString;
+    actor_id: z.ZodOptional<z.ZodString>;
     operator_scopes: z.ZodDefault<z.ZodString>;
     optional_scopes: z.ZodDefault<z.ZodString>;
 }, z.core.$strict>;
@@ -238,14 +238,6 @@ export declare const appOAuthTokenSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.Z
     refresh_token: z.ZodString;
     client_id: z.ZodString;
     client_secret: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    grant_type: z.ZodLiteral<"urn:voyant:params:oauth:grant-type:actor-token-exchange">;
-    installation_id: z.ZodString;
-    viewer_id: z.ZodString;
-    viewer_scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    contextual_scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    client_id: z.ZodString;
-    client_secret: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "grant_type">, z.ZodTransform<{
     client_secret: string | undefined;
     grant_type: "authorization_code";
@@ -258,14 +250,6 @@ export declare const appOAuthTokenSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.Z
     grant_type: "refresh_token";
     refresh_token: string;
     client_id: string;
-} | {
-    client_secret: string | undefined;
-    grant_type: "urn:voyant:params:oauth:grant-type:actor-token-exchange";
-    installation_id: string;
-    viewer_id: string;
-    viewer_scopes: string[];
-    client_id: string;
-    contextual_scopes?: string[] | undefined;
 }, {
     grant_type: "authorization_code";
     code: string;
@@ -278,14 +262,6 @@ export declare const appOAuthTokenSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.Z
     refresh_token: string;
     client_id: string;
     client_secret?: string | undefined;
-} | {
-    grant_type: "urn:voyant:params:oauth:grant-type:actor-token-exchange";
-    installation_id: string;
-    viewer_id: string;
-    viewer_scopes: string[];
-    client_id: string;
-    contextual_scopes?: string[] | undefined;
-    client_secret?: string | undefined;
 }>>;
 export declare const appCredentialRevocationSchema: z.ZodObject<{
     installationId: z.ZodString;

package/dist/contracts.js

@@ -271,7 +271,9 @@ export const appOAuthAuthorizeQuerySchema = z
     state: z.string().trim().min(1),
     code_challenge: z.string().trim().min(1),
     code_challenge_method: z.literal("S256"),
-    actor_id: z.string().trim().min(1),
+    /** Deprecated input; the route derives the actor from the staff session. */
+    actor_id: z.string().trim().min(1).optional(),
+    /** Deprecated input; the route derives the grant ceiling from staff scopes. */
     operator_scopes: z.string().trim().default(""),
     optional_scopes: z.string().trim().default(""),
 })
@@ -292,15 +294,6 @@ export const appOAuthTokenSchema = z
         client_id: z.string().trim().min(1),
         client_secret: z.string().trim().optional(),
     }),
-    z.object({
-        grant_type: z.literal("urn:voyant:params:oauth:grant-type:actor-token-exchange"),
-        installation_id: z.string().trim().min(1),
-        viewer_id: z.string().trim().min(1),
-        viewer_scopes: z.array(scopeSchema).default([]),
-        contextual_scopes: z.array(scopeSchema).optional(),
-        client_id: z.string().trim().min(1),
-        client_secret: z.string().trim().optional(),
-    }),
 ])
     .transform((input) => ({
     ...input,

package/dist/oauth-service.d.ts

@@ -1,9 +1,11 @@
-import type { VoyantAuthContext } from "@voyant-travel/core";
+import type { VoyantAppContextConstraint, VoyantAuthContext } from "@voyant-travel/core";
 import type { AccessCatalog } from "@voyant-travel/types/api-keys";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 export interface AppOAuthServiceOptions {
     accessCatalog: AccessCatalog;
     deploymentId: string;
+    /** Managed confidential runtimes fail closed unless a client secret is registered. */
+    clientAuthentication?: "optional" | "required";
     now?: () => Date;
 }
 export interface AuthorizeAppInput {
@@ -37,6 +39,8 @@ export interface TokenExchangeInput {
     viewerId: string;
     viewerScopes: readonly string[];
     contextualScopes?: readonly string[];
+    /** Immutable host context signed into the extension session token. */
+    contextConstraint: VoyantAppContextConstraint;
     clientId: string;
     clientSecret?: string;
 }
@@ -64,3 +68,4 @@ export declare function createAppOAuthService(options: AppOAuthServiceOptions):
 };
 export declare function intersectAppTokenScopes(...sets: readonly (readonly string[])[]): string[];
 export declare function readStoredScopes(metadata: Record<string, unknown>): string[] | null;
+export declare function readStoredAppContextConstraint(metadata: Record<string, unknown>): VoyantAppContextConstraint | null;