@voyant-travel/apps 0.2.0 → 0.3.0

package/dist/oauth-service.d.ts

@@ -0,0 +1,66 @@
+import type { VoyantAuthContext } from "@voyant-travel/core";
+import type { AccessCatalog } from "@voyant-travel/types/api-keys";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+export interface AppOAuthServiceOptions {
+    accessCatalog: AccessCatalog;
+    deploymentId: string;
+    now?: () => Date;
+}
+export interface AuthorizeAppInput {
+    appId: string;
+    releaseId: string;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+    actorId: string;
+    operatorGrantedScopes: readonly string[];
+    grantedOptionalScopes?: readonly string[];
+}
+export interface TokenCodeInput {
+    grantType: "authorization_code";
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+    clientId: string;
+    clientSecret?: string;
+}
+export interface RefreshTokenInput {
+    grantType: "refresh_token";
+    refreshToken: string;
+    clientId: string;
+    clientSecret?: string;
+}
+export interface TokenExchangeInput {
+    grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange";
+    installationId: string;
+    viewerId: string;
+    viewerScopes: readonly string[];
+    contextualScopes?: readonly string[];
+    clientId: string;
+    clientSecret?: string;
+}
+export type AppTokenInput = TokenCodeInput | RefreshTokenInput | TokenExchangeInput;
+export declare function createAppOAuthService(options: AppOAuthServiceOptions): {
+    authorize: (db: PostgresJsDatabase, input: AuthorizeAppInput) => Promise<{
+        code: string;
+        state: string;
+        redirectUri: string;
+        expiresAt: Date;
+    }>;
+    token: (db: PostgresJsDatabase, input: AppTokenInput) => Promise<{
+        refreshToken?: string | undefined;
+        accessToken: string;
+        tokenType: "Bearer";
+        expiresIn: number;
+        scope: string;
+        tokenMode: "offline" | "online";
+    }>;
+    resolveAccessToken: (db: PostgresJsDatabase, rawToken: string) => Promise<VoyantAuthContext | null>;
+    revokeInstallationCredentials: (db: PostgresJsDatabase, installationId: string, actorId: string) => Promise<{
+        installationId: string;
+        generation: number;
+    }>;
+};
+export declare function intersectAppTokenScopes(...sets: readonly (readonly string[])[]): string[];
+export declare function readStoredScopes(metadata: Record<string, unknown>): string[] | null;

package/dist/oauth-service.js

