@botcord/daemon 0.2.36 → 0.2.38

package/src/gateway/channels/login-session.ts

@@ -0,0 +1,135 @@
+/**
+ * In-memory login-session store used by the daemon's third-party gateway
+ * control frames. Today only WeChat consumes it (qrcode → bot token), but
+ * the shape is provider-generic so future LINE/Discord OAuth callbacks can
+ * reuse the same store without a control-frame churn.
+ *
+ * The store is intentionally NOT persisted — bot tokens never live anywhere
+ * outside the daemon process or the per-gateway secret file. A daemon
+ * restart drops in-flight logins; the user just rescans.
+ */
+
+import { randomBytes } from "node:crypto";
+
+export type LoginProvider = "wechat" | "telegram";
+
+export interface LoginSession {
+  loginId: string;
+  accountId: string;
+  gatewayId?: string;
+  provider: LoginProvider;
+  /** WeChat: opaque qrcode string returned by `get_bot_qrcode`. */
+  qrcode?: string;
+  /** Optional renderable URL for the qrcode. */
+  qrcodeUrl?: string;
+  /** WeChat iLink base URL the bot token will be used against. */
+  baseUrl?: string;
+  /** Stored only after the user confirms the qrcode. Never returned to Hub. */
+  botToken?: string;
+  /** Masked preview safe for Hub/dashboard display. */
+  tokenPreview?: string;
+  /** Unix millis. */
+  expiresAt: number;
+}
+
+/** Default session TTL: 5 minutes per the design doc. */
+export const LOGIN_SESSION_TTL_MS = 5 * 60 * 1000;
+
+export interface LoginSessionStoreOptions {
+  /** Override the wall clock — used by tests. */
+  now?: () => number;
+  /** Override the TTL applied at `create` time. */
+  ttlMs?: number;
+}
+
+/**
+ * Lazy-evicting login session map. Eviction runs inline on every read/write
+ * so no background timer is required and tests can scrub state by advancing
+ * a fake clock.
+ */
+export class LoginSessionStore {
+  private readonly sessions = new Map<string, LoginSession>();
+  private readonly now: () => number;
+  private readonly ttlMs: number;
+
+  constructor(opts: LoginSessionStoreOptions = {}) {
+    this.now = opts.now ?? (() => Date.now());
+    this.ttlMs = opts.ttlMs ?? LOGIN_SESSION_TTL_MS;
+  }
+
+  /**
+   * Insert a fresh session. `expiresAt` is computed as `now() + ttlMs`
+   * unless the caller pre-populated it. Returns the persisted record.
+   */
+  create(input: Omit<LoginSession, "expiresAt"> & { expiresAt?: number }): LoginSession {
+    this.sweep();
+    const expiresAt = typeof input.expiresAt === "number" ? input.expiresAt : this.now() + this.ttlMs;
+    const session: LoginSession = { ...input, expiresAt };
+    this.sessions.set(session.loginId, session);
+    return session;
+  }
+
+  /** Get a non-expired session by id, or `null` when missing/expired. */
+  get(loginId: string): LoginSession | null {
+    this.sweep();
+    return this.sessions.get(loginId) ?? null;
+  }
+
+  /**
+   * Apply a partial patch to the session in place. No-op when the session
+   * is missing or expired. Returns the updated record (or `null`).
+   */
+  update(loginId: string, patch: Partial<LoginSession>): LoginSession | null {
+    const cur = this.get(loginId);
+    if (!cur) return null;
+    const next = { ...cur, ...patch };
+    this.sessions.set(loginId, next);
+    return next;
+  }
+
+  delete(loginId: string): boolean {
+    return this.sessions.delete(loginId);
+  }
+
+  /** Drop every entry whose `expiresAt` is in the past. */
+  sweep(): void {
+    const t = this.now();
+    for (const [id, s] of this.sessions) {
+      if (s.expiresAt <= t) this.sessions.delete(id);
+    }
+  }
+
+  /** Test helper: number of live sessions after sweep. */
+  size(): number {
+    this.sweep();
+    return this.sessions.size;
+  }
+}
+
+/**
+ * Build a masked preview suitable for dashboard display. Returns the raw
+ * value untouched when shorter than 8 chars (no point masking) or `""` when
+ * empty. Default format: `"abcd...wxyz"` with a single ellipsis, never
+ * leaking the middle of the secret.
+ */
+export function maskTokenPreview(token: string | undefined | null): string {
+  if (!token) return "";
+  if (token.length <= 8) return token;
+  return `${token.slice(0, 4)}...${token.slice(-4)}`;
+}
+
+/**
+ * Allocate a new login id. Format `wxl_<base36ts>_<rand>` so it sorts by
+ * creation time and is trivially distinguishable from BotCord agent ids.
+ *
+ * W8: the random tail uses `crypto.randomBytes` (cryptographically secure)
+ * instead of `Math.random()` so an attacker cannot predict in-flight login
+ * ids and racefully claim someone else's session.
+ */
+export function mintLoginId(provider: LoginProvider): string {
+  const prefix = provider === "wechat" ? "wxl" : "tgl";
+  const ts = Date.now().toString(36);
+  // 32 hex chars = 128 bits of entropy — W5 regression fix from round 2.
+  const rand = randomBytes(16).toString("hex");
+  return `${prefix}_${ts}_${rand}`;
+}

