@pooriaarab/foxlink 0.0.0-stage → 0.1.0

package/dist/gmail.js

@@ -0,0 +1,157 @@
+import { FoxlinkError } from "./errors.js";
+import { FOXLINK_TOOLS, gated, hasControl } from "./gated.js";
+import { GOOGLE_ENDPOINTS, GOOGLE_SCOPES } from "./provider.js";
+import { htmlToText } from "./text.js";
+const SEND_SCOPES = [GOOGLE_SCOPES.gmailSend, "https://www.googleapis.com/auth/gmail.modify", "https://mail.google.com/"];
+const ADDRESS = /^[^\s@<>,;:"()[\]\\]+@[^\s@<>,;:"()[\]\\]+\.[^\s@<>,;:"()[\]\\]+$/;
+const b64 = (text) => {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(text))
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+};
+function validMessage(m) {
+    if (!m || typeof m.to !== "string" || typeof m.subject !== "string" || typeof m.body !== "string")
+        return false;
+    const to = m.to.split(",").map((a) => a.trim());
+    if (to.length > 10 || !to.every((a) => ADDRESS.test(a)))
+        return false;
+    return !hasControl(m.to) && !hasControl(m.subject) && m.subject.length <= 500 && m.body.length <= 100_000;
+}
+/**
+ * RFC 2047 encoded words of 75 characters at most, folded on new lines. Each
+ * word holds whole characters (45 bytes at most), so no character is split.
+ */
+function encodedWords(text) {
+    const words = [];
+    let chunk = "";
+    for (const char of text) {
+        if (new TextEncoder().encode(chunk + char).length > 45) {
+            words.push(chunk);
+            chunk = "";
+        }
+        chunk += char;
+    }
+    if (chunk)
+        words.push(chunk);
+    return words.map((w) => `=?UTF-8?B?${b64(w)}?=`).join("\r\n ");
+}
+/** An RFC 5322 message with a UTF-8 text body. A non-ASCII subject is RFC 2047 encoded. */
+function mime(m) {
+    const plain = /^[\x20-\x7e]*$/.test(m.subject) && !m.subject.includes("=?");
+    const subject = plain ? m.subject : encodedWords(m.subject);
+    const body = (b64(m.body).match(/.{1,76}/g) ?? []).join("\r\n");
+    return [`To: ${m.to.split(",").map((a) => a.trim()).join(", ")}`, `Subject: ${subject}`, "MIME-Version: 1.0", 'Content-Type: text/plain; charset="UTF-8"', "Content-Transfer-Encoding: base64", "", body].join("\r\n");
+}
+const READ_SCOPES = [GOOGLE_SCOPES.gmailRead, "https://www.googleapis.com/auth/gmail.modify", "https://mail.google.com/"];
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+const PAGE_TOKEN = /^[A-Za-z0-9_-]{1,256}$/;
+const header = (part, name) => part?.headers?.find((h) => h.name.toLowerCase() === name)?.value ?? "";
+function decodeBody(data) {
+    const binary = atob(data.replace(/-/g, "+").replace(/_/g, "/"));
+    return new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0)));
+}
+/** Every part with a body, depth first, with no attachments. */
+function bodies(part, out = []) {
+    if (!part)
+        return out;
+    if (part.parts?.length)
+        for (const child of part.parts)
+            bodies(child, out);
+    else if (!part.filename && !part.body?.attachmentId && typeof part.body?.data === "string")
+        out.push(part);
+    return out;
+}
+/** The plain text of a message: the first text/plain part, else the first text/html part as text. */
+export function messageText(payload) {
+    const parts = bodies(payload);
+    const plain = parts.find((p) => p.mimeType === "text/plain");
+    if (plain?.body?.data !== undefined)
+        return decodeBody(plain.body.data).replace(/\r\n/g, "\n").trim();
+    const html = parts.find((p) => p.mimeType === "text/html");
+    return html?.body?.data !== undefined ? htmlToText(decodeBody(html.body.data)) : "";
+}
+const summary = (m) => ({
+    trust: "untrusted",
+    source: "gmail",
+    id: m.id,
+    threadId: m.threadId ?? m.id,
+    from: header(m.payload, "from"),
+    to: header(m.payload, "to"),
+    subject: header(m.payload, "subject"),
+    date: header(m.payload, "date"),
+    snippet: m.snippet ?? "",
+});
+const clampMax = (value) => (typeof value === "number" && Number.isFinite(value) ? Math.min(Math.max(Math.trunc(value), 1), 50) : 10);
+export function gmail(link, options = {}) {
+    const base = options.baseUrl ?? link.provider.endpoints?.gmailBase ?? GOOGLE_ENDPOINTS.gmailBase;
+    async function hasAny(scopes) {
+        for (const s of scopes)
+            if (await link.hasScope(s))
+                return true;
+        return false;
+    }
+    async function needScope(scopes) {
+        if (await hasAny(scopes))
+            return;
+        throw new FoxlinkError("missing-scope", `This call needs the scope ${scopes[0] ?? ""}. Connect again and grant it.`);
+    }
+    async function getJson(path, params = []) {
+        const url = new URL(`${base}/users/me/${path}`);
+        for (const [k, v] of params)
+            url.searchParams.append(k, v);
+        const res = await link.fetch(url);
+        if (!res.ok)
+            throw new FoxlinkError("http-error", `Gmail answered HTTP ${res.status}.`, { status: res.status });
+        return (await res.json());
+    }
+    return Object.freeze({
+        /** Newest messages first, with their headers. One list request and one request for each message. */
+        async listMessages(request = {}) {
+            await needScope(READ_SCOPES);
+            if (request.pageToken !== undefined && !PAGE_TOKEN.test(request.pageToken))
+                throw new FoxlinkError("bad-input", "pageToken is not a Gmail page token.");
+            const params = [["maxResults", String(clampMax(request.max))]];
+            if (request.query)
+                params.push(["q", String(request.query).slice(0, 500)]);
+            if (request.pageToken)
+                params.push(["pageToken", request.pageToken]);
+            const list = await getJson("messages", params);
+            const ids = (list.messages ?? []).map((m) => m.id).filter((id) => ID.test(id));
+            const messages = [];
+            for (let i = 0; i < ids.length; i += 5) {
+                const chunk = ids.slice(i, i + 5).map((id) => getJson(`messages/${id}`, [["format", "metadata"], ...["From", "To", "Subject", "Date"].map((h) => ["metadataHeaders", h])]));
+                messages.push(...(await Promise.all(chunk)).map(summary));
+            }
+            return list.nextPageToken ? { messages, nextPageToken: list.nextPageToken } : { messages };
+        },
+        /** One message, with its body as plain text. HTML loses scripts, styles, and images. */
+        async getMessage(id) {
+            await needScope(READ_SCOPES);
+            if (typeof id !== "string" || !ID.test(id))
+                throw new FoxlinkError("bad-input", "id is not a Gmail message ID.");
+            const m = await getJson(`messages/${id}`, [["format", "full"]]);
+            return { ...summary(m), text: messageText(m.payload) };
+        },
+        /**
+         * Send a plain text message, after a foxgate decision with scope `submit`.
+         * The first call returns `ask`. Call again with the approval token.
+         */
+        async sendMessage(message, approval = {}) {
+            if (!validMessage(message))
+                return { status: "refused", reason: "bad-input" };
+            if (!(await hasAny(SEND_SCOPES)))
+                return { status: "refused", reason: "missing-scope" };
+            const args = { to: message.to, subject: message.subject, body: message.body };
+            const action = { tool: "foxlink.gmail.send", scope: FOXLINK_TOOLS["foxlink.gmail.send"], domain: new URL(base).hostname, args };
+            return gated(options.gate, action, approval.token, async (judged) => {
+                const raw = b64(mime(judged)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+                const res = await link.fetch(`${base}/users/me/messages/send`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ raw }) });
+                if (!res.ok)
+                    throw new FoxlinkError("http-error", `Gmail answered HTTP ${res.status}.`, { status: res.status });
+                const sent = (await res.json());
+                return { status: "sent", id: String(sent.id ?? "") };
+            });
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { FoxlinkError, type FoxlinkErrorCode } from "./errors.js";
+export { GOOGLE_ENDPOINTS, GOOGLE_SCOPES, defineProvider, googleProvider, loopbackRedirectUrl, type GoogleEndpoints, type Provider, type ProviderConfig, type ProviderOptions, } from "./provider.js";
+export { createLink, type IdentityLike, type Link, type LinkOptions, type LinkStatus } from "./link.js";
+export { gmail, messageText, type Gmail, type Message, type MessageSummary, type OutgoingMessage } from "./gmail.js";
+export { decodeEntities, htmlToText, toPromptText, type Untrusted } from "./text.js";
+export { calendar, type Calendar, type CalendarEvent, type NewEvent } from "./calendar.js";
+export { FOXLINK_TOOLS } from "./gated.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { FoxlinkError } from "./errors.js";
+export { GOOGLE_ENDPOINTS, GOOGLE_SCOPES, defineProvider, googleProvider, loopbackRedirectUrl, } from "./provider.js";
+export { createLink } from "./link.js";
+export { gmail, messageText } from "./gmail.js";
+export { decodeEntities, htmlToText, toPromptText } from "./text.js";
+export { calendar } from "./calendar.js";
+export { FOXLINK_TOOLS } from "./gated.js";

package/dist/link.d.ts

@@ -0,0 +1,67 @@
+import { type Store } from "foxgate";
+import type { Vault } from "foxvault";
+import { type GoogleEndpoints, type Provider } from "./provider.js";
+/** The parts of `browser.identity` that foxlink uses. */
+export interface IdentityLike {
+    getRedirectURL(): string;
+    launchWebAuthFlow(details: {
+        url: string;
+        interactive: boolean;
+    }): Promise<string>;
+}
+export interface LinkOptions {
+    /** From `defineProvider` or `googleProvider`. */
+    provider: Provider & {
+        readonly endpoints?: Readonly<GoogleEndpoints>;
+    };
+    /** A foxvault vault. It keeps the access token and the refresh token. */
+    vault: Vault;
+    /** Where the token record (scopes and expiry, no tokens) lives. Default: memoryStore(). */
+    store?: Store;
+    /** `browser.identity` in Firefox. */
+    identity?: IdentityLike;
+    /** The redirect URI. Default: from `identity` and `provider.redirect`. */
+    redirectUri?: string;
+    /** Opens the authorize URL and returns the redirect URL. Default: `identity.launchWebAuthFlow`. */
+    launch?: (details: {
+        url: string;
+        interactive: boolean;
+    }) => Promise<string>;
+    /** `inject`: foxvault adds the header in Firefox (attachHeaderInjection). `use`: foxlink adds it in host code. Default: `use`. */
+    transport?: "use" | "inject";
+    fetch?: typeof fetch;
+    /** The clock, in ms since 1970. Default: Date.now. */
+    now?: () => number;
+    /** Refresh this long before the access token expires. Default: 60 seconds. */
+    skewMs?: number;
+}
+export interface LinkStatus {
+    connected: boolean;
+    scopes: string[];
+    /** When the access token expires, in ms since 1970, by the local clock. */
+    expiresAt?: number;
+    /** False when the provider sent no refresh token. Then the user must connect again when the access token expires. */
+    refreshable?: boolean;
+}
+export declare function createLink(options: LinkOptions): Readonly<{
+    provider: Readonly<Required<Omit<import("./provider.js").ProviderConfig, "clientSecret" | "revokeUrl">>> & {
+        readonly clientSecret?: string;
+        readonly revokeUrl?: string;
+    } & {
+        readonly endpoints?: Readonly<GoogleEndpoints>;
+    };
+    connect: (request?: {
+        scopes?: string[];
+        interactive?: boolean;
+    }) => Promise<LinkStatus>;
+    status: () => Promise<LinkStatus>;
+    fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    disconnect: () => Promise<{
+        revoked: boolean;
+    }>;
+    /** True when the user granted this scope. */
+    hasScope: (scope: string) => Promise<boolean>;
+    /** The redirect URI to register with the provider. */
+    redirectUri: () => string;
+}>;
+export type Link = ReturnType<typeof createLink>;

package/dist/link.js

@@ -0,0 +1,299 @@
+import { memoryStore } from "foxgate";
+import { FoxlinkError, safeCode } from "./errors.js";
+import { loopbackRedirectUrl } from "./provider.js";
+const b64url = (bytes) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const random = (n) => b64url(crypto.getRandomValues(new Uint8Array(n)));
+const sha256 = async (text) => b64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))));
+/** Keep expires_in between 60 seconds and 1 day. A missing or bad value counts as 300 seconds. */
+const lifetimeMs = (value) => {
+    const n = typeof value === "number" ? value : typeof value === "string" && value.trim() ? Number(value) : Number.NaN;
+    return (Number.isFinite(n) ? Math.min(Math.max(n, 60), 86_400) : 300) * 1000;
+};
+function tokenResult(result) {
+    if (!result.ok) {
+        const oauthError = safeCode(result.body.error);
+        throw new FoxlinkError("token-error", `The token endpoint refused${oauthError ? ` with ${oauthError}` : ""} (HTTP ${result.status}).`, { status: result.status, oauthError });
+    }
+    const token = result.body.access_token;
+    if (typeof token !== "string" || token.length < 8 || token.length > 4096)
+        throw new FoxlinkError("token-error", "The token endpoint sent no usable access token.");
+    return result.body;
+}
+const idTokenFail = () => new FoxlinkError("id-token", "The ID token does not match this sign-in.");
+export function createLink(options) {
+    const { provider, vault } = options;
+    const store = options.store ?? memoryStore();
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const now = options.now ?? Date.now;
+    const transport = options.transport ?? "use";
+    if (transport !== "use" && transport !== "inject")
+        throw new FoxlinkError("bad-config", "transport must be use or inject.");
+    const key = `foxlink:${provider.id}`;
+    const handles = { access: `vault:flk-${provider.id}-access`, refresh: `vault:flk-${provider.id}-refresh` };
+    const tokenHosts = [...new Set([provider.tokenUrl, provider.revokeUrl ?? provider.tokenUrl].map((u) => new URL(u).hostname))];
+    let connecting = false;
+    let refreshing;
+    /** Goes up by one with each new access token, so two 401s for one token send one refresh. */
+    let generation = 0;
+    const redirectUri = () => {
+        if (options.redirectUri)
+            return options.redirectUri;
+        if (!options.identity)
+            throw new FoxlinkError("bad-config", "Pass identity (browser.identity) or redirectUri.");
+        const url = options.identity.getRedirectURL();
+        return provider.redirect === "loopback" ? loopbackRedirectUrl(url) : url;
+    };
+    const readRecord = async () => {
+        const value = (await store.get(key));
+        return value && typeof value === "object" && Array.isArray(value.scopes) && typeof value.expiresAt === "number" && typeof value.issuedAt === "number" ? value : undefined;
+    };
+    /** POST a form. It never throws, so it can run inside vault.use. */
+    async function postForm(url, params, asClient = true) {
+        const body = new URLSearchParams(asClient ? { client_id: provider.clientId, ...params } : params);
+        if (asClient && provider.clientSecret)
+            body.set("client_secret", provider.clientSecret);
+        try {
+            const res = await doFetch(url, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: body.toString() });
+            const parsed = await res.json().catch(() => ({}));
+            return { ok: res.ok, status: res.status, body: parsed && typeof parsed === "object" ? parsed : {} };
+        }
+        catch {
+            return { ok: false, status: 0, body: {} };
+        }
+    }
+    /** Revoke a token that foxlink will not keep. Errors are ignored: the token is dropped either way. */
+    async function revokeQuietly(token) {
+        if (provider.revokeUrl && token)
+            await postForm(provider.revokeUrl, { token }, false);
+    }
+    async function save(tokens, scopes, replaceRefresh) {
+        await vault.remove(handles.access);
+        await vault.set(handles.access, tokens.access_token, { domains: provider.apiHosts });
+        if (transport === "inject") {
+            await vault.injectHeader({ handle: handles.access, header: "Authorization", hosts: provider.apiHosts, format: "Bearer {secret}", allowHttp: provider.allowHttp });
+        }
+        if (typeof tokens.refresh_token === "string" && tokens.refresh_token.length >= 8) {
+            await vault.remove(handles.refresh);
+            await vault.set(handles.refresh, tokens.refresh_token, { domains: tokenHosts });
+        }
+        else if (replaceRefresh) {
+            await vault.remove(handles.refresh);
+        }
+        const refreshable = (await vault.list()).some((s) => s.handle === handles.refresh);
+        const issuedAt = now();
+        const record = { scopes, issuedAt, expiresAt: issuedAt + lifetimeMs(tokens.expires_in), refreshable };
+        await store.set(key, record);
+        return record;
+    }
+    function checkIdToken(idToken, nonce) {
+        const payload = typeof idToken === "string" ? idToken.split(".")[1] : undefined;
+        let claims;
+        try {
+            claims = JSON.parse(atob((payload ?? "").replace(/-/g, "+").replace(/_/g, "/")));
+        }
+        catch {
+            throw idTokenFail();
+        }
+        const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+        if (claims.nonce !== nonce || !aud.includes(provider.clientId))
+            throw idTokenFail();
+        if (provider.issuers.length && !provider.issuers.includes(String(claims.iss)))
+            throw idTokenFail();
+    }
+    async function connect(request = {}) {
+        if (connecting)
+            throw new FoxlinkError("busy", "A connect is already running.");
+        connecting = true;
+        // A refresh that is still running belongs to the old grant. It throws its result away.
+        generation += 1;
+        try {
+            const scopes = [...new Set(request.scopes ?? provider.scopes)];
+            if (scopes.length === 0 || !scopes.every((s) => provider.allowedScopes.includes(s))) {
+                throw new FoxlinkError("bad-scope", "Ask only for scopes that the provider config allows.");
+            }
+            const redirect = redirectUri();
+            const verifier = random(32);
+            const state = random(24);
+            const nonce = scopes.includes("openid") ? random(24) : undefined;
+            const url = new URL(provider.authorizeUrl);
+            const params = {
+                ...provider.authParams,
+                client_id: provider.clientId,
+                redirect_uri: redirect,
+                response_type: "code",
+                scope: scopes.join(" "),
+                state,
+                code_challenge: await sha256(verifier),
+                code_challenge_method: "S256",
+                ...(nonce ? { nonce } : {}),
+            };
+            for (const [name, value] of Object.entries(params))
+                url.searchParams.set(name, value);
+            const launch = options.launch ?? options.identity?.launchWebAuthFlow.bind(options.identity);
+            if (!launch)
+                throw new FoxlinkError("bad-config", "Pass identity (browser.identity) or launch.");
+            let back;
+            try {
+                back = new URL(await launch({ url: url.href, interactive: request.interactive ?? true }));
+            }
+            catch {
+                throw new FoxlinkError("authorize-failed", "The sign-in window failed or was closed.");
+            }
+            const expected = new URL(redirect);
+            if (back.origin !== expected.origin || back.pathname !== expected.pathname)
+                throw new FoxlinkError("redirect-mismatch", "The sign-in returned to a URL that is not the redirect URI.");
+            if (back.searchParams.get("state") !== state)
+                throw new FoxlinkError("state-mismatch", "The sign-in state does not match. Try to connect again.");
+            const error = back.searchParams.get("error");
+            if (error === "access_denied")
+                throw new FoxlinkError("access-denied", "The user did not allow access.");
+            const code = back.searchParams.get("code");
+            if (error || !code) {
+                const oauthError = safeCode(error);
+                throw new FoxlinkError("authorize-failed", `The sign-in failed${oauthError ? ` with ${oauthError}` : ""}.`, { oauthError });
+            }
+            const tokens = tokenResult(await postForm(provider.tokenUrl, { grant_type: "authorization_code", code, redirect_uri: redirect, code_verifier: verifier }));
+            const granted = typeof tokens.scope === "string" ? tokens.scope.split(" ").filter(Boolean) : scopes;
+            try {
+                if (granted.some((s) => !scopes.includes(s)))
+                    throw new FoxlinkError("scope-creep", "The provider granted more scopes than foxlink asked for.");
+                if (nonce)
+                    checkIdToken(tokens.id_token, nonce);
+            }
+            catch (refused) {
+                await revokeQuietly(tokens.refresh_token ?? tokens.access_token);
+                throw refused;
+            }
+            if (refreshing)
+                await refreshing.catch(() => undefined);
+            generation += 1;
+            await save(tokens, granted, true);
+            return await status();
+        }
+        finally {
+            connecting = false;
+        }
+    }
+    async function forget() {
+        await vault.remove(handles.access);
+        await vault.remove(handles.refresh);
+        await store.set(key, null);
+        generation += 1;
+    }
+    async function doRefresh() {
+        const started = generation;
+        const record = await readRecord();
+        if (!record)
+            throw new FoxlinkError("not-connected", "Connect first.");
+        if (!record.refreshable) {
+            await forget();
+            throw new FoxlinkError("reconnect", "The access token expired and there is no refresh token. Connect again.");
+        }
+        const result = await vault.use(handles.refresh, (token) => postForm(provider.tokenUrl, { grant_type: "refresh_token", refresh_token: token }));
+        if (result.status >= 400 && result.status < 500 && safeCode(result.body.error) === "invalid_grant") {
+            await forget();
+            throw new FoxlinkError("reconnect", "The provider refused the refresh token. Connect again.", { status: result.status, oauthError: "invalid_grant" });
+        }
+        // A connect or a disconnect ran meanwhile. This token is from a grant that foxlink no longer keeps.
+        if (generation !== started)
+            return;
+        const tokens = tokenResult(result);
+        // A refresh cannot add scopes. Keep the ones that both lists hold.
+        const granted = typeof tokens.scope === "string" ? tokens.scope.split(" ").filter((s) => record.scopes.includes(s)) : record.scopes;
+        await save(tokens, granted, false);
+        generation += 1;
+    }
+    /** Refresh the access token. Calls at the same time share one request. */
+    function refresh() {
+        refreshing ??= doRefresh().finally(() => {
+            refreshing = undefined;
+        });
+        return refreshing;
+    }
+    async function sendOnce(url, init) {
+        const headers = new Headers(init.headers);
+        headers.delete("authorization");
+        if (transport === "inject")
+            return doFetch(url.href, { ...init, headers });
+        const out = await vault.use(handles.access, async (token) => {
+            headers.set("authorization", `Bearer ${token}`);
+            try {
+                return { response: await doFetch(url.href, { ...init, headers }) };
+            }
+            catch {
+                return { response: undefined };
+            }
+        });
+        if (!out.response)
+            throw new FoxlinkError("http-error", `The request to ${url.hostname} failed.`, { status: 0 });
+        return out.response;
+    }
+    async function send(url, init) {
+        if (refreshing)
+            await refreshing;
+        return sendOnce(url, init);
+    }
+    /** fetch for the API hosts, with the access token. It refreshes on expiry and one time on 401. */
+    async function authorizedFetch(input, init = {}) {
+        let url;
+        try {
+            url = new URL(String(input));
+        }
+        catch {
+            throw new FoxlinkError("bad-host", "Not a URL.");
+        }
+        const httpOk = url.protocol === "https:" || (provider.allowHttp && url.protocol === "http:");
+        if (!httpOk || !provider.apiHosts.includes(url.hostname))
+            throw new FoxlinkError("bad-host", `${url.hostname} is not an API host of this provider.`);
+        const record = await readRecord();
+        if (!record)
+            throw new FoxlinkError("not-connected", "Connect first.");
+        // The margin is at most half of the token life, so a short-lived token is not refreshed before every call.
+        const margin = Math.min(options.skewMs ?? 60_000, (record.expiresAt - record.issuedAt) / 2);
+        if (now() >= record.expiresAt - margin)
+            await refresh();
+        if (!(await readRecord()))
+            throw new FoxlinkError("not-connected", "Connect first.");
+        const seen = generation;
+        const first = await send(url, init);
+        if (first.status !== 401)
+            return first;
+        if (seen === generation)
+            await refresh();
+        if (!(await readRecord()))
+            throw new FoxlinkError("not-connected", "Connect first.");
+        const second = await send(url, init);
+        if (second.status === 401)
+            throw new FoxlinkError("unauthorized", "The provider refused the new access token.", { status: 401 });
+        return second;
+    }
+    /** Revoke the grant at the provider, then forget every token. It forgets them also when the revoke fails. */
+    async function disconnect() {
+        let revoked = false;
+        const held = new Set((await vault.list()).map((s) => s.handle));
+        const handle = held.has(handles.refresh) ? handles.refresh : held.has(handles.access) ? handles.access : undefined;
+        if (provider.revokeUrl && handle) {
+            const revokeUrl = provider.revokeUrl;
+            revoked = (await vault.use(handle, (token) => postForm(revokeUrl, { token }, false))).ok;
+        }
+        await forget();
+        return { revoked };
+    }
+    async function status() {
+        const record = await readRecord();
+        if (!record)
+            return { connected: false, scopes: [] };
+        return { connected: true, scopes: [...record.scopes], expiresAt: record.expiresAt, refreshable: record.refreshable };
+    }
+    return Object.freeze({
+        provider,
+        connect,
+        status,
+        fetch: authorizedFetch,
+        disconnect,
+        /** True when the user granted this scope. */
+        hasScope: async (scope) => Boolean((await readRecord())?.scopes.includes(scope)),
+        /** The redirect URI to register with the provider. */
+        redirectUri,
+    });
+}

