@hraness/ghostget 0.17.2

package/src/whatsapp-message-bundle-v2.ts

@@ -0,0 +1,195 @@
+import { types as nodeTypes } from "node:util";
+
+import {
+  LOCAL_MESSAGE_BUNDLE_V1_SCHEMA_VERSION,
+  parseLocalMessageBundleV1Record,
+  type LocalMessageBundleV1Record,
+} from "@hraness/message-like-me/message-bundle-v1";
+import {
+  LOCAL_MESSAGE_BUNDLE_V2_ARTIFACTS,
+  LOCAL_MESSAGE_BUNDLE_V2_FORMAT,
+  LOCAL_MESSAGE_BUNDLE_V2_LIMITS,
+  LOCAL_MESSAGE_BUNDLE_V2_NETWORK,
+  LOCAL_MESSAGE_BUNDLE_V2_PROVIDER_ID,
+  LOCAL_MESSAGE_BUNDLE_V2_PROVIDER_VERSION,
+  LOCAL_MESSAGE_BUNDLE_V2_SCHEMA_VERSION,
+  LOCAL_MESSAGE_BUNDLE_V2_SOURCE_ID,
+  LOCAL_MESSAGE_BUNDLE_V2_SOURCE_TRANSFORM_VERSION,
+  MessageBundleV2ContractError,
+  localMessageBundleV2BundleSha256,
+  localMessageBundleV2ManifestProjection,
+  parseLocalMessageBundleV2Manifest,
+  parseLocalMessageBundleV2Record,
+  type LocalMessageBundleV2AccountRecord,
+  type LocalMessageBundleV2Artifact,
+  type LocalMessageBundleV2AttachmentRecord,
+  type LocalMessageBundleV2ConversationRecord,
+  type LocalMessageBundleV2Manifest,
+  type LocalMessageBundleV2ManifestProjection,
+  type LocalMessageBundleV2MessageRecord,
+  type LocalMessageBundleV2ParticipantRecord,
+  type LocalMessageBundleV2Provenance,
+  type LocalMessageBundleV2ReactionRecord,
+  type LocalMessageBundleV2Record,
+  type LocalMessageBundleV2RecordKind,
+  type LocalMessageBundleV2TombstoneRecord,
+} from "@hraness/message-like-me/message-bundle-v2";
+
+import {
+  parseBeeperMessageLikeMeCompletion,
+  type BeeperMessageLikeMeCompletion,
+} from "./beeper-message-bundle-v1";
+
+export const WHATSAPP_MESSAGE_BUNDLE_V2_SCHEMA_VERSION =
+  LOCAL_MESSAGE_BUNDLE_V2_SCHEMA_VERSION;
+export const WHATSAPP_MESSAGE_BUNDLE_V2_FORMAT = LOCAL_MESSAGE_BUNDLE_V2_FORMAT;
+export const WHATSAPP_MESSAGE_BUNDLE_V2_SOURCE = Object.freeze({
+  id: LOCAL_MESSAGE_BUNDLE_V2_SOURCE_ID,
+  version: LOCAL_MESSAGE_BUNDLE_V2_SOURCE_TRANSFORM_VERSION,
+});
+export const WHATSAPP_MESSAGE_BUNDLE_V2_PROVIDER = Object.freeze({
+  id: LOCAL_MESSAGE_BUNDLE_V2_PROVIDER_ID,
+  version: LOCAL_MESSAGE_BUNDLE_V2_PROVIDER_VERSION,
+});
+export const WHATSAPP_MESSAGE_BUNDLE_V2_NETWORK = LOCAL_MESSAGE_BUNDLE_V2_NETWORK;
+export const WHATSAPP_MESSAGE_BUNDLE_V2_ARTIFACTS = LOCAL_MESSAGE_BUNDLE_V2_ARTIFACTS;
+export const WHATSAPP_MESSAGE_BUNDLE_V2_LIMITS = LOCAL_MESSAGE_BUNDLE_V2_LIMITS;
+
+export type WhatsAppMessageBundleV2Provenance = LocalMessageBundleV2Provenance;
+export type WhatsAppMessageBundleV2Attachment = LocalMessageBundleV2AttachmentRecord;
+export type WhatsAppMessageBundleV2Account = LocalMessageBundleV2AccountRecord;
+export type WhatsAppMessageBundleV2Participant = LocalMessageBundleV2ParticipantRecord;
+export type WhatsAppMessageBundleV2Conversation = LocalMessageBundleV2ConversationRecord;
+export type WhatsAppMessageBundleV2Message = LocalMessageBundleV2MessageRecord;
+export type WhatsAppMessageBundleV2Reaction = LocalMessageBundleV2ReactionRecord;
+export type WhatsAppMessageBundleV2Tombstone = LocalMessageBundleV2TombstoneRecord;
+export type WhatsAppMessageBundleV2Record = LocalMessageBundleV2Record;
+export type WhatsAppMessageBundleV2Artifact = LocalMessageBundleV2Artifact;
+export type WhatsAppMessageBundleV2ManifestProjection = LocalMessageBundleV2ManifestProjection;
+export type WhatsAppMessageBundleV2Manifest = LocalMessageBundleV2Manifest;
+
+export type WhatsAppMessageBundleV2Descriptor = Readonly<{
+  source: typeof WHATSAPP_MESSAGE_BUNDLE_V2_SOURCE;
+  provider: typeof WHATSAPP_MESSAGE_BUNDLE_V2_PROVIDER;
+}>;
+
+export type WhatsAppMessageBundleV2Completion = BeeperMessageLikeMeCompletion;
+
+type JsonRecord = Readonly<Record<string, unknown>>;
+
+function fail(message: string): never {
+  throw new MessageBundleV2ContractError(`WhatsApp Message Like Me v2 contract: ${message}`);
+}
+
+function plainRecord(value: unknown, label: string): JsonRecord {
+  if (
+    typeof value !== "object"
+    || value === null
+    || Array.isArray(value)
+    || nodeTypes.isProxy(value)
+    || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+  ) return fail(`${label} must be a plain object`);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    const descriptor = typeof key === "string" ? descriptors[key] : undefined;
+    if (
+      typeof key !== "string"
+      || descriptor === undefined
+      || descriptor.enumerable !== true
+      || !("value" in descriptor)
+    ) return fail(`${label} must contain only enumerable string data properties`);
+  }
+  return Object.freeze(Object.fromEntries(
+    Object.entries(descriptors).map(([key, descriptor]) => [key, descriptor.value]),
+  ));
+}
+
+function exactKeys(value: JsonRecord, expected: readonly string[], label: string): void {
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    fail(`${label} contains unsupported or missing fields`);
+  }
+}
+
+function recordKind(value: unknown, index: number): LocalMessageBundleV2RecordKind {
+  const label = `record[${String(index)}]`;
+  const record = plainRecord(value, label);
+  const kind = record.kind;
+  if (
+    kind !== "account"
+    && kind !== "participant"
+    && kind !== "conversation"
+    && kind !== "message"
+    && kind !== "reaction"
+    && kind !== "tombstone"
+  ) return fail(`${label}.kind is unsupported`);
+  return kind;
+}
+
+export function parseWhatsAppMessageBundleV2Record(
+  value: unknown,
+  index = 0,
+): WhatsAppMessageBundleV2Record {
+  if (!Number.isSafeInteger(index) || index < 0 || index >= WHATSAPP_MESSAGE_BUNDLE_V2_LIMITS.records) {
+    return fail("record index is outside the bundle bound");
+  }
+  const kind = recordKind(value, index);
+  return parseLocalMessageBundleV2Record(value, kind, `WhatsApp ${kind} record[${String(index)}]`);
+}
+
+export function toLocalMessageBundleV1Record(
+  value: WhatsAppMessageBundleV2Record,
+): LocalMessageBundleV1Record {
+  const parsed = parseWhatsAppMessageBundleV2Record(value);
+  return parseLocalMessageBundleV1Record(
+    Object.freeze({ ...parsed, schemaVersion: LOCAL_MESSAGE_BUNDLE_V1_SCHEMA_VERSION }),
+    parsed.kind,
+    "WhatsApp v1 compatibility record",
+  );
+}
+
+export function parseWhatsAppMessageBundleV2Descriptor(
+  value: unknown,
+): WhatsAppMessageBundleV2Descriptor {
+  const descriptor = plainRecord(value, "descriptor");
+  exactKeys(descriptor, ["source", "provider"], "descriptor");
+  const source = plainRecord(descriptor.source, "descriptor.source");
+  const provider = plainRecord(descriptor.provider, "descriptor.provider");
+  exactKeys(source, ["id", "version"], "descriptor.source");
+  exactKeys(provider, ["id", "version"], "descriptor.provider");
+  if (
+    source.id !== WHATSAPP_MESSAGE_BUNDLE_V2_SOURCE.id
+    || source.version !== WHATSAPP_MESSAGE_BUNDLE_V2_SOURCE.version
+    || provider.id !== WHATSAPP_MESSAGE_BUNDLE_V2_PROVIDER.id
+    || provider.version !== WHATSAPP_MESSAGE_BUNDLE_V2_PROVIDER.version
+  ) return fail("descriptor does not match the pinned direct WhatsApp producer");
+  return Object.freeze({
+    source: WHATSAPP_MESSAGE_BUNDLE_V2_SOURCE,
+    provider: WHATSAPP_MESSAGE_BUNDLE_V2_PROVIDER,
+  });
+}
+
+export function parseWhatsAppMessageBundleV2Completion(
+  value: unknown,
+): WhatsAppMessageBundleV2Completion {
+  return parseBeeperMessageLikeMeCompletion(value);
+}
+
+export function whatsAppMessageBundleV2Projection(
+  manifest: WhatsAppMessageBundleV2Manifest,
+): WhatsAppMessageBundleV2ManifestProjection {
+  return localMessageBundleV2ManifestProjection(manifest);
+}
+
+export function whatsAppMessageBundleV2BundleSha256(
+  projection: WhatsAppMessageBundleV2ManifestProjection,
+): string {
+  return localMessageBundleV2BundleSha256(projection);
+}
+
+export function parseWhatsAppMessageBundleV2Manifest(
+  value: unknown,
+): WhatsAppMessageBundleV2Manifest {
+  return parseLocalMessageBundleV2Manifest(value);
+}

