@byokit/connect 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.4.0 (2026-10-12)
+
+- Dependency update: pins @byokit/secrets 0.5.1.
+
+- FEAT: One documented house Google client route: `googleClientFile(path)` in `@byokit/connect/node` reads Google's downloaded Desktop-app JSON (mode 600) for Gmail and every other Google preset, returns `null` when it is absent, and refuses a file other users can read, a non-regular file, or another client type.
+
+## 0.3.0 (2026-10-06)
+
+- Add approval-gated Gmail send (`MailSender`): one plain-text message per call, sent only after the host's approval returns `true` for that exact message.
+
+- Add typed Gmail read and search (`MailReader`) on a connection: envelopes, one bounded body, opaque page tokens.
+- Add owner-bound mail history and export (`MailHistory`): cross-page envelopes and `json`/`csv` export, foreign principals denied before any fetch.
+
 ## 0.2.0 (2026-10-01)
 
 - FIX: Preserve provider refresh-token lifetimes and sanitized OAuth error causes for setup guidance.

package/README.md

@@ -48,7 +48,7 @@ older flow; callbacks have a 15-minute deadline and can be used only once.
 Google requires the host's registered client. Use a Desktop client with loopback,
 or register the exact HTTPS/native redirect for that client. Presets keep Google's
 offline/consent parameters and request one service at a time: `google` (identity),
-`drive` (`drive.file`), `gmail` (read-only) and `calendar` (events). The host owns
+`drive` (`drive.file`), `gmail` (read-only; pass `scopes` to send) and `calendar` (events). The host owns
 Google consent-screen publishing and API enablement. The kit does not probe
 undocumented provider pages or impose a product-specific approval policy.
 
@@ -60,6 +60,44 @@ parameters. Options `scopes` override the preset/discovered scopes; security
 parameters (`state`, PKCE, response type, client and redirect) cannot be overridden
 through `extra`. A sign-in with explicitly incomplete granted scopes is not saved.
 
