@hraness/ghostget 0.17.6 → 0.18.2

package/src/messaging-automation-factory.ts

@@ -0,0 +1,148 @@
+import { randomUUID } from "node:crypto";
+import { canonicalJson, sha256 } from "./canonical-json";
+import type { GhostgetAuth } from "./auth";
+import { MessagingAutomationHost } from "./messaging-automation";
+import type { AutomationActionKind, AutomationProviderId, AutomationProviderStatus, MessagingAutomationProvider } from "./messaging-automation-types";
+import { AUTOMATION_ACTION_KINDS } from "./messaging-automation-validation";
+import { automationPermissionOperation, loadImsgAutomationRuntime, loadWhatsAppAutomationRuntime } from "./messaging-automation-descriptors";
+import { describeOperationPermission, type OperationPermissionDescription } from "./operation-permission";
+import { loadProviderPluginExtensionRuntime } from "./provider-plugin";
+import type { ProviderPluginRegistry } from "./provider-plugin-registry";
+import { acquireWebSessionCleanupAdmission, type WebSessionCleanupAdmissionController } from "./web-session-cleanup-admission";
+import type { ProviderPluginCleanupBarrierRegistrar } from "./provider-plugin-cleanup-execution";
+import { AutomationHostRecoveryRequired, type AutomationHostAccount, type AutomationHostSession } from "./messaging-automation-server";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+type Concrete = MessagingAutomationProvider & { start?(signal?: AbortSignal): Promise<void> };
+type Admission = Readonly<{ auth: GhostgetAuth; accountIdentity: string; implementationIdentity: string }>;
+export type MessagingAutomationSessionOptions = Readonly<{
+  providers: readonly AutomationHostAccount[];
+  environment: Environment;
+  registry: ProviderPluginRegistry;
+  resolveAsset(assetId: string, signal?: AbortSignal): Promise<Readonly<{ bytes: Uint8Array; sha256: string }>>;
+}>;
+
+/** Reads account metadata only when an explicit owner operation calls authorize.
+ * Creation never starts a network connection or reads a conversation. */
+export async function createMessagingAutomationSession(options: MessagingAutomationSessionOptions): Promise<AutomationHostSession> {
+  const providers: MessagingAutomationProvider[] = [];
+  const starts = new Map<AutomationProviderId, (signal?: AbortSignal) => Promise<AutomationProviderStatus>>();
+  try {
+    for (const selected of options.providers) {
+      const adapterId = selected.provider === "imessage" ? "imessage-direct" : "whatsapp-web";
+      let custody: WebSessionCleanupAdmissionController | undefined;
+      let custodyIdentity: string | undefined;
+      let poisoned = false, persistent = false, closed = false, started = false;
+      let watching: ReturnType<typeof setInterval> | undefined;
+      let closing: Promise<void> | undefined;
+      const describe = (operation: string, signal?: AbortSignal) => describeOperationPermission(adapterId, automationPermissionOperation(operation), selected.authId, { registry: options.registry, environment: options.environment, ...(signal ? { signal } : {}) });
+      const identity = (description: OperationPermissionDescription) => sha256(canonicalJson({
+        protocol: "ghostget.messaging-automation/1", provider: selected.provider,
+        pluginId: description.coordinate.pluginId, manifestHash: description.coordinate.manifestHash,
+        closureHash: description.coordinate.closureHash, portableHash: description.coordinate.portableHash,
+      }));
+      const authorize = async (operation: string, signal?: AbortSignal): Promise<Admission> => {
+        signal?.throwIfAborted();
+        if (poisoned) throw new AutomationHostRecoveryRequired("Host custody unavailable");
+        if (closed) throw new Error("Host closed");
+        const description = describe(operation, signal);
+        if (description.decision !== "allow") throw new Error("Explicit managed operation allow required");
+        const auth = description.auth as GhostgetAuth;
+        if (auth.kind !== "linked-device-store" || auth.provider !== selected.provider || auth.id !== selected.authId) throw new Error("Exact linked-device account required");
+        const implementationIdentity = identity(description);
+        const coordinate = sha256(canonicalJson({ auth, incarnation: description.coordinate.authIncarnation, implementationIdentity }));
+        if (custody && coordinate !== custodyIdentity) throw new Error("Account or implementation changed during host custody");
+        if (!custody) {
+          const plugin = description.resolution.plugin;
+          custody = acquireWebSessionCleanupAdmission({
+            runId: randomUUID(), pluginId: plugin.id, pluginVersion: plugin.version,
+            pluginImplementationHash: options.registry.implementationHash(description.resolution.binding).toString("hex"),
+            adapterId, adapterHash: description.coordinate.manifestHash, surfaceId: selected.provider,
+            authId: selected.authId, authHash: sha256(canonicalJson(auth)),
+            transport: selected.provider === "imessage" ? "local-cli" : "web-session-api",
+            executionIdentityHash: implementationIdentity,
+          }, options.environment);
+          custodyIdentity = coordinate;
+        }
+        return { auth, accountIdentity: description.coordinate.authIncarnation, implementationIdentity };
+      };
+      const registerCleanupBarrier: ProviderPluginCleanupBarrierRegistrar = barrier => {
+        if (!custody || poisoned || closed) throw new AutomationHostRecoveryRequired("Provider cleanup has no durable admission");
+        return custody.registerCleanupBarrier(barrier);
+      };
+      let finishing: Promise<void> | undefined;
+      const finishCustody = (): Promise<void> => {
+        if (finishing) return finishing;
+        finishing = (async () => {
+        if (!custody) return;
+        const owned = custody; owned.closeRegistration();
+        const settled = await Promise.allSettled(owned.barriers);
+        if (settled.some(item => item.status === "rejected")) {
+          poisoned = true; owned.cleanupUnsafe(); throw new AutomationHostRecoveryRequired("Provider cleanup remains uncertain");
+        }
+        owned.cleanupComplete(); owned.release(); custody = undefined; custodyIdentity = undefined;
+        })().finally(() => { finishing = undefined; });
+        return finishing;
+      };
+      const execution = { environment: options.environment, registerCleanupBarrier };
+      const binding = options.registry.requireOperationDefinition(selected.provider === "imessage" ? "local-cli" : "linked-device", selected.provider, "messaging.automation.read", 1).binding;
+      const concrete: Concrete = await loadProviderPluginExtensionRuntime(binding.loadRuntime, async () => selected.provider === "imessage"
+        ? (await loadImsgAutomationRuntime()).createImsgAutomationProvider({ authorize, execution, resolveAsset: options.resolveAsset })
+        : (await loadWhatsAppAutomationRuntime()).createWhatsAppAutomationProvider({ authorize, execution, resolveAsset: options.resolveAsset }));
+      const call = async <T>(work: () => Promise<T>): Promise<T> => {
+        if (poisoned) throw new AutomationHostRecoveryRequired("Host is fenced");
+        if (closed) throw new Error("Host closed");
+        try { return await work(); } finally { if (!persistent) await finishCustody(); }
+      };
+      const status = async (signal?: AbortSignal) => call(async () => {
+        const status = await concrete.inspect(signal);
+        const actions = Object.fromEntries(AUTOMATION_ACTION_KINDS.map((kind: AutomationActionKind) => {
+          let allowed = false;
+          try { const admission = describe(kind, signal); allowed = admission.decision === "allow" && identity(admission) === status.identity.implementationIdentity && admission.coordinate.authIncarnation === status.identity.accountIdentity; } catch { /* unsupported operation has no authority */ }
+          return [kind, allowed || !status.actions[kind].available ? status.actions[kind] : { available: false, reason: "Enable this exact account operation in Ghostget permissions before granting a contact access." }];
+        })) as AutomationProviderStatus["actions"];
+        return { ...status, actions };
+      });
+      const wrapped: MessagingAutomationProvider = {
+        provider: selected.provider, inspect: status,
+        conversations: (input, signal) => call(() => concrete.conversations(input, signal)),
+        resolve: (input, signal) => call(() => concrete.resolve(input, signal)),
+        history: (input, signal) => call(() => concrete.history(input, signal)),
+        events: (input, signal) => call(() => concrete.events(input, signal)),
+        send: (input, signal) => call(() => concrete.send(input, signal)),
+        close: () => {
+          if (closing) return closing;
+          if (watching) { clearInterval(watching); watching = undefined; }
+          closing = (async () => {
+            try { await concrete.close(); await finishCustody(); closed = true; }
+            catch { poisoned = true; custody?.closeRegistration(); custody?.cleanupUnsafe(); throw new AutomationHostRecoveryRequired("Provider cleanup requires recovery"); }
+          })();
+          return closing;
+        },
+      };
+      providers.push(wrapped);
+      starts.set(selected.provider, async signal => {
+        if (!concrete.start || selected.provider !== "whatsapp" || closed || poisoned) throw new Error("This provider has no start operation");
+        if (started) return status(signal);
+        persistent = true;
+        try {
+          // The sync ceiling is independent of send/read allows. Watch its
+          // exact decision while the linked-device process remains alive.
+          const ceiling = describe("start", signal);
+          if (ceiling.decision !== "allow") throw new Error("Explicit sync permission required");
+          await concrete.start(signal); started = true;
+          const check = () => {
+            let allowed = false;
+            try { const current = describe("start"); allowed = current.decision === "allow" && current.digest === ceiling.digest && current.coordinate.authIncarnation === ceiling.coordinate.authIncarnation; } catch { /* changed/missing auth or policy revokes active sync */ }
+            if (!allowed) void wrapped.close().catch(() => undefined);
+          };
+          watching = setInterval(check, 1_000); watching.unref(); check();
+          return await status(signal);
+        }
+        catch (error) { try { await wrapped.close(); } catch { throw new AutomationHostRecoveryRequired("Provider start cleanup requires recovery"); } throw error; }
+      });
+    }
+    const host = new MessagingAutomationHost(providers, options.environment);
+    return { host, start: (provider, signal) => { const start = starts.get(provider); if (!start) throw new Error("Provider not configured"); return start(signal); } };
+  } catch (error) { await Promise.allSettled(providers.map(provider => provider.close())); throw error; }
+}

