@boxxy/auth-oauth 0.0.1 → 0.2.2

package/src/http/normalize-public-url.ts

@@ -0,0 +1,29 @@
+// Copied from atc: packages/mcp/src/http/normalize-public-url.ts at commit 4fe647cf.
+
+import { isLoopbackHost } from './is-loopback-host.ts';
+
+export function normalizePublicURL(raw: string): string {
+  let url: URL;
+
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`the public URL '${raw}' is not a URL`);
+  }
+
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHost(url.hostname))) {
+    throw new Error(`the public URL '${raw}' must use https unless its host is loopback`);
+  }
+
+  if ((url.pathname !== '/' && url.pathname !== '') || url.search !== '' || url.hash !== '') {
+    throw new Error(
+      `the public URL '${raw}' must be a bare origin, with no path, query, or fragment`,
+    );
+  }
+
+  if (url.username !== '' || url.password !== '') {
+    throw new Error(`the public URL '${raw}' must not carry credentials`);
+  }
+
+  return url.origin;
+}

package/src/http/pick-error-message.ts

@@ -0,0 +1,21 @@
+// Copied from atc: packages/mcp/src/http/pick-error-message.ts at commit 4fe647cf.
+
+// The error codes better-auth sends to the error page, each with the fixed
+// sentence boxxy shows for it.
+const ERROR_MESSAGES: Readonly<Record<string, string>> = {
+  invalid_client: 'the client is not one added to boxxy.',
+  client_disabled: 'the client is disabled.',
+  invalid_redirect: 'the redirect URI is not one the client was added with.',
+  unauthorized_client: 'the client may not use the authorization code grant.',
+  unsupported_response_type: 'boxxy supports only the authorization code response type.',
+  invalid_request: 'the request is malformed.',
+};
+
+export function pickErrorMessage(code: string | null): string {
+  // the page never shows text from the request, so a link to it cannot make
+  // boxxy's origin display words an attacker chose.
+  const reason =
+    code !== null && Object.hasOwn(ERROR_MESSAGES, code) ? ERROR_MESSAGES[code] : undefined;
+
+  return `boxxy refused this authorization request: ${reason ?? 'the request is not valid.'}`;
+}

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

@@ -0,0 +1,21 @@
+// Adapted from atc: packages/contract/src/gateway-paths.ts at commit 4fe647cf.
+
+// The routes of the public door: the browser pages a person opens, and the routes a machine
+// client calls. The door serves nothing else.
+export const PUBLIC_DOOR_PATHS = {
+  browser: {
+    authorize: '/oauth2/authorize',
+    login: '/login',
+    enroll: '/enroll',
+    consent: '/consent',
+    error: '/error',
+  },
+  machine: {
+    mcp: '/mcp',
+    token: '/oauth2/token',
+    revoke: '/oauth2/revoke',
+    authorizationServerMetadata: '/.well-known/oauth-authorization-server',
+    resourceMetadata: '/.well-known/oauth-protected-resource',
+    mcpResourceMetadata: '/.well-known/oauth-protected-resource/mcp',
+  },
+} as const;

package/src/http/read-token-access.ts

@@ -0,0 +1,44 @@
+// Copied from atc: packages/mcp/src/http/read-token-access.ts at commit 4fe647cf.
+
+import { grantScopes } from '@boxxy/contract';
+import type { GrantScope } from '@boxxy/contract';
+import { isAPIError } from 'better-auth/api';
+import type { HTTPServerContext } from '../auth/types.ts';
+import { isRecord } from '../utils/is-record.ts';
+
+interface TokenAccess {
+  readonly clientID: string;
+  readonly scopes: readonly GrantScope[];
+}
+
+// An inactive, unknown, expired or revoked token, one bound to another
+// resource, or one without a client id reads as null. Reading records no use.
+export async function readTokenAccess(
+  ctx: HTTPServerContext,
+  token: string,
+): Promise<TokenAccess | null> {
+  let payload: unknown;
+
+  try {
+    payload = await ctx.store.auth.api.verifyMCPAccessToken({ body: { token } });
+  } catch (error) {
+    if (isAPIError(error)) {
+      return null;
+    }
+
+    throw error;
+  }
+
+  if (!isRecord(payload) || ![payload['aud']].flat().includes(ctx.resource)) {
+    return null;
+  }
+
+  const granted = typeof payload['scope'] === 'string' ? payload['scope'].split(' ') : [];
+  const clientID = typeof payload['client_id'] === 'string' ? payload['client_id'] : '';
+
+  if (clientID === '') {
+    return null;
+  }
+
+  return { clientID, scopes: grantScopes.filter((scope) => granted.includes(scope)) };
+}

