@wirecat/cli-core 0.412.0 → 0.414.0

package/dist/oauth/keeper.d.ts

@@ -0,0 +1,41 @@
+import { type CredentialSource, type Logger } from "@wirecat/cli-base";
+import { type AuthorizeOptions } from "./authorize.js";
+import type { OAuthProvider, TokenSet } from "./provider.js";
+import type { TokenStorage } from "./storage.js";
+export interface TokenKeeperOptions {
+    provider: OAuthProvider;
+    storage: TokenStorage;
+    /** The CLI's config directory: the keyring entry varies with it, so the lock must too. */
+    lockDir: string;
+    fetch: typeof fetch;
+    /** `drive personal session start`: named in every failure that needs a new sign-in. */
+    signInCommand: string;
+    now?: () => number;
+    signal?: AbortSignal;
+    log?: Logger;
+    /** Longer than one token request's 30 s limit, so a live refresher finishes first. Real time, not `now`. */
+    lockWaitMs?: number;
+    lockRetryMs?: number;
+    /** An access token expiring later than this from now is used as is. */
+    freshForMs?: number;
+}
+export type SignInOptions = Omit<AuthorizeOptions, "provider" | "signal"> & {
+    /** Runs before anything is saved; it may refuse the account or add fields to the entry (drive's `principal`). */
+    accept?: (tokens: TokenSet) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
+};
+export interface TokenKeeper {
+    accessToken(): Promise<string>;
+    tokens(): Promise<TokenSet>;
+    signIn(options: SignInOptions): Promise<{
+        scopes: string[];
+    }>;
+    /** Saves tokens a CLI got by a flow of its own, under the same lock. */
+    save(tokens: TokenSet, extra?: Record<string, unknown>): Promise<void>;
+    signOut(options?: {
+        revoke?: boolean;
+    }): Promise<{
+        revoked: boolean;
+        removed: CredentialSource[];
+    }>;
+}
+export declare const tokenKeeper: (options: TokenKeeperOptions) => TokenKeeper;

package/dist/oauth/keeper.js

