《移动游戏产品的架构·商业化与发行工程》12.1 隐私政策、权限与数据采集清单

// file: src/biz/privacy-manifest.ts
// tier: L1
// verify: node --test test/biz/privacy-manifest.test.ts

export type DataCategory =
  | "device-id"
  | "account-id"
  | "payment"
  | "location"
  | "contacts"
  | "usage"
  | "advertising";

export type PermissionName =
  | "internet"
  | "network-state"
  | "storage"
  | "phone-state"
  | "location"
  | "contacts"
  | "notification"
  | "camera";

export type SdkPurpose = "login" | "payment" | "ads" | "analytics" | "push" | "share";

export interface SdkEntry {
  readonly name: string;
  readonly vendor: string;
  readonly purpose: SdkPurpose;
  readonly collects: readonly DataCategory[];
  readonly permissions: readonly PermissionName[];
  readonly policyUrl: string;
  readonly initBeforeConsent: boolean;
}

export interface PermissionJustification {
  readonly permission: PermissionName;
  readonly reason: string;
  readonly optional: boolean;
  readonly usedBy: readonly ("first-party" | "sdk")[];
}

export interface PrivacyManifest {
  readonly product: string;
  readonly policyVersion: string;
  readonly sdks: readonly SdkEntry[];
  readonly declaredPermissions: readonly PermissionJustification[];
  readonly policyCategories: readonly DataCategory[];
}

export type IssueCode =
  | "empty-sdk"
  | "missing-policy"
  | "undeclared-category"
  | "undeclared-permission"
  | "no-justification"
  | "unneeded-permission"
  | "init-before-consent";

export interface ManifestIssue {
  readonly code: IssueCode;
  readonly subject: string;
  readonly detail: string;
}

export interface ManifestReport {
  readonly product: string;
  readonly policyVersion: string;
  readonly sdkCount: number;
  readonly permissionCount: number;
  readonly optionalPermissionCount: number;
  readonly issues: readonly ManifestIssue[];
  readonly ok: boolean;
}

export interface ConsentPlan {
  readonly allowed: readonly string[];
  readonly blocked: readonly string[];
}

export interface ManifestBaseline {
  readonly product: string;
  readonly sdkCount: number;
  readonly permissionCount: number;
}

export const CASE_BASELINES: readonly ManifestBaseline[] = [
  { product: "潮汐消消", sdkCount: 14, permissionCount: 8 },
  { product: "潮汐方舟", sdkCount: 11, permissionCount: 10 },
];

export function auditManifest(manifest: PrivacyManifest): ManifestReport {
  const issues: ManifestIssue[] = [];
  const declared = new Set(manifest.declaredPermissions.map((item) => item.permission));
  const categories = new Set(manifest.policyCategories);

  for (const sdk of manifest.sdks) {
    if (sdk.name.trim() === "") {
      issues.push({ code: "empty-sdk", subject: sdk.vendor, detail: "SDK name is empty" });
    }
    if (!sdk.policyUrl.startsWith("https://")) {
      issues.push({
        code: "missing-policy",
        subject: sdk.name,
        detail: `policy url must be https, got ${sdk.policyUrl || "(empty)"}`,
      });
    }
    for (const category of sdk.collects) {
      if (!categories.has(category)) {
        issues.push({
          code: "undeclared-category",
          subject: sdk.name,
          detail: `collects ${category} but the privacy policy does not declare it`,
        });
      }
    }
    for (const permission of sdk.permissions) {
      if (!declared.has(permission)) {
        issues.push({
          code: "undeclared-permission",
          subject: sdk.name,
          detail: `requests ${permission} without a declared justification`,
        });
      }
    }
    if (sdk.initBeforeConsent) {
      issues.push({
        code: "init-before-consent",
        subject: sdk.name,
        detail: "SDK is initialized before the player grants consent",
      });
    }
  }

  for (const item of manifest.declaredPermissions) {
    if (item.reason.trim() === "") {
      issues.push({
        code: "no-justification",
        subject: item.permission,
        detail: "permission reason is empty",
      });
    }
    if (item.usedBy.length === 0) {
      issues.push({
        code: "unneeded-permission",
        subject: item.permission,
        detail: "permission is declared but unused",
      });
    }
  }

  return {
    product: manifest.product,
    policyVersion: manifest.policyVersion,
    sdkCount: manifest.sdks.length,
    permissionCount: manifest.declaredPermissions.length,
    optionalPermissionCount: manifest.declaredPermissions.filter((item) => item.optional).length,
    issues,
    ok: issues.length === 0,
  };
}

export function planSdkInit(manifest: PrivacyManifest, consentGranted: boolean): ConsentPlan {
  const allowed: string[] = [];
  const blocked: string[] = [];
  for (const sdk of manifest.sdks) {
    const needsConsent = sdk.purpose === "ads" || sdk.purpose === "analytics";
    if (needsConsent && !consentGranted) {
      blocked.push(sdk.name);
    } else {
      allowed.push(sdk.name);
    }
  }
  return { allowed, blocked };
}

export function compareWithBaseline(
  report: ManifestReport,
  baseline: ManifestBaseline,
): { matched: boolean; detail: string } {
  const drift: string[] = [];
  if (report.sdkCount !== baseline.sdkCount) {
    drift.push(`sdk ${report.sdkCount} != ${baseline.sdkCount}`);
  }
  if (report.permissionCount !== baseline.permissionCount) {
    drift.push(`permission ${report.permissionCount} != ${baseline.permissionCount}`);
  }
  if (drift.length === 0) {
    return { matched: true, detail: `${baseline.product} matches baseline` };
  }
  return { matched: false, detail: `${baseline.product} drift: ${drift.join("; ")}` };
}

export function formatManifestReport(report: ManifestReport): string {
  const codes = [...new Set(report.issues.map((issue) => issue.code))].join(",") || "none";
  const state = report.ok ? "ok" : "issues";
  return `${report.product} ${report.policyVersion} ${state} sdks=${report.sdkCount} permissions=${report.permissionCount} optional=${report.optionalPermissionCount} codes=${codes}`;
}