@decohere/http 0.0.1-dev.126 → 0.0.1-dev.5

package/tests/auth.oidc.integration.spec.ts

@@ -0,0 +1,161 @@
+import axios from "axios";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { App } from "../src/app/app.js";
+import { AuthConfig } from "../src/auth/auth.config.js";
+import "../src/auth/auth.extensions.js";
+import { Builder } from "../src/builder/builder.js";
+import "../src/http/http.extensions.js";
+import type { IConfigurationService } from "@decohere/core/configuration";
+import { ConfigurationServiceToken } from "@decohere/core/configuration";
+import type { Constructable } from "@decohere/core/reflection";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+import { Authorize, Controller, Get } from "../src/routing/index.js";
+import { listenEphemeral } from "./helpers/listen-ephemeral.js";
+import { LocalOidcServer } from "./helpers/local-oidc-server.js";
+
+// Started once for the whole suite — key generation is expensive.
+let oidc: LocalOidcServer;
+
+beforeAll(async () => {
+	oidc = await LocalOidcServer.start();
+});
+
+afterAll(async () => {
+	await oidc.stop();
+});
+
+// Configures the app to use discoveryUrl pointing at the local OIDC server.
+class OidcConfigService implements IConfigurationService {
+	public get dataSources() {
+		return [];
+	}
+	public async get<T extends object>(type: Constructable<T> | string): Promise<T> {
+		if (type === AuthConfig) {
+			const config = new AuthConfig();
+			config.discoveryUrl = oidc.issuer;
+			config.audience = "https://api.test";
+			return config as unknown as T;
+		}
+		return {} as T;
+	}
+}
+
+@Authorize("read", "Article")
+@Controller()
+class OidcController {
+	@Get("/resource")
+	public resource() {
+		return { ok: true };
+	}
+}
+
+describe("Auth integration — discoveryUrl + real RS256 tokens", () => {
+	let app: App;
+
+	beforeEach(async () => {
+		app = await Builder.create()
+			.withHttpProvider(FastifyProvider)
+			.withServices((c) => {
+				c.registerSingleton(ConfigurationServiceToken, new OidcConfigService());
+			})
+			.withAuth()
+			.withControllers(OidcController)
+			.build();
+
+		axios.defaults.baseURL = await listenEphemeral(app);
+	});
+
+	afterEach(async () => {
+		await app.dispose();
+	});
+
+	it("returns 401 when no token is provided", async () => {
+		await expect(axios.get("/oidc/resource")).rejects.toMatchObject({
+			response: { status: 401 },
+		});
+	});
+
+	it("accepts a valid RS256 token issued by the local IdP", async () => {
+		const token = await oidc.signToken({ sub: "user-1", scope: "read:Article" });
+		const res = await axios.get("/oidc/resource", {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		expect(res.status).toBe(200);
+	});
+
+	it("returns 401 for a token signed with the wrong key", async () => {
+		// Use the wrong OIDC server (different key pair)
+		const wrongOidc = await LocalOidcServer.start();
+		const token = await wrongOidc.signToken({ sub: "user-1", scope: "read:Article" });
+		await wrongOidc.stop();
+
+		await expect(
+			axios.get("/oidc/resource", { headers: { Authorization: `Bearer ${token}` } }),
+		).rejects.toMatchObject({ response: { status: 401 } });
+	});
+
+	it("returns 401 for an expired token", async () => {
+		const token = await oidc.signToken({ sub: "user-1", scope: "read:Article" }, "-1s");
+		await expect(
+			axios.get("/oidc/resource", { headers: { Authorization: `Bearer ${token}` } }),
+		).rejects.toMatchObject({ response: { status: 401 } });
+	});
+
+	it("returns 403 when the token lacks the required scope", async () => {
+		const token = await oidc.signToken({ sub: "user-1", scope: "write:Article" });
+		await expect(
+			axios.get("/oidc/resource", { headers: { Authorization: `Bearer ${token}` } }),
+		).rejects.toMatchObject({ response: { status: 403 } });
+	});
+});
+
+describe("Auth integration — principalMapper", () => {
+	let app: App;
+
+	beforeEach(async () => {
+		// Map Keycloak-style realm_access.roles to scopes
+		app = await Builder.create()
+			.withHttpProvider(FastifyProvider)
+			.withServices((c) => {
+				c.registerSingleton(ConfigurationServiceToken, new OidcConfigService());
+			})
+			.withAuth(undefined, {
+				principalMapper: (payload) => ({
+					sub: payload.sub as string,
+					scopes: ((payload.realm_access as { roles?: string[] })?.roles ?? []).map(
+						(r) => `read:${r}`,
+					),
+				}),
+			})
+			.withControllers(OidcController)
+			.build();
+
+		axios.defaults.baseURL = await listenEphemeral(app);
+	});
+
+	afterEach(async () => {
+		await app.dispose();
+	});
+
+	it("maps custom claims to scopes via principalMapper", async () => {
+		// Token uses realm_access.roles instead of scope claim
+		const token = await oidc.signToken({
+			sub: "user-1",
+			realm_access: { roles: ["Article"] },
+		});
+		const res = await axios.get("/oidc/resource", {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		expect(res.status).toBe(200);
+	});
+
+	it("returns 403 when custom-mapped scopes do not satisfy the requirement", async () => {
+		const token = await oidc.signToken({
+			sub: "user-1",
+			realm_access: { roles: ["OtherResource"] },
+		});
+		await expect(
+			axios.get("/oidc/resource", { headers: { Authorization: `Bearer ${token}` } }),
+		).rejects.toMatchObject({ response: { status: 403 } });
+	});
+});

package/tests/auth.token-service.spec.ts

@@ -0,0 +1,251 @@
+import { exportJWK, exportSPKI, generateKeyPair, SignJWT } from "jose";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TokenService } from "../src/auth/token-service.js";
+import { UnauthorizedError } from "../src/routing/anvil.types.js";
+
+async function mintToken(
+	privateKey: Parameters<typeof SignJWT.prototype.sign>[0],
+	payload: Record<string, unknown> = {},
+	options: { exp?: string; iss?: string; aud?: string; alg?: string } = {},
+) {
+	return new SignJWT(payload)
+		.setProtectedHeader({ alg: options.alg ?? "RS256" })
+		.setIssuedAt()
+		.setSubject((payload.sub as string) ?? "user-1")
+		.setIssuer(options.iss ?? "test-issuer")
+		.setAudience(options.aud ?? "test-audience")
+		.setExpirationTime(options.exp ?? "5m")
+		.sign(privateKey);
+}
+
+describe("TokenService", () => {
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+	describe("RS256 with public key (PEM)", () => {
+		it("verifies a valid token and returns the principal", async () => {
+			const { publicKey, privateKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				algorithms: ["RS256"],
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+
+			const token = await mintToken(privateKey, { roles: ["admin"] });
+			const principal = await service.verify(token);
+
+			expect(principal.sub).toBe("user-1");
+			expect(principal.roles).toContain("admin");
+		});
+
+		it("throws UnauthorizedError for an expired token", async () => {
+			const { publicKey, privateKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+
+			const token = await mintToken(privateKey, {}, { exp: "1s" });
+			// Wait for token to expire (jose v6 has 1-second resolution)
+			await new Promise((r) => setTimeout(r, 1100));
+
+			await expect(service.verify(token)).rejects.toThrow(UnauthorizedError);
+		});
+
+		it("throws UnauthorizedError for wrong issuer", async () => {
+			const { publicKey, privateKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "expected-issuer",
+				audience: "test-audience",
+			});
+
+			const token = await mintToken(privateKey, {}, { iss: "wrong-issuer" });
+			await expect(service.verify(token)).rejects.toThrow(UnauthorizedError);
+		});
+
+		it("throws UnauthorizedError for wrong audience", async () => {
+			const { publicKey, privateKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "test-issuer",
+				audience: "expected-audience",
+			});
+
+			const token = await mintToken(privateKey, {}, { aud: "wrong-audience" });
+			await expect(service.verify(token)).rejects.toThrow(UnauthorizedError);
+		});
+
+		it("does not accept a foreign-audience token when configured audience is empty", async () => {
+			const { publicKey, privateKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			// Empty audience must fail closed — jose skips `aud` checks when audience is ""/undefined.
+			expect(
+				() =>
+					new TokenService({
+						publicKey: pem,
+						issuer: "test-issuer",
+						audience: "",
+					}),
+			).toThrow(/audience must be a non-empty string/);
+
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "test-issuer",
+				audience: "https://api.webapi",
+			});
+			const token = await mintToken(
+				privateKey,
+				{ scope: "create:Hello" },
+				{ aud: "https://api.other" },
+			);
+			await expect(service.verify(token)).rejects.toThrow(UnauthorizedError);
+		});
+
+		it("throws UnauthorizedError when signed with a different key", async () => {
+			const { publicKey } = await generateKeyPair("RS256");
+			const { privateKey: otherPrivate } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+
+			const token = await mintToken(otherPrivate, {}, {});
+			await expect(service.verify(token)).rejects.toThrow(UnauthorizedError);
+		});
+
+		it("throws UnauthorizedError for a malformed token string", async () => {
+			const { publicKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+
+			await expect(service.verify("not.a.jwt")).rejects.toThrow(UnauthorizedError);
+		});
+	});
+
+	describe("RS256 with public key (JWK JSON)", () => {
+		it("verifies a valid token using a JWK public key", async () => {
+			const { publicKey, privateKey } = await generateKeyPair("RS256");
+			const jwkObj = await exportJWK(publicKey);
+			// JWK must include alg for importJWK without explicit algorithm arg
+			jwkObj.alg = "RS256";
+			const jwk = JSON.stringify(jwkObj);
+			const service = new TokenService({
+				publicKey: jwk,
+				algorithms: ["RS256"],
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+
+			const token = await mintToken(privateKey);
+			const principal = await service.verify(token);
+			expect(principal.sub).toBe("user-1");
+		});
+	});
+
+	describe("HS256 with shared secret", () => {
+		const secret = "super-secret-key-that-is-long-enough-for-hs256";
+
+		it("verifies a HS256 token signed with the same secret", async () => {
+			const service = new TokenService({
+				secret,
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+			const token = await service.sign({ sub: "alice", roles: ["reader"] });
+			const principal = await service.verify(token);
+
+			expect(principal.sub).toBe("alice");
+			expect(principal.roles).toContain("reader");
+		});
+
+		it("throws UnauthorizedError when secret does not match", async () => {
+			const signer = new TokenService({ secret, issuer: "x", audience: "y" });
+			const verifier = new TokenService({
+				secret: "different-secret-at-least-32-chars-long",
+				issuer: "x",
+				audience: "y",
+			});
+
+			const token = await signer.sign({ sub: "bob" });
+			await expect(verifier.verify(token)).rejects.toThrow(UnauthorizedError);
+		});
+
+		it("sign() throws when not using SecretConfig", async () => {
+			const { publicKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+
+			await expect(service.sign({ sub: "x" })).rejects.toThrow("SecretConfig");
+		});
+	});
+
+	describe("devStatic mode", () => {
+		it("returns the static principal for any token in development", async () => {
+			vi.stubEnv("NODE_ENV", "development");
+			const service = new TokenService({
+				devStatic: { sub: "dev-user", roles: ["admin"] },
+			});
+
+			const principal = await service.verify("any-token-at-all");
+			expect(principal.sub).toBe("dev-user");
+			expect(principal.roles).toContain("admin");
+		});
+
+		it("rejects constructing TokenService with devStatic when NODE_ENV is production", () => {
+			vi.stubEnv("NODE_ENV", "production");
+			expect(
+				() =>
+					new TokenService({
+						devStatic: { sub: "dev-user", roles: ["admin"] },
+					}),
+			).toThrow(/devStatic.*NODE_ENV/);
+		});
+	});
+
+	describe("scope claim parsing", () => {
+		it("splits a space-separated scope string into scopes array", async () => {
+			const { publicKey, privateKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+
+			const token = await mintToken(privateKey, { scope: "read write" });
+			const principal = await service.verify(token);
+			expect(principal.scopes).toEqual(["read", "write"]);
+		});
+
+		it("uses a scopes array claim directly", async () => {
+			const { publicKey, privateKey } = await generateKeyPair("RS256");
+			const pem = await exportSPKI(publicKey);
+			const service = new TokenService({
+				publicKey: pem,
+				issuer: "test-issuer",
+				audience: "test-audience",
+			});
+
+			const token = await mintToken(privateKey, { scopes: ["read", "admin"] });
+			const principal = await service.verify(token);
+			expect(principal.scopes).toEqual(["read", "admin"]);
+		});
+	});
+});

package/tests/builder.spec.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { App } from "../src/app/app.js";
+import { Builder } from "../src/builder/builder.js";
+
+describe("Builder", () => {
+	it("builds a custom App subclass when provided", async () => {
+		class CustomApp extends App {}
+
+		const app = await Builder.create().build(CustomApp);
+		expect(app).toBeInstanceOf(CustomApp);
+	});
+});

package/tests/health.integration.spec.ts

@@ -0,0 +1,111 @@
+import axios from "axios";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { App } from "../src/app/app.js";
+import { AuthConfig } from "../src/auth/auth.config.js";
+import "../src/auth/auth.extensions.js";
+import { Builder } from "../src/builder/builder.js";
+import type { IReadinessCheck } from "../src/health/readiness.types.js";
+import "../src/http/http.extensions.js";
+import "../src/health/health.extensions.js";
+import type { IConfigurationService } from "@decohere/core/configuration";
+import { ConfigurationServiceToken } from "@decohere/core/configuration";
+import type { Constructable } from "@decohere/core/reflection";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+import { Authorize, Controller, Get } from "../src/routing/index.js";
+import { listenEphemeral } from "./helpers/listen-ephemeral.js";
+
+class DevStaticConfigService implements IConfigurationService {
+	public get dataSources() {
+		return [];
+	}
+	public async get<T extends object>(type: Constructable<T> | string): Promise<T> {
+		if (type === AuthConfig) {
+			const config = new AuthConfig();
+			config.devStatic = { sub: "dev-user", scopes: ["read:Article"] };
+			return config as unknown as T;
+		}
+		return {} as T;
+	}
+}
+
+@Controller()
+class GuardController {
+	@Authorize("read", "Article")
+	@Get("/protected")
+	public secure() {
+		return { ok: true };
+	}
+}
+
+describe("health / ready probes", () => {
+	let app: App;
+
+	afterEach(async () => {
+		await app?.dispose();
+		vi.unstubAllEnvs();
+	});
+
+	it("GET /health returns 200 { status: ok } without auth", async () => {
+		app = await Builder.create().withHttpProvider(FastifyProvider).withHealth().build();
+		axios.defaults.baseURL = await listenEphemeral(app);
+
+		const res = await axios.get("/health");
+		expect(res.status).toBe(200);
+		expect(res.data).toEqual({ status: "ok" });
+	});
+
+	it("GET /ready returns 200 when no readiness checks are registered", async () => {
+		app = await Builder.create().withHttpProvider(FastifyProvider).withHealth().build();
+		axios.defaults.baseURL = await listenEphemeral(app);
+
+		const res = await axios.get("/ready");
+		expect(res.status).toBe(200);
+		expect(res.data).toEqual({ status: "ok" });
+	});
+
+	it("GET /ready returns 503 when a readiness check fails", async () => {
+		const failing: IReadinessCheck = {
+			name: "db",
+			async check() {
+				throw new Error("connection refused");
+			},
+		};
+
+		app = await Builder.create()
+			.withHttpProvider(FastifyProvider)
+			.withHealth({ checks: [failing] })
+			.build();
+		axios.defaults.baseURL = await listenEphemeral(app);
+
+		const res = await axios.get("/ready", { validateStatus: () => true });
+		expect(res.status).toBe(503);
+		expect(res.data).toEqual({ message: "Not ready" });
+	});
+
+	it("GET /health and /ready stay anonymous when withAuth is enabled", async () => {
+		vi.stubEnv("NODE_ENV", "development");
+
+		app = await Builder.create()
+			.withHttpProvider(FastifyProvider)
+			.withServices((c) => {
+				c.registerSingleton(ConfigurationServiceToken, new DevStaticConfigService());
+			})
+			.withAuth()
+			.withHealth()
+			.withControllers(GuardController)
+			.build();
+		axios.defaults.baseURL = await listenEphemeral(app);
+
+		const health = await axios.get("/health");
+		expect(health.status).toBe(200);
+		expect(health.data).toEqual({ status: "ok" });
+
+		const ready = await axios.get("/ready");
+		expect(ready.status).toBe(200);
+		expect(ready.data).toEqual({ status: "ok" });
+
+		await expect(axios.get("/guard/protected")).rejects.toMatchObject({
+			response: { status: 401 },
+		});
+	});
+});

package/tests/helpers/listen-ephemeral.ts

@@ -0,0 +1,13 @@
+import type { App } from "../../src/app/app.js";
+
+/**
+ * Bind an OS-assigned port (`listen(0)`) on loopback and return the advertised origin.
+ */
+export async function listenEphemeral(app: App): Promise<string> {
+	await app.start({ port: 0, host: "127.0.0.1" });
+	const address = app.addresses[0];
+	if (address == null) {
+		throw new Error("app.start({ port: 0 }) advertised no IPv4 address");
+	}
+	return address;
+}

package/tests/helpers/local-oidc-server.ts

@@ -0,0 +1,100 @@
+/**
+ * Minimal in-process OIDC server for integration testing.
+ *
+ * Uses the `jose` library (already an `@decohere/http` dependency) to generate a real
+ * RS256 key pair and serve standard OIDC discovery + JWKS endpoints via a
+ * Node.js HTTP server bound to a random port.
+ *
+ * No external dependencies, no Docker, works in CI.
+ *
+ * Usage:
+ * ```ts
+ * const oidc = await LocalOidcServer.start();
+ * // configure `@decohere/http` with: discoveryUrl: oidc.issuer
+ * const token = await oidc.signToken({ sub: "user-1", scope: "read:Article" });
+ * await oidc.stop();
+ * ```
+ */
+
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { CryptoKey } from "jose";
+import { exportJWK, generateKeyPair, SignJWT } from "jose";
+
+export class LocalOidcServer {
+	private constructor(
+		private readonly server: Server,
+		private readonly privateKey: CryptoKey,
+		private readonly port: number,
+	) {}
+
+	public static async start(): Promise<LocalOidcServer> {
+		const { privateKey, publicKey } = await generateKeyPair("RS256");
+		const publicJwk = {
+			...(await exportJWK(publicKey)),
+			use: "sig",
+			alg: "RS256",
+			kid: "test-key-1",
+		};
+
+		const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+			const issuer = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+
+			if (req.url === "/.well-known/openid-configuration") {
+				res.writeHead(200, { "Content-Type": "application/json" });
+				res.end(
+					JSON.stringify({
+						issuer,
+						jwks_uri: `${issuer}/jwks`,
+						authorization_endpoint: `${issuer}/auth`,
+						token_endpoint: `${issuer}/token`,
+						response_types_supported: ["code"],
+						subject_types_supported: ["public"],
+						id_token_signing_alg_values_supported: ["RS256"],
+					}),
+				);
+				return;
+			}
+
+			if (req.url === "/jwks") {
+				res.writeHead(200, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ keys: [publicJwk] }));
+				return;
+			}
+
+			res.writeHead(404);
+			res.end();
+		});
+
+		await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+		const port = (server.address() as AddressInfo).port;
+
+		return new LocalOidcServer(server, privateKey, port);
+	}
+
+	public get issuer(): string {
+		return `http://127.0.0.1:${this.port}`;
+	}
+
+	public async signToken(
+		claims: Record<string, unknown> & { aud?: string },
+		expiresIn = "1h",
+	): Promise<string> {
+		const { aud, ...rest } = claims;
+		let builder = new SignJWT(rest)
+			.setProtectedHeader({ alg: "RS256", kid: "test-key-1" })
+			.setIssuedAt()
+			.setIssuer(this.issuer)
+			.setExpirationTime(expiresIn);
+		// Default audience so tests match AuthConfig.audience (required by TokenService).
+		builder = builder.setAudience(typeof aud === "string" ? aud : "https://api.test");
+		return builder.sign(this.privateKey);
+	}
+
+	public stop(): Promise<void> {
+		return new Promise((resolve, reject) =>
+			this.server.close((err) => (err ? reject(err) : resolve())),
+		);
+	}
+}