@@ -0,0 +1,136 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError, isCliError } from "@wirecat/cli-base";
+import { acquireLock } from "../files/index.js";
+import { authorize } from "./authorize.js";
+import { requestTokens, revokeToken, TOKEN_LOG_EVENT } from "./requests.js";
+const inFlight = new Map();
+export const tokenKeeper = (options) => {
+    const { provider, storage, signal, log } = options;
+    const now = options.now ?? Date.now;
+    const fresh = (tokens) => Boolean(tokens.accessToken) &&
+        tokens.expiresAt !== undefined &&
+        tokens.expiresAt > now() + (options.freshForMs ?? 60_000);
+    const lockPath = join(options.lockDir, `oauth-${createHash("sha256").update(storage.key).digest("hex").slice(0, 16)}.lock`);
+    const clientOf = (stored) => {
+        const saved = stored?.client;
+        if (!saved || saved.clientSecret || saved.clientId !== provider.client.clientId)
+            return saved ?? provider.client;
+        return provider.client;
+    };
+    const context = (client, previous) => ({
+        fetch: options.fetch,
+        client,
+        now,
+        signInCommand: options.signInCommand,
+        ...(signal ? { signal } : {}),
+        ...(log ? { log } : {}),
+        ...(previous ? { previous } : {}),
+    });
+    const exchange = (params, ctx) => provider.exchange ? provider.exchange(params, ctx) : requestTokens(provider, params, ctx);
+    const notSignedIn = () => new CliError("authentication_error", `not signed in to ${provider.name}; run ${options.signInCommand}`, {
+        reason: "oauth.missing",
+    });
+    const busy = (error) => isCliError(error) && error.details.reason === "file.locked";
+    const acquire = async () => {
+        const started = performance.now();
+        let waiting = false;
+        for (;;) {
+            try {
+                return await acquireLock(lockPath, signal ? { signal } : {});
+            }
+            catch (error) {
+                if (!busy(error))
+                    throw error;
+                if (!waiting) {
+                    waiting = true;
+                    log?.info({
+                        event: TOKEN_LOG_EVENT,
+                        provider: provider.id,
+                        operation: "lock",
+                        outcome: "waiting",
+                        pid: process.pid,
+                    });
+                }
+                if (performance.now() - started > (options.lockWaitMs ?? 45_000))
+                    throw new CliError("provider_unavailable", `another process holds this ${provider.name} sign-in; retry`, {
+                        reason: "oauth.locked",
+                        retryable: true,
+                    });
+                await delay(options.lockRetryMs ?? 50, undefined, signal ? { signal } : {}).catch(() => {
+                    throw new CliError("cancelled", `${provider.name} sign-in was cancelled`);
+                });
+            }
+        }
+    };
+    const locked = async (work) => {
+        const lock = await acquire();
+        try {
+            return await work();
+        }
+        finally {
+            await lock.release().catch(() => { });
+        }
+    };
+    const shared = (work) => {
+        const running = inFlight.get(lockPath);
+        if (running)
+            return running;
+        const started = locked(work).finally(() => inFlight.delete(lockPath));
+        inFlight.set(lockPath, started);
+        return started;
+    };
+    const tokens = async () => {
+        const seen = storage.read();
+        if (!seen)
+            throw notSignedIn();
+        if (fresh(seen.tokens))
+            return seen.tokens;
+        return shared(async () => {
+            const current = storage.read();
+            if (!current)
+                throw notSignedIn();
+            // Another process refreshed while this one waited for the lock: its result is the one to use.
+            if (fresh(current.tokens) || current.tokens.refreshToken !== seen.tokens.refreshToken)
+                return current.tokens;
+            const client = clientOf(current);
+            const refreshed = await exchange({ grant_type: "refresh_token", refresh_token: current.tokens.refreshToken }, context(client, current.tokens));
+            storage.write({ tokens: refreshed, client });
+            return refreshed;
+        });
+    };
+    return {
+        tokens,
+        accessToken: async () => {
+            const current = await tokens();
+            if (!current.accessToken)
+                throw notSignedIn();
+            return current.accessToken;
+        },
+        signIn: async ({ accept, ...authorizeOptions }) => {
+            storage.probe();
+            const authorization = await authorize({ ...authorizeOptions, provider, ...(signal ? { signal } : {}) });
+            const client = provider.client;
+            const received = await exchange({
+                grant_type: "authorization_code",
+                code: authorization.code,
+                redirect_uri: authorization.redirectUri,
+                code_verifier: authorization.codeVerifier,
+            }, context(client));
+            const extra = (await accept?.(received)) ?? undefined;
+            await locked(async () => storage.write({ tokens: received, client, ...(extra ? { extra } : {}) }));
+            return { scopes: received.scopes };
+        },
+        save: (saved, extra) => locked(async () => storage.write({ tokens: saved, client: clientOf(storage.read()), ...(extra ? { extra } : {}) })),
+        signOut: ({ revoke = false } = {}) => locked(async () => {
+            const current = storage.read();
+            let revoked = false;
+            if (revoke && current) {
+                await revokeToken(provider, current.tokens, context(clientOf(current)));
+                revoked = true;
+            }
+            return { revoked, removed: storage.remove() };
+        }),
+    };
+};

package/dist/oauth/provider.d.ts

@@ -0,0 +1,54 @@
+import type { Logger } from "@wirecat/cli-base";
+/** The app identity a provider issued; an installed app's secret is public, not account access. */
+export interface OAuthClient {
+    clientId: string;
+    clientSecret?: string;
+}
+export interface TokenSet {
+    accessToken?: string;
+    refreshToken: string;
+    /** UTC milliseconds; unknown means "refresh before use". */
+    expiresAt?: number;
+    scopes: string[];
+    tokenType?: string;
+}
+export interface RequestContext {
+    fetch: typeof fetch;
+    client: OAuthClient;
+    now: () => number;
+    signal?: AbortSignal;
+    log?: Logger;
+    /** The command that signs in again, named in every failure that needs it. */
+    signInCommand: string;
+}
+export interface ExchangeContext extends RequestContext {
+    /** The tokens being refreshed; absent for the first exchange. */
+    previous?: TokenSet;
+}
+/**
+ * A provider as a CLI declares it. cli-core holds no provider's URLs or ids; every step may be replaced, and the
+ * keeper still holds the lock and the storage around it.
+ */
+export interface OAuthProvider {
+    /** A short word, part of new keyring account names: `google`, `zoom`. */
+    id: string;
+    /** The name people know, used in messages: `Google`. */
+    name: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    revokeUrl?: string;
+    client: OAuthClient;
+    /**
+     * `loopback` sends the browser to `http://127.0.0.1:<port>/callback`. `relay` sends it to a fixed page that
+     * forwards to the loopback port, which it reads from `state` (`<port>.<random>`).
+     */
+    redirect: {
+        kind: "loopback";
+    } | {
+        kind: "relay";
+        url: string;
+    };
+    authorizeParams?: Record<string, string>;
+    exchange?: (params: Record<string, string>, context: ExchangeContext) => Promise<TokenSet>;
+    revoke?: (tokens: TokenSet, context: RequestContext) => Promise<void>;
+}

