@voyant-travel/apps 0.4.0 → 0.5.0

package/dist/locale-resolution.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { createHostLabelResolver, resolveAppLocale, resolveTextDirection, } from "./locale-resolution.js";
+describe("resolveAppLocale", () => {
+    const declaration = { defaultLocale: "en", supportedLocales: ["en", "pt", "pt-BR", "ar"] };
+    it("prefers an exact match", () => {
+        expect(resolveAppLocale("pt-BR", declaration).appLocale).toBe("pt-BR");
+    });
+    it("falls back to a language match when the exact tag is absent", () => {
+        expect(resolveAppLocale("pt-PT", declaration).appLocale).toBe("pt");
+    });
+    it("is case-insensitive on the requested tag", () => {
+        expect(resolveAppLocale("PT-br", declaration).appLocale).toBe("pt-BR");
+    });
+    it("falls back to the declared default when nothing matches", () => {
+        expect(resolveAppLocale("de-DE", declaration).appLocale).toBe("en");
+    });
+    it("resolves text direction from the resolved locale", () => {
+        expect(resolveAppLocale("ar", declaration).direction).toBe("rtl");
+        expect(resolveAppLocale("en", declaration).direction).toBe("ltr");
+    });
+});
+describe("resolveTextDirection", () => {
+    it("marks RTL languages", () => {
+        expect(resolveTextDirection("he-IL")).toBe("rtl");
+        expect(resolveTextDirection("fa")).toBe("rtl");
+        expect(resolveTextDirection("en-US")).toBe("ltr");
+    });
+});
+describe("createHostLabelResolver", () => {
+    const rows = [
+        { locale: "en", surface: "extension", messageKey: "title", text: "Reports" },
+        { locale: "en", surface: "navigation", messageKey: "nav", text: "Reports" },
+        { locale: "pt", surface: "extension", messageKey: "title", text: "Relatórios" },
+    ];
+    it("resolves in the app locale first", () => {
+        const resolver = createHostLabelResolver(rows, "pt", "en");
+        expect(resolver.resolve("title")).toBe("Relatórios");
+    });
+    it("falls back to the default locale deterministically", () => {
+        const resolver = createHostLabelResolver(rows, "pt", "en");
+        // "nav" is missing in pt; falls back to en.
+        expect(resolver.resolve("nav", ["navigation"])).toBe("Reports");
+    });
+    it("returns null when no surface carries the key", () => {
+        const resolver = createHostLabelResolver(rows, "en", "en");
+        expect(resolver.resolve("missing")).toBeNull();
+    });
+});

package/dist/routes.d.ts

@@ -12,6 +12,15 @@ export interface AppsAdminRouteOptions extends AppsServiceOptions {
         accessCatalog: AccessCatalog;
         deploymentId: string;
     };
+    /**
+     * Enables the iframe session-token broker. Requires {@link oauth} for the
+     * deployment audience and the actor-token-exchange primitive. `secret` is the
+     * root secret the signing key is HKDF-derived from.
+     */
+    sessionToken?: {
+        secret: string;
+        ttlSeconds?: number;
+    };
 }
 export declare function createAppsAdminRoutes(options?: AppsAdminRouteOptions): Hono<Env, import("hono/types").BlankSchema, "/">;
 export {};

package/dist/routes.js

@@ -1,9 +1,10 @@
-import { parseJsonBody, parseQuery, RequestValidationError } from "@voyant-travel/hono";
+import { parseJsonBody, parseQuery, RequestValidationError, requireUserId, } from "@voyant-travel/hono";
 import { Hono } from "hono";
 import { z } from "zod";
