@voyant-travel/apps 0.4.0 → 0.6.0

package/dist/session-token.d.ts

@@ -0,0 +1,82 @@
+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";
+/** 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. */
+export declare const APP_SESSION_TOKEN_ISSUER = "voyant:apps:session-token";
+/** The domain record a slot/detail surface is scoped to (null on list surfaces). */
+export interface AppSessionTokenEntity {
+    type: string;
+    id: string;
+}
+/** The context the host binds a session token to at issuance time. */
+export interface AppSessionTokenContext {
+    /** App registration id — becomes the token audience. */
+    appId: string;
+    installationId: string;
+    deploymentId: string;
+    /** The admin viewer the token acts on behalf of. */
+    viewerId: string;
+    entity?: AppSessionTokenEntity | null;
+    slot?: string | null;
+}
+/** The decoded, verified claim set. */
+export interface AppSessionTokenClaims {
+    iss: string;
+    /** Audience — the app registration id the token was minted for. */
+    aud: string;
+    /** Subject — the admin viewer id. */
+    sub: string;
+    installationId: string;
+    deploymentId: string;
+    entity: AppSessionTokenEntity | null;
+    slot: string | null;
+    iat: number;
+    exp: number;
+    /** Unique token id; the exchange store enforces single use by this value. */
+    jti: string;
+}
+export interface SignAppSessionTokenOptions {
+    now?: () => Date;
+    ttlSeconds?: number;
+    /** Override the generated token id (tests/replay fixtures). */
+    jti?: string;
+}
+export interface SignedAppSessionToken {
+    token: string;
+    claims: AppSessionTokenClaims;
+    /** Expiry as epoch milliseconds, convenient for the protocol payload. */
+    expiresAtMs: number;
+}
+/**
+ * Mint a signed admin session token for the given context. The returned
+ * `claims.jti` should be recorded by the caller so the exchange can enforce
+ * single use.
+ */
+export declare function signAppSessionToken(context: AppSessionTokenContext, secret: string, options?: SignAppSessionTokenOptions): SignedAppSessionToken;
+export interface VerifyAppSessionTokenExpectations {
+    /** Reject unless `aud` equals this app id. */
+    audience?: string;
+    /** Reject unless `deploymentId` equals this deployment. */
+    deploymentId?: string;
+    now?: () => Date;
+}
+export type AppSessionTokenVerifyResult = {
+    ok: true;
+    claims: AppSessionTokenClaims;
+} | {
+    ok: false;
+    reason: AppSessionTokenRejectReason;
+};
+export type AppSessionTokenRejectReason = "malformed" | "bad_signature" | "expired" | "wrong_issuer" | "audience_mismatch" | "deployment_mismatch";
+/**
+ * Verify a session token's signature, issuer, expiry, and (when supplied)
+ * audience and deployment binding. Returns the decoded claims on success or a
+ * machine-readable rejection reason. This does NOT enforce single use — the
+ * exchange service consumes `claims.jti` to reject replay.
+ */
+export declare function verifyAppSessionToken(token: string, secret: string, expectations?: VerifyAppSessionTokenExpectations): AppSessionTokenVerifyResult;

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

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

package/dist/session-token.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { APP_SESSION_TOKEN_PREFIX, signAppSessionToken, verifyAppSessionToken, } from "./session-token.js";
+const secret = "test-deployment-session-secret-value-000000000000";
+const context = {
+    appId: "app_1",
+    installationId: "apin_1",
+    deploymentId: "dep_1",
+    viewerId: "usr_1",
+    entity: { type: "booking", id: "book_1" },
+    slot: "booking.details.header",
+};
+const at = (iso) => () => new Date(iso);
+describe("app session token", () => {
+    it("round-trips claims, binds context, and carries a unique id", () => {
+        const signed = signAppSessionToken(context, secret, { now: at("2026-07-17T10:00:00Z") });
+        expect(signed.token.startsWith(APP_SESSION_TOKEN_PREFIX)).toBe(true);
+        const result = verifyAppSessionToken(signed.token, secret, {
+            audience: "app_1",
+            deploymentId: "dep_1",
+            now: at("2026-07-17T10:01:00Z"),
+        });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.claims.aud).toBe("app_1");
+        expect(result.claims.sub).toBe("usr_1");
+        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.jti).toMatch(/^st_/);
+    });
+    it("mints a distinct jti per issuance", () => {
+        const a = signAppSessionToken(context, secret, { now: at("2026-07-17T10:00:00Z") });
+        const b = signAppSessionToken(context, secret, { now: at("2026-07-17T10:00:00Z") });
+        expect(a.claims.jti).not.toBe(b.claims.jti);
+    });
+    it("rejects a token past its short expiry", () => {
+        const signed = signAppSessionToken(context, secret, {
+            now: at("2026-07-17T10:00:00Z"),
+            ttlSeconds: 120,
+        });
+        const result = verifyAppSessionToken(signed.token, secret, {
+            now: at("2026-07-17T10:03:00Z"),
+        });
+        expect(result).toEqual({ ok: false, reason: "expired" });
+    });
+    it("fails closed on audience mismatch (confused deputy)", () => {
+        const signed = signAppSessionToken(context, secret, { now: at("2026-07-17T10:00:00Z") });
+        const result = verifyAppSessionToken(signed.token, secret, {
+            audience: "app_other",
+            now: at("2026-07-17T10:01:00Z"),
+        });
+        expect(result).toEqual({ ok: false, reason: "audience_mismatch" });
+    });
+    it("fails closed on deployment mismatch", () => {
+        const signed = signAppSessionToken(context, secret, { now: at("2026-07-17T10:00:00Z") });
+        const result = verifyAppSessionToken(signed.token, secret, {
+            deploymentId: "dep_other",
+            now: at("2026-07-17T10:01:00Z"),
+        });
+        expect(result).toEqual({ ok: false, reason: "deployment_mismatch" });
+    });
+    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`;
+        const result = verifyAppSessionToken(tampered, secret, { now: at("2026-07-17T10:01:00Z") });
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(["bad_signature", "malformed"]).toContain(result.reason);
+    });
+    it("rejects a token signed with a different secret (context-separated key)", () => {
+        const signed = signAppSessionToken(context, secret, { now: at("2026-07-17T10:00:00Z") });
+        const result = verifyAppSessionToken(signed.token, `${secret}-rotated`, {
+            now: at("2026-07-17T10:01:00Z"),
+        });
+        expect(result).toEqual({ ok: false, reason: "bad_signature" });
+    });
+    it("rejects a non-session-token string", () => {
+        expect(verifyAppSessionToken("nope", secret)).toEqual({ ok: false, reason: "malformed" });
+        expect(verifyAppSessionToken("vsess_only.two", secret)).toEqual({
+            ok: false,
+            reason: "malformed",
+        });
+    });
+    it("normalizes a list-surface (no entity) context", () => {
+        const signed = signAppSessionToken({ ...context, entity: null, slot: null }, secret, {
+            now: at("2026-07-17T10:00:00Z"),
+        });
+        const result = verifyAppSessionToken(signed.token, secret, { now: at("2026-07-17T10:01:00Z") });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.claims.entity).toBeNull();
+        expect(result.claims.slot).toBeNull();
+    });
+});

package/dist/voyant.js

@@ -1,5 +1,9 @@
 import { defineModule, requirePort } from "@voyant-travel/core/project";
 import { customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntimePort, } from "@voyant-travel/core/runtime-port";
+const appsAdminRuntime = {
+    entry: "@voyant-travel/apps-react/admin",
+    export: "createSelectedAppsAdminExtension",
+};
 const appInstallationLifecyclePayloadSchema = {
     type: "object",
     additionalProperties: false,
@@ -120,8 +124,11 @@ export const appsVoyantModule = defineModule({
                 wildcard: "explicit-resource",
             },
             {
-                id: "@voyant-travel/apps#access.webhooks",
-                resource: "webhooks",
+                id: "@voyant-travel/apps#access.app-webhooks",
+                // Namespaced `app-webhooks` (not `webhooks`) to avoid a duplicate
+                // access-resource authority with @voyant-travel/workflow-runs, which
+                // owns the deployment `webhooks` resource.
+                resource: "app-webhooks",
                 label: "App webhooks",
                 description: "Read webhook health and request replay.",
                 remoteSafe: true,
@@ -189,6 +196,49 @@ export const appsVoyantModule = defineModule({
             },
         ],
     },
+    admin: {
+        compositionOrder: 170,
+        runtime: appsAdminRuntime,
+        copy: [
+            {
+                id: "@voyant-travel/apps#admin.copy",
+                namespace: "apps.admin",
+                fallbackLocale: "en",
+                runtime: {
+                    entry: "@voyant-travel/apps-react/i18n",
+                    export: "appsUiMessageDefinitions",
+                },
+            },
+        ],
+        routes: [
+            {
+                id: "@voyant-travel/apps#admin.route.installed",
+                path: "/apps",
+                requiredScopes: ["apps:read"],
+                runtime: appsAdminRuntime,
+            },
+            {
+                id: "@voyant-travel/apps#admin.route.developer",
+                path: "/apps/developer",
+                requiredScopes: ["apps:write"],
+                runtime: appsAdminRuntime,
+            },
+        ],
+        nav: [
+            {
+                id: "@voyant-travel/apps#admin.nav.installed",
+                routeId: "@voyant-travel/apps#admin.route.installed",
+                label: { namespace: "apps.admin", key: "navigation.title" },
+                order: 170,
+            },
+            {
+                id: "@voyant-travel/apps#admin.nav.developer",
+                routeId: "@voyant-travel/apps#admin.route.developer",
+                label: { namespace: "apps.admin", key: "navigation.developerTitle" },
+                order: 171,
+            },
+        ],
+    },
     lifecycle: { uninstall: { default: "retain-data", purge: "not-supported" } },
     meta: {
         ownership: "package",

package/migrations/20260717150000_app_session_tokens.sql

@@ -0,0 +1,18 @@
+CREATE TABLE "app_session_tokens" (
+	"id" text PRIMARY KEY NOT NULL,
+	"installation_id" text NOT NULL,
+	"app_id" text NOT NULL,
+	"deployment_id" text NOT NULL,
+	"jti" text NOT NULL,
+	"viewer_id" text NOT NULL,
+	"entity_type" text,
+	"entity_id" text,
+	"slot" text,
+	"issued_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"consumed_at" timestamp with time zone,
+	"consumed_by_actor_id" text
+);--> statement-breakpoint
+ALTER TABLE "app_session_tokens" ADD CONSTRAINT "app_session_tokens_installation_id_app_installations_id_fk" FOREIGN KEY ("installation_id") REFERENCES "public"."app_installations"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "uidx_app_session_tokens_jti" ON "app_session_tokens" USING btree ("jti");--> statement-breakpoint
+CREATE INDEX "idx_app_session_tokens_installation" ON "app_session_tokens" USING btree ("installation_id","expires_at");

package/migrations/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1784298600000,
       "tag": "20260717143000_app_oauth_authorization",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1784300400000,
+      "tag": "20260717150000_app_session_tokens",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/apps",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -49,11 +49,21 @@
       "import": "./dist/consent.js",
       "default": "./dist/consent.js"
     },
+    "./extension-resolution": {
+      "types": "./dist/extension-resolution.d.ts",
+      "import": "./dist/extension-resolution.js",
+      "default": "./dist/extension-resolution.js"
+    },
     "./ingestion": {
       "types": "./dist/ingestion.d.ts",
       "import": "./dist/ingestion.js",
       "default": "./dist/ingestion.js"
     },
+    "./locale-resolution": {
+      "types": "./dist/locale-resolution.d.ts",
+      "import": "./dist/locale-resolution.js",
+      "default": "./dist/locale-resolution.js"
+    },
     "./installation-service": {
       "types": "./dist/installation-service.d.ts",
       "import": "./dist/installation-service.js",
@@ -84,6 +94,16 @@
       "import": "./dist/service.js",
       "default": "./dist/service.js"
     },
+    "./session-token": {
+      "types": "./dist/session-token.d.ts",
+      "import": "./dist/session-token.js",
+      "default": "./dist/session-token.js"
+    },
+    "./session-token-service": {
+      "types": "./dist/session-token-service.d.ts",
+      "import": "./dist/session-token-service.js",
+      "default": "./dist/session-token-service.js"
+    },
     "./voyant": {
       "types": "./dist/voyant.d.ts",
       "import": "./dist/voyant.js",
@@ -95,8 +115,8 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.27",
     "zod": "^4.4.3",
-    "@voyant-travel/admin": "^0.126.2",
-    "@voyant-travel/admin-extension-sdk": "^0.1.1",
+    "@voyant-travel/admin": "^0.127.0",
+    "@voyant-travel/admin-extension-sdk": "^0.2.0",
     "@voyant-travel/core": "^0.125.2",
     "@voyant-travel/custom-fields": "^0.2.1",
     "@voyant-travel/db": "^0.114.10",