@voyant-travel/apps 0.7.0 → 0.9.0

package/dist/oauth-service.js

@@ -2,12 +2,14 @@ import { ApiHttpError } from "@voyant-travel/hono";
 import { and, eq } from "drizzle-orm";
 import { computeAppConsent } from "./consent.js";
 import { APP_ACCESS_TOKEN_PREFIX, APP_AUTH_CODE_PREFIX, APP_REFRESH_TOKEN_PREFIX, constantTimeEqual, randomToken, sha256Hex, verifyPkceS256, } from "./oauth-crypto.js";
-import { appAccessCredentials, appAuditEvents, appCredentials, appGrants, appInstallations, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleases, apps, } from "./schema.js";
+import { assertActiveInstallation, assertManagedBinding, assertManagedInstallationAuthority, assertTokenClient, ensureAuthorizedInstallation, grantedScopes, isInstallationUsable, managedBindingMatches, requireInstallation, selectInstallation, } from "./oauth-installation.js";
+import { appAccessCredentials, appAuditEvents, appCredentials, appInstallations, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleases, } from "./schema.js";
 const CODE_TTL_MS = 5 * 60 * 1000;
 const OFFLINE_ACCESS_TTL_MS = 60 * 60 * 1000;
 const ONLINE_ACCESS_TTL_MS = 10 * 60 * 1000;
 const REFRESH_TTL_MS = 90 * 24 * 60 * 60 * 1000;
 export function createAppOAuthService(options) {
+    assertManagedInstallationAuthority(options.managedInstallation);
     const now = () => options.now?.() ?? new Date();
     async function authorize(db, input) {
         assertState(input.state);
@@ -22,10 +24,12 @@ export function createAppOAuthService(options) {
             operatorGrantedScopes: input.operatorGrantedScopes,
             grantedOptionalScopes: input.grantedOptionalScopes,
         });
+        const managedBinding = await resolveManagedBinding(input.appId, input.releaseId);
         const installation = await ensureAuthorizedInstallation(db, {
             appId: input.appId,
             releaseId: input.releaseId,
             deploymentId: options.deploymentId,
+            managedBinding,
             actorId: input.actorId,
             grantedScopes: consent.grantedScopes,
             deniedOptionalScopes: consent.deniedOptionalScopes,
@@ -37,6 +41,8 @@ export function createAppOAuthService(options) {
             installationId: installation.id,
             releaseId: input.releaseId,
             deploymentId: options.deploymentId,
+            workloadEnvironmentId: managedBinding?.workloadEnvironmentId,
+            contractGeneration: managedBinding?.contractGeneration,
             codeHash: sha256Hex(code),
             stateHash: sha256Hex(input.state),
             redirectUri: input.redirectUri,
@@ -55,7 +61,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")
@@ -73,8 +79,17 @@ export function createAppOAuthService(options) {
         if (!credential || (credential.expiresAt && credential.expiresAt <= now()))
             return null;
         const installation = await selectInstallation(db, credential.installationId);
-        if (!installation || !isInstallationUsable(installation, credential.generation))
+        if (!installation)
+            return null;
+        const managedBinding = await resolveManagedBindingOrNull(installation.appId, installation.releaseId);
+        if (options.managedInstallation && !managedBinding)
+            return null;
+        const effectiveManagedBinding = managedBinding ?? undefined;
+        if (!isInstallationUsable(installation, credential.generation) ||
+            !managedBindingMatches(installation, effectiveManagedBinding) ||
+            !managedBindingMatches(credential, effectiveManagedBinding)) {
             return null;
+        }
         // Online tokens resolve to the scope set minted at exchange (viewer/context
         // intersection); recomputing from grants would silently widen them. Offline
         // tokens track live grants so revoking a scope applies immediately. A
@@ -82,6 +97,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",
@@ -90,14 +112,23 @@ export function createAppOAuthService(options) {
             appInstallationId: installation.id,
             appReleaseId: installation.releaseId,
             appCredentialGeneration: credential.generation,
+            ...(effectiveManagedBinding
+                ? {
+                    appWorkloadEnvironmentId: effectiveManagedBinding.workloadEnvironmentId,
+                    appContractGeneration: effectiveManagedBinding.contractGeneration,
+                }
+                : {}),
             appTokenMode: credential.tokenMode,
             appViewerId: credential.viewerId ?? undefined,
+            ...(appContextConstraint ? { appContextConstraint } : {}),
             scopes,
         };
     }
     async function revokeInstallationCredentials(db, installationId, actorId) {
         return db.transaction(async (tx) => {
             const installation = await requireInstallation(tx, installationId);
+            const managedBinding = await resolveManagedBinding(installation.appId, installation.releaseId);
+            assertManagedBinding(installation, managedBinding);
             const generation = installation.credentialGeneration + 1;
             await tx
                 .update(appInstallations)
@@ -134,13 +165,19 @@ export function createAppOAuthService(options) {
             if (!verifyPkceS256(input.codeVerifier, code.codeChallenge)) {
                 throw oauthError("invalid_grant", "PKCE verifier does not match the authorization code");
             }
+            if (!options.managedInstallation && code.deploymentId !== options.deploymentId) {
+                throw oauthError("invalid_grant", "Authorization code belongs to a different runtime");
+            }
+            const managedBinding = await resolveManagedBinding(code.appId, code.releaseId);
+            assertManagedBinding(code, managedBinding);
             await tx
                 .update(appOAuthAuthorizationCodes)
                 .set({ consumedAt: now() })
                 .where(eq(appOAuthAuthorizationCodes.id, code.id));
             const installation = await requireInstallation(tx, code.installationId);
             assertActiveInstallation(installation);
-            const tokens = await mintTokens(tx, installation, code.actorId, null, code.grantedScopes);
+            assertManagedBinding(installation, managedBinding);
+            const tokens = await mintTokens(tx, installation, code.actorId, null, code.grantedScopes, managedBinding);
             await audit(tx, installation, code.actorId, "token", "oauth.code.exchanged", {});
             return tokens;
         });
@@ -157,8 +194,11 @@ export function createAppOAuthService(options) {
                 throw oauthError("invalid_grant", "Refresh token is invalid");
             }
             const installation = await requireInstallation(tx, tokenRow.installationId);
+            const managedBinding = await resolveManagedBinding(installation.appId, installation.releaseId);
             assertTokenClient(installation, input.clientId);
             assertActiveInstallation(installation);
+            assertManagedBinding(tokenRow, managedBinding);
+            assertManagedBinding(installation, managedBinding);
             if (installation.credentialGeneration !== tokenRow.generation) {
                 throw oauthError("invalid_grant", "Refresh token generation was revoked");
             }
@@ -166,7 +206,7 @@ export function createAppOAuthService(options) {
                 .update(appOAuthRefreshTokens)
                 .set({ status: "inactive", revokedAt: now() })
                 .where(eq(appOAuthRefreshTokens.id, tokenRow.id));
-            const tokens = await mintTokens(tx, installation, "app", null, await grantedScopes(tx, installation.id), {
+            const tokens = await mintTokens(tx, installation, "app", null, await grantedScopes(tx, installation.id), managedBinding, {
                 rotatedFromId: tokenRow.id,
             });
             await audit(tx, installation, "app", "token", "oauth.refresh.rotated", {
@@ -177,8 +217,10 @@ export function createAppOAuthService(options) {
     }
     async function exchangeActorToken(db, input) {
         const installation = await requireInstallation(db, input.installationId);
+        const managedBinding = await resolveManagedBinding(installation.appId, installation.releaseId);
         assertTokenClient(installation, input.clientId);
         assertActiveInstallation(installation);
+        assertManagedBinding(installation, managedBinding);
         const grants = await grantedScopes(db, installation.id);
         const contextual = input.contextualScopes ?? grants;
         const scopes = intersectAppTokenScopes(grants, input.viewerScopes, contextual);
@@ -187,11 +229,17 @@ export function createAppOAuthService(options) {
         await db.insert(appAccessCredentials).values({
             installationId: installation.id,
             generation: installation.credentialGeneration,
+            workloadEnvironmentId: managedBinding?.workloadEnvironmentId,
+            contractGeneration: managedBinding?.contractGeneration,
             tokenMode: "online",
             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,
@@ -202,7 +250,7 @@ export function createAppOAuthService(options) {
         });
         return tokenResponse(accessToken, null, expiresAt, scopes, "online");
     }
-    async function mintTokens(db, installation, actorId, viewerId, scopes, refreshOptions = {}) {
+    async function mintTokens(db, installation, actorId, viewerId, scopes, managedBinding, refreshOptions = {}) {
         const accessToken = randomToken(APP_ACCESS_TOKEN_PREFIX);
         const refreshToken = randomToken(APP_REFRESH_TOKEN_PREFIX);
         const accessExpiresAt = new Date(now().getTime() + OFFLINE_ACCESS_TTL_MS);
@@ -211,6 +259,8 @@ export function createAppOAuthService(options) {
         await db.insert(appAccessCredentials).values({
             installationId: installation.id,
             generation,
+            workloadEnvironmentId: managedBinding?.workloadEnvironmentId,
+            contractGeneration: managedBinding?.contractGeneration,
             tokenMode: "offline",
             credentialHash: sha256Hex(accessToken),
             encryptedMetadata: { scopeCount: scopes.length },
@@ -223,6 +273,8 @@ export function createAppOAuthService(options) {
             installationId: installation.id,
             tokenHash: sha256Hex(refreshToken),
             generation,
+            workloadEnvironmentId: managedBinding?.workloadEnvironmentId,
+            contractGeneration: managedBinding?.contractGeneration,
             rotatedFromId: refreshOptions.rotatedFromId,
             expiresAt: refreshExpiresAt,
         });
@@ -231,6 +283,31 @@ export function createAppOAuthService(options) {
     function isExpired(expiresAt) {
         return Boolean(expiresAt && expiresAt <= now());
     }
+    async function resolveManagedBinding(appId, releaseId) {
+        if (!options.managedInstallation)
+            return undefined;
+        const contract = await options.managedInstallation.resolveInstallationContract({
+            appId,
+            releaseId,
+        });
+        if (!contract ||
+            !Number.isSafeInteger(contract.contractGeneration) ||
+            contract.contractGeneration <= 0) {
+            throw oauthError("invalid_grant", "Managed app installation contract is unavailable");
+        }
+        return {
+            workloadEnvironmentId: options.managedInstallation.workloadEnvironmentId,
+            contractGeneration: contract.contractGeneration,
+        };
+    }
+    async function resolveManagedBindingOrNull(appId, releaseId) {
+        try {
+            return await resolveManagedBinding(appId, releaseId);
+        }
+        catch {
+            return null;
+        }
+    }
 }
 function tokenResponse(accessToken, refreshToken, expiresAt, scopes, tokenMode) {
     return {
@@ -242,14 +319,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);
     }
@@ -280,94 +360,6 @@ async function requireExactRedirectUri(db, appId, redirectUri) {
     if (!row)
         throw oauthError("invalid_request", "Redirect URI is not registered for this app");
 }
-async function ensureAuthorizedInstallation(db, input) {
-    return db.transaction(async (tx) => {
-        const [app] = await tx.select().from(apps).where(eq(apps.id, input.appId)).limit(1);
-        if (!app)
-            throw oauthError("invalid_request", "App registration not found", 404);
-        const [existing] = await tx
-            .select()
-            .from(appInstallations)
-            .where(and(eq(appInstallations.deploymentId, input.deploymentId), eq(appInstallations.appId, input.appId)))
-            .limit(1);
-        const installation = existing ??
-            (await tx
-                .insert(appInstallations)
-                .values({
-                appId: input.appId,
-                deploymentId: input.deploymentId,
-                releaseId: input.releaseId,
-                status: "active",
-                namespace: app.platformNamespace,
-                installedBy: input.actorId,
-                authorizedAt: new Date(),
-                activatedAt: new Date(),
-            })
-                .returning())[0];
-        if (!installation)
-            throw oauthError("server_error", "Could not create installation", 500);
-        for (const scope of input.grantedScopes) {
-            await tx
-                .insert(appGrants)
-                .values({
-                installationId: installation.id,
-                scope,
-                status: "granted",
-                optional: false,
-                grantedAt: new Date(),
-            })
-                .onConflictDoUpdate({
-                target: [appGrants.installationId, appGrants.scope],
-                set: { status: "granted", grantedAt: new Date(), revokedAt: null },
-            });
-        }
-        for (const scope of input.deniedOptionalScopes) {
-            await tx
-                .insert(appGrants)
-                .values({ installationId: installation.id, scope, status: "optional", optional: true })
-                .onConflictDoUpdate({
-                target: [appGrants.installationId, appGrants.scope],
-                set: { status: "optional", optional: true },
-            });
-        }
-        return installation;
-    });
-}
-async function requireInstallation(db, installationId) {
-    const installation = await selectInstallation(db, installationId);
-    if (!installation)
-        throw oauthError("invalid_grant", "App installation not found", 404);
-    return installation;
-}
-async function selectInstallation(db, installationId) {
-    const [installation] = await db
-        .select()
-        .from(appInstallations)
-        .where(eq(appInstallations.id, installationId))
-        .limit(1);
-    return installation ?? null;
-}
-async function grantedScopes(db, installationId) {
-    const rows = await db
-        .select({ scope: appGrants.scope })
-        .from(appGrants)
-        .where(and(eq(appGrants.installationId, installationId), eq(appGrants.status, "granted")))
-        .orderBy(appGrants.scope);
-    return rows.map((row) => row.scope);
-}
-function assertActiveInstallation(installation) {
-    if (installation.status !== "active") {
-        throw oauthError("invalid_grant", "App installation is not active");
-    }
-}
-function isInstallationUsable(installation, generation) {
-    return installation?.status === "active" && installation.credentialGeneration === generation;
-}
-function assertTokenClient(installation, clientId) {
-    if (installation.appId !== clientId) {
-        throw oauthError("invalid_grant", "Token belongs to a different app");
-    }
-}
 export function intersectAppTokenScopes(...sets) {
     const [first = [], ...rest] = sets;
     return first.filter((scope) => rest.every((set) => set.includes(scope))).sort();
@@ -382,6 +374,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,24 @@
 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 { appAccessCredentials, appCredentials, appGrants, appInstallations, appReleases, } from "./schema.js";
+function accessTokenDatabase(installation, credential) {
+    return Object.assign(Object.create(null), {
+        select: () => ({
+            from: (table) => {
+                if (table === appAccessCredentials) {
+                    return { where: () => ({ limit: async () => [credential] }) };
+                }
+                if (table === appInstallations) {
+                    return { where: () => ({ limit: async () => [installation] }) };
+                }
+                if (table === appGrants) {
+                    return { where: () => ({ orderBy: async () => [] }) };
+                }
+                return { where: () => ({ limit: async () => [] }) };
+            },
+        }),
+    });
+}
 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 +34,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 +92,88 @@ 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" });
+    });
+});
+describe("managed installation token binding", () => {
+    const baseInstallation = {
+        id: "inst_1",
+        appId: "app_1",
+        releaseId: "release_1",
+        deploymentId: "deployment_revision_1",
+        workloadEnvironmentId: "workload_environment_1",
+        contractGeneration: 4,
+        credentialGeneration: 2,
+        status: "active",
+    };
+    const baseCredential = {
+        id: "credential_1",
+        installationId: "inst_1",
+        workloadEnvironmentId: "workload_environment_1",
+        contractGeneration: 4,
+        generation: 2,
+        tokenMode: "offline",
+        encryptedMetadata: {},
+        status: "active",
+        expiresAt: new Date("2026-07-19T00:00:00Z"),
+        viewerId: null,
+    };
+    it("resolves the per-app generation into the runtime auth context", async () => {
+        const generations = new Map([
+            ["app_1", 4],
+            ["app_2", 11],
+        ]);
+        const service = createAppOAuthService({
+            accessCatalog: { resources: [], presets: [] },
+            deploymentId: "deployment_revision_2",
+            managedInstallation: {
+                workloadEnvironmentId: "workload_environment_1",
+                resolveInstallationContract: async ({ appId }) => ({
+                    contractGeneration: generations.get(appId) ?? 0,
+                }),
+            },
+            now: () => new Date("2026-07-18T12:00:00Z"),
+        });
+        await expect(service.resolveAccessToken(accessTokenDatabase(baseInstallation, baseCredential), "vapp_fixture")).resolves.toMatchObject({
+            appWorkloadEnvironmentId: "workload_environment_1",
+            appContractGeneration: 4,
+        });
+    });
+    it.each([
+        ["workload_environment_other", 4],
+        ["workload_environment_1", 3],
+    ])("rejects credential binding workload=%s generation=%s", async (workloadEnvironmentId, contractGeneration) => {
+        const service = createAppOAuthService({
+            accessCatalog: { resources: [], presets: [] },
+            deploymentId: "deployment_revision_2",
+            managedInstallation: {
+                workloadEnvironmentId: "workload_environment_1",
+                resolveInstallationContract: async () => ({ contractGeneration: 4 }),
+            },
+            now: () => new Date("2026-07-18T12:00:00Z"),
+        });
+        await expect(service.resolveAccessToken(accessTokenDatabase(baseInstallation, {
+            ...baseCredential,
+            workloadEnvironmentId,
+            contractGeneration,
+        }), "vapp_fixture")).resolves.toBeNull();
+    });
+});

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,23 @@
 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 { ManagedAppInstallationAuthority } from "./runtime-port.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;
+        managedInstallation?: ManagedAppInstallationAuthority;
+        clientAuthentication?: "optional" | "required";
     };
     /**
      * Enables the iframe session-token broker. Requires {@link oauth} for the
@@ -26,6 +26,7 @@ export interface AppsAdminRouteOptions extends AppsServiceOptions {
      */
     sessionToken?: {
         secret: string;
+        managedInstallation?: ManagedAppInstallationAuthority;
         ttlSeconds?: number;
     };
     /**
@@ -39,4 +40,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 {};