@ractive-ch/tab-mcp 0.0.0-stage → 0.1.0-alpha.1

package/ip.d.ts

@@ -0,0 +1,22 @@
+/**
+ * IP address parsing and the public-address check used by the CIMD fetcher's
+ * SSRF guard (threat model A3) and by log truncation (A9).
+ */
+/** Parse dotted-quad IPv4 into four octets, or undefined. */
+export declare function parseIpv4(ip: string): number[] | undefined;
+/** Parse IPv6 (with `::`, an optional zone, an embedded IPv4 tail) into 8 groups. */
+export declare function parseIpv6(ip: string): number[] | undefined;
+/**
+ * Whether an IP address (v4 or v6 text) is a globally reachable unicast
+ * address. Anything that does not parse counts as not public.
+ */
+export declare function isPublicIp(ip: string): boolean;
+/** Whether a URL hostname is a loopback name or address. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * The key per-IP limits count under (threat model A8, DEC-061): an IPv4
+ * address as is (/32, since many users share one behind NAT or CGNAT
+ * anyway), an IPv6 address by its /64, which one subscriber usually gets
+ * whole. IPv4-mapped IPv6 counts as IPv4. Anything else is used verbatim.
+ */
+export declare function ipPrefixKey(ip: string): string;

package/log.d.ts

@@ -0,0 +1,33 @@
+import type { LogLevel } from "./config.js";
+/**
+ * Structured JSON-line logging (threat model A9). Callers pass only metadata:
+ * never request or response bodies, tool names, arguments, results, tokens,
+ * pairing codes or page secrets. There is deliberately no helper that accepts
+ * a body.
+ */
+export type LogFields = Record<string, string | number | boolean | null>;
+export interface Logger {
+    error(event: string, fields?: LogFields): void;
+    warn(event: string, fields?: LogFields): void;
+    info(event: string, fields?: LogFields): void;
+    debug(event: string, fields?: LogFields): void;
+}
+/** A logger that writes one JSON object per line to `sink` (stdout by default). */
+export declare function createLogger(level: LogLevel, sink?: (line: string) => void): Logger;
+/**
+ * Truncate an IP for logs: IPv4 to /24, IPv6 to /48. IPv4-mapped IPv6
+ * (`::ffff:a.b.c.d`) is treated as IPv4. `?` if it does not parse.
+ */
+export declare function truncateIp(ip: string): string;
+/**
+ * Defence in depth (DEC-047). The relay catches errors per message and per
+ * request; anything that still escapes is logged, never silently fatal:
+ * - an unhandled promise rejection is logged and the relay keeps running, so one
+ *   bad request or tab cannot end every other session;
+ * - an uncaught exception is logged and the process exits with 1, because the
+ *   relay's state may be inconsistent; the supervisor (Docker, systemd) restarts
+ *   it and AI apps keep their tokens (they live in the store).
+ * Only the error's name is logged: messages can carry request data.
+ * Returns a function that removes the handlers.
+ */
+export declare function installCrashLogging(logger: Logger, exit?: (code: number) => void): () => void;