package/src/messaging-automation-server.ts

@@ -0,0 +1,183 @@
+import { createHash, randomUUID } from "node:crypto";
+import { once } from "node:events";
+import type { Readable, Writable } from "node:stream";
+import { canonicalJson } from "./canonical-json";
+import { MessagingAutomationHost } from "./messaging-automation";
+import { MESSAGING_AUTOMATION_PROTOCOL as protocol, type AutomationGrantRequest, type AutomationProviderId, type AutomationProviderStatus } from "./messaging-automation-types";
+import { automationArray, automationDigest, automationId, automationInteger, automationRecord, automationText, parseAutomationAction } from "./messaging-automation-validation";
+import { createMessagingAutomationSession } from "./messaging-automation-factory";
+import type { ProviderPluginRegistry } from "./provider-plugin-registry";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+export type AutomationHostAccount = Readonly<{ provider: AutomationProviderId; authId: string }>;
+export type AutomationHostSession = Readonly<{ host: MessagingAutomationHost; start(provider: AutomationProviderId, signal?: AbortSignal): Promise<AutomationProviderStatus> }>;
+type Asset = { bytes: Uint8Array; sha256: string; expires: number; plan: string | null };
+const MAX_ASSET = 16 * 1024 * 1024;
+const MAX_FRAME = 24 * 1024 * 1024;
+const MAX_RESPONSE = 32 * 1024 * 1024;
+const provider = (value: unknown): AutomationProviderId => { if (value !== "imessage" && value !== "whatsapp") throw new Error("Invalid provider"); return value; };
+export class AutomationHostRecoveryRequired extends Error {}
+
+/** One trusted owner connection. No agent receives this port. */
+export class MessagingAutomationRpcServer {
+  private session: AutomationHostSession | undefined;
+  private initialized = false;
+  private initializing: Promise<AutomationHostSession> | undefined;
+  private closed = false;
+  private normalBusy = false;
+  private priorityBusy = 0;
+  private readonly requests = new Set<string>();
+  private readonly assets = new Map<string, Asset>();
+  private executingPlan: string | null = null;
+  private readonly abort = new AbortController();
+  private closing: Promise<void> | undefined;
+  constructor(private readonly options: Readonly<{
+    environment: Environment; registry: ProviderPluginRegistry;
+    now?: () => number;
+    createSession?: typeof createMessagingAutomationSession;
+  }>) {}
+  private now() { return this.options.now?.() ?? Date.now(); }
+  private sweep() { for (const [id, asset] of this.assets) if (asset.expires <= this.now() && asset.plan !== this.executingPlan) this.assets.delete(id); }
+  private host() { if (!this.session || this.closed) throw new Error("Host not ready"); return this.session.host; }
+  private async dispatch(method: string, raw: unknown): Promise<unknown> {
+    this.sweep();
+    if (method === "initialize") {
+      if (this.initialized || this.closed) throw new Error("Already initialized");
+      const r = automationRecord(raw, ["providers"]);
+      const accounts = automationArray(r.providers, 2).map(value => {
+        const item = automationRecord(value, ["provider", "authId"]); const authId = automationText(item.authId, 48);
+        if (!/^[a-z][a-z0-9-]{0,47}$/u.test(authId)) throw new Error("Invalid account identifier");
+        return { provider: provider(item.provider), authId };
+      });
+      if (accounts.length === 0 || new Set(accounts.map(item => item.provider)).size !== accounts.length) throw new Error("Distinct configured providers required");
+      this.initialized = true;
+      this.initializing = (this.options.createSession ?? createMessagingAutomationSession)({
+        providers: accounts, environment: this.options.environment, registry: this.options.registry,
+        resolveAsset: async id => {
+          this.sweep(); const asset = this.assets.get(id);
+          if (!asset || !this.executingPlan || asset.plan !== this.executingPlan || asset.expires <= this.now()) throw new Error("Asset is unavailable for this plan");
+          return { bytes: new Uint8Array(asset.bytes), sha256: asset.sha256 };
+        },
+      });
+      this.session = await this.initializing;
+      if (this.closed) throw new Error("Host closed during initialization");
+      return { initialized: true };
+    }
+    if (method === "close") { automationRecord(raw, []); await this.close(); return { closed: true }; }
+    const host = this.host();
+    if (method === "status" || method === "start") {
+      const r = automationRecord(raw, ["provider"]); const selected = provider(r.provider);
+      return method === "status" ? host.providerStatus(selected, this.abort.signal) : this.session!.start(selected, this.abort.signal);
+    }
+    if (method === "conversations") { const r = automationRecord(raw, ["provider", "limit"]); return host.conversations({ provider: provider(r.provider), limit: automationInteger(r.limit, 1, 200) }, this.abort.signal); }
+    if (method === "enroll") { const r = automationRecord(raw, ["provider", "coordinate"]); return host.enroll({ provider: provider(r.provider), coordinate: r.coordinate }, this.abort.signal); }
+    if (method === "enrollments") { automationRecord(raw, []); return host.enrollments(); }
+    if (method === "grant") {
+      const r = automationRecord(raw, ["intentId", "enrollmentId", "expectedBindingDigest", "actions", "expiresAt", "maximumActions", "minimumIntervalMs"]);
+      const { intentId, ...request } = r; return host.grant(request as AutomationGrantRequest, automationId(intentId));
+    }
+    if (method === "grant.by-intent") { const r = automationRecord(raw, ["intentId"]); return { grant: host.grantByIntent(automationId(r.intentId)) }; }
+    if (method === "grant.get") { const r = automationRecord(raw, ["grantId"]); return host.grantStatus(automationId(r.grantId)); }
+    if (method === "revoke") { const r = automationRecord(raw, ["grantId"]); host.revoke(automationId(r.grantId)); return { revoked: true }; }
+    if (method === "cancel") { const r = automationRecord(raw, ["planId"]); return { cancelled: host.cancel(automationId(r.planId)) }; }
+    if (method === "poll") { const r = automationRecord(raw, ["enrollmentId"]); return host.poll(automationId(r.enrollmentId), this.abort.signal); }
+    if (method === "history") { const r = automationRecord(raw, ["enrollmentId", "limit"]); return host.history({ enrollmentId: automationId(r.enrollmentId), limit: automationInteger(r.limit, 1, 200) }); }
+    if (method === "events") {
+      const r = automationRecord(raw, ["enrollmentIds", "cursor", "limit"]);
+      return host.events({ enrollmentIds: automationArray(r.enrollmentIds, 50).map(automationId), cursor: r.cursor === null ? null : automationText(r.cursor, 16_384), limit: automationInteger(r.limit, 1, 500) });
+    }
+    if (method === "asset") {
+      const r = automationRecord(raw, ["bytesBase64", "sha256"]); const digest = automationDigest(r.sha256);
+      if (typeof r.bytesBase64 !== "string" || r.bytesBase64.length > Math.ceil(MAX_ASSET / 3) * 4) throw new Error("Invalid asset length");
+      const bytes = Buffer.from(r.bytesBase64, "base64");
+      if (!bytes.length || bytes.length > MAX_ASSET || bytes.toString("base64") !== r.bytesBase64 || createHash("sha256").update(bytes).digest("hex") !== digest) throw new Error("Invalid asset");
+      if (this.assets.size >= 32 || [...this.assets.values()].reduce((sum, asset) => sum + asset.bytes.length, bytes.length) > 64 * 1024 * 1024) throw new Error("Asset capacity exceeded");
+      const assetId = `asset:${randomUUID()}`, expires = this.now() + 300_000;
+      this.assets.set(assetId, { bytes, sha256: digest, expires, plan: null });
+      return { assetId, bytes: bytes.length, sha256: digest, expiresAt: new Date(expires).toISOString() };
+    }
+    if (method === "prepare") {
+      const r = automationRecord(raw, ["enrollmentId", "expectedRevision", "intentId", "actions"]);
+      const actions = automationArray(r.actions, 8).map(parseAutomationAction);
+      const ids = new Set(actions.flatMap(action => action.kind === "attachment" || action.kind === "sticker" ? [action.assetId] : []));
+      for (const id of ids) { const asset = this.assets.get(id); if (!asset || asset.plan !== null) throw new Error("Missing or already-bound asset"); }
+      const plan = host.prepare({ enrollmentId: automationId(r.enrollmentId), expectedRevision: automationInteger(r.expectedRevision, 0, Number.MAX_SAFE_INTEGER), intentId: automationId(r.intentId), actions });
+      for (const id of ids) { const asset = this.assets.get(id)!; asset.plan = plan.id; asset.expires = Date.parse(plan.expiresAt); }
+      return plan;
+    }
+    if (method === "submit") {
+      const r = automationRecord(raw, ["planId", "grantId"]); const planId = automationId(r.planId); this.executingPlan = planId;
+      try { return await host.submit({ planId, grantId: automationId(r.grantId) }, this.abort.signal); }
+      finally { this.executingPlan = null; for (const [id, asset] of this.assets) if (asset.plan === planId) this.assets.delete(id); }
+    }
+    if (method === "run") { const r = automationRecord(raw, ["runId"]); return host.run(automationId(r.runId)); }
+    throw new Error("Unknown method");
+  }
+  async handle(value: unknown): Promise<unknown> {
+    let id = "invalid", priority = false, admitted = false;
+    try {
+      const r = automationRecord(value, ["protocol", "id", "method", "params"]);
+      id = automationText(r.id, 64); if (!/^[A-Za-z0-9._:-]+$/u.test(id) || r.protocol !== protocol) throw new Error("Invalid envelope");
+      const method = automationText(r.method, 32); priority = ["cancel", "revoke", "close"].includes(method);
+      if (this.requests.has(id) || (priority ? this.priorityBusy >= 8 : this.normalBusy)) return { protocol, id, ok: false, error: { code: "not-ready", message: "The owner host is busy or this request is already active." } };
+      this.requests.add(id); admitted = true;
+      if (priority) this.priorityBusy++; else this.normalBusy = true;
+      const result = await this.dispatch(method, r.params);
+      return { protocol, id, ok: true, result };
+    } catch (error) {
+      return { protocol, id, ok: false, error: { code: error instanceof AutomationHostRecoveryRequired ? "recovery-required" : this.closed ? "not-ready" : "unavailable", message: error instanceof AutomationHostRecoveryRequired ? "Provider cleanup requires explicit host recovery; this instance cannot continue." : "The requested operation is unavailable. Review account permissions, provider setup, scope and current state." } };
+    } finally { if (admitted) { this.requests.delete(id); if (priority) this.priorityBusy--; else this.normalBusy = false; } }
+  }
+  close(): Promise<void> {
+    this.closed = true; this.abort.abort(); this.assets.clear();
+    return this.closing ??= (async () => {
+      const session = this.session ?? await this.initializing?.catch(() => undefined);
+      if (session) { try { await session.host.close(); } catch { throw new AutomationHostRecoveryRequired("Host cleanup requires recovery"); } }
+    })();
+  }
+}
+
+export async function serveMessagingAutomationStdio(options: Readonly<{
+  input: Readable; output: Writable; environment: Environment; registry: ProviderPluginRegistry; signal?: AbortSignal;
+}>): Promise<void> {
+  const server = new MessagingAutomationRpcServer(options);
+  const pending = new Set<Promise<void>>(); let writing = Promise.resolve();
+  const write = (value: unknown) => writing = writing.then(async () => {
+    const frame = canonicalJson(value) + "\n";
+    if (Buffer.byteLength(frame) > MAX_RESPONSE) throw new Error("Owner response exceeds bound");
+    if (!options.output.write(frame)) {
+      const abort = new AbortController();
+      const timer = setTimeout(() => abort.abort(), 30_000);
+      try { await once(options.output, "drain", { signal: abort.signal }); }
+      finally { clearTimeout(timer); }
+    }
+  });
+  const stop = () => { options.input.destroy(); void server.close().catch(() => undefined); };
+  options.signal?.addEventListener("abort", stop, { once: true });
+  let buffer = Buffer.alloc(0); let failure: unknown;
+  try {
+    options.signal?.throwIfAborted();
+    for await (const chunk of options.input) {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array);
+      if (buffer.length + bytes.length > MAX_FRAME * 2) throw new Error("Owner frame exceeds bound");
+      buffer = Buffer.concat([buffer, bytes]);
+      for (;;) {
+        const newline = buffer.indexOf(10); if (newline < 0) break;
+        if (newline > MAX_FRAME || pending.size >= 10) throw new Error("Owner request capacity exceeded");
+        const line = buffer.subarray(0, newline); buffer = buffer.subarray(newline + 1);
+        const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+        let task: Promise<void>;
+        task = server.handle(value).then(write).catch(error => { failure ??= error; stop(); }).finally(() => pending.delete(task));
+        pending.add(task);
+      }
+      if (buffer.length > MAX_FRAME) throw new Error("Owner frame exceeds bound");
+    }
+    if (buffer.length) throw new Error("Owner request was truncated");
+  } catch (error) { failure ??= error; }
+  finally {
+    options.signal?.removeEventListener("abort", stop);
+    try { await server.close(); } catch (error) { failure ??= error; }
+    await Promise.allSettled(pending); await writing;
+  }
+  if (failure) throw failure;
+}

