@boxxy/auth-oauth 0.0.1 → 0.2.2

package/src/auth/remove-owner-session.ts

@@ -0,0 +1,11 @@
+// Copied from atc: packages/mcp/src/auth/remove-owner-session.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export async function removeOwnerSession(
+  db: Kysely<MCPAuthSchema>,
+  sessionID: string,
+): Promise<void> {
+  await db.deleteFrom('session').where('id', '=', sessionID).execute();
+}

package/src/auth/render-consent-page.ts

@@ -0,0 +1,61 @@
+// Copied from atc: packages/mcp/src/auth/render-consent-page.ts at commit 4fe647cf.
+
+import type { GrantScope } from '@boxxy/contract';
+import { PUBLIC_DOOR_PATHS } from '../http/public-door-paths.ts';
+import { toHTMLText } from './to-html-text.ts';
+
+interface ConsentPageView {
+  // The signed authorization query the page posts back.
+  readonly oauthQuery: string;
+  readonly clientName: string;
+  readonly redirectURI: string;
+  readonly scopes: readonly GrantScope[];
+}
+
+const SCOPE_LABELS: Readonly<Record<GrantScope, string>> = {
+  read: 'Read items, their cost and times, and the runner status',
+  write:
+    'File and change items, add notes, retry, wake and close them, and pause or resume the runner',
+};
+
+// Only reading starts granted; every scope that lets the client act starts
+// withheld.
+const GRANTED_BY_DEFAULT: ReadonlySet<GrantScope> = new Set<GrantScope>(['read']);
+
+export function renderConsentPage(view: ConsentPageView): string {
+  const scopeRows = view.scopes
+    .map((scope) => {
+      const checked = GRANTED_BY_DEFAULT.has(scope) ? ' checked' : '';
+
+      return `<label><input type="checkbox" name="scope" value="${scope}"${checked}> ${toHTMLText(SCOPE_LABELS[scope])}</label>`;
+    })
+    .join('\n');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Choose what to allow</title>
+<style>
+body { font-family: system-ui, sans-serif; max-width: 32rem; margin: 3rem auto; padding: 0 1rem; line-height: 1.5; }
+label { display: block; margin: 0.25rem 0; }
+code { word-break: break-all; }
+button { font: inherit; margin-right: 0.5rem; }
+</style>
+</head>
+<body>
+<h1>Choose what to allow</h1>
+<p><strong>${toHTMLText(view.clientName)}</strong> returns to <code>${toHTMLText(view.redirectURI)}</code> with the access you allow here.</p>
+<form method="post" action="${PUBLIC_DOOR_PATHS.browser.consent}">
+<input type="hidden" name="oauth_query" value="${toHTMLText(view.oauthQuery)}">
+<fieldset>
+<legend>Allow it to</legend>
+${scopeRows}
+</fieldset>
+<p><button type="submit" name="decision" value="approve">Allow</button><button type="submit" name="decision" value="deny">Deny</button></p>
+</form>
+</body>
+</html>
+`;
+}

package/src/auth/render-enroll-page.ts

@@ -0,0 +1,59 @@
+// Copied from atc: packages/mcp/src/auth/render-enroll-page.ts at commit 4fe647cf.
+
+import { PUBLIC_DOOR_PATHS } from '../http/public-door-paths.ts';
+import { PASSKEY_SCRIPT } from './passkey-script.ts';
+import { toHTMLText } from './to-html-text.ts';
+import { toScriptJSON } from './to-script-json.ts';
+
+interface EnrollPageView {
+  // The enrollment token the owner typed, once it checked out, with the
+  // WebAuthn creation options for its challenge; null asks for the token.
+  readonly ceremony: { readonly token: string; readonly options: unknown } | null;
+  readonly error: string | null;
+
+  // The token a link carried, to fill in the form; absent when the owner types it
+  readonly prefill?: string;
+}
+
+export function renderEnrollPage(view: EnrollPageView): string {
+  const error = view.error === null ? '' : `<p class="error">${toHTMLText(view.error)}</p>`;
+
+  const step =
+    view.ceremony === null
+      ? `<p>Type the enrollment token that <code>boxxy auth enroll</code> printed, or open the link it printed.</p>
+<form method="post" action="${PUBLIC_DOOR_PATHS.browser.enroll}">
+<label>Enrollment token <input name="token" autocomplete="off" autofocus required${view.prefill === undefined ? '' : ` value="${toHTMLText(view.prefill)}"`}></label>
+<button type="submit">Continue</button>
+</form>`
+      : `<p>Create a passkey for boxxy. Your device asks you to verify yourself.</p>
+<script type="application/json" id="boxxy-passkey">${toScriptJSON({ mode: 'create', options: view.ceremony.options })}</script>
+<form method="post" action="${PUBLIC_DOOR_PATHS.browser.enroll}" id="boxxy-passkey-form">
+<input type="hidden" name="token" value="${toHTMLText(view.ceremony.token)}">
+<input type="hidden" name="credential" value="">
+<button type="button" id="boxxy-passkey-start" autofocus>Create a passkey</button>
+</form>
+<p id="boxxy-passkey-status" class="error" role="status"></p>
+<script>${PASSKEY_SCRIPT.source}</script>`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Enroll a passkey for boxxy</title>
+<style>
+body { font-family: system-ui, sans-serif; max-width: 32rem; margin: 3rem auto; padding: 0 1rem; line-height: 1.5; }
+input[name="token"] { font: inherit; font-family: ui-monospace, monospace; padding: 0.25rem; width: 100%; }
+.error { color: #b00020; }
+code { word-break: break-all; }
+button { font: inherit; }
+</style>
+</head>
+<body>
+<h1>Enroll a passkey for boxxy</h1>
+${error}
+${step}
+</body>
+</html>
+`;
+}

