@boopkit/cap-oauth-server 0.1.0

package/scaffold/src/middleware/oauth-server.ts

@@ -0,0 +1,227 @@
+/**
+ * @boopkit/cap-oauth-server — routes and middleware, pre-wired from
+ * OAuthServerService.
+ *
+ * Three mounts, and they are deliberately separate.
+ *
+ * **`oauthDiscoveryRoutes`** carries the two `.well-known` documents. They
+ * mount **outside `/api`** and are reachable with **no authentication** — they
+ * are what a client reads before it holds any credential at all, so a 401 here
+ * is a connect failure the client cannot recover from. They need no session,
+ * which is why the hook mounts them early.
+ *
+ * **`oauthServerRoutes`** carries everything that needs the request context
+ * cap-users builds. It mounts at `preRoutes` order 54, after cap-users'
+ * `addAuthContext` at 16 — the consent screen reads `res.locals.auth` to decide
+ * whether it is showing a consent card, a login form or a signup form. The
+ * back-channel endpoints — `POST /oauth/register`, `POST /oauth/token` and
+ * `POST /oauth/revoke` — need no session at all, since no browser is behind
+ * them, but they live here so the OAuth surface is one mount rather than four
+ * that have to be kept in step.
+ * The `/connections` screen is on this mount too, gated by cap-users'
+ * `requireAuth`: it is an ordinary page of the application, met by a person in a
+ * browser rather than by a connector.
+ *
+ * **`resolveOAuthBearer`** is the resource-server half and is **not** mounted
+ * by a hook. It goes on the routers an application actually wants to expose to
+ * a connector, which is a decision only that application can make. Mounting it
+ * app-wide would put an OAuth door on every route in the site.
+ *
+ * ## Two bearer doors on one header, and why that is safe here
+ *
+ * cap-users' `resolveBearer` reads the same `Authorization` header for API
+ * keys. Both are built from the same `createBearerMiddleware`, and — the part
+ * that matters — **both refuse rather than fall through** to the session
+ * cookie. The shape the spec warns against is a silent fallback, which lets a
+ * request carrying a revoked credential succeed on the strength of a cookie the
+ * caller was not presenting. Neither of these does that. Do not mount both on
+ * one router: pick the door that router's callers use.
+ */
+
+import {
+  createConnectionsRouter,
+  createConsentRouter,
+  createDiscoveryRouter,
+  createOAuthResourceServer,
+  createRegistrationRouter,
+  createRevocationRouter,
+  createTokenRouter,
+} from '@boopkit/cap-oauth-server';
+import { Router, type Request, type Response } from 'express';
+
+import { requireAuth } from './auth';
+import OAuthServerService from '../services/oauth-server.service';
+import UserService from '../services/users.service';
+
+const {
+  config,
+  clientRegistryService,
+  tokenService,
+  grantService,
+  authorizationCodeService,
+  revocationService,
+} = OAuthServerService;
+
+/** `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`. */
+const oauthDiscoveryRoutes = createDiscoveryRouter(config);
+
+/**
+ * The browser-facing and back-channel OAuth surface.
+ *
+ * Scope descriptions are read from `app.locals.oauthScopeDescriptions` at render
+ * time, so an application that populates them after this module is imported —
+ * which is every boop application, since this mount is injected above the
+ * application's own `app.locals` assignments — still works. The warning naming
+ * any advertised scope you have not described reads the same value on the first
+ * request the router serves, so it tells you the truth about your own wiring
+ * rather than about an argument the scaffold does not pass. That warning is the
+ * only thing standing between a developer and a consent page that asks a user to
+ * approve `workflows:advance`.
+ *
+ * Pass `scopeDescriptions` below only for words you want as a default;
+ * `app.locals` overrides it key by key.
+ */
+const oauthServerRoutes = Router();
+
+oauthServerRoutes.use(
+  createRegistrationRouter({
+    clientRegistry: clientRegistryService,
+    rateLimit: {
+      limit: config.registrationRateLimit,
+      windowMs: config.registrationRateWindowMs,
+    },
+  }),
+);
+
+oauthServerRoutes.use(
+  createConsentRouter({
+    clientRegistry: clientRegistryService,
+    authorizationCodeService,
+    // How somebody signs in on this page is your decision, not the
+    // capability's — the same way `requireSignIn` below is. These two adapters
+    // are cap-users straight through, which is right for an application whose
+    // login page calls `authService.login` too.
+    //
+    // If yours does not — the common reason is minting the `email` identity
+    // later than signup, so `authService.login` cannot find a person your own
+    // login form admits — pass the function your login controller calls here
+    // instead. Two doors that disagree about one password cannot be explained
+    // to the person standing in front of them: cap-users returns one generic
+    // failure on purpose, so that saying more would confirm the account exists.
+    signIn: ({ email, password, sessionToken }) =>
+      UserService.authService.login(email, password, sessionToken),
+    register: (registration) => UserService.authService.signup(registration),
+    scopesSupported: config.scopesSupported,
+    // Describe every scope you advertise, in your app's composition root:
+    //   app.locals.oauthScopeDescriptions = { profile: 'See your name and…' };
+    scopeDescriptions: undefined,
+  }),
+);
+
+oauthServerRoutes.use(
+  createTokenRouter({
+    clientRegistry: clientRegistryService,
+    tokenService,
+    grantService,
+    authorizationCodeService,
+  }),
+);
+
+/**
+ * `POST /oauth/revoke` — RFC 7009, where a connector hands a token back.
+ *
+ * The third of the three ways a connection ends, and the only one a piece of
+ * software rather than a person starts. It is mounted because the discovery
+ * document advertises `revocation_endpoint`, and this capability's rule is that
+ * advertising an endpoint which answers 404 is a lie a client cannot interpret.
+ *
+ * A refresh token presented here ends the whole grant; an access token ends only
+ * itself. The controller's header argues both, and the second one is the
+ * surprising half.
+ */
+oauthServerRoutes.use(
+  createRevocationRouter({
+    clientRegistry: clientRegistryService,
+    tokenService,
+    revocationService,
+  }),
+);
+
+/**
+ * `/connections` — where a person sees what they have connected and disconnects
+ * one. An ordinary page of the application, gated by cap-users' `requireAuth`
+ * like every other page, and linked to from wherever your account settings live.
+ *
+ * `requireAuth` is injected rather than reached for, so this capability never
+ * forms its own opinion about what "signed in" means. Change `basePath` if
+ * `/connections` collides with a route you already have; every link on both
+ * pages is built from it.
+ */
+oauthServerRoutes.use(
+  createConnectionsRouter({
+    grantService,
+    revocationService,
+    clientRegistry: clientRegistryService,
+    requireSignIn: requireAuth(),
+  }),
+);
+
+/**
+ * Resolve `Authorization: Bearer <oauth access token>` onto `req.user`, and the
+ * grant behind it onto `req.oauthGrant`. Labels the request `'oauth'`, which is
+ * what makes it fail `requireApiKey` by construction.
+ *
+ * Mount it on the router you are protecting, ahead of `requireOAuth`:
+ *
+ *   app.use('/api/mcp', resolveOAuthBearer, requireOAuth('profile'), mcpRoutes);
+ *
+ * Both come out of one factory so they cannot be given different
+ * `WWW-Authenticate` challenges. A caller with a bad token is refused by the
+ * resolver and a caller with no token at all by the gate, so both have to carry
+ * the `resource_metadata` pointer — and Claude does not honour that header on a
+ * 200, which makes the 401 the only place it can arrive.
+ */
+const { resolveBearer: resolveOAuthBearer, requireOAuth } =
+  createOAuthResourceServer(
+  {
+    authService: UserService.authService,
+    identityService: UserService.identityService,
+    userService: UserService.userService,
+  },
+  {
+    tokenService,
+    grantService,
+    findUserById: (userId) => UserService.userService.findById(userId),
+    // RFC 9728: point an unauthenticated caller at the document that tells it
+    // where to go. `requireOAuth` sends this same value, because the resolver
+    // hands it forward on the request rather than it being configured twice.
+    challenge: `Bearer resource_metadata="${config.issuer}/.well-known/oauth-protected-resource"`,
+  },
+);
+
+/**
+ * `GET /api/oauth/whoami` — the smallest protected resource there is.
+ *
+ * It exists so this scaffold ships one route the guard is actually mounted on,
+ * rather than only an import somebody is told to use. That makes it the thing to
+ * curl with a fresh access token when you are checking a deployment end to end:
+ * it answers with the user the token resolved to and the scopes the **grant**
+ * currently carries, which is what the guard reads on every request.
+ *
+ * Delete it once you have a real protected surface, or keep it — it grants a
+ * connector nothing it did not already have by holding the token.
+ */
+oauthServerRoutes.get(
+  '/api/oauth/whoami',
+  resolveOAuthBearer,
+  requireOAuth(),
+  (req: Request, res: Response) => {
+    res.json({
+      userId: (req.user as unknown as { id: number } | undefined)?.id,
+      clientId: req.oauthGrant?.client_id ?? null,
+      scopes: req.oauthGrant?.scopes ?? [],
+    });
+  },
+);
+
+export { oauthDiscoveryRoutes, oauthServerRoutes, resolveOAuthBearer, requireOAuth };

