@voyant-travel/apps 0.8.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,
@@ -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
@@ -97,6 +112,12 @@ 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 } : {}),
@@ -106,6 +127,8 @@ export function createAppOAuthService(options) {
     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)
@@ -142,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;
         });
@@ -165,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");
             }
@@ -174,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", {
@@ -185,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);
@@ -195,6 +229,8 @@ 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
@@ -214,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);
@@ -223,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 },
@@ -235,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,
         });
@@ -243,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 {
@@ -295,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();

package/dist/oauth-service.test.js

@@ -1,6 +1,24 @@
 import { describe, expect, it } from "vitest";
 import { createAppOAuthService, intersectAppTokenScopes, readStoredAppContextConstraint, readStoredScopes, } from "./oauth-service.js";
-import { appCredentials, appReleases } from "./schema.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"]);
@@ -95,3 +113,67 @@ describe("managed client authentication", () => {
         })).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.d.ts

@@ -3,6 +3,7 @@ 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 { 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 = {
@@ -15,6 +16,7 @@ export interface AppsAdminRouteOptions extends AppsServiceOptions {
     oauth?: {
         accessCatalog: AccessCatalog;
         deploymentId: string;
+        managedInstallation?: ManagedAppInstallationAuthority;
         clientAuthentication?: "optional" | "required";
     };
     /**
@@ -24,6 +26,7 @@ export interface AppsAdminRouteOptions extends AppsServiceOptions {
      */
     sessionToken?: {
         secret: string;
+        managedInstallation?: ManagedAppInstallationAuthority;
         ttlSeconds?: number;
     };
     /**

package/dist/routes.js

@@ -18,6 +18,7 @@ export function createAppsAdminRoutes(options = {}) {
     const service = createAppsService(options);
     const installations = createAppInstallationService({
         deploymentId: options.oauth?.deploymentId ?? options.deploymentId,
+        managedInstallation: options.oauth?.managedInstallation,
         platformApiVersion: options.platformApiVersion,
         eventBus: options.eventBus,
         customFields: options.customFields,
@@ -29,6 +30,7 @@ export function createAppsAdminRoutes(options = {}) {
             secret: options.sessionToken.secret,
             ttlSeconds: options.sessionToken.ttlSeconds,
             deploymentId: options.oauth.deploymentId,
+            managedInstallation: options.sessionToken.managedInstallation ?? options.oauth.managedInstallation,
             oauth,
         })
         : null;

package/dist/runtime-contributor.d.ts

@@ -5,5 +5,9 @@ export interface AppsRuntimeContributorHost {
         id: string;
     }): boolean;
 }
-/** Package-owned, provider-neutral managed-auth configuration. */
+/**
+ * Managed installation contracts are host authority and cannot be reconstructed
+ * from scalar environment values. Hosts contribute `apps.managed-auth`
+ * explicitly; self-hosted runtimes keep the port absent.
+ */
 export declare function createAppsRuntimePortContribution(host: AppsRuntimeContributorHost): Readonly<Record<string, unknown>>;

package/dist/runtime-contributor.js

@@ -1,26 +1,11 @@
 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. */
+/**
+ * Managed installation contracts are host authority and cannot be reconstructed
+ * from scalar environment values. Hosts contribute `apps.managed-auth`
+ * explicitly; self-hosted runtimes keep the port absent.
+ */
 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 };
+    return {};
 }

package/dist/runtime-contributor.test.js

@@ -10,23 +10,12 @@ function host(values) {
     };
 }
 describe("createAppsRuntimePortContribution", () => {
-    it("stays off unless both managed-auth inputs are present", () => {
+    it("stays off because scalar environment values cannot authorize managed installations", () => {
         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  ",
+        expect(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,
-            },
-        });
+        }))).toEqual({});
     });
     it("does not replace an explicitly host-provided managed-auth port", () => {
         const contribution = createAppsRuntimePortContribution({
@@ -38,15 +27,29 @@ describe("createAppsRuntimePortContribution", () => {
         });
         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/);
+    it("resolves independent per-app generations within one workload environment", async () => {
+        const generations = new Map([
+            ["app_1", 2],
+            ["app_2", 9],
+        ]);
+        const runtime = {
+            runtimeAudience: "runtime-audience",
+            installationAuthority: {
+                workloadEnvironmentId: "workload_environment_1",
+                resolveInstallationContract: async ({ appId }) => ({
+                    contractGeneration: generations.get(appId) ?? 0,
+                }),
+            },
+            sessionTokenSigningSecret: "s".repeat(32),
+        };
+        expect(() => appsManagedAuthRuntimePort.test(runtime)).not.toThrow();
+        await expect(runtime.installationAuthority.resolveInstallationContract({
+            appId: "app_1",
+            releaseId: "release_1",
+        })).resolves.toEqual({ contractGeneration: 2 });
+        await expect(runtime.installationAuthority.resolveInstallationContract({
+            appId: "app_2",
+            releaseId: "release_2",
+        })).resolves.toEqual({ contractGeneration: 9 });
     });
 });

package/dist/runtime-port.d.ts

@@ -1,6 +1,27 @@
+/** Persisted host contract for one managed app installation. */
+export interface ManagedAppInstallationBinding {
+    workloadEnvironmentId: string;
+    contractGeneration: number;
+}
+export interface ManagedAppInstallationContractInput {
+    appId: string;
+    releaseId: string;
+}
+export interface ManagedAppInstallationContract {
+    /** Per-app monotonic generation. Advancing it invalidates prior app credentials. */
+    contractGeneration: number;
+}
+export interface ManagedAppInstallationAuthority {
+    /** Stable opaque workload-environment identity across runtime rollouts. */
+    workloadEnvironmentId: string;
+    /** Resolve the current admitted contract for this specific app release. */
+    resolveInstallationContract(input: ManagedAppInstallationContractInput): Promise<ManagedAppInstallationContract | null>;
+}
 export interface AppsManagedAuthRuntime {
     /** Stable audience shared by authorization, installations, and session tokens. */
     runtimeAudience: string;
+    /** Provider-neutral managed installation authority supplied by the host. */
+    installationAuthority: ManagedAppInstallationAuthority;
     /** Host-owned HMAC material for short-lived extension session tokens. */
     sessionTokenSigningSecret: string;
     sessionTokenTtlSeconds?: number;

package/dist/runtime-port.js

@@ -8,6 +8,12 @@ export const appsManagedAuthRuntimePort = definePort({
         if (!runtime.runtimeAudience?.trim()) {
             throw new TypeError("apps.managed-auth runtimeAudience must be a non-empty string.");
         }
+        if (!runtime.installationAuthority?.workloadEnvironmentId?.trim()) {
+            throw new TypeError("apps.managed-auth installationAuthority.workloadEnvironmentId must be a non-empty string.");
+        }
+        if (typeof runtime.installationAuthority.resolveInstallationContract !== "function") {
+            throw new TypeError("apps.managed-auth installationAuthority.resolveInstallationContract must be a function.");
+        }
         if (typeof runtime.sessionTokenSigningSecret !== "string" ||
             runtime.sessionTokenSigningSecret.length < 32) {
             throw new TypeError("apps.managed-auth sessionTokenSigningSecret must contain at least 32 characters.");