@o3co/create-auth-provider 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.1.0",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/Dockerfile

@@ -13,11 +13,17 @@ FROM node-base AS deps
 
 COPY package.json ./
 
+USER node
+
 RUN pnpm install
 
 #############################################
 FROM deps AS builder
 
+# USER node inherited from deps stage; repeated here to make the builder
+# hardening invariant obvious in Dockerfile reviews.
+USER node
+
 COPY tsconfig.json ./
 COPY config/ ./config/
 COPY src/ ./src/
@@ -31,13 +37,22 @@ ENV NODE_ENV=production
 
 COPY --from=deps /home/node/package.json /home/node/pnpm-lock.yaml ./
 
+USER node
+
 RUN pnpm install --prod \
  && pnpm store prune
 
 COPY --from=builder /home/node/dist/ ./dist/
 COPY --from=builder /home/node/config/ ./config/
 
-USER node
+ENV HTTP_PORT=3000
+EXPOSE ${HTTP_PORT}
+
+# Use the shell form so ${HTTP_PORT} expands at probe time. The HOCON
+# config reads `${?HTTP_PORT}` for `http.port`, so app.listen() and the
+# healthcheck stay in sync regardless of the operator's port choice.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD wget -q -O /dev/null "http://localhost:${HTTP_PORT}/_healthcheck" || exit 1
 
 ENTRYPOINT ["tini", "--"]
 CMD ["node", "dist/app.mjs"]
@@ -53,6 +68,4 @@ CMD ["pnpm", "run", "test", "--", "--passWithNoTests"]
 #############################################
 FROM builder AS develop
 
-USER node
-
 CMD ["pnpm", "run", "debug"]

package/templates/standalone/README.md

@@ -94,6 +94,7 @@ fail fast rather than silently falling back to defaults.
 | Variable | Default | Description |
 |---|---|---|
 | `SESSION_SECRET` | — | **Required.** Session signing secret |
+| `SESSION_NAME` | `__Host-auth.session` | Session cookie name. The default uses the `__Host-` prefix and therefore requires `SESSION_SECURE=true` and no `SESSION_DOMAIN`. |
 | `SESSION_MAX_AGE` | `3600000` | Session cookie max age in milliseconds |
 | `SESSION_SECURE` | `true` | Set `Secure` flag on session cookie |
 | `SESSION_SAME_SITE` | `lax` | `SameSite` attribute (`lax`, `strict`, `none`) |
@@ -102,6 +103,11 @@ fail fast rather than silently falling back to defaults.
 | `SESSION_STORAGE_REDIS_URL` | `redis://localhost:6379` | Redis connection URL for session storage |
 | `SESSION_STORAGE_REDIS_PASSWORD` | — | Redis password for session storage |
 
+If you set `SESSION_SECURE=false` for local HTTP development or set `SESSION_DOMAIN`
+for shared-domain cookies, also set `SESSION_NAME` to a non-`__Host-` value such as
+`auth.sid`. The server fails fast when a `__Host-` cookie name is combined with
+attributes that browsers reject for that prefix.
+
 ### Google Federation
 
 | Variable | Default | Description |
@@ -136,6 +142,20 @@ fail fast rather than silently falling back to defaults.
 | `CLIENT_CODE_PASSWORD` | — | Redis password for code storage |
 | `CLIENT_CODE_DEFAULT_EXPIRES_IN` | `600` | Default authorization code lifetime in seconds |
 
+### Redis Namespacing
+
+For multi-tenant Redis clusters, set deployment-specific key prefixes so two
+auth.provider instances cannot collide in the same database:
+
+| Variable | Default | Description |
+|---|---|---|
+| `REDIS_SESSION_STORES_KEY_PREFIX` | `ss:` | Outer prefix for user sessions, RP registry, session-family index, and session-federation index. |
+| `REFRESH_TOKEN_FAMILY_STORE_KEY_PREFIX` | `rtfam:` | Prefix for refresh-token family records. |
+| `CLIENT_CODE_KEY_PREFIX` | `oauth:code:` | Prefix for OAuth authorization codes. |
+
+Use values that include the deployment name, for example `tenant-a:ss:`,
+`tenant-a:rtfam:`, and `tenant-a:code:`.
+
 ### Endpoints
 
 | Variable | Default | Description |
@@ -185,6 +205,18 @@ make test
 
 The `docker-compose.yml` starts the auth server together with a Redis container. Configure environment variables in `.env`.
 
