@voyant-travel/apps 0.9.1 → 0.10.1

package/dist/marketplace-acquisition.js

@@ -0,0 +1,410 @@
+import { randomBytes } from "node:crypto";
+import { ApiHttpError } from "@voyant-travel/hono";
+import { and, eq, isNull } from "drizzle-orm";
+import { z } from "zod";
+import { canonicalJsonStringify, compileAppManifest, } from "./compiler.js";
+import { appCredentials, appInstallations, appRedirectUris, appReleaseArtifacts, appReleaseLocalizations, appReleases, apps, } from "./schema.js";
+const httpsUrlSchema = z
+    .string()
+    .url()
+    .refine((value) => new URL(value).protocol === "https:", "URL must use HTTPS.");
+/**
+ * Provider-neutral, host-verified input to the deployment-local app registry.
+ * A managed host adapts its private catalog model to this closed contract only
+ * after it has authenticated the deployment and verified artifact provenance.
+ */
+export const hostVerifiedMarketplaceAcquisitionSchema = z
+    .object({
+    schemaVersion: z.literal("voyant.runtime-marketplace-acquisition.v1"),
+    acquisitionId: z.string().trim().min(1).max(200),
+    app: z
+        .object({
+        id: z.string().trim().min(1).max(200),
+        ownerId: z.string().trim().min(1).max(200),
+        displayName: z.string().trim().min(1).max(120),
+        slug: z
+            .string()
+            .trim()
+            .regex(/^[a-z0-9][a-z0-9-]{0,78}[a-z0-9]$/),
+        redirectUris: z.array(httpsUrlSchema).max(20),
+        oauthClient: z
+            .object({
+            method: z.literal("client_secret_post"),
+            /** Verifier for a high-entropy publisher-held secret; never the raw secret. */
+            secretSha256: z.string().regex(/^[a-f0-9]{64}$/),
+        })
+            .strict(),
+    })
+        .strict(),
+    release: z
+        .object({
+        id: z.string().trim().min(1).max(200),
+        manifest: z.unknown(),
+        digest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+        signature: z.string().trim().min(1).max(16_384).optional(),
+        provenance: z.record(z.string(), z.unknown()),
+        assetInventory: z.record(z.string(), z.unknown()).default({ files: [] }),
+    })
+        .strict(),
+})
+    .strict();
+export const resolveMarketplaceInstallIntentSchema = z
+    .object({ intent: z.string().trim().min(1).max(2048) })
+    .strict();
+export const marketplaceInstallIntentResultSchema = z.object({
+    data: z
+        .object({
+        appId: z.string(),
+        releaseId: z.string(),
+        acquisitionId: z.string(),
+        created: z.boolean(),
+    })
+        .strict(),
+});
+export const marketplaceSetupHandoffResultSchema = z.object({
+    data: z.object({ redirectUrl: httpsUrlSchema }).strict(),
+});
+export const MARKETPLACE_SETUP_ASSERTION_TYPE = "voyant-marketplace-setup+jwt";
+/** Claims signed by the managed host and verified by the remote app backend. */
+export const marketplaceSetupAssertionClaimsSchema = z
+    .object({
+    schemaVersion: z.literal("voyant.marketplace-setup-assertion.v1"),
+    iss: z.string().trim().min(1),
+    aud: z.string().trim().min(1),
+    sub: z.string().trim().min(1),
+    jti: z.string().trim().min(1).max(200),
+    iat: z.number().int().nonnegative(),
+    exp: z.number().int().positive(),
+    installationId: z.string().trim().min(1).max(200),
+    appId: z.string().trim().min(1).max(200),
+    releaseId: z.string().trim().min(1).max(200),
+    authorizationUrl: httpsUrlSchema,
+    tokenUrl: httpsUrlSchema,
+    redirectUri: httpsUrlSchema,
+})
+    .strict()
+    .superRefine((claims, context) => {
+    if (claims.sub !== claims.installationId) {
+        context.addIssue({
+            code: "custom",
+            path: ["sub"],
+            message: "Setup assertion subject must equal installationId.",
+        });
+    }
+    if (claims.aud !== claims.appId) {
+        context.addIssue({
+            code: "custom",
+            path: ["aud"],
+            message: "Setup assertion audience must equal appId.",
+        });
+    }
+    if (claims.exp <= claims.iat || claims.exp - claims.iat > 300) {
+        context.addIssue({
+            code: "custom",
+            path: ["exp"],
+            message: "Setup assertion lifetime must be positive and no longer than 300 seconds.",
+        });
+    }
+});
+export function createMarketplaceAcquisitionService(options) {
+    return {
+        async resolveAndAcquire(db, input) {
+            const raw = await options.resolveAcquisitionIntent({ intent: input.intent });
+            if (!raw) {
+                throw new ApiHttpError("Marketplace install intent was not found or has expired", {
+                    status: 404,
+                    code: "app_marketplace_intent_unavailable",
+                });
+            }
+            const acquisition = hostVerifiedMarketplaceAcquisitionSchema.parse(raw);
+            const compiled = compileAppManifest(acquisition.release.manifest, options);
+            if (compiled.digest !== acquisition.release.digest) {
+                throw new ApiHttpError("Marketplace release digest verification failed", {
+                    status: 409,
+                    code: "app_marketplace_digest_mismatch",
+                });
+            }
+            return db.transaction(async (tx) => {
+                const app = await acquireApp(tx, acquisition, input.actorId);
+                await reconcileOAuthClient(tx, app.id, acquisition.app.oauthClient.secretSha256);
+                await reconcileRedirectUris(tx, app.id, acquisition.app.redirectUris);
+                const release = await acquireRelease(tx, acquisition, compiled, input.actorId);
+                return {
+                    appId: app.id,
+                    releaseId: release.id,
+                    acquisitionId: acquisition.acquisitionId,
+                    created: release.created,
+                };
+            });
+        },
+        async createSetupHandoff(db, installationId) {
+            const [row] = await db
+                .select({
+                installationId: appInstallations.id,
+                appId: apps.id,
+                releaseId: appReleases.id,
+                distribution: apps.distribution,
+                status: appInstallations.status,
+                normalizedRecord: appReleases.normalizedRecord,
+            })
+                .from(appInstallations)
+                .innerJoin(apps, eq(apps.id, appInstallations.appId))
+                .innerJoin(appReleases, eq(appReleases.id, appInstallations.releaseId))
+                .where(eq(appInstallations.id, installationId))
+                .limit(1);
+            if (row?.distribution !== "marketplace" || row.status !== "active") {
+                throw new ApiHttpError("Active Marketplace installation not found", {
+                    status: 404,
+                    code: "app_marketplace_installation_not_found",
+                });
+            }
+            const setupUrl = readSetupUrl(row.normalizedRecord);
+            if (!setupUrl) {
+                throw new ApiHttpError("This app release has no setup handoff", {
+                    status: 409,
+                    code: "app_marketplace_setup_unavailable",
+                });
+            }
+            const handoff = await options.createSetupHandoff({
+                installationId: row.installationId,
+                appId: row.appId,
+                releaseId: row.releaseId,
+            });
+            const redirectUrl = parseTrustedSetupRedirect(handoff.redirectUrl, setupUrl);
+            return { redirectUrl };
+        },
+    };
+}
+async function acquireApp(db, acquisition, actorId) {
+    const existing = await selectAppForUpdate(db, acquisition.app.id);
+    if (existing) {
+        if (existing.distribution !== "marketplace" || existing.ownerId !== acquisition.app.ownerId) {
+            throw immutableIdentityConflict("Marketplace app identity conflicts with the local registry");
+        }
+        const [updated] = await db
+            .update(apps)
+            .set({
+            displayName: acquisition.app.displayName,
+            slug: acquisition.app.slug,
+            lifecycleState: "active",
+            updatedAt: new Date(),
+        })
+            .where(eq(apps.id, existing.id))
+            .returning();
+        return updated ?? existing;
+    }
+    const [created] = await db
+        .insert(apps)
+        .values({
+        id: acquisition.app.id,
+        ownerId: acquisition.app.ownerId,
+        displayName: acquisition.app.displayName,
+        slug: acquisition.app.slug,
+        distribution: "marketplace",
+        platformNamespace: `app--${randomBytes(10).toString("hex")}`,
+        createdBy: actorId,
+    })
+        .onConflictDoNothing()
+        .returning();
+    const row = created ?? (await selectAppForUpdate(db, acquisition.app.id));
+    if (row?.distribution !== "marketplace" || row.ownerId !== acquisition.app.ownerId) {
+        throw immutableIdentityConflict("Marketplace app identity could not be admitted");
+    }
+    return row;
+}
+async function reconcileOAuthClient(db, appId, secretSha256) {
+    const expectedVerifier = `sha256:${secretSha256}`;
+    const [active] = await db
+        .select()
+        .from(appCredentials)
+        .where(and(eq(appCredentials.appId, appId), eq(appCredentials.kind, "client_secret"), isNull(appCredentials.retiredAt)))
+        .limit(1);
+    if (active) {
+        if (active.kmsKeyRef !== expectedVerifier) {
+            throw immutableIdentityConflict("Marketplace OAuth client verifier conflicts with the admitted app");
+        }
+        return;
+    }
+    const generations = await db
+        .select({ generation: appCredentials.generation })
+        .from(appCredentials)
+        .where(and(eq(appCredentials.appId, appId), eq(appCredentials.kind, "client_secret")));
+    await db.insert(appCredentials).values({
+        appId,
+        kind: "client_secret",
+        generation: Math.max(0, ...generations.map((credential) => credential.generation)) + 1,
+        kmsKeyRef: expectedVerifier,
+    });
+}
+async function reconcileRedirectUris(db, appId, redirectUris) {
+    const desired = [...new Set(redirectUris)].sort();
+    const current = await db
+        .select({ redirectUri: appRedirectUris.redirectUri })
+        .from(appRedirectUris)
+        .where(eq(appRedirectUris.appId, appId));
+    const present = current.map((row) => row.redirectUri).sort();
+    if (JSON.stringify(present) === JSON.stringify(desired))
+        return;
+    await db.delete(appRedirectUris).where(eq(appRedirectUris.appId, appId));
+    if (desired.length > 0) {
+        await db.insert(appRedirectUris).values(desired.map((redirectUri) => ({ appId, redirectUri })));
+    }
+}
+async function acquireRelease(db, acquisition, compiled, actorId) {
+    const byId = await selectReleaseByIdForUpdate(db, acquisition.release.id);
+    const byVersion = await selectReleaseByVersion(db, acquisition.app.id, compiled.manifest.releaseVersion);
+    const byDigest = await selectReleaseByDigest(db, acquisition.app.id, compiled.digest);
+    for (const existing of [byId, byVersion, byDigest]) {
+        if (existing &&
+            (existing.id !== acquisition.release.id ||
+                existing.appId !== acquisition.app.id ||
+                existing.releaseVersion !== compiled.manifest.releaseVersion ||
+                existing.manifestDigest !== compiled.digest)) {
+            throw immutableIdentityConflict("Marketplace release identity conflicts with an immutable local release");
+        }
+    }
+    const existing = byId ?? byVersion ?? byDigest;
+    if (existing) {
+        if (existing.state !== "available") {
+            throw new ApiHttpError("Marketplace release is not locally available", {
+                status: 409,
+                code: "app_marketplace_release_unavailable",
+            });
+        }
+        if (canonicalJsonStringify(existing.manifestSnapshot) !== compiled.canonicalJson) {
+            throw immutableIdentityConflict("Marketplace release snapshot conflicts with the admitted manifest");
+        }
+        const [artifact] = await db
+            .select()
+            .from(appReleaseArtifacts)
+            .where(eq(appReleaseArtifacts.releaseId, existing.id))
+            .limit(1);
+        const expectedProvenance = marketplaceArtifactProvenance(acquisition);
+        if (artifact?.digest !== compiled.digest ||
+            artifact.state !== "available" ||
+            artifact.signature !== (acquisition.release.signature ?? null) ||
+            canonicalJsonStringify(artifact.provenance) !== canonicalJsonStringify(expectedProvenance) ||
+            canonicalJsonStringify(artifact.assetInventory) !==
+                canonicalJsonStringify(acquisition.release.assetInventory)) {
+            throw immutableIdentityConflict("Marketplace release artifact conflicts with the admitted manifest");
+        }
+        return { ...existing, created: false };
+    }
+    const manifestSnapshot = JSON.parse(compiled.canonicalJson);
+    const normalizedRecord = JSON.parse(JSON.stringify(compiled.normalizedRelease));
+    const [created] = await db
+        .insert(appReleases)
+        .values({
+        id: acquisition.release.id,
+        appId: acquisition.app.id,
+        releaseVersion: compiled.manifest.releaseVersion,
+        manifestSchemaVersion: compiled.manifest.schemaVersion,
+        manifestDigest: compiled.digest,
+        manifestSnapshot,
+        normalizedRecord,
+        apiCompatibility: compiled.manifest.apiCompatibility,
+        defaultLocale: compiled.manifest.locales.default,
+        supportedLocales: [...compiled.normalizedRelease.supportedLocales],
+        state: "available",
+        createdBy: actorId,
+    })
+        .returning();
+    if (!created) {
+        throw new ApiHttpError("Marketplace release could not be admitted", {
+            status: 500,
+            code: "app_marketplace_release_write_failed",
+        });
+    }
+    await db.insert(appReleaseArtifacts).values({
+        releaseId: created.id,
+        digest: compiled.digest,
+        signature: acquisition.release.signature ?? null,
+        provenance: marketplaceArtifactProvenance(acquisition),
+        registryCoordinates: null,
+        assetInventory: acquisition.release.assetInventory,
+        state: "available",
+    });
+    if (compiled.normalizedRelease.localizations.length > 0) {
+        await db.insert(appReleaseLocalizations).values(compiled.normalizedRelease.localizations.map((localization) => ({
+            releaseId: created.id,
+            ...localization,
+        })));
+    }
+    return { ...created, created: true };
+}
+function marketplaceArtifactProvenance(acquisition) {
+    return {
+        ...acquisition.release.provenance,
+        acquisitionId: acquisition.acquisitionId,
+        source: "managed-marketplace",
+    };
+}
+async function selectAppForUpdate(db, appId) {
+    const [row] = await db.select().from(apps).where(eq(apps.id, appId)).for("update").limit(1);
+    return row ?? null;
+}
+async function selectReleaseByIdForUpdate(db, releaseId) {
+    const [row] = await db
+        .select()
+        .from(appReleases)
+        .where(eq(appReleases.id, releaseId))
+        .for("update")
+        .limit(1);
+    return row ?? null;
+}
+async function selectReleaseByVersion(db, appId, version) {
+    const [row] = await db
+        .select()
+        .from(appReleases)
+        .where(and(eq(appReleases.appId, appId), eq(appReleases.releaseVersion, version)))
+        .limit(1);
+    return row ?? null;
+}
+async function selectReleaseByDigest(db, appId, digest) {
+    const [row] = await db
+        .select()
+        .from(appReleases)
+        .where(and(eq(appReleases.appId, appId), eq(appReleases.manifestDigest, digest)))
+        .limit(1);
+    return row ?? null;
+}
+function immutableIdentityConflict(message) {
+    return new ApiHttpError(message, {
+        status: 409,
+        code: "app_marketplace_identity_conflict",
+    });
+}
+function readSetupUrl(normalizedRecord) {
+    const urls = normalizedRecord.urls;
+    if (!urls || typeof urls !== "object" || Array.isArray(urls))
+        return null;
+    const setup = urls.setup;
+    if (typeof setup !== "string")
+        return null;
+    try {
+        const parsed = new URL(setup);
+        return parsed.protocol === "https:" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseTrustedSetupRedirect(input, admittedSetupUrl) {
+    let redirect;
+    try {
+        redirect = new URL(input);
+    }
+    catch {
+        throw new ApiHttpError("Managed setup handoff returned an invalid redirect", {
+            status: 502,
+            code: "app_marketplace_setup_invalid",
+        });
+    }
+    if (redirect.protocol !== "https:" || redirect.origin !== admittedSetupUrl.origin) {
+        throw new ApiHttpError("Managed setup handoff returned an untrusted redirect", {
+            status: 502,
+            code: "app_marketplace_setup_invalid",
+        });
+    }
+    return redirect.toString();
+}

package/dist/marketplace-acquisition.test.d.ts

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

package/dist/marketplace-acquisition.test.js

@@ -0,0 +1,191 @@
+import { eq } from "drizzle-orm";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { compileAppManifest } from "./compiler.js";
+import { createAppInstallationService } from "./installation-service.js";
+import { createMarketplaceAcquisitionService, hostVerifiedMarketplaceAcquisitionSchema, marketplaceSetupAssertionClaimsSchema, } from "./marketplace-acquisition.js";
+import { appCredentials, appRedirectUris, appReleaseArtifacts, appReleases, apps, } from "./schema.js";
+import { validManifest } from "./test-fixtures.js";
+const DB_AVAILABLE = !!process.env.TEST_DATABASE_URL;
+function acquisition(overrides = {}) {
+    const digest = compileAppManifest(validManifest).digest;
+    return {
+        schemaVersion: "voyant.runtime-marketplace-acquisition.v1",
+        acquisitionId: "acquisition_1",
+        app: {
+            id: "marketplace_app_1",
+            ownerId: "publisher_1",
+            displayName: "Accounting Bridge",
+            slug: "accounting-bridge",
+            redirectUris: ["https://app.example.com/oauth/callback"],
+            oauthClient: {
+                method: "client_secret_post",
+                secretSha256: "a".repeat(64),
+            },
+        },
+        release: {
+            id: "marketplace_release_1",
+            manifest: validManifest,
+            digest,
+            signature: "host-verified-signature",
+            provenance: { publisherId: "publisher_1", reviewId: "review_1" },
+            assetInventory: { files: [] },
+        },
+        ...overrides,
+    };
+}
+describe("Marketplace OAuth client acquisition contract", () => {
+    it("admits only a publisher-held secret verifier, never a raw secret", () => {
+        const current = acquisition();
+        expect(hostVerifiedMarketplaceAcquisitionSchema.parse(current).app.oauthClient).toEqual({
+            method: "client_secret_post",
+            secretSha256: "a".repeat(64),
+        });
+        expect(() => hostVerifiedMarketplaceAcquisitionSchema.parse({
+            ...current,
+            app: {
+                ...current.app,
+                oauthClient: {
+                    ...current.app.oauthClient,
+                    secret: "must-not-cross-the-host-boundary",
+                },
+            },
+        })).toThrow();
+    });
+});
+describe("Marketplace setup assertion contract", () => {
+    const valid = {
+        schemaVersion: "voyant.marketplace-setup-assertion.v1",
+        iss: "https://cloud.example.com",
+        aud: "marketplace_app_1",
+        sub: "installation_1",
+        jti: "setup_nonce_1",
+        iat: 1_000,
+        exp: 1_300,
+        installationId: "installation_1",
+        appId: "marketplace_app_1",
+        releaseId: "marketplace_release_1",
+        authorizationUrl: "https://admin.example.com/apps/oauth/authorize",
+        tokenUrl: "https://admin.example.com/api/v1/admin/apps/oauth/token",
+        redirectUri: "https://app.example.com/oauth/callback",
+    };
+    it("binds subject, audience, identity, exact OAuth coordinates, and a five-minute lifetime", () => {
+        expect(marketplaceSetupAssertionClaimsSchema.parse(valid)).toEqual(valid);
+        expect(() => marketplaceSetupAssertionClaimsSchema.parse({ ...valid, sub: "another_installation" })).toThrow(/subject/i);
+        expect(() => marketplaceSetupAssertionClaimsSchema.parse({ ...valid, aud: "another_app" })).toThrow(/audience/i);
+        expect(() => marketplaceSetupAssertionClaimsSchema.parse({ ...valid, exp: 1_301 })).toThrow(/300 seconds/i);
+    });
+    it("rejects non-HTTPS coordinates", () => {
+        expect(() => marketplaceSetupAssertionClaimsSchema.parse({
+            ...valid,
+            tokenUrl: "http://admin.example.com/api/v1/admin/apps/oauth/token",
+        })).toThrow(/HTTPS/i);
+    });
+});
+describe.skipIf(!DB_AVAILABLE)("managed Marketplace acquisition", () => {
+    let db;
+    beforeAll(async () => {
+        const { createTestDb } = await import("@voyant-travel/db/test-utils");
+        db = createTestDb();
+    });
+    beforeEach(async () => {
+        const { cleanupTestDb } = await import("@voyant-travel/db/test-utils");
+        await cleanupTestDb(db);
+    });
+    it("idempotently admits a host-verified app and immutable available release", async () => {
+        const current = acquisition();
+        const resolveAcquisitionIntent = vi.fn(async () => current);
+        const service = createMarketplaceAcquisitionService({
+            resolveAcquisitionIntent,
+            createSetupHandoff: vi.fn(),
+        });
+        const first = await service.resolveAndAcquire(db, { intent: "opaque-1", actorId: "user_1" });
+        const second = await service.resolveAndAcquire(db, { intent: "opaque-1", actorId: "user_1" });
+        expect(first).toMatchObject({
+            appId: current.app.id,
+            releaseId: current.release.id,
+            acquisitionId: current.acquisitionId,
+            created: true,
+        });
+        expect(second).toMatchObject({ created: false });
+        expect(resolveAcquisitionIntent).toHaveBeenNthCalledWith(1, { intent: "opaque-1" });
+        const [app] = await db.select().from(apps).where(eq(apps.id, current.app.id));
+        const releases = await db
+            .select()
+            .from(appReleases)
+            .where(eq(appReleases.appId, current.app.id));
+        const artifacts = await db
+            .select()
+            .from(appReleaseArtifacts)
+            .where(eq(appReleaseArtifacts.releaseId, current.release.id));
+        const redirects = await db
+            .select()
+            .from(appRedirectUris)
+            .where(eq(appRedirectUris.appId, current.app.id));
+        const credentials = await db
+            .select()
+            .from(appCredentials)
+            .where(eq(appCredentials.appId, current.app.id));
+        expect(app).toMatchObject({
+            distribution: "marketplace",
+            ownerId: current.app.ownerId,
+            displayName: current.app.displayName,
+        });
+        expect(releases).toHaveLength(1);
+        expect(releases[0]).toMatchObject({
+            state: "available",
+            manifestDigest: current.release.digest,
+        });
+        expect(artifacts).toHaveLength(1);
+        expect(artifacts[0]?.registryCoordinates).toBeNull();
+        expect(redirects.map((row) => row.redirectUri)).toEqual(current.app.redirectUris);
+        expect(credentials).toHaveLength(1);
+        expect(credentials[0]).toMatchObject({
+            kind: "client_secret",
+            generation: 1,
+            kmsKeyRef: `sha256:${current.app.oauthClient.secretSha256}`,
+        });
+        current.release.signature = "different-signature";
+        await expect(service.resolveAndAcquire(db, { intent: "opaque-1", actorId: "user_1" })).rejects.toMatchObject({ status: 409, code: "app_marketplace_identity_conflict" });
+        current.release.signature = "host-verified-signature";
+        current.app.oauthClient.secretSha256 = "b".repeat(64);
+        await expect(service.resolveAndAcquire(db, { intent: "opaque-1", actorId: "user_1" })).rejects.toMatchObject({ status: 409, code: "app_marketplace_identity_conflict" });
+    });
+    it("rejects a digest that does not match the independently compiled manifest", async () => {
+        const service = createMarketplaceAcquisitionService({
+            resolveAcquisitionIntent: async () => acquisition({ release: { ...acquisition().release, digest: `sha256:${"0".repeat(64)}` } }),
+            createSetupHandoff: vi.fn(),
+        });
+        await expect(service.resolveAndAcquire(db, { intent: "opaque-1", actorId: "user_1" })).rejects.toMatchObject({ status: 409, code: "app_marketplace_digest_mismatch" });
+    });
+    it("creates setup only from active installation identity and an admitted setup origin", async () => {
+        const current = acquisition();
+        const createSetupHandoff = vi.fn(async () => ({
+            redirectUrl: "https://app.example.com/setup?code=one-time-opaque",
+        }));
+        const service = createMarketplaceAcquisitionService({
+            resolveAcquisitionIntent: async () => current,
+            createSetupHandoff,
+        });
+        await service.resolveAndAcquire(db, { intent: "opaque-1", actorId: "user_1" });
+        const installed = await createAppInstallationService({ deploymentId: "deployment_1" }).install(db, {
+            appId: current.app.id,
+            releaseId: current.release.id,
+            actorId: "user_1",
+        });
+        await expect(service.createSetupHandoff(db, installed.installation.id)).resolves.toEqual({
+            redirectUrl: "https://app.example.com/setup?code=one-time-opaque",
+        });
+        expect(createSetupHandoff).toHaveBeenCalledWith({
+            installationId: installed.installation.id,
+            appId: current.app.id,
+            releaseId: current.release.id,
+        });
+        createSetupHandoff.mockResolvedValueOnce({
+            redirectUrl: "https://attacker.example/setup?code=stolen",
+        });
+        await expect(service.createSetupHandoff(db, installed.installation.id)).rejects.toMatchObject({
+            status: 502,
+            code: "app_marketplace_setup_invalid",
+        });
+    });
+});

package/dist/oauth-redirect.d.ts

@@ -0,0 +1,6 @@
+export declare function buildAppOAuthCallbackUrl(input: {
+    redirectUri: string;
+    code: string;
+    state: string;
+    nonce?: string;
+}): URL;

package/dist/oauth-redirect.js

@@ -0,0 +1,8 @@
+export function buildAppOAuthCallbackUrl(input) {
+    const redirectUrl = new URL(input.redirectUri);
+    redirectUrl.searchParams.set("code", input.code);
+    redirectUrl.searchParams.set("state", input.state);
+    if (input.nonce)
+        redirectUrl.searchParams.set("nonce", input.nonce);
+    return redirectUrl;
+}

package/dist/oauth-redirect.test.d.ts

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

package/dist/oauth-redirect.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { appOAuthAuthorizeQuerySchema } from "./contracts.js";
+import { buildAppOAuthCallbackUrl } from "./oauth-redirect.js";
+const request = {
+    response_type: "code",
+    client_id: "app_smartbill",
+    release_id: "release_smartbill_1",
+    redirect_uri: "https://voyant-smartbill-app-dev.pixelmakers.io/v1/setup/oauth/callback",
+    state: "state_1",
+    code_challenge: "challenge_1",
+    code_challenge_method: "S256",
+};
+describe("app OAuth callback binding", () => {
+    it("accepts and echoes an app-generated nonce", () => {
+        const nonce = "n".repeat(43);
+        const parsed = appOAuthAuthorizeQuerySchema.parse({ ...request, nonce });
+        const redirect = buildAppOAuthCallbackUrl({
+            redirectUri: parsed.redirect_uri,
+            code: "authorization_code_1",
+            state: parsed.state,
+            nonce: parsed.nonce,
+        });
+        expect(redirect.searchParams.get("code")).toBe("authorization_code_1");
+        expect(redirect.searchParams.get("state")).toBe("state_1");
+        expect(redirect.searchParams.get("nonce")).toBe(nonce);
+    });
+    it("keeps nonce optional for OAuth clients that use state and PKCE only", () => {
+        const parsed = appOAuthAuthorizeQuerySchema.parse(request);
+        const redirect = buildAppOAuthCallbackUrl({
+            redirectUri: parsed.redirect_uri,
+            code: "authorization_code_1",
+            state: parsed.state,
+        });
+        expect(redirect.searchParams.has("nonce")).toBe(false);
+    });
+    it("rejects short nonce values", () => {
+        expect(() => appOAuthAuthorizeQuerySchema.parse({ ...request, nonce: "short" })).toThrow();
+    });
+});

package/dist/oauth-service.js

@@ -1,5 +1,5 @@
 import { ApiHttpError } from "@voyant-travel/hono";
-import { and, eq } from "drizzle-orm";
+import { and, eq, isNull } from "drizzle-orm";
 import { computeAppConsent } from "./consent.js";
 import { APP_ACCESS_TOKEN_PREFIX, APP_AUTH_CODE_PREFIX, APP_REFRESH_TOKEN_PREFIX, constantTimeEqual, randomToken, sha256Hex, verifyPkceS256, } from "./oauth-crypto.js";
 import { assertActiveInstallation, assertManagedBinding, assertManagedInstallationAuthority, assertTokenClient, ensureAuthorizedInstallation, grantedScopes, isInstallationUsable, managedBindingMatches, requireInstallation, selectInstallation, } from "./oauth-installation.js";
@@ -323,7 +323,7 @@ async function authenticateClient(db, appId, clientSecret, required) {
     const [secret] = await db
         .select()
         .from(appCredentials)
-        .where(and(eq(appCredentials.appId, appId), eq(appCredentials.kind, "client_secret")))
+        .where(and(eq(appCredentials.appId, appId), eq(appCredentials.kind, "client_secret"), isNull(appCredentials.retiredAt)))
         .limit(1);
     if (!secret) {
         if (required)