@voyant-travel/apps 0.7.0 → 0.9.0

package/dist/session-token-service.js

@@ -13,18 +13,22 @@
  * Both paths write `app_audit_events` so issuance and exchange are auditable.
  */
 import { ApiHttpError } from "@voyant-travel/hono";
-import { and, eq, isNull } from "drizzle-orm";
+import { and, eq, gt, isNull } from "drizzle-orm";
 import { appAuditEvents, appInstallations, appSessionTokens, } from "./schema.js";
 import { signAppSessionToken, verifyAppSessionToken, } from "./session-token.js";
 export function createAppSessionTokenService(options) {
     const now = () => options.now?.() ?? new Date();
     async function issue(db, input) {
         const installation = await requireActiveInstallation(db, input.installationId);
+        const managedBinding = await resolveManagedBinding(options.managedInstallation, installation.appId, installation.releaseId);
+        assertManagedBinding(installation, managedBinding);
         const context = {
             appId: installation.appId,
             installationId: installation.id,
             deploymentId: installation.deploymentId,
+            ...(managedBinding ?? {}),
             viewerId: input.viewerId,
+            viewerScopes: input.viewerScopes ?? [],
             entity: input.entity ?? null,
             slot: input.slot ?? null,
         };
@@ -36,6 +40,8 @@ export function createAppSessionTokenService(options) {
             installationId: installation.id,
             appId: installation.appId,
             deploymentId: installation.deploymentId,
+            workloadEnvironmentId: managedBinding?.workloadEnvironmentId,
+            contractGeneration: managedBinding?.contractGeneration,
             jti: signed.claims.jti,
             viewerId: input.viewerId,
             entityType: signed.claims.entity?.type ?? null,
@@ -52,7 +58,7 @@ export function createAppSessionTokenService(options) {
     }
     async function exchange(db, input) {
         const verified = verifyAppSessionToken(input.token, options.secret, {
-            deploymentId: options.deploymentId,
+            deploymentId: options.managedInstallation ? undefined : options.deploymentId,
             audience: input.clientId,
             now,
         });
@@ -63,37 +69,93 @@ export function createAppSessionTokenService(options) {
             });
         }
         const { claims } = verified;
-        // Single-use: consume the jti atomically. A row that is missing or already
-        // consumed is a replay and is refused before any credential is minted.
-        const consumed = await db
-            .update(appSessionTokens)
-            .set({ consumedAt: now(), consumedByActorId: claims.sub })
-            .where(and(eq(appSessionTokens.jti, claims.jti), isNull(appSessionTokens.consumedAt)))
-            .returning({ id: appSessionTokens.id });
-        if (consumed.length === 0) {
-            throw new ApiHttpError("Session token has already been used", {
-                status: 401,
-                code: "app_session_token_replayed",
+        return db.transaction(async (tx) => {
+            const installation = await requireActiveInstallation(tx, claims.installationId);
+            const managedBinding = await resolveManagedBinding(options.managedInstallation, installation.appId, installation.releaseId);
+            if (installation.appId !== claims.aud ||
+                (!managedBinding && installation.deploymentId !== claims.deploymentId) ||
+                !managedBindingMatches(installation, managedBinding) ||
+                !managedBindingMatches(claims, managedBinding)) {
+                throw new ApiHttpError("Session token installation context changed", {
+                    status: 401,
+                    code: "app_session_token_installation_mismatch",
+                });
+            }
+            // Client authentication and token construction happen before consumption,
+            // but in the same transaction. If authentication/minting fails, or another
+            // exchange wins the JTI race, every credential side effect rolls back.
+            const tokens = await options.oauth.token(tx, {
+                grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
+                installationId: installation.id,
+                viewerId: claims.sub,
+                viewerScopes: intersectRequestedScopes(claims.viewerScopes, input.viewerScopes),
+                contextualScopes: input.contextualScopes,
+                contextConstraint: { entity: claims.entity, slot: claims.slot },
+                clientId: input.clientId,
+                clientSecret: input.clientSecret,
             });
-        }
-        const installation = await requireActiveInstallation(db, claims.installationId);
-        const tokens = await options.oauth.token(db, {
-            grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
-            installationId: installation.id,
-            viewerId: claims.sub,
-            viewerScopes: input.viewerScopes,
-            contextualScopes: input.contextualScopes,
-            clientId: input.clientId,
-            clientSecret: input.clientSecret,
-        });
-        await audit(db, installation, claims.sub, "session-token.exchanged", {
-            jti: claims.jti,
-            slot: claims.slot,
+            const consumed = await tx
+                .update(appSessionTokens)
+                .set({ consumedAt: now(), consumedByActorId: claims.sub })
+                .where(and(eq(appSessionTokens.jti, claims.jti), eq(appSessionTokens.installationId, installation.id), eq(appSessionTokens.appId, claims.aud), eq(appSessionTokens.deploymentId, claims.deploymentId), ...(managedBinding
+                ? [
+                    eq(appSessionTokens.workloadEnvironmentId, managedBinding.workloadEnvironmentId),
+                    eq(appSessionTokens.contractGeneration, managedBinding.contractGeneration),
+                ]
+                : []), eq(appSessionTokens.viewerId, claims.sub), isNull(appSessionTokens.consumedAt), gt(appSessionTokens.expiresAt, now())))
+                .returning({ id: appSessionTokens.id });
+            if (consumed.length === 0) {
+                throw new ApiHttpError("Session token has already been used", {
+                    status: 401,
+                    code: "app_session_token_replayed",
+                });
+            }
+            await audit(tx, installation, claims.sub, "session-token.exchanged", {
+                jti: claims.jti,
+                slot: claims.slot,
+                entityType: claims.entity?.type ?? null,
+                entityId: claims.entity?.id ?? null,
+            });
+            return tokens;
         });
-        return tokens;
     }
     return { issue, exchange };
 }
+async function resolveManagedBinding(authority, appId, releaseId) {
+    if (!authority)
+        return undefined;
+    const contract = await authority.resolveInstallationContract({ appId, releaseId });
+    if (!contract ||
+        !Number.isSafeInteger(contract.contractGeneration) ||
+        contract.contractGeneration <= 0) {
+        throw new ApiHttpError("Managed app installation contract is unavailable", {
+            status: 401,
+            code: "app_session_token_contract_unavailable",
+        });
+    }
+    return {
+        workloadEnvironmentId: authority.workloadEnvironmentId,
+        contractGeneration: contract.contractGeneration,
+    };
+}
+function managedBindingMatches(persisted, expected) {
+    if (!expected)
+        return true;
+    return (persisted.workloadEnvironmentId === expected.workloadEnvironmentId &&
+        persisted.contractGeneration === expected.contractGeneration);
+}
+function assertManagedBinding(persisted, expected) {
+    if (!managedBindingMatches(persisted, expected)) {
+        throw new ApiHttpError("App installation belongs to a different managed environment", {
+            status: 401,
+            code: "app_session_token_installation_mismatch",
+        });
+    }
+}
+function intersectRequestedScopes(trustedViewerScopes, requestedScopes) {
+    const trusted = new Set(trustedViewerScopes);
+    return Array.from(new Set(requestedScopes.filter((scope) => trusted.has(scope)))).sort();
+}
 async function requireActiveInstallation(db, installationId) {
     const [installation] = await db
         .select()

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

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

package/dist/session-token-service.test.js

@@ -0,0 +1,187 @@
+import { ApiHttpError } from "@voyant-travel/hono";
+import { describe, expect, it, vi } from "vitest";
+import { appOAuthTokenSchema } from "./contracts.js";
+import { createAppSessionTokenService } from "./session-token-service.js";
+function trackedDatabaseStub(installationOverrides = {}) {
+    const installation = {
+        id: "inst_1",
+        appId: "app_1",
+        releaseId: "rel_1",
+        deploymentId: "dep_1",
+        status: "active",
+        namespace: "app--one",
+        ...installationOverrides,
+    };
+    const consume = vi.fn().mockResolvedValue([{ id: "session_1" }]);
+    const db = {
+        select: () => ({
+            from: () => ({ where: () => ({ limit: async () => [installation] }) }),
+        }),
+        insert: () => ({ values: async () => undefined }),
+        update: () => ({
+            set: () => ({ where: () => ({ returning: consume }) }),
+        }),
+        transaction: async (callback) => callback(db),
+    };
+    return { db, consume };
+}
+function databaseStub() {
+    return trackedDatabaseStub().db;
+}
+describe("app session token service", () => {
+    it("does not expose an app-asserted viewer scope grant on the public OAuth schema", () => {
+        expect(appOAuthTokenSchema.safeParse({
+            grant_type: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
+            installation_id: "inst_1",
+            viewer_id: "viewer_1",
+            viewer_scopes: ["finance-document-artifacts:write"],
+            client_id: "app_1",
+        }).success).toBe(false);
+    });
+    it("intersects app-requested scopes with host-signed viewer authority", async () => {
+        const token = vi.fn().mockResolvedValue({ accessToken: "online" });
+        const service = createAppSessionTokenService({
+            secret: "test-deployment-session-secret-value-000000000000",
+            deploymentId: "dep_1",
+            oauth: { token },
+            now: () => new Date("2026-07-18T09:00:00.000Z"),
+        });
+        const db = databaseStub();
+        const issued = await service.issue(db, {
+            installationId: "inst_1",
+            viewerId: "viewer_1",
+            viewerScopes: ["finance-documents:read", "finance-document-artifacts:write"],
+            entity: { type: "invoice", id: "invoice_1" },
+            slot: "invoice.details.after-summary",
+        });
+        await service.exchange(db, {
+            token: issued.token,
+            clientId: "app_1",
+            clientSecret: "secret",
+            viewerScopes: [
+                "finance-documents:read",
+                "finance-document-artifacts:write",
+                "finance-external-sync:write",
+            ],
+        });
+        expect(token).toHaveBeenCalledWith(db, expect.objectContaining({
+            viewerId: "viewer_1",
+            viewerScopes: ["finance-document-artifacts:write", "finance-documents:read"],
+            contextConstraint: {
+                entity: { type: "invoice", id: "invoice_1" },
+                slot: "invoice.details.after-summary",
+            },
+        }));
+    });
+    it("fails closed to no online scopes when issuance had no viewer authority", async () => {
+        const token = vi.fn().mockResolvedValue({ accessToken: "online" });
+        const service = createAppSessionTokenService({
+            secret: "test-deployment-session-secret-value-000000000000",
+            deploymentId: "dep_1",
+            oauth: { token },
+            now: () => new Date("2026-07-18T09:00:00.000Z"),
+        });
+        const db = databaseStub();
+        const issued = await service.issue(db, {
+            installationId: "inst_1",
+            viewerId: "viewer_1",
+        });
+        await service.exchange(db, {
+            token: issued.token,
+            clientId: "app_1",
+            viewerScopes: ["finance-document-artifacts:write"],
+        });
+        expect(token).toHaveBeenCalledWith(db, expect.objectContaining({ viewerScopes: [] }));
+    });
+    it("does not consume the JTI when app client authentication fails", async () => {
+        const token = vi.fn(async (_db, input) => {
+            if (input.clientSecret !== "right-secret") {
+                throw new ApiHttpError("Client authentication failed", {
+                    status: 401,
+                    code: "invalid_client",
+                });
+            }
+            return { accessToken: "online" };
+        });
+        const service = createAppSessionTokenService({
+            secret: "test-deployment-session-secret-value-000000000000",
+            deploymentId: "dep_1",
+            oauth: { token },
+            now: () => new Date("2026-07-18T09:00:00.000Z"),
+        });
+        const { db, consume } = trackedDatabaseStub();
+        const issued = await service.issue(db, {
+            installationId: "inst_1",
+            viewerId: "viewer_1",
+        });
+        await expect(service.exchange(db, {
+            token: issued.token,
+            clientId: "app_1",
+            clientSecret: "wrong-secret",
+            viewerScopes: [],
+        })).rejects.toMatchObject({ code: "invalid_client" });
+        expect(consume).not.toHaveBeenCalled();
+        await expect(service.exchange(db, {
+            token: issued.token,
+            clientId: "app_1",
+            clientSecret: "right-secret",
+            viewerScopes: [],
+        })).resolves.toEqual({ accessToken: "online" });
+        expect(consume).toHaveBeenCalledOnce();
+    });
+    it("leaves the JTI retryable when online credential minting fails", async () => {
+        const token = vi
+            .fn()
+            .mockRejectedValueOnce(new Error("credential insert failed"))
+            .mockResolvedValueOnce({ accessToken: "online" });
+        const service = createAppSessionTokenService({
+            secret: "test-deployment-session-secret-value-000000000000",
+            deploymentId: "dep_1",
+            oauth: { token },
+            now: () => new Date("2026-07-18T09:00:00.000Z"),
+        });
+        const { db, consume } = trackedDatabaseStub();
+        const issued = await service.issue(db, {
+            installationId: "inst_1",
+            viewerId: "viewer_1",
+        });
+        const input = {
+            token: issued.token,
+            clientId: "app_1",
+            viewerScopes: [],
+        };
+        await expect(service.exchange(db, input)).rejects.toThrow("credential insert failed");
+        expect(consume).not.toHaveBeenCalled();
+        await expect(service.exchange(db, input)).resolves.toEqual({ accessToken: "online" });
+        expect(consume).toHaveBeenCalledOnce();
+    });
+    it("keeps a managed session exchange valid across deployment rollouts", async () => {
+        const token = vi.fn().mockResolvedValue({ accessToken: "online" });
+        const installationAuthority = {
+            workloadEnvironmentId: "workload_environment_1",
+            resolveInstallationContract: async () => ({ contractGeneration: 7 }),
+        };
+        const { db } = trackedDatabaseStub({
+            workloadEnvironmentId: "workload_environment_1",
+            contractGeneration: 7,
+        });
+        const issued = await createAppSessionTokenService({
+            secret: "test-deployment-session-secret-value-000000000000",
+            deploymentId: "deployment_revision_1",
+            managedInstallation: installationAuthority,
+            oauth: { token },
+            now: () => new Date("2026-07-18T09:00:00.000Z"),
+        }).issue(db, { installationId: "inst_1", viewerId: "viewer_1" });
+        await expect(createAppSessionTokenService({
+            secret: "test-deployment-session-secret-value-000000000000",
+            deploymentId: "deployment_revision_2",
+            managedInstallation: installationAuthority,
+            oauth: { token },
+            now: () => new Date("2026-07-18T09:00:01.000Z"),
+        }).exchange(db, {
+            token: issued.token,
+            clientId: "app_1",
+            viewerScopes: [],
+        })).resolves.toEqual({ accessToken: "online" });
+    });
+});

package/dist/session-token.d.ts

@@ -3,7 +3,7 @@ export declare const APP_SESSION_TOKEN_PREFIX = "vsess_";
  * HKDF context label under which admin session tokens are signed. Bumping the
  * version suffix invalidates every outstanding token.
  */
-export declare const APP_SESSION_TOKEN_KEY_CONTEXT = "voyant:app-session-token:v1";
+export declare const APP_SESSION_TOKEN_KEY_CONTEXT = "voyant:app-session-token:v2";
 /** Default token lifetime — short enough to make replay low value. */
 export declare const APP_SESSION_TOKEN_TTL_SECONDS = 120;
 /** Stable issuer claim, distinguishing these from every other Voyant token. */
@@ -19,8 +19,12 @@ export interface AppSessionTokenContext {
     appId: string;
     installationId: string;
     deploymentId: string;
+    workloadEnvironmentId?: string;
+    contractGeneration?: number;
     /** The admin viewer the token acts on behalf of. */
     viewerId: string;
+    /** Host-authenticated viewer permissions captured at issuance. */
+    viewerScopes?: readonly string[];
     entity?: AppSessionTokenEntity | null;
     slot?: string | null;
 }
@@ -33,8 +37,12 @@ export interface AppSessionTokenClaims {
     sub: string;
     installationId: string;
     deploymentId: string;
+    workloadEnvironmentId?: string;
+    contractGeneration?: number;
     entity: AppSessionTokenEntity | null;
     slot: string | null;
+    /** Host-authenticated viewer permissions; never supplied by the app backend. */
+    viewerScopes: string[];
     iat: number;
     exp: number;
     /** Unique token id; the exchange store enforces single use by this value. */
@@ -63,6 +71,9 @@ export interface VerifyAppSessionTokenExpectations {
     audience?: string;
     /** Reject unless `deploymentId` equals this deployment. */
     deploymentId?: string;
+    /** Managed workload-environment and contract binding; both are required together. */
+    workloadEnvironmentId?: string;
+    contractGeneration?: number;
     now?: () => Date;
 }
 export type AppSessionTokenVerifyResult = {
@@ -72,7 +83,7 @@ export type AppSessionTokenVerifyResult = {
     ok: false;
     reason: AppSessionTokenRejectReason;
 };
-export type AppSessionTokenRejectReason = "malformed" | "bad_signature" | "expired" | "wrong_issuer" | "audience_mismatch" | "deployment_mismatch";
+export type AppSessionTokenRejectReason = "malformed" | "bad_signature" | "expired" | "wrong_issuer" | "audience_mismatch" | "deployment_mismatch" | "workload_environment_mismatch" | "contract_generation_mismatch";
 /**
  * Verify a session token's signature, issuer, expiry, and (when supplied)
  * audience and deployment binding. Returns the decoded claims on success or a

package/dist/session-token.test.js

@@ -6,9 +6,15 @@ const context = {
     installationId: "apin_1",
     deploymentId: "dep_1",
     viewerId: "usr_1",
+    viewerScopes: ["finance-documents:read", "finance-document-artifacts:write"],
     entity: { type: "booking", id: "book_1" },
     slot: "booking.details.header",
 };
+const managedContext = {
+    ...context,
+    workloadEnvironmentId: "workload_environment_1",
+    contractGeneration: 3,
+};
 const at = (iso) => () => new Date(iso);
 describe("app session token", () => {
     it("round-trips claims, binds context, and carries a unique id", () => {
@@ -27,6 +33,10 @@ describe("app session token", () => {
         expect(result.claims.installationId).toBe("apin_1");
         expect(result.claims.entity).toEqual({ type: "booking", id: "book_1" });
         expect(result.claims.slot).toBe("booking.details.header");
+        expect(result.claims.viewerScopes).toEqual([
+            "finance-document-artifacts:write",
+            "finance-documents:read",
+        ]);
         expect(result.claims.jti).toMatch(/^st_/);
     });
     it("mints a distinct jti per issuance", () => {
@@ -60,6 +70,47 @@ describe("app session token", () => {
         });
         expect(result).toEqual({ ok: false, reason: "deployment_mismatch" });
     });
+    it("uses the stable workload environment rather than deployment revision in managed mode", () => {
+        const signed = signAppSessionToken({ ...managedContext, deploymentId: "deployment_revision_1" }, secret, { now: at("2026-07-17T10:00:00Z") });
+        const result = verifyAppSessionToken(signed.token, secret, {
+            audience: "app_1",
+            workloadEnvironmentId: "workload_environment_1",
+            contractGeneration: 3,
+            now: at("2026-07-17T10:01:00Z"),
+        });
+        expect(result.ok).toBe(true);
+    });
+    it("fails closed across managed workload environments and stale contract generations", () => {
+        const signed = signAppSessionToken(managedContext, secret, {
+            now: at("2026-07-17T10:00:00Z"),
+        });
+        expect(verifyAppSessionToken(signed.token, secret, {
+            workloadEnvironmentId: "workload_environment_other",
+            contractGeneration: 3,
+            now: at("2026-07-17T10:01:00Z"),
+        })).toEqual({ ok: false, reason: "workload_environment_mismatch" });
+        expect(verifyAppSessionToken(signed.token, secret, {
+            workloadEnvironmentId: "workload_environment_1",
+            contractGeneration: 4,
+            now: at("2026-07-17T10:01:00Z"),
+        })).toEqual({ ok: false, reason: "contract_generation_mismatch" });
+    });
+    it("supports independent app contract generations in one workload environment", () => {
+        const first = signAppSessionToken({ ...managedContext, appId: "app_1", contractGeneration: 2 }, secret, { now: at("2026-07-17T10:00:00Z") });
+        const second = signAppSessionToken({ ...managedContext, appId: "app_2", contractGeneration: 9 }, secret, { now: at("2026-07-17T10:00:00Z") });
+        expect(verifyAppSessionToken(first.token, secret, {
+            audience: "app_1",
+            workloadEnvironmentId: "workload_environment_1",
+            contractGeneration: 2,
+            now: at("2026-07-17T10:01:00Z"),
+        }).ok).toBe(true);
+        expect(verifyAppSessionToken(second.token, secret, {
+            audience: "app_2",
+            workloadEnvironmentId: "workload_environment_1",
+            contractGeneration: 9,
+            now: at("2026-07-17T10:01:00Z"),
+        }).ok).toBe(true);
+    });
     it("rejects a tampered signature", () => {
         const signed = signAppSessionToken(context, secret, { now: at("2026-07-17T10:00:00Z") });
         const tampered = `${signed.token.slice(0, -2)}xy`;

package/dist/voyant.js

@@ -1,6 +1,7 @@
-import { defineModule, requirePort } from "@voyant-travel/core/project";
+import { defineModule, providePort, requirePort } from "@voyant-travel/core/project";
 import { customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntimePort, } from "@voyant-travel/core/runtime-port";
 import { financeAppApiRuntimePort } from "@voyant-travel/finance-contracts/runtime-port";
+import { appsManagedAuthRuntimePort } from "./runtime-port.js";
 const appsAdminRuntime = {
     entry: "@voyant-travel/apps-react/admin",
     export: "createSelectedAppsAdminExtension",
@@ -29,7 +30,11 @@ export const appsVoyantModule = defineModule({
             cardinality: "many",
         }),
         requirePort(financeAppApiRuntimePort, { optional: true }),
+        requirePort(appsManagedAuthRuntimePort, { optional: true }),
     ],
+    provides: {
+        ports: [providePort(appsManagedAuthRuntimePort)],
+    },
     api: [
         {
             id: "@voyant-travel/apps#api.admin",
@@ -56,6 +61,27 @@ export const appsVoyantModule = defineModule({
             source: "./migrations",
         },
     ],
+    config: [
+        {
+            id: "@voyant-travel/apps#config.runtime-audience",
+            key: "VOYANT_APP_RUNTIME_AUDIENCE",
+            required: false,
+        },
+        {
+            id: "@voyant-travel/apps#config.session-token-ttl-seconds",
+            key: "VOYANT_APP_SESSION_TOKEN_TTL_SECONDS",
+            required: false,
+        },
+    ],
+    secrets: [
+        {
+            id: "@voyant-travel/apps#secret.session-token-signing-secret",
+            key: "VOYANT_APP_SESSION_TOKEN_SIGNING_SECRET",
+            required: false,
+            description: "Signing material for short-lived remote extension session tokens.",
+            rotation: "replace-only",
+        },
+    ],
     events: [
         {
             id: "@voyant-travel/apps#event.installation-active",
@@ -300,6 +326,74 @@ export const appsVoyantModule = defineModule({
                 ],
                 wildcard: "explicit-resource",
             },
+            {
+                id: "@voyant-travel/apps#access.finance-document-artifacts",
+                resource: "finance-document-artifacts",
+                label: "Finance document artifacts",
+                description: "Attach private provider-generated renditions to finance documents.",
+                remoteSafe: true,
+                actions: [
+                    {
+                        action: "write",
+                        label: "Attach finance document artifacts",
+                        description: "Upload and bind a bounded provider-generated finance document PDF.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                ],
+                wildcard: "explicit-resource",
+            },
+            {
+                id: "@voyant-travel/apps#access.finance-external-sync",
+                resource: "finance-external-sync",
+                label: "Finance external synchronization",
+                description: "Report provider-neutral synchronization outcomes for finance documents.",
+                remoteSafe: true,
+                actions: [
+                    {
+                        action: "write",
+                        label: "Report finance synchronization",
+                        description: "Record ordered success, retryable-failure, or terminal-failure state.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                ],
+                wildcard: "explicit-resource",
+            },
+            {
+                id: "@voyant-travel/apps#access.finance-external-lifecycle",
+                resource: "finance-external-lifecycle",
+                label: "Finance external lifecycle",
+                description: "Report provider-neutral lifecycle facts for finance documents.",
+                remoteSafe: true,
+                actions: [
+                    {
+                        action: "write",
+                        label: "Report finance lifecycle",
+                        description: "Record an ordered conversion or void observation.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                ],
+                wildcard: "explicit-resource",
+            },
+            {
+                id: "@voyant-travel/apps#access.finance-settlement-observations",
+                resource: "finance-settlement-observations",
+                label: "Finance settlement observations",
+                description: "Report provider-neutral settlement evidence without creating payments.",
+                remoteSafe: true,
+                actions: [
+                    {
+                        action: "write",
+                        label: "Report settlement observations",
+                        description: "Record ordered partial or paid observations and payment identifiers.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                ],
+                wildcard: "explicit-resource",
+            },
             {
                 id: "@voyant-travel/apps#access.apps",
                 resource: "apps",

package/migrations/20260718205748_managed_installation_binding.sql

@@ -0,0 +1,16 @@
+ALTER TABLE "app_installations" ADD COLUMN "workload_environment_id" text;--> statement-breakpoint
+ALTER TABLE "app_installations" ADD COLUMN "contract_generation" integer;--> statement-breakpoint
+ALTER TABLE "app_access_credentials" ADD COLUMN "workload_environment_id" text;--> statement-breakpoint
+ALTER TABLE "app_access_credentials" ADD COLUMN "contract_generation" integer;--> statement-breakpoint
+ALTER TABLE "app_oauth_authorization_codes" ADD COLUMN "workload_environment_id" text;--> statement-breakpoint
+ALTER TABLE "app_oauth_authorization_codes" ADD COLUMN "contract_generation" integer;--> statement-breakpoint
+ALTER TABLE "app_oauth_refresh_tokens" ADD COLUMN "workload_environment_id" text;--> statement-breakpoint
+ALTER TABLE "app_oauth_refresh_tokens" ADD COLUMN "contract_generation" integer;--> statement-breakpoint
+ALTER TABLE "app_session_tokens" ADD COLUMN "workload_environment_id" text;--> statement-breakpoint
+ALTER TABLE "app_session_tokens" ADD COLUMN "contract_generation" integer;--> statement-breakpoint
+ALTER TABLE "app_installations" ADD CONSTRAINT "app_installations_managed_binding_complete" CHECK (("workload_environment_id" IS NULL AND "contract_generation" IS NULL) OR ("workload_environment_id" IS NOT NULL AND "contract_generation" > 0));--> statement-breakpoint
+ALTER TABLE "app_access_credentials" ADD CONSTRAINT "app_access_credentials_managed_binding_complete" CHECK (("workload_environment_id" IS NULL AND "contract_generation" IS NULL) OR ("workload_environment_id" IS NOT NULL AND "contract_generation" > 0));--> statement-breakpoint
+ALTER TABLE "app_oauth_authorization_codes" ADD CONSTRAINT "app_oauth_codes_managed_binding_complete" CHECK (("workload_environment_id" IS NULL AND "contract_generation" IS NULL) OR ("workload_environment_id" IS NOT NULL AND "contract_generation" > 0));--> statement-breakpoint
+ALTER TABLE "app_oauth_refresh_tokens" ADD CONSTRAINT "app_oauth_refresh_tokens_managed_binding_complete" CHECK (("workload_environment_id" IS NULL AND "contract_generation" IS NULL) OR ("workload_environment_id" IS NOT NULL AND "contract_generation" > 0));--> statement-breakpoint
+ALTER TABLE "app_session_tokens" ADD CONSTRAINT "app_session_tokens_managed_binding_complete" CHECK (("workload_environment_id" IS NULL AND "contract_generation" IS NULL) OR ("workload_environment_id" IS NOT NULL AND "contract_generation" > 0));--> statement-breakpoint
+CREATE UNIQUE INDEX "uidx_app_installations_workload_environment_app" ON "app_installations" USING btree ("workload_environment_id","app_id") WHERE "workload_environment_id" IS NOT NULL;

package/migrations/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1784300400000,
       "tag": "20260717150000_app_session_tokens",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1784397468000,
+      "tag": "20260718205748_managed_installation_binding",
+      "breakpoints": true
     }
   ]
-}
+}