Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
4.0 KB
Raw Blame
/**
 * Per-(human, channel) workspace key derivation.
 *
 * `mcp-host` is a collective agent (one Pod = one agent shared by many humans).
 * Conversations are isolated by `sessionKey` (`userId:channelType:...`), but the
 * filesystem workspace is flat and global. This helper produces the stable,
 * filesystem-safe key used to namespace per-user data under `users/<userKey>/`
 * (FS isolation, plan F0–F5).
 *
 * The key is `sha256("<channelType>:<sender>")` truncated to 16 hex chars:
 *  - **stable**: same input → same key (memory survives across the user's
 *    sessions on the same channel),
 *  - **channel-namespaced**: the same `sender` string on different channels
 *    yields different keys → no accidental cross-channel collision (C2),
 *  - **path-safe**: only `[0-9a-f]`, so a malicious `sender` (`../`, `/`, null
 *    bytes) can never traverse out of the namespace, and no PII lands in a
 *    directory name.
 *
 * Cross-channel identity reconciliation (the same human across Telegram/Desktop
 * sharing one key) is deliberately NOT done here — that is the deferred
 * canonical-identity work (C4). This helper isolates by (person, channel).
 */
import { createHash } from 'node:crypto'
import type { IncomingMessage } from '../server/types'
import { parseSessionKey } from '../session/types'

/** Reserved namespace for tasks with no human origin (cron, system, internal). */
export const SYSTEM_USER_KEY = '_system'

/** Length of the truncated hex digest used as the user key. */
const KEY_HEX_LENGTH = 16

/**
 * Derive the user key from a bare `(sender, channelType)` pair. An empty or
 * whitespace-only `sender` maps to {@link SYSTEM_USER_KEY} (no human origin).
 */
export function deriveUserKey(
  sender: string | null | undefined,
  channelType: string | null | undefined
): string {
  const normalizedSender = (sender ?? '').trim()
  if (normalizedSender.length === 0) return SYSTEM_USER_KEY
  const normalizedChannel = (channelType ?? '').trim()
  return createHash('sha256')
    .update(`${normalizedChannel}:${normalizedSender}`, 'utf8')
    .digest('hex')
    .slice(0, KEY_HEX_LENGTH)
}

/**
 * Derive the user key from a task's source message. Cron/system/internal tasks
 * carry no `sourceMessage` → {@link SYSTEM_USER_KEY}.
 */
/**
 * Shared normalization so the source path and the sessionKey path produce the
 * SAME key for the same logical session. Mirrors TaskExecutor's sessionKey
 * construction (`userId: sender || 'anonymous'`, `channelType: channelType ||
 * 'internal'`) and maps that exact source-less fallback to the system key.
 */
function deriveUserKeyForSession(
  userId: string | null | undefined,
  channelType: string | null | undefined
): string {
  const u = userId || 'anonymous'
  const c = channelType || 'internal'
  if (u === 'anonymous' && c === 'internal') return SYSTEM_USER_KEY
  return deriveUserKey(u, c)
}

export function deriveUserKeyFromSource(
  sourceMessage?: Pick<IncomingMessage, 'sender' | 'channelType'> | null
): string {
  if (!sourceMessage) return SYSTEM_USER_KEY
  return deriveUserKeyForSession(sourceMessage.sender, sourceMessage.channelType)
}

/**
 * Derive the user key from a serialized `sessionKey`
 * (`userId:channelType:channelId:threadId`). Used by the compaction path, which
 * only has the sessionKey (no `sourceMessage`).
 *
 * MUST agree with {@link deriveUserKeyFromSource} for the same logical session.
 * `TaskExecutor` builds the sessionKey with `userId: msg?.sender || 'anonymous'`
 * and `channelType: msg?.channelType || 'internal'` for tasks without a source
 * message (cron/system/internal). Those map back to {@link SYSTEM_USER_KEY} so
 * the compaction path and the source path don't split-brain into two roots for
 * the same system task. A malformed sessionKey also maps to the system key.
 */
export function deriveUserKeyFromSessionKey(sessionKey: string): string {
  const parsed = parseSessionKey(sessionKey)
  if (!parsed) return SYSTEM_USER_KEY
  return deriveUserKeyForSession(parsed.userId, parsed.channelType)
}