@portaidentity/server 1.7.0

package/dist/middleware/security-headers.js

@@ -0,0 +1,159 @@
+/**
+ * Global HTTP security headers middleware.
+ *
+ * Adds defence-in-depth security headers to every response produced by
+ * the Porta application.  The headers mitigate a broad class of browser-
+ * side attacks (clickjacking, MIME-sniffing, cross-origin information
+ * leakage, protocol downgrade) without depending on an upstream reverse
+ * proxy — if the proxy is a dumb passthrough, these headers still reach
+ * the browser.
+ *
+ * Headers set on every response:
+ *   X-Content-Type-Options: nosniff          — prevent MIME-sniffing
+ *   X-Frame-Options: DENY                    — prevent clickjacking
+ *   Referrer-Policy: strict-origin-when-cross-origin
+ *                                            — limit referrer leakage
+ *   X-XSS-Protection: 0                      — disable legacy XSS filter
+ *                                              (buggy; rely on CSP instead)
+ *   Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()
+ *                                            — restrict browser APIs
+ *   Content-Security-Policy                  — strict default, relaxed for
+ *                                              HTML pages (see below)
+ *
+ * Conditional headers:
+ *   Strict-Transport-Security                — only emitted when the
+ *     configured issuer URL uses https://
+ *
+ * Content-Security-Policy strategy:
+ *   - Default (JSON / non-HTML responses):
+ *       `default-src 'none'`  — nothing to render, nothing to load.
+ *   - HTML responses (login, consent, 2FA, password-reset, etc.):
+ *       `default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'`
+ *     The interaction templates use inline `<style>` blocks and may
+ *     inject custom branding CSS via `{{{branding.customCss}}}`, hence
+ *     `style-src 'unsafe-inline'` is required.  Login pages must never
+ *     be embedded in iframes (`frame-ancestors 'none'`).
+ *
+ *     Note: `form-action` is intentionally omitted.  Chrome enforces
+ *     `form-action` on the entire redirect chain of a form submission,
+ *     not just the immediate target.  After login, the OIDC provider
+ *     redirects through the authorization endpoint and then to the
+ *     client's `redirect_uri` (a different origin).  Chrome blocks
+ *     this final redirect as a `form-action 'self'` violation, while
+ *     Firefox only checks the immediate action URL.  CSRF tokens are
+ *     the primary defence against cross-site form attacks; removing
+ *     `form-action` has negligible security impact given that
+ *     `script-src 'unsafe-inline'` already allows fetch/XHR exfiltration.
+ *
+ * Placement:
+ *   Mount early in the middleware stack — after `errorHandler()` and
+ *   `requestLogger()` but before any route-specific middleware. This
+ *   ensures headers are present even on error responses.
+ */
+import { config } from '../config/index.js';
+// ---------------------------------------------------------------------------
+// Exported constants — consumed by tests and by other middleware that may
+// need to reference or override specific values.
+// ---------------------------------------------------------------------------
+/**
+ * Static security headers applied to every response regardless of
+ * content type or route.
+ */
+export const STATIC_SECURITY_HEADERS = Object.freeze({
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Referrer-Policy': 'strict-origin-when-cross-origin',
+    'X-XSS-Protection': '0',
+    'Permissions-Policy': 'camera=(), microphone=(), geolocation=(), payment=()',
+});
+/**
+ * Strict Content-Security-Policy for non-HTML (JSON, plain-text) responses.
+ * Disallows all resource loading — there is nothing for a browser to render
+ * in a JSON API response.
+ */
+export const DEFAULT_CSP = "default-src 'none'";
+/**
+ * Relaxed Content-Security-Policy for HTML pages (login, consent, 2FA,
+ * password reset, invitation, magic-link confirmation, etc.).
+ *
+ * - `style-src 'unsafe-inline'`   — templates use inline `<style>` blocks,
+ *                                    inline style attributes, and custom
+ *                                    branding CSS injection.
+ * - `script-src 'unsafe-inline'`  — login.hbs uses an inline `<script>` for
+ *                                    dual-method email copying, and
+ *                                    two-factor-verify.hbs uses one for
+ *                                    OTP/recovery mode toggling.
+ * - `frame-ancestors 'none'`      — prevents embedding in iframes
+ *                                    (modern replacement for X-Frame-Options).
+ *
+ * `form-action` is intentionally omitted — see module-level doc comment.
+ */
+export const HTML_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; frame-ancestors 'none'";
+/**
+ * HSTS header value — one year, include subdomains.
+ * Only emitted when the configured issuer URL uses https.
+ */
+export const HSTS_VALUE = 'max-age=31536000; includeSubDomains';
+// ---------------------------------------------------------------------------
+// Middleware factory
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether HSTS should be emitted based on the configured
+ * issuer URL.  Returns `true` when the issuer starts with `https://`.
+ *
+ * Evaluated once at middleware creation time (issuer doesn't change
+ * at runtime).
+ */
+function shouldEmitHsts() {
+    try {
+        return config.issuerBaseUrl.startsWith('https://');
+    }
+    catch {
+        // Config may not be available in test environments — safe to skip.
+        return false;
+    }
+}
+/**
+ * Create the global security-headers Koa middleware.
+ *
+ * Sets static security headers on every response **before** downstream
+ * handlers run, then adjusts the Content-Security-Policy after the
+ * response body is produced — if the response is HTML, the CSP is
+ * relaxed to allow inline styles and form submissions.
+ *
+ * @returns Koa middleware function
+ */
+export function securityHeaders() {
+    const emitHsts = shouldEmitHsts();
+    return async function securityHeadersMiddleware(ctx, next) {
+        // -----------------------------------------------------------------------
+        // Phase 1 — set all static headers before downstream processing.
+        // This ensures headers are present even when a downstream handler
+        // throws and the error handler generates the final response.
+        // -----------------------------------------------------------------------
+        for (const [name, value] of Object.entries(STATIC_SECURITY_HEADERS)) {
+            ctx.set(name, value);
+        }
+        // Default strict CSP — overridden post-response for HTML pages.
+        ctx.set('Content-Security-Policy', DEFAULT_CSP);
+        // HSTS — only when the deployment uses HTTPS.
+        if (emitHsts) {
+            ctx.set('Strict-Transport-Security', HSTS_VALUE);
+        }
+        // -----------------------------------------------------------------------
+        // Phase 2 — run downstream middleware / route handlers.
+        // -----------------------------------------------------------------------
+        await next();
+        // -----------------------------------------------------------------------
+        // Phase 3 — adjust CSP for HTML responses.
+        // After the response body and content-type have been set by the route
+        // handler, check if the response is HTML and apply the relaxed CSP
+        // that allows inline styles and form submissions.
+        // -----------------------------------------------------------------------
+        const contentType = ctx.response.get('Content-Type') || '';
+        if (contentType.includes('text/html')) {
+            ctx.set('Content-Security-Policy', HTML_CSP);
+        }
+    };
+}
+//# sourceMappingURL=security-headers.js.map

