ofw-mcp 2.4.4 → 2.6.3

package/dist/cache/node.js

@@ -0,0 +1,85 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, chmodSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { OFWCacheCore, LocalCacheStore } from './store.js';
+// The `node:sqlite` backend for the OFW message cache — a local on-disk SQLite
+// file used by the stdio/desktop server. The query logic lives in OFWCacheCore
+// (src/cache/store.ts); this file only adapts `node:sqlite` to the SqlDriver
+// surface and manages the file handle + permissions. (The hosted Cloudflare
+// connector uses a Durable Object backend instead — a later task.)
+/** Adapts a `node:sqlite` DatabaseSync to the driver surface the core needs. */
+export class NodeSqlDriver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    execScript(sql) {
+        this.db.exec(sql);
+    }
+    run(sql, params) {
+        this.db.prepare(sql).run(...params);
+    }
+    get(sql, params) {
+        return this.db.prepare(sql).get(...params);
+    }
+    all(sql, params) {
+        return this.db.prepare(sql).all(...params);
+    }
+    transaction(fn) {
+        this.db.exec('BEGIN');
+        try {
+            fn();
+            this.db.exec('COMMIT');
+        }
+        catch (e) {
+            this.db.exec('ROLLBACK');
+            throw e;
+        }
+    }
+}
+// The cache holds full co-parenting message history — keep it private to the
+// owning user. Modes are asserted on every open (not just creation): mkdirSync
+// `mode` and SQLite's default file mode only apply when the path is first
+// created, so a pre-existing dir/db keeps whatever (world-readable) mode it
+// had. The -wal/-shm siblings appear and disappear with WAL checkpoints, hence
+// the existence check.
+export function enforceCachePermissions(dbPath) {
+    chmodSync(dirname(dbPath), 0o700);
+    chmodSync(dbPath, 0o600);
+    for (const sibling of [`${dbPath}-wal`, `${dbPath}-shm`]) {
+        if (existsSync(sibling))
+            chmodSync(sibling, 0o600);
+    }
+}
+/**
+ * A file-backed OFW message cache. `open()` creates parent dirs, locks the dir
+ * and DB down to 0700/0600, enables WAL, and applies the schema. Pass
+ * `:memory:` for an ephemeral in-memory cache (tests) — no dirs or chmod.
+ */
+export class OFWCache extends LocalCacheStore {
+    db;
+    constructor(db, core) {
+        super(core);
+        this.db = db;
+    }
+    static open(path) {
+        const memory = path === ':memory:';
+        if (!memory)
+            mkdirSync(dirname(path), { recursive: true });
+        const db = new DatabaseSync(path);
+        // First pass: lock down dir + db before WAL siblings exist.
+        if (!memory)
+            enforceCachePermissions(path);
+        db.exec('PRAGMA journal_mode = WAL');
+        db.exec('PRAGMA foreign_keys = ON');
+        // Constructing the core applies the schema (and writes the -wal/-shm files).
+        const core = new OFWCacheCore(new NodeSqlDriver(db));
+        // Second pass: lock down the -wal/-shm the schema writes created.
+        if (!memory)
+            enforceCachePermissions(path);
+        return new OFWCache(db, core);
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/cache/store.js

@@ -0,0 +1,480 @@
+// Storage-agnostic core for the OFW message cache.
+//
+// All message reads (list/get/drafts/unread-sent) are served from this cache;
+// only ofw_sync_messages walks OFW for new content. The SQL lives here ONCE,
+// over a tiny synchronous {@link SqlDriver}, so the same schema/queries back
+// both engines: `node:sqlite` on the stdio/desktop server (src/cache/node.ts)
+// and a Durable Object's SQLite on the hosted Cloudflare connector (a later
+// task). This module imports nothing platform-specific.
+function rowFromDb(r) {
+    return {
+        id: r.id,
+        folder: r.folder,
+        subject: r.subject,
+        fromUser: r.from_user,
+        sentAt: r.sent_at,
+        recipients: JSON.parse(r.recipients_json),
+        body: r.body,
+        fetchedBodyAt: r.fetched_body_at,
+        replyToId: r.reply_to_id,
+        chainRootId: r.chain_root_id,
+        listData: JSON.parse(r.list_data_json),
+    };
+}
+function draftFromDb(r) {
+    return {
+        id: r.id,
+        subject: r.subject,
+        body: r.body,
+        recipients: JSON.parse(r.recipients_json),
+        replyToId: r.reply_to_id,
+        modifiedAt: r.modified_at,
+        listData: JSON.parse(r.list_data_json),
+    };
+}
+function attachmentFromDb(r) {
+    return {
+        fileId: r.file_id,
+        fileName: r.file_name,
+        label: r.label,
+        mimeType: r.mime_type,
+        sizeBytes: r.size_bytes,
+        metadata: JSON.parse(r.metadata_json),
+        messageIds: JSON.parse(r.message_ids_json),
+        downloadedPath: r.downloaded_path,
+        downloadedAt: r.downloaded_at,
+    };
+}
+// node:sqlite rejects `undefined` as a bound parameter ("Provided value cannot
+// be bound"). Normalize undefined to null for nullable columns so callers
+// don't have to remember; throw with a useful error for NOT NULL fields that
+// somehow arrived as undefined.
+function nullish(v) {
+    return v === undefined ? null : v;
+}
+function requireString(field, v) {
+    if (typeof v === 'string')
+        return v;
+    throw new Error(`cache: ${field} is required (got ${v === undefined ? 'undefined' : 'null'})`);
+}
+/** Schema statements, split so a driver that only runs one statement per call works. */
+export const SCHEMA_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS messages (
+     id INTEGER PRIMARY KEY,
+     folder TEXT NOT NULL,
+     subject TEXT NOT NULL,
+     from_user TEXT NOT NULL,
+     sent_at TEXT NOT NULL,
+     recipients_json TEXT NOT NULL,
+     body TEXT,
+     fetched_body_at TEXT,
+     reply_to_id INTEGER,
+     chain_root_id INTEGER,
+     list_data_json TEXT NOT NULL,
+     last_seen_at TEXT NOT NULL
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_messages_folder_sent_at ON messages(folder, sent_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_messages_chain_root ON messages(chain_root_id)`,
+    `CREATE TABLE IF NOT EXISTS drafts (
+     id INTEGER PRIMARY KEY,
+     subject TEXT NOT NULL,
+     body TEXT NOT NULL,
+     recipients_json TEXT NOT NULL,
+     reply_to_id INTEGER,
+     modified_at TEXT NOT NULL,
+     list_data_json TEXT NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS sync_state (
+     folder TEXT PRIMARY KEY,
+     last_sync_at TEXT NOT NULL,
+     newest_id INTEGER
+   )`,
+    `CREATE TABLE IF NOT EXISTS meta (
+     key TEXT PRIMARY KEY,
+     value TEXT NOT NULL
+   )`,
+    // v2: attachments table. Idempotent — IF NOT EXISTS.
+    `CREATE TABLE IF NOT EXISTS attachments (
+     file_id INTEGER PRIMARY KEY,
+     file_name TEXT NOT NULL,
+     label TEXT NOT NULL,
+     mime_type TEXT NOT NULL,
+     size_bytes INTEGER,
+     metadata_json TEXT NOT NULL,
+     message_ids_json TEXT NOT NULL,
+     downloaded_path TEXT,
+     downloaded_at TEXT,
+     fetched_metadata_at TEXT NOT NULL
+   )`,
+];
+/**
+ * Idempotent post-schema migrations, applied after {@link SCHEMA_STATEMENTS} on
+ * every open. SQLite has no `ADD COLUMN IF NOT EXISTS`, so each statement runs
+ * inside a try/catch — re-running against an already-migrated DB throws
+ * "duplicate column name", which is swallowed. Driver-agnostic: both
+ * `node:sqlite` and the Durable Object's SQLite raise synchronously.
+ */
+export const MIGRATIONS = [
+    // Resumable deep-sync cursor. Absent/NULL → SyncState.resumePage null.
+    'ALTER TABLE sync_state ADD COLUMN resume_page INTEGER',
+];
+/** The schema version stamped into the `meta` table on open. */
+export const SCHEMA_VERSION = '2';
+// Build the WHERE clause + bound params for message queries. listMessages and
+// countMessages share this so the filter semantics can't drift.
+function buildMessageFilter(opts) {
+    const wheres = [];
+    const params = [];
+    if (opts.folder !== undefined) {
+        wheres.push('folder = ?');
+        params.push(opts.folder);
+    }
+    if (opts.since !== undefined) {
+        wheres.push('sent_at >= ?');
+        params.push(opts.since);
+    }
+    if (opts.until !== undefined) {
+        wheres.push('sent_at < ?');
+        params.push(opts.until);
+    }
+    if (opts.q !== undefined && opts.q.length > 0) {
+        const pattern = `%${opts.q}%`;
+        wheres.push('(subject LIKE ? OR body LIKE ?)');
+        params.push(pattern, pattern);
+    }
+    return {
+        where: wheres.length > 0 ? `WHERE ${wheres.join(' AND ')}` : '',
+        params,
+    };
+}
+/**
+ * The OFW cache logic over a synchronous {@link SqlDriver}. The constructor
+ * applies the schema (idempotent CREATE IF NOT EXISTS) and stamps the schema
+ * version into the `meta` table.
+ */
+export class OFWCacheCore {
+    db;
+    constructor(db) {
+        this.db = db;
+        for (const stmt of SCHEMA_STATEMENTS)
+            this.db.execScript(stmt);
+        for (const stmt of MIGRATIONS) {
+            try {
+                this.db.execScript(stmt);
+            }
+            catch {
+                // Idempotent: the column already exists on a previously-migrated DB.
+                // SQLite lacks ADD COLUMN IF NOT EXISTS, so a re-run throws "duplicate
+                // column name" — swallow it and move on.
+            }
+        }
+        this.db.run('INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value', ['schema_version', SCHEMA_VERSION]);
+    }
+    upsertMessage(row) {
+        this.db.run(`INSERT INTO messages (
+         id, folder, subject, from_user, sent_at, recipients_json,
+         body, fetched_body_at, reply_to_id, chain_root_id, list_data_json, last_seen_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         folder=excluded.folder,
+         subject=excluded.subject,
+         from_user=excluded.from_user,
+         sent_at=excluded.sent_at,
+         recipients_json=excluded.recipients_json,
+         body=excluded.body,
+         fetched_body_at=excluded.fetched_body_at,
+         reply_to_id=excluded.reply_to_id,
+         chain_root_id=excluded.chain_root_id,
+         list_data_json=excluded.list_data_json,
+         last_seen_at=excluded.last_seen_at`, [
+            row.id,
+            requireString('messages.folder', row.folder),
+            requireString('messages.subject', row.subject),
+            requireString('messages.fromUser', row.fromUser),
+            requireString('messages.sentAt', row.sentAt),
+            JSON.stringify(row.recipients ?? []),
+            nullish(row.body),
+            nullish(row.fetchedBodyAt),
+            nullish(row.replyToId),
+            nullish(row.chainRootId),
+            JSON.stringify(row.listData ?? null),
+            new Date().toISOString(),
+        ]);
+    }
+    /**
+     * Batch upsert every row in a single transaction — one round-trip's worth of
+     * work (crucial on the Durable Object backend, where each RPC is a subrequest).
+     * Empty array is a no-op (no transaction opened).
+     */
+    upsertMessages(rows) {
+        if (rows.length === 0)
+            return;
+        this.db.transaction(() => {
+            for (const row of rows)
+                this.upsertMessage(row);
+        });
+    }
+    getMessage(id) {
+        const r = this.db.get('SELECT * FROM messages WHERE id = ?', [id]);
+        return r ? rowFromDb(r) : null;
+    }
+    /**
+     * Batch read: one `SELECT ... WHERE id IN (...)` returning the present rows
+     * (absent ids are simply omitted — order is not guaranteed). Empty ids returns
+     * `[]` without querying.
+     */
+    getMessages(ids) {
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(', ');
+        const rows = this.db.all(`SELECT * FROM messages WHERE id IN (${placeholders})`, ids);
+        return rows.map(rowFromDb);
+    }
+    /**
+     * Remove a row from the `messages` table. Used by syncDrafts to evict
+     * stale rows that were cached when a draft was previously read through
+     * `ofw_get_message` (which would have wrongly classified it as `inbox`)
+     * — the drafts table is the authoritative source for that id now.
+     */
+    deleteMessage(id) {
+        this.db.run('DELETE FROM messages WHERE id = ?', [id]);
+    }
+    listMessages(opts) {
+        const { where, params } = buildMessageFilter(opts);
+        const offset = (opts.page - 1) * opts.size;
+        const rows = this.db.all(`SELECT * FROM messages ${where}
+       ORDER BY sent_at DESC, id DESC
+       LIMIT ? OFFSET ?`, [...params, opts.size, offset]);
+        return rows.map(rowFromDb);
+    }
+    countMessages(opts) {
+        const { where, params } = buildMessageFilter(opts);
+        const r = this.db.get(`SELECT COUNT(*) as n FROM messages ${where}`, params);
+        /* v8 ignore next -- SELECT COUNT(*) always returns exactly one row; the ?./?? are defensive */
+        return r?.n ?? 0;
+    }
+    upsertDraft(row) {
+        this.db.run(`INSERT INTO drafts (id, subject, body, recipients_json, reply_to_id, modified_at, list_data_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         subject=excluded.subject,
+         body=excluded.body,
+         recipients_json=excluded.recipients_json,
+         reply_to_id=excluded.reply_to_id,
+         modified_at=excluded.modified_at,
+         list_data_json=excluded.list_data_json`, [
+            row.id,
+            requireString('drafts.subject', row.subject),
+            requireString('drafts.body', row.body),
+            JSON.stringify(row.recipients ?? []),
+            nullish(row.replyToId),
+            requireString('drafts.modifiedAt', row.modifiedAt),
+            JSON.stringify(row.listData ?? null),
+        ]);
+    }
+    /** Batch upsert every draft in a single transaction. Empty array is a no-op. */
+    upsertDrafts(rows) {
+        if (rows.length === 0)
+            return;
+        this.db.transaction(() => {
+            for (const row of rows)
+                this.upsertDraft(row);
+        });
+    }
+    getDraft(id) {
+        const r = this.db.get('SELECT * FROM drafts WHERE id = ?', [id]);
+        return r ? draftFromDb(r) : null;
+    }
+    /**
+     * Batch read: one `SELECT ... WHERE id IN (...)` returning the present drafts
+     * (absent ids omitted — order not guaranteed). Empty ids returns `[]` without
+     * querying.
+     */
+    getDrafts(ids) {
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(', ');
+        const rows = this.db.all(`SELECT * FROM drafts WHERE id IN (${placeholders})`, ids);
+        return rows.map(draftFromDb);
+    }
+    listDrafts(opts) {
+        const offset = (opts.page - 1) * opts.size;
+        const rows = this.db.all('SELECT * FROM drafts ORDER BY modified_at DESC, id DESC LIMIT ? OFFSET ?', [opts.size, offset]);
+        return rows.map(draftFromDb);
+    }
+    deleteDraft(id) {
+        this.db.run('DELETE FROM drafts WHERE id = ?', [id]);
+    }
+    listDraftIds() {
+        const rows = this.db.all('SELECT id FROM drafts', []);
+        return rows.map((r) => r.id);
+    }
+    getSyncState(folder) {
+        const r = this.db.get('SELECT last_sync_at, newest_id, resume_page FROM sync_state WHERE folder = ?', [folder]);
+        if (!r)
+            return null;
+        // A DB migrated before resume_page existed can still return the row
+        // without the column; normalize a missing/NULL value to null.
+        return { lastSyncAt: r.last_sync_at, newestId: r.newest_id, resumePage: r.resume_page ?? null };
+    }
+    setSyncState(folder, state) {
+        this.db.run(`INSERT INTO sync_state (folder, last_sync_at, newest_id, resume_page) VALUES (?, ?, ?, ?)
+       ON CONFLICT(folder) DO UPDATE SET
+         last_sync_at = excluded.last_sync_at,
+         newest_id = excluded.newest_id,
+         resume_page = excluded.resume_page`, [folder, state.lastSyncAt, nullish(state.newestId), nullish(state.resumePage)]);
+    }
+    getMeta(key) {
+        const r = this.db.get('SELECT value FROM meta WHERE key = ?', [key]);
+        return r ? r.value : null;
+    }
+    setMeta(key, value) {
+        this.db.run('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value', [key, value]);
+    }
+    findLatestReplyTip(replyToId) {
+        const parent = this.db.get('SELECT id, folder, chain_root_id FROM messages WHERE id = ?', [replyToId]);
+        if (!parent)
+            return replyToId;
+        const chainRoot = parent.chain_root_id ?? parent.id;
+        const tip = this.db.get(`SELECT id FROM messages
+       WHERE folder = 'sent' AND chain_root_id = ?
+       ORDER BY id DESC LIMIT 1`, [chainRoot]);
+        return tip ? tip.id : replyToId;
+    }
+    getAttachment(fileId) {
+        const r = this.db.get('SELECT * FROM attachments WHERE file_id = ?', [fileId]);
+        return r ? attachmentFromDb(r) : null;
+    }
+    listAttachmentsForMessage(messageId) {
+        // SQLite JSON1 contains check
+        const rows = this.db.all(`SELECT * FROM attachments
+       WHERE EXISTS (SELECT 1 FROM json_each(message_ids_json) WHERE value = ?)
+       ORDER BY file_id`, [messageId]);
+        return rows.map(attachmentFromDb);
+    }
+    upsertAttachmentForMessage(input) {
+        const existing = this.db.get('SELECT message_ids_json FROM attachments WHERE file_id = ?', [input.fileId]);
+        // messageId === 0 is the "metadata-only, not yet linked to a message"
+        // sentinel used by upload-without-send and download-by-id. Don't
+        // pollute the array with it — leave the list empty / unchanged.
+        const prior = existing ? JSON.parse(existing.message_ids_json) : [];
+        let messageIds;
+        if (input.messageId === 0) {
+            messageIds = prior;
+        }
+        else if (prior.includes(input.messageId)) {
+            messageIds = prior;
+        }
+        else {
+            messageIds = [...prior, input.messageId];
+        }
+        this.db.run(`INSERT INTO attachments (
+         file_id, file_name, label, mime_type, size_bytes,
+         metadata_json, message_ids_json, fetched_metadata_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(file_id) DO UPDATE SET
+         file_name=excluded.file_name,
+         label=excluded.label,
+         mime_type=excluded.mime_type,
+         size_bytes=excluded.size_bytes,
+         metadata_json=excluded.metadata_json,
+         message_ids_json=excluded.message_ids_json,
+         fetched_metadata_at=excluded.fetched_metadata_at`, [
+            input.fileId,
+            requireString('attachments.fileName', input.fileName),
+            requireString('attachments.label', input.label),
+            requireString('attachments.mimeType', input.mimeType),
+            nullish(input.sizeBytes),
+            JSON.stringify(input.metadata ?? null),
+            JSON.stringify(messageIds),
+            new Date().toISOString(),
+        ]);
+    }
+    markAttachmentDownloaded(fileId, path) {
+        this.db.run('UPDATE attachments SET downloaded_path = ?, downloaded_at = ? WHERE file_id = ?', [
+            path,
+            new Date().toISOString(),
+            fileId,
+        ]);
+    }
+}
+/**
+ * Adapts a synchronous {@link OFWCacheCore} to the async {@link CacheStore}
+ * interface. Used by the in-process node backend; the Durable Object backend
+ * implements CacheStore over a real RPC boundary instead.
+ */
+export class LocalCacheStore {
+    core;
+    constructor(core) {
+        this.core = core;
+    }
+    async upsertMessage(row) {
+        this.core.upsertMessage(row);
+    }
+    async upsertMessages(rows) {
+        this.core.upsertMessages(rows);
+    }
+    async getMessage(id) {
+        return this.core.getMessage(id);
+    }
+    async getMessages(ids) {
+        return this.core.getMessages(ids);
+    }
+    async deleteMessage(id) {
+        this.core.deleteMessage(id);
+    }
+    async listMessages(opts) {
+        return this.core.listMessages(opts);
+    }
+    async countMessages(opts) {
+        return this.core.countMessages(opts);
+    }
+    async upsertDraft(row) {
+        this.core.upsertDraft(row);
+    }
+    async upsertDrafts(rows) {
+        this.core.upsertDrafts(rows);
+    }
+    async getDraft(id) {
+        return this.core.getDraft(id);
+    }
+    async getDrafts(ids) {
+        return this.core.getDrafts(ids);
+    }
+    async listDrafts(opts) {
+        return this.core.listDrafts(opts);
+    }
+    async deleteDraft(id) {
+        this.core.deleteDraft(id);
+    }
+    async listDraftIds() {
+        return this.core.listDraftIds();
+    }
+    async getSyncState(folder) {
+        return this.core.getSyncState(folder);
+    }
+    async setSyncState(folder, state) {
+        this.core.setSyncState(folder, state);
+    }
+    async getMeta(key) {
+        return this.core.getMeta(key);
+    }
+    async setMeta(key, value) {
+        this.core.setMeta(key, value);
+    }
+    async findLatestReplyTip(replyToId) {
+        return this.core.findLatestReplyTip(replyToId);
+    }
+    async getAttachment(fileId) {
+        return this.core.getAttachment(fileId);
+    }
+    async listAttachmentsForMessage(messageId) {
+        return this.core.listAttachmentsForMessage(messageId);
+    }
+    async upsertAttachmentForMessage(input) {
+        this.core.upsertAttachmentForMessage(input);
+    }
+    async markAttachmentDownloaded(fileId, path) {
+        this.core.markAttachmentDownloaded(fileId, path);
+    }
+}

package/dist/client.js

@@ -6,9 +6,17 @@ import { resolveAuth } from './auth.js';
 import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS, OFW_TOKEN_EXPIRY_SKEW_MS } from './protocol.js';
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
 // bundle). loadDotenvSafely applies override:false + quiet:true and swallows a
-// missing dotenv module, matching the prior inline try/catch exactly.
-const __dirname = dirname(fileURLToPath(import.meta.url));
-await loadDotenvSafely({ path: join(__dirname, '..', '.env') });
+// missing dotenv module. The try/catch additionally guards the Cloudflare
+// Worker runtime, where `import.meta.url` is undefined and
+// `fileURLToPath(undefined)` would otherwise throw at module init (Worker
+// startup validation) — there is no filesystem / .env to load there anyway.
+try {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    await loadDotenvSafely({ path: join(dir, '..', '.env') });
+}
+catch {
+    /* v8 ignore next -- only reached in a non-Node runtime (Workers): no .env to load */
+}
 // Parse a Content-Disposition header for a filename. Prefers RFC 6266
 // `filename*=UTF-8''…` (percent-decoded) and falls back to `filename="…"`.
 function parseContentDispositionFilename(cd) {
@@ -58,6 +66,16 @@ export class OFWClient {
     // already-expired placeholder token so the first request drives the refresh
     // callback — i.e. the original "log in on first request" behavior.
     tokenManager;
+    // Optional injected auth resolver. When set, the refresh callback uses it
+    // instead of the module-level global `resolveAuth` (env-var → fetchproxy
+    // priority). A hosted per-user deployment injects its own resolver so each
+    // request carries that user's credentials — see the Cloudflare Worker
+    // deployment. Left undefined by the stdio path, which falls back to the
+    // global resolver, keeping that behaviour byte-for-byte identical.
+    authResolver;
+    constructor(opts) {
+        this.authResolver = opts?.resolveAuth;
+    }
     getTokenManager() {
         if (!this.tokenManager) {
             this.tokenManager = new TokenManager({
@@ -69,7 +87,7 @@ export class OFWClient {
                 // path uses (the 401-replay covers a wrong guess). We re-arm the
                 // sentinel so the manager can refresh again later.
                 refresh: async () => {
-                    const { token, expiresAt } = await resolveAuth();
+                    const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
                     return {
                         accessToken: token,
                         refreshToken: OFW_REFRESH_SENTINEL,

package/dist/config.js

@@ -61,6 +61,27 @@ export function getWriteMode() {
     console.error(`[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" — failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`);
     return 'none';
 }
+/**
+ * Calendar-write opt-in for 'drafts' deployments.
+ *
+ * Messages have a draft stage (the human sends from the web UI), so 'drafts'
+ * mode keeps a human between model output and the court-visible record.
+ * Calendar events have no draft stage — but unlike a sent message they are
+ * fully reversible (editable and deletable), so a drafts-mode user may accept
+ * direct calendar writes without accepting sends. Setting
+ * OFW_CALENDAR_WRITES=true registers the calendar write tools
+ * (ofw_create_event, ofw_update_event, ofw_delete_event) alongside the
+ * draft-level message writes.
+ *
+ * The flag never overrides 'none': that mode is the hard read-only guarantee,
+ * including the fail-closed result of an unrecognized OFW_WRITE_MODE.
+ */
+export function getCalendarWritesAllowed() {
+    const mode = getWriteMode();
+    if (mode === 'all')
+        return true;
+    return mode === 'drafts' && parseBoolEnv('OFW_CALENDAR_WRITES');
+}
 // Default for ofw_download_attachment's `inline` arg when the caller doesn't
 // pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as
 // MCP content blocks by default (skipping disk) — useful on sandboxed MCP
@@ -68,3 +89,24 @@ export function getWriteMode() {
 export function getDefaultInlineAttachments() {
     return parseBoolEnv('OFW_INLINE_ATTACHMENTS');
 }
+/**
+ * Per-invocation OFW-request budget for ofw_sync_messages.
+ *
+ * The hosted Cloudflare Worker connector enforces a subrequest cap per request
+ * (every OFW API fetch and every Durable-Object cache RPC counts), so a deep
+ * backfill must be bounded and resumable there. Set OFW_SYNC_MAX_REQUESTS to a
+ * positive integer to cap the number of OFW requests one sync call may make
+ * before pausing; the next call resumes the walk (deep or not) where it left off.
+ *
+ * Unset / blank / non-positive / non-integer → POSITIVE_INFINITY, i.e. the
+ * local stdio server stays unbounded (walks fully in one call) by default.
+ */
+export function getSyncMaxRequests() {
+    const raw = readEnvVar('OFW_SYNC_MAX_REQUESTS');
+    if (raw === undefined)
+        return Number.POSITIVE_INFINITY;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        return Number.POSITIVE_INFINITY;
+    return n;
+}