stegdoc 3.0.2 → 5.0.0

package/src/lib/log-generator.js

@@ -0,0 +1,764 @@
+/**
+ * Log-Based Steganography Engine (v5)
+ *
+ * Encodes binary payload into realistic nginx access log entries.
+ * Payload is distributed across URL paths, query params, referer fields,
+ * UUIDs (X-Request-ID), and hex trace IDs (X-Trace-ID).
+ *
+ * No hidden sheets — the data IS the logs.
+ */
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/**
+ * Payload bytes carried per channel per log line.
+ * These are RAW BYTE counts (before base64url/hex encoding).
+ */
+const CHANNEL_SIZES = {
+  urlPath: 21,      // base64url in URL path segment (28 chars)
+  queryToken: 21,   // base64url in ?token= param (28 chars)
+  queryState: 21,   // base64url in &state= param (28 chars)
+  referer: 21,      // base64url in referer ?ref= param (28 chars)
+  requestId: 14,    // hex in UUID v4 format (32 hex chars, 6 bits forced)
+  traceId: 16,      // hex in 32-char trace ID
+};
+
+const BYTES_PER_DATA_LINE = Object.values(CHANNEL_SIZES).reduce((a, b) => a + b, 0); // 114
+
+const HEADER_MARKER_PATH = '/api/v1/health';
+
+// ─── IP Pool (Zipfian-ish distribution) ─────────────────────────────────────
+
+const IP_POOL_FREQUENT = [
+  '10.0.14.72', '10.0.14.73', '10.0.14.80', '10.0.15.12',
+  '172.16.0.45', '172.16.0.46', '192.168.1.100', '192.168.1.101',
+];
+
+const IP_POOL_RARE = [
+  '10.0.14.91', '10.0.14.92', '10.0.14.93', '10.0.15.20',
+  '10.0.15.21', '10.0.15.30', '10.0.16.10', '10.0.16.11',
+  '172.16.0.50', '172.16.0.51', '172.16.0.55', '172.16.1.10',
+  '172.16.1.15', '172.16.1.20', '192.168.1.110', '192.168.1.120',
+  '192.168.1.130', '192.168.1.140', '192.168.1.200', '192.168.2.10',
+  '192.168.2.20', '192.168.2.30', '192.168.2.40', '192.168.2.50',
+];
+
+// ─── User-Agent Pool ────────────────────────────────────────────────────────
+
+const USER_AGENTS = [
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:123.0) Gecko/20100101 Firefox/123.0',
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3 Safari/605.1.15',
+  'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Edge/122.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:123.0) Gecko/20100101 Firefox/123.0',
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3 Mobile/15E148 Safari/604.1',
+  'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Mobile Safari/537.36',
+  // Bots (occasional)
+  'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)',
+  'Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm)',
+];
+
+// Weights for UA selection (frequent browsers appear more)
+const UA_WEIGHTS = [20, 15, 12, 10, 8, 7, 6, 5, 4, 3, 1, 1];
+
+// ─── URL Path Templates (for data lines) ───────────────────────────────────
+
+// All templates place the token as the LAST path segment for unambiguous extraction.
+const URL_TEMPLATES = [
+  { path: '/api/v2/sessions/validate/{0}', query: 'token={1}&state={2}' },
+  { path: '/api/v2/auth/callback/{0}', query: 'token={1}&state={2}' },
+  { path: '/api/v2/users/profile/{0}', query: 'token={1}&state={2}' },
+  { path: '/api/v2/tokens/refresh/{0}', query: 'token={1}&state={2}' },
+  { path: '/api/v2/oauth/authorize/{0}', query: 'token={1}&state={2}' },
+  { path: '/api/v2/verify/email/{0}', query: 'token={1}&state={2}' },
+  { path: '/api/v2/sso/saml/{0}', query: 'token={1}&state={2}' },
+  { path: '/api/v2/mfa/challenge/{0}', query: 'token={1}&state={2}' },
+];
+
+const REFERER_TEMPLATES = [
+  'https://dashboard.internal.local/overview?ref={0}',
+  'https://dashboard.internal.local/settings?ref={0}',
+  'https://sso.internal.local/auth/login?ref={0}',
+  'https://dashboard.internal.local/account?ref={0}',
+  'https://admin.internal.local/users?ref={0}',
+  'https://dashboard.internal.local/reports?ref={0}',
+];
+
+// ─── Status Code Distribution ───────────────────────────────────────────────
+
+const STATUS_CODES = [
+  { code: 200, weight: 75 },
+  { code: 201, weight: 3 },
+  { code: 204, weight: 2 },
+  { code: 301, weight: 3 },
+  { code: 302, weight: 5 },
+  { code: 304, weight: 4 },
+  { code: 400, weight: 2 },
+  { code: 401, weight: 1 },
+  { code: 403, weight: 1 },
+  { code: 404, weight: 3 },
+  { code: 500, weight: 1 },
+];
+
+// ─── HTTP Methods ───────────────────────────────────────────────────────────
+
+const HTTP_METHODS = [
+  { method: 'GET', weight: 70 },
+  { method: 'POST', weight: 20 },
+  { method: 'PUT', weight: 5 },
+  { method: 'DELETE', weight: 3 },
+  { method: 'PATCH', weight: 2 },
+];
+
+// ─── Timestamp Management ───────────────────────────────────────────────────
+
+let sharedTimeState = null;
+
+function initTimeState() {
+  if (!sharedTimeState) {
+    const now = new Date();
+    sharedTimeState = {
+      current: new Date(now.getTime() - 4 * 60 * 60 * 1000), // Start 4 hours ago
+      end: now,
+    };
+  }
+  return sharedTimeState;
+}
+
+function resetTimeState() {
+  sharedTimeState = null;
+}
+
+function nextTimestamp() {
+  const state = initTimeState();
+  // Advance by 0.1-3 seconds (realistic inter-request interval)
+  const advanceMs = 100 + Math.floor(Math.random() * 2900);
+  state.current = new Date(state.current.getTime() + advanceMs);
+
+  const d = state.current;
+  const day = String(d.getDate()).padStart(2, '0');
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const mon = months[d.getMonth()];
+  const year = d.getFullYear();
+  const h = String(d.getHours()).padStart(2, '0');
+  const m = String(d.getMinutes()).padStart(2, '0');
+  const s = String(d.getSeconds()).padStart(2, '0');
+
+  return `[${day}/${mon}/${year}:${h}:${m}:${s} +0000]`;
+}
+
+// ─── Base64url Helpers ──────────────────────────────────────────────────────
+
+function toBase64Url(buffer) {
+  return buffer.toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+function fromBase64Url(str) {
+  // Restore padding
+  let s = str.replace(/-/g, '+').replace(/_/g, '/');
+  const pad = (4 - (s.length % 4)) % 4;
+  s += '='.repeat(pad);
+  return Buffer.from(s, 'base64');
+}
+
+// ─── UUID Payload Encoding ──────────────────────────────────────────────────
+
+/**
+ * Encode exactly 14 bytes into a valid UUID v4 string.
+ * Uses 28 hex chars from payload, inserts version nibble (4) and variant bits (10xx).
+ */
+function encodeUuidPayload(buf14) {
+  if (buf14.length !== 14) throw new Error(`UUID payload must be 14 bytes, got ${buf14.length}`);
+
+  const hex = buf14.toString('hex'); // 28 chars
+
+  // UUID hex layout (32 chars, no dashes):
+  // Positions: 0-7 | 8-11 | 12(ver)13-15 | 16(var)17-19 | 20-31
+  // We inject version nibble '4' at pos 12, variant nibble at pos 16
+  // Variant: top 2 bits = 10, bottom 2 bits from payload
+  const variantNibble = (8 | (parseInt(hex[12], 16) & 0x3)).toString(16);
+
+  const uuidHex =
+    hex.slice(0, 12) +     // positions 0-11 (payload bytes 0-5)
+    '4' +                   // position 12 (version)
+    hex.slice(12, 15) +    // positions 13-15 (payload byte 6 low nibble + byte 7 high nibble)
+    variantNibble +         // position 16 (variant, carries 2 bits from payload)
+    hex.slice(15, 28);     // positions 17-31 ... wait, 28-15 = 13 chars at positions 17-29, need 15 chars (17-31)
+
+  // Let me recalculate. We have 28 payload hex chars to place in 30 usable positions
+  // (32 total - version nibble - variant loses 2 bits = 30 full nibbles + 2 bits)
+  // Actually: 32 positions - 1 (version fully replaced) = 31 positions
+  // Position 16 carries 2 payload bits (low 2 of the nibble), high 2 are forced to 10
+  // So: 30 full nibbles + 2 bits = 122 bits = 15.25 bytes
+  // We use 14 bytes = 112 bits = 28 nibbles, well within 30+2
+
+  // Simpler approach: place 28 hex chars sequentially, skip position 12 and 16
+  // Position 0-11: hex[0-11]
+  // Position 12: '4' (version)
+  // Position 13-15: hex[12-14]
+  // Position 16: variant nibble (8 | (hex[15] & 0x3))... but this destroys 2 bits of hex[15]
+
+  // Even simpler: just use first 12 + last 16 hex chars = 28, around the forced nibbles
+  // No — let's do it properly with a clean algorithm:
+
+  // Actually the above code has an issue. Let me redo this cleanly.
+  // We have 28 hex chars (14 bytes payload).
+  // We need to place them into 32 UUID hex positions, skipping pos 12 (version=4)
+  // and at pos 16 modifying the high 2 bits (variant=10).
+
+  // Available positions for full payload nibbles: 0-11, 13-15, 17-31 = 30 positions
+  // Position 16 carries 2 payload bits (low 2) + 2 forced bits (high 2)
+  // We only need 28 positions, so we have room.
+
+  // Strategy: fill positions 0-11 with hex[0-11], skip 12 (='4'),
+  // fill positions 13-15 with hex[12-14],
+  // position 16 = (0x8 | (parseInt(hex[15], 16) & 0x3)).toString(16) -- carries 2 bits
+  // fill positions 17-31 with hex[16-27]... that's only 12 chars but need 15.
+
+  // hex chars used: 0-11(12) + 12-14(3) + [15 partial 2 bits] + 16-27(12) = 27 full + 2 bits
+  // That's only 27.25 nibbles = 13.625 bytes. Not 14. We're short.
+
+  // The issue: position 16 only carries 2 bits from hex[15], wasting 2 bits.
+  // So we actually carry: 12 + 3 + 0.5 + 12 = 27.5 nibbles = 110 bits = 13.75 bytes
+  // We can reliably carry 13 bytes this way, not 14.
+
+  // To carry 14 bytes (112 bits = 28 nibbles), we need 28 full nibble positions.
+  // Available full positions: 0-11 (12) + 13-15 (3) + 17-31 (15) = 30 full positions.
+  // Plus position 16 carries 2 partial bits.
+  // So 30 full positions > 28 needed. We have room!
+
+  // Correct strategy:
+  // Positions 0-11: hex[0-11]     (12 nibbles)
+  // Position 12: '4'              (version)
+  // Positions 13-15: hex[12-14]   (3 nibbles)
+  // Position 16: variant nibble   (forced, carries 0 payload bits)
+  // Positions 17-31: hex[15-27]   (13 nibbles) -- wait 27-15+1 = 13, total = 12+3+13 = 28 ✓
+
+  // So position 16 is FULLY forced (no payload bits), and we use 30 available
+  // full positions minus 2 unused = 28 payload nibbles.
+
+  // Build it:
+  const pos0_11 = hex.slice(0, 12);
+  const pos13_15 = hex.slice(12, 15);
+  const pos16 = ['8', '9', 'a', 'b'][Math.floor(Math.random() * 4)]; // random valid variant
+  const pos17_31 = hex.slice(15, 28);
+
+  const full = pos0_11 + '4' + pos13_15 + pos16 + pos17_31;
+  // full length: 12 + 1 + 3 + 1 + 13 = 30... need 32
+
+  // I'm off by 2. Let me count UUID hex chars: 8-4-4-4-12 = 32 chars without dashes.
+  // Positions 0-31.
+  // 0-11 = 12, pos12 = 1, 13-15 = 3, pos16 = 1, 17-31 = 15. Total = 12+1+3+1+15 = 32. ✓
+  // So positions 17-31 = 15 chars. hex[15-27] = 13 chars. Need 15.
+  // 13 < 15. We're 2 chars short.
+
+  // We have 28 payload nibbles to place in 30 available slots (0-11, 13-15, 17-31).
+  // That's 12 + 3 + 15 = 30 slots. 28 payload chars leaves 2 unused.
+  // Fill remaining 2 with random hex to complete the UUID.
+
+  const padding = randomHex(2);
+  const fullHex = pos0_11 + '4' + pos13_15 + pos16 + hex.slice(15, 28) + padding;
+
+  return `${fullHex.slice(0, 8)}-${fullHex.slice(8, 12)}-${fullHex.slice(12, 16)}-${fullHex.slice(16, 20)}-${fullHex.slice(20, 32)}`;
+}
+
+function decodeUuidPayload(uuidStr) {
+  const hex = uuidStr.replace(/-/g, '');
+  if (hex.length !== 32) throw new Error('Invalid UUID format');
+
+  // Extract payload nibbles from known positions:
+  // Positions 0-11: payload[0-11]
+  // Position 12: version (skip)
+  // Positions 13-15: payload[12-14]
+  // Position 16: variant (skip)
+  // Positions 17-29: payload[15-27]
+  // Positions 30-31: padding (skip)
+
+  const payloadHex =
+    hex.slice(0, 12) +    // 12 nibbles
+    hex.slice(13, 16) +   // 3 nibbles
+    hex.slice(17, 30);    // 13 nibbles = 28 total
+
+  return Buffer.from(payloadHex, 'hex'); // 14 bytes
+}
+
+// ─── Trace ID Encoding ──────────────────────────────────────────────────────
+
+function encodeTraceId(buf16) {
+  if (buf16.length !== 16) throw new Error(`Trace ID payload must be 16 bytes, got ${buf16.length}`);
+  return buf16.toString('hex');
+}
+
+function decodeTraceId(traceStr) {
+  return Buffer.from(traceStr, 'hex');
+}
+
+// ─── Random Helpers ─────────────────────────────────────────────────────────
+
+const crypto = require('crypto');
+
+function randomHex(chars) {
+  return crypto.randomBytes(Math.ceil(chars / 2)).toString('hex').slice(0, chars);
+}
+
+function weightedRandom(items) {
+  const total = items.reduce((sum, item) => sum + item.weight, 0);
+  let r = Math.random() * total;
+  for (const item of items) {
+    r -= item.weight;
+    if (r <= 0) return item;
+  }
+  return items[0];
+}
+
+function randomIp() {
+  // 80% frequent IPs, 20% rare
+  if (Math.random() < 0.8) {
+    return IP_POOL_FREQUENT[Math.floor(Math.random() * IP_POOL_FREQUENT.length)];
+  }
+  return IP_POOL_RARE[Math.floor(Math.random() * IP_POOL_RARE.length)];
+}
+
+function randomUserAgent() {
+  const totalWeight = UA_WEIGHTS.reduce((a, b) => a + b, 0);
+  let r = Math.random() * totalWeight;
+  for (let i = 0; i < USER_AGENTS.length; i++) {
+    r -= UA_WEIGHTS[i];
+    if (r <= 0) return USER_AGENTS[i];
+  }
+  return USER_AGENTS[0];
+}
+
+function randomResponseBytes(status) {
+  if (status === 204 || status === 304) return 0;
+  if (status >= 300 && status < 400) return 0;
+  if (status === 404) return 200 + Math.floor(Math.random() * 300);
+  if (status >= 500) return 300 + Math.floor(Math.random() * 500);
+  // 200-range: typical API response sizes
+  return 100 + Math.floor(Math.random() * 15000);
+}
+
+function randomFillerUuid() {
+  const bytes = crypto.randomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function randomFillerTraceId() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+// ─── Core Encoding ──────────────────────────────────────────────────────────
+
+/**
+ * Generate column headers for the Access Logs sheet.
+ */
+function generateLogHeaders() {
+  return [
+    'Remote Address',
+    'Timestamp',
+    'Method',
+    'Request',
+    'Status',
+    'Bytes',
+    'Referer',
+    'User-Agent',
+    'X-Request-ID',
+    'X-Trace-ID',
+  ];
+}
+
+/**
+ * Distribute a payload chunk (Buffer) across log line channels.
+ * Returns { urlPath, queryToken, queryState, referer, requestId, traceId } as encoded strings.
+ */
+function distributePayload(payloadBuf) {
+  let offset = 0;
+
+  function take(n) {
+    const end = Math.min(offset + n, payloadBuf.length);
+    const slice = payloadBuf.slice(offset, end);
+    offset = end;
+    return slice;
+  }
+
+  function takePadded(n) {
+    const slice = take(n);
+    if (slice.length < n) {
+      // Pad with random bytes for the last partial line
+      return Buffer.concat([slice, crypto.randomBytes(n - slice.length)]);
+    }
+    return slice;
+  }
+
+  return {
+    urlPath: toBase64Url(takePadded(CHANNEL_SIZES.urlPath)),
+    queryToken: toBase64Url(takePadded(CHANNEL_SIZES.queryToken)),
+    queryState: toBase64Url(takePadded(CHANNEL_SIZES.queryState)),
+    referer: toBase64Url(takePadded(CHANNEL_SIZES.referer)),
+    requestId: encodeUuidPayload(takePadded(CHANNEL_SIZES.requestId)),
+    traceId: encodeTraceId(takePadded(CHANNEL_SIZES.traceId)),
+    bytesConsumed: Math.min(offset, payloadBuf.length),
+  };
+}
+
+/**
+ * Generate a data log line carrying payload bytes.
+ * @param {Buffer} payloadChunk - Chunk of payload for this line (up to BYTES_PER_DATA_LINE)
+ * @returns {Array} Row array of 10 cell values
+ */
+function generateDataLogLine(payloadChunk) {
+  const channels = distributePayload(payloadChunk);
+  const template = URL_TEMPLATES[Math.floor(Math.random() * URL_TEMPLATES.length)];
+  const refTemplate = REFERER_TEMPLATES[Math.floor(Math.random() * REFERER_TEMPLATES.length)];
+  const method = weightedRandom(HTTP_METHODS).method;
+  const statusObj = weightedRandom(STATUS_CODES);
+  const status = statusObj.code;
+
+  const requestPath = template.path.replace('{0}', channels.urlPath) +
+    '?' + template.query.replace('{1}', channels.queryToken).replace('{2}', channels.queryState);
+
+  const refererUrl = refTemplate.replace('{0}', channels.referer);
+
+  return [
+    randomIp(),
+    nextTimestamp(),
+    method,
+    `${method} ${requestPath} HTTP/1.1`,
+    status,
+    randomResponseBytes(status),
+    refererUrl,
+    randomUserAgent(),
+    channels.requestId,
+    channels.traceId,
+  ];
+}
+
+/**
+ * Generate a header log line carrying metadata/encryption bytes.
+ * Uses the /api/v1/health marker so the decoder can identify these lines.
+ * @param {Buffer} payloadChunk - Metadata chunk for this line
+ * @returns {Array} Row array of 10 cell values
+ */
+function generateHeaderLogLine(payloadChunk) {
+  const channels = distributePayload(payloadChunk);
+  const status = 200;
+
+  // Health check always uses GET and the marker path
+  const requestPath = `${HEADER_MARKER_PATH}/${channels.urlPath}` +
+    `?token=${channels.queryToken}&state=${channels.queryState}`;
+
+  const refererUrl = `https://monitor.internal.local/health?ref=${channels.referer}`;
+
+  return [
+    '10.0.0.1',  // Monitoring system IP (consistent)
+    nextTimestamp(),
+    'GET',
+    `GET ${requestPath} HTTP/1.1`,
+    status,
+    randomResponseBytes(status),
+    refererUrl,
+    'HealthCheck/1.0 (monitoring)',
+    channels.requestId,
+    channels.traceId,
+  ];
+}
+
+/**
+ * Generate a pure filler log line (no payload, all random data).
+ * @returns {Array} Row array of 10 cell values
+ */
+function generateFillerLogLine() {
+  const template = URL_TEMPLATES[Math.floor(Math.random() * URL_TEMPLATES.length)];
+  const refTemplate = REFERER_TEMPLATES[Math.floor(Math.random() * REFERER_TEMPLATES.length)];
+  const method = weightedRandom(HTTP_METHODS).method;
+  const status = weightedRandom(STATUS_CODES).code;
+
+  // Random tokens for realistic look
+  const randPath = toBase64Url(crypto.randomBytes(CHANNEL_SIZES.urlPath));
+  const randToken = toBase64Url(crypto.randomBytes(CHANNEL_SIZES.queryToken));
+  const randState = toBase64Url(crypto.randomBytes(CHANNEL_SIZES.queryState));
+  const randRef = toBase64Url(crypto.randomBytes(CHANNEL_SIZES.referer));
+
+  const requestPath = template.path.replace('{0}', randPath) +
+    '?' + template.query.replace('{1}', randToken).replace('{2}', randState);
+  const refererUrl = refTemplate.replace('{0}', randRef);
+
+  return [
+    randomIp(),
+    nextTimestamp(),
+    method,
+    `${method} ${requestPath} HTTP/1.1`,
+    status,
+    randomResponseBytes(status),
+    refererUrl,
+    randomUserAgent(),
+    randomFillerUuid(),
+    randomFillerTraceId(),
+  ];
+}
+
+// ─── Core Decoding ──────────────────────────────────────────────────────────
+
+/**
+ * Check if a row is a header line (carries metadata).
+ * @param {Array} row - Row array from spreadsheet
+ * @returns {boolean}
+ */
+function isHeaderLine(row) {
+  const request = String(row[3] || '');
+  return request.includes(HEADER_MARKER_PATH);
+}
+
+/**
+ * Extract payload bytes from a data or header log line.
+ * @param {Array} row - Row array from spreadsheet
+ * @returns {Buffer} Extracted payload bytes (up to BYTES_PER_DATA_LINE)
+ */
+function extractPayloadFromLine(row) {
+  const request = String(row[3] || '');
+  const referer = String(row[6] || '');
+  const requestId = String(row[8] || '');
+  const traceId = String(row[9] || '');
+
+  const buffers = [];
+
+  // Strip HTTP version from request: "GET /path?q=v HTTP/1.1" → "/path?q=v"
+  const urlOnly = request.replace(/^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+/, '').replace(/\s+HTTP\/[\d.]+$/, '');
+
+  // 1. URL path segment — extract the LAST base64url segment from the path
+  let pathPayload;
+  const pathOnly = urlOnly.split('?')[0]; // Remove query string
+  if (isHeaderLine(row)) {
+    // Header: /api/v1/health/{token}
+    const pathMatch = pathOnly.match(/\/api\/v1\/health\/([A-Za-z0-9_-]+)$/);
+    pathPayload = pathMatch ? pathMatch[1] : null;
+  } else {
+    // Data: token is always the last path segment after /api/v2/.../<word>/
+    const segments = pathOnly.split('/').filter(Boolean);
+    // Last segment is the token (all templates place {0} last)
+    pathPayload = segments.length > 0 ? segments[segments.length - 1] : null;
+    // Verify it looks like base64url (at least 20 chars of [A-Za-z0-9_-])
+    if (pathPayload && !/^[A-Za-z0-9_-]{20,}$/.test(pathPayload)) {
+      pathPayload = null;
+    }
+  }
+  buffers.push(pathPayload ? fromBase64Url(pathPayload).slice(0, CHANNEL_SIZES.urlPath) : Buffer.alloc(CHANNEL_SIZES.urlPath));
+
+  // 2. Query token param
+  const tokenMatch = urlOnly.match(/[?&]token=([A-Za-z0-9_-]+)/);
+  buffers.push(tokenMatch ? fromBase64Url(tokenMatch[1]).slice(0, CHANNEL_SIZES.queryToken) : Buffer.alloc(CHANNEL_SIZES.queryToken));
+
+  // 3. Query state param
+  const stateMatch = urlOnly.match(/[?&]state=([A-Za-z0-9_-]+)/);
+  buffers.push(stateMatch ? fromBase64Url(stateMatch[1]).slice(0, CHANNEL_SIZES.queryState) : Buffer.alloc(CHANNEL_SIZES.queryState));
+
+  // 4. Referer ref param
+  const refMatch = referer.match(/[?&]ref=([A-Za-z0-9_-]+)/);
+  buffers.push(refMatch ? fromBase64Url(refMatch[1]).slice(0, CHANNEL_SIZES.referer) : Buffer.alloc(CHANNEL_SIZES.referer));
+
+  // 5. X-Request-ID (UUID)
+  if (requestId && requestId.includes('-')) {
+    buffers.push(decodeUuidPayload(requestId));
+  } else {
+    buffers.push(Buffer.alloc(CHANNEL_SIZES.requestId));
+  }
+
+  // 6. X-Trace-ID (hex)
+  if (traceId && traceId.length === 32 && /^[a-f0-9]+$/i.test(traceId)) {
+    buffers.push(decodeTraceId(traceId));
+  } else {
+    buffers.push(Buffer.alloc(CHANNEL_SIZES.traceId));
+  }
+
+  return Buffer.concat(buffers);
+}
+
+// ─── High-Level API ─────────────────────────────────────────────────────────
+
+/**
+ * Encode a complete payload buffer into log line rows.
+ * Returns { headerRows, dataRows, fillerRows } — arrays of row arrays.
+ *
+ * @param {Buffer} payloadBuffer - The encrypted payload bytes
+ * @param {string} metadataJson - Serialized metadata JSON
+ * @param {string} encryptionMeta - Packed encryption meta (iv:salt:authTag) or ''
+ * @returns {object} { headerRows, dataRows, fillerRows }
+ */
+function encodePayloadToLogLines(payloadBuffer, metadataJson, encryptionMeta) {
+  // Build the header payload with length-prefixed format to avoid parsing ambiguity.
+  // Format: "STGD05|<metaLen>|<encLen>|{metadataJson}{encryptionMeta}"
+  // This way we know exactly where metadata ends and encryption meta begins.
+  const metaBytes = Buffer.from(metadataJson, 'utf8');
+  const encBytes = Buffer.from(encryptionMeta || '', 'utf8');
+  const prefix = `STGD05|${metaBytes.length}|${encBytes.length}|`;
+  const headerPayload = Buffer.concat([Buffer.from(prefix), metaBytes, encBytes]);
+
+  // Generate header lines
+  const headerLineCount = Math.ceil(headerPayload.length / BYTES_PER_DATA_LINE);
+  const headerRows = [];
+  for (let i = 0; i < headerLineCount; i++) {
+    const start = i * BYTES_PER_DATA_LINE;
+    const chunk = headerPayload.slice(start, start + BYTES_PER_DATA_LINE);
+    headerRows.push(generateHeaderLogLine(chunk));
+  }
+
+  // Generate data lines
+  const dataLineCount = Math.ceil(payloadBuffer.length / BYTES_PER_DATA_LINE);
+  const dataRows = [];
+  for (let i = 0; i < dataLineCount; i++) {
+    const start = i * BYTES_PER_DATA_LINE;
+    const chunk = payloadBuffer.slice(start, start + BYTES_PER_DATA_LINE);
+    dataRows.push(generateDataLogLine(chunk));
+  }
+
+  // Generate filler lines for realism
+  const fillerCount = Math.max(30, Math.floor(dataLineCount * 0.2));
+  const fillerRows = [];
+  for (let i = 0; i < fillerCount; i++) {
+    fillerRows.push(generateFillerLogLine());
+  }
+
+  return { headerRows, dataRows, fillerRows };
+}
+
+/**
+ * Decode log line rows back into metadata and payload.
+ * @param {Array<Array>} allRows - All rows from the spreadsheet (excluding header row)
+ * @returns {object} { metadataJson, encryptionMeta, payloadBuffer }
+ */
+function decodeLogLines(allRows) {
+  const headerPayloadBuffers = [];
+  const dataPayloadBuffers = [];
+
+  // Separate header lines from data/filler lines
+  let headersDone = false;
+  let dataLinesRead = 0;
+
+  for (const row of allRows) {
+    if (!headersDone && isHeaderLine(row)) {
+      headerPayloadBuffers.push(extractPayloadFromLine(row));
+    } else {
+      headersDone = true;
+      // Could be data or filler — collect all, we'll truncate later
+      dataPayloadBuffers.push(extractPayloadFromLine(row));
+    }
+  }
+
+  // Reassemble header payload
+  const headerPayload = Buffer.concat(headerPayloadBuffers);
+  const headerStr = headerPayload.toString('utf8');
+
+  // Parse header: "STGD05|<metaLen>|<encLen>|{metadataJson}{encryptionMeta}"
+  const markerIdx = headerStr.indexOf('STGD05|');
+  if (markerIdx === -1) {
+    throw new Error('Invalid v5 format: magic marker not found. This may not be a stegdoc v5 file.');
+  }
+
+  const afterMarker = headerStr.slice(markerIdx + 7);
+
+  // Parse length fields
+  const firstPipe = afterMarker.indexOf('|');
+  if (firstPipe === -1) {
+    throw new Error('Invalid v5 format: malformed header payload.');
+  }
+  const secondPipe = afterMarker.indexOf('|', firstPipe + 1);
+  if (secondPipe === -1) {
+    throw new Error('Invalid v5 format: malformed header payload (missing encLen).');
+  }
+
+  const metaLen = parseInt(afterMarker.slice(0, firstPipe), 10);
+  const encLen = parseInt(afterMarker.slice(firstPipe + 1, secondPipe), 10);
+
+  if (isNaN(metaLen) || isNaN(encLen)) {
+    throw new Error('Invalid v5 format: non-numeric length fields.');
+  }
+
+  // Extract exact bytes using the known lengths
+  const dataStart = markerIdx + 7 + secondPipe + 1;
+  const metadataBytes = headerPayload.slice(dataStart, dataStart + metaLen);
+  const encryptionBytes = headerPayload.slice(dataStart + metaLen, dataStart + metaLen + encLen);
+
+  const metadataJson = metadataBytes.toString('utf8');
+  const encryptionMeta = encryptionBytes.toString('utf8');
+
+  // Parse metadata to get payloadSize for truncation
+  let metadata;
+  try {
+    metadata = JSON.parse(metadataJson);
+  } catch (e) {
+    throw new Error(`Failed to parse v5 metadata: ${e.message}`);
+  }
+
+  const payloadSize = metadata.payloadSize;
+  if (typeof payloadSize !== 'number' || payloadSize < 0) {
+    throw new Error('Invalid v5 metadata: missing or invalid payloadSize');
+  }
+
+  // Use dataLineCount from metadata to only read actual data lines (skip filler)
+  const dataLineCount = metadata.dataLineCount;
+  if (typeof dataLineCount !== 'number' || dataLineCount < 0) {
+    throw new Error('Invalid v5 metadata: missing or invalid dataLineCount');
+  }
+
+  // Re-extract only the correct number of data lines
+  const actualDataBuffers = dataPayloadBuffers.slice(0, dataLineCount);
+  const fullPayload = Buffer.concat(actualDataBuffers);
+
+  // Truncate to exact payload size
+  const payloadBuffer = fullPayload.slice(0, payloadSize);
+
+  return {
+    metadataJson,
+    encryptionMeta: encryptionMeta || '',
+    payloadBuffer,
+    metadata,
+  };
+}
+
+// ─── Utilities ──────────────────────────────────────────────────────────────
+
+/**
+ * Calculate the number of data lines needed for a payload.
+ * @param {number} payloadSizeBytes - Payload size in bytes
+ * @returns {number} Number of data lines
+ */
+function calculateDataLineCount(payloadSizeBytes) {
+  return Math.ceil(payloadSizeBytes / BYTES_PER_DATA_LINE);
+}
+
+module.exports = {
+  // Constants
+  BYTES_PER_DATA_LINE,
+  CHANNEL_SIZES,
+
+  // Encoding
+  generateLogHeaders,
+  generateDataLogLine,
+  generateHeaderLogLine,
+  generateFillerLogLine,
+  encodePayloadToLogLines,
+
+  // Decoding
+  isHeaderLine,
+  extractPayloadFromLine,
+  decodeLogLines,
+
+  // Utilities
+  calculateDataLineCount,
+  toBase64Url,
+  fromBase64Url,
+  encodeUuidPayload,
+  decodeUuidPayload,
+  encodeTraceId,
+  decodeTraceId,
+  resetTimeState,
+};