@boopkit/cap-oauth-server 0.1.4 → 0.3.1

package/dist/client-prune.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClientInUsePredicate = createClientInUsePredicate;
+exports.createClientPruneJob = createClientPruneJob;
+const client_registry_service_js_1 = require("./client-registry-service.js");
+const grant_service_js_1 = require("./grant-service.js");
+/**
+ * The real `isInUse` predicate: is anybody still connected to this client?
+ *
+ * Suitable for passing straight to `pruneAbandonedClients`. It is `false` for a
+ * client nobody ever connected and for one every user has disconnected, and
+ * `true` the moment one live grant names the client's `publicId`.
+ */
+function createClientInUsePredicate(options) {
+    const { grantService, tokenService } = options;
+    return async function isInUse(client) {
+        const userIds = await tokenService.findUserIdsForClient(client.publicId);
+        for (const userId of userIds) {
+            const grants = await grantService.list(userId);
+            // The full `client_public_id`, never a prefix of it: a `startsWith` here
+            // would let a neighbouring client's live grant keep this row alive, which
+            // is the same too-broad match `revokeClient` refuses for the same reason.
+            const connected = grants.some((grant) => grant.client_public_id === client.publicId && (0, grant_service_js_1.isGrantActive)(grant));
+            if (connected)
+                return true;
+        }
+        return false;
+    };
+}
+/**
+ * The scheduled sweep, as one callable object.
+ *
+ * A job rather than a loose function because the thing that was missing was a
+ * *call site*: a scaffolded application schedules `run()` — from its own cron,
+ * from Heroku Scheduler, or from a cap-background-jobs consumer — and the
+ * capability owns which rows go and which stay.
+ */
+function createClientPruneJob(options) {
+    const { clientRegistry } = options;
+    const ttlMs = options.ttlMs ?? client_registry_service_js_1.DEFAULT_ABANDONED_CLIENT_TTL_MS;
+    const now = options.now ?? (() => new Date());
+    const isInUse = createClientInUsePredicate(options);
+    return {
+        async run() {
+            const before = new Date(now().getTime() - ttlMs);
+            const removed = await clientRegistry.pruneAbandonedClients({ before, isInUse });
+            return { before, removed };
+        },
+    };
+}
+//# sourceMappingURL=client-prune.js.map

package/dist/client-prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-prune.js","sourceRoot":"","sources":["../src/client-prune.ts"],"names":[],"mappings":";;AA0EA,gEAqBC;AAkCD,oDAaC;AA7ID,6EAA+E;AAC/E,yDAAsE;AAiEtE;;;;;;GAMG;AACH,SAAgB,0BAA0B,CACxC,OAA2B;IAE3B,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IAE/C,OAAO,KAAK,UAAU,OAAO,CAAC,MAAmB;QAC/C,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEzE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC/C,yEAAyE;YACzE,0EAA0E;YAC1E,0EAA0E;YAC1E,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAC3B,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,KAAK,MAAM,CAAC,QAAQ,IAAI,IAAA,gCAAa,EAAC,KAAK,CAAC,CAC9E,CAAC;YACF,IAAI,SAAS;gBAAE,OAAO,IAAI,CAAC;QAC7B,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AA0BD;;;;;;;GAOG;AACH,SAAgB,oBAAoB,CAAC,OAA2B;IAC9D,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,4DAA+B,CAAC;IAC/D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;IAEpD,OAAO;QACL,KAAK,CAAC,GAAG;YACP,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,CAAC;YACjD,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,qBAAqB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YAChF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/client-registry-service.d.ts

@@ -1,5 +1,5 @@
 import { type FetchLike } from './metadata-document.js';
-import type { ClientMetadataInput, OauthClient, OauthClientDelegate, StaticClientInput } from './types.js';
+import type { ClientMetadataInput, ClientMode, OauthClient, OauthClientDelegate, StaticClientInput } from './types.js';
 /**
  * The client registry — who is asking, and what they are allowed to ask for.
  *
@@ -26,6 +26,11 @@ import type { ClientMetadataInput, OauthClient, OauthClientDelegate, StaticClien
  * `redirect_uris` required and validated at registration, a ceiling on total
  * rows, per-IP rate limiting at the transport, and a prune for rows that never
  * went anywhere.
+ *
+ * All four cover `metadata_document` as well as `dynamic`, because both modes
+ * are written on behalf of somebody nobody authenticated. Scoping them to
+ * `dynamic` is the shape of boop-jd4x: the CIMD path wrote an uncounted,
+ * unlimited, uncollected row per distinct URL a caller named.
  */
 /** Sensible RFC 7591 defaults for a client that asked for nothing specific. */
 export declare const DEFAULT_GRANT_TYPES: string[];
@@ -36,6 +41,22 @@ export declare const DEFAULT_METADATA_MAX_AGE_MS: number;
 export declare const DEFAULT_ABANDONED_CLIENT_TTL_MS: number;
 /** How many rows open registration may create before it starts refusing. */
 export declare const DEFAULT_MAX_REGISTERED_CLIENTS = 1000;