@@ -0,0 +1,398 @@
+import { ApiHttpError } from "@voyant-travel/hono";
+import { and, eq } 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 { appAccessCredentials, appAuditEvents, appCredentials, appGrants, appInstallations, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleases, apps, } from "./schema.js";
+const CODE_TTL_MS = 5 * 60 * 1000;
+const OFFLINE_ACCESS_TTL_MS = 60 * 60 * 1000;
+const ONLINE_ACCESS_TTL_MS = 10 * 60 * 1000;
+const REFRESH_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+export function createAppOAuthService(options) {
+    const now = () => options.now?.() ?? new Date();
+    async function authorize(db, input) {
+        assertState(input.state);
+        if (input.codeChallengeMethod !== "S256") {
+            throw oauthError("invalid_request", "PKCE S256 is required");
+        }
+        const release = await requireRelease(db, input.appId, input.releaseId);
+        await requireExactRedirectUri(db, input.appId, input.redirectUri);
+        const consent = computeAppConsent({
+            release,
+            accessCatalog: options.accessCatalog,
+            operatorGrantedScopes: input.operatorGrantedScopes,
+            grantedOptionalScopes: input.grantedOptionalScopes,
+        });
+        const installation = await ensureAuthorizedInstallation(db, {
+            appId: input.appId,
+            releaseId: input.releaseId,
+            deploymentId: options.deploymentId,
+            actorId: input.actorId,
+            grantedScopes: consent.grantedScopes,
+            deniedOptionalScopes: consent.deniedOptionalScopes,
+        });
+        const code = randomToken(APP_AUTH_CODE_PREFIX);
+        const expiresAt = new Date(now().getTime() + CODE_TTL_MS);
+        await db.insert(appOAuthAuthorizationCodes).values({
+            appId: input.appId,
+            installationId: installation.id,
+            releaseId: input.releaseId,
+            deploymentId: options.deploymentId,
+            codeHash: sha256Hex(code),
+            stateHash: sha256Hex(input.state),
+            redirectUri: input.redirectUri,
+            codeChallenge: input.codeChallenge,
+            codeChallengeMethod: input.codeChallengeMethod,
+            requestedScopes: [...consent.requiredScopes, ...consent.optionalScopes].sort(),
+            grantedScopes: consent.grantedScopes,
+            deniedOptionalScopes: consent.deniedOptionalScopes,
+            actorId: input.actorId,
+            expiresAt,
+        });
+        await audit(db, installation, input.actorId, "consent", "oauth.consent.recorded", {
+            grantedScopes: consent.grantedScopes,
+            deniedOptionalScopes: consent.deniedOptionalScopes,
+        });
+        return { code, state: input.state, redirectUri: input.redirectUri, expiresAt };
+    }
+    async function token(db, input) {
+        await authenticateClient(db, input.clientId, input.clientSecret);
+        if (input.grantType === "authorization_code")
+            return exchangeCode(db, input);
+        if (input.grantType === "refresh_token")
+            return refresh(db, input);
+        return exchangeActorToken(db, input);
+    }
+    async function resolveAccessToken(db, rawToken) {
+        if (!rawToken.startsWith(APP_ACCESS_TOKEN_PREFIX))
+            return null;
+        const [credential] = await db
+            .select()
+            .from(appAccessCredentials)
+            .where(and(eq(appAccessCredentials.credentialHash, sha256Hex(rawToken)), eq(appAccessCredentials.status, "active")))
+            .limit(1);
+        if (!credential || (credential.expiresAt && credential.expiresAt <= now()))
+            return null;
+        const installation = await selectInstallation(db, credential.installationId);
+        if (!installation || !isInstallationUsable(installation, credential.generation))
+            return null;
+        // Online tokens resolve to the scope set minted at exchange (viewer/context
+        // intersection); recomputing from grants would silently widen them. Offline
+        // tokens track live grants so revoking a scope applies immediately. A
+        // missing stored set on an online token fails closed to no scopes.
+        const scopes = credential.tokenMode === "online"
+            ? (readStoredScopes(credential.encryptedMetadata) ?? [])
+            : await grantedScopes(db, installation.id);
+        return {
+            callerType: "app",
+            actor: "staff",
+            audience: "staff",
+            appId: installation.appId,
+            appInstallationId: installation.id,
+            appReleaseId: installation.releaseId,
+            appCredentialGeneration: credential.generation,
+            appTokenMode: credential.tokenMode,
+            appViewerId: credential.viewerId ?? undefined,
+            scopes,
+        };
+    }
+    async function revokeInstallationCredentials(db, installationId, actorId) {
+        return db.transaction(async (tx) => {
+            const installation = await requireInstallation(tx, installationId);
+            const generation = installation.credentialGeneration + 1;
+            await tx
+                .update(appInstallations)
+                .set({ credentialGeneration: generation, updatedAt: now() })
+                .where(eq(appInstallations.id, installation.id));
+            await tx
+                .update(appAccessCredentials)
+                .set({ status: "revoked", deactivatedAt: now() })
+                .where(eq(appAccessCredentials.installationId, installation.id));
+            await tx
+                .update(appOAuthRefreshTokens)
+                .set({ status: "revoked", revokedAt: now() })
+                .where(eq(appOAuthRefreshTokens.installationId, installation.id));
+            await audit(tx, installation, actorId, "credential", "credential.revoked", { generation });
+            return { installationId: installation.id, generation };
+        });
+    }
+    return { authorize, token, resolveAccessToken, revokeInstallationCredentials };
+    async function exchangeCode(db, input) {
+        return db.transaction(async (tx) => {
+            const codeHash = sha256Hex(input.code);
+            const [code] = await tx
+                .select()
+                .from(appOAuthAuthorizationCodes)
+                .where(eq(appOAuthAuthorizationCodes.codeHash, codeHash))
+                .for("update")
+                .limit(1);
+            if (!code || code.consumedAt || code.expiresAt <= now()) {
+                throw oauthError("invalid_grant", "Authorization code is invalid, expired, or consumed");
+            }
+            if (code.appId !== input.clientId || code.redirectUri !== input.redirectUri) {
+                throw oauthError("invalid_grant", "Authorization code was issued to different client data");
+            }
+            if (!verifyPkceS256(input.codeVerifier, code.codeChallenge)) {
+                throw oauthError("invalid_grant", "PKCE verifier does not match the authorization code");
+            }
+            await tx
+                .update(appOAuthAuthorizationCodes)
+                .set({ consumedAt: now() })
+                .where(eq(appOAuthAuthorizationCodes.id, code.id));
+            const installation = await requireInstallation(tx, code.installationId);
+            assertActiveInstallation(installation);
+            const tokens = await mintTokens(tx, installation, code.actorId, null, code.grantedScopes);
+            await audit(tx, installation, code.actorId, "token", "oauth.code.exchanged", {});
+            return tokens;
+        });
+    }
+    async function refresh(db, input) {
+        return db.transaction(async (tx) => {
+            const [tokenRow] = await tx
+                .select()
+                .from(appOAuthRefreshTokens)
+                .where(eq(appOAuthRefreshTokens.tokenHash, sha256Hex(input.refreshToken)))
+                .for("update")
+                .limit(1);
+            if (tokenRow?.status !== "active" || isExpired(tokenRow.expiresAt)) {
+                throw oauthError("invalid_grant", "Refresh token is invalid");
+            }
+            const installation = await requireInstallation(tx, tokenRow.installationId);
+            assertTokenClient(installation, input.clientId);
+            assertActiveInstallation(installation);
+            if (installation.credentialGeneration !== tokenRow.generation) {
+                throw oauthError("invalid_grant", "Refresh token generation was revoked");
+            }
+            await tx
+                .update(appOAuthRefreshTokens)
+                .set({ status: "inactive", revokedAt: now() })
+                .where(eq(appOAuthRefreshTokens.id, tokenRow.id));
+            const tokens = await mintTokens(tx, installation, "app", null, await grantedScopes(tx, installation.id), {
+                rotatedFromId: tokenRow.id,
+            });
+            await audit(tx, installation, "app", "token", "oauth.refresh.rotated", {
+                generation: installation.credentialGeneration,
+            });
+            return tokens;
+        });
+    }
+    async function exchangeActorToken(db, input) {
+        const installation = await requireInstallation(db, input.installationId);
+        assertTokenClient(installation, input.clientId);
+        assertActiveInstallation(installation);
+        const grants = await grantedScopes(db, installation.id);
+        const contextual = input.contextualScopes ?? grants;
+        const scopes = intersectAppTokenScopes(grants, input.viewerScopes, contextual);
+        const accessToken = randomToken(APP_ACCESS_TOKEN_PREFIX);
+        const expiresAt = new Date(now().getTime() + ONLINE_ACCESS_TTL_MS);
+        await db.insert(appAccessCredentials).values({
+            installationId: installation.id,
+            generation: installation.credentialGeneration,
+            tokenMode: "online",
+            credentialHash: sha256Hex(accessToken),
+            // Online tokens are intentionally narrowed; the resolver must honor the
+            // minted set rather than recomputing from installation grants.
+            encryptedMetadata: { scopeCount: scopes.length, scopes: [...scopes] },
+            status: "active",
+            actorId: input.viewerId,
+            viewerId: input.viewerId,
+            expiresAt,
+        });
+        await audit(db, installation, input.viewerId, "token", "oauth.actor_token.exchanged", {
+            grantedScopes: scopes,
+        });
+        return tokenResponse(accessToken, null, expiresAt, scopes, "online");
+    }
+    async function mintTokens(db, installation, actorId, viewerId, scopes, refreshOptions = {}) {
+        const accessToken = randomToken(APP_ACCESS_TOKEN_PREFIX);
+        const refreshToken = randomToken(APP_REFRESH_TOKEN_PREFIX);
+        const accessExpiresAt = new Date(now().getTime() + OFFLINE_ACCESS_TTL_MS);
+        const refreshExpiresAt = new Date(now().getTime() + REFRESH_TTL_MS);
+        const generation = installation.credentialGeneration;
+        await db.insert(appAccessCredentials).values({
+            installationId: installation.id,
+            generation,
+            tokenMode: "offline",
+            credentialHash: sha256Hex(accessToken),
+            encryptedMetadata: { scopeCount: scopes.length },
+            status: "active",
+            actorId,
+            viewerId,
+            expiresAt: accessExpiresAt,
+        });
+        await db.insert(appOAuthRefreshTokens).values({
+            installationId: installation.id,
+            tokenHash: sha256Hex(refreshToken),
+            generation,
+            rotatedFromId: refreshOptions.rotatedFromId,
+            expiresAt: refreshExpiresAt,
+        });
+        return tokenResponse(accessToken, refreshToken, accessExpiresAt, scopes, "offline");
+    }
+    function isExpired(expiresAt) {
+        return Boolean(expiresAt && expiresAt <= now());
+    }
+}
+function tokenResponse(accessToken, refreshToken, expiresAt, scopes, tokenMode) {
+    return {
+        accessToken,
+        tokenType: "Bearer",
+        expiresIn: Math.max(0, Math.floor((expiresAt.getTime() - Date.now()) / 1000)),
+        scope: scopes.join(" "),
+        tokenMode,
+        ...(refreshToken ? { refreshToken } : {}),
+    };
+}
+async function authenticateClient(db, appId, clientSecret) {
+    const [secret] = await db
+        .select()
+        .from(appCredentials)
+        .where(and(eq(appCredentials.appId, appId), eq(appCredentials.kind, "client_secret")))
+        .limit(1);
+    if (!secret)
+        return;
+    if (!clientSecret || !secret.kmsKeyRef.startsWith("sha256:")) {
+        throw oauthError("invalid_client", "Client authentication failed", 401);
+    }
+    const expected = secret.kmsKeyRef.slice("sha256:".length);
+    if (!constantTimeEqual(sha256Hex(clientSecret), expected)) {
+        throw oauthError("invalid_client", "Client authentication failed", 401);
+    }
+}
+async function requireRelease(db, appId, releaseId) {
+    const [release] = await db
+        .select()
+        .from(appReleases)
+        .where(and(eq(appReleases.id, releaseId), eq(appReleases.appId, appId)))
+        .limit(1);
+    if (!release)
+        throw oauthError("invalid_request", "App release not found", 404);
+    if (release.state !== "available") {
+        throw oauthError("invalid_request", "App release is not available for authorization", 409);
+    }
+    return release;
+}
+async function requireExactRedirectUri(db, appId, redirectUri) {
+    const [row] = await db
+        .select()
+        .from(appRedirectUris)
+        .where(and(eq(appRedirectUris.appId, appId), eq(appRedirectUris.redirectUri, redirectUri)))
+        .limit(1);
+    if (!row)
+        throw oauthError("invalid_request", "Redirect URI is not registered for this app");
+}
+async function ensureAuthorizedInstallation(db, input) {
+    return db.transaction(async (tx) => {
+        const [app] = await tx.select().from(apps).where(eq(apps.id, input.appId)).limit(1);
+        if (!app)
+            throw oauthError("invalid_request", "App registration not found", 404);
+        const [existing] = await tx
+            .select()
+            .from(appInstallations)
+            .where(and(eq(appInstallations.deploymentId, input.deploymentId), eq(appInstallations.appId, input.appId)))
+            .limit(1);
+        const installation = existing ??
+            (await tx
+                .insert(appInstallations)
+                .values({
+                appId: input.appId,
+                deploymentId: input.deploymentId,
+                releaseId: input.releaseId,
+                status: "active",
+                namespace: app.platformNamespace,
+                installedBy: input.actorId,
+                authorizedAt: new Date(),
+                activatedAt: new Date(),
+            })
+                .returning())[0];
+        if (!installation)
+            throw oauthError("server_error", "Could not create installation", 500);
+        for (const scope of input.grantedScopes) {
+            await tx
+                .insert(appGrants)
+                .values({
+                installationId: installation.id,
+                scope,
+                status: "granted",
+                optional: false,
+                grantedAt: new Date(),
+            })
+                .onConflictDoUpdate({
+                target: [appGrants.installationId, appGrants.scope],
+                set: { status: "granted", grantedAt: new Date(), revokedAt: null },
+            });
+        }
+        for (const scope of input.deniedOptionalScopes) {
+            await tx
+                .insert(appGrants)
+                .values({ installationId: installation.id, scope, status: "optional", optional: true })
+                .onConflictDoUpdate({
+                target: [appGrants.installationId, appGrants.scope],
+                set: { status: "optional", optional: true },
+            });
+        }
+        return installation;
+    });
+}
+async function requireInstallation(db, installationId) {
+    const installation = await selectInstallation(db, installationId);
+    if (!installation)
+        throw oauthError("invalid_grant", "App installation not found", 404);
+    return installation;
+}
+async function selectInstallation(db, installationId) {
+    const [installation] = await db
+        .select()
+        .from(appInstallations)
+        .where(eq(appInstallations.id, installationId))
+        .limit(1);
+    return installation ?? null;
+}
+async function grantedScopes(db, installationId) {
+    const rows = await db
+        .select({ scope: appGrants.scope })
+        .from(appGrants)
+        .where(and(eq(appGrants.installationId, installationId), eq(appGrants.status, "granted")))
+        .orderBy(appGrants.scope);
+    return rows.map((row) => row.scope);
+}
+function assertActiveInstallation(installation) {
+    if (installation.status !== "active") {
+        throw oauthError("invalid_grant", "App installation is not active");
+    }
+}
+function isInstallationUsable(installation, generation) {
+    return installation?.status === "active" && installation.credentialGeneration === generation;
+}
+function assertTokenClient(installation, clientId) {
+    if (installation.appId !== clientId) {
+        throw oauthError("invalid_grant", "Token belongs to a different app");
+    }
+}
+export function intersectAppTokenScopes(...sets) {
+    const [first = [], ...rest] = sets;
+    return first.filter((scope) => rest.every((set) => set.includes(scope))).sort();
+}
+function assertState(state) {
+    if (!state.trim())
+        throw oauthError("invalid_request", "OAuth state is required");
+}
+export function readStoredScopes(metadata) {
+    const stored = metadata.scopes;
+    if (!Array.isArray(stored))
+        return null;
+    return stored.filter((scope) => typeof scope === "string");
+}
+function oauthError(error, description, status = 400) {
+    return new ApiHttpError(description, { status, code: error });
+}
+async function audit(db, installation, actorId, kind, action, details) {
+    await db.insert(appAuditEvents).values({
+        installationId: installation.id,
+        appId: installation.appId,
+        deploymentId: installation.deploymentId,
+        actorId,
+        kind,
+        action,
+        details,
+    });
+}

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

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

