@boxxy/auth-oauth 0.0.1 → 0.2.2

package/dist/auth/verify-passkey-registration.d.ts

@@ -0,0 +1,14 @@
+interface RegistrationCheck {
+    readonly credential: string;
+    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 declare function verifyPasskeyRegistration(check: RegistrationCheck): Promise<RegisteredPasskey | null>;
+export {};

package/dist/auth/verify-session-passkey.d.ts

@@ -0,0 +1,8 @@
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+interface SessionPasskey {
+    readonly sessionID: string;
+    readonly passkeyID: string;
+}
+export declare function verifySessionPasskey(db: Kysely<MCPAuthSchema>, check: SessionPasskey): Promise<boolean>;
+export {};

package/dist/auth/write-grant-use.d.ts

@@ -0,0 +1,3 @@
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+export declare function writeGrantUse(db: Kysely<MCPAuthSchema>, grantID: string, now: number): Promise<void>;

package/dist/http/answer-mcp-request.d.ts

@@ -0,0 +1,9 @@
+import type { HTTPServerContext, Requester } from '../auth/types.ts';
+export interface McpAuthInfo {
+    readonly token: string;
+    readonly clientId: string;
+    readonly scopes: string[];
+    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/http/build-page-response.d.ts

@@ -0,0 +1,5 @@
+export declare function buildPageResponse(status: number, body: {
+    readonly page: string;
+} | {
+    readonly message: string;
+}, formTargets?: readonly string[], scriptSources?: readonly string[]): Response;

package/dist/http/create-mcp-http-app.d.ts

@@ -0,0 +1,92 @@
+import type { HTTPServerContext, Requester, SecurityEvent } from '../auth/types.ts';
+import type { McpServe } from './answer-mcp-request.ts';
+interface MCPHTTPAppOptions {
+    readonly hosts: ReadonlySet<string>;
+    readonly origins: ReadonlySet<string>;
+    readonly readContext: () => HTTPServerContext | null;
+    readonly readRequester: (request: Request) => Requester;
+    readonly serveMCP: McpServe;
+    readonly security: {
+        readonly record: (event: SecurityEvent) => void;
+    };
+}
+interface RouteContext {
+    readonly request: Request;
+}
+export declare function createMCPHTTPApp(options: MCPHTTPAppOptions): import("elysia/types").AddRoute<"", "local", import("elysia").DefaultSingleton, {
+    typebox: {};
+    error: [];
+}, import("elysia").DefaultMetadata, {
+    oauth2: {
+        revoke: {
+            post: {
+                body: unknown;
+                params: {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: Response;
+                };
+                error: never;
+            };
+        };
+    };
+} & {
+    ".well-known": {
+        "oauth-authorization-server": {
+            get: {
+                body: unknown;
+                params: {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: Response;
+                };
+                error: never;
+            };
+        };
+    };
+} & {
+    oauth2: {
+        authorize: {
+            get: {
+                body: unknown;
+                params: {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: Response;
+                };
+                error: never;
+            };
+        };
+    };
+} & {
+    oauth2: {
+        token: {
+            post: {
+                body: unknown;
+                params: {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: Response;
+                };
+                error: never;
+            };
+        };
+    };
+}, import("elysia").DefaultEphemeral, {
+    derive: {};
+    schema: {};
+    schemas: {};
+    response: import("elysia/types").ExtractErrorFromHandle<Response>;
+    error: [{
+        error: Error;
+        response: {};
+        passes: false;
+        '~return': Response;
+        '~catchAll': true;
+    }];
+}, "get", "/error", import("elysia/types").IntersectIfObjectSchema<import("elysia").UnwrapRoute<{}, {}, "/error">, import("elysia/types").MergeScopedSchemas<{}, {}, {}>>, {}, (context: RouteContext) => Response>;
+export {};

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

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

package/dist/http/is-loopback-host.d.ts

@@ -0,0 +1 @@
+export declare function isLoopbackHost(host: string): boolean;

package/dist/http/normalize-public-url.d.ts

@@ -0,0 +1 @@
+export declare function normalizePublicURL(raw: string): string;

package/dist/http/pick-error-message.d.ts

@@ -0,0 +1 @@
+export declare function pickErrorMessage(code: string | null): string;

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

@@ -0,0 +1,17 @@
+export declare const PUBLIC_DOOR_PATHS: {
+    readonly browser: {
+        readonly authorize: '/oauth2/authorize';
+        readonly login: '/login';
+        readonly enroll: '/enroll';
+        readonly consent: '/consent';
+        readonly error: '/error';
+    };
+    readonly machine: {
+        readonly mcp: '/mcp';
+        readonly token: '/oauth2/token';
+        readonly revoke: '/oauth2/revoke';
+        readonly authorizationServerMetadata: '/.well-known/oauth-authorization-server';
+        readonly resourceMetadata: '/.well-known/oauth-protected-resource';
+        readonly mcpResourceMetadata: '/.well-known/oauth-protected-resource/mcp';
+    };
+};

package/dist/http/read-token-access.d.ts

@@ -0,0 +1,8 @@
+import type { GrantScope } from '@boxxy/contract';
+import type { HTTPServerContext } from '../auth/types.ts';
+interface TokenAccess {
+    readonly clientID: string;
+    readonly scopes: readonly GrantScope[];
+}
+export declare function readTokenAccess(ctx: HTTPServerContext, token: string): Promise<TokenAccess | null>;
+export {};

package/dist/http/verify-access-token.d.ts

@@ -0,0 +1,2 @@
+import type { HTTPServerContext, VerifiedAccess } from '../auth/types.ts';
+export declare function verifyAccessToken(ctx: HTTPServerContext, token: string): Promise<VerifiedAccess | null>;

package/dist/index.d.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/dist/test-utils/authorize-test-client.d.ts

@@ -0,0 +1,13 @@
+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 {};

package/dist/test-utils/build-mock-new-passkey.d.ts

@@ -0,0 +1,2 @@
+import type { NewPasskey } from '../auth/create-passkey.ts';
+export declare function buildMockNewPasskey(overrides?: Partial<NewPasskey>): NewPasskey;

package/dist/test-utils/build-passkey-seeder.d.ts

@@ -0,0 +1,5 @@
+import type { PasskeyInput } from './seed-passkey.ts';
+import type { MCPAuthSeedDeps } from './types.ts';
+export declare function buildPasskeySeeder(deps: MCPAuthSeedDeps): {
+    passkey: (input?: PasskeyInput) => Promise<import("../auth/create-passkey.ts").NewPasskey>;
+};

package/dist/test-utils/build-seeder.d.ts

@@ -0,0 +1,5 @@
+import type { MCPAuthSeedDeps } from './types.ts';
+export type TestDeps = MCPAuthSeedDeps;
+export declare function buildSeeder(deps: TestDeps): {
+    passkey: (input?: import("./seed-passkey.ts").PasskeyInput) => Promise<import("../auth/create-passkey.ts").NewPasskey>;
+};

package/dist/test-utils/build-stub-authenticator.d.ts

@@ -0,0 +1,48 @@
+interface CreationOptions {
+    readonly challenge: string;
+    readonly rp: {
+        readonly id?: string;
+    };
+    readonly user: {
+        readonly id: string;
+    };
+}
+interface RequestOptions {
+    readonly challenge: string;
+    readonly rpId?: string;
+}
+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>>;
+}
+export declare function buildStubAuthenticator(): {
+    credentialID: string;
+    create(options: CreationOptions, ceremony: Ceremony): Promise<StubRegistration>;
+    signAssertion(options: RequestOptions, ceremony: Ceremony): Promise<StubAssertion>;
+};
+export {};

package/dist/test-utils/build-stub-clock.d.ts

@@ -0,0 +1,7 @@
+export declare function buildStubClock(startMs: number): {
+    now: () => number;
+    schedule: (callback: () => void, delayMs: number) => () => void;
+    advance(durationMs: number): void;
+    collectPending: () => number[];
+    collectDelays: () => number[];
+};

package/dist/test-utils/load-web-authn-early.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test-utils/register-test-cleanup.d.ts

@@ -0,0 +1 @@
+export declare function registerTestCleanup<T>(release: () => T): () => T;

package/dist/test-utils/seed-passkey.d.ts

@@ -0,0 +1,4 @@
+import type { NewPasskey } from '../auth/create-passkey.ts';
+import type { MCPAuthSeedDeps } from './types.ts';
+export type PasskeyInput = Partial<Omit<NewPasskey, 'tokenHash'>>;
+export declare function seedPasskey(deps: MCPAuthSeedDeps, input?: PasskeyInput): Promise<NewPasskey>;

package/dist/test-utils/setup-temp-dir.d.ts

@@ -0,0 +1,6 @@
+interface TempDir {
+    readonly path: string;
+    readonly teardown: () => void;
+}
+export declare function setupTempDir(prefix: string): TempDir;
+export {};

package/dist/test-utils/start-stub-telemetry-collector.d.ts

@@ -0,0 +1,5 @@
+export declare function startStubTelemetryCollector(): {
+    url: string;
+    received: string[];
+    stop: () => Promise<void>;
+};

package/dist/test-utils/types.d.ts

@@ -0,0 +1,7 @@
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from '../auth/mcp-auth-schema.ts';
+import type { AuthClock } from '../utils/types.ts';
+export interface MCPAuthSeedDeps {
+    readonly db: Kysely<MCPAuthSchema>;
+    readonly clock: Pick<AuthClock, 'now'>;
+}

package/dist/utils/is-record.d.ts

@@ -0,0 +1 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/utils/parse-json-strings.d.ts

@@ -0,0 +1 @@
+export declare function parseJSONStrings(raw: string): string[] | null;

package/dist/utils/types.d.ts

@@ -0,0 +1,4 @@
+export interface AuthClock {
+    readonly now: () => number;
+    readonly schedule: (callback: () => void, delayMs: number) => () => void;
+}

package/package.json

@@ -1,13 +1,54 @@
 {
   "name": "@boxxy/auth-oauth",
-  "version": "0.0.1",
+  "version": "0.2.2",
+  "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",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zgeoff/boxxy.git",
     "directory": "adapters/auth-oauth"
   },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@better-auth/mcp": "1.7.15",
+    "@better-auth/oauth-provider": "1.7.15",
+    "@boxxy/contract": "0.2.2",
+    "@simplewebauthn/server": "14.0.3",
+    "@zgeoff/kysely-bun-sqlite": "0.3.2",
+    "better-auth": "1.7.15",
+    "elysia": "2.0.0-rc.0",
+    "exact-mirror": "1.2.6",
+    "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"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
   }
 }

