@o3co/create-auth-provider 0.5.3 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,8 +28,8 @@
     "node": ">=18.19.0"
   },
   "devDependencies": {
-    "@types/node": "^25.1.0",
-    "vitest": "^4.1.2"
+    "@types/node": "^25.7.0",
+    "vitest": "^4.1.6"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/config/application.conf

@@ -1,3 +1,11 @@
+# Application-level overrides for the standalone template.
+#
+# The library ships its declarative defaults in
+#   @o3co/auth-provider-core/reference.conf
+# (resolved at boot via standalone/src/app.mts withFallback chain).
+# Values omitted here inherit from that baseline; add overrides only
+# for keys this deployment intentionally diverges on.
+
 http {
   port = 3000
   port = ${?HTTP_PORT}
@@ -6,81 +14,22 @@ 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}
-      local {
-        algorithm = "HS256"
-        algorithm = ${?OAUTH_JWT_ALGORITHM}
-        kid = "v0"
-        kid = ${?OAUTH_JWT_KID}
-        secret = ${?OAUTH_JWT_SECRET}
-        privateKey = ${?OAUTH_JWT_PRIVATE_KEY}
-        privateKeyPath = ${?OAUTH_JWT_PRIVATE_KEY_PATH}
-        publicKey = ${?OAUTH_JWT_PUBLIC_KEY}
-        publicKeyPath = ${?OAUTH_JWT_PUBLIC_KEY_PATH}
-        # 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 = []
-      }
-    }
-  }
-  accessToken {
-    expiresIn = 3600
-    expiresIn = ${?OAUTH_ACCESS_TOKEN_EXPIRES_IN}
-  }
-  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} }
+    # Template is a typical web-app OP — enable the universal user-auth path.
+    # client_credentials remains off (reference.conf default); deployments that
+    # need M2M flows set OAUTH_GRANTS_CLIENT_CREDENTIALS_ENABLED=true or add
+    # `client_credentials { enabled = true }` in their own application.conf.
+    #
+    # The env-override line (`enabled = ${?OAUTH_GRANTS_*_ENABLED}`) is repeated
+    # at this layer because HOCON precedence: application.conf wins over
+    # reference.conf, so without the env-override line at the template layer,
+    # an operator setting OAUTH_GRANTS_SESSION_ENABLED=false (etc.) cannot
+    # disable the grant — the env var only takes effect at the layer where
+    # the substitution is written.
+    session {
+      enabled = true
+      enabled = ${?OAUTH_GRANTS_SESSION_ENABLED}
+    }
     authorization_code {
       enabled = true
       enabled = ${?OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED}
@@ -89,13 +38,14 @@ oauth {
         requireS256 = ${?OAUTH_GRANTS_AUTHORIZATION_CODE_PKCE_REQUIRE_S256}
       }
     }
-    refresh_token { enabled = true, enabled = ${?OAUTH_GRANTS_REFRESH_TOKEN_ENABLED} }
+    refresh_token {
+      enabled = true
+      enabled = ${?OAUTH_GRANTS_REFRESH_TOKEN_ENABLED}
+    }
+    # client_credentials: omitted -> inherits reference.conf default (enabled = false).
+    # Operators that need M2M flows set OAUTH_GRANTS_CLIENT_CREDENTIALS_ENABLED=true
+    # or add `client_credentials { enabled = true }` here.
   }
