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

package/README.md

@@ -58,7 +58,7 @@ Builder.create()
 
 **`exclude`.** Patterns for paths the mount never answers, neither a file nor the fallback (the request gets the JSON `404`), for anything the defaults get wrong. They are globs ([picomatch](https://github.com/micromatch/picomatch), `dot` on) matched against the full request path after decoding it and collapsing repeated slashes, not relative to the prefix: `*` is any characters within one segment, `**` crosses segments, `?` is one character. `"/docs/**"` covers `/docs`, `/docs/` and everything below.
 
-Why this shape, and what is left (running the UI's own build): [ADR 0007](../../docs/adr/0007-serving-a-built-ui-from-http.md).
+Why this shape, and what is left (running the UI's own build is [#381](https://github.com/typesmiths/decohere/issues/381)): [ADR 0007](../../docs/adr/0007-serving-a-built-ui-from-http.md).
 
 ## Global prefix
 
@@ -113,7 +113,7 @@ What to know about the plugin's behaviour:
 - **A `304`** for a file can carry the `Content-Encoding` header of the `200` it stands for. It has no body.
 - **Helmet, CORS and the rate limit** are unaffected, and an error reply (a `401`, a `400` with a large body) is compressed like any other.
 - **BREACH.** Compressing a response served over HTTPS that contains both a secret and input an attacker controls can leak the secret to someone who can watch response sizes. It mostly concerns HTML that reflects input next to a CSRF token. A JSON API that authenticates with a bearer token in a header is low risk, because the token is not in the body. If you render such pages, mask per-response secrets, do not reflect input beside them, or turn compression off for them.
-- **Pre-compressed files.** Serving `.br`/`.gz` files built ahead of time is a possible later step; today static files are compressed on the fly.
+- **Pre-compressed files.** Serving `.br`/`.gz` files built ahead of time is a possible later step ([#642](https://github.com/typesmiths/decohere/issues/642)); today static files are compressed on the fly.
 - **Testing.** Node's `fetch` negotiates and decodes compression itself. To see what is on the wire, use `node:http` and read the body undecoded.
 
 Why this shape: [ADR 0008](../../docs/adr/0008-response-compression-in-http.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/http",
-  "version": "0.0.1-dev.126",
+  "version": "0.0.1-dev.5",
   "description": "Web API and microservice platform built on Fastify with decorator-based routing",
   "keywords": [
     "typescript",
@@ -12,15 +12,6 @@
     "decorators",
     "decohere"
   ],
-  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/http#readme",
-  "bugs": {
-    "url": "https://github.com/typesmiths/decohere/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/typesmiths/decohere.git",
-    "directory": "projects/http"
-  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -56,9 +47,9 @@
   },
   "dependencies": {
     "@casl/ability": "^6.8.1",
-    "@decohere/core": "0.0.1-dev.126",
-    "@decohere/crucible": "0.0.1-dev.126",
-    "@decohere/scribe": "0.0.1-dev.126",
+    "@decohere/di": "0.0.1-dev.5",
+    "@decohere/core": "0.0.1-dev.5",
+    "@decohere/scribe": "0.0.1-dev.5",
     "@fastify/compress": "^9.2.1",
     "@fastify/cors": "^11.3.0",
     "@fastify/helmet": "^13.1.0",

package/src/app/app.ts

@@ -0,0 +1,147 @@
+import { type LifetimeScope, LifetimeScopeToken } from "@decohere/di";
+import { inject, optional } from "@decohere/di/decorators";
+import {
+	ConfigurationServiceToken,
+	type IConfigurationService,
+} from "@decohere/core/configuration";
+import { scribe } from "@decohere/scribe";
+import { HostedServiceHostToken, HttpProviderToken } from "../const.js";
+import type { HostedServiceHost } from "../hosting/hosted-service-host.js";
+import type { HttpProvider, StartResponse } from "../routing/anvil.types.js";
+
+const DEFAULT_PORT = 3000;
+const DEFAULT_SHUTDOWN_SIGNALS: readonly NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+
+export class ApiConfiguration {
+	public port: number;
+}
+
+export type StartOptions = {
+	port: number;
+	host?: string;
+	/**
+	 * Signals that stop the app gracefully: stop accepting connections, let in-flight
+	 * requests finish, stop hosted services, then dispose services. Default SIGTERM and SIGINT; `false` to
+	 * handle signals yourself.
+	 */
+	shutdownSignals?: readonly NodeJS.Signals[] | false;
+	/** How long a signalled shutdown may take before the process exits with code 1. Default 10s. */
+	shutdownTimeoutMs?: number;
+};
+
+export class App {
+	private _addresses = Array.of<string>();
+	private logger = scribe.logger(App.name);
+	private disposing: Promise<void> | undefined;
+	private disposingContainer = false;
+	private signalHandler: ((signal: NodeJS.Signals) => void) | undefined;
+	private shutdownSignals: readonly NodeJS.Signals[] = [];
+
+	public constructor(
+		@inject(LifetimeScopeToken) private readonly container: LifetimeScope,
+		@inject(ConfigurationServiceToken)
+		@optional()
+		private configurationService?: IConfigurationService,
+		@inject(HttpProviderToken) @optional() private httpProvider?: HttpProvider,
+		@inject(HostedServiceHostToken) @optional() private hostedServices?: HostedServiceHost,
+	) {}
+
+	public get addresses(): readonly string[] {
+		return this._addresses;
+	}
+
+	public async start(options?: StartOptions): Promise<StartResponse> {
+		this.logger.info("Starting app");
+		// Before HTTP, so a request never reaches a service that has not started.
+		await this.hostedServices?.start(this.container);
+		// The app was stopped while a hosted service was still starting.
+		if (this.disposing != null) return;
+		const hasHostedServices = this.hostedServices != null && !this.hostedServices.isEmpty;
+		if (!this.httpProvider) {
+			if (hasHostedServices) this.stopOnSignals(options);
+			return;
+		}
+		const port = await this.getPort(options);
+		this.logger.info(`Starting http on port ${port}`);
+		const startResponse = await this.httpProvider?.start({
+			port,
+			...(options?.host != null ? { host: options.host } : {}),
+		});
+		this._addresses = [...startResponse.addresses];
+		this.logger.info("Listening on:", this._addresses);
+		this.stopOnSignals(options);
+		return startResponse;
+	}
+
+	public [Symbol.asyncDispose]() {
+		// The container holds this App too; when stop() disposes the container it lands
+		// here, and awaiting our own shutdown would deadlock.
+		if (this.disposingContainer) return Promise.resolve();
+		return this.dispose();
+	}
+
+	/** Stop the app. Calling it again (or from a signal) returns the same shutdown. */
+	public dispose(): Promise<void> {
+		this.disposing ??= this.stop();
+		return this.disposing;
+	}
+
+	private async stop(): Promise<void> {
+		// Removed first, so a second Ctrl+C / SIGTERM gets Node's default: exit now.
+		this.removeSignalHandlers();
+		this.logger.info("Stopping");
+		// Hosted services hear the signal at once, so background work winds down while HTTP drains.
+		this.hostedServices?.abort();
+		try {
+			// HTTP first: in-flight requests still need the services (DB pools etc.) that
+			// disposing the container would close.
+			await this.httpProvider?.stop();
+			// Hosted services next, while what they use is still open.
+			await this.hostedServices?.stop();
+		} finally {
+			this.disposingContainer = true;
+			await this.container[Symbol.asyncDispose]();
+			await scribe.stop();
+		}
+	}
+
+	private stopOnSignals(options?: StartOptions) {
+		const signals = options?.shutdownSignals ?? DEFAULT_SHUTDOWN_SIGNALS;
+		const timeoutMs = options?.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+		if (signals === false || signals.length === 0) return;
+		this.signalHandler = (signal) => {
+			this.logger.info(`Received ${signal}; finishing in-flight requests`);
+			// console.error, not the logger: scribe may be the thing that's stuck.
+			const timer = setTimeout(() => {
+				console.error(`Shutdown did not finish within ${timeoutMs}ms; exiting.`);
+				process.exit(1);
+			}, timeoutMs);
+			timer.unref();
+			this.dispose().then(
+				() => clearTimeout(timer),
+				(error: unknown) => {
+					clearTimeout(timer);
+					console.error("Shutdown failed:", error);
+					process.exit(1);
+				},
+			);
+		};
+		this.shutdownSignals = signals;
+		for (const signal of signals) process.on(signal, this.signalHandler);
+	}
+
+	private removeSignalHandlers() {
+		if (!this.signalHandler) return;
+		for (const signal of this.shutdownSignals) process.off(signal, this.signalHandler);
+	}
+
+	private async getPort(options?: StartOptions) {
+		const port =
+			options?.port ??
+			(await this.configurationService?.get(ApiConfiguration))?.port ??
+			DEFAULT_PORT;
+
+		return port;
+	}
+}

package/src/app/module.ts

@@ -0,0 +1,19 @@
+import type { ContainerBuilder } from "@decohere/di";
+import type { Constructable } from "@decohere/core/reflection";
+
+export type ModuleDefinition = {
+	name: string;
+	entities?: Constructable[];
+	repositories?: Constructable[];
+	registerServices?(containerBuilder: ContainerBuilder): void;
+};
+
+export abstract class Module {
+	public abstract name: string;
+	public constructor(data: Partial<Module>) {
+		Object.assign(this, data);
+	}
+	public readonly entities?: readonly Constructable[];
+	public readonly repositories?: readonly Constructable[];
+	public abstract registerServices?(containerBuilder: ContainerBuilder): void;
+}

package/src/auth/ability.ts

@@ -0,0 +1,56 @@
+import { AbilityBuilder, createMongoAbility } from "@casl/ability";
+import type { Principal } from "./auth.types.js";
+
+/** Root role — expands to CASL `manage`/`all` (covers every future ability). */
+export const ADMIN_ROLE = "admin";
+
+/**
+ * Default CASL ability factory.
+ *
+ * - `admin` role → `manage` / `all` (wildcard)
+ * - otherwise map `principal.scopes` of the form `"action:Subject"` to CASL rules
+ *
+ * Pass a custom factory to `withAuth()` (or override the app stub) for product-specific rules.
+ */
+export function defineAbilitiesFor(principal: Principal) {
+	const { can, build } = new AbilityBuilder(createMongoAbility);
+	if (principal.roles?.includes(ADMIN_ROLE)) {
+		can("manage", "all");
+		return build();
+	}
+	for (const scope of principal.scopes ?? []) {
+		const [action, subject] = scope.split(":");
+		if (action && subject) can(action, subject);
+	}
+	return build();
+}
+
+/**
+ * Map a raw JWT payload → {@link Principal}.
+ *
+ * Merges OAuth `scope` / `scopes` with an IdP `permissions` claim (e.g. Auth0 API permissions).
+ * Override via `withAuth(..., { principalMapper })` when claims differ.
+ */
+export function createPrincipalFromPayload(payload: Record<string, unknown>): Principal {
+	const sub = typeof payload.sub === "string" ? payload.sub : "";
+	const fromScopeClaim =
+		typeof payload.scope === "string"
+			? payload.scope.split(" ").filter(Boolean)
+			: Array.isArray(payload.scopes)
+				? (payload.scopes as unknown[]).filter((s): s is string => typeof s === "string")
+				: [];
+	const fromPermissions = Array.isArray(payload.permissions)
+		? (payload.permissions as unknown[]).filter((s): s is string => typeof s === "string")
+		: [];
+	const merged = [...new Set([...fromScopeClaim, ...fromPermissions])];
+	const scopes = merged.length > 0 ? merged : undefined;
+	const roles = Array.isArray(payload.roles)
+		? (payload.roles as unknown[]).filter((r): r is string => typeof r === "string")
+		: undefined;
+	return {
+		...payload,
+		sub,
+		roles: roles && roles.length > 0 ? roles : undefined,
+		scopes,
+	};
+}

package/src/auth/auth.config.ts

@@ -0,0 +1,34 @@
+import type { Principal } from "./auth.types.js";
+
+/**
+ * Configuration for the TokenService, read from the `auth` section of the
+ * application config file. Exactly one of the discriminant fields must be set.
+ *
+ * Production  → use `jwksUrl`, `publicKey`, or `secret`.
+ * Development → use `devStatic` (only works when NODE_ENV=development).
+ */
+export class AuthConfig {
+	/** OIDC discovery URL — the issuer base URL, e.g. https://accounts.google.com.
+	 *  The framework appends `/.well-known/openid-configuration` automatically.
+	 *  Use this instead of `jwksUrl` for any standard OIDC-compliant IdP.
+	 */
+	public discoveryUrl?: string;
+
+	/** JWKS endpoint URL (RS256 / ES256 via remote key set). */
+	public jwksUrl?: string;
+
+	/** PEM-encoded public key or JWK JSON string (RS256 / ES256 static key). */
+	public publicKey?: string;
+	public algorithms?: string[];
+
+	/** Shared secret for HS256. */
+	public secret?: string;
+
+	/** Issuer claim to validate (all non-devStatic variants). */
+	public issuer?: string;
+	/** Audience claim to validate (all non-devStatic variants). */
+	public audience?: string;
+
+	/** Static principal injected for every request (development only). */
+	public devStatic?: Principal;
+}

package/src/auth/auth.extensions.ts

@@ -0,0 +1,115 @@
+import type { ContainerBuilder } from "@decohere/di";
+import { extension } from "@decohere/core/extensibility";
+import { Builder } from "../builder/builder.js";
+import { AuthorizationServiceToken, TokenServiceToken } from "../const.js";
+import { defineAbilitiesFor } from "./ability.js";
+import { AuthConfig } from "./auth.config.js";
+import type { PrincipalMapper, TokenServiceConfig } from "./auth.types.js";
+import { assertDevStaticAllowed, assertNonEmptyAudience } from "./auth.types.js";
+import type { AbilityFactory } from "./casl-authorization.service.js";
+import { CaslAuthorizationService } from "./casl-authorization.service.js";
+import { TokenService } from "./token-service.js";
+
+export { ADMIN_ROLE, createPrincipalFromPayload, defineAbilitiesFor } from "./ability.js";
+
+export type WithAuthOptions = {
+	/**
+	 * Override the default JWT payload → Principal mapping.
+	 * Use this when your IdP stores roles or scopes in non-standard claims.
+	 *
+	 * @example Keycloak realm roles:
+	 * ```ts
+	 * builder.withAuth(factory, {
+	 *   principalMapper: (p) => ({
+	 *     sub: p.sub as string,
+	 *     scopes: (p.realm_access as any)?.roles?.map((r: string) => `manage:${r}`) ?? [],
+	 *   }),
+	 * });
+	 * ```
+	 */
+	principalMapper?: PrincipalMapper;
+};
+
+declare module "@decohere/http" {
+	interface Builder {
+		/**
+		 * Configure JWT authentication from the `auth` config section and wire
+		 * up a CASL authorization service.
+		 *
+		 * By default, `defineAbilitiesFor` grants `manage`/`all` for the `admin`
+		 * role and maps `principal.scopes` of the form `"action:Subject"` to CASL
+		 * rules. Pass a custom `abilityFactory` to override that behaviour.
+		 *
+		 * Requires `.withConfiguration(...)` to be called on the builder.
+		 *
+		 * @example Default (scope-based, no boilerplate):
+		 * ```ts
+		 * builder.withConfiguration(YamlDataSource).withAuth();
+		 * ```
+		 *
+		 * @example Custom override:
+		 * ```ts
+		 * builder.withAuth((principal) => {
+		 *   const { can, build } = new AbilityBuilder(createMongoAbility);
+		 *   // custom logic ...
+		 *   return build();
+		 * });
+		 * ```
+		 */
+		withAuth(abilityFactory?: AbilityFactory, options?: WithAuthOptions): Builder;
+	}
+}
+
+export class BuilderExtensions {
+	@extension(Builder)
+	public static withAuth(
+		builder: Builder,
+		abilityFactory: AbilityFactory = defineAbilitiesFor,
+		options?: WithAuthOptions,
+	) {
+		builder.registerPreBuildStep(async (configService, containerBuilder: ContainerBuilder) => {
+			const authConfig = await configService.get(AuthConfig);
+			const tokenConfig = toTokenServiceConfig(authConfig);
+			const tokenService = new TokenService(tokenConfig, options?.principalMapper);
+			containerBuilder.registerSingleton(TokenServiceToken, tokenService);
+			containerBuilder.registerSingleton(
+				AuthorizationServiceToken,
+				new CaslAuthorizationService(abilityFactory, tokenService),
+			);
+		});
+		return builder;
+	}
+}
+
+function toTokenServiceConfig(config: AuthConfig): TokenServiceConfig {
+	// Prefer real verification strategies over devStatic so a leftover
+	// development block cannot disable OIDC/JWKS in any environment.
+	if (config.discoveryUrl != null) {
+		assertNonEmptyAudience(config.audience);
+		return { discoveryUrl: config.discoveryUrl, audience: config.audience };
+	}
+	if (config.jwksUrl != null) {
+		assertNonEmptyAudience(config.audience);
+		return { jwksUrl: config.jwksUrl, issuer: config.issuer, audience: config.audience };
+	}
+	if (config.publicKey != null) {
+		assertNonEmptyAudience(config.audience);
+		return {
+			publicKey: config.publicKey,
+			algorithms: config.algorithms,
+			issuer: config.issuer,
+			audience: config.audience,
+		};
+	}
+	if (config.secret != null) {
+		assertNonEmptyAudience(config.audience);
+		return { secret: config.secret, issuer: config.issuer, audience: config.audience };
+	}
+	if (config.devStatic != null) {
+		assertDevStaticAllowed();
+		return { devStatic: config.devStatic };
+	}
+	throw new Error(
+		"AuthConfig must specify one of: discoveryUrl, jwksUrl, publicKey, secret, or devStatic",
+	);
+}

package/src/auth/auth.types.ts

@@ -0,0 +1,124 @@
+export type Principal = {
+	sub: string;
+	roles?: string[];
+	scopes?: string[];
+	[key: string]: unknown;
+};
+
+/** Maps a raw JWT payload to a Principal. Override the default via withAuth() options. */
+export type PrincipalMapper = (payload: Record<string, unknown>) => Principal;
+
+export type JwksConfig = {
+	jwksUrl: string;
+	issuer?: string;
+	/** Required — empty/undefined disables jose `aud` checks (cross-API token accept). */
+	audience: string;
+};
+
+export type PublicKeyConfig = {
+	publicKey: string; // PEM or JWK JSON string
+	algorithms?: string[];
+	issuer?: string;
+	/** Required — empty/undefined disables jose `aud` checks (cross-API token accept). */
+	audience: string;
+};
+
+export type SecretConfig = {
+	secret: string;
+	issuer?: string;
+	/** Required — empty/undefined disables jose `aud` checks (cross-API token accept). */
+	audience: string;
+};
+
+export type DevStaticConfig = {
+	devStatic: Principal;
+};
+
+/**
+ * Resolve IdP configuration automatically from an OIDC discovery endpoint
+ * (`{discoveryUrl}/.well-known/openid-configuration`). The `discoveryUrl` is
+ * also used as the expected `iss` claim unless the discovery document provides
+ * a different value.
+ */
+export type DiscoveryConfig = {
+	discoveryUrl: string;
+	/** Required — empty/undefined disables jose `aud` checks (cross-API token accept). */
+	audience: string;
+};
+
+/**
+ * Framework-agnostic authorization service. Implement this interface (e.g.
+ * via CaslAuthorizationService) and register it under AuthorizationServiceToken.
+ * Throw ForbiddenError to deny access.
+ */
+export interface IAuthorizationService {
+	authorizeRequest(
+		request: import("../routing/anvil.types.js").HttpRequest,
+		action: string,
+		subject: string,
+	): Promise<Principal>;
+	/**
+	 * Verify the request has a valid principal without checking a CASL ability.
+	 * Used when auth is enabled but the route has no `@Authorize` metadata.
+	 */
+	authenticateRequest(
+		request: import("../routing/anvil.types.js").HttpRequest,
+	): Promise<Principal>;
+	authorize(principal: Principal, action: string, subject: string): Promise<void>;
+}
+
+export type TokenServiceConfig =
+	JwksConfig | PublicKeyConfig | SecretConfig | DevStaticConfig | DiscoveryConfig;
+
+export function isDiscoveryConfig(config: TokenServiceConfig): config is DiscoveryConfig {
+	return "discoveryUrl" in config;
+}
+
+export function isDevStaticConfig(config: TokenServiceConfig): config is DevStaticConfig {
+	return "devStatic" in config;
+}
+
+export function isJwksConfig(config: TokenServiceConfig): config is JwksConfig {
+	return "jwksUrl" in config;
+}
+
+export function isPublicKeyConfig(config: TokenServiceConfig): config is PublicKeyConfig {
+	return "publicKey" in config;
+}
+
+export function isSecretConfig(config: TokenServiceConfig): config is SecretConfig {
+	return "secret" in config;
+}
+
+/** `devStatic` is only valid for local development NODE_ENV values. */
+export function isDevelopmentNodeEnv(nodeEnv = process.env.NODE_ENV): boolean {
+	const env = nodeEnv?.toLowerCase();
+	return env === "development" || env === "dev";
+}
+
+/**
+ * Refuse `devStatic` outside development — otherwise any Bearer string is
+ * accepted as the configured principal (auth bypass in production).
+ */
+export function assertDevStaticAllowed(nodeEnv = process.env.NODE_ENV): void {
+	if (!isDevelopmentNodeEnv(nodeEnv)) {
+		throw new Error(
+			`AuthConfig.devStatic is only allowed when NODE_ENV is "development" or "dev" (got ${JSON.stringify(nodeEnv ?? "")}).`,
+		);
+	}
+}
+
+/**
+ * jose skips `aud` validation when `audience` is undefined or "". Require a
+ * non-empty audience for every non-devStatic verification strategy.
+ */
+export function assertNonEmptyAudience(
+	audience: string | undefined,
+): asserts audience is string {
+	if (typeof audience !== "string" || audience.trim().length === 0) {
+		throw new Error(
+			`JWT audience must be a non-empty string (got ${JSON.stringify(audience)}). ` +
+				"Empty audience disables aud validation and accepts tokens minted for other APIs.",
+		);
+	}
+}

package/src/auth/casl-authorization.service.ts

@@ -0,0 +1,62 @@
+import type { AnyAbility } from "@casl/ability";
+import type { HttpRequest } from "../routing/anvil.types.js";
+import { ForbiddenError } from "../routing/anvil.types.js";
+import type { IAuthorizationService, Principal } from "./auth.types.js";
+import type { TokenService } from "./token-service.js";
+
+export type AbilityFactory = (principal: Principal) => AnyAbility;
+
+/**
+ * IAuthorizationService implementation backed by CASL.
+ *
+ * Register it under AuthorizationServiceToken:
+ * ```ts
+ * builder.withServices((c) =>
+ *   c.registerSingleton(AuthorizationServiceToken, new CaslAuthorizationService((principal) => {
+ *     const { can, build } = new AbilityBuilder(createMongoAbility);
+ *     if (principal.roles?.includes("admin")) can("manage", "all");
+ *     else can("read", "Post");
+ *     return build();
+ *   }))
+ * );
+ * ```
+ */
+export class CaslAuthorizationService implements IAuthorizationService {
+	private readonly factory: AbilityFactory;
+	private readonly tokenService?: TokenService;
+
+	public constructor(factory: AbilityFactory, tokenService?: TokenService) {
+		this.factory = factory;
+		this.tokenService = tokenService;
+	}
+
+	public async authorizeRequest(
+		request: HttpRequest,
+		action: string,
+		subject: string,
+	): Promise<Principal> {
+		const principal = await this.authenticateRequest(request);
+		await this.authorize(principal, action, subject);
+		return principal;
+	}
+
+	public async authenticateRequest(request: HttpRequest): Promise<Principal> {
+		if (!this.tokenService) {
+			throw new Error(
+				"CaslAuthorizationService requires a TokenService to authenticate requests. Register it via .withAuth().",
+			);
+		}
+		return this.tokenService.verifyRequest(request);
+	}
+
+	public async authorize(
+		principal: Principal,
+		action: string,
+		subject: string,
+	): Promise<void> {
+		const ability = this.factory(principal);
+		if (ability.cannot(action, subject)) {
+			throw new ForbiddenError(`Cannot perform "${action}" on "${subject}"`);
+		}
+	}
+}

package/{types/src/auth/principal-provider.d.ts → src/auth/principal-provider.ts}

@@ -1,20 +1,28 @@
 import type { Principal } from "./auth.types.js";
+
 /**
  * Read-only view of the authenticated principal for the current request.
  * Inject this interface (via IPrincipalProviderToken) in any request-scoped
  * service to access the verified identity without coupling to the routing layer.
  */
 export interface IPrincipalProvider {
-    readonly currentPrincipal: Principal | undefined;
+	readonly currentPrincipal: Principal | undefined;
 }
+
 /**
  * Concrete, request-scoped implementation. The Router sets the principal
  * after JWT verification; downstream services consume it via IPrincipalProvider.
  *
  * @internal — framework use only. Inject IPrincipalProvider, not this class.
  */
-export declare class PrincipalProvider implements IPrincipalProvider {
-    private _principal;
-    get currentPrincipal(): Principal | undefined;
-    setPrincipal(principal: Principal | undefined): void;
+export class PrincipalProvider implements IPrincipalProvider {
+	private _principal: Principal | undefined;
+
+	public get currentPrincipal(): Principal | undefined {
+		return this._principal;
+	}
+
+	public setPrincipal(principal: Principal | undefined): void {
+		this._principal = principal;
+	}
 }