@dereekb/oauth-resource 14.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hapier Creative LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# @dereekb/oauth-resource
+
+The **resource-server** half of OAuth: verify a bearer token that somebody else issued.
+
+`@dereekb/firebase-server/oidc` is a complete authorization server, but its bearer middleware only
+works **in-process** — it validates by looking the token up in the provider's own Firestore adapter.
+Any service that is not that API process (a Docker'd sidecar, a worker, a standalone MCP host) needs
+to verify by **signature**, against a published JWKS, and that is what this package does.
+
+It is deliberately tiny. `jose` + `@dereekb/util` are the only hard dependencies; `express` and
+`cors` are optional peers used only by the `/express` subpath. Nothing Firebase, Nest, or
+oidc-provider shaped is anywhere in its install graph, so a plain Express service does not end up
+installing a native image library in order to check a signature.
+
+## Entry points
+
+| Entry | Purpose |
+|---|---|
+| `@dereekb/oauth-resource` | Issuer profiles + JWKS discovery, `verifyBearerJwt`, the RFC 6750 challenge builder, the RFC 9728 metadata document, and the `AuthInfo`-shaped verified caller. Framework-free. |
+| `@dereekb/oauth-resource/express` | `requireBearer()` middleware and `createWellKnownRouter()`. Adds `express` + `cors` as optional peers, and ships the `express-serve-static-core` `req.auth` augmentation. |
+| `@dereekb/oauth-resource/firebase` | The consume side of the user-scoped Firestore session bridge: `openFirebaseUserSession`, `firebaseUserSessionPool`, and the SDK-identity diagnostic. Adds `firebase` + `@dereekb/firebase` as optional peers. |
+
+## Trust model
+
+A resource server trusts a small, explicit set of **issuers**. The incoming token's `iss` claim
+selects one; that profile's JWKS verifies the signature; `jose` then enforces `iss` / `aud` / `exp` /
+`nbf` / `iat` with a 60 s tolerance. Two issuer kinds are built in:
+
+- **`firebase`** — Firebase Auth ID tokens for a project, verified against Google's shared
+  `securetoken` JWKS. The only accepted audience is the project id.
+- **`oidc`** — any OAuth 2.0 / OpenID Connect authorization server. Its `jwks_uri` is discovered
+  from `{iss}/.well-known/openid-configuration`, falling back to the conventional `{iss}/jwks`.
+
+```ts
+import { buildIssuerProfiles, verifyBearerJwt } from '@dereekb/oauth-resource';
+
+const profiles = buildIssuerProfiles({
+  firebaseProjectIds: ['my-project'],
+  oidcIssuers: ['https://api.example.com/oidc'],
+  audiences: ['https://db.example.com', 'https://db.example.com/mcp']
+});
+
+const verified = await verifyBearerJwt(token, { profiles });
+```
+
+Two behaviors here are load-bearing and deliberate:
+
+- **`getKey` is lazy, and discovery is memoized on success only.** A discovery outage surfaces as a
+  401 on the affected request instead of taking the service down at boot, and the next request
+  retries rather than latching onto the failure.
+- **The key resolver is injectable.** A spec passes `createLocalJWKSet(...)`, and an authorization
+  server verifying its *own* tokens in-process passes its local key set rather than making an HTTP
+  call back to itself.
+
+## The audience is the point
+
+An OAuth access token is issued **for a resource**. A client asks for one with RFC 8707
+`resource=https://db.example.com/mcp`, and the authorization server stamps that resource server's
+`audience` onto the token. Verifying `aud` is therefore what stops a token minted for one service
+from being replayed against another.
+
+On the dbx-components authorization-server side, that entry is declared with
+`buildOidcResourceServer({ url, scope, audience, accessTokenFormat, accessTokenTTL })` from
+`@dereekb/firebase-server/oidc`, and `firebaseServerIssuerProfiles()` emits the matching
+`buildIssuerProfiles` config from the same `OidcModuleConfig` — so an API and its satellites cannot
+drift on issuer or audience strings.
+
+**Set `accessTokenFormat: 'jwt'` for anything off-box.** The default format is opaque: a database
+key that only the issuing provider can validate. A remote service fundamentally cannot verify one.
+The trade-off is that a JWT access token has no adapter record and therefore **cannot be revoked
+before `exp`** — keep its TTL short.
+
+## Policy gates
+
+`verifyBearerJwt` proves *who* the caller is; it does not decide *what* they may do.
+
+- `requiredClaims` / `claimPredicate` gate on account claims. They apply to `firebase` issuers only
+  by default (`claimGateKinds`), because an OAuth access token carries scopes rather than app
+  account claims. A failure is `forbidden` (403 / `insufficient_scope`), not `unauthorized`.
+- Scope enforcement is per-route and belongs to the caller — the Express middleware's
+  `requiredScopes` covers the simple case.
+
+Every rejection throws an `OAuthResourceError` carrying a code (`unauthorized` / `forbidden`), an
+HTTP status, and a `toEnvelope()` body. Supply an `errorFactory` to throw your own API error type
+instead, and an `errorResponseFactory` on the middleware to shape the response body to match.
+
+## Express
+
+```ts
+import { createWellKnownRouter, requireBearer } from '@dereekb/oauth-resource/express';
+
+app.use(createWellKnownRouter({ resource: `${PUBLIC_URL}/mcp`, authorizationServers: [ISSUER], scopesSupported: SCOPES }));
+app.use('/mcp', requireBearer({ verify: { profiles }, resourceMetadataUrl: RESOURCE_METADATA_URL, realm: 'my-db' }));
+```
+
+`requireBearer` attaches the verified caller to `req.auth` in the MCP SDK's `AuthInfo` shape (a
+structurally identical local interface — taking an SDK peer dependency to borrow a five-field type
+was not worth it), and answers a failure with the correct RFC 6750 challenge: `invalid_request` when
+no token was presented, `invalid_token` when one was but failed, `insufficient_scope` on a 403 —
+each carrying the `resource_metadata=` discovery hint.
+
+`createWellKnownRouter` serves the RFC 9728 document at **both** the path-suffixed
+(`/.well-known/oauth-protected-resource/mcp`, what clients try first) and bare paths, CORS-open. It
+is hand-rolled rather than taken from the MCP SDK because the SDK's builder also wants the
+authorization-server metadata document, which a resource server never hosts — it points at one.
+
+## User-scoped Firestore sessions
+
+`@dereekb/oauth-resource/firebase` turns a verified bearer token carrying the `session.firestore`
+scope into a live, **rules-evaluated** `FirestoreContext` for that token's user:
+
+```
+verified bearer token (scope: session.firestore)
+  → GET <apiBaseUrl>/session/firestore           Authorization: Bearer <access_token>
+  → { uid, customToken, appCheckToken?, expiresAt }
+  → initializeApp → initializeAppCheck(CustomProvider) → signInWithCustomToken
+  → clientFirebaseFirestoreContextFactory(getFirestore(app))
+  → make<App>FirestoreCollections(ctx)           ← the same object the Angular app builds
+```
+
+The mint endpoint is `@dereekb/firebase-server`'s session module; this package is the consume side
+only.
+
+```ts
+import { firebaseUserSessionPool } from '@dereekb/oauth-resource/firebase';
+
+const pool = firebaseUserSessionPool({ namespace: 'my-service', firebase: FIREBASE_CLIENT_CONFIG, apiBaseUrl: API_BASE_URL });
+
+// `verified.subject` is the Firebase uid for a firebase-server-issued OIDC token
+const rows = await pool.useSession({ uid: verified.subject, accessToken }, async (session) => {
+  const collections = makeMyAppFirestoreCollections(session.firestoreContext);
+  return collections.thing.queryDocument(/* … */).getDocs();
+});
+```
+
+**This is not an Admin-SDK bypass — that is the whole point.** The client SDK is the only Firestore
+transport that carries a user ID token, so every read and write here is evaluated against
+`firestore.rules` exactly as it would be in the browser app, and the user's stored custom claims land
+at the top level of the exchanged ID token so `request.auth.token.<claim>` behaves identically. An
+Admin-SDK context reaching this path is a bug, and
+`inspectFirebaseClientFirestoreIdentity` reports it as `unexpected-driver`.
+
+The custom token is always minted for the presented token's own `auth.uid`, with no way to name
+another user. Pass `uid` to `openFirebaseUserSession` (the pool always does) and that property is
+asserted locally too, before any Firebase app is registered.
+
+### App Check comes first, and a session never reuses an app
+
+`initializeAppCheck` must run before any other Firebase call, or requests go out unattested and are
+rejected in production. It also means a session that mints its own credentials must initialize a
+**fresh** `FirebaseApp`: `initializeAppCheck` on an app whose provider is already initialized
+silently returns the existing instance when `CustomProvider.isEqual` matches, and `isEqual` compares
+`getToken.toString()` — the source text of the closure, which is identical across two closures built
+at the same call site over different tokens. Reusing an app therefore keeps the *first* attestation
+and drops the newly minted one. App reuse is the pool's job, at the session-object level.
+
+Every app is named `<namespace>::<scope>::<uid>` (scope defaults to the project id), so
+`closeFirebaseUserSessionApps({ namespace })` sweeps every app an owner registered from `getApps()`
+alone — no side registry, idempotent by construction.
+
+### Pool cap and TTL
+
+A signed-in `Auth` runs a token-refresh timer and a live `Firestore` holds handles, so both leak per
+user without teardown. The pool is the per-`(scope, uid)` lifecycle owner:
+
+- **Lease-based.** `useSession(input, fn)` borrows for the callback's duration; `openSession` +
+  `release()` is the escape hatch. Reference counting is what makes eviction safe — the pool never
+  tears down a session someone is mid-query on.
+- **`maxSessions` (default 32)** bounds *concurrently distinct users*. At cap the least-recently-used
+  **idle** entry is evicted. When every entry is leased the pool emits `over-capacity`, marks the LRU
+  entry for teardown-on-release, and **admits anyway**: the cap is a target, its overshoot is bounded
+  by the host's own request concurrency, and refusing a user because others are busy is worse than a
+  brief overshoot.
+- **TTL is driven by App Check, not Auth.** A signed-in `Auth` refreshes its ID token indefinitely;
+  the App Check token does not — it is minted once by the API with no local attestation to refresh
+  against. So the ceiling is the envelope's `expiresAt`, floored by `maxSessionAgeMs` (default one
+  hour, the Firebase credential ceiling). Past `expiresAt - refreshSkewMs` the whole app is torn down
+  and re-minted: one round trip, versus a silently unattested connection.
+
+### Credential handling
+
+A `FirestoreSessionCredentials` is a **bearer credential for its user**. The pool's own state is
+in-memory and dies with the process; this package ships the `FirestoreSessionCredentialsCache` port
+and the expiry policy but **no** persistent store. Supply one only if you can protect it at least as
+well as a 0600 file.

