@boxxy/auth-oauth 0.0.0-stage → 0.2.1

package/src/auth/create-approval-state.ts

@@ -0,0 +1,221 @@
+// Copied from atc: packages/mcp/src/auth/create-approval-state.ts at commit 4fe647cf.
+
+import { randomBytes } from 'node:crypto';
+
+interface ApprovalRequest {
+  // The signed authorization query the login page carries: one per request.
+  readonly key: string;
+  readonly clientID: string;
+  readonly clientName: string;
+  readonly redirectURI: string;
+}
+
+interface PendingApproval extends ApprovalRequest {
+  // Random, minted with the approval and never taken from the request, so
+  // the security events of one authorization can be matched up.
+  readonly correlationID: string;
+  failures: number;
+  readonly expiresAt: number;
+
+  // The one WebAuthn challenge this request's login page holds, if any.
+  challenge: { readonly value: string; readonly expiresAt: number } | null;
+}
+
+export type TakenChallenge =
+  | { readonly kind: 'taken'; readonly challenge: string }
+  | { readonly kind: 'expired' }
+  | { readonly kind: 'missing' };
+
+// At most this many approvals wait at once across every client, and each
+// client holds at most this many. Across every client, at most this many
+// approvals start per minute.
+const MAX_PENDING = 16;
+const MAX_PENDING_PER_CLIENT = 3;
+const MAX_STARTS_PER_MINUTE = 10;
+const MAX_FAILURES = 5;
+const MINUTE_MS = 60_000;
+
+// How long a login page's challenge stays valid, unless its request
+// expires sooner.
+const CHALLENGE_MS = 5 * MINUTE_MS;
+
+interface ApprovedRequest {
+  readonly binding: string;
+  readonly correlationID: string;
+  readonly expiresAt: number;
+}
+
+export interface ApprovalState {
+  // Returns null when the last minute already holds its share of starts.
+  readonly createPending: (request: ApprovalRequest) => PendingApproval | null;
+
+  readonly findPending: (key: string) => PendingApproval | null;
+
+  // A fresh random challenge for the request's login page, replacing any
+  // earlier one, or null when the request no longer waits.
+  readonly mintChallenge: (key: string) => string | null;
+
+  // Takes the request's challenge, so it verifies at most one assertion.
+  readonly claimChallenge: (key: string) => TakenChallenge;
+
+  // A failed sign-in counts against the request; the last allowed failure
+  // drops it.
+  readonly recordFailure: (key: string) => 'retry' | 'locked';
+
+  readonly removePending: (key: string) => void;
+
+  readonly recordApproved: (
+    sessionID: string,
+    approved: Omit<ApprovedRequest, 'expiresAt'>,
+  ) => void;
+
+  // What an owner session approved, or null once it expired or went.
+  readonly findApproved: (sessionID: string) => ApprovedRequest | null;
+
+  readonly removeApproved: (sessionID: string) => void;
+}
+
+export function createApprovalState(pendingMs: number, now: () => number): ApprovalState {
+  const pending = new Map<string, PendingApproval>();
+
+  // Owner session id to the binding of the request its sign-in approved.
+  const approved = new Map<string, ApprovedRequest>();
+
+  // Approval start times within the last minute, oldest first.
+  let startedAt: readonly number[] = [];
+
+  const dropExpired = (at: number): void => {
+    for (const [key, approval] of pending) {
+      if (approval.expiresAt <= at) {
+        pending.delete(key);
+      }
+    }
+
+    for (const [sessionID, request] of approved) {
+      if (request.expiresAt <= at) {
+        approved.delete(sessionID);
+      }
+    }
+  };
+
+  const findPending = (key: string): PendingApproval | null => {
+    dropExpired(now());
+
+    return pending.get(key) ?? null;
+  };
+
+  return {
+    createPending: (request) => {
+      const current = now();
+
+      dropExpired(current);
+
+      startedAt = startedAt.filter((at) => current - at < MINUTE_MS);
+
+      if (startedAt.length >= MAX_STARTS_PER_MINUTE) {
+        return null;
+      }
+
+      const own = [...pending].filter(([, approval]) => approval.clientID === request.clientID);
+      const [ownOldest] = own;
+
+      // a new approval drops the oldest rather than being refused, so no client can
+      // hold the owner's approvals hostage.
+      if (own.length >= MAX_PENDING_PER_CLIENT && ownOldest !== undefined) {
+        pending.delete(ownOldest[0]);
+      }
+
+      const oldest = pending.keys().next();
+
+      if (pending.size >= MAX_PENDING && oldest.done !== true) {
+        pending.delete(oldest.value);
+      }
+
+      const approval: PendingApproval = {
+        ...request,
+        correlationID: crypto.randomUUID(),
+        failures: 0,
+        expiresAt: current + pendingMs,
+        challenge: null,
+      };
+
+      pending.set(approval.key, approval);
+
+      startedAt = [...startedAt, current];
+
+      return approval;
+    },
+
+    findPending,
+
+    mintChallenge: (key) => {
+      const approval = findPending(key);
+
+      if (approval === null) {
+        return null;
+      }
+
+      const value = randomBytes(32).toString('base64url');
+
+      approval.challenge = {
+        value,
+        expiresAt: Math.min(now() + CHALLENGE_MS, approval.expiresAt),
+      };
+
+      return value;
+    },
+
+    claimChallenge: (key) => {
+      const approval = findPending(key);
+      const challenge = approval?.challenge ?? null;
+
+      if (approval === null || challenge === null) {
+        return { kind: 'missing' };
+      }
+
+      approval.challenge = null;
+
+      if (challenge.expiresAt <= now()) {
+        return { kind: 'expired' };
+      }
+
+      return { kind: 'taken', challenge: challenge.value };
+    },
+
+    recordFailure: (key) => {
+      const approval = findPending(key);
+
+      if (approval === null) {
+        return 'locked';
+      }
+
+      approval.failures += 1;
+
+      if (approval.failures >= MAX_FAILURES) {
+        pending.delete(key);
+
+        return 'locked';
+      }
+
+      return 'retry';
+    },
+
+    removePending: (key) => {
+      pending.delete(key);
+    },
+
+    recordApproved: (sessionID, request) => {
+      approved.set(sessionID, { ...request, expiresAt: now() + pendingMs });
+    },
+
+    findApproved: (sessionID) => {
+      dropExpired(now());
+
+      return approved.get(sessionID) ?? null;
+    },
+
+    removeApproved: (sessionID) => {
+      approved.delete(sessionID);
+    },
+  };
+}