package/scaffold/src/scripts/seed-oauth-clients.ts

@@ -0,0 +1,72 @@
+/**
+ * Seed the operator's static OAuth clients.
+ *
+ * Run with `npm run oauth:seed-clients`.
+ *
+ * ## What a static client is for
+ *
+ * Two of the three registration modes need no operator: a connector that
+ * supports RFC 7591 registers itself, and one that publishes a Client ID
+ * Metadata Document is picked up on first sight. A *static* client is the third
+ * case — software you decided to trust, whose `client_id` you chose, and whose
+ * redirect URIs you are vouching for yourself.
+ *
+ * The registration endpoint cannot modify or delete a row written here. That is
+ * checked in `ClientRegistryService`, not left to convention: `/oauth/register`
+ * is unauthenticated, and a client the operator vouched for must not be
+ * rewritable by a stranger.
+ *
+ * ## Editing this file
+ *
+ * Add your clients to `STATIC_CLIENTS` below and re-run. Seeding is idempotent:
+ * a second run updates the metadata of an existing row and **keeps its
+ * `publicId`**, so live tokens — which carry that value as their prefix — keep
+ * resolving.
+ */
+
+import { clientRegistryService } from '../services/oauth-server.service';
+import type { StaticClientInput } from '@boopkit/cap-oauth-server';
+
+/**
+ * The clients this deployment trusts by name.
+ *
+ * The example below is Claude Code, which binds an ephemeral loopback port at
+ * connect time — hence two loopback entries with no port. `matchRedirectUri`
+ * relaxes the port for loopback `http` and for nothing else (RFC 8252 §7.3), so
+ * these two entries accept `http://127.0.0.1:52731/callback` and refuse
+ * `https://anywhere-else.example/callback`.
+ *
+ * A desktop or mobile application that is handed the response by its operating
+ * system registers its own URI scheme instead — `claude://oauth/callback`, or
+ * the reverse-DNS form `com.example.app:/oauth2redirect/cb` (§7.1). Those are
+ * matched exactly, port included, because there is no ephemeral port involved.
+ *
+ * Delete it if you do not want it: an empty array is a valid configuration and
+ * the seed is then a no-op.
+ */
+const STATIC_CLIENTS: StaticClientInput[] = [
+  {
+    clientId: 'claude-code',
+    name: 'Claude Code',
+    description: 'Anthropic’s coding agent, connecting from your own machine',
+    clientUri: 'https://claude.com/claude-code',
+    redirectUris: ['http://localhost/callback', 'http://127.0.0.1/callback'],
+  },
+];
+
+export async function seedStaticClients(): Promise<void> {
+  for (const client of STATIC_CLIENTS) {
+    const row = await clientRegistryService.registerStaticClient(client);
+    console.log(`  ${row.clientId} → publicId ${row.publicId} (${row.redirectUris.length} redirect URIs)`);
+  }
+  console.log(`Seeded ${STATIC_CLIENTS.length} static OAuth client(s).`);
+}
+
+if (require.main === module) {
+  seedStaticClients()
+    .then(() => process.exit(0))
+    .catch((err) => {
+      console.error('Seeding static OAuth clients failed:', err);
+      process.exit(1);
+    });
+}

package/scaffold/src/services/oauth-server.service.ts

@@ -0,0 +1,101 @@
+/**
+ * @boopkit/cap-oauth-server — service wiring.
+ *
+ * The one file that knows both halves: the app's Prisma client and cap-users'
+ * services on one side, the capability's services on the other. Everything with
+ * a decision in it lives in `@boopkit/cap-oauth-server`; this binds it.
+ *
+ * ## The identity boundary
+ *
+ * `db.oauthClient` is the *only* model this capability touches. Users,
+ * accounts, identities and properties belong to cap-users, and this capability
+ * reaches them through the services `users.service` already built — never
+ * through `db`. A `db.user` / `db.account` / `db.userIdentity` (and friends)
+ * anywhere under `src/` is what the import audit in boop's suite fails on by
+ * name.
+ *
+ * The two cap-users services handed over below arrive as the narrow
+ * `IdentityStore` and `PropertyStore` ports the package declares. The package
+ * cannot ask for more than those ports allow, which is what keeps
+ * `oauth-grants` and `oauth-codes` the only two properties it ever reaches.
+ */
+
+import db from '../db';
+import UserService from './users.service';
+import {
+  createAuthorizationCodeService,
+  createClientRegistryService,
+  createGrantService,
+  createRevocationService,
+  createTokenService,
+  matchRedirectUri,
+  readServerConfig,
+  type FetchLike,
+  type IdentityStore,
+  type PropertyStore,
+} from '@boopkit/cap-oauth-server';
+
+/** Read once at boot: a running process has one answer, and clamps warn once. */
+export const oauthServerConfig = readServerConfig(process.env);
+
+export const clientRegistryService = createClientRegistryService(db.oauthClient, {
+  // Node's global `fetch`, narrowed to the shape the capability declares. This
+  // is the seam boop's own tests drive; here it is the real network.
+  fetch: globalThis.fetch as unknown as FetchLike,
+  maxRegisteredClients: oauthServerConfig.maxRegisteredClients,
+  defaultScopes: oauthServerConfig.scopesSupported,
+  onMetadataRefreshFailed: (clientId, err) => {
+    // A stale document that could not be refreshed is served from cache, so the
+    // user's consent still works — but the failure is not silent, because a
+    // client whose document has been unreachable for a week is a client whose
+    // redirect URIs may have changed under us.
+    console.warn(`[oauth-server] metadata refresh failed for ${clientId}:`, err);
+  },
+});
+
+/**
+ * The token service reads both TTLs here, once, at construction — never per
+ * request. An out-of-range value is clamped with a warning naming the value and
+ * the bound rather than refused; an application should not fail to boot over a
+ * token lifetime.
+ */
+export const tokenService = createTokenService({
+  identityStore: UserService.identityService as IdentityStore,
+  accessTokenTtlSeconds: oauthServerConfig.accessTokenTtlSeconds,
+  refreshTokenTtlSeconds: oauthServerConfig.refreshTokenTtlSeconds,
+});
+
+export const grantService = createGrantService({
+  propertyStore: UserService.userPropertyService as PropertyStore,
+});
+
+export const authorizationCodeService = createAuthorizationCodeService({
+  tokenService,
+  propertyStore: UserService.userPropertyService as PropertyStore,
+  // Injected rather than imported inside the service, so RFC 8252's
+  // loopback-port exception lives in one function with its own test table.
+  matchRedirectUri,
+});
+
+/**
+ * Disconnecting a client: end the grant with a reason, then end-date its token
+ * rows so the client's very next request fails whatever its access token's
+ * stated lifetime says.
+ *
+ * Nothing is deleted. The ended grant record is the audit trail, and it is what
+ * distinguishes a revoked client from one that merely rotated its refresh token
+ * — rotation end-dates identity rows too, so those rows cannot carry the signal.
+ */
+export const revocationService = createRevocationService({ grantService, tokenService });
+
+const OAuthServerService = {
+  name: 'oauth_server' as const,
+  config: oauthServerConfig,
+  clientRegistryService,
+  tokenService,
+  grantService,
+  authorizationCodeService,
+  revocationService,
+};
+
+export default OAuthServerService;