package/src/auth/render-login-page.ts

@@ -0,0 +1,58 @@
+// Copied from atc: packages/mcp/src/auth/render-login-page.ts at commit 4fe647cf.
+
+import { PUBLIC_DOOR_PATHS } from '../http/public-door-paths.ts';
+import { PASSKEY_SCRIPT } from './passkey-script.ts';
+import { toHTMLText } from './to-html-text.ts';
+import { toScriptJSON } from './to-script-json.ts';
+
+interface LoginPageView {
+  // The signed authorization query the page posts back.
+  readonly oauthQuery: string;
+  readonly clientName: string;
+  readonly redirectURI: string;
+
+  // The WebAuthn request options for this page's challenge, or null when
+  // no passkey is enrolled, so there is nothing to sign in with.
+  readonly options: unknown;
+  readonly error: string | null;
+}
+
+export function renderLoginPage(view: LoginPageView): string {
+  const error = view.error === null ? '' : `<p class="error">${toHTMLText(view.error)}</p>`;
+
+  const signIn =
+    view.options === null
+      ? `<p class="error">No passkey is enrolled, so nobody can sign in. On the host that runs boxxy, run <code>boxxy auth enroll</code>, then follow what it prints.</p>`
+      : `<script type="application/json" id="boxxy-passkey">${toScriptJSON({ mode: 'get', options: view.options })}</script>
+<form method="post" action="${PUBLIC_DOOR_PATHS.browser.login}" id="boxxy-passkey-form">
+<input type="hidden" name="oauth_query" value="${toHTMLText(view.oauthQuery)}">
+<input type="hidden" name="credential" value="">
+<button type="button" id="boxxy-passkey-start" autofocus>Sign in with a passkey</button>
+</form>
+<p id="boxxy-passkey-status" class="error" role="status"></p>
+<script>${PASSKEY_SCRIPT.source}</script>`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Sign in to boxxy</title>
+<style>
+body { font-family: system-ui, sans-serif; max-width: 32rem; margin: 3rem auto; padding: 0 1rem; line-height: 1.5; }
+.error { color: #b00020; }
+code { word-break: break-all; }
+button { font: inherit; }
+</style>
+</head>
+<body>
+<h1>Sign in to boxxy</h1>
+<p><strong>${toHTMLText(view.clientName)}</strong> wants access to your boxxy work.</p>
+<p>After approval it returns to <code>${toHTMLText(view.redirectURI)}</code>.</p>
+<p>Sign in with your passkey. You choose what to allow on the next page.</p>
+${error}
+${signIn}
+</body>
+</html>
+`;
+}

package/src/auth/revoke-grant.ts

@@ -0,0 +1,25 @@
+// Copied from atc: packages/mcp/src/auth/revoke-grant.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export function revokeGrant(db: Kysely<MCPAuthSchema>, grantID: string): Promise<boolean> {
+  return db.transaction().execute(async (trx) => {
+    const grant = await trx
+      .selectFrom('oauthRefreshToken')
+      .select('clientId')
+      .where('authorizationCodeId', '=', grantID)
+      .executeTakeFirst();
+
+    if (grant === undefined) {
+      return false;
+    }
+
+    await trx.deleteFrom('oauthAccessToken').where('authorizationCodeId', '=', grantID).execute();
+    await trx.deleteFrom('oauthRefreshToken').where('authorizationCodeId', '=', grantID).execute();
+    await trx.deleteFrom('oauthConsent').where('clientId', '=', grant.clientId).execute();
+    await trx.deleteFrom('boxxy_grant_use').where('grant_id', '=', grantID).execute();
+
+    return true;
+  });
+}

package/src/auth/to-html-text.ts

@@ -0,0 +1,10 @@
+// Copied from atc: packages/mcp/src/auth/to-html-text.ts at commit 4fe647cf.
+
+export function toHTMLText(text: string): string {
+  return text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}

package/src/auth/to-script-json.ts

@@ -0,0 +1,8 @@
+// Copied from atc: packages/mcp/src/auth/to-script-json.ts at commit 4fe647cf.
+
+export function toScriptJSON(value: unknown): string {
+  return JSON.stringify(value)
+    .replaceAll('<', String.raw`\u003c`)
+    .replaceAll('>', String.raw`\u003e`)
+    .replaceAll('&', String.raw`\u0026`);
+}

package/src/auth/types.ts

@@ -0,0 +1,115 @@
+// Copied from atc: packages/mcp/src/auth/types.ts at commit 4fe647cf.
+
+import type { GrantScope } from '@boxxy/contract';
+import type { AuthClock } from '../utils/types.ts';
+import type { ApprovalState } from './create-approval-state.ts';
+import type { EnrollmentState } from './create-enrollment-state.ts';
+import type { openMCPAuth } from './open-mcp-auth.ts';
+
+export interface Requester {
+  readonly socketAddress: string | null;
+
+  // the `CF-Connecting-IP` header. Anyone can send it, so it is `trusted`
+  // only when the socket's peer is a proxy the owner listed.
+  readonly connectingIP: {
+    readonly address: string;
+    readonly provenance: 'trusted' | 'unverified';
+  } | null;
+  readonly userAgent: string | null;
+}
+
+export type SecurityOutcome =
+  | { readonly kind: 'authorize_started'; readonly outcome: 'accepted' }
+  | {
+      readonly kind: 'authorize_started';
+      readonly outcome: 'rejected';
+      readonly reason: 'rate_limited';
+    }
+  | {
+      readonly kind: 'authorize_invalid';
+      readonly outcome: 'rejected';
+      readonly reason: AuthorizeInvalidReason;
+    }
+  | { readonly kind: 'owner_auth'; readonly outcome: 'succeeded' }
+  | {
+      readonly kind: 'owner_auth';
+      readonly outcome: 'failed';
+      readonly reason?: OwnerAuthFailure;
+    }
+  | { readonly kind: 'consent'; readonly outcome: 'allowed' }
+  | { readonly kind: 'consent'; readonly outcome: 'denied'; readonly reason?: 'none_ticked' }
+  | {
+      readonly kind: 'token_exchange';
+      readonly outcome: 'rejected';
+      readonly reason: TokenExchangeReason;
+    }
+  | { readonly kind: 'bearer'; readonly outcome: 'rejected'; readonly reason: BearerReason };
+
+export type OwnerAuthFailure =
+  | 'assertion_failed'
+  | 'locked'
+  | 'expired'
+  | 'not_enrolled'
+  | 'invalid_token';
+
+export type AuthorizeInvalidReason =
+  | 'invalid_client'
+  | 'client_disabled'
+  | 'invalid_redirect'
+  | 'unauthorized_client'
+  | 'unsupported_response_type'
+  | 'invalid_request'
+  | 'invalid_scope'
+  | 'invalid_target'
+  | 'bad_host'
+  | 'bad_origin'
+  | 'other';
+
+export type TokenExchangeReason =
+  | 'invalid_request'
+  | 'invalid_client'
+  | 'invalid_grant'
+  | 'unauthorized_client'
+  | 'unsupported_grant_type'
+  | 'invalid_scope'
+  | 'invalid_target'
+  | 'other';
+
+type BearerReason = 'malformed' | 'invalid_token';
+
+export type SecurityEvent = SecurityOutcome & {
+  readonly path: string;
+  readonly requester: Requester;
+  readonly client?: { readonly id: string; readonly name: string };
+  readonly redirectHost?: string;
+  readonly correlationID?: string;
+};
+
+// What a valid bearer token grants: the client it was issued to, and the
+// scopes it holds.
+export interface VerifiedAccess {
+  readonly clientID: string;
+  readonly clientName: string;
+  readonly scopes: readonly GrantScope[];
+}
+
+type MCPAuth = Awaited<ReturnType<typeof openMCPAuth>>;
+
+// What every HTTP route reads: the authorization server, the approvals waiting for the owner, and
+// the passkey enrollments in progress.
+export interface HTTPServerContext {
+  // The public origin: the OAuth issuer.
+  readonly origin: string;
+
+  // `<origin>/mcp`: the one resource every token is bound to.
+  readonly resource: string;
+  readonly store: MCPAuth;
+  readonly approvals: ApprovalState;
+  readonly enrollments: EnrollmentState;
+
+  // Receives each sign-in outcome and each refused token as a security event.
+  readonly security: { readonly record: (event: SecurityEvent) => void };
+
+  // The time the routes stamp and check expiries against.
+  readonly clock: AuthClock;
+}

package/src/auth/update-passkey-use.ts

@@ -0,0 +1,31 @@
+// Copied from atc: packages/mcp/src/auth/update-passkey-use.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+interface PasskeyUse {
+  readonly id: string;
+
+  // The counter the verification read, which the passkey must still hold,
+  // so a passkey removed during the verification, or a concurrent assertion
+  // that stored a newer counter, makes this use fail.
+  readonly counter: number;
+  readonly newCounter: number;
+
+  // Epoch milliseconds, stamped as the passkey's last use.
+  readonly now: number;
+}
+
+export async function updatePasskeyUse(
+  db: Kysely<MCPAuthSchema>,
+  use: PasskeyUse,
+): Promise<boolean> {
+  const stored = await db
+    .updateTable('boxxy_passkey')
+    .set({ counter: use.newCounter, last_used_at: new Date(use.now).toISOString() })
+    .where('id', '=', use.id)
+    .where('counter', '=', use.counter)
+    .executeTakeFirst();
+
+  return stored.numUpdatedRows > 0n;
+}

package/src/auth/verify-oauth-query.ts

@@ -0,0 +1,41 @@
+// Copied from atc: packages/mcp/src/auth/verify-oauth-query.ts at commit 4fe647cf.
+
+import { constantTimeEqual, makeSignature } from 'better-auth/crypto';
+
+export async function verifyOAuthQuery(
+  oauthQuery: string,
+  secret: string,
+  now: number,
+): Promise<boolean> {
+  const params = new URLSearchParams(oauthQuery);
+
+  const signatures = params.getAll('sig');
+  const [signature] = signatures;
+  const expiresAt = Number(params.get('exp')) * 1000;
+
+  if (signatures.length !== 1 || signature === undefined || signature === '') {
+    return false;
+  }
+
+  params.delete('sig');
+
+  // Ordered by name, then by value, comparing code units as better-auth does
+  // when it signs; the NUL separator sorts a name before any longer name it
+  // prefixes.
+  const canonical = new URLSearchParams(
+    [...params].toSorted(([keyA, valueA], [keyB, valueB]) => {
+      const pairA = `${keyA}\u0000${valueA}`;
+      const pairB = `${keyB}\u0000${valueB}`;
+
+      if (pairA === pairB) {
+        return 0;
+      }
+
+      return pairA < pairB ? -1 : 1;
+    }),
+  );
+
+  const expected = await makeSignature(canonical.toString(), secret);
+
+  return constantTimeEqual(signature, expected) && Number.isFinite(expiresAt) && expiresAt >= now;
+}

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

@@ -0,0 +1,124 @@
+// Copied from atc: packages/mcp/src/auth/verify-passkey-assertion.ts at commit 4fe647cf.
+
+import type {
+  AuthenticationResponseJSON,
+  VerifiedAuthenticationResponse,
+} from '@simplewebauthn/server';
+import type { Kysely } from 'kysely';
+import { z } from 'zod';
+import { parseJSONStrings } from '../utils/parse-json-strings.ts';
+import { loadWebAuthn } from './load-web-authn.ts';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+import { updatePasskeyUse } from './update-passkey-use.ts';
+
+interface AssertionCheck {
+  // The credential JSON the sign-in page posted.
+  readonly credential: string;
+
+  // The challenge the page was given, which the caller has already taken.
+  readonly challenge: string;
+  readonly origin: string;
+  readonly rpID: string;
+
+  // Epoch milliseconds, stamped as the passkey's last use.
+  readonly now: number;
+}
+
+export async function verifyPasskeyAssertion(
+  db: Kysely<MCPAuthSchema>,
+  check: AssertionCheck,
+): Promise<string | null> {
+  const response = parseAssertion(check.credential);
+
+  if (response === null) {
+    return null;
+  }
+
+  const passkey = await db
+    .selectFrom('boxxy_passkey')
+    .select(['id', 'public_key', 'counter', 'transports'])
+    .where('id', '=', response.id)
+    .executeTakeFirst();
+
+  if (passkey === undefined) {
+    return null;
+  }
+
+  const webAuthn = await loadWebAuthn();
+
+  let verified: VerifiedAuthenticationResponse;
+
+  try {
+    verified = await webAuthn.verifyAuthenticationResponse({
+      response,
+      expectedChallenge: check.challenge,
+      expectedOrigin: check.origin,
+      expectedRPID: check.rpID,
+      expectedType: 'webauthn.get',
+      requireUserVerification: true,
+      credential: {
+        id: passkey.id,
+        publicKey: new Uint8Array(Buffer.from(passkey.public_key, 'base64url')),
+        counter: passkey.counter,
+        transports: parseJSONStrings(passkey.transports) ?? [],
+      },
+    });
+  } catch {
+    return null;
+  }
+
+  if (!verified.verified || !verified.authenticationInfo.userVerified) {
+    return null;
+  }
+
+  const stored = await updatePasskeyUse(db, {
+    id: passkey.id,
+    counter: passkey.counter,
+    newCounter: verified.authenticationInfo.newCounter,
+    now: check.now,
+  });
+
+  return stored ? passkey.id : null;
+}
+
+const ASSERTION_REPLY = z.object({
+  clientDataJSON: z.string(),
+  authenticatorData: z.string(),
+  signature: z.string(),
+  userHandle: z.string().optional(),
+});
+
+const ASSERTION = z.object({
+  id: z.string().min(1),
+  rawId: z.string().min(1),
+  type: z.literal('public-key'),
+  response: ASSERTION_REPLY,
+});
+
+// The posted JSON when it has the shape of an authentication response,
+// else null; the verifier checks every value.
+function parseAssertion(credential: string): AuthenticationResponseJSON | null {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(credential);
+  } catch {
+    return null;
+  }
+
+  const result = ASSERTION.safeParse(parsed);
+
+  if (!result.success) {
+    return null;
+  }
+
+  const { userHandle, ...response } = result.data.response;
+
+  return {
+    id: result.data.id,
+    rawId: result.data.rawId,
+    type: result.data.type,
+    response: userHandle === undefined ? response : { ...response, userHandle },
+    clientExtensionResults: {},
+  };
+}

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

@@ -0,0 +1,118 @@
+// Copied from atc: packages/mcp/src/auth/verify-passkey-registration.ts at commit 4fe647cf.
+
+import type { RegistrationResponseJSON } from '@simplewebauthn/server';
+import { z } from 'zod';
+import { loadWebAuthn } from './load-web-authn.ts';
+
+interface RegistrationCheck {
+  // The credential JSON the enrollment page posted.
+  readonly credential: string;
+
+  // The challenge the page was given, which the caller has already taken.
+  readonly challenge: string;
+  readonly origin: string;
+  readonly rpID: string;
+}
+
+export interface RegisteredPasskey {
+  readonly id: string;
+  readonly publicKey: Uint8Array;
+  readonly counter: number;
+  readonly transports: readonly string[];
+}
+
+export async function verifyPasskeyRegistration(
+  check: RegistrationCheck,
+): Promise<RegisteredPasskey | null> {
+  const response = parseRegistration(check.credential);
+
+  if (response === null) {
+    return null;
+  }
+
+  const webAuthn = await loadWebAuthn();
+
+  try {
+    const verified = await webAuthn.verifyRegistrationResponse({
+      response,
+      expectedChallenge: check.challenge,
+      expectedOrigin: check.origin,
+      expectedRPID: check.rpID,
+      expectedType: 'webauthn.create',
+      requireUserVerification: true,
+    });
+
+    if (!verified.verified || !verified.registrationInfo.userVerified) {
+      return null;
+    }
+
+    const credential = verified.registrationInfo.credential;
+
+    return {
+      id: credential.id,
+      publicKey: credential.publicKey,
+      counter: credential.counter,
+      transports: response.response.transports ?? [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+const TRANSPORTS: ReadonlySet<string> = new Set([
+  'ble',
+  'cable',
+  'hybrid',
+  'internal',
+  'nfc',
+  'smart-card',
+  'usb',
+]);
+
+const REGISTRATION_REPLY = z.object({
+  clientDataJSON: z.string(),
+  attestationObject: z.string(),
+  transports: z.string().array().optional(),
+});
+
+const REGISTRATION = z.object({
+  id: z.string().min(1),
+  rawId: z.string().min(1),
+  type: z.literal('public-key'),
+  response: REGISTRATION_REPLY,
+});
+
+// The posted JSON when it has the shape of a registration response, keeping
+// only the transports WebAuthn defines, else null; the verifier checks
+// every value.
+function parseRegistration(credential: string): RegistrationResponseJSON | null {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(credential);
+  } catch {
+    return null;
+  }
+
+  const result = REGISTRATION.safeParse(parsed);
+
+  if (!result.success) {
+    return null;
+  }
+
+  const transports = (result.data.response.transports ?? []).filter((transport) =>
+    TRANSPORTS.has(transport),
+  );
+
+  return {
+    id: result.data.id,
+    rawId: result.data.rawId,
+    type: result.data.type,
+    response: {
+      clientDataJSON: result.data.response.clientDataJSON,
+      attestationObject: result.data.response.attestationObject,
+      transports,
+    },
+    clientExtensionResults: {},
+  };
+}