@boxxy/auth-oauth 0.2.6 → 0.2.8

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

@@ -1,221 +0,0 @@
-// 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-enrollment-state.ts

@@ -1,56 +0,0 @@
-// 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

@@ -1,28 +0,0 @@
-// 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

@@ -1,113 +0,0 @@
-// 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

@@ -1,48 +0,0 @@
-// 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/derive-token-hash.ts

@@ -1,7 +0,0 @@
-// 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');
-}

package/src/auth/is-allowed-redirect-uri.ts

@@ -1,19 +0,0 @@
-// Copied from atc: packages/mcp/src/auth/is-allowed-redirect-uri.ts at commit 4fe647cf.
-
-import { isLoopbackHost } from '../http/is-loopback-host.ts';
-
-export function isAllowedRedirectURI(raw: string): boolean {
-  let url: URL;
-
-  try {
-    url = new URL(raw);
-  } catch {
-    return false;
-  }
-
-  if (url.hash !== '' || url.username !== '' || url.password !== '') {
-    return false;
-  }
-
-  return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopbackHost(url.hostname));
-}

package/src/auth/load-web-authn.ts

@@ -1,19 +0,0 @@
-// Copied from atc: packages/mcp/src/auth/load-web-authn.ts at commit 4fe647cf.
-
-import type {
-  verifyAuthenticationResponse,
-  verifyRegistrationResponse,
-} from '@simplewebauthn/server';
-
-export interface WebAuthn {
-  readonly verifyAuthenticationResponse: typeof verifyAuthenticationResponse;
-  readonly verifyRegistrationResponse: typeof verifyRegistrationResponse;
-}
-
-export async function loadWebAuthn(): Promise<WebAuthn> {
-  // the library imports this polyfill itself, but a compiled binary's bundle runs
-  // its certificate code before that import, so the polyfill loads first.
-  await import('reflect-metadata');
-
-  return import('@simplewebauthn/server');
-}

package/src/auth/mcp-auth-database.ts

@@ -1,10 +0,0 @@
-// Copied from atc: packages/mcp/src/auth/mcp-auth-database.ts at commit 4fe647cf.
-
-import type { Dialect } from 'kysely';
-
-export interface MCPAuthDatabase {
-  readonly dialect: Dialect;
-
-  // releases the file, once Kysely is done with it.
-  readonly close: () => void;
-}

package/src/auth/mcp-auth-schema.ts

@@ -1,56 +0,0 @@
-// Copied from atc: packages/mcp/src/auth/mcp-auth-schema.ts at commit 4fe647cf.
-
-// only the columns boxxy reads and writes itself: better-auth owns the tables and
-// their migrations. Dates are ISO 8601 strings and string lists are JSON arrays.
-export interface MCPAuthSchema {
-  readonly oauthClient: {
-    readonly id: string;
-    readonly clientId: string;
-    readonly name: string | null;
-    readonly redirectUris: string;
-    readonly createdAt: string | null;
-  };
-  readonly oauthAccessToken: {
-    readonly id: string;
-    readonly token: string;
-    readonly clientId: string;
-    readonly sessionId: string | null;
-    readonly authorizationCodeId: string | null;
-  };
-  readonly oauthRefreshToken: {
-    readonly id: string;
-    readonly clientId: string;
-    readonly sessionId: string | null;
-    readonly authorizationCodeId: string | null;
-    readonly scopes: string;
-    readonly createdAt: string;
-    readonly expiresAt: string;
-    readonly revoked: string | null;
-  };
-  readonly oauthConsent: { readonly id: string; readonly clientId: string };
-  readonly oauthResource: { readonly identifier: string };
-  readonly session: { readonly id: string; readonly expiresAt: string };
-
-  // When each grant last reached /mcp, keyed by the grant's authorization code id.
-  readonly boxxy_grant_use: { readonly grant_id: string; readonly last_used_at: string };
-
-  // The owner's passkeys: the credential id and its COSE public key, both
-  // base64url, the signature counter the authenticator last returned, and
-  // its transports as a JSON array.
-  readonly boxxy_passkey: {
-    readonly id: string;
-    readonly public_key: string;
-    readonly counter: number;
-    readonly transports: string;
-    readonly created_at: string;
-    readonly last_used_at: string | null;
-  };
-
-  // The hash of each enrollment token a host command minted and no passkey
-  // has used yet.
-  readonly boxxy_enrollment_token: {
-    readonly token_hash: string;
-    readonly created_at: string;
-    readonly expires_at: string;
-  };
-}

package/src/auth/normalize-client-name.ts

@@ -1,22 +0,0 @@
-// Copied from atc: packages/mcp/src/auth/normalize-client-name.ts at commit 4fe647cf.
-
-export function normalizeClientName(
-  raw: unknown,
-  fallback = 'unnamed client',
-  maxLength = 100,
-): string {
-  if (typeof raw !== 'string') {
-    return fallback;
-  }
-
-  const folded = raw
-    .replaceAll(/[\t\n\v\f\r]/gu, ' ')
-    .replaceAll(/[\p{Cc}\p{Cf}]/gu, '')
-    .replaceAll(/\s+/gu, ' ')
-    .trim();
-
-  // The cut counts code points, so it never splits a surrogate pair.
-  const cut = folded.replace(new RegExp(`^(?<kept>.{${maxLength}}).+$`, 'su'), '$<kept>').trim();
-
-  return cut === '' ? fallback : cut;
-}