Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

14.2 KB
Raw Blame
/** 深度校验来自设备链路或磁盘的同步状态,拒绝畸形/超量数据进入 SQLite。 */

import {
  DEFAULT_CONTACTS_CONFIG,
  MAX_NORMALIZED_IDENTITY_VALUE_LEN,
  isContactKind,
  isContactSource,
  isContactStatus,
} from "../types.js";
import {
  CONTACTS_SYNC_VERSION,
  membershipSyncId,
  type ContactsDataSnapshot,
  type ContactsStampedValue,
  type ContactsSyncConflictMembership,
  type ContactsSyncEntity,
  type ContactsSyncStamp,
  type ContactsSyncState,
} from "./types.js";

export const CONTACTS_SYNC_MAX_ROWS_PER_TABLE = 100_000;
const MAX_ID_LENGTH = 160;

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function isString(
  value: unknown,
  max: number,
  allowEmpty = true,
): value is string {
  return (
    typeof value === "string" &&
    value.length <= max &&
    (allowEmpty || value.length > 0)
  );
}

function isUtf8String(value: unknown, maxBytes: number): value is string {
  return (
    typeof value === "string" && Buffer.byteLength(value, "utf8") <= maxBytes
  );
}

/**
 * 这些 SQLite 文本列的本地写入契约没有长度上限;同步层只能校验类型,不能
 * 自行收紧合法域。传输层仍以整包解压上限约束来自设备的数据总量。
 */
function isUnboundedLocalText(value: unknown): value is string {
  return typeof value === "string";
}

function isId(value: unknown): value is string {
  return isString(value, MAX_ID_LENGTH, false) && !value.includes("\u0000");
}

function isStamp(value: unknown): value is ContactsSyncStamp {
  if (!isRecord(value)) return false;
  return (
    Number.isSafeInteger(value.counter) &&
    (value.counter as number) > 0 &&
    isString(value.nodeId, 128, false) &&
    /^[A-Za-z0-9._:-]+$/.test(value.nodeId as string)
  );
}

function isStamped<T>(
  value: unknown,
  validate: (candidate: unknown) => candidate is T,
): value is ContactsStampedValue<T> {
  return isRecord(value) && isStamp(value.stamp) && validate(value.value);
}

function isStringArray(value: unknown): value is string[] {
  return (
    Array.isArray(value) &&
    value.length <= DEFAULT_CONTACTS_CONFIG.maxAliases &&
    value.every((entry) =>
      isString(entry, DEFAULT_CONTACTS_CONFIG.maxDisplayNameLen, false),
    )
  );
}

function isEntityArray<T>(
  value: unknown,
  validate: (candidate: unknown) => candidate is T,
  validateId: (candidate: unknown) => candidate is string = isId,
): value is Array<ContactsSyncEntity<T>> {
  if (!Array.isArray(value) || value.length > CONTACTS_SYNC_MAX_ROWS_PER_TABLE)
    return false;
  const ids = new Set<string>();
  for (const candidate of value) {
    if (
      !isRecord(candidate) ||
      !validateId(candidate.id) ||
      ids.has(candidate.id)
    )
      return false;
    if (!isStamped(candidate.value, validate)) return false;
    if (candidate.deleted !== undefined && !isStamp(candidate.deleted))
      return false;
    ids.add(candidate.id);
  }
  return true;
}

