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

package/src/auth/safe-outbound-url.ts

@@ -0,0 +1,117 @@
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+
+/**
+ * Validate URLs used for OIDC discovery / JWKS fetches to reduce SSRF risk.
+ *
+ * - http(s) only; https required except loopback (local IdP tests)
+ * - no credentials in the URL
+ * - hostname must not resolve to private, link-local, or metadata ranges
+ *   (loopback allowed only when NODE_ENV is development/dev/test)
+ */
+export async function assertSafeOutboundUrl(raw: string, label: string): Promise<URL> {
+	let url: URL;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw new Error(`Invalid ${label}: ${raw}`);
+	}
+
+	if (url.protocol !== "https:" && url.protocol !== "http:") {
+		throw new Error(`${label} must use http or https (got ${url.protocol})`);
+	}
+
+	if (url.username || url.password) {
+		throw new Error(`${label} must not include credentials`);
+	}
+
+	const hostname = url.hostname.replace(/^\[|\]$/g, "");
+	if (isBlockedHostname(hostname)) {
+		throw new Error(`${label} host is not allowed (${hostname})`);
+	}
+
+	const ips = await resolveIps(hostname);
+	const allowLoopback = isLoopbackAllowed();
+	for (const ip of ips) {
+		if (isBlockedIp(ip, allowLoopback)) {
+			throw new Error(`${label} resolves to a blocked address (${ip})`);
+		}
+	}
+
+	if (url.protocol === "http:") {
+		const loopbackOnly =
+			isLoopbackHostname(hostname) || (ips.length > 0 && ips.every((ip) => isLoopbackIp(ip)));
+		if (!loopbackOnly || !allowLoopback) {
+			throw new Error(`${label} must use https unless targeting loopback in development/test`);
+		}
+	}
+
+	return url;
+}
+
+function isLoopbackAllowed(): boolean {
+	const env = process.env.NODE_ENV ?? "";
+	return env === "development" || env === "dev" || env === "test";
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+
+function isBlockedHostname(hostname: string): boolean {
+	const lower = hostname.toLowerCase();
+	return (
+		lower === "metadata.google.internal" ||
+		lower === "metadata" ||
+		lower.endsWith(".metadata.google.internal")
+	);
+}
+
+async function resolveIps(hostname: string): Promise<string[]> {
+	if (isIP(hostname)) {
+		return [hostname];
+	}
+	const results = await lookup(hostname, { all: true, verbatim: true });
+	return results.map((r) => r.address);
+}
+
+function isLoopbackIp(ip: string): boolean {
+	const list = new BlockList();
+	list.addSubnet("127.0.0.0", 8, "ipv4");
+	list.addAddress("::1", "ipv6");
+	list.addSubnet("::ffff:127.0.0.0", 104, "ipv6");
+	return list.check(ip);
+}
+
+function isBlockedIp(ip: string, allowLoopback: boolean): boolean {
+	if (allowLoopback && isLoopbackIp(ip)) {
+		return false;
+	}
+
+	const list = new BlockList();
+	// IPv4 special-use / private
+	list.addSubnet("0.0.0.0", 8, "ipv4");
+	list.addSubnet("10.0.0.0", 8, "ipv4");
+	list.addSubnet("100.64.0.0", 10, "ipv4"); // shared address space
+	list.addSubnet("127.0.0.0", 8, "ipv4");
+	list.addSubnet("169.254.0.0", 16, "ipv4"); // link-local / cloud metadata
+	list.addSubnet("172.16.0.0", 12, "ipv4");
+	list.addSubnet("192.168.0.0", 16, "ipv4");
+	list.addSubnet("198.18.0.0", 15, "ipv4"); // benchmarking
+	// IPv6
+	list.addAddress("::1", "ipv6");
+	list.addSubnet("fc00::", 7, "ipv6"); // unique local
+	list.addSubnet("fe80::", 10, "ipv6"); // link-local
+
+	if (list.check(ip)) {
+		return true;
+	}
+
+	// Mapped IPv4 inside IPv6 (::ffff:a.b.c.d)
+	const mapped = ip.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+	if (mapped) {
+		return isBlockedIp(mapped[1], allowLoopback);
+	}
+
+	return false;
+}

package/src/auth/token-service.ts

@@ -0,0 +1,192 @@
+import {
+	createRemoteJWKSet,
+	importJWK,
+	importSPKI,
+	type JWTPayload,
+	type JWTVerifyGetKey,
+	jwtVerify,
+	SignJWT,
+} from "jose";
+import type { HttpRequest } from "../routing/anvil.types.js";
+import { UnauthorizedError } from "../routing/anvil.types.js";
+import { createPrincipalFromPayload } from "./ability.js";
+import type {
+	Principal,
+	PrincipalMapper,
+	PublicKeyConfig,
+	SecretConfig,
+	TokenServiceConfig,
+} from "./auth.types.js";
+import {
+	assertDevStaticAllowed,
+	assertNonEmptyAudience,
+	isDevStaticConfig,
+	isDiscoveryConfig,
+	isJwksConfig,
+	isPublicKeyConfig,
+	isSecretConfig,
+} from "./auth.types.js";
+import { assertSafeOutboundUrl } from "./safe-outbound-url.js";
+
+/** Key material + claim checks needed for a single jwtVerify call. */
+type VerificationContext = {
+	key: JWTVerifyGetKey | Awaited<ReturnType<typeof importJWK>> | Uint8Array;
+	issuer?: string;
+	audience?: string;
+};
+
+export class TokenService {
+	private readonly config: TokenServiceConfig;
+	private readonly principalMapper?: PrincipalMapper;
+	/** Lazily resolved JWKS set when using OIDC discovery. */
+	private discoveryJwks?: ReturnType<typeof createRemoteJWKSet>;
+	private discoveryIssuer?: string;
+	/** Remote key set for `jwksUrl` mode, created once so jose can cache the keys (#499). */
+	private configuredJwks?: ReturnType<typeof createRemoteJWKSet>;
+
+	public constructor(config: TokenServiceConfig, principalMapper?: PrincipalMapper) {
+		if (isDevStaticConfig(config)) {
+			assertDevStaticAllowed();
+		} else {
+			assertNonEmptyAudience(config.audience);
+		}
+		this.config = config;
+		this.principalMapper = principalMapper;
+	}
+
+	public async verifyRequest(request: HttpRequest): Promise<Principal> {
+		const authHeader = request.headers.authorization;
+		if (!authHeader) {
+			throw new UnauthorizedError("Missing Authorization header");
+		}
+		const spaceIdx = authHeader.indexOf(" ");
+		if (spaceIdx === -1) {
+			throw new UnauthorizedError("Malformed Authorization header");
+		}
+		const scheme = authHeader.slice(0, spaceIdx);
+		if (scheme !== "Bearer") {
+			throw new UnauthorizedError(`Unsupported authorization scheme: ${scheme}`);
+		}
+		const credentials = authHeader.slice(spaceIdx + 1);
+		return this.verify(credentials);
+	}
+
+	public async verify(credentials: string): Promise<Principal> {
+		if (isDevStaticConfig(this.config)) {
+			return this.config.devStatic;
+		}
+
+		try {
+			const { key, issuer, audience } = await this.resolveVerificationContext();
+			// jose's overloads don't accept Key | JWKS-getter as a union; runtime does.
+			const { payload } = await jwtVerify(credentials, key as never, { issuer, audience });
+			return this.mapPrincipal(payload);
+		} catch (err) {
+			throw new UnauthorizedError(
+				err instanceof Error ? err.message : "Token verification failed",
+			);
+		}
+	}
+
+	/**
+	 * Resolve how to verify tokens for the configured strategy:
+	 * - OIDC discovery → fetch JWKS + issuer from `/.well-known/openid-configuration`
+	 * - explicit JWKS URL → remote key set + configured issuer/audience
+	 * - public key / shared secret → static key material + configured issuer/audience
+	 */
+	private async resolveVerificationContext(): Promise<VerificationContext> {
+		if (isDiscoveryConfig(this.config)) {
+			const { jwks, issuer } = await this.resolveOidcDiscovery();
+			return { key: jwks, issuer, audience: this.config.audience };
+		}
+		if (isJwksConfig(this.config)) {
+			this.configuredJwks ??= createRemoteJWKSet(
+				await assertSafeOutboundUrl(this.config.jwksUrl, "jwksUrl"),
+			);
+			return {
+				key: this.configuredJwks,
+				issuer: this.config.issuer,
+				audience: this.config.audience,
+			};
+		}
+		return {
+			key: await this.getStaticKey(),
+			issuer: (this.config as PublicKeyConfig | SecretConfig).issuer,
+			audience: (this.config as PublicKeyConfig | SecretConfig).audience,
+		};
+	}
+
+	private async resolveOidcDiscovery(): Promise<{
+		jwks: ReturnType<typeof createRemoteJWKSet>;
+		issuer: string;
+	}> {
+		if (this.discoveryJwks && this.discoveryIssuer) {
+			return { jwks: this.discoveryJwks, issuer: this.discoveryIssuer };
+		}
+		const { discoveryUrl } = this.config as import("./auth.types.js").DiscoveryConfig;
+		await assertSafeOutboundUrl(discoveryUrl, "discoveryUrl");
+		const resp = await fetch(
+			`${discoveryUrl.replace(/\/$/, "")}/.well-known/openid-configuration`,
+			{
+				redirect: "error",
+			},
+		);
+		if (!resp.ok) {
+			throw new Error(`OIDC discovery failed for ${discoveryUrl}: HTTP ${resp.status}`);
+		}
+		const doc = (await resp.json()) as { issuer: string; jwks_uri: string };
+		if (typeof doc.jwks_uri !== "string" || doc.jwks_uri.length === 0) {
+			throw new Error(`OIDC discovery for ${discoveryUrl} did not return jwks_uri`);
+		}
+		const jwksUrl = await assertSafeOutboundUrl(doc.jwks_uri, "jwks_uri");
+		this.discoveryIssuer = doc.issuer;
+		this.discoveryJwks = createRemoteJWKSet(jwksUrl);
+		return { jwks: this.discoveryJwks, issuer: this.discoveryIssuer };
+	}
+
+	/**
+	 * Sign a payload and return a JWT string.
+	 * Only available when configured with a SecretConfig (HS256).
+	 * For RS256/ES256 issuance, the caller is responsible for key management.
+	 */
+	public async sign(
+		payload: Omit<JWTPayload, "iss" | "aud"> & Record<string, unknown>,
+		expiresIn = "1h",
+	): Promise<string> {
+		if (!isSecretConfig(this.config)) {
+			throw new Error("TokenService.sign() requires SecretConfig (shared secret / HS256)");
+		}
+		const key = new TextEncoder().encode(this.config.secret);
+		return new SignJWT(payload)
+			.setProtectedHeader({ alg: "HS256" })
+			.setIssuedAt()
+			.setIssuer(this.config.issuer ?? "")
+			.setAudience(this.config.audience ?? "")
+			.setExpirationTime(expiresIn)
+			.sign(key);
+	}
+
+	private async getStaticKey(): Promise<Awaited<ReturnType<typeof importJWK>> | Uint8Array> {
+		if (isPublicKeyConfig(this.config)) {
+			const cfg = this.config as PublicKeyConfig;
+			const trimmed = cfg.publicKey.trim();
+			if (trimmed.startsWith("{")) {
+				const jwk = JSON.parse(trimmed) as Parameters<typeof importJWK>[0];
+				return importJWK(jwk);
+			}
+			return importSPKI(trimmed, cfg.algorithms?.[0] ?? "RS256");
+		}
+
+		if (isSecretConfig(this.config)) {
+			const enc = new TextEncoder().encode((this.config as SecretConfig).secret);
+			return enc;
+		}
+
+		throw new Error("Invalid TokenService configuration");
+	}
+
+	private mapPrincipal(payload: JWTPayload): Principal {
+		if (this.principalMapper) return this.principalMapper(payload as Record<string, unknown>);
+		return createPrincipalFromPayload(payload as Record<string, unknown>);
+	}
+}

package/src/builder/builder.ts

@@ -0,0 +1,118 @@
+import { type ContainerBuilder, ServiceContainerBuilder, type IContainer } from "@decohere/di";
+import {
+	ConfigurationServiceToken,
+	type IConfigurationService,
+} from "@decohere/core/configuration";
+import type { Constructable } from "@decohere/core/reflection";
+import { type Logger, scribe } from "@decohere/scribe";
+import { App } from "../app/app.js";
+import { HostedServiceHostToken } from "../const.js";
+import type { HostedService } from "../hosting/hosted-service.js";
+import { HostedServiceHost } from "../hosting/hosted-service-host.js";
+
+export type BuilderOptions = {
+	containerBuilder?: ServiceContainerBuilder;
+	applicationName?: string;
+};
+
+export class Builder<T extends App = App> {
+	public static create<T extends App = App>(options?: BuilderOptions) {
+		return new Builder<T>(options);
+	}
+
+	public readonly containerBuilder: ServiceContainerBuilder;
+	public readonly applicationName?: string;
+	private readonly logger: Logger = scribe.logger("name");
+	private userServices: ((containerBuilder: ContainerBuilder) => void)[] = [];
+	private preBuildSteps: ((
+		config: IConfigurationService,
+		containerBuilder: ContainerBuilder,
+	) => Promise<void> | void)[] = [];
+	private postBuildSteps: ((container: IContainer) => Promise<void> | void)[] = [];
+	private readonly hostedServices = new HostedServiceHost();
+
+	public constructor(options?: BuilderOptions) {
+		this.containerBuilder = options?.containerBuilder ?? new ServiceContainerBuilder();
+		this.applicationName = options?.applicationName;
+	}
+
+	public withServices(userServices: (containerBuilder: ContainerBuilder) => void): Builder<T> {
+		this.userServices.push(userServices);
+		return this;
+	}
+
+	/**
+	 * Run {@link HostedService}s for the life of the app: started in this order before the HTTP
+	 * server listens, stopped in reverse when the app stops (including SIGTERM and Flux reboots).
+	 * Each is registered as a singleton, so other services can inject it by its class.
+	 */
+	public withHostedService(...types: Constructable<HostedService>[]): Builder<T> {
+		for (const type of types) this.containerBuilder.registerSingleton(type);
+		this.hostedServices.add(...types);
+		return this;
+	}
+
+	public registerPreBuildStep(
+		step: (
+			config: IConfigurationService,
+			containerBuilder: ContainerBuilder,
+		) => Promise<void> | void,
+	) {
+		this.preBuildSteps.push(step);
+	}
+
+	public registerPostBuildStep(step: (container: IContainer) => Promise<void> | void) {
+		this.postBuildSteps.push(step);
+	}
+
+	public async buildAndStart<T extends App>(type?: Constructable<T>): Promise<T | App> {
+		const app = await this.build(type);
+		await app.start();
+		this.logger.info("App started...");
+		return app;
+	}
+
+	public async build<T extends App = App>(type?: Constructable<T>): Promise<T | App> {
+		this.logger.info("Building App...");
+		this.configureUserServices();
+		this.configureApp(type);
+		await this.runPreBuildSteps(this.containerBuilder);
+		const container = this.containerBuilder.build();
+		await this.runPostBuildSteps(container);
+		const app = this.resolveApp(container, type);
+		return app;
+	}
+
+	private configureUserServices() {
+		for (const userService of this.userServices) {
+			userService(this.containerBuilder);
+		}
+	}
+
+	private async runPreBuildSteps(containerBuilder: ContainerBuilder) {
+		if (this.preBuildSteps.length === 0) {
+			return;
+		}
+		const container = containerBuilder.build();
+		const config = container.resolve(ConfigurationServiceToken) as IConfigurationService;
+		for (const step of this.preBuildSteps) {
+			await step(config, containerBuilder);
+		}
+	}
+
+	private async runPostBuildSteps(container: IContainer) {
+		for (const step of this.postBuildSteps) {
+			await step(container);
+		}
+	}
+
+	private configureApp(type: Constructable) {
+		this.containerBuilder.registerSingleton(HostedServiceHostToken, this.hostedServices);
+		this.containerBuilder.registerSingleton(type ?? App);
+	}
+
+	private resolveApp<T extends App>(container: IContainer, type: Constructable<T>) {
+		const app = type ? container.resolve(type) : container.resolve(App);
+		return app;
+	}
+}

package/{es6/src/const.js → src/const.ts}

@@ -1,5 +1,8 @@
+import type { Metadata } from "./routing/anvil.types.js";
+
 const Anvil = "anvil";
 const RoutingKey = `${Anvil}:Routing`;
+
 export const RouteRegistryToken = Symbol("RouteRegistryToken");
 export const HttpProviderToken = Symbol("HttpProviderToken");
 export const RouterToken = Symbol("RouterToken");
@@ -12,22 +15,27 @@ export const ExceptionFilterHostToken = Symbol("ExceptionFilterHost");
 export const ReadinessCheckToken = Symbol("ReadinessCheck");
 export const ReadinessServiceToken = Symbol("ReadinessService");
 export const HostedServiceHostToken = Symbol("HostedServiceHost");
+export type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
 export const HTTPMethods = {
-    GET: "GET",
-    PUT: "PUT",
-    POST: "POST",
-    PATCH: "PATCH",
-    DELETE: "DELETE"
-};
+	GET: "GET",
+	PUT: "PUT",
+	POST: "POST",
+	PATCH: "PATCH",
+	DELETE: "DELETE",
+} satisfies Record<string, HTTPMethod>;
+
+type AuthMetadata = "authorize" | "allowAnonymous";
+type ResponseMetadata = "httpCode" | "headers" | "catch" | "sse";
+
 export const MetadataKeys = {
-    controller: `${RoutingKey}:controller`,
-    route: `${RoutingKey}:route`,
-    parameter: `${RoutingKey}:parameter`,
-    fieldMap: `${RoutingKey}:fieldMap`,
-    authorize: `${RoutingKey}:authorize`,
-    allowAnonymous: `${RoutingKey}:allowAnonymous`,
-    httpCode: `${RoutingKey}:httpCode`,
-    headers: `${RoutingKey}:headers`,
-    catch: `${RoutingKey}:catch`,
-    sse: `${RoutingKey}:sse`
-};
+	controller: `${RoutingKey}:controller`,
+	route: `${RoutingKey}:route`,
+	parameter: `${RoutingKey}:parameter`,
+	fieldMap: `${RoutingKey}:fieldMap`,
+	authorize: `${RoutingKey}:authorize`,
+	allowAnonymous: `${RoutingKey}:allowAnonymous`,
+	httpCode: `${RoutingKey}:httpCode`,
+	headers: `${RoutingKey}:headers`,
+	catch: `${RoutingKey}:catch`,
+	sse: `${RoutingKey}:sse`,
+} satisfies Record<Metadata | AuthMetadata | ResponseMetadata, string>;

