@every-app/sdk 0.1.14 → 0.3.0-rc.1

package/dist/internal/protocol.js

@@ -0,0 +1,250 @@
+/**
+ * @every-app/sdk/internal — Every App platform protocol internals.
+ *
+ * This subpath is for the Every App platform itself (gateway, perimeter, CLI),
+ * not for app authors. It owns the wire constants, claim shapes, claim codecs,
+ * and gateway-side JWT minters shared by the platform packages.
+ */
+import { SignJWT, importPKCS8 } from "jose";
+export const IDENTITY_ALG = "RS256";
+export const IDENTITY_KEY_ID = "everyapp-identity";
+export const IDENTITY_DEV_KEY_ID = "everyapp-identity-dev";
+/**
+ * The only issuer a dev-kid token may name. The same value as
+ * `@every-app/sdk/dev`'s, kept apart so the Worker never loads the module
+ * `cloudflare.config.ts` does (a test pins the two together).
+ */
+export const DEV_ISSUER = "https://gateway.dev.localhost";
+export const IDENTITY_HEADER = "x-everyapp-identity";
+export const PUBLIC_HEADER = "x-everyapp-public";
+/**
+ * Carries the gateway's system token on its own calls to an app (the tools
+ * catalog fetch). Never an identity: no user, and it only opens the endpoint
+ * named by its `purpose` claim.
+ */
+export const SYSTEM_HEADER = "x-everyapp-system";
+/**
+ * On a refusal the AppGateway binding makes itself (the app's manifest lacks
+ * the capability, the gateway holds no key), as opposed to the provider's
+ * own answer passed through: the refusal's code, also in the JSON body.
+ */
+export const GATEWAY_ERROR_HEADER = "x-everyapp-error";
+/**
+ * On a shared app's call to the AppGateway binding for work no request
+ * started (a cron, a Workflow step): the organization the work is for. The
+ * gateway believes it only from a shared app's Worker, and only for an
+ * active organization with a live member; an organization's own app may
+ * only name its own. The perimeter strips it, with every `x-everyapp-*`,
+ * from what browsers send.
+ */
+export const ORG_HEADER = "x-everyapp-org";
+/** 120-second lifetime — caps revocation staleness while surviving clock skew. */
+export const IDENTITY_TTL_SECONDS = 120;
+/** System tokens are minted per call and live at most a minute. */
+export const SYSTEM_TOKEN_TTL_SECONDS = 60;
+/** Env var carrying the app's manifest id. */
+export const APP_ID_ENV = "EVERYAPP_APP_ID";
+/**
+ * Env var carrying the expected identity audience: the app's Worker name,
+ * which the gateway stamps as `aud` on every token it mints for the app. Two
+ * Workers of one app id (two organizations' copies) never accept each
+ * other's tokens.
+ */
+export const AUDIENCE_ENV = "EVERYAPP_AUDIENCE";
+/** Default env var carrying a JSON array of SPKI PEM public keys. */
+export const PUBLIC_KEYS_ENV = "EVERYAPP_IDENTITY_PUBLIC_KEYS";
+/** Env var carrying the expected gateway issuer for user identity verification. */
+export const ISSUER_ENV = "EVERYAPP_IDENTITY_ISSUER";
+/**
+ * Env var set to `1` on a shared app's Workers (one Worker for every
+ * organization): a gateway call from them must say whom it is for.
+ */
+export const SHARED_ENV = "EVERYAPP_SHARED";
+/** When set to `1` or `true` in the worker env, the dev identity kid is accepted. */
+export const DEV_ENV = "EVERYAPP_DEV";
+/** `sub` claim the gateway mints public-route markers with. */
+export const PUBLIC_MARKER_SUB = "public";
+/** `sub` claim of gateway system tokens. */
+export const SYSTEM_TOKEN_SUB = "system";
+export class ProtocolClaimsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProtocolClaimsError";
+    }
+}
+export function identitySubjectToClaims(subject, opts) {
+    return {
+        typ: "user",
+        email: subject.email,
+        org_id: subject.orgId,
+        org_role: subject.orgRole,
+        chan: opts.channel ?? "web",
+        act: opts.actor ?? { sub: subject.sub },
+        scopes: opts.scopes ?? ["*"],
+        jti: opts.jti,
+        ...(opts.toolCall
+            ? { tc: { id: opts.toolCall.id, name: opts.toolCall.name } }
+            : {}),
+    };
+}
+function parseToolCallClaim(value) {
+    if (value === undefined)
+        return undefined;
+    const claim = value;
+    if (!claim ||
+        typeof claim !== "object" ||
+        typeof claim.id !== "string" ||
+        typeof claim.name !== "string" ||
+        !claim.id ||
+        !claim.name) {
+        throw new ProtocolClaimsError("identity token has a malformed tc claim");
+    }
+    return { id: claim.id, name: claim.name };
+}
+export function identityClaimsToEveryAppUser(payload) {
+    if (payload.typ !== "user") {
+        throw new ProtocolClaimsError("identity token has wrong typ");
+    }
+    const sub = payload.sub;
+    const email = payload.email;
+    const orgId = payload.org_id;
+    const orgRole = payload.org_role;
+    if (!sub || !email || !orgId || !orgRole) {
+        throw new ProtocolClaimsError("identity token missing required claims");
+    }
+    const chan = payload.chan ?? "web";
+    const act = payload.act ?? { sub };
+    const scopes = Array.isArray(payload.scopes)
+        ? payload.scopes.filter((scope) => typeof scope === "string")
+        : ["*"];
+    const toolCall = parseToolCallClaim(payload.tc);
+    return {
+        id: sub,
+        email,
+        orgId,
+        orgRole,
+        channel: chan,
+        actor: { sub: act.sub ?? sub },
+        scopes,
+        jti: payload.jti ?? "",
+        ...(toolCall ? { toolCall } : {}),
+    };
+}
+export function publicMarkerClaims(jti) {
+    return { typ: "public", pub: true, jti };
+}
+export function assertPublicMarkerClaims(payload) {
+    if (payload.typ !== "public") {
+        throw new ProtocolClaimsError("public marker has wrong typ");
+    }
+    if (payload.pub !== true || payload.sub !== PUBLIC_MARKER_SUB) {
+        throw new ProtocolClaimsError("token is not a public-route marker");
+    }
+}
+/**
+ * A system token opens exactly one endpoint and lives at most
+ * {@link SYSTEM_TOKEN_TTL_SECONDS}: a leaked one is short-lived and useless
+ * anywhere else.
+ */
+export function assertSystemClaims(payload, purpose) {
+    if (payload.typ !== "system" || payload.sub !== SYSTEM_TOKEN_SUB) {
+        throw new ProtocolClaimsError("token is not a system token");
+    }
+    if (payload.purpose !== purpose) {
+        throw new ProtocolClaimsError(`system token purpose "${String(payload.purpose)}" is not "${purpose}"`);
+    }
+    if (typeof payload.iat !== "number" ||
+        typeof payload.exp !== "number" ||
+        payload.exp - payload.iat > SYSTEM_TOKEN_TTL_SECONDS) {
+        throw new ProtocolClaimsError(`system token must expire within ${SYSTEM_TOKEN_TTL_SECONDS}s of issue`);
+    }
+    return payload;
+}
+let cachedPrivateKey = null;
+async function loadPrivateKey(privateKeyPem) {
+    const pem = privateKeyPem.replace(/\\n/g, "\n");
+    if (cachedPrivateKey && cachedPrivateKey.pem === pem) {
+        return cachedPrivateKey.key;
+    }
+    const key = await importPKCS8(pem, IDENTITY_ALG);
+    cachedPrivateKey = { pem, key };
+    return key;
+}
+/**
+ * Mint an identity JWT. Returns the compact JWS string to inject as
+ * `x-everyapp-identity`.
+ */
+export async function mintIdentityJwt(privateKeyPem, opts) {
+    const key = await loadPrivateKey(privateKeyPem);
+    const nowSec = Math.floor((opts.now ?? Date.now()) / 1000);
+    const ttl = opts.ttlSeconds ?? IDENTITY_TTL_SECONDS;
+    const jti = crypto.randomUUID();
+    return new SignJWT(identitySubjectToClaims(opts.subject, {
+        channel: opts.channel,
+        actor: opts.actor,
+        scopes: opts.scopes,
+        toolCall: opts.toolCall,
+        jti,
+    }))
+        .setProtectedHeader({
+        alg: IDENTITY_ALG,
+        kid: opts.keyId ?? IDENTITY_KEY_ID,
+    })
+        .setIssuer(opts.issuer)
+        .setSubject(opts.subject.sub)
+        .setAudience(opts.audience)
+        .setIssuedAt(nowSec)
+        .setExpirationTime(nowSec + ttl)
+        .sign(key);
+}
+/**
+ * Mint the public-route marker for `x-everyapp-public`. A bare header value
+ * is never a trust source, so the marker is a signed, short-lived, app-scoped
+ * JWT with `pub: true` and `typ: "public"` that the SDK verifies exactly like
+ * an identity token.
+ */
+export async function mintPublicMarkerJwt(privateKeyPem, opts) {
+    const key = await loadPrivateKey(privateKeyPem);
+    const nowSec = Math.floor((opts.now ?? Date.now()) / 1000);
+    const ttl = opts.ttlSeconds ?? IDENTITY_TTL_SECONDS;
+    return new SignJWT(publicMarkerClaims(crypto.randomUUID()))
+        .setProtectedHeader({
+        alg: IDENTITY_ALG,
+        kid: opts.keyId ?? IDENTITY_KEY_ID,
+    })
+        .setIssuer(opts.issuer)
+        .setSubject(PUBLIC_MARKER_SUB)
+        .setAudience(opts.audience)
+        .setIssuedAt(nowSec)
+        .setExpirationTime(nowSec + ttl)
+        .sign(key);
+}
+/**
+ * Mint the gateway's system token for `x-everyapp-system`: no user, one
+ * purpose, one app, one minute. The SDK only accepts it on the endpoint its
+ * purpose names, and never as an identity.
+ */
+export async function mintSystemJwt(privateKeyPem, opts) {
+    const ttl = opts.ttlSeconds ?? SYSTEM_TOKEN_TTL_SECONDS;
+    if (ttl <= 0 || ttl > SYSTEM_TOKEN_TTL_SECONDS) {
+        throw new RangeError(`system tokens live at most ${SYSTEM_TOKEN_TTL_SECONDS}s (got ${ttl})`);
+    }
+    const key = await loadPrivateKey(privateKeyPem);
+    const nowSec = Math.floor((opts.now ?? Date.now()) / 1000);
+    const claims = {
+        typ: "system",
+        purpose: opts.purpose,
+        jti: crypto.randomUUID(),
+    };
+    return new SignJWT(claims)
+        .setProtectedHeader({
+        alg: IDENTITY_ALG,
+        kid: opts.keyId ?? IDENTITY_KEY_ID,
+    })
+        .setIssuer(opts.issuer)
+        .setSubject(SYSTEM_TOKEN_SUB)
+        .setAudience(opts.audience)
+        .setIssuedAt(nowSec)
+        .setExpirationTime(nowSec + ttl)
+        .sign(key);
+}

