@knowledgefutures/sdk 0.0.0-stage → 0.2.1

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 {};

package/dist/whistle/wire.js

@@ -0,0 +1,98 @@
+/**
+ * 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 const SECURITY_KINDS = [
+    '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',
+    // From box agents (vector/vector.toml), not app code.
+    'ssh.failed',
+    'ssh.success',
+    'sudo',
+];
+const MAX_DETAIL_BYTES = 8_000;
+const SENSITIVE_KEY = /pass(word)?|secret|token|cookie|authorization|api[-_]?key|session/i;
+/**
+ * `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 function scrub(detail) {
+    if (!detail)
+        return undefined;
+    const walk = (value, depth) => {
+        if (depth > 4)
+            return '[depth]';
+        if (Array.isArray(value))
+            return value.slice(0, 50).map((v) => walk(v, depth + 1));
+        if (value && typeof value === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(value)) {
+                out[k] = SENSITIVE_KEY.test(k) ? '[redacted]' : walk(v, depth + 1);
+            }
+            return out;
+        }
+        if (typeof value === 'string' && value.length > 2_000)
+            return `${value.slice(0, 2_000)}…`;
+        // JSON.stringify throws on a bigint.
+        if (typeof value === 'bigint')
+            return value.toString();
+        return value;
+    };
+    const out = walk(detail, 0);
+    if (JSON.stringify(out).length > MAX_DETAIL_BYTES)
+        return { truncated: true };
+    return out;
+}
+const isString = (v) => typeof v === 'string' && v.length > 0;
+const KINDS = new Set(SECURITY_KINDS);
+/**
+ * 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 function parseWire(input) {
+    let value = input;
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (!s.startsWith('{') || !s.includes('"kf"'))
+            return null;
+        try {
+            value = JSON.parse(s);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!value || typeof value !== 'object')
+        return null;
+    const o = value;
+    if (o.v !== 1 || !isString(o.project) || !isString(o.environment) || !isString(o.at))
+        return null;
+    if (o.kf === 'security') {
+        if (!isString(o.kind) || !KINDS.has(o.kind))
+            return null;
+        return o;
+    }
+    if (o.kf === 'error') {
+        if (!isString(o.type) || typeof o.message !== 'string')
+            return null;
+        return o;
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@knowledgefutures/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "Zero-config clients for Knowledge Futures platform services, configured by the console.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowledgefutures/kf-console.git",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "default": "./dist/storage/index.js"
+    },
+    "./storage/testing": {
+      "types": "./dist/storage/testing.d.ts",
+      "default": "./dist/storage/testing.js"
+    },
+    "./whistle": {
+      "types": "./dist/whistle/index.d.ts",
+      "default": "./dist/whistle/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }