@every-app/sdk 0.2.0 → 0.3.0-rc.10

package/dist/internal/remoteMcp.js

@@ -0,0 +1,543 @@
+/**
+ * Remote MCP apps: any remote MCP server registered on a gateway by URL
+ * (`everyapp mcp add <url>`, Admin → Apps → Add app → "Add an MCP server",
+ * `everyapp_mcp_add`), served to members' AI clients as an MCP app of the
+ * Gateway's own, like a built-in provider app (./providerApps.ts) but with
+ * its tools read from the server and each call forwarded to it with a
+ * credential the Gateway holds (docs/design/2026-10-mcp-by-url.md).
+ *
+ * The registration record is the app row's manifest: `id`, `name`,
+ * `description` and a `remote` block ({@link RemoteMcpBlock}): the one URL
+ * the Gateway ever fetches, how it authenticates ({@link RemoteMcpAuth},
+ * the credential always the NAME of a Gateway setting, never a value), how
+ * a tool's risk is decided when the server's annotations don't say, the
+ * operator's per-tool overrides, and a revision the writers bump so the
+ * Gateway re-lists the tools on first use after a change.
+ *
+ * Everything here is pure and shared by the CLI, the perimeter's registry
+ * rules, the Gateway (which serves the row and validates again at every
+ * fetch) and the settings model (./appSettings.ts), so the rules cannot
+ * drift: what the URL may be, what the credential may be called, how a
+ * server's tool names become the ToolBus's, and what risk a tool gets.
+ */
+import { CAPABILITIES } from "./capabilities.js";
+import { isRemoteMcpSecretName } from "./gatewaySettings.js";
+import { isProviderAppId } from "./providerApps.js";
+import { TOOL_NAME_PATTERN, isToolRisk } from "./tools.js";
+export const REMOTE_MCP_AUTH_KINDS = [
+    "none",
+    "bearer",
+    "header",
+    "basic",
+    "oauth",
+];
+/**
+ * How a tool's risk is decided for the app. `annotations`: from the
+ * server's hints ({@link remoteToolRisk}); `read` or `write`: every tool,
+ * whatever it says. A per-tool override wins over all three.
+ */
+export const REMOTE_MCP_RISK_DEFAULTS = [
+    "annotations",
+    "read",
+    "write",
+];
+const ID_PATTERN = /^[a-z]([a-z0-9-]*[a-z0-9])?$/;
+const ID_MAX_LENGTH = 32;
+/** App ids a remote server can't take: the Gateway's own tool prefix. */
+const RESERVED_IDS = ["everyapp"];
+const SECRET_MAX_LENGTH = 64;
+const HEADER_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,100}$/;
+const PREFIX_MAX_LENGTH = 32;
+const URL_MAX_LENGTH = 2048;
+const NAME_MAX_LENGTH = 255;
+const DESCRIPTION_MAX_LENGTH = 1000;
+const OVERRIDES_MAX = 500;
+const UPSTREAM_NAME_MAX = 256;
+/**
+ * Headers the `header` kind may not name: the ones the Gateway sets on the
+ * request, the ones that route it, and the ones that would carry something
+ * other than this app's credential.
+ */
+const FORBIDDEN_AUTH_HEADERS = new Set([
+    "authorization",
+    "cookie",
+    "host",
+    "content-type",
+    "content-length",
+    "accept",
+    "connection",
+    "transfer-encoding",
+    "mcp-session-id",
+    "mcp-protocol-version",
+    "mcp-method",
+    "mcp-name",
+]);
+/** The default credential name for an app id: `treg` → `TREG_MCP_TOKEN`. */
+export function remoteMcpSecretName(id) {
+    return `${id.toUpperCase().replace(/-/g, "_")}_MCP_TOKEN`;
+}
+/** Whether `id` can be a remote MCP app's id (kebab-case, at most 32, not reserved, not a built-in's). */
+export function remoteMcpIdProblem(id) {
+    if (typeof id !== "string" || !ID_PATTERN.test(id)) {
+        return "the id must be kebab-case: lowercase letters, digits and hyphens, starting with a letter";
+    }
+    if (id.length > ID_MAX_LENGTH) {
+        return `the id must be at most ${ID_MAX_LENGTH} characters`;
+    }
+    if (RESERVED_IDS.includes(id))
+        return `"${id}" is reserved`;
+    if (isProviderAppId(id)) {
+        return `"${id}" is the Gateway's built-in MCP app; a remote server can't take its id`;
+    }
+    return null;
+}
+/**
+ * An app id from the server's URL: the host's registrable name, `www`,
+ * `mcp` and `api` dropped (`https://mcp.deepwiki.com/mcp` → `deepwiki`,
+ * `https://treg.to/mcp/` → `treg`); null when nothing usable is left (an
+ * IP, `localhost`), in which case the caller asks for `--name`.
+ */
+export function remoteMcpIdFromUrl(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase().replace(/\.$/, "");
+    }
+    catch {
+        return null;
+    }
+    if (!host || /^[\d.]+$/.test(host) || host.includes(":"))
+        return null;
+    const labels = host.split(".").filter((label) => label.length > 0);
+    if (labels.length < 2)
+        return null;
+    // The label before the public suffix, roughly: the last label that
+    // isn't a known two-level suffix part (co.uk, com.au).
+    const SECOND_LEVEL = new Set(["co", "com", "net", "org", "gov", "edu", "ac"]);
+    let index = labels.length - 2;
+    if (index > 0 &&
+        SECOND_LEVEL.has(labels[index]) &&
+        labels[index + 1].length === 2) {
+        index -= 1;
+    }
+    const candidate = labels[index] ?? "";
+    const id = candidate
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-")
+        .slice(0, ID_MAX_LENGTH)
+        .replace(/-+$/g, "");
+    if (!id || !ID_PATTERN.test(id))
+        return null;
+    return remoteMcpIdProblem(id) ? null : id;
+}
+function isSameOrSubdomain(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/** The hosts whose keys the Gateway holds: a remote server is never one of them. */
+export function reservedUpstreamHosts() {
+    const hosts = new Set([
+        "api.openai.com",
+        "openrouter.ai",
+        "gateway.ai.cloudflare.com",
+        "api.cloudflare.com",
+    ]);
+    for (const capability of Object.values(CAPABILITIES)) {
+        if (capability.mode === "api_key") {
+            for (const host of capability.hosts)
+                hosts.add(host);
+        }
+        else if (capability.mode === "oauth_client") {
+            for (const endpoint of capability.token) {
+                if ("host" in endpoint && typeof endpoint.host === "string") {
+                    hosts.add(endpoint.host);
+                }
+            }
+        }
+    }
+    return [...hosts].sort();
+}
+/**
+ * Why `url` can't be a remote MCP server's address, or null when it can:
+ * `https:` (or `http:` and loopback hosts only while the Gateway itself
+ * runs on `http://`, local dev), a host name rather than an address, no
+ * credentials or fragment in it, not the Gateway's own origin or one of
+ * its app hosts, and not a provider whose key the Gateway holds. The
+ * Gateway checks the stored URL again before every fetch, so a row edited
+ * by hand is refused the same way.
+ */
+export function remoteMcpUrlProblem(url, env) {
+    if (typeof url !== "string" || !url.trim())
+        return "give the server's URL";
+    if (url.length > URL_MAX_LENGTH)
+        return "the URL is too long";
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return "the URL doesn't parse";
+    }
+    const local = env.gatewayUrl.trim().toLowerCase().startsWith("http://");
+    if (parsed.username || parsed.password) {
+        return "the URL must not carry credentials; the Gateway sends the credential from its own setting";
+    }
+    if (parsed.hash)
+        return "the URL must not have a fragment";
+    const host = parsed.hostname.toLowerCase().replace(/\.$/, "");
+    const loopback = host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host === "127.0.0.1" ||
+        host === "[::1]" ||
+        host === "::1";
+    if (parsed.protocol !== "https:") {
+        if (parsed.protocol === "http:" && local && loopback) {
+            // Local dev: a fake or local server on this machine.
+        }
+        else {
+            return local
+                ? "the URL must be https://, or http:// on localhost while the Gateway runs locally"
+                : "the URL must be https://";
+        }
+    }
+    if (!host)
+        return "the URL has no host";
+    if (!loopback && (/^[\d.]+$/.test(host) || host.startsWith("["))) {
+        return "the URL must name a host, not an IP address";
+    }
+    if (loopback && !local) {
+        return "the URL must name a public host";
+    }
+    // The Gateway's own host: any port and every subdomain of it in
+    // production (a Worker on the same zone would be the gateway or an app);
+    // in local dev the exact origin only, so a fake server on another
+    // localhost port is fine.
+    let gatewayHost = "";
+    let gatewayOrigin = "";
+    try {
+        const gateway = new URL(env.gatewayUrl);
+        gatewayHost = gateway.hostname.toLowerCase().replace(/\.$/, "");
+        gatewayOrigin = gateway.origin.toLowerCase();
+    }
+    catch {
+        gatewayHost = "";
+    }
+    if (gatewayHost) {
+        const ownHost = local
+            ? parsed.origin.toLowerCase() === gatewayOrigin
+            : isSameOrSubdomain(host, gatewayHost);
+        if (ownHost)
+            return "the URL is this Gateway's own address";
+    }
+    for (const domain of [env.appBaseDomain, env.thirdPartyDomain]) {
+        const normalized = (domain ?? "").trim().toLowerCase().replace(/\.$/, "");
+        if (normalized && isSameOrSubdomain(host, normalized)) {
+            return `the URL is on this Gateway's app domain (${normalized})`;
+        }
+    }
+    if (reservedUpstreamHosts().includes(host)) {
+        return `${host} is a provider this Gateway holds a key for; apps reach it through the Gateway's capabilities, not as an MCP app`;
+    }
+    return null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The credential name's problem, or null: in the family, and bounded. */
+export function remoteMcpSecretProblem(name) {
+    if (typeof name !== "string" || !name)
+        return "give the credential's setting name";
+    if (name.length > SECRET_MAX_LENGTH)
+        return "the credential's name is too long";
+    if (!isRemoteMcpSecretName(name)) {
+        return `the credential's name must end in _MCP_TOKEN (letters, digits and underscores), like ${remoteMcpSecretName("treg")}`;
+    }
+    return null;
+}
+/** The auth block's problem, or the block as typed. */
+export function parseRemoteMcpAuth(raw) {
+    if (!isRecord(raw) || typeof raw["kind"] !== "string") {
+        return { ok: false, problem: "auth must name a kind" };
+    }
+    const kind = raw["kind"];
+    if (!REMOTE_MCP_AUTH_KINDS.includes(kind)) {
+        return {
+            ok: false,
+            problem: `auth.kind must be one of ${REMOTE_MCP_AUTH_KINDS.join(", ")}`,
+        };
+    }
+    if (kind === "none" || kind === "oauth") {
+        return { ok: true, auth: { kind } };
+    }
+    const secretProblem = remoteMcpSecretProblem(raw["secret"]);
+    if (secretProblem)
+        return { ok: false, problem: `auth.secret: ${secretProblem}` };
+    const secret = raw["secret"];
+    if (kind === "bearer" || kind === "basic") {
+        return { ok: true, auth: { kind, secret } };
+    }
+    const header = raw["header"];
+    if (typeof header !== "string" || !HEADER_NAME_PATTERN.test(header)) {
+        return { ok: false, problem: "auth.header must be an HTTP header name" };
+    }
+    if (FORBIDDEN_AUTH_HEADERS.has(header.toLowerCase())) {
+        return {
+            ok: false,
+            problem: `auth.header can't be ${header}; use kind "bearer" or "basic" for Authorization`,
+        };
+    }
+    const prefix = raw["prefix"];
+    if (prefix !== undefined) {
+        if (typeof prefix !== "string" ||
+            prefix.length > PREFIX_MAX_LENGTH ||
+            /[\r\n]/.test(prefix)) {
+            return { ok: false, problem: "auth.prefix must be a short string" };
+        }
+    }
+    return {
+        ok: true,
+        auth: {
+            kind: "header",
+            secret,
+            header,
+            ...(typeof prefix === "string" && prefix ? { prefix } : {}),
+        },
+    };
+}
+/**
+ * The `remote` block of a stored manifest, checked field by field (a row
+ * edited by hand must not make the Gateway send a credential anywhere the
+ * rules refuse), or why it can't be read. The URL is checked against the
+ * Gateway's environment by the caller ({@link remoteMcpUrlProblem}).
+ */
+export function parseRemoteMcpBlock(raw) {
+    if (!isRecord(raw))
+        return { ok: false, problem: "remote must be an object" };
+    const url = raw["url"];
+    if (typeof url !== "string" || !url || url.length > URL_MAX_LENGTH) {
+        return { ok: false, problem: "remote.url must be a URL" };
+    }
+    const auth = parseRemoteMcpAuth(raw["auth"]);
+    if (!auth.ok)
+        return auth;
+    const risk = raw["risk"] ?? "annotations";
+    if (!REMOTE_MCP_RISK_DEFAULTS.includes(risk)) {
+        return {
+            ok: false,
+            problem: `remote.risk must be one of ${REMOTE_MCP_RISK_DEFAULTS.join(", ")}`,
+        };
+    }
+    const tools = {};
+    const rawTools = raw["tools"] ?? {};
+    if (!isRecord(rawTools))
+        return { ok: false, problem: "remote.tools must be an object" };
+    const entries = Object.entries(rawTools);
+    if (entries.length > OVERRIDES_MAX) {
+        return {
+            ok: false,
+            problem: `remote.tools has more than ${OVERRIDES_MAX} entries`,
+        };
+    }
+    for (const [name, override] of entries) {
+        if (!name || name.length > UPSTREAM_NAME_MAX) {
+            return {
+                ok: false,
+                problem: "remote.tools has a tool name that is empty or too long",
+            };
+        }
+        if (!isRecord(override)) {
+            return { ok: false, problem: `remote.tools.${name} must be an object` };
+        }
+        const out = {};
+        if (override["risk"] !== undefined) {
+            if (!isToolRisk(override["risk"])) {
+                return {
+                    ok: false,
+                    problem: `remote.tools.${name}.risk must be read, write or destructive`,
+                };
+            }
+            out.risk = override["risk"];
+        }
+        if (override["enabled"] !== undefined) {
+            if (typeof override["enabled"] !== "boolean") {
+                return {
+                    ok: false,
+                    problem: `remote.tools.${name}.enabled must be true or false`,
+                };
+            }
+            out.enabled = override["enabled"];
+        }
+        tools[name] = out;
+    }
+    const rev = raw["rev"] ?? 1;
+    if (typeof rev !== "number" || !Number.isInteger(rev) || rev < 1) {
+        return { ok: false, problem: "remote.rev must be a positive integer" };
+    }
+    return {
+        ok: true,
+        block: {
+            url,
+            auth: auth.auth,
+            risk: risk,
+            tools,
+            rev,
+        },
+    };
+}
+/**
+ * The `remote` block of a stored manifest, or null when the manifest has
+ * none (a built-in provider app's, a deployed app's) or it can't be read
+ * (such a row is a provider row the Gateway serves nothing for and lists
+ * as needing setup, see app-setup).
+ */
+export function remoteMcpOf(manifest) {
+    if (!isRecord(manifest) || manifest["remote"] === undefined)
+        return null;
+    const parsed = parseRemoteMcpBlock(manifest["remote"]);
+    return parsed.ok ? parsed.block : null;
+}
+/** Whether a stored manifest declares a remote MCP server at all (well-formed or not). */
+export function hasRemoteMcpBlock(manifest) {
+    return isRecord(manifest) && manifest["remote"] !== undefined;
+}
+/** The credential's setting name the block declares, if its kind takes one. */
+export function remoteMcpSecretOf(auth) {
+    return "secret" in auth ? auth.secret : null;
+}
+/**
+ * A description for a row that gave none: the server's origin, read as a
+ * sentence. The origin only: a path or query may carry something the
+ * registrar meant for the server alone, and the description reaches every
+ * member with access and every AI client.
+ */
+export function remoteMcpDefaultDescription(name, url) {
+    let where = "";
+    try {
+        where = new URL(url).origin;
+    }
+    catch {
+        where = "";
+    }
+    return `${name}'s MCP server${where ? ` at ${where}` : ""}, served to your AI clients through this Gateway.`;
+}
+/**
+ * The operator's override for a server tool: by the server's name, or by
+ * a name that becomes the same ToolBus name ({@link normalizeRemoteToolName}),
+ * so a server that renames `send-mail` to `send_mail` can't bring a tool the
+ * operator turned off back under the same listed name.
+ */
+export function remoteToolOverride(block, upstreamName) {
+    const exact = block.tools[upstreamName];
+    if (exact)
+        return exact;
+    const local = normalizeRemoteToolName(upstreamName);
+    if (!local)
+        return undefined;
+    for (const [key, override] of Object.entries(block.tools)) {
+        if (normalizeRemoteToolName(key) === local)
+            return override;
+    }
+    return undefined;
+}
+/** Whether a server's tool name can travel in an HTTP header (`Mcp-Name`): visible ASCII, bounded. */
+export function isHeaderSafeToolName(name) {
+    return /^[\x21-\x7e]{1,256}$/.test(name);
+}
+/** The manifest a remote MCP app's row stores, from what the registrar gave. */
+export function remoteMcpAppManifest(input) {
+    const name = (input.name ?? "").trim().slice(0, NAME_MAX_LENGTH) || input.id;
+    const description = (input.description ?? "").trim().slice(0, DESCRIPTION_MAX_LENGTH) ||
+        remoteMcpDefaultDescription(name, input.remote.url);
+    return { id: input.id, name, description, remote: input.remote };
+}
+/**
+ * A tool's risk for the Gateway. An override wins; then the app's `read`
+ * or `write` default; then the server's hints, read conservatively: an
+ * explicit `readOnlyHint: true` is `read`, an explicit `destructiveHint:
+ * true` is `destructive` (hidden until approvals exist), and anything
+ * else, a missing hint included, is `write`. The spec's missing-means-true
+ * default for `destructiveHint` is not followed: it would hide every
+ * unhinted tool.
+ */
+export function remoteToolRisk(hints, block, upstreamName) {
+    const override = remoteToolOverride(block, upstreamName)?.risk;
+    if (override)
+        return { risk: override, source: "override" };
+    if (block.risk === "read" || block.risk === "write") {
+        return { risk: block.risk, source: "app" };
+    }
+    if (hints?.readOnlyHint === true)
+        return { risk: "read", source: "hint" };
+    if (hints?.destructiveHint === true) {
+        return { risk: "destructive", source: "hint" };
+    }
+    return { risk: "write", source: "default" };
+}
+/** Whether the operator left the tool on (the default). */
+export function remoteToolEnabled(block, upstreamName) {
+    return remoteToolOverride(block, upstreamName)?.enabled !== false;
+}
+/**
+ * A server's tool name as the ToolBus lists it: lowercase snake_case, at
+ * most 48 characters (`TOOL_NAME_PATTERN`). camelCase is split
+ * (`getUser` → `get_user`), `-`, `.`, `/` and spaces become `_`, anything
+ * else is dropped, runs of `_` collapse, and a leading digit gets a `t_`
+ * in front. Null when nothing usable is left.
+ */
+export function normalizeRemoteToolName(name) {
+    if (typeof name !== "string")
+        return null;
+    let out = name
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase()
+        .replace(/[\s./:-]+/g, "_")
+        .replace(/[^a-z0-9_]/g, "")
+        .replace(/_{2,}/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!out)
+        return null;
+    if (/^[0-9]/.test(out))
+        out = `t_${out}`;
+    out = out.slice(0, 48).replace(/_+$/g, "");
+    return TOOL_NAME_PATTERN.test(out) ? out : null;
+}
+/**
+ * The request headers that carry the credential for `auth`, from the
+ * setting's value. The value never appears anywhere else.
+ */
+export function remoteMcpAuthHeaders(auth, value) {
+    switch (auth.kind) {
+        case "none":
+        case "oauth":
+            return {};
+        case "bearer":
+            return { authorization: `Bearer ${value}` };
+        case "basic":
+            return { authorization: `Basic ${base64(value)}` };
+        case "header":
+            return { [auth.header]: `${auth.prefix ?? ""}${value}` };
+    }
+}
+function base64(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+/** Plain words for an auth kind, for lists and dialogs. */
+export function remoteMcpAuthLabel(auth) {
+    switch (auth.kind) {
+        case "none":
+            return "no credential";
+        case "bearer":
+            return "bearer token";
+        case "basic":
+            return "user and password";
+        case "header":
+            return `header ${auth.header}`;
+        case "oauth":
+            return "OAuth (not supported yet)";
+    }
+}

package/dist/internal/signInProviders.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The sign-in providers a Gateway can offer beside passwords ("Continue
+ * with Google"), as data: what each one is called, the Worker secrets it
+ * reads, where the OAuth app is made, the scopes asked for and which claim
+ * becomes the email. One catalog serves the Gateway (which providers are
+ * on, the sign-in page's buttons, Manage workspace → Sign-in), the CLI
+ * (`everyapp signin add|list|show|remove`, `secret set`), the manifest
+ * validator (an app's own secret can never take one of these names) and
+ * the docs' drift tests.
+ *
+ * Naming rule, agreed with the provider registry's conventions
+ * (docs/design/2026-10-provider-registry.md, section 6): a sign-in
+ * provider's settings are `<ID>_SIGNIN_<FIELD>`, with FIELD one of
+ * CLIENT_ID, CLIENT_SECRET, ISSUER, LABEL or TENANT. The `_SIGNIN_` infix is
+ * what keeps the family apart from the API providers' `<ID>_API_KEY`,
+ * `<ID>_CLIENT_ID` (the OAuth clients the Gateway holds for apps) and the
+ * MCP apps' `<ID>_MCP_TOKEN`: `GOOGLE_SIGNIN_CLIENT_ID` is the sign-in
+ * provider's, `GOOGLE_WORKSPACE_CLIENT_ID` the OAuth client apps use, and
+ * a registered provider row or an app manifest can never claim a name in
+ * the family (isSignInSettingName).
+ *
+ * The settings are Worker secrets, set under the Cloudflare login (`everyapp
+ * signin add`, or `secret set`), never from the admin UI or an agent
+ * connection: a stolen session can't add a way in.
+ */
+export declare const SIGN_IN_PROVIDER_IDS: readonly ["google", "microsoft", "github", "apple", "cloudflare", "oidc"];
+export type SignInProviderId = (typeof SIGN_IN_PROVIDER_IDS)[number];
+/** What a setting of a sign-in provider holds. */
+export type SignInSettingRole = "clientId" | "clientSecret" | "issuer" | "label" | "tenant";
+export interface SignInSetting {
+    /** `GOOGLE_SIGNIN_CLIENT_ID`. */
+    readonly name: string;
+    readonly role: SignInSettingRole;
+    /** Without it the provider is off (an incomplete set is reported). */
+    readonly required: boolean;
+    /**
+     * A plain value (an id, a URL, a word) `everyapp secret set` may show as
+     * typed; a credential stays hidden.
+     */
+    readonly plain: boolean;
+    /** One line: what to paste here. */
+    readonly what: string;
+}
+export interface SignInProvider {
+    readonly id: SignInProviderId;
+    /** The button: "Continue with <label>". The `oidc` entry's label is a setting. */
+    readonly label: string;
+    /** Where the OAuth app is created. */
+    readonly console: string;
+    /** What the OAuth app is called there ("OAuth client ID", "App registration"). */
+    readonly appNoun: string;
+    readonly settings: readonly SignInSetting[];
+    /** The scopes requested: identity only, nothing an app could act with. */
+    readonly scopes: readonly string[];
+    /** Which claim becomes the email, and what makes it count as verified. */
+    readonly emailClaim: string;
+    /** The everyapp skill's setup guide, relative to the skill. */
+    readonly setup: `setup/signin-${SignInProviderId}.md`;
+    /** Caveats worth a line in every listing. */
+    readonly notes: readonly string[];
+}
+/** The path Better Auth serves the provider's callback on, under the Gateway's URL. */
+export declare function signInCallbackPath(id: SignInProviderId): string;
+/** The redirect URL to register with the provider, for a Gateway at `gatewayUrl`. */
+export declare function signInCallbackUrl(gatewayUrl: string, id: SignInProviderId): string;
+export declare const SIGN_IN_PROVIDERS: Readonly<Record<SignInProviderId, SignInProvider>>;
+/** The catalog in listing order. */
+export declare const SIGN_IN_PROVIDER_LIST: readonly SignInProvider[];
+export declare function isSignInProviderId(value: string): value is SignInProviderId;
+/**
+ * Every setting a sign-in provider reads, in catalog order: what `everyapp
+ * secret set` accepts for the Gateway, and what the Gateway's dev config
+ * declares.
+ */
+export declare const SIGN_IN_GATEWAY_SETTINGS: readonly string[];
+/** The plain (non-credential) ones among them: ids, the issuer, the label, the tenant. */
+export declare const PLAIN_SIGN_IN_SETTINGS: readonly string[];
+/**
+ * The family: any name of the shape `<ID>_SIGNIN_<FIELD>`. Reserved for the
+ * catalog above, whether or not an entry reads the name today, so no
+ * registered provider row and no app manifest can ever take one.
+ */
+export declare const SIGN_IN_SETTING_PATTERN: RegExp;
+export declare function isSignInSettingName(name: string): boolean;
+/** The provider a setting belongs to, if one reads it. */
+export declare function signInProviderOfSetting(name: string): SignInProvider | null;
+/** Whether a provider is on, off, or half set up, from which names are set. */
+export type SignInProviderStatus = "on" | "off" | "incomplete";
+export interface SignInProviderState {
+    readonly id: SignInProviderId;
+    readonly status: SignInProviderStatus;
+    /** The required settings not set (empty when on or off). */
+    readonly missing: readonly string[];
+    /** The settings set, required or not. */
+    readonly set: readonly string[];
+}
+/**
+ * A provider's state from which of its settings exist: on when every
+ * required one is set, off when none at all is, incomplete in between (the
+ * Gateway refuses to half-configure a sign-in: the provider is off and the
+ * problem is reported).
+ */
+export declare function signInProviderState(provider: SignInProvider, isSet: (name: string) => boolean): SignInProviderState;
+//# sourceMappingURL=signInProviders.d.ts.map

package/dist/internal/signInProviders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signInProviders.d.ts","sourceRoot":"","sources":["../../src/internal/signInProviders.ts"],"names":[],"mappings":"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"}