@hivemagnus/hive-common 0.0.0-stage → 0.2.0

package/dist/health/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `/health/live` and `/health/ready` responses with named, time-limited dependency checks.
+ * Framework-free: adapters in `/hono` and `/node-http` serve these.
+ */
+export declare const HEALTH_PATHS: {
+    readonly live: "/health/live";
+    readonly ready: "/health/ready";
+};
+/** Paths products used before the suite standard. Serve them only while clients still call them. */
+export declare const LEGACY_HEALTH_ALIASES: Readonly<Record<HealthKind, readonly string[]>>;
+export type HealthKind = 'live' | 'ready';
+export type CheckStatus = 'up' | 'down';
+/** What a check function may return. Throwing, `false` or `{ ok: false }` all mean down. */
+export type CheckOutcome = void | boolean | {
+    readonly ok?: boolean;
+    readonly details?: Readonly<Record<string, unknown>>;
+};
+export interface HealthCheck {
+    /** Shown in the response, for example `database` or `oathweave`. */
+    readonly name: string;
+    /** Receives a signal that aborts at the timeout; pass it to fetch and database calls. */
+    readonly check: (signal: AbortSignal) => CheckOutcome | Promise<CheckOutcome>;
+    /** Milliseconds before the check counts as down. Defaults to the readiness default. */
+    readonly timeoutMs?: number;
+    /** A non-critical check that fails makes the service `degraded`, still 200. Defaults to true. */
+    readonly critical?: boolean;
+}
+export interface CheckReport {
+    readonly status: CheckStatus;
+    readonly critical: boolean;
+    readonly latencyMs: number;
+    /** `timeout` or `failed`, or the error message when `exposeErrors` is on. */
+    readonly error?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+export interface LiveBody {
+    readonly status: 'live';
+    readonly service?: string;
+    readonly version?: string;
+    readonly time: string;
+}
+export interface ReadyBody {
+    readonly status: 'ready' | 'degraded' | 'not_ready';
+    readonly service?: string;
+    readonly version?: string;
+    readonly time: string;
+    readonly checks: Readonly<Record<string, CheckReport>>;
+}
+export interface HealthResponse<B> {
+    readonly status: 200 | 503;
+    readonly body: B;
+    readonly headers: Readonly<Record<string, string>>;
+}
+/**
+ * A product's own liveness body, in place of the standard `LiveBody`: an object served as is,
+ * or a function called on every liveness request with the standard body.
+ */
+export type LiveBodyOverride<L extends object> = L | ((standard: LiveBody) => L);
+/** `L` is the liveness body type: `LiveBody` unless `liveBody` is set. */
+export interface HealthOptions<L extends object = LiveBody> {
+    readonly service?: string;
+    readonly version?: string;
+    readonly checks?: readonly HealthCheck[];
+    /** Default per-check timeout. 2000 ms. */
+    readonly timeoutMs?: number;
+    /**
+     * Include error messages from failing checks. Off by default: readiness is often reachable
+     * without authentication, and error messages can name internal hosts.
+     */
+    readonly exposeErrors?: boolean;
+    /** Also serve the legacy paths in `LEGACY_HEALTH_ALIASES`, or a custom alias map. */
+    readonly aliases?: boolean | Partial<Readonly<Record<HealthKind, readonly string[]>>>;
+    readonly now?: () => number;
+    /**
+     * Serve this body from `/health/live` instead of the standard one, for a product that keeps
+     * a published liveness body such as `{ status: 'ok' }`. The status (200) and headers are
+     * unchanged, and liveness still never runs checks. Readiness is not affected.
+     */
+    readonly liveBody?: LiveBodyOverride<L>;
+}
+/**
+ * The liveness response: 200 whenever the process can answer. It never runs checks. The body
+ * is the standard `LiveBody`, or the product's own when `liveBody` is set.
+ */
+export declare function liveness<L extends object = LiveBody>(options?: HealthOptions<L>): HealthResponse<L>;
+/** Run every check concurrently and build the readiness response: 503 if a critical check is down. */
+export declare function readiness(options?: HealthOptions<object>): Promise<HealthResponse<ReadyBody>>;
+/** Which health endpoint a path names, including legacy aliases when enabled. */
+export declare function resolveHealthPath(pathname: string, aliases?: HealthOptions['aliases']): HealthKind | undefined;
+/** All paths served for each kind, standard first. */
+export declare function healthPaths(aliases?: HealthOptions['aliases']): Readonly<Record<HealthKind, readonly string[]>>;
+/** `L` is the liveness body type: `LiveBody` unless `liveBody` was set. */
+export interface Health<L extends object = LiveBody> {
+    live(): HealthResponse<L>;
+    ready(): Promise<HealthResponse<ReadyBody>>;
+    /** The response for a health path, or undefined when the path is not a health path. */
+    handle(pathname: string): Promise<HealthResponse<L | ReadyBody>> | undefined;
+    readonly paths: Readonly<Record<HealthKind, readonly string[]>>;
+}
+/** Bind options once and serve both endpoints. */
+export declare function createHealth<L extends object = LiveBody>(options?: HealthOptions<L>): Health<L>;

package/dist/health/index.js

@@ -0,0 +1,126 @@
+/**
+ * `/health/live` and `/health/ready` responses with named, time-limited dependency checks.
+ * Framework-free: adapters in `/hono` and `/node-http` serve these.
+ */
+export const HEALTH_PATHS = { live: '/health/live', ready: '/health/ready' };
+/** Paths products used before the suite standard. Serve them only while clients still call them. */
+export const LEGACY_HEALTH_ALIASES = {
+    live: ['/health', '/healthz', '/livez', '/live', '/api/health'],
+    ready: ['/ready', '/readyz'],
+};
+const HEADERS = { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' };
+function identity(options) {
+    return { ...(options.service ? { service: options.service } : {}), ...(options.version ? { version: options.version } : {}) };
+}
+function assertLiveBody(value) {
+    if (value !== undefined && typeof value !== 'function' && (typeof value !== 'object' || value === null || Array.isArray(value))) {
+        throw new TypeError('liveBody must be an object or a function');
+    }
+}
+/**
+ * The liveness response: 200 whenever the process can answer. It never runs checks. The body
+ * is the standard `LiveBody`, or the product's own when `liveBody` is set.
+ */
+export function liveness(options = {}) {
+    assertLiveBody(options.liveBody);
+    const now = options.now ?? Date.now;
+    const standard = { status: 'live', ...identity(options), time: new Date(now()).toISOString() };
+    const custom = options.liveBody;
+    const body = custom === undefined ? standard : typeof custom === 'function' ? custom(standard) : { ...custom };
+    return { status: 200, body: body, headers: HEADERS };
+}
+class CheckTimeout extends Error {
+}
+async function runCheck(check, defaultTimeout, exposeErrors, now) {
+    const critical = check.critical ?? true;
+    const timeoutMs = check.timeoutMs ?? defaultTimeout;
+    const controller = new AbortController();
+    const started = now();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort(new CheckTimeout('timeout'));
+            reject(new CheckTimeout('timeout'));
+        }, timeoutMs);
+    });
+    try {
+        const outcome = await Promise.race([Promise.resolve().then(() => check.check(controller.signal)), timeout]);
+        const latencyMs = Math.max(0, now() - started);
+        const ok = outcome === undefined || outcome === true || (typeof outcome === 'object' && outcome !== null && outcome.ok !== false);
+        const details = typeof outcome === 'object' && outcome !== null ? outcome.details : undefined;
+        return { status: ok ? 'up' : 'down', critical, latencyMs, ...(ok ? {} : { error: 'failed' }), ...(details ? { details } : {}) };
+    }
+    catch (error) {
+        const latencyMs = Math.max(0, now() - started);
+        const reason = error instanceof CheckTimeout ? 'timeout' : exposeErrors && error instanceof Error && error.message ? error.message.slice(0, 300) : 'failed';
+        return { status: 'down', critical, latencyMs, error: reason };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Run every check concurrently and build the readiness response: 503 if a critical check is down. */
+export async function readiness(options = {}) {
+    const now = options.now ?? Date.now;
+    const checks = options.checks ?? [];
+    const names = new Set();
+    for (const check of checks) {
+        if (!check.name || names.has(check.name))
+            throw new Error(`Health check names must be unique and non-empty: ${check.name}`);
+        names.add(check.name);
+    }
+    const reports = await Promise.all(checks.map(check => runCheck(check, options.timeoutMs ?? 2000, options.exposeErrors ?? false, now)));
+    const byName = {};
+    checks.forEach((check, index) => { byName[check.name] = reports[index]; });
+    const criticalDown = reports.some(report => report.status === 'down' && report.critical);
+    const anyDown = reports.some(report => report.status === 'down');
+    const status = criticalDown ? 'not_ready' : anyDown ? 'degraded' : 'ready';
+    return {
+        status: criticalDown ? 503 : 200,
+        body: { status, ...identity(options), time: new Date(now()).toISOString(), checks: byName },
+        headers: HEADERS,
+    };
+}
+/** Which health endpoint a path names, including legacy aliases when enabled. */
+export function resolveHealthPath(pathname, aliases = false) {
+    const path = pathname.length > 1 ? pathname.replace(/\/+$/, '') : pathname;
+    if (path === HEALTH_PATHS.live)
+        return 'live';
+    if (path === HEALTH_PATHS.ready)
+        return 'ready';
+    const map = aliasMap(aliases);
+    if (map.live.includes(path))
+        return 'live';
+    if (map.ready.includes(path))
+        return 'ready';
+    return undefined;
+}
+/** All paths served for each kind, standard first. */
+export function healthPaths(aliases = false) {
+    const map = aliasMap(aliases);
+    return { live: [HEALTH_PATHS.live, ...map.live], ready: [HEALTH_PATHS.ready, ...map.ready] };
+}
+function aliasMap(aliases) {
+    if (aliases === true)
+        return { live: LEGACY_HEALTH_ALIASES.live, ready: LEGACY_HEALTH_ALIASES.ready };
+    if (!aliases)
+        return { live: [], ready: [] };
+    return { live: aliases.live ?? [], ready: aliases.ready ?? [] };
+}
+/** Bind options once and serve both endpoints. */
+export function createHealth(options = {}) {
+    assertLiveBody(options.liveBody);
+    return {
+        live: () => liveness(options),
+        ready: () => readiness(options),
+        handle(pathname) {
+            const kind = resolveHealthPath(pathname, options.aliases);
+            if (kind === 'live')
+                return Promise.resolve(liveness(options));
+            if (kind === 'ready')
+                return readiness(options);
+            return undefined;
+        },
+        paths: healthPaths(options.aliases),
+    };
+}

package/dist/hono/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Hono adapters: request context, Oathweave auth, the error envelope and health routes.
+ * `hono` is an optional peer dependency (>= 4.13.18).
+ *
+ *   const app = new Hono<HiveEnv>();
+ *   app.use(requestContext());
+ *   registerHealthRoutes(app, { checks });
+ *   app.use('/v1/*', oathweaveAuth(verifier));
+ *   app.onError(errorHandler({ logger }));
+ *   app.notFound(notFoundHandler());
+ */
+import type { Context, Env, ErrorHandler, Hono, MiddlewareHandler, NotFoundHandler } from 'hono';
+import { type CreateRequestContextOptions, type RequestContext } from '../context/index.js';
+import { type HealthOptions, type LiveBody } from '../health/index.js';
+import type { Logger } from '../log/index.js';
+import type { AcceptPrincipal, OathweavePrincipal } from '../oathweave/claims.js';
+import { type PermissionOptions } from '../oathweave/links.js';
+import type { OathweaveVerifier } from '../oathweave/verifier.js';
+/** Context variables set by these middlewares. Use `new Hono<HiveEnv>()` or extend it. */
+export interface HiveVariables {
+    hiveContext: RequestContext;
+    hivePrincipal: OathweavePrincipal;
+}
+export interface HiveEnv extends Env {
+    Variables: HiveVariables;
+}
+/** The request context set by `requestContext()`, or undefined. */
+export declare function getHiveContext(c: Context): RequestContext | undefined;
+/** The verified principal set by `oathweaveAuth()`, or undefined. */
+export declare function getPrincipal(c: Context): OathweavePrincipal | undefined;
+/** The verified principal, or a 401 when the route was not authenticated. */
+export declare function requirePrincipal(c: Context): OathweavePrincipal;
+export interface RequestContextMiddlewareOptions extends CreateRequestContextOptions {
+    /** Echo the request ID as `x-request-id` on the response. Defaults to true. */
+    readonly responseHeader?: boolean;
+}
+/** Create the request context, run the rest of the request inside it and echo `x-request-id`. */
+export declare function requestContext(options?: RequestContextMiddlewareOptions): MiddlewareHandler;
+export interface OathweaveAuthOptions {
+    /** Which principals this route accepts. Defaults to the verifier's default. */
+    readonly accept?: AcceptPrincipal;
+    /** When false, a request without credentials passes with no principal; a bad token still fails. */
+    readonly required?: boolean;
+    /** Further checks after verification, such as an identity-link lookup. Throw to refuse. */
+    readonly authorize?: (principal: OathweavePrincipal, c: Context) => void | Promise<void>;
+}
+/** Verify `Authorization: Bearer` with Oathweave and set `hivePrincipal`. Failures throw OathweaveError. */
+export declare function oathweaveAuth(verifier: OathweaveVerifier, options?: OathweaveAuthOptions): MiddlewareHandler;
+/** Require every listed permission (403 otherwise). Must follow `oathweaveAuth()`. */
+export declare function requirePermission(permissions: readonly string[], options?: PermissionOptions): MiddlewareHandler;
+/** Require at least one listed role (403 otherwise). Must follow `oathweaveAuth()`. */
+export declare function requireRole(roles: readonly string[]): MiddlewareHandler;
+/** Require every listed scope (403 otherwise). Must follow `oathweaveAuth()`. */
+export declare function requireScope(scopes: readonly string[]): MiddlewareHandler;
+export interface ErrorHandlerOptions {
+    /** Unexpected errors (not HiveError) are logged here at error level. */
+    readonly logger?: Pick<Logger, 'error'>;
+}
+/** `app.onError(errorHandler())`: HiveError → envelope; everything else → generic 500, logged. */
+export declare function errorHandler(options?: ErrorHandlerOptions): ErrorHandler;
+/** `app.notFound(notFoundHandler())`: a 404 envelope. */
+export declare function notFoundHandler(): NotFoundHandler;
+/**
+ * Serve `/health/live`, `/health/ready` and any aliases on `app` (GET and HEAD). Set
+ * `liveBody` to keep a product's published liveness body.
+ */
+export declare function registerHealthRoutes<E extends Env, L extends object = LiveBody>(app: Hono<E>, options?: HealthOptions<L>): void;

package/dist/hono/index.js

@@ -0,0 +1,108 @@
+import { HTTPException } from 'hono/http-exception';
+import { createRequestContext, runWithRequestContext, } from '../context/index.js';
+import { defaultCodeForStatus, defaultMessageForStatus, HiveError, toErrorResponse } from '../errors/index.js';
+import { createHealth } from '../health/index.js';
+import { OathweaveError } from '../oathweave/errors.js';
+import { hasAnyRole, hasScopes, requirePermissions } from '../oathweave/links.js';
+/** The request context set by `requestContext()`, or undefined. */
+export function getHiveContext(c) {
+    return c.get('hiveContext');
+}
+/** The verified principal set by `oathweaveAuth()`, or undefined. */
+export function getPrincipal(c) {
+    return c.get('hivePrincipal');
+}
+/** The verified principal, or a 401 when the route was not authenticated. */
+export function requirePrincipal(c) {
+    const principal = getPrincipal(c);
+    if (!principal)
+        throw new OathweaveError('missing_token');
+    return principal;
+}
+/** Create the request context, run the rest of the request inside it and echo `x-request-id`. */
+export function requestContext(options = {}) {
+    return async (c, next) => {
+        const context = createRequestContext(name => c.req.header(name), options);
+        c.set('hiveContext', context);
+        await runWithRequestContext(context, next);
+        if (options.responseHeader ?? true)
+            c.header('x-request-id', context.requestId);
+    };
+}
+/** Verify `Authorization: Bearer` with Oathweave and set `hivePrincipal`. Failures throw OathweaveError. */
+export function oathweaveAuth(verifier, options = {}) {
+    return async (c, next) => {
+        const header = c.req.header('authorization');
+        if (!header && options.required === false) {
+            await next();
+            return;
+        }
+        const principal = await verifier.verifyAuthorization(header, options.accept ? { accept: options.accept } : {});
+        await options.authorize?.(principal, c);
+        c.set('hivePrincipal', principal);
+        const context = getHiveContext(c);
+        if (context)
+            context.principal = principal;
+        await next();
+    };
+}
+/** Require every listed permission (403 otherwise). Must follow `oathweaveAuth()`. */
+export function requirePermission(permissions, options = {}) {
+    return async (c, next) => {
+        requirePermissions(requirePrincipal(c), permissions, options);
+        await next();
+    };
+}
+/** Require at least one listed role (403 otherwise). Must follow `oathweaveAuth()`. */
+export function requireRole(roles) {
+    return async (c, next) => {
+        if (!hasAnyRole(requirePrincipal(c), roles))
+            throw new OathweaveError('insufficient_permission', { details: { roles: [...roles] } });
+        await next();
+    };
+}
+/** Require every listed scope (403 otherwise). Must follow `oathweaveAuth()`. */
+export function requireScope(scopes) {
+    return async (c, next) => {
+        if (!hasScopes(requirePrincipal(c), scopes))
+            throw new OathweaveError('insufficient_permission', { details: { scopes: [...scopes] } });
+        await next();
+    };
+}
+function respond(c, error, options) {
+    const requestId = getHiveContext(c)?.requestId;
+    let value = error;
+    // Hono's own HTTPException (body limits, bad JSON, etc.) keeps its status with a standard code.
+    if (!HiveError.is(error) && error instanceof HTTPException && error.status >= 400 && error.status <= 599) {
+        const message = error.status >= 500 || !error.message ? defaultMessageForStatus(error.status) : error.message;
+        value = new HiveError(defaultCodeForStatus(error.status), message, { status: error.status, cause: error });
+    }
+    const response = toErrorResponse(value, {
+        requestId,
+        onUnexpected: unexpected => options.logger?.error('unhandled error', { err: unexpected, path: c.req.path, method: c.req.method }),
+    });
+    return new Response(JSON.stringify(response.body), { status: response.status, headers: response.headers });
+}
+/** `app.onError(errorHandler())`: HiveError → envelope; everything else → generic 500, logged. */
+export function errorHandler(options = {}) {
+    return (error, c) => respond(c, error, options);
+}
+/** `app.notFound(notFoundHandler())`: a 404 envelope. */
+export function notFoundHandler() {
+    return c => respond(c, HiveError.notFound(), {});
+}
+/**
+ * Serve `/health/live`, `/health/ready` and any aliases on `app` (GET and HEAD). Set
+ * `liveBody` to keep a product's published liveness body.
+ */
+export function registerHealthRoutes(app, options = {}) {
+    const health = createHealth(options);
+    const serve = (kind) => async (c) => {
+        const result = kind === 'live' ? health.live() : await health.ready();
+        return new Response(c.req.method === 'HEAD' ? null : JSON.stringify(result.body), { status: result.status, headers: result.headers });
+    };
+    for (const path of health.paths.live)
+        app.get(path, serve('live'));
+    for (const path of health.paths.ready)
+        app.get(path, serve('ready'));
+}

package/dist/log/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A small structured JSON logger. One line per entry, secrets redacted, and the current
+ * request ID and trace ID added automatically from the request context.
+ */
+import { type RequestContext } from '../context/index.js';
+export { redact, redactHeaders, redactText, isSensitiveKey, REDACTED, type RedactOptions } from './redact.js';
+export declare const LOG_LEVELS: readonly ["trace", "debug", "info", "warn", "error", "fatal"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+export type LogFields = Readonly<Record<string, unknown>>;
+export interface Logger {
+    trace(message: string, fields?: LogFields): void;
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    fatal(message: string, fields?: LogFields): void;
+    /** A logger that adds `bindings` to every line. */
+    child(bindings: LogFields): Logger;
+    isLevelEnabled(level: LogLevel): boolean;
+    readonly level: LogLevel | 'silent';
+}
+export interface LoggerOptions {
+    /** Minimum level written. Defaults to `LOG_LEVEL` when valid, else `info`. */
+    readonly level?: LogLevel | 'silent';
+    /** Fields on every line, such as `{ service: 'hivemem' }`. */
+    readonly bindings?: LogFields;
+    /** Where lines go. Defaults to `process.stdout.write` with a trailing newline. */
+    readonly write?: (line: string) => void;
+    /** Redact secrets. On by default; turn off only for trusted, already-clean fields. */
+    readonly redact?: boolean;
+    /** Extra keys to redact. */
+    readonly redactKeys?: readonly string[];
+    /** Include `err.stack` for Error fields. Off by default. */
+    readonly stacks?: boolean;
+    readonly now?: () => number;
+    /** Where the request context comes from. Defaults to the AsyncLocalStorage context. */
+    readonly context?: () => RequestContext | undefined;
+}
+export declare function createLogger(options?: LoggerOptions): Logger;

package/dist/log/index.js

@@ -0,0 +1,80 @@
+/**
+ * A small structured JSON logger. One line per entry, secrets redacted, and the current
+ * request ID and trace ID added automatically from the request context.
+ */
+import { getRequestContext } from '../context/index.js';
+import { redact } from './redact.js';
+export { redact, redactHeaders, redactText, isSensitiveKey, REDACTED } from './redact.js';
+export const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+const SEVERITY = { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60, silent: 100 };
+function defaultLevel() {
+    const value = typeof process !== 'undefined' ? process.env['LOG_LEVEL']?.toLowerCase() : undefined;
+    return LOG_LEVELS.includes(value) ? value : 'info';
+}
+function serializeErrors(fields, stacks) {
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (value instanceof Error) {
+            const code = value.code;
+            const status = value.status;
+            result[key] = {
+                name: value.name,
+                message: value.message,
+                ...(typeof code === 'string' || typeof code === 'number' ? { code } : {}),
+                ...(typeof status === 'number' ? { status } : {}),
+                ...(stacks && value.stack ? { stack: value.stack } : {}),
+            };
+        }
+        else
+            result[key] = value;
+    }
+    return result;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value, (_key, item) => (typeof item === 'bigint' ? item.toString() : item));
+    }
+    catch {
+        return JSON.stringify({ level: 'error', msg: 'log entry could not be serialised' });
+    }
+}
+export function createLogger(options = {}) {
+    const level = options.level ?? defaultLevel();
+    const threshold = SEVERITY[level];
+    const write = options.write ?? ((line) => { process.stdout.write(`${line}\n`); });
+    const shouldRedact = options.redact ?? true;
+    const now = options.now ?? Date.now;
+    const context = options.context ?? getRequestContext;
+    const bindings = options.bindings ?? {};
+    const emit = (entryLevel, message, fields) => {
+        if (SEVERITY[entryLevel] < threshold)
+            return;
+        const current = context();
+        const merged = {
+            ...bindings,
+            ...(current ? current.bindings : {}),
+            ...serializeErrors({ ...fields }, options.stacks ?? false),
+        };
+        // Reserved fields win over bindings so a caller cannot forge them.
+        const entry = {
+            ...(shouldRedact ? redact(merged, { keys: options.redactKeys ?? [] }) : merged),
+            time: new Date(now()).toISOString(),
+            level: entryLevel,
+            msg: shouldRedact ? redact(message) : message,
+            ...(current ? { requestId: current.requestId, traceId: current.trace.traceId } : {}),
+        };
+        write(safeStringify(entry));
+    };
+    const logger = {
+        level,
+        trace: (message, fields) => emit('trace', message, fields),
+        debug: (message, fields) => emit('debug', message, fields),
+        info: (message, fields) => emit('info', message, fields),
+        warn: (message, fields) => emit('warn', message, fields),
+        error: (message, fields) => emit('error', message, fields),
+        fatal: (message, fields) => emit('fatal', message, fields),
+        child: childBindings => createLogger({ ...options, level, bindings: { ...bindings, ...childBindings } }),
+        isLevelEnabled: candidate => SEVERITY[candidate] >= threshold,
+    };
+    return logger;
+}

