clavarium-tether 0.1.0-next.2 → 0.1.0-next.20

package/bin/cli.mjs

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { ask, findFolder } from '../server/mcp.mjs';
 import { NAME, VERSION, FOLDER, ENV_DIR } from '../server/name.mjs';
 
-export const HELP = `${NAME}: act on the targets you were given (machines, folders, browsers).
+export const HELP = `${NAME}: act on the targets you were given (machines, folders, browsers, mailboxes, calendars, address books).
 
   ${NAME}                                  your targets, your level on each, its rules
   ${NAME} run TARGET "command" [--timeout S]   run a command: its output and exit code
@@ -33,6 +33,19 @@ export const HELP = `${NAME}: act on the targets you were given (machines, folde
   ${NAME} browser TARGET key KEY [--selector S] [--tab N]
   ${NAME} browser TARGET scroll [--dx N] [--dy N] [--selector S] [--tab N]
   ${NAME} browser TARGET drag FROM TO [--tab N]
+  ${NAME} mail TARGET list [--mailbox NAME]            recent messages: who, subject, when
+  ${NAME} mail TARGET read UID [--mailbox NAME]        one message in full
+  ${NAME} mail TARGET search "text" [--mailbox NAME]
+  ${NAME} mail TARGET move UID MAILBOX                 move a message to a folder
+  ${NAME} mail TARGET flag UID read|unread|flagged|unflagged
+  ${NAME} mail TARGET send --to "a@b,c@d" --subject "..." --body "..." [--cc "..."] [--attach FILE]
+  ${NAME} calendar TARGET list [--from DATE] [--to DATE]   events in a window (default: from now on)
+  ${NAME} calendar TARGET read ID
+  ${NAME} calendar TARGET create --title "..." --start ISO --end ISO [--where "..."]
+  ${NAME} calendar TARGET attach EVENT_ID FILE             join a file to an event (Microsoft)
+  ${NAME} contacts TARGET list                          name, emails, phones
+  ${NAME} contacts TARGET read ID
+  ${NAME} contacts TARGET attach CONTACT_ID FILE           set a contact's photo (Microsoft)
   ${NAME} serve [--store DIR] [--port N] [--side FOLDER=NAME] [--local FOLDER[=TITLE]]
                                        keep targets yourself, with their page (no application)
 
@@ -44,6 +57,11 @@ ${NAME} ${VERSION}`;
 
 const FILE_VERBS = ['list', 'read', 'search', 'write', 'move', 'delete'];
 const BROWSER_VERBS = ['tabs', 'open', 'shot', 'html', 'console', 'eval', 'click', 'type', 'key', 'scroll', 'drag'];
+const MAIL_VERBS = ['list', 'read', 'search', 'move', 'flag', 'send'];
+const CAL_VERBS = ['list', 'read', 'create', 'attach'];
+const CONTACT_VERBS = ['list', 'read', 'attach'];
+const baseName = (p) => String(p).split('/').pop();
+const readB64 = (p) => { try { return readFileSync(p).toString('base64'); } catch { return null; } };
 
 /* A command line, read: [verb, args] or { refused }. A --from file is read by run(). */
 export function read(argv) {
@@ -97,6 +115,50 @@ export function read(argv) {
                 default: return need(p.length === 2, 'browser TARGET drag FROM TO') ?? ['browser.drag', { target, from: p[0], to: p[1], ...tab, ...why }];
             }
         }