package/src/whatsapp-message-like-me-cli.ts

@@ -0,0 +1,195 @@
+import { randomUUID } from "node:crypto";
+
+import type { GhostgetAuth } from "./auth";
+import { canonicalJson, sha256 } from "./canonical-json";
+import {
+  exportWhatsAppMessageLikeMeBundle,
+  type WhatsAppMessageLikeMeBundleProgress,
+  type WhatsAppMessageLikeMeExportResult,
+} from "./whatsapp-message-like-me-export";
+import {
+  createWhatsAppMessageLikeMeSource,
+  type WhatsAppMessageLikeMeProgress,
+  type WhatsAppMessageLikeMeSourceDependencies,
+} from "./whatsapp-message-like-me-source";
+import { containsWhatsAppContactProjectionCleanupUnverified } from "./providers/whatsapp-web-runtime";
+import {
+  WHATSAPP_MESSAGE_BUNDLE_V2_PROVIDER,
+  WHATSAPP_MESSAGE_BUNDLE_V2_SOURCE,
+} from "./whatsapp-message-bundle-v2";
+import {
+  acquireBeeperMessageLikeMeExportAdmission,
+  recoverBeeperMessageLikeMeDirectoryLeases,
+  releaseBeeperMessageLikeMeExportAdmission,
+} from "./beeper-message-like-me-recovery";
+
+export type WhatsAppMessageLikeMeCliProgress =
+  | WhatsAppMessageLikeMeProgress
+  | WhatsAppMessageLikeMeBundleProgress
+  | Readonly<{ phase: "recovery-started" }>
+  | Readonly<{
+      phase: "recovery-completed";
+      recovered: number;
+      published: number;
+    }>;
+
+export type WhatsAppMessageLikeMeCliRequest = Readonly<{
+  auth: GhostgetAuth;
+  outputRoot: string;
+  environment?: Readonly<Record<string, string | undefined>>;
+  signal?: AbortSignal;
+  onProgress?: (progress: WhatsAppMessageLikeMeCliProgress) => void;
+  /** Test-only source boundary seams. */
+  sourceDependencies?: WhatsAppMessageLikeMeSourceDependencies;
+}>;
+
+export type WhatsAppMessageLikeMeExportReceipt = Readonly<{
+  schemaVersion: 1;
+  format: "wrench.whatsapp-message-like-me-export-receipt";
+  runId: string;
+  operation: "whatsapp.export-message-like-me";
+  status: "succeeded";
+  transport: "linked-device-local-store";
+  startedAt: string;
+  finishedAt: string;
+  auth: Readonly<{
+    id: string;
+    provider: "whatsapp";
+    identitySha256: string;
+  }>;
+  source: typeof WHATSAPP_MESSAGE_BUNDLE_V2_SOURCE;
+  provider: typeof WHATSAPP_MESSAGE_BUNDLE_V2_PROVIDER;
+  completeness: WhatsAppMessageLikeMeExportResult["manifest"]["completeness"];
+  warnings: readonly string[];
+  counts: WhatsAppMessageLikeMeExportResult["manifest"]["counts"];
+  output: Readonly<{
+    schemaVersion: 2;
+    format: "message-like-me.local-message-bundle";
+    directory: string;
+    manifestSha256: string;
+  }>;
+  privacy: Readonly<{
+    classification: "private-local";
+    attachments: "metadata-only";
+    credentials: "excluded";
+    sourcePaths: "excluded";
+    mediaBytes: "excluded";
+    cloudSync: "none";
+  }>;
+  integrity: Readonly<{ algorithm: "sha256"; receiptSha256: string }>;
+}>;
+
+export type WhatsAppMessageLikeMeCliResult = Readonly<{
+  receipt: WhatsAppMessageLikeMeExportReceipt;
+  bundle: WhatsAppMessageLikeMeExportResult;
+}>;
+
+function fail(message: string): never {
+  throw new Error(`WhatsApp Message Like Me CLI: ${message}`);
+}
+
+export async function exportWhatsAppMessageLikeMeFromAuth(
+  request: WhatsAppMessageLikeMeCliRequest,
+): Promise<WhatsAppMessageLikeMeCliResult> {
+  if (
+    request.auth.kind !== "linked-device-store"
+    || request.auth.provider !== "whatsapp"
+    || request.auth.subject === undefined
+  ) return fail("a bound WhatsApp linked-device-store auth locator is required");
+  const environment = request.environment ?? process.env;
+  request.onProgress?.(Object.freeze({ phase: "recovery-started" }));
+  const admission = acquireBeeperMessageLikeMeExportAdmission({ environment });
+  let releaseAdmission = true;
+  let bundle: WhatsAppMessageLikeMeExportResult;
+  const startedAt = new Date().toISOString();
+  try {
+    const recovery = await recoverBeeperMessageLikeMeDirectoryLeases({ environment });
+    if (recovery.active > 0 || recovery.indeterminate > 0) {
+      return fail("another private message export is active or prior recovery is indeterminate");
+    }
+    request.onProgress?.(Object.freeze({
+      phase: "recovery-completed",
+      recovered: recovery.recovered,
+      published: recovery.published,
+    }));
+    bundle = await exportWhatsAppMessageLikeMeBundle({
+      outputRoot: request.outputRoot,
+      source: createWhatsAppMessageLikeMeSource({
+        auth: request.auth,
+        stateEnvironment: environment,
+        admission,
+        ...(request.signal === undefined ? {} : { signal: request.signal }),
+        ...(request.onProgress === undefined ? {} : { onProgress: request.onProgress }),
+        ...(request.sourceDependencies === undefined
+          ? {}
+          : { dependencies: request.sourceDependencies }),
+      }),
+      ...(request.signal === undefined ? {} : { signal: request.signal }),
+      ...(request.onProgress === undefined ? {} : { onProgress: request.onProgress }),
+      recoveryEnvironment: environment,
+    });
+  } catch (error) {
+    if (containsWhatsAppContactProjectionCleanupUnverified(error)) {
+      // The exact helper may still own the admitted private store. Keep the
+      // durable admission claim occupied so no later export can overlap an
+      // indeterminate process lifetime.
+      releaseAdmission = false;
+    }
+    throw error;
+  } finally {
+    if (releaseAdmission) releaseBeeperMessageLikeMeExportAdmission(admission);
+  }
+  const finishedAt = new Date().toISOString();
+  const projection = Object.freeze({
+    schemaVersion: 1 as const,
+    format: "wrench.whatsapp-message-like-me-export-receipt" as const,
+    runId: randomUUID(),
+    operation: "whatsapp.export-message-like-me" as const,
+    status: "succeeded" as const,
+    transport: "linked-device-local-store" as const,
+    startedAt,
+    finishedAt,
+    auth: Object.freeze({
+      id: request.auth.id,
+      provider: "whatsapp" as const,
+      identitySha256: sha256(canonicalJson({
+        id: request.auth.id,
+        provider: request.auth.provider,
+        subject: request.auth.subject,
+      })),
+    }),
+    source: WHATSAPP_MESSAGE_BUNDLE_V2_SOURCE,
+    provider: WHATSAPP_MESSAGE_BUNDLE_V2_PROVIDER,
+    completeness: bundle.manifest.completeness,
+    warnings: bundle.manifest.warnings,
+    counts: bundle.manifest.counts,
+    output: Object.freeze({
+      schemaVersion: 2 as const,
+      format: "message-like-me.local-message-bundle" as const,
+      directory: bundle.outputRoot,
+      manifestSha256: bundle.manifestSha256,
+    }),
+    privacy: Object.freeze({
+      classification: "private-local" as const,
+      attachments: "metadata-only" as const,
+      credentials: "excluded" as const,
+      sourcePaths: "excluded" as const,
+      mediaBytes: "excluded" as const,
+      cloudSync: "none" as const,
+    }),
+  });
+  const receipt: WhatsAppMessageLikeMeExportReceipt = Object.freeze({
+    ...projection,
+    integrity: Object.freeze({
+      algorithm: "sha256",
+      receiptSha256: sha256(canonicalJson(projection)),
+    }),
+  });
+  return Object.freeze({ receipt, bundle });
+}
+
+export function encodeWhatsAppMessageLikeMeCliResult(
+  value: WhatsAppMessageLikeMeCliResult,
+): string {
+  return `${canonicalJson(value.receipt)}\n`;
+}