@zintrust/trace 0.9.3 → 1.2.0

package/dist/storage/ProxyTraceStorage.js

@@ -0,0 +1,109 @@
+import { ErrorFactory, RemoteSignedJson } from '@zintrust/core';
+const ensureConfigured = (settings) => {
+    if (settings.baseUrl.trim() === '') {
+        throw ErrorFactory.createConfigError('TRACE_PROXY_URL is required when TRACE_PROXY=true');
+    }
+    if (settings.keyId.trim() === '' || settings.secret.trim() === '') {
+        throw ErrorFactory.createConfigError('TRACE_PROXY signing credentials are required when TRACE_PROXY=true');
+    }
+};
+const normalizePath = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '/zin/trace/write';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+const trimTrailingSlashes = (value) => {
+    let trimmed = value;
+    while (trimmed.endsWith('/')) {
+        trimmed = trimmed.slice(0, -1);
+    }
+    return trimmed;
+};
+const createUnsupportedReadError = () => ErrorFactory.createConfigError('Trace proxy sender storage does not expose dashboard/query operations. Use the trace server for reads.');
+const buildSettings = (settings) => {
+    ensureConfigured(settings);
+    const normalizedPath = normalizePath(settings.path);
+    return {
+        baseUrl: settings.baseUrl,
+        keyId: settings.keyId,
+        secret: settings.secret,
+        timeoutMs: settings.timeoutMs,
+        signaturePathPrefixToStrip: new URL(settings.baseUrl).pathname,
+        missingUrlMessage: 'TRACE_PROXY_URL is required when TRACE_PROXY=true',
+        missingCredentialsMessage: 'TRACE_PROXY signing credentials are required when TRACE_PROXY=true',
+        messages: {
+            unauthorized: 'Trace proxy rejected the request credentials',
+            forbidden: 'Trace proxy rejected the request signature',
+            rateLimited: 'Trace proxy rate-limited the request',
+            rejected: 'Trace proxy rejected the request payload',
+            error: 'Trace proxy request failed',
+            timedOut: 'Trace proxy request timed out',
+        },
+        normalizedPath,
+    };
+};
+const appendSuffix = (path, suffix) => {
+    const base = trimTrailingSlashes(normalizePath(path));
+    const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
+    return `${base}${tail}`;
+};
+const unsupportedQueryEntries = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedGetEntry = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedGetBatch = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedQueryBatchEntries = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedPrune = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedClear = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedGetMonitoring = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedAddMonitoring = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedRemoveMonitoring = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedStats = async () => {
+    throw createUnsupportedReadError();
+};
+export const ProxyTraceStorage = Object.freeze({
+    create(settings) {
+        const normalized = buildSettings(settings);
+        return Object.freeze({
+            async writeEntry(entry) {
+                await RemoteSignedJson.request(normalized, normalized.normalizedPath, {
+                    entry,
+                });
+            },
+            async updateEntry(uuid, patch) {
+                await RemoteSignedJson.request(normalized, appendSuffix(normalized.normalizedPath, '/update'), { uuid, patch });
+            },
+            async markFamilyStale(familyHash, exceptUuid) {
+                await RemoteSignedJson.request(normalized, appendSuffix(normalized.normalizedPath, '/mark-family-stale'), { familyHash, exceptUuid });
+            },
+            queryEntries: unsupportedQueryEntries,
+            getEntry: unsupportedGetEntry,
+            getBatch: unsupportedGetBatch,
+            queryBatchEntries: unsupportedQueryBatchEntries,
+            prune: unsupportedPrune,
+            clear: unsupportedClear,
+            getMonitoring: unsupportedGetMonitoring,
+            addMonitoring: unsupportedAddMonitoring,
+            removeMonitoring: unsupportedRemoveMonitoring,
+            stats: unsupportedStats,
+        });
+    },
+});
+export default ProxyTraceStorage;

package/dist/storage/TraceContentBudget.js