package/src/messaging-automation-types.ts

@@ -0,0 +1,155 @@
+/** Closed host-side messaging contract. Provider credentials and local paths never cross it. */
+export const MESSAGING_AUTOMATION_PROTOCOL = "ghostget.messaging-automation/1" as const;
+
+export type AutomationProviderId = "imessage" | "whatsapp";
+export type AutomationActionKind = AutomationAction["kind"];
+export type AutomationCoordinate =
+  | Readonly<{ provider: "imessage"; chatGuid: string; service: "iMessage"; observedChatRowId: number }>
+  | Readonly<{ provider: "whatsapp"; conversationJid: string }>;
+export type AutomationIdentity = Readonly<{
+  provider: AutomationProviderId;
+  authId: string;
+  /** Ghostget's public lifecycle authIdentity; detects replacement including A → B → A. */
+  accountIdentity: string;
+  accountSubject: string;
+  /** Exact reviewed provider implementation and contract closure digest. */
+  implementationIdentity: string;
+  /** Exact provider database/session generation; changes invalidate cursors and enrollment. */
+  sourceGeneration: string;
+}>;
+export type AutomationCapability = Readonly<{ available: boolean; reason: string | null }>;
+export type AutomationProviderStatus = Readonly<{
+  identity: AutomationIdentity;
+  connected: boolean;
+  events: AutomationCapability;
+  actions: Readonly<Record<AutomationActionKind, AutomationCapability>>;
+}>;
+export type AutomationConversation = Readonly<{
+  coordinate: AutomationCoordinate;
+  title: string | null;
+  kind: "single" | "group" | "unknown";
+  /** Exact current participant identities, never inferred from a display name. */
+  participants: readonly string[];
+}>;
+export type AutomationMessage = Readonly<{
+  id: string;
+  coordinate: AutomationCoordinate;
+  direction: "incoming" | "outgoing" | "unknown";
+  occurredAt: string;
+  text: string | null;
+  kind: "message" | "reaction" | "edit" | "delete";
+  relatedMessageId: string | null;
+  /** Metadata only; provider keys and paths stay inside Ghostget. */
+  attachments: readonly Readonly<{ name: string | null; mimeType: string | null; sizeBytes: number | null }>[];
+}>;
+export type AutomationAction =
+  | Readonly<{ kind: "text"; text: string }>
+  | Readonly<{ kind: "attachment"; assetId: string; name: string; mimeType: string }>
+  | Readonly<{ kind: "reaction"; messageId: string; emoji: string; remove: boolean }>
+  | Readonly<{ kind: "sticker"; assetId: string; messageId: string | null }>
+  | Readonly<{ kind: "link"; url: string }>
+  | Readonly<{ kind: "poll"; question: string; options: readonly string[]; maximumSelections: number | null }>
+  | Readonly<{ kind: "app-clip"; url: string }>
+  | Readonly<{ kind: "experience"; experienceId: string; parameters: Readonly<Record<string, string>> }>;
+export type AutomationProviderPage = Readonly<{
+  identity: AutomationIdentity;
+  messages: readonly AutomationMessage[];
+  nextCursor: string;
+  caughtUp: boolean;
+  /** A known/possible lost interval is explicit and prevents automatic dispatch. */
+  gap: boolean;
+}>;
+export type AutomationProviderSendResult =
+  | Readonly<{ state: "accepted"; messageId: string | null; providerReceiptId: string | null; delivery: "unknown" }>
+  | Readonly<{ state: "not-started"; reason: string }>
+  | Readonly<{ state: "indeterminate"; reason: string }>;
+
+/**
+ * Trusted Ghostget host port, never handed to an agent. Production implementations
+ * check existing operation permissions and exact identity before each operation.
+ * One send means one dispatch; implementations must never retry after uncertainty.
+ */
+export interface MessagingAutomationProvider {
+  readonly provider: AutomationProviderId;
+  inspect(signal?: AbortSignal): Promise<AutomationProviderStatus>;
+  conversations(input: Readonly<{ limit: number }>, signal?: AbortSignal): Promise<Readonly<{
+    identity: AutomationIdentity; conversations: readonly AutomationConversation[]; complete: boolean;
+  }>>;
+  resolve(coordinate: AutomationCoordinate, signal?: AbortSignal): Promise<Readonly<{
+    identity: AutomationIdentity; conversation: AutomationConversation;
+  }>>;
+  history(input: Readonly<{ coordinate: AutomationCoordinate; limit: number }>, signal?: AbortSignal): Promise<AutomationProviderPage>;
+  events(input: Readonly<{ coordinates: readonly AutomationCoordinate[]; cursor: string | null; limit: number }>, signal?: AbortSignal): Promise<AutomationProviderPage>;
+  send(input: Readonly<{
+    identity: AutomationIdentity;
+    coordinate: AutomationCoordinate;
+    action: AutomationAction;
+    /** Host's durable action claim, useful for provider idempotency only where proven. */
+    intentId: string;
+  }>, signal?: AbortSignal): Promise<AutomationProviderSendResult>;
+  /** Waits for owned provider children to terminate; uncertainty must reject. */
+  close(): Promise<void>;
+}
+
+export type AutomationEnrollment = Readonly<{
+  id: string; identity: AutomationIdentity; conversation: AutomationConversation;
+  bindingDigest: string; revision: number; ready: boolean; reason: string | null;
+}>;
+export type AutomationGrantRequest = Readonly<{
+  enrollmentId: string; expectedBindingDigest: string;
+  actions: readonly AutomationActionKind[];
+  expiresAt: string; maximumActions: number; minimumIntervalMs: number;
+}>;
+export type AutomationGrant = AutomationGrantRequest & Readonly<{ id: string; revoked: boolean; consumedActions: number }>;
+export type AutomationPlanRequest = Readonly<{
+  enrollmentId: string; expectedRevision: number; intentId: string; actions: readonly AutomationAction[];
+}>;
+export type AutomationPlan = AutomationPlanRequest & Readonly<{ id: string; digest: string; bindingDigest: string; expiresAt: string }>;
+export type AutomationRun = Readonly<{
+  id: string; planId: string; intentId: string; enrollmentId: string;
+  state: "started" | "accepted" | "failed" | "partial" | "indeterminate";
+  accepted: readonly Readonly<{ messageId: string | null; providerReceiptId: string | null }>[];
+  totalActions: number; reason: string | null; retryable: false;
+}>;
+export type AutomationEvent = Readonly<{ sequence: number; enrollmentId: string; revision: number; message: AutomationMessage }>;
+
+/** Public trusted-host surface. No registry, database or provider implementation
+ * types are part of this contract. Creating a host requires Bun. */
+export interface MessagingAutomationHostApi {
+  providerStatus(provider: AutomationProviderId, signal?: AbortSignal): Promise<AutomationProviderStatus>;
+  conversations(input: Readonly<{ provider: AutomationProviderId; limit: number }>, signal?: AbortSignal): Promise<Readonly<{
+    identity: AutomationIdentity; conversations: readonly AutomationConversation[]; complete: boolean;
+  }>>;
+  enroll(input: Readonly<{ provider: AutomationProviderId; coordinate: AutomationCoordinate }>, signal?: AbortSignal): Promise<AutomationEnrollment>;
+  enrollments(): readonly AutomationEnrollment[];
+  history(input: Readonly<{ enrollmentId: string; limit: number }>): Readonly<{ enrollment: AutomationEnrollment; messages: readonly AutomationMessage[] }>;
+  grant(request: AutomationGrantRequest, intentId?: string): AutomationGrant;
+  grantByIntent(intentId: string): AutomationGrant | null;
+  grantStatus(grantId: string): AutomationGrant;
+  revoke(grantId: string): void;
+  poll(enrollmentId: string, signal?: AbortSignal): Promise<AutomationEnrollment>;
+  events(input: Readonly<{ enrollmentIds: readonly string[]; cursor: string | null; limit: number }>): Readonly<{
+    events: readonly AutomationEvent[]; nextCursor: string; caughtUp: boolean;
+  }>;
+  prepare(request: AutomationPlanRequest): AutomationPlan;
+  submit(input: Readonly<{ planId: string; grantId: string }>, signal?: AbortSignal): Promise<AutomationRun>;
+  run(runId: string): AutomationRun;
+  cancel(planId: string): boolean;
+  /** Resolves only after all provider operations and owned children have joined. */
+  close(): Promise<void>;
+}
+
+export type MessagingRuntimeInstallation = Readonly<{ version: string; sha256: string; alreadyPresent?: boolean }>;
+
+/** Injected providers are trusted owner code and must enforce their permissions.
+ * Use the CLI stdio host for built-in account/registry-managed providers. */
+export declare function createMessagingAutomationHost(
+  providers: readonly MessagingAutomationProvider[],
+  environment?: Readonly<Record<string, string | undefined>>,
+): Promise<MessagingAutomationHostApi>;
+
+/** Installs exact bundled bytes; never pairs, starts sync or grants authority. */
+export declare function installBundledMessagingRuntime(
+  provider: AutomationProviderId,
+  environment?: Readonly<Record<string, string | undefined>>,
+): Promise<MessagingRuntimeInstallation>;

