@voyant-travel/apps 0.7.0 → 0.9.0

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";
@@ -16,16 +18,19 @@ 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,
     });
     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,
             ttlSeconds: options.sessionToken.ttlSeconds,
             deploymentId: options.oauth.deploymentId,
+            managedInstallation: options.sessionToken.managedInstallation ?? options.oauth.managedInstallation,
             oauth,
         })
         : null;
@@ -42,8 +47,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 +58,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 +80,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 +107,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 +130,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 +244,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,13 @@
-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;
+}
+/**
+ * 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,3 +1,11 @@
-export function createAppsRuntimePortContribution() {
+import { appsManagedAuthRuntimePort } from "./runtime-port.js";
+/**
+ * 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 {};
     return {};
 }

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

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

package/dist/runtime-contributor.test.js

@@ -0,0 +1,55 @@
+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 because scalar environment values cannot authorize managed installations", () => {
+        expect(createAppsRuntimePortContribution(host({}))).toEqual({});
+        expect(createAppsRuntimePortContribution(host({
+            VOYANT_APP_RUNTIME_AUDIENCE: "deployment-1",
+            VOYANT_APP_SESSION_TOKEN_SIGNING_SECRET: "s".repeat(32),
+        }))).toEqual({});
+    });
+    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("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

@@ -0,0 +1,29 @@
+/** 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;
+}
+export declare const appsManagedAuthRuntimePort: import("@voyant-travel/core/project").VoyantPort<AppsManagedAuthRuntime>;

package/dist/runtime-port.js

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

package/dist/schema.d.ts

@@ -995,6 +995,40 @@ export declare const appInstallations: import("drizzle-orm/pg-core").PgTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        workloadEnvironmentId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "workload_environment_id";
+            tableName: "app_installations";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        contractGeneration: import("drizzle-orm/pg-core").PgColumn<{
+            name: "contract_generation";
+            tableName: "app_installations";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         releaseId: import("drizzle-orm/pg-core").PgColumn<{
             name: "release_id";
             tableName: "app_installations";
@@ -1519,6 +1553,40 @@ export declare const appAccessCredentials: import("drizzle-orm/pg-core").PgTable
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        workloadEnvironmentId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "workload_environment_id";
+            tableName: "app_access_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        contractGeneration: import("drizzle-orm/pg-core").PgColumn<{
+            name: "contract_generation";
+            tableName: "app_access_credentials";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         tokenMode: import("drizzle-orm/pg-core").PgColumn<{
             name: "token_mode";
             tableName: "app_access_credentials";
@@ -1766,6 +1834,40 @@ export declare const appOAuthAuthorizationCodes: import("drizzle-orm/pg-core").P
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        workloadEnvironmentId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "workload_environment_id";
+            tableName: "app_oauth_authorization_codes";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        contractGeneration: import("drizzle-orm/pg-core").PgColumn<{
+            name: "contract_generation";
+            tableName: "app_oauth_authorization_codes";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         codeHash: import("drizzle-orm/pg-core").PgColumn<{
             name: "code_hash";
             tableName: "app_oauth_authorization_codes";
@@ -2051,6 +2153,40 @@ export declare const appOAuthRefreshTokens: import("drizzle-orm/pg-core").PgTabl
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        workloadEnvironmentId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "workload_environment_id";
+            tableName: "app_oauth_refresh_tokens";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        contractGeneration: import("drizzle-orm/pg-core").PgColumn<{
+            name: "contract_generation";
+            tableName: "app_oauth_refresh_tokens";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         status: import("drizzle-orm/pg-core").PgColumn<{
             name: "status";
             tableName: "app_oauth_refresh_tokens";
@@ -3007,6 +3143,40 @@ export declare const appSessionTokens: import("drizzle-orm/pg-core").PgTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        workloadEnvironmentId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "workload_environment_id";
+            tableName: "app_session_tokens";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        contractGeneration: import("drizzle-orm/pg-core").PgColumn<{
+            name: "contract_generation";
+            tableName: "app_session_tokens";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         jti: import("drizzle-orm/pg-core").PgColumn<{
             name: "jti";
             tableName: "app_session_tokens";

package/dist/schema.js

@@ -155,6 +155,8 @@ export const appInstallations = pgTable("app_installations", {
         .notNull()
         .references(() => apps.id, { onDelete: "cascade" }),
     deploymentId: text("deployment_id").notNull(),
+    workloadEnvironmentId: text("workload_environment_id"),
+    contractGeneration: integer("contract_generation"),
     releaseId: text("release_id")
         .notNull()
         .references(() => appReleases.id, { onDelete: "restrict" }),
@@ -182,6 +184,10 @@ export const appInstallations = pgTable("app_installations", {
     index("idx_app_installations_app").on(table.appId, table.status),
     index("idx_app_installations_deployment").on(table.deploymentId, table.status),
     uniqueIndex("uidx_app_installations_deployment_app").on(table.deploymentId, table.appId),
+    uniqueIndex("uidx_app_installations_workload_environment_app")
+        .on(table.workloadEnvironmentId, table.appId)
+        .where(sql `${table.workloadEnvironmentId} IS NOT NULL`),
+    check("app_installations_managed_binding_complete", sql `(${table.workloadEnvironmentId} IS NULL AND ${table.contractGeneration} IS NULL) OR (${table.workloadEnvironmentId} IS NOT NULL AND ${table.contractGeneration} > 0)`),
     // agent-quality: raw-sql reviewed -- owner: apps; identifier is a Drizzle-owned column and the literal prefix is static.
     check("app_installations_namespace_reserved", sql `${table.namespace} LIKE 'app--%'`),
 ]);
@@ -206,6 +212,8 @@ export const appAccessCredentials = pgTable("app_access_credentials", {
         .notNull()
         .references(() => appInstallations.id, { onDelete: "cascade" }),
     generation: integer("generation").notNull(),
+    workloadEnvironmentId: text("workload_environment_id"),
+    contractGeneration: integer("contract_generation"),
     tokenMode: appAccessTokenModeEnum("token_mode").notNull().default("offline"),
     credentialHash: text("credential_hash").notNull(),
     encryptedMetadata: jsonb("encrypted_metadata").$type().notNull(),
@@ -218,6 +226,7 @@ export const appAccessCredentials = pgTable("app_access_credentials", {
 }, (table) => [
     index("idx_app_access_credentials_installation").on(table.installationId, table.status),
     index("idx_app_access_credentials_generation").on(table.installationId, table.tokenMode, table.generation),
+    check("app_access_credentials_managed_binding_complete", sql `(${table.workloadEnvironmentId} IS NULL AND ${table.contractGeneration} IS NULL) OR (${table.workloadEnvironmentId} IS NOT NULL AND ${table.contractGeneration} > 0)`),
 ]);
 export const appOAuthAuthorizationCodes = pgTable("app_oauth_authorization_codes", {
     id: typeId("app_oauth_authorization_codes"),
@@ -231,6 +240,8 @@ export const appOAuthAuthorizationCodes = pgTable("app_oauth_authorization_codes
         .notNull()
         .references(() => appReleases.id, { onDelete: "cascade" }),
     deploymentId: text("deployment_id").notNull(),
+    workloadEnvironmentId: text("workload_environment_id"),
+    contractGeneration: integer("contract_generation"),
     codeHash: text("code_hash").notNull(),
     stateHash: text("state_hash").notNull(),
     redirectUri: text("redirect_uri").notNull(),
@@ -246,6 +257,7 @@ export const appOAuthAuthorizationCodes = pgTable("app_oauth_authorization_codes
 }, (table) => [
     uniqueIndex("uidx_app_oauth_codes_hash").on(table.codeHash),
     index("idx_app_oauth_codes_installation").on(table.installationId, table.expiresAt),
+    check("app_oauth_codes_managed_binding_complete", sql `(${table.workloadEnvironmentId} IS NULL AND ${table.contractGeneration} IS NULL) OR (${table.workloadEnvironmentId} IS NOT NULL AND ${table.contractGeneration} > 0)`),
 ]);
 export const appOAuthRefreshTokens = pgTable("app_oauth_refresh_tokens", {
     id: typeId("app_oauth_refresh_tokens"),
@@ -254,6 +266,8 @@ export const appOAuthRefreshTokens = pgTable("app_oauth_refresh_tokens", {
         .references(() => appInstallations.id, { onDelete: "cascade" }),
     tokenHash: text("token_hash").notNull(),
     generation: integer("generation").notNull(),
+    workloadEnvironmentId: text("workload_environment_id"),
+    contractGeneration: integer("contract_generation"),
     status: appAccessCredentialStatusEnum("status").notNull().default("active"),
     rotatedFromId: text("rotated_from_id"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
@@ -262,6 +276,7 @@ export const appOAuthRefreshTokens = pgTable("app_oauth_refresh_tokens", {
 }, (table) => [
     uniqueIndex("uidx_app_oauth_refresh_tokens_hash").on(table.tokenHash),
     index("idx_app_oauth_refresh_tokens_installation").on(table.installationId, table.status),
+    check("app_oauth_refresh_tokens_managed_binding_complete", sql `(${table.workloadEnvironmentId} IS NULL AND ${table.contractGeneration} IS NULL) OR (${table.workloadEnvironmentId} IS NOT NULL AND ${table.contractGeneration} > 0)`),
 ]);
 export const appInstallationSettings = pgTable("app_installation_settings", {
     id: typeId("app_installation_settings"),
@@ -354,6 +369,8 @@ export const appSessionTokens = pgTable("app_session_tokens", {
         .references(() => appInstallations.id, { onDelete: "cascade" }),
     appId: text("app_id").notNull(),
     deploymentId: text("deployment_id").notNull(),
+    workloadEnvironmentId: text("workload_environment_id"),
+    contractGeneration: integer("contract_generation"),
     jti: text("jti").notNull(),
     viewerId: text("viewer_id").notNull(),
     entityType: text("entity_type"),
@@ -366,4 +383,5 @@ export const appSessionTokens = pgTable("app_session_tokens", {
 }, (table) => [
     uniqueIndex("uidx_app_session_tokens_jti").on(table.jti),
     index("idx_app_session_tokens_installation").on(table.installationId, table.expiresAt),
+    check("app_session_tokens_managed_binding_complete", sql `(${table.workloadEnvironmentId} IS NULL AND ${table.contractGeneration} IS NULL) OR (${table.workloadEnvironmentId} IS NOT NULL AND ${table.contractGeneration} > 0)`),
 ]);

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

@@ -1,5 +1,6 @@
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { createAppOAuthService } from "./oauth-service.js";
+import type { ManagedAppInstallationAuthority } from "./runtime-port.js";
 import { type AppSessionTokenEntity } from "./session-token.js";
 type AppOAuthService = ReturnType<typeof createAppOAuthService>;
 export interface AppSessionTokenServiceOptions {
@@ -7,6 +8,7 @@ export interface AppSessionTokenServiceOptions {
     secret: string;
     /** The deployment audience the tokens are bound to. */
     deploymentId: string;
+    managedInstallation?: ManagedAppInstallationAuthority;
     /** OAuth service supplying the online actor-token-exchange primitive. */
     oauth: AppOAuthService;
     ttlSeconds?: number;
@@ -15,6 +17,8 @@ export interface AppSessionTokenServiceOptions {
 export interface IssueAppSessionTokenInput {
     installationId: string;
     viewerId: string;
+    /** Current host-authenticated viewer permissions. */
+    viewerScopes?: readonly string[];
     entity?: AppSessionTokenEntity | null;
     slot?: string | null;
 }