@voyant-travel/apps 0.6.3 → 0.8.0

package/dist/runtime-port.d.ts

@@ -0,0 +1,8 @@
+export interface AppsManagedAuthRuntime {
+    /** Stable audience shared by authorization, installations, and session tokens. */
+    runtimeAudience: string;
+    /** 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,22 @@
+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 (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/session-token-service.d.ts

@@ -15,6 +15,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;
 }

package/dist/session-token-service.js

@@ -13,7 +13,7 @@
  * 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) {
@@ -25,6 +25,7 @@ export function createAppSessionTokenService(options) {
             installationId: installation.id,
             deploymentId: installation.deploymentId,
             viewerId: input.viewerId,
+            viewerScopes: input.viewerScopes ?? [],
             entity: input.entity ?? null,
             slot: input.slot ?? null,
         };
@@ -63,37 +64,53 @@ 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);
+            if (installation.appId !== claims.aud || installation.deploymentId !== claims.deploymentId) {
+                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), 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 };
 }
+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,157 @@
+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() {
+    const installation = {
+        id: "inst_1",
+        appId: "app_1",
+        releaseId: "rel_1",
+        deploymentId: "dep_1",
+        status: "active",
+        namespace: "app--one",
+    };
+    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();
+    });
+});

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. */
@@ -21,6 +21,8 @@ export interface AppSessionTokenContext {
     deploymentId: string;
     /** 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;
 }
@@ -35,6 +37,8 @@ export interface AppSessionTokenClaims {
     deploymentId: string;
     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. */

package/dist/session-token.test.js

@@ -6,6 +6,7 @@ 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",
 };
@@ -27,6 +28,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", () => {

package/dist/voyant.js

@@ -1,5 +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",
@@ -27,7 +29,12 @@ export const appsVoyantModule = defineModule({
             optional: true,
             cardinality: "many",
         }),
+        requirePort(financeAppApiRuntimePort, { optional: true }),
+        requirePort(appsManagedAuthRuntimePort, { optional: true }),
     ],
+    provides: {
+        ports: [providePort(appsManagedAuthRuntimePort)],
+    },
     api: [
         {
             id: "@voyant-travel/apps#api.admin",
@@ -54,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",
@@ -259,6 +287,113 @@ export const appsVoyantModule = defineModule({
                 ],
                 wildcard: "explicit-resource",
             },
+            {
+                id: "@voyant-travel/apps#access.finance-external-references",
+                resource: "finance-external-references",
+                label: "Finance external references",
+                description: "Read and record provider-owned finance document references.",
+                remoteSafe: true,
+                actions: [
+                    {
+                        action: "read",
+                        label: "Read external references",
+                        description: "Read the app provider's reference for a finance document.",
+                    },
+                    {
+                        action: "write",
+                        label: "Write external references",
+                        description: "Idempotently record the app provider's finance document reference.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                ],
+                wildcard: "explicit-resource",
+            },
+            {
+                id: "@voyant-travel/apps#access.finance-external-allocation",
+                resource: "finance-external-allocation",
+                label: "External finance number allocation",
+                description: "Write a provider-owned number to a pending finance document.",
+                remoteSafe: true,
+                actions: [
+                    {
+                        action: "write",
+                        label: "Allocate external finance number",
+                        description: "Atomically finalize a pending provider-owned document number.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                ],
+                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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/apps",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -89,6 +89,11 @@
       "import": "./dist/runtime-contributor.js",
       "default": "./dist/runtime-contributor.js"
     },
+    "./runtime-port": {
+      "types": "./dist/runtime-port.d.ts",
+      "import": "./dist/runtime-port.js",
+      "default": "./dist/runtime-port.js"
+    },
     "./schema": {
       "types": "./dist/schema.d.ts",
       "import": "./dist/schema.js",
@@ -124,9 +129,10 @@
     "@voyant-travel/admin": "^0.127.0",
     "@voyant-travel/admin-extension-sdk": "^0.2.0",
     "@voyant-travel/core": "^0.127.0",
-    "@voyant-travel/custom-fields": "^0.2.3",
+    "@voyant-travel/custom-fields": "^0.2.4",
+    "@voyant-travel/finance-contracts": "^0.107.0",
     "@voyant-travel/db": "^0.114.13",
-    "@voyant-travel/hono": "^0.128.6",
+    "@voyant-travel/hono": "^0.129.0",
     "@voyant-travel/types": "^0.109.4",
     "@voyant-travel/webhook-delivery": "^0.4.2"
   },