package/express/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";

package/express/index.esm.js

@@ -0,0 +1,321 @@
+import { isOAuthResourceError, OAuthResourceError, defaultOAuthResourceErrorFactory, buildBearerChallenge, bearerChallengeErrorForCode, oauthResourceAuthInfoForVerifiedBearer, readBearerToken, verifyBearerJwt, buildProtectedResourceMetadata, oauthProtectedResourcePathForResource, OAUTH_PROTECTED_RESOURCE_PATH } from '@dereekb/oauth-resource';
+import cors from 'cors';
+import { Router } from 'express';
+
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) resolve(value);
+    else Promise.resolve(value).then(_next, _throw);
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else obj[key] = value;
+    return obj;
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+// MARK: Constants
+/**
+ * Placeholder auth attached to every request when verification is disabled.
+ */ var AUTH_DISABLED_CLIENT_ID = 'dev';
+/**
+ * Lifetime, in seconds, stamped on the placeholder auth when verification is disabled.
+ */ var AUTH_DISABLED_EXPIRES_IN_SECONDS = 3600;
+/**
+ * Default {@link OAuthResourceErrorResponseFactory}. Reads an {@link OAuthResourceError}'s own
+ * status / code / envelope; anything else is reported as a generic 401.
+ *
+ * @param error - The thrown error.
+ * @returns The response to send.
+ */ var defaultOAuthResourceErrorResponseFactory = function defaultOAuthResourceErrorResponseFactory(error) {
+    var resourceError = isOAuthResourceError(error) ? error : new OAuthResourceError({
+        code: 'unauthorized',
+        message: 'Invalid bearer token.'
+    });
+    return {
+        status: resourceError.status,
+        code: resourceError.code,
+        body: resourceError.toEnvelope()
+    };
+};
+/**
+ * Express middleware that requires a valid bearer JWT (see {@link verifyBearerJwt}) and attaches it
+ * as `req.auth`. A failure answers with the configured error envelope plus an RFC 6750
+ * `WWW-Authenticate` challenge carrying the protected-resource metadata URL.
+ *
+ * @param config - Verification options plus the challenge / policy settings.
+ * @returns The middleware.
+ */ function requireBearer(config) {
+    var _config_errorResponseFactory, _config_requiredScopes, _config_verify_errorFactory;
+    var errorResponseFactory = (_config_errorResponseFactory = config.errorResponseFactory) !== null && _config_errorResponseFactory !== void 0 ? _config_errorResponseFactory : defaultOAuthResourceErrorResponseFactory;
+    var requiredScopes = (_config_requiredScopes = config.requiredScopes) !== null && _config_requiredScopes !== void 0 ? _config_requiredScopes : [];
+    var errorFactory = (_config_verify_errorFactory = config.verify.errorFactory) !== null && _config_verify_errorFactory !== void 0 ? _config_verify_errorFactory : defaultOAuthResourceErrorFactory;
+    return function(req, res, next) {
+        return _async_to_generator(function() {
+            var token, verified, authInfo, missingScope, error, response, challenge;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        token = readBearerToken(req.headers.authorization);
+                        _state.label = 1;
+                    case 1:
+                        _state.trys.push([
+                            1,
+                            5,
+                            ,
+                            6
+                        ]);
+                        if (!(config.authDisabled === true)) return [
+                            3,
+                            2
+                        ];
+                        req.auth = {
+                            token: AUTH_DISABLED_CLIENT_ID,
+                            clientId: AUTH_DISABLED_CLIENT_ID,
+                            scopes: [],
+                            expiresAt: Math.floor(Date.now() / 1000) + AUTH_DISABLED_EXPIRES_IN_SECONDS
+                        };
+                        return [
+                            3,
+                            4
+                        ];
+                    case 2:
+                        if (token === undefined) {
+                            throw errorFactory({
+                                code: 'unauthorized',
+                                message: 'Missing bearer token.'
+                            });
+                        }
+                        return [
+                            4,
+                            verifyBearerJwt(token, config.verify)
+                        ];
+                    case 3:
+                        verified = _state.sent();
+                        authInfo = oauthResourceAuthInfoForVerifiedBearer(verified);
+                        missingScope = requiredScopes.find(function(scope) {
+                            return !authInfo.scopes.includes(scope);
+                        });
+                        if (missingScope != null) {
+                            throw errorFactory({
+                                code: 'forbidden',
+                                message: 'Token is missing the required "'.concat(missingScope, '" scope.'),
+                                details: {
+                                    scope: missingScope
+                                }
+                            });
+                        }
+                        req.auth = authInfo;
+                        _state.label = 4;
+                    case 4:
+                        next();
+                        return [
+                            3,
+                            6
+                        ];
+                    case 5:
+                        error = _state.sent();
+                        response = errorResponseFactory(error);
+                        challenge = buildBearerChallenge(_object_spread({
+                            error: bearerChallengeErrorForCode({
+                                code: response.code,
+                                hadToken: token !== undefined
+                            }),
+                            realm: config.realm,
+                            resourceMetadataUrl: config.resourceMetadataUrl
+                        }, response.code === 'forbidden' && requiredScopes.length > 0 ? {
+                            scope: requiredScopes.join(' ')
+                        } : {}));
+                        res.status(response.status).setHeader('WWW-Authenticate', challenge).json(response.body);
+                        return [
+                            3,
+                            6
+                        ];
+                    case 6:
+                        return [
+                            2
+                        ];
+                }
+            });
+        })();
+    };
+}
+
+// MARK: Constants
+/**
+ * How long a client may cache the protected-resource metadata document, in seconds.
+ */ var DEFAULT_PROTECTED_RESOURCE_METADATA_MAX_AGE = 300;
+/**
+ * Serves the RFC 9728 metadata at both the path-suffixed (`…/oauth-protected-resource/mcp`,
+ * what clients try first) and bare well-known paths. Public and CORS-open so a browser-based
+ * client can discover the issuer, and built once at construction.
+ *
+ * @param config - The metadata document's inputs plus the resource path and cache lifetime.
+ * @returns The router.
+ */ function createWellKnownRouter(config) {
+    var _config_maxAge, _config_resourcePath;
+    var document = buildProtectedResourceMetadata(config);
+    var maxAge = (_config_maxAge = config.maxAge) !== null && _config_maxAge !== void 0 ? _config_maxAge : DEFAULT_PROTECTED_RESOURCE_METADATA_MAX_AGE;
+    var serve = function serve(_req, res) {
+        res.setHeader('cache-control', "public, max-age=".concat(maxAge)).json(document);
+    };
+    var router = Router();
+    var suffixedPath = oauthProtectedResourcePathForResource((_config_resourcePath = config.resourcePath) !== null && _config_resourcePath !== void 0 ? _config_resourcePath : resourcePathForResource(config.resource));
+    if (suffixedPath !== OAUTH_PROTECTED_RESOURCE_PATH) {
+        router.get(suffixedPath, cors(), serve);
+    }
+    router.get(OAUTH_PROTECTED_RESOURCE_PATH, cors(), serve);
+    return router;
+}
+// MARK: Internal
+function resourcePathForResource(resource) {
+    var path = '';
+    try {
+        path = new URL(resource).pathname;
+    } catch (unused) {
+        // not an absolute URL — treat the whole value as the path
+        path = resource;
+    }
+    return path;
+}
+
+export { AUTH_DISABLED_CLIENT_ID, AUTH_DISABLED_EXPIRES_IN_SECONDS, DEFAULT_PROTECTED_RESOURCE_METADATA_MAX_AGE, createWellKnownRouter, defaultOAuthResourceErrorResponseFactory, requireBearer };

