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

package/dist/internal/providerRegistry.js

@@ -0,0 +1,262 @@
+/**
+ * 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 { CAPABILITIES, CAPABILITY_IDS, capabilitySettings, } from "./capabilities.js";
+import { isDevOnlyGatewaySetting, isInstallOwnedGatewaySetting, isReservedAppSecretName, isSettableGatewaySetting, } from "./gatewaySettings.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.
+ */
+export function providerBindingKey(capability) {
+    const auth = Object.fromEntries(Object.entries(capability.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,
+    ]));
+    return JSON.stringify({
+        auth,
+        hostSetting: capability.hostSetting ?? null,
+        hosts: [...capability.hosts].sort(),
+    });
+}
+/** 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 (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 capability.hosts) {
+        const problem = publicHostProblem(host) ?? context.refuseHost?.(host);
+        if (problem) {
+            return { id, code: "PROVIDER_HOST_REFUSED", message: problem };
+        }
+    }
+    return null;
+}
+/** 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 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]]));
+    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,
+    };
+}
+/** 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,55 @@
+/**
+ * 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.
+ *
+ * This slice parses API-key providers (`auth.kind` bearer, header, query
+ * or basic). An AI provider or an OAuth client is a catalog entry only;
+ * the parser says so rather than guessing.
+ *
+ * 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 ApiKeyCapability } 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;
+export interface ProviderSpecProblem {
+    /** Dotted: `auth.secret`, `hosts.1`, or `(root)`. */
+    path: string;
+    message: string;
+}
+export type ParsedProviderSpec = {
+    ok: true;
+    id: string;
+    capability: ApiKeyCapability;
+} | {
+    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: ApiKeyCapability): Record<string, unknown>;
+/** The methods an app with `access: "write"` may use on `capability` besides its read methods. */
+export declare function writeMethodsOf(capability: ApiKeyCapability): 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;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAIL,KAAK,gBAAgB,EAMtB,MAAM,mBAAmB,CAAC;AAE3B,oEAAoE;AACpE,eAAO,MAAM,WAAW,QAA2B,CAAC;AACpD,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,QAA2B,CAAC;AAC7D,0FAA0F;AAC1F,eAAO,MAAM,aAAa,QACoD,CAAC;AA0D/E,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AA+fnD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAqKpE;AAED,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,gBAAgB,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwCzB;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAC5B,UAAU,EAAE,gBAAgB,GAC3B,SAAS,MAAM,EAAE,CAEnB"}