package/dist/middleware/security-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-headers.js","sourceRoot":"","sources":["../../src/middleware/security-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,8EAA8E;AAC9E,0EAA0E;AAC1E,iDAAiD;AACjD,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAqC,MAAM,CAAC,MAAM,CAAC;IACrF,wBAAwB,EAAE,SAAS;IACnC,iBAAiB,EAAE,MAAM;IACzB,iBAAiB,EAAE,iCAAiC;IACpD,kBAAkB,EAAE,GAAG;IACvB,oBAAoB,EAAE,sDAAsD;CAC7E,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,QAAQ,GACnB,mGAAmG,CAAC;AAEtG;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,qCAAqC,CAAC;AAEhE,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAC;IAElC,OAAO,KAAK,UAAU,yBAAyB,CAAC,GAAG,EAAE,IAAI;QACvD,0EAA0E;QAC1E,iEAAiE;QACjE,kEAAkE;QAClE,6DAA6D;QAC7D,0EAA0E;QAC1E,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvB,CAAC;QAED,gEAAgE;QAChE,GAAG,CAAC,GAAG,CAAC,yBAAyB,EAAE,WAAW,CAAC,CAAC;QAEhD,8CAA8C;QAC9C,IAAI,QAAQ,EAAE,CAAC;YACb,GAAG,CAAC,GAAG,CAAC,2BAA2B,EAAE,UAAU,CAAC,CAAC;QACnD,CAAC;QAED,0EAA0E;QAC1E,wDAAwD;QACxD,0EAA0E;QAC1E,MAAM,IAAI,EAAE,CAAC;QAEb,0EAA0E;QAC1E,2CAA2C;QAC3C,sEAAsE;QACtE,mEAAmE;QACnE,kDAAkD;QAClD,0EAA0E;QAC1E,MAAM,WAAW,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAC3D,IAAI,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YACtC,GAAG,CAAC,GAAG,CAAC,yBAAyB,EAAE,QAAQ,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/tenant-resolver.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Multi-tenant resolver middleware.
+ *
+ * Extracts the organization slug from the URL path, resolves the
+ * organization using Redis cache (with DB fallback), validates the
+ * organization status, and sets tenant context on ctx.state.
+ *
+ * This middleware is applied to routes under /:orgSlug/* — it does NOT
+ * apply to root-level routes like /health.
+ *
+ * Resolution flow:
+ *   1. Extract orgSlug from route params
+ *   2. Check Redis cache: getCachedOrganizationBySlug(orgSlug)
+ *   3. If cache miss, query DB: findOrganizationBySlug(orgSlug)
+ *   4. If found from DB, cache it: cacheOrganization(org)
+ *   5. Validate status:
+ *      - archived → 404 "Organization not found"
+ *      - suspended → 403 "Organization is suspended"
+ *      - active → continue
+ *   6. Set ctx.state.organization (full Organization object)
+ *   7. Set ctx.state.issuer
+ *
+ * Returns:
+ *   - 404 if organization not found or archived
+ *   - 403 if organization is suspended
+ */
+import type { Middleware } from 'koa';
+/**
+ * Create the tenant resolver middleware.
+ *
+ * Expects the route to have an `:orgSlug` parameter (e.g., `/:orgSlug/*`).
+ * Resolves the organization via cache-first strategy and validates status.
+ *
+ * @returns Koa middleware function
+ */
+export declare function tenantResolver(): Middleware;
+//# sourceMappingURL=tenant-resolver.d.ts.map

