foxlend 0.0.0-stage → 0.1.0

package/dist/egress.js

@@ -0,0 +1,65 @@
+// The egress allow list (docs/failure-modes.md E1-E15). judge() decides one
+// request. The webRequest and proxy listeners in loans.ts call it.
+import { matchesPattern, parsePattern } from "foxgate";
+import { hostOf } from "./site.js";
+const PASS = { block: false };
+const NETWORK = new Set(["http:", "https:", "ws:", "wss:"]);
+const LOCAL = new Set(["data:", "blob:", "about:"]);
+const OWN_STORES = new Set(["firefox-default", "firefox-private"]);
+const compiled = new Map();
+// A pattern that no longer parses (the public suffix list changed) matches nothing (E16).
+const matches = (host, pattern, publicSuffix) => {
+    let parsed = compiled.get(pattern);
+    if (!parsed) {
+        try {
+            parsed = parsePattern(pattern, publicSuffix);
+        }
+        catch {
+            return false;
+        }
+        compiled.set(pattern, parsed);
+    }
+    return matchesPattern(host, parsed);
+};
+/** The host of a network URL, "local" for a URL that stays in the browser, or undefined for anything else. */
+function hostOfUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (LOCAL.has(parsed.protocol))
+            return "local";
+        if (!NETWORK.has(parsed.protocol))
+            return undefined;
+        return hostOf(parsed.hostname);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Decide one request. `loans` undefined means the loan list could not be
+ * read: then every container other than the default and the private one is
+ * blocked (E13).
+ */
+export function judge(request, loans, now, publicSuffix) {
+    const store = request.cookieStoreId;
+    if (!loans) {
+        if (store === undefined || OWN_STORES.has(store))
+            return PASS;
+        const host = hostOfUrl(request.url);
+        return { block: true, loanId: "unknown", reason: "no-state", ...(host && host !== "local" ? { host } : {}) };
+    }
+    const loan = store === undefined ? undefined : loans.find((l) => l.cookieStoreId === store);
+    if (!loan)
+        return PASS;
+    const host = hostOfUrl(request.url);
+    const block = (reason) => ({ block: true, loanId: loan.id, reason, ...(host && host !== "local" ? { host } : {}) });
+    if (loan.state === "revoking")
+        return block("revoking");
+    if (now >= loan.expiresAt)
+        return block("expired");
+    if (host === "local")
+        return PASS;
+    if (host === undefined)
+        return block("bad-url");
+    return loan.patterns.some((p) => matches(host, p, publicSuffix)) ? PASS : block("not-allowed");
+}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export type FoxlendErrorCode = "bad-domain" | "bad-allow" | "bad-ttl" | "bad-url" | "bad-scope" | "lend-failed" | "revoke-failed" | "storage-error" | "setting-failed" | "no-host-access";
+/** Every error that foxlend throws on purpose. Read `code`, not the message. */
+export declare class FoxlendError extends Error {
+    readonly code: FoxlendErrorCode;
+    constructor(code: FoxlendErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+/** Every error that foxlend throws on purpose. Read `code`, not the message. */
+export class FoxlendError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "FoxlendError";
+        this.code = code;
+    }
+}

package/dist/foxlend.d.ts

@@ -0,0 +1,41 @@
+import type { Host, PublicSuffix } from "foxgate";
+import { type BrowserLike, type Listenable } from "./browser.js";
+import { type BlockedRequest } from "./guard.js";
+import { type LendOptions } from "./lend.js";
+import { type RevokedEvent } from "./revoke.js";
+import { type Loan } from "./state.js";
+export interface FoxlendOptions {
+    /** The WebExtension `browser` object. */
+    browser: BrowserLike;
+    /** The foxgate host. foxlend adds one grant per loan and revokes it with the loan. */
+    host: Pick<Host, "addGrant" | "revokeGrant" | "grants">;
+    /** Default: withDefaultRule(browser.publicSuffix). Give foxgate the same object. */
+    publicSuffix?: PublicSuffix;
+    /** The clock, in ms since 1970. Default: Date.now. */
+    now?: () => number;
+    /** The longest loan, in ms. Default: 24 hours. */
+    maxTtlMs?: number;
+    /** Also block through proxy.onRequest. Default: true when `browser.proxy` exists. */
+    proxyLayer?: boolean;
+    /** Turn off network prediction (DNS prefetch, link prefetch) while a loan is active. Default: true. */
+    stopPrediction?: boolean;
+    /** Turn off WebRTC while a loan is active. Default: true. */
+    stopWebRtc?: boolean;
+    /** The browser.storage.local key. Default: "foxlend". */
+    storageKey?: string;
+}
+export interface Foxlend {
+    lend(options: LendOptions): Promise<Loan>;
+    /** Returns false when there is no such loan. Throws FoxlendError `revoke-failed` when a step fails. */
+    revoke(loan: Loan | string): Promise<boolean>;
+    listLoans(): Promise<Loan[]>;
+    /** Revoke loans whose time is over, and remove containers that no loan holds. foxlend runs it at start. */
+    sweep(): Promise<void>;
+    onBlocked: Listenable<BlockedRequest>;
+    onRevoked: Listenable<RevokedEvent>;
+}
+/**
+ * Call this at the top level of the background script, so Firefox can wake
+ * the event page for a request, an alarm, or a browser start.
+ */
+export declare function createFoxlend(options: FoxlendOptions): Foxlend;

