@boxxy/auth-oauth 0.0.1 → 0.2.1

package/src/auth/verify-session-passkey.ts

@@ -0,0 +1,47 @@
+// Copied from atc: packages/mcp/src/auth/verify-session-passkey.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+interface SessionPasskey {
+  // The owner session a passkey sign-in just created.
+  readonly sessionID: string;
+
+  // The passkey whose assertion signed the owner in.
+  readonly passkeyID: string;
+}
+
+export async function verifySessionPasskey(
+  db: Kysely<MCPAuthSchema>,
+  check: SessionPasskey,
+): Promise<boolean> {
+  try {
+    return await db.transaction().execute(async (trx) => {
+      const passkey = await trx
+        .selectFrom('boxxy_passkey')
+        .select('id')
+        .where('id', '=', check.passkeyID)
+        .executeTakeFirst();
+
+      const session = await trx
+        .selectFrom('session')
+        .select('id')
+        .where('id', '=', check.sessionID)
+        .executeTakeFirst();
+
+      if (passkey !== undefined && session !== undefined) {
+        return true;
+      }
+
+      await trx.deleteFrom('session').where('id', '=', check.sessionID).execute();
+
+      return false;
+    });
+  } catch {
+    // a transaction that fails, such as one a concurrent write keeps busy, still
+    // removes the session.
+    await db.deleteFrom('session').where('id', '=', check.sessionID).execute();
+
+    return false;
+  }
+}

package/src/auth/write-grant-use.ts

@@ -0,0 +1,18 @@
+// Copied from atc: packages/mcp/src/auth/write-grant-use.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export async function writeGrantUse(
+  db: Kysely<MCPAuthSchema>,
+  grantID: string,
+  now: number,
+): Promise<void> {
+  const lastUsedAt = new Date(now).toISOString();
+
+  await db
+    .insertInto('boxxy_grant_use')
+    .values({ grant_id: grantID, last_used_at: lastUsedAt })
+    .onConflict((conflict) => conflict.column('grant_id').doUpdateSet({ last_used_at: lastUsedAt }))
+    .execute();
+}

package/src/http/answer-mcp-request.ts

@@ -0,0 +1,77 @@
+// Copied from atc: packages/mcp/src/http/answer-mcp-request.ts at commit 4fe647cf.
+
+import type { HTTPServerContext, Requester } from '../auth/types.ts';
+import { PUBLIC_DOOR_PATHS } from './public-door-paths.ts';
+import { verifyAccessToken } from './verify-access-token.ts';
+
+// What the MCP transport reads of a verified token: the scopes it holds, and the resource metadata
+// that a scope challenge points at.
+export interface McpAuthInfo {
+  readonly token: string;
+  readonly clientId: string;
+  readonly scopes: string[];
+  readonly resourceMetadataUrl: string;
+}
+
+// Serves one MCP request for a token that verified.
+export type McpServe = (request: Request, authInfo: McpAuthInfo) => Promise<Response>;
+
+// `requester` is where the request came from, for its security events.
+export async function answerMCPRequest(
+  ctx: HTTPServerContext,
+  request: Request,
+  requester: Requester,
+  serve: McpServe,
+): Promise<Response> {
+  const path = new URL(request.url).pathname;
+
+  const metadataURL = `${ctx.origin}${PUBLIC_DOOR_PATHS.machine.mcpResourceMetadata}`;
+  const authorization = request.headers.get('authorization');
+  const token = /^Bearer (?<token>\S+)$/iu.exec(authorization ?? '')?.groups?.['token'];
+
+  if (token === undefined) {
+    // a request with no header at all is a client discovering the
+    // authorization server, so only a header that holds no bearer token is
+    // recorded.
+    if (authorization !== null) {
+      ctx.security.record({
+        kind: 'bearer',
+        outcome: 'rejected',
+        reason: 'malformed',
+        path,
+        requester,
+      });
+    }
+
+    return new Response(null, {
+      status: 401,
+      headers: { 'www-authenticate': `Bearer resource_metadata="${metadataURL}"` },
+    });
+  }
+
+  const access = await verifyAccessToken(ctx, token);
+
+  if (access === null) {
+    ctx.security.record({
+      kind: 'bearer',
+      outcome: 'rejected',
+      reason: 'invalid_token',
+      path,
+      requester,
+    });
+
+    return new Response(null, {
+      status: 401,
+      headers: {
+        'www-authenticate': `Bearer error="invalid_token", resource_metadata="${metadataURL}"`,
+      },
+    });
+  }
+
+  return serve(request, {
+    token,
+    clientId: access.clientID,
+    scopes: [...access.scopes],
+    resourceMetadataUrl: metadataURL,
+  });
+}