+## The house Google client
+
+One Google OAuth client serves every Google route the house runs: this kit's Gmail
+reader and sender, and Crewhouse's Google connections.
+
+- **Client:** type **Desktop app**, in the house's own Google Cloud project, with the
+  Gmail, Calendar and Drive APIs enabled. Desktop clients accept any loopback port, so
+  `connectLoopback` needs no redirect registration.
+- **Consent:** audience External, published (*In production*; *Testing* grants stop
+  after 7 days). The consent screen lists `gmail.readonly`, `gmail.send`,
+  `calendar.events` and `drive.file`. Each connection still asks for one service;
+  sending adds `gmail.send` through `scopes`.
+- **Secret:** the JSON Google offers to download, unchanged, at
+  `~/.config/byokit/google-oauth-client.json`, mode 600. Never in a repository, a log
+  or a test HOME.
+
+```ts
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { connectLoopback, googleClientFile } from '@byokit/connect/node';
+import type { Keystore } from '@byokit/secrets';
+
+declare const store: Keystore;
+declare const yourApp: { openExternal(url: string): Promise<void>; setUpGoogle(): never };
+
+const client = await googleClientFile(join(homedir(), '.config', 'byokit', 'google-oauth-client.json'));
+if (!client) yourApp.setUpGoogle(); // No file yet: Google is not set up on this computer.
+const attempt = await connectLoopback('gmail', { store, person: 'Umer', client,
+  scopes: ['https://www.googleapis.com/auth/gmail.readonly', 'https://www.googleapis.com/auth/gmail.send'],
+  open: url => yourApp.openExternal(url) });
+await attempt.done; // Then MailReader/MailSender on attempt.connection.
+```
+
+`googleClientFile(path)` reads only the path the host passes. It returns `null` when
+the file is absent, and refuses a file other users can read, a non-regular file
+at the path, or any client type other than Desktop app, with a plain message
+that never repeats the file's contents.
+
 ## Check app details and inspect grant lifetime
 
 ```ts
@@ -151,6 +189,60 @@ A 401 triggers one refresh/retry; redirects are refused. Close clients before
 `disconnect()` to release their streams. Arbitrary unauthenticated MCP servers and
 legacy HTTP+SSE transports are outside this sign-in kit's initial scope.
 
+## Read and search Gmail
+
+```ts
+import { connect, MailReader } from '@byokit/connect';
+import type { Keystore } from '@byokit/secrets';
+declare const store: Keystore;
+const gmail = connect('gmail', { store, person: 'Umer', redirectUri: 'https://your-app.example/connect/callback' });
+const mail = new MailReader(gmail, { maxBodyChars: 20_000 });
+const page = await mail.search('invoice'); // Gmail syntax; follow page.nextPageToken.
+const message = await mail.get(page.messages[0].id); // Envelope plus bounded body.
+```
+
+`search`/`list` return one page of envelopes; `get` adds the decoded body, cut at
+`maxBodyChars` (`body.truncated` says so). A 401 retries once, then reads as
+signed-out; rate limits carry `until` from `Retry-After`.
+
+## Send Gmail, one approval per message
+
+```ts
+import { connect, MailSender, type OutgoingMail } from '@byokit/connect';
+import type { Keystore } from '@byokit/secrets';
+declare const store: Keystore;
+declare function askPerson(mail: OutgoingMail): Promise<boolean>; // The host's own confirm step.
+const gmail = connect('gmail', { store, person: 'Umer', redirectUri: 'https://your-app.example/connect/callback',
+  scopes: ['https://www.googleapis.com/auth/gmail.send'] });
+const sender = new MailSender(gmail, mail => askPerson(mail));
+const sent = await sender.send({ to: 'crew@example.test', subject: 'Invoice paid', body: 'Thanks, Umer' });
+```
+
+Sending needs the `gmail.send` scope, requested through `scopes` (a grant without it
+fails sign-in with `scope`). Every `send` asks the approval once with the frozen
+message it will encode; only `true` sends, and anything else, including a throw,
+is `MailError` code `denied` before any token or provider call. One message per
+call: no batching, queue, retry or background send. A network failure leaves the
+outcome unknown, so check Sent before asking to send again. Plain-text bodies to
+bare addresses only: no cc/bcc, display names, HTML, attachments, replies in a
+thread or labels.
+
+## Owner-bound history and export
+
+```ts
+import { MailHistory, type Connection } from '@byokit/connect';
+declare const gmail: Connection; // Signed in for Umer.
+const history = new MailHistory(gmail, { owner: 'Umer' });
+const rows = await history.messages({ principal: 'Umer', query: 'invoice' });
+const csv = await history.export({ principal: 'Umer', query: 'invoice', format: 'csv' }); // Or 'json'.
+```
+
+The host binds `owner` once; every call names its `principal` and anything else
+is denied (`HistoryError` code `denied`) before any provider fetch. Retrieval
+pages through `search`/`list` up to `maxMessages` (default 100, at most 500).
+Export writes envelopes only — message bodies are never exported. Provider
+failures keep their `MailError` code, `status` and `until` under `HistoryError`.
+
 ## Refresh, errors and storage
 
 Refresh runs when the token is within one minute of expiry, or after a 401. It is
@@ -221,13 +313,13 @@ the connection handle; never persist its returned access token separately.
 ## Crewhouse adoption
 
 Replace the OAuth, token-file and `RemoteMcp` portions of `src/connections.ts` with
-one handle per member/app. Pass the member's keystore and member ID, the host's
-registered Google client when applicable, and Crewhouse's callback address. Keep
+one handle per member/app. Pass the member's keystore and member ID, the house Google
+client from `googleClientFile` when applicable, and Crewhouse's callback address. Keep
 flow handles in the host's callback routing table until completion/cancellation.
 Crewhouse retains its own connection screen, Google setup guidance and tool gates.
 For remote apps, call `mcp()` and use `listTools`/`callTool` with their full results;
-for Gmail/Calendar use `token()` until their typed kits sit on this connection.
-No raw OAuth, refresh or MCP transport needs to remain in the consumer.
+for Gmail use `MailReader`/`MailSender` below; for Calendar use `token()` until its typed kit
+sits on this connection. No raw OAuth, refresh or MCP transport needs to remain in the consumer.
 
 ## Verification
 
@@ -237,8 +329,11 @@ npm run check
 sh scripts/test.sh 'packages/connect/test/*.test.ts'
 ```
 
-Tests use fake providers and a real loopback callback only. They cover PKCE/state,
-replay/cancel/expiry, discovery/DCR/resource binding, refresh races and revocation,
-per-person isolation, rich MCP JSON/SSE responses and browser bundling. No real
-accounts or outbound network calls are used. Live provider/device sign-ins are not
-claimed by these tests.
+`packages/connect/test/journey-connect.test.ts` drives the built package the way a
+host app does — `connect`/`signIn`/`token`/`mcp`, the loopback listener, the house
+Google client, `MailReader`/`MailSender` and `MailHistory`. Fake providers and a real
+loopback callback only. It covers PKCE/state and exact-callback binding, per-person
+isolation, refresh races and revocation, discovery/DCR/resource binding, rich MCP
+JSON/SSE responses, the approved/denied send, owner-bound history and browser
+bundling. No real accounts or outbound network calls are used. Live
+provider/device sign-ins are not claimed by these tests.

