@byokit/connect 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 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.
+- Add a client-details check without a user grant, with plain outcomes for accepted, rejected and uncertain replies.
+
 ## 0.1.0 (2026-10-01)
 
 

package/README.md

@@ -24,7 +24,7 @@ import type { Keystore } from '@byokit/secrets';
 declare const store: Keystore;
 const drive = connect('drive', {
   store,
-  person: 'person-42',
+  person: 'Umer',
   redirectUri: 'https://your-app.example/connect/callback',
   client: { id: 'your-google-client-id', secret: 'your-google-client-secret' },
 });
@@ -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,75 @@ 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
+import type { Connection } from '@byokit/connect';
+
+declare const drive: Connection;
+declare const enteredClientId: string;
+declare const enteredClientSecret: string;
+
+const check = await drive.verifyClient(); // Uses options.client.
+// Or check newly entered details without changing the saved connection:
+const entered = await drive.verifyClient({ id: enteredClientId, secret: enteredClientSecret });
+const grant = await drive.grant(); // Trusted app code only; contains credentials.
+```
+
+`grant()` returns a snapshot or `null` and makes no provider call. Times are Unix
+milliseconds. `refreshTokenExpiresIn` preserves the provider's
+`refresh_token_expires_in` seconds; `refreshTokenExpiresAt` is its absolute deadline.
+Sign-in/refresh responses calculate the deadline when received, and omitted refresh
+lifetime fields retain the previous deadline. Expired refresh grants require
+sign-in without sending another refresh request.
+
+`verifyClient(client?)` uses the selected token endpoint with a deliberately
+nonexistent refresh grant, without reading or changing the person's grant. For
+Google, `invalid_client` yields `outcome: 'invalid'`; a 400 `invalid_grant` yields
+`'valid'`; network failures and all other replies yield `'inconclusive'`. Each
+outcome includes a plain `message`; failed provider replies may carry the same
+sanitized diagnostic `cause` as `ConnectError`. A secret is required. This checks
+client authentication only; it does not check consent-screen publishing, enabled
+APIs, redirect registration or scopes. Tests use injected fake endpoints only.
+
 ## Loopback on a computer
 
 ```ts
@@ -70,7 +139,7 @@ declare const store: Keystore;
 declare const yourApp: { openExternal(url: string): Promise<void> };
 
 const attempt = await connectLoopback('notion', {
-  store, person: 'person-42',
+  store, person: 'Umer',
   open: url => yourApp.openExternal(url),
 });
 await attempt.done;