package/dist/middleware/tenant-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-resolver.d.ts","sourceRoot":"","sources":["../../src/middleware/tenant-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAStC;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAyC3C"}

package/dist/middleware/tenant-resolver.js

@@ -0,0 +1,71 @@
+/**
+ * Multi-tenant resolver middleware.
+ *
+ * Extracts the organization slug from the URL path, resolves the
+ * organization using Redis cache (with DB fallback), validates the
+ * organization status, and sets tenant context on ctx.state.
+ *
+ * This middleware is applied to routes under /:orgSlug/* — it does NOT
+ * apply to root-level routes like /health.
+ *
+ * Resolution flow:
+ *   1. Extract orgSlug from route params
+ *   2. Check Redis cache: getCachedOrganizationBySlug(orgSlug)
+ *   3. If cache miss, query DB: findOrganizationBySlug(orgSlug)
+ *   4. If found from DB, cache it: cacheOrganization(org)
+ *   5. Validate status:
+ *      - archived → 404 "Organization not found"
+ *      - suspended → 403 "Organization is suspended"
+ *      - active → continue
+ *   6. Set ctx.state.organization (full Organization object)
+ *   7. Set ctx.state.issuer
+ *
+ * Returns:
+ *   - 404 if organization not found or archived
+ *   - 403 if organization is suspended
+ */
+import { config } from '../config/index.js';
+import { getCachedOrganizationBySlug, cacheOrganization, } from '../organizations/cache.js';
+import { findOrganizationBySlug } from '../organizations/repository.js';
+/**
+ * Create the tenant resolver middleware.
+ *
+ * Expects the route to have an `:orgSlug` parameter (e.g., `/:orgSlug/*`).
+ * Resolves the organization via cache-first strategy and validates status.
+ *
+ * @returns Koa middleware function
+ */
+export function tenantResolver() {
+    return async (ctx, next) => {
+        const orgSlug = ctx.params?.orgSlug;
+        if (!orgSlug) {
+            ctx.throw(404, 'Organization not found');
+        }
+        // 1. Try Redis cache first
+        let org = await getCachedOrganizationBySlug(orgSlug);
+        // 2. Cache miss → query database (returns all statuses)
+        if (!org) {
+            org = await findOrganizationBySlug(orgSlug);
+            // 3. Cache the result for subsequent requests
+            if (org) {
+                await cacheOrganization(org);
+            }
+        }
+        // 4. Not found at all
+        if (!org) {
+            return ctx.throw(404, 'Organization not found');
+        }
+        // 5. Status-dependent responses
+        if (org.status === 'archived') {
+            return ctx.throw(404, 'Organization not found');
+        }
+        if (org.status === 'suspended') {
+            return ctx.throw(403, 'Organization is suspended');
+        }
+        // 6. Set tenant context for downstream middleware and OIDC provider
+        ctx.state.organization = org;
+        ctx.state.issuer = `${config.issuerBaseUrl}/${org.slug}`;
+        await next();
+    };
+}
+//# sourceMappingURL=tenant-resolver.js.map