package/express/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dereekb/oauth-resource/express",
+  "version": "14.4.0",
+  "sideEffects": false,
+  "type": "module",
+  "peerDependencies": {
+    "@dereekb/oauth-resource": "14.4.0",
+    "@dereekb/util": "14.4.0",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "jose": "^6.2.12",
+    "make-error": "^1.3.6"
+  },
+  "devDependencies": {
+    "jose": "^6.2.12",
+    "supertest": "^7.2.2"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.esm.js",
+  "types": "./index.d.ts"
+}

package/express/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/express/src/lib/bearer.middleware.d.ts

@@ -0,0 +1,78 @@
+import { type OAuthResourceAuthInfo, type OAuthResourceErrorCode, type VerifyBearerOptions } from '@dereekb/oauth-resource';
+import { type Maybe } from '@dereekb/util';
+import { type RequestHandler } from 'express';
+declare module 'express-serve-static-core' {
+    interface Request {
+        /**
+         * The verified bearer, in the MCP SDK's `AuthInfo` shape — the SDK's `toNodeHandler`
+         * forwards it to the MCP handler as `authInfo`.
+         */
+        auth?: OAuthResourceAuthInfo;
+    }
+}
+/**
+ * Placeholder auth attached to every request when verification is disabled.
+ */
+export declare const AUTH_DISABLED_CLIENT_ID = "dev";
+/**
+ * Lifetime, in seconds, stamped on the placeholder auth when verification is disabled.
+ */
+export declare const AUTH_DISABLED_EXPIRES_IN_SECONDS = 3600;
+/**
+ * How a rejected request is answered: the status, the RFC 6750 error token to challenge with, and
+ * the JSON body.
+ */
+export interface OAuthResourceErrorResponse {
+    readonly status: number;
+    readonly code: OAuthResourceErrorCode;
+    readonly body: unknown;
+}
+/**
+ * Maps a thrown error onto the response the middleware sends.
+ *
+ * The companion of {@link VerifyBearerOptions.errorFactory}: a consumer that throws its own API
+ * error type supplies one of these to shape the body with its own envelope.
+ */
+export type OAuthResourceErrorResponseFactory = (error: unknown) => OAuthResourceErrorResponse;
+/**
+ * Default {@link OAuthResourceErrorResponseFactory}. Reads an {@link OAuthResourceError}'s own
+ * status / code / envelope; anything else is reported as a generic 401.
+ *
+ * @param error - The thrown error.
+ * @returns The response to send.
+ */
+export declare const defaultOAuthResourceErrorResponseFactory: OAuthResourceErrorResponseFactory;
+export interface RequireBearerConfig {
+    readonly verify: VerifyBearerOptions;
+    /**
+     * Skip verification and attach a placeholder auth. Development only — it authorizes every caller.
+     */
+    readonly authDisabled?: Maybe<boolean>;
+    /**
+     * Absolute URL of the RFC 9728 protected-resource metadata, advertised in the
+     * `WWW-Authenticate` challenge so OAuth clients can discover the authorization server.
+     */
+    readonly resourceMetadataUrl?: Maybe<string>;
+    /**
+     * Protection space name emitted as the challenge's `realm`. Omitted by default.
+     */
+    readonly realm?: Maybe<string>;
+    /**
+     * Scopes the token must carry. A token missing any of them is rejected as `forbidden`, which
+     * emits an `insufficient_scope` challenge carrying the required scopes.
+     */
+    readonly requiredScopes?: Maybe<readonly string[]>;
+    /**
+     * Maps a thrown error onto the response. Defaults to {@link defaultOAuthResourceErrorResponseFactory}.
+     */
+    readonly errorResponseFactory?: Maybe<OAuthResourceErrorResponseFactory>;
+}
+/**
+ * Express middleware that requires a valid bearer JWT (see {@link verifyBearerJwt}) and attaches it
+ * as `req.auth`. A failure answers with the configured error envelope plus an RFC 6750
+ * `WWW-Authenticate` challenge carrying the protected-resource metadata URL.
+ *
+ * @param config - Verification options plus the challenge / policy settings.
+ * @returns The middleware.
+ */
+export declare function requireBearer(config: RequireBearerConfig): RequestHandler;

package/express/src/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './bearer.middleware';
+export * from './well-known.router';