@zintrust/trace 0.9.3 → 0.9.4

package/README.md

@@ -32,6 +32,13 @@ You can still import the package migrations manually if you prefer to keep them
 TRACE_ENABLED=true
 TRACE_DB_CONNECTION=d1        # optional — omit to inherit DB_CONNECTION
 TRACE_QUERY_CONNECTION=main   # optional — app DB to observe for SQL traces
+TRACE_SERVICE_TAG=            # optional — global trace tag, falls back to APP_NAME when empty
+TRACE_PROXY=false             # optional — send writes to a remote trace server instead of local DB
+TRACE_PROXY_URL=              # required when TRACE_PROXY=true
+TRACE_PROXY_PATH=/zin/trace/write
+TRACE_PROXY_KEY_ID=           # optional — falls back to APP_NAME
+TRACE_PROXY_SECRET=           # optional — falls back to APP_KEY
+TRACE_PROXY_TIMEOUT_MS=30000
 TRACE_PRUNE_HOURS=24          # how long entries are kept (default: 24)
 TRACE_SLOW_QUERY_MS=100       # slow-query threshold in ms (default: 100)
 TRACE_LOG_LEVEL=info          # minimum log level captured (default: info)
@@ -52,6 +59,8 @@ TRACE_REDACT_QUERY=
 
 When `TRACE_CONTENT_QUEUE_DRIVER` is set, trace writes enqueue through that registered queue driver and an internal trace worker drains them outside the live request path. When it is unset, oversized content is replaced with `Trace content exceeded budget and was replaced.` before persistence instead of running the heavy compaction loop inline.
 
+When `TRACE_PROXY=true`, the local runtime keeps collecting the same trace payload it would normally send to storage, but it sends the write/update/stale-family operations to `TRACE_PROXY_URL + TRACE_PROXY_PATH` instead of writing directly to the local trace database. The receiver can then persist those entries with the standard `TraceStorage` flow.
+
 This currently works with any queue driver already registered in ZinTrust. First-class Cloudflare Queue support still requires a dedicated queue driver and queue-runtime registration for that transport.
 
 ### 2. Enable the plugin in `zintrust.plugins.*`
@@ -154,6 +163,28 @@ registerTraceDashboard(router, {
 });
 ```
 
+### 3b. Optional remote trace ingest gateway
+
+If you want one project to send trace writes to another project, mount the signed ingest gateway on the trace server:
+
+```ts
+// routes/api.ts
+import { registerTraceIngestGateway } from '@zintrust/trace';
+
+registerTraceIngestGateway(router, {
+  basePath: '/zin/trace/write',
+  middleware: ['admin'], // optional
+});
+```
+
+The sender runtime uses `TRACE_PROXY_URL`, `TRACE_PROXY_PATH`, `TRACE_PROXY_KEY_ID`, and `TRACE_PROXY_SECRET` to sign write requests. On the receiver side, `TRACE_PROXY_KEY_ID` and `TRACE_PROXY_SECRET` must match the sender pair or fall back to the same `APP_NAME` and `APP_KEY` values.
+
+The ingest gateway exposes exactly these signed POST endpoints:
+
+- `TRACE_PROXY_PATH` for new trace entries
+- `TRACE_PROXY_PATH + /update` for trace content updates
+- `TRACE_PROXY_PATH + /mark-family-stale` for latest-entry rotation
+
 The dashboard SPA will be available at `GET /trace` (or your chosen `basePath`).
 
 If you need custom storage wiring, keep using the low-level route registrar:

package/dist/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.9.3",
-  "buildDate": "2026-04-22T15:48:24.454Z",
+  "version": "0.9.4",
+  "buildDate": "2026-04-23T11:29:28.904Z",
   "buildEnvironment": {
-    "node": "v20.20.2",
-    "platform": "linux",
-    "arch": "x64"
+    "node": "v22.22.1",
+    "platform": "darwin",
+    "arch": "arm64"
   },
   "git": {
-    "commit": "552dfdf4",
-    "branch": "master"
+    "commit": "eebcc3ad",
+    "branch": "release"
   },
   "package": {
     "engines": {
@@ -29,6 +29,10 @@
       "size": 4640,
       "sha256": "c51cc312046b6b2bbe1673f1ff9508425cc7140a1d2341907f67aa36069c09f9"
     },
+    "build-manifest.json": {
+      "size": 14744,
+      "sha256": "92fc9e1e76ba84696dbdaf02aa2ed7588c6e1234d586e24bf8bab4f54104ad61"
+    },
     "cli-register.d.ts": {
       "size": 255,
       "sha256": "da8d689fe5ef32e97e755f28017e4d3cb1aa63489073a71907ea41ad5761ede9"
@@ -42,8 +46,8 @@
       "sha256": "b034cbef0c71fb868071363624ef7a9f8d7acc20f8be8c895dd5db5a75e81f37"
     },
     "config.js": {
-      "size": 10064,
-      "sha256": "cef8c30f280d02b765c3930c1f5d9bac083596f9b944197fe4ad008be6627475"
+      "size": 10503,
+      "sha256": "4514e95067194c7afacb1202a8f1caffc64a400dd995cf809301b1a51a67da38"
     },
     "context.d.ts": {
       "size": 596,
@@ -78,12 +82,20 @@
       "sha256": "b260cd17012cd5bf5f24f24eb8958d0cf79bed1d976412def3706f960b3aefa6"
     },
     "index.d.ts": {
-      "size": 2599,
-      "sha256": "5ee9fa0c65942078a1ac7f38afcdc6b86595842191c766190974733c6f8d86c6"
+      "size": 2693,
+      "sha256": "901aaefe88fb2cc1e7771cd541f41ebcfe6443390bd66905eacbda51f1a6f73d"
     },
     "index.js": {
-      "size": 3324,
-      "sha256": "93a911d7f3813199936568bf8a63d598ec8f32a0006810453f0487a73e042ab3"
+      "size": 3421,
+      "sha256": "478b80c6aa6c2eea2d109aa2e6fe090d77469d186b3e6a19ababb7d1f6d0be7e"
+    },
+    "ingest/TraceIngestGateway.d.ts": {
+      "size": 786,
+      "sha256": "3a0a46fa5bbf5367047214533ec0ee92a171ee35a60d25c197eea1eed1ff0f65"
+    },
+    "ingest/TraceIngestGateway.js": {
+      "size": 8456,
+      "sha256": "56df56cecda7110d1096c3beef1ef62c386f4a0e85120ebfb4cdfc5ab3b758d7"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.d.ts": {
       "size": 304,
@@ -138,16 +150,32 @@
       "sha256": "71d366165dd36f1675aa253a76262b226fb6c62e5ab632746b8aea61c0c625fc"
     },
     "register.js": {
-      "size": 16585,
-      "sha256": "1e940ce8c216991572c633f34bc66ca6ef980c11e84042b02e957d99e142dbe5"
+      "size": 19822,
+      "sha256": "c553356d90c812f7de430d5679b1d44468131433e034ae2ea89e2876b1254444"
+    },
+    "storage/DebuggerStorage.d.ts": {
+      "size": 517,
+      "sha256": "c9c215aaa414f7b0c1fec6c82b054fc52bdf97af58f96f35c7f96672fb859c31"
+    },
+    "storage/DebuggerStorage.js": {
+      "size": 7442,
+      "sha256": "5ecce0fcfcf695df587a7b90a7a5c7efd2e64ad13c9f2d104b392f89f34f0dc4"
+    },
+    "storage/ProxyTraceStorage.d.ts": {
+      "size": 339,
+      "sha256": "9c724ff342dfe82da12e7cce95593f6623faa80c40f97593719b8e78e95f266d"
+    },
+    "storage/ProxyTraceStorage.js": {
+      "size": 4158,
+      "sha256": "097d82e94c6ef38661fb57a20d378ba890dbacd03a22666aaf4aba4dfdedf735"
     },
     "storage/TraceContentBudget.d.ts": {
       "size": 1306,
       "sha256": "606a37af0a4aef4866c22cc727f67f485c43181b40eb831e1920b8b90fdaf503"
     },
     "storage/TraceContentBudget.js": {
-      "size": 11412,
-      "sha256": "e5a72a6bb0c8bb432ea4aa7e8c5b43a8bf9e83d1b2935e102b4d1697da5fd18e"
+      "size": 11434,
+      "sha256": "f53229e7233cf13b095780451b68c912a95dc3f44e17c49289446219231e7e06"
     },
     "storage/TraceContentRedaction.d.ts": {
       "size": 207,
@@ -165,6 +193,14 @@
       "size": 2465,
       "sha256": "ace7e492373d2dccdbefe20040d30fffd7ad9f8e71113b7a044bddf92dcdf6fb"
     },
+    "storage/TraceServiceTag.d.ts": {
+      "size": 224,
+      "sha256": "35d93c82d6db80071946adaa8e40d012408b469949f1002f85ae3fd20b0a70c8"
+    },
+    "storage/TraceServiceTag.js": {
+      "size": 1916,
+      "sha256": "1ddad82563c98ddbb4033e9b8fb31901d635cffa7024d499a896f0d7a6d00900"
+    },
     "storage/TraceStorage.d.ts": {
       "size": 517,
       "sha256": "c9c215aaa414f7b0c1fec6c82b054fc52bdf97af58f96f35c7f96672fb859c31"
@@ -182,16 +218,16 @@
       "sha256": "6fc34e6e52a9b463db0967dba4aec4c8c706b6978c496f568637ffc15327279a"
     },
     "storage/index.d.ts": {
-      "size": 100,
-      "sha256": "1f2c1529bd5fa9c7a026695e4a8b184973b80d149afc778a8d86bcd03cbe093c"
+      "size": 210,
+      "sha256": "bb4c3a0c73eb3e2629dd1a1dbc29eecedd1910a37b221357cc7981ced320bdeb"
     },
     "storage/index.js": {
-      "size": 50,
-      "sha256": "d916e8e3abb1b1087f6b184851b0e6265e53380d7857b008e745d566aad15d44"
+      "size": 166,
+      "sha256": "ed5e83e108cd15f9a3976be71e966bdf0c44d8e0266d1d2dbad189f0885ad501"
     },
     "types.d.ts": {
-      "size": 9825,
-      "sha256": "53a1b2a572b9b5a73261f8c9b85903a3955bf71ec582f96c5b5249951aeb9b88"
+      "size": 10037,
+      "sha256": "68a2de953af2fce1a12447078177ff886f10e853c760378e13478b2558648868"
     },
     "types.js": {
       "size": 696,

package/dist/config.js

@@ -163,10 +163,27 @@ const mergeContentDispatch = (base, override) => {
             },
     };
 };
+const mergeProxyConfig = (base, override) => {
+    if (override === undefined)
+        return base;
+    return {
+        ...base,
+        ...override,
+    };
+};
 const DEFAULTS = Object.freeze({
     enabled: false,
     connection: undefined,
     observeConnection: undefined,
+    serviceTag: undefined,
+    proxy: {
+        enabled: false,
+        url: undefined,
+        path: '/zin/trace/write',
+        keyId: undefined,
+        secret: undefined,
+        timeoutMs: 30000,
+    },
     pruneAfterHours: 24,
     ignoreRoutes: ['/trace', '/health', '/ping'],
     ignorePaths: [],
@@ -247,6 +264,7 @@ export const TraceConfig = Object.freeze({
         return Object.freeze({
             ...DEFAULTS,
             ...overrides,
+            proxy: mergeProxyConfig(DEFAULTS.proxy, overrides.proxy),
             contentDispatch: mergeContentDispatch(DEFAULTS.contentDispatch, overrides.contentDispatch),
             watchers: mergeWatchers(DEFAULTS.watchers, overrides.watchers),
             redaction: {

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { TraceContentRedaction } from './storage/TraceContentRedaction';
 export { TraceContext } from './context';
 export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes';
 export type { TraceDashboardOptions, TraceDashboardRegistrationOptions } from './dashboard/routes';
+export { registerTraceIngestGateway, TraceIngestGateway } from './ingest/TraceIngestGateway';
 export { AuthWatcher } from './watchers/AuthWatcher';
 export { BatchWatcher } from './watchers/BatchWatcher';
 export { CacheWatcher } from './watchers/CacheWatcher';

package/dist/index.js

@@ -24,6 +24,7 @@ export { TraceContext } from './context.js';
 // Dashboard
 // ---------------------------------------------------------------------------
 export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes.js';
+export { registerTraceIngestGateway, TraceIngestGateway } from './ingest/TraceIngestGateway.js';
 // ---------------------------------------------------------------------------
 // Watchers (named re-exports for use with custom wiring)
 // ---------------------------------------------------------------------------

package/dist/ingest/TraceIngestGateway.d.ts

@@ -0,0 +1,22 @@
+import { type IRouter } from '@zintrust/core';
+import type { ITraceStorage } from '../types';
+type TraceIngestGatewaySettings = {
+    basePath: string;
+    keyId: string;
+    secret: string;
+    signingWindowMs: number;
+    nonceTtlMs: number;
+    middleware: ReadonlyArray<string>;
+    storage: ITraceStorage;
+};
+type TraceIngestGatewayOverrides = Partial<Omit<TraceIngestGatewaySettings, 'storage'> & {
+    storage: ITraceStorage;
+    connectionName: string;
+}>;
+export declare const TraceIngestGateway: Readonly<{
+    create(overrides?: TraceIngestGatewayOverrides): {
+        registerRoutes: (router: IRouter) => void;
+    };
+}>;
+export declare const registerTraceIngestGateway: (router: IRouter, overrides?: TraceIngestGatewayOverrides) => void;
+export default TraceIngestGateway;

package/dist/ingest/TraceIngestGateway.js

@@ -0,0 +1,215 @@
+import { Env, ErrorFactory, Router, SignedRequest, useDatabase, } from '@zintrust/core';
+import { TraceConfig } from '../config.js';
+import { TraceStorage } from '../storage/index.js';
+const nonces = new Map();
+const nowMs = () => Date.now();
+const normalizePath = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '/zin/trace/write';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+const parseMiddleware = (value) => value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+const appendSuffix = (path, suffix) => {
+    const base = normalizePath(path).replace(/\/+$/, '');
+    const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
+    return `${base}${tail}`;
+};
+const cleanupExpiredNonces = () => {
+    const current = nowMs();
+    for (const [nonceKey, expiresAt] of nonces.entries()) {
+        if (expiresAt <= current) {
+            nonces.delete(nonceKey);
+        }
+    }
+};
+const storeNonce = async (keyId, nonce, ttlMs) => {
+    cleanupExpiredNonces();
+    const nonceKey = `${keyId}:${nonce}`;
+    if (nonces.has(nonceKey))
+        return false;
+    nonces.set(nonceKey, nowMs() + Math.max(ttlMs, 1));
+    return true;
+};
+const getBodyRecord = (req) => {
+    const body = req.getBody?.() ?? req.body;
+    if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+        return body;
+    }
+    return {};
+};
+const getRawBody = (req) => {
+    const rawText = req.context['rawBodyText'];
+    if (typeof rawText === 'string')
+        return rawText;
+    return JSON.stringify(getBodyRecord(req));
+};
+const toIncomingHeaders = (req) => {
+    const headers = req.getHeaders();
+    const normalize = (value) => {
+        if (Array.isArray(value))
+            return value.join(',');
+        return value;
+    };
+    return {
+        'x-zt-key-id': normalize(headers['x-zt-key-id']),
+        'x-zt-timestamp': normalize(headers['x-zt-timestamp']),
+        'x-zt-nonce': normalize(headers['x-zt-nonce']),
+        'x-zt-body-sha256': normalize(headers['x-zt-body-sha256']),
+        'x-zt-signature': normalize(headers['x-zt-signature']),
+    };
+};
+const sendFailure = (res, status, code, message, details) => {
+    const payload = {
+        ok: false,
+        error: { code, message, details },
+    };
+    res.status(status).json(payload);
+};
+const sendSuccess = (res) => {
+    const payload = { ok: true };
+    res.status(200).json(payload);
+};
+const verifyRequest = async (req, bodyText, settings, path) => {
+    if (settings.keyId.trim() === '' || settings.secret.trim() === '') {
+        return {
+            ok: false,
+            code: 'CONFIG_ERROR',
+            status: 500,
+            message: 'Trace ingest signing credentials are not configured',
+        };
+    }
+    const verifyResult = await SignedRequest.verify({
+        method: req.getMethod(),
+        url: new URL(path, 'http://localhost'),
+        body: bodyText,
+        headers: toIncomingHeaders(req),
+        nowMs: nowMs(),
+        windowMs: settings.signingWindowMs,
+        verifyNonce: async (keyId, nonce) => storeNonce(keyId, nonce, settings.nonceTtlMs),
+        getSecretForKeyId: async (keyId) => {
+            if (keyId === settings.keyId)
+                return settings.secret;
+            return undefined;
+        },
+    });
+    if (verifyResult.ok === true)
+        return { ok: true };
+    return {
+        ok: false,
+        code: verifyResult.code,
+        status: verifyResult.code === 'EXPIRED' || verifyResult.code === 'REPLAYED' ? 401 : 403,
+        message: verifyResult.message,
+    };
+};
+const createWriteHandler = (settings, path) => {
+    return async (req, res) => {
+        const body = getBodyRecord(req);
+        const auth = await verifyRequest(req, getRawBody(req), settings, path);
+        if (auth.ok === false) {
+            sendFailure(res, auth.status, auth.code, auth.message);
+            return;
+        }
+        const entry = body['entry'];
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            sendFailure(res, 400, 'VALIDATION_ERROR', 'entry must be an object');
+            return;
+        }
+        await settings.storage.writeEntry(entry);
+        sendSuccess(res);
+    };
+};
+const createUpdateHandler = (settings, path) => {
+    return async (req, res) => {
+        const body = getBodyRecord(req);
+        const auth = await verifyRequest(req, getRawBody(req), settings, path);
+        if (auth.ok === false) {
+            sendFailure(res, auth.status, auth.code, auth.message);
+            return;
+        }
+        const uuid = body['uuid'];
+        const patch = body['patch'];
+        if (typeof uuid !== 'string' || uuid.trim() === '') {
+            sendFailure(res, 400, 'VALIDATION_ERROR', 'uuid is required');
+            return;
+        }
+        if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) {
+            sendFailure(res, 400, 'VALIDATION_ERROR', 'patch must be an object');
+            return;
+        }
+        await settings.storage.updateEntry(uuid, patch);
+        sendSuccess(res);
+    };
+};
+const createMarkFamilyStaleHandler = (settings, path) => {
+    return async (req, res) => {
+        const body = getBodyRecord(req);
+        const auth = await verifyRequest(req, getRawBody(req), settings, path);
+        if (auth.ok === false) {
+            sendFailure(res, auth.status, auth.code, auth.message);
+            return;
+        }
+        const familyHash = body['familyHash'];
+        const exceptUuid = body['exceptUuid'];
+        if (typeof familyHash !== 'string' || familyHash.trim() === '') {
+            sendFailure(res, 400, 'VALIDATION_ERROR', 'familyHash is required');
+            return;
+        }
+        if (typeof exceptUuid !== 'string' || exceptUuid.trim() === '') {
+            sendFailure(res, 400, 'VALIDATION_ERROR', 'exceptUuid is required');
+            return;
+        }
+        await settings.storage.markFamilyStale(familyHash, exceptUuid);
+        sendSuccess(res);
+    };
+};
+const resolveStorage = (overrides) => {
+    if (overrides?.storage !== undefined)
+        return overrides.storage;
+    const connectionName = overrides?.connectionName ?? TraceConfig.merge().connection;
+    const db = useDatabase(undefined, connectionName);
+    if (db === undefined) {
+        throw ErrorFactory.createConfigError('Trace ingest connection is not configured.', {
+            connectionName,
+            envKey: 'TRACE_DB_CONNECTION',
+        });
+    }
+    return TraceStorage.resolveStorage(db);
+};
+const readSettings = (overrides) => {
+    const configuredSecret = (overrides?.secret ?? Env.get('TRACE_PROXY_SECRET', '')).trim();
+    const configuredKeyId = (overrides?.keyId ?? Env.get('TRACE_PROXY_KEY_ID', '')).trim();
+    return {
+        basePath: normalizePath(overrides?.basePath ?? Env.get('TRACE_PROXY_PATH', '/zin/trace/write')),
+        keyId: configuredKeyId === '' ? (Env.APP_NAME || 'zintrust').trim() : configuredKeyId,
+        secret: configuredSecret === '' ? Env.APP_KEY : configuredSecret,
+        signingWindowMs: overrides?.signingWindowMs ?? Env.getInt('TRACE_PROXY_SIGNING_WINDOW_MS', 60000),
+        nonceTtlMs: overrides?.nonceTtlMs ?? Env.getInt('TRACE_PROXY_NONCE_TTL_MS', 120000),
+        middleware: overrides?.middleware ?? parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', '')),
+        storage: resolveStorage(overrides),
+    };
+};
+export const TraceIngestGateway = Object.freeze({
+    create(overrides) {
+        const settings = readSettings(overrides);
+        const routeOptions = settings.middleware.length > 0
+            ? { middleware: settings.middleware }
+            : undefined;
+        const updatePath = appendSuffix(settings.basePath, '/update');
+        const markFamilyStalePath = appendSuffix(settings.basePath, '/mark-family-stale');
+        return {
+            registerRoutes(router) {
+                Router.post(router, settings.basePath, createWriteHandler(settings, settings.basePath), routeOptions);
+                Router.post(router, updatePath, createUpdateHandler(settings, updatePath), routeOptions);
+                Router.post(router, markFamilyStalePath, createMarkFamilyStaleHandler(settings, markFamilyStalePath), routeOptions);
+            },
+        };
+    },
+});
+export const registerTraceIngestGateway = (router, overrides) => {
+    TraceIngestGateway.create(overrides).registerRoutes(router);
+};
+export default TraceIngestGateway;

package/dist/register.js

@@ -21,7 +21,7 @@
  */
 import { TraceConfig } from './config.js';
 import { TraceContext } from './context.js';
-import { TraceStorage } from './storage/index.js';
+import { ProxyTraceStorage, TraceServiceTag, TraceStorage } from './storage/index.js';
 import { TraceContentBudget } from './storage/TraceContentBudget.js';
 import { TraceContentRedaction } from './storage/TraceContentRedaction.js';
 import { TraceEntryFiltering } from './storage/TraceEntryFiltering.js';
@@ -142,6 +142,15 @@ if (!traceAlreadyInitialized && Env) {
         const pruneAfterHoursRaw = Env.get('TRACE_PRUNE_HOURS', '').trim();
         const slowQueryThresholdRaw = Env.get('TRACE_SLOW_QUERY_MS', '').trim();
         const logMinLevelRaw = Env.get('TRACE_LOG_LEVEL', '').trim();
+        const traceProxyRaw = Env.get('TRACE_PROXY', '').trim();
+        const traceProxyUrlRaw = Env.get('TRACE_PROXY_URL', '').trim();
+        const traceProxyPathRaw = Env.get('TRACE_PROXY_PATH', '').trim();
+        const traceProxyKeyIdRaw = Env.get('TRACE_PROXY_KEY_ID', '').trim();
+        const traceProxySecretRaw = Env.get('TRACE_PROXY_SECRET', '').trim();
+        const traceProxyTimeoutRaw = Env.get('TRACE_PROXY_TIMEOUT_MS', '').trim();
+        const traceServiceTagRaw = Env.get('TRACE_SERVICE_TAG', '').trim();
+        const appNameRaw = Env.get('APP_NAME', '').trim();
+        const appKeyRaw = Env.get('APP_KEY', '').trim();
         const captureCachePayloadsRaw = Env.get('TRACE_CACHE_PAYLOADS', '').trim();
         const captureQueryBindingsRaw = Env.get('TRACE_QUERY_BINDINGS', '').trim();
         const contentDispatchDriverRaw = Env.get('TRACE_CONTENT_QUEUE_DRIVER', '').trim();
@@ -166,6 +175,21 @@ if (!traceAlreadyInitialized && Env) {
         const logMinLevel = (logMinLevelRaw === '' ? startupOverrides?.logMinLevel : logMinLevelRaw);
         const captureCachePayloads = parseEnvBool(captureCachePayloadsRaw) ?? startupOverrides?.captureCachePayloads;
         const captureQueryBindings = parseEnvBool(captureQueryBindingsRaw) ?? startupOverrides?.captureQueryBindings;
+        const traceProxyEnabled = parseEnvBool(traceProxyRaw) ?? startupOverrides?.proxy?.enabled;
+        const traceProxyUrl = traceProxyUrlRaw === '' ? startupOverrides?.proxy?.url : traceProxyUrlRaw;
+        const traceProxyPath = traceProxyPathRaw === '' ? startupOverrides?.proxy?.path : traceProxyPathRaw;
+        const traceProxyKeyId = traceProxyKeyIdRaw === ''
+            ? (startupOverrides?.proxy?.keyId ?? appNameRaw)
+            : traceProxyKeyIdRaw;
+        const traceProxySecret = traceProxySecretRaw === ''
+            ? (startupOverrides?.proxy?.secret ?? appKeyRaw)
+            : traceProxySecretRaw;
+        const traceProxyTimeout = traceProxyTimeoutRaw === ''
+            ? startupOverrides?.proxy?.timeoutMs
+            : Number.parseInt(traceProxyTimeoutRaw, 10);
+        const traceServiceTag = traceServiceTagRaw === ''
+            ? (startupOverrides?.serviceTag ?? appNameRaw).trim() || undefined
+            : traceServiceTagRaw;
         const contentDispatchDriver = contentDispatchDriverRaw === ''
             ? startupOverrides?.contentDispatch?.driver
             : contentDispatchDriverRaw;
@@ -201,6 +225,29 @@ if (!traceAlreadyInitialized && Env) {
             enabled,
             connection,
             observeConnection,
+            ...(typeof traceServiceTag === 'string' && traceServiceTag !== ''
+                ? { serviceTag: traceServiceTag }
+                : {}),
+            proxy: {
+                ...TraceConfig.defaults().proxy,
+                ...startupOverrides?.proxy,
+                ...(typeof traceProxyEnabled === 'boolean' ? { enabled: traceProxyEnabled } : {}),
+                ...(typeof traceProxyUrl === 'string' && traceProxyUrl !== ''
+                    ? { url: traceProxyUrl }
+                    : {}),
+                ...(typeof traceProxyPath === 'string' && traceProxyPath !== ''
+                    ? { path: traceProxyPath }
+                    : {}),
+                ...(typeof traceProxyKeyId === 'string' && traceProxyKeyId !== ''
+                    ? { keyId: traceProxyKeyId }
+                    : {}),
+                ...(typeof traceProxySecret === 'string' && traceProxySecret !== ''
+                    ? { secret: traceProxySecret }
+                    : {}),
+                ...(typeof traceProxyTimeout === 'number' && Number.isFinite(traceProxyTimeout)
+                    ? { timeoutMs: traceProxyTimeout }
+                    : {}),
+            },
             ...(typeof pruneAfterHours === 'number' && Number.isFinite(pruneAfterHours)
                 ? { pruneAfterHours }
                 : {}),
@@ -264,7 +311,16 @@ if (!traceAlreadyInitialized && Env) {
             envKey: 'TRACE_QUERY_CONNECTION',
         });
         await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
-        const storage = TraceWriteDiagnostics.wrapStorage(TraceContentBudget.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config), config.redaction), config), {
+        const resolvedStorage = config.proxy.enabled
+            ? ProxyTraceStorage.create({
+                baseUrl: config.proxy.url ?? '',
+                path: config.proxy.path,
+                keyId: config.proxy.keyId ?? '',
+                secret: config.proxy.secret ?? '',
+                timeoutMs: config.proxy.timeoutMs,
+            })
+            : TraceStorage.resolveStorage(storageDb);
+        const storage = TraceWriteDiagnostics.wrapStorage(TraceContentBudget.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceServiceTag.wrapStorage(resolvedStorage, config), config), config.redaction), config), {
             connectionName: resolvedConnectionName,
             logger: core.Logger,
         });

package/dist/storage/DebuggerStorage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * TraceStorage — sealed namespace wrapping the D1/SQLite driver.
+ * Resolves the correct IDatabase from the app config, then delegates all
+ * read/write operations to the trace storage facade.
+ */
+import type { IDatabase } from '@zintrust/core';
+import type { ITraceStorage } from '../types';
+export declare const TraceStorage: Readonly<{
+    resolveStorage: (db: IDatabase) => ITraceStorage;
+    reset: () => void;
+    familyHash: (input: string) => string;
+}>;
+export { type ITraceStorage } from '../types';