package/dist/provider.d.ts

@@ -0,0 +1,63 @@
+/** An OAuth 2.0 provider that issues codes with PKCE. */
+export interface ProviderConfig {
+    /** A short name, `a-z 0-9 -`. foxlink uses it in vault handles and store keys. */
+    id: string;
+    clientId: string;
+    /** Only for providers that want one from an installed app. It is sent to the token endpoint only. */
+    clientSecret?: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    revokeUrl?: string;
+    /** The scopes that `connect()` asks for by default. */
+    scopes: string[];
+    /** The most that `connect({ scopes })` may ask for. Default: `scopes`. */
+    allowedScopes?: string[];
+    /** The hosts that get the access token. */
+    apiHosts: string[];
+    /** More parameters for the authorize URL. */
+    authParams?: Record<string, string>;
+    /** `loopback` gives `http://127.0.0.1/mozoauth2/<id>`. `extension` gives `identity.getRedirectURL()`. */
+    redirect?: "loopback" | "extension";
+    /** The `iss` values to accept in an ID token. */
+    issuers?: string[];
+    /** Allow `http:` endpoints and API hosts. Only for test servers. */
+    allowHttp?: boolean;
+}
+export type Provider = Readonly<Required<Omit<ProviderConfig, "clientSecret" | "revokeUrl">>> & {
+    readonly clientSecret?: string;
+    readonly revokeUrl?: string;
+};
+/** Check a provider config and freeze it. Throws `bad-config`. */
+export declare function defineProvider(config: ProviderConfig): Provider;
+/** `http://127.0.0.1/mozoauth2/<subdomain>` from the URL that `identity.getRedirectURL()` returns (Firefox 86+). */
+export declare function loopbackRedirectUrl(extensionRedirectUrl: string): string;
+/** Google scopes that the Gmail and Calendar clients use. */
+export declare const GOOGLE_SCOPES: Readonly<{
+    gmailRead: "https://www.googleapis.com/auth/gmail.readonly";
+    gmailSend: "https://www.googleapis.com/auth/gmail.send";
+    calendarRead: "https://www.googleapis.com/auth/calendar.readonly";
+    calendarEvents: "https://www.googleapis.com/auth/calendar.events";
+}>;
+export interface GoogleEndpoints {
+    authorizeUrl: string;
+    tokenUrl: string;
+    revokeUrl: string;
+    gmailBase: string;
+    calendarBase: string;
+}
+export declare const GOOGLE_ENDPOINTS: Readonly<GoogleEndpoints>;
+export interface ProviderOptions {
+    clientId: string;
+    clientSecret?: string;
+    /** Default: Gmail read and Calendar read. */
+    scopes?: string[];
+    /** Default: `scopes`. Add `GOOGLE_SCOPES.gmailSend` or `calendarEvents` to let `connect` ask for them. */
+    allowedScopes?: string[];
+    /** Other endpoints, for a test server. */
+    endpoints?: Partial<GoogleEndpoints>;
+    allowHttp?: boolean;
+}
+/** The Google preset: loopback redirect, offline access, and read-only scopes by default. */
+export declare function googleProvider(options: ProviderOptions): Provider & {
+    readonly endpoints: Readonly<GoogleEndpoints>;
+};