@o3co/create-auth-policy-verifier 0.3.1 → 0.5.0

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

@@ -4,71 +4,112 @@
 /*
  * Smoke tests for the standalone template.
  *
- * These tests verify that the app created by the standalone template boots correctly
- * and that core HTTP endpoints respond as expected.
+ * These tests boot the app from `config/application.conf` — the file the image
+ * ships and an operator deploys — read through `loadAppConfig`, the same
+ * function `main.mts` calls. Nothing here restates the policy: the thing under
+ * test is the thing that ships.
  *
- * The composition here intentionally mirrors main.mts — using builtinCollectorsModule
- * and registry keys that match application.conf — so that renames or interface changes
- * in the builtins package are caught here before reaching production.
+ * That is the point of #113. The suite used to assemble its own config, minus
+ * the one collector that made the shipped file deny every request, and stayed
+ * green while the product was non-functional. A config the tests hand-write can
+ * agree with `application.conf` only by vigilance, and it stopped agreeing.
  *
- * Note: ResourceActionPermissionRuleCollector is omitted from the smoke config because
- * it requires a permission store (e.g. StaticPermissionCollector) to grant any access.
- * The scope-based check via ResourceActionScopeRuleCollector is sufficient to exercise
- * the allow/deny paths in isolation.
+ * The three values the file deliberately does not carry — the HS256 secret, the
+ * issuer and the audience — come from the environment here exactly as they do
+ * in a deployment. A credential must never be written in a config file, so
+ * supplying them is loading the shipped config, not editing it.
  */
+import { fileURLToPath } from "node:url";
 import { builtinCollectorsModule } from "@o3co/auth.policy-verifier.builtins";
-import {
-	AppConfigSchema,
-	builtinKeyResolversModule,
-	createApp,
-} from "@o3co/auth.policy-verifier.server";
+import { consoleLogger } from "@o3co/auth.policy-verifier.core";
+import type { AppConfig } from "@o3co/auth.policy-verifier.server";
+import { builtinKeyResolversModule, createApp } from "@o3co/auth.policy-verifier.server";
 import { SignJWT } from "jose";
 import request from "supertest";
 import { describe, expect, it } from "vitest";
+import { loadAppConfig } from "../loadConfig.js";
 
-const JWT_SECRET = "standalone-smoke-secret";
+/** 64 hex characters — 32 decoded bytes, the entropy floor #114 enforces. */
+const JWT_SECRET = "11".repeat(32);
 const secretKey = new TextEncoder().encode(JWT_SECRET);
+const ISSUER = "https://issuer.test";
+const AUDIENCE = "https://api.test";
+
+const configDirPath = fileURLToPath(new URL("../../config/", import.meta.url));
 
 async function signToken(payload: Record<string, unknown>): Promise<string> {
-	return new SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt().sign(secretKey);
+	return (
+		new SignJWT(payload)
+			.setProtectedHeader({ alg: "HS256", typ: "at+jwt" })
+			.setIssuedAt()
+			// iat and exp are both mandatory now (#110).
+			.setExpirationTime("1h")
+			.setIssuer(ISSUER)
+			.setAudience(AUDIENCE)
+			.sign(secretKey)
+	);
 }
 