package/src/http/build-page-response.ts

@@ -0,0 +1,26 @@
+// Copied from atc: packages/mcp/src/http/build-page-response.ts at commit 4fe647cf.
+
+import { toHTMLText } from '../auth/to-html-text.ts';
+
+export function buildPageResponse(
+  status: number,
+  body: { readonly page: string } | { readonly message: string },
+  formTargets: readonly string[] = [],
+  scriptSources: readonly string[] = [],
+): Response {
+  const html =
+    'page' in body
+      ? body.page
+      : `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>boxxy</title></head><body><p>${toHTMLText(body.message)}</p></body></html>`;
+
+  return new Response(html, {
+    status,
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'content-security-policy': `default-src 'none'; style-src 'unsafe-inline';${scriptSources.length === 0 ? '' : ` script-src ${scriptSources.join(' ')};`} form-action 'self'${formTargets.map((target) => ` ${target}`).join('')}; frame-ancestors 'none'; base-uri 'none'`,
+      'x-frame-options': 'DENY',
+      'cache-control': 'no-store',
+      'referrer-policy': 'same-origin',
+    },
+  });
+}

package/src/http/create-mcp-http-app.ts

@@ -0,0 +1,340 @@
+// Copied from atc: packages/mcp/src/http/create-mcp-http-app.ts at commit 4fe647cf.
+
+import { Elysia } from 'elysia';
+import invariant from 'tiny-invariant';
+import { match } from 'ts-pattern';
+import { answerAuthorizeRequest } from '../auth/answer-authorize-request.ts';
+import { answerConsentRequest } from '../auth/answer-consent-request.ts';
+import { answerEnrollRequest } from '../auth/answer-enroll-request.ts';
+import { answerLoginRequest } from '../auth/answer-login-request.ts';
+import { recordRefusedExchange } from '../auth/record-refused-exchange.ts';
+import type { HTTPServerContext, Requester, SecurityEvent } from '../auth/types.ts';
+import { isRecord } from '../utils/is-record.ts';
+import { answerMCPRequest } from './answer-mcp-request.ts';
+import type { McpServe } from './answer-mcp-request.ts';
+import { buildPageResponse } from './build-page-response.ts';
+import { pickErrorMessage } from './pick-error-message.ts';
+import { PUBLIC_DOOR_PATHS } from './public-door-paths.ts';
+
+interface MCPHTTPAppOptions {
+  // The Host header values the server answers to.
+  readonly hosts: ReadonlySet<string>;
+
+  // The origins a browser form or an MCP request may come from.
+  readonly origins: ReadonlySet<string>;
+
+  // The routes' context once the authorization server's database is open,
+  // and null before.
+  readonly readContext: () => HTTPServerContext | null;
+
+  // Where a request came from, for its security events.
+  readonly readRequester: (request: Request) => Requester;
+
+  // Answers an MCP request whose bearer token verified.
+  readonly serveMCP: McpServe;
+
+  // Receives each refused Host or origin.
+  readonly security: { readonly record: (event: SecurityEvent) => void };
+}
+
+// The browser pages: passkey sign-in, passkey enrollment, and consent.
+// the part of Elysia's context that the routes read
+interface RouteContext {
+  readonly request: Request;
+}
+
+const PAGE_PATHS = [
+  PUBLIC_DOOR_PATHS.browser.login,
+  PUBLIC_DOOR_PATHS.browser.enroll,
+  PUBLIC_DOOR_PATHS.browser.consent,
+] as const;
+
+// Both paths serve the protected resource metadata for `<origin>/mcp`.
+const RESOURCE_METADATA_PATHS = [
+  PUBLIC_DOOR_PATHS.machine.resourceMetadata,
+  PUBLIC_DOOR_PATHS.machine.mcpResourceMetadata,
+] as const;
+
+export function createMCPHTTPApp(options: MCPHTTPAppOptions) {
+  const requireContext = (): HTTPServerContext => {
+    const ctx = options.readContext();
+
+    invariant(ctx, 'a route ran before the authorization server opened');
+
+    return ctx;
+  };
+
+  const app = new Elysia()
+    .onRequest((context: RouteContext) => {
+      const path = new URL(context.request.url).pathname;
+
+      const host = context.request.headers.get('host');
+
+      if (host === null || !options.hosts.has(host)) {
+        options.security.record({
+          kind: 'authorize_invalid',
+          outcome: 'rejected',
+          reason: 'bad_host',
+          path,
+          requester: options.readRequester(context.request),
+        });
+
+        return new Response(null, { status: 403 });
+      }
+
+      // Elysia answers with any value a hook returns but undefined, null included
+      return options.readContext() === null ? new Response(null, { status: 503 }) : undefined;
+    })
+    .onError(() => new Response(null, { status: 503 }))
+    .post(PUBLIC_DOOR_PATHS.machine.revoke, (context: RouteContext) =>
+      requireContext().store.auth.handler(toPublicRequest(requireContext(), context.request)),
+    )
+    .get(PUBLIC_DOOR_PATHS.machine.authorizationServerMetadata, (context: RouteContext) =>
+      answerMetadataRequest(requireContext(), context.request, 'authorization-server'),
+    )
+    .get(PUBLIC_DOOR_PATHS.browser.authorize, (context: RouteContext) =>
+      answerAuthorizeRequest(
+        requireContext(),
+        new URL(context.request.url),
+        options.readRequester(context.request),
+      ),
+    )
+    .post(PUBLIC_DOOR_PATHS.machine.token, (context: RouteContext) =>
+      answerTokenRequest(requireContext(), context.request, options.readRequester(context.request)),
+    )
+    .get(PUBLIC_DOOR_PATHS.browser.error, (context: RouteContext) => {
+      const error = new URL(context.request.url).searchParams.get('error');
+
+      return buildPageResponse(400, { message: pickErrorMessage(error) });
+    });
+
+  for (const path of RESOURCE_METADATA_PATHS) {
+    app.get(path, (context: RouteContext) =>
+      answerMetadataRequest(requireContext(), context.request, 'resource'),
+    );
+  }
+
+  for (const path of PAGE_PATHS) {
+    app.get(path, (context: RouteContext) =>
+      answerPageRequest(requireContext(), {
+        path,
+        request: context.request,
+        body: '',
+        requester: options.readRequester(context.request),
+      }),
+    );
+
+    app.post(
+      path,
+      {
+        // a form posts from the server's own pages, so a post with no origin
+        // or another one is a forged form
+        beforeHandle: (context: RouteContext) => {
+          const origin = context.request.headers.get('origin');
+          const isForged = origin === null || !options.origins.has(origin);
+
+          if (isForged) {
+            recordBadOrigin(options, context.request);
+          }
+
+          return isForged
+            ? buildPageResponse(403, { message: 'The form came from an unexpected origin.' })
+            : undefined;
+        },
+      },
+      async (context: RouteContext) => {
+        const body = await context.request.text();
+
+        return answerPageRequest(requireContext(), {
+          path,
+          request: context.request,
+          body,
+          requester: options.readRequester(context.request),
+        });
+      },
+    );
+  }
+
+  app.all(
+    PUBLIC_DOOR_PATHS.machine.mcp,
+    {
+      beforeHandle: (context: RouteContext) => {
+        const origin = context.request.headers.get('origin');
+        const isForeign = origin !== null && !options.origins.has(origin);
+
+        if (isForeign) {
+          recordBadOrigin(options, context.request);
+        }
+
+        return isForeign ? new Response(null, { status: 403 }) : undefined;
+      },
+    },
+    (context: RouteContext) => {
+      if (context.request.method !== 'POST') {
+        return new Response(null, { status: 405, headers: { allow: 'POST' } });
+      }
+
+      return answerMCPRequest(
+        requireContext(),
+        context.request,
+        options.readRequester(context.request),
+        options.serveMCP,
+      );
+    },
+  );
+
+  // every other path, the RPC route and the health check included, answers 404
+  app.all('*', () => new Response(null, { status: 404 }));
+
+  return app;
+}
+
+// better-auth builds every URL it returns from its base URL, so a request
+// that reached the local address is handed over as if it came to the public
+// origin.
+function toPublicRequest(ctx: HTTPServerContext, request: Request): Request {
+  const url = new URL(request.url);
+
+  return new Request(`${ctx.origin}${url.pathname}${url.search}`, request);
+}
+
+// The metadata advertises only what boxxy's clients can use: public clients
+// with no client authentication, no introspection endpoint, and Bearer
+// tokens alone, so nothing about DPoP.
+async function answerMetadataRequest(
+  ctx: HTTPServerContext,
+  request: Request,
+  kind: 'authorization-server' | 'resource',
+): Promise<Response> {
+  const response = await ctx.store.auth.handler(toPublicRequest(ctx, request));
+  const metadata: unknown = await response.json();
+
+  if (!isRecord(metadata)) {
+    return new Response(null, { status: 503 });
+  }
+
+  const advertised = Object.fromEntries(
+    Object.entries(metadata).filter(
+      ([key]) => !key.startsWith('introspection_') && !key.startsWith('dpop_'),
+    ),
+  );
+
+  if (kind === 'resource') {
+    return Response.json(advertised, { status: response.status });
+  }
+
+  return Response.json({
+    ...advertised,
+    token_endpoint_auth_methods_supported: ['none'],
+    revocation_endpoint_auth_methods_supported: ['none'],
+  });
+}
+
+// better-auth binds a code exchange's tokens to the owner session that approved it.
+async function answerTokenRequest(
+  ctx: HTTPServerContext,
+  request: Request,
+  requester: Requester,
+): Promise<Response> {
+  // the body is read once here, so the refusal's event can name its client.
+  const body = await request.text();
+
+  const sent = new Request(request.url, { method: request.method, headers: request.headers, body });
+
+  const response = await ctx.store.auth.handler(toPublicRequest(ctx, sent));
+
+  if (!response.ok) {
+    await recordRefusedExchange(ctx, {
+      contentType: request.headers.get('content-type'),
+      body,
+      response,
+      path: new URL(request.url).pathname,
+      requester,
+    });
+
+    return response;
+  }
+
+  const attached = await ctx.store.db
+    .selectFrom('oauthAccessToken')
+    .select('sessionId')
+    .where('sessionId', 'is not', null)
+    .union(
+      ctx.store.db
+        .selectFrom('oauthRefreshToken')
+        .select('sessionId')
+        .where('sessionId', 'is not', null),
+    )
+    .execute();
+
+  const sessionIDs = attached.flatMap((row) => (row.sessionId === null ? [] : [row.sessionId]));
+
+  // detached tokens outlive their session, so a session's end never ends a grant.
+  await ctx.store.db
+    .updateTable('oauthAccessToken')
+    .set({ sessionId: null })
+    .where('sessionId', 'is not', null)
+    .execute();
+
+  await ctx.store.db
+    .updateTable('oauthRefreshToken')
+    .set({ sessionId: null })
+    .where('sessionId', 'is not', null)
+    .execute();
+
+  const now = new Date(ctx.clock.now()).toISOString();
+
+  // the session's one authorization is done.
+  await ctx.store.db
+    .deleteFrom('session')
+    .where((eb) =>
+      eb.or([
+        eb('expiresAt', '<', now),
+        ...(sessionIDs.length === 0 ? [] : [eb('id', 'in', sessionIDs)]),
+      ]),
+    )
+    .execute();
+
+  return response;
+}
+
+interface PageRequest {
+  readonly path: (typeof PAGE_PATHS)[number];
+  readonly request: Request;
+  readonly body: string;
+  readonly requester: Requester;
+}
+
+function answerPageRequest(ctx: HTTPServerContext, page: PageRequest): Promise<Response> {
+  const method = page.request.method === 'POST' ? 'POST' : 'GET';
+
+  const url = new URL(page.request.url);
+
+  return match(page.path)
+    .with(PUBLIC_DOOR_PATHS.browser.login, () =>
+      answerLoginRequest(ctx, { method, url, body: page.body, requester: page.requester }),
+    )
+    .with(PUBLIC_DOOR_PATHS.browser.enroll, () =>
+      answerEnrollRequest(ctx, { method, url, body: page.body, requester: page.requester }),
+    )
+    .with(PUBLIC_DOOR_PATHS.browser.consent, () =>
+      answerConsentRequest(ctx, {
+        method,
+        url,
+        cookie: page.request.headers.get('cookie'),
+        body: page.body,
+        requester: page.requester,
+      }),
+    )
+    .exhaustive();
+}
+
+function recordBadOrigin(options: MCPHTTPAppOptions, request: Request): void {
+  options.security.record({
+    kind: 'authorize_invalid',
+    outcome: 'rejected',
+    reason: 'bad_origin',
+    path: new URL(request.url).pathname,
+    requester: options.readRequester(request),
+  });
+}

