@knowledgefutures/sdk 0.1.0 → 0.2.1

package/README.md

@@ -20,6 +20,53 @@ import { memoryStorage } from '@knowledgefutures/sdk/storage/testing'
 `createStorage(env)` builds a client from an explicit environment, such as a
 Worker's `env` when `nodejs_compat` is off.
 
+## Whistle (`kf/whistle@1`)
+
+On a Worker the console hosts, declaring `kf/whistle@1` is enough for errors:
+Whistle tails every run, so uncaught exceptions, `console.error(err)` and cron
+runs reach it with no code. Log `console.error(err)`, not `err.message`, to keep
+the stack. This entry point is for what a run can't say by itself.
+
+On Hono, one line, registered before the routes:
+
+```ts
+import { whistle } from '@knowledgefutures/sdk/whistle'
+
+app.use(whistle())
+```
+
+It records a 403, or a 401 to a request that sent an `Authorization` header,
+as `access.denied` (Whistle alerts on bursts per client and per user), and a
+successful write under `/admin` or `/api/admin` as `admin.action`, with the
+route pattern and the user. The user is `c.var.user.id` unless
+`user: (c) => …` says otherwise; `admin` sets the prefixes. On a Worker it
+also logs an error a custom `onError` turned into a 5xx, which the tail would
+otherwise never see.
+
+The rest by hand:
+
+```ts
+import { checkIn, requestFields, telemetryFromEnv } from '@knowledgefutures/sdk/whistle'
+
+const t = telemetryFromEnv(env, { waitUntil })
+t.securityEvent('auth.failed', {
+  actor: `user:${id}`,
+  outcome: 'failure',
+  ...requestFields(request),
+})
+
+// A job that isn't a Worker cron: Whistle says when it fails or stops running.
+await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { every: 1440 })
+```
+
+`captureError(err)` is for an error the app handles and doesn't log; on a
+tailed Worker, one it also logs or throws would count twice. `sentryDsn(url)`
+turns `KF_WHISTLE_URL` into a Sentry DSN, for apps that keep a Sentry SDK.
+`actor` is an id (`user:<id>`), never an email or a name, and `detail` is
+scrubbed of anything named like a credential. Events go under
+`KF_WHISTLE_PROJECT` and `KF_WHISTLE_ENVIRONMENT`, which the console and
+`kf dev` set; pass `project` and `environment` elsewhere.
+
 What a project declares and what the services give it:
 [console.knowledgefutures.org/llms.txt](https://console.knowledgefutures.org/llms.txt).
 Source: `packages/sdk/` in [knowledgefutures/kf-console](https://github.com/knowledgefutures/kf-console).

package/dist/whistle/hono.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `app.use(whistle())`: Hono middleware for what a tailed Worker's runs don't
+ * say by themselves. Typed by shape, so the SDK doesn't depend on Hono.
+ *
+ *   403s, and 401s to a request that presented a credential → `access.denied`
+ *   writes under /admin that succeed                       → `admin.action`
+ *   an error a custom onError turned into a 5xx            → console.error, for the tail
+ *
+ * The user comes from `c.var.user.id` unless `user` says otherwise.
+ */
+import { type Sink } from './index.js';
+/**
+ * The parts of Hono's Context this reads. `var` is loose so a `user` option
+ * reads the app's variables untyped; `whistle<Context<AppEnv>>()` types them.
+ */
+export interface HonoContextLike {
+    req: {
+        raw: Request;
+        method: string;
+        path: string;
+        routePath: string;
+    };
+    res: Response;
+    env: unknown;
+    error: Error | undefined;
+    var: any;
+}
+export interface WhistleOptions<C extends HonoContextLike = HonoContextLike> {
+    /** The console project key, e.g. `kf/pilot`. Default: `KF_WHISTLE_PROJECT`, which the console sets. */
+    project?: string;
+    /** Default: `KF_WHISTLE_ENVIRONMENT`, which the console sets, else `production`. */
+    environment?: string;
+    /** The signed-in user's id, if any; asked only when there's an event. Default: `c.var.user?.id`. */
+    user?: (c: C) => string | null | undefined | Promise<string | null | undefined>;
+    /** Path prefixes whose successful writes are recorded. Default `/admin`, `/api/admin`; false for none. */
+    admin?: string[] | false;
+    /** Where `KF_*` variables come from. Default: `c.env`, then `process.env`. */
+    env?: Record<string, unknown>;
+    /** Tests: where events go instead of Whistle. */
+    sink?: Sink;
+}
+export declare function whistle<C extends HonoContextLike = HonoContextLike>(options?: WhistleOptions<C>): (c: C, next: () => Promise<void>) => Promise<void>;

package/dist/whistle/hono.js

@@ -0,0 +1,89 @@
+/**
+ * `app.use(whistle())`: Hono middleware for what a tailed Worker's runs don't
+ * say by themselves. Typed by shape, so the SDK doesn't depend on Hono.
+ *
+ *   403s, and 401s to a request that presented a credential → `access.denied`
+ *   writes under /admin that succeed                       → `admin.action`
+ *   an error a custom onError turned into a 5xx            → console.error, for the tail
+ *
+ * The user comes from `c.var.user.id` unless `user` says otherwise.
+ */
+import { defined, requestFields, telemetryFromEnv } from './index.js';
+const WRITES = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const NAMES = [
+    'KF_WHISTLE_URL',
+    'KF_WHISTLE_PROJECT',
+    'KF_WHISTLE_ENVIRONMENT',
+    'KF_DEPLOYMENT_ID',
+    'KF_COMMIT',
+];
+const record = (v) => v && typeof v === 'object' ? v : undefined;
+const processEnv = () => record(globalThis.process?.env) ?? {};
+function variables(c, given) {
+    const out = {};
+    const sources = given ? [given] : [record(c.env) ?? {}, processEnv()];
+    for (const name of NAMES) {
+        const found = sources.map((s) => s[name]).find((v) => typeof v === 'string' && v);
+        if (found !== undefined)
+            out[name] = found;
+    }
+    return out;
+}
+/** `c.executionCtx` throws outside Workers. */
+function waitUntilOf(c) {
+    try {
+        const ctx = c.executionCtx;
+        return ctx ? (p) => ctx.waitUntil(p) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function defaultUser(c) {
+    const id = record(record(c.var)?.user)?.id;
+    return typeof id === 'string' || typeof id === 'number' ? String(id) : undefined;
+}
+const under = (path, prefixes) => prefixes.some((p) => path === p || path.startsWith(`${p}/`));
+let warned = false;
+export function whistle(options = {}) {
+    const admin = options.admin === false ? [] : (options.admin ?? ['/admin', '/api/admin']);
+    return async (c, next) => {
+        await next();
+        try {
+            const status = c.res.status;
+            const waitUntil = waitUntilOf(c);
+            // On a Worker the tail reads this; it drops a second copy of an error in the same run.
+            if (c.error && status >= 500 && waitUntil)
+                console.error(c.error);
+            const method = c.req.method.toUpperCase();
+            const denied = status === 403 || (status === 401 && c.req.raw.headers.has('authorization'));
+            const adminWrite = status < 400 && WRITES.has(method) && under(c.req.path, admin);
+            if (!denied && !adminWrite)
+                return;
+            const env = variables(c, options.env);
+            if (!options.project && !env.KF_WHISTLE_PROJECT) {
+                if (!warned) {
+                    warned = true;
+                    console.warn('whistle(): no project; pass { project } or redeploy through the console');
+                }
+                return;
+            }
+            const t = telemetryFromEnv(env, defined({
+                project: options.project,
+                environment: options.environment,
+                sink: options.sink,
+                waitUntil,
+            }));
+            const id = await (options.user ?? defaultUser)(c);
+            t.securityEvent(denied ? 'access.denied' : 'admin.action', {
+                ...defined({ actor: id ? `user:${id}` : undefined }),
+                ...requestFields(c.req.raw),
+                ...(denied ? { outcome: 'denied' } : {}),
+                detail: { method, route: c.req.routePath, status },
+            });
+        }
+        catch {
+            // Telemetry never breaks the request it describes.
+        }
+    };
+}

package/dist/whistle/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `@knowledgefutures/sdk/whistle` — what a project that declares
+ * `kf/whistle@1` tells Whistle beyond what its Worker's runs already say.
+ * On a Worker the console hosts, Whistle tails every run, so uncaught
+ * exceptions, `console.error(err)` and cron runs need nothing from here.
+ * This is for security events, errors the app handles without logging, and
+ * check-ins from jobs that aren't Worker crons:
+ *
+ *   app.use(whistle()) // Hono: denied requests and admin writes (hono.ts)
+ *   const t = telemetryFromEnv(env, { waitUntil })
+ *   t.securityEvent('auth.failed', { actor: `user:${id}`, ...requestFields(request) })
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { every: 1440 })
+ *
+ * With `KF_WHISTLE_URL` (the console hands it out) events go straight to
+ * Whistle; without it, to the console as JSON lines. Moved here from
+ * kf-whistle's `@kf/telemetry`, which Whistle keeps for parsing until it
+ * reads this package instead: the wire format (wire.ts) must not drift
+ * between the two.
+ */
+import { type SecurityEvent, type SecurityKind, type WireEvent } from './wire.js';
+export * from './wire.js';
+export interface Sink {
+    emit(event: WireEvent): void;
+}
+/** Workers (and anything whose stdout is collected): one JSON line per event. */
+export declare const consoleSink: Sink;
+/** Every event to each sink. */
+export declare function teeSink(...sinks: Sink[]): Sink;
+export interface WhistleTarget {
+    /** Whistle's origin, e.g. https://whistle.kfutures.org. */
+    origin: string;
+    /** The ingest key, sent as a bearer. */
+    key: string;
+}
+/** `KF_WHISTLE_URL` (`https://<instance>:<key>@<host>/`) as an origin and a key, or null. */
+export declare function parseWhistleUrl(url: string | undefined): WhistleTarget | null;
+/**
+ * A Sentry DSN that sends to Whistle, from `KF_WHISTLE_URL`: how an app on a
+ * Sentry SDK moves without code changes beyond `dsn` (and `release:
+ * KF_DEPLOYMENT_ID`, so errors group by deployment). Null without a URL, or
+ * when the key isn't one a DSN can carry (Sentry takes only [A-Za-z0-9_]).
+ * The project id is a placeholder: Sentry wants a number, Whistle goes by the key.
+ */
+export declare function sentryDsn(url: string | undefined): string | null;
+/**
+ * Reports one run of a scheduled job to Whistle: `every` (minutes) says how
+ * often it should run, so Whistle can say when it stops. Never throws; false
+ * when there's no KF_WHISTLE_URL or the send failed.
+ *
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { every: 1440 })
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { status: 'error', message: String(e) })
+ */
+export declare function checkIn(url: string | undefined, name: string, run?: {
+    status?: 'ok' | 'error';
+    every?: number;
+    grace?: number;
+    message?: string;
+}, doFetch?: typeof fetch): Promise<boolean>;
+export interface WhistleSinkOptions {
+    fetch?: typeof fetch;
+    /** On Workers, the request's `ctx.waitUntil`, so the send outlives the response. */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * Posts events to Whistle's `/v1/events` as NDJSON, batched per tick. `flush()`
+ * sends what's queued now; failures are dropped, never thrown.
+ */
+export declare function whistleSink(target: WhistleTarget, options?: WhistleSinkOptions): Sink & {
+    flush(): Promise<void>;
+};
+export interface TelemetryOptions {
+    project: string;
+    environment: string;
+    sink?: Sink;
+    now?: () => Date;
+    /** The console's deployment id and commit, stamped on every event. */
+    deployment?: string;
+    commit?: string;
+}
+/**
+ * Telemetry set up from what the console hands a project: `KF_WHISTLE_URL`
+ * (sends straight to Whistle), `KF_WHISTLE_PROJECT` and `KF_WHISTLE_ENVIRONMENT`
+ * (what Whistle files events under), `KF_DEPLOYMENT_ID` and `KF_COMMIT`.
+ * Without `KF_WHISTLE_URL`, console output. Not both: on Workers, Cloudflare's
+ * export would deliver the console line as well, and every event would count twice.
+ */
+export declare function telemetryFromEnv(env: Record<string, unknown>, options?: Partial<Omit<TelemetryOptions, 'deployment' | 'commit'>> & WhistleSinkOptions): Telemetry;
+export interface SecurityFields {
+    actor?: string;
+    ip?: string;
+    country?: string;
+    role?: string;
+    outcome?: SecurityEvent['outcome'];
+    rayId?: string;
+    traceId?: string;
+    detail?: Record<string, unknown>;
+}
+export interface ErrorContext {
+    route?: string;
+    rayId?: string;
+    traceId?: string;
+    detail?: Record<string, unknown>;
+}
+export interface Telemetry {
+    securityEvent(kind: SecurityKind, fields?: SecurityFields): void;
+    captureError(error: unknown, context?: ErrorContext): void;
+    /** Runs `fn`; if it throws, records the error with `name` as its route, then rethrows. */
+    span<T>(name: string, fn: () => T | Promise<T>, context?: ErrorContext): Promise<T>;
+}
+/** `T` with its possibly-undefined properties made optional and non-undefined, as `defined` returns it. */
+export type Defined<T> = {
+    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+} & {
+    [K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
+};
+/** `{ ...o }` without the undefined values, so events stay small and exact. */
+export declare function defined<T extends object>(o: T): Defined<T>;
+/** An Error, or whatever was thrown, as the three exception fields. */
+export declare function describeError(error: unknown): {
+    type: string;
+    message: string;
+    stack?: string;
+};
+export declare function createTelemetry(options: TelemetryOptions): Telemetry;
+/**
+ * What a request carries that events want, on Cloudflare: the client IP, its
+ * country, and the Ray ID that joins an event to its edge log row. Elsewhere,
+ * pass them yourself.
+ */
+export declare function requestFields(request: Request): {
+    ip?: string;
+    country?: string;
+    rayId?: string;
+};
+export { whistle, type HonoContextLike, type WhistleOptions } from './hono.js';

package/dist/whistle/index.js

@@ -0,0 +1,249 @@
+/**
+ * `@knowledgefutures/sdk/whistle` — what a project that declares
+ * `kf/whistle@1` tells Whistle beyond what its Worker's runs already say.
+ * On a Worker the console hosts, Whistle tails every run, so uncaught
+ * exceptions, `console.error(err)` and cron runs need nothing from here.
+ * This is for security events, errors the app handles without logging, and
+ * check-ins from jobs that aren't Worker crons:
+ *
+ *   app.use(whistle()) // Hono: denied requests and admin writes (hono.ts)
+ *   const t = telemetryFromEnv(env, { waitUntil })
+ *   t.securityEvent('auth.failed', { actor: `user:${id}`, ...requestFields(request) })
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { every: 1440 })
+ *
+ * With `KF_WHISTLE_URL` (the console hands it out) events go straight to
+ * Whistle; without it, to the console as JSON lines. Moved here from
+ * kf-whistle's `@kf/telemetry`, which Whistle keeps for parsing until it
+ * reads this package instead: the wire format (wire.ts) must not drift
+ * between the two.
+ */
+import { scrub, } from './wire.js';
+export * from './wire.js';
+/** Workers (and anything whose stdout is collected): one JSON line per event. */
+export const consoleSink = {
+    emit(event) {
+        const line = JSON.stringify(event);
+        // console.error so Workers Logs, and the OTLP export, mark it as an error.
+        if (event.kf === 'error')
+            console.error(line);
+        else
+            console.log(line);
+    },
+};
+/** Every event to each sink. */
+export function teeSink(...sinks) {
+    return {
+        emit(event) {
+            for (const s of sinks) {
+                try {
+                    s.emit(event);
+                }
+                catch {
+                    // One sink failing never stops the others.
+                }
+            }
+        },
+    };
+}
+/** `KF_WHISTLE_URL` (`https://<instance>:<key>@<host>/`) as an origin and a key, or null. */
+export function parseWhistleUrl(url) {
+    if (!url)
+        return null;
+    try {
+        const u = new URL(url);
+        const key = decodeURIComponent(u.password);
+        if (!key || !/^https?:$/.test(u.protocol))
+            return null;
+        return { origin: `${u.protocol}//${u.host}`, key };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A Sentry DSN that sends to Whistle, from `KF_WHISTLE_URL`: how an app on a
+ * Sentry SDK moves without code changes beyond `dsn` (and `release:
+ * KF_DEPLOYMENT_ID`, so errors group by deployment). Null without a URL, or
+ * when the key isn't one a DSN can carry (Sentry takes only [A-Za-z0-9_]).
+ * The project id is a placeholder: Sentry wants a number, Whistle goes by the key.
+ */
+export function sentryDsn(url) {
+    const target = parseWhistleUrl(url);
+    if (!target || !/^\w+$/.test(target.key))
+        return null;
+    const [scheme, host] = target.origin.split('//');
+    return `${scheme}//${target.key}@${host}/1`;
+}
+/**
+ * Reports one run of a scheduled job to Whistle: `every` (minutes) says how
+ * often it should run, so Whistle can say when it stops. Never throws; false
+ * when there's no KF_WHISTLE_URL or the send failed.
+ *
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { every: 1440 })
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { status: 'error', message: String(e) })
+ */
+export async function checkIn(url, name, run = {}, doFetch = fetch) {
+    const target = parseWhistleUrl(url);
+    if (!target)
+        return false;
+    try {
+        const res = await doFetch(`${target.origin}/v1/checkins/${encodeURIComponent(name)}`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${target.key}`, 'content-type': 'application/json' },
+            body: JSON.stringify(run),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Posts events to Whistle's `/v1/events` as NDJSON, batched per tick. `flush()`
+ * sends what's queued now; failures are dropped, never thrown.
+ */
+export function whistleSink(target, options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    let queue = [];
+    let scheduled = false;
+    const flush = async () => {
+        scheduled = false;
+        if (queue.length === 0)
+            return;
+        const body = queue.map((e) => JSON.stringify(e)).join('\n');
+        queue = [];
+        try {
+            await doFetch(`${target.origin}/v1/events`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${target.key}`, 'content-type': 'application/x-ndjson' },
+                body,
+            });
+        }
+        catch {
+            // Telemetry never breaks the request it describes.
+        }
+    };
+    return {
+        emit(event) {
+            queue.push(event);
+            if (scheduled)
+                return;
+            scheduled = true;
+            const sent = new Promise((resolve) => queueMicrotask(() => void flush().then(resolve)));
+            options.waitUntil?.(sent);
+        },
+        flush,
+    };
+}
+/**
+ * Telemetry set up from what the console hands a project: `KF_WHISTLE_URL`
+ * (sends straight to Whistle), `KF_WHISTLE_PROJECT` and `KF_WHISTLE_ENVIRONMENT`
+ * (what Whistle files events under), `KF_DEPLOYMENT_ID` and `KF_COMMIT`.
+ * Without `KF_WHISTLE_URL`, console output. Not both: on Workers, Cloudflare's
+ * export would deliver the console line as well, and every event would count twice.
+ */
+export function telemetryFromEnv(env, options = {}) {
+    const read = (k) => typeof env[k] === 'string' && env[k] ? env[k] : undefined;
+    const target = parseWhistleUrl(read('KF_WHISTLE_URL'));
+    const sink = options.sink ??
+        (target
+            ? whistleSink(target, defined({ fetch: options.fetch, waitUntil: options.waitUntil }))
+            : consoleSink);
+    return createTelemetry(defined({
+        // Whistle refuses events for a project their key isn't for.
+        project: options.project ?? read('KF_WHISTLE_PROJECT') ?? 'unknown',
+        environment: options.environment ?? read('KF_WHISTLE_ENVIRONMENT') ?? 'production',
+        sink,
+        now: options.now,
+        deployment: read('KF_DEPLOYMENT_ID'),
+        commit: read('KF_COMMIT'),
+    }));
+}
+/** `{ ...o }` without the undefined values, so events stay small and exact. */
+export function defined(o) {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+}
+/** An Error, or whatever was thrown, as the three exception fields. */
+export function describeError(error) {
+    if (error instanceof Error) {
+        return defined({ type: error.name || 'Error', message: error.message, stack: error.stack });
+    }
+    if (typeof error === 'string')
+        return { type: 'string', message: error };
+    try {
+        return { type: typeof error, message: JSON.stringify(error) ?? String(error) };
+    }
+    catch {
+        return { type: typeof error, message: String(error) };
+    }
+}
+export function createTelemetry(options) {
+    const sink = options.sink ?? consoleSink;
+    const now = options.now ?? (() => new Date());
+    const base = () => defined({
+        v: 1,
+        project: options.project,
+        environment: options.environment,
+        at: now().toISOString(),
+        deployment: options.deployment,
+        commit: options.commit,
+    });
+    // Building the event is guarded too: `detail` is whatever the app passed.
+    const emit = (build) => {
+        try {
+            sink.emit(build());
+        }
+        catch {
+            // Telemetry never breaks the request it describes.
+        }
+    };
+    const captureError = (error, context = {}) => emit(() => defined({
+        kf: 'error',
+        ...base(),
+        ...describeError(error),
+        route: context.route,
+        rayId: context.rayId,
+        traceId: context.traceId,
+        detail: scrub(context.detail),
+    }));
+    return {
+        securityEvent(kind, fields = {}) {
+            emit(() => defined({
+                kf: 'security',
+                ...base(),
+                kind,
+                actor: fields.actor,
+                ip: fields.ip,
+                country: fields.country,
+                role: fields.role,
+                outcome: fields.outcome,
+                rayId: fields.rayId,
+                traceId: fields.traceId,
+                detail: scrub(fields.detail),
+            }));
+        },
+        captureError,
+        async span(name, fn, context = {}) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                captureError(error, { route: name, ...context });
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * What a request carries that events want, on Cloudflare: the client IP, its
+ * country, and the Ray ID that joins an event to its edge log row. Elsewhere,
+ * pass them yourself.
+ */
+export function requestFields(request) {
+    return defined({
+        ip: request.headers.get('cf-connecting-ip') ?? undefined,
+        country: request.headers.get('cf-ipcountry') ?? undefined,
+        rayId: request.headers.get('cf-ray')?.split('-')[0],
+    });
+}
+export { whistle } from './hono.js';

package/dist/whistle/wire.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The wire format: one JSON object per event, the same on every runtime.
+ *
+ * Sent to Whistle's `/v1/events` as NDJSON, or written as the body of a
+ * `console.log`/`console.error` line. Box agents send the same objects.
+ * Whistle parses it with `parseWire`, so this file is the contract between
+ * apps and Whistle; kf-whistle's `packages/telemetry/src/wire.ts` must say
+ * the same until Whistle imports it from here.
+ */
+/** Security events: what a careful attacker can't avoid causing. Add kinds here, nowhere else. */
+export declare const SECURITY_KINDS: readonly ["auth.failed", "auth.success", "auth.mfa_failed", "auth.reset_requested", "token.created", "token.used_new_ip", "access.denied", "admin.action", "secret.read", "member.added", "export.large", "ssh.failed", "ssh.success", "sudo"];
+export type SecurityKind = (typeof SECURITY_KINDS)[number];
+interface Common {
+    v: 1;
+    /** `<account>/<project>`, the console key. */
+    project: string;
+    environment: string;
+    /** ISO 8601. */
+    at: string;
+    /** The edge request this happened in, when there is one: joins to the edge log lake. */
+    rayId?: string;
+    traceId?: string;
+    /** The console's deployment id (KF_DEPLOYMENT_ID) and its commit (KF_COMMIT). */
+    deployment?: string;
+    commit?: string;
+    detail?: Record<string, unknown>;
+}
+export interface SecurityEvent extends Common {
+    kf: 'security';
+    kind: SecurityKind;
+    /** Who: `user:<id>`, `token:<id>`, `ip`, or a box user. Never an email or a name. */
+    actor?: string;
+    ip?: string;
+    /** ISO 3166 alpha-2, from `cf-ipcountry` on Cloudflare. */
+    country?: string;
+    /** Staff, admin, member: lets rules treat privileged sign-ins differently. */
+    role?: string;
+    outcome?: 'success' | 'failure' | 'denied';
+}
+export interface ErrorEvent extends Common {
+    kf: 'error';
+    /** `exception.type`: TypeError, D1_ERROR… */
+    type: string;
+    /** `exception.message`. */
+    message: string;
+    /** `exception.stacktrace`. */
+    stack?: string;
+    /** The route pattern (`/api/projects/:id`), not the URL: keeps ids out of grouping. */
+    route?: string;
+}
+export type WireEvent = SecurityEvent | ErrorEvent;
+/**
+ * `detail` without anything that looks like a credential, and bounded in size.
+ * Apps pass objects they didn't fully build (a request's params, an error's
+ * cause), so this is the last line before a secret ends up in the lake.
+ */
+export declare function scrub(detail: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * A wire event from a log body (a JSON string or an already-parsed object), or
+ * null when it isn't one. Tolerant of extra fields; strict about the ones rules
+ * depend on, so a malformed event never matches a rule by accident.
+ */
+export declare function parseWire(input: unknown): WireEvent | null;
+export {};