+        case 'mail': {
+            const [what, ...p] = rest;
+            if (!target || !MAIL_VERBS.includes(what)) return { refused: `${NAME} mail TARGET ${MAIL_VERBS.join('|')} ...` };
+            const box = flags.mailbox !== undefined ? { mailbox: flags.mailbox } : {};
+            switch (what) {
+                case 'list': return ['mail.list', { target, ...box }];
+                case 'read': return need(p[0], 'mail TARGET read UID [--mailbox NAME]') ?? ['mail.read', { target, uid: p[0], ...box }];
+                case 'search': return need(p.length, 'mail TARGET search "text" [--mailbox NAME]') ?? ['mail.search', { target, text: p.join(' '), ...box }];
+                case 'move': return need(p.length === 2, 'mail TARGET move UID MAILBOX') ?? ['mail.move', { target, uid: p[0], mailbox: p[1], ...why }];
+                case 'flag': return need(p.length === 2, 'mail TARGET flag UID FLAG') ?? ['mail.flag', { target, uid: p[0], flag: p[1], ...why }];
+                default: {
+                    const bad = need(flags.to !== undefined && flags.subject !== undefined && flags.body !== undefined, 'mail TARGET send --to "a@b" --subject "..." --body "..." [--cc "..."] [--attach FILE]');
+                    if (bad) return bad;
+                    let att = {};
+                    if (flags.attach !== undefined) { const b = readB64(flags.attach); if (b === null) return { refused: `cannot read the file to attach: ${flags.attach}` }; att = { attach: b, attachName: flags['attach-name'] || baseName(flags.attach) }; }
+                    return ['mail.send', { target, to: flags.to, subject: flags.subject, body: flags.body, ...(flags.cc !== undefined ? { cc: flags.cc } : {}), ...att, ...why }];
+                }
+            }
+        }
+        case 'calendar': {
+            const [what, ...p] = rest;
+            if (!target || !CAL_VERBS.includes(what)) return { refused: `${NAME} calendar TARGET ${CAL_VERBS.join('|')} ...` };
+            switch (what) {
+                case 'list': return ['calendar.list', { target, ...(flags.from !== undefined ? { from: flags.from } : {}), ...(flags.to !== undefined ? { to: flags.to } : {}) }];
+                case 'read': return need(p[0], 'calendar TARGET read ID') ?? ['calendar.read', { target, id: p[0] }];
+                case 'attach': {
+                    if (p.length < 2) return { refused: 'calendar TARGET attach EVENT_ID FILE' };
+                    const b = readB64(p[1]); if (b === null) return { refused: `cannot read the file to attach: ${p[1]}` };
+                    return ['calendar.attach', { target, id: p[0], attach: b, attachName: flags['attach-name'] || baseName(p[1]), ...why }];
+                }
+                default: return need(flags.title !== undefined && flags.start !== undefined && flags.end !== undefined, 'calendar TARGET create --title "..." --start ISO --end ISO [--where "..."]') ?? ['calendar.create', { target, title: flags.title, start: flags.start, end: flags.end, ...(flags.where !== undefined ? { where: flags.where } : {}), ...why }];
+            }
+        }
+        case 'contacts': {
+            const [what, ...p] = rest;
+            if (!target || !CONTACT_VERBS.includes(what)) return { refused: `${NAME} contacts TARGET ${CONTACT_VERBS.join('|')} ...` };
+            if (what === 'list') return ['contacts.list', { target }];
+            if (what === 'attach') {
+                if (p.length < 2) return { refused: 'contacts TARGET attach CONTACT_ID FILE (a photo)' };
+                const b = readB64(p[1]); if (b === null) return { refused: `cannot read the file to attach: ${p[1]}` };
+                return ['contacts.attach', { target, id: p[0], attach: b, attachName: flags['attach-name'] || baseName(p[1]), ...why }];
+            }
+            return need(p[0], 'contacts TARGET read ID') ?? ['contacts.read', { target, id: p[0] }];
+        }
         default: return { refused: `Unknown: ${verb}. Run "${NAME} --help".` };
     }
 }

package/host/connectors/calendar.mjs