package/src/http/create-public-door.ts

@@ -0,0 +1,150 @@
+// Adapted from atc: packages/mcp/src/http/start-mcp-http-server.ts at commit 4fe647cf.
+
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { APPROVAL_WINDOW_SECONDS } from '../auth/approval-window-seconds.ts';
+import { createApprovalState } from '../auth/create-approval-state.ts';
+import { createAuthAdmin } from '../auth/create-auth-admin.ts';
+import type { AuthAdmin } from '../auth/create-auth-admin.ts';
+import { createEnrollmentState } from '../auth/create-enrollment-state.ts';
+import { createSecurityEventLog } from '../auth/create-security-event-log.ts';
+import { openAuthDatabase } from '../auth/open-auth-database.ts';
+import { openMCPAuth } from '../auth/open-mcp-auth.ts';
+import type { HTTPServerContext, Requester } from '../auth/types.ts';
+import type { AuthClock } from '../utils/types.ts';
+import type { McpServe } from './answer-mcp-request.ts';
+import { createMCPHTTPApp } from './create-mcp-http-app.ts';
+import { isLoopbackHost } from './is-loopback-host.ts';
+import { normalizePublicURL } from './normalize-public-url.ts';
+import { PUBLIC_DOOR_PATHS } from './public-door-paths.ts';
+
+export interface PublicDoorOptions {
+  // The origin clients reach the door at: the OAuth issuer.
+  readonly publicURL: string;
+
+  // The address the door listens on, which decides whether the public URL has to be https.
+  readonly hostname: string;
+  readonly dbPath: string;
+
+  // The socket peers whose `CF-Connecting-IP` header a security event labels `trusted`, each
+  // exactly as the socket reports its address.
+  readonly trustForwardedFrom: readonly string[];
+
+  // Receives one JSON line per sign-in outcome or refused token.
+  readonly writeSecurityLine: (line: string) => void;
+
+  // The address of the socket a request came in on, or null.
+  readonly readPeer: (request: Request) => string | null;
+
+  // Answers an MCP request whose bearer token verified.
+  readonly serveMCP: McpServe;
+  readonly clock?: AuthClock;
+}
+
+export interface PublicDoor {
+  // Answers a request of the door; it serves nothing but the MCP and OAuth routes.
+  readonly answerRequest: (request: Request) => Promise<Response>;
+
+  // The door answers to the loopback address on this port as well as to its public host.
+  readonly addLocalPort: (port: number) => void;
+  readonly admin: AuthAdmin;
+  readonly stop: () => Promise<void>;
+}
+
+const systemClock: AuthClock = {
+  now: () => Date.now(),
+  schedule: (callback, delayMs) => {
+    const timer = setTimeout(callback, delayMs);
+
+    return () => {
+      clearTimeout(timer);
+    };
+  },
+};
+
+// Opens the authorization database and builds the door's routes. Throws on a public URL that is
+// not an https origin, or not a loopback address while the door listens beyond loopback.
+export async function createPublicDoor(options: PublicDoorOptions): Promise<PublicDoor> {
+  const clock = options.clock ?? systemClock;
+  const origin = normalizePublicURL(options.publicURL);
+
+  // The door speaks plain HTTP, so a listener other machines can reach sits behind something that
+  // terminates TLS, and the public URL clients use is that https origin.
+  if (!isLoopbackHost(options.hostname) && !origin.startsWith('https:')) {
+    throw new Error(
+      `listening on '${options.hostname}' reaches beyond this machine, so the public door needs an https public URL`,
+    );
+  }
+
+  const security = createSecurityEventLog({ print: options.writeSecurityLine, clock });
+
+  const trustedProxies: ReadonlySet<string> = new Set(options.trustForwardedFrom);
+
+  // The socket's peer is the requester, or the proxy or tunnel in front of the door. Only a listed
+  // peer vouches for the forwarded address.
+  const readRequester = (request: Request): Requester => {
+    const socketAddress = options.readPeer(request);
+    const connectingIP = request.headers.get('cf-connecting-ip');
+
+    return {
+      socketAddress,
+      connectingIP:
+        connectingIP === null
+          ? null
+          : {
+              address: connectingIP,
+              provenance:
+                socketAddress !== null && trustedProxies.has(socketAddress)
+                  ? 'trusted'
+                  : 'unverified',
+            },
+      userAgent: request.headers.get('user-agent'),
+    };
+  };
+
+  mkdirSync(dirname(options.dbPath), { recursive: true });
+
+  const store = await openMCPAuth({
+    dbPath: options.dbPath,
+    openDatabase: openAuthDatabase,
+    origin,
+  });
+
+  const hosts = new Set<string>([new URL(origin).host]);
+  const origins = new Set<string>([origin]);
+
+  const context: HTTPServerContext = {
+    origin,
+    resource: `${origin}${PUBLIC_DOOR_PATHS.machine.mcp}`,
+    store,
+    approvals: createApprovalState(APPROVAL_WINDOW_SECONDS * 1000, () => clock.now()),
+    enrollments: createEnrollmentState(() => clock.now()),
+    security,
+    clock,
+  };
+
+  const app = createMCPHTTPApp({
+    hosts,
+    origins,
+    readContext: () => context,
+    readRequester,
+    serveMCP: options.serveMCP,
+    security,
+  });
+
+  return {
+    answerRequest: (request) => app.handle(request),
+    addLocalPort: (port) => {
+      hosts.add(`127.0.0.1:${port}`);
+      hosts.add(`localhost:${port}`);
+      origins.add(`http://127.0.0.1:${port}`);
+      origins.add(`http://localhost:${port}`);
+    },
+    admin: createAuthAdmin({ store, origin, clock }),
+    stop: async () => {
+      await store.close();
+
+      security.drain();
+    },
+  };
+}

package/src/http/is-loopback-host.ts

@@ -0,0 +1,10 @@
+// Copied from atc: packages/mcp/src/http/is-loopback-host.ts at commit 4fe647cf.
+
+export function isLoopbackHost(host: string): boolean {
+  return (
+    host === 'localhost' ||
+    host === '::1' ||
+    host === '[::1]' ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/u.test(host)
+  );
+}