function isContact(value: unknown): boolean {
  if (!isRecord(value) || !isId(value.id)) return false;
  if (!isStamped(value.kind, (v): v is "person" | "org" => isContactKind(v)))
    return false;
  if (
    !isStamped(value.displayName, (v): v is string =>
      isString(v, DEFAULT_CONTACTS_CONFIG.maxDisplayNameLen, false),
    )
  )
    return false;
  if (!isStamped(value.aliases, isStringArray)) return false;
  if (
    !isStamped(value.summary, (v): v is string =>
      isString(v, DEFAULT_CONTACTS_CONFIG.maxSummaryLen),
    )
  )
    return false;
  if (
    !isStamped(value.narrative, (v): v is string =>
      isUtf8String(v, DEFAULT_CONTACTS_CONFIG.maxNarrativeBytes),
    )
  )
    return false;
  if (
    !isStamped(value.agentNotes, (v): v is string =>
      isString(v, DEFAULT_CONTACTS_CONFIG.maxAgentNotesLen),
    )
  )
    return false;
  if (!isStatus(value.status)) return false;
  if (
    !isStamped(value.source, (v): v is "manual" | "agent" | "import" =>
      isContactSource(v),
    )
  )
    return false;
  if (!isStamped(value.createdAt, (v): v is string => isString(v, 64, false)))
    return false;
  if (!isStamped(value.updatedAt, (v): v is string => isString(v, 64, false)))
    return false;
  return value.deleted === undefined || isStamp(value.deleted);
}

function isConflictMembership(
  value: unknown,
): value is ContactsSyncConflictMembership {
  return (
    isRecord(value) &&
    isString(value.platform, 32, false) &&
    /^[a-z0-9_-]+$/.test(value.platform as string) &&
    isString(value.normalizedValue, MAX_NORMALIZED_IDENTITY_VALUE_LEN, false) &&
    isString(value.membershipHash, 64, false) &&
    /^[a-f0-9]{64}$/.test(value.membershipHash as string)
  );
}

function isStatus(value: unknown): boolean {
  if (
    !isStamped(value, (candidate): candidate is "confirmed" | "pending" =>
      isContactStatus(candidate),
    )
  ) {
    return false;
  }
  if (!isRecord(value) || value.acknowledgedConflicts === undefined)
    return true;
  if (
    !Array.isArray(value.acknowledgedConflicts) ||
    value.acknowledgedConflicts.length > CONTACTS_SYNC_MAX_ROWS_PER_TABLE
  ) {
    return false;
  }
  const keys = new Set<string>();
  for (const membership of value.acknowledgedConflicts) {
    if (!isConflictMembership(membership)) return false;
    const key = `${membership.platform}\u0000${membership.normalizedValue}`;
    if (keys.has(key)) return false;
    keys.add(key);
  }
  return true;
}

function isIdentity(value: unknown): value is {
  contactId: string;
  platform: string;
  value: string;
  normalizedValue: string;
  label: string;
  note: string;
  createdAt: string;
} {
  if (!isRecord(value) || !isId(value.contactId)) return false;
  return (
    isString(value.platform, 32, false) &&
    /^[a-z0-9_-]+$/.test(value.platform) &&
    isString(value.value, DEFAULT_CONTACTS_CONFIG.maxIdentityValueLen, false) &&
    isString(value.normalizedValue, MAX_NORMALIZED_IDENTITY_VALUE_LEN, false) &&
    isUnboundedLocalText(value.label) &&
    isUnboundedLocalText(value.note) &&
    isString(value.createdAt, 64, false)
  );
}

function isEvent(value: unknown): value is {
  contactId: string;
  date: string;
  text: string;
  source: string;
  createdAt: string;
} {
  if (!isRecord(value) || !isId(value.contactId)) return false;
  return (
    isString(value.date, 32, false) &&
    isString(value.text, DEFAULT_CONTACTS_CONFIG.maxEventTextLen, false) &&
    isUnboundedLocalText(value.source) &&
    isString(value.createdAt, 64, false)
  );
}

function isGroup(value: unknown): value is {
  name: string;
  description: string;
  createdAt: string;
} {
  return (
    isRecord(value) &&
    isString(value.name, DEFAULT_CONTACTS_CONFIG.maxGroupNameLen, false) &&
    isUnboundedLocalText(value.description) &&
    isString(value.createdAt, 64, false)
  );
}

function isMembership(
  value: unknown,
): value is { groupId: string; contactId: string } {
  return isRecord(value) && isId(value.groupId) && isId(value.contactId);
}

function isMembershipId(value: unknown): value is string {
  return (
    typeof value === "string" &&
    value.length > 2 &&
    value.length <= MAX_ID_LENGTH * 2 + 1
  );
}