+The production image sets `ENV HTTP_PORT=3000` and uses it for both `EXPOSE`
+and the Docker-native healthcheck against `/_healthcheck`. The HOCON config
+also reads `${?HTTP_PORT}` for `http.port`, so `app.listen()` and the
+healthcheck cannot drift apart. To run on a different port:
+
+```bash
+docker run -e HTTP_PORT=8080 -p 8080:8080 my-auth-provider
+```
+
+`EXPOSE` is image metadata and does not publish ports by itself, so the
+explicit `-p` mapping is still required.
+
 ## Adding Custom Modules
 
 To add a custom module, import it in `src/buildModules.mts` and include it in the `modules` array passed to `createApp`:

package/templates/standalone/config/application.conf

@@ -8,15 +8,17 @@ 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
+    # SF-1 / Phase G / S2: legacy typ acceptance for the
+    # central JWT verifier. The the default is `false`: tokens whose
+    # `typ` header is absent are rejected. Operators with v0.4.x tokens
+    # still in circulation can opt back to legacy acceptance with
+    # `OAUTH_JWT_LEGACY_TYP_ACCEPT=true` for their own bounded migration
+    # window — when set, typ-less tokens verify with a
+    # `jwt_verify_legacy_typ` warning. Per the v0.5.1 ADR the literal
+    # default lives in HOCON, not the Zod schema — this keeps a single
+    # source of truth so the env-var override path and the file default
+    # don't drift.
+    legacyTypAccept = false
     legacyTypAccept = ${?OAUTH_JWT_LEGACY_TYP_ACCEPT}
     signingKey {
       provider = "local"
@@ -60,24 +62,11 @@ oauth {
     # 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.
+    # SF-6 / Phase G / M6: refresh tokens lacking jti or
+    # family_id claims when rotation is wired are always rejected.
+    # The only valid value is "reject"; the `accept-with-warning`
+    # migration-window opt-in was removed.
     # 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} }
@@ -91,6 +80,11 @@ oauth {
     }
     refresh_token { enabled = true, enabled = ${?OAUTH_GRANTS_REFRESH_TOKEN_ENABLED} }
   }
+  # IH-6: when oauth.jwt.issuer is configured, require `openid` in
+  # /authorize scope by default. Set OAUTH_OIDC_MODE=dual only if this OP
+  # intentionally also accepts OAuth-only authorization requests.
+  oidcMode = "oidc-required"
+  oidcMode = ${?OAUTH_OIDC_MODE}
   # 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
@@ -102,10 +96,22 @@ oauth {
     adapter = "redis"
     adapter = ${?OAUTH_CODE_ADAPTER}
   }
+  # F10: maximum existing RFC 8693 actor chain depth accepted before adding
+  # the current actor. Depth 3 allows one current actor plus two prior nested
+  # actors; lower for stricter delegation environments.
+  tokenExchange {
+    maxActorChainDepth = 3
+    maxActorChainDepth = ${?OAUTH_TOKEN_EXCHANGE_MAX_ACTOR_CHAIN_DEPTH}
+  }
 }
 
 session {
   secret = ${?SESSION_SECRET}
+  # MIN-2: __Host- prefix requires Secure, Path=/, and no Domain attribute.
+  # If SESSION_SECURE=false or SESSION_DOMAIN is set, also override
+  # SESSION_NAME to a non-__Host- value.
+  name = "__Host-auth.session"
+  name = ${?SESSION_NAME}
   maxAge = 3600000
   maxAge = ${?SESSION_MAX_AGE}
   secure = true
@@ -222,11 +228,28 @@ rateLimiter {
   adapter = ${?RATE_LIMITER_ADAPTER}
 }
 
+memoryRateLimiter {
+  # SF-10: bound the in-memory OAuth endpoint rate-limiter bucket map.
+  # Multi-replica production should use `rateLimiter.adapter = "redis"`;
+  # this cap keeps the single-process fallback from growing without limit.
+  maxBuckets = 10000
+  maxBuckets = ${?MEMORY_RATE_LIMITER_MAX_BUCKETS}
+}
+
 userSessionStores {
   adapter = "memory"
   adapter = ${?USER_SESSION_STORES_ADAPTER}
 }
 
+# MIN-3: outer namespace for the four bundled Redis user-session stores.
+# The module appends fixed sub-prefixes (`us:`, `rp:`, `fi:`, `fed:`).
+# Multi-tenant Redis deployments should set a deployment-specific value,
+# e.g. `tenant-a:ss:`.
+redisSessionStores {
+  keyPrefix = "ss:"
+  keyPrefix = ${?REDIS_SESSION_STORES_KEY_PREFIX}
+}
+
 # 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

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.5.2",
+	"version": "0.6.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -45,7 +45,7 @@
 		"supertest": "^7.1.0",
 		"tsx": "^4.21.0",
 		"typescript": "^5.9.3",
-		"vitest": "^4.1.2"
+		"vitest": "^4.1.4"
 	},
 	"pnpm": {
 		"onlyBuiltDependencies": [

package/templates/standalone/src/__tests__/smoke.test.mts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { readFileSync } from "node:fs";
 import {
 	type AppConfig,
 	createApp,
@@ -30,6 +31,8 @@ import request from "supertest";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { buildModules } from "../buildModules.mjs";
 
+const dockerfile = readFileSync(new URL("../../Dockerfile", import.meta.url), "utf8");
+
 const config: AppConfig = {
 	http: { port: 0, trustProxy: false },
 	oauth: {
@@ -51,6 +54,7 @@ const config: AppConfig = {
 			legacyRtPolicy: "reject" as const,
 		},
 		grants: {},
+		oidcMode: "oidc-required",
 		// OR-9: explicit memory adapter for the smoke test. The legacy
 		// `repositories.code.type` fallback would also pick memory here,
 		// but the explicit setting documents the intent and avoids
@@ -59,6 +63,7 @@ const config: AppConfig = {
 	},
 	session: {
 		secret: "test-session-secret",
+		name: "auth.sid",
 		maxAge: 3600000,
 		secure: false,
 		sameSite: "lax",
@@ -180,6 +185,36 @@ describe("standalone smoke test", () => {
 		handleRef = undefined;
 	});
 
+	it("Dockerfile declares runtime metadata and runs install/build steps as node", () => {
+		// Default port is 3000 but the HEALTHCHECK and EXPOSE must read it
+		// from ${HTTP_PORT} so an operator overriding the env var keeps the
+		// app, EXPOSE metadata, and healthcheck in sync. Assert the ENV /
+		// EXPOSE / HEALTHCHECK structure rather than the literal port so the
+		// test is not brittle when operators or downstream forks change the
+		// default.
+		// The literal `${HTTP_PORT}` token from the Dockerfile is split across
+		// concatenations to sidestep biome's `noTemplateCurlyInString` rule
+		// (it cannot statically tell that this string is intentionally NOT
+		// a JS template placeholder — it is a Dockerfile env-substitution).
+		const HTTP_PORT_VAR = `$${"{"}HTTP_PORT}`;
+		expect(dockerfile).toContain("ENV HTTP_PORT=3000");
+		expect(dockerfile).toContain(`EXPOSE ${HTTP_PORT_VAR}`);
+		expect(dockerfile).toMatch(
+			/HEALTHCHECK\s+--interval=30s\s+--timeout=3s\s+--start-period=10s\s+--retries=3/,
+		);
+		// Match the literal `${HTTP_PORT}` token inside the HEALTHCHECK CMD.
+		// `[$]` (character class) sidesteps biome's `noTemplateCurlyInString`
+		// false-positive without changing what we actually accept.
+		expect(dockerfile).toMatch(
+			/CMD\s+wget\s+-q\s+-O\s+\/dev\/null\s+"http:\/\/localhost:[$]\{HTTP_PORT\}\/_healthcheck"\s+\|\|\s+exit\s+1/,
+		);
+		expect(dockerfile).toMatch(/FROM node-base AS deps[\s\S]*USER node[\s\S]*RUN pnpm install/);
+		expect(dockerfile).toMatch(/FROM deps AS builder[\s\S]*USER node[\s\S]*RUN pnpm run build/);
+		expect(dockerfile).toMatch(
+			/FROM node-base AS runtime[\s\S]*USER node[\s\S]*RUN pnpm install --prod/,
+		);
+	});
+
 	it("GET /_healthcheck returns 200", async () => {
 		const { app, handle } = await buildApp();
 		handleRef = handle;

package/templates/versions.json

@@ -1,10 +1,10 @@
 {
-	"@o3co/auth-provider-core": "0.5.2",
-	"@o3co/auth-provider-federation-google": "0.5.2",
-	"@o3co/auth-provider-federation-github": "0.5.2",
-	"@o3co/auth-provider-oauth": "0.5.2",
-	"@o3co/auth-provider-oauth-token-exchange": "0.5.2",
-	"@o3co/auth-provider-session": "0.5.2",
-	"@o3co/auth-provider-foundation": "0.5.2",
-	"@o3co/auth-provider-redis": "0.5.2"
+	"@o3co/auth-provider-core": "0.6.0",
+	"@o3co/auth-provider-federation-google": "0.6.0",
+	"@o3co/auth-provider-federation-github": "0.6.0",
+	"@o3co/auth-provider-oauth": "0.6.0",
+	"@o3co/auth-provider-oauth-token-exchange": "0.6.0",
+	"@o3co/auth-provider-session": "0.6.0",
+	"@o3co/auth-provider-foundation": "0.6.0",
+	"@o3co/auth-provider-redis": "0.6.0"
 }