@zintrust/trace 0.9.2 → 0.9.4

package/src/ingest/TraceIngestGateway.ts

@@ -0,0 +1,317 @@
+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 appendSuffix = (path: string, suffix: string): string => {
+  const base = normalizePath(path).replace(/\/+$/, '');
+  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 readSettings = (overrides?: TraceIngestGatewayOverrides): TraceIngestGatewaySettings => {
+  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?: TraceIngestGatewayOverrides): {
+    registerRoutes: (router: IRouter) => void;
+  } {
+    const settings = readSettings(overrides);
+    const routeOptions: RouteOptions | undefined =
+      settings.middleware.length > 0
+        ? ({ middleware: settings.middleware } as RouteOptions)
+        : undefined;
+    const updatePath = appendSuffix(settings.basePath, '/update');
+    const markFamilyStalePath = appendSuffix(settings.basePath, '/mark-family-stale');
+
+    return {
+      registerRoutes(router: IRouter): void {
+        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: IRouter,
+  overrides?: TraceIngestGatewayOverrides
+): void => {
+  TraceIngestGateway.create(overrides).registerRoutes(router);
+};
+
+export default TraceIngestGateway;

package/src/register.ts

@@ -21,11 +21,17 @@
  */
 import { TraceConfig } from './config';
 import { TraceContext } from './context';
-import { TraceStorage } from './storage';
+import { ProxyTraceStorage, TraceServiceTag, TraceStorage } from './storage';
 import { TraceContentBudget } from './storage/TraceContentBudget';
 import { TraceContentRedaction } from './storage/TraceContentRedaction';
 import { TraceEntryFiltering } from './storage/TraceEntryFiltering';
 import { TraceWriteDiagnostics } from './storage/TraceWriteDiagnostics';
+import {
+  assertTraceConnectionResolved,
+  assertTraceStorageReady,
+  resolveObservedConnectionName,
+  resolveTraceConnectionName,
+} from './TraceConnection';
 import type { ITraceWatcherConfig, TraceConfigOverrides } from './types';
 
 export type {}; // side-effect ESM module
@@ -38,7 +44,6 @@ type GlobalTraceRegisterState = {
 };
 
 const globalTraceRegisterState = globalThis as unknown as GlobalTraceRegisterState;
-globalTraceRegisterState.__zintrust_system_trace_plugin_requested__ = true;
 const traceAlreadyInitialized =
   globalTraceRegisterState.__zintrust_system_trace_register_initialized__ === true;
 
@@ -80,14 +85,6 @@ type CoreApi = {
   };
 };
 
-type CoreDatabase = import('@zintrust/core').IDatabase;
-
-const TRACE_REQUIRED_TABLES = [
-  'zin_trace_entries',
-  'zin_trace_entries_tags',
-  'zin_trace_monitoring',
-] as const;
-
 type GlobalMiddlewareRegistrarState = {
   __zintrust_register_global_middleware__?: ITraceWatcherConfig['registerMiddleware'];
   __zintrust_pending_global_middlewares__?: Array<
@@ -111,44 +108,6 @@ const resolveRegisterMiddleware = (): NonNullable<ITraceWatcherConfig['registerM
   };
 };
 
-const resolveTraceConnectionName = (
-  env: Pick<NonNullable<CoreApi['Env']>, 'get'> | undefined,
-  configuredConnection?: string
-): string => {
-  const resolveDefaultConnection = (): string => {
-    const defaultConnection = env?.get('DB_CONNECTION', '').trim() ?? '';
-    if (defaultConnection === '' || defaultConnection === 'default') return 'default';
-    return defaultConnection;
-  };
-
-  const explicitConnection = configuredConnection?.trim();
-  if (explicitConnection !== undefined && explicitConnection !== '') {
-    return explicitConnection === 'default' ? resolveDefaultConnection() : explicitConnection;
-  }
-
-  return resolveDefaultConnection();
-};
-
-const resolveObservedConnectionName = (
-  env: Pick<NonNullable<CoreApi['Env']>, 'get'> | undefined,
-  configuredObservedConnection: string | undefined,
-  storageConnectionName: string
-): string => {
-  if (
-    typeof configuredObservedConnection === 'string' &&
-    configuredObservedConnection.trim() !== ''
-  ) {
-    return resolveTraceConnectionName(env, configuredObservedConnection);
-  }
-
-  const defaultConnectionName = resolveTraceConnectionName(env);
-  if (storageConnectionName !== defaultConnectionName) {
-    return defaultConnectionName;
-  }
-
-  return storageConnectionName;
-};
-
 const isObjectValue = (value: unknown): value is Record<string, unknown> => {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 };
@@ -240,71 +199,6 @@ const buildTraceRedactionOverrides = (input: {
     : undefined;
 };
 
-const createTraceConfigError = (coreApi: CoreApi, message: string, details?: unknown): Error => {
-  if (coreApi.ErrorFactory?.createConfigError !== undefined) {
-    return coreApi.ErrorFactory.createConfigError(message, details);
-  }
-
-  const error = new globalThis.Error(message) as Error & {
-    code?: string;
-    details?: unknown;
-    name?: string;
-    statusCode?: number;
-  };
-  error.name = 'ConfigError';
-  error.code = 'CONFIG_ERROR';
-  error.statusCode = 500;
-  error.details = details;
-  return error;
-};
-
-function assertTraceConnectionResolved(
-  coreApi: CoreApi,
-  db: CoreDatabase | undefined,
-  params: { connectionName: string; envKey: 'TRACE_DB_CONNECTION' | 'TRACE_QUERY_CONNECTION' }
-): asserts db is CoreDatabase {
-  if (db !== undefined) {
-    return;
-  }
-
-  throw createTraceConfigError(
-    coreApi,
-    `Trace connection "${params.connectionName}" could not be resolved.`,
-    {
-      connectionName: params.connectionName,
-      envKey: params.envKey,
-      hint:
-        params.envKey === 'TRACE_DB_CONNECTION'
-          ? 'Configure TRACE_DB_CONNECTION to an existing database connection before enabling TRACE_ENABLED.'
-          : 'Configure TRACE_QUERY_CONNECTION, or ensure DB_CONNECTION resolves to an existing database connection.',
-    }
-  );
-}
-
-const assertTraceStorageReady = async (
-  coreApi: CoreApi,
-  db: CoreDatabase,
-  connectionName: string
-): Promise<void> => {
-  try {
-    await Promise.all(
-      TRACE_REQUIRED_TABLES.map(async (table) => {
-        await db.queryOne(`SELECT 1 AS ok FROM ${table} LIMIT 1`, []);
-      })
-    );
-  } catch (error) {
-    throw createTraceConfigError(
-      coreApi,
-      `Trace storage connection "${connectionName}" is not ready. Create the database if needed and run \`zin migrate:trace\` before enabling TRACE_ENABLED.`,
-      {
-        connectionName,
-        error,
-        requiredTables: [...TRACE_REQUIRED_TABLES],
-      }
-    );
-  }
-};
-
 const core = (await importCore()) as CoreApi;
 const Env = core.Env;
 const startupOverrides = await resolveTraceStartupOverrides(core);
@@ -318,6 +212,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();
@@ -368,6 +271,26 @@ if (!traceAlreadyInitialized && Env) {
       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
@@ -411,6 +334,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 }
         : {}),
@@ -485,10 +431,23 @@ if (!traceAlreadyInitialized && Env) {
     });
     await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
 
+    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(TraceStorage.resolveStorage(storageDb), config),
+          TraceEntryFiltering.wrapStorage(
+            TraceServiceTag.wrapStorage(resolvedStorage, config),
+            config
+          ),
           config.redaction
         ),
         config