package/dist/oauth/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/oauth/requests.d.ts

@@ -0,0 +1,11 @@
+import type { ExchangeContext, OAuthProvider, RequestContext, TokenSet } from "./provider.js";
+export declare const TOKEN_LOG_EVENT = "oauth.token";
+/** The keys the module's log records carry, for a run log's `allow`; names only, never a token. */
+export declare const TOKEN_LOG_ALLOW: readonly ["provider", "operation", "outcome", "status", "rotated", "pid"];
+/**
+ * The token endpoint, form-encoded, for both grants. Nothing from the request or the response reaches a message or
+ * a log record: both carry codes and tokens.
+ */
+export declare const requestTokens: (provider: OAuthProvider, params: Record<string, string>, context: ExchangeContext) => Promise<TokenSet>;
+/** Revokes the refresh token at `revokeUrl`. A provider without one, or with another method, declares `revoke`. */
+export declare const revokeToken: (provider: OAuthProvider, tokens: TokenSet, context: RequestContext) => Promise<void>;

package/dist/oauth/requests.js

@@ -0,0 +1,129 @@
+import { CliError, isCliError } from "@wirecat/cli-base";
+const REQUEST_LIMIT_MS = 30_000;
+export const TOKEN_LOG_EVENT = "oauth.token";
+/** The keys the module's log records carry, for a run log's `allow`; names only, never a token. */
+export const TOKEN_LOG_ALLOW = ["provider", "operation", "outcome", "status", "rotated", "pid"];
+const object = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("not an object");
+    return value;
+};
+const requestSignal = (signal) => signal ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_LIMIT_MS)]) : AbortSignal.timeout(REQUEST_LIMIT_MS);
+const cancelledBy = (signal) => {
+    if (!signal?.aborted)
+        return;
+    throw isCliError(signal.reason) ? signal.reason : new CliError("cancelled", "sign-in was cancelled");
+};
+const post = async (url, body, context) => {
+    cancelledBy(context.signal);
+    try {
+        return await context.fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body,
+            signal: requestSignal(context.signal),
+            redirect: "error",
+        });
+    }
+    catch {
+        cancelledBy(context.signal);
+        return undefined;
+    }
+};
+const clientFields = ({ client }) => ({
+    client_id: client.clientId,
+    ...(client.clientSecret ? { client_secret: client.clientSecret } : {}),
+});
+/**
+ * The token endpoint, form-encoded, for both grants. Nothing from the request or the response reaches a message or
+ * a log record: both carry codes and tokens.
+ */
+export const requestTokens = async (provider, params, context) => {
+    const operation = params.grant_type ?? "unknown";
+    const record = (level, fields) => context.log?.[level]({ event: TOKEN_LOG_EVENT, provider: provider.id, operation, pid: process.pid, ...fields });
+    const again = `run ${context.signInCommand} again`;
+    const response = await post(provider.tokenUrl, new URLSearchParams({ ...params, ...clientFields(context) }), context);
+    if (!response) {
+        record("warn", { outcome: "no_response" });
+        throw new CliError("outcome_unknown", `${provider.name} token request did not finish; ${again} if it keeps failing`, {
+            reason: "oauth.no-response",
+        });
+    }
+    if (!response.ok) {
+        record("warn", { outcome: "rejected", status: response.status });
+        if (response.status === 429 || response.status >= 500)
+            throw new CliError("provider_unavailable", `${provider.name} token request failed (HTTP ${response.status})`, {
+                status: response.status,
+                retryable: true,
+                reason: "oauth.unavailable",
+            });
+        throw new CliError("authentication_error", `${provider.name} sign-in was refused (HTTP ${response.status}); ${again}`, {
+            status: response.status,
+            reason: "oauth.expired",
+        });
+    }
+    let body;
+    try {
+        body = object(await response.json());
+    }
+    catch {
+        record("error", { outcome: "unreadable_response", status: response.status });
+        throw new CliError("invalid_response", `${provider.name} returned an unreadable token response; ${again}`, {
+            reason: "oauth.invalid-response",
+        });
+    }
+    const previous = context.previous;
+    const refreshToken = typeof body.refresh_token === "string" && body.refresh_token ? body.refresh_token : previous?.refreshToken;
+    const expiresIn = body.expires_in;
+    if (typeof body.access_token !== "string" ||
+        !body.access_token ||
+        (expiresIn !== undefined && (typeof expiresIn !== "number" || !Number.isFinite(expiresIn) || expiresIn <= 0)) ||
+        (body.scope !== undefined && typeof body.scope !== "string") ||
+        (body.token_type !== undefined && typeof body.token_type !== "string")) {
+        record("error", { outcome: "invalid_response", status: response.status });
+        throw new CliError("invalid_response", `${provider.name} returned an invalid token response; ${again}`, {
+            reason: "oauth.invalid-response",
+        });
+    }
+    if (!refreshToken) {
+        record("error", { outcome: "no_refresh_token", status: response.status });
+        throw new CliError("authentication_error", `${provider.name} returned no offline refresh token; ${again}`, {
+            reason: "oauth.failed",
+        });
+    }
+    const scopes = typeof body.scope === "string" ? body.scope.split(/\s+/).filter(Boolean) : (previous?.scopes ?? []);
+    const tokenType = typeof body.token_type === "string" ? body.token_type : previous?.tokenType;
+    record("info", {
+        outcome: "received",
+        status: response.status,
+        ...(previous ? { rotated: refreshToken !== previous.refreshToken } : {}),
+    });
+    return {
+        accessToken: body.access_token,
+        refreshToken,
+        ...(typeof expiresIn === "number" ? { expiresAt: context.now() + expiresIn * 1000 } : {}),
+        scopes,
+        ...(tokenType ? { tokenType } : {}),
+    };
+};
+/** Revokes the refresh token at `revokeUrl`. A provider without one, or with another method, declares `revoke`. */
+export const revokeToken = async (provider, tokens, context) => {
+    if (provider.revoke)
+        return provider.revoke(tokens, context);
+    if (!provider.revokeUrl)
+        throw new CliError("validation_error", `${provider.name} declares no way to revoke a sign-in`);
+    const response = await post(provider.revokeUrl, new URLSearchParams({ token: tokens.refreshToken, ...clientFields(context) }), context);
+    context.log?.[response?.ok ? "info" : "warn"]({
+        event: TOKEN_LOG_EVENT,
+        provider: provider.id,
+        operation: "revoke",
+        pid: process.pid,
+        outcome: response?.ok ? "revoked" : response ? "rejected" : "no_response",
+        ...(response ? { status: response.status } : {}),
+    });
+    if (!response?.ok)
+        throw new CliError("outcome_unknown", `${provider.name} did not confirm the revoke`, {
+            reason: "oauth.revoke-failed",
+            ...(response ? { status: response.status } : {}),
+        });
+};