package/src/health/health.controller.ts

@@ -0,0 +1,34 @@
+import { inject, injectable } from "@decohere/di/decorators";
+import { ReadinessServiceToken } from "../const.js";
+import { HttpError } from "../routing/anvil.types.js";
+import { AllowAnonymous, Controller, Get } from "../routing/index.js";
+import { ReadinessService } from "./readiness.service.js";
+
+/**
+ * Liveness (`/health`) and readiness (`/ready`) probes.
+ * Both are anonymous so orchestration can scrape them with auth enabled, and stay at the root
+ * under a global prefix, where platforms look for them.
+ */
+@Controller({ prefix: "/", globalPrefix: false })
+@injectable()
+export class HealthController {
+	public constructor(
+		@inject(ReadinessServiceToken) private readonly readiness: ReadinessService,
+	) {}
+
+	@AllowAnonymous()
+	@Get("/health")
+	public health() {
+		return { status: "ok" };
+	}
+
+	@AllowAnonymous()
+	@Get("/ready")
+	public async ready() {
+		const result = await this.readiness.checkAll();
+		if (!result.ok) {
+			throw new HttpError("Not ready", 503);
+		}
+		return { status: "ok" };
+	}
+}

package/src/health/health.extensions.ts

@@ -0,0 +1,53 @@
+import type { ContainerBuilder } from "@decohere/di";
+import { extension } from "@decohere/core/extensibility";
+import { Builder } from "../builder/builder.js";
+import { ReadinessCheckToken, ReadinessServiceToken } from "../const.js";
+import "../http/http.extensions.js";
+import { getOrCreateHttpOptions } from "../http/http.options.store.js";
+import { HealthController } from "./health.controller.js";
+import { ReadinessService } from "./readiness.service.js";
+import type { IReadinessCheck } from "./readiness.types.js";
+
+export type WithHealthOptions = {
+	/** Extra readiness probes (e.g. custom dependency checks). */
+	checks?: IReadinessCheck[];
+	/**
+	 * Serve the probes under the global prefix (`/api/health`) instead of at the root. Default
+	 * `false`: Cloud Run, Kubernetes and most load balancers probe the root.
+	 */
+	underGlobalPrefix?: boolean;
+};
+
+declare module "@decohere/http" {
+	interface Builder {
+		/**
+		 * Register anonymous `/health` (liveness) and `/ready` (readiness) routes.
+		 *
+		 * Readiness runs every {@link IReadinessCheck} registered under
+		 * {@link ReadinessCheckToken} (TypeORM registers one per datasource when
+		 * `.withTypeOrm()` is used). Pass `checks` for app-specific probes.
+		 *
+		 * The probes stay at the root under `withGlobalPrefix`, unless `underGlobalPrefix` is set.
+		 *
+		 * Requires `.withHttpProvider(...)` (or `@decohere/http/http` side-effect).
+		 */
+		withHealth(options?: WithHealthOptions): Builder;
+	}
+}
+
+export class BuilderExtensions {
+	@extension(Builder)
+	public static withHealth(builder: Builder, options?: WithHealthOptions) {
+		builder.withServices((containerBuilder: ContainerBuilder) => {
+			containerBuilder.registerSingleton(ReadinessServiceToken, ReadinessService);
+			for (const check of options?.checks ?? []) {
+				containerBuilder.registerSingleton(ReadinessCheckToken, check);
+			}
+		});
+		if (options?.underGlobalPrefix === true) {
+			getOrCreateHttpOptions(builder).underGlobalPrefix.add(HealthController);
+		}
+		builder.withControllers(HealthController);
+		return builder;
+	}
+}