package/src/auth/create-auth-admin.ts

@@ -0,0 +1,78 @@
+import { PUBLIC_DOOR_PATHS } from '../http/public-door-paths.ts';
+import type { AuthClock } from '../utils/types.ts';
+import { createEnrollmentToken } from './create-enrollment-token.ts';
+import { isAllowedRedirectURI } from './is-allowed-redirect-uri.ts';
+import { normalizeClientName } from './normalize-client-name.ts';
+import type { openMCPAuth } from './open-mcp-auth.ts';
+import { readClientViews } from './read-client-views.ts';
+import type { ClientView } from './read-client-views.ts';
+import { readGrantViews } from './read-grant-views.ts';
+import type { GrantView } from './read-grant-views.ts';
+import { removeClient } from './remove-client.ts';
+import { revokeGrant } from './revoke-grant.ts';
+
+type MCPAuth = Awaited<ReturnType<typeof openMCPAuth>>;
+
+export interface AuthAdminInput {
+  readonly store: MCPAuth;
+  readonly origin: string;
+  readonly clock: AuthClock;
+}
+
+export type AddClientAnswer =
+  | { readonly kind: 'added'; readonly clientID: string; readonly name: string }
+  | { readonly kind: 'refused'; readonly redirectURI: string };
+
+export interface EnrollmentLink {
+  readonly token: string;
+  readonly link: string;
+  readonly expiresAt: number;
+}
+
+// What the owner's commands do to the authorization database: add and remove clients, revoke
+// grants, and mint the token that enrolls a passkey.
+export interface AuthAdmin {
+  readonly enroll: () => Promise<EnrollmentLink>;
+  readonly addClient: (name: string, redirectURIs: readonly string[]) => Promise<AddClientAnswer>;
+  readonly listClients: () => Promise<readonly ClientView[]>;
+  readonly removeClient: (clientID: string) => Promise<boolean>;
+  readonly listGrants: () => Promise<readonly GrantView[]>;
+  readonly revokeGrant: (grantID: string) => Promise<boolean>;
+}
+
+export function createAuthAdmin(input: AuthAdminInput): AuthAdmin {
+  const store = input.store;
+  const origin = input.origin;
+  const clock = input.clock;
+
+  return {
+    enroll: async () => {
+      const created = await createEnrollmentToken(store.db, clock.now());
+
+      return {
+        token: created.token,
+        link: `${origin}${PUBLIC_DOOR_PATHS.browser.enroll}?token=${created.token}`,
+        expiresAt: created.expiresAt,
+      };
+    },
+    addClient: async (name, redirectURIs) => {
+      const refused = redirectURIs.find((uri) => !isAllowedRedirectURI(uri));
+
+      if (refused !== undefined) {
+        return { kind: 'refused', redirectURI: refused };
+      }
+
+      const clientName = normalizeClientName(name);
+
+      const created = await store.auth.api.createFixedClient({
+        body: { name: clientName, redirectURIs: [...redirectURIs] },
+      });
+
+      return { kind: 'added', clientID: created.clientID, name: clientName };
+    },
+    listClients: () => readClientViews(store.db),
+    removeClient: (clientID) => removeClient(store.db, clientID),
+    listGrants: () => readGrantViews(store.db),
+    revokeGrant: (grantID) => revokeGrant(store.db, grantID),
+  };
+}