@@ -0,0 +1,196 @@
+/* THE CALENDAR CONNECTOR: a person's calendar (Google or Microsoft) reached by the
+ * keeper over the provider's REST API with a token, never a password. Like the mail
+ * connector, the refresh token is the host's and the agent never sees it; a short
+ * access token is minted per call. Inspired by the MIT Google/Microsoft MCP servers,
+ * the calls reimplemented here so the token stays host-side and the levels gate them.
+ *
+ *   target.config.provider   'google' or 'microsoft'
+ *   target.config.clientId   optional: an own OAuth app instead of Thunderbird's
+ *   target.secrets.refresh   the NAME of the refresh token in the host's secret store
+ *   target.secrets.secret    optional: the NAME of an own client secret
+ *
+ * Reads (watch): calendar.list, calendar.read. Acts (above watch): calendar.create.
+ * `fetch` is injected for tests. (Note: the Thunderbird client covers Google calendar
+ * cleanly; a Microsoft calendar needs the right Graph scope on the connected account.)
+ */
+import { no, Refused } from '../../server/verbs.mjs';
+import { refreshAccess, thunderbird, PROVIDERS } from '../oauth.mjs';
+
+const LIST_MAX = 25;
+const READ_MAX = 256 * 1024;
+const dateField = (s) => (/^\d{4}-\d{2}-\d{2}$/.test(s) ? { date: s } : { dateTime: s });
+
+const API = {
+    google: {
+        list: (n, { from, to } = {}) => `https://www.googleapis.com/calendar/v3/calendars/primary/events?maxResults=${n}&singleEvents=true&orderBy=startTime&timeMin=${encodeURIComponent(from)}${to ? `&timeMax=${encodeURIComponent(to)}` : ''}`,
+        event: (id) => `https://www.googleapis.com/calendar/v3/calendars/primary/events/${encodeURIComponent(id)}`,
+        create: 'https://www.googleapis.com/calendar/v3/calendars/primary/events',
+        items: (j) => j.items ?? [],
+        brief: (e) => `${e.id}\n  ${e.start?.dateTime ?? e.start?.date ?? '?'} — ${e.summary ?? '(no title)'}${e.location ? `  @ ${e.location}` : ''}`,
+        body: ({ title, start, end, where }) => ({ summary: title, start: dateField(start), end: dateField(end), ...(where ? { location: where } : {}) }),
+    },
+    microsoft: {
+        /* calendarView, not /events: /events orders over the WHOLE calendar, so it
+           returns the oldest events, not the next ones. calendarView takes a window
+           (from now on) and expands recurrences, so "list" means what is coming. */
+        list: (n, { from, to } = {}) => `https://graph.microsoft.com/v1.0/me/calendarView?startDateTime=${encodeURIComponent(from)}&endDateTime=${encodeURIComponent(to)}&$top=${n}&$orderby=start/dateTime&$select=id,subject,start,end,location`,
+        event: (id) => `https://graph.microsoft.com/v1.0/me/events/${encodeURIComponent(id)}`,
+        create: 'https://graph.microsoft.com/v1.0/me/events',
+        items: (j) => j.value ?? [],
+        brief: (e) => `${e.id}\n  ${e.start?.dateTime ?? '?'} — ${e.subject ?? '(no title)'}${e.location?.displayName ? `  @ ${e.location.displayName}` : ''}`,
+        body: ({ title, start, end, where }) => ({ subject: title, start: { dateTime: start, timeZone: 'UTC' }, end: { dateTime: end, timeZone: 'UTC' }, ...(where ? { location: { displayName: where } } : {}) }),
+    },
+};
+
+export function calendar({ fetch: fetchImpl = globalThis.fetch } = {}) {
+    const tokens = new Map();
+    const providerOf = (target) => { const p = String(target.config?.provider ?? ''); if (!API[p] || !PROVIDERS[p]) no(`${target.title}: set its provider to google or microsoft`); return p; };
+
+    async function access(target, ctx) {
+        const provider = providerOf(target);
+        const cached = tokens.get(target.id);
+        if (cached && cached.exp > Date.now() + 60_000) return cached.value;
+        const refresh = await ctx.secret('refresh');
+        if (!refresh) no(`${target.title}: its refresh token is empty -- reconnect the account`);
+        const clientId = target.config?.clientId || thunderbird(provider).clientId;
+        const clientSecret = target.secrets?.secret ? await ctx.secret('secret') : thunderbird(provider).clientSecret;
+        let t;
+        try { t = await refreshAccess(provider, { clientId, clientSecret, refreshToken: refresh, fetch: fetchImpl }); }
+        catch (e) { if (e instanceof Refused) throw e; no(`${target.title}: the calendar must be reconnected (its authorisation was refused)`); }
+        tokens.set(target.id, { value: t.accessToken, exp: t.expiresAt });
+        return t.accessToken;
+    }
+
+    async function call(target, ctx, method, url, json) {
+        const token = await access(target, ctx);
+        const headers = { Authorization: `Bearer ${token}` };
+        if (json !== undefined) headers['Content-Type'] = 'application/json';
+        let res;
+        try { res = await fetchImpl(url, { method, headers, ...(json !== undefined ? { body: JSON.stringify(json) } : {}) }); }
+        catch (e) { if (e instanceof Refused) throw e; no(`${target.title}: cannot reach the calendar`); }
+        if (res.status === 401 || res.status === 403) no(`${target.title}: not authorized -- reconnect the account (the calendar scope may be missing)`);
+        return res;
+    }
+    const bodyError = async (res) => { try { const j = await res.json(); return j?.error?.message || ''; } catch { return ''; } };
+
+    /* GOOGLE CALENDAR OVER CalDAV. The REST Calendar API needs that API turned on
+       in the OAuth client's own Google project; the borrowed Thunderbird client is
+       a CalDAV client (that is how it reads Google calendars), not a REST one, so
+       REST is refused. CalDAV uses the same calendar scope the client carries (as
+       its contacts do over CardDAV), so the host speaks a small calendar-query and
+       parses the returned iCalendar. The collection URL needs the account address. */
+    const decodeXml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+    const userOf = (target) => { const u = String(target.config?.user ?? '').trim(); if (!u) no(`${target.title}: reconnect the account so it carries its address (the Google calendar needs it)`); return u; };
+    const CALDAV = (user) => `https://apidata.googleusercontent.com/caldav/v2/${encodeURIComponent(user)}/events/`;
+    const icalUTC = (iso) => new Date(iso).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+    const fmtICal = (dt) => { const m = /^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2}))?/.exec(dt || ''); return m ? (m[4] ? `${m[1]}-${m[2]}-${m[3]} ${m[4]}:${m[5]}` : `${m[1]}-${m[2]}-${m[3]}`) : (dt || '?'); };
+    const veventField = (v, re) => { const m = re.exec(v); return m ? m[1].trim() : ''; };
+    function fromVevent(text) {
+        const v = String(text).replace(/\r?\n[ \t]/g, '');
+        return { summary: veventField(v, /^SUMMARY[^:\r\n]*:(.+)$/im), start: veventField(v, /^DTSTART[^:\r\n]*:(.+)$/im), location: veventField(v, /^LOCATION[^:\r\n]*:(.+)$/im) };
+    }
+    async function dav(target, ctx, method, url, { headers = {}, body } = {}) {
+        const token = await access(target, ctx);
+        let res;
+        try { res = await fetchImpl(url, { method, headers: { Authorization: `Bearer ${token}`, ...headers }, ...(body !== undefined ? { body } : {}) }); }
+        catch (e) { if (e instanceof Refused) throw e; no(`${target.title}: cannot reach the calendar`); }
+        if (res.status === 401 || res.status === 403) no(`${target.title}: not authorized -- reconnect the account (the calendar scope may be missing)`);
+        return res;
+    }
+    /* The events in a window, each expanded to its occurrences, briefed one per line. */
+    async function googleList(target, ctx, { from, to }) {
+        const s = icalUTC(from); const e = icalUTC(to);
+        const body = `<?xml version="1.0" encoding="utf-8"?><C:calendar-query xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav"><D:prop><D:getetag/><C:calendar-data><C:expand start="${s}" end="${e}"/></C:calendar-data></D:prop><C:filter><C:comp-filter name="VCALENDAR"><C:comp-filter name="VEVENT"><C:time-range start="${s}" end="${e}"/></C:comp-filter></C:comp-filter></C:filter></C:calendar-query>`;
+        const res = await dav(target, ctx, 'REPORT', CALDAV(userOf(target)), { headers: { Depth: '1', 'Content-Type': 'application/xml; charset=utf-8' }, body });
+        if (!res.ok) no(`${target.title}: the calendar could not be read (${res.status})`);
+        const xml = await res.text();
+        const out = [];
+        for (const block of xml.split(/<[A-Za-z0-9]*:?response[\s>]/i).slice(1)) {
+            const href = /<[^>]*?:?href[^>]*>([\s\S]*?)<\/[^>]*?:?href>/i.exec(block)?.[1]?.trim();
+            const data = /<[^>]*?:?calendar-data[^>]*>([\s\S]*?)<\/[^>]*?:?calendar-data>/i.exec(block)?.[1];
+            if (!data) continue;
+            for (const piece of decodeXml(data).split(/BEGIN:VEVENT/i).slice(1)) {
+                const ev = fromVevent(piece);
+                if (ev.summary || ev.start) out.push({ id: href, ...ev });
+            }
+        }
+        out.sort((x, y) => String(x.start).localeCompare(String(y.start)));
+        return out.slice(0, LIST_MAX).map((ev) => `${ev.id || '(no id)'}\n  ${fmtICal(ev.start)} — ${ev.summary || '(no title)'}${ev.location ? `  @ ${ev.location}` : ''}`);
+    }
+    async function googleRead(target, ctx, id) {
+        const url = /^https?:\/\//.test(id) ? id : new URL(id, CALDAV(userOf(target))).href;
+        const res = await dav(target, ctx, 'GET', url, { headers: { 'Content-Type': 'text/calendar' } });
+        if (res.status === 404) no('no such event');
+        if (!res.ok) no(`${target.title}: that event could not be read (${res.status})`);
+        return (await res.text()).slice(0, READ_MAX);
+    }
+
+    const verbs = {
+        /* Events in a window, soonest first. By default from now on (the next
+           events); `from`/`to` (ISO dates or datetimes) move it into the past or
+           future, so the agent can look at any week or month, not only what's next. */
+        async 'calendar.list'(target, a, ctx) {
+            const provider = providerOf(target);
+            const when = (s) => { const d = s ? new Date(s) : null; return d && !Number.isNaN(d.getTime()) ? d.toISOString() : null; };
+            const from = when(a.from) ?? new Date().toISOString();
+            const to = when(a.to) ?? new Date(new Date(from).getTime() + 365 * 86_400_000).toISOString();
+            /* Google over CalDAV (the REST API its client cannot use); Microsoft over Graph. */
+            if (provider === 'google') {
+                const items = await googleList(target, ctx, { from, to });
+                const text = items.length ? items.join('\n') : 'No event in that range.';
+                return { text, size: Buffer.byteLength(text) };
+            }
+            const api = API[provider];
+            const res = await call(target, ctx, 'GET', api.list(LIST_MAX, { from, to }));
+            if (!res.ok) no(`${target.title}: ${res.status} ${await bodyError(res)}`.trim());
+            const items = api.items(await res.json());
+            const text = items.length ? items.map(api.brief).join('\n') : 'No event in that range.';
+            return { text, size: Buffer.byteLength(text) };
+        },
+        /* One event in full, by its id. */
+        async 'calendar.read'(target, a, ctx) {
+            const provider = providerOf(target);
+            if (provider === 'google') { const text = await googleRead(target, ctx, String(a.id)); return { text, size: Buffer.byteLength(text) }; }
+            const api = API[provider];
+            const res = await call(target, ctx, 'GET', api.event(String(a.id)));
+            if (res.status === 404) no('no such event');
+            if (!res.ok) no(`${target.title}: ${res.status} ${await bodyError(res)}`.trim());
+            const text = JSON.stringify(await res.json(), null, 1).slice(0, READ_MAX);
+            return { text, size: Buffer.byteLength(text) };
+        },
+        /* Create an event. An act: the start and end are ISO times (a bare date is all-day). */
+        async 'calendar.create'(target, a, ctx) {
+            const api = API[providerOf(target)];
+            if (!a.title) no('an event needs a title');
+            if (!a.start || !a.end) no('an event needs a start and an end (ISO times, e.g. 2030-01-02T09:00:00Z)');
+            const res = await call(target, ctx, 'POST', api.create, api.body({ title: a.title, start: a.start, end: a.end, where: a.where }));
+            if (!res.ok) no(`${target.title}: the event was not created (${res.status} ${await bodyError(res)})`.trim());
+            const made = await res.json().catch(() => ({}));
+            return { text: `Created: ${a.title} (${a.start}). Its id is ${made.id ?? '(unknown)'}.`, size: 0 };
+        },
+        /* Join a file to an event. An act. Microsoft takes the bytes inline (Graph
+           fileAttachment); a Google calendar attach is a Drive link, added once the
+           files connector is in -- for now it is Microsoft only. */
+        async 'calendar.attach'(target, a, ctx) {
+            const provider = providerOf(target);
+            if (provider !== 'microsoft') no(`${target.title}: joining a file to an event is Microsoft-only for now`);
+            if (!a.id) no('attach needs the event id (from the list)');
+            if (!a.attach) no('attach needs the file (its base64 bytes)');
+            const att = { '@odata.type': '#microsoft.graph.fileAttachment', name: String(a.attachName || 'attachment'), contentBytes: String(a.attach) };
+            const res = await call(target, ctx, 'POST', `https://graph.microsoft.com/v1.0/me/events/${encodeURIComponent(String(a.id))}/attachments`, att);
+            if (!res.ok) no(`${target.title}: the file was not attached (${res.status} ${await bodyError(res)})`.trim());
+            return { text: `Attached ${a.attachName || 'the file'} to the event.`, size: 0 };
+        },
+    };
+
+    return {
+        name: 'calendar',
+        verbs: Object.keys(verbs),
+        run(verb, target, a, ctx) {
+            if (!verbs[verb]) no(`${verb} is not done by this connector`);
+            return verbs[verb](target, a, ctx);
+        },
+        close() { tokens.clear(); },
+        shutdown() { tokens.clear(); },
+    };
+}

