@ultimat3/auth 22.14.0 → 23.0.0

package/CLAUDE.md

@@ -135,6 +135,11 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `deleteSessionsForUser`, `deleteSessionsForOrg`, `deleteSessionsCreatedBefore`); callers throw
   `X_NOT_IMPLEMENTED` naming the method.
 - An api key's scopes are the agent actor's scopes. Never union them with the owner's roles.
+- **`apiKeyResolver(() => store)` is the ONE token → caller mapping** (`api-key-resolver.ts`):
+  `verifyApiKey` → `apiKeyActor`, `X_API_KEY_INVALID` → `null`, everything else rethrown. Its
+  `ApiKeyCaller` is structurally http's `BearerCaller` and mcp's `ResolvedToken` — declared here
+  because tier 2 imports neither. The store is a thunk (a mount is declared before boot installs
+  the database client). No second in-memory key store: `MemoryAdapter` IS an `ApiKeyStore`.
 - Rotate the session id on any privilege change (`rotateSession`, called by `updatePrivileges` in
   `privileges.ts`), never patch the row.
 - **Every argon2 call goes through `kdfGate()`** — width 8, queue 64, `X_OVERLOADED` past it

package/README.md

@@ -663,6 +663,35 @@ const actor = apiKeyActor(await verifyApiKey(auth.adapter, plaintext));  // kind
 
 An api key's scopes become **exactly** the agent actor's scopes — never the owning user's roles.
 
+### The resolver a mount takes
+
+`apiKeyResolver(() => store)` is that last line as the `resolveToken` a bearer mount
+(`defineApi({ http: { mounts } })`) and an MCP endpoint (`defineAppMcp`) both take — one resolver
+for both doors.
+
+```ts
+import type { ApiKeyStore } from '@ultimat3/auth';
+import { apiKeyResolver, BuiltinAdapter } from '@ultimat3/auth';
+
+let keys: ApiKeyStore | undefined;
+
+/** `resolveToken: resolveKey` — on the mount, and on `defineAppMcp()`. */
+export const resolveKey = apiKeyResolver(() => {
+  keys ??= new BuiltinAdapter();
+  return keys;
+});
+```
+
+| Presented | Answer |
+|---|---|
+| a live key | `{ actor, scopes }` — the agent actor for the key's org, and its scopes as a `Set` |
+| malformed, unknown, wrong secret, revoked, expired | `null`, all five alike: the mount answers one indistinguishable 401 |
+| a store that FAILS | the throw, untouched — a database that is down is not a wrong key |
+
+The store is a THUNK, read when a token is presented: a mount is declared when its module is
+evaluated, and `new BuiltinAdapter()` takes the process's database client, which boot installs
+later. In a test the store is `new MemoryAdapter()` — every `AuthAdapter` is an `ApiKeyStore`.
+
 ## Errors
 
 | Code | When |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "22.14.0",
+  "version": "23.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,8 +32,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.14.0",
-    "@ultimat3/db": "22.14.0",
-    "@ultimat3/schema": "22.14.0"
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/db": "23.0.0",
+    "@ultimat3/schema": "23.0.0"
   }
 }

package/src/api-key-resolver.ts

@@ -0,0 +1,50 @@
+// Single responsibility: a presented API key → who is calling, in the shape a bearer mount and an
+// MCP endpoint both take as `resolveToken`. `verifyApiKey` answers a record or throws; this is the
+// one place that turns its ONE rejection into the `null` those surfaces answer 401 for — and
+// leaves everything else a throw, because "the database is down" is not "your key is wrong".
+
+import { type Clock, isUltimateError, systemClock } from '@ultimat3/core';
+import type { ApiKeyStore } from './adapter';
+import { apiKeyActor, verifyApiKey } from './api-keys';
+import type { PolicyActor } from './policy-bridge';
+
+/**
+ * What a verified key resolves to. Structurally `@ultimat3/http`'s `BearerCaller` and
+ * `@ultimat3/mcp`'s `ResolvedToken` — declared here because this tier can import neither.
+ */
+export interface ApiKeyCaller {
+  /** The agent actor: the key's org, and its scopes as the permissions a policy reads. */
+  readonly actor: PolicyActor;
+  /** The key's scopes — what the mount's scope map is cut by. */
+  readonly scopes: ReadonlySet<string>;
+}
+
+export interface ApiKeyResolverOptions {
+  readonly clock?: Clock | undefined;
+}
+
+/**
+ * `resolveToken: apiKeyResolver(() => keys)` on `defineApi({ http: { mounts } })` and on
+ * `defineAppMcp()` — one resolver for both.
+ *
+ * `store` is a THUNK, read when a token is presented and never captured: a mount is declared when
+ * its module is evaluated, and `new BuiltinAdapter()` takes the process's database client, which
+ * boot installs later. `() => new MemoryAdapter()` would be a new, empty store per request — hold
+ * the instance and return it.
+ */
+export function apiKeyResolver(
+  store: () => ApiKeyStore,
+  options: ApiKeyResolverOptions = {},
+): (token: string) => Promise<ApiKeyCaller | null> {
+  return async (token) => {
+    try {
+      const record = await verifyApiKey(store(), token, options.clock ?? systemClock);
+      return { actor: apiKeyActor(record), scopes: new Set(record.scopes) };
+    } catch (thrown) {
+      // Every way a key can be wrong is this one code, by `verifyApiKey`'s own design: a caller
+      // that could tell "revoked" from "unknown" could enumerate ids.
+      if (isUltimateError(thrown) && thrown.code === 'X_API_KEY_INVALID') return null;
+      throw thrown;
+    }
+  };
+}

