@boxxy/auth-oauth 0.2.7 → 0.2.9

package/README.md

@@ -37,6 +37,10 @@ The package runs on [Bun](https://bun.sh) 1.3 or newer.
   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.
+- With `serviceTokens`, the door signs in the service clients of a service-token file with the
+  `client_credentials` grant. It reads the file again on SIGHUP, and passes each outcome to
+  `onReload`: the clients replaced, or the old clients kept with the reason.
+- `mintServiceSecret()` draws a service client's secret and its digest, for the file.
 - `./test-utils/authorize-test-client` signs a client in through `door.auth` with a stub passkey,
   for tests.
 

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

@@ -19,9 +19,6 @@ export type RemoveClientAnswer = {
     readonly kind: 'removed';
 } | {
     readonly kind: 'not-found';
-} | {
-    readonly kind: 'ambiguous';
-    readonly name: string;
 };
 export interface EnrollmentLink {
     readonly token: string;

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

@@ -1,8 +1,13 @@
 import type { GrantScope } from '@boxxy/contract';
 import type { MCPAuth } from '@zgeoff/mcp-auth';
 import type { AuthAdmin } from '../auth/create-auth-admin.ts';
+import type { ServiceTokenReload } from '../service-tokens/reload-service-tokens.ts';
 import type { AuthClock } from '../utils/types.ts';
 import type { McpServe } from './types.ts';
+export interface ServiceTokensOptions {
+    readonly file: string;
+    readonly onReload: (reload: ServiceTokenReload) => void;
+}
 export interface PublicDoorOptions {
     readonly publicURL: string;
     readonly hostname: string;
@@ -13,6 +18,7 @@ export interface PublicDoorOptions {
     readonly readPeer: (request: Request) => string | null;
     readonly serveMCP: McpServe;
     readonly clock?: AuthClock;
+    readonly serviceTokens?: ServiceTokensOptions;
 }
 export interface PublicDoor {
     readonly answerRequest: (request: Request) => Promise<Response>;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 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 type { PublicDoor, PublicDoorOptions, ServiceTokensOptions, } from './http/create-public-door.ts';
 export { createPublicDoor } from './http/create-public-door.ts';
 export { isLoopbackHost } from './http/is-loopback-host.ts';
+export type { ServiceTokenReload } from './service-tokens/reload-service-tokens.ts';
+export { mintServiceSecret } from '@zgeoff/mcp-auth';

package/dist/service-tokens/constants.d.ts

@@ -0,0 +1 @@
+export declare const serviceTokenPrefix = "boxxy_svc_";

package/dist/service-tokens/parse-service-token-text.d.ts

@@ -0,0 +1,3 @@
+import type { GrantScope } from '@boxxy/contract';
+import type { ParsedServiceTokenFile } from '@zgeoff/mcp-auth';
+export declare function parseServiceTokenText(text: string): ParsedServiceTokenFile<GrantScope>;

package/dist/service-tokens/read-service-token-file.d.ts

@@ -0,0 +1,3 @@
+import type { GrantScope } from '@boxxy/contract';
+import type { ParsedServiceTokenFile } from '@zgeoff/mcp-auth';
+export declare function readServiceTokenFile(path: string): Promise<ParsedServiceTokenFile<GrantScope>>;

package/dist/service-tokens/reload-service-tokens.d.ts

@@ -0,0 +1,10 @@
+import type { GrantScope } from '@boxxy/contract';
+import type { MCPAuth } from '@zgeoff/mcp-auth';
+export type ServiceTokenReload = {
+    readonly kind: 'replaced';
+    readonly clients: number;
+} | {
+    readonly kind: 'kept';
+    readonly reason: string;
+};
+export declare function reloadServiceTokens(auth: Pick<MCPAuth<GrantScope>, 'replaceServiceTokens'>, path: string): Promise<ServiceTokenReload>;

package/dist/service-tokens/start-service-token-reloads.d.ts

@@ -0,0 +1,9 @@
+import type { GrantScope } from '@boxxy/contract';
+import type { MCPAuth } from '@zgeoff/mcp-auth';
+import type { ServiceTokenReload } from './reload-service-tokens.ts';
+export interface ServiceTokenReloads {
+    readonly auth: Pick<MCPAuth<GrantScope>, 'replaceServiceTokens'>;
+    readonly path: string;
+    readonly onReload: (reload: ServiceTokenReload) => void;
+}
+export declare function startServiceTokenReloads(reloads: ServiceTokenReloads): () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/auth-oauth",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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,15 +31,16 @@
     "typecheck": "tsrs --noEmit"
   },
   "dependencies": {
-    "@boxxy/contract": "0.2.7",
+    "@boxxy/contract": "0.2.9",
     "@zgeoff/kysely-bun-sqlite": "0.3.2",
-    "@zgeoff/mcp-auth": "0.1.0",
+    "@zgeoff/mcp-auth": "0.2.2",
     "@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",
-    "typebox": "1.4.3"
+    "typebox": "1.4.3",
+    "zod": "4.6.7"
   },
   "engines": {
     "bun": ">=1.3",

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

@@ -1,7 +1,7 @@
 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 type { ClientView, GrantID, GrantView, MCPAuth, OAuthClientID } from '@zgeoff/mcp-auth';
 import { toTagged } from '@zgeoff/std';
 
 export interface AuthAdminInput {
@@ -16,12 +16,7 @@ export type AddClientAnswer =
   | { 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 type RemoveClientAnswer = { readonly kind: 'removed' } | { readonly kind: 'not-found' };
 
 export interface EnrollmentLink {
   readonly token: string;
@@ -72,17 +67,13 @@ export function createAuthAdmin(input: AuthAdminInput): AuthAdmin {
     },
     listClients: () => auth.clients.list(),
     removeClient: async (clientID) => {
-      const clients = await auth.clients.list();
-
-      const answer = pickClientToRemove(clients, clientID);
-
-      if (answer.kind === 'remove') {
-        await auth.clients.remove(answer.name);
+      try {
+        await auth.clients.remove(toTagged<OAuthClientID>(clientID));
 
         return { kind: 'removed' };
+      } catch (error) {
+        return pickRemoveRefusal(error);
       }
-
-      return answer;
     },
     listGrants: async () => {
       const grants = await auth.grants.list();
@@ -114,24 +105,14 @@ function pickAddRefusal(error: unknown, name: string): AddClientAnswer {
   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) {
+// The package refuses an unknown client ID with a coded error; any other error is not the owner's
+// input.
+function pickRemoveRefusal(error: unknown): RemoveClientAnswer {
+  if (error instanceof MCPAuthError && error.code === 'not-found') {
     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 };
+  throw error;
 }
 
 function toAuthGrantView(grant: GrantView): AuthGrantView {

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

@@ -1,6 +1,5 @@
-import { DEFAULT_PATHS } from '@zgeoff/mcp-auth';
+import { DEFAULT_PATHS, normalizeClientName } from '@zgeoff/mcp-auth';
 import type { SecurityEvent } from '@zgeoff/mcp-auth';
-import { normalizeClientName } from './normalize-client-name.ts';
 
 // The IDs in an event are tagged strings, and a line needs only their text.
 type LoggedSecurityEvent = Omit<SecurityEvent, 'client' | 'correlationID'> & {

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

@@ -4,18 +4,27 @@ import { dirname } from 'node:path';
 import type { GrantScope } from '@boxxy/contract';
 import { grantScopes } from '@boxxy/contract';
 import { DEFAULT_PATHS, openMCPAuth } from '@zgeoff/mcp-auth';
-import type { MCPAuth, Requester } from '@zgeoff/mcp-auth';
+import type { MCPAuth, Requester, ServiceTokenFile } from '@zgeoff/mcp-auth';
 import { createMCPHTTPApp } from '@zgeoff/mcp-auth/elysia';
 import { createAuthAdmin } from '../auth/create-auth-admin.ts';
 import type { AuthAdmin } from '../auth/create-auth-admin.ts';
 import { createSecurityEventLog } from '../auth/create-security-event-log.ts';
 import { openAuthDatabase } from '../auth/open-auth-database.ts';
 import { runAuthMigrations } from '../migrations/run-auth-migrations.ts';
+import { serviceTokenPrefix } from '../service-tokens/constants.ts';
+import { readServiceTokenFile } from '../service-tokens/read-service-token-file.ts';
+import type { ServiceTokenReload } from '../service-tokens/reload-service-tokens.ts';
+import { startServiceTokenReloads } from '../service-tokens/start-service-token-reloads.ts';
 import type { AuthClock } from '../utils/types.ts';
 import { isLoopbackHost } from './is-loopback-host.ts';
 import { normalizePublicURL } from './normalize-public-url.ts';
 import type { McpServe } from './types.ts';
 
+export interface ServiceTokensOptions {
+  readonly file: string;
+  readonly onReload: (reload: ServiceTokenReload) => void;
+}
+
 export interface PublicDoorOptions {
   // The origin clients reach the door at: the OAuth issuer.
   readonly publicURL: string;
@@ -40,6 +49,11 @@ export interface PublicDoorOptions {
   // Answers an MCP request whose bearer token verified.
   readonly serveMCP: McpServe;
   readonly clock?: AuthClock;
+
+  // The file of the service clients that sign in with the client_credentials grant. The door reads
+  // it at start, and again on each SIGHUP, and reports each reload. With none, the door takes no
+  // service client.
+  readonly serviceTokens?: ServiceTokensOptions;
 }
 
 export interface PublicDoor {
@@ -70,8 +84,8 @@ const systemClock: AuthClock = {
 const NO_APP_PREFIX = '/.boxxy-none';
 
 // Opens and migrates the authorization database and builds the door's routes. Throws on a public
-// URL that is not an https origin, or not a loopback address while the door listens beyond
-// loopback.
+// URL that is neither https nor loopback while the door listens beyond loopback, and on a broken
+// service-token file, so a deploy never serves without its service clients.
 export async function createPublicDoor(options: PublicDoorOptions): Promise<PublicDoor> {
   const clock = options.clock ?? systemClock;
   const origin = normalizePublicURL(options.publicURL);
@@ -110,14 +124,21 @@ export async function createPublicDoor(options: PublicDoorOptions): Promise<Publ
     };
   };
 
+  const serviceTokens =
+    options.serviceTokens === undefined
+      ? null
+      : await readStartFile(options.serviceTokens.file, origin);
+
   mkdirSync(dirname(options.dbPath), { recursive: true });
 
   const sqlite = openAuthDatabase(options.dbPath);
 
-  const auth = await openAuth(sqlite, origin, clock, security).catch((error: unknown) => {
-    sqlite.close();
-    throw error;
-  });
+  const auth = await openAuth({ sqlite, origin, clock, security, serviceTokens }).catch(
+    (error: unknown) => {
+      sqlite.close();
+      throw error;
+    },
+  );
 
   const hosts = new Set<string>([new URL(origin).host]);
   const origins = new Set<string>([origin]);
@@ -149,6 +170,15 @@ export async function createPublicDoor(options: PublicDoorOptions): Promise<Publ
 
   const sweep = startSweep(auth, clock, options.onSweepError);
 
+  const stopReloads =
+    options.serviceTokens === undefined
+      ? () => Promise.resolve()
+      : startServiceTokenReloads({
+          auth,
+          path: options.serviceTokens.file,
+          onReload: options.serviceTokens.onReload,
+        });
+
   return {
     answerRequest: (request) => app.handle(request),
     addLocalPort: (port) => {
@@ -162,6 +192,8 @@ export async function createPublicDoor(options: PublicDoorOptions): Promise<Publ
     stop: async () => {
       sweep.stop();
 
+      await stopReloads();
+
       await auth.close();
 
       sqlite.close();
@@ -170,23 +202,45 @@ export async function createPublicDoor(options: PublicDoorOptions): Promise<Publ
   };
 }
 
-async function openAuth(
-  sqlite: Database,
-  origin: string,
-  clock: AuthClock,
-  security: ReturnType<typeof createSecurityEventLog>,
-): Promise<MCPAuth<GrantScope>> {
-  await runAuthMigrations(sqlite);
+async function readStartFile(path: string, origin: string): Promise<ServiceTokenFile<GrantScope>> {
+  const parsed = await readServiceTokenFile(path);
+
+  if (!parsed.ok) {
+    throw new Error(`the service-token file ${path} is not valid: ${parsed.reason}`);
+  }
+
+  if (parsed.file.resource !== `${origin}/mcp`) {
+    throw new Error(
+      `the service-token file ${path} is not valid: it names the resource ${parsed.file.resource}, where the door serves ${origin}/mcp`,
+    );
+  }
+
+  return parsed.file;
+}
+
+interface AuthOpening {
+  readonly sqlite: Database;
+  readonly origin: string;
+  readonly clock: AuthClock;
+  readonly security: ReturnType<typeof createSecurityEventLog>;
+  readonly serviceTokens: ServiceTokenFile<GrantScope> | null;
+}
+
+async function openAuth(opening: AuthOpening): Promise<MCPAuth<GrantScope>> {
+  await runAuthMigrations(opening.sqlite);
 
   return openMCPAuth({
-    database: sqlite,
-    origin,
+    database: opening.sqlite,
+    origin: opening.origin,
     productName: 'boxxy',
     scopes: grantScopes,
     paths: DEFAULT_PATHS,
     tables: { passkey: 'boxxy_passkey', enrollmentToken: 'boxxy_enrollment_token' },
-    clock,
-    security,
+    clock: opening.clock,
+    security: opening.security,
+    ...(opening.serviceTokens === null
+      ? {}
+      : { serviceTokens: { prefix: serviceTokenPrefix, file: opening.serviceTokens } }),
 
     // Each MCP request builds its own server and holds no stream open, so a revoke has nothing to
     // end beyond the tokens the package deletes.

package/src/index.ts

@@ -7,6 +7,16 @@ export type {
 } 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 type {
+  PublicDoor,
+  PublicDoorOptions,
+  ServiceTokensOptions,
+} from './http/create-public-door.ts';
+
 export { createPublicDoor } from './http/create-public-door.ts';
 export { isLoopbackHost } from './http/is-loopback-host.ts';
+export type { ServiceTokenReload } from './service-tokens/reload-service-tokens.ts';
+
+// The secret of a new service client, and the sha256 digest that its service-token file holds.
+export { mintServiceSecret } from '@zgeoff/mcp-auth';

package/src/service-tokens/constants.ts

@@ -0,0 +1,4 @@
+// The auth core routes a bearer by its first characters, so it needs a static-token prefix, though
+// boxxy refuses a file with a static token. It must not start with, or be the start of, the `svca_`
+// of each access token that the core issues to a service client.
+export const serviceTokenPrefix = 'boxxy_svc_';

package/src/service-tokens/parse-service-token-text.ts

@@ -0,0 +1,45 @@
+import type { GrantScope } from '@boxxy/contract';
+import { grantScopes } from '@boxxy/contract';
+import { parseServiceTokenFile } from '@zgeoff/mcp-auth';
+import type { ParsedServiceTokenFile } from '@zgeoff/mcp-auth';
+import { z } from 'zod';
+import { serviceTokenPrefix } from './constants.ts';
+
+// The package's parser, with two departures that the public door's design explains: a file of no
+// clients parses, so removing the last client revokes it, and a client with a static token is
+// refused, since anyone who read the file could send that token. No reason quotes the file.
+export function parseServiceTokenText(text: string): ParsedServiceTokenFile<GrantScope> {
+  const parsed = parseServiceTokenFile(text, { prefix: serviceTokenPrefix, scopes: grantScopes });
+
+  if (!parsed.ok) {
+    return findEmptyFile(text) ?? parsed;
+  }
+
+  const holder = parsed.file.clients.find((client) => client.tokens.length > 0);
+
+  return holder === undefined
+    ? parsed
+    : {
+        ok: false,
+        reason: `the client ${holder.name} holds a static token, and boxxy takes only secretDigests`,
+      };
+}
+
+const emptyFileSchema = z.strictObject({
+  resource: z.string().min(1),
+  clients: z.strictObject({}),
+});
+
+function findEmptyFile(text: string): ParsedServiceTokenFile<GrantScope> | null {
+  let raw: unknown;
+
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return null;
+  }
+
+  const empty = emptyFileSchema.safeParse(raw);
+
+  return empty.success ? { ok: true, file: { resource: empty.data.resource, clients: [] } } : null;
+}

package/src/service-tokens/read-service-token-file.ts

@@ -0,0 +1,22 @@
+import { readFile } from 'node:fs/promises';
+import type { GrantScope } from '@boxxy/contract';
+import type { ParsedServiceTokenFile } from '@zgeoff/mcp-auth';
+import { parseServiceTokenText } from './parse-service-token-text.ts';
+
+// The service clients in the file at `path`. A file that is missing or fails to parse gives the
+// reason, which never quotes the file.
+export async function readServiceTokenFile(
+  path: string,
+): Promise<ParsedServiceTokenFile<GrantScope>> {
+  let text: string;
+
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (error) {
+    const code = error instanceof Error && 'code' in error ? String(error.code) : 'unknown';
+
+    return { ok: false, reason: `the file cannot be read (${code})` };
+  }
+
+  return parseServiceTokenText(text);
+}

package/src/service-tokens/reload-service-tokens.ts

@@ -0,0 +1,33 @@
+import type { GrantScope } from '@boxxy/contract';
+import { MCPAuthError } from '@zgeoff/mcp-auth';
+import type { MCPAuth } from '@zgeoff/mcp-auth';
+import { readServiceTokenFile } from './read-service-token-file.ts';
+
+export type ServiceTokenReload =
+  | { readonly kind: 'replaced'; readonly clients: number }
+  | { readonly kind: 'kept'; readonly reason: string };
+
+// Reads the service-token file again and hands it to the auth core. A file that fails to read or
+// parse, or that names another resource, leaves the clients the core holds as they were.
+export async function reloadServiceTokens(
+  auth: Pick<MCPAuth<GrantScope>, 'replaceServiceTokens'>,
+  path: string,
+): Promise<ServiceTokenReload> {
+  const parsed = await readServiceTokenFile(path);
+
+  if (!parsed.ok) {
+    return { kind: 'kept', reason: parsed.reason };
+  }
+
+  try {
+    auth.replaceServiceTokens(parsed.file);
+  } catch (error) {
+    if (error instanceof MCPAuthError) {
+      return { kind: 'kept', reason: error.message };
+    }
+
+    throw error;
+  }
+
+  return { kind: 'replaced', clients: parsed.file.clients.length };
+}

package/src/service-tokens/start-service-token-reloads.ts

@@ -0,0 +1,51 @@
+import type { GrantScope } from '@boxxy/contract';
+import type { MCPAuth } from '@zgeoff/mcp-auth';
+import { reloadServiceTokens } from './reload-service-tokens.ts';
+import type { ServiceTokenReload } from './reload-service-tokens.ts';
+
+export interface ServiceTokenReloads {
+  readonly auth: Pick<MCPAuth<GrantScope>, 'replaceServiceTokens'>;
+  readonly path: string;
+  readonly onReload: (reload: ServiceTokenReload) => void;
+}
+
+// Each SIGHUP reads the service-token file again and reports the outcome. Reloads run one at a
+// time, so an older read never lands after a newer one. The returned function stops listening and
+// waits for the last reload.
+export function startServiceTokenReloads(reloads: ServiceTokenReloads): () => Promise<void> {
+  let reloading = Promise.resolve();
+
+  const onHangUp = (): void => {
+    const previous = reloading;
+
+    reloading = (async () => {
+      await previous;
+      await runReload(reloads);
+    })();
+  };
+
+  process.on('SIGHUP', onHangUp);
+
+  return async () => {
+    process.off('SIGHUP', onHangUp);
+
+    await reloading;
+  };
+}
+
+async function runReload(reloads: ServiceTokenReloads): Promise<void> {
+  const reload = await reloadServiceTokens(reloads.auth, reloads.path).catch(
+    (error: unknown): ServiceTokenReload => ({
+      kind: 'kept',
+      reason: `the reload failed: ${String(error)}`,
+    }),
+  );
+
+  // a report that throws must not reject the chain, which would skip every later reload and fail
+  // the door's stop; stderr is the one place left to say so
+  try {
+    reloads.onReload(reload);
+  } catch (error) {
+    process.stderr.write(`the service-token reload was not reported: ${String(error)}\n`);
+  }
+}

package/dist/auth/normalize-client-name.d.ts

@@ -1 +0,0 @@
-export declare function normalizeClientName(raw: unknown, fallback?: string, maxLength?: number): string;

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

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