@voyant-travel/apps 0.7.0 → 0.8.0

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,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/apps",
-  "version": "0.7.0",
+  "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,10 +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"
   },