-// Config mirrors the structure of application.conf, using the same builtin registry keys.
-// PayloadScopeCollector extracts scopes from the JWT "scope" claim.
-// ResourceActionScopeRuleCollector requires scope "<action>:<resourceType>" to be present.
-// DotNotationResourceParser is the default and matches the omitted resource.parser in application.conf.
-const baseConfig = AppConfigSchema.parse({
-	oauth: { jwt: { secret: JWT_SECRET, validate: true } },
-	attribute: {
-		collectors: [
-			{ collector: "PayloadScopeCollector" },
-			{ collector: "PayloadSubjectIdCollector" },
-		],
-	},
-	rule: {
-		collectors: [{ collector: "ResourceActionScopeRuleCollector" }],
-	},
-	// resource.parser defaults to "DotNotationResourceParser" — matches application.conf omission
-});
+/** The three values `application.conf` leaves to the deployment. */
+const DEPLOYMENT_ENV = {
+	OAUTH_JWT_SECRET: JWT_SECRET,
+	OAUTH_JWT_ISSUER: ISSUER,
+	OAUTH_JWT_AUDIENCE: AUDIENCE,
+} as const;
+
+/**
+ * The shipped config, loaded the way the container loads it: the development
+ * overlay resolved against `config/application.conf`, with the deployment's
+ * three values in the environment.
+ *
+ * `process.env` is process-wide, and a test file does not own it. So each
+ * variable's prior value is **restored**, not deleted — and "was absent" is
+ * restored as absent rather than as `""`, which is a different state this very
+ * config distinguishes (an exported-empty credential is refused rather than read
+ * as "unset"). Deleting unconditionally would hand any file sharing the worker a
+ * value this one happened to clear.
+ *
+ * The window is nil as well as tidy: every step here is synchronous —
+ * `loadAppConfig` parses and validates without awaiting — and this runs at module
+ * scope, so no other file's code can be scheduled between the assignment and the
+ * restore.
+ */
+function loadShippedConfig(): AppConfig {
+	const saved: Array<[key: string, previous: string | undefined]> = Object.keys(DEPLOYMENT_ENV).map(
+		(key) => [key, process.env[key]],
+	);
+	Object.assign(process.env, DEPLOYMENT_ENV);
+	try {
+		return loadAppConfig(configDirPath, "development");
+	} finally {
+		for (const [key, previous] of saved) {
+			if (previous === undefined) delete process.env[key];
+			else process.env[key] = previous;
+		}
+	}
+}
+
+const shippedConfig = loadShippedConfig();
+
+/** The composition `main.mts` builds, over whichever config is handed in. */
+function createShippedApp(config: AppConfig = shippedConfig) {
+	return createApp({
+		pathResolver: (s: string) => s,
+		config,
+		modules: [builtinCollectorsModule, builtinKeyResolversModule],
+	});
+}
 
 describe("standalone smoke", () => {
 	it("GET /healthcheck returns 200", async () => {
-		const app = await createApp({
-			pathResolver: (s: string) => s,
-			config: baseConfig,
-			modules: [builtinCollectorsModule, builtinKeyResolversModule],
-		});
+		const app = await createShippedApp();
 
 		const res = await request(app).get("/healthcheck");
 		expect(res.status).toBe(200);
 	});
 
 	it("POST /verify with sufficient scope returns 200 (allow)", async () => {
-		const app = await createApp({
-			pathResolver: (s: string) => s,
-			config: baseConfig,
-			modules: [builtinCollectorsModule, builtinKeyResolversModule],
-		});
+		const app = await createShippedApp();
 
 		// PayloadScopeCollector extracts "read:document" from the JWT scope claim.
 		// ResourceActionScopeRuleCollector requires scope "<action>:<resourceType>".
@@ -83,12 +124,122 @@ describe("standalone smoke", () => {
 		expect(res.body.decision).toBe("allow");
 	});
 
+	it("POST /verify with a scopeless token returns 403 (deny)", async () => {
+		const app = await createShippedApp();
+
+		// A validly-signed token carrying no scope claim asserts no capability, so a
+		// scope-only pipeline must deny it rather than collect zero rules and allow.
+		const token = await signToken({ sub: "user-1" });
+		const res = await request(app)
+			.post("/verify")
+			.set("Authorization", `Bearer ${token}`)
+			.send({ resource: "document", action: "read" });
+
+		expect(res.status).toBe(403);
+		expect(res.body.decision).toBe("deny");
+	});
+
+	it("POST /verify with an id_token signed by the same key returns 401", async () => {
+		const app = await createShippedApp();
+
+		// The paired provider signs id_tokens with the same key as access tokens;
+		// only the typ header separates them.
+		const token = await new SignJWT({ scope: "read:document" })
+			.setProtectedHeader({ alg: "HS256", typ: "id+jwt" })
+			.setIssuedAt()
+			.setExpirationTime("1h")
+			.setIssuer(ISSUER)
+			.setAudience(AUDIENCE)
+			.sign(secretKey);
+		const res = await request(app)
+			.post("/verify")
+			.set("Authorization", `Bearer ${token}`)
+			.send({ resource: "document", action: "read" });
+
+		expect(res.status).toBe(401);
+		expect(res.body.code).toBe("invalid_token");
+	});
+
+	it("POST /verify/batch decides every entry in one round trip", async () => {
+		const app = await createShippedApp();
+
+		const token = await signToken({ sub: "user-1", scope: "read:document" });
+		const res = await request(app)
+			.post("/verify/batch")
+			.set("Authorization", `Bearer ${token}`)
+			.send({
+				decisions: [
+					{ resource: "document", action: "read" },
+					{ resource: "document", action: "write" },
+				],
+			});
+
+		expect(res.status).toBe(200);
+		expect(res.body.decisions.map((d: { decision: string }) => d.decision)).toEqual([
+			"allow",
+			"deny",
+		]);
+		expect(res.body.decisions[0].subject).toBe("user-1");
+	});
+
+	it("POST /verify with a differently-cased scope returns 403 (deny)", async () => {
+		const app = await createShippedApp();
+
+		// Scope values are case-sensitive opaque strings (RFC 6749 §3.3), so
+		// "read:DOCUMENT" must not satisfy the required "read:document".
+		const token = await signToken({ scope: "read:DOCUMENT" });
+		const res = await request(app)
+			.post("/verify")
+			.set("Authorization", `Bearer ${token}`)
+			.send({ resource: "document", action: "read" });
+
+		expect(res.status).toBe(403);
+		expect(res.body.decision).toBe("deny");
+	});
+
+	it("POST /verify with a bare scope returns 403 unless the rewrite is opted into", async () => {
+		const app = await createShippedApp();
+
+		// A bare "document" is not rewritten to "read:document" by default.
+		const token = await signToken({ scope: "document" });
+		const res = await request(app)
+			.post("/verify")
+			.set("Authorization", `Bearer ${token}`)
+			.send({ resource: "document", action: "read" });
+
+		expect(res.status).toBe(403);
+		expect(res.body.decision).toBe("deny");
+	});
+
+	it("POST /verify allows a bare scope once allowBareScopeRewrite is configured", async () => {
+		// The one config in this file that is deliberately NOT the shipped one:
+		// it exercises the opt-in application.conf documents in a comment beside
+		// the collector, which is the only path a deployment has to re-enable the
+		// old rewrite. It is derived from the shipped config rather than written
+		// out, so the single key under test is the single thing that differs.
+		const rewritingConfig: AppConfig = {
+			...shippedConfig,
+			rule: {
+				...shippedConfig.rule,
+				collectors: [
+					{ collector: "ResourceActionScopeRuleCollector", allowBareScopeRewrite: true },
+				],
+			},
+		};
+		const app = await createShippedApp(rewritingConfig);
+
+		const token = await signToken({ scope: "document" });
+		const res = await request(app)
+			.post("/verify")
+			.set("Authorization", `Bearer ${token}`)
+			.send({ resource: "document", action: "read" });
+
+		expect(res.status).toBe(200);
+		expect(res.body.decision).toBe("allow");
+	});
+
 	it("POST /verify with insufficient scope returns 403 (deny)", async () => {
-		const app = await createApp({
-			pathResolver: (s: string) => s,
-			config: baseConfig,
-			modules: [builtinCollectorsModule, builtinKeyResolversModule],
-		});
+		const app = await createShippedApp();
 
 		// Token has "write:document" but action is "read", so HasScope("read:document") fails.
 		const token = await signToken({ scope: "write:document" });
@@ -101,3 +252,58 @@ describe("standalone smoke", () => {
 		expect(res.body.decision).toBe("deny");
 	});
 });
+
+/*
+ * #111. The template is the deployable shape, so these assert what an operator
+ * of *this* composition actually gets — not what the library can be wired to do.
+ */
+describe("standalone observability", () => {
+	it("GET /metrics serves the Prometheus text format with the decision counters", async () => {
+		const app = await createShippedApp();
+
+		const token = await signToken({ sub: "user-1", scope: "read:document" });
+		await request(app)
+			.post("/verify")
+			.set("Authorization", `Bearer ${token}`)
+			.send({ resource: "document", action: "read" });
+
+		const res = await request(app).get("/metrics");
+		expect(res.status).toBe(200);
+		expect(res.headers["content-type"]).toContain("text/plain");
+		expect(res.text).toContain('auth_decisions_total{decision="allow"} 1');
+		expect(res.text).toContain("auth_policy_verifier_process_cpu_user_seconds_total");
+	});
+
+	it("emits the per-decision audit line through the injected logger", async () => {
+		// main.mts injects pino here; a capturing stand-in proves the line reaches
+		// whatever the composition root wired, at the level `logging.level` gates.
+		const lines: Array<{ obj: Record<string, unknown>; msg?: string }> = [];
+		const app = await createApp({
+			pathResolver: (s: string) => s,
+			config: shippedConfig,
+			modules: [builtinCollectorsModule, builtinKeyResolversModule],
+			logger: {
+				...consoleLogger,
+				info(obj: Record<string, unknown> | string, msg?: string) {
+					if (typeof obj === "object") lines.push({ obj, msg });
+				},
+			},
+		});
+
+		const token = await signToken({ sub: "user-1", scope: "read:document" });
+		await request(app)
+			.post("/verify")
+			.set("Authorization", `Bearer ${token}`)
+			.set("x-request-id", "trace-1")
+			.send({ resource: "document:9", action: "read" });
+
+		const decision = lines.find((l) => l.msg === "decision");
+		expect(decision?.obj).toMatchObject({
+			sub: "user-1",
+			resource: "document:9",
+			action: "read",
+			decision: "allow",
+			requestId: "trace-1",
+		});
+	});
+});

package/templates/standalone/src/configPath.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+import path from "node:path";
+
+export interface ResolvedConfigPaths {
+	readonly applicationConfPath: string;
+	readonly envConfPath: string;
+}
+
+export function resolveConfigPaths(configDirPath: string, env: string): ResolvedConfigPaths {
+	const normalizedConfigDir = path.resolve(configDirPath);
+	const applicationConfPath = path.join(normalizedConfigDir, "application.conf");
+	const envConfPath = path.resolve(normalizedConfigDir, `${env}.conf`);
+	if (path.dirname(envConfPath) !== normalizedConfigDir) {
+		throw new Error(
+			`Invalid config environment name: "${env}" resolves outside ${normalizedConfigDir}`,
+		);
+	}
+	return { applicationConfPath, envConfPath };
+}

package/templates/standalone/src/loadConfig.ts

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+import { type AppConfig, AppConfigSchema } from "@o3co/auth.policy-verifier.server";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import { resolveConfigPaths } from "./configPath.js";
+
+/**
+ * Loads the validated application config for `env` from `configDirPath`.
+ *
+ * The `<env>.conf` overlay is layered over `application.conf`. An overlay that
+ * declares nothing (the shipped development/production files are comments
+ * only) is an empty HOCON document and falls through to the base layer.
+ */
+export function loadAppConfig(configDirPath: string, env: string): AppConfig {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDirPath, env);
+	return validate(
+		parseFile(envConfPath).withFallback(parseFile(applicationConfPath)),
+		AppConfigSchema,
+	);
+}

package/templates/standalone/src/logger.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AppConfig } from "@o3co/auth.policy-verifier.server";
+import { pino, stdSerializers } from "pino";
+
+/**
+ * The composition root's logger, injected into `createApp` so the verify
+ * router's failure events (`jwt_token_rejected`, `jwt_verification_unavailable`,
+ * `verify_internal_error`) reach an aggregator-ready sink (#107).
+ *
+ * pino, emitting newline-delimited JSON on stdout — the shape every log
+ * aggregator ingests without a parser, and the reason the `Logger` port carries
+ * pino's two-overload call signature. A pino instance therefore satisfies the
+ * port structurally, with no adapter. pino drops sub-threshold calls before
+ * formatting, so `logging.level` is honoured at zero cost for the levels it
+ * excludes.
+ *
+ * The same wiring exists in the auth.provider standalone template; keeping the
+ * two composition roots symmetric is what lets one aggregator pipeline serve
+ * the whole stack.
+ */
+export function createAppLogger(config: AppConfig) {
+	return pino({
+		name: "policy-verifier",
+		level: config.logging.level,
+		// `err` is pino's conventional key for an Error, and every structured
+		// event in this stack uses it — `logger.error({ err }, "…_error")`.
+		// Without the serialiser an Error stringifies to `{}` and the stack is
+		// lost exactly where it is needed.
+		serializers: { err: stdSerializers.err },
+	});
+}

package/templates/standalone/src/main.mts

@@ -4,28 +4,25 @@
 /*
  * Standalone entrypoint — creates and starts the policy-verifier server.
  */
-import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { builtinCollectorsModule } from "@o3co/auth.policy-verifier.builtins";
-import {
-	AppConfigSchema,
-	builtinKeyResolversModule,
-	createApp,
-} from "@o3co/auth.policy-verifier.server";
-import { createLogger, gracefulShutdown } from "@o3co/auth.utils";
-import { parseFile } from "@o3co/ts.hocon";
-import { validate } from "@o3co/ts.hocon/zod";
+import { builtinKeyResolversModule, createApp } from "@o3co/auth.policy-verifier.server";
+import { gracefulShutdown } from "@o3co/auth.utils";
+import { loadAppConfig } from "./loadConfig.js";
+import { createAppLogger } from "./logger.js";
 
-const logger = createLogger("policy-verifier");
+const env = process.env.CONFIG_ENV || process.env.NODE_ENV || "development";
+const configDir = new URL("../config/", import.meta.url);
+const configDirPath = fileURLToPath(configDir);
 
-const config = validate(
-	parseFile(resolve(import.meta.dirname, "../config/application.conf")),
-	AppConfigSchema,
-);
+const config = loadAppConfig(configDirPath, env);
+const logger = createAppLogger(config);
 
 const app = await createApp({
 	pathResolver: import.meta.resolve,
 	config,
 	modules: [builtinCollectorsModule, builtinKeyResolversModule],
+	logger,
 });
 
 const server = app.listen(config.http.port, config.http.hostname, () => {

package/templates/standalone/tsconfig.json

@@ -22,6 +22,7 @@
 	],
 	"exclude": [
 		"node_modules",
-		"dist"
+		"dist",
+		"src/**/__tests__/**"
 	]
 }

package/templates/standalone/tsconfig.typecheck.json

@@ -0,0 +1,8 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

package/templates/versions.json

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

package/dist/__tests__/index.test.d.mts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=index.test.d.mts.map

package/dist/__tests__/index.test.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.test.d.mts","sourceRoot":"","sources":["../../src/__tests__/index.test.mts"],"names":[],"mappings":""}