@pellux/goodvibes-tui 0.24.0 → 0.25.0

package/src/daemon/operator/index.ts

@@ -0,0 +1,43 @@
+// Foundation barrel for the daemon operator-method scaffolding.
+// Surfaces import only from here, from src/config/*, and from the SDK.
+
+export type {
+  OperatorAccess,
+  OperatorTransport,
+  OperatorEffect,
+  OperatorMethodDescriptor,
+  CatalogMethodDescriptor,
+  OperatorInvocation,
+  OperatorHandler,
+  OperatorLogger,
+  OperatorContext,
+  Unregister,
+  SurfaceRegister,
+  InboundChannelItem,
+  ChannelRoute,
+  DraftRecord,
+  CalendarEventSummary,
+} from './types.ts';
+export { OperatorError, REQUIRE_CONFIRM, sha256First, redactWebhook } from './types.ts';
+
+export {
+  declareOperatorMethod,
+  declareOperatorMethods,
+  assertConfirmed,
+} from './register-helper.ts';
+
+export { OperatorSqliteStore } from './sqlite-store.ts';
+export type { OperatorSqliteOptions } from './sqlite-store.ts';
+
+export {
+  createDaemonCredentialStore,
+  createAtRestCipher,
+} from './credential-store.ts';
+export type { DaemonCredentialStore, AtRestCipher } from './credential-store.ts';
+
+// NOTE: `registerDaemonOperatorSurfaces` / `DaemonOperatorSurfaces` are NOT
+// re-exported here. `surfaces.ts` is the composition root that imports every
+// surface register module; re-exporting it from this foundation barrel would
+// make any leaf module that imports the barrel transitively pull in the whole
+// surface graph, forming an import cycle. The composition root (services.ts)
+// imports them directly from './surfaces.ts'.

package/src/daemon/operator/register-helper.ts