package/dist/oauth-service.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { createAppOAuthService, intersectAppTokenScopes, readStoredScopes, } from "./oauth-service.js";
+import { appReleases } from "./schema.js";
+describe("app OAuth online token scope intersection", () => {
+    it("never exceeds either app grants, viewer grants, or contextual restrictions", () => {
+        expect(intersectAppTokenScopes(["bookings:read", "invoices:read"], ["bookings:read", "customers:read"], ["bookings:read", "invoices:read"])).toEqual(["bookings:read"]);
+        expect(intersectAppTokenScopes(["bookings:read"], ["bookings:read", "invoices:read"], ["bookings:read", "invoices:read"])).toEqual(["bookings:read"]);
+    });
+});
+describe("stored online token scopes", () => {
+    it("round-trips the minted scope set and ignores malformed metadata", () => {
+        expect(readStoredScopes({ scopeCount: 1, scopes: ["bookings:read"] })).toEqual([
+            "bookings:read",
+        ]);
+        expect(readStoredScopes({ scopes: ["bookings:read", 7, null] })).toEqual(["bookings:read"]);
+        expect(readStoredScopes({ scopeCount: 2 })).toBeNull();
+        expect(readStoredScopes({ scopes: "bookings:read" })).toBeNull();
+    });
+});
+describe("authorization release lifecycle", () => {
+    function dbWithRelease(state) {
+        const release = {
+            id: "apprel_1",
+            appId: "app_1",
+            state,
+            releaseVersion: "1.0.0",
+        };
+        const db = Object.create(null);
+        Object.assign(db, {
+            select: () => ({
+                from: (table) => ({
+                    where: () => ({
+                        limit: async () => (table === appReleases ? [release] : []),
+                    }),
+                }),
+            }),
+        });
+        return db;
+    }
+    const authorizeInput = {
+        appId: "app_1",
+        releaseId: "apprel_1",
+        redirectUri: "https://app.example.com/callback",
+        state: "state-1",
+        codeChallenge: "c".repeat(43),
+        codeChallengeMethod: "S256",
+        actorId: "user_1",
+        operatorGrantedScopes: [],
+        grantedOptionalScopes: [],
+    };
+    it.each(["suspended", "yanked"])("rejects a %s release before any side effect", async (state) => {
+        const service = createAppOAuthService({
+            accessCatalog: { resources: [], presets: [] },
+            deploymentId: "dep_1",
+        });
+        await expect(service.authorize(dbWithRelease(state), authorizeInput)).rejects.toMatchObject({
+            status: 409,
+        });
+    });
+});