package/SECURITY.md

@@ -2,7 +2,8 @@
 
 The host supplies a keystore and person identifier. Scope it to the person and app on
 this device. Tokens and dynamic client credentials are written only to that store;
-the kit never reads ambient accounts, environment keys or credential files. No
+the kit never reads ambient accounts, environment keys or credential files. The only
+file it reads is the Google client file at the path the host passes to `googleClientFile`. No
 server pool or account sharing is provided. Connection keys are fixed-length SHA-256 names over person, provider,
 resource, issuer/token endpoint and configured client ID. Long identities therefore
 fit every keystore backend without exposing those identities in keyring labels.

package/dist/history.d.ts

@@ -0,0 +1,40 @@
+import { type MailCredential, type MailEnvelope, type MailReaderOptions } from './mail.ts';
+export type HistoryFormat = 'json' | 'csv';
+export type HistoryErrorCode = 'denied' | 'invalid' | 'network' | 'signed-out' | 'rate-limited';
+export declare class HistoryError extends Error {
+    readonly code: HistoryErrorCode;
+    readonly status?: number;
+    readonly until?: number;
+    constructor(code: HistoryErrorCode, message: string, o?: {
+        status?: number;
+        until?: number;
+        cause?: unknown;
+    });
+}
+export interface MailHistoryOptions extends MailReaderOptions {
+    /** Person the host seated this credential for; all other principals are denied. */
+    owner: string;
+}
+export interface HistoryQuery {
+    principal: string;
+    /** Gmail search syntax; absent lists recent mail. */
+    query?: string;
+    /** Envelopes collected across pages, default 100, at most 500. */
+    maxMessages?: number;
+    /** Provider page size, 1..500, default 20. */
+    pageSize?: number;
+    signal?: AbortSignal;
+}
+export interface HistoryExportQuery extends HistoryQuery {
+    format: HistoryFormat;
+}
+export declare class MailHistory {
+    private reader;
+    private owner;
+    constructor(credential: MailCredential, options: MailHistoryOptions);
+    private allow;
+    /** Envelopes across pages, oldest page token first, cut at `maxMessages`. */
+    messages(query: HistoryQuery): Promise<MailEnvelope[]>;
+    /** `json` array or `csv` rows of the same envelopes; bodies are never exported. */
+    export(query: HistoryExportQuery): Promise<string>;
+}

package/dist/history.js

@@ -0,0 +1,82 @@
+// Owner-bound mail history and export. The credential (a Connection) stays the
+// only authentication; every call names its principal and anything but the bound
+// owner is denied before any provider fetch. This module never sends.
+import { MailReader, MailError } from "./mail.js";
+export class HistoryError extends Error {
+    code;
+    status;
+    until;
+    constructor(code, message, o = {}) {
+        super(message, o.cause === undefined ? undefined : { cause: o.cause });
+        this.name = 'HistoryError';
+        this.code = code;
+        if (o.status !== undefined)
+            this.status = o.status;
+        if (o.until !== undefined)
+            this.until = o.until;
+    }
+}
+const MAX_MESSAGES = 500;
+const int = (value, fallback, what) => {
+    const n = value ?? fallback;
+    if (!Number.isInteger(n) || n < 1 || n > MAX_MESSAGES)
+        throw new RangeError(`mail history ${what} is 1..500`);
+    return n;
+};
+const cell = (value) => /[",\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+function toCsv(rows) {
+    const lines = ['id,threadId,subject,from,to,date,snippet,labelIds'];
+    for (const m of rows)
+        lines.push([m.id, m.threadId, m.subject, m.from, m.to, m.date, m.snippet, m.labelIds.join('|')].map(cell).join(','));
+    return `${lines.join('\n')}\n`;
+}
+export class MailHistory {
+    reader;
+    owner;
+    constructor(credential, options) {
+        if (!credential || typeof credential.token !== 'function')
+            throw new TypeError('mail history needs a credential with token()');
+        if (!options || typeof options.owner !== 'string' || !options.owner.trim())
+            throw new TypeError('mail history needs a non-empty owner');
+        this.owner = options.owner;
+        this.reader = new MailReader(credential, options);
+    }
+    allow(principal) {
+        if (typeof principal !== 'string' || !principal)
+            throw new TypeError('mail history needs a non-empty principal');
+        if (principal !== this.owner)
+            throw new HistoryError('denied', 'mail history is not shared with this principal');
+        return principal;
+    }
+    /** Envelopes across pages, oldest page token first, cut at `maxMessages`. */
+    async messages(query) {
+        this.allow(query?.principal);
+        const { query: q, signal } = query ?? {};
+        if (q !== undefined && (typeof q !== 'string' || !q.trim()))
+            throw new TypeError('mail history needs a non-empty query');
+        const max = int(query?.maxMessages, 100, 'maxMessages'), size = int(query?.pageSize, 20, 'pageSize');
+        const rows = [];
+        let pageToken;
+        try {
+            do {
+                const page = q ? await this.reader.search(q.trim(), { maxResults: size, ...(pageToken ? { pageToken } : {}), ...(signal ? { signal } : {}) })
+                    : await this.reader.list({ maxResults: size, ...(pageToken ? { pageToken } : {}), ...(signal ? { signal } : {}) });
+                rows.push(...page.messages);
+                pageToken = rows.length < max ? page.nextPageToken : undefined;
+            } while (pageToken);
+        }
+        catch (error) {
+            if (error instanceof MailError)
+                throw new HistoryError(error.code, `mail history ${error.code === 'signed-out' ? 'sign-in is gone or refused' : 'provider failed'}`, { ...(error.status !== undefined ? { status: error.status } : {}), ...(error.until !== undefined ? { until: error.until } : {}) });
+            throw error;
+        }
+        return rows.slice(0, max);
+    }
+    /** `json` array or `csv` rows of the same envelopes; bodies are never exported. */
+    async export(query) {
+        if (query?.format !== 'json' && query?.format !== 'csv')
+            throw new TypeError('mail history export format is json or csv');
+        const rows = await this.messages(query);
+        return query.format === 'json' ? JSON.stringify(rows, null, 2) : toCsv(rows);
+    }
+}