package/host/connectors/contacts.mjs

@@ -0,0 +1,154 @@
+/* THE CONTACTS CONNECTOR: a person's address book (Google or Microsoft) reached by
+ * the keeper with a token the host holds and the agent never sees. Microsoft is a
+ * REST read over Graph; Google is CardDAV (the scope the Thunderbird client carries),
+ * so the host speaks a small REPORT and parses the returned vCards. Read only for now
+ * (list, read) -- looking someone up is the common need; writing contacts comes later.
+ * Inspired by the MIT Google/Microsoft MCP servers, reimplemented host-side.
+ *
+ *   target.config.provider   'google' or 'microsoft'
+ *   target.config.user       the email address (Google CardDAV needs it in the URL)
+ *   target.secrets.refresh   the NAME of the refresh token in the host's secret store
+ */
+import { no, Refused } from '../../server/verbs.mjs';
+import { refreshAccess, thunderbird, PROVIDERS } from '../oauth.mjs';
+
+const LIST_MAX = 50;
+
+/* A vCard's useful fields. Lines fold with a leading space; unfold first. */
+function fromVcard(text) {
+    const v = String(text).replace(/\r?\n[ \t]/g, '');
+    const one = (re) => { const m = re.exec(v); return m ? m[1].trim() : ''; };
+    const many = (re) => [...v.matchAll(re)].map((m) => m[1].trim()).filter(Boolean);
+    return { name: one(/^FN[^:\r\n]*:(.+)$/im), emails: many(/^EMAIL[^:\r\n]*:(.+)$/gim), tels: many(/^TEL[^:\r\n]*:(.+)$/gim) };
+}
+const brief = (id, c) => `${id}\n  ${c.name || '(no name)'}${c.emails.length ? `  <${c.emails.join(', ')}>` : ''}${c.tels.length ? `  tel ${c.tels.join(' ')}` : ''}`;
+const decodeXml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+
+/* Microsoft returns JSON: normalise one contact to the same shape. */
+const fromMs = (c) => ({ name: c.displayName || [c.givenName, c.surname].filter(Boolean).join(' '), emails: (c.emailAddresses ?? []).map((e) => e.address).filter(Boolean), tels: [c.mobilePhone, ...(c.businessPhones ?? []), ...(c.homePhones ?? [])].filter(Boolean) });
+
+export function contacts({ fetch: fetchImpl = globalThis.fetch } = {}) {
+    const tokens = new Map();
+    const providerOf = (target) => { const p = String(target.config?.provider ?? ''); if (!PROVIDERS[p] || !(p === 'google' || p === 'microsoft')) no(`${target.title}: set its provider to google or microsoft`); return p; };
+    const userOf = (target) => { const u = String(target.config?.user ?? '').trim(); if (!u) no(`${target.title}: set its email address`); return u; };
+
+    async function access(target, ctx) {
+        const provider = providerOf(target);
+        const cached = tokens.get(target.id);
+        if (cached && cached.exp > Date.now() + 60_000) return cached.value;
+        const refresh = await ctx.secret('refresh');
+        if (!refresh) no(`${target.title}: its refresh token is empty -- reconnect the account`);
+        const clientId = target.config?.clientId || thunderbird(provider).clientId;
+        const clientSecret = target.secrets?.secret ? await ctx.secret('secret') : thunderbird(provider).clientSecret;
+        let t;
+        try { t = await refreshAccess(provider, { clientId, clientSecret, refreshToken: refresh, fetch: fetchImpl }); }
+        catch (e) { if (e instanceof Refused) throw e; no(`${target.title}: the contacts must be reconnected (its authorisation was refused)`); }
+        tokens.set(target.id, { value: t.accessToken, exp: t.expiresAt });
+        return t.accessToken;
+    }
+    async function req(target, ctx, method, url, { headers = {}, body } = {}) {
+        const token = await access(target, ctx);
+        let res;
+        try { res = await fetchImpl(url, { method, headers: { Authorization: `Bearer ${token}`, ...headers }, ...(body !== undefined ? { body } : {}) }); }
+        catch (e) { if (e instanceof Refused) throw e; no(`${target.title}: cannot reach the address book`); }
+        if (res.status === 401 || res.status === 403) no(`${target.title}: not authorized -- reconnect the account (the contacts scope may be missing)`);
+        return res;
+    }
+
+    const CARDDAV = (user) => `https://www.googleapis.com/carddav/v1/principals/${encodeURIComponent(user)}/lists/default/`;
+    /* Listing all of a Google address book over CardDAV: an addressbook-query
+       needs a CARDDAV:filter (RFC 6352), and a match-all filter is awkward, so
+       enumerate the entries with a PROPFIND, then fetch their vCards with an
+       addressbook-multiget (both standard, and what Google accepts). */
+    const PROPFIND = '<?xml version="1.0" encoding="utf-8"?><D:propfind xmlns:D="DAV:"><D:prop><D:getetag/></D:prop></D:propfind>';
+    const hrefsIn = (xml) => [...xml.matchAll(/<[^>]*?:?href[^>]*>([\s\S]*?)<\/[^>]*?:?href>/gi)].map((m) => decodeXml(m[1].trim()));
+
+    async function googleList(target, ctx) {
+        const base = CARDDAV(userOf(target));
+        const basePath = (() => { try { return new URL(base).pathname.replace(/\/+$/, ''); } catch { return ''; } })();
+        const listed = await req(target, ctx, 'PROPFIND', base, { headers: { Depth: '1', 'Content-Type': 'application/xml; charset=utf-8' }, body: PROPFIND });
+        if (!listed.ok) no(`${target.title}: the address book could not be read (${listed.status})`);
+        /* The collection lists itself and its contacts; keep the entries, whatever
+           they are named (Google uses an id, not a .vcf suffix). A contact is any
+           href under the collection that is not the collection itself. */
+        const hrefs = hrefsIn(await listed.text()).filter((h) => {
+            const clean = h.replace(/[?#].*$/, '');
+            if (!clean || clean.endsWith('/')) return false;
+            let p; try { p = new URL(h, base).pathname.replace(/\/+$/, ''); } catch { p = clean.replace(/\/+$/, ''); }
+            return p !== basePath;
+        }).slice(0, LIST_MAX);
+        if (!hrefs.length) return [];
+        const body = `<?xml version="1.0" encoding="utf-8"?><C:addressbook-multiget xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav"><D:prop><D:getetag/><C:address-data/></D:prop>${hrefs.map((h) => `<D:href>${h.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</D:href>`).join('')}</C:addressbook-multiget>`;
+        const res = await req(target, ctx, 'REPORT', base, { headers: { Depth: '1', 'Content-Type': 'application/xml; charset=utf-8' }, body });
+        if (!res.ok) no(`${target.title}: the address book could not be read (${res.status})`);
+        const xml = await res.text();
+        const out = [];
+        const blocks = xml.split(/<[A-Za-z0-9]*:?response[\s>]/i).slice(1);
+        for (const block of blocks) {
+            const href = /<[^>]*?:?href[^>]*>([\s\S]*?)<\/[^>]*?:?href>/i.exec(block)?.[1]?.trim();
+            const data = /<[^>]*?:?address-data[^>]*>([\s\S]*?)<\/[^>]*?:?address-data>/i.exec(block)?.[1];
+            if (!data) continue;
+            const card = fromVcard(decodeXml(data));
+            if (card.name || card.emails.length) out.push(brief(href || '(no id)', card));
+            if (out.length >= LIST_MAX) break;
+        }
+        return out;
+    }
+
+    const verbs = {
+        /* The address book, briefly: name, emails, phones. */
+        async 'contacts.list'(target, a, ctx) {
+            const provider = providerOf(target);
+            if (provider === 'google') { const items = await googleList(target, ctx); const text = items.length ? items.join('\n') : 'No contact.'; return { text, size: Buffer.byteLength(text) }; }
+            const res = await req(target, ctx, 'GET', 'https://graph.microsoft.com/v1.0/me/contacts?$top=50&$select=id,displayName,givenName,surname,emailAddresses,mobilePhone,businessPhones,homePhones');
+            if (!res.ok) no(`${target.title}: the address book could not be read (${res.status})`);
+            const items = ((await res.json()).value ?? []).map((c) => brief(c.id, fromMs(c)));
+            const text = items.length ? items.join('\n') : 'No contact.';
+            return { text, size: Buffer.byteLength(text) };
+        },
+        /* One contact in full, by its id (the Microsoft id, or the Google CardDAV href). */
+        async 'contacts.read'(target, a, ctx) {
+            const provider = providerOf(target);
+            const id = String(a.id ?? '').trim();
+            if (!id) no('read needs the contact id');
+            if (provider === 'google') {
+                const url = /^https?:\/\//.test(id) ? id : `https://www.googleapis.com${id.startsWith('/') ? '' : '/'}${id}`;
+                const res = await req(target, ctx, 'GET', url, { headers: { 'Content-Type': 'text/vcard' } });
+                if (res.status === 404) no('no such contact');
+                if (!res.ok) no(`${target.title}: that contact could not be read (${res.status})`);
+                const text = (await res.text()).slice(0, 64 * 1024);
+                return { text, size: Buffer.byteLength(text) };
+            }
+            const res = await req(target, ctx, 'GET', `https://graph.microsoft.com/v1.0/me/contacts/${encodeURIComponent(id)}`);
+            if (res.status === 404) no('no such contact');
+            if (!res.ok) no(`${target.title}: that contact could not be read (${res.status})`);
+            const text = JSON.stringify(await res.json(), null, 1).slice(0, 64 * 1024);
+            return { text, size: Buffer.byteLength(text) };
+        },
+        /* Set a contact's photo. An act. Microsoft takes the image bytes (Graph);
+           a Google photo means editing the vCard (coming with contacts writing) --
+           Microsoft only for now. */
+        async 'contacts.attach'(target, a, ctx) {
+            const provider = providerOf(target);
+            if (provider !== 'microsoft') no(`${target.title}: setting a contact photo is Microsoft-only for now`);
+            const id = String(a.id ?? '').trim();
+            if (!id) no('attach needs the contact id');
+            if (!a.attach) no('attach needs the photo (its base64 bytes)');
+            const res = await req(target, ctx, 'PUT', `https://graph.microsoft.com/v1.0/me/contacts/${encodeURIComponent(id)}/photo/$value`, { headers: { 'Content-Type': 'image/jpeg' }, body: Buffer.from(String(a.attach), 'base64') });
+            if (res.status === 404) no('no such contact');
+            if (!res.ok) no(`${target.title}: the photo was not set (${res.status})`);
+            return { text: `Set the photo on ${id}.`, size: 0 };
+        },
+    };
+
+    return {
+        name: 'contacts',
+        verbs: Object.keys(verbs),
+        run(verb, target, a, ctx) {
+            if (!verbs[verb]) no(`${verb} is not done by this connector`);
+            return verbs[verb](target, a, ctx);
+        },
+        close() { tokens.clear(); },
+        shutdown() { tokens.clear(); },
+    };
+}

package/host/connectors/graphmail.mjs

@@ -0,0 +1,114 @@
+/* MICROSOFT MAIL OVER GRAPH, for the mail connector's Microsoft path.
+ *
+ * The borrowed Microsoft client (Thunderbird's) takes Graph scopes: its token
+ * reads mail, calendar and contacts over graph.microsoft.com. So a Microsoft
+ * mailbox is
+ * reached here over Graph REST, not IMAP -- the same six verbs the IMAP path
+ * gives (list, read, search, move, flag, send), reimplemented host-side so the
+ * token never leaves this process and the Tether levels gate the acts.
+ *
+ * `token(target, ctx)` mints a Graph access token from the target's refresh
+ * token (the mail connector passes its own `access`). `fetch` is injected for
+ * tests. Message ids are Graph's own opaque ids (long strings), used as the
+ * "uid" for read/move/flag.
+ */
+import { no } from '../../server/verbs.mjs';
+
+const GRAPH = 'https://graph.microsoft.com/v1.0';
+const LIST_MAX = 30;
+const READ_MAX = 512 * 1024;
+/* Friendly folder words mapped to Graph's well-known names; anything else is
+   passed through (a folder's own id or display name). */
+const FOLDER = { inbox: 'inbox', sent: 'sentitems', 'sent items': 'sentitems', drafts: 'drafts', draft: 'drafts', trash: 'deleteditems', deleted: 'deleteditems', 'deleted items': 'deleteditems', junk: 'junkemail', spam: 'junkemail', archive: 'archive' };
+const folderOf = (name) => { const n = String(name ?? '').trim(); if (!n) return 'inbox'; return FOLDER[n.toLowerCase()] ?? n; };
+
+const addrsOf = (list) => (list ?? []).map((r) => r?.emailAddress?.address).filter(Boolean).join(', ');
+const stripHtml = (html) => String(html ?? '')
+    .replace(/<\s*(script|style)[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, ' ')
+    .replace(/<\s*br\s*\/?\s*>/gi, '\n').replace(/<\s*\/\s*(p|div|li|tr|h[1-6])\s*>/gi, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/gi, ' ').replace(/&amp;/gi, '&').replace(/&lt;/gi, '<').replace(/&gt;/gi, '>').replace(/&quot;/gi, '"').replace(/&#39;/gi, "'")
+    .replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+
+export function graphMail({ fetch: fetchImpl = globalThis.fetch, token }) {
+    async function call(target, ctx, method, path, body) {
+        const access = await token(target, ctx);
+        const r = await fetchImpl(`${GRAPH}${path}`, {
+            method,
+            headers: { authorization: `Bearer ${access}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        if (r.status === 401 || r.status === 403) no(`${target.title}: not authorized -- reconnect the account (the Microsoft mail scope may be missing)`);
+        if (!r.ok) { let m = ''; try { m = (await r.json())?.error?.message ?? ''; } catch { /* no json */ } no(`${target.title}: ${m || `the mail request failed (${r.status})`}`); }
+        if (r.status === 204) return null;
+        return r.json();
+    }
+
+    const brief = (m) => `#${m.id}\n  ${m.receivedDateTime ?? ''}\n  From: ${addrsOf([m.from])}\n  Subject: ${m.subject ?? ''}`;
+
+    return {
+        async list(target, a, ctx) {
+            const folder = folderOf(a.mailbox);
+            const data = await call(target, ctx, 'GET', `/me/mailFolders/${encodeURIComponent(folder)}/messages?$top=${LIST_MAX}&$select=id,receivedDateTime,from,subject&$orderby=receivedDateTime%20desc`);
+            const items = (data?.value ?? []).map(brief);
+            const text = items.length ? items.join('\n') : 'No message.';
+            return { text, size: Buffer.byteLength(text) };
+        },
+        async read(target, a, ctx) {
+            const id = String(a.uid ?? '').trim();
+            if (!id) no('read needs the message id (from the list)');
+            const m = await call(target, ctx, 'GET', `/me/messages/${encodeURIComponent(id)}?$select=id,receivedDateTime,from,toRecipients,ccRecipients,subject,body,hasAttachments`);
+            const bodyText = m?.body?.contentType === 'html' ? stripHtml(m.body.content) : (m?.body?.content ?? '');
+            let att = '';
+            if (m?.hasAttachments) {
+                const at = await call(target, ctx, 'GET', `/me/messages/${encodeURIComponent(id)}/attachments?$select=name,contentType,size`);
+                att = (at?.value ?? []).map((x) => `  - ${x.name} (${x.contentType}, ${Math.round((x.size || 0) / 1024)} KB)`).join('\n');
+            }
+            const head = [`From: ${addrsOf([m.from])}`, `To: ${addrsOf(m.toRecipients)}`, m?.ccRecipients?.length ? `Cc: ${addrsOf(m.ccRecipients)}` : '', `Date: ${m.receivedDateTime ?? ''}`, `Subject: ${m.subject ?? ''}`].filter(Boolean).join('\n');
+            const text = `${head}\n\n${bodyText}${att ? `\n\nAttachments:\n${att}` : ''}`.slice(0, READ_MAX);
+            return { text, size: Buffer.byteLength(text) };
+        },
+        async search(target, a, ctx) {
+            const q = String(a.text ?? '').trim();
+            if (!q) no('search needs some text');
+            const data = await call(target, ctx, 'GET', `/me/messages?$search=${encodeURIComponent(`"${q}"`)}&$top=${LIST_MAX}&$select=id,receivedDateTime,from,subject`);
+            const items = (data?.value ?? []).map(brief);
+            const text = items.length ? items.join('\n') : 'Nothing found.';
+            return { text, size: Buffer.byteLength(text) };
+        },
+        async move(target, a, ctx) {
+            const id = String(a.uid ?? '').trim();
+            if (!id) no('move needs the message id');
+            if (!String(a.mailbox ?? '').trim()) no('move needs a destination folder');
+            await call(target, ctx, 'POST', `/me/messages/${encodeURIComponent(id)}/move`, { destinationId: folderOf(a.mailbox) });
+            return { text: `Moved ${id} to ${a.mailbox}.`, size: 0 };
+        },
+        async flag(target, a, ctx) {
+            const id = String(a.uid ?? '').trim();
+            if (!id) no('flag needs the message id');
+            const f = String(a.flag ?? '').toLowerCase().trim();
+            const body = f === 'read' ? { isRead: true } : f === 'unread' ? { isRead: false }
+                : f === 'flagged' ? { flag: { flagStatus: 'flagged' } } : f === 'unflagged' ? { flag: { flagStatus: 'notFlagged' } }
+                    : no('flag is read, unread, flagged or unflagged');
+            await call(target, ctx, 'PATCH', `/me/messages/${encodeURIComponent(id)}`, body);
+            return { text: `Marked ${id} ${f}.`, size: 0 };
+        },
+        async send(target, a, ctx) {
+            const to = String(a.to ?? '').split(',').map((x) => x.trim()).filter(Boolean);
+            if (!to.length) no('send needs a recipient (to)');
+            const cc = String(a.cc ?? '').split(',').map((x) => x.trim()).filter(Boolean);
+            /* A file joined to the message: its bytes, already base64 (what Graph
+               wants), and a name. One attachment for now (the common need). */
+            const attach = String(a.attach ?? '');
+            const message = {
+                subject: String(a.subject ?? ''),
+                body: { contentType: 'text', content: String(a.body ?? '') },
+                toRecipients: to.map((address) => ({ emailAddress: { address } })),
+                ...(cc.length ? { ccRecipients: cc.map((address) => ({ emailAddress: { address } })) } : {}),
+                ...(attach ? { attachments: [{ '@odata.type': '#microsoft.graph.fileAttachment', name: String(a.attachName || 'attachment'), contentBytes: attach }] } : {}),
+            };
+            await call(target, ctx, 'POST', '/me/sendMail', { message, saveToSentItems: true });
+            return { text: `Sent to ${to.join(', ')}${attach ? ` with ${a.attachName || 'an attachment'}` : ''}.`, size: 0 };
+        },
+    };
+}