@o3co/create-auth-provider 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",
@@ -24,6 +24,9 @@
     "dist",
     "templates"
   ],
+  "engines": {
+    "node": ">=18.19.0"
+  },
   "devDependencies": {
     "@types/node": "^25.1.0",
     "vitest": "^4.1.2"

package/templates/standalone/README.md

@@ -2,6 +2,23 @@
 
 Deployable server template for auth.provider. This is the composition root — it reads config, loads modules, and starts the Express server. Generated by `@o3co/create-auth-provider`.
 
+## Requirements
+
+- **Node.js** `>=18.19.0`
+- **`bcrypt` native binary**: this template depends transitively on `bcrypt@6.x`, which ships **prebuilt N-API binaries** for `darwin-arm64`, `darwin-x64`, `linux-x64` (glibc and musl), `linux-arm64` (glibc and musl), `linux-arm`, `win32-x64`, and `win32-arm64`. On these platforms `pnpm install` succeeds without compiling from source, and no extra toolchain is required (the `darwin-*`, `node:*-alpine`, and `node:*-bookworm` images all match a shipped prebuild). On platforms or libc/arch combinations that have no matching prebuild, `pnpm install` falls back to compiling, which then requires a C++ compiler and Python (the standard Node.js native-addon toolchain): Debian/Ubuntu `apt-get install build-essential python3`, Alpine `apk add make g++ python3`, macOS `xcode-select --install`. The pnpm 10 `onlyBuiltDependencies` allowlist for `bcrypt` is set in this template's `package.json` so a fresh `pnpm install` does not silently skip the install hook on those platforms.
+- **Redis 7.2 LTS or later** for any Redis-backed adapter (refresh token family store, code repository, federation token store, session store). The `pExpireGT` flag pair on which several adapters depend was introduced in Redis 7.0+; 7.2 LTS is the tested floor. Tested against AWS ElastiCache for Redis 7.2, Upstash Redis, Redis Cloud 7.2, and self-managed `redis:7.2-alpine`.
+- **ioredis** `^5.4.1` (direct runtime dependency, used by the refresh-token-family client). Other Redis-backed adapters in this template still use the `redis` npm package; ioredis is added for the RT family store specifically.
+
+## Multi-replica deployments
+
+When running multiple instances of the standalone server behind a load balancer, point `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` at a **shared** Redis 7.2+ instance. Without a shared Redis URL, every replica holds refresh-token families in its own connection (and any local-only Redis), so a refresh request that lands on a replica that did not issue the token returns `invalid_grant` on every other request in a round-robin LB.
+
+Other multi-replica considerations covered by the default modules:
+
+- The session store is wired via `redisSessionStoresModule`; set the corresponding session-store Redis URL (per `session.storage.redis.url`).
+- The code repository defaults to Redis when `repositories.code.type = "redis"`; set `CLIENT_CODE_ENDPOINT_URI` to a shared Redis instance.
+- The federation token store can be backed by Redis via `federationTokenStore.type = "redis"` (deferred to operator config; default is in-memory).
+
 ## Usage
 
 ```bash

package/templates/standalone/config/application.conf

@@ -8,6 +8,16 @@ http {
 oauth {
   jwt {
     issuer = ${?OAUTH_JWT_ISSUER}
+    # SF-1 (v0.5.1): legacy typ acceptance for the central JWT verifier.
+    # When true (default), tokens whose `typ` header is absent are
+    # accepted with a `jwt_verify_legacy_typ` warning so v0.4.x tokens
+    # keep verifying through the v0.5.x transition window. Flip to false
+    # in v0.6+ to reject typ-less tokens. Active default per the v0.5.1
+    # ADR: literal default lives in HOCON (zod has no `.default()`).
+    # Operators set OAUTH_JWT_LEGACY_TYP_ACCEPT to override (set "false"
+    # to enforce strict mode early).
+    legacyTypAccept = true
+    legacyTypAccept = ${?OAUTH_JWT_LEGACY_TYP_ACCEPT}
     signingKey {
       provider = "local"
       provider = ${?OAUTH_JWT_SIGNING_KEY_PROVIDER}
@@ -21,7 +31,18 @@ oauth {
         privateKeyPath = ${?OAUTH_JWT_PRIVATE_KEY_PATH}
         publicKey = ${?OAUTH_JWT_PUBLIC_KEY}
         publicKeyPath = ${?OAUTH_JWT_PUBLIC_KEY_PATH}
-        previousKeys = []
+        # IH-9: HS256 key rotation. To rotate without downtime, set the
+        # new secret + kid here (e.g. "v1") and move the old pair into
+        # `previousSecrets` with an `expiresAt` covering the access-token
+        # TTL plus a buffer. `getVerificationKey(kid)` resolves old
+        # tokens by kid until `expiresAt`. Operators on RS256/ES256/EdDSA
+        # use the asymmetric-shaped `previousKeys` instead — the
+        # discriminated-union schema rejects mixing the shapes.
+        # Example:
+        #   previousSecrets = [
+        #     { kid = "v0", secret = "<old>", expiresAt = "2026-06-05T00:00:00Z" }
+        #   ]
+        previousSecrets = []
       }
     }
   }
@@ -32,6 +53,31 @@ oauth {
   refreshToken {
     expiresIn = 86400
     expiresIn = ${?OAUTH_REFRESH_TOKEN_EXPIRES_IN}
+    # CC-2 (v0.5.1): handling for refresh tokens whose family_id is not
+    # found in the rotation store. "reject" (default, inherited from core
+    # application.conf) is safe-by-default. Use "accept" only during a
+    # bounded migration window — e.g. moving from v0.4.x in-memory family
+    # store to Redis with old tokens still in circulation. Operators set
+    # OAUTH_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY for env-var override.
+    # unknownFamilyPolicy = "reject"
+    # SF-6 (v0.5.1): handling for refresh tokens lacking jti or family_id
+    # claims when rotation is wired. "reject" (default) is safe. Use
+    # "accept-with-warning" only during a migration window where v0.4.x
+    # tokens (issued before claim standardization) are still in circulation;
+    # that mode skips replay detection for the request and emits an audit
+    # log. Pair with `unknownFamilyPolicy = "accept"` to avoid immediate
+    # rejection on the next refresh — see Phase F migration guide.
+    # legacyRtPolicy = "reject"
+    # AS-12 (v0.5.1): v0.5.x default accepts v0.4.x refresh tokens that use
+    # payload.type = "refresh" or claims.user.id as the subject. Set false
+    # only after all pre-v0.5 refresh tokens have expired; remaining legacy
+    # tokens will be rejected with invalid_grant. The strict marker-required
+    # gate is preserved across both flag values: a typ-less JWT with no
+    # payload.type is rejected at the refresh-grant gate even when
+    # oauth.jwt.legacyTypAccept = true (AT-as-RT confusion stays defended).
+    # Operators set OAUTH_REFRESH_TOKEN_LEGACY_TOKEN_COMPAT for env-var
+    # override.
+    # legacyTokenCompat = true
   }
   grants {
     session { enabled = true, enabled = ${?OAUTH_GRANTS_SESSION_ENABLED} }
@@ -45,6 +91,17 @@ oauth {
     }
     refresh_token { enabled = true, enabled = ${?OAUTH_GRANTS_REFRESH_TOKEN_ENABLED} }
   }
+  # OR-9: adapter switch for the OAuth authorization-code repository. When
+  # set to "redis", the standalone composition root wires
+  # `redisCodeRepositoryModule` against the shared ioredis socket
+  # (`standaloneRedisClientsModule`). Memory-only deployments lose codes on
+  # restart and across replicas — multi-replica production MUST use "redis".
+  # Supersedes the legacy `repositories.code.type` switch (kept below for
+  # one release cycle for backward compat).
+  code {
+    adapter = "redis"
+    adapter = ${?OAUTH_CODE_ADAPTER}
+  }
 }
 
 session {
@@ -68,8 +125,21 @@ session {
   }
 }
 
+# Rate limiting for SESSION routes (e.g. /session/login bruteforce protection).
+# Uses windowMs (milliseconds) — consumed by express-rate-limit in Session.mts.
+# NOTE (IH-18): this section does NOT govern OAuth endpoint rate limiting.
+#       For OAuth rate limiting (/token, /authorize), use the `rateLimiter`
+#       component (memoryRateLimiterModule or redisRateLimiterModule) with
+#       its own `memoryRateLimiter.*` / `redisRateLimiter.*` config section
+#       (uses `windowSeconds` instead of `windowMs`). Switch via
+#       `rateLimiter.adapter = "memory" | "redis"` (see below).
 rateLimit {
   login { windowMs = 900000, limit = 20 }
+  # OR-5: fail-mode for the OAuth-endpoint rate limiter when the limiter
+  # backend errors. "open" = allow + `logger.error`. "closed" = HTTP 503
+  # + `logger.error` (recommended for security-sensitive deployments).
+  failMode = "open"
+  failMode = ${?RATE_LIMIT_FAIL_MODE}
 }
 
 federations {
@@ -126,10 +196,78 @@ endpoints {
     url = "/login"
     url = ${?ENDPOINTS_LOGIN_URL}
   }
-  client { url = ${?ENDPOINTS_CLIENT_URL} }
-  authCallback { url = ${?ENDPOINTS_AUTH_CALLBACK_URL} }
+  # IH-10: `client { url }` and `authCallback { url }` removed — no
+  # production consumer reads them.
 }
 
 cors {
   allowedOrigins = []
 }
+
+# Wave 5d (IH-14 + OR-M1 + OR-4): adapter switches for the OAuth-endpoint
+# rate limiter and the user-session stores (4-store split: userSessionStore
+# / sessionRPRegistry / sessionFamilyIndex / sessionFederationIndex).
+#
+# Multi-replica production MUST set BOTH to `"redis"`. The defaults are
+# `"memory"` for backward-compat with single-instance deployments and CI;
+# in-memory rate-limit counters / session state are isolated per replica
+# and inconsistent under load-balanced traffic.
+#
+# When `userSessionStores.adapter = "redis"` or `rateLimiter.adapter = "redis"`,
+# the standalone composition root opens a single shared ioredis connection
+# (via `standaloneRedisClientsModule`) consuming `refreshTokenFamilyStore.redis.url`
+# (D-2 v2). One ioredis socket per replica backs ALL Redis-typed clients.
+rateLimiter {
+  adapter = "memory"
+  adapter = ${?RATE_LIMITER_ADAPTER}
+}
+
+userSessionStores {
+  adapter = "memory"
+  adapter = ${?USER_SESSION_STORES_ADAPTER}
+}
+
+# D-2 v2 + Wave 5d: ioredis connection-config consumed by the shared
+# `standaloneRedisClientsModule` in `templates/standalone/src/modules.mts`.
+# One ioredis socket per replica backs ALL Redis-typed clients (RT family
+# + 4 user-session stores + rate limiter). Multi-replica deployments MUST
+# point this at a shared Redis 7.2+ instance — without it, each replica
+# stores RT families in its own ioredis connection against a local-only
+# Redis, defeating the cross-replica persistence purpose. Module-internal
+# config (keyPrefix / casRetryLimit) lives separately under
+# `redisRefreshTokenFamilyStore.*` (consumed by the store module's schema).
+redisRefreshTokenFamilyStore {
+  keyPrefix = "rtfam:"
+  keyPrefix = ${?REFRESH_TOKEN_FAMILY_STORE_KEY_PREFIX}
+  casRetryLimit = 3
+  casRetryLimit = ${?REFRESH_TOKEN_FAMILY_STORE_CAS_RETRY_LIMIT}
+}
+
+# OR-9 (Wave 5d): module-internal config for `redisCodeRepositoryModule`.
+# Consumed when `oauth.code.adapter = "redis"`. The shared ioredis socket
+# (`standaloneRedisClientsModule`) provides the `codeRepositoryClient`
+# slot; this section governs only key namespacing and the default
+# expiry-in-seconds the repository uses when /authorize doesn't supply one.
+#
+# Multi-tenant deployments override `keyPrefix` to isolate tenants in the
+# same Redis instance — e.g. `keyPrefix = "tenant-a:code:"` keeps tenant A's
+# codes from colliding with tenant B's under the default `oauth:code:`
+# prefix (MIN-3 advisory).
+redisCodeRepository {
+  # No literal default for keyPrefix — the RedisCodeRepository constructor
+  # falls back to `oauth:code:` when this field is absent. Operators that
+  # need multi-tenant isolation set CLIENT_CODE_KEY_PREFIX (e.g.
+  # `tenant-a:code:`); leaving the env var unset keeps the constructor
+  # default intact via HOCON's `${?VAR}` "absent if unset" semantics.
+  keyPrefix = ${?CLIENT_CODE_KEY_PREFIX}
+  defaultExpiresIn = 600
+  defaultExpiresIn = ${?CLIENT_CODE_DEFAULT_EXPIRES_IN}
+}
+
+refreshTokenFamilyStore {
+  redis {
+    url = "redis://localhost:6379"
+    url = ${?REFRESH_TOKEN_FAMILY_STORE_REDIS_URL}
+    password = ${?REFRESH_TOKEN_FAMILY_STORE_REDIS_PASSWORD}
+  }
+}

package/templates/standalone/config/clients.yaml.example

@@ -1,14 +1,30 @@
 # Example client definitions loaded via loadYamlMap into InMemoryClientRepository.
 # Copy this file to clients.yaml and customize for your deployment.
 #
-# Secret format:
+# `tokenEndpointAuthMethod` is REQUIRED (RFC 6749 §2.3 / RFC 7591 §2):
+#   - "client_secret_basic": HTTP Basic Authorization header — recommended for confidential clients
+#   - "client_secret_post":  form-encoded body parameters
+#   - "none":                public client — no clientSecret; PKCE/S256 mandatory at /authorize
+#
+# Secret format (only for confidential clients — basic / post):
 #   - Plain text: "my-secret"
 #   - Bcrypt hash: "$2b$10$..." (generate with: node -e "require('bcrypt').hash('secret',10).then(console.log)")
 
 my-app:
+  tokenEndpointAuthMethod: "client_secret_basic"
   clientSecret: "$2b$10$REPLACE_WITH_BCRYPT_HASH"
   allowedRedirectUris:
     - "http://localhost:3000/callback"
   allowedScopes:
     - "read"
     - "write"
+
+# Public client example (e.g., a single-page app or mobile app):
+# my-spa:
+#   tokenEndpointAuthMethod: "none"
+#   # clientSecret MUST be absent for "none" clients.
+#   allowedRedirectUris:
+#     - "https://app.example/callback"
+#   allowedScopes:
+#     - "openid"
+#     - "profile"

package/templates/standalone/docker-compose.test.yml

@@ -8,7 +8,7 @@ services:
         condition: service_healthy
 
   redis:
-    image: redis:7-alpine
+    image: redis:7.2-alpine
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 5s

package/templates/standalone/docker-compose.yml

@@ -16,7 +16,7 @@ services:
         required: false
 
   redis:
-    image: redis:7-alpine
+    image: redis:7.2-alpine
     ports:
       - "127.0.0.1:6379:6379"
     healthcheck:

package/templates/standalone/package.json

@@ -1,8 +1,11 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.5.1",
+	"version": "0.5.2",
 	"private": true,
 	"license": "Apache-2.0",
+	"engines": {
+		"node": ">=18.19.0"
+	},
 	"packageManager": "pnpm@10.29.3",
 	"type": "module",
 	"scripts": {
@@ -24,14 +27,15 @@
 		"@o3co/auth-provider-session": "workspace:*",
 		"@o3co/auth-provider-foundation": "workspace:*",
 		"@o3co/auth-provider-redis": "workspace:*",
-		"@o3co/auth.utils": "^0.0.3",
+		"@o3co/auth.utils": "^0.0.4",
 		"@o3co/ts.hocon": "^1.1.0",
 		"connect-redis": "^9.0.0",
 		"express": "^5.2.1",
 		"express-session": "^1.19.0",
 		"helmet": "^8.1.0",
+		"ioredis": "^5.4.1",
 		"pino": "^10.3.1",
-		"redis": "^5.10.0"
+		"redis": "^5.12.1"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",
@@ -42,5 +46,10 @@
 		"tsx": "^4.21.0",
 		"typescript": "^5.9.3",
 		"vitest": "^4.1.2"
+	},
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"bcrypt"
+		]
 	}
 }

package/templates/standalone/src/__tests__/refresh-token-family-client-module.test.mts

@@ -0,0 +1,180 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { LifecycleRegistrar } from "@o3co/auth-provider-core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// D-2 v2: ioredis Redis constructor capture. The module under test imports
+// `Redis` from "ioredis"; vi.mock replaces that import so the test never
+// opens a real socket. Captured arguments verify that the validated config
+// reaches the constructor (BLOCKER 1: schema strip closure).
+const redisCtorCalls: Array<{ url: string; options: Record<string, unknown> | undefined }> = [];
+const quitSpies: Array<ReturnType<typeof vi.fn>> = [];
+const onSpies: Array<ReturnType<typeof vi.fn>> = [];
+
+vi.mock("ioredis", () => {
+	class MockRedis {
+		duplicate(): MockRedis {
+			return new MockRedis("redis://duplicate.local");
+		}
+		on = vi.fn();
+		quit = vi.fn(async () => "OK" as const);
+		// Minimal command surface — `makeIoredisClients` only invokes these
+		// during construction in some paths; tests never exercise the wrapped
+		// client itself, so most stubs are unused.
+		set = vi.fn();
+		get = vi.fn();
+		pttl = vi.fn();
+		watch = vi.fn();
+		unwatch = vi.fn();
+		multi = vi.fn(() => ({
+			set: vi.fn().mockReturnThis(),
+			exec: vi.fn(async () => []),
+		}));
+
+		constructor(url: string, options?: Record<string, unknown>) {
+			redisCtorCalls.push({ url, options });
+			onSpies.push(this.on);
+			quitSpies.push(this.quit);
+		}
+	}
+	return { Redis: MockRedis, default: MockRedis };
+});
+
+// Imported AFTER vi.mock so the mocked ioredis is in scope.
+const importModule = async () =>
+	(await import("../modules.mjs")) as typeof import("../modules.mjs") & {
+		standaloneRedisClientsModule: import("@o3co/auth-provider-core").Module;
+	};
+
+// D-1 / D-5 are already merged on develop, so importing `standaloneRedisClientsModule`
+// from `../modules.mjs` is the natural integration point. Pre-fix the export does not
+// exist — TS error → RED.
+
+const baseConfig = {
+	refreshTokenFamilyStore: {
+		redis: { url: "redis://example.com:6379", password: "test-pw" },
+	},
+};
+
+describe("D-2 / standaloneRedisClientsModule", () => {
+	beforeEach(() => {
+		redisCtorCalls.length = 0;
+		quitSpies.length = 0;
+		onSpies.length = 0;
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("passes operator-supplied Redis URL + password from config to the ioredis constructor (BLOCKER 1 closure)", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		await provides.refreshTokenFamilyClient({ config: { ...baseConfig } });
+
+		expect(redisCtorCalls).toHaveLength(1);
+		expect(redisCtorCalls[0]?.url).toBe("redis://example.com:6379");
+		expect(redisCtorCalls[0]?.options?.password).toBe("test-pw");
+	});
+
+	it("registers io.quit() with lifecycleRegistrar when provided; drain calls quit exactly once", async () => {
+		const registered: Array<() => Promise<void>> = [];
+		const lifecycleRegistrar: LifecycleRegistrar = {
+			register: (cleanup) => {
+				registered.push(cleanup);
+			},
+		};
+
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		await provides.refreshTokenFamilyClient({ config: { ...baseConfig }, lifecycleRegistrar });
+
+		expect(registered).toHaveLength(1);
+		// Pre-drain: quit not yet called.
+		expect(quitSpies[0]).not.toHaveBeenCalled();
+
+		// Drain (simulate handle.dispose()).
+		await registered[0]?.();
+		expect(quitSpies[0]).toHaveBeenCalledTimes(1);
+	});
+
+	it("does not crash when lifecycleRegistrar is absent (graceful no-op, no quit registered)", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+
+		// No lifecycleRegistrar key in deps — must not throw and must NOT
+		// register a cleanup (verified by the absence of any quit invocation
+		// after the factory resolves; the registrar branch is the only place
+		// `quit()` would be wired up in the no-real-shutdown unit-test path).
+		await expect(
+			provides.refreshTokenFamilyClient({ config: { ...baseConfig } }),
+		).resolves.toBeDefined();
+		expect(quitSpies[0]).not.toHaveBeenCalled();
+	});
+
+	it("fails fast when refreshTokenFamilyStore.redis.url is missing (no silent localhost fallback)", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+
+		// Operator deliberately removed the section — must throw instead of
+		// silently falling back to redis://localhost:6379 (which would re-
+		// introduce the OR-1 multi-replica failure mode in production).
+		await expect(provides.refreshTokenFamilyClient({ config: {} })).rejects.toThrow(
+			/refreshTokenFamilyStore\.redis\.url/,
+		);
+		// And no ioredis instance was constructed because we threw before
+		// `new Redis(...)`.
+		expect(redisCtorCalls).toHaveLength(0);
+	});
+
+	it("attaches an error event handler to the ioredis client (prevents unhandled-error crash)", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		await provides.refreshTokenFamilyClient({ config: { ...baseConfig } });
+
+		expect(onSpies[0]).toHaveBeenCalledWith("error", expect.any(Function));
+	});
+
+	it("declares 'config' as required and 'lifecycleRegistrar' as optional", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const m = standaloneRedisClientsModule as {
+			requires?: readonly string[];
+			optional?: readonly string[];
+		};
+		expect(m.requires).toContain("config");
+		expect(m.optional).toContain("lifecycleRegistrar");
+	});
+});