package/src/messaging-automation-validation.ts

@@ -0,0 +1,110 @@
+import { types } from "node:util";
+import type { AutomationAction, AutomationActionKind, AutomationCoordinate, AutomationIdentity, AutomationMessage } from "./messaging-automation-types";
+
+export const AUTOMATION_ACTION_KINDS = Object.freeze(["text", "attachment", "reaction", "sticker", "link", "poll", "app-clip", "experience"] as const);
+export function automationRecord(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (types.isProxy(value) || typeof value !== "object" || value === null || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new Error("Messaging automation value must be a plain object.");
+  const fields = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(fields).length !== keys.length || keys.some(key => !Object.hasOwn(fields, key))
+    || Reflect.ownKeys(fields).some(key => typeof key !== "string" || !keys.includes(key) || !fields[key]?.enumerable || !("value" in fields[key]!))) {
+    throw new Error("Messaging automation value has unsupported fields.");
+  }
+  return value as Record<string, unknown>;
+}
+export function automationText(value: unknown, maximum = 256, empty = false): string {
+  if (typeof value !== "string" || (!empty && value.length === 0) || Buffer.byteLength(value) > maximum || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value)
+    || Buffer.from(value, "utf8").toString("utf8") !== value) throw new Error("Messaging automation text is invalid or exceeds its bound.");
+  return value;
+}
+export function automationId(value: unknown): string {
+  const id = automationText(value, 256);
+  if (!/^[A-Za-z0-9._:-]+$/u.test(id)) throw new Error("Messaging automation identifier is invalid.");
+  return id;
+}
+export function automationDigest(value: unknown): string {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) throw new Error("Messaging automation digest is invalid.");
+  return value;
+}
+export function automationInteger(value: unknown, minimum: number, maximum: number): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new Error("Messaging automation integer is outside its bound.");
+  return value;
+}
+export function automationArray(value: unknown, maximum: number): readonly unknown[] {
+  if (types.isProxy(value) || !Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > maximum
+    || Reflect.ownKeys(value).length !== value.length + 1) throw new Error("Messaging automation list is invalid or exceeds its bound.");
+  for (let i = 0; i < value.length; i++) {
+    const field = Object.getOwnPropertyDescriptor(value, String(i));
+    if (field === undefined || !field.enumerable || !("value" in field)) throw new Error("Messaging automation list must be dense data.");
+  }
+  return value;
+}
+export function automationDate(value: unknown): string {
+  const text = automationText(value, 32);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(text) || !Number.isFinite(Date.parse(text)) || new Date(text).toISOString() !== text) throw new Error("Messaging automation time must be canonical UTC.");
+  return text;
+}
+export function parseAutomationCoordinate(value: unknown): AutomationCoordinate {
+  if (typeof value !== "object" || value === null || types.isProxy(value)) throw new Error("Messaging coordinate is invalid.");
+  const provider = Object.getOwnPropertyDescriptor(value, "provider")?.value;
+  if (provider === "imessage") {
+    const r = automationRecord(value, ["provider", "chatGuid", "service", "observedChatRowId"]);
+    const chatGuid = automationText(r.chatGuid, 1024);
+    if (!chatGuid.startsWith("iMessage;") || r.service !== "iMessage") throw new Error("Only exact iMessage conversations are supported.");
+    return Object.freeze({ provider, chatGuid, service: "iMessage", observedChatRowId: automationInteger(r.observedChatRowId, 1, Number.MAX_SAFE_INTEGER) });
+  }
+  const r = automationRecord(value, ["provider", "conversationJid"]);
+  if (provider !== "whatsapp" || typeof r.conversationJid !== "string" || !/^(?:[1-9][0-9]{4,14}@s\.whatsapp\.net|[1-9][0-9]{4,19}@lid)$/u.test(r.conversationJid)) throw new Error("Only exact individual WhatsApp conversations are supported.");
+  return Object.freeze({ provider, conversationJid: r.conversationJid });
+}
+export function parseAutomationIdentity(value: unknown): AutomationIdentity {
+  const r = automationRecord(value, ["provider", "authId", "accountIdentity", "accountSubject", "implementationIdentity", "sourceGeneration"]);
+  if (r.provider !== "imessage" && r.provider !== "whatsapp") throw new Error("Messaging provider is invalid.");
+  return Object.freeze({ provider: r.provider, authId: automationId(r.authId), accountIdentity: automationDigest(r.accountIdentity), accountSubject: automationText(r.accountSubject, 512), implementationIdentity: automationDigest(r.implementationIdentity), sourceGeneration: automationText(r.sourceGeneration, 256) });
+}
+export function parseAutomationActionKind(value: unknown): AutomationActionKind {
+  if (!AUTOMATION_ACTION_KINDS.includes(value as AutomationActionKind)) throw new Error("Messaging action is unsupported.");
+  return value as AutomationActionKind;
+}
+function https(value: unknown): string {
+  const url = automationText(value, 4096);
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" || parsed.username || parsed.password) throw new Error("Messaging links require credential-free HTTPS.");
+  return url;
+}
+export function parseAutomationAction(value: unknown): AutomationAction {
+  if (typeof value !== "object" || value === null || types.isProxy(value)) throw new Error("Messaging action is invalid.");
+  const kind = parseAutomationActionKind(Object.getOwnPropertyDescriptor(value, "kind")?.value);
+  if (kind === "text") { const r = automationRecord(value, ["kind", "text"]); return Object.freeze({ kind, text: automationText(r.text, 65536) }); }
+  if (kind === "link" || kind === "app-clip") { const r = automationRecord(value, ["kind", "url"]); return Object.freeze({ kind, url: https(r.url) }); }
+  if (kind === "attachment") {
+    const r = automationRecord(value, ["kind", "assetId", "name", "mimeType"]);
+    const name = automationText(r.name, 255); const mimeType = automationText(r.mimeType, 128);
+    if (/[\\/\r\n]/u.test(name) || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/u.test(mimeType)) throw new Error("Messaging attachment metadata is invalid.");
+    return Object.freeze({ kind, assetId: automationId(r.assetId), name, mimeType });
+  }
+  if (kind === "reaction") {
+    const r = automationRecord(value, ["kind", "messageId", "emoji", "remove"]); const emoji = automationText(r.emoji, 64, true);
+    if (typeof r.remove !== "boolean" || (!r.remove && (emoji.length === 0 || [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(emoji)].length !== 1))) throw new Error("Messaging reaction is invalid.");
+    return Object.freeze({ kind, messageId: automationId(r.messageId), emoji, remove: r.remove });
+  }
+  if (kind === "sticker") { const r = automationRecord(value, ["kind", "assetId", "messageId"]); return Object.freeze({ kind, assetId: automationId(r.assetId), messageId: r.messageId === null ? null : automationId(r.messageId) }); }
+  if (kind === "poll") {
+    const r = automationRecord(value, ["kind", "question", "options", "maximumSelections"]);
+    const options = automationArray(r.options, 12).map(option => automationText(option, 256));
+    if (options.length < 2 || new Set(options).size !== options.length) throw new Error("Messaging poll needs distinct options.");
+    return Object.freeze({ kind, question: automationText(r.question, 1024), options: Object.freeze(options), maximumSelections: r.maximumSelections === null ? null : automationInteger(r.maximumSelections, 1, options.length) });
+  }
+  const r = automationRecord(value, ["kind", "experienceId", "parameters"]);
+  if (typeof r.parameters !== "object" || r.parameters === null || types.isProxy(r.parameters)) throw new Error("Messaging experience parameters are invalid.");
+  const keys = Object.keys(r.parameters); if (keys.length > 16) throw new Error("Messaging experience parameters exceed their bound.");
+  const parameters = automationRecord(r.parameters, keys);
+  return Object.freeze({ kind, experienceId: automationId(r.experienceId), parameters: Object.freeze(Object.fromEntries(keys.map(key => [automationId(key), automationText(parameters[key], 4096, true)]))) });
+}
+export function parseAutomationMessage(value: unknown): AutomationMessage {
+  const r = automationRecord(value, ["id", "coordinate", "direction", "occurredAt", "text", "kind", "relatedMessageId", "attachments"]);
+  if (r.direction !== "incoming" && r.direction !== "outgoing" && r.direction !== "unknown") throw new Error("Messaging authorship is invalid.");
+  if (r.kind !== "message" && r.kind !== "reaction" && r.kind !== "edit" && r.kind !== "delete") throw new Error("Messaging event kind is invalid.");
+  const attachments = automationArray(r.attachments, 20).map(value => { const a = automationRecord(value, ["name", "mimeType", "sizeBytes"]); return Object.freeze({ name: a.name === null ? null : automationText(a.name, 512), mimeType: a.mimeType === null ? null : automationText(a.mimeType, 256), sizeBytes: a.sizeBytes === null ? null : automationInteger(a.sizeBytes, 0, 1024 * 1024 * 1024) }); });
+  return Object.freeze({ id: automationId(r.id), coordinate: parseAutomationCoordinate(r.coordinate), direction: r.direction, occurredAt: automationDate(r.occurredAt), text: r.text === null ? null : automationText(r.text, 65536, true), kind: r.kind, relatedMessageId: r.relatedMessageId === null ? null : automationId(r.relatedMessageId), attachments: Object.freeze(attachments) });
+}