package/dist/index.d.ts

@@ -2,6 +2,10 @@ export { connect, Connection } from './connect.ts';
 export { providers } from './providers.ts';
 export type { ProviderId } from './providers.ts';
 export { ConnectError } from './errors.ts';
+export { MailReader, MailSender, MailError } from './mail.ts';
+export { MailHistory, HistoryError } from './history.ts';
+export type { HistoryFormat, HistoryErrorCode, MailHistoryOptions, HistoryQuery, HistoryExportQuery } from './history.ts';
+export type { MailErrorCode, MailCredential, MailReaderOptions, MailEnvelope, MailBody, MailMessage, MailPage, MailListOptions, MailGetOptions, MailSenderOptions, MailDraft, OutgoingMail, MailApproval, MailSendOptions, SentMail } from './mail.ts';
 export type { ConnectErrorCode, ProviderErrorCause } from './errors.ts';
 export type { Provider, OAuthClient, OAuthEndpoints, ConnectOptions, SignIn, McpOptions, Grant, ClientVerification } from './types.ts';
 export { Client } from '@modelcontextprotocol/sdk/client/index.js';

package/dist/index.js

@@ -1,6 +1,8 @@
 export { connect, Connection } from "./connect.js";
 export { providers } from "./providers.js";
 export { ConnectError } from "./errors.js";
+export { MailReader, MailSender, MailError } from "./mail.js";
+export { MailHistory, HistoryError } from "./history.js";
 // Expose the pinned engine for typed protocol pass-through without a second SDK pin.
 export { Client } from '@modelcontextprotocol/sdk/client/index.js';
 export * from '@modelcontextprotocol/sdk/types.js';

package/dist/mail.d.ts