package/dist/middleware/tenant-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-resolver.js","sourceRoot":"","sources":["../../src/middleware/tenant-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAGxE;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;QAEpC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;QAC3C,CAAC;QAED,2BAA2B;QAC3B,IAAI,GAAG,GAAwB,MAAM,2BAA2B,CAAC,OAAO,CAAC,CAAC;QAE1E,wDAAwD;QACxD,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,MAAM,sBAAsB,CAAC,OAAO,CAAC,CAAC;YAE5C,8CAA8C;YAC9C,IAAI,GAAG,EAAE,CAAC;gBACR,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QAED,sBAAsB;QACtB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;QAClD,CAAC;QAED,gCAAgC;QAChC,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC9B,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YAC/B,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,2BAA2B,CAAC,CAAC;QACrD,CAAC;QAED,oEAAoE;QACpE,GAAG,CAAC,KAAK,CAAC,YAAY,GAAG,GAAG,CAAC;QAC7B,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,MAAM,CAAC,aAAa,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAEzD,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/token-rate-limiter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Token and introspection endpoint rate limiter middleware.
+ *
+ * Protects the OAuth token endpoint (`POST /:orgSlug/oidc/token`) and
+ * token introspection endpoint (`POST /:orgSlug/oidc/token/introspection`)
+ * against abuse: client-credentials flooding, authorization-code
+ * brute-forcing, token enumeration, and general endpoint spam.
+ *
+ * Rate limiting is per-IP + per-client_id composite key.  If `client_id`
+ * is not present in the request body (e.g. `client_secret_basic` auth
+ * sends credentials in the `Authorization` header), the key falls back
+ * to `unknown` — all such requests from the same IP share one counter.
+ *
+ * Reuses the existing `checkRateLimit()` infrastructure from
+ * `src/auth/rate-limiter.ts` which provides Redis INCR+EXPIRE sliding
+ * window and graceful degradation on Redis failure.
+ *
+ * Placement: mount as global middleware **before** the OIDC provider
+ * router in `src/server.ts`.  The path regex ensures only matching
+ * requests are rate-limited — all other paths pass through untouched.
+ *
+ * @module middleware/token-rate-limiter
+ */
+import type { Middleware } from 'koa';
+import type { RateLimitConfig } from '../auth/rate-limiter.js';
+/**
+ * Regex matching the OIDC token endpoint path.
+ *
+ * Pattern: `/<orgSlug>/oidc/token` where orgSlug starts with a
+ * lowercase alphanumeric character followed by zero or more lowercase
+ * alphanumeric or hyphen characters.
+ *
+ * Matches:  `/acme/oidc/token`, `/my-org/oidc/token`
+ * Rejects:  `/api/admin/something`, `/acme/oidc/token/extra`
+ */
+export declare const TOKEN_PATH_REGEX: RegExp;
+/**
+ * Rate limit configuration for the token endpoint.
+ *
+ * 30 requests per 5-minute window — generous enough for legitimate
+ * applications (SPAs refreshing tokens, server-side token exchanges)
+ * while catching automated abuse.
+ */
+export declare const TOKEN_RATE_LIMIT: RateLimitConfig;
+/**
+ * Create the token endpoint rate limiter middleware.
+ *
+ * Only intercepts `POST` requests to paths matching `TOKEN_PATH_REGEX`.
+ * Sets informational `X-RateLimit-*` headers on every token response
+ * and returns a `429` with an OAuth-format error body when the limit
+ * is exceeded.
+ *
+ * @returns Koa middleware that rate-limits the OIDC token endpoint
+ */
+export declare function tokenRateLimiter(): Middleware;
+/**
+ * Regex matching the OIDC token introspection endpoint path.
+ *
+ * Pattern: `/<orgSlug>/oidc/token/introspection` where orgSlug uses
+ * the same slug format as TOKEN_PATH_REGEX.
+ *
+ * Matches:  `/acme/oidc/token/introspection`, `/my-org/oidc/token/introspection`
+ * Rejects:  `/acme/oidc/token`, `/api/admin/introspection`
+ */
+export declare const INTROSPECTION_PATH_REGEX: RegExp;
+/**
+ * Rate limit configuration for the introspection endpoint.
+ *
+ * 100 requests per 60-second window — higher than the token endpoint
+ * because introspection is used by resource servers to validate tokens
+ * on every API call.  The higher limit accommodates legitimate traffic
+ * while still preventing token enumeration attacks.
+ */
+export declare const INTROSPECTION_RATE_LIMIT: RateLimitConfig;
+/**
+ * Create the introspection endpoint rate limiter middleware.
+ *
+ * Only intercepts `POST` requests to paths matching
+ * `INTROSPECTION_PATH_REGEX`.  Sets informational `X-RateLimit-*`
+ * headers and returns a `429` with an OAuth-format error body when
+ * the limit is exceeded.
+ *
+ * Key format: `ratelimit:introspect:{ip}:{clientId}` — composite key
+ * per-IP + per-client_id for granular rate limiting.
+ *
+ * @returns Koa middleware that rate-limits the OIDC introspection endpoint
+ */
+export declare function introspectionRateLimiter(): Middleware;
+//# sourceMappingURL=token-rate-limiter.d.ts.map

