@o3co/create-auth-policy-verifier 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-policy-verifier",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Scaffold a new o3co/auth.policy-verifier project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",

package/templates/standalone/README.ja.md

@@ -43,7 +43,9 @@ OAUTH_JWT_SECRET=$(openssl rand -hex 32) \
 | `OAUTH_JWT_JWKS_TIMEOUT_MS` | `5000` | JWKS 取得をこの時間で打ち切る |
 | `OAUTH_JWT_JWKS_COOLDOWN_MS` | `30000` | JWKS 再取得の最小間隔 |
 | `OAUTH_JWT_JWKS_CACHE_MAX_AGE_MS` | `600000` | 取得した JWKS をキャッシュから返す期間 |
-| `OAUTH_JWT_TOKEN_TYPE` | `at+jwt` | 受け入れる `typ` ヘッダ。同じ鍵で署名された id/refresh/logout token を拒否する |
+| `OAUTH_JWT_TOKEN_TYPE` | `at+jwt` | 受け入れる `typ` ヘッダ。同じ鍵で署名された id/refresh/logout token を拒否する。`*` で pin しない（その場合 `audience` を OIDC client id にしてはいけない） |
+| `OAUTH_JWT_AUDIENCE_CLAIM` | `aud` | audience を読む claim。`azp`（Clerk）、`client_id`（Cognito）。`aud` 以外を指定すると `aud` は一切見ない |
+| `OAUTH_AUTHENTICATOR` | `jwt` | subject を確立する token authenticator。他の名前は `main.mts` で module が登録したもの |
 | `OAUTH_JWT_MODE` | `verify` | `verify` はトークンを完全検証。明示的な `insecure-decode`（テスト専用）は署名検証なしでデコードする — `exp`/`nbf` は引き続き強制される |
 | `RULE_ON_EMPTY_RULE_SET` | `deny` | ルールが 1 つも集まらなかったときの決定（`deny` \| `allow`） |
 | `VERIFY_MAX_BATCH_SIZE` | `50` | `POST /verify/batch` の件数上限 |

package/templates/standalone/README.md

@@ -43,7 +43,9 @@ Individual values can also be overridden with environment variables.
 | `OAUTH_JWT_JWKS_TIMEOUT_MS` | `5000` | Abort a JWKS fetch after this long |
 | `OAUTH_JWT_JWKS_COOLDOWN_MS` | `30000` | Minimum spacing between JWKS fetches |
 | `OAUTH_JWT_JWKS_CACHE_MAX_AGE_MS` | `600000` | How long a fetched JWKS is served from cache |
-| `OAUTH_JWT_TOKEN_TYPE` | `at+jwt` | Accepted `typ` header; rejects id/refresh/logout tokens signed with the same key |
+| `OAUTH_JWT_TOKEN_TYPE` | `at+jwt` | Accepted `typ` header; rejects id/refresh/logout tokens signed with the same key. `*` pins nothing (then `audience` must not be an OIDC client id) |
+| `OAUTH_JWT_AUDIENCE_CLAIM` | `aud` | Claim the audience is read from: `azp` (Clerk), `client_id` (Cognito). Anything but `aud` means `aud` is not consulted at all |
+| `OAUTH_AUTHENTICATOR` | `jwt` | Which token authenticator establishes the subject; another name must be registered by a module in `main.mts` |
 | `OAUTH_JWT_MODE` | `verify` | `verify` fully verifies tokens; the explicit `insecure-decode` (test-only) decodes without signature verification — `exp`/`nbf` are still enforced |
 | `RULE_ON_EMPTY_RULE_SET` | `deny` | Decision when no rule is collected (`deny` \| `allow`) |
 | `VERIFY_MAX_BATCH_SIZE` | `50` | Cap on `POST /verify/batch` entries |

package/templates/standalone/config/application.conf