package/dist/oauth/storage.d.ts

@@ -0,0 +1,48 @@
+import { type CredentialSource, type CredentialsOptions } from "@wirecat/cli-base";
+import type { OAuthClient, TokenSet } from "./provider.js";
+export interface StoredTokens {
+    tokens: TokenSet;
+    /** The app the entry was signed in with, when the entry records it; refresh must use that one. */
+    client?: OAuthClient;
+}
+export interface EncodeInput {
+    tokens: TokenSet;
+    client: OAuthClient;
+    /** The entry as stored before, so fields the codec does not own survive a write. */
+    previous?: string;
+    /** Fields a CLI adds at sign-in, such as drive's `principal`. */
+    extra?: Record<string, unknown>;
+}
+/** Every failure throws a fixed message: a parser's message would quote the secret. */
+export interface TokenCodec {
+    decode(raw: string): StoredTokens;
+    encode(input: EncodeInput): string;
+}
+export interface TokenStorage {
+    /** Names the entry across processes; the lock is keyed by it. */
+    readonly key: string;
+    /** Throws when the entry cannot be saved, so a sign-in fails before the browser, not after consent. */
+    probe(): void;
+    read(): StoredTokens | undefined;
+    write(input: Omit<EncodeInput, "previous">): void;
+    remove(): CredentialSource[];
+}
+export declare const oauthAccount: (providerId: string, profile: string) => string;
+/** The entry every new sign-in writes: account `oauth:<provider>:<profile>` under the CLI's own service. */
+export declare const standardCodec: (providerId: string) => TokenCodec;
+/**
+ * drive's entry as drive-cli writes it today: `{principal, clientId, clientSecret?, tokens: {access_token,
+ * refresh_token, expiry_date, scope, token_type, …}}`. A write keeps every field it does not own.
+ */
+export declare const driveSessionCodec: TokenCodec;
+/** zm's entry as zoom-cli writes it today: `{accessToken, refreshToken, expiresAt, scopes}`, all four required. */
+export declare const zoomTokenCodec: TokenCodec;
+export interface CredentialStorageOptions {
+    /** What the CLI passes `Credentials` today; the same options address the same entry. */
+    credentials: CredentialsOptions;
+    account: string;
+    /** Older accounts read when `account` is empty; a hit is copied to `account` and left in place. */
+    legacyAccounts?: readonly string[];
+    codec: TokenCodec;
+}
+export declare const credentialStorage: (options: CredentialStorageOptions) => TokenStorage;