package/dist/middleware/token-rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/middleware/token-rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAO/D;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,QAAwC,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAG9B,CAAC;AAMF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAwD7C;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,QAAuD,CAAC;AAE7F;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAGtC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,IAAI,UAAU,CAqDrD"}

package/dist/middleware/token-rate-limiter.js

@@ -0,0 +1,189 @@
+/**
+ * Token and introspection endpoint rate limiter middleware.
+ *
+ * Protects the OAuth token endpoint (`POST /:orgSlug/oidc/token`) and
+ * token introspection endpoint (`POST /:orgSlug/oidc/token/introspection`)
+ * against abuse: client-credentials flooding, authorization-code
+ * brute-forcing, token enumeration, and general endpoint spam.
+ *
+ * Rate limiting is per-IP + per-client_id composite key.  If `client_id`
+ * is not present in the request body (e.g. `client_secret_basic` auth
+ * sends credentials in the `Authorization` header), the key falls back
+ * to `unknown` — all such requests from the same IP share one counter.
+ *
+ * Reuses the existing `checkRateLimit()` infrastructure from
+ * `src/auth/rate-limiter.ts` which provides Redis INCR+EXPIRE sliding
+ * window and graceful degradation on Redis failure.
+ *
+ * Placement: mount as global middleware **before** the OIDC provider
+ * router in `src/server.ts`.  The path regex ensures only matching
+ * requests are rate-limited — all other paths pass through untouched.
+ *
+ * @module middleware/token-rate-limiter
+ */
+import { checkRateLimit } from '../auth/rate-limiter.js';
+import { logger } from '../lib/logger.js';
+// ---------------------------------------------------------------------------
+// Constants — exported for test assertions and documentation
+// ---------------------------------------------------------------------------
+/**
+ * Regex matching the OIDC token endpoint path.
+ *
+ * Pattern: `/<orgSlug>/oidc/token` where orgSlug starts with a
+ * lowercase alphanumeric character followed by zero or more lowercase
+ * alphanumeric or hyphen characters.
+ *
+ * Matches:  `/acme/oidc/token`, `/my-org/oidc/token`
+ * Rejects:  `/api/admin/something`, `/acme/oidc/token/extra`
+ */
+export const TOKEN_PATH_REGEX = /^\/[a-z0-9][a-z0-9-]*\/oidc\/token$/;
+/**
+ * Rate limit configuration for the token endpoint.
+ *
+ * 30 requests per 5-minute window — generous enough for legitimate
+ * applications (SPAs refreshing tokens, server-side token exchanges)
+ * while catching automated abuse.
+ */
+export const TOKEN_RATE_LIMIT = {
+    max: 30,
+    windowSeconds: 300,
+};
+// ---------------------------------------------------------------------------
+// Middleware factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the token endpoint rate limiter middleware.
+ *
+ * Only intercepts `POST` requests to paths matching `TOKEN_PATH_REGEX`.
+ * Sets informational `X-RateLimit-*` headers on every token response
+ * and returns a `429` with an OAuth-format error body when the limit
+ * is exceeded.
+ *
+ * @returns Koa middleware that rate-limits the OIDC token endpoint
+ */
+export function tokenRateLimiter() {
+    return async function tokenRateLimiterMiddleware(ctx, next) {
+        // Only rate-limit POST to the token endpoint — GET, OPTIONS, etc.
+        // and all non-token paths pass through immediately.
+        if (ctx.method !== 'POST' || !TOKEN_PATH_REGEX.test(ctx.path)) {
+            return next();
+        }
+        // Extract client_id from the parsed request body if available.
+        // The selective bodyParser in server.ts excludes OIDC routes, so
+        // ctx.request.body may be empty when this middleware runs.
+        // Fall back to 'unknown' — all unidentified clients from the same
+        // IP share a single rate limit counter, which is acceptable.
+        const body = ctx.request.body;
+        const clientId = body?.client_id;
+        const clientKey = typeof clientId === 'string' && clientId.length > 0
+            ? clientId
+            : 'unknown';
+        // Composite key: per-IP + per-client_id for granular rate limiting
+        const key = `ratelimit:token:${ctx.ip}:${clientKey}`;
+        const result = await checkRateLimit(key, TOKEN_RATE_LIMIT);
+        // Informational headers on all responses — helps legitimate clients
+        // monitor their usage and implement backoff strategies.
+        ctx.set('X-RateLimit-Limit', String(TOKEN_RATE_LIMIT.max));
+        ctx.set('X-RateLimit-Remaining', String(result.remaining));
+        if (!result.allowed) {
+            logger.warn({
+                action: 'token_rate_limit_exceeded',
+                ip: ctx.ip,
+                clientId: clientKey,
+                path: ctx.path,
+            }, 'Token endpoint rate limit exceeded');
+            ctx.status = 429;
+            ctx.set('Retry-After', String(result.retryAfter));
+            // OAuth 2.0 error format — clients that parse token endpoint
+            // errors can handle this structured response.
+            ctx.body = {
+                error: 'rate_limit_exceeded',
+                error_description: 'Too many token requests. Please try again later.',
+                retry_after: result.retryAfter,
+            };
+            return;
+        }
+        return next();
+    };
+}
+// ---------------------------------------------------------------------------
+// Introspection endpoint rate limiter
+// ---------------------------------------------------------------------------
+/**
+ * Regex matching the OIDC token introspection endpoint path.
+ *
+ * Pattern: `/<orgSlug>/oidc/token/introspection` where orgSlug uses
+ * the same slug format as TOKEN_PATH_REGEX.
+ *
+ * Matches:  `/acme/oidc/token/introspection`, `/my-org/oidc/token/introspection`
+ * Rejects:  `/acme/oidc/token`, `/api/admin/introspection`
+ */
+export const INTROSPECTION_PATH_REGEX = /^\/[a-z0-9][a-z0-9-]*\/oidc\/token\/introspection$/;
+/**
+ * Rate limit configuration for the introspection endpoint.
+ *
+ * 100 requests per 60-second window — higher than the token endpoint
+ * because introspection is used by resource servers to validate tokens
+ * on every API call.  The higher limit accommodates legitimate traffic
+ * while still preventing token enumeration attacks.
+ */
+export const INTROSPECTION_RATE_LIMIT = {
+    max: 100,
+    windowSeconds: 60,
+};
+/**
+ * Create the introspection endpoint rate limiter middleware.
+ *
+ * Only intercepts `POST` requests to paths matching
+ * `INTROSPECTION_PATH_REGEX`.  Sets informational `X-RateLimit-*`
+ * headers and returns a `429` with an OAuth-format error body when
+ * the limit is exceeded.
+ *
+ * Key format: `ratelimit:introspect:{ip}:{clientId}` — composite key
+ * per-IP + per-client_id for granular rate limiting.
+ *
+ * @returns Koa middleware that rate-limits the OIDC introspection endpoint
+ */
+export function introspectionRateLimiter() {
+    return async function introspectionRateLimiterMiddleware(ctx, next) {
+        // Only rate-limit POST to the introspection endpoint.
+        if (ctx.method !== 'POST' || !INTROSPECTION_PATH_REGEX.test(ctx.path)) {
+            return next();
+        }
+        // Extract client_id from the parsed request body if available.
+        // Introspection requests carry client credentials — client_id may
+        // be in the body (client_secret_post) or absent (client_secret_basic).
+        const body = ctx.request.body;
+        const clientId = body?.client_id;
+        const clientKey = typeof clientId === 'string' && clientId.length > 0
+            ? clientId
+            : 'unknown';
+        // Composite key: per-IP + per-client_id — separate namespace from
+        // the token endpoint to keep counters independent.
+        const key = `ratelimit:introspect:${ctx.ip}:${clientKey}`;
+        const result = await checkRateLimit(key, INTROSPECTION_RATE_LIMIT);
+        // Informational headers on all matched responses.
+        ctx.set('X-RateLimit-Limit', String(INTROSPECTION_RATE_LIMIT.max));
+        ctx.set('X-RateLimit-Remaining', String(result.remaining));
+        if (!result.allowed) {
+            logger.warn({
+                action: 'introspection_rate_limit_exceeded',
+                ip: ctx.ip,
+                clientId: clientKey,
+                path: ctx.path,
+            }, 'Introspection endpoint rate limit exceeded');
+            ctx.status = 429;
+            ctx.set('Retry-After', String(result.retryAfter));
+            // OAuth 2.0 error format — resource servers parsing introspection
+            // errors can handle this structured response.
+            ctx.body = {
+                error: 'rate_limit_exceeded',
+                error_description: 'Too many introspection requests. Please try again later.',
+                retry_after: result.retryAfter,
+            };
+            return;
+        }
+        return next();
+    };
+}
+//# sourceMappingURL=token-rate-limiter.js.map