-import { appCredentialRevocationSchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
+import { appCredentialRevocationSchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appSessionTokenExchangeSchema, appSessionTokenIssueSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
 import { createAppOAuthService } from "./oauth-service.js";
 import { createAppsService } from "./service.js";
+import { createAppSessionTokenService } from "./session-token-service.js";
 import { listAppWebhookHealth, replayAppWebhookDelivery } from "./webhook-delivery.js";
 const appIdParamSchema = z.object({ appId: z.string().min(1) });
 const installationIdParamSchema = z.object({ installationId: z.string().min(1) });
@@ -11,6 +12,14 @@ export function createAppsAdminRoutes(options = {}) {
     const routes = new Hono();
     const service = createAppsService(options);
     const oauth = options.oauth ? createAppOAuthService(options.oauth) : null;
+    const sessionTokens = oauth && options.oauth && options.sessionToken
+        ? createAppSessionTokenService({
+            secret: options.sessionToken.secret,
+            ttlSeconds: options.sessionToken.ttlSeconds,
+            deploymentId: options.oauth.deploymentId,
+            oauth,
+        })
+        : null;
     routes.get("/", async (c) => {
         const query = parseQuery(c, appListQuerySchema);
         return c.json(await service.list(c.get("db"), query), 200);
@@ -81,6 +90,38 @@ export function createAppsAdminRoutes(options = {}) {
         const result = await oauth.revokeInstallationCredentials(c.get("db"), body.installationId, body.actorId);
         return c.json(result, 200);
     });
+    // Staff-authenticated: the admin host requests a short-lived session token for
+    // the current viewer + entity/slot context. The viewer is taken from the
+    // authenticated session, never from the frame.
+    routes.post("/installations/:installationId/session-token", async (c) => {
+        if (!sessionTokens)
+            return c.json({ error: "App session tokens are not configured" }, 501);
+        const { installationId } = parseInstallationParams(c.req.param());
+        const viewerId = requireUserId(c);
+        const body = await parseJsonBody(c, appSessionTokenIssueSchema);
+        const issued = await sessionTokens.issue(c.get("db"), {
+            installationId,
+            viewerId,
+            entity: body.entity ?? null,
+            slot: body.slot ?? null,
+        });
+        return c.json({ data: issued }, 201);
+    });
+    // App-backend-facing: exchange a presented session token for online actor
+    // access. Client-authenticated; bounded by viewer ∩ app grants.
+    routes.post("/oauth/session-token/exchange", async (c) => {
+        if (!sessionTokens)
+            return c.json({ error: "App session tokens are not configured" }, 501);
+        const body = await parseJsonBody(c, appSessionTokenExchangeSchema);
+        const token = await sessionTokens.exchange(c.get("db"), {
+            token: body.session_token,
+            clientId: body.client_id,
+            clientSecret: body.client_secret,
+            viewerScopes: body.viewer_scopes,
+            contextualScopes: body.contextual_scopes,
+        });
+        return c.json(token, 200);
+    });
     routes.get("/:appId", async (c) => {
         const { appId } = parseParams(c.req.param());
         const app = await service.get(c.get("db"), appId);

package/dist/schema.d.ts

@@ -2928,6 +2928,241 @@ export declare const appAuditEvents: import("drizzle-orm/pg-core").PgTableWithCo
     };
     dialect: "pg";
 }>;
+/**
+ * Issued admin session tokens for iframe extensions. Each row is the durable
+ * record of one short-lived, single-use session token: it makes issuance and
+ * exchange auditable and provides the replay guard — a token's `jti` may be
+ * consumed at most once (unique index + a conditional update on `consumedAt`).
+ * The token bytes are never stored; only the signed claim identity.
+ */
+export declare const appSessionTokens: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "app_session_tokens";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "app_session_tokens";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        installationId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "installation_id";
+            tableName: "app_session_tokens";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        appId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "app_id";
+            tableName: "app_session_tokens";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deploymentId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "deployment_id";
+            tableName: "app_session_tokens";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        jti: import("drizzle-orm/pg-core").PgColumn<{
+            name: "jti";
+            tableName: "app_session_tokens";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        viewerId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "viewer_id";
+            tableName: "app_session_tokens";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        entityType: import("drizzle-orm/pg-core").PgColumn<{
+            name: "entity_type";
+            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;
+        }, {}, {}>;
+        entityId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "entity_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;
+        }, {}, {}>;
+        slot: import("drizzle-orm/pg-core").PgColumn<{
+            name: "slot";
+            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;
+        }, {}, {}>;
+        issuedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "issued_at";
+            tableName: "app_session_tokens";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        expiresAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "expires_at";
+            tableName: "app_session_tokens";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        consumedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "consumed_at";
+            tableName: "app_session_tokens";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        consumedByActorId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "consumed_by_actor_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;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 export type AppRegistration = typeof apps.$inferSelect;
 export type NewAppRegistration = typeof apps.$inferInsert;
 export type AppRelease = typeof appReleases.$inferSelect;
@@ -2935,3 +3170,5 @@ export type NewAppRelease = typeof appReleases.$inferInsert;
 export type AppInstallation = typeof appInstallations.$inferSelect;
 export type NewAppInstallation = typeof appInstallations.$inferInsert;
 export type AppAccessCredential = typeof appAccessCredentials.$inferSelect;
+export type AppSessionTokenRow = typeof appSessionTokens.$inferSelect;
+export type NewAppSessionTokenRow = typeof appSessionTokens.$inferInsert;

package/dist/schema.js

@@ -340,3 +340,30 @@ export const appAuditEvents = pgTable("app_audit_events", {
     index("idx_app_audit_events_installation").on(table.installationId, table.createdAt),
     index("idx_app_audit_events_app").on(table.appId, table.deploymentId, table.createdAt),
 ]);
+/**
+ * Issued admin session tokens for iframe extensions. Each row is the durable
+ * record of one short-lived, single-use session token: it makes issuance and
+ * exchange auditable and provides the replay guard — a token's `jti` may be
+ * consumed at most once (unique index + a conditional update on `consumedAt`).
+ * The token bytes are never stored; only the signed claim identity.
+ */
+export const appSessionTokens = pgTable("app_session_tokens", {
+    id: typeId("app_session_tokens"),
+    installationId: text("installation_id")
+        .notNull()
+        .references(() => appInstallations.id, { onDelete: "cascade" }),
+    appId: text("app_id").notNull(),
+    deploymentId: text("deployment_id").notNull(),
+    jti: text("jti").notNull(),
+    viewerId: text("viewer_id").notNull(),
+    entityType: text("entity_type"),
+    entityId: text("entity_id"),
+    slot: text("slot"),
+    issuedAt: timestamp("issued_at", { withTimezone: true }).notNull().defaultNow(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    consumedAt: timestamp("consumed_at", { withTimezone: true }),
+    consumedByActorId: text("consumed_by_actor_id"),
+}, (table) => [
+    uniqueIndex("uidx_app_session_tokens_jti").on(table.jti),
+    index("idx_app_session_tokens_installation").on(table.installationId, table.expiresAt),
+]);

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

@@ -0,0 +1,47 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { createAppOAuthService } from "./oauth-service.js";
+import { type AppSessionTokenEntity } from "./session-token.js";
+type AppOAuthService = ReturnType<typeof createAppOAuthService>;
+export interface AppSessionTokenServiceOptions {
+    /** Root secret; the signing key is HKDF-derived from it under a private context. */
+    secret: string;
+    /** The deployment audience the tokens are bound to. */
+    deploymentId: string;
+    /** OAuth service supplying the online actor-token-exchange primitive. */
+    oauth: AppOAuthService;
+    ttlSeconds?: number;
+    now?: () => Date;
+}
+export interface IssueAppSessionTokenInput {
+    installationId: string;
+    viewerId: string;
+    entity?: AppSessionTokenEntity | null;
+    slot?: string | null;
+}
+export interface IssuedAppSessionToken {
+    token: string;
+    tokenId: string;
+    expiresAtMs: number;
+}
+export interface ExchangeAppSessionTokenInput {
+    token: string;
+    /** Authenticating app client; must match the token audience (confused-deputy guard). */
+    clientId: string;
+    clientSecret?: string;
+    /** The viewer's current effective scopes; the online token is bounded by these. */
+    viewerScopes: readonly string[];
+    /** Optional further contextual narrowing (defaults to the app grants). */
+    contextualScopes?: readonly string[];
+}
+export declare function createAppSessionTokenService(options: AppSessionTokenServiceOptions): {
+    issue: (db: PostgresJsDatabase, input: IssueAppSessionTokenInput) => Promise<IssuedAppSessionToken>;
+    exchange: (db: PostgresJsDatabase, input: ExchangeAppSessionTokenInput) => Promise<{
+        refreshToken?: string | undefined;
+        accessToken: string;
+        tokenType: "Bearer";
+        expiresIn: number;
+        scope: string;
+        tokenMode: "offline" | "online";
+    }>;
+};
+export {};

package/dist/session-token-service.js

@@ -0,0 +1,127 @@
+/**
+ * Issuance, replay guard, and backend exchange for admin session tokens.
+ *
+ * The crypto lives in `session-token.ts`; this module binds it to the
+ * installation aggregate:
+ * - {@link issueAppSessionToken} mints a token for an active installation and
+ *   records the `jti` so it can be consumed exactly once.
+ * - {@link exchangeAppSessionToken} verifies a token an app backend presents,
+ *   consumes its `jti` (rejecting replay), and swaps it for online actor access
+ *   via the existing OAuth actor-token-exchange primitive — bounded by the
+ *   intersection of the app's grants and the viewer's scopes.
+ *
+ * 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 { 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 context = {
+            appId: installation.appId,
+            installationId: installation.id,
+            deploymentId: installation.deploymentId,
+            viewerId: input.viewerId,
+            entity: input.entity ?? null,
+            slot: input.slot ?? null,
+        };
+        const signed = signAppSessionToken(context, options.secret, {
+            now,
+            ttlSeconds: options.ttlSeconds,
+        });
+        await db.insert(appSessionTokens).values({
+            installationId: installation.id,
+            appId: installation.appId,
+            deploymentId: installation.deploymentId,
+            jti: signed.claims.jti,
+            viewerId: input.viewerId,
+            entityType: signed.claims.entity?.type ?? null,
+            entityId: signed.claims.entity?.id ?? null,
+            slot: signed.claims.slot,
+            expiresAt: new Date(signed.claims.exp * 1000),
+        });
+        await audit(db, installation, input.viewerId, "session-token.issued", {
+            jti: signed.claims.jti,
+            slot: signed.claims.slot,
+            entityType: signed.claims.entity?.type ?? null,
+        });
+        return { token: signed.token, tokenId: signed.claims.jti, expiresAtMs: signed.expiresAtMs };
+    }
+    async function exchange(db, input) {
+        const verified = verifyAppSessionToken(input.token, options.secret, {
+            deploymentId: options.deploymentId,
+            audience: input.clientId,
+            now,
+        });
+        if (!verified.ok) {
+            throw new ApiHttpError("Session token rejected", {
+                status: 401,
+                code: `app_session_token_${verified.reason}`,
+            });
+        }
+        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",
+            });
+        }
+        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,
+        });
+        return tokens;
+    }
+    return { issue, exchange };
+}
+async function requireActiveInstallation(db, installationId) {
+    const [installation] = await db
+        .select()
+        .from(appInstallations)
+        .where(eq(appInstallations.id, installationId))
+        .limit(1);
+    if (!installation) {
+        throw new ApiHttpError("App installation not found", {
+            status: 404,
+            code: "app_installation_not_found",
+        });
+    }
+    if (installation.status !== "active") {
+        throw new ApiHttpError("App installation is not active", {
+            status: 403,
+            code: "app_installation_not_active",
+        });
+    }
+    return installation;
+}
+async function audit(db, installation, actorId, action, details) {
+    await db.insert(appAuditEvents).values({
+        installationId: installation.id,
+        appId: installation.appId,
+        deploymentId: installation.deploymentId,
+        actorId,
+        kind: "token",
+        action,
+        details,
+    });
+}

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 {};