@boxxy/auth-oauth 0.2.5 → 0.2.7

package/README.md

@@ -11,8 +11,10 @@
   </p>
 </div>
 
-The OAuth server behind boxxy's public door: it lets the owner's assistant reach the owner's MCP
-tools from anywhere, with a grant that the owner approved with a passkey.
+boxxy's public door: it lets the owner's assistant reach the owner's MCP tools from anywhere, with a
+grant that the owner approved with a passkey. The OAuth server is
+[`@zgeoff/mcp-auth`](https://www.npmjs.com/package/@zgeoff/mcp-auth); this package opens it on
+boxxy's auth database, with boxxy's scopes and table names.
 
 ## Install
 
@@ -26,21 +28,18 @@ The package runs on [Bun](https://bun.sh) 1.3 or newer.
 
 ## Features
 
-- `createPublicDoor(options)` opens the auth database and returns the door: `answerRequest` for each
-  request, `addLocalPort` for the loopback address, `admin` for the owner's commands and `stop`.
-- The door serves `/mcp`, the OAuth routes (`/oauth2/authorize`, `/oauth2/token`, `/oauth2/revoke`
-  and the two `.well-known` documents) and the sign-in pages (`/login`, `/enroll`, `/consent`,
-  `/error`), and answers 404 on any other path.
-- It checks the `Host` and `Origin` headers, verifies each bearer token against the auth database,
-  and passes the verified token to the `serveMCP` callback that the app gives it.
+- `createPublicDoor(options)` opens and migrates the auth database and returns the door:
+  `answerRequest` for each request, `addLocalPort` for the loopback address, `admin` for the owner's
+  commands, `auth` for the test helpers, and `stop`.
+- The door serves MCP at `/mcp` and at `/`, the OAuth routes, the two `.well-known` documents and
+  the sign-in pages, and answers 404 on any other path.
+- It checks the `Host` and `Origin` headers, verifies each bearer token, and passes the verified
+  token to the `serveMCP` callback that the app gives it.
 - It writes each sign-in outcome and each refused token to `writeSecurityLine` as a JSON line.
 - `admin` enrolls a passkey, adds and removes clients, and lists and revokes grants.
-- `./test-utils/authorize-test-client` runs the whole sign-in against a door with a stub passkey,
+- `./test-utils/authorize-test-client` signs a client in through `door.auth` with a stub passkey,
   for tests.
 
-The code is a copy of the OAuth server in atc's `@atc/mcp`. Each copied file names its source path
-and commit in its first line.
-
 ## Documentation
 
 [The public door](../../docs/design/boxxy/v1-api-and-auth.md#the-public-door) describes the

package/dist/auth/create-auth-admin.d.ts

@@ -1,12 +1,8 @@
-import type { AuthClock } from '../utils/types.ts';
-import type { openMCPAuth } from './open-mcp-auth.ts';
-import type { ClientView } from './read-client-views.ts';
-import type { GrantView } from './read-grant-views.ts';
-type MCPAuth = Awaited<ReturnType<typeof openMCPAuth>>;
+import type { GrantScope } from '@boxxy/contract';
+import type { ClientView, MCPAuth } from '@zgeoff/mcp-auth';
 export interface AuthAdminInput {
-    readonly store: MCPAuth;
+    readonly auth: MCPAuth<GrantScope>;
     readonly origin: string;
-    readonly clock: AuthClock;
 }
 export type AddClientAnswer = {
     readonly kind: 'added';
@@ -14,20 +10,37 @@ export type AddClientAnswer = {
     readonly name: string;
 } | {
     readonly kind: 'refused';
-    readonly redirectURI: string;
+    readonly message: string;
+} | {
+    readonly kind: 'conflict';
+    readonly name: string;
+};
+export type RemoveClientAnswer = {
+    readonly kind: 'removed';
+} | {
+    readonly kind: 'not-found';
+} | {
+    readonly kind: 'ambiguous';
+    readonly name: string;
 };
 export interface EnrollmentLink {
     readonly token: string;
     readonly link: string;
-    readonly expiresAt: number;
+}
+export interface AuthGrantView {
+    readonly grantID: string;
+    readonly clientID: string;
+    readonly clientName: string;
+    readonly scopes: readonly GrantScope[];
+    readonly createdAt: string;
+    readonly lastUsedAt: string | null;
 }
 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 removeClient: (clientID: string) => Promise<RemoveClientAnswer>;
+    readonly listGrants: () => Promise<readonly AuthGrantView[]>;
     readonly revokeGrant: (grantID: string) => Promise<boolean>;
 }
 export declare function createAuthAdmin(input: AuthAdminInput): AuthAdmin;
-export {};

package/dist/auth/create-security-event-log.d.ts

@@ -1,5 +1,5 @@
+import type { SecurityEvent } from '@zgeoff/mcp-auth';
 import type { AuthClock } from '../utils/types.ts';
-import type { SecurityEvent } from './types.ts';
 interface SecurityEventLogOptions {
     readonly print: (line: string) => void;
     readonly clock: AuthClock;

package/dist/auth/format-security-event.d.ts

@@ -1,7 +1,15 @@
-import type { SecurityEvent } from './types.ts';
+import type { SecurityEvent } from '@zgeoff/mcp-auth';
+type LoggedSecurityEvent = Omit<SecurityEvent, 'client' | 'correlationID'> & {
+    readonly client?: {
+        readonly id: string;
+        readonly name: string;
+    };
+    readonly correlationID?: string;
+};
 export interface SuppressedSecurityEvent {
     readonly kind: 'suppressed';
     readonly reason: SecurityEvent['kind'];
     readonly count: number;
 }
-export declare function formatSecurityEvent(event: SecurityEvent | SuppressedSecurityEvent, at: number): string;
+export declare function formatSecurityEvent(event: LoggedSecurityEvent | SuppressedSecurityEvent, at: number): string;
+export {};

package/dist/auth/open-auth-database.d.ts

@@ -1,2 +1,2 @@
-import type { MCPAuthDatabase } from './mcp-auth-database.ts';
-export declare function openAuthDatabase(path: string): MCPAuthDatabase;
+import { Database } from 'bun:sqlite';
+export declare function openAuthDatabase(path: string): Database;

package/dist/http/create-public-door.d.ts

@@ -1,12 +1,15 @@
+import type { GrantScope } from '@boxxy/contract';
+import type { MCPAuth } from '@zgeoff/mcp-auth';
 import type { AuthAdmin } from '../auth/create-auth-admin.ts';
 import type { AuthClock } from '../utils/types.ts';
-import type { McpServe } from './answer-mcp-request.ts';
+import type { McpServe } from './types.ts';
 export interface PublicDoorOptions {
     readonly publicURL: string;
     readonly hostname: string;
     readonly dbPath: string;
     readonly trustForwardedFrom: readonly string[];
     readonly writeSecurityLine: (line: string) => void;
+    readonly onSweepError: (error: unknown) => void;
     readonly readPeer: (request: Request) => string | null;
     readonly serveMCP: McpServe;
     readonly clock?: AuthClock;
@@ -15,6 +18,7 @@ export interface PublicDoor {
     readonly answerRequest: (request: Request) => Promise<Response>;
     readonly addLocalPort: (port: number) => void;
     readonly admin: AuthAdmin;
+    readonly auth: MCPAuth<GrantScope>;
     readonly stop: () => Promise<void>;
 }
 export declare function createPublicDoor(options: PublicDoorOptions): Promise<PublicDoor>;

package/dist/http/{answer-mcp-request.d.ts → types.d.ts}

@@ -1,4 +1,3 @@
-import type { HTTPServerContext, Requester } from '../auth/types.ts';
 export interface McpAuthInfo {
     readonly token: string;
     readonly clientId: string;
@@ -6,4 +5,3 @@ export interface McpAuthInfo {
     readonly resourceMetadataUrl: string;
 }
 export type McpServe = (request: Request, authInfo: McpAuthInfo) => Promise<Response>;
-export declare function answerMCPRequest(ctx: HTTPServerContext, request: Request, requester: Requester, serve: McpServe): Promise<Response>;

package/dist/index.d.ts

@@ -1,8 +1,5 @@
-export type { AddClientAnswer, AuthAdmin, EnrollmentLink } from './auth/create-auth-admin.ts';
-export type { McpAuthInfo, McpServe } from './http/answer-mcp-request.ts';
+export type { AddClientAnswer, AuthAdmin, AuthGrantView, EnrollmentLink, RemoveClientAnswer, } from './auth/create-auth-admin.ts';
+export type { McpAuthInfo, McpServe } from './http/types.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/dist/migrations/grant-rows-migration.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from 'kysely/migration';
+export declare const grantRowsMigration: Migration;

package/dist/migrations/run-auth-migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Database } from 'bun:sqlite';
+export declare function runAuthMigrations(sqlite: Database): Promise<void>;

package/dist/test-utils/authorize-test-client.d.ts

@@ -1,13 +1 @@
-import type { PublicDoor } from '../http/create-public-door.ts';
-interface AuthorizeInput {
-    readonly origin: string;
-    readonly requested: readonly string[];
-    readonly ticked: readonly string[];
-}
-export interface TestGrant {
-    readonly clientID: string;
-    readonly accessToken: string;
-    readonly refreshToken: string;
-}
-export declare function authorizeTestClient(door: PublicDoor, input: AuthorizeInput): Promise<TestGrant>;
-export {};
+export { authorizeTestClient } from '@zgeoff/mcp-auth/testing';

package/dist/test-utils/pre-package-schema.d.ts

@@ -0,0 +1 @@
+export declare const PRE_PACKAGE_SCHEMA: string[];

package/dist/test-utils/seed-pre-package-auth.d.ts

@@ -0,0 +1,21 @@
+import type { Database } from 'bun:sqlite';
+export interface PrePackageGrant {
+    readonly clientName: string;
+    readonly scopes: readonly string[];
+    readonly refreshes: number;
+    readonly lastUsedAt: string | null;
+    readonly isExpired?: boolean;
+}
+export interface PrePackageAuth {
+    readonly origin: string;
+    readonly grants: readonly PrePackageGrant[];
+    readonly passkeyID: string;
+    readonly now: number;
+}
+export interface SeededPrePackageGrant {
+    readonly grantID: string;
+    readonly clientID: string;
+    readonly accessToken: string;
+    readonly refreshToken: string;
+}
+export declare function seedPrePackageAuth(sqlite: Database, input: PrePackageAuth): SeededPrePackageGrant[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/auth-oauth",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "boxxy's public door: an OAuth server for the owner's MCP endpoint, with passkey sign-in",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/adapters/auth-oauth#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -31,21 +31,15 @@
     "typecheck": "tsrs --noEmit"
   },
   "dependencies": {
-    "@better-auth/mcp": "1.7.15",
-    "@better-auth/oauth-provider": "1.7.15",
-    "@boxxy/contract": "0.2.5",
-    "@simplewebauthn/server": "14.0.3",
+    "@boxxy/contract": "0.2.7",
     "@zgeoff/kysely-bun-sqlite": "0.3.2",
-    "better-auth": "1.7.15",
-    "elysia": "2.0.0-rc.0",
-    "exact-mirror": "1.2.6",
+    "@zgeoff/mcp-auth": "0.1.0",
+    "@zgeoff/std": "0.4.3",
+    "elysia": "2.0.0-rc.3",
+    "exact-mirror": "1.2.7",
     "kysely": "0.29.8",
     "openapi-types": "12.1.3",
-    "reflect-metadata": "0.2.2",
-    "tiny-invariant": "1.3.3",
-    "ts-pattern": "5.9.2",
-    "typebox": "1.4.3",
-    "zod": "4.6.7"
+    "typebox": "1.4.3"
   },
   "engines": {
     "bun": ">=1.3",

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

@@ -1,32 +1,40 @@
-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>>;
+import type { GrantScope } from '@boxxy/contract';
+import { grantScopes } from '@boxxy/contract';
+import { MCPAuthError } from '@zgeoff/mcp-auth';
+import type { ClientView, GrantID, GrantView, MCPAuth } from '@zgeoff/mcp-auth';
+import { toTagged } from '@zgeoff/std';
 
 export interface AuthAdminInput {
-  readonly store: MCPAuth;
+  readonly auth: MCPAuth<GrantScope>;
   readonly origin: string;
-  readonly clock: AuthClock;
 }
 
 export type AddClientAnswer =
   | { readonly kind: 'added'; readonly clientID: string; readonly name: string }
-  | { readonly kind: 'refused'; readonly redirectURI: string };
+
+  // the message says which rule the name or a redirect URI broke
+  | { readonly kind: 'refused'; readonly message: string }
+  | { readonly kind: 'conflict'; readonly name: string };
+
+export type RemoveClientAnswer =
+  | { readonly kind: 'removed' }
+  | { readonly kind: 'not-found' }
+
+  // another client has the same name, and the OAuth server removes a client by its name
+  | { readonly kind: 'ambiguous'; readonly name: string };
 
 export interface EnrollmentLink {
   readonly token: string;
   readonly link: string;
-  readonly expiresAt: number;
+}
+
+export interface AuthGrantView {
+  readonly grantID: string;
+  readonly clientID: string;
+  readonly clientName: string;
+  readonly scopes: readonly GrantScope[];
+  readonly createdAt: string;
+  readonly lastUsedAt: string | null;
 }
 
 // What the owner's commands do to the authorization database: add and remove clients, revoke
@@ -35,44 +43,104 @@ 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 removeClient: (clientID: string) => Promise<RemoveClientAnswer>;
+  readonly listGrants: () => Promise<readonly AuthGrantView[]>;
   readonly revokeGrant: (grantID: string) => Promise<boolean>;
 }
 
 export function createAuthAdmin(input: AuthAdminInput): AuthAdmin {
-  const store = input.store;
-  const origin = input.origin;
-  const clock = input.clock;
+  const auth = input.auth;
 
   return {
     enroll: async () => {
-      const created = await createEnrollmentToken(store.db, clock.now());
+      const token = await auth.passkeys.createEnrollmentToken();
+
+      const link = new URL(`${input.origin}${auth.paths.browser.enroll}`);
+
+      link.searchParams.set('token', token);
 
-      return {
-        token: created.token,
-        link: `${origin}${PUBLIC_DOOR_PATHS.browser.enroll}?token=${created.token}`,
-        expiresAt: created.expiresAt,
-      };
+      return { token, link: link.href };
     },
     addClient: async (name, redirectURIs) => {
-      const refused = redirectURIs.find((uri) => !isAllowedRedirectURI(uri));
+      try {
+        const added = await auth.clients.add(name, redirectURIs);
 
-      if (refused !== undefined) {
-        return { kind: 'refused', redirectURI: refused };
+        return { kind: 'added', clientID: added.clientID, name: added.name };
+      } catch (error) {
+        return pickAddRefusal(error, name);
       }
+    },
+    listClients: () => auth.clients.list(),
+    removeClient: async (clientID) => {
+      const clients = await auth.clients.list();
+
+      const answer = pickClientToRemove(clients, clientID);
 
-      const clientName = normalizeClientName(name);
+      if (answer.kind === 'remove') {
+        await auth.clients.remove(answer.name);
 
-      const created = await store.auth.api.createFixedClient({
-        body: { name: clientName, redirectURIs: [...redirectURIs] },
-      });
+        return { kind: 'removed' };
+      }
 
-      return { kind: 'added', clientID: created.clientID, name: clientName };
+      return answer;
     },
-    listClients: () => readClientViews(store.db),
-    removeClient: (clientID) => removeClient(store.db, clientID),
-    listGrants: () => readGrantViews(store.db),
-    revokeGrant: (grantID) => revokeGrant(store.db, grantID),
+    listGrants: async () => {
+      const grants = await auth.grants.list();
+
+      return grants.map((grant) => toAuthGrantView(grant));
+    },
+
+    // The package lists only grants with a live refresh token, and a grant can hold a live access
+    // token without one, so the revoke goes to the package by ID.
+    revokeGrant: (grantID) => auth.grants.revoke(toTagged<GrantID>(grantID)),
+  };
+}
+
+// The package refuses a bad name or redirect URI, and a taken name, with a coded error; any other
+// error is not the owner's input.
+function pickAddRefusal(error: unknown, name: string): AddClientAnswer {
+  if (!(error instanceof MCPAuthError)) {
+    throw error;
+  }
+
+  if (error.code === 'conflict') {
+    return { kind: 'conflict', name };
+  }
+
+  if (error.code === 'invalid-client-name' || error.code === 'invalid-redirect-uri') {
+    return { kind: 'refused', message: error.message };
+  }
+
+  throw error;
+}
+
+type ClientToRemove =
+  | { readonly kind: 'remove'; readonly name: string }
+  | Exclude<RemoveClientAnswer, { readonly kind: 'removed' }>;
+
+function pickClientToRemove(clients: readonly ClientView[], clientID: string): ClientToRemove {
+  const client = clients.find((view) => view.clientID === clientID);
+
+  if (client === undefined) {
+    return { kind: 'not-found' };
+  }
+
+  const isShared = clients.some(
+    (view) => view.name === client.name && view.clientID !== client.clientID,
+  );
+
+  return isShared
+    ? { kind: 'ambiguous', name: client.name }
+    : { kind: 'remove', name: client.name };
+}
+
+function toAuthGrantView(grant: GrantView): AuthGrantView {
+  return {
+    grantID: grant.grantID,
+    clientID: grant.clientID,
+    clientName: grant.clientName,
+    scopes: grantScopes.filter((scope) => grant.scopes.includes(scope)),
+    createdAt: grant.createdAt,
+    lastUsedAt: grant.lastUsedAt,
   };
 }

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

@@ -1,8 +1,6 @@
-// Copied from atc: packages/mcp/src/auth/create-security-event-log.ts at commit 4fe647cf.
-
+import type { SecurityEvent } from '@zgeoff/mcp-auth';
 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.

package/src/auth/format-security-event.ts

@@ -1,8 +1,12 @@
-// Copied from atc: packages/mcp/src/auth/format-security-event.ts at commit 4fe647cf.
-
-import { PUBLIC_DOOR_PATHS } from '../http/public-door-paths.ts';
+import { DEFAULT_PATHS } from '@zgeoff/mcp-auth';
+import type { SecurityEvent } from '@zgeoff/mcp-auth';
 import { normalizeClientName } from './normalize-client-name.ts';
-import type { SecurityEvent } from './types.ts';
+
+// The IDs in an event are tagged strings, and a line needs only their text.
+type LoggedSecurityEvent = Omit<SecurityEvent, 'client' | 'correlationID'> & {
+  readonly client?: { readonly id: string; readonly name: string };
+  readonly correlationID?: string;
+};
 
 export interface SuppressedSecurityEvent {
   readonly kind: 'suppressed';
@@ -12,11 +16,11 @@ export interface SuppressedSecurityEvent {
 
 // The paths an event may hold as its route.
 const ROUTES: ReadonlySet<string> = new Set(
-  Object.values(PUBLIC_DOOR_PATHS).flatMap((group) => Object.values(group)),
+  Object.values(DEFAULT_PATHS).flatMap((group) => Object.values(group)),
 );
 
 export function formatSecurityEvent(
-  event: SecurityEvent | SuppressedSecurityEvent,
+  event: LoggedSecurityEvent | SuppressedSecurityEvent,
   at: number,
 ): string {
   const head = { version: 1, ts: new Date(at).toISOString(), kind: event.kind };
@@ -30,9 +34,9 @@ export function formatSecurityEvent(
   const fields = {
     ...head,
     outcome: event.outcome,
-    ...('reason' in event && event.reason !== undefined ? { reason: event.reason } : {}),
+    ...(event.reason === undefined ? {} : { reason: event.reason }),
     ...(event.kind === 'owner_auth'
-      ? { method: event.path === PUBLIC_DOOR_PATHS.browser.enroll ? 'enrollment_token' : 'passkey' }
+      ? { method: event.path === DEFAULT_PATHS.browser.enroll ? 'enrollment_token' : 'passkey' }
       : {}),
     route: ROUTES.has(event.path) ? event.path : 'other',
     ...(event.client === undefined
@@ -43,9 +47,6 @@ export function formatSecurityEvent(
             name: toEventText(event.client.name, 100),
           },
         }),
-    ...(event.redirectHost === undefined
-      ? {}
-      : { redirectHost: toEventText(event.redirectHost, 255) }),
     ...(event.correlationID === undefined ? {} : { correlationID: event.correlationID }),
     ...(requester.socketAddress === null
       ? {}

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

@@ -1,5 +1,3 @@
-// Copied from atc: packages/mcp/src/auth/normalize-client-name.ts at commit 4fe647cf.
-
 export function normalizeClientName(
   raw: unknown,
   fallback = 'unnamed client',

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

@@ -1,22 +1,17 @@
-// Adapted from atc: packages/mcp/src/testing/open-test-auth-database.ts at commit 4fe647cf.
-
 import { Database } from 'bun:sqlite';
-import { buildSQLiteDialect } from '@zgeoff/kysely-bun-sqlite';
-import type { MCPAuthDatabase } from './mcp-auth-database.ts';
+import { chmodSync, closeSync, openSync } from 'node:fs';
+
+// The file holds token hashes and sessions, so only its owner may read it. SQLite gives the WAL and
+// shared-memory files the main file's mode, so the mode is set before SQLite opens the file.
+export function openAuthDatabase(path: string): Database {
+  closeSync(openSync(path, 'a', 0o600));
+  chmodSync(path, 0o600);
 
-// A write waits for another process's lock, and the cascades from a client to its tokens need
-// foreign keys.
-export function openAuthDatabase(path: string): MCPAuthDatabase {
   const sqlite = new Database(path, { create: true });
 
   sqlite.run('PRAGMA journal_mode = WAL;');
   sqlite.run('PRAGMA busy_timeout = 5000;');
   sqlite.run('PRAGMA foreign_keys = ON;');
 
-  return {
-    dialect: buildSQLiteDialect(sqlite),
-    close: () => {
-      sqlite.close();
-    },
-  };
+  return sqlite;
 }