@@ -0,0 +1,108 @@
+/** Why a read, search or send failed. `message` is for logs; never show it to a person. */
+export type MailErrorCode = 'invalid' | 'network' | 'signed-out' | 'rate-limited' | 'denied';
+export declare class MailError extends Error {
+    readonly code: MailErrorCode;
+    readonly status?: number;
+    readonly until?: number;
+    constructor(code: MailErrorCode, message: string, o?: {
+        status?: number;
+        until?: number;
+        cause?: unknown;
+    });
+}
+/** The only credential a reader or sender needs. `Connection` satisfies this structurally. */
+export interface MailCredential {
+    token(rejectedAccessToken?: string): Promise<string>;
+}
+export interface MailSenderOptions {
+    userId?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+export interface MailReaderOptions extends MailSenderOptions {
+    maxBodyChars?: number;
+}
+/** One message. `to` is one or more bare addresses (`name@host`); the sender is the signed-in mailbox. */
+export interface MailDraft {
+    to: string | readonly string[];
+    subject: string;
+    body: string;
+}
+/** Exactly what will be sent, frozen: the approval sees the same object the send encodes. */
+export interface OutgoingMail {
+    readonly to: readonly string[];
+    readonly subject: string;
+    readonly body: string;
+}
+/** Asked once per message, before any token or provider call. Only `true` sends; anything else, or a throw, denies. */
+export type MailApproval = (mail: OutgoingMail) => boolean | Promise<boolean>;
+export interface MailSendOptions {
+    signal?: AbortSignal;
+}
+export interface SentMail {
+    id: string;
+    threadId: string;
+    labelIds: readonly string[];
+}
+/** Headers plus snippet. Absent headers read as `''`. */
+export interface MailEnvelope {
+    id: string;
+    threadId: string;
+    subject: string;
+    from: string;
+    to: string;
+    date: string;
+    snippet: string;
+    labelIds: readonly string[];
+}
+/** Decoded `text/plain` body. `text/html`-only mail reads as `''`; the snippet still shows. */
+export interface MailBody {
+    text: string;
+    truncated: boolean;
+}
+export interface MailMessage extends MailEnvelope {
+    body: MailBody;
+}
+/** One page. `nextPageToken` is absent on the last page. */
+export interface MailPage {
+    messages: MailEnvelope[];
+    nextPageToken?: string;
+    resultSizeEstimate?: number;
+}
+export interface MailListOptions {
+    maxResults?: number;
+    pageToken?: string;
+    signal?: AbortSignal;
+}
+export interface MailGetOptions {
+    signal?: AbortSignal;
+}
+declare class Gmail {
+    private credential;
+    private userId;
+    private fetcher;
+    private now;
+    constructor(kind: string, credential: MailCredential, options: MailSenderOptions);
+    /** GET with `params`, or POST `body` as JSON. A 401 retries once with a fresh token. */
+    protected call(path: string, params: Record<string, string | readonly string[]>, signal?: AbortSignal, body?: unknown): Promise<unknown>;
+}
+export declare class MailReader extends Gmail {
+    private maxBodyChars;
+    constructor(credential: MailCredential, options?: MailReaderOptions);
+    /** `q` is Gmail search syntax. */
+    search(query: string, options?: MailListOptions): Promise<MailPage>;
+    list(options?: MailListOptions): Promise<MailPage>;
+    /** Envelope plus the body, decoded and cut at `maxBodyChars`. */
+    get(id: string, options?: MailGetOptions): Promise<MailMessage>;
+    private page;
+    private envelope;
+    private bodyText;
+}
+/** Sends one message at a time from the signed-in Gmail, each only after its own approval. Needs `gmail.send`. */
+export declare class MailSender extends Gmail {
+    private approve;
+    constructor(credential: MailCredential, approve: MailApproval, options?: MailSenderOptions);
+    /** Asks the approval with the frozen message, then sends it once. Never retried: a failed send asks again. */
+    send(draft: MailDraft, options?: MailSendOptions): Promise<SentMail>;
+}
+export {};

package/dist/mail.js

@@ -0,0 +1,263 @@
+export class MailError extends Error {
+    code;
+    status;
+    until;
+    constructor(code, message, o = {}) {
+        super(message, o.cause === undefined ? undefined : { cause: o.cause });
+        this.name = 'MailError';
+        this.code = code;
+        if (o.status !== undefined)
+            this.status = o.status;
+        if (o.until !== undefined)
+            this.until = o.until;
+    }
+}
+const API = 'https://gmail.googleapis.com/gmail/v1';
+const MAX_RESULTS = 500;
+const HEADERS = ['Subject', 'From', 'To', 'Date'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function mailShape(what) { return new MailError('invalid', `mail provider answered outside its shape (${what})`); }
+function field(value, what) {
+    if (typeof value !== 'string')
+        throw mailShape(what);
+    return value;
+}
+/** Base64url without `Buffer`, so the reader stays portable. */
+function decodeBase64Url(data) {
+    const abc = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    const clean = data.replace(/=+$/, '');
+    const out = new Uint8Array(Math.floor(clean.length * 3 / 4) + 1);
+    let n = 0, bits = 0, acc = 0;
+    for (const ch of clean) {
+        const v = abc.indexOf(ch);
+        if (v < 0)
+            throw mailShape('body data');
+        acc = (acc << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[n++] = (acc >> bits) & 255;
+        }
+    }
+    return new TextDecoder().decode(out.subarray(0, n));
+}
+class Gmail {
+    credential;
+    userId;
+    fetcher;
+    now;
+    constructor(kind, credential, options) {
+        if (!credential || typeof credential.token !== 'function')
+            throw new TypeError(`${kind} needs a credential with token()`);
+        const { userId = 'me', fetch, now = Date.now } = options ?? {};
+        if (typeof userId !== 'string' || !userId.trim())
+            throw new TypeError(`${kind} needs a non-empty userId`);
+        this.credential = credential;
+        this.userId = userId;
+        this.fetcher = fetch ?? globalThis.fetch;
+        this.now = now;
+    }
+    /** GET with `params`, or POST `body` as JSON. A 401 retries once with a fresh token. */
+    async call(path, params, signal, body) {
+        signal?.throwIfAborted();
+        const refused = (cause) => new MailError('signed-out', 'mail credential refused', { cause });
+        const send = async (access) => {
+            const url = new URL(`${API}/users/${encodeURIComponent(this.userId)}${path}`);
+            for (const [key, value] of Object.entries(params))
+                for (const v of Array.isArray(value) ? value : [value])
+                    url.searchParams.append(key, v);
+            try {
+                return await this.fetcher(url, body === undefined ? { headers: { authorization: `Bearer ${access}` }, signal }
+                    : { method: 'POST', headers: { authorization: `Bearer ${access}`, 'content-type': 'application/json' }, body: JSON.stringify(body), signal });
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                throw new MailError('network', 'mail provider could not be reached', { cause: error });
+            }
+        };
+        const access = await this.credential.token().catch(cause => { throw refused(cause); });
+        let res = await send(access);
+        if (res.status === 401)
+            res = await send(await this.credential.token(access).catch(cause => { throw refused(cause); }));
+        if (res.status === 401 || res.status === 403)
+            throw new MailError('signed-out', 'mail sign-in is gone or refused', { status: res.status });
+        if (res.status === 429) {
+            const after = Number(res.headers.get('retry-after'));
+            const until = Number.isFinite(after) && after >= 0 ? this.now() + after * 1000 : undefined;
+            throw new MailError('rate-limited', 'mail provider is rate limited', { status: 429, ...(until === undefined ? {} : { until }) });
+        }
+        if (!res.ok)
+            throw new MailError('network', `mail provider answered HTTP ${res.status}`, { status: res.status });
+        try {
+            return await res.json();
+        }
+        catch (error) {
+            throw new MailError('invalid', 'mail provider answered outside its shape (json)', { cause: error });
+        }
+    }
+}
+export class MailReader extends Gmail {
+    maxBodyChars;
+    constructor(credential, options = {}) {
+        super('MailReader', credential, options);
+        const { maxBodyChars = 20_000 } = options ?? {};
+        if (!Number.isInteger(maxBodyChars) || maxBodyChars <= 0)
+            throw new RangeError('MailReader maxBodyChars must be a positive integer');
+        this.maxBodyChars = maxBodyChars;
+    }
+    /** `q` is Gmail search syntax. */
+    async search(query, options = {}) {
+        if (typeof query !== 'string' || !query.trim())
+            throw new TypeError('mail search needs a non-empty query');
+        return this.page({ q: query.trim() }, options);
+    }
+    async list(options = {}) {
+        return this.page({}, options);
+    }
+    /** Envelope plus the body, decoded and cut at `maxBodyChars`. */
+    async get(id, options = {}) {
+        if (typeof id !== 'string' || !id)
+            throw new TypeError('mail message id must be a non-empty string');
+        const json = await this.call(`/messages/${encodeURIComponent(id)}`, { format: 'full' }, options.signal);
+        const text = this.bodyText(isRecord(json) && isRecord(json.payload) ? json.payload : {});
+        const truncated = text.length > this.maxBodyChars;
+        return { ...this.envelope(json), body: { text: truncated ? text.slice(0, this.maxBodyChars) : text, truncated } };
+    }
+    async page(extra, options) {
+        const { maxResults = 20, pageToken, signal } = options ?? {};
+        if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > MAX_RESULTS)
+            throw new RangeError('mail maxResults is 1..500');
+        if (pageToken !== undefined && typeof pageToken !== 'string')
+            throw new TypeError('mail pageToken must be a string');
+        const params = { maxResults: String(maxResults), ...extra };
+        if (pageToken)
+            params.pageToken = pageToken;
+        const json = await this.call('/messages', params, signal);
+        if (!isRecord(json))
+            throw mailShape('list');
+        if (json.messages !== undefined && !Array.isArray(json.messages))
+            throw mailShape('list');
+        const messages = [];
+        for (const item of json.messages ?? []) {
+            if (!isRecord(item))
+                throw mailShape('list');
+            messages.push(this.envelope(await this.call(`/messages/${encodeURIComponent(field(item.id, 'message id'))}`, { format: 'metadata', metadataHeaders: HEADERS }, signal)));
+        }
+        const token = json.nextPageToken, size = json.resultSizeEstimate;
+        if (token !== undefined && (typeof token !== 'string' || !token))
+            throw mailShape('list');
+        if (size !== undefined && typeof size !== 'number')
+            throw mailShape('list');
+        return { messages, ...(typeof token === 'string' && token ? { nextPageToken: token } : {}),
+            ...(typeof size === 'number' ? { resultSizeEstimate: size } : {}) };
+    }
+    envelope(json) {
+        if (!isRecord(json))
+            throw mailShape('message');
+        const headers = isRecord(json.payload) && Array.isArray(json.payload.headers) ? json.payload.headers : [];
+        const find = (name) => {
+            for (const h of headers)
+                if (isRecord(h) && typeof h.name === 'string' && h.name.toLowerCase() === name.toLowerCase())
+                    return typeof h.value === 'string' ? h.value : '';
+            return '';
+        };
+        const rawLabels = json.labelIds;
+        const labelIds = Array.isArray(rawLabels) && rawLabels.every(v => typeof v === 'string') ? [...rawLabels] : [];
+        return { id: field(json.id, 'id'), threadId: field(json.threadId, 'threadId'),
+            subject: find('Subject'), from: find('From'), to: find('To'), date: find('Date'),
+            snippet: typeof json.snippet === 'string' ? json.snippet : '', labelIds };
+    }
+    bodyText(part) {
+        if (!isRecord(part))
+            return '';
+        const texts = [];
+        if (part.mimeType === 'text/plain' && isRecord(part.body) && typeof part.body.data === 'string' && part.body.data)
+            texts.push(decodeBase64Url(part.body.data));
+        if (Array.isArray(part.parts))
+            for (const child of part.parts)
+                texts.push(this.bodyText(child));
+        return texts.join('\n');
+    }
+}
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** Base64 without `Buffer`, so the sender stays portable. */
+function encodeBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const n = bytes[i] << 16 | (bytes[i + 1] ?? 0) << 8 | (bytes[i + 2] ?? 0);
+        out += B64[n >> 18 & 63] + B64[n >> 12 & 63] + (i + 1 < bytes.length ? B64[n >> 6 & 63] : '=') + (i + 2 < bytes.length ? B64[n & 63] : '=');
+    }
+    return out;
+}
+const utf8 = (text) => new TextEncoder().encode(text);
+const ADDRESS = /^[^\s@<>()[\]\\,;:"]+@[^\s@<>()[\]\\,;:"]+\.[^\s@<>()[\]\\,;:".]+$/;
+/** Validates and freezes one draft; rejects header injection and anything but bare addresses. */
+function outgoing(draft) {
+    if (!isRecord(draft))
+        throw new TypeError('mail send takes one draft object');
+    const { to: rawTo, subject, body } = draft;
+    // Copy first, then check the copy: the approval and the send see exactly what was checked.
+    const to = typeof rawTo === 'string' ? [rawTo] : Array.isArray(rawTo) ? Array.from(rawTo) : [];
+    if (!to.length || !to.every(a => typeof a === 'string' && ADDRESS.test(a)))
+        throw new TypeError('mail to must be one or more bare addresses');
+    if (typeof subject !== 'string' || /[\r\n]/.test(subject))
+        throw new TypeError('mail subject must be one line of text');
+    if (typeof body !== 'string')
+        throw new TypeError('mail body must be text');
+    return Object.freeze({ to: Object.freeze(to), subject, body });
+}
+/** RFC 2047 encoded words of at most 45 bytes each, so no word splits a character. Plain only when
+ *  a reader cannot decode it differently (`=?`) and the line stays short. */
+function headerText(text) {
+    if (/^[\x20-\x7e]*$/.test(text) && !text.includes('=?') && text.length <= 900)
+        return text;
+    const words = [];
+    let chunk = '';
+    for (const ch of text) {
+        if (utf8(chunk + ch).length > 45) {
+            words.push(chunk);
+            chunk = '';
+        }
+        chunk += ch;
+    }
+    words.push(chunk);
+    return words.map(w => `=?UTF-8?B?${encodeBase64(utf8(w))}?=`).join('\r\n ');
+}
+function mime(mail) {
+    const body = encodeBase64(utf8(mail.body.replace(/\r?\n/g, '\r\n'))).replace(/.{76}/g, '$&\r\n');
+    return [`To: ${mail.to.join(', ')}`, `Subject: ${headerText(mail.subject)}`, 'MIME-Version: 1.0',
+        'Content-Type: text/plain; charset=UTF-8', 'Content-Transfer-Encoding: base64', '', body].join('\r\n');
+}
+/** Sends one message at a time from the signed-in Gmail, each only after its own approval. Needs `gmail.send`. */
+export class MailSender extends Gmail {
+    approve;
+    constructor(credential, approve, options = {}) {
+        super('MailSender', credential, options);
+        if (typeof approve !== 'function')
+            throw new TypeError('MailSender needs an approval function');
+        this.approve = approve;
+    }
+    /** Asks the approval with the frozen message, then sends it once. Never retried: a failed send asks again. */
+    async send(draft, options = {}) {
+        const mail = outgoing(draft);
+        options.signal?.throwIfAborted();
+        let approved;
+        try {
+            approved = await this.approve(mail);
+        }
+        catch (cause) {
+            throw new MailError('denied', 'mail send was not approved', { cause });
+        }
+        if (approved !== true)
+            throw new MailError('denied', 'mail send was not approved');
+        const raw = encodeBase64(utf8(mime(mail))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+        const json = await this.call('/messages/send', {}, options.signal, { raw });
+        if (!isRecord(json))
+            throw mailShape('sent');
+        const labels = json.labelIds;
+        return { id: field(json.id, 'id'), threadId: field(json.threadId, 'threadId'),
+            labelIds: Array.isArray(labels) && labels.every(v => typeof v === 'string') ? [...labels] : [] };
+    }
+}

package/dist/node.d.ts

@@ -1,5 +1,5 @@
 import { type Connection } from './connect.ts';
-import type { ConnectOptions, Provider } from './types.ts';
+import type { ConnectOptions, OAuthClient, Provider } from './types.ts';
 import type { ProviderId } from './providers.ts';
 export interface LoopbackOptions extends Omit<ConnectOptions, 'redirectUri'> {
     /** Host opens the browser; BYOKit never spawns the person's browser or CLI. */
@@ -11,3 +11,6 @@ export declare function connectLoopback(target: ProviderId | Provider | string,
     done: Promise<void>;
     cancel(): void;
 }>;
+/** Reads the house Google client: the Desktop-app JSON downloaded from Google, at the path the host names.
+ * Absent file is `null` (Google not set up); a file other users can read, a non-regular file, or any other client type, is refused. */
+export declare function googleClientFile(path: string): Promise<OAuthClient | null>;

package/dist/node.js

@@ -1,5 +1,7 @@
 import WORDS from './words.json' with { type: 'json' };
 import { createServer } from 'node:http';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
 import { connect } from "./connect.js";
 import { ConnectError } from "./errors.js";
 /** One-shot loopback listener on an OS-assigned port; closes on completion, cancel or timeout. */
@@ -87,3 +89,38 @@ export async function connectLoopback(target, options) {
         throw error;
     }
 }
+/** Reads the house Google client: the Desktop-app JSON downloaded from Google, at the path the host names.
+ * Absent file is `null` (Google not set up); a file other users can read, a non-regular file, or any other client type, is refused. */
+export async function googleClientFile(path) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        const info = await file.stat();
+        // Non-blocking open: a FIFO at the path is refused here instead of hanging.
+        if (!info.isFile())
+            throw new Error(WORDS.clientFile.shape);
+        if (process.platform !== 'win32' && info.mode & 0o077)
+            throw new Error(WORDS.clientFile.mode);
+        let installed;
+        try {
+            installed = JSON.parse(await file.readFile('utf8'))?.installed;
+        }
+        catch {
+            throw new Error(WORDS.clientFile.shape);
+        }
+        const id = installed?.client_id, secret = installed?.client_secret;
+        if (typeof id !== 'string' || !/^[\w-]+\.apps\.googleusercontent\.com$/.test(id) || typeof secret !== 'string' || !secret)
+            throw new Error(WORDS.clientFile.shape);
+        return { id, secret };
+    }
+    finally {
+        await file.close();
+    }
+}

package/dist/words.json

@@ -18,6 +18,10 @@
         "connected": "Connected. You can return to the app.",
         "failed": "Sign-in did not finish. Return to the app and try again."
     },
+    "clientFile": {
+        "mode": "Your Google app file can be read by other people on this computer. Make it private to you.",
+        "shape": "Your Google app file is not a Desktop app downloaded from Google. Download it again."
+    },
     "verification": {
         "valid": "Your app details work.",
         "invalid": "Check your app details and try again.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/connect",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Connect a person's third-party apps with PKCE, refresh and typed remote MCP.",
   "license": "Apache-2.0",
   "type": "module",
@@ -37,6 +37,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.31.0",
-    "@byokit/secrets": "0.5.0"
+    "@byokit/secrets": "0.5.1"
   }
 }