@@ -0,0 +1,150 @@
+import type {
+  GatewayMethodAccess,
+  GatewayMethodDescriptor,
+  GatewayMethodInvocation,
+  GatewayMethodSource,
+  GatewayMethodTransport,
+} from '@pellux/goodvibes-sdk/platform/control-plane';
+import type {
+  CatalogMethodDescriptor,
+  OperatorAccess,
+  OperatorContext,
+  OperatorHandler,
+  OperatorInvocation,
+  OperatorMethodDescriptor,
+  OperatorTransport,
+  Unregister,
+} from './types.ts';
+import { OperatorError, REQUIRE_CONFIRM } from './types.ts';
+
+const CATALOG_TRANSPORTS = new Set<GatewayMethodTransport>(['http', 'ws', 'internal']);
+
+function mapAccess(access: OperatorAccess): GatewayMethodAccess {
+  // The SDK has no 'operator' access tier; map it to 'admin'.
+  return access === 'operator' ? 'admin' : access;
+}
+
+function mapSource(source: string | undefined, pluginId: string | undefined): GatewayMethodSource {
+  // The SDK accepts only 'builtin' | 'plugin'. Daemon-owned methods register as
+  // 'builtin' unless they carry a pluginId.
+  if (source === 'plugin' || pluginId !== undefined) return 'plugin';
+  return 'builtin';
+}
+
+function mapTransport(transport: OperatorTransport[] | undefined): GatewayMethodTransport[] {
+  const candidates = transport ?? ['ws', 'internal'];
+  return candidates.filter((t): t is GatewayMethodTransport => CATALOG_TRANSPORTS.has(t as GatewayMethodTransport));
+}
+
+function toCatalogDescriptor(descriptor: OperatorMethodDescriptor): CatalogMethodDescriptor {
+  // Strip non-catalog fields (effect, confirm). Only the SDK-recognized fields
+  // are forwarded to catalog.register().
+  return {
+    id: descriptor.id,
+    title: descriptor.title,
+    description: descriptor.description,
+    category: descriptor.category,
+    source: mapSource(descriptor.source, descriptor.pluginId),
+    access: mapAccess(descriptor.access),
+    transport: mapTransport(descriptor.transport),
+    scopes: descriptor.scopes,
+    ...(descriptor.pluginId !== undefined ? { pluginId: descriptor.pluginId } : {}),
+    ...(descriptor.inputSchema !== undefined ? { inputSchema: descriptor.inputSchema } : {}),
+    ...(descriptor.outputSchema !== undefined ? { outputSchema: descriptor.outputSchema } : {}),
+  };
+}
+
+function hasConfirmFlag(body: unknown): boolean {
+  return (
+    typeof body === 'object'
+    && body !== null
+    && (body as { confirm?: unknown }).confirm === true
+  );
+}
+
+function explicitUserRequestFlag(metadata: Record<string, unknown> | undefined): boolean {
+  return metadata?.explicitUserRequest === true;
+}
+
+/**
+ * Assert that an invocation carries an explicit, confirmed user request.
+ * Throws OperatorError(REQUIRE_CONFIRM, 403) when not confirmed.
+ */
+export function assertConfirmed(input: {
+  body: unknown;
+  context: { explicitUserRequest?: boolean };
+}): void {
+  if (!hasConfirmFlag(input.body) || input.context.explicitUserRequest !== true) {
+    throw new OperatorError(
+      'This operation requires explicit user confirmation.',
+      REQUIRE_CONFIRM,
+      403,
+    );
+  }
+}
+
+/**
+ * Declare one operator method: applies defaults, wraps the handler with a
+ * confirm-guard + error mapping, and registers it against the real catalog.
+ * Returns the catalog's unregister function.
+ */
+export function declareOperatorMethod<TBody, TResult>(
+  ctx: OperatorContext,
+  descriptor: OperatorMethodDescriptor,
+  handler: OperatorHandler<TBody, TResult>,
+): Unregister {
+  const catalogDescriptor = toCatalogDescriptor(descriptor);
+  const requiresConfirm = descriptor.confirm === true;
+
+  const wrappedHandler = async (input: GatewayMethodInvocation): Promise<unknown> => {
+    // Normalize the SDK invocation context into the operator-facing shape.
+    const explicitUserRequest = explicitUserRequestFlag(input.context.metadata);
+    const operatorContext = {
+      principalId: input.context.principalId ?? '',
+      explicitUserRequest,
+    };
+    try {
+      if (requiresConfirm) {
+        assertConfirmed({ body: input.body, context: operatorContext });
+      }
+      const invocation: OperatorInvocation<TBody> = {
+        body: input.body as TBody,
+        context: operatorContext,
+      };
+      return await handler(invocation);
+    } catch (error) {
+      if (error instanceof OperatorError) throw error;
+      const message = error instanceof Error ? error.message : String(error);
+      throw new OperatorError(message, 'OPERATOR_HANDLER_FAILED', 500);
+    }
+  };
+
+  // CatalogMethodDescriptor is structurally a GatewayMethodDescriptor.
+  return ctx.catalog.register(catalogDescriptor as GatewayMethodDescriptor, wrappedHandler);
+}
+
+/**
+ * Register many methods at once. Returns a single Unregister that tears them all
+ * down (invoking each individual unregister fn in reverse registration order).
+ */
+export function declareOperatorMethods(
+  ctx: OperatorContext,
+  entries: Array<{
+    descriptor: OperatorMethodDescriptor;
+    handler: OperatorHandler<unknown, unknown>;
+  }>,
+): Unregister {
+  const unregisters: Unregister[] = [];
+  for (const entry of entries) {
+    unregisters.push(declareOperatorMethod(ctx, entry.descriptor, entry.handler));
+  }
+  return () => {
+    for (let i = unregisters.length - 1; i >= 0; i -= 1) {
+      try {
+        unregisters[i]?.();
+      } catch {
+        // Best-effort teardown: continue unregistering the rest.
+      }
+    }
+  };
+}

package/src/daemon/operator/sqlite-store.ts