function isRelation(value: unknown): value is {
  fromId: string;
  toId: string;
  relation: string;
  note: string;
  createdAt: string;
} {
  return (
    isRecord(value) &&
    isId(value.fromId) &&
    isId(value.toId) &&
    isString(value.relation, DEFAULT_CONTACTS_CONFIG.maxRelationLen, false) &&
    isUnboundedLocalText(value.note) &&
    isString(value.createdAt, 64, false)
  );
}

function isSnapshotContact(value: unknown): boolean {
  return (
    isRecord(value) &&
    isId(value.id) &&
    isContactKind(value.kind) &&
    isString(
      value.displayName,
      DEFAULT_CONTACTS_CONFIG.maxDisplayNameLen,
      false,
    ) &&
    isStringArray(value.aliases) &&
    isString(value.summary, DEFAULT_CONTACTS_CONFIG.maxSummaryLen) &&
    isUtf8String(value.narrative, DEFAULT_CONTACTS_CONFIG.maxNarrativeBytes) &&
    isString(value.agentNotes, DEFAULT_CONTACTS_CONFIG.maxAgentNotesLen) &&
    isContactStatus(value.status) &&
    isContactSource(value.source) &&
    isString(value.createdAt, 64, false) &&
    isString(value.updatedAt, 64, false)
  );
}

function isSnapshotArray(
  value: unknown,
  validate: (candidate: unknown) => boolean,
  validateId: (candidate: unknown) => candidate is string = isId,
): value is Array<Record<string, unknown> & { id: string }> {
  if (!Array.isArray(value) || value.length > CONTACTS_SYNC_MAX_ROWS_PER_TABLE)
    return false;
  const ids = new Set<string>();
  for (const candidate of value) {
    if (
      !isRecord(candidate) ||
      !validateId(candidate.id) ||
      ids.has(candidate.id) ||
      !validate(candidate)
    ) {
      return false;
    }
    ids.add(candidate.id);
  }
  return true;
}

/**
 * projection_json 会作为下一次本地差异捕获的可信基线;必须完整 fail-closed。
 * 只校验 id 会把损坏行误判成“本机删除”,进而向 CRDT 写入永久 tombstone。
 */
export function isValidContactsDataSnapshot(
  value: unknown,
): value is ContactsDataSnapshot {
  if (!isRecord(value)) return false;
  if (
    !isSnapshotArray(value.contacts, isSnapshotContact) ||
    !isSnapshotArray(
      value.identities,
      (candidate) => isRecord(candidate) && isIdentity(candidate),
    ) ||
    !isSnapshotArray(
      value.events,
      (candidate) => isRecord(candidate) && isEvent(candidate),
    ) ||
    !isSnapshotArray(
      value.groups,
      (candidate) => isRecord(candidate) && isGroup(candidate),
    ) ||
    !isSnapshotArray(
      value.memberships,
      (candidate) =>
        isRecord(candidate) &&
        isMembership(candidate) &&
        (candidate as unknown as { id: string }).id ===
          membershipSyncId(candidate.groupId, candidate.contactId),
      isMembershipId,
    ) ||
    !isSnapshotArray(
      value.relations,
      (candidate) => isRecord(candidate) && isRelation(candidate),
    )
  ) {
    return false;
  }

  const snapshot = value as unknown as ContactsDataSnapshot;
  const contactIds = new Set(snapshot.contacts.map((contact) => contact.id));
  const groupIds = new Set(snapshot.groups.map((group) => group.id));
  const uniqueGroups = new Set<string>();
  for (const group of snapshot.groups) {
    if (uniqueGroups.has(group.name)) return false;
    uniqueGroups.add(group.name);
  }

  const uniqueIdentities = new Set<string>();
  for (const identity of snapshot.identities) {
    if (!contactIds.has(identity.contactId)) return false;
    const key = `${identity.platform}\u0000${identity.normalizedValue}`;
    if (uniqueIdentities.has(key)) return false;
    uniqueIdentities.add(key);
  }
  if (snapshot.events.some((event) => !contactIds.has(event.contactId)))
    return false;
  if (
    snapshot.memberships.some(
      (membership) =>
        !contactIds.has(membership.contactId) ||
        !groupIds.has(membership.groupId),
    )
  ) {
    return false;
  }

  const uniqueRelations = new Set<string>();
  for (const relation of snapshot.relations) {
    if (
      relation.fromId === relation.toId ||
      !contactIds.has(relation.fromId) ||
      !contactIds.has(relation.toId)
    ) {
      return false;
    }
    const key = `${relation.fromId}\u0000${relation.toId}\u0000${relation.relation}`;
    if (uniqueRelations.has(key)) return false;
    uniqueRelations.add(key);
  }
  return true;
}