package/src/http/verify-access-token.ts

@@ -0,0 +1,46 @@
+// Copied from atc: packages/mcp/src/http/verify-access-token.ts at commit 4fe647cf.
+
+import { deriveTokenHash } from '../auth/derive-token-hash.ts';
+import { normalizeClientName } from '../auth/normalize-client-name.ts';
+import { readClientName } from '../auth/read-client-name.ts';
+import type { HTTPServerContext, VerifiedAccess } from '../auth/types.ts';
+import { writeGrantUse } from '../auth/write-grant-use.ts';
+import { readTokenAccess } from './read-token-access.ts';
+
+// Verifying stamps when the token's grant was last used.
+export async function verifyAccessToken(
+  ctx: HTTPServerContext,
+  token: string,
+): Promise<VerifiedAccess | null> {
+  const access = await readTokenAccess(ctx, token);
+
+  if (access === null) {
+    return null;
+  }
+
+  await upsertGrantUse(ctx, token);
+
+  const storedName = await readClientName(ctx.store.db, access.clientID);
+
+  return {
+    clientID: access.clientID,
+    clientName: normalizeClientName(storedName, 'remote'),
+    scopes: access.scopes,
+  };
+}
+
+async function upsertGrantUse(ctx: HTTPServerContext, token: string): Promise<void> {
+  const row = await ctx.store.db
+    .selectFrom('oauthAccessToken')
+    .select('authorizationCodeId')
+    .where('token', '=', deriveTokenHash(token))
+    .executeTakeFirst();
+
+  const grantID = row?.authorizationCodeId ?? null;
+
+  if (grantID === null) {
+    return;
+  }
+
+  await writeGrantUse(ctx.store.db, grantID, ctx.clock.now());
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { AddClientAnswer, AuthAdmin, EnrollmentLink } from './auth/create-auth-admin.ts';
+export type { McpAuthInfo, McpServe } from './http/answer-mcp-request.ts';
+export type { PublicDoor, PublicDoorOptions } from './http/create-public-door.ts';
+export { createPublicDoor } from './http/create-public-door.ts';
+export type { ClientView } from './auth/read-client-views.ts';
+export type { GrantView } from './auth/read-grant-views.ts';
+export type { VerifiedAccess } from './auth/types.ts';
+export { isLoopbackHost } from './http/is-loopback-host.ts';

package/src/test-utils/authorize-test-client.ts

@@ -0,0 +1,194 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import type { PublicDoor } from '../http/create-public-door.ts';
+import { buildStubAuthenticator } from './build-stub-authenticator.ts';
+
+interface AuthorizeInput {
+  // the origin the door was created with, such as `https://boxxy.example`
+  readonly origin: string;
+
+  // the scopes the client asks for, and the ones the owner ticks on the consent page
+  readonly requested: readonly string[];
+  readonly ticked: readonly string[];
+}
+
+export interface TestGrant {
+  readonly clientID: string;
+  readonly accessToken: string;
+  readonly refreshToken: string;
+}
+
+const tokenSchema = z.object({ access_token: z.string(), refresh_token: z.string() });
+
+// Runs the whole sign-in against a door, the way a client and the owner's browser would: enrolls a
+// passkey, adds a client, then authorizes it with a passkey sign-in, consent and a code exchange.
+export async function authorizeTestClient(
+  door: PublicDoor,
+  input: AuthorizeInput,
+): Promise<TestGrant> {
+  const authenticator = buildStubAuthenticator();
+
+  const host = new URL(input.origin).host;
+
+  const redirectURI = 'https://client.example/callback';
+
+  const send = (path: string, init: RequestInit & { readonly cookie?: string } = {}) => {
+    const headers = new Headers(init.headers);
+
+    headers.set('host', host);
+
+    if (init.method === 'POST') {
+      headers.set('origin', input.origin);
+    }
+
+    if (init.cookie !== undefined) {
+      headers.set('cookie', init.cookie);
+    }
+
+    return door.answerRequest(new Request(`${input.origin}${path}`, { ...init, headers }));
+  };
+
+  const postForm = (
+    path: string,
+    fields: Readonly<Record<string, string | string[]>>,
+    cookie?: string,
+  ) => {
+    const body = new URLSearchParams();
+
+    for (const [name, value] of Object.entries(fields)) {
+      for (const item of [value].flat()) {
+        body.append(name, item);
+      }
+    }
+
+    return send(path, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+      ...(cookie === undefined ? {} : { cookie }),
+    });
+  };
+
+  const enrollment = await door.admin.enroll();
+  const enrolling = await postForm('/enroll', { token: enrollment.token });
+  const enrollingPage = await enrolling.text();
+
+  const creation = readOptions(enrollingPage);
+
+  const registration = await authenticator.create(
+    {
+      challenge: String(creation['challenge']),
+      rp: { id: new URL(input.origin).hostname },
+      user: { id: 'b3duZXI' },
+    },
+    { origin: input.origin },
+  );
+
+  const enrolled = await postForm('/enroll', {
+    token: enrollment.token,
+    credential: JSON.stringify(registration),
+  });
+
+  if (enrolled.status !== 200) {
+    throw new Error(`the stub passkey did not enroll: ${enrolled.status}`);
+  }
+
+  const added = await door.admin.addClient('test client', [redirectURI]);
+
+  if (added.kind !== 'added') {
+    throw new Error('the test client was refused');
+  }
+
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+
+  const authorizeQuery = new URLSearchParams({
+    response_type: 'code',
+    client_id: added.clientID,
+    redirect_uri: redirectURI,
+    scope: input.requested.join(' '),
+    state: 'state-1',
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+  });
+
+  const authorized = await send(`/oauth2/authorize?${authorizeQuery.toString()}`);
+
+  const loginLocation = new URL(authorized.headers.get('location') ?? '', input.origin);
+
+  const oauthQuery = loginLocation.search.slice(1);
+
+  const loginPage = await send(`${loginLocation.pathname}${loginLocation.search}`);
+  const loginHtml = await loginPage.text();
+
+  const request = readOptions(loginHtml);
+
+  const assertion = await authenticator.signAssertion(
+    { challenge: String(request['challenge']), rpId: new URL(input.origin).hostname },
+    { origin: input.origin },
+  );
+
+  const signedIn = await postForm('/login', {
+    oauth_query: oauthQuery,
+    credential: JSON.stringify(assertion),
+  });
+
+  const cookie = signedIn.headers
+    .getSetCookie()
+    .map((line) => line.split(';')[0])
+    .join('; ');
+
+  const consentLocation = new URL(signedIn.headers.get('location') ?? '', input.origin);
+
+  const consented = await postForm(
+    '/consent',
+    {
+      oauth_query: consentLocation.search.slice(1),
+      decision: 'approve',
+      scope: [...input.ticked],
+    },
+    cookie,
+  );
+
+  const code = new URL(consented.headers.get('location') ?? '', redirectURI).searchParams.get(
+    'code',
+  );
+
+  if (code === null) {
+    throw new Error(`the consent issued no code: ${consented.status}`);
+  }
+
+  const exchanged = await postForm('/oauth2/token', {
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectURI,
+    client_id: added.clientID,
+    code_verifier: verifier,
+    resource: `${input.origin}/mcp`,
+  });
+
+  const exchangedBody: unknown = await exchanged.json();
+
+  const tokens = tokenSchema.parse(exchangedBody);
+
+  return {
+    clientID: added.clientID,
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+  };
+}
+
+const scriptSchema = z.object({ options: z.record(z.string(), z.unknown()) });
+
+// The WebAuthn options that a page carries in its passkey script block.
+function readOptions(page: string): Record<string, unknown> {
+  const block = /<script type="application\/json" id="boxxy-passkey">(?<json>.*?)<\/script>/su.exec(
+    page,
+  )?.groups?.['json'];
+
+  if (block === undefined) {
+    throw new Error('the page carries no passkey options');
+  }
+
+  return scriptSchema.parse(JSON.parse(block.replaceAll(String.raw`\u003c`, '<'))).options;
+}