package/src/auth/create-enrollment-state.ts

@@ -0,0 +1,56 @@
+// Copied from atc: packages/mcp/src/auth/create-enrollment-state.ts at commit 4fe647cf.
+
+import { randomBytes } from 'node:crypto';
+import type { TakenChallenge } from './create-approval-state.ts';
+
+// At most this many enrollment challenges wait at once; a new one past the
+// limit drops the oldest.
+const MAX_CHALLENGES = 8;
+
+// How long an enrollment page's challenge stays valid.
+const CHALLENGE_MS = 5 * 60_000;
+
+export interface EnrollmentState {
+  readonly mintChallenge: (tokenHash: string) => string;
+
+  // Takes the token's challenge, so it verifies at most one registration.
+  readonly claimChallenge: (tokenHash: string) => TakenChallenge;
+}
+
+export function createEnrollmentState(now: () => number): EnrollmentState {
+  const challenges = new Map<string, { readonly value: string; readonly expiresAt: number }>();
+
+  return {
+    mintChallenge: (tokenHash) => {
+      challenges.delete(tokenHash);
+
+      const oldest = challenges.keys().next();
+
+      if (challenges.size >= MAX_CHALLENGES && oldest.done !== true) {
+        challenges.delete(oldest.value);
+      }
+
+      const value = randomBytes(32).toString('base64url');
+
+      challenges.set(tokenHash, { value, expiresAt: now() + CHALLENGE_MS });
+
+      return value;
+    },
+
+    claimChallenge: (tokenHash) => {
+      const challenge = challenges.get(tokenHash);
+
+      if (challenge === undefined) {
+        return { kind: 'missing' };
+      }
+
+      challenges.delete(tokenHash);
+
+      if (challenge.expiresAt <= now()) {
+        return { kind: 'expired' };
+      }
+
+      return { kind: 'taken', challenge: challenge.value };
+    },
+  };
+}

package/src/auth/create-enrollment-token.ts

@@ -0,0 +1,28 @@
+// Copied from atc: packages/mcp/src/auth/create-enrollment-token.ts at commit 4fe647cf.
+
+import { randomBytes } from 'node:crypto';
+import type { Kysely } from 'kysely';
+import { deriveTokenHash } from './derive-token-hash.ts';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+// How long an enrollment token stays usable after the host command mints it.
+const ENROLLMENT_TOKEN_MS = 15 * 60_000;
+
+export async function createEnrollmentToken(
+  db: Kysely<MCPAuthSchema>,
+  now: number,
+): Promise<{ readonly token: string; readonly expiresAt: number }> {
+  const token = `boxxy-enroll-${randomBytes(32).toString('base64url')}`;
+  const expiresAt = now + ENROLLMENT_TOKEN_MS;
+
+  await db
+    .insertInto('boxxy_enrollment_token')
+    .values({
+      token_hash: deriveTokenHash(token),
+      created_at: new Date(now).toISOString(),
+      expires_at: new Date(expiresAt).toISOString(),
+    })
+    .execute();
+
+  return { token, expiresAt };
+}

package/src/auth/create-owner-plugin.ts

