inkwatch/shared/events.js

'use strict';

/**
 * 埋点（M5）的事件名与净化规则 —— **5 个事件名的唯一机器副本**。
 *
 * ── 权威与副本 ─────────────────────────────────────────────────────
 * 权威名单在 `docs/SPEC-v2.md` §6.1.1（**改名字只能从那里发起**）。本文件是它的
 * 机器副本，承担差集的另一侧。`openapi.yaml` 与设计稿**刻意不复制**：`openapi.yaml`
 * 的 `EventsBatchRequest.name` 明确写"本文件不复制"且不设 `enum` —— 一旦设 `enum`，
 * AC-20 要求的"整条丢弃 + 计入 `dropped`"就会在网关层被变成 400，
 * **埋点失败被升级成业务失败**，正好违反 AC-22 的精神。
 *
 * ── 为什么不做"逐事件 props 白名单" ────────────────────────────────
 * SPEC 只锁了 5 个事件名，**没有定义逐事件的 props 字段**。此时若在这里发明一套
 * （`{app_open: ['platform','app_version']}`），等于把"产品还没定的字段"由实现方
 * 单方面定死，然后让客户端照着写 —— 那份字段名会立刻变成事实上的契约，而它没有
 * 任何依据。所以这里做的是**形状白名单**，不是字段名白名单：
 *   · 键名必须 `^[a-z][a-z0-9_]{0,31}$`；
 *   · 值只接受标量（string / 有穷 number / boolean），数组与嵌套对象**整条丢弃**；
 *   · 单条 props 至多 12 个键、序列化后至多 2KB；
 *   · 敏感键名（口令/令牌/邮箱/电话/设备名…）**直接丢弃该键**（隐私边界见 SPEC §10）。
 * 形状约束能挡住"埋点变成第二个用户表"这条路上最现实的风险，且不假装知道产品要什么。
 *
 * ── 净化的方向：丢弃，不报错 ──────────────────────────────────────
 * 净化与白名单的失败一律是"丢弃这一条/这个键"，端点**永远 202**（AC-20/AC-22）。
 * 埋点不是业务：让埋点失败去阻断用户动作，是本末倒置。
 */

/** 5 个事件名（逐字，**不要改名、不要增删、不要排序"优化"**）。权威：SPEC §6.1.1 */
const EVENT_NAMES = Object.freeze([
  'app_open',
  'first_frame_shown',
  'quota_blocked',
  'upgrade_click',
  'upgrade_requested',
]);

const EVENT_NAME_SET = new Set(EVENT_NAMES);

/** 单次上报的受理上限（AC-21：超出部分计入 dropped，不是 400） */
const MAX_BATCH = 20;

/** 单条事件的 props 形状上限 */
const MAX_PROP_KEYS = 12;
const MAX_PROP_JSON_BYTES = 2048;
const MAX_PROP_STRING_LEN = 200;

/** 键名合法形状 */
const PROP_KEY_RE = /^[a-z][a-z0-9_]{0,31}$/;

/**
 * 敏感键名：命中即丢弃该键。
 *
 * 隐私边界（SPEC §10）写明不采集键盘/屏幕/浏览记录/通讯录/位置。这里额外把
 * "能反查到人的标识"和"凭据"一律挡掉 —— 它们出现在埋点里从来不是"统计需要"，
 * 而是某次调试顺手打进去的，然后永久留在库里。
 */
const SENSITIVE_PROP_KEYS = new Set([
  'secret', 'password', 'passwd', 'token', 'access_token', 'refresh_token',
  'email', 'phone', 'mobile', 'device_name', 'display_name', 'ip',
  'authorization', 'cookie', 'session',
]);

function isScalar(v) {
  return typeof v === 'string' || typeof v === 'boolean'
    || (typeof v === 'number' && Number.isFinite(v));
}

/**
 * 净化 props。返回 `{}` 表示"没有可留的"（调用方按"无 props"落库，不算丢弃）。
 * 只丢键、不丢整条：一个多余键不该让整条事件消失（丢整条会丢分母）。
 */
function sanitizeProps(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
  const out = {};
  let n = 0;
  for (const [k, v] of Object.entries(raw)) {
    if (n >= MAX_PROP_KEYS) break;
    const key = String(k).toLowerCase();
    if (!PROP_KEY_RE.test(key)) continue;
    if (SENSITIVE_PROP_KEYS.has(key)) continue;
    if (!isScalar(v)) continue;                       // 数组/对象整条丢弃
    if (typeof v === 'string' && v.length > MAX_PROP_STRING_LEN) continue;
    out[key] = v;
    n += 1;
  }
  if (JSON.stringify(out).length > MAX_PROP_JSON_BYTES) return {};
  return out;
}

/**
 * 规整一批上报。**只返回可落库的条目与丢弃数**，不抛错。
 *
 * @param {unknown} raw 请求体里的 `events`
 * @returns {{ accepted: Array<{name:string, props:object, ts:Date|null}>, dropped: number }}
 */
function normalizeBatch(raw) {
  const arr = Array.isArray(raw) ? raw : [];
  const accepted = [];
  let dropped = 0;

  for (let i = 0; i < arr.length; i += 1) {
    const item = arr[i];
    // 超过上限的部分一律计 dropped（AC-21）。注意这里**继续循环**而不是 break：
    // break 之后 `dropped` 只加到上限那一刻，剩下的条目既不受理也不计数 ——
    // 于是 accepted + dropped !== 上报条数，统计口径对不上。
    if (i >= MAX_BATCH) { dropped += 1; continue; }
    if (!item || typeof item !== 'object' || Array.isArray(item)) { dropped += 1; continue; }
    const name = typeof item.name === 'string' ? item.name.trim() : '';
    if (!EVENT_NAME_SET.has(name)) { dropped += 1; continue; }   // AC-20

    // ts 是**客户端提示**，落库时间以服务端 now() 为准（时钟不可信）。
    // 这里只把它当"可选元数据"保留下来前先做形状校验：非法的直接不带。
    let ts = null;
    if (typeof item.ts === 'string' || typeof item.ts === 'number') {
      const d = new Date(item.ts);
      if (!Number.isNaN(d.getTime())) ts = d;
    }
    accepted.push({ name, props: sanitizeProps(item.props), ts });
  }
  return { accepted, dropped };
}

module.exports = {
  EVENT_NAMES,
  EVENT_NAME_SET,
  MAX_BATCH,
  MAX_PROP_KEYS,
  MAX_PROP_STRING_LEN,
  SENSITIVE_PROP_KEYS,
  sanitizeProps,
  normalizeBatch,
};