@jini-ai/core 0.1.0

package/dist/origin-validation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module origin-validation
+ *
+ * Same-origin / allow-listed-origin validation for a locally-bound HTTP
+ * daemon: is this browser request actually coming from a page the daemon
+ * itself served (or an operator-configured allow-listed origin), as
+ * opposed to an arbitrary third-party site making a cross-site request to
+ * the daemon's loopback/private-LAN port.
+ *
+ * Generalized from an upstream flat daemon module: the origin hardcoded its
+ * host product's env-var names, now fields on
+ * {@link OriginValidationEnvConfig} — see `source-map.md` for the exact
+ * mapping. One function, a bypass for a specific product's own
+ * browser-extension-driven ingest route, was deliberately **not** ported —
+ * it names a specific product route and product feature with no generic
+ * equivalent; see `source-map.md`.
+ */
+export interface ParsedHostHeader {
+    hostname: string;
+    host: string;
+    port: string;
+}
+export interface RequestWithOriginHeaders {
+    headers?: {
+        host?: unknown;
+        origin?: unknown;
+        'sec-fetch-site'?: unknown;
+    };
+}
+/** Names the env vars this port reads. */
+export interface OriginValidationEnvConfig {
+    /** Env var carrying a comma-separated list of extra allow-listed origins. */
+    allowedOriginsEnvVar: string;
+    /** Env var carrying an additional browser-facing port to treat as local (e.g. a separate web dev server). */
+    webPortEnvVar: string;
+    /** Env var carrying the host the daemon itself is bound to (default `'127.0.0.1'`). */
+    bindHostEnvVar: string;
+}
+/** Parses and validates {@link OriginValidationEnvConfig.allowedOriginsEnvVar} into normalized origins. */
+export declare function configuredAllowedOrigins(config: OriginValidationEnvConfig, env?: NodeJS.ProcessEnv): string[];
+/** The `host` (hostname:port) component of each configured allowed origin. */
+export declare function configuredAllowedHosts(origins: string[]): string[];
+/** The set of browser-facing ports considered "local": the daemon's own port plus an optional configured web port. */
+export declare function allowedBrowserPorts(config: OriginValidationEnvConfig, port: number | string | null | undefined, env?: NodeJS.ProcessEnv): number[];
+/** Parses a raw `Host` header value into hostname/host/port, or `null` when unparseable. */
+export declare function parseHostHeader(value: unknown): ParsedHostHeader | null;
+/** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16). */
+export declare function isPrivateIpv4(hostname: unknown): boolean;
+/** Whether `hostname` is a literal IPv4 address or bracketed IPv6 literal (as opposed to a DNS name). */
+export declare function isIpLiteralHostname(hostname: unknown): boolean;
+/** Whether `hostname` is loopback, unspecified, or a private-LAN address. */
+export declare function isLoopbackOrPrivateLanHost(hostname: unknown): boolean;
+/** Whether a request's `Host` header names a locally-served or explicitly allow-listed host. */
+export declare function isAllowedBrowserHost(config: OriginValidationEnvConfig, hostHeader: unknown, ports: number[], bindHost: string, extraAllowedOrigins: string[]): boolean;
+/** Whether an `Origin` header value names a locally-served or explicitly allow-listed origin. */
+export declare function isAllowedBrowserOrigin(config: OriginValidationEnvConfig, origin: unknown, hostHeader: unknown, ports: number[], bindHost: string, extraAllowedOrigins: string[]): boolean;
+/**
+ * The top-level same-origin gate: is `req` a request the daemon should treat
+ * as coming from one of its own locally-served (or explicitly allow-listed)
+ * pages.
+ */
+export declare function isLocalSameOrigin(config: OriginValidationEnvConfig, req: RequestWithOriginHeaders, port: number | string | null | undefined, env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=origin-validation.d.ts.map

package/dist/origin-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin-validation.d.ts","sourceRoot":"","sources":["../src/origin-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACxC,6EAA6E;IAC7E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,6GAA6G;IAC7G,aAAa,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,2GAA2G;AAC3G,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,yBAAyB,EACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAcV;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAElE;AAED,sHAAsH;AACtH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,yBAAyB,EACjC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAOV;AAUD,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CASvE;AAED,uHAAuH;AACvH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAQxD;AAED,yGAAyG;AACzG,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAQ9D;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAWrE;AAED,gGAAgG;AAChG,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,yBAAyB,EACjC,UAAU,EAAE,OAAO,EACnB,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAChB,mBAAmB,EAAE,MAAM,EAAE,GAC5B,OAAO,CAaT;AAED,iGAAiG;AACjG,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,yBAAyB,EACjC,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,OAAO,EACnB,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAChB,mBAAmB,EAAE,MAAM,EAAE,GAC5B,OAAO,CA4BT;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,yBAAyB,EACjC,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAmCT"}

package/dist/origin-validation.js

@@ -0,0 +1,198 @@
+/**
+ * @module origin-validation
+ *
+ * Same-origin / allow-listed-origin validation for a locally-bound HTTP
+ * daemon: is this browser request actually coming from a page the daemon
+ * itself served (or an operator-configured allow-listed origin), as
+ * opposed to an arbitrary third-party site making a cross-site request to
+ * the daemon's loopback/private-LAN port.
+ *
+ * Generalized from an upstream flat daemon module: the origin hardcoded its
+ * host product's env-var names, now fields on
+ * {@link OriginValidationEnvConfig} — see `source-map.md` for the exact
+ * mapping. One function, a bypass for a specific product's own
+ * browser-extension-driven ingest route, was deliberately **not** ported —
+ * it names a specific product route and product feature with no generic
+ * equivalent; see `source-map.md`.
+ */
+/** Parses and validates {@link OriginValidationEnvConfig.allowedOriginsEnvVar} into normalized origins. */
+export function configuredAllowedOrigins(config, env = process.env) {
+    const raw = env[config.allowedOriginsEnvVar] || '';
+    if (!raw.trim())
+        return [];
+    return raw
+        .split(',')
+        .map((origin) => origin.trim())
+        .filter(Boolean)
+        .map((origin) => {
+        const parsed = new URL(origin);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            throw new Error(`${config.allowedOriginsEnvVar} only supports http:// and https:// origins`);
+        }
+        return parsed.origin;
+    });
+}
+/** The `host` (hostname:port) component of each configured allowed origin. */
+export function configuredAllowedHosts(origins) {
+    return origins.map((origin) => new URL(origin).host);
+}
+/** The set of browser-facing ports considered "local": the daemon's own port plus an optional configured web port. */
+export function allowedBrowserPorts(config, port, env = process.env) {
+    const ports = [];
+    const primary = Number(port);
+    if (primary)
+        ports.push(primary);
+    const webPort = Number(env[config.webPortEnvVar]);
+    if (webPort && webPort !== primary)
+        ports.push(webPort);
+    return ports;
+}
+function headerValue(value) {
+    if (Array.isArray(value)) {
+        const first = value[0];
+        return first == null ? undefined : String(first);
+    }
+    return value == null ? undefined : String(value);
+}
+/** Parses a raw `Host` header value into hostname/host/port, or `null` when unparseable. */
+export function parseHostHeader(value) {
+    const raw = String(headerValue(value) || '').trim();
+    if (!raw)
+        return null;
+    try {
+        const parsed = new URL(`http://${raw}`);
+        return { hostname: parsed.hostname, host: parsed.host, port: parsed.port || '80' };
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16). */
+export function isPrivateIpv4(hostname) {
+    const parts = String(hostname || '').split('.');
+    if (parts.length !== 4)
+        return false;
+    if (!parts.every((part) => /^\d+$/.test(part)))
+        return false;
+    const octets = parts.map((part) => Number(part));
+    if (!octets.every((n) => Number.isInteger(n) && n >= 0 && n <= 255))
+        return false;
+    const [a, b] = octets;
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+}
+/** Whether `hostname` is a literal IPv4 address or bracketed IPv6 literal (as opposed to a DNS name). */
+export function isIpLiteralHostname(hostname) {
+    const host = String(hostname || '').trim();
+    if (!host)
+        return false;
+    if (host.startsWith('[') && host.endsWith(']'))
+        return true;
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return false;
+    if (!parts.every((part) => /^\d+$/.test(part)))
+        return false;
+    return parts.map(Number).every((n) => Number.isInteger(n) && n >= 0 && n <= 255);
+}
+/** Whether `hostname` is loopback, unspecified, or a private-LAN address. */
+export function isLoopbackOrPrivateLanHost(hostname) {
+    const host = String(hostname || '').toLowerCase();
+    return (host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host === '::1' ||
+        host === '[::1]' ||
+        host === '0.0.0.0' ||
+        host === '::' ||
+        isPrivateIpv4(host));
+}
+/** Whether a request's `Host` header names a locally-served or explicitly allow-listed host. */
+export function isAllowedBrowserHost(config, hostHeader, ports, bindHost, extraAllowedOrigins) {
+    const requestHost = parseHostHeader(hostHeader);
+    if (!requestHost)
+        return false;
+    const loopbackHosts = ['127.0.0.1', 'localhost', '[::1]'];
+    const explicitHosts = new Set([
+        ...ports.flatMap((p) => [...loopbackHosts.map((h) => `${h}:${p}`), `${bindHost}:${p}`]),
+        ...configuredAllowedHosts(extraAllowedOrigins),
+    ]);
+    if (explicitHosts.has(requestHost.host))
+        return true;
+    if (!ports.map(String).includes(requestHost.port))
+        return false;
+    return isLoopbackOrPrivateLanHost(requestHost.hostname);
+}
+/** Whether an `Origin` header value names a locally-served or explicitly allow-listed origin. */
+export function isAllowedBrowserOrigin(config, origin, hostHeader, ports, bindHost, extraAllowedOrigins) {
+    if (extraAllowedOrigins.includes(String(origin)))
+        return true;
+    let parsedOrigin;
+    try {
+        parsedOrigin = new URL(String(origin));
+    }
+    catch {
+        return false;
+    }
+    if (parsedOrigin.protocol !== 'http:' && parsedOrigin.protocol !== 'https:')
+        return false;
+    const requestHost = parseHostHeader(hostHeader);
+    if (!requestHost)
+        return false;
+    const schemes = ['http', 'https'];
+    const loopbackHosts = ['127.0.0.1', 'localhost', '[::1]'];
+    const explicitOrigins = new Set(ports.flatMap((p) => [
+        ...schemes.flatMap((s) => loopbackHosts.map((h) => `${s}://${h}:${p}`)),
+        ...schemes.map((s) => `${s}://${bindHost}:${p}`),
+    ]));
+    if (explicitOrigins.has(String(origin)))
+        return true;
+    const originPort = parsedOrigin.port || (parsedOrigin.protocol === 'https:' ? '443' : '80');
+    if (!ports.map(String).includes(originPort))
+        return false;
+    if (parsedOrigin.hostname !== requestHost.hostname)
+        return false;
+    return isLoopbackOrPrivateLanHost(parsedOrigin.hostname);
+}
+/**
+ * The top-level same-origin gate: is `req` a request the daemon should treat
+ * as coming from one of its own locally-served (or explicitly allow-listed)
+ * pages.
+ */
+export function isLocalSameOrigin(config, req, port, env = process.env) {
+    const host = String(headerValue(req.headers?.host) || '');
+    const origin = headerValue(req.headers?.origin);
+    const ports = allowedBrowserPorts(config, port, env);
+    const bindHost = env[config.bindHostEnvVar] || '127.0.0.1';
+    const extraAllowedOrigins = configuredAllowedOrigins(config, env);
+    const ipOnlyExtraOrigins = extraAllowedOrigins.filter((o) => isIpLiteralHostname(new URL(o).hostname));
+    const localHostAllowed = isAllowedBrowserHost(config, host, ports, bindHost, ipOnlyExtraOrigins);
+    if (origin == null || origin === '') {
+        if (localHostAllowed)
+            return true;
+        // Browsers (Firefox, Chrome) omit Origin on same-origin GET subresource
+        // requests per the Fetch spec, which makes hostname entries in the
+        // allow-list unreachable for legitimate same-origin GETs through a
+        // reverse proxy. Sec-Fetch-Site is set by the user agent and cannot be
+        // modified by JavaScript, so a value of "same-origin" attests that the
+        // request originated from the same origin as the target — a cross-site
+        // `<img>`/`<script>` exploit would carry "cross-site" instead. Only
+        // consult the broader allow-list once that signal is present.
+        const fetchSite = headerValue(req.headers?.['sec-fetch-site']);
+        if (fetchSite === 'same-origin') {
+            return isAllowedBrowserHost(config, host, ports, bindHost, extraAllowedOrigins);
+        }
+        return false;
+    }
+    // Reverse-proxy deployments terminate the browser connection at the proxy
+    // and open a fresh upstream connection to the daemon. The Host header the
+    // daemon sees is the proxy upstream's address, not the browser-visible
+    // origin, so the host check below fails even when the user explicitly
+    // listed their proxy origin in the allow-list. Trust the Origin header in
+    // that case: a client-supplied origin that exactly matches an explicitly
+    // allow-listed entry is the documented escape hatch for these deployments.
+    if (extraAllowedOrigins.includes(origin))
+        return true;
+    if (!isAllowedBrowserHost(config, host, ports, bindHost, extraAllowedOrigins))
+        return false;
+    return isAllowedBrowserOrigin(config, origin, host, ports, bindHost, extraAllowedOrigins);
+}
+//# sourceMappingURL=origin-validation.js.map

package/dist/origin-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin-validation.js","sourceRoot":"","sources":["../src/origin-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA0BH,2GAA2G;AAC3G,MAAM,UAAU,wBAAwB,CACtC,MAAiC,EACjC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC;IACnD,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC;IAC3B,OAAO,GAAG;SACP,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;SAC9B,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACd,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,CAAC,oBAAoB,6CAA6C,CAAC,CAAC;QAC/F,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,sBAAsB,CAAC,OAAiB;IACtD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AACvD,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,mBAAmB,CACjC,MAAiC,EACjC,IAAwC,EACxC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,KAAK,GAAG,EAAE,CAAC;IACjB,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAClD,IAAI,OAAO,IAAI,OAAO,KAAK,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC;QACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,uHAAuH;AACvH,MAAM,UAAU,aAAa,CAAC,QAAiB;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7D,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAClF,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAA0C,CAAC;IAC1D,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;AAC/G,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7D,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;AACnF,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,0BAA0B,CAAC,QAAiB;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAClD,OAAO,CACL,IAAI,KAAK,WAAW;QACpB,IAAI,KAAK,WAAW;QACpB,IAAI,KAAK,KAAK;QACd,IAAI,KAAK,OAAO;QAChB,IAAI,KAAK,SAAS;QAClB,IAAI,KAAK,IAAI;QACb,aAAa,CAAC,IAAI,CAAC,CACpB,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,oBAAoB,CAClC,MAAiC,EACjC,UAAmB,EACnB,KAAe,EACf,QAAgB,EAChB,mBAA6B;IAE7B,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAE/B,MAAM,aAAa,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;QAC5B,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,GAAG,QAAQ,IAAI,CAAC,EAAE,CAAC,CAAC;QACvF,GAAG,sBAAsB,CAAC,mBAAmB,CAAC;KAC/C,CAAC,CAAC;IACH,IAAI,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAErD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,OAAO,0BAA0B,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;AAC1D,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,sBAAsB,CACpC,MAAiC,EACjC,MAAe,EACf,UAAmB,EACnB,KAAe,EACf,QAAgB,EAChB,mBAA6B;IAE7B,IAAI,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9D,IAAI,YAAY,CAAC;IACjB,IAAI,CAAC;QACH,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,YAAY,CAAC,QAAQ,KAAK,OAAO,IAAI,YAAY,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE1F,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAE/B,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,aAAa,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1D,MAAM,eAAe,GAAG,IAAI,GAAG,CAC7B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACnB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,QAAQ,IAAI,CAAC,EAAE,CAAC;KACjD,CAAC,CACH,CAAC;IACF,IAAI,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAErD,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5F,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1D,IAAI,YAAY,CAAC,QAAQ,KAAK,WAAW,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACjE,OAAO,0BAA0B,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAiC,EACjC,GAA6B,EAC7B,IAAwC,EACxC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,mBAAmB,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,WAAW,CAAC;IAC3D,MAAM,mBAAmB,GAAG,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClE,MAAM,kBAAkB,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEvG,MAAM,gBAAgB,GAAG,oBAAoB,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC;IACjG,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QACpC,IAAI,gBAAgB;YAAE,OAAO,IAAI,CAAC;QAClC,wEAAwE;QACxE,mEAAmE;QACnE,mEAAmE;QACnE,uEAAuE;QACvE,uEAAuE;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,8DAA8D;QAC9D,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC;QAC/D,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;YAChC,OAAO,oBAAoB,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,0EAA0E;IAC1E,0EAA0E;IAC1E,uEAAuE;IACvE,sEAAsE;IACtE,0EAA0E;IAC1E,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,CAAC,oBAAoB,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,mBAAmB,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5F,OAAO,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC;AAC5F,CAAC"}

package/dist/pack.d.ts

@@ -0,0 +1,26 @@
+import type { AnyToken, ManyToken, Token } from './token.js';
+/**
+ * The only resolver a pack's `services` factory ever sees. Scoped to that
+ * pack's own declared `deps` — resolving a token the pack didn't declare is a
+ * bug (kernel escape hatch), not a convenience, so it throws rather than
+ * silently falling through to a global container.
+ */
+export interface PackContainer {
+    get<T>(t: Token<T, string>): T;
+    getMany<T>(t: ManyToken<T, string>): T[];
+}
+export interface Pack<Deps extends readonly AnyToken<unknown, string>[] = readonly AnyToken<unknown, string>[], Services = unknown, Name extends string = string> {
+    readonly name: Name;
+    readonly deps: Deps;
+    readonly services: (c: PackContainer) => Services;
+    readonly http?: (app: unknown, services: Services) => void;
+    readonly cli?: (reg: unknown, services: Services) => void;
+}
+export declare function definePack<const Name extends string, const Deps extends readonly AnyToken<unknown, string>[], Services>(def: {
+    name: Name;
+    deps: Deps;
+    services: (c: PackContainer) => Services;
+    http?: (app: unknown, services: Services) => void;
+    cli?: (reg: unknown, services: Services) => void;
+}): Pack<Deps, Services, Name>;
+//# sourceMappingURL=pack.d.ts.map

package/dist/pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../src/pack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,IAAI,CACnB,IAAI,SAAS,SAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,GAAG,SAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,EACxF,QAAQ,GAAG,OAAO,EAClB,IAAI,SAAS,MAAM,GAAG,MAAM;IAE5B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,QAAQ,CAAC;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CAC3D;AAED,wBAAgB,UAAU,CACxB,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,KAAK,CAAC,IAAI,SAAS,SAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,EACvD,QAAQ,EACR,GAAG,EAAE;IACL,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,QAAQ,CAAC;IACzC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IAClD,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CAClD,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAE7B"}

package/dist/pack.js

@@ -0,0 +1,4 @@
+export function definePack(def) {
+    return def;
+}
+//# sourceMappingURL=pack.js.map

package/dist/pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.js","sourceRoot":"","sources":["../src/pack.ts"],"names":[],"mappings":"AAyBA,MAAM,UAAU,UAAU,CAIxB,GAMD;IACC,OAAO,GAA4C,CAAC;AACtD,CAAC"}

package/dist/principal.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `Principal` — the authenticated/authorized identity a kernel operation
+ * (a tool call, a run) is performed on behalf of. Deliberately minimal per
+ * extraction-plan.md §3 ("Principal/Authorizer, pure interfaces"): the
+ * kernel only needs an opaque, stable identity plus an optional coarse
+ * role/capability hint a `ToolPolicy` can branch on — anything richer
+ * (session, auth provider, user profile) is a consumer concern layered on
+ * top, never a kernel noun.
+ */
+export interface Principal {
+    /** Opaque, stable identity — never assumed to be a product user id. */
+    readonly id: string;
+    /** Optional coarse role/capability hints a policy may consult. */
+    readonly roles?: readonly string[];
+}
+//# sourceMappingURL=principal.d.ts.map

package/dist/principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.d.ts","sourceRoot":"","sources":["../src/principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC"}

package/dist/principal.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=principal.js.map

package/dist/principal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.js","sourceRoot":"","sources":["../src/principal.ts"],"names":[],"mappings":""}

package/dist/redact.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module redact
+ *
+ * Lexical secret / PII scrubber for telemetry payloads. Verbatim port of
+ * OD's `apps/daemon/src/redact.ts` — no product-identity strings or
+ * hardcoded env vars in the original, so no genericization was needed.
+ *
+ * Runs before any prompt or assistant text is sent to an external
+ * observability sink. The patterns here are intentionally conservative:
+ * each one matches a well-defined token shape with extremely low
+ * false-positive rate (API keys have a fixed prefix, JWTs have the
+ * "header.payload.signature" triple, credit-card matches go through a Luhn
+ * check). What this file does NOT do — and any caller-facing copy must
+ * reflect that — is detect names, addresses, business secrets, or anything
+ * that requires understanding the meaning of the surrounding text. That's
+ * an ML / LLM problem this module doesn't take on.
+ *
+ * Output format: every match is replaced by `[REDACTED:<kind>]` so a
+ * reviewer reading a trace can see exactly which category fired without
+ * recovering the original value.
+ *
+ * References:
+ * - Langfuse client-side masking guidance:
+ *   https://langfuse.com/docs/observability/features/masking
+ * - GitHub token format:
+ *   https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github
+ * - AWS access key shape: 'AKIA' + 16 uppercase alphanumerics.
+ * - Luhn algorithm (credit cards): https://en.wikipedia.org/wiki/Luhn_algorithm
+ */
+/**
+ * Returns `input` with every recognised secret / PII pattern replaced by a
+ * `[REDACTED:<kind>]` marker. Idempotent — re-running on already redacted
+ * text only matches new tokens.
+ *
+ * Empty / non-string input passes through unchanged so the caller can use
+ * this as a no-op on optional fields.
+ */
+export declare function redactSecrets(input: string): string;
+/**
+ * Same as {@link redactSecrets} but also returns per-category counts so the
+ * caller can attach an audit summary to the trace metadata ('we stripped 2
+ * keys + 1 email before send').
+ */
+export declare function redactSecretsWithCounts(input: string): {
+    redacted: string;
+    counts: Record<string, number>;
+};
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAiHH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBnD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,CAmCA"}

package/dist/redact.js

@@ -0,0 +1,190 @@
+/**
+ * @module redact
+ *
+ * Lexical secret / PII scrubber for telemetry payloads. Verbatim port of
+ * OD's `apps/daemon/src/redact.ts` — no product-identity strings or
+ * hardcoded env vars in the original, so no genericization was needed.
+ *
+ * Runs before any prompt or assistant text is sent to an external
+ * observability sink. The patterns here are intentionally conservative:
+ * each one matches a well-defined token shape with extremely low
+ * false-positive rate (API keys have a fixed prefix, JWTs have the
+ * "header.payload.signature" triple, credit-card matches go through a Luhn
+ * check). What this file does NOT do — and any caller-facing copy must
+ * reflect that — is detect names, addresses, business secrets, or anything
+ * that requires understanding the meaning of the surrounding text. That's
+ * an ML / LLM problem this module doesn't take on.
+ *
+ * Output format: every match is replaced by `[REDACTED:<kind>]` so a
+ * reviewer reading a trace can see exactly which category fired without
+ * recovering the original value.
+ *
+ * References:
+ * - Langfuse client-side masking guidance:
+ *   https://langfuse.com/docs/observability/features/masking
+ * - GitHub token format:
+ *   https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github
+ * - AWS access key shape: 'AKIA' + 16 uppercase alphanumerics.
+ * - Luhn algorithm (credit cards): https://en.wikipedia.org/wiki/Luhn_algorithm
+ */
+// Order matters: list specific rules before more general ones. Langfuse
+// keys (`sk-lf-...`) would otherwise be eaten by the generic `sk-...`
+// rule and labeled as a generic OpenAI-style key.
+const PATTERNS = [
+    // Langfuse public/secret keys (pk-lf- / sk-lf-). Must run before the
+    // generic sk- rule so the more specific label wins.
+    { name: 'langfuse_key', regex: /\b(?:pk|sk)-lf-[A-Za-z0-9-]{16,}\b/g },
+    // Anthropic / OpenAI-style keys: 'sk-' + optional sub-prefix + base64-ish.
+    // Both vendors plus a long tail of OpenAI-compatible providers (DeepSeek,
+    // MiniMax, Together, etc.) ship keys in this shape, so a single rule
+    // covers most "sk-..." secrets a user might paste into a prompt.
+    { name: 'sk_key', regex: /\bsk-(?:proj-|live-|test-|ant-)?[A-Za-z0-9_-]{20,}\b/g },
+    // GitHub personal / OAuth / server / user-server / refresh tokens.
+    { name: 'github_token', regex: /\bgh[opsur]_[A-Za-z0-9]{36,251}\b/g },
+    // GitHub legacy 40-hex personal access tokens that ship with no prefix
+    // are indistinguishable from a sha1 hash, so we don't try to match them
+    // here — false positives would be brutal in commit logs / artifact slugs.
+    // AWS access key id. The matching secret access key is just 40 base64
+    // chars with no fixed shape, so we cannot reliably redact it without
+    // huge collateral damage; flagging the access key id at least
+    // signals a paste happened.
+    { name: 'aws_access_key', regex: /\bAKIA[0-9A-Z]{16}\b/g },
+    // Google API keys — legacy AIza… (Maps / AI Studio) and service-account-
+    // bound AQ.… keys AI Studio now issues. AQ. must run before the generic
+    // sk_ rule would mis-label unrelated tokens.
+    { name: 'google_api_key', regex: /\bAQ\.[A-Za-z0-9_-]{20,}\b/g },
+    { name: 'google_api_key', regex: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+    // Slack tokens.
+    { name: 'slack_token', regex: /\bxox[abprs]-[0-9A-Za-z-]{10,}\b/g },
+    // Stripe keys.
+    { name: 'stripe_key', regex: /\b(?:sk|pk|rk)_(?:live|test)_[0-9a-zA-Z]{16,}\b/g },
+    // JSON Web Tokens. The "header.payload.signature" triple is distinctive
+    // enough that false positives are rare (the literal "eyJ" prefix is the
+    // base64 encoding of '{"' which is how every JOSE header starts).
+    { name: 'jwt', regex: /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g },
+    // Bearer tokens in HTTP Authorization header copy/paste. We only match
+    // the value, not the literal 'Bearer ', so the marker stays readable in
+    // the redacted output ("Authorization: Bearer [REDACTED:bearer_token]").
+    { name: 'bearer_token', regex: /(?<=\bBearer\s+)[A-Za-z0-9._~+/-]{16,}={0,2}/g },
+    // Email addresses. Conservative enough to require a TLD-like trailer.
+    { name: 'email', regex: /\b[\w.+-]+@[\w-]+\.[\w.-]+\b/g },
+    // IPv4. Reject all-zero / 255.255.255.255-ish junk shapes by gating on
+    // each octet being 0-255.
+    {
+        name: 'ipv4',
+        regex: /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\b/g,
+    },
+    // Phone numbers. Tight US-leaning shape; a global PII detector would
+    // need a real lib. We keep this so US-based test prompts ('call me at
+    // (415) 555-...') don't ship. Note: no leading \b — '(' isn't a word
+    // char, so a starting boundary would refuse to match `(415)`. We
+    // require a non-digit (or start of string) before the run instead.
+    {
+        name: 'phone',
+        regex: /(?<!\d)(?:\+?\d{1,3}[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}(?!\d)/g,
+    },
+];
+// Credit card sweep is special: a naive 13-19 digit run matches a lot of
+// non-card numbers (timestamps, IDs, hashes). We isolate the candidate
+// then run a Luhn check before redacting.
+const CARD_CANDIDATE = /\b(?:\d[ -]?){12,18}\d\b/g;
+const API_KEY_HEADER = /(^|[^?&\w-])("?)(x-api-key|api-key|x-goog-api-key)\2(\s*[:=]\s*)("[^"]*"|[^\s,;"'#}]+)/gi;
+const API_KEY_QUERY = /([?&](?:key|api_key|api-key)=)[^&#\s,;"']+/gi;
+// The length guard and the per-digit `d < 0 || d > 9` guard from the origin
+// were both dropped here (a documented deviation from the otherwise-verbatim
+// port — see source-map.md): `isLuhnValid` is private with exactly one call
+// site (the `CARD_CANDIDATE.replace` callbacks below), and `CARD_CANDIDATE`'s
+// own regex (`\b(?:\d[ -]?){12,18}\d\b`) already guarantees any string
+// reaching here is 13-19 characters, and the preceding `match.replace(/\D/g,
+// '')` strip guarantees every character is an ASCII digit — so both guards
+// were provably unreachable, not speculative.
+function isLuhnValid(digits) {
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i -= 1) {
+        let d = digits.charCodeAt(i) - 48;
+        if (alt) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+function redactApiKeyHeaderValue(prefix, quote, name, separator, value) {
+    const redactedValue = value.startsWith('"') ? '"[REDACTED:api_key_header]"' : '[REDACTED:api_key_header]';
+    return `${prefix}${quote}${name}${quote}${separator}${redactedValue}`;
+}
+/**
+ * Returns `input` with every recognised secret / PII pattern replaced by a
+ * `[REDACTED:<kind>]` marker. Idempotent — re-running on already redacted
+ * text only matches new tokens.
+ *
+ * Empty / non-string input passes through unchanged so the caller can use
+ * this as a no-op on optional fields.
+ */
+export function redactSecrets(input) {
+    if (!input)
+        return input;
+    let out = input;
+    for (const { name, regex } of PATTERNS) {
+        out = out.replace(regex, `[REDACTED:${name}]`);
+    }
+    out = out
+        .replace(API_KEY_HEADER, (_match, prefix, quote, name, separator, value) => redactApiKeyHeaderValue(prefix, quote, name, separator, value))
+        .replace(API_KEY_QUERY, '$1[REDACTED:api_key_query]');
+    out = out.replace(CARD_CANDIDATE, (match) => {
+        const digits = match.replace(/\D/g, '');
+        return isLuhnValid(digits) ? '[REDACTED:credit_card]' : match;
+    });
+    return out;
+}
+/**
+ * Same as {@link redactSecrets} but also returns per-category counts so the
+ * caller can attach an audit summary to the trace metadata ('we stripped 2
+ * keys + 1 email before send').
+ */
+export function redactSecretsWithCounts(input) {
+    const counts = {};
+    if (!input)
+        return { redacted: input, counts };
+    let out = input;
+    for (const { name, regex } of PATTERNS) {
+        let matched = 0;
+        out = out.replace(regex, () => {
+            matched += 1;
+            return `[REDACTED:${name}]`;
+        });
+        if (matched > 0)
+            counts[name] = matched;
+    }
+    let apiKeyHeaderCount = 0;
+    out = out.replace(API_KEY_HEADER, (_match, prefix, quote, name, separator, value) => {
+        apiKeyHeaderCount += 1;
+        return redactApiKeyHeaderValue(prefix, quote, name, separator, value);
+    });
+    if (apiKeyHeaderCount > 0)
+        counts.api_key_header = apiKeyHeaderCount;
+    let apiKeyQueryCount = 0;
+    out = out.replace(API_KEY_QUERY, (_match, prefix) => {
+        apiKeyQueryCount += 1;
+        return `${prefix}[REDACTED:api_key_query]`;
+    });
+    if (apiKeyQueryCount > 0)
+        counts.api_key_query = apiKeyQueryCount;
+    let cardCount = 0;
+    out = out.replace(CARD_CANDIDATE, (match) => {
+        const digits = match.replace(/\D/g, '');
+        if (isLuhnValid(digits)) {
+            cardCount += 1;
+            return '[REDACTED:credit_card]';
+        }
+        return match;
+    });
+    if (cardCount > 0)
+        counts.credit_card = cardCount;
+    return { redacted: out, counts };
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"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"}

package/dist/token.d.ts

@@ -0,0 +1,22 @@
+export interface Token<T, Id extends string = string> {
+    readonly id: Id;
+    readonly version: number;
+    readonly cardinality: 'one';
+    /** Phantom — never assigned; carries T for inference only. */
+    readonly __type?: T;
+}
+export interface ManyToken<T, Id extends string = string> {
+    readonly id: Id;
+    readonly version: number;
+    readonly cardinality: 'many';
+    /** Phantom — never assigned; carries T for inference only. */
+    readonly __type?: T;
+}
+export type AnyToken<T = unknown, Id extends string = string> = Token<T, Id> | ManyToken<T, Id>;
+export declare function token<T, const Id extends string = string>(id: Id, opts?: {
+    version?: number;
+}): Token<T, Id>;
+export declare function manyToken<T, const Id extends string = string>(id: Id, opts?: {
+    version?: number;
+}): ManyToken<T, Id>;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK,CAAC,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM;IAClD,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM;IACtD,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;CACrB;AAED,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAEhG,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAEhH;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAC3D,EAAE,EAAE,EAAE,EACN,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAElB"}

package/dist/token.js

@@ -0,0 +1,7 @@
+export function token(id, opts = {}) {
+    return { id, version: opts.version ?? 1, cardinality: 'one' };
+}
+export function manyToken(id, opts = {}) {
+    return { id, version: opts.version ?? 1, cardinality: 'many' };
+}
+//# sourceMappingURL=token.js.map