@@ -179,6 +179,7 @@ const getCoreRuntime = async () => {
 };
 const getQueueWorkerApi = async () => {
     try {
+        // @ts-ignore
         const mod = (await import('@zintrust/workers'));
         return typeof mod.createQueueWorker === 'function' ? mod : null;
     }

package/dist/storage/TraceServiceTag.d.ts

@@ -0,0 +1,5 @@
+import type { ITraceConfig, ITraceStorage } from '../types';
+export declare const TraceServiceTag: Readonly<{
+    wrapStorage(storage: ITraceStorage, config: ITraceConfig): ITraceStorage;
+}>;
+export default TraceServiceTag;

package/dist/storage/TraceServiceTag.js

@@ -0,0 +1,43 @@
+import { ErrorFactory } from '@zintrust/core';
+const appendServiceTag = (entry, serviceTag) => {
+    const normalizedTag = serviceTag?.trim() ?? '';
+    if (normalizedTag === '' || entry.tags.includes(normalizedTag)) {
+        return entry;
+    }
+    return {
+        ...entry,
+        tags: [...entry.tags, normalizedTag],
+    };
+};
+const unsupportedRead = async () => {
+    throw ErrorFactory.createConfigError('Trace proxy mode only supports runtime persistence on the sender. Query the trace server database or dashboard directly.');
+};
+const bindOrUnsupported = (method) => {
+    if (method === undefined) {
+        return unsupportedRead;
+    }
+    return method;
+};
+export const TraceServiceTag = Object.freeze({
+    wrapStorage(storage, config) {
+        const writeEntry = async (entry) => {
+            await storage.writeEntry(appendServiceTag(entry, config.serviceTag));
+        };
+        return Object.freeze({
+            writeEntry,
+            updateEntry: storage.updateEntry.bind(storage),
+            markFamilyStale: storage.markFamilyStale.bind(storage),
+            queryEntries: bindOrUnsupported(storage.queryEntries?.bind(storage)),
+            getEntry: bindOrUnsupported(storage.getEntry?.bind(storage)),
+            getBatch: bindOrUnsupported(storage.getBatch?.bind(storage)),
+            queryBatchEntries: bindOrUnsupported(storage.queryBatchEntries?.bind(storage)),
+            prune: bindOrUnsupported(storage.prune?.bind(storage)),
+            clear: bindOrUnsupported(storage.clear?.bind(storage)),
+            getMonitoring: bindOrUnsupported(storage.getMonitoring?.bind(storage)),
+            addMonitoring: bindOrUnsupported(storage.addMonitoring?.bind(storage)),
+            removeMonitoring: bindOrUnsupported(storage.removeMonitoring?.bind(storage)),
+            stats: bindOrUnsupported(storage.stats?.bind(storage)),
+        });
+    },
+});
+export default TraceServiceTag;

package/dist/storage/index.d.ts

@@ -1,2 +1,4 @@
 export { TraceStorage } from './TraceStorage';
 export type { ITraceStorage } from './TraceStorage';
+export { ProxyTraceStorage } from './ProxyTraceStorage';
+export { TraceServiceTag } from './TraceServiceTag';

package/dist/storage/index.js

@@ -1 +1,3 @@
 export { TraceStorage } from './TraceStorage.js';
+export { ProxyTraceStorage } from './ProxyTraceStorage.js';
+export { TraceServiceTag } from './TraceServiceTag.js';

package/dist/types.d.ts

@@ -316,6 +316,14 @@ export type TraceContentDispatchConfig = {
     enqueueTimeoutMs: number;
     worker: TraceContentDispatchWorkerConfig;
 };
+export type TraceProxyConfig = {
+    enabled: boolean;
+    url?: string;
+    path: string;
+    keyId?: string;
+    secret?: string;
+    timeoutMs: number;
+};
 export type TraceWatcherToggle = boolean | TraceFilterRule;
 export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
 export type TraceClientRequestWatcherToggle = boolean | TraceClientRequestWatcherConfig;
@@ -345,6 +353,8 @@ export interface ITraceConfig {
     enabled: boolean;
     connection?: string;
     observeConnection?: string;
+    serviceTag?: string;
+    proxy: TraceProxyConfig;
     pruneAfterHours: number;
     ignoreRoutes: string[];
     ignorePaths: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.9.3",
+  "version": "1.2.0",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.9.2"
+    "@zintrust/core": "^0.9.6"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -8,6 +8,7 @@ import type {
   TraceConfigOverrides,
   TraceContentDispatchConfig,
   TraceFilterRule,
+  TraceProxyConfig,
   TraceRequestWatcherConfig,
   TraceWatcherToggle,
 } from './types';
@@ -253,10 +254,31 @@ const mergeContentDispatch = (
   };
 };
 
+const mergeProxyConfig = (
+  base: TraceProxyConfig,
+  override?: TraceConfigOverrides['proxy']
+): TraceProxyConfig => {
+  if (override === undefined) return base;
+
+  return {
+    ...base,
+    ...override,
+  };
+};
+
 const DEFAULTS: ITraceConfig = 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: [],
@@ -342,6 +364,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/src/index.ts

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

package/src/ingest/TraceIngestGateway.ts

@@ -0,0 +1,360 @@
+import {
+  Env,
+  ErrorFactory,
+  Router,
+  SignedRequest,
+  useDatabase,
+  type IRequest,
+  type IResponse,
+  type IRouter,
+  type RouteOptions,
+} from '@zintrust/core';
+import { TraceConfig } from '../config';
+import { TraceStorage } from '../storage';
+import type { ITraceEntry, 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 }
+>;
+
+type TraceGatewayFailure = {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+};
+
+type TraceGatewaySuccess = {
+  ok: true;
+};
+
+const nonces = new Map<string, number>();
+
+const nowMs = (): number => Date.now();
+
+const normalizePath = (value: string): string => {
+  const trimmed = value.trim();
+  if (trimmed === '') return '/zin/trace/write';
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+
+const parseMiddleware = (value: string): ReadonlyArray<string> =>
+  value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+
+const trimTrailingSlashes = (value: string): string => {
+  let trimmed = value;
+  while (trimmed.endsWith('/')) {
+    trimmed = trimmed.slice(0, -1);
+  }
+  return trimmed;
+};
+
+const appendSuffix = (path: string, suffix: string): string => {
+  const base = trimTrailingSlashes(normalizePath(path));
+  const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
+  return `${base}${tail}`;
+};
+
+const cleanupExpiredNonces = (): void => {
+  const current = nowMs();
+  for (const [nonceKey, expiresAt] of nonces.entries()) {
+    if (expiresAt <= current) {
+      nonces.delete(nonceKey);
+    }
+  }
+};
+
+const storeNonce = async (keyId: string, nonce: string, ttlMs: number): Promise<boolean> => {
+  cleanupExpiredNonces();
+  const nonceKey = `${keyId}:${nonce}`;
+  if (nonces.has(nonceKey)) return false;
+  nonces.set(nonceKey, nowMs() + Math.max(ttlMs, 1));
+  return true;
+};
+
+const getBodyRecord = (req: IRequest): Record<string, unknown> => {
+  const body = req.getBody?.() ?? req.body;
+  if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+    return body as Record<string, unknown>;
+  }
+  return {};
+};
+
+const getRawBody = (req: IRequest): string => {
+  const rawText = req.context['rawBodyText'];
+  if (typeof rawText === 'string') return rawText;
+  return JSON.stringify(getBodyRecord(req));
+};
+
+const toIncomingHeaders = (req: IRequest): Record<string, string | undefined> => {
+  const headers = req.getHeaders();
+  const normalize = (value: string | string[] | undefined): string | undefined => {
+    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: IResponse,
+  status: number,
+  code: string,
+  message: string,
+  details?: unknown
+): void => {
+  const payload: TraceGatewayFailure = {
+    ok: false,
+    error: { code, message, details },
+  };
+  res.status(status).json(payload);
+};
+
+const sendSuccess = (res: IResponse): void => {
+  const payload: TraceGatewaySuccess = { ok: true };
+  res.status(200).json(payload);
+};
+
+const verifyRequest = async (
+  req: IRequest,
+  bodyText: string,
+  settings: TraceIngestGatewaySettings,
+  path: string
+): Promise<{ ok: true } | { ok: false; code: string; status: number; message: string }> => {
+  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: string, nonce: string) =>
+      storeNonce(keyId, nonce, settings.nonceTtlMs),
+    getSecretForKeyId: async (keyId: string) => {
+      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: TraceIngestGatewaySettings, path: string) => {
+  return async (req: IRequest, res: IResponse): Promise<void> => {
+    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 as ITraceEntry);
+    sendSuccess(res);
+  };
+};
+
+const createUpdateHandler = (settings: TraceIngestGatewaySettings, path: string) => {
+  return async (req: IRequest, res: IResponse): Promise<void> => {
+    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 as Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+    );
+    sendSuccess(res);
+  };
+};
+
+const createMarkFamilyStaleHandler = (settings: TraceIngestGatewaySettings, path: string) => {
+  return async (req: IRequest, res: IResponse): Promise<void> => {
+    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?: TraceIngestGatewayOverrides): ITraceStorage => {
+  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 readConfiguredKeyId = (overrides?: TraceIngestGatewayOverrides): string => {
+  return (overrides?.keyId ?? Env.get('TRACE_PROXY_KEY_ID', '')).trim();
+};
+
+const readConfiguredSecret = (overrides?: TraceIngestGatewayOverrides): string => {
+  return (overrides?.secret ?? Env.get('TRACE_PROXY_SECRET', '')).trim();
+};
+
+const resolveKeyId = (overrides?: TraceIngestGatewayOverrides): string => {
+  const configuredKeyId = readConfiguredKeyId(overrides);
+  if (configuredKeyId !== '') return configuredKeyId;
+  return (Env.APP_NAME || 'zintrust').trim();
+};
+
+const resolveSecret = (overrides?: TraceIngestGatewayOverrides): string => {
+  const configuredSecret = readConfiguredSecret(overrides);
+  if (configuredSecret !== '') return configuredSecret;
+  return Env.APP_KEY;
+};
+
+const resolveSigningWindowMs = (overrides?: TraceIngestGatewayOverrides): number => {
+  return overrides?.signingWindowMs ?? Env.getInt('TRACE_PROXY_SIGNING_WINDOW_MS', 60000);
+};
+
+const resolveNonceTtlMs = (overrides?: TraceIngestGatewayOverrides): number => {
+  return overrides?.nonceTtlMs ?? Env.getInt('TRACE_PROXY_NONCE_TTL_MS', 120000);
+};
+
+const resolveMiddleware = (overrides?: TraceIngestGatewayOverrides): ReadonlyArray<string> => {
+  return overrides?.middleware ?? parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', ''));
+};
+
+const readSettings = (overrides?: TraceIngestGatewayOverrides): TraceIngestGatewaySettings => {
+  return {
+    basePath: normalizePath(overrides?.basePath ?? Env.get('TRACE_PROXY_PATH', '/zin/trace/write')),
+    keyId: resolveKeyId(overrides),
+    secret: resolveSecret(overrides),
+    signingWindowMs: resolveSigningWindowMs(overrides),
+    nonceTtlMs: resolveNonceTtlMs(overrides),
+    middleware: resolveMiddleware(overrides),
+    storage: resolveStorage(overrides),
+  };
+};
+
+const getRouteOptions = (settings: TraceIngestGatewaySettings): RouteOptions | undefined => {
+  if (settings.middleware.length === 0) return undefined;
+  return { middleware: settings.middleware } as RouteOptions;
+};
+
+const registerRoutes = (router: IRouter, settings: TraceIngestGatewaySettings): void => {
+  const routeOptions = getRouteOptions(settings);
+  const updatePath = appendSuffix(settings.basePath, '/update');
+  const markFamilyStalePath = appendSuffix(settings.basePath, '/mark-family-stale');
+
+  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 TraceIngestGateway = Object.freeze({
+  create(overrides?: TraceIngestGatewayOverrides): {
+    registerRoutes: (router: IRouter) => void;
+  } {
+    const settings = readSettings(overrides);
+
+    return {
+      registerRoutes(router: IRouter): void {
+        registerRoutes(router, settings);
+      },
+    };
+  },
+});
+
+export const registerTraceIngestGateway = (
+  router: IRouter,
+  overrides?: TraceIngestGatewayOverrides
+): void => {
+  TraceIngestGateway.create(overrides).registerRoutes(router);
+};
+
+export default TraceIngestGateway;