+/**
+ * The modes the ceiling and the prune are about: every row a stranger caused.
+ *
+ * `dynamic` is the obvious one — `POST /oauth/register` is an unauthenticated
+ * write. `metadata_document` is the one that was missed, and it is the same
+ * thing wearing a different hat: an unauthenticated `GET /oauth/authorize`
+ * naming an https `client_id` nobody vetted writes a permanent row too. Scoping
+ * the abuse controls to `dynamic` left that path with no ceiling, no limiter and
+ * no collector, so a loop over `?client_id=https://attacker.example/c?n=<N>`
+ * filled the table one row at a time (boop-jd4x).
+ *
+ * `static` is deliberately absent. An operator wrote those rows, and letting
+ * them consume the ceiling would let an operator's own seed script lock open
+ * registration shut.
+ */
+export declare const STRANGER_CREATED_MODES: readonly ClientMode[];
 export interface ClientRegistryServiceOptions {
     /**
      * The HTTP boundary for metadata documents. Required only if
@@ -43,22 +64,53 @@ export interface ClientRegistryServiceOptions {
      * never calls it.
      */
     fetch?: FetchLike;
-    /** Ceiling on `dynamic` rows. `Infinity` disables the check. */
+    /**
+     * Ceiling on rows a stranger caused — `dynamic` *and* `metadata_document`.
+     * `Infinity` disables the check. See `STRANGER_CREATED_MODES`.
+     */
     maxRegisteredClients?: number;
     /** Cache age past which a metadata document is re-fetched. */
     metadataMaxAgeMs?: number;
     metadataTimeoutMs?: number;
     metadataMaxBytes?: number;
     metadataMaxRedirects?: number;
+    /**
+     * Resolve a hostname to the addresses it points at, so that a *name* aimed at
+     * the internal network is refused like a literal address is.
+     *
+     * Optional and injected because this package has no business importing
+     * `node:dns` — the scaffold wires `dns.promises.lookup`. Without it the guard
+     * still refuses every literal private, loopback and link-local target; with
+     * it, `internal.example` resolving to `10.0.0.5` is refused too.
+     */
+    metadataResolveHost?: (hostname: string) => Promise<string[]>;
     /** Scopes a client may be granted, if it named none. */
     defaultScopes?: string[];
+    /**
+     * Every scope this server advertises — the ceiling on what any registration
+     * may claim, whoever wrote it.
+     *
+     * Registration is unauthenticated, so `scope` on the way in is a string a
+     * stranger chose. Storing it unfiltered makes the discovery document's
+     * `scopes_supported` untrue and puts an undescribed word in front of a user
+     * on the consent screen. Defaults to `defaultScopes`, which for a correctly
+     * wired server is the same list; an empty list bounds nothing, which is what
+     * a registry built with no scope configuration at all has always done.
+     */
+    scopesSupported?: string[];
     /** Injectable clock, so expiry and cache-age tests do not sleep. */
     now?: () => Date;
-    /** Called when a re-fetch fails and the cached copy is used instead. */
+    /**
+     * Called when a re-fetch fails and the cached copy is used instead.
+     *
+     * Not called for the one re-fetch failure that is thrown to the caller
+     * instead: a document that now declares an authentication method without
+     * offering `none`. See `resolveMetadataDocument`.
+     */
     onMetadataRefreshFailed?(clientId: string, err: unknown): void;
 }
 export interface PruneOptions {
-    /** Delete abandoned `dynamic` rows created before this instant. */
+    /** Delete abandoned stranger-created rows created before this instant. */
     before?: Date;
     /**
      * Is this row still in use?
@@ -91,13 +143,38 @@ export interface ClientRegistryService {
     suspend(clientId: string): Promise<OauthClient>;
     /** Re-enable a suspended client. */
     unsuspend(clientId: string): Promise<OauthClient>;
-    /** Registration-surface update. Refuses a `static` row. */
+    /**
+     * Amend a registered client's metadata. Refuses a `static` row.
+     *
+     * There is no HTTP route behind this and there is not meant to be: RFC 7592
+     * client management is deliberately not implemented (see the note on
+     * `refuseStatic`). This is the host application's own management API — what
+     * an admin screen or a support script calls — and it validates exactly what
+     * `registerDynamic` validates, so a client cannot reach a value through an
+     * amendment that it could not have registered in the first place.
+     */
     updateRegistration(clientId: string, input: ClientMetadataInput): Promise<OauthClient>;
-    /** Registration-surface delete. Refuses a `static` row. */
+    /**
+     * Remove a registered client. Refuses a `static` row.
+     *
+     * The same host-application surface as `updateRegistration`, and the blunt
+     * instrument of the two: it drops the row, and with it the `publicId` that
+     * every live token for that client carries as its prefix. Prefer `suspend`
+     * for a client that may still have tokens outstanding — see
+     * `pruneAbandonedClients`, which asks `isInUse` before deleting anything.
+     */
     deleteRegistration(clientId: string): Promise<void>;
-    /** How many rows the ceiling counts. */
+    /** How many rows the ceiling counts — see `STRANGER_CREATED_MODES`. */
     countRegistered(): Promise<number>;
-    /** Garbage-collect abandoned dynamic rows. Returns the client ids removed. */
+    /**
+     * Garbage-collect abandoned stranger-created rows. Returns the client ids
+     * removed.
+     *
+     * A `metadata_document` row is swept on the same terms as a `dynamic` one.
+     * Its metadata is re-fetchable, so re-creating it costs one request; what is
+     * not re-creatable is its `publicId`, which is the prefix every live token for
+     * that client carries — and that is exactly what `isInUse` is for.
+     */
     pruneAbandonedClients(options?: PruneOptions): Promise<string[]>;
 }
 /**

package/dist/client-registry-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-registry-service.d.ts","sourceRoot":"","sources":["../src/client-registry-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client-registry-service.d.ts","sourceRoot":"","sources":["../src/client-registry-service.ts"],"names":[],"mappings":"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"}