package/dist/foxlend.js

@@ -0,0 +1,49 @@
+import { emitter } from "./browser.js";
+import { attachGuard } from "./guard.js";
+import { lendLoan } from "./lend.js";
+import { revokeNow, sweepNow } from "./revoke.js";
+import { withDefaultRule } from "./site.js";
+import { loanStore } from "./state.js";
+/**
+ * Call this at the top level of the background script, so Firefox can wake
+ * the event page for a request, an alarm, or a browser start.
+ */
+export function createFoxlend(options) {
+    const { browser } = options;
+    const publicSuffix = options.publicSuffix ?? (browser.publicSuffix ? withDefaultRule(browser.publicSuffix) : undefined);
+    if (!publicSuffix)
+        throw new TypeError("foxlend needs a public suffix list: Firefox 153+ with the publicSuffix permission, or the publicSuffix option.");
+    const store = loanStore(browser, options.storageKey ?? "foxlend");
+    const blocked = emitter();
+    const revoked = emitter();
+    const ctx = {
+        browser,
+        host: options.host,
+        store,
+        now: options.now ?? Date.now,
+        publicSuffix,
+        maxTtlMs: options.maxTtlMs ?? 24 * 60 * 60 * 1000,
+        settings: [
+            ...(options.stopPrediction === false ? [] : ["networkPredictionEnabled"]),
+            ...(options.stopWebRtc === false ? [] : ["peerConnectionEnabled"]),
+        ],
+    };
+    attachGuard({ browser, store, now: ctx.now, publicSuffix, proxyLayer: options.proxyLayer ?? browser.proxy !== undefined, onBlocked: blocked.emit });
+    const revoke = (id, reason) => store.serial(() => revokeNow(ctx, id, reason, revoked.emit));
+    const sweep = () => store.serial(() => sweepNow(ctx, revoked.emit));
+    browser.alarms.onAlarm.addListener(({ name }) => {
+        if (name.startsWith("foxlend:"))
+            revoke(name.slice("foxlend:".length), "ttl").catch(() => undefined);
+    });
+    browser.permissions.onRemoved.addListener(() => void sweep().catch(() => undefined));
+    browser.runtime.onStartup.addListener(() => void sweep().catch(() => undefined));
+    sweep().catch(() => undefined);
+    return Object.freeze({
+        lend: (lendOptions) => lendLoan(ctx, lendOptions),
+        revoke: (loan) => revoke(typeof loan === "string" ? loan : loan.id, "user"),
+        listLoans: async () => structuredClone(await store.loans()),
+        sweep,
+        onBlocked: blocked.event,
+        onRevoked: revoked.event,
+    });
+}

package/dist/guard.d.ts

@@ -0,0 +1,28 @@
+import type { PublicSuffix } from "foxgate";
+import type { BrowserLike, ProxyInfo } from "./browser.js";
+import { type BlockReason } from "./egress.js";
+import type { LoanStore } from "./state.js";
+/** A request that the guard stopped. */
+export interface BlockedRequest {
+    loanId: string;
+    url: string;
+    host?: string;
+    /** The webRequest resource type, or "speculative" for a preconnect. */
+    type: string;
+    /** The page or script that sent the request, when Firefox knows it. */
+    initiator?: string;
+    layer: "webRequest" | "proxy";
+    reason: BlockReason;
+    at: number;
+}
+/** Port 9 is the discard port. Nothing answers, so the request fails. */
+export declare const DEAD_PROXY: ProxyInfo;
+export interface GuardOptions {
+    browser: BrowserLike;
+    store: LoanStore;
+    now: () => number;
+    publicSuffix: PublicSuffix;
+    proxyLayer: boolean;
+    onBlocked: (event: BlockedRequest) => void;
+}
+export declare function attachGuard({ browser, store, now, publicSuffix, proxyLayer, onBlocked }: GuardOptions): void;