package/src/gateway/channels/secret-store.ts

@@ -0,0 +1,100 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+// W3: logger for corrupt-file warnings. Using console so no circular dep on log.ts.
+const _warn = (msg: string) => console.warn(`[secret-store] ${msg}`);
+
+const DEFAULT_GATEWAYS_DIR = path.join(
+  homedir(),
+  ".botcord",
+  "daemon",
+  "gateways",
+);
+
+/**
+ * Resolve the on-disk secret-file path for a third-party gateway. Honors an
+ * explicit override when provided; otherwise falls back to
+ * `~/.botcord/daemon/gateways/{id}.json` (mode 0600 inside a 0700 dir).
+ */
+export function defaultGatewaySecretPath(
+  gatewayId: string,
+  override?: string,
+): string {
+  if (override && override.length > 0) return override;
+  return path.join(DEFAULT_GATEWAYS_DIR, `${gatewayId}.json`);
+}
+
+/**
+ * Load a previously-written secret blob. Returns `null` when the file is
+ * absent — callers treat that as "not yet authorized" rather than an error.
+ */
+export function loadGatewaySecret<T = Record<string, unknown>>(
+  gatewayId: string,
+  override?: string,
+): T | null {
+  const file = defaultGatewaySecretPath(gatewayId, override);
+  if (!existsSync(file)) return null;
+  const raw = readFileSync(file, "utf8");
+  // W3: guard against corrupt files — JSON.parse throws on malformed input.
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    _warn(`corrupt secret file at ${file} — ignoring`);
+    return null;
+  }
+}
+
+/**
+ * Persist a secret blob with mode `0600`, ensuring the parent directory
+ * exists with mode `0700`. Writes go through a `.tmp` rename for atomicity.
+ *
+ * The parent directory mode is re-applied on every write so a permission
+ * drift (e.g. operator chmod) is corrected the next time the daemon writes.
+ */
+export function saveGatewaySecret(
+  gatewayId: string,
+  secret: Record<string, unknown>,
+  override?: string,
+): string {
+  const file = defaultGatewaySecretPath(gatewayId, override);
+  const dir = path.dirname(file);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+    // best-effort
+  }
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify(secret, null, 2), { mode: 0o600 });
+  try {
+    chmodSync(tmp, 0o600);
+  } catch {
+    // best-effort
+  }
+  renameSync(tmp, file);
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    // best-effort
+  }
+  return file;
+}
+
+/** Remove a previously-saved secret. No-op when the file is missing. */
+export function deleteGatewaySecret(
+  gatewayId: string,
+  override?: string,
+): void {
+  const file = defaultGatewaySecretPath(gatewayId, override);
+  if (!existsSync(file)) return;
+  unlinkSync(file);
+}

package/src/gateway/channels/state-store.ts