package/dist/routes.d.ts

@@ -1,3 +1,4 @@
+import type { AccessCatalog } from "@voyant-travel/types/api-keys";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import { Hono } from "hono";
 import { type AppsServiceOptions } from "./service.js";
@@ -6,5 +7,11 @@ type Env = {
         db: PostgresJsDatabase;
     };
 };
-export declare function createAppsAdminRoutes(options?: AppsServiceOptions): Hono<Env, import("hono/types").BlankSchema, "/">;
+export interface AppsAdminRouteOptions extends AppsServiceOptions {
+    oauth?: {
+        accessCatalog: AccessCatalog;
+        deploymentId: string;
+    };
+}
+export declare function createAppsAdminRoutes(options?: AppsAdminRouteOptions): Hono<Env, import("hono/types").BlankSchema, "/">;
 export {};

package/dist/routes.js

@@ -1,7 +1,8 @@
 import { parseJsonBody, parseQuery, RequestValidationError } from "@voyant-travel/hono";
 import { Hono } from "hono";
 import { z } from "zod";
-import { appListQuerySchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
+import { appCredentialRevocationSchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
+import { createAppOAuthService } from "./oauth-service.js";
 import { createAppsService } from "./service.js";
 import { listAppWebhookHealth, replayAppWebhookDelivery } from "./webhook-delivery.js";
 const appIdParamSchema = z.object({ appId: z.string().min(1) });
@@ -9,6 +10,7 @@ const installationIdParamSchema = z.object({ installationId: z.string().min(1) }
 export function createAppsAdminRoutes(options = {}) {
     const routes = new Hono();
     const service = createAppsService(options);
+    const oauth = options.oauth ? createAppOAuthService(options.oauth) : null;
     routes.get("/", async (c) => {
         const query = parseQuery(c, appListQuerySchema);
         return c.json(await service.list(c.get("db"), query), 200);
@@ -18,6 +20,67 @@ export function createAppsAdminRoutes(options = {}) {
         const app = await service.createCustomApp(c.get("db"), body);
         return c.json({ data: app }, 201);
     });
+    // Consent approval mutates state (installation, grants, authorization code),
+    // so it must never be reachable through read-scoped GET requests. The admin
+    // consent UI submits the approval and performs the redirect itself.
+    routes.post("/oauth/authorize", async (c) => {
+        if (!oauth)
+            return c.json({ error: "App OAuth is not configured" }, 501);
+        const body = await parseJsonBody(c, appOAuthAuthorizeQuerySchema);
+        const result = await oauth.authorize(c.get("db"), {
+            appId: body.client_id,
+            releaseId: body.release_id,
+            redirectUri: body.redirect_uri,
+            state: body.state,
+            codeChallenge: body.code_challenge,
+            codeChallengeMethod: body.code_challenge_method,
+            actorId: body.actor_id,
+            operatorGrantedScopes: splitScopes(body.operator_scopes),
+            grantedOptionalScopes: splitScopes(body.optional_scopes),
+        });
+        const redirectUrl = new URL(result.redirectUri);
+        redirectUrl.searchParams.set("code", result.code);
+        redirectUrl.searchParams.set("state", result.state);
+        return c.json({ data: { redirectUrl: redirectUrl.toString(), state: result.state } }, 200);
+    });
+    routes.post("/oauth/token", async (c) => {
+        if (!oauth)
+            return c.json({ error: "App OAuth is not configured" }, 501);
+        const body = await parseJsonBody(c, appOAuthTokenSchema);
+        const token = body.grant_type === "authorization_code"
+            ? await oauth.token(c.get("db"), {
+                grantType: "authorization_code",
+                code: body.code,
+                redirectUri: body.redirect_uri,
+                codeVerifier: body.code_verifier,
+                clientId: body.client_id,
+                clientSecret: body.client_secret,
+            })
+            : body.grant_type === "refresh_token"
+                ? await oauth.token(c.get("db"), {
+                    grantType: "refresh_token",
+                    refreshToken: body.refresh_token,
+                    clientId: body.client_id,
+                    clientSecret: body.client_secret,
+                })
+                : await oauth.token(c.get("db"), {
+                    grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
+                    installationId: body.installation_id,
+                    viewerId: body.viewer_id,
+                    viewerScopes: body.viewer_scopes,
+                    contextualScopes: body.contextual_scopes,
+                    clientId: body.client_id,
+                    clientSecret: body.client_secret,
+                });
+        return c.json(token, 200);
+    });
+    routes.post("/oauth/revoke-installation", async (c) => {
+        if (!oauth)
+            return c.json({ error: "App OAuth is not configured" }, 501);
+        const body = await parseJsonBody(c, appCredentialRevocationSchema);
+        const result = await oauth.revokeInstallationCredentials(c.get("db"), body.installationId, body.actorId);
+        return c.json(result, 200);
+    });
     routes.get("/:appId", async (c) => {
         const { appId } = parseParams(c.req.param());
         const app = await service.get(c.get("db"), appId);
@@ -51,6 +114,12 @@ export function createAppsAdminRoutes(options = {}) {
     });
     return routes;
 }
+function splitScopes(value) {
+    return value
+        .split(/[,\s]+/)
+        .map((scope) => scope.trim())
+        .filter(Boolean);
+}
 function parseParams(input) {
     const parsed = appIdParamSchema.safeParse(input);
     if (!parsed.success)