package/dist/middleware/token-rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-rate-limiter.js","sourceRoot":"","sources":["../../src/middleware/token-rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/oidc/account-finder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Account finder for node-oidc-provider.
+ *
+ * Maps user records from the database to OIDC account objects with a
+ * claims() method. The provider calls findAccount when it needs user
+ * information for ID tokens, userinfo endpoint responses, etc.
+ *
+ * This implementation delegates to the user service for lookup and
+ * the claims builder for scope-based claims mapping. The user must
+ * be active to be returned — non-active users get undefined (no account).
+ *
+ * Claims flow:
+ * 1. buildUserClaims(user, scopes) → standard OIDC claims (sub, name, email...)
+ * 2. buildRoleClaims(userId) → role slugs array (cache-first)
+ * 3. buildPermissionClaims(userId) → permission slugs array (cache-first)
+ * 4. buildCustomClaims(userId, appId, tokenType) → custom per-app claims
+ *
+ * The applicationId for custom claims is resolved from the OIDC client
+ * context. If unavailable (e.g., no client context), custom claims are
+ * skipped gracefully.
+ *
+ * @see users/service.ts — User lookup for OIDC
+ * @see users/claims.ts — Standard OIDC claims builder
+ * @see rbac/user-role-service.ts — RBAC claims builders
+ * @see custom-claims/service.ts — Custom claims builder
+ */
+/** OIDC Account object — returned by findAccount, used by the provider */
+export interface OidcAccount {
+    /** The subject identifier (user UUID) */
+    accountId: string;
+    /**
+     * Return OIDC claims for the user.
+     * @param use - Token type ('id_token' or 'userinfo')
+     * @param scope - Granted scopes (space-separated)
+     * @returns Object with OIDC Standard Claims + RBAC + custom claims
+     */
+    claims: (use: string, scope: string) => Promise<Record<string, unknown>>;
+}
+/**
+ * Find an OIDC account by subject identifier (user ID).
+ *
+ * Delegates to the user service's findUserForOidc which returns
+ * active users only. Returns an account object with a claims() method
+ * that builds scope-filtered OIDC Standard Claims merged with RBAC
+ * role/permission claims and per-application custom claims.
+ *
+ * @param ctx - Koa context with OIDC extensions (used to resolve client/app context)
+ * @param sub - The subject identifier (user UUID)
+ * @returns Account object with claims() method, or undefined if not found
+ */
+export declare function findAccount(ctx: unknown, sub: string): Promise<OidcAccount | undefined>;
+//# sourceMappingURL=account-finder.d.ts.map

package/dist/oidc/account-finder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-finder.d.ts","sourceRoot":"","sources":["../../src/oidc/account-finder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAmDlC"}