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

package/dist/internal/providerRegistry.js

@@ -0,0 +1,432 @@
+/**
+ * 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`).
+ *
+ * A second kind of row, a scope-set overlay (`provider_scope_sets`,
+ * `everyapp provider scope-set add`), adds a named scope set to a
+ * built-in OAuth client that has scope sets (Google, Microsoft, Slack):
+ * its scopes, and the routes on the client's own API hosts it unlocks,
+ * checked by the rules a built-in set is checked by
+ * (`providers.scope-set-overlay-within-client`). An overlay never replaces
+ * one of the client's own sets, never names a host outside the client's
+ * `api`, and never applies to a registered row (an operator replaces the
+ * row's spec instead). Apps list an overlay set under `scopes` as they
+ * list a built-in one.
+ */
+import { CAPABILITIES, CAPABILITY_IDS, capabilitySettings, } from "./capabilities.js";
+import { isDevOnlyGatewaySetting, isInstallOwnedGatewaySetting, isReservedAppSecretName, isSettableGatewaySetting, } from "./gatewaySettings.js";
+import { parseScopeSetOverlay, withScopeSets } from "./oauthSpec.js";
+import { isSignInSettingName } from "./signInProviders.js";
+import { describeSpecProblems, parseProviderSpec, PROVIDER_ID, } from "./providerSpec.js";
+/**
+ * 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. For an OAuth
+ * provider the client is bound to its authorize, token and revoke URLs,
+ * its API hosts, where the client goes on the token request and its
+ * client setting names (`oauth.client-bound-to-endpoints`): an admin who
+ * re-points `tokenUrl` has to paste the secret again.
+ */
+export function providerBindingKey(capability) {
+    if (capability.mode === "ai") {
+        // An `ai` row's key is bound to where the proxy sends it: its base URL and the key's placement.
+        return JSON.stringify({
+            kind: "ai",
+            auth: sortedAuth(capability.auth),
+            origin: capability.origin,
+            basePath: capability.basePath ?? null,
+        });
+    }
+    if (capability.mode === "oauth_client") {
+        return JSON.stringify({
+            kind: "oauth2-user",
+            authorizeUrl: capability.authorize.url,
+            tokenUrl: capability.flow?.tokenUrl ?? null,
+            revokeUrl: capability.flow?.revokeUrl ?? null,
+            inject: capability.token[0]?.inject ?? "form",
+            clientId: capability.secrets.clientId,
+            clientSecret: capability.secrets.clientSecret ?? null,
+            hosts: [...capability.api].sort(),
+        });
+    }
+    return JSON.stringify({
+        auth: sortedAuth(capability.auth),
+        hostSetting: capability.hostSetting ?? null,
+        hosts: [...capability.hosts].sort(),
+    });
+}
+/** An auth block with its keys sorted, one level down too, for a canonical key. */
+function sortedAuth(auth) {
+    return Object.fromEntries(Object.entries(auth)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([field, value]) => [
+        field,
+        typeof value === "object" && value !== null
+            ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))
+            : value,
+    ]));
+}
+/** The reserved app id no provider may take. */
+const RESERVED_IDS = new Set(["everyapp"]);
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/;
+const LOCAL_SUFFIXES = [".localhost", ".local", ".internal", ".arpa"];
+/** The prefix a provider's own Gateway settings carry: `stripe` → `STRIPE_`, `tiktok-business` → `TIKTOK_BUSINESS_`. */
+export function providerSettingPrefix(id) {
+    return `${id.toUpperCase().replace(/-/g, "_")}_`;
+}
+/** Why `host` can't be a row's, by the pure rules alone; null when it can. */
+export function publicHostProblem(host) {
+    if (IPV4.test(host))
+        return `${host} is an IP address, not a host name`;
+    if (host === "localhost" ||
+        LOCAL_SUFFIXES.some((suffix) => host.endsWith(suffix))) {
+        return `${host} is not a public host`;
+    }
+    return null;
+}
+/** A bare lowercase host from a host or a URL; null when neither. */
+function bareHost(value) {
+    const text = value?.trim().toLowerCase().replace(/\.$/, "");
+    if (!text)
+        return null;
+    if (!text.includes("/"))
+        return text;
+    try {
+        return new URL(text).hostname.toLowerCase();
+    }
+    catch {
+        return 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 function gatewayHostRefusal(host, hosts) {
+    const own = bareHost(hosts.gatewayHost);
+    if (own && host === own)
+        return `${host} is this gateway's own host`;
+    const base = bareHost(hosts.appBaseDomain);
+    if (base && (host === base || host.endsWith(`.${base}`))) {
+        return `${host} is under this gateway's app domain ${base}`;
+    }
+    const third = bareHost(hosts.thirdPartyDomain);
+    if (third && (host === third || host.endsWith(`.${third}`))) {
+        return `${host} is under this gateway's third-party domain ${third}`;
+    }
+    return 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 function rowSecretProblem(id, name, taken) {
+    const prefix = providerSettingPrefix(id);
+    if (!name.startsWith(prefix)) {
+        return `${name} doesn't start with ${prefix}: a provider's settings carry its own id`;
+    }
+    if (isInstallOwnedGatewaySetting(name)) {
+        return `${name} is one of the Gateway's own keys`;
+    }
+    if (isDevOnlyGatewaySetting(name)) {
+        return `${name} is a local-development setting`;
+    }
+    if (isReservedAppSecretName(name)) {
+        return `${name} is a name everyapp sets itself`;
+    }
+    if (isSignInSettingName(name)) {
+        return `${name} is a sign-in provider's setting name (every <ID>_SIGNIN_<FIELD> name is the Gateway's, set with \`everyapp signin add\`)`;
+    }
+    if (isSettableGatewaySetting(name)) {
+        return `${name} is a Gateway setting another provider or the Gateway reads`;
+    }
+    if (taken(name)) {
+        return `${name} is another registered provider's`;
+    }
+    return 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 function checkProviderRow(id, capability, context) {
+    if (RESERVED_IDS.has(id) || CAPABILITY_IDS.includes(id)) {
+        return {
+            id,
+            code: "PROVIDER_BUILTIN",
+            message: `${id} is a built-in provider; a registered one can't take its id`,
+        };
+    }
+    for (const name of capabilitySettings(capability)) {
+        const problem = rowSecretProblem(id, name, (each) => context.rowSettings.has(each));
+        if (problem) {
+            return { id, code: "PROVIDER_SECRET_TAKEN", message: problem };
+        }
+    }
+    for (const host of registrableHosts(capability)) {
+        const problem = publicHostProblem(host) ?? context.refuseHost?.(host);
+        if (problem) {
+            return { id, code: "PROVIDER_HOST_REFUSED", message: problem };
+        }
+    }
+    return null;
+}
+/**
+ * Every host a row sends a secret to: an API-key provider's `hosts`; an
+ * OAuth provider's API hosts (the token), and its authorize, token and
+ * revoke hosts (the client). Each passes the row host rules.
+ */
+export function registrableHosts(capability) {
+    if (capability.mode === "api_key")
+        return [...capability.hosts];
+    if (capability.mode === "ai")
+        return [new URL(capability.origin).hostname.toLowerCase()];
+    const hosts = [...capability.api];
+    const urls = [
+        capability.authorize.url,
+        capability.flow?.tokenUrl,
+        capability.flow?.revokeUrl,
+        capability.flow?.identity?.url,
+    ];
+    for (const url of urls) {
+        if (!url)
+            continue;
+        try {
+            const host = new URL(url).hostname.toLowerCase();
+            if (!hosts.includes(host))
+                hosts.push(host);
+        }
+        catch {
+            // The parser refused it already.
+        }
+    }
+    return hosts;
+}
+/** A row's spec parsed and checked: the capability, or the refusal. */
+export function resolveProviderRow(row, context) {
+    let spec = row.spec;
+    if (typeof spec === "string") {
+        try {
+            spec = JSON.parse(spec);
+        }
+        catch {
+            return {
+                ok: false,
+                refusal: {
+                    id: row.id,
+                    code: "PROVIDER_SPEC_INVALID",
+                    message: "the stored spec isn't JSON",
+                },
+            };
+        }
+    }
+    const parsed = parseProviderSpec(spec);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            refusal: {
+                id: row.id,
+                code: "PROVIDER_SPEC_INVALID",
+                message: describeSpecProblems(parsed.problems),
+            },
+        };
+    }
+    if (parsed.id !== row.id || !PROVIDER_ID.test(row.id)) {
+        return {
+            ok: false,
+            refusal: {
+                id: row.id,
+                code: "PROVIDER_SPEC_INVALID",
+                message: `the row is ${row.id} but its spec says ${parsed.id}`,
+            },
+        };
+    }
+    const refusal = checkProviderRow(parsed.id, parsed.capability, context);
+    return refusal
+        ? { ok: false, refusal }
+        : { ok: true, capability: parsed.capability };
+}
+/**
+ * The built-in OAuth client an overlay may extend: a catalog entry of mode
+ * `oauth_client` with a scope policy. Null for anything else (an API-key
+ * entry, a client without sets, a registered row, an unknown id).
+ */
+export function overlayableClient(providerId) {
+    if (!CAPABILITY_IDS.includes(providerId))
+        return null;
+    const capability = CAPABILITIES[providerId];
+    return capability.mode === "oauth_client" && capability.scopePolicy
+        ? capability
+        : null;
+}
+/** An overlay row's spec parsed and checked against its client: the set, or the refusal. */
+export function resolveScopeSetRow(row) {
+    const refuse = (code, message) => ({
+        ok: false,
+        refusal: { providerId: row.providerId, name: row.name, code, message },
+    });
+    const client = overlayableClient(row.providerId);
+    if (!client) {
+        return refuse("SCOPE_SET_PROVIDER_UNKNOWN", `${row.providerId} isn't a built-in OAuth client with scope sets (google-workspace, microsoft-365, slack); a registered provider's sets are in its spec`);
+    }
+    if (Object.hasOwn(client.scopePolicy.sets, row.name)) {
+        return refuse("SCOPE_SET_BUILTIN", `${row.name} is one of ${row.providerId}'s own sets; an overlay adds a set, never replaces one`);
+    }
+    let spec = row.spec;
+    if (typeof spec === "string") {
+        try {
+            spec = JSON.parse(spec);
+        }
+        catch {
+            return refuse("SCOPE_SET_INVALID", "the stored spec isn't JSON");
+        }
+    }
+    const parsed = parseScopeSetOverlay(typeof spec === "object" && spec !== null && !Array.isArray(spec)
+        ? { ...spec, name: row.name }
+        : spec, { id: row.providerId, capability: client });
+    if (!parsed.ok) {
+        return refuse("SCOPE_SET_INVALID", describeSpecProblems(parsed.problems));
+    }
+    return { ok: true, set: parsed.set };
+}
+/**
+ * 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 function providerRegistry(rows = [], options = {}) {
+    const catalog = new Map(CAPABILITY_IDS.map((id) => [id, CAPABILITIES[id]]));
+    // Scope-set overlays on the catalog's OAuth clients, before any row is
+    // looked at: a row never shadows the catalog, with or without overlays.
+    const overlays = [];
+    const rejectedScopeSets = [];
+    const overlaySets = new Map();
+    for (const row of options.scopeSets ?? []) {
+        if (overlays.some((each) => each.providerId === row.providerId && each.name === row.name)) {
+            rejectedScopeSets.push({
+                providerId: row.providerId,
+                name: row.name,
+                code: "SCOPE_SET_INVALID",
+                message: "listed twice",
+            });
+            continue;
+        }
+        const resolved = resolveScopeSetRow(row);
+        if (!resolved.ok) {
+            rejectedScopeSets.push(resolved.refusal);
+            continue;
+        }
+        overlays.push({
+            providerId: row.providerId,
+            name: row.name,
+            set: resolved.set,
+            addedBy: row.addedBy ?? null,
+            addedAt: row.addedAt ?? null,
+        });
+        const sets = overlaySets.get(row.providerId) ?? {};
+        sets[row.name] = resolved.set;
+        overlaySets.set(row.providerId, sets);
+    }
+    for (const [id, sets] of overlaySets) {
+        const client = catalog.get(id);
+        if (client?.mode === "oauth_client") {
+            catalog.set(id, withScopeSets(client, sets));
+        }
+    }
+    const accepted = new Map();
+    const rejected = [];
+    const rowSettings = new Set();
+    for (const row of rows) {
+        if (accepted.has(row.id)) {
+            rejected.push({
+                id: row.id,
+                code: "PROVIDER_SPEC_INVALID",
+                message: "listed twice",
+            });
+            continue;
+        }
+        const resolved = resolveProviderRow(row, {
+            rowSettings,
+            ...(options.refuseHost ? { refuseHost: options.refuseHost } : {}),
+        });
+        if (!resolved.ok) {
+            rejected.push(resolved.refusal);
+            continue;
+        }
+        accepted.set(row.id, {
+            id: row.id,
+            capability: resolved.capability,
+            bound: row.boundTo === providerBindingKey(resolved.capability),
+            addedBy: row.addedBy ?? null,
+            addedAt: row.addedAt ?? null,
+        });
+        for (const name of capabilitySettings(resolved.capability)) {
+            rowSettings.add(name);
+        }
+    }
+    const all = new Map([
+        ...catalog,
+        ...[...accepted.values()].map((row) => [row.id, row.capability]),
+    ]);
+    let names;
+    let unbound;
+    return {
+        get: (id) => all.get(id),
+        ids: () => [...all.keys()],
+        entries: () => [...all.entries()],
+        sourceOf: (id) => catalog.has(id) ? "catalog" : accepted.has(id) ? "row" : undefined,
+        settingNames: () => {
+            names ??= new Set([...all.values()].flatMap((capability) => capabilitySettings(capability)));
+            return names;
+        },
+        bound: (id) => catalog.has(id) || (accepted.get(id)?.bound ?? false),
+        unboundSettings: () => {
+            unbound ??= new Set([...accepted.values()]
+                .filter((row) => !row.bound)
+                .flatMap((row) => capabilitySettings(row.capability)));
+            return unbound;
+        },
+        rows: () => [...accepted.values()],
+        rejected,
+        scopeSets: () => [...overlays],
+        scopeSetSource: (providerId, name) => {
+            if (overlays.some((each) => each.providerId === providerId && each.name === name)) {
+                return "row";
+            }
+            const capability = CAPABILITY_IDS.includes(providerId)
+                ? CAPABILITIES[providerId]
+                : undefined;
+            return capability?.mode === "oauth_client" &&
+                capability.scopePolicy &&
+                Object.hasOwn(capability.scopePolicy.sets, name)
+                ? "catalog"
+                : undefined;
+        },
+        rejectedScopeSets,
+    };
+}
+/** The catalog alone, as a registry: what every surface reads without a gateway's rows. */
+export const BUILTIN_PROVIDERS = providerRegistry();

package/dist/internal/providerSpec.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A provider spec: the shape `everyapp provider add` takes as JSON (and
+ * `everyapp_provider_add` as a tool argument), and the shape every
+ * built-in catalog entry has in TypeScript (./capabilities.ts), so a
+ * catalog entry is nothing a row couldn't be. `parseProviderSpec` turns
+ * JSON into an {@link ApiKeyCapability} or names every problem; nothing
+ * here reads a value: a spec names Gateway settings, never holds one.
+ *
+ * Three kinds parse: API-key providers (`auth.kind` bearer, header, query
+ * or basic), OAuth providers (`auth.kind` oauth2-user, the half in
+ * ./oauthSpec.ts: the Gateway runs the flow and holds the tokens,
+ * docs/design/2026-10-oauth-providers.md), and OpenAI-compatible model
+ * providers (`mode: "ai"`: a `baseUrl`, the key's placement, the models
+ * it serves and the default, its inference routes; the AI proxy serves a
+ * row exactly as it serves a catalog `ai` entry, inference POSTs alone,
+ * `store: false` on chat, the usage tap, so a new model vendor is a
+ * registered spec, not a catalog release).
+ *
+ * The rules that make a row safe on a particular gateway (its secret names
+ * are its own, its hosts are public, it shadows no catalog entry) are the
+ * registry's (./providerRegistry.ts), run after this parse.
+ */
+import { type AiProviderCapability, type ApiKeyCapability, type OAuthClientCapability } from "./capabilities.js";
+/** A provider id: lowercase, a letter first, 2 to 40 characters. */
+export declare const PROVIDER_ID: RegExp;
+/** A Gateway setting name a provider may hold: upper case, 3 to 64 characters. */
+export declare const PROVIDER_SECRET_NAME: RegExp;
+/** A bare lowercase host with at least one dot: labels of letters, digits and hyphens. */
+export declare const PROVIDER_HOST: RegExp;
+/** What an `ai` row serves by default: chat, and embeddings when it names an embeddings model. */
+export declare const AI_SPEC_CHAT_ROUTE = "/v1/chat/completions";
+export declare const AI_SPEC_EMBEDDINGS_ROUTE = "/v1/embeddings";
+export interface ProviderSpecProblem {
+    /** Dotted: `auth.secret`, `hosts.1`, or `(root)`. */
+    path: string;
+    message: string;
+}
+/** What a row or a preset may be: an API key, an OAuth provider with a `flow`, or an OpenAI-compatible model provider. */
+export type RegistrableCapability = ApiKeyCapability | OAuthClientCapability | AiProviderCapability;
+export type ParsedProviderSpec = {
+    ok: true;
+    id: string;
+    capability: RegistrableCapability;
+} | {
+    ok: false;
+    problems: ProviderSpecProblem[];
+};
+/**
+ * Parse a provider spec. Every problem is reported, with its path, so a
+ * person fixes the file once. On success the id and the catalog-shaped
+ * capability, defaults filled in (`access` read, `readMethods` GET and
+ * HEAD, no account-wide paths).
+ */
+export declare function parseProviderSpec(input: unknown): ParsedProviderSpec;
+/** The problems as one line: `auth.secret: must name a Gateway setting; hosts.0: …`. */
+export declare function describeSpecProblems(problems: readonly ProviderSpecProblem[]): string;
+/**
+ * The spec of an API-key capability as JSON (`provider show`, the
+ * catalog's round trip): the entry's fields in the spec's names, with the
+ * defaults the parser fills in spelled out, so `parseProviderSpec` of it
+ * gives the entry back.
+ */
+export declare function providerSpecOf(id: string, capability: RegistrableCapability): Record<string, unknown>;
+/** The methods an app with `access: "write"` may use on `capability` besides its read methods. */
+export declare function writeMethodsOf(capability: RegistrableCapability): readonly string[];
+//# sourceMappingURL=providerSpec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"providerSpec.d.ts","sourceRoot":"","sources":["../../src/internal/providerSpec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAM3B,MAAM,mBAAmB,CAAC;AAG3B,oEAAoE;AACpE,eAAO,MAAM,WAAW,QAA2B,CAAC;AACpD,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,QAA2B,CAAC;AAC7D,0FAA0F;AAC1F,eAAO,MAAM,aAAa,QACoD,CAAC;AA4C/E,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AACzD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AA+EzD,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0HAA0H;AAC1H,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,qBAAqB,GACrB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,qBAAqB,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AA+iBnD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CA2NpE;AAkOD,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,GACvC,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuGzB;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAC5B,UAAU,EAAE,qBAAqB,GAChC,SAAS,MAAM,EAAE,CAKnB"}