@boopkit/cap-oauth-server 0.1.4 → 0.3.1

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

@@ -0,0 +1,86 @@
+/**
+ * Garbage-collect abandoned OAuth client registrations.
+ *
+ * Run with `npm run oauth:prune-clients`. **Schedule it** — see below.
+ *
+ * ## What it deletes, and what stops it
+ *
+ * `POST /oauth/register` and the Client ID Metadata Document path both write a
+ * registry row for a caller nobody authenticated. Most of those rows are real
+ * connectors. Some are a script that walked away, and those never go anywhere:
+ * no consent, no grant, no token. After thirty days they are garbage, and this
+ * is what collects them.
+ *
+ * A row is deleted only when **nobody has that client connected** — that is,
+ * when no user's `oauth-grants` holds a live entry naming its `publicId`. The
+ * capability owns that question (`createClientInUsePredicate`), because the row
+ * that matters is the one carrying the `publicId` every live token for that
+ * client has as its prefix.
+ *
+ * Rows an operator wrote with `npm run oauth:seed-clients` are never touched,
+ * however old they are. Only the two unauthenticated modes are swept.
+ *
+ * ## Scheduling it
+ *
+ * Nothing here runs on a timer by itself, and an unscheduled prune is the same
+ * as no prune: `OAUTH_MAX_REGISTERED_CLIENTS` then becomes the only bound on
+ * registry growth, and a deployment that reaches it starts refusing legitimate
+ * registrations. Pick one:
+ *
+ *   - **Heroku Scheduler** (or your platform's equivalent): run
+ *     `npm run oauth:prune-clients` daily.
+ *   - **cron**, on a host you control:
+ *     `0 4 * * * cd /srv/app && npm run oauth:prune-clients`
+ *   - **cap-background-jobs**, if this project has it: import
+ *     `pruneAbandonedOAuthClients` from a job controller's `onMessage` and give
+ *     the queue a daily entry in `src/scheduler.ts`. That is the right home once
+ *     the sweep is one of several recurring jobs.
+ *
+ * Daily is a suggestion, not a requirement. The sweep is idempotent and reads
+ * only rows older than the cutoff, so running it more often changes nothing but
+ * the size of each batch.
+ */
+
+import { createClientPruneJob } from '@boopkit/cap-oauth-server';
+
+import {
+  clientRegistryService,
+  grantService,
+  tokenService,
+} from '../services/oauth-server.service';
+
+/**
+ * How long an unconnected registration survives. Thirty days, per the plan.
+ *
+ * Shorten it if open registration is being abused; do not shorten it below the
+ * time a person plausibly takes between installing a connector and approving
+ * it, because that gap is exactly what this measures.
+ */
+const ABANDONED_AFTER_DAYS = 30;
+
+const pruneJob = createClientPruneJob({
+  clientRegistry: clientRegistryService,
+  grantService,
+  tokenService,
+  ttlMs: ABANDONED_AFTER_DAYS * 24 * 60 * 60 * 1000,
+});
+
+/** One sweep. Exported so a background-jobs consumer can call it directly. */
+export async function pruneAbandonedOAuthClients(): Promise<string[]> {
+  const { before, removed } = await pruneJob.run();
+  console.log(
+    `[oauth-server] pruned ${removed.length} abandoned client registration(s) ` +
+      `created before ${before.toISOString()}`,
+  );
+  for (const clientId of removed) console.log(`  removed ${clientId}`);
+  return removed;
+}
+
+if (require.main === module) {
+  pruneAbandonedOAuthClients()
+    .then(() => process.exit(0))
+    .catch((err) => {
+      console.error('Pruning abandoned OAuth clients failed:', err);
+      process.exit(1);
+    });
+}

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

@@ -20,6 +20,8 @@
  * `oauth-grants` and `oauth-codes` the only two properties it ever reaches.
  */
 
+import { promises as dns } from 'node:dns';
+
 import db from '../db';
 import UserService from './users.service';
 import {
@@ -43,7 +45,29 @@ export const clientRegistryService = createClientRegistryService(db.oauthClient,
   // is the seam boop's own tests drive; here it is the real network.
   fetch: globalThis.fetch as unknown as FetchLike,
   maxRegisteredClients: oauthServerConfig.maxRegisteredClients,
+  // Where a metadata document may live. A Client ID Metadata Document is
+  // fetched at a URL an unauthenticated caller chose, so without this the
+  // consent endpoint is an SSRF probe of whatever network this app runs in —
+  // the body is discarded, but existence and latency are readable off the
+  // response time. The capability refuses every literal private, loopback and
+  // link-local target on its own; this resolver is what extends that to a name
+  // like `db.internal.example` that merely *points* somewhere private.
+  //
+  // It lives here rather than in the package because a capability has no
+  // business importing `node:dns`. Swap it for your own if you run a resolver
+  // with a different view of the network.
+  metadataResolveHost: async (hostname) => {
+    const records = await dns.lookup(hostname, { all: true });
+    return records.map((record) => record.address);
+  },
+  // Two different questions, answered from one list here: what a client is
+  // granted when it asks for nothing, and what it may ask for at all. Narrow
+  // `defaultScopes` if you want a smaller default grant — but leave
+  // `scopesSupported` as the advertised list, because it is the ceiling that
+  // keeps an unauthenticated registrant from writing itself a scope this
+  // server's discovery document says it does not have.
   defaultScopes: oauthServerConfig.scopesSupported,
+  scopesSupported: 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

package/scaffold/views/oauth-consent-error.hbs

@@ -6,9 +6,16 @@
   redirect: sending an error to an unverified redirect URI is the open redirect.
   So the person is told here instead, on our own page.
 
-  The message names what was wrong with the request and nothing about the
-  registry — a page that distinguished "no such client" from "that client is
-  suspended" would be an enumeration oracle for whoever is probing.
+  The message names what was wrong, including when what was wrong is that the
+  client has been suspended. That distinction is deliberate. It is not the
+  enumeration oracle it looks like: a registered `client_id` is already
+  distinguishable from an unregistered one here — probe either with a
+  `redirect_uri` the client does not own and only the registered one is told the
+  URI is unregistered, which is a sentence RFC 6749 requires this page to say —
+  and a `client_id` is a public identifier regardless, carried in the
+  authorization URL of every user the client has ever sent. What naming the
+  suspension buys is a suspended client's operator reading the right column
+  instead of hunting a registration that is perfectly intact (boop-wwxg).
 --}}
 <div class="consent-page">
   <section class="consent-card consent-card--error">