package/src/test-utils/build-mock-new-passkey.ts

@@ -0,0 +1,15 @@
+// Copied from atc: packages/mcp/src/test-utils/build-mock-new-passkey.ts at commit 4fe647cf.
+
+import type { NewPasskey } from '../auth/create-passkey.ts';
+
+export function buildMockNewPasskey(overrides: Partial<NewPasskey> = {}): NewPasskey {
+  return {
+    tokenHash: 'a'.repeat(64),
+    id: 'credential-0001',
+    publicKey: 'AQID',
+    counter: 0,
+    transports: ['internal'],
+    now: Date.parse('2026-01-01T00:00:00Z'),
+    ...overrides,
+  };
+}

package/src/test-utils/build-passkey-seeder.ts

@@ -0,0 +1,11 @@
+// Copied from atc: packages/mcp/src/test-utils/build-passkey-seeder.ts at commit 4fe647cf.
+
+import { seedPasskey } from './seed-passkey.ts';
+import type { PasskeyInput } from './seed-passkey.ts';
+import type { MCPAuthSeedDeps } from './types.ts';
+
+export function buildPasskeySeeder(deps: MCPAuthSeedDeps) {
+  return {
+    passkey: (input?: PasskeyInput) => seedPasskey(deps, input),
+  };
+}