package/dist/internal/providerApps.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Provider apps, "MCP apps" to the person: a data provider (DataForSEO
+ * today) offered to members as an app of the Gateway's own, with no page
+ * and no Worker to deploy. The operator turns it on (`everyapp mcp on
+ * <id>`) and sets the provider's key as a Gateway setting; the Gateway then
+ * serves the provider's tools on its `/mcp` under `<id>_<tool>` names, with
+ * the key never leaving the Gateway, every call attributed to the member
+ * who made it, counted and audited like an app's capability calls. The
+ * launcher lists it under "MCP apps" and its card opens the "Use it from
+ * your agent" dialog instead of a page (docs/design/2026-10-mcp-apps-ui.md).
+ *
+ * A provider app is an `apps` row of tier {@link PROVIDER_APP_TIER} with no
+ * hostname and no Worker name: the perimeter never routes it, and the
+ * Gateway reaches its tools in-process rather than over a service binding.
+ * Its manifest is generated here, so the settings model
+ * (./appSettings.ts) reads the provider's key as a required Gateway setting
+ * like any app's capability. The registry rules that write the row are in
+ * `@every-app/perimeter/registry` (providerApps.ts); the Gateway serves it
+ * from `apps/every-app-gateway/src/server/provider-apps/`.
+ */
+import { type ApiKeyCapabilityId } from "./capabilities.js";
+/** The `apps.tier` of a provider app: no Worker, served by the Gateway itself. */
+export declare const PROVIDER_APP_TIER = "provider";
+export interface ProviderAppDefinition {
+    /** The app id (its slug and tool-name prefix): lowercase, no underscore. */
+    id: string;
+    /** What Admin → Apps and the launcher call it. */
+    name: string;
+    /** What it is for, as the app library and `everyapp_list_apps` tell it. */
+    description: string;
+    /**
+     * The `api_key` capability whose Gateway setting holds the key and whose
+     * proxy rules (hosts, methods, account-wide paths) every tool call obeys.
+     */
+    capability: ApiKeyCapabilityId;
+    /** Why the app lists the capability: the manifest entry's `why`. */
+    why: string;
+    /**
+     * What to say to an agent to try it, after "Use <name> to": the "Use it
+     * from your agent" dialog's example sentence.
+     */
+    example: string;
+}
+export declare const PROVIDER_APPS: {
+    readonly dataforseo: {
+        readonly id: "dataforseo";
+        readonly name: "DataForSEO";
+        readonly description: "SEO data for your agent: keyword metrics and suggestions, live Google results, domain rankings, competitors and backlinks, through the Gateway's DataForSEO key.";
+        readonly capability: "dataforseo";
+        readonly why: "Serves DataForSEO's keyword, search-result, domain and backlink data to members' AI clients.";
+        readonly example: "find keyword ideas for a page about running shoes";
+    };
+};
+export type ProviderAppId = keyof typeof PROVIDER_APPS;
+/** The provider app ids, in a stable order. */
+export declare const PROVIDER_APP_IDS: ProviderAppId[];
+export declare function isProviderAppId(id: string): id is ProviderAppId;
+/** The Gateway setting that holds a provider app's key (`DATAFORSEO_API_KEY`). */
+export declare function providerAppKeySetting(id: ProviderAppId): string;
+/**
+ * The manifest a provider app's registry row stores: what a deployed app
+ * would declare to use the same capability, so Admin → Apps, the settings
+ * model and the integration proxy read it like any app's. Read-only
+ * access: every provider app only reads data.
+ */
+export declare function providerAppManifest(id: ProviderAppId): {
+    id: string;
+    name: string;
+    description: string;
+    capabilities: Record<string, {
+        access: "read";
+        why: string;
+    }>;
+};
+//# sourceMappingURL=providerApps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"providerApps.d.ts","sourceRoot":"","sources":["../../src/internal/providerApps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAE5C,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,EAAE,kBAAkB,CAAC;IAC/B,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,aAAa;;;;;;;;;CAUgC,CAAC;AAE3D,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,aAAa,CAAC;AAEvD,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,EAEjB,aAAa,EAAE,CAAC;AAE5B,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,aAAa,CAE/D;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,aAAa,GAAG;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/D,CAUA"}

