API reference: Middleware & helpers

requestId(opts?: RequestIdOptions): Hooks
secureHeaders(opts?: SecureHeadersOptions): Hooks
cors(opts: CorsOptions): Hooks
rateLimit(opts: RateLimitOptions): Hooks
loginThrottle(opts?: LoginThrottleOptions): Hooks    // default key: TCP peer (IPv6 grouped by ipv6Subnet)
timing(headerName?: string): Hooks
compression(opts?: CompressionOptions): Hooks        // skips SSE, NDJSON/JSON Lines/json-seq, Cache-Control: no-transform
bearerAuth(opts: BearerAuthOptions): Hooks
basicAuth(opts: BasicAuthOptions): Hooks
markAuthHook(hooks: Hooks): Hooks
const AUTH_HOOK_MARKER: unique symbol  // stamped by built-ins and markAuthHook()
csrf(opts?: CsrfOptions): Hooks
fetchMetadata(opts?: FetchMetadataOptions): Hooks   // Sec-Fetch-Site/Mode/Dest enforcement
requireScopes(scopes: string[], opts?: RequireScopesOptions): Hooks
                                                      // { phase?: "beforeHandle" | "preBody"; match?: "all" | "any" }
requireRoles(roles: string[], opts?: RequireRolesOptions): Hooks
                                                      // { claim?: string | (claims) => unknown; match?: "all" | "any" }; always preBody
ipRestriction(opts: IpRestrictionOptions): Hooks    // CIDR allow/deny
loadShedding(opts?: LoadSheddingOptions): Hooks
etag(opts?: ETagOptions): Hooks                      // 304 + Set-Cookie / Cache-Control skip
  // SSE, NDJSON, unknown-length, and over-maxBytes bodies are sent untagged

app.use(rateLimit({ windowMs: 60_000, max: 120, standardHeaders: "draft-8", legacyHeaders: false }));
// RateLimit-Policy: "120-in-60sec"; q=120; w=60
// RateLimit: "120-in-60sec"; r=119; t=60

import { App, every, jwk, requireScopes } from "@daloyjs/core";

app.use(every(
  jwk({ jwks, algorithms: ["RS256"], issuer, audience, maxLifetimeSeconds: 86_400 }),
  // 403 before any body I/O; owning either scope is enough.
  requireScopes(["agent.chat", "agent.admin"], { phase: "preBody", match: "any" }),
));

import { jwk, requireRoles } from "@daloyjs/core";

app.use(jwk({ jwks, algorithms: ["RS256"], issuer, audience }));

requireRoles(["Books.Admin"]);                                   // Entra app roles (`roles`)
requireRoles(["admins"], { claim: "cognito:groups" });           // a named top-level claim
requireRoles(["delete:books"], { claim: "permissions" });        // Auth0 RBAC
requireRoles(["editor", "admin"], {                              // Keycloak, any one role
  claim: (c) => (c.realm_access as { roles?: unknown } | undefined)?.roles,
  match: "any",
});

every(...layers: Hooks[]): Hooks      // run every lifecycle phase in order
some (...layers: Hooks[]): Hooks      // pass the first successful preBody/beforeHandle auth gate
except(when: ExceptPredicate, hooks: Hooks): Hooks  // exempt paths from preBody + beforeHandle gates

type ExceptPredicate =
  | string                            // path glob: "*" = one segment, "**" = any suffix
  | string[]                          // any-of globs
  | ((ctx) => boolean | Promise<boolean>);

// Globs match the canonical path the router dispatches on. The Node adapter
// resolves raw %2e%2e dot segments and folds \ to / before routing, and the
// Node and Lambda adapters refuse (400) a Host containing \ / ? # @ % or
// whitespace, so a crafted target cannot slip past an except() glob. Route
// params and wildcards never bind "." or "..".

defineDependency<TName, TValue, TStateKey>(opts: {
  name: TName;
  dependsOn?: readonly string[];      // refuses cycles at registration
  stateKey?: TStateKey;
  resolve: (ctx) => TValue | Promise<TValue>;
}): DependencyHooks   // per-request cached; runs once per dependency per request

defineConfig<S extends StandardSchemaV1>(opts: {
  schema: S;
  source?: ConfigSource;               // default: "env" (process.env)
  stderr?: { write(chunk: string): void } | false;
}): Promise<StandardSchemaV1.InferOutput<S>>;
  // Async. Validates once at startup; throws ConfigValidationError on missing/invalid values.

type ConfigSource =
  | "env"
  | { kind: "env";    env: Record<string, string | undefined> }
  | { kind: "file";   path: string; parse?: (text: string) => unknown }
  | { kind: "object"; data: Record<string, unknown> }
  | { kind: "custom"; resolve: () => Promise<Record<string, unknown>> };

class ConfigValidationError extends Error {
  readonly issues: ReadonlyArray<{ key: string; message: string }>;
}

type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";

createLogger(opts?: ConsoleLoggerOptions): Logger;
const noopLogger: Logger;
const DEFAULT_REDACT_KEYS: ReadonlyArray<string>;  // password, token, secret, authorization, ...
sanitizeUrlForLog(url: string): string;             // redacts sensitive query values
sanitizeUrlQueryForLog(search: string): string;     // same rules for a bare query string (since 1.3.7)
// Redaction copies on write: it never mutates the objects you pass to a log call.

interface ConsoleLoggerOptions {
  level?: LogLevel;
  bindings?: Record<string, unknown>;
  write?: (line: string) => void;
  redact?: LoggerRedactionOptions;     // { keys?, replacer? }
}

interface Logger {
  trace(obj?, msg?): void;
  debug(obj?, msg?): void;
  info (obj?, msg?): void;
  warn (obj?, msg?): void;
  error(obj?, msg?): void;
  fatal(obj?, msg?): void;
  child(bindings: Record<string, unknown>): Logger;
}

interface StartupBannerLink { label: string; url: string }
interface StartupBannerOptions {
  name?: string;        // default: "DaloyJS"
  version?: string;
  url: string;
  runtime?: string;     // e.g. "Node.js", "Bun"
  links?: StartupBannerLink[];
  color?: boolean;
  ascii?: boolean;
}

formatStartupBanner(opts: StartupBannerOptions): string;
printStartupBanner(opts: StartupBannerOptions): void;

type BehindProxyConfig = "none" | "loopback" | { hops: number } | { cidrs: readonly string[] };
interface ConnInfo { remoteAddress?: string; remotePort?: number; tls?: boolean }

getConnInfo(req: Request): ConnInfo | undefined;
setConnInfo(req: Request, info: ConnInfo): void;   // adapter helper
assertBehindProxy(cfg: BehindProxyConfig | undefined): void;
resolveClientIp(ctx, cfg?: BehindProxyConfig): string | undefined;
readRemoteAddress(ctx): string | undefined;
readRemotePort(ctx): number | undefined;
pickForwardedForByHops(header: string, hops: number): string | undefined;

// Spoof-resistant client IP: reads `hops` entries from the RIGHT of
// X-Forwarded-For (the slots your own proxy chain wrote). Falls back to
// X-Real-IP only when hops === 1; past that a chain shorter than the
// declaration yields undefined rather than a caller-settable header.
resolveForwardedClientIp(req: Request, hops?: number): string | undefined;

subdomains(hostname: string, opts?: SubdomainsOptions): SubdomainsResult;

interface SubdomainsOptions {
  baseDomain?: string;                 // pin the registrable base; skips the PSL entirely
  extraSuffixes?: readonly string[];   // extra shared-hosting suffixes
  production?: boolean;                // default: false; throws on a stale PSL snapshot
}

interface SubdomainsResult {
  baseDomain: string;                  // e.g. "example.co.uk"
  subdomain: string;                   // e.g. "api.tenant"; "" when none
  labels: readonly string[];           // e.g. ["api", "tenant"]
}

const PSL_SNAPSHOT_DATE: string;       // ISO date of the bundled PSL snapshot
const MAX_SNAPSHOT_AGE_DAYS: number;   // 90; refuses to use a stale snapshot
const PSL_PUBLIC_SUFFIXES: readonly string[];

// The staleness check applies only to the PSL path. A call with baseDomain
// never reads the snapshot, so baseDomain + production: true always works.