@@ -91,7 +160,7 @@ import type { Keystore } from '@byokit/secrets';
 declare const store: Keystore;
 
 const notion = connect('notion', {
-  store, person: 'person-42', redirectUri: 'https://your-app.example/connect/callback',
+  store, person: 'Umer', redirectUri: 'https://your-app.example/connect/callback',
 });
 // Sign in once, then reconstruct this handle across app restarts.
 const mcp = await notion.mcp({
@@ -120,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
@@ -131,7 +254,10 @@ failure; an expired token is never returned. Tokens without `expires_in` remain
 valid until rejected, then refresh if possible. No background timer is needed.
 
 `ConnectError.code` is a typed app diagnostic and `message` is a plain sentence.
-OAuth errors never include provider bodies, callback codes or tokens. No errors or
+OAuth errors expose an optional typed `cause` with `error` and
+`error_description`, sanitized against supplied/returned credentials and URLs.
+The message remains a plain sentence. Treat provider descriptions as untrusted
+text; they are diagnostics for the host, not ready-to-render UI. No errors or
 tokens are logged. MCP results/errors are private application content and should
 be treated accordingly. `fetch`, `now`, request and flow timeouts are injectable.
 
@@ -187,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
 

package/SECURITY.md

@@ -2,13 +2,17 @@
 
 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.
 
-Treat `token()` as trusted app code: never display or log its result. The kit does
-not log credentials or include provider response bodies in OAuth errors. The full
+Treat `token()` and `grant()` as trusted app code: never display or log their results.
+The kit does not log credentials or include raw provider response bodies in OAuth
+errors. OAuth causes retain only `error` and `error_description`, with supplied and
+returned credentials (including URL/form encodings), URLs and authorization headers
+redacted. Treat descriptions as untrusted diagnostic text, never as HTML. The full
 MCP client can return private content and server error messages; handle those as
 private app data. Close each MCP client when finished.
 

package/dist/connect.d.ts

@@ -1,6 +1,6 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { type ProviderId } from './providers.ts';
-import type { ConnectOptions, Provider, SignIn, McpOptions } from './types.ts';
+import type { ConnectOptions, OAuthClient, Provider, SignIn, McpOptions, Grant, ClientVerification } from './types.ts';
 /** One person's connection on one device; the host owns the store and browser. */
 export declare class Connection {
     readonly provider: Readonly<Provider>;
@@ -14,6 +14,11 @@ export declare class Connection {
     private get timeout();
     private get now();
     private saved;
+    /** Snapshot for trusted app code, including the provider's refresh lifetime. */
+    grant(): Promise<Grant | null>;
+    /** Google checks app credentials before rejecting this deliberately nonexistent refresh grant.
+     * Only invalid_grant confirms the details; other responses cannot prove validity. */
+    verifyClient(input?: OAuthClient): Promise<ClientVerification>;
     connected(): Promise<boolean>;
     disconnect(): Promise<void>;
     /** Starts a fresh browser sign-in. No opt-in flag or server-held account is required. */

package/dist/connect.js

@@ -1,6 +1,7 @@
+import WORDS from './words.json' with { type: 'json' };
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ConnectError } from "./errors.js";
+import { ConnectError, providerCause } from "./errors.js";
 import { discover } from "./discovery.js";
 import { endpoint, redirect, request, json } from "./http.js";
 import { providers } from "./providers.js";
@@ -26,6 +27,15 @@ function serial(slot, action) {
 }
 function base64url(bytes) { return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); }
 function random() { return base64url(crypto.getRandomValues(new Uint8Array(32))); }
+function validClient(client) {
+    if (!client || typeof client.id !== 'string' || !client.id.trim() ||
+        (client.secret !== undefined && (typeof client.secret !== 'string' || !client.secret)) ||
+        (client.authMethod !== undefined && !['none', 'client_secret_post', 'client_secret_basic'].includes(client.authMethod)) ||
+        (client.authMethod?.startsWith('client_secret_') && !client.secret))
+        throw new ConnectError('configuration');
+    return { id: client.id, secret: client.secret, authMethod: client.authMethod };
+}
+function validTime(value) { return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0); }
 /** One person's connection on one device; the host owns the store and browser. */
 export class Connection {
     provider;
@@ -73,6 +83,36 @@ export class Connection {
             throw new ConnectError('token');
         }
     }
+    /** Snapshot for trusted app code, including the provider's refresh lifetime. */
+    async grant() {
+        const saved = await this.saved();
+        if (!saved)
+            return null;
+        const t = saved.tokens;
+        return { accessToken: t.access, refreshToken: t.refresh, expiresAt: t.expires, scope: t.scope,
+            refreshTokenExpiresIn: t.refreshExpiresIn, refreshTokenExpiresAt: t.refreshExpiresAt };
+    }
+    /** Google checks app credentials before rejecting this deliberately nonexistent refresh grant.
+     * Only invalid_grant confirms the details; other responses cannot prove validity. */
+    async verifyClient(input) {
+        const client = validClient((input ?? this.options.client));
+        if (!client.secret || client.authMethod === 'none')
+            throw new ConnectError('configuration');
+        try {
+            const info = await discover(this.provider, this.fetcher, this.timeout);
+            await this.exchange(info, client, { grant_type: 'refresh_token', refresh_token: 'byokit-client-check-not-a-grant' });
+        }
+        catch (error) {
+            if (!(error instanceof ConnectError))
+                throw error;
+            if (error.cause?.error === 'invalid_client' && (error.status === 400 || error.status === 401))
+                return { outcome: 'invalid', message: WORDS.verification.invalid, cause: error.cause };
+            if (error.cause?.error === 'invalid_grant' && error.status === 400)
+                return { outcome: 'valid', message: WORDS.verification.valid };
+            return { outcome: 'inconclusive', message: WORDS.verification.inconclusive, cause: error.cause };
+        }
+        return { outcome: 'inconclusive', message: WORDS.verification.inconclusive };
+    }
     async connected() { return !!await this.saved(); }
     async disconnect() {
         ++this.slot.epoch;
@@ -122,7 +162,7 @@ export class Connection {
                         throw new ConnectError('callback');
                 consumed = true;
                 if (returned.searchParams.has('error'))
-                    throw new ConnectError('declined');
+                    throw new ConnectError('declined', undefined, providerCause(Object.fromEntries(returned.searchParams), [state, verifier, client.id, client.secret ?? '', ...returned.searchParams.getAll('code')]));
                 if (returned.searchParams.getAll('code').length !== 1 || !returned.searchParams.get('code'))
                     throw new ConnectError('callback');
                 await serial(this.slot, async () => {
@@ -148,11 +188,9 @@ export class Connection {
             method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json' },
             body: JSON.stringify({ client_name: this.options.clientName ?? 'BYOKit', redirect_uris: [this.options.redirectUri], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'none' }),
         }, this.timeout);
-        if (!response.ok) {
-            await response.body?.cancel();
-            throw new ConnectError('registration', response.status);
-        }
         const m = await json(response, 'registration');
+        if (!response.ok || m.error)
+            throw new ConnectError('registration', response.status, providerCause(m, [this.options.clientName ?? 'BYOKit', this.options.redirectUri]));
         if (typeof m.client_id !== 'string' || !m.client_id || (m.token_endpoint_auth_method !== undefined && m.token_endpoint_auth_method !== 'none'))
             throw new ConnectError('registration');
         return { id: m.client_id, authMethod: 'none' };
@@ -172,15 +210,20 @@ export class Connection {
         const m = await json(response, 'token');
         if (!response.ok || m.error) {
             // Only an explicit invalid grant proves revocation. Transient failures preserve the sign-in.
+            const cause = providerCause(m, [client.id, client.secret ?? '', previous?.access ?? '', previous?.refresh ?? '', ...Object.values(fields)]);
             if (m.error === 'invalid_grant' && previous)
-                throw new ConnectError('signin', response.status);
-            throw new ConnectError('token', response.status);
+                throw new ConnectError('signin', response.status, cause);
+            throw new ConnectError('token', response.status, cause);
         }
         if (typeof m.access_token !== 'string' || !m.access_token || typeof m.token_type !== 'string' || m.token_type.toLowerCase() !== 'bearer' || (m.expires_in !== undefined && (!Number.isFinite(Number(m.expires_in)) || Number(m.expires_in) < 0)))
             throw new ConnectError('token');
+        if (m.refresh_token_expires_in !== undefined && (!validTime(m.refresh_token_expires_in) || !Number.isFinite(this.now + Number(m.refresh_token_expires_in) * 1000)))
+            throw new ConnectError('token');
         return { access: m.access_token, refresh: typeof m.refresh_token === 'string' ? m.refresh_token : previous?.refresh,
             expires: m.expires_in === undefined ? undefined : this.now + Number(m.expires_in) * 1000,
-            scope: typeof m.scope === 'string' ? m.scope : previous?.scope };
+            scope: typeof m.scope === 'string' ? m.scope : previous?.scope,
+            refreshExpiresIn: typeof m.refresh_token_expires_in === 'number' ? m.refresh_token_expires_in : previous?.refreshExpiresIn,
+            refreshExpiresAt: typeof m.refresh_token_expires_in === 'number' ? this.now + m.refresh_token_expires_in * 1000 : previous?.refreshExpiresAt };
     }
     /** For trusted app code (mail/calendar/API calls). Never display or log this value. */
     async token(rejectedAccessToken) {
@@ -202,6 +245,11 @@ export class Connection {
                     return old.access;
                 throw new ConnectError('signin');
             }
+            if (old.refreshExpiresAt !== undefined && old.refreshExpiresAt <= this.now) {
+                if (!force && old.expires !== undefined && old.expires > this.now)
+                    return old.access;
+                throw new ConnectError('signin');
+            }
             try {
                 const tokens = await this.exchange(saved, saved.client, { grant_type: 'refresh_token', refresh_token: old.refresh }, old);
                 if (epoch !== this.slot.epoch)

package/dist/errors.d.ts

@@ -1,7 +1,14 @@
 export type ConnectErrorCode = 'configuration' | 'discovery' | 'registration' | 'callback' | 'expired' | 'declined' | 'scope' | 'token' | 'signin' | 'network';
-/** Never includes provider bodies, callback codes, credentials or URLs. */
+export interface ProviderErrorCause {
+    readonly error: string;
+    readonly error_description?: string;
+}
+/** Preserve OAuth diagnostics, removing credentials supplied to or returned by the provider. */
+export declare function providerCause(body: Record<string, unknown>, secrets: readonly string[]): ProviderErrorCause | undefined;
+/** Plain message and optional sanitized OAuth cause; never includes raw response bodies. */
 export declare class ConnectError extends Error {
     readonly code: ConnectErrorCode;
     readonly status?: number;
-    constructor(code: ConnectErrorCode, status?: number);
+    readonly cause?: ProviderErrorCause;
+    constructor(code: ConnectErrorCode, status?: number, cause?: ProviderErrorCause);
 }

package/dist/errors.js

@@ -1,11 +1,31 @@
 import WORDS from './words.json' with { type: 'json' };
 const words = WORDS.errors;
-/** Never includes provider bodies, callback codes, credentials or URLs. */
+/** Preserve OAuth diagnostics, removing credentials supplied to or returned by the provider. */
+export function providerCause(body, secrets) {
+    if (typeof body.error !== 'string')
+        return undefined;
+    const values = [...secrets, ...['access_token', 'refresh_token', 'id_token', 'client_secret', 'client_id'].map(k => body[k]).filter((v) => typeof v === 'string')];
+    const redact = (text) => {
+        for (const value of values.filter(Boolean).sort((a, b) => b.length - a.length)) {
+            const variants = new Set([value, new URLSearchParams({ v: value }).toString().slice(2)]);
+            try {
+                variants.add(encodeURIComponent(value));
+            }
+            catch { /* Malformed Unicode still gets literal/form redaction. */ }
+            for (const encoded of variants)
+                text = text.split(encoded).join('[redacted]');
+        }
+        return text.replace(/https?:\/\/[^\s<>"']+/gi, '[redacted]').replace(/(?:Bearer|Basic)\s+[^\s,;]+/gi, '[redacted]');
+    };
+    const standard = ['invalid_request', 'invalid_client', 'invalid_grant', 'unauthorized_client', 'unsupported_grant_type', 'invalid_scope', 'access_denied', 'server_error', 'temporarily_unavailable', 'invalid_client_metadata', 'invalid_redirect_uri'];
+    return Object.freeze({ error: standard.includes(body.error) && !values.includes(body.error) ? body.error : redact(body.error), ...(typeof body.error_description === 'string' ? { error_description: redact(body.error_description) } : {}) });
+}
+/** Plain message and optional sanitized OAuth cause; never includes raw response bodies. */
 export class ConnectError extends Error {
     code;
     status;
-    constructor(code, status) {
-        super(words[code]);
+    constructor(code, status, cause) {
+        super(words[code], cause ? { cause } : undefined);
         this.name = 'ConnectError';
         this.code = code;
         this.status = status;

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,7 +2,11 @@ export { connect, Connection } from './connect.ts';
 export { providers } from './providers.ts';
 export type { ProviderId } from './providers.ts';
 export { ConnectError } from './errors.ts';
-export type { ConnectErrorCode } from './errors.ts';
-export type { Provider, OAuthClient, OAuthEndpoints, ConnectOptions, SignIn, McpOptions } from './types.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';
 export * from '@modelcontextprotocol/sdk/types.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/types.d.ts

@@ -53,3 +53,26 @@ export interface McpOptions {
     /** Register sampling/elicitation/request/notification handlers before connecting. */
     configure?: (client: import('@modelcontextprotocol/sdk/client/index.js').Client) => void;
 }
+/** Trusted app data only: never display or log credentials. Times are Unix milliseconds. */
+export interface Grant {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scope?: string;
+    /** The provider's refresh_token_expires_in value, in seconds. */
+    refreshTokenExpiresIn?: number;
+    /** Absolute deadline; unlike the duration, this does not restart on restore. */
+    refreshTokenExpiresAt?: number;
+}
+export type ClientVerification = {
+    outcome: 'valid';
+    message: string;
+} | {
+    outcome: 'invalid';
+    message: string;
+    cause?: import('./errors.ts').ProviderErrorCause;
+} | {
+    outcome: 'inconclusive';
+    message: string;
+    cause?: import('./errors.ts').ProviderErrorCause;
+};

package/dist/words.json

@@ -17,5 +17,14 @@
         "finishing": "Sign-in is already finishing. Return to the app.",
         "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.",
+        "inconclusive": "Your app details could not be checked. Try again later."
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/connect",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Connect a person's third-party apps with PKCE, refresh and typed remote MCP.",
   "license": "Apache-2.0",
   "type": "module",