package/dist/internal/providerApps.js

@@ -0,0 +1,59 @@
+/**
+ * Provider apps, "MCP apps" to the person: a data provider (DataForSEO
+ * today) offered to members as an app of the Gateway's own, with no page
+ * and no Worker to deploy. The operator turns it on (`everyapp mcp on
+ * <id>`) and sets the provider's key as a Gateway setting; the Gateway then
+ * serves the provider's tools on its `/mcp` under `<id>_<tool>` names, with
+ * the key never leaving the Gateway, every call attributed to the member
+ * who made it, counted and audited like an app's capability calls. The
+ * launcher lists it under "MCP apps" and its card opens the "Use it from
+ * your agent" dialog instead of a page (docs/design/2026-10-mcp-apps-ui.md).
+ *
+ * A provider app is an `apps` row of tier {@link PROVIDER_APP_TIER} with no
+ * hostname and no Worker name: the perimeter never routes it, and the
+ * Gateway reaches its tools in-process rather than over a service binding.
+ * Its manifest is generated here, so the settings model
+ * (./appSettings.ts) reads the provider's key as a required Gateway setting
+ * like any app's capability. The registry rules that write the row are in
+ * `@every-app/perimeter/registry` (providerApps.ts); the Gateway serves it
+ * from `apps/every-app-gateway/src/server/provider-apps/`.
+ */
+import { CAPABILITIES, authSettingNames, } from "./capabilities.js";
+/** The `apps.tier` of a provider app: no Worker, served by the Gateway itself. */
+export const PROVIDER_APP_TIER = "provider";
+export const PROVIDER_APPS = {
+    dataforseo: {
+        id: "dataforseo",
+        name: "DataForSEO",
+        description: "SEO data for your agent: keyword metrics and suggestions, live Google results, domain rankings, competitors and backlinks, through the Gateway's DataForSEO key.",
+        capability: "dataforseo",
+        why: "Serves DataForSEO's keyword, search-result, domain and backlink data to members' AI clients.",
+        example: "find keyword ideas for a page about running shoes",
+    },
+};
+/** The provider app ids, in a stable order. */
+export const PROVIDER_APP_IDS = Object.keys(PROVIDER_APPS).sort();
+export function isProviderAppId(id) {
+    return Object.hasOwn(PROVIDER_APPS, id);
+}
+/** The Gateway setting that holds a provider app's key (`DATAFORSEO_API_KEY`). */
+export function providerAppKeySetting(id) {
+    return authSettingNames(CAPABILITIES[PROVIDER_APPS[id].capability].auth)[0];
+}
+/**
+ * The manifest a provider app's registry row stores: what a deployed app
+ * would declare to use the same capability, so Admin → Apps, the settings
+ * model and the integration proxy read it like any app's. Read-only
+ * access: every provider app only reads data.
+ */
+export function providerAppManifest(id) {
+    const provider = PROVIDER_APPS[id];
+    return {
+        id: provider.id,
+        name: provider.name,
+        description: provider.description,
+        capabilities: {
+            [provider.capability]: { access: "read", why: provider.why },
+        },
+    };
+}