package/src/auth/answer-authorize-request.ts

@@ -0,0 +1,137 @@
+// Copied from atc: packages/mcp/src/auth/answer-authorize-request.ts at commit 4fe647cf.
+
+import { buildPageResponse } from '../http/build-page-response.ts';
+import { PUBLIC_DOOR_PATHS } from '../http/public-door-paths.ts';
+import { normalizeClientName } from './normalize-client-name.ts';
+import { readClientName } from './read-client-name.ts';
+import type { AuthorizeInvalidReason, HTTPServerContext, Requester } from './types.ts';
+
+export async function answerAuthorizeRequest(
+  ctx: HTTPServerContext,
+  url: URL,
+  requester: Requester,
+): Promise<Response> {
+  const params = new URLSearchParams(url.searchParams);
+
+  // every authorization asks for a fresh passkey sign-in and the consent page,
+  // whatever session or consent the browser kept.
+  params.set('prompt', 'login consent');
+
+  const scope = params.get('scope');
+
+  if (scope !== null) {
+    const scopes = scope.split(' ').filter((item) => item !== '');
+
+    params.set('scope', [...new Set([...scopes, 'offline_access'])].join(' '));
+  }
+
+  if (!params.has('resource')) {
+    params.set('resource', ctx.resource);
+  }
+
+  const response = await ctx.store.auth.handler(
+    new Request(`${ctx.origin}${PUBLIC_DOOR_PATHS.browser.authorize}?${params.toString()}`, {
+      headers: { accept: 'text/html' },
+    }),
+  );
+
+  const location = response.headers.get('location');
+  const target = location === null ? null : new URL(location, ctx.origin);
+
+  if (
+    target === null ||
+    target.origin !== ctx.origin ||
+    target.pathname !== PUBLIC_DOOR_PATHS.browser.login
+  ) {
+    await recordInvalidRequest(ctx, url, requester, target);
+
+    return response;
+  }
+
+  const clientID = target.searchParams.get('client_id') ?? '';
+  const redirectURI = target.searchParams.get('redirect_uri') ?? '';
+
+  const storedName = await readClientName(ctx.store.db, clientID);
+
+  const clientName = normalizeClientName(storedName);
+
+  const accepted = {
+    path: url.pathname,
+    requester,
+    client: { id: clientID, name: clientName },
+    redirectHost: new URL(redirectURI).host,
+  };
+
+  const approval = ctx.approvals.createPending({
+    key: target.search.slice(1),
+    clientID,
+    clientName,
+    redirectURI,
+  });
+
+  if (approval === null) {
+    ctx.security.record({
+      kind: 'authorize_started',
+      outcome: 'rejected',
+      reason: 'rate_limited',
+      ...accepted,
+    });
+
+    return buildPageResponse(429, {
+      message: 'Too many approvals started in the last minute. Wait a minute, then start again.',
+    });
+  }
+
+  ctx.security.record({
+    kind: 'authorize_started',
+    outcome: 'accepted',
+    ...accepted,
+    correlationID: approval.correlationID,
+  });
+
+  return response;
+}
+
+// A refusal that returns to the client went to a redirect URI better-auth
+// validated, so only then does the event hold its host. The client's id
+// and name go in only for a client boxxy holds.
+async function recordInvalidRequest(
+  ctx: HTTPServerContext,
+  url: URL,
+  requester: Requester,
+  target: URL | null,
+): Promise<void> {
+  const code = target?.searchParams.get('error') ?? null;
+  const reason = isAuthorizeError(code) ? code : 'other';
+  const clientID = url.searchParams.get('client_id');
+  const storedName = clientID === null ? null : await readClientName(ctx.store.db, clientID);
+
+  ctx.security.record({
+    kind: 'authorize_invalid',
+    outcome: 'rejected',
+    reason,
+    path: url.pathname,
+    requester,
+    ...(clientID === null || storedName === null
+      ? {}
+      : { client: { id: clientID, name: normalizeClientName(storedName) } }),
+    ...(target === null || target.origin === ctx.origin ? {} : { redirectHost: target.host }),
+  });
+}
+
+// The better-auth error codes an `authorize_invalid` event may hold; any
+// other code becomes `other`.
+const AUTHORIZE_ERRORS: ReadonlySet<string> = new Set([
+  'invalid_client',
+  'client_disabled',
+  'invalid_redirect',
+  'unauthorized_client',
+  'unsupported_response_type',
+  'invalid_request',
+  'invalid_scope',
+  'invalid_target',
+]);
+
+function isAuthorizeError(code: string | null): code is AuthorizeInvalidReason {
+  return code !== null && AUTHORIZE_ERRORS.has(code);
+}