@zintrust/trace 0.9.3 → 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,7 +21,7 @@
  */
 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';
@@ -212,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();
@@ -262,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
@@ -305,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 }
         : {}),
@@ -379,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

package/src/storage/ProxyTraceStorage.ts

@@ -0,0 +1,182 @@
+import { ErrorFactory, RemoteSignedJson } from '@zintrust/core';
+import type { ITraceEntry, ITraceStorage } from '../types';
+
+type ProxyTraceStorageSettings = {
+  baseUrl: string;
+  path: string;
+  keyId: string;
+  secret: string;
+  timeoutMs: number;
+};
+
+type TraceProxyWriteRequest = {
+  entry: ITraceEntry;
+};
+
+type TraceProxyUpdateRequest = {
+  uuid: string;
+  patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>;
+};
+
+type TraceProxyMarkFamilyStaleRequest = {
+  familyHash: string;
+  exceptUuid: string;
+};
+
+const ensureConfigured = (settings: ProxyTraceStorageSettings): void => {
+  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: string): string => {
+  const trimmed = value.trim();
+  if (trimmed === '') return '/zin/trace/write';
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+
+const createUnsupportedReadError = (): Error =>
+  ErrorFactory.createConfigError(
+    'Trace proxy sender storage does not expose dashboard/query operations. Use the trace server for reads.'
+  );
+
+type ProxyRequestSettings = {
+  baseUrl: string;
+  keyId: string;
+  secret: string;
+  timeoutMs: number;
+  signaturePathPrefixToStrip: string;
+  missingUrlMessage: string;
+  missingCredentialsMessage: string;
+  messages: {
+    unauthorized: string;
+    forbidden: string;
+    rateLimited: string;
+    rejected: string;
+    error: string;
+    timedOut: string;
+  };
+  normalizedPath: string;
+};
+
+const buildSettings = (settings: ProxyTraceStorageSettings): ProxyRequestSettings => {
+  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: string, suffix: string): string => {
+  const base = normalizePath(path).replace(/\/+$/, '');
+  const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
+  return `${base}${tail}`;
+};
+
+const unsupportedQueryEntries: ITraceStorage['queryEntries'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedGetEntry: ITraceStorage['getEntry'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedGetBatch: ITraceStorage['getBatch'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedQueryBatchEntries: ITraceStorage['queryBatchEntries'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedPrune: ITraceStorage['prune'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedClear: ITraceStorage['clear'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedGetMonitoring: ITraceStorage['getMonitoring'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedAddMonitoring: ITraceStorage['addMonitoring'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedRemoveMonitoring: ITraceStorage['removeMonitoring'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedStats: ITraceStorage['stats'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+export const ProxyTraceStorage = Object.freeze({
+  create(settings: ProxyTraceStorageSettings): ITraceStorage {
+    const normalized = buildSettings(settings);
+
+    return Object.freeze({
+      async writeEntry(entry: ITraceEntry): Promise<void> {
+        await RemoteSignedJson.request<{ ok: true }>(normalized, normalized.normalizedPath, {
+          entry,
+        } satisfies TraceProxyWriteRequest);
+      },
+
+      async updateEntry(
+        uuid: string,
+        patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+      ): Promise<void> {
+        await RemoteSignedJson.request<{ ok: true }>(
+          normalized,
+          appendSuffix(normalized.normalizedPath, '/update'),
+          { uuid, patch } satisfies TraceProxyUpdateRequest
+        );
+      },
+
+      async markFamilyStale(familyHash: string, exceptUuid: string): Promise<void> {
+        await RemoteSignedJson.request<{ ok: true }>(
+          normalized,
+          appendSuffix(normalized.normalizedPath, '/mark-family-stale'),
+          { familyHash, exceptUuid } satisfies TraceProxyMarkFamilyStaleRequest
+        );
+      },
+
+      queryEntries: unsupportedQueryEntries,
+      getEntry: unsupportedGetEntry,
+      getBatch: unsupportedGetBatch,
+      queryBatchEntries: unsupportedQueryBatchEntries,
+      prune: unsupportedPrune,
+      clear: unsupportedClear,
+      getMonitoring: unsupportedGetMonitoring,
+      addMonitoring: unsupportedAddMonitoring,
+      removeMonitoring: unsupportedRemoveMonitoring,
+      stats: unsupportedStats,
+    });
+  },
+});
+
+export default ProxyTraceStorage;

package/src/storage/TraceContentBudget.ts

@@ -285,6 +285,7 @@ const getCoreRuntime = async (): Promise<{
 
 const getQueueWorkerApi = async (): Promise<QueueWorkerApi | null> => {
   try {
+    // @ts-ignore
     const mod = (await import('@zintrust/workers')) as unknown as QueueWorkerApi;
     return typeof mod.createQueueWorker === 'function' ? mod : null;
   } catch {

package/src/storage/TraceServiceTag.ts

@@ -0,0 +1,56 @@
+import { ErrorFactory } from '@zintrust/core';
+import type { ITraceConfig, ITraceEntry, ITraceStorage } from '../types';
+
+const appendServiceTag = (entry: ITraceEntry, serviceTag?: string): ITraceEntry => {
+  const normalizedTag = serviceTag?.trim() ?? '';
+  if (normalizedTag === '' || entry.tags.includes(normalizedTag)) {
+    return entry;
+  }
+
+  return {
+    ...entry,
+    tags: [...entry.tags, normalizedTag],
+  };
+};
+
+const unsupportedRead = async <T>(): Promise<T> => {
+  throw ErrorFactory.createConfigError(
+    'Trace proxy mode only supports runtime persistence on the sender. Query the trace server database or dashboard directly.'
+  );
+};
+
+const bindOrUnsupported = <T extends (...args: never[]) => Promise<unknown>>(
+  method: T | undefined
+): T => {
+  if (method === undefined) {
+    return unsupportedRead as unknown as T;
+  }
+
+  return method;
+};
+
+export const TraceServiceTag = Object.freeze({
+  wrapStorage(storage: ITraceStorage, config: ITraceConfig): ITraceStorage {
+    const writeEntry = async (entry: ITraceEntry): Promise<void> => {
+      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/src/storage/index.ts

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

package/src/types.ts

@@ -373,6 +373,15 @@ export type TraceContentDispatchConfig = {
   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;
@@ -404,6 +413,8 @@ export interface ITraceConfig {
   enabled: boolean;
   connection?: string;
   observeConnection?: string;
+  serviceTag?: string;
+  proxy: TraceProxyConfig;
   pruneAfterHours: number;
   ignoreRoutes: string[];
   ignorePaths: string[];