package/dist/internal/providerRegistry.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The provider registry: the built-in catalog (./capabilities.ts) and the
+ * providers one gateway registered as rows (`everyapp provider add`,
+ * `everyapp_provider_add`), resolved as one lookup
+ * (docs/design/2026-10-provider-registry.md). The catalog comes first and
+ * a row can never shadow it. Every row is parsed and checked again each
+ * time a registry is built, so a row written by hand into D1, or one that
+ * stopped passing the rules when a later catalog took its name, is left
+ * out and named in `rejected` rather than served.
+ *
+ * The rules a row must pass (the register's `registry.*` invariants):
+ *
+ *  - `registry.builtin-precedence`: not a catalog id, and never `everyapp`;
+ *  - `registry.row-secret-is-its-own`: each Gateway setting it names starts
+ *    with its own id (`STRIPE_` for `stripe`) and is nobody else's: no
+ *    install-owned, dev-only or reserved name, no settable Gateway setting
+ *    (the catalog's keys and clients included), no other row's;
+ *  - `registry.row-hosts-public-https`: each host is a public DNS name (not
+ *    an IP literal, localhost, or a `.local`, `.internal` or `.arpa` name)
+ *    and not one the gateway serves itself (`refuseHost`, which knows the
+ *    gateway's own host and `APP_BASE_DOMAIN`).
+ */
+import { type ApiKeyCapability, type Capability, type CapabilityLookup } from "./capabilities.js";
+/** A `providers` row as the gateway or the CLI read it. */
+export interface ProviderRow {
+    id: string;
+    /** The spec, as JSON text or already parsed. */
+    spec: unknown;
+    /**
+     * What the row's key was set for: {@link providerBindingKey} of the row
+     * as it was when `everyapp secret set` last set one of its settings;
+     * null until then. The gateway reads the row's settings only while this
+     * equals the key of the row it has now (`providers.value-bound-to-hosts`).
+     */
+    boundTo?: string | null;
+    /** Who registered it (the Cloudflare login's email, or a member's), for the person setting its key. */
+    addedBy?: string | null;
+    /** When, in epoch milliseconds. */
+    addedAt?: number | null;
+}
+/**
+ * The part of a row a key is set for: its hosts, its host setting and its
+ * auth, as one canonical string (sorted keys, sorted hosts), so that
+ * replacing a row's hosts or auth changes the key and the value it held
+ * is no longer read until the operator sets it again.
+ */
+export declare function providerBindingKey(capability: ApiKeyCapability): string;
+/** One registered row as `provider list` and `provider show` report it. */
+export interface RegisteredProvider {
+    id: string;
+    capability: ApiKeyCapability;
+    /** Whether the row's key was set for the hosts and auth it has now. */
+    bound: boolean;
+    addedBy: string | null;
+    addedAt: number | null;
+}
+export type RowRefusalCode = "PROVIDER_SPEC_INVALID" | "PROVIDER_BUILTIN" | "PROVIDER_SECRET_TAKEN" | "PROVIDER_HOST_REFUSED";
+/** Why a row is not a provider on this gateway. */
+export interface RowRefusal {
+    id: string;
+    code: RowRefusalCode;
+    message: string;
+}
+export interface ProviderRegistry extends CapabilityLookup {
+    /** Every id, the catalog's first in catalog order, then the rows' in row order. */
+    ids(): readonly string[];
+    entries(): ReadonlyArray<readonly [string, Capability]>;
+    sourceOf(id: string): "catalog" | "row" | undefined;
+    /** Every Gateway setting any provider reads, the catalog's and the rows'. */
+    settingNames(): ReadonlySet<string>;
+    /**
+     * Whether `id`'s settings may be read: always for a catalog entry; for a
+     * row, only while its key was set for the hosts and auth it has now.
+     * False for an id the registry doesn't have.
+     */
+    bound(id: string): boolean;
+    /** The settings of rows whose key isn't bound: read as unset everywhere. */
+    unboundSettings(): ReadonlySet<string>;
+    /** The registered rows this registry serves, in row order. */
+    rows(): readonly RegisteredProvider[];
+    /** The rows this registry left out, each with why. */
+    readonly rejected: readonly RowRefusal[];
+}
+export interface ProviderRegistryOptions {
+    /**
+     * A host no row may name on this gateway, with why: the gateway's own
+     * host and anything under its apps' base domain. The pure rules refuse
+     * the rest (IP literals, localhost, `.internal`).
+     */
+    refuseHost?: (host: string) => string | null;
+}
+/** The prefix a provider's own Gateway settings carry: `stripe` → `STRIPE_`, `tiktok-business` → `TIKTOK_BUSINESS_`. */
+export declare function providerSettingPrefix(id: string): string;
+/** Why `host` can't be a row's, by the pure rules alone; null when it can. */
+export declare function publicHostProblem(host: string): string | null;
+/** What a gateway serves itself, for {@link gatewayHostRefusal}. */
+export interface GatewayHosts {
+    /** The gateway's own host (`apps.example.com`), or its URL. */
+    gatewayHost?: string | null;
+    /** Where its apps live (`APP_BASE_DOMAIN`): the domain and everything under it. */
+    appBaseDomain?: string | null;
+    /** A hosted gateway's third-party domain (`THIRD_PARTY_DOMAIN`), when it has one. */
+    thirdPartyDomain?: string | null;
+}
+/**
+ * Why a row can't send its key to `host` on this gateway: the gateway's
+ * own host, an app host under its base domain, or a host under its
+ * third-party domain. Null when none applies. The gateway applies it on
+ * every read (`refusedGatewayHost`, with its env) and the CLI at `provider
+ * add` (with the install's gateway host and base domain), in the same words.
+ */
+export declare function gatewayHostRefusal(host: string, hosts: GatewayHosts): string | null;
+/**
+ * Why a setting name can't be a row's: a name the Gateway, the catalog or
+ * another provider already reads, or one outside the row's own prefix.
+ * Null when the row may hold it.
+ */
+export declare function rowSecretProblem(id: string, name: string, taken: (name: string) => boolean): string | null;
+/**
+ * Check one parsed row against the catalog and the other rows. Pure: the
+ * CLI runs it before writing D1, the MCP tool before writing, and the
+ * gateway again on every read.
+ */
+export declare function checkProviderRow(id: string, capability: ApiKeyCapability, context: {
+    /** Settings the other rows hold. */
+    rowSettings: ReadonlySet<string>;
+    refuseHost?: (host: string) => string | null;
+}): RowRefusal | null;
+/** A row's spec parsed and checked: the capability, or the refusal. */
+export declare function resolveProviderRow(row: ProviderRow, context: {
+    rowSettings: ReadonlySet<string>;
+    refuseHost?: (host: string) => string | null;
+}): {
+    ok: true;
+    capability: ApiKeyCapability;
+} | {
+    ok: false;
+    refusal: RowRefusal;
+};
+/**
+ * The catalog and `rows` as one registry. Rows are taken in order; a row
+ * whose settings another earlier row holds is the one refused.
+ */
+export declare function providerRegistry(rows?: readonly ProviderRow[], options?: ProviderRegistryOptions): ProviderRegistry;
+/** The catalog alone, as a registry: what every surface reads without a gateway's rows. */
+export declare const BUILTIN_PROVIDERS: ProviderRegistry;
+//# sourceMappingURL=providerRegistry.d.ts.map

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

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