export function isValidContactsSyncState(
  value: unknown,
): value is ContactsSyncState {
  if (!isRecord(value) || value.version !== CONTACTS_SYNC_VERSION) return false;
  if (!Array.isArray(value.clocks) || value.clocks.length > 256) return false;
  const clockNodes = new Set<string>();
  for (const clock of value.clocks) {
    if (
      !isRecord(clock) ||
      !isStamp({ counter: clock.counter, nodeId: clock.nodeId })
    )
      return false;
    if (clockNodes.has(clock.nodeId as string)) return false;
    clockNodes.add(clock.nodeId as string);
  }
  if (
    !Array.isArray(value.contacts) ||
    value.contacts.length > CONTACTS_SYNC_MAX_ROWS_PER_TABLE
  )
    return false;
  const contactIds = new Set<string>();
  let acknowledgedConflictCount = 0;
  for (const contact of value.contacts) {
    if (!isContact(contact) || contactIds.has((contact as { id: string }).id))
      return false;
    acknowledgedConflictCount +=
      (contact as { status: { acknowledgedConflicts?: unknown[] } }).status
        .acknowledgedConflicts?.length ?? 0;
    if (acknowledgedConflictCount > CONTACTS_SYNC_MAX_ROWS_PER_TABLE)
      return false;
    contactIds.add((contact as { id: string }).id);
  }
  if (!isEntityArray(value.identities, isIdentity)) return false;
  if (!isEntityArray(value.events, isEvent)) return false;
  if (!isEntityArray(value.groups, isGroup)) return false;
  if (!isEntityArray(value.memberships, isMembership, isMembershipId))
    return false;
  for (const membership of value.memberships) {
    const entry = membership as ContactsSyncEntity<{
      groupId: string;
      contactId: string;
    }>;
    if (
      entry.id !==
      membershipSyncId(entry.value.value.groupId, entry.value.value.contactId)
    )
      return false;
  }
  if (!isEntityArray(value.relations, isRelation)) return false;
  return clocksCoverEveryStamp(value as unknown as ContactsSyncState);
}

function clocksCoverEveryStamp(state: ContactsSyncState): boolean {
  const clocks = new Map(
    state.clocks.map((clock) => [clock.nodeId, clock.counter]),
  );
  const covered = (stamp: ContactsSyncStamp | undefined): boolean =>
    !stamp || (clocks.get(stamp.nodeId) ?? 0) >= stamp.counter;
  for (const contact of state.contacts) {
    if (
      !covered(contact.kind.stamp) ||
      !covered(contact.displayName.stamp) ||
      !covered(contact.aliases.stamp) ||
      !covered(contact.summary.stamp) ||
      !covered(contact.narrative.stamp) ||
      !covered(contact.agentNotes.stamp) ||
      !covered(contact.status.stamp) ||
      !covered(contact.source.stamp) ||
      !covered(contact.createdAt.stamp) ||
      !covered(contact.updatedAt.stamp) ||
      !covered(contact.deleted)
    ) {
      return false;
    }
  }
  for (const records of [
    state.identities,
    state.events,
    state.groups,
    state.memberships,
    state.relations,
  ]) {
    for (const record of records) {
      if (!covered(record.value.stamp) || !covered(record.deleted)) {
        return false;
      }
    }
  }
  return true;
}