@@ -0,0 +1,213 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+const DEFAULT_GATEWAYS_DIR = path.join(
+  homedir(),
+  ".botcord",
+  "daemon",
+  "gateways",
+);
+
+const DEFAULT_DEBOUNCE_MS = 1000;
+
+/**
+ * On-disk cursor + provider-state for one third-party gateway. Kept separate
+ * from `secret-store` so high-frequency cursor advancements don't churn the
+ * secret file (and so cursor doesn't end up in any secret backup).
+ */
+export interface ThirdPartyGatewayState {
+  cursor?: string;
+  providerState?: Record<string, unknown>;
+  updatedAt: string;
+}
+
+export function defaultGatewayStatePath(
+  gatewayId: string,
+  override?: string,
+): string {
+  if (override && override.length > 0) return override;
+  return path.join(DEFAULT_GATEWAYS_DIR, `${gatewayId}.state.json`);
+}
+
+function readState(file: string): ThirdPartyGatewayState {
+  if (!existsSync(file)) return { updatedAt: new Date(0).toISOString() };
+  try {
+    return JSON.parse(readFileSync(file, "utf8")) as ThirdPartyGatewayState;
+  } catch {
+    return { updatedAt: new Date(0).toISOString() };
+  }
+}
+
+function writeStateSync(file: string, state: ThirdPartyGatewayState): void {
+  const dir = path.dirname(file);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+export interface GatewayStateStoreOptions {
+  /** Override the on-disk path; defaults to `~/.botcord/daemon/gateways/{id}.state.json`. */
+  override?: string;
+  /** Debounce window for batching writes; defaults to 1000ms. Use `0` for sync writes (tests). */
+  debounceMs?: number;
+}
+
+/**
+ * Per-gateway state store with debounced writes. Reads are always synchronous
+ * against the in-memory snapshot, so the polling loop sees its own writes
+ * even before they are flushed to disk. `flush()` is exposed for shutdown
+ * paths and tests; `close()` flushes and clears the timer.
+ */
+const MAX_FLUSH_RETRIES = 10;
+
+export class GatewayStateStore {
+  private readonly file: string;
+  private readonly debounceMs: number;
+  private state: ThirdPartyGatewayState;
+  private timer: NodeJS.Timeout | null = null;
+  private dirty = false;
+  private flushRetryCount = 0;
+  /** W9: most recent write error surfaced for diagnostics. Cleared on success. */
+  lastError: Error | null = null;
+
+  constructor(gatewayId: string, opts: GatewayStateStoreOptions = {}) {
+    this.file = defaultGatewayStatePath(gatewayId, opts.override);
+    this.debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    this.state = readState(this.file);
+  }
+
+  /** Read the current cursor (in-memory; reflects pending writes). */
+  getCursor(): string | undefined {
+    return this.state.cursor;
+  }
+
+  /** Read the current provider-state bag. Mutating the returned object does not persist. */
+  getProviderState(): Record<string, unknown> | undefined {
+    return this.state.providerState;
+  }
+
+  getSnapshot(): ThirdPartyGatewayState {
+    return { ...this.state };
+  }
+
+  /** Update cursor + optional provider state and schedule a debounced flush. */
+  update(patch: {
+    cursor?: string;
+    providerState?: Record<string, unknown>;
+  }): void {
+    if (patch.cursor !== undefined) this.state.cursor = patch.cursor;
+    if (patch.providerState !== undefined) {
+      this.state.providerState = patch.providerState;
+    }
+    this.state.updatedAt = new Date().toISOString();
+    this.scheduleFlush();
+  }
+
+  /**
+   * Force a synchronous write of the pending state, if any.
+   *
+   * W9: on write failure, leave `dirty=true` and re-arm the debounce timer
+   * so a subsequent `update()` (or background timer fire) retries instead of
+   * silently dropping the pending state. The error is also re-thrown so
+   * callers that explicitly invoke `flush()` (shutdown paths, tests) see it.
+   */
+  flush(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (!this.dirty) return;
+    try {
+      writeStateSync(this.file, this.state);
+      this.dirty = false;
+      this.lastError = null;
+      this.flushRetryCount = 0;
+    } catch (err) {
+      this.lastError = err instanceof Error ? err : new Error(String(err));
+      // Keep dirty=true so the next update() re-arms a flush. We also
+      // schedule a retry now in case the caller has nothing else queued.
+      this.scheduleFlushRetry();
+      throw this.lastError;
+    }
+  }
+
+  /** Flush and stop accepting future debounced writes. */
+  close(): void {
+    this.flush();
+  }
+
+  /** On-disk path; exposed for tests and diagnostics. */
+  get filePath(): string {
+    return this.file;
+  }
+
+  private scheduleFlush(): void {
+    this.dirty = true;
+    if (this.debounceMs <= 0) {
+      // W9: synchronous mode — re-throw on failure so the caller sees the
+      // problem instead of having the data silently disappear.
+      this.flush();
+      return;
+    }
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      if (!this.dirty) return;
+      try {
+        writeStateSync(this.file, this.state);
+        this.dirty = false;
+        this.lastError = null;
+        this.flushRetryCount = 0;
+      } catch (err) {
+        // W9: keep dirty=true and re-arm so the failed write retries.
+        this.lastError = err instanceof Error ? err : new Error(String(err));
+        this.scheduleFlushRetry();
+      }
+    }, this.debounceMs);
+    if (typeof this.timer.unref === "function") this.timer.unref();
+  }
+
+  /**
+   * Re-arm the debounce timer after a write failure. Bounded delay (capped
+   * at 5s) so transient failures do not become a hot-spin retry loop.
+   * After MAX_FLUSH_RETRIES consecutive failures, log and stop retrying so
+   * a permanently broken write path cannot loop indefinitely. `lastError` is
+   * left set so callers can detect persistent failure.
+   */
+  private scheduleFlushRetry(): void {
+    if (this.debounceMs <= 0) return; // sync mode: caller decides
+    if (this.timer) return;
+    this.flushRetryCount += 1;
+    if (this.flushRetryCount > MAX_FLUSH_RETRIES) {
+      // Persistent failure — give up. lastError remains set for diagnostics.
+      console.error(
+        `[state-store] flush failed ${MAX_FLUSH_RETRIES} times; giving up on ${this.file}`,
+        this.lastError,
+      );
+      return;
+    }
+    const retryMs = Math.min(Math.max(this.debounceMs, 250), 5000);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      if (!this.dirty) return;
+      try {
+        writeStateSync(this.file, this.state);
+        this.dirty = false;
+        this.lastError = null;
+        this.flushRetryCount = 0;
+      } catch (err) {
+        this.lastError = err instanceof Error ? err : new Error(String(err));
+        this.scheduleFlushRetry();
+      }
+    }, retryMs);
+    if (typeof this.timer.unref === "function") this.timer.unref();
+  }
+}