package/dist/oauth/storage.js

@@ -0,0 +1,197 @@
+import { CliError, Credentials, keyringService, } from "@wirecat/cli-base";
+const invalid = () => new CliError("authentication_error", "the saved sign-in cannot be read; sign in again", { reason: "oauth.invalid" });
+const parse = (raw) => {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw invalid();
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw invalid();
+    return value;
+};
+const text = (value) => (typeof value === "string" && value ? value : undefined);
+const finite = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+const previousOf = (raw) => {
+    if (raw === undefined)
+        return {};
+    try {
+        return parse(raw);
+    }
+    catch {
+        return {};
+    }
+};
+const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
+export const oauthAccount = (providerId, profile) => {
+    if (!profile.trim())
+        throw new CliError("validation_error", "name a profile: a sign-in always belongs to one");
+    return `oauth:${providerId}:${profile}`;
+};
+/** The entry every new sign-in writes: account `oauth:<provider>:<profile>` under the CLI's own service. */
+export const standardCodec = (providerId) => ({
+    decode: (raw) => {
+        const value = parse(raw);
+        const refreshToken = text(value.refreshToken);
+        const clientId = text(value.clientId);
+        if (value.version !== 1 || value.provider !== providerId || !refreshToken || !clientId)
+            throw invalid();
+        if (!Array.isArray(value.scopes) || !value.scopes.every((scope) => typeof scope === "string"))
+            throw invalid();
+        return {
+            client: { clientId },
+            tokens: defined({
+                accessToken: text(value.accessToken),
+                refreshToken,
+                expiresAt: finite(value.expiresAt),
+                scopes: value.scopes,
+                tokenType: text(value.tokenType),
+            }),
+        };
+    },
+    encode: ({ tokens, client, previous, extra }) => JSON.stringify(defined({
+        ...previousOf(previous),
+        ...extra,
+        version: 1,
+        provider: providerId,
+        clientId: client.clientId,
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+        expiresAt: tokens.expiresAt,
+        scopes: tokens.scopes,
+        tokenType: tokens.tokenType,
+    })),
+});
+/**
+ * drive's entry as drive-cli writes it today: `{principal, clientId, clientSecret?, tokens: {access_token,
+ * refresh_token, expiry_date, scope, token_type, …}}`. A write keeps every field it does not own.
+ */
+export const driveSessionCodec = {
+    decode: (raw) => {
+        const value = parse(raw);
+        const tokens = value.tokens;
+        if (typeof tokens !== "object" || tokens === null || Array.isArray(tokens))
+            throw invalid();
+        const fields = tokens;
+        const refreshToken = text(fields.refresh_token);
+        const clientId = text(value.clientId);
+        if (!refreshToken || !clientId || typeof value.principal !== "string")
+            throw invalid();
+        return {
+            client: defined({ clientId, clientSecret: text(value.clientSecret) }),
+            tokens: defined({
+                accessToken: text(fields.access_token),
+                refreshToken,
+                expiresAt: finite(fields.expiry_date),
+                scopes: typeof fields.scope === "string" ? fields.scope.split(/\s+/).filter(Boolean) : [],
+                tokenType: text(fields.token_type),
+            }),
+        };
+    },
+    encode: ({ tokens, client, previous, extra }) => {
+        const before = previousOf(previous);
+        const oldTokens = typeof before.tokens === "object" && before.tokens !== null ? before.tokens : {};
+        const session = {
+            ...before,
+            ...extra,
+            clientId: client.clientId,
+            ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+            tokens: defined({
+                ...oldTokens,
+                access_token: tokens.accessToken,
+                refresh_token: tokens.refreshToken,
+                expiry_date: tokens.expiresAt,
+                ...(tokens.scopes.length ? { scope: tokens.scopes.join(" ") } : {}),
+                token_type: tokens.tokenType,
+            }),
+        };
+        if (typeof session.principal !== "string")
+            throw new CliError("configuration_error", "drive's sign-in entry needs the account's principal");
+        return JSON.stringify(session);
+    },
+};
+/** zm's entry as zoom-cli writes it today: `{accessToken, refreshToken, expiresAt, scopes}`, all four required. */
+export const zoomTokenCodec = {
+    decode: (raw) => {
+        const value = parse(raw);
+        const accessToken = text(value.accessToken);
+        const refreshToken = text(value.refreshToken);
+        const expiresAt = finite(value.expiresAt);
+        if (!accessToken || !refreshToken || expiresAt === undefined)
+            throw invalid();
+        if (!Array.isArray(value.scopes) || !value.scopes.every((scope) => typeof scope === "string"))
+            throw invalid();
+        return { tokens: { accessToken, refreshToken, expiresAt, scopes: value.scopes } };
+    },
+    encode: ({ tokens }) => {
+        if (!tokens.accessToken)
+            throw new CliError("invalid_response", "zm's sign-in entry needs an access token");
+        return JSON.stringify({
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt ?? 0,
+            scopes: tokens.scopes,
+        });
+    },
+};
+const keyringFailure = () => new CliError("configuration_error", "could not reach the saved sign-in; use an available keyring or file storage", {
+    reason: "oauth.not-saved",
+});
+export const credentialStorage = (options) => {
+    if (!options.credentials.keyring)
+        throw new CliError("configuration_error", "a sign-in store needs its keyring passed in, never a default");
+    const credentials = new Credentials(options.credentials);
+    const { account, codec } = options;
+    const service = keyringService(options.credentials.service, options.credentials.configDir, options.credentials.isolated);
+    const raw = (name) => {
+        try {
+            return credentials.read(name)?.secret;
+        }
+        catch {
+            throw keyringFailure();
+        }
+    };
+    const save = (value) => {
+        try {
+            credentials.write(account, value);
+        }
+        catch {
+            throw keyringFailure();
+        }
+    };
+    const current = () => {
+        const own = raw(account);
+        if (own !== undefined)
+            return own;
+        for (const legacy of options.legacyAccounts ?? []) {
+            const found = raw(legacy);
+            if (found === undefined)
+                continue;
+            codec.decode(found);
+            save(found);
+            return found;
+        }
+        return undefined;
+    };
+    return {
+        key: `${service}\u0000${account}`,
+        probe: () => {
+            raw(account);
+        },
+        read: () => {
+            const value = current();
+            return value === undefined ? undefined : codec.decode(value);
+        },
+        write: (input) => save(codec.encode({ ...input, previous: raw(account) })),
+        remove: () => {
+            try {
+                return credentials.remove(account);
+            }
+            catch {
+                throw keyringFailure();
+            }
+        },
+    };
+};

package/dist/ports/app.d.ts

@@ -14,6 +14,11 @@ export interface AppIdentity {
     issues?: string;
     /** The language of the transcript a person reads: its day headings and the word for "you". `ru-RU` when unset. */
     locale?: string;
+    /**
+     * ISO 639-1 codes of the languages its content is mostly in (`["ru"]`). The first run pre-ticks the ones search
+     * can stem in place of English and the system's language; the person still confirms, since the choice is shared.
+     */
+    contentLanguages?: readonly string[];
     /** Error reasons and detail keys of its own — max's `max_code`, tg's `migrated_chat_id` — kept in every error it prints. */
     errors?: AppErrors;
 }

package/dist/services/project-gathering.d.ts

@@ -77,6 +77,8 @@ export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, reque
         source: number | null;
         lane: string | null;
         state: "in-scope" | "out-of-scope" | "unavailable";
+        items: number;
+        capped: boolean;
     }[];
     fetch: {
         state: ProjectFetchState;