package/dist/guard.js

@@ -0,0 +1,40 @@
+import { judge } from "./egress.js";
+/** Port 9 is the discard port. Nothing answers, so the request fails. */
+export const DEAD_PROXY = { type: "socks", host: "127.0.0.1", port: 9, proxyDNS: true };
+const OWN_STORES = new Set(["firefox-default", "firefox-private"]);
+export function attachGuard({ browser, store, now, publicSuffix, proxyLayer, onBlocked }) {
+    const decide = (details, loans, layer) => {
+        // Firefox lets a request pass when a blocking listener throws, so an error blocks (E16).
+        let verdict;
+        try {
+            // A removed loan container is blocked as if it were still being revoked (L17).
+            const all = loans && [...loans, ...store.retired().map((id) => ({ id: "retired", cookieStoreId: id, patterns: [], expiresAt: 0, state: "revoking" }))];
+            verdict = judge(details, all, now(), publicSuffix);
+        }
+        catch {
+            verdict = { block: true, loanId: "unknown", reason: "error" };
+        }
+        if (!verdict.block)
+            return false;
+        // webRequest reports what it blocks. The proxy layer reports only what webRequest cannot see.
+        if (layer === "webRequest" || details.type === "speculative") {
+            const initiator = details.originUrl ?? details.documentUrl;
+            onBlocked({ loanId: verdict.loanId, url: details.url, ...(verdict.host ? { host: verdict.host } : {}), type: details.type, ...(initiator ? { initiator } : {}), layer, reason: verdict.reason, at: now() });
+        }
+        return true;
+    };
+    // Answer at once when the loans are in memory. Else wait for storage (E12).
+    function answer(details, layer, blocked) {
+        const id = details.cookieStoreId;
+        if (id === undefined || OWN_STORES.has(id))
+            return undefined;
+        const cached = store.cached();
+        if (cached)
+            return decide(details, cached, layer) ? blocked : undefined;
+        return store.load().then((loans) => (decide(details, loans, layer) ? blocked : undefined));
+    }
+    // Firefox refuses a cookieStoreId filter (E15), so listen to all URLs.
+    browser.webRequest.onBeforeRequest.addListener((details) => answer(details, "webRequest", { cancel: true }), { urls: ["<all_urls>"] }, ["blocking"]);
+    if (proxyLayer && browser.proxy)
+        browser.proxy.onRequest.addListener((details) => answer(details, "proxy", DEAD_PROXY), { urls: ["<all_urls>"] });
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { FoxlendError, type FoxlendErrorCode } from "./errors.js";
+export { hostOf, loanPatterns, siteOf, withDefaultRule, type PatternInput, type PublicSuffixApi } from "./site.js";
+export { planCopy, type Cookie, type CookieSetDetails, type CopyOptions, type SkippedCookie } from "./cookies.js";
+export { judge, type BlockReason, type LoanState, type RequestInfo, type Verdict } from "./egress.js";
+export { emitter, type BrowserEvent, type BrowserLike, type BrowserSetting, type BrowserSettingName, type ContextualIdentity, type Listenable, type ProxyInfo, type RequestDetails } from "./browser.js";
+export { createFoxlend, type Foxlend, type FoxlendOptions } from "./foxlend.js";
+export { DEAD_PROXY, type BlockedRequest } from "./guard.js";
+export type { Loan } from "./state.js";
+export { CONTAINER, type LendOptions } from "./lend.js";
+export type { RevokedEvent } from "./revoke.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+// The public API of foxlend.
+export { FoxlendError } from "./errors.js";
+export { hostOf, loanPatterns, siteOf, withDefaultRule } from "./site.js";
+export { planCopy } from "./cookies.js";
+export { judge } from "./egress.js";
+export { emitter } from "./browser.js";
+export { createFoxlend } from "./foxlend.js";
+export { DEAD_PROXY } from "./guard.js";
+export { CONTAINER } from "./lend.js";

package/dist/lend.d.ts

@@ -0,0 +1,44 @@
+import type { Host, PublicSuffix, Scope } from "foxgate";
+import type { BrowserLike, BrowserSettingName } from "./browser.js";
+import type { Loan, LoanStore } from "./state.js";
+export interface LendOptions {
+    /** The host to lend, for example `www.example.com`. */
+    domain: string;
+    /** The foxgate scope of the grant: "read", "fill", "submit", or "pay". */
+    scope: Scope;
+    /** How long the loan lasts, in ms. */
+    ttlMs: number;
+    /** More hosts that pages in the loan may reach. Exact hosts or `*.` plus a host. */
+    allow?: string[];
+    /** The task URL to open. Default: `https://<domain>/`. */
+    url?: string;
+    /** Hide the loan tab from the tab strip. Needs the `tabHide` permission. */
+    hidden?: boolean;
+    /** "site" (default): the whole registrable domain. "host": the exact host only. */
+    match?: "site" | "host";
+    /** The tools that the foxgate grant allows. Default: every tool. */
+    tools?: string[];
+}
+export interface LoanContext {
+    browser: BrowserLike;
+    host: Pick<Host, "addGrant" | "revokeGrant" | "grants">;
+    store: LoanStore;
+    now: () => number;
+    publicSuffix: PublicSuffix;
+    maxTtlMs: number;
+    /** The browser-wide settings to turn off while a loan is active (E6, E17). */
+    settings: BrowserSettingName[];
+}
+export declare const CONTAINER: {
+    readonly prefix: "Agent · ";
+    readonly color: "purple";
+    readonly icon: "fingerprint";
+};
+export declare const alarmName: (loanId: string) => string;
+/** True when the guard can see every request: the extension has access to all sites (E19). */
+export declare const hasHostAccess: (ctx: LoanContext) => Promise<boolean>;
+/** Give the browser-wide settings back when no loan is left (E6, E17, L15). */
+export declare function releaseSettings(ctx: LoanContext): Promise<void>;
+/** Close the loan tabs, clear and remove the container, and revoke the grant. */
+export declare function teardown(ctx: LoanContext, loan: Pick<Loan, "cookieStoreId" | "grantId">): Promise<void>;
+export declare function lendLoan(ctx: LoanContext, options: LendOptions): Promise<Loan>;

package/dist/lend.js

@@ -0,0 +1,170 @@
+import { planCopy } from "./cookies.js";
+import { judge } from "./egress.js";
+import { FoxlendError } from "./errors.js";
+import { hostOf, loanPatterns, siteOf } from "./site.js";
+export const CONTAINER = { prefix: "Agent · ", color: "purple", icon: "fingerprint" };
+export const alarmName = (loanId) => `foxlend:${loanId}`;
+const SCOPES = ["read", "fill", "submit", "pay"];
+const message = (error) => (error instanceof Error ? error.message : String(error));
+const cookieUrl = (c) => `${c.secure ? "https" : "http"}://${c.domain.replace(/^\./, "")}${c.path}`;
+const randomId = () => [...crypto.getRandomValues(new Uint8Array(12))].map((b) => b.toString(16).padStart(2, "0")).join("");
+/** True when the guard can see every request: the extension has access to all sites (E19). */
+export const hasHostAccess = (ctx) => ctx.browser.permissions.contains({ origins: ["<all_urls>"] }).catch(() => false);
+/** Give the browser-wide settings back when no loan is left (E6, E17, L15). */
+export async function releaseSettings(ctx) {
+    if ((await ctx.store.loans()).length > 0)
+        return;
+    for (const name of ctx.settings)
+        await ctx.browser.privacy?.network[name]?.clear({}).catch(() => false);
+}
+/** Turn each browser-wide setting off, or throw `setting-failed` (E18). */
+async function holdSettings(ctx) {
+    for (const name of ctx.settings) {
+        const setting = ctx.browser.privacy?.network[name];
+        const refuse = (why) => new FoxlendError("setting-failed", `foxlend cannot turn off privacy.network.${name}: ${why}. Pass ${name === "peerConnectionEnabled" ? "stopWebRtc" : "stopPrediction"}: false to lend with it on.`);
+        if (!setting)
+            throw refuse("the privacy API is missing (add the privacy permission)");
+        const { levelOfControl } = await setting.get({});
+        if (!/^controll(able|ed)_by_this_extension$/.test(levelOfControl))
+            throw refuse(`it is ${levelOfControl}`);
+        if (!(await setting.set({ value: false }).catch(() => false)))
+            throw refuse("Firefox did not change it");
+    }
+}
+/** Close every tab of one container. Query again until none is left. */
+async function closeTabs(b, id) {
+    for (let round = 0;; round++) {
+        const open = (await b.tabs.query({ cookieStoreId: id })).flatMap((t) => (t.id === undefined ? [] : [t.id]));
+        if (open.length === 0)
+            return;
+        if (round === 5)
+            throw new Error(`Tabs stay open in ${id}.`);
+        await b.tabs.remove(open);
+    }
+}
+/** Close the loan tabs, clear and remove the container, and revoke the grant. */
+export async function teardown(ctx, loan) {
+    const b = ctx.browser;
+    const id = loan.cookieStoreId;
+    if (id) {
+        // From here on the guard blocks this container for good, also after a restart (L17).
+        await ctx.store.retire(id);
+        // Removing a container does not close its tabs (L5). Close them first.
+        await closeTabs(b, id);
+        // Only "not found" means gone. Any other error keeps the loan revoking (L13).
+        const exists = await b.contextualIdentities.get(id).then(() => true, (error) => {
+            if (/Invalid contextual identity/.test(message(error)))
+                return false;
+            throw error;
+        });
+        if (exists) {
+            // Firefox refuses serviceWorkers with cookieStoreId and then clears nothing (L6).
+            await b.browsingData.remove({ cookieStoreId: id }, { cookies: true, localStorage: true, indexedDB: true });
+            for (const c of await b.cookies.getAll({ storeId: id, partitionKey: {}, firstPartyDomain: null })) {
+                await b.cookies.remove({ url: cookieUrl(c), name: c.name, storeId: id, ...(c.partitionKey ? { partitionKey: c.partitionKey } : {}), ...(c.firstPartyDomain ? { firstPartyDomain: c.firstPartyDomain } : {}) });
+            }
+            await b.contextualIdentities.remove(id);
+        }
+        // A tab can open after the last query and before the remove (L17).
+        await closeTabs(b, id);
+    }
+    if (loan.grantId)
+        await ctx.host.revokeGrant(loan.grantId);
+}
+export async function lendLoan(ctx, options) {
+    const { browser: b, publicSuffix } = ctx;
+    if (!SCOPES.includes(options.scope))
+        throw new FoxlendError("bad-scope", `The scope must be one of ${SCOPES.join(", ")}.`);
+    const { ttlMs } = options;
+    if (typeof ttlMs !== "number" || !Number.isFinite(ttlMs) || ttlMs <= 0 || ttlMs > ctx.maxTtlMs) {
+        throw new FoxlendError("bad-ttl", `ttlMs must be a number above 0 and at most ${ctx.maxTtlMs}.`);
+    }
+    const match = options.match ?? "site";
+    const domain = hostOf(options.domain);
+    const site = siteOf(domain, publicSuffix);
+    const allow = options.allow ?? [];
+    const patterns = loanPatterns({ host: domain, match, allow, publicSuffix });
+    const url = options.url ?? `https://${domain}/`;
+    const probe = { id: "probe", cookieStoreId: "probe", patterns, expiresAt: Infinity, state: "active" };
+    if (judge({ url, type: "main_frame", cookieStoreId: "probe" }, [probe], 0, publicSuffix).block) {
+        throw new FoxlendError("bad-url", `${url} is not on the loan allow list (${patterns.join(", ")}).`);
+    }
+    return ctx.store.serial(async () => {
+        if (!(await hasHostAccess(ctx)))
+            throw new FoxlendError("no-host-access", "foxlend needs access to all sites, or the guard cannot see the loan's requests. Allow it in about:addons.");
+        // DNS prefetch and WebRTC are outside both guard layers (E6, E17). Without them off, no loan (E18).
+        try {
+            await holdSettings(ctx);
+        }
+        catch (error) {
+            await releaseSettings(ctx);
+            throw error;
+        }
+        const createdAt = ctx.now();
+        let loan = {
+            id: randomId(),
+            state: "creating",
+            patterns,
+            expiresAt: createdAt + ttlMs,
+            domain,
+            site,
+            scope: options.scope,
+            match,
+            allow,
+            url,
+            createdAt,
+            containerName: `${CONTAINER.prefix}${site}`,
+            hidden: false,
+            copied: 0,
+            skipped: [],
+        };
+        const put = async (patch) => {
+            loan = { ...loan, ...patch };
+            await ctx.store.save([...(await ctx.store.loans()).filter((l) => l.id !== loan.id), loan]);
+        };
+        // The record exists before the container, so a crash cannot hide a container (L2).
+        await put({});
+        try {
+            const container = await b.contextualIdentities.create({ name: loan.containerName, color: CONTAINER.color, icon: CONTAINER.icon });
+            await put({ cookieStoreId: container.cookieStoreId });
+            // Only read the default container (K10). firstPartyDomain null matches all (K9).
+            const source = await b.cookies.getAll({ storeId: "firefox-default", partitionKey: {}, firstPartyDomain: null });
+            const plan = planCopy(source, { host: domain, match, patterns, storeId: container.cookieStoreId, endsAt: loan.expiresAt, now: createdAt, publicSuffix });
+            const skipped = [...plan.skipped];
+            let copied = 0;
+            for (const details of plan.set) {
+                try {
+                    await b.cookies.set(details);
+                    copied++;
+                }
+                catch (error) {
+                    skipped.push({ name: details.name, domain: details.domain ?? new URL(details.url).hostname, reason: "set-failed", message: message(error) });
+                }
+            }
+            await put({ grantRequested: true });
+            const grant = await ctx.host.addGrant({ scope: options.scope, domains: patterns, expiresAt: loan.expiresAt, ...(options.tools ? { tools: options.tools } : {}) });
+            // Save the grant ID before any other step, so the undo can revoke it (L16).
+            await put({ grantId: grant.id });
+            b.alarms.create(alarmName(loan.id), { when: loan.expiresAt });
+            await put({ state: "active", copied, skipped });
+            const tab = await b.tabs.create({ url, cookieStoreId: container.cookieStoreId, active: !options.hidden });
+            let hidden = false;
+            if (options.hidden && tab.id !== undefined)
+                hidden = await b.tabs.hide([tab.id]).then(() => true, () => false);
+            await put({ ...(tab.id === undefined ? {} : { tabId: tab.id }), hidden });
+            return structuredClone(loan);
+        }
+        catch (error) {
+            // Undo what is done (L3). If the undo fails too, the guard keeps blocking and the next sweep retries.
+            try {
+                await teardown(ctx, loan);
+                await ctx.store.save((await ctx.store.loans()).filter((l) => l.id !== loan.id));
+                await releaseSettings(ctx);
+            }
+            catch {
+                await put({ state: "revoking" }).catch(() => undefined);
+            }
+            throw new FoxlendError("lend-failed", `The loan for ${domain} failed and was undone: ${message(error)}`, { cause: error });
+        }
+    });
+}

package/dist/revoke.d.ts

@@ -0,0 +1,15 @@
+import type { Loan } from "./state.js";
+import { type LoanContext } from "./lend.js";
+/** Why a loan ended. "startup": a loan that never became active, or a revoke that failed before. */
+export interface RevokedEvent {
+    loan: Loan;
+    reason: "user" | "ttl" | "startup" | "permission";
+}
+/** Revoke one loan. Call it inside store.serial(). */
+export declare function revokeNow(ctx: LoanContext, id: string, reason: RevokedEvent["reason"], emit: (event: RevokedEvent) => void): Promise<boolean>;
+/**
+ * Revoke loans whose time is over or that never became active, set the
+ * alarms again for the others, and remove foxlend containers that no loan
+ * holds. Call it inside store.serial().
+ */
+export declare function sweepNow(ctx: LoanContext, emit: (event: RevokedEvent) => void): Promise<void>;

package/dist/revoke.js

@@ -0,0 +1,60 @@
+import { alarmName, CONTAINER, hasHostAccess, releaseSettings, teardown } from "./lend.js";
+import { FoxlendError } from "./errors.js";
+const message = (error) => (error instanceof Error ? error.message : String(error));
+/**
+ * The grant of a record that asked for one and never got its ID (L14): same
+ * scope, domains, and end time, and no other loan holds it.
+ */
+async function lostGrant(ctx, loan, loans) {
+    const held = new Set(loans.map((l) => l.grantId));
+    const same = (domains) => JSON.stringify(domains) === JSON.stringify(loan.patterns);
+    return (await ctx.host.grants()).find((g) => !held.has(g.id) && g.scope === loan.scope && g.expiresAt === loan.expiresAt && same(g.domains))?.id;
+}
+/** Revoke one loan. Call it inside store.serial(). */
+export async function revokeNow(ctx, id, reason, emit) {
+    const loans = await ctx.store.loans();
+    const found = loans.find((l) => l.id === id);
+    if (!found)
+        return false;
+    // The guard blocks the container from this line on (E11).
+    const grantId = found.grantId ?? (found.grantRequested ? await lostGrant(ctx, found, loans) : undefined);
+    const loan = { ...found, state: "revoking", ...(grantId ? { grantId } : {}) };
+    await ctx.store.save(loans.map((l) => (l.id === id ? loan : l)));
+    try {
+        await teardown(ctx, loan);
+        await ctx.browser.alarms.clear(alarmName(id));
+    }
+    catch (error) {
+        throw new FoxlendError("revoke-failed", `The loan for ${loan.domain} is not fully revoked: ${message(error)}. Its requests stay blocked, and the next start tries again.`, { cause: error });
+    }
+    await ctx.store.save((await ctx.store.loans()).filter((l) => l.id !== id));
+    await releaseSettings(ctx);
+    emit({ loan, reason });
+    return true;
+}
+/**
+ * Revoke loans whose time is over or that never became active, set the
+ * alarms again for the others, and remove foxlend containers that no loan
+ * holds. Call it inside store.serial().
+ */
+export async function sweepNow(ctx, emit) {
+    const now = ctx.now();
+    // Without access to all sites the guard sees nothing, so no loan may stay (E19).
+    const blind = !(await hasHostAccess(ctx));
+    for (const loan of await ctx.store.loans()) {
+        const expired = loan.expiresAt <= now;
+        if (blind || expired || loan.state !== "active") {
+            await revokeNow(ctx, loan.id, blind ? "permission" : expired ? "ttl" : "startup", emit).catch(() => false);
+        }
+        else {
+            ctx.browser.alarms.create(alarmName(loan.id), { when: loan.expiresAt });
+        }
+    }
+    const held = new Set((await ctx.store.loans()).map((l) => l.cookieStoreId));
+    for (const c of await ctx.browser.contextualIdentities.query({})) {
+        const ours = c.name.startsWith(CONTAINER.prefix) && c.color === CONTAINER.color && c.icon === CONTAINER.icon;
+        if (ours && !held.has(c.cookieStoreId))
+            await teardown(ctx, { cookieStoreId: c.cookieStoreId }).catch(() => undefined);
+    }
+    await releaseSettings(ctx);
+}

package/dist/site.d.ts

@@ -0,0 +1,32 @@
+import { type PublicSuffix } from "foxgate";
+/** The parts of Firefox `browser.publicSuffix` (153+) that foxlend reads. */
+export interface PublicSuffixApi {
+    getDomain(host: string): string | null | undefined;
+    getKnownSuffix(host: string): string | null | undefined;
+}
+export declare const IPV4: RegExp;
+/**
+ * Wrap `browser.publicSuffix` with the default rule of the public suffix list
+ * ("*"): a host on a top-level domain that is not on the list (for example
+ * `.test` or `.localhost`) has the last two labels as its site. Firefox
+ * returns null for these hosts. Pass the result to foxgate too.
+ */
+export declare function withDefaultRule(api: PublicSuffixApi): PublicSuffix;
+/** Lowercase punycode host. Throws FoxlendError `bad-domain`. */
+export declare function hostOf(input: string): string;
+/** The registrable domain of a host. Throws FoxlendError `bad-domain` for a public suffix. */
+export declare function siteOf(input: string, publicSuffix: PublicSuffix): string;
+/** True when `host` is `domain` or a subdomain of it, by whole labels. */
+export declare const within: (host: string, domain: string) => boolean;
+export interface PatternInput {
+    host: string;
+    /** "site": the site and all its subdomains. "host": the exact host only. */
+    match: "site" | "host";
+    allow: string[];
+    publicSuffix: PublicSuffix;
+}
+/**
+ * The host patterns of a loan: the lent site (or host), then the allow list.
+ * The same strings are the egress allow list and the foxgate grant domains.
+ */
+export declare function loanPatterns({ host, match, allow, publicSuffix }: PatternInput): string[];