@hivemagnus/hive-common 0.0.0-stage → 0.1.0

package/dist/events/index.js

@@ -0,0 +1,232 @@
+/**
+ * HiveEvent feeds and the ChatterMost notifier. The HiveEvent schema and validator live in
+ * `/contracts` (isomorphic); this module re-exports them.
+ */
+import { validateHiveEvent, } from '../contracts/index.js';
+import { HiveError } from '../errors/index.js';
+import { endpointProblem } from '../oathweave/endpoint.js';
+import { redactText } from '../log/redact.js';
+export { HIVE_EVENT_LIMITS, HIVE_EVENT_SEVERITIES, HIVE_EVENT_VERSION, isHiveEvent, validateHiveEvent, validateHiveEventPage, } from '../contracts/index.js';
+// ---------------------------------------------------------------------------------------
+// Feed: GET /v1/hive/events?after=<cursor>&limit=<n>
+export const HIVE_EVENTS_PATH = '/v1/hive/events';
+/** Read `after` and `limit` from a query. Throws a 400 HiveError on malformed values. */
+export function parseFeedQuery(query, options = {}) {
+    const read = (name) => {
+        if (query instanceof URLSearchParams) {
+            const values = query.getAll(name);
+            if (values.length > 1)
+                throw new HiveError('invalid_query', `${name} must be given once`, { status: 400 });
+            return values[0];
+        }
+        const value = query[name];
+        if (Array.isArray(value)) {
+            if (value.length > 1)
+                throw new HiveError('invalid_query', `${name} must be given once`, { status: 400 });
+            return value[0];
+        }
+        return value;
+    };
+    const defaultLimit = options.defaultLimit ?? 50;
+    const maxLimit = options.maxLimit ?? 200;
+    const rawLimit = read('limit');
+    let limit = defaultLimit;
+    if (rawLimit !== undefined && rawLimit !== '') {
+        if (!/^\d{1,6}$/.test(rawLimit) || Number(rawLimit) < 1) {
+            throw new HiveError('invalid_query', `limit must be an integer from 1 to ${maxLimit}`, { status: 400 });
+        }
+        limit = Math.min(Number(rawLimit), maxLimit);
+    }
+    const after = read('after');
+    if (after !== undefined && after !== '' && !/^[A-Za-z0-9._~:-]{1,512}$/.test(after)) {
+        throw new HiveError('invalid_query', 'after must be a cursor from a previous page', { status: 400 });
+    }
+    return { after: after || undefined, limit };
+}
+/**
+ * Build a feed page. Pass up to `limit + 1` items read after the cursor, in feed order; the
+ * extra item only tells whether there is a next page and is not returned.
+ */
+export function feedPage(items, limit, cursorOf) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new RangeError('limit must be a positive integer');
+    const data = items.slice(0, limit);
+    const last = data.at(-1);
+    return { data, nextCursor: items.length > limit && last !== undefined ? cursorOf(last) : null };
+}
+/** Encode a cursor position as an opaque base64url string. Isomorphic. */
+export function encodeCursor(position) {
+    const bytes = new TextEncoder().encode(JSON.stringify(position));
+    let binary = '';
+    bytes.forEach(byte => { binary += String.fromCharCode(byte); });
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Decode a cursor from `encodeCursor()`. Throws a 400 HiveError when it was tampered with. */
+export function decodeCursor(cursor) {
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(cursor))
+            throw new Error('not base64url');
+        const binary = atob(cursor.replace(/-/g, '+').replace(/_/g, '/'));
+        const value = JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, char => char.charCodeAt(0))));
+        if (!value || typeof value !== 'object' || Array.isArray(value)
+            || !Object.values(value).every(item => typeof item === 'string' || typeof item === 'number'))
+            throw new Error('not a position');
+        return value;
+    }
+    catch {
+        throw new HiveError('invalid_cursor', 'The cursor is not valid', { status: 400 });
+    }
+}
+/** An in-memory DedupeStore with TTL and a size bound. Per process only. */
+export class MemoryDedupeStore {
+    #entries = new Map();
+    #max;
+    #now;
+    constructor(options = {}) {
+        this.#max = options.maxEntries ?? 10_000;
+        this.#now = options.now ?? Date.now;
+    }
+    claim(key, ttlMs) {
+        const now = this.#now();
+        const expiresAt = this.#entries.get(key);
+        if (expiresAt !== undefined && expiresAt > now)
+            return false;
+        this.#entries.delete(key);
+        if (this.#entries.size >= this.#max) {
+            for (const [entry, expiry] of this.#entries)
+                if (expiry <= now)
+                    this.#entries.delete(entry);
+            while (this.#entries.size >= this.#max)
+                this.#entries.delete(this.#entries.keys().next().value);
+        }
+        this.#entries.set(key, now + ttlMs);
+        return true;
+    }
+    release(key) {
+        this.#entries.delete(key);
+    }
+    get size() {
+        return this.#entries.size;
+    }
+}
+const SEVERITY_ICON = {
+    info: ':information_source:',
+    warning: ':warning:',
+    critical: ':rotating_light:',
+};
+/** Neutralise Markdown and mentions in event text so a product cannot ping a channel or forge links. */
+function escapeMarkdown(value) {
+    return value
+        .replace(/[\\`*_~[\]()#>|]/g, char => `\\${char}`)
+        .replace(/@(?=[A-Za-z0-9])/g, '@​')
+        .replace(/<!/g, '<​!');
+}
+/** The default message: severity icon, product and title, summary, and a link. */
+export function formatChatterMostMessage(event, options = {}) {
+    const title = `${SEVERITY_ICON[event.severity]} **${escapeMarkdown(event.product)}: ${escapeMarkdown(event.title)}**`;
+    const summary = event.summary ? `\n${escapeMarkdown(event.summary)}` : '';
+    let link = '';
+    if (options.linkBaseUrl) {
+        const url = new URL(event.link.path, options.linkBaseUrl);
+        link = `\n[Open in ${escapeMarkdown(event.link.product)}](${url.href.replace(/[()]/g, encodeURIComponent)})`;
+    }
+    else
+        link = `\n${escapeMarkdown(event.link.product)}: \`${event.link.path.replace(/`/g, '')}\``;
+    return `${title}${summary}${link}`.slice(0, 16_000);
+}
+function retryAfterMs(response) {
+    const value = response.headers.get('retry-after');
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+/**
+ * Posts HiveEvents to a Mattermost-compatible incoming webhook (ChatterMost). One-way
+ * announcements only. Each event ID is delivered at most once per dedupe window; failures
+ * release the claim so a later call can retry.
+ */
+export class ChatterMostNotifier {
+    #options;
+    #fetch;
+    #dedupe;
+    #sleep;
+    #random;
+    constructor(options) {
+        const problem = endpointProblem(options.webhookUrl, { allowInsecureLoopback: options.allowInsecureLoopback ?? false });
+        // The URL is a secret, so the error describes the problem without echoing it.
+        if (problem)
+            throw new TypeError(`ChatterMost webhookUrl ${problem}`);
+        if (options.linkBaseUrl !== undefined && endpointProblem(options.linkBaseUrl, { allowInsecureLoopback: true })) {
+            throw new TypeError('ChatterMost linkBaseUrl must be an https origin');
+        }
+        this.#options = options;
+        this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+        this.#dedupe = options.dedupe ?? new MemoryDedupeStore();
+        this.#sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+        this.#random = options.random ?? Math.random;
+    }
+    /** The webhook body for an event. */
+    payload(event) {
+        if (this.#options.format)
+            return this.#options.format(event);
+        return {
+            text: formatChatterMostMessage(event, this.#options.linkBaseUrl ? { linkBaseUrl: this.#options.linkBaseUrl } : {}),
+            ...(this.#options.username ? { username: this.#options.username } : {}),
+            ...(this.#options.iconUrl ? { icon_url: this.#options.iconUrl } : {}),
+            ...(this.#options.channel ? { channel: this.#options.channel } : {}),
+            props: { hive_event: { id: event.id, product: event.product, type: event.type, severity: event.severity } },
+        };
+    }
+    /** Validate and deliver one event. Never throws for delivery failures; it reports them. */
+    async notify(input) {
+        const validation = validateHiveEvent(input);
+        if (!validation.ok)
+            throw HiveError.validation('The event is not a valid HiveEvent', validation.issues);
+        const event = validation.value;
+        const key = `hive-event:${event.product}:${event.id}`;
+        if (!await this.#dedupe.claim(key, this.#options.dedupeTtlMs ?? 24 * 60 * 60_000))
+            return { status: 'duplicate', attempts: 0 };
+        const body = JSON.stringify(this.payload(event));
+        const retries = this.#options.retries ?? 3;
+        const base = this.#options.backoffMs ?? 500;
+        const max = this.#options.maxBackoffMs ?? 8_000;
+        let lastError = 'failed';
+        let lastStatus;
+        let attempts = 0;
+        for (let attempt = 1; attempt <= retries + 1; attempt++) {
+            attempts = attempt;
+            let wait;
+            try {
+                const response = await this.#fetch(this.#options.webhookUrl, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body,
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(this.#options.timeoutMs ?? 5_000),
+                });
+                void response.body?.cancel().catch(() => undefined);
+                if (response.ok)
+                    return { status: 'sent', attempts: attempt };
+                lastStatus = response.status;
+                lastError = `HTTP ${response.status}`;
+                // Other 4xx mean the request itself is wrong; repeating it cannot help.
+                if (response.status !== 408 && response.status !== 429 && response.status < 500)
+                    break;
+                wait = retryAfterMs(response);
+            }
+            catch (error) {
+                lastStatus = undefined;
+                lastError = error instanceof Error && error.name === 'TimeoutError' ? 'timeout' : 'network error';
+            }
+            if (attempt <= retries) {
+                const backoff = Math.min(max, base * 2 ** (attempt - 1));
+                await this.#sleep(Math.min(max, wait ?? Math.round(backoff * (0.5 + this.#random() / 2))));
+            }
+        }
+        await this.#dedupe.release(key);
+        return { status: 'failed', attempts, error: redactText(lastError), ...(lastStatus !== undefined ? { httpStatus: lastStatus } : {}) };
+    }
+}

package/dist/health/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `/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>>;
+}
+export interface HealthOptions {
+    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;
+}
+/** The liveness response: 200 whenever the process can answer. It never runs checks. */
+export declare function liveness(options?: HealthOptions): HealthResponse<LiveBody>;
+/** Run every check concurrently and build the readiness response: 503 if a critical check is down. */
+export declare function readiness(options?: HealthOptions): 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[]>>;
+export interface Health {
+    live(): HealthResponse<LiveBody>;
+    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<LiveBody | ReadyBody>> | undefined;
+    readonly paths: Readonly<Record<HealthKind, readonly string[]>>;
+}
+/** Bind options once and serve both endpoints. */
+export declare function createHealth(options?: HealthOptions): Health;

package/dist/health/index.js

@@ -0,0 +1,113 @@
+/**
+ * `/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 } : {}) };
+}
+/** The liveness response: 200 whenever the process can answer. It never runs checks. */
+export function liveness(options = {}) {
+    const now = options.now ?? Date.now;
+    return { status: 200, body: { status: 'live', ...identity(options), time: new Date(now()).toISOString() }, 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 = {}) {
+    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,64 @@
+/**
+ * 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 } 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). */
+export declare function registerHealthRoutes<E extends Env>(app: Hono<E>, options?: HealthOptions): void;

package/dist/hono/index.js

@@ -0,0 +1,105 @@
+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). */
+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;