@@ -35,6 +35,15 @@ http {
 }
 
 oauth {
+  # Which token authenticator establishes the subject of a decision. "jwt"
+  # (the default) is the built-in bearer-JWT path the block below configures.
+  # A deployment whose IdP issues opaque tokens, or whose gateway already
+  # authenticated the caller, registers its own authenticator in main.mts and
+  # names it here — see docs/extending.md, "Writing a token authenticator".
+  # With another name the `jwt` block must be omitted — that authenticator's
+  # keys go under its own sub-block (oauth.<name> { … }).
+  authenticator = "jwt"
+  authenticator = ${?OAUTH_AUTHENTICATOR}
   jwt {
     algorithm = "HS256"
     algorithm = ${?OAUTH_JWT_ALGORITHM}
@@ -120,6 +129,19 @@ oauth {
     # rejects id_tokens, refresh tokens and logout tokens signed with the same key.
     tokenType = "at+jwt"
     tokenType = ${?OAUTH_JWT_TOKEN_TYPE}
+    # `tokenType = "*"` (exactly that) pins nothing — any typ, or none. For
+    # issuers whose tokens carry no typ header (Cognito). The audience is then
+    # the only thing telling an access token from an id_token signed with the
+    # same key, so `audience` must NOT be an OIDC client id under "*": use an
+    # API identifier, or an audienceClaim id_tokens lack (Cognito: client_id).
+    # The claim the audience is read from. "aud" (the default) is RFC 9068;
+    # "azp" binds a Clerk session token, "client_id" a Cognito access token.
+    # The check moves, it never goes away — `audience` above stays required.
+    # With anything but "aud" here, `aud` is NOT consulted at all: use it only
+    # for issuers that emit no aud, and never name a claim the user can write
+    # (Clerk unsafe_metadata, Auth0 user_metadata).
+    audienceClaim = "aud"
+    audienceClaim = ${?OAUTH_JWT_AUDIENCE_CLAIM}
 
     # Bounds on a presented token's own lifetime. Both apply in EVERY mode,
     # insecure-decode included. `exp` itself is required and has no setting:
@@ -176,6 +198,8 @@ attribute {
   # can never pass — see the note in the rule block.
   collectors = [
     # The token's `scope` claim, split into the list the scope rule reads.
+    # `claim = "scp"` reads Okta's scope array instead; pair it with the same
+    # `claim` on ResourceActionScopeRuleCollector below (#219).
     { collector = "PayloadScopeCollector" }
     # The token's `sub`, which becomes the `subject` on the decision response
     # and the `sub` field on the audit log line.

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-policy-verifier-standalone",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.29.3",

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

@@ -89,12 +89,12 @@ describe("loadAppConfig", () => {
 				pathPrefix: "",
 				callerAuth: { header: "x-caller-token" },
 			});
-			expect(config.oauth.jwt.algorithm).toBe("HS256");
-			expect(config.oauth.jwt.secret).toBe(TEST_SECRET);
-			expect(config.oauth.jwt.mode).toBe("verify");
-			expect(config.oauth.jwt.issuer).toBe("https://issuer.test");
-			expect(config.oauth.jwt.audience).toBe("https://api.test");
-			expect(config.oauth.jwt.tokenType).toBe("at+jwt");
+			expect(config.oauth.jwt?.algorithm).toBe("HS256");
+			expect(config.oauth.jwt?.secret).toBe(TEST_SECRET);
+			expect(config.oauth.jwt?.mode).toBe("verify");
+			expect(config.oauth.jwt?.issuer).toBe("https://issuer.test");
+			expect(config.oauth.jwt?.audience).toBe("https://api.test");
+			expect(config.oauth.jwt?.tokenType).toBe("at+jwt");
 			expect(config.verify.maxBatchSize).toBe(50);
 		},
 	);
@@ -170,7 +170,7 @@ describe("loadAppConfig", () => {
 
 		const config = loadAppConfig(configDirPath, "development");
 
-		expect(config.oauth.jwt.mode).toBe("insecure-decode");
+		expect(config.oauth.jwt?.mode).toBe("insecure-decode");
 	});
 
 	it("rejects a boolean-ish OAUTH_JWT_MODE left over from the removed OAUTH_JWT_VALIDATE", () => {
@@ -237,11 +237,11 @@ describe("loadAppConfig — numeric knobs through the real 3-tier resolution (#1
 		const config = loadAppConfig(configDirPath, "development");
 
 		expect(config.http.port).toBe(3000);
-		expect(config.oauth.jwt.jwksTimeoutMs).toBe(5000);
-		expect(config.oauth.jwt.jwksCooldownMs).toBe(30_000);
-		expect(config.oauth.jwt.jwksCacheMaxAgeMs).toBe(600_000);
-		expect(config.oauth.jwt.maxTokenAgeSeconds).toBe(86_400);
-		expect(config.oauth.jwt.clockToleranceSeconds).toBe(0);
+		expect(config.oauth.jwt?.jwksTimeoutMs).toBe(5000);
+		expect(config.oauth.jwt?.jwksCooldownMs).toBe(30_000);
+		expect(config.oauth.jwt?.jwksCacheMaxAgeMs).toBe(600_000);
+		expect(config.oauth.jwt?.maxTokenAgeSeconds).toBe(86_400);
+		expect(config.oauth.jwt?.clockToleranceSeconds).toBe(0);
 		expect(config.verify.maxBatchSize).toBe(50);
 		// The request limits (#118) travel the same path.
 		expect(config.verify.maxBodyBytes).toBe(65_536);
@@ -272,11 +272,11 @@ describe("loadAppConfig — numeric knobs through the real 3-tier resolution (#1
 		const config = loadAppConfig(configDirPath, "development");
 
 		expect(config.http.port).toBe(8080);
-		expect(config.oauth.jwt.jwksTimeoutMs).toBe(2500);
-		expect(config.oauth.jwt.jwksCooldownMs).toBe(0);
-		expect(config.oauth.jwt.jwksCacheMaxAgeMs).toBe(120_000);
-		expect(config.oauth.jwt.maxTokenAgeSeconds).toBe(600);
-		expect(config.oauth.jwt.clockToleranceSeconds).toBe(60);
+		expect(config.oauth.jwt?.jwksTimeoutMs).toBe(2500);
+		expect(config.oauth.jwt?.jwksCooldownMs).toBe(0);
+		expect(config.oauth.jwt?.jwksCacheMaxAgeMs).toBe(120_000);
+		expect(config.oauth.jwt?.maxTokenAgeSeconds).toBe(600);
+		expect(config.oauth.jwt?.clockToleranceSeconds).toBe(60);
 		expect(config.verify.maxBatchSize).toBe(25);
 		expect(config.verify.maxBodyBytes).toBe(16_384);
 		expect(config.verify.maxResourceLength).toBe(128);

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

@@ -239,6 +239,34 @@ describe("installGracefulShutdown", () => {
 		expect(exitProcess).toHaveBeenCalledWith(3);
 	});
 
+	it("reports the cleanup outcome as the reason, not the drain that preceded it", async () => {
+		// `exitCode` became 1 while `reason` still said "drained", so the one line
+		// an operator alerts on contradicted itself. The drain outcome is still
+		// carried, under its own key, so neither fact is lost.
+		const { signals, finishDraining, logger, exit } = install({
+			cleanup: () => Promise.reject(new Error("teardown failed")),
+		});
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await settle();
+		expect(logger.info).toHaveBeenCalledWith(
+			{ reason: "cleanup-failed", drain: "drained", exitCode: 1 },
+			"graceful shutdown: complete",
+		);
+		expect(exit).toHaveBeenCalledWith(1);
+	});
+
+	it("keeps reason and drain identical when cleanup succeeds", async () => {
+		const { signals, finishDraining, logger } = install({ cleanup: () => Promise.resolve() });
+		signals.get("SIGTERM")?.();
+		finishDraining();
+		await settle();
+		expect(logger.info).toHaveBeenCalledWith(
+			{ reason: "drained", drain: "drained", exitCode: 0 },
+			"graceful shutdown: complete",
+		);
+	});
+
 	it("removes its own signal listeners once shutting down", () => {
 		const { signals } = install();
 		signals.get("SIGTERM")?.();

package/templates/standalone/src/shutdown.ts

@@ -61,7 +61,7 @@ export interface GracefulShutdownOptions {
 	 * sequence — size both against the orchestrator's grace period, not one.
 	 */
 	readonly cleanupTimeoutMs?: number;
-	/** Injected in tests; defaults to `process.exit`. */
+	/** Injected in tests; defaults to {@link deferExit}. */
 	readonly exit?: (code: number) => void;
 	/** Injected in tests; defaults to `process.on`. */
 	readonly onSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
@@ -136,10 +136,16 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		if (finished) return;
 		finished = true;
 		let exitCode = code;
+		// `reason` names whatever decided the exit code, so the line an operator
+		// alerts on cannot say "drained" next to a non-zero code. The drain
+		// outcome keeps its own key rather than being overwritten — both facts
+		// are wanted, and a stable shape is what makes the line queryable.
+		let outcome = reason;
 		try {
 			if ((await runCleanup()) === CLEANUP_TIMED_OUT) {
 				logger.error({ cleanupTimeoutMs }, "graceful shutdown: cleanup timed out");
 				exitCode = 1;
+				outcome = "cleanup-timeout";
 			}
 		} catch (err) {
 			// Through the app logger, not `console.error`: a shutdown that
@@ -148,8 +154,9 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 			// drops.
 			logger.error({ err }, "graceful shutdown: cleanup failed");
 			exitCode = 1;
+			outcome = "cleanup-failed";
 		}
-		logger.info({ reason, exitCode }, "graceful shutdown: complete");
+		logger.info({ reason: outcome, drain: reason, exitCode }, "graceful shutdown: complete");
 		exit(exitCode);
 	};
 

package/templates/versions.json

@@ -1,5 +1,5 @@
 {
-	"@o3co/auth.policy-verifier.core": "0.8.0",
-	"@o3co/auth.policy-verifier.builtins": "0.8.0",
-	"@o3co/auth.policy-verifier.server": "0.8.0"
+	"@o3co/auth.policy-verifier.core": "0.9.0",
+	"@o3co/auth.policy-verifier.builtins": "0.9.0",
+	"@o3co/auth.policy-verifier.server": "0.9.0"
 }