@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/lib/adapters/_python-sidecar-base.js

@@ -0,0 +1,207 @@
+/**
+ * PythonSidecarAdapter — shared infrastructure for adapters whose extraction
+ * + parsing happens in the forensics-bridge Python sidecar.
+ *
+ * Design rationale (see Personal_Data_Hub_Python_Sidecar.md §6.2):
+ *
+ *  - Subclasses define WHICH sidecar methods to invoke and HOW to orchestrate
+ *    them (per-data-source pull + parse). The shared base only handles
+ *    raw-event yielding + raw archival shape + supervisor wiring.
+ *  - `sync(opts)` is an async generator that yields {entityType, originalId,
+ *    capturedAt, payload} envelopes. `payload` is the already-normalized
+ *    UnifiedSchema entity emitted by the sidecar — `normalize()` then routes
+ *    it into the right NormalizedBatch bucket (events / persons / places / etc).
+ *  - Cancellation works through SidecarSupervisor's per-invoke timeout. The
+ *    registry's batchSize-driven iteration means partial progress is preserved
+ *    even if a later parse_* method times out mid-stream.
+ *
+ * Subclass contract:
+ *
+ *    class MyAdapter extends PythonSidecarAdapter {
+ *      name = "my-adapter";
+ *      version = "0.1.0";
+ *      capabilities = ["sync:sidecar"];
+ *      dataDisclosure = { ... };
+ *      async *_runSidecar(opts, emit) { ... use this._invoke(...) ... }
+ *    }
+ *
+ * The base exposes _invoke() which wraps SidecarSupervisor.invoke with
+ * onChunk routed into the adapter's yielded stream. Subclasses build up
+ * one or more invoke() calls inside `_runSidecar`.
+ */
+
+"use strict";
+
+class PythonSidecarAdapter {
+  /**
+   * @param {object} opts
+   * @param {import("../sidecar").SidecarSupervisor} opts.supervisor
+   * @param {string} [opts.name]    Override the class-level name if needed.
+   * @param {object} [opts.logger]  Optional logger; falls back to noop.
+   */
+  constructor(opts) {
+    if (!opts || !opts.supervisor) {
+      throw new Error("PythonSidecarAdapter: opts.supervisor required");
+    }
+    this.supervisor = opts.supervisor;
+    if (opts.name) this.name = opts.name;
+    this._logger = opts.logger || { info: () => {}, warn: () => {}, error: () => {} };
+  }
+
+  // -------------------------------------------------------------------------
+  // PersonalDataAdapter contract — required surface
+  // -------------------------------------------------------------------------
+
+  /**
+   * Override in subclasses.
+   * Default: no-op success (sidecar-backed adapters typically check device
+   * availability via subclass-specific sidecar methods).
+   */
+  async authenticate(_ctx) {
+    return { ok: true };
+  }
+
+  async healthCheck() {
+    try {
+      const pong = await this.supervisor.invoke("sidecar.ping", {}, { timeoutMs: 3000 });
+      return { ok: true, version: pong.version };
+    } catch (err) {
+      return { ok: false, reason: `sidecar.ping failed: ${err.code || err.message}` };
+    }
+  }
+
+  /**
+   * AdapterRegistry calls `normalize(raw)` once per raw event. Since the
+   * sidecar already returns UnifiedSchema entities, we just bucket the
+   * `raw.payload` (an entity dict) into the right NormalizedBatch slot
+   * based on its declared `entityType`.
+   *
+   * Yields a normalized batch with exactly one entity in one bucket.
+   */
+  normalize(raw) {
+    const empty = { events: [], persons: [], places: [], items: [], topics: [] };
+    if (!raw || typeof raw !== "object" || !raw.payload) return empty;
+    const t = raw.entityType;
+    const p = raw.payload;
+    if (t === "person") return { ...empty, persons: [p] };
+    if (t === "event") return { ...empty, events: [p] };
+    if (t === "place") return { ...empty, places: [p] };
+    if (t === "item") return { ...empty, items: [p] };
+    if (t === "topic") return { ...empty, topics: [p] };
+    // Defensive: unknown bucket → drop entity, registry counts as invalid.
+    return empty;
+  }
+
+  /**
+   * Subclasses MUST override `_runSidecar(opts, emit)`. `emit(raw)` is the
+   * generator-yielder; the base wires it up. Subclass returns the final
+   * orchestration result (used for adapter-progress audit, not for ingest).
+   */
+  async *sync(opts = {}) {
+    // Buffer between subclass producer and async-generator consumer.
+    // Using a small array + Promise resolution lets _runSidecar use callbacks
+    // while still yielding to the consumer one raw at a time.
+    const queue = [];
+    let done = false;
+    let runErr = null;
+    let resumeWaiter = null;
+
+    const emit = (raw) => {
+      queue.push(raw);
+      if (resumeWaiter) {
+        const r = resumeWaiter;
+        resumeWaiter = null;
+        r();
+      }
+    };
+
+    const runPromise = (async () => {
+      try {
+        await this._runSidecar(opts, emit);
+      } catch (err) {
+        runErr = err;
+      } finally {
+        done = true;
+        if (resumeWaiter) {
+          const r = resumeWaiter;
+          resumeWaiter = null;
+          r();
+        }
+      }
+    })();
+
+    try {
+      while (true) {
+        if (queue.length > 0) {
+          yield queue.shift();
+          continue;
+        }
+        if (done) break;
+        await new Promise((res) => {
+          resumeWaiter = res;
+        });
+      }
+      // Drain any items added after `done` flipped but before we noticed.
+      while (queue.length > 0) yield queue.shift();
+      if (runErr) throw runErr;
+    } finally {
+      // Make sure the producer task is awaited even if the consumer aborts.
+      try {
+        await runPromise;
+      } catch (_e) {
+        /* already captured in runErr */
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Subclass surface
+  // -------------------------------------------------------------------------
+
+  /**
+   * Override me. `emit(rawEvent)` queues a raw event for the consumer of
+   * the async generator returned by `sync()`. Subclasses typically:
+   *   1. Optionally call `this.supervisor.invoke("xxx.pull_file", ...)`.
+   *   2. Call `this.supervisor.invoke("xxx.parse_yyy", ..., { onChunk })`.
+   *   3. Inside onChunk, walk each entity → `emit({entityType, originalId,
+   *      capturedAt, payload})`.
+   *
+   * @param {object} _opts  options from registry.syncAdapter
+   * @param {(raw: object) => void} _emit  push a raw event to the stream
+   * @returns {Promise<object>} subclass-defined run summary
+   */
+  async _runSidecar(_opts, _emit) {
+    throw new Error(
+      `PythonSidecarAdapter[${this.name}]: subclass must implement _runSidecar(opts, emit)`,
+    );
+  }
+
+  /**
+   * Helper: walk a NormalizedBatch chunk and emit one raw per entity. Used
+   * by subclasses that want to forward all 5 buckets generically.
+   */
+  _emitChunkAsRaws(batch, emit) {
+    if (!batch || typeof batch !== "object") return;
+    const flush = (arr, entityType) => {
+      if (!Array.isArray(arr)) return;
+      for (const entity of arr) {
+        if (!entity || typeof entity !== "object") continue;
+        emit({
+          entityType,
+          originalId:
+            (entity.source && entity.source.originalId) || entity.id || null,
+          capturedAt:
+            (entity.source && entity.source.capturedAt) || Date.now(),
+          payload: entity,
+        });
+      }
+    };
+    flush(batch.persons, "person");
+    flush(batch.events, "event");
+    flush(batch.places, "place");
+    flush(batch.items, "item");
+    flush(batch.topics, "topic");
+  }
+}
+
+module.exports = { PythonSidecarAdapter };

package/lib/adapters/ai-chat-history/ai-chat-adapter.js

@@ -0,0 +1,374 @@
+/**
+ * AIChatHistoryAdapter — Phase 10 旗舰差异化 adapter.
+ *
+ * Fans out to 8 vendor sub-adapters (DeepSeek / Kimi / 通义 / 智谱 / 混元 /
+ * 千帆 / 扣子 / Dreamina) and re-emits their conversation + message stream as
+ * RawConversation / RawMessage envelopes. The AdapterRegistry will then call
+ * `normalize()` per envelope to fold them into the LocalVault.
+ *
+ * Phase 10.1 (this file): skeleton — adapter contract satisfied, schema-map
+ * fully implemented, vendor specs registered but their listConversations /
+ * listMessages throw VENDOR_NOT_WIRED. This is enough to:
+ *   1. register the adapter with AdapterRegistry without it failing assertAdapter
+ *   2. exercise normalize() with synthetic Raw* inputs in tests
+ *   3. exercise the per-vendor enable/disable flow in the hub UI
+ *   4. surface a precise "this vendor isn't wired yet" error to the user
+ *
+ * Phase 10.2+ replaces each vendor's listConversations / listMessages /
+ * validateCookie with real HTTP wiring against the documented endpoints in
+ * docs/design/Adapter_AIChat_History.md §6.
+ */
+
+"use strict";
+
+const { EVENT_SUBTYPES } = require("../../constants");
+
+const { SUPPORTED_VENDORS, assertVendorSpec, NotImplementedYetError } =
+  require("./vendor-spec");
+const { CookieAuthSession } = require("./cookie-auth");
+const { HttpClient, CookieExpiredError, RateLimitedError } = require("./http-client");
+const {
+  ADAPTER_NAME,
+  ADAPTER_VERSION,
+  conversationToBatch,
+  buildMessageEvent,
+  buildVendorPerson,
+  buildConversationTopic,
+  buildGeneratedImageItems,
+} = require("./schema-map");
+
+const { SPEC: deepseekSpec } = require("./vendors/deepseek");
+const { SPEC: kimiSpec } = require("./vendors/kimi");
+const { SPEC: tongyiSpec } = require("./vendors/tongyi");
+const { SPEC: zhipuSpec } = require("./vendors/zhipu");
+const { SPEC: hunyuanSpec } = require("./vendors/hunyuan");
+const { SPEC: qianfanSpec } = require("./vendors/qianfan");
+const { SPEC: cozeSpec } = require("./vendors/coze");
+const { SPEC: dreaminaSpec } = require("./vendors/dreamina");
+const { SPEC: doubaoSpec } = require("./vendors/doubao");
+
+const DEFAULT_VENDOR_SPECS = Object.freeze({
+  deepseek: deepseekSpec,
+  kimi: kimiSpec,
+  tongyi: tongyiSpec,
+  zhipu: zhipuSpec,
+  hunyuan: hunyuanSpec,
+  qianfan: qianfanSpec,
+  coze: cozeSpec,
+  dreamina: dreaminaSpec,
+  doubao: doubaoSpec,
+});
+
+class AIChatHistoryAdapter {
+  /**
+   * @param {object} [opts]
+   * @param {Record<string, CookieAuthSession>} [opts.sessions]
+   *        Per-vendor cookie session, keyed by vendor name. Vendors without
+   *        a session are skipped during sync (the hub flags them in the UI
+   *        as "needs login").
+   * @param {Record<string, object>} [opts.vendorSpecs]
+   *        Override one or more vendor specs (used by tests to inject fixtures).
+   * @param {function} [opts.fetch]
+   *        Fetch override forwarded to per-vendor HttpClient. Defaults to
+   *        global fetch (Node 22+). Tests inject a stub.
+   * @param {function} [opts.sleep]
+   *        Sleep override (test seam) for HttpClient rate-limit + backoff.
+   * @param {function} [opts.now]
+   *        Clock override (test seam) for HttpClient rate-limit.
+   * @param {object} [opts.logger]
+   */
+  constructor(opts = {}) {
+    this.name = ADAPTER_NAME;
+    this.version = ADAPTER_VERSION;
+    this.capabilities = [
+      "sync:cookie-multi-vendor",
+      "parse:ai-conversations",
+      "ingest:cross-vendor",
+    ];
+    this.extractMode = "web-api";
+    this.rateLimits = { perMinute: 60 }; // aggregate across vendors; per-vendor caps in spec
+    this.dataDisclosure = {
+      fields: [
+        "ai-chat:vendor,conversationId,messageId,role,text,modelName",
+        "ai-chat:attachments(url,filename,mimeType,size)",
+        "ai-chat:generatedImages(url,prompt,model,params)",
+        "ai-chat:toolCalls",
+      ],
+      sensitivity: "high",
+      legalGate: false,
+      notice:
+        "AI 对话史含您输入的所有问题与上传的附件。所有数据在本机加密存储；分析时本地 LLM 可读取；不向任何厂商回传。",
+    };
+
+    this._logger = opts.logger || { info: () => {}, warn: () => {}, error: () => {} };
+
+    // Vendor specs are registered upfront so that listVendors() / health
+    // checks work even before any cookie is configured.
+    const specs = { ...DEFAULT_VENDOR_SPECS, ...(opts.vendorSpecs || {}) };
+    for (const [vendor, spec] of Object.entries(specs)) {
+      const check = assertVendorSpec(spec);
+      if (!check.ok) {
+        throw new Error(
+          `AIChatHistoryAdapter: vendor "${vendor}" spec invalid: ${check.errors.join("; ")}`,
+        );
+      }
+    }
+    this._vendorSpecs = specs;
+    this._sessions = { ...(opts.sessions || {}) };
+    this._fetch = opts.fetch;
+    this._sleep = opts.sleep;
+    this._now = opts.now;
+    this._httpClients = new Map(); // vendor → HttpClient, lazy
+  }
+
+  _getHttpClient(vendor) {
+    let client = this._httpClients.get(vendor);
+    if (!client) {
+      const spec = this._vendorSpecs[vendor];
+      client = new HttpClient({
+        vendor,
+        rateLimits: spec.rateLimits,
+        fetch: this._fetch,
+        sleep: this._sleep,
+        now: this._now,
+        logger: this._logger,
+      });
+      this._httpClients.set(vendor, client);
+    }
+    return client;
+  }
+
+  // -------------------------------------------------------------------------
+  // PersonalDataAdapter contract
+  // -------------------------------------------------------------------------
+
+  /**
+   * Authentication is delegated per-vendor: the hub UI captures cookies via
+   * the Electron WebView and registers them with `setSession(vendor, session)`.
+   * `authenticate(ctx)` here only does a quick survey — returns { ok: true,
+   * vendorsReady: [...], vendorsNeedingLogin: [...] }.
+   */
+  async authenticate(_ctx = {}) {
+    const vendorsReady = [];
+    const vendorsNeedingLogin = [];
+    for (const vendor of Object.keys(this._vendorSpecs)) {
+      if (this._sessions[vendor]) {
+        vendorsReady.push(vendor);
+      } else {
+        vendorsNeedingLogin.push(vendor);
+      }
+    }
+    // Surface ok=true even when no vendor is configured yet — the UI manages
+    // the per-vendor onboarding state and `sync()` will simply yield zero
+    // events when no sessions are present.
+    return { ok: true, vendorsReady, vendorsNeedingLogin };
+  }
+
+  async healthCheck() {
+    // Per-vendor health is collected in parallel; the adapter as a whole is
+    // healthy iff at least one vendor has a valid cookie (or no vendors are
+    // yet onboarded — fresh-install state).
+    const perVendor = {};
+    for (const [vendor, spec] of Object.entries(this._vendorSpecs)) {
+      const sess = this._sessions[vendor];
+      if (!sess) {
+        perVendor[vendor] = { ok: false, reason: "no-session" };
+        continue;
+      }
+      try {
+        const httpClient = this._getHttpClient(vendor);
+        perVendor[vendor] = await spec.validateCookie({ session: sess, vendor, httpClient });
+      } catch (err) {
+        perVendor[vendor] = { ok: false, reason: err.code || err.message };
+      }
+    }
+    return { ok: true, perVendor };
+  }
+
+  /**
+   * Stream conversation + message envelopes across all configured vendors.
+   *
+   * Yields AdapterRegistry-compliant envelopes:
+   *   { originalId, capturedAt, payload: { kind, vendor, conversation|message } }
+   *
+   * The inner `payload.kind` distinguishes:
+   *   - "conversation"           → emit Topic + vendor Person (no Event yet)
+   *   - "message"                → emit Event + items + vendor Person
+   *   - "vendor-not-wired"       → no-op normalize (Phase 10.1 stub trace)
+   *   - "vendor-cookie-expired"  → no-op normalize (401/403 trace)
+   *   - "vendor-rate-limited"    → no-op normalize (429 trace after retries)
+   *
+   * The registry calls `normalize(raw)` per yielded envelope. One yield per
+   * conversation/message keeps registry batches small so a slow vendor
+   * doesn't block faster ones at the registry boundary.
+   *
+   * @param {object} [opts]
+   * @param {string[]} [opts.vendors]   restrict to a subset
+   * @param {object} [opts.watermarks]  per-vendor cursor / since IDs
+   */
+  async *sync(opts = {}) {
+    const targetVendors = opts.vendors
+      ? opts.vendors.filter((v) => this._vendorSpecs[v])
+      : Object.keys(this._vendorSpecs);
+
+    for (const vendor of targetVendors) {
+      const sess = this._sessions[vendor];
+      if (!sess) {
+        this._logger.info(`[ai-chat] skipping vendor=${vendor}: no session`);
+        continue;
+      }
+      const spec = this._vendorSpecs[vendor];
+      const httpClient = this._getHttpClient(vendor);
+      const ctx = { session: sess, vendor, httpClient };
+      const vendorWatermark = (opts.watermarks && opts.watermarks[vendor]) || null;
+
+      try {
+        for await (const conv of spec.listConversations(ctx, { since: vendorWatermark })) {
+          yield {
+            originalId: `${vendor}:conv:${conv.originalId}`,
+            capturedAt: Number(conv.updatedAt) || Number(conv.createdAt) || Date.now(),
+            payload: { kind: "conversation", vendor, conversation: conv },
+          };
+
+          for await (const msg of spec.listMessages(ctx, conv.originalId, {})) {
+            yield {
+              originalId: `${vendor}:msg:${msg.originalId}`,
+              capturedAt: Number(msg.createdAt) || Date.now(),
+              payload: { kind: "message", vendor, message: msg },
+            };
+          }
+        }
+      } catch (err) {
+        const traceCapturedAt = Date.now();
+        if (err instanceof NotImplementedYetError) {
+          this._logger.warn(
+            `[ai-chat] vendor=${vendor} not wired (Phase 10.2+ work): ${err.message}`,
+          );
+          yield {
+            originalId: `${vendor}:trace:not-wired:${traceCapturedAt}`,
+            capturedAt: traceCapturedAt,
+            payload: { kind: "vendor-not-wired", vendor, error: err.code },
+          };
+          continue;
+        }
+        if (err instanceof CookieExpiredError) {
+          this._logger.warn(`[ai-chat] vendor=${vendor} cookie expired: ${err.message}`);
+          yield {
+            originalId: `${vendor}:trace:cookie-expired:${traceCapturedAt}`,
+            capturedAt: traceCapturedAt,
+            payload: { kind: "vendor-cookie-expired", vendor, error: err.code },
+          };
+          continue;
+        }
+        if (err instanceof RateLimitedError) {
+          this._logger.warn(`[ai-chat] vendor=${vendor} rate limited: ${err.message}`);
+          yield {
+            originalId: `${vendor}:trace:rate-limited:${traceCapturedAt}`,
+            capturedAt: traceCapturedAt,
+            payload: {
+              kind: "vendor-rate-limited",
+              vendor,
+              error: err.code,
+              retryAfterMs: err.retryAfterMs,
+            },
+          };
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Convert one raw event into a NormalizedBatch.
+   *
+   * For "conversation" raws we emit only the conversation Topic + vendor
+   * Person (events are emitted lazily as their messages arrive). This lets
+   * the vault link Event.topics[] to a Topic that already exists.
+   */
+  normalize(raw) {
+    if (!raw || typeof raw !== "object") {
+      return { events: [], persons: [], places: [], items: [], topics: [] };
+    }
+    // Registry-compliant envelopes wrap kind inside payload. Adapter-internal
+    // tests (Phase 10.1) sometimes pass the inner shape directly — accept
+    // both for forward compat.
+    const inner = raw.payload && typeof raw.payload === "object" ? raw.payload : raw;
+    const kind = inner.kind;
+
+    if (kind === "vendor-not-wired" || kind === "vendor-cookie-expired" || kind === "vendor-rate-limited") {
+      // Nothing to write; the warning was already logged by sync().
+      return { events: [], persons: [], places: [], items: [], topics: [] };
+    }
+
+    if (kind === "conversation") {
+      const conv = inner.conversation;
+      const spec = this._vendorSpecs[conv.vendor];
+      const displayName = spec ? spec.displayName : conv.vendor;
+      return {
+        events: [],
+        persons: [buildVendorPerson(conv.vendor, displayName)],
+        places: [],
+        items: [],
+        topics: [buildConversationTopic(conv)],
+      };
+    }
+
+    if (kind === "message") {
+      const msg = inner.message;
+      const spec = this._vendorSpecs[msg.vendor];
+      const displayName = spec ? spec.displayName : msg.vendor;
+      return {
+        events: [buildMessageEvent(msg)],
+        persons: [buildVendorPerson(msg.vendor, displayName)],
+        places: [],
+        items: buildGeneratedImageItems(msg),
+        topics: [], // Topic was already emitted with the conversation event
+      };
+    }
+
+    return { events: [], persons: [], places: [], items: [], topics: [] };
+  }
+
+  // -------------------------------------------------------------------------
+  // Hub UI hooks (not part of PersonalDataAdapter contract)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Register a cookie session captured from the WebView for a given vendor.
+   */
+  setSession(vendor, session) {
+    if (!this._vendorSpecs[vendor]) {
+      throw new Error(`AIChatHistoryAdapter: unknown vendor "${vendor}"`);
+    }
+    if (!(session instanceof CookieAuthSession)) {
+      throw new Error("AIChatHistoryAdapter: session must be a CookieAuthSession");
+    }
+    this._sessions[vendor] = session;
+  }
+
+  clearSession(vendor) {
+    delete this._sessions[vendor];
+  }
+
+  listVendors() {
+    return Object.values(this._vendorSpecs).map((spec) => ({
+      name: spec.name,
+      displayName: spec.displayName,
+      androidPackage: spec.androidPackage,
+      loginUrl: spec.loginUrl,
+      hasSession: Boolean(this._sessions[spec.name]),
+    }));
+  }
+}
+
+module.exports = {
+  AIChatHistoryAdapter,
+  SUPPORTED_VENDORS,
+  DEFAULT_VENDOR_SPECS,
+  // re-export for convenience
+  ADAPTER_NAME,
+  ADAPTER_VERSION,
+  EVENT_SUBTYPE_AI_MESSAGE: EVENT_SUBTYPES.AI_MESSAGE,
+  EVENT_SUBTYPE_AI_IMAGE_GENERATION: EVENT_SUBTYPES.AI_IMAGE_GENERATION,
+};

package/lib/adapters/ai-chat-history/cookie-auth.js

@@ -0,0 +1,109 @@
+/**
+ * CookieAuthSession — minimal cookie jar + WebView-ingested cookie blob.
+ *
+ * Phase 10.1 skeleton: this is the place where the parent hub will hand a
+ * vendor adapter the cookie blob captured from Electron's webContents.session
+ * cookie store. Vendor sub-adapters call `applyTo(headers)` to inject cookies
+ * into an outbound fetch.
+ *
+ * The blob is the raw output of `session.cookies.get({ url })`, i.e. an array
+ * of `{ name, value, domain, path, secure, httpOnly, expirationDate? }`.
+ * We don't try to be a full RFC 6265 jar — for these vendors the page that
+ * issued the cookie and the page we POST back to are always same-origin, so
+ * a flat `name=value;` header is enough.
+ *
+ * Phase 10.2+ will replace this with `tough-cookie` if multi-domain expiry
+ * tracking turns out to be required (Coze uses two domains).
+ */
+
+"use strict";
+
+class CookieAuthSession {
+  /**
+   * @param {object} opts
+   * @param {string} opts.vendor                   matches a SUPPORTED_VENDORS entry
+   * @param {Array<{name:string,value:string,domain?:string,path?:string,expirationDate?:number}>} opts.cookies
+   * @param {number} [opts.capturedAt]             unix ms when cookies were captured
+   */
+  constructor(opts) {
+    if (!opts || typeof opts !== "object") {
+      throw new Error("CookieAuthSession: opts required");
+    }
+    if (typeof opts.vendor !== "string" || opts.vendor.length === 0) {
+      throw new Error("CookieAuthSession: opts.vendor required");
+    }
+    if (!Array.isArray(opts.cookies)) {
+      throw new Error("CookieAuthSession: opts.cookies must be an array");
+    }
+    this.vendor = opts.vendor;
+    this.cookies = opts.cookies.slice();
+    this.capturedAt = typeof opts.capturedAt === "number" ? opts.capturedAt : Date.now();
+  }
+
+  /**
+   * @returns {boolean} true if any cookie carries an explicit expiry that has passed.
+   */
+  isExpired(nowMs = Date.now()) {
+    if (this.cookies.length === 0) return true;
+    let sawExpiry = false;
+    for (const c of this.cookies) {
+      if (typeof c.expirationDate === "number") {
+        sawExpiry = true;
+        if (c.expirationDate * 1000 <= nowMs) return true;
+      }
+    }
+    return sawExpiry ? false : false; // session-only cookies — caller revalidates via validateCookie()
+  }
+
+  /**
+   * Returns a Cookie header value: "name1=value1; name2=value2; ...".
+   * Filters by optional domain match (suffix) — vendors with multi-domain
+   * cookies (coze) call applyTo per host.
+   */
+  toHeaderValue(matchDomain) {
+    const filtered = matchDomain
+      ? this.cookies.filter((c) => {
+          if (!c.domain) return true;
+          const d = c.domain.startsWith(".") ? c.domain.slice(1) : c.domain;
+          return matchDomain === d || matchDomain.endsWith("." + d);
+        })
+      : this.cookies;
+    return filtered.map((c) => `${c.name}=${c.value}`).join("; ");
+  }
+
+  /**
+   * Mutates `headers` in place: sets `Cookie` from `toHeaderValue(matchDomain)`.
+   */
+  applyTo(headers, matchDomain) {
+    headers.Cookie = this.toHeaderValue(matchDomain);
+    return headers;
+  }
+
+  /**
+   * Get a single cookie value by name. Returns undefined if not present.
+   * Used by vendors that need to compute auth tokens from cookie components
+   * (e.g. mtop-style sign from `_m_h5_tk`).
+   */
+  get(name) {
+    const c = this.cookies.find((c) => c.name === name);
+    return c ? c.value : undefined;
+  }
+
+  /**
+   * Serialize for vault persistence. Cookie values themselves still need to
+   * be encrypted at the vault layer — this method only flattens for storage.
+   */
+  toJSON() {
+    return {
+      vendor: this.vendor,
+      capturedAt: this.capturedAt,
+      cookies: this.cookies,
+    };
+  }
+
+  static fromJSON(json) {
+    return new CookieAuthSession(json);
+  }
+}
+
+module.exports = { CookieAuthSession };