@@ -0,0 +1,124 @@
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import initSqlJs from 'sql.js';
+
+type SqlJsStatic = Awaited<ReturnType<typeof initSqlJs>>;
+type SqlDatabase = InstanceType<SqlJsStatic['Database']>;
+
+export interface OperatorSqliteOptions {
+  workingDirectory: string;
+  /** e.g. 'channel-routes.sqlite', 'drafts.sqlite', 'inbox-cursors.sqlite' */
+  fileName: string;
+  /** CREATE TABLE / INDEX statements run once on init (idempotent: IF NOT EXISTS). */
+  schema: string[];
+}
+
+let sqlJsStaticPromise: Promise<SqlJsStatic> | null = null;
+
+async function loadSqlJs(): Promise<SqlJsStatic> {
+  if (!sqlJsStaticPromise) {
+    sqlJsStaticPromise = initSqlJs();
+  }
+  return sqlJsStaticPromise;
+}
+
+/**
+ * Daemon sqlite helper following the project MemoryStore lifecycle
+ * (sql.js WASM: init → run/exec → save → close). One file per concern under
+ * {workingDirectory}/.goodvibes/tui/operator/{fileName}.
+ */
+export class OperatorSqliteStore {
+  private readonly options: OperatorSqliteOptions;
+  private readonly resolvedPath: string;
+  private db: SqlDatabase | null = null;
+
+  constructor(options: OperatorSqliteOptions) {
+    this.options = options;
+    this.resolvedPath = join(
+      options.workingDirectory,
+      '.goodvibes',
+      'tui',
+      'operator',
+      options.fileName,
+    );
+  }
+
+  get dbPath(): string {
+    return this.resolvedPath;
+  }
+
+  private requireDb(): SqlDatabase {
+    if (!this.db) {
+      throw new Error(`OperatorSqliteStore not initialized: ${this.resolvedPath}`);
+    }
+    return this.db;
+  }
+
+  async init(): Promise<void> {
+    if (this.db) return;
+    await mkdir(dirname(this.resolvedPath), { recursive: true });
+    const SQL = await loadSqlJs();
+    const existing = existsSync(this.resolvedPath) ? readFileSync(this.resolvedPath) : undefined;
+    this.db = existing ? new SQL.Database(existing) : new SQL.Database();
+    for (const statement of this.options.schema) {
+      this.db.run(statement);
+    }
+  }
+
+  /** Execute a write (INSERT/UPDATE/DELETE/CREATE). */
+  run(sql: string, params?: (string | number | Uint8Array | null)[]): void {
+    this.requireDb().run(sql, params);
+  }
+
+  /** SELECT → array of row objects (columns mapped to values). */
+  all<T = Record<string, unknown>>(sql: string, params?: (string | number)[]): T[] {
+    const result = this.requireDb().exec(sql, params);
+    if (result.length === 0) return [];
+    const { columns, values } = result[0]!;
+    return values.map((row) => {
+      const obj: Record<string, unknown> = {};
+      for (let i = 0; i < columns.length; i += 1) {
+        obj[columns[i]!] = row[i];
+      }
+      return obj as T;
+    });
+  }
+
+  /** First row or null. */
+  get<T = Record<string, unknown>>(sql: string, params?: (string | number)[]): T | null {
+    const rows = this.all<T>(sql, params);
+    return rows.length > 0 ? rows[0]! : null;
+  }
+
+  /** Serialize and atomically persist to dbPath (tmp + rename). */
+  async save(): Promise<void> {
+    const db = this.requireDb();
+    await mkdir(dirname(this.resolvedPath), { recursive: true });
+    const data = db.export();
+    const tmpPath = `${this.resolvedPath}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmpPath, data);
+    await rename(tmpPath, this.resolvedPath);
+  }
+
+  close(): void {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+
+  /** BEGIN/COMMIT around fn; ROLLBACK on throw (synchronous sql.js). */
+  transaction(fn: () => void): void {
+    const db = this.requireDb();
+    db.run('BEGIN');
+    try {
+      fn();
+      db.run('COMMIT');
+    } catch (error) {
+      db.run('ROLLBACK');
+      throw error;
+    }
+  }
+}

package/src/daemon/operator/surfaces.ts

@@ -0,0 +1,137 @@
+// ---------------------------------------------------------------------------
+// Daemon operator-surface integration root.
+//
+// `registerDaemonOperatorSurfaces(ctx)` is the single call the runtime services
+// layer (src/runtime/services.ts) makes to publish every daemon operator
+// surface against the shared GatewayMethodCatalog. Each surface module owns its
+// own method declarations; this module only composes their register entry
+// points and aggregates teardown.
+//
+// Surfaces wired here:
+//   - channels.routing.*        (routing/register.ts)
+//   - channels.inbox.list +     (triage/integration.ts -> registerTriagedInbox,
+//     inbox.triage.*             which registers the inbox surface through a
+//                                catalog proxy that overlays triage scores, plus
+//                                the inbox.triage.list / .tag methods)
+//   - channels.drafts.*         (channels/drafts/register.ts)
+//   - calendar.* (CalDAV)       (calendar/register.ts)
+//   - email.*                   (email/register.ts)
+//   - remote.peers.register +   (remote/register.ts) — the register method is
+//     remote dispatch adapter    published on the catalog and the dispatch
+//                                adapter for the existing remote.peers.invoke
+//                                route is exposed on the returned handle.
+//
+// Every surface initializes its stores lazily (on first method invocation), so
+// this composition is synchronous and never blocks daemon bootstrap on disk I/O.
+// The remote peer-registry store is the one async initializer; it is kicked off
+// in the background and the dispatch adapter awaits it implicitly on first use.
+// ---------------------------------------------------------------------------
+
+import type { OperatorContext, Unregister } from './types.ts';
+import { registerRoutingMethods, type RoutingRegistration } from '../channels/routing/register.ts';
+import { createInboxRouteResolver } from '../channels/routing/inbox-bridge.ts';
+import { registerTriagedInbox } from '../triage/integration.ts';
+import { registerDraftsMethods } from '../channels/drafts/register.ts';
+import { registerCalendarMethods } from '../calendar/register.ts';
+import { registerEmailMethods } from '../email/register.ts';
+import {
+  createRemoteSurface,
+  type RemoteSurface,
+  type RemoteInvokeAdapter,
+} from '../remote/register.ts';
+
+/**
+ * Handles returned to the integrator. `unregister()` tears every surface down in
+ * reverse registration order. `remoteDispatch` is the invoke adapter the daemon
+ * server attaches to the existing `remote.peers.invoke` route; `remoteSurface`
+ * exposes the underlying peer registry / dispatcher for advanced wiring.
+ */
+export interface DaemonOperatorSurfaces {
+  /** Tear down every registered operator surface (reverse order). */
+  readonly unregister: Unregister;
+  /** Routing registration handle (store + resolver reuse). */
+  readonly routing: RoutingRegistration;
+  /** Remote execution surface (peer registry + dispatcher). */
+  readonly remoteSurface: RemoteSurface;
+  /** Dispatch adapter for the existing remote.peers.invoke route. */
+  readonly remoteDispatch: RemoteInvokeAdapter;
+}
+
+/**
+ * Register every daemon operator surface against the catalog in `ctx`.
+ *
+ * Synchronous: surfaces defer their disk I/O until first invocation. The only
+ * async initializer (the remote peer registry) is started in the background and
+ * its failure is logged rather than thrown so daemon bootstrap is never blocked.
+ */
+export function registerDaemonOperatorSurfaces(ctx: OperatorContext): DaemonOperatorSurfaces {
+  const teardowns: Unregister[] = [];
+  const pushTeardown = (fn: Unregister): void => {
+    teardowns.push(fn);
+  };
+
+  // Aggregate teardown invoked in reverse registration order; best-effort so one
+  // failing teardown never strands the rest.
+  const unregister: Unregister = () => {
+    for (let i = teardowns.length - 1; i >= 0; i -= 1) {
+      try {
+        teardowns[i]?.();
+      } catch (error) {
+        ctx.logger.warn('operator surface teardown failed', {
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  };
+
+  try {
+    // 1. Routing control plane (channels.routing.list/assign/delete).
+    const routing = registerRoutingMethods(ctx);
+    pushTeardown(routing);
+
+    // 2. Triaged inbox: channels.inbox.list (triage-enriched) + inbox.triage.*.
+    //    Bridge routing's resolver into the inbox so inbound items resolve their
+    //    routeId via the channel<->profile bindings (exact > surface-only >
+    //    wildcard). The resolver is best-effort: a null lookup leaves the item
+    //    unrouted (offline/default fallback) and never throws.
+    pushTeardown(
+      registerTriagedInbox(ctx, {
+        inbox: { resolveRouteId: createInboxRouteResolver(routing.resolver) },
+      }),
+    );
+
+    // 3. Channel drafts mirror (channels.drafts.list/get/save/delete).
+    pushTeardown(registerDraftsMethods(ctx));
+
+    // 4. Calendar (CalDAV) operator methods.
+    pushTeardown(registerCalendarMethods(ctx));
+
+    // 5. Email operator surface (read/list/draft/send).
+    pushTeardown(registerEmailMethods(ctx));
+
+    // 6. Remote execution surface: publish remote.peers.register and build the
+    //    dispatch adapter for the existing remote.peers.invoke route.
+    const remoteSurface = createRemoteSurface(ctx);
+    const unregisterRemoteMethod = remoteSurface.register();
+    const remoteDispatch = remoteSurface.registerDispatch();
+    pushTeardown(() => {
+      try {
+        unregisterRemoteMethod();
+      } finally {
+        remoteSurface.close();
+      }
+    });
+    // Background-init the peer registry store; never block bootstrap on it.
+    void remoteSurface.init().catch((error: unknown) => {
+      ctx.logger.error('remote surface peer-registry init failed', {
+        message: error instanceof Error ? error.message : String(error),
+      });
+    });
+
+    return { unregister, routing, remoteSurface, remoteDispatch };
+  } catch (error) {
+    // Roll back any surfaces registered before the failure.
+    unregister();
+    throw error;
+  }
+}

package/src/daemon/operator/types.ts

@@ -0,0 +1,207 @@
+import { createHash } from 'node:crypto';
+import type {
+  GatewayMethodCatalog,
+  GatewayMethodAccess,
+  GatewayMethodSource,
+  GatewayMethodTransport,
+} from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { SecretsManager } from '../../config/secrets.ts';
+
+// ---------------------------------------------------------------------------
+// Access / transport / effect vocabularies
+// ---------------------------------------------------------------------------
+
+export type OperatorAccess = 'public' | 'authenticated' | 'operator';
+export type OperatorTransport = 'ws' | 'internal' | 'http';
+export type OperatorEffect =
+  | 'read-only'
+  | 'read-only-network'
+  | 'confirmed-effect'
+  | 'confirmed-connected-host-state'
+  | 'local-state-mutation';
+
+// ---------------------------------------------------------------------------
+// Method descriptor
+//
+// Matches catalog.register() descriptor (services.ts survey). The SDK catalog
+// has NO confirmationRequired / effect fields — confirmation is application-level
+// via request body `confirm:true`. The `effect` and `confirm` fields below are
+// metadata-only here; enforcement happens in the handler against body.confirm.
+// ---------------------------------------------------------------------------
+
+export interface OperatorMethodDescriptor {
+  id: string;
+  title: string;
+  description: string;
+  category: string;
+  source?: string; // default 'daemon'
+  access: OperatorAccess;
+  transport?: OperatorTransport[]; // default ['ws','internal']
+  scopes: string[];
+  pluginId?: string;
+  inputSchema?: Record<string, unknown>; // JSON Schema
+  outputSchema?: Record<string, unknown>; // JSON Schema
+  effect?: OperatorEffect; // app-level metadata, not sent to catalog
+  confirm?: boolean; // when true, handler MUST require body.confirm === true
+}
+
+// The exact descriptor shape the SDK catalog.register() accepts
+// (GatewayMethodDescriptor). `source`/`access`/`transport` use the SDK's narrow
+// unions, so the app-level OperatorAccess 'operator' is mapped to 'admin' and the
+// app-level source 'daemon' is mapped to 'builtin' before registration.
+export interface CatalogMethodDescriptor {
+  readonly id: string;
+  readonly title: string;
+  readonly description: string;
+  readonly category: string;
+  readonly source: GatewayMethodSource;
+  readonly access: GatewayMethodAccess;
+  readonly transport: readonly GatewayMethodTransport[];
+  readonly scopes: readonly string[];
+  readonly pluginId?: string;
+  readonly inputSchema?: Record<string, unknown>;
+  readonly outputSchema?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Handler / invocation
+//
+// Matches catalog handler input: async ({ body, context }) => unknown
+// ---------------------------------------------------------------------------
+
+export interface OperatorInvocation<TBody = unknown> {
+  body: TBody;
+  context: { principalId: string; explicitUserRequest?: boolean };
+}
+
+export type OperatorHandler<TBody = unknown, TResult = unknown> = (
+  input: OperatorInvocation<TBody>,
+) => Promise<TResult>;
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+export interface OperatorLogger {
+  info(msg: string, meta?: unknown): void;
+  warn(msg: string, meta?: unknown): void;
+  error(msg: string, meta?: unknown): void;
+}
+
+// ---------------------------------------------------------------------------
+// OperatorContext
+//
+// Context injected into every surface register() by services.ts (the ONE
+// allowed edit there).
+// ---------------------------------------------------------------------------
+
+export interface OperatorContext {
+  readonly catalog: GatewayMethodCatalog;
+  readonly secrets: SecretsManager;
+  // Narrow to the read surface actually used by surfaces (get / getCategory).
+  readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+  readonly logger: OperatorLogger;
+}
+
+export type Unregister = () => void;
+
+// Every surface module's default/contract: register(ctx) => Unregister
+// (call to remove all its methods).
+export type SurfaceRegister = (ctx: OperatorContext) => Unregister;
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class OperatorError extends Error {
+  readonly code: string;
+  readonly status: number;
+
+  constructor(message: string, code: string, status = 400) {
+    super(message);
+    this.name = 'OperatorError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export const REQUIRE_CONFIRM = 'OPERATOR_CONFIRMATION_REQUIRED';
+
+// ---------------------------------------------------------------------------
+// Handoff domain types (shared across surfaces)
+// ---------------------------------------------------------------------------
+
+export interface InboundChannelItem {
+  id: string;
+  surface: string;
+  accountId?: string;
+  conversationId?: string;
+  conversationKind?: 'direct' | 'group' | 'channel' | 'thread' | string;
+  fromDigest: string; // sha256First(fromAddress, 16)
+  messageDigest: string; // sha256First(messageBody, 12)
+  subject?: string;
+  snippet?: string;
+  receivedAt: string; // ISO-8601
+  unread: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ChannelRoute {
+  id: string;
+  surface: string;
+  accountId?: string;
+  matchKind: 'sender' | 'conversation' | 'keyword' | 'default' | string;
+  matchValue: string;
+  targetSurface: string;
+  targetConversationId?: string;
+  priority: number;
+  enabled: boolean;
+  webhook?: string; // redacted on read via redactWebhook()
+  createdAt: string; // ISO-8601
+  updatedAt: string; // ISO-8601
+}
+
+export interface DraftRecord {
+  id: string;
+  surface: string;
+  accountId?: string;
+  conversationId?: string;
+  to?: string;
+  subject?: string;
+  bodyCiphertext: string; // AES-256-GCM, base64(iv|tag|ct) — never plaintext at rest
+  status: 'draft' | 'queued' | 'sent' | 'failed' | string;
+  createdAt: string; // ISO-8601
+  updatedAt: string; // ISO-8601
+  metadata?: Record<string, unknown>;
+}
+
+export interface CalendarEventSummary {
+  id: string;
+  calendarId?: string;
+  title: string;
+  start: string; // ISO-8601
+  end: string; // ISO-8601
+  allDay?: boolean;
+  location?: string;
+  organizerDigest?: string; // sha256First(organizer, 16)
+  status?: 'confirmed' | 'tentative' | 'cancelled' | string;
+  metadata?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Digest / redaction conventions (shared pure helpers)
+// ---------------------------------------------------------------------------
+
+/** SHA-256 of input, truncated to the first `hexChars` hex characters. */
+export function sha256First(input: string, hexChars: number): string {
+  const digest = createHash('sha256').update(input, 'utf-8').digest('hex');
+  return digest.slice(0, Math.max(0, hexChars));
+}
+
+/** Returns '[redacted]' when a value is present, otherwise undefined. */
+export function redactWebhook(value?: string): string | undefined {
+  return value === undefined || value === null || value === '' ? undefined : '[redacted]';
+}