@voyant-travel/apps 0.7.0 → 0.8.0

package/dist/oauth-service.js

@@ -55,7 +55,7 @@ export function createAppOAuthService(options) {
         return { code, state: input.state, redirectUri: input.redirectUri, expiresAt };
     }
     async function token(db, input) {
-        await authenticateClient(db, input.clientId, input.clientSecret);
+        await authenticateClient(db, input.clientId, input.clientSecret, options.clientAuthentication === "required");
         if (input.grantType === "authorization_code")
             return exchangeCode(db, input);
         if (input.grantType === "refresh_token")
@@ -82,6 +82,13 @@ export function createAppOAuthService(options) {
         const scopes = credential.tokenMode === "online"
             ? (readStoredScopes(credential.encryptedMetadata) ?? [])
             : await grantedScopes(db, installation.id);
+        const appContextConstraint = credential.tokenMode === "online"
+            ? readStoredAppContextConstraint(credential.encryptedMetadata)
+            : undefined;
+        // Every online actor token is minted from an extension session. Missing or
+        // malformed context metadata must invalidate it rather than silently widen it.
+        if (credential.tokenMode === "online" && !appContextConstraint)
+            return null;
         return {
             callerType: "app",
             actor: "staff",
@@ -92,6 +99,7 @@ export function createAppOAuthService(options) {
             appCredentialGeneration: credential.generation,
             appTokenMode: credential.tokenMode,
             appViewerId: credential.viewerId ?? undefined,
+            ...(appContextConstraint ? { appContextConstraint } : {}),
             scopes,
         };
     }
@@ -191,7 +199,11 @@ export function createAppOAuthService(options) {
             credentialHash: sha256Hex(accessToken),
             // Online tokens are intentionally narrowed; the resolver must honor the
             // minted set rather than recomputing from installation grants.
-            encryptedMetadata: { scopeCount: scopes.length, scopes: [...scopes] },
+            encryptedMetadata: {
+                scopeCount: scopes.length,
+                scopes: [...scopes],
+                contextConstraint: input.contextConstraint,
+            },
             status: "active",
             actorId: input.viewerId,
             viewerId: input.viewerId,
@@ -242,14 +254,17 @@ function tokenResponse(accessToken, refreshToken, expiresAt, scopes, tokenMode)
         ...(refreshToken ? { refreshToken } : {}),
     };
 }
-async function authenticateClient(db, appId, clientSecret) {
+async function authenticateClient(db, appId, clientSecret, required) {
     const [secret] = await db
         .select()
         .from(appCredentials)
         .where(and(eq(appCredentials.appId, appId), eq(appCredentials.kind, "client_secret")))
         .limit(1);
-    if (!secret)
+    if (!secret) {
+        if (required)
+            throw oauthError("invalid_client", "Client authentication failed", 401);
         return;
+    }
     if (!clientSecret || !secret.kmsKeyRef.startsWith("sha256:")) {
         throw oauthError("invalid_client", "Client authentication failed", 401);
     }
@@ -382,6 +397,28 @@ export function readStoredScopes(metadata) {
         return null;
     return stored.filter((scope) => typeof scope === "string");
 }
+export function readStoredAppContextConstraint(metadata) {
+    const value = metadata.contextConstraint;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const slot = record.slot;
+    if (slot !== null && (typeof slot !== "string" || slot.length === 0))
+        return null;
+    const entity = record.entity;
+    if (entity === null)
+        return { entity: null, slot };
+    if (!entity || typeof entity !== "object" || Array.isArray(entity))
+        return null;
+    const entityRecord = entity;
+    if (typeof entityRecord.type !== "string" ||
+        entityRecord.type.length === 0 ||
+        typeof entityRecord.id !== "string" ||
+        entityRecord.id.length === 0) {
+        return null;
+    }
+    return { entity: { type: entityRecord.type, id: entityRecord.id }, slot };
+}
 function oauthError(error, description, status = 400) {
     return new ApiHttpError(description, { status, code: error });
 }

package/dist/oauth-service.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { createAppOAuthService, intersectAppTokenScopes, readStoredScopes, } from "./oauth-service.js";
-import { appReleases } from "./schema.js";
+import { createAppOAuthService, intersectAppTokenScopes, readStoredAppContextConstraint, readStoredScopes, } from "./oauth-service.js";
+import { appCredentials, appReleases } from "./schema.js";
 describe("app OAuth online token scope intersection", () => {
     it("never exceeds either app grants, viewer grants, or contextual restrictions", () => {
         expect(intersectAppTokenScopes(["bookings:read", "invoices:read"], ["bookings:read", "customers:read"], ["bookings:read", "invoices:read"])).toEqual(["bookings:read"]);
@@ -16,6 +16,22 @@ describe("stored online token scopes", () => {
         expect(readStoredScopes({ scopeCount: 2 })).toBeNull();
         expect(readStoredScopes({ scopes: "bookings:read" })).toBeNull();
     });
+    it("fails closed unless immutable extension context metadata is complete", () => {
+        expect(readStoredAppContextConstraint({
+            contextConstraint: {
+                entity: { type: "invoice", id: "invoice_1" },
+                slot: "invoice.details.after-summary",
+            },
+        })).toEqual({
+            entity: { type: "invoice", id: "invoice_1" },
+            slot: "invoice.details.after-summary",
+        });
+        expect(readStoredAppContextConstraint({})).toBeNull();
+        expect(readStoredAppContextConstraint({ contextConstraint: { entity: { type: "invoice" } } })).toBeNull();
+        expect(readStoredAppContextConstraint({
+            contextConstraint: { entity: { type: "invoice", id: "invoice_1" }, slot: "" },
+        })).toBeNull();
+    });
 });
 describe("authorization release lifecycle", () => {
     function dbWithRelease(state) {
@@ -58,3 +74,24 @@ describe("authorization release lifecycle", () => {
         });
     });
 });
+describe("managed client authentication", () => {
+    it("fails closed when confidential-client provisioning is absent", async () => {
+        const db = Object.assign(Object.create(null), {
+            select: () => ({
+                from: (table) => ({
+                    where: () => ({ limit: async () => (table === appCredentials ? [] : []) }),
+                }),
+            }),
+        });
+        const service = createAppOAuthService({
+            accessCatalog: { resources: [], presets: [] },
+            deploymentId: "dep_1",
+            clientAuthentication: "required",
+        });
+        await expect(service.token(db, {
+            grantType: "refresh_token",
+            refreshToken: "app_refresh_fixture",
+            clientId: "app_1",
+        })).rejects.toMatchObject({ status: 401, code: "invalid_client" });
+    });
+});

package/dist/routes-openapi.d.ts

@@ -91,7 +91,7 @@ export declare const authorizeAppOAuthRoute: {
                         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>;
@@ -147,14 +147,6 @@ export declare const issueAppOAuthTokenRoute: {
                         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";
@@ -167,14 +159,6 @@ export declare const issueAppOAuthTokenRoute: {
                         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;
@@ -187,14 +171,6 @@ export declare const issueAppOAuthTokenRoute: {
                         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;
                     }>>;
                 };
             };

package/dist/routes-viewer-scopes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/routes-viewer-scopes.test.js

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { resolveOperatorGrantableRemoteAppScopes, resolveViewerRemoteAppScopes } from "./routes.js";
+const catalog = {
+    resources: [
+        {
+            id: "finance-artifacts",
+            unitId: "apps",
+            resource: "finance-document-artifacts",
+            label: "Artifacts",
+            description: "Artifacts",
+            wildcard: "explicit-resource",
+            remoteSafe: true,
+            actions: [
+                {
+                    action: "write",
+                    label: "Write",
+                    description: "Write",
+                    wildcard: "explicit",
+                },
+            ],
+        },
+        {
+            id: "apps-admin",
+            unitId: "apps",
+            resource: "apps",
+            label: "Apps",
+            description: "Apps",
+            wildcard: "allow",
+            actions: [{ action: "write", label: "Write", description: "Write" }],
+        },
+    ],
+    presets: [],
+};
+describe("viewer scope projection for remote extensions", () => {
+    it("projects only host-authorized remote-safe permissions", () => {
+        expect(resolveViewerRemoteAppScopes(["finance-document-artifacts:write", "apps:write"], catalog)).toEqual(["finance-document-artifacts:write"]);
+    });
+    it("does not treat a generic wildcard as an explicit sensitive action", () => {
+        expect(resolveViewerRemoteAppScopes(["*"], catalog)).toEqual([]);
+    });
+    it("derives consent authority from the staff grants and remote-safe catalog", () => {
+        expect(resolveOperatorGrantableRemoteAppScopes(["*"], catalog)).toEqual([]);
+        expect(resolveOperatorGrantableRemoteAppScopes(["finance-document-artifacts:write", "apps:write"], catalog)).toEqual(["finance-document-artifacts:write"]);
+        expect(resolveOperatorGrantableRemoteAppScopes(["apps:write"], catalog)).toEqual([]);
+    });
+});

package/dist/routes.d.ts

@@ -1,23 +1,21 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { EventBus } from "@voyant-travel/core/events";
 import type { createCustomFieldsService } from "@voyant-travel/custom-fields";
-import type { AccessCatalog } from "@voyant-travel/types/api-keys";
+import { type AccessCatalog } from "@voyant-travel/types/api-keys";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import { type AppsServiceOptions } from "./service.js";
 type CustomFieldsService = ReturnType<typeof createCustomFieldsService>;
 type Env = {
-    Bindings: {
-        /** Deployment identity; the install lifecycle is scoped to it. */
-        VOYANT_CLOUD_DEPLOYMENT_ID?: string;
-    };
     Variables: {
         db: PostgresJsDatabase;
+        scopes?: string[];
     };
 };
 export interface AppsAdminRouteOptions extends AppsServiceOptions {
     oauth?: {
         accessCatalog: AccessCatalog;
         deploymentId: string;
+        clientAuthentication?: "optional" | "required";
     };
     /**
      * Enables the iframe session-token broker. Requires {@link oauth} for the
@@ -39,4 +37,6 @@ export interface AppsAdminRouteOptions extends AppsServiceOptions {
     customFields?: CustomFieldsService;
 }
 export declare function createAppsAdminRoutes(options?: AppsAdminRouteOptions): OpenAPIHono<Env, {}, "/">;
+export declare function resolveViewerRemoteAppScopes(scopes: readonly string[], catalog: AccessCatalog | undefined): string[];
+export declare function resolveOperatorGrantableRemoteAppScopes(scopes: readonly string[], catalog: AccessCatalog): string[];
 export {};

package/dist/routes.js

@@ -1,6 +1,8 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { openApiValidationHook, parseJsonBody, parseQuery, RequestValidationError, requireUserId, } from "@voyant-travel/hono";
+import { hasApiKeyPermission, permissionStringsToPermissions, } from "@voyant-travel/types/api-keys";
 import { z } from "zod";
+import { grantableRemoteAppScopes } from "./consent.js";
 import { activateInstallationBodySchema, appCredentialRevocationSchema, appInstallationAuditQuerySchema, appInstallationListQuerySchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appSessionTokenExchangeSchema, appSessionTokenIssueSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, installAppSchema, lifecycleActionBodySchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
 import { listAppReleases, listInstallationAudit, listInstallationSummaries, loadInstallationDetail, } from "./installation-read-model.js";
 import { createAppInstallationService } from "./installation-service.js";
@@ -21,6 +23,7 @@ export function createAppsAdminRoutes(options = {}) {
         customFields: options.customFields,
     });
     const oauth = options.oauth ? createAppOAuthService(options.oauth) : null;
+    const oauthAccessCatalog = options.oauth?.accessCatalog;
     const sessionTokens = oauth && options.oauth && options.sessionToken
         ? createAppSessionTokenService({
             secret: options.sessionToken.secret,
@@ -42,8 +45,9 @@ export function createAppsAdminRoutes(options = {}) {
     // so it must never be reachable through read-scoped GET requests. The admin
     // consent UI submits the approval and performs the redirect itself.
     routes.openapi(authorizeAppOAuthRoute, async (c) => {
-        if (!oauth)
+        if (!oauth || !oauthAccessCatalog) {
             return c.json({ error: "App OAuth is not configured" }, 501);
+        }
         const body = await parseJsonBody(c, appOAuthAuthorizeQuerySchema);
         const result = await oauth.authorize(c.get("db"), {
             appId: body.client_id,
@@ -52,8 +56,8 @@ export function createAppsAdminRoutes(options = {}) {
             state: body.state,
             codeChallenge: body.code_challenge,
             codeChallengeMethod: body.code_challenge_method,
-            actorId: body.actor_id,
-            operatorGrantedScopes: splitScopes(body.operator_scopes),
+            actorId: requireUserId(c),
+            operatorGrantedScopes: resolveOperatorGrantableRemoteAppScopes(c.get("scopes") ?? [], oauthAccessCatalog),
             grantedOptionalScopes: splitScopes(body.optional_scopes),
         });
         const redirectUrl = new URL(result.redirectUri);
@@ -74,22 +78,12 @@ export function createAppsAdminRoutes(options = {}) {
                 clientId: body.client_id,
                 clientSecret: body.client_secret,
             })
-            : body.grant_type === "refresh_token"
-                ? await oauth.token(c.get("db"), {
-                    grantType: "refresh_token",
-                    refreshToken: body.refresh_token,
-                    clientId: body.client_id,
-                    clientSecret: body.client_secret,
-                })
-                : await oauth.token(c.get("db"), {
-                    grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
-                    installationId: body.installation_id,
-                    viewerId: body.viewer_id,
-                    viewerScopes: body.viewer_scopes,
-                    contextualScopes: body.contextual_scopes,
-                    clientId: body.client_id,
-                    clientSecret: body.client_secret,
-                });
+            : await oauth.token(c.get("db"), {
+                grantType: "refresh_token",
+                refreshToken: body.refresh_token,
+                clientId: body.client_id,
+                clientSecret: body.client_secret,
+            });
         return c.json(token, 200);
     });
     routes.openapi(revokeAppInstallationCredentialsRoute, async (c) => {
@@ -111,6 +105,7 @@ export function createAppsAdminRoutes(options = {}) {
         const issued = await sessionTokens.issue(c.get("db"), {
             installationId,
             viewerId,
+            viewerScopes: resolveViewerRemoteAppScopes(c.get("scopes") ?? [], options.oauth?.accessCatalog),
             entity: body.entity ?? null,
             slot: body.slot ?? null,
         });
@@ -133,11 +128,10 @@ export function createAppsAdminRoutes(options = {}) {
     });
     routes.openapi(installAppRoute, async (c) => {
         const body = await parseJsonBody(c, installAppSchema);
-        // The deployment id is a runtime value (not known at graph-composition
-        // time), so resolve it per request: explicit body → runtime env →
-        // construction option. Without this the standard runtime mounts these
-        // routes with no deployment id and every install 400s (app_deployment_required).
-        const deploymentId = body.deploymentId ?? c.env?.VOYANT_CLOUD_DEPLOYMENT_ID?.trim() ?? options.deploymentId;
+        // A configured managed runtime audience is authoritative so installation
+        // identity cannot diverge from later OAuth token audiences. Direct/custom
+        // hosts without managed auth may still supply an explicit deployment ID.
+        const deploymentId = options.oauth?.deploymentId ?? body.deploymentId ?? options.deploymentId;
         const result = await installations.install(c.get("db"), {
             appId: body.appId,
             releaseId: body.releaseId,
@@ -248,6 +242,29 @@ export function createAppsAdminRoutes(options = {}) {
     });
     return routes;
 }
+export function resolveViewerRemoteAppScopes(scopes, catalog) {
+    if (!catalog)
+        return [];
+    const permissions = permissionStringsToPermissions(scopes);
+    return catalog.resources
+        .flatMap((resource) => resource.actions
+        .filter((action) => (resource.remoteSafe || action.remoteSafe) &&
+        hasApiKeyPermission(permissions, resource.resource, action.action, catalog))
+        .map((action) => `${resource.resource}:${action.action}`))
+        .sort();
+}
+export function resolveOperatorGrantableRemoteAppScopes(scopes, catalog) {
+    const grantable = grantableRemoteAppScopes(catalog);
+    const permissions = permissionStringsToPermissions(scopes);
+    return [...grantable]
+        .filter((scope) => {
+        const separator = scope.lastIndexOf(":");
+        if (separator <= 0)
+            return false;
+        return hasApiKeyPermission(permissions, scope.slice(0, separator), scope.slice(separator + 1), catalog);
+    })
+        .sort();
+}
 function splitScopes(value) {
     return value
         .split(/[,\s]+/)

package/dist/runtime-contributor.d.ts

@@ -1 +1,9 @@
-export declare function createAppsRuntimePortContribution(): Readonly<Record<string, unknown>>;
+import type { VoyantRuntimeHostPrimitives } from "@voyant-travel/core";
+export interface AppsRuntimeContributorHost {
+    primitives: Pick<VoyantRuntimeHostPrimitives, "config">;
+    hasRuntimePort?(port: {
+        id: string;
+    }): boolean;
+}
+/** Package-owned, provider-neutral managed-auth configuration. */
+export declare function createAppsRuntimePortContribution(host: AppsRuntimeContributorHost): Readonly<Record<string, unknown>>;

package/dist/runtime-contributor.js

@@ -1,3 +1,26 @@
-export function createAppsRuntimePortContribution() {
-    return {};
+import { appsManagedAuthRuntimePort } from "./runtime-port.js";
+function readString(host, key) {
+    const value = host.primitives.config.read(undefined, key);
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+/** Package-owned, provider-neutral managed-auth configuration. */
+export function createAppsRuntimePortContribution(host) {
+    if (host.hasRuntimePort?.(appsManagedAuthRuntimePort))
+        return {};
+    const runtimeAudience = readString(host, "VOYANT_APP_RUNTIME_AUDIENCE");
+    const sessionTokenSigningSecret = readString(host, "VOYANT_APP_SESSION_TOKEN_SIGNING_SECRET");
+    if (!runtimeAudience || !sessionTokenSigningSecret)
+        return {};
+    const ttlInput = readString(host, "VOYANT_APP_SESSION_TOKEN_TTL_SECONDS");
+    const sessionTokenTtlSeconds = ttlInput === undefined ? undefined : Number(ttlInput);
+    const runtime = {
+        runtimeAudience,
+        sessionTokenSigningSecret,
+        ...(sessionTokenTtlSeconds === undefined ? {} : { sessionTokenTtlSeconds }),
+    };
+    appsManagedAuthRuntimePort.test(runtime);
+    return { [appsManagedAuthRuntimePort.id]: runtime };
 }

package/dist/runtime-contributor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime-contributor.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { createAppsRuntimePortContribution } from "./runtime-contributor.js";
+import { appsManagedAuthRuntimePort } from "./runtime-port.js";
+function host(values) {
+    return {
+        hasRuntimePort: () => false,
+        primitives: {
+            config: { read: (_bindings, key) => values[key] },
+        },
+    };
+}
+describe("createAppsRuntimePortContribution", () => {
+    it("stays off unless both managed-auth inputs are present", () => {
+        expect(createAppsRuntimePortContribution(host({}))).toEqual({});
+        expect(createAppsRuntimePortContribution(host({ VOYANT_APP_RUNTIME_AUDIENCE: "deployment-1" }))).toEqual({});
+    });
+    it("contributes validated provider-neutral managed-auth configuration", () => {
+        const contribution = createAppsRuntimePortContribution(host({
+            VOYANT_APP_RUNTIME_AUDIENCE: "  deployment-1  ",
+            VOYANT_APP_SESSION_TOKEN_SIGNING_SECRET: "s".repeat(32),
+            VOYANT_APP_SESSION_TOKEN_TTL_SECONDS: "180",
+        }));
+        expect(contribution).toEqual({
+            [appsManagedAuthRuntimePort.id]: {
+                runtimeAudience: "deployment-1",
+                sessionTokenSigningSecret: "s".repeat(32),
+                sessionTokenTtlSeconds: 180,
+            },
+        });
+    });
+    it("does not replace an explicitly host-provided managed-auth port", () => {
+        const contribution = createAppsRuntimePortContribution({
+            ...host({
+                VOYANT_APP_RUNTIME_AUDIENCE: "deployment-from-env",
+                VOYANT_APP_SESSION_TOKEN_SIGNING_SECRET: "s".repeat(32),
+            }),
+            hasRuntimePort: (port) => port.id === appsManagedAuthRuntimePort.id,
+        });
+        expect(contribution).toEqual({});
+    });
+    it("rejects weak signing material and long-lived session tokens", () => {
+        expect(() => createAppsRuntimePortContribution(host({
+            VOYANT_APP_RUNTIME_AUDIENCE: "deployment-1",
+            VOYANT_APP_SESSION_TOKEN_SIGNING_SECRET: "test-secret",
+        }))).toThrow(/at least 32 characters/);
+        expect(() => createAppsRuntimePortContribution(host({
+            VOYANT_APP_RUNTIME_AUDIENCE: "deployment-1",
+            VOYANT_APP_SESSION_TOKEN_SIGNING_SECRET: "s".repeat(32),
+            VOYANT_APP_SESSION_TOKEN_TTL_SECONDS: "301",
+        }))).toThrow(/1 through 300/);
+    });
+});

package/dist/runtime-port.d.ts

@@ -0,0 +1,8 @@
+export interface AppsManagedAuthRuntime {
+    /** Stable audience shared by authorization, installations, and session tokens. */
+    runtimeAudience: string;
+    /** Host-owned HMAC material for short-lived extension session tokens. */
+    sessionTokenSigningSecret: string;
+    sessionTokenTtlSeconds?: number;
+}
+export declare const appsManagedAuthRuntimePort: import("@voyant-travel/core/project").VoyantPort<AppsManagedAuthRuntime>;

package/dist/runtime-port.js

@@ -0,0 +1,22 @@
+import { definePort } from "@voyant-travel/core/project";
+export const appsManagedAuthRuntimePort = definePort({
+    id: "apps.managed-auth",
+    test(runtime) {
+        if (!runtime || typeof runtime !== "object") {
+            throw new TypeError("apps.managed-auth must be an object.");
+        }
+        if (!runtime.runtimeAudience?.trim()) {
+            throw new TypeError("apps.managed-auth runtimeAudience must be a non-empty string.");
+        }
+        if (typeof runtime.sessionTokenSigningSecret !== "string" ||
+            runtime.sessionTokenSigningSecret.length < 32) {
+            throw new TypeError("apps.managed-auth sessionTokenSigningSecret must contain at least 32 characters.");
+        }
+        if (runtime.sessionTokenTtlSeconds !== undefined &&
+            (!Number.isInteger(runtime.sessionTokenTtlSeconds) ||
+                runtime.sessionTokenTtlSeconds <= 0 ||
+                runtime.sessionTokenTtlSeconds > 300)) {
+            throw new TypeError("apps.managed-auth sessionTokenTtlSeconds must be an integer from 1 through 300 when provided.");
+        }
+    },
+});

package/dist/session-token-service.d.ts

@@ -15,6 +15,8 @@ export interface AppSessionTokenServiceOptions {
 export interface IssueAppSessionTokenInput {
     installationId: string;
     viewerId: string;
+    /** Current host-authenticated viewer permissions. */
+    viewerScopes?: readonly string[];
     entity?: AppSessionTokenEntity | null;
     slot?: string | null;
 }

package/dist/session-token-service.js

@@ -13,7 +13,7 @@
  * Both paths write `app_audit_events` so issuance and exchange are auditable.
  */
 import { ApiHttpError } from "@voyant-travel/hono";
-import { and, eq, isNull } from "drizzle-orm";
+import { and, eq, gt, isNull } from "drizzle-orm";
 import { appAuditEvents, appInstallations, appSessionTokens, } from "./schema.js";
 import { signAppSessionToken, verifyAppSessionToken, } from "./session-token.js";
 export function createAppSessionTokenService(options) {
@@ -25,6 +25,7 @@ export function createAppSessionTokenService(options) {
             installationId: installation.id,
             deploymentId: installation.deploymentId,
             viewerId: input.viewerId,
+            viewerScopes: input.viewerScopes ?? [],
             entity: input.entity ?? null,
             slot: input.slot ?? null,
         };
@@ -63,37 +64,53 @@ export function createAppSessionTokenService(options) {
             });
         }
         const { claims } = verified;
-        // Single-use: consume the jti atomically. A row that is missing or already
-        // consumed is a replay and is refused before any credential is minted.
-        const consumed = await db
-            .update(appSessionTokens)
-            .set({ consumedAt: now(), consumedByActorId: claims.sub })
-            .where(and(eq(appSessionTokens.jti, claims.jti), isNull(appSessionTokens.consumedAt)))
-            .returning({ id: appSessionTokens.id });
-        if (consumed.length === 0) {
-            throw new ApiHttpError("Session token has already been used", {
-                status: 401,
-                code: "app_session_token_replayed",
+        return db.transaction(async (tx) => {
+            const installation = await requireActiveInstallation(tx, claims.installationId);
+            if (installation.appId !== claims.aud || installation.deploymentId !== claims.deploymentId) {
+                throw new ApiHttpError("Session token installation context changed", {
+                    status: 401,
+                    code: "app_session_token_installation_mismatch",
+                });
+            }
+            // Client authentication and token construction happen before consumption,
+            // but in the same transaction. If authentication/minting fails, or another
+            // exchange wins the JTI race, every credential side effect rolls back.
+            const tokens = await options.oauth.token(tx, {
+                grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
+                installationId: installation.id,
+                viewerId: claims.sub,
+                viewerScopes: intersectRequestedScopes(claims.viewerScopes, input.viewerScopes),
+                contextualScopes: input.contextualScopes,
+                contextConstraint: { entity: claims.entity, slot: claims.slot },
+                clientId: input.clientId,
+                clientSecret: input.clientSecret,
             });
-        }
-        const installation = await requireActiveInstallation(db, claims.installationId);
-        const tokens = await options.oauth.token(db, {
-            grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
-            installationId: installation.id,
-            viewerId: claims.sub,
-            viewerScopes: input.viewerScopes,
-            contextualScopes: input.contextualScopes,
-            clientId: input.clientId,
-            clientSecret: input.clientSecret,
-        });
-        await audit(db, installation, claims.sub, "session-token.exchanged", {
-            jti: claims.jti,
-            slot: claims.slot,
+            const consumed = await tx
+                .update(appSessionTokens)
+                .set({ consumedAt: now(), consumedByActorId: claims.sub })
+                .where(and(eq(appSessionTokens.jti, claims.jti), eq(appSessionTokens.installationId, installation.id), eq(appSessionTokens.appId, claims.aud), eq(appSessionTokens.deploymentId, claims.deploymentId), eq(appSessionTokens.viewerId, claims.sub), isNull(appSessionTokens.consumedAt), gt(appSessionTokens.expiresAt, now())))
+                .returning({ id: appSessionTokens.id });
+            if (consumed.length === 0) {
+                throw new ApiHttpError("Session token has already been used", {
+                    status: 401,
+                    code: "app_session_token_replayed",
+                });
+            }
+            await audit(tx, installation, claims.sub, "session-token.exchanged", {
+                jti: claims.jti,
+                slot: claims.slot,
+                entityType: claims.entity?.type ?? null,
+                entityId: claims.entity?.id ?? null,
+            });
+            return tokens;
         });
-        return tokens;
     }
     return { issue, exchange };
 }
+function intersectRequestedScopes(trustedViewerScopes, requestedScopes) {
+    const trusted = new Set(trustedViewerScopes);
+    return Array.from(new Set(requestedScopes.filter((scope) => trusted.has(scope)))).sort();
+}
 async function requireActiveInstallation(db, installationId) {
     const [installation] = await db
         .select()

package/dist/session-token-service.test.d.ts

@@ -0,0 +1 @@
+export {};