@@ -0,0 +1,113 @@
+// Copied from atc: packages/mcp/src/auth/create-owner-plugin.ts at commit 4fe647cf.
+
+import { getOAuthProviderApi } from '@better-auth/oauth-provider';
+import { grantScopes } from '@boxxy/contract';
+import type { BetterAuthPlugin } from 'better-auth';
+import { createAuthEndpoint } from 'better-auth/api';
+import { setSessionCookie } from 'better-auth/cookies';
+import { generateRandomString } from 'better-auth/crypto';
+import { z } from 'zod';
+import { isAllowedRedirectURI } from './is-allowed-redirect-uri.ts';
+
+// boxxy has one user: the owner who runs it. better-auth needs an email for
+// every user, so the owner gets one no mail ever reaches.
+const OWNER_EMAIL = 'owner@boxxy.invalid';
+const REDIRECT_URI = z.string().refine(isAllowedRedirectURI);
+
+export function createOwnerPlugin() {
+  return {
+    id: 'boxxy-owner',
+
+    // every endpoint is server-only: better-auth refuses it over HTTP, so only boxxy's
+    // own routes reach it, after checking what it guards.
+    endpoints: {
+      signInOwner: createAuthEndpoint(
+        '/boxxy/sign-in-owner',
+        {
+          method: 'POST',
+          body: z.object({ oauth_query: z.string().optional() }),
+          metadata: { SERVER_ONLY: true },
+        },
+        async (ctx) => {
+          const adapter = ctx.context.internalAdapter;
+
+          const existing = await adapter.findUserByEmail(OWNER_EMAIL);
+
+          const user =
+            existing === null
+              ? await adapter.createUser(
+                  { email: OWNER_EMAIL, name: 'owner', emailVerified: true },
+                  { method: 'admin' },
+                )
+              : existing.user;
+
+          const session = await adapter.createSession(user.id);
+
+          await setSessionCookie(ctx, { session, user });
+
+          return ctx.json({ signedIn: true });
+        },
+      ),
+      verifyMCPAccessToken: createAuthEndpoint(
+        '/boxxy/verify-access-token',
+        {
+          method: 'POST',
+          body: z.object({ token: z.string() }),
+          metadata: { SERVER_ONLY: true },
+        },
+        async (ctx) => {
+          const provider = ctx.context.getPlugin('oauth-provider');
+
+          if (provider === null) {
+            throw new Error('the oauth-provider plugin is not installed');
+          }
+
+          const payload = await getOAuthProviderApi(ctx, provider.options).requireActiveAccessToken(
+            ctx.body.token,
+          );
+
+          return ctx.json(payload);
+        },
+      ),
+      createFixedClient: createAuthEndpoint(
+        '/boxxy/create-fixed-client',
+        {
+          method: 'POST',
+          body: z.object({
+            name: z.string().min(1),
+            redirectURIs: z.array(REDIRECT_URI).min(1),
+          }),
+          metadata: { SERVER_ONLY: true },
+        },
+        async (ctx) => {
+          const clientID = generateRandomString(32, 'a-z', 'A-Z', '0-9');
+
+          const now = new Date();
+
+          await ctx.context.adapter.create({
+            model: 'oauthClient',
+            data: {
+              clientId: clientID,
+              name: ctx.body.name,
+              redirectUris: ctx.body.redirectURIs,
+              scopes: [...grantScopes, 'offline_access'],
+              clientCredentialsScopes: [],
+              tokenEndpointAuthMethod: 'none',
+              grantTypes: ['authorization_code', 'refresh_token'],
+              responseTypes: ['code'],
+              applicationType: ctx.body.redirectURIs.every((uri) => uri.startsWith('https:'))
+                ? 'web'
+                : 'native',
+              requirePKCE: true,
+              disabled: false,
+              createdAt: now,
+              updatedAt: now,
+            },
+          });
+
+          return ctx.json({ clientID });
+        },
+      ),
+    },
+  } satisfies BetterAuthPlugin;
+}

package/src/auth/create-passkey.ts

