ysk-omni 1.0.0

package/dist/utils/api-key-crypto.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiKeySecret = createApiKeySecret;
+exports.apiKeyPrefix = apiKeyPrefix;
+exports.hashApiKeySha256 = hashApiKeySha256;
+exports.scryptHash = scryptHash;
+exports.hashApiKey = hashApiKey;
+exports.verifyApiKey = verifyApiKey;
+/**
+ * API key secret generation + hashing (shared by HTTP API + CLI).
+ * Prefer scrypt for new keys; SHA-256 remains verifiable for legacy rows.
+ */
+const node_crypto_1 = require("node:crypto");
+const constants_1 = require("../config/constants");
+function createApiKeySecret() {
+    return `${constants_1.API_KEY_PREFIX}${(0, node_crypto_1.randomBytes)(24).toString('base64url')}`;
+}
+function apiKeyPrefix(rawKey) {
+    return rawKey.slice(0, 16);
+}
+/** Legacy: plain SHA-256 hex (64 chars). */
+function hashApiKeySha256(rawKey) {
+    return (0, node_crypto_1.createHash)('sha256').update(rawKey, 'utf8').digest('hex');
+}
+/** Preferred: scrypt$saltHex$hashHex */
+function scryptHash(rawKey, salt = (0, node_crypto_1.randomBytes)(16)) {
+    const hash = (0, node_crypto_1.scryptSync)(rawKey, salt, 32);
+    return `scrypt$${salt.toString('hex')}$${hash.toString('hex')}`;
+}
+/** New keys: scrypt. */
+function hashApiKey(rawKey) {
+    return scryptHash(rawKey);
+}
+function verifyApiKey(rawKey, keyHash) {
+    try {
+        if (keyHash.startsWith('scrypt$')) {
+            const parts = keyHash.split('$');
+            if (parts.length !== 3)
+                return false;
+            const salt = Buffer.from(parts[1], 'hex');
+            const expected = Buffer.from(parts[2], 'hex');
+            const actual = (0, node_crypto_1.scryptSync)(rawKey, salt, expected.length);
+            return (0, node_crypto_1.timingSafeEqual)(actual, expected);
+        }
+        const computed = hashApiKeySha256(rawKey);
+        return (0, node_crypto_1.timingSafeEqual)(Buffer.from(computed, 'hex'), Buffer.from(keyHash, 'hex'));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=api-key-crypto.js.map

package/dist/utils/api-key-crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-crypto.js","sourceRoot":"","sources":["../../src/utils/api-key-crypto.ts"],"names":[],"mappings":";;AAOA,gDAEC;AAED,oCAEC;AAGD,4CAEC;AAGD,gCAGC;AAGD,gCAEC;AAED,oCAkBC;AAjDD;;;GAGG;AACH,6CAAmF;AACnF,mDAAqD;AAErD,SAAgB,kBAAkB;IAChC,OAAO,GAAG,0BAAc,GAAG,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;AACrE,CAAC;AAED,SAAgB,YAAY,CAAC,MAAc;IACzC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,4CAA4C;AAC5C,SAAgB,gBAAgB,CAAC,MAAc;IAC7C,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,wCAAwC;AACxC,SAAgB,UAAU,CAAC,MAAc,EAAE,IAAI,GAAG,IAAA,yBAAW,EAAC,EAAE,CAAC;IAC/D,MAAM,IAAI,GAAG,IAAA,wBAAU,EAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAC1C,OAAO,UAAU,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,wBAAwB;AACxB,SAAgB,UAAU,CAAC,MAAc;IACvC,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,SAAgB,YAAY,CAAC,MAAc,EAAE,OAAe;IAC1D,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACrC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,KAAK,CAAC,CAAC;YAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,KAAK,CAAC,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAA,wBAAU,EAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;YACzD,OAAO,IAAA,6BAAe,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC1C,OAAO,IAAA,6BAAe,EACpB,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,EAC5B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAC5B,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/utils/api-key-id.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OTP Admin sessions use synthetic ids (`admin-session:…`) that are not rows
+ * in `api_keys`. Using them as FK → Prisma P2003 / HTTP 500.
+ */
+export declare function isSyntheticApiKeyId(id: string | null | undefined): boolean;
+/** For AuditLog.apiKeyId (nullable FK). */
+export declare function toAuditApiKeyId(id: string | null | undefined): string | null;
+/**
+ * For Document / ChatRequest ownership (required FK).
+ * Prefer a real key id; otherwise fall back to the oldest active admin key.
+ */
+export declare function toPersistentApiKeyId(preferredId: string | null | undefined): Promise<string>;
+//# sourceMappingURL=api-key-id.d.ts.map

package/dist/utils/api-key-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-id.d.ts","sourceRoot":"","sources":["../../src/utils/api-key-id.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAM1E;AAED,2CAA2C;AAC3C,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAE5E;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/dist/utils/api-key-id.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSyntheticApiKeyId = isSyntheticApiKeyId;
+exports.toAuditApiKeyId = toAuditApiKeyId;
+exports.toPersistentApiKeyId = toPersistentApiKeyId;
+const database_1 = require("../config/database");
+const constants_1 = require("../config/constants");
+const exception_factory_1 = require("../exceptions/exception.factory");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * OTP Admin sessions use synthetic ids (`admin-session:…`) that are not rows
+ * in `api_keys`. Using them as FK → Prisma P2003 / HTTP 500.
+ */
+function isSyntheticApiKeyId(id) {
+    if (!id)
+        return true;
+    if (id.startsWith('admin-session:'))
+        return true;
+    if (id.startsWith('otp_sess'))
+        return true;
+    if (!UUID_RE.test(id))
+        return true;
+    return false;
+}
+/** For AuditLog.apiKeyId (nullable FK). */
+function toAuditApiKeyId(id) {
+    return isSyntheticApiKeyId(id) ? null : id;
+}
+/**
+ * For Document / ChatRequest ownership (required FK).
+ * Prefer a real key id; otherwise fall back to the oldest active admin key.
+ */
+async function toPersistentApiKeyId(preferredId) {
+    if (preferredId && !isSyntheticApiKeyId(preferredId)) {
+        const exists = await database_1.prisma.apiKey.findUnique({
+            where: { id: preferredId },
+            select: { id: true },
+        });
+        if (exists)
+            return exists.id;
+    }
+    const admin = await database_1.prisma.apiKey.findFirst({
+        where: { isActive: true, role: constants_1.ROLES.ADMIN },
+        orderBy: { createdAt: 'asc' },
+        select: { id: true },
+    });
+    if (admin)
+        return admin.id;
+    throw exception_factory_1.ExceptionFactory.internal('No admin API key available for resource ownership — create an admin API key (ysk-omni key create)');
+}
+//# sourceMappingURL=api-key-id.js.map

package/dist/utils/api-key-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-id.js","sourceRoot":"","sources":["../../src/utils/api-key-id.ts"],"names":[],"mappings":";;AAWA,kDAMC;AAGD,0CAEC;AAMD,oDAqBC;AAjDD,iDAA4C;AAC5C,mDAA4C;AAC5C,uEAAmE;AAEnE,MAAM,OAAO,GACX,4EAA4E,CAAC;AAE/E;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,EAA6B;IAC/D,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IACrB,IAAI,EAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2CAA2C;AAC3C,SAAgB,eAAe,CAAC,EAA6B;IAC3D,OAAO,mBAAmB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,EAAa,CAAC;AACzD,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,oBAAoB,CACxC,WAAsC;IAEtC,IAAI,WAAW,IAAI,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,MAAM,iBAAM,CAAC,MAAM,CAAC,UAAU,CAAC;YAC5C,KAAK,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE;YAC1B,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE;SACrB,CAAC,CAAC;QACH,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,iBAAM,CAAC,MAAM,CAAC,SAAS,CAAC;QAC1C,KAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,iBAAK,CAAC,KAAK,EAAE;QAC5C,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE;QAC7B,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE;KACrB,CAAC,CAAC;IACH,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,EAAE,CAAC;IAE3B,MAAM,oCAAgB,CAAC,QAAQ,CAC7B,mGAAmG,CACpG,CAAC;AACJ,CAAC"}

package/dist/utils/async-handler.d.ts

@@ -0,0 +1,5 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+type AsyncRequestHandler = (req: Request, res: Response, next: NextFunction) => Promise<unknown>;
+export declare function asyncHandler(fn: AsyncRequestHandler): RequestHandler;
+export {};
+//# sourceMappingURL=async-handler.d.ts.map

package/dist/utils/async-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-handler.d.ts","sourceRoot":"","sources":["../../src/utils/async-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/E,KAAK,mBAAmB,GAAG,CACzB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,KACf,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,wBAAgB,YAAY,CAAC,EAAE,EAAE,mBAAmB,GAAG,cAAc,CAIpE"}

package/dist/utils/async-handler.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asyncHandler = asyncHandler;
+function asyncHandler(fn) {
+    return (req, res, next) => {
+        Promise.resolve(fn(req, res, next)).catch(next);
+    };
+}
+//# sourceMappingURL=async-handler.js.map

package/dist/utils/async-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-handler.js","sourceRoot":"","sources":["../../src/utils/async-handler.ts"],"names":[],"mappings":";;AAQA,oCAIC;AAJD,SAAgB,YAAY,CAAC,EAAuB;IAClD,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACxB,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/client-ip.d.ts

@@ -0,0 +1,28 @@
+import type { Request } from 'express';
+import type { ProxyIpConfig } from '../interfaces/proxy-ip-config.interface';
+export type { ProxyIpSource } from '../interfaces/proxy-ip-source.type';
+export type { ProxyIpConfig } from '../interfaces/proxy-ip-config.interface';
+/** Default: only local reverse proxies (same host) may inject IP headers. */
+export declare const DEFAULT_TRUSTED_PROXIES: string[];
+export declare function getProxyIpConfig(): ProxyIpConfig;
+export declare function setProxyIpConfig(partial: Partial<ProxyIpConfig>): ProxyIpConfig;
+export declare function resetProxyIpConfig(cfg?: ProxyIpConfig): void;
+/** TCP peer (immediate connection), never from headers. */
+export declare function getSocketIp(req: Request): string;
+/**
+ * True when the connecting peer is allowed to set client-IP headers.
+ * Uses exact + CIDR match via ipAllowed.
+ */
+export declare function isTrustedProxyPeer(peerIp: string, trustedProxies?: string[]): boolean;
+/** Prefer middleware-resolved clientIp; fall back to live resolve. */
+export declare function requestIp(req: Request): string;
+/**
+ * Resolve client IP for rate-limit / ban / audit / DDoS.
+ *
+ * Security: proxy headers are ignored unless the TCP peer is in trustedProxies.
+ * Untrusted peers always get the socket IP (cannot spoof CF-Connecting-IP etc.).
+ */
+export declare function getClientIp(req: Request, override?: Partial<ProxyIpConfig>): string;
+/** Express `trust proxy` setting from hops count. */
+export declare function expressTrustProxySetting(hops: number): boolean | number;
+//# sourceMappingURL=client-ip.d.ts.map

package/dist/utils/client-ip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-ip.d.ts","sourceRoot":"","sources":["../../src/utils/client-ip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAS7E,YAAY,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAE7E,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,UAAuB,CAAC;AAa5D,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAa/E;AAED,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,IAAI,CAW5D;AAoDD,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAMhD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,MAAM,EAAE,GACxB,OAAO,CAQT;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAG9C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAChC,MAAM,CA8DR;AAED,qDAAqD;AACrD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAIvE"}

package/dist/utils/client-ip.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TRUSTED_PROXIES = void 0;
+exports.getProxyIpConfig = getProxyIpConfig;
+exports.setProxyIpConfig = setProxyIpConfig;
+exports.resetProxyIpConfig = resetProxyIpConfig;
+exports.getSocketIp = getSocketIp;
+exports.isTrustedProxyPeer = isTrustedProxyPeer;
+exports.requestIp = requestIp;
+exports.getClientIp = getClientIp;
+exports.expressTrustProxySetting = expressTrustProxySetting;
+const ip_match_1 = require("./ip-match");
+/** Default: only local reverse proxies (same host) may inject IP headers. */
+exports.DEFAULT_TRUSTED_PROXIES = ['127.0.0.1', '::1'];
+const DEFAULT_CFG = {
+    trustHops: 1,
+    source: 'auto',
+    trustedProxies: [...exports.DEFAULT_TRUSTED_PROXIES],
+};
+let runtimeCfg = {
+    ...DEFAULT_CFG,
+    trustedProxies: [...exports.DEFAULT_TRUSTED_PROXIES],
+};
+function getProxyIpConfig() {
+    return runtimeCfg;
+}
+function setProxyIpConfig(partial) {
+    runtimeCfg = {
+        trustHops: clampHops(partial.trustHops != null ? partial.trustHops : runtimeCfg.trustHops),
+        source: normalizeSource(partial.source ?? runtimeCfg.source),
+        trustedProxies: sanitizeTrusted(partial.trustedProxies !== undefined
+            ? partial.trustedProxies
+            : runtimeCfg.trustedProxies),
+    };
+    return runtimeCfg;
+}
+function resetProxyIpConfig(cfg) {
+    runtimeCfg = cfg
+        ? {
+            trustHops: clampHops(cfg.trustHops),
+            source: normalizeSource(cfg.source),
+            trustedProxies: sanitizeTrusted(cfg.trustedProxies),
+        }
+        : {
+            ...DEFAULT_CFG,
+            trustedProxies: [...exports.DEFAULT_TRUSTED_PROXIES],
+        };
+}
+function clampHops(n) {
+    if (!Number.isFinite(n))
+        return 1;
+    return Math.max(0, Math.min(10, Math.floor(n)));
+}
+function normalizeSource(s) {
+    const v = String(s || 'auto');
+    if (v === 'cloudflare' ||
+        v === 'nginx' ||
+        v === 'x-forwarded-for' ||
+        v === 'socket' ||
+        v === 'auto') {
+        return v;
+    }
+    return 'auto';
+}
+/** Reject world-open CIDRs that would enable IP header spoofing. */
+function isOverlyBroadCidr(entry) {
+    const e = entry.trim().toLowerCase();
+    return (e === '0.0.0.0/0' ||
+        e === '::/0' ||
+        e === '0.0.0.0' ||
+        e === '::' ||
+        e === '*');
+}
+function sanitizeTrusted(list) {
+    const parsed = (0, ip_match_1.parseIpList)(list ?? []).filter((e) => !isOverlyBroadCidr(e));
+    if (!parsed.length)
+        return [...exports.DEFAULT_TRUSTED_PROXIES];
+    // Always keep loopback as safe defaults alongside custom list
+    const set = new Set([...exports.DEFAULT_TRUSTED_PROXIES, ...parsed]);
+    return [...set].filter(ip_match_1.isValidIpOrCidr);
+}
+function header(req, name) {
+    const raw = req.headers[name];
+    if (!raw)
+        return '';
+    const v = Array.isArray(raw) ? raw[0] : raw;
+    return String(v || '').trim();
+}
+function firstIpFromList(value) {
+    return value.split(',')[0]?.trim() || '';
+}
+/** TCP peer (immediate connection), never from headers. */
+function getSocketIp(req) {
+    const socketRaw = req.socket?.remoteAddress ||
+        req.connection?.remoteAddress ||
+        '';
+    return socketRaw ? (0, ip_match_1.normalizeIp)(socketRaw) : '';
+}
+/**
+ * True when the connecting peer is allowed to set client-IP headers.
+ * Uses exact + CIDR match via ipAllowed.
+ */
+function isTrustedProxyPeer(peerIp, trustedProxies) {
+    const list = trustedProxies && trustedProxies.length
+        ? trustedProxies
+        : runtimeCfg.trustedProxies;
+    if (!peerIp || peerIp === 'unknown')
+        return false;
+    // ipAllowed: empty list = allow all — we never pass empty after sanitize
+    return (0, ip_match_1.ipAllowed)(peerIp, list.length ? list : exports.DEFAULT_TRUSTED_PROXIES);
+}
+/** Prefer middleware-resolved clientIp; fall back to live resolve. */
+function requestIp(req) {
+    if (req.clientIp)
+        return req.clientIp;
+    return getClientIp(req);
+}
+/**
+ * Resolve client IP for rate-limit / ban / audit / DDoS.
+ *
+ * Security: proxy headers are ignored unless the TCP peer is in trustedProxies.
+ * Untrusted peers always get the socket IP (cannot spoof CF-Connecting-IP etc.).
+ */
+function getClientIp(req, override) {
+    const cfg = {
+        trustHops: clampHops(override?.trustHops ?? runtimeCfg.trustHops),
+        source: normalizeSource(override?.source ?? runtimeCfg.source),
+        trustedProxies: sanitizeTrusted(override?.trustedProxies ?? runtimeCfg.trustedProxies),
+    };
+    const socketIp = getSocketIp(req);
+    if (!socketIp)
+        return 'unknown';
+    if (cfg.source === 'socket' || cfg.trustHops <= 0) {
+        return socketIp;
+    }
+    // CRITICAL: never trust client-supplied IP headers from untrusted peers
+    if (!isTrustedProxyPeer(socketIp, cfg.trustedProxies)) {
+        return socketIp;
+    }
+    const pickHeader = (name) => {
+        const h = header(req, name);
+        if (!h)
+            return null;
+        const ip = (0, ip_match_1.normalizeIp)(firstIpFromList(h));
+        return ip && ip !== 'unknown' ? ip : null;
+    };
+    // Cloudflare headers only when explicitly selected, or auto + CF-Ray
+    // (nginx on loopback must not honor a client-injected CF-Connecting-IP).
+    const looksLikeCloudflare = Boolean(header(req, 'cf-ray'));
+    if (cfg.source === 'cloudflare' ||
+        (cfg.source === 'auto' && looksLikeCloudflare)) {
+        const cf = pickHeader('cf-connecting-ip') || pickHeader('true-client-ip');
+        if (cf)
+            return cf;
+    }
+    // nginx X-Real-IP
+    if (cfg.source === 'nginx' || cfg.source === 'auto') {
+        const real = pickHeader('x-real-ip');
+        if (real)
+            return real;
+    }
+    // Express trust-proxy hop parsing of X-Forwarded-For
+    if (cfg.source === 'x-forwarded-for' ||
+        cfg.source === 'auto' ||
+        cfg.source === 'nginx' ||
+        cfg.source === 'cloudflare') {
+        if (req.ip) {
+            const fromExpress = (0, ip_match_1.normalizeIp)(req.ip);
+            if (fromExpress && fromExpress !== 'unknown')
+                return fromExpress;
+        }
+        // Trusted peer only: take rightmost-1 style is Express job; if missing,
+        // do NOT use leftmost (attacker-controlled). Prefer socket as last resort.
+    }
+    return socketIp;
+}
+/** Express `trust proxy` setting from hops count. */
+function expressTrustProxySetting(hops) {
+    const n = clampHops(hops);
+    if (n <= 0)
+        return false;
+    return n;
+}
+//# sourceMappingURL=client-ip.js.map

package/dist/utils/client-ip.js.map

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

package/dist/utils/engine-event-parse.d.ts

@@ -0,0 +1,24 @@
+import type { EngineToolCall, EngineUsage } from '../interfaces/engine-collected-output.interface';
+import type { EngineResponseMeta } from '../interfaces/engine-response-meta.interface';
+/** Parse usage object from end event. */
+export declare function parseEngineUsage(raw: unknown): EngineUsage | undefined;
+/**
+ * Extract OpenAI-style tool_calls from stream events.
+ * Handles multiple event shapes (tool_call, tool_use, function_call, batches).
+ */
+export declare function parseEngineToolCallEvent(event: {
+    type?: string;
+    data?: unknown;
+    [k: string]: unknown;
+}): EngineToolCall[];
+export declare function usageToOpenAi(u?: EngineUsage): {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+        cache_creation_tokens?: number;
+    };
+};
+export declare function engineUsageToMetaCost(u?: EngineUsage): EngineResponseMeta['cost'] | undefined;
+//# sourceMappingURL=engine-event-parse.d.ts.map

package/dist/utils/engine-event-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-event-parse.d.ts","sourceRoot":"","sources":["../../src/utils/engine-event-parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACZ,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAGvF,yCAAyC;AACzC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAsDtE;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,GAAG,cAAc,EAAE,CA8FnB;AAED,wBAAgB,aAAa,CAAC,CAAC,CAAC,EAAE,WAAW,GAAG;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;CACH,CAqBA;AAED,wBAAgB,qBAAqB,CACnC,CAAC,CAAC,EAAE,WAAW,GACd,kBAAkB,CAAC,MAAM,CAAC,GAAG,SAAS,CAgBxC"}

package/dist/utils/engine-event-parse.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEngineUsage = parseEngineUsage;
+exports.parseEngineToolCallEvent = parseEngineToolCallEvent;
+exports.usageToOpenAi = usageToOpenAi;
+exports.engineUsageToMetaCost = engineUsageToMetaCost;
+const id_1 = require("./id");
+/** Parse usage object from end event. */
+function parseEngineUsage(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const u = raw;
+    const out = {};
+    if (typeof u.input_tokens === 'number')
+        out.input_tokens = u.input_tokens;
+    if (typeof u.output_tokens === 'number')
+        out.output_tokens = u.output_tokens;
+    if (typeof u.total_tokens === 'number')
+        out.total_tokens = u.total_tokens;
+    if (typeof u.reasoning_tokens === 'number') {
+        out.reasoning_tokens = u.reasoning_tokens;
+    }
+    if (typeof u.cache_read_input_tokens === 'number') {
+        out.cache_read_input_tokens = u.cache_read_input_tokens;
+    }
+    if (typeof u.cache_creation_input_tokens === 'number') {
+        out.cache_creation_input_tokens = u.cache_creation_input_tokens;
+    }
+    if (typeof u.inputTokens === 'number')
+        out.input_tokens = u.inputTokens;
+    if (typeof u.outputTokens === 'number')
+        out.output_tokens = u.outputTokens;
+    if (typeof u.totalTokens === 'number')
+        out.total_tokens = u.totalTokens;
+    if (typeof u.cacheReadInputTokens === 'number') {
+        out.cache_read_input_tokens = u.cacheReadInputTokens;
+    }
+    if (typeof u.cacheCreationInputTokens === 'number') {
+        out.cache_creation_input_tokens = u.cacheCreationInputTokens;
+    }
+    if (typeof u.usage_is_incomplete === 'boolean') {
+        out.usage_is_incomplete = u.usage_is_incomplete;
+    }
+    if (typeof u.cost_is_partial === 'boolean') {
+        out.cost_is_partial = u.cost_is_partial;
+    }
+    if (typeof u.total_cost_usd === 'number') {
+        out.total_cost_usd = u.total_cost_usd;
+    }
+    if (typeof u.total_cost_usd_ticks === 'number') {
+        out.total_cost_usd_ticks = u.total_cost_usd_ticks;
+    }
+    if (out.input_tokens == null &&
+        out.output_tokens == null &&
+        out.total_tokens == null &&
+        out.cache_read_input_tokens == null &&
+        out.cache_creation_input_tokens == null) {
+        return undefined;
+    }
+    if (out.total_tokens == null) {
+        out.total_tokens =
+            (out.input_tokens || 0) +
+                (out.cache_read_input_tokens || 0) +
+                (out.cache_creation_input_tokens || 0) +
+                (out.output_tokens || 0);
+    }
+    return out;
+}
+function newToolCallId() {
+    return `call_${(0, id_1.createId)().replace(/-/g, '').slice(0, 24)}`;
+}
+/**
+ * Extract OpenAI-style tool_calls from stream events.
+ * Handles multiple event shapes (tool_call, tool_use, function_call, batches).
+ */
+function parseEngineToolCallEvent(event) {
+    const t = String(event.type || '').toLowerCase();
+    const out = [];
+    if (t === 'tool_call_update' ||
+        t === 'usage' ||
+        t === 'plan' ||
+        t === 'available_commands' ||
+        t === 'thought' ||
+        t === 'text') {
+        return out;
+    }
+    const push = (name, args, id) => {
+        if (!name)
+            return;
+        out.push({
+            id: id || newToolCallId(),
+            type: 'function',
+            function: {
+                name,
+                arguments: typeof args === 'string' ? args : JSON.stringify(args ?? {}),
+            },
+        });
+    };
+    const fromObj = (d) => {
+        const fn = d.function && typeof d.function === 'object'
+            ? d.function
+            : undefined;
+        const name = String(d.name ||
+            d.tool ||
+            d.toolName ||
+            d.tool_name ||
+            fn?.name ||
+            '');
+        const args = d.arguments ??
+            d.rawInput ??
+            d.input ??
+            d.parameters ??
+            d.args ??
+            fn?.arguments;
+        const id = (typeof d.id === 'string' && d.id) ||
+            (typeof d.toolCallId === 'string' && d.toolCallId) ||
+            undefined;
+        push(name, args, id);
+    };
+    if (t === 'tool_call' ||
+        t === 'tool' ||
+        t === 'function_call' ||
+        t === 'tool_use' ||
+        t === 'tool_request' ||
+        t === 'invoke_tool') {
+        const d = event.data && typeof event.data === 'object'
+            ? event.data
+            : event;
+        fromObj(d);
+    }
+    // Nested data.tool_calls
+    const dataObj = event.data && typeof event.data === 'object'
+        ? event.data
+        : null;
+    if (dataObj && Array.isArray(dataObj.tool_calls)) {
+        for (const tc of dataObj.tool_calls) {
+            if (tc && typeof tc === 'object')
+                fromObj(tc);
+        }
+    }
+    if (Array.isArray(event.tool_calls)) {
+        for (const tc of event.tool_calls) {
+            if (tc && typeof tc === 'object')
+                fromObj(tc);
+        }
+    }
+    // end event sometimes embeds tool_calls
+    if (t === 'end' && Array.isArray(event.tool_calls)) {
+        for (const tc of event.tool_calls) {
+            if (tc && typeof tc === 'object')
+                fromObj(tc);
+        }
+    }
+    return out;
+}
+function usageToOpenAi(u) {
+    const cached = u?.cache_read_input_tokens;
+    const created = u?.cache_creation_input_tokens;
+    const prompt = (u?.input_tokens ?? 0) + (cached ?? 0) + (created ?? 0);
+    const completion = u?.output_tokens ?? 0;
+    const details = cached != null || created != null
+        ? {
+            ...(cached != null ? { cached_tokens: cached } : {}),
+            ...(created != null ? { cache_creation_tokens: created } : {}),
+        }
+        : undefined;
+    return {
+        prompt_tokens: prompt,
+        completion_tokens: completion,
+        total_tokens: u?.total_tokens ?? prompt + completion,
+        ...(details && Object.keys(details).length
+            ? { prompt_tokens_details: details }
+            : {}),
+    };
+}
+function engineUsageToMetaCost(u) {
+    if (!u)
+        return undefined;
+    if (u.total_cost_usd == null &&
+        u.total_cost_usd_ticks == null &&
+        u.cost_is_partial == null &&
+        u.usage_is_incomplete == null) {
+        return undefined;
+    }
+    return {
+        total_cost_usd: u.total_cost_usd,
+        total_cost_usd_ticks: u.total_cost_usd_ticks,
+        cost_is_partial: u.cost_is_partial,
+        usage_is_incomplete: u.usage_is_incomplete,
+    };
+}
+//# sourceMappingURL=engine-event-parse.js.map

package/dist/utils/engine-event-parse.js.map

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

package/dist/utils/engine-session.d.ts

@@ -0,0 +1,25 @@
+export declare function isUuid(value: string): boolean;
+/** RFC 4122 UUID v5 (SHA-1 name-based). */
+export declare function uuidV5(name: string, namespace?: string): string;
+/**
+ * Deterministic local engine session UUID for a tenant + client session id.
+ * 1.0+ requires `-s` to be a UUID and only accepts it on first create.
+ */
+export declare function namespacedEngineSessionId(apiKeyId: string, clientSessionId: string): string;
+export type EngineSessionCliMode = 'create' | 'resume';
+export type ResolvedEngineSession = {
+    mode: EngineSessionCliMode;
+    engineSessionId: string;
+};
+/**
+ * Decide create (`-s`) vs resume (`--resume`) for a client `session_id`.
+ * `knownEngineSessionId` comes from a persisted alias row.
+ */
+export declare function resolveEngineSessionBinding(input: {
+    apiKeyId: string;
+    clientSessionId: string;
+    knownEngineSessionId?: string | null;
+    knownByEngineId?: string | null;
+}): ResolvedEngineSession;
+export declare function isSessionAlreadyExistsError(err: unknown): boolean;
+//# sourceMappingURL=engine-session.d.ts.map

package/dist/utils/engine-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-session.d.ts","sourceRoot":"","sources":["../../src/utils/engine-session.ts"],"names":[],"mappings":"AAQA,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7C;AAWD,2CAA2C;AAC3C,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAoB,GAAG,MAAM,CAS1E;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,MAAM,CAGR;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,GAAG,qBAAqB,CAcxB;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAmBjE"}