《互联网产品的客户端架构·规模化与架构演进》8.1 数据分级与最小权限

// file: src/security/data-classification.ts
// tier: L1
// verify: node --test test/security/data-classification.test.ts

export type DataLevel = "public" | "internal" | "sensitive" | "very-sensitive";

export type Purpose =
  | "core-service"
  | "analytics"
  | "personalization"
  | "ads"
  | "security-audit";

export type Channel = "local" | "own-service" | "third-party" | "export";

export type FieldSpec = { name: string; level: DataLevel };

export type DataAsset = {
  id: string;
  title: string;
  fields: FieldSpec[];
  purposes: Purpose[];
  channels: Channel[];
  retentionDays: number | null;
};

export type AccessRequest = {
  assetId: string;
  fields: string[];
  purpose: Purpose;
  channel: Channel;
};

export type AccessDecision = {
  allowed: boolean;
  level: DataLevel | "unknown";
  reasons: string[];
};

export const DATA_LEVELS: DataLevel[] = [
  "public",
  "internal",
  "sensitive",
  "very-sensitive",
];

const LEVEL_RANK: Record<DataLevel, number> = {
  public: 1,
  internal: 2,
  sensitive: 3,
  "very-sensitive": 4,
};

const CHANNEL_CEILING: Record<Channel, number> = {
  local: 4,
  "own-service": 4,
  "third-party": 2,
  export: 3,
};

const RETENTION_LIMIT: Partial<Record<DataLevel, number>> = {
  sensitive: 365,
  "very-sensitive": 30,
};

export const ASSETS: DataAsset[] = [
  {
    id: "order-basic", title: "订单基础信息",
    fields: [
      { name: "orderId", level: "internal" },
      { name: "amount", level: "internal" },
      { name: "status", level: "internal" },
    ],
    purposes: ["core-service", "analytics", "security-audit"],
    channels: ["local", "own-service"], retentionDays: null,
  },
  {
    id: "device-profile", title: "设备画像",
    fields: [
      { name: "osVersion", level: "public" },
      { name: "screenSize", level: "public" },
      { name: "deviceId", level: "internal" },
    ],
    purposes: ["core-service", "analytics", "personalization"],
    channels: ["local", "own-service", "third-party", "export"], retentionDays: null,
  },
  {
    id: "precise-location", title: "精确位置",
    fields: [
      { name: "city", level: "sensitive" },
      { name: "latitude", level: "very-sensitive" },
      { name: "longitude", level: "very-sensitive" },
    ],
    purposes: ["core-service", "personalization", "ads"],
    channels: ["local", "own-service"], retentionDays: 30,
  },
  {
    id: "contact-book", title: "通讯录",
    fields: [
      { name: "displayName", level: "sensitive" },
      { name: "phone", level: "very-sensitive" },
      { name: "email", level: "sensitive" },
    ],
    purposes: ["core-service"],
    channels: ["local", "own-service"], retentionDays: 30,
  },
  {
    id: "ad-identifier", title: "广告标识",
    fields: [
      { name: "clickId", level: "sensitive" },
      { name: "idfa", level: "very-sensitive" },
    ],
    purposes: ["ads", "analytics"],
    channels: ["local", "own-service"], retentionDays: 30,
  },
];

export function levelRank(level: DataLevel): number {
  return LEVEL_RANK[level];
}

export function maxLevel(levels: DataLevel[]): DataLevel {
  return levels.reduce<DataLevel>(
    (strongest, level) => (LEVEL_RANK[level] > LEVEL_RANK[strongest] ? level : strongest),
    "public",
  );
}

export function assetById(id: string): DataAsset | undefined {
  return ASSETS.find((asset) => asset.id === id);
}

export function resolveFields(
  assetId: string,
  fields: string[],
): { level: DataLevel; unknown: string[] } | undefined {
  const asset = assetById(assetId);
  if (!asset) {
    return undefined;
  }
  const known = new Map(asset.fields.map((field) => [field.name, field.level]));
  const unknown = fields.filter((name) => !known.has(name));
  const levels = fields
    .filter((name) => known.has(name))
    .map((name) => known.get(name) as DataLevel);
  return { level: maxLevel(levels), unknown };
}

export function channelAllowed(level: DataLevel, channel: Channel): boolean {
  return LEVEL_RANK[level] <= CHANNEL_CEILING[channel];
}

export function accessDecision(request: AccessRequest): AccessDecision {
  const asset = assetById(request.assetId);
  if (!asset) {
    return { allowed: false, level: "unknown", reasons: ["unknown-asset"] };
  }
  if (request.fields.length === 0) {
    return { allowed: false, level: "unknown", reasons: ["no-fields"] };
  }
  const resolved = resolveFields(request.assetId, request.fields);
  if (!resolved) {
    return { allowed: false, level: "unknown", reasons: ["unknown-asset"] };
  }
  if (resolved.unknown.length > 0) {
    return {
      allowed: false,
      level: "unknown",
      reasons: resolved.unknown.map((name) => `unknown-field:${name}`),
    };
  }
  const reasons: string[] = [];
  if (!asset.purposes.includes(request.purpose)) {
    reasons.push("purpose-not-declared");
  }
  if (!asset.channels.includes(request.channel)) {
    reasons.push("channel-not-declared");
  }
  if (!channelAllowed(resolved.level, request.channel)) {
    reasons.push(`channel-ceiling:${resolved.level}`);
  }
  return { allowed: reasons.length === 0, level: resolved.level, reasons };
}

export function auditAssets(assets: DataAsset[] = ASSETS): string[] {
  const issues: string[] = [];
  for (const asset of assets) {
    const level = maxLevel(asset.fields.map((field) => field.level));
    for (const channel of asset.channels) {
      if (!channelAllowed(level, channel)) {
        issues.push(`${asset.id}:channel-ceiling:${channel}`);
      }
    }
    const limit = RETENTION_LIMIT[level];
    if (limit !== undefined && asset.retentionDays === null) {
      issues.push(`${asset.id}:retention-missing`);
    }
    if (limit !== undefined && asset.retentionDays !== null && asset.retentionDays > limit) {
      issues.push(`${asset.id}:retention-too-long:${asset.retentionDays}`);
    }
  }
  return issues;
}

✔ 四个数据级别按由低到高排列 (0.916375ms)
✔ 最大级别在字段集合中胜出 (0.098292ms)
✔ 资产可以从 id 找回 (0.071291ms)
✔ 字段解析返回最大级别与未知字段 (0.100833ms)
✔ 字段级最小权限：只申请公开字段时级别为公开 (0.110791ms)
✔ 用途未声明时拒绝访问 (0.060125ms)
✔ 流向未声明时拒绝访问 (0.072541ms)
✔ 敏感字段流向第三方同时触发未声明与上限 (0.063917ms)
✔ 极敏感字段不允许导出 (0.065ms)
✔ 内部字段可以在声明过的第三方流向中使用 (0.103459ms)
✔ 极敏感字段在本机自有服务内允许使用 (0.06075ms)
✔ 未声明资产返回 unknown 级别 (0.056834ms)
✔ 空字段请求被拒绝而不是默认放行 (0.042667ms)
✔ 未知字段逐个列出后拒绝 (0.052583ms)
✔ 流向上限按级别判定 (0.052167ms)
✔ 默认资产清单通过分级审计 (0.086375ms)
✔ 审计能发现极敏感资产流向第三方 (0.053584ms)
✔ 审计能发现缺失与过长的保留期 (0.080875ms)
ℹ tests 18
ℹ suites 0
ℹ pass 18
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 130.146625