@@ -0,0 +1,48 @@
+// Copied from atc: packages/mcp/src/auth/create-passkey.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export interface NewPasskey {
+  // The hash of the enrollment token the passkey was enrolled with.
+  readonly tokenHash: string;
+
+  // The credential id and its COSE public key, both base64url.
+  readonly id: string;
+  readonly publicKey: string;
+  readonly counter: number;
+  readonly transports: readonly string[];
+
+  // Epoch milliseconds.
+  readonly now: number;
+}
+
+export function createPasskey(db: Kysely<MCPAuthSchema>, passkey: NewPasskey): Promise<boolean> {
+  return db.transaction().execute(async (trx) => {
+    // spending the token in the same transaction as the insert lets one token
+    // enroll one passkey.
+    const spent = await trx
+      .deleteFrom('boxxy_enrollment_token')
+      .where('token_hash', '=', passkey.tokenHash)
+      .where('expires_at', '>', new Date(passkey.now).toISOString())
+      .executeTakeFirst();
+
+    if (spent.numDeletedRows === 0n) {
+      return false;
+    }
+
+    await trx
+      .insertInto('boxxy_passkey')
+      .values({
+        id: passkey.id,
+        public_key: passkey.publicKey,
+        counter: passkey.counter,
+        transports: JSON.stringify(passkey.transports),
+        created_at: new Date(passkey.now).toISOString(),
+        last_used_at: null,
+      })
+      .execute();
+
+    return true;
+  });
+}

package/src/auth/create-security-event-log.ts

@@ -0,0 +1,97 @@
+// Copied from atc: packages/mcp/src/auth/create-security-event-log.ts at commit 4fe647cf.
+
+import type { AuthClock } from '../utils/types.ts';
+import { formatSecurityEvent } from './format-security-event.ts';
+import type { SecurityEvent } from './types.ts';
+
+interface SecurityEventLogOptions {
+  // Receives each `{json}` line.
+  readonly print: (line: string) => void;
+  readonly clock: AuthClock;
+}
+
+interface KindWindow {
+  readonly startedAt: number;
+  printed: number;
+  dropped: number;
+  cancelFlush: (() => void) | null;
+}
+
+// Each kind prints at most this many events per window; the rest are
+// counted and written as one `suppressed` event when the window ends.
+const MAX_EVENTS_PER_WINDOW = 20;
+const WINDOW_MS = 60_000;
+
+export interface SecurityEventLog {
+  readonly record: (event: SecurityEvent) => void;
+  readonly drain: () => void;
+}
+
+export function createSecurityEventLog(opts: SecurityEventLogOptions): SecurityEventLog {
+  const windows = new Map<SecurityEvent['kind'], KindWindow>();
+
+  const printSuppressed = (
+    kind: SecurityEvent['kind'],
+    window: Readonly<KindWindow>,
+    now: number,
+  ): void => {
+    window.cancelFlush?.();
+
+    if (window.dropped > 0) {
+      opts.print(
+        formatSecurityEvent({ kind: 'suppressed', reason: kind, count: window.dropped }, now),
+      );
+    }
+  };
+
+  const drainEnded = (now: number): void => {
+    for (const [kind, window] of windows) {
+      if (now - window.startedAt >= WINDOW_MS) {
+        windows.delete(kind);
+
+        printSuppressed(kind, window, now);
+      }
+    }
+  };
+
+  return {
+    record: (event) => {
+      const now = opts.clock.now();
+
+      drainEnded(now);
+
+      let window = windows.get(event.kind);
+
+      if (window === undefined) {
+        window = { startedAt: now, printed: 0, dropped: 0, cancelFlush: null };
+
+        windows.set(event.kind, window);
+      }
+
+      if (window.printed < MAX_EVENTS_PER_WINDOW) {
+        window.printed++;
+
+        opts.print(formatSecurityEvent(event, now));
+
+        return;
+      }
+
+      window.dropped++;
+
+      window.cancelFlush ??= opts.clock.schedule(
+        () => {
+          drainEnded(opts.clock.now());
+        },
+        window.startedAt + WINDOW_MS - now,
+      );
+    },
+
+    drain: () => {
+      for (const [kind, window] of windows) {
+        printSuppressed(kind, window, opts.clock.now());
+      }
+
+      windows.clear();
+    },
+  };
+}

package/src/auth/derive-token-hash.ts

@@ -0,0 +1,7 @@
+// Copied from atc: packages/mcp/src/auth/derive-token-hash.ts at commit 4fe647cf.
+
+import { createHash } from 'node:crypto';
+
+export function deriveTokenHash(token: string): string {
+  return createHash('sha256').update(token).digest('base64url');
+}