@voyant-travel/apps 0.6.3 → 0.8.0

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

@@ -29,8 +29,8 @@ export declare const appOwnedCustomFieldDeclarationSchema: z.ZodObject<{
     }, z.core.$strip>>>>;
     logicalNamespace: z.ZodOptional<z.ZodString>;
     dataClassification: z.ZodDefault<z.ZodEnum<{
-        internal: "internal";
         public: "public";
+        internal: "internal";
         confidential: "confidential";
         restricted: "restricted";
         personal: "personal";
@@ -106,8 +106,8 @@ export declare const appManifestSchema: z.ZodPipe<z.ZodRecord<z.ZodString, z.Zod
         }, z.core.$strip>>>>;
         logicalNamespace: z.ZodOptional<z.ZodString>;
         dataClassification: z.ZodDefault<z.ZodEnum<{
-            internal: "internal";
             public: "public";
+            internal: "internal";
             confidential: "confidential";
             restricted: "restricted";
             personal: "personal";
@@ -134,8 +134,8 @@ export declare const appManifestSchema: z.ZodPipe<z.ZodRecord<z.ZodString, z.Zod
     }, z.core.$strict>;
     data: z.ZodObject<{
         classifications: z.ZodArray<z.ZodEnum<{
-            internal: "internal";
             public: "public";
+            internal: "internal";
             confidential: "confidential";
             restricted: "restricted";
             personal: "personal";
@@ -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;

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