-  # 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
@@ -107,13 +57,6 @@ 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 {
@@ -149,17 +92,20 @@ session {
 #       component (memoryRateLimiterModule or redisRateLimiterModule) with
 #       its own `memoryRateLimiter.*` / `redisRateLimiter.*` config section
 #       (uses `windowSeconds` instead of `windowMs`). Switch via
-#       `rateLimiter.adapter = "memory" | "redis"` (see below).
+#       `rateLimiter.adapter = "memory" | "redis"` (see reference.conf).
 rateLimit {
+  # `login` is per-deployment tuning (bruteforce-window + limit), kept in
+  # this layer so operators can tweak without forking reference.conf.
   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}
+  # rateLimit.failMode: inherits reference.conf default ("closed").
+  # Deployments that prefer fail-open override here:
+  #   failMode = "open"
+  #   failMode = ${?RATE_LIMIT_FAIL_MODE}
 }
 
 federations {
+  # Template ships a Google federation declaration disabled-by-default.
+  # Operators enable + populate credentials via env vars.
   google {
     enabled = false
     enabled = ${?FEDERATIONS_GOOGLE_ENABLED}
@@ -221,83 +167,13 @@ 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}
-}
-
-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
 # + 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}
-}
-
+# Redis, defeating the cross-replica persistence purpose.
 refreshTokenFamilyStore {
   redis {
     url = "redis://localhost:6379"

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.5.3",
+	"version": "0.7.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -40,12 +40,12 @@
 	"devDependencies": {
 		"@types/express": "^5.0.6",
 		"@types/express-session": "^1",
-		"@types/node": "^25.1.0",
+		"@types/node": "^25.7.0",
 		"@types/supertest": "^7.2.0",
 		"supertest": "^7.1.0",
 		"tsx": "^4.21.0",
 		"typescript": "^5.9.3",
-		"vitest": "^4.1.2"
+		"vitest": "^4.1.6"
 	},
 	"pnpm": {
 		"onlyBuiltDependencies": [

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

@@ -14,8 +14,10 @@
  * limitations under the License.
  */
 
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import { describe, expect, it } from "vitest";
-import { resolveConfigPaths } from "../configPath.mjs";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
 
 describe("resolveConfigPaths", () => {
 	it("accepts a configDirPath with a trailing slash (regression: fileURLToPath preserves trailing /)", () => {
@@ -48,3 +50,18 @@ describe("resolveConfigPaths", () => {
 		).toThrow(/resolves outside/);
 	});
 });
+
+describe("resolveLibraryReferenceConfPath", () => {
+	it("returns an absolute path ending in reference.conf", () => {
+		const path = resolveLibraryReferenceConfPath();
+		expect(path.endsWith("reference.conf")).toBe(true);
+		// Use `isAbsolute` rather than `startsWith("/")` so the assertion
+		// holds on Windows (e.g. `C:\...`) as well as POSIX paths.
+		expect(isAbsolute(path)).toBe(true);
+	});
+
+	it("points to a file that exists on disk", () => {
+		const path = resolveLibraryReferenceConfPath();
+		expect(existsSync(path)).toBe(true);
+	});
+});

package/templates/standalone/src/__tests__/library-reference-resolution.smoke.test.mts

@@ -0,0 +1,29 @@
+/*
+ * 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 { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+describe("library reference.conf subpath resolution", () => {
+	it("resolves @o3co/auth-provider-core/reference.conf to a readable file", () => {
+		const url = import.meta.resolve("@o3co/auth-provider-core/reference.conf");
+		const path = fileURLToPath(url);
+		expect(existsSync(path)).toBe(true);
+		const content = readFileSync(path, "utf-8");
+		expect(content).toMatch(/oauth\s*\{/); // sanity: HOCON content
+	});
+});

package/templates/standalone/src/__tests__/three-tier-resolution.test.mts

@@ -0,0 +1,117 @@
+/*
+ * 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 { fileURLToPath } from "node:url";
+import { type AppConfig, AppConfigSchema } from "@o3co/auth-provider-core";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import { describe, expect, it } from "vitest";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
+
+// config/ is two levels above this test file:
+//   src/__tests__/ → src/ → standalone/ → config/
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+// Provide required secrets so AppConfigSchema parse succeeds. These are
+// test-only values — no real keys are embedded here.
+const testEnv = {
+	OAUTH_JWT_SECRET: "test-secret-three-tier",
+	SESSION_SECRET: "test-session-secret-three-tier",
+};
+
+function buildResolvedConfig(env: string, extraEnv: Record<string, string> = {}): AppConfig {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, env);
+	const libraryReferencePath = resolveLibraryReferenceConfPath();
+	const resolvedEnv = { ...testEnv, ...extraEnv };
+	return validate(
+		parseFile(envConfPath, { env: resolvedEnv })
+			.withFallback(parseFile(applicationConfPath, { env: resolvedEnv }))
+			.withFallback(parseFile(libraryReferencePath, { env: resolvedEnv })),
+		AppConfigSchema,
+	);
+}
+
+// `oauth.grants` is declared as `z.object({}).passthrough()` in the schema,
+// so the inferred TS type is `{}` per entry and accessing `.enabled` doesn't
+// compile under `tsc --strict`. Tests assert against the resolved runtime
+// shape (string from env substitution, boolean from literal), so the cast
+// is intentional and well-bounded.
+type GrantEntry = { enabled?: unknown };
+const grants = (config: AppConfig) =>
+	(config.oauth.grants as unknown as Record<string, GrantEntry | undefined>) ?? {};
+
+describe("three-tier HOCON resolution (env → application.conf → reference.conf)", () => {
+	it("template application.conf wins over reference.conf for grant.enabled", () => {
+		const config = buildResolvedConfig("development");
+		// Template's application.conf sets authorization_code.enabled = true.
+		// This test asserts the resolved value — it remains true whether
+		// reference.conf says false (current secure-default) or true (legacy).
+		expect(grants(config).authorization_code?.enabled).toBe(true);
+	});
+
+	it("reference.conf default reaches resolved config when template omits the key", () => {
+		const config = buildResolvedConfig("development");
+		// tokenExchange.maxActorChainDepth is library-owned in both layers
+		// (template doesn't override it). Verifies precedence falls through.
+		expect(config.oauth.tokenExchange?.maxActorChainDepth).toBe(3);
+	});
+
+	it("env var at template layer can disable a template-enabled grant (precedence: env-override line must be repeated)", () => {
+		// Template enables authorization_code via application.conf. The env-override
+		// line is repeated at the template layer alongside `enabled = true`,
+		// so OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED=false reaches the resolved value.
+		// Without the repeated env line, the substitution at reference.conf is
+		// shadowed by the template's literal `true`.
+		// Note: ts.hocon substitutes env vars as strings; the schema (passthrough)
+		// preserves the string. The assertion checks the string form so that
+		// the precedence invariant is testable now; a future schema-coercion PR
+		// (separate from this one) will make this resolve to boolean false.
+		const config = buildResolvedConfig("development", {
+			OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED: "false",
+		});
+		expect(grants(config).authorization_code?.enabled).toBe("false");
+	});
+
+	it("reference.conf default for rateLimit.failMode is 'closed'", () => {
+		const config = buildResolvedConfig("development");
+		expect(config.rateLimit?.failMode).toBe("closed");
+	});
+
+	it("reference.conf default for client_credentials.enabled is false", () => {
+		// Template doesn't enable client_credentials. Reference default propagates.
+		const config = buildResolvedConfig("development");
+		expect(grants(config).client_credentials?.enabled).toBe(false);
+	});
+
+	it("reference.conf default for oauth.resourceIndicator.enabled is false", () => {
+		// reference.conf must ship the literal `false` anchor so that the
+		// schema coercion (coerceBooleanFromEnv) can produce a boolean value.
+		// Without the HOCON block the field resolves to undefined.
+		const config = buildResolvedConfig("development");
+		expect(config.oauth.resourceIndicator?.enabled).toBe(false);
+	});
+
+	it("env var OAUTH_RESOURCE_INDICATOR_ENABLED=true reaches resolved config and coerces to boolean true", () => {
+		// HOCON env-substitution returns a string. The reference.conf anchor
+		// (`enabled = ${?OAUTH_RESOURCE_INDICATOR_ENABLED}`) lets the env var
+		// reach the resolved layer; the schema's coerceBooleanFromEnv turns
+		// "true" → true so `=== true` guards in grant handlers work correctly.
+		const config = buildResolvedConfig("development", {
+			OAUTH_RESOURCE_INDICATOR_ENABLED: "true",
+		});
+		expect(config.oauth.resourceIndicator?.enabled).toBe(true);
+	});
+});

package/templates/standalone/src/app.mts

@@ -23,16 +23,24 @@ import helmet from "helmet";
 
 import logger from "#/logger.mjs";
 import { buildModules } from "./buildModules.mjs";
-import { resolveConfigPaths } from "./configPath.mjs";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "./configPath.mjs";
 
 // Step 1: Load and validate application config (HOCON → Zod schema).
 // ENV = CONFIG_ENV || NODE_ENV || "development"; missing {ENV}.conf is fatal.
+//
+// 3-tier HOCON precedence (highest → lowest):
+//   1. {env}.conf         — environment-specific overrides (e.g. production.conf)
+//   2. application.conf   — template-level consumer delta
+//   3. reference.conf     — library defaults shipped in @o3co/auth-provider-core
 const env = process.env.CONFIG_ENV || process.env.NODE_ENV || "development";
 const configDir = new URL("../config/", import.meta.url);
 const configDirPath = fileURLToPath(configDir);
 const { applicationConfPath, envConfPath } = resolveConfigPaths(configDirPath, env);
+const libraryReferencePath = resolveLibraryReferenceConfPath();
 const config: AppConfig = validate(
-	parseFile(envConfPath).withFallback(parseFile(applicationConfPath)),
+	parseFile(envConfPath)
+		.withFallback(parseFile(applicationConfPath))
+		.withFallback(parseFile(libraryReferencePath)),
 	AppConfigSchema,
 );
 

package/templates/standalone/src/buildModules.mts

@@ -97,9 +97,9 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 
 	// OR-9: effective code-repo adapter. `oauth.code.adapter` is the
 	// authoritative switch; the legacy `repositories.code.type = "redis"`
-	// path is honored for one release with a deprecation warn so existing
-	// operators relying on `CLIENT_CODE_TYPE=redis` env-var overrides keep
-	// working until they migrate. Removed in v0.6.
+	// path is honored with a deprecation warn so existing operators
+	// relying on `CLIENT_CODE_TYPE=redis` env-var overrides keep working
+	// until they migrate. See CHANGELOG for the removal version.
 	const oauthCodeAdapter = config.oauth?.code?.adapter;
 	const legacyCodeType = (config.repositories?.code as { type?: string } | undefined)?.type;
 	let codeRepositoryAdapter: "memory" | "redis";
@@ -108,7 +108,7 @@ export function buildModules(config: AppConfig, overrides: BuildModulesOverrides
 	} else if (legacyCodeType === "redis") {
 		console.warn(
 			'[buildModules] `repositories.code.type = "redis"` is deprecated; use ' +
-				'`oauth.code.adapter = "redis"` instead (will be removed in v0.6).',
+				'`oauth.code.adapter = "redis"` instead — see CHANGELOG for the removal version.',
 		);
 		codeRepositoryAdapter = "redis";
 	} else {

package/templates/standalone/src/configPath.mts

@@ -14,13 +14,43 @@
  * limitations under the License.
  */
 
+import { createRequire } from "node:module";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 export interface ResolvedConfigPaths {
 	readonly applicationConfPath: string;
 	readonly envConfPath: string;
 }
 
+const REFERENCE_CONF_SUBPATH = "@o3co/auth-provider-core/reference.conf";
+
+/**
+ * Returns the absolute path to the shipped `reference.conf` inside
+ * `@o3co/auth-provider-core`. This file is the bottom layer of the
+ * 3-tier HOCON precedence chain (reference.conf → application.conf → {env}.conf).
+ *
+ * Primary path: `import.meta.resolve` (Node.js Stability 1.2 RC, unflagged
+ * since Node 18.19.0 / 20.6.0 — the engine floor of every package in this
+ * scope). Fallback: `createRequire(import.meta.url).resolve(...)`. The
+ * fallback covers two edge cases:
+ *
+ * 1. A future Node release deprecates or alters the sync form of
+ *    `import.meta.resolve` (still labelled Stability 1.2 RC per Node docs).
+ * 2. An exotic runtime / loader where `import.meta.resolve` is not
+ *    available but CommonJS-style resolution still is.
+ *
+ * Both APIs read the same `exports` map in `@o3co/auth-provider-core`'s
+ * `package.json`, so the resolved path is identical.
+ */
+export function resolveLibraryReferenceConfPath(): string {
+	try {
+		return fileURLToPath(import.meta.resolve(REFERENCE_CONF_SUBPATH));
+	} catch {
+		return createRequire(import.meta.url).resolve(REFERENCE_CONF_SUBPATH);
+	}
+}
+
 export function resolveConfigPaths(configDirPath: string, env: string): ResolvedConfigPaths {
 	// path.resolve strips trailing slashes that fileURLToPath may preserve, so
 	// the containment check below compares equal shapes (path.dirname never

package/templates/versions.json

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