package/src/index.ts

@@ -17,6 +17,8 @@ export type {
   UserStore,
   VerificationStore,
 } from './adapter';
+export type { ApiKeyCaller, ApiKeyResolverOptions } from './api-key-resolver';
+export { apiKeyResolver } from './api-key-resolver';
 export type { ApiKeySummary, IssueApiKeyInput, IssuedApiKey, ParsedApiKey } from './api-keys';
 export {
   API_KEY_NAMESPACE,

package/src/auth-fixture.ts

@@ -1,26 +0,0 @@
-// Single responsibility: the three values every credential-flow suite needs — cheap KDF
-// parameters, the password they all sign in with, and the `AuthError` catcher. Three test files
-// share them, and three private copies is three chances for one to drift from what the flow
-// actually enforces. Not part of the public API — `index.ts` deliberately does not re-export it.
-
-import { AuthError } from './errors';
-import type { PasswordParams } from './password';
-
-// Fast KDF parameters: these tests are about the credential flow, not argon2's cost.
-export const FAST_PARAMS: PasswordParams = { algorithm: 'argon2id', memoryCost: 8192, timeCost: 1 };
-
-export const PASSWORD = 'correct-horse-battery-staple-42';
-
-/** Captures the thrown `AuthError`, or `undefined` when the call unexpectedly resolved. The
- *  caller's `expect(error?.code).toBe(...)` is then the assertion that fails, naming the code it
- *  wanted — a sentinel thrown from in here would carry no code and no fix. Anything that is not
- *  an `AuthError` is rethrown untouched: this helper never swallows an unexpected failure. */
-export const caught = async (fn: () => Promise<unknown>): Promise<AuthError | undefined> => {
-  try {
-    await fn();
-    return undefined;
-  } catch (error) {
-    if (error instanceof AuthError) return error;
-    throw error;
-  }
-};

package/src/id-token-fixture.ts

@@ -1,20 +0,0 @@
-// Single responsibility: the one way this package's tests mint an id token. Three OAuth test
-// files each needs a base64url-encoded JWT, and three private copies of the encoder is three
-// chances for one to drift from what `decodeIdToken` actually parses. Not part of the public
-// API — `index.ts` deliberately does not re-export it.
-
-import type { IdTokenClaims } from './id-token';
-import { base64Url } from './tokens';
-
-/** `base64Url` takes bytes because every real secret is bytes; a JWT segment is text. */
-export const base64UrlText = (value: string): string => base64Url(new TextEncoder().encode(value));
-
-/**
- * Header, payload, and a signature that is not one. Signatures are never checked here — the
- * token is only ever read straight off the token endpoint — so a fixture needs no signer.
- */
-// The union, and not `Record<string, unknown>` alone: `IdTokenClaims` is an `interface`, so it has
-// no implicit index signature and the one shape this fixture exists to serialise was the one shape
-// it refused. The record arm stays for the malformed payloads `id-token.test.ts` builds by hand.
-export const unsignedJwt = (claims: IdTokenClaims | Readonly<Record<string, unknown>>): string =>
-  `${base64UrlText('{"alg":"RS256"}')}.${base64UrlText(JSON.stringify(claims))}.signature`;

package/src/oauth-login-fixture.ts

@@ -1,53 +0,0 @@
-// The fixtures the three `oauth-login` suites share: the frozen instant, a fresh
-// `MemoryAdapter`-backed `Auth`, the two request bodies, the code of a rejection and a JSON
-// `Response`. Shared rather than copied — three suites building their own `Auth` would be three
-// flows that agree only by construction, the same reason `backfill-pass-fixture.ts` exists.
-
-import { frozenClock, isUltimateError } from '@ultimat3/core';
-import { type Auth, defineAuth } from './auth';
-import { MemoryAdapter } from './memory-adapter';
-import type { OAuthTokens } from './oauth-exchange';
-import type { OAuthProfile } from './oauth-profile';
-
-export const NOW = new Date('2026-08-09T12:00:00.000Z');
-
-export const credentials = { clientId: 'client-id', clientSecret: 'client-secret' };
-
-/** One adapter and the `Auth` over it, minted per `beforeEach` — never shared between tests. */
-export const freshAuth = (): { adapter: MemoryAdapter; auth: Auth } => {
-  const adapter = new MemoryAdapter();
-  return {
-    adapter,
-    auth: defineAuth({ adapter, clock: frozenClock(NOW), providers: ['github', 'google'] }),
-  };
-};
-
-export const profile = (overrides: Partial<OAuthProfile> = {}): OAuthProfile => ({
-  provider: 'github',
-  providerAccountId: '583231',
-  email: 'ada@example.com',
-  emailVerified: true,
-  name: 'Ada Lovelace',
-  ...overrides,
-});
-
-export const tokens = (overrides: Partial<OAuthTokens> = {}): OAuthTokens => ({
-  accessToken: 'gho_first',
-  refreshToken: null,
-  expiresAt: null,
-  idToken: null,
-  claims: null,
-  ...overrides,
-});
-
-export const codeOf = async (call: Promise<unknown>): Promise<string> => {
-  try {
-    await call;
-  } catch (error) {
-    return isUltimateError(error) ? error.code : `not-an-UltimateError: ${String(error)}`;
-  }
-  return 'did-not-throw';
-};
-
-export const json = (body: unknown): Response =>
-  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' } });