package/src/test-utils/build-seeder.ts

@@ -0,0 +1,10 @@
+// Copied from atc: packages/mcp/src/test-utils/build-seeder.ts at commit 4fe647cf.
+
+import { buildPasskeySeeder } from './build-passkey-seeder.ts';
+import type { MCPAuthSeedDeps } from './types.ts';
+
+export type TestDeps = MCPAuthSeedDeps;
+
+export function buildSeeder(deps: TestDeps) {
+  return buildPasskeySeeder(deps);
+}

package/src/test-utils/build-stub-authenticator.ts

@@ -0,0 +1,244 @@
+// Copied from atc: packages/test-utils/src/build-stub-authenticator.ts at commit 4fe647cf.
+
+import { createHash, randomBytes } from 'node:crypto';
+
+// The parts of the creation and request options a browser passes to
+// navigator.credentials that an authenticator reads.
+interface CreationOptions {
+  readonly challenge: string;
+  readonly rp: { readonly id?: string };
+  readonly user: { readonly id: string };
+}
+
+interface RequestOptions {
+  readonly challenge: string;
+  readonly rpId?: string;
+}
+
+// What a browser and its authenticator put in a response, each defaulting
+// to the honest value: the page's origin as given, the RP ID the options
+// hold, and a verified user.
+interface Ceremony {
+  readonly origin: string;
+  readonly rpID?: string;
+  readonly userVerified?: boolean;
+}
+
+export interface StubRegistration {
+  readonly id: string;
+  readonly rawId: string;
+  readonly type: 'public-key';
+  readonly response: {
+    readonly clientDataJSON: string;
+    readonly attestationObject: string;
+    readonly transports: readonly string[];
+  };
+  readonly clientExtensionResults: Readonly<Record<string, never>>;
+  readonly authenticatorAttachment: 'platform';
+}
+
+export interface StubAssertion {
+  readonly id: string;
+  readonly rawId: string;
+  readonly type: 'public-key';
+  readonly response: {
+    readonly clientDataJSON: string;
+    readonly authenticatorData: string;
+    readonly signature: string;
+    readonly userHandle: string;
+  };
+  readonly clientExtensionResults: Readonly<Record<string, never>>;
+}
+
+const FLAG_AT = 0x40;
+
+type CBORValue = number | string | Buffer | ReadonlyMap<number | string, CBORValue>;
+
+export function buildStubAuthenticator() {
+  const credentialID = randomBytes(16);
+
+  const keys = crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, [
+    'sign',
+    'verify',
+  ]);
+
+  let userHandle: string | null = null;
+  let counter = 0;
+
+  return {
+    credentialID: credentialID.toString('base64url'),
+    async create(options: CreationOptions, ceremony: Ceremony): Promise<StubRegistration> {
+      const pair = await keys;
+      const jwk = await crypto.subtle.exportKey('jwk', pair.publicKey);
+
+      userHandle = options.user.id;
+
+      // A COSE EC2 key: kty 2, alg -7 (ES256), crv 1 (P-256), x, y.
+      const coseKey = encodeCBOR(
+        new Map<number, CBORValue>([
+          [1, 2],
+          [3, -7],
+          [-1, 1],
+          [-2, Buffer.from(jwk.x ?? '', 'base64url')],
+          [-3, Buffer.from(jwk.y ?? '', 'base64url')],
+        ]),
+      );
+
+      const length = Buffer.alloc(2);
+
+      length.writeUInt16BE(credentialID.length);
+
+      const authData = Buffer.concat([
+        buildAuthenticatorHeader(ceremony.rpID ?? options.rp.id ?? '', ceremony, 0, FLAG_AT),
+        Buffer.alloc(16),
+        length,
+        credentialID,
+        coseKey,
+      ]);
+
+      const attestationObject = encodeCBOR(
+        new Map<string, CBORValue>([
+          ['fmt', 'none'],
+          ['attStmt', new Map()],
+          ['authData', authData],
+        ]),
+      );
+
+      return {
+        id: credentialID.toString('base64url'),
+        rawId: credentialID.toString('base64url'),
+        type: 'public-key',
+        response: {
+          clientDataJSON: buildClientData('webauthn.create', options.challenge, ceremony),
+          attestationObject: attestationObject.toString('base64url'),
+          transports: ['internal'],
+        },
+        clientExtensionResults: {},
+        authenticatorAttachment: 'platform',
+      };
+    },
+    async signAssertion(options: RequestOptions, ceremony: Ceremony): Promise<StubAssertion> {
+      if (userHandle === null) {
+        throw new Error('the stub authenticator holds no credential yet');
+      }
+
+      const pair = await keys;
+
+      counter += 1;
+
+      const authenticatorData = buildAuthenticatorHeader(
+        ceremony.rpID ?? options.rpId ?? '',
+        ceremony,
+        counter,
+        0,
+      );
+
+      const clientDataJSON = buildClientData('webauthn.get', options.challenge, ceremony);
+
+      const signed = Buffer.concat([
+        authenticatorData,
+        createHash('sha256').update(Buffer.from(clientDataJSON, 'base64url')).digest(),
+      ]);
+
+      const raw = await crypto.subtle.sign(
+        { name: 'ECDSA', hash: 'SHA-256' },
+        pair.privateKey,
+        signed,
+      );
+
+      return {
+        id: credentialID.toString('base64url'),
+        rawId: credentialID.toString('base64url'),
+        type: 'public-key',
+        response: {
+          clientDataJSON,
+          authenticatorData: authenticatorData.toString('base64url'),
+          signature: toDERSignature(Buffer.from(raw)).toString('base64url'),
+          userHandle,
+        },
+        clientExtensionResults: {},
+      };
+    },
+  };
+}
+
+// The CBOR subset a COSE key and a `none` attestation need: integers,
+// byte strings, text strings, and maps.
+function encodeCBOR(value: CBORValue): Buffer {
+  if (typeof value === 'number') {
+    return value >= 0 ? encodeCBORHead(0, value) : encodeCBORHead(1, -1 - value);
+  }
+
+  if (typeof value === 'string') {
+    const text = Buffer.from(value);
+
+    return Buffer.concat([encodeCBORHead(3, text.length), text]);
+  }
+
+  if (Buffer.isBuffer(value)) {
+    return Buffer.concat([encodeCBORHead(2, value.length), value]);
+  }
+
+  return Buffer.concat([
+    encodeCBORHead(5, value.size),
+    ...[...value].flatMap(([key, item]) => [encodeCBOR(key), encodeCBOR(item)]),
+  ]);
+}
+
+function encodeCBORHead(major: number, length: number): Buffer {
+  if (length < 24) {
+    return Buffer.from([(major << 5) | length]);
+  }
+
+  if (length < 256) {
+    return Buffer.from([(major << 5) | 24, length]);
+  }
+
+  const head = Buffer.alloc(3);
+
+  head.writeUInt8((major << 5) | 25);
+  head.writeUInt16BE(length, 1);
+
+  return head;
+}
+
+const FLAG_UP = 0x01;
+const FLAG_UV = 0x04;
+
+// The RP ID hash, the flags with user presence always set, and the
+// big-endian signature counter.
+function buildAuthenticatorHeader(
+  rpID: string,
+  ceremony: Ceremony,
+  signCount: number,
+  extraFlags: number,
+): Buffer {
+  const flags = FLAG_UP | (ceremony.userVerified === false ? 0 : FLAG_UV) | extraFlags;
+  const count = Buffer.alloc(4);
+
+  count.writeUInt32BE(signCount);
+
+  return Buffer.concat([createHash('sha256').update(rpID).digest(), Buffer.from([flags]), count]);
+}
+
+function buildClientData(type: string, challenge: string, ceremony: Ceremony): string {
+  return Buffer.from(
+    JSON.stringify({ type, challenge, origin: ceremony.origin, crossOrigin: false }),
+  ).toString('base64url');
+}
+
+// WebCrypto signs ECDSA as r and s side by side; WebAuthn carries the
+// signature as an ASN.1 DER sequence of two integers.
+function toDERSignature(raw: Buffer): Buffer {
+  const integers = [raw.subarray(0, 32), raw.subarray(32)].map((part) => {
+    const start = part.findIndex((byte) => byte !== 0);
+    const trimmed = start === -1 ? Buffer.from([0]) : part.subarray(start);
+    const value = (trimmed[0] ?? 0) >= 0x80 ? Buffer.concat([Buffer.from([0]), trimmed]) : trimmed;
+
+    return Buffer.concat([Buffer.from([0x02, value.length]), value]);
+  });
+
+  const body = Buffer.concat(integers);
+
+  return Buffer.concat([Buffer.from([0x30, body.length]), body]);
+}