package/src/health/readiness.service.ts

@@ -0,0 +1,33 @@
+import { inject, injectable } from "@decohere/di/decorators";
+import { HostedServiceHostToken, ReadinessCheckToken } from "../const.js";
+import type { HostedServiceHost } from "../hosting/hosted-service-host.js";
+import type { IReadinessCheck, ReadinessResult } from "./readiness.types.js";
+
+@injectable()
+export class ReadinessService {
+	private readonly checks: readonly IReadinessCheck[];
+
+	public constructor(
+		@inject(ReadinessCheckToken) checks: IReadinessCheck[] = [],
+		@inject(HostedServiceHostToken) private readonly hostedServices?: HostedServiceHost,
+	) {
+		this.checks = checks;
+	}
+
+	/** Registered checks, then each started hosted service that has a `check()` (still warming up). */
+	public async checkAll(): Promise<ReadinessResult> {
+		const failures: string[] = [];
+		const probes = [...this.checks, ...(this.hostedServices?.readinessChecks() ?? [])];
+		for (const probe of probes) {
+			try {
+				await probe.check();
+			} catch {
+				failures.push(probe.name);
+			}
+		}
+		if (failures.length > 0) {
+			return { ok: false, failures };
+		}
+		return { ok: true };
+	}
+}

package/{types/src/health/readiness.types.d.ts → src/health/readiness.types.ts}

@@ -3,12 +3,8 @@
  * Register instances under {@link ReadinessCheckToken} (multi-inject).
  */
 export interface IReadinessCheck {
-    readonly name: string;
-    check(): Promise<void>;
+	readonly name: string;
+	check(): Promise<void>;
 }
-export type ReadinessResult = {
-    ok: true;
-} | {
-    ok: false;
-    failures: string[];
-};
+
+export type ReadinessResult = { ok: true } | { ok: false; failures: string[] };