@decohere/http 0.0.1-dev.116

package/es6/src/auth/casl-authorization.service.js

@@ -0,0 +1,40 @@
+import { ForbiddenError } from "../routing/anvil.types.js";
+/**
+ * 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 {
+    factory;
+    tokenService;
+    constructor(factory, tokenService){
+        this.factory = factory;
+        this.tokenService = tokenService;
+    }
+    async authorizeRequest(request, action, subject) {
+        const principal = await this.authenticateRequest(request);
+        await this.authorize(principal, action, subject);
+        return principal;
+    }
+    async authenticateRequest(request) {
+        if (!this.tokenService) {
+            throw new Error("CaslAuthorizationService requires a TokenService to authenticate requests. Register it via .withAuth().");
+        }
+        return this.tokenService.verifyRequest(request);
+    }
+    async authorize(principal, action, subject) {
+        const ability = this.factory(principal);
+        if (ability.cannot(action, subject)) {
+            throw new ForbiddenError(`Cannot perform "${action}" on "${subject}"`);
+        }
+    }
+}

package/es6/src/auth/index.js

@@ -0,0 +1,6 @@
+export * from "./ability.js";
+export * from "./auth.config.js";
+export * from "./auth.types.js";
+export * from "./casl-authorization.service.js";
+export * from "./principal-provider.js";
+export * from "./token-service.js";

package/es6/src/auth/principal-provider.js

@@ -0,0 +1,14 @@
+/**
+ * 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 class PrincipalProvider {
+    _principal;
+    get currentPrincipal() {
+        return this._principal;
+    }
+    setPrincipal(principal) {
+        this._principal = principal;
+    }
+}

package/es6/src/auth/safe-outbound-url.js

@@ -0,0 +1,99 @@
+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, label) {
+    let 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() {
+    const env = process.env.NODE_ENV ?? "";
+    return env === "development" || env === "dev" || env === "test";
+}
+function isLoopbackHostname(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+function isBlockedHostname(hostname) {
+    const lower = hostname.toLowerCase();
+    return lower === "metadata.google.internal" || lower === "metadata" || lower.endsWith(".metadata.google.internal");
+}
+async function resolveIps(hostname) {
+    if (isIP(hostname)) {
+        return [
+            hostname
+        ];
+    }
+    const results = await lookup(hostname, {
+        all: true,
+        verbatim: true
+    });
+    return results.map((r)=>r.address);
+}
+function isLoopbackIp(ip) {
+    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, allowLoopback) {
+    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/es6/src/auth/token-service.js

@@ -0,0 +1,141 @@
+import { createRemoteJWKSet, importJWK, importSPKI, jwtVerify, SignJWT } from "jose";
+import { UnauthorizedError } from "../routing/anvil.types.js";
+import { createPrincipalFromPayload } from "./ability.js";
+import { assertDevStaticAllowed, assertNonEmptyAudience, isDevStaticConfig, isDiscoveryConfig, isJwksConfig, isPublicKeyConfig, isSecretConfig } from "./auth.types.js";
+import { assertSafeOutboundUrl } from "./safe-outbound-url.js";
+export class TokenService {
+    config;
+    principalMapper;
+    /** Lazily resolved JWKS set when using OIDC discovery. */ discoveryJwks;
+    discoveryIssuer;
+    /** Remote key set for `jwksUrl` mode, created once so jose can cache the keys (#499). */ configuredJwks;
+    constructor(config, principalMapper){
+        if (isDevStaticConfig(config)) {
+            assertDevStaticAllowed();
+        } else {
+            assertNonEmptyAudience(config.audience);
+        }
+        this.config = config;
+        this.principalMapper = principalMapper;
+    }
+    async verifyRequest(request) {
+        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);
+    }
+    async verify(credentials) {
+        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, {
+                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
+	 */ async resolveVerificationContext() {
+        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.issuer,
+            audience: this.config.audience
+        };
+    }
+    async resolveOidcDiscovery() {
+        if (this.discoveryJwks && this.discoveryIssuer) {
+            return {
+                jwks: this.discoveryJwks,
+                issuer: this.discoveryIssuer
+            };
+        }
+        const { discoveryUrl } = this.config;
+        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();
+        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.
+	 */ async sign(payload, expiresIn = "1h") {
+        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);
+    }
+    async getStaticKey() {
+        if (isPublicKeyConfig(this.config)) {
+            const cfg = this.config;
+            const trimmed = cfg.publicKey.trim();
+            if (trimmed.startsWith("{")) {
+                const jwk = JSON.parse(trimmed);
+                return importJWK(jwk);
+            }
+            return importSPKI(trimmed, cfg.algorithms?.[0] ?? "RS256");
+        }
+        if (isSecretConfig(this.config)) {
+            const enc = new TextEncoder().encode(this.config.secret);
+            return enc;
+        }
+        throw new Error("Invalid TokenService configuration");
+    }
+    mapPrincipal(payload) {
+        if (this.principalMapper) return this.principalMapper(payload);
+        return createPrincipalFromPayload(payload);
+    }
+}

package/es6/src/builder/builder.js

@@ -0,0 +1,85 @@
+import { ServiceContainerBuilder } from "@decohere/crucible";
+import { ConfigurationServiceToken } from "@decohere/core/configuration";
+import { scribe } from "@decohere/scribe";
+import { App } from "../app/app.js";
+import { HostedServiceHostToken } from "../const.js";
+import { HostedServiceHost } from "../hosting/hosted-service-host.js";
+export class Builder {
+    static create(options) {
+        return new Builder(options);
+    }
+    containerBuilder;
+    applicationName;
+    logger = scribe.logger("name");
+    userServices = [];
+    preBuildSteps = [];
+    postBuildSteps = [];
+    hostedServices = new HostedServiceHost();
+    constructor(options){
+        this.containerBuilder = options?.containerBuilder ?? new ServiceContainerBuilder();
+        this.applicationName = options?.applicationName;
+    }
+    withServices(userServices) {
+        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.
+	 */ withHostedService(...types) {
+        for (const type of types)this.containerBuilder.registerSingleton(type);
+        this.hostedServices.add(...types);
+        return this;
+    }
+    registerPreBuildStep(step) {
+        this.preBuildSteps.push(step);
+    }
+    registerPostBuildStep(step) {
+        this.postBuildSteps.push(step);
+    }
+    async buildAndStart(type) {
+        const app = await this.build(type);
+        await app.start();
+        this.logger.info("App started...");
+        return app;
+    }
+    async build(type) {
+        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;
+    }
+    configureUserServices() {
+        for (const userService of this.userServices){
+            userService(this.containerBuilder);
+        }
+    }
+    async runPreBuildSteps(containerBuilder) {
+        if (this.preBuildSteps.length === 0) {
+            return;
+        }
+        const container = containerBuilder.build();
+        const config = container.resolve(ConfigurationServiceToken);
+        for (const step of this.preBuildSteps){
+            await step(config, containerBuilder);
+        }
+    }
+    async runPostBuildSteps(container) {
+        for (const step of this.postBuildSteps){
+            await step(container);
+        }
+    }
+    configureApp(type) {
+        this.containerBuilder.registerSingleton(HostedServiceHostToken, this.hostedServices);
+        this.containerBuilder.registerSingleton(type ?? App);
+    }
+    resolveApp(container, type) {
+        const app = type ? container.resolve(type) : container.resolve(App);
+        return app;
+    }
+}

package/es6/src/builder/index.js

@@ -0,0 +1 @@
+export * from "./builder.js";

package/es6/src/const.js

@@ -0,0 +1,33 @@
+const Anvil = "anvil";
+const RoutingKey = `${Anvil}:Routing`;
+export const RouteRegistryToken = Symbol("RouteRegistryToken");
+export const HttpProviderToken = Symbol("HttpProviderToken");
+export const RouterToken = Symbol("RouterToken");
+export const PrincipalToken = Symbol("PrincipalToken");
+export const IPrincipalProviderToken = Symbol("IPrincipalProvider");
+export const TokenServiceToken = Symbol("TokenService");
+export const AuthorizationServiceToken = Symbol("AuthorizationService");
+export const HttpOptionsToken = Symbol("HttpOptions");
+export const ExceptionFilterHostToken = Symbol("ExceptionFilterHost");
+export const ReadinessCheckToken = Symbol("ReadinessCheck");
+export const ReadinessServiceToken = Symbol("ReadinessService");
+export const HostedServiceHostToken = Symbol("HostedServiceHost");
+export const HTTPMethods = {
+    GET: "GET",
+    PUT: "PUT",
+    POST: "POST",
+    PATCH: "PATCH",
+    DELETE: "DELETE"
+};
+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`
+};

package/es6/src/health/health.controller.js

@@ -0,0 +1,65 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { inject, injectable } from "@decohere/crucible/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";
+export class HealthController {
+    readiness;
+    constructor(readiness){
+        this.readiness = readiness;
+    }
+    health() {
+        return {
+            status: "ok"
+        };
+    }
+    async ready() {
+        const result = await this.readiness.checkAll();
+        if (!result.ok) {
+            throw new HttpError("Not ready", 503);
+        }
+        return {
+            status: "ok"
+        };
+    }
+}
+_ts_decorate([
+    AllowAnonymous(),
+    Get("/health"),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", []),
+    _ts_metadata("design:returntype", void 0)
+], HealthController.prototype, "health", null);
+_ts_decorate([
+    AllowAnonymous(),
+    Get("/ready"),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", []),
+    _ts_metadata("design:returntype", Promise)
+], HealthController.prototype, "ready", null);
+HealthController = _ts_decorate([
+    Controller({
+        prefix: "/",
+        globalPrefix: false
+    }),
+    injectable(),
+    _ts_param(0, inject(ReadinessServiceToken)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof ReadinessService === "undefined" ? Object : ReadinessService
+    ])
+], HealthController);

package/es6/src/health/health.extensions.js

@@ -0,0 +1,40 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+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";
+export class BuilderExtensions {
+    static withHealth(builder, options) {
+        builder.withServices((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;
+    }
+}
+_ts_decorate([
+    extension(Builder),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Builder === "undefined" ? Object : Builder,
+        typeof WithHealthOptions === "undefined" ? Object : WithHealthOptions
+    ]),
+    _ts_metadata("design:returntype", void 0)
+], BuilderExtensions, "withHealth", null);

package/es6/src/health/index.js

@@ -0,0 +1,4 @@
+export * from "./health.controller.js";
+export * from "./health.extensions.js";
+export * from "./readiness.service.js";
+export * from "./readiness.types.js";

package/es6/src/health/readiness.service.js

@@ -0,0 +1,57 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { inject, injectable } from "@decohere/crucible/decorators";
+import { HostedServiceHostToken, ReadinessCheckToken } from "../const.js";
+export class ReadinessService {
+    hostedServices;
+    checks;
+    constructor(checks = [], hostedServices){
+        this.hostedServices = hostedServices;
+        this.checks = checks;
+    }
+    /** Registered checks, then each started hosted service that has a `check()` (still warming up). */ async checkAll() {
+        const failures = [];
+        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
+        };
+    }
+}
+ReadinessService = _ts_decorate([
+    injectable(),
+    _ts_param(0, inject(ReadinessCheckToken)),
+    _ts_param(1, inject(HostedServiceHostToken)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        Array,
+        typeof HostedServiceHost === "undefined" ? Object : HostedServiceHost
+    ])
+], ReadinessService);

package/es6/src/health/readiness.types.js

@@ -0,0 +1,4 @@
+/**
+ * A dependency probe run by `GET /ready`.
+ * Register instances under {@link ReadinessCheckToken} (multi-inject).
+ */ export { };