package/dist/log/redact.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Secret redaction for logs and diagnostics. Follows the suite pattern (secret-looking keys
+ * are masked, strings are scrubbed of credentials) and adds headers, JWTs, URL credentials,
+ * provider token formats and cycle-safe traversal.
+ */
+export declare const REDACTED = "[REDACTED]";
+/** True for a key whose value should never be logged. */
+export declare function isSensitiveKey(key: string): boolean;
+/** Scrub credentials out of free text. */
+export declare function redactText(value: string): string;
+export interface RedactOptions {
+    /** Extra keys to mask, compared case-insensitively and exactly. */
+    readonly keys?: readonly string[];
+}
+/**
+ * A deep copy of `value` with secrets masked. Sensitive keys holding strings, objects or
+ * arrays are replaced by `[REDACTED]`; numbers and booleans under such keys (token counts,
+ * `hasPassword` flags) are kept. Strings everywhere are scrubbed with `redactText()`.
+ * Errors become `{ name, message, code? }`; cycles become `[Circular]`.
+ */
+export declare function redact<T>(value: T, options?: RedactOptions): T;
+/** Mask sensitive request or response headers, keeping the others. */
+export declare function redactHeaders(headers: Readonly<Record<string, string | readonly string[] | undefined>> | Headers): Record<string, unknown>;

package/dist/log/redact.js

@@ -0,0 +1,111 @@
+/**
+ * Secret redaction for logs and diagnostics. Follows the suite pattern (secret-looking keys
+ * are masked, strings are scrubbed of credentials) and adds headers, JWTs, URL credentials,
+ * provider token formats and cycle-safe traversal.
+ */
+export const REDACTED = '[REDACTED]';
+const MAX_DEPTH = 10;
+/** Key fragments, compared after lowercasing and removing `-`, `_` and `.`. */
+const SENSITIVE_KEY_PARTS = [
+    'authorization', 'cookie', 'password', 'passwd', 'passphrase', 'secret', 'token',
+    'apikey', 'privatekey', 'accesskey', 'signingkey', 'credential', 'webhookurl', 'sessionid',
+];
+/** Keys that end in "key" but are not secret. */
+const NON_SECRET_KEYS = new Set(['publickey', 'idempotencykey', 'cachekey', 'sortkey', 'partitionkey', 'primarykey', 'foreignkey']);
+/** True for a key whose value should never be logged. */
+export function isSensitiveKey(key) {
+    const normalized = key.toLowerCase().replace(/[-_.\s]/g, '');
+    if (NON_SECRET_KEYS.has(normalized))
+        return false;
+    if (SENSITIVE_KEY_PARTS.some(part => normalized.includes(part)))
+        return true;
+    // key, apiKey, signing_key, x-api-key, keyMaterial...; not "keys", "monkey" is accepted collateral.
+    return normalized === 'key' || normalized.endsWith('key') || normalized.startsWith('keymaterial');
+}
+const TEXT_RULES = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, REDACTED],
+    // Authorization schemes.
+    [/\b(Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{4,}/gi, `$1 ${REDACTED}`],
+    // JWT / JWS compact serialisations (header.payload.signature, signature may be empty).
+    [/\beyJ[A-Za-z0-9_-]{5,}\.eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g, REDACTED],
+    // Provider key formats.
+    [/\bsk-[A-Za-z0-9_-]{12,}/g, REDACTED],
+    [/\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g, REDACTED],
+    [/\bnpm_[A-Za-z0-9]{20,}\b/g, REDACTED],
+    [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, REDACTED],
+    [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, REDACTED],
+    // Credentials in URLs.
+    [/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi, `$1${REDACTED}@`],
+    // Secret-looking query parameters and key=value / key: value pairs.
+    [/([?&](?:access_token|refresh_token|id_token|token|code|client_secret|api_key|apikey|key|password|sig|signature)=)[^&#\s]+/gi, `$1${REDACTED}`],
+    [/\b((?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|client[_-]?secret|password|passwd|private[_-]?key)["']?\s*[:=]\s*["']?)[^"',\s}&]+/gi, `$1${REDACTED}`],
+];
+/** Scrub credentials out of free text. */
+export function redactText(value) {
+    let text = value;
+    for (const [pattern, replacement] of TEXT_RULES)
+        text = text.replace(pattern, replacement);
+    return text;
+}
+/**
+ * A deep copy of `value` with secrets masked. Sensitive keys holding strings, objects or
+ * arrays are replaced by `[REDACTED]`; numbers and booleans under such keys (token counts,
+ * `hasPassword` flags) are kept. Strings everywhere are scrubbed with `redactText()`.
+ * Errors become `{ name, message, code? }`; cycles become `[Circular]`.
+ */
+export function redact(value, options = {}) {
+    const extra = new Set((options.keys ?? []).map(key => key.toLowerCase()));
+    const seen = new WeakSet();
+    const visit = (item, depth) => {
+        if (typeof item === 'string')
+            return redactText(item);
+        if (typeof item === 'bigint')
+            return item.toString();
+        if (typeof item !== 'object' || item === null)
+            return item;
+        if (seen.has(item))
+            return '[Circular]';
+        if (depth >= MAX_DEPTH)
+            return '[Truncated]';
+        seen.add(item);
+        try {
+            if (item instanceof Date)
+                return Number.isNaN(item.getTime()) ? null : item.toISOString();
+            if (item instanceof Error) {
+                const code = item.code;
+                return { name: item.name, message: redactText(item.message), ...(typeof code === 'string' || typeof code === 'number' ? { code } : {}) };
+            }
+            if (typeof item.forEach === 'function' && typeof item.entries === 'function'
+                && typeof item.get === 'function' && !(item instanceof Map)) {
+                // fetch Headers and similar.
+                const record = {};
+                item.forEach((headerValue, key) => { record[key] = headerValue; });
+                return visit(record, depth);
+            }
+            if (item instanceof Map)
+                return visit(Object.fromEntries(item), depth);
+            if (item instanceof Set)
+                return visit([...item], depth);
+            if (ArrayBuffer.isView(item) || item instanceof ArrayBuffer)
+                return `[Binary ${item.byteLength} bytes]`;
+            if (Array.isArray(item))
+                return item.map(element => visit(element, depth + 1));
+            const result = {};
+            for (const [key, child] of Object.entries(item)) {
+                const sensitive = isSensitiveKey(key) || extra.has(key.toLowerCase());
+                result[key] = sensitive && (typeof child === 'string' || (typeof child === 'object' && child !== null))
+                    ? REDACTED
+                    : visit(child, depth + 1);
+            }
+            return result;
+        }
+        finally {
+            seen.delete(item);
+        }
+    };
+    return visit(value, 0);
+}
+/** Mask sensitive request or response headers, keeping the others. */
+export function redactHeaders(headers) {
+    return redact(headers);
+}