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

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,218 @@
+/**
+ * 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 { type Capability, type CapabilityLookup, type OAuthClientCapability, type OAuthScopeSet } from "./capabilities.js";
+import { type RegistrableCapability } from "./providerSpec.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;
+}
+/** A `provider_scope_sets` row as the gateway or the CLI read it. */
+export interface ScopeSetRow {
+    /** The built-in OAuth client the set belongs to (`google-workspace`). */
+    providerId: string;
+    /** The set's name, what an app lists under `scopes` (`gmail.send`). */
+    name: string;
+    /** The set's spec, as JSON text or already parsed (`parseScopeSetOverlay`'s shape). */
+    spec: unknown;
+    addedBy?: string | null;
+    addedAt?: number | null;
+}
+/** One overlay the registry serves, as `provider show` reports it. */
+export interface RegisteredScopeSet {
+    providerId: string;
+    name: string;
+    set: OAuthScopeSet;
+    addedBy: string | null;
+    addedAt: number | null;
+}
+export type ScopeSetRefusalCode = "SCOPE_SET_INVALID" | "SCOPE_SET_PROVIDER_UNKNOWN" | "SCOPE_SET_BUILTIN";
+/** Why an overlay row is not a scope set on this gateway. */
+export interface ScopeSetRefusal {
+    providerId: string;
+    name: string;
+    code: ScopeSetRefusalCode;
+    message: string;
+}
+/**
+ * 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 declare function providerBindingKey(capability: RegistrableCapability): string;
+/** One registered row as `provider list` and `provider show` report it. */
+export interface RegisteredProvider {
+    id: string;
+    capability: RegistrableCapability;
+    /** 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[];
+    /** The scope-set overlays this registry applied to built-in clients, in row order. */
+    scopeSets(): readonly RegisteredScopeSet[];
+    /** Where a client's scope set comes from: its catalog entry, an overlay row, or nowhere. */
+    scopeSetSource(providerId: string, name: string): "catalog" | "row" | undefined;
+    /** The overlay rows this registry left out, each with why. */
+    readonly rejectedScopeSets: readonly ScopeSetRefusal[];
+}
+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 scope-set overlays (`provider_scope_sets`), applied to the catalog's OAuth clients. */
+    scopeSets?: readonly ScopeSetRow[];
+}
+/** 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: RegistrableCapability, context: {
+    /** Settings the other rows hold. */
+    rowSettings: ReadonlySet<string>;
+    refuseHost?: (host: string) => string | null;
+}): RowRefusal | 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 declare function registrableHosts(capability: RegistrableCapability): string[];
+/** 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: RegistrableCapability;
+} | {
+    ok: false;
+    refusal: RowRefusal;
+};
+/**
+ * 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 declare function overlayableClient(providerId: string): OAuthClientCapability | null;
+/** An overlay row's spec parsed and checked against its client: the set, or the refusal. */
+export declare function resolveScopeSetRow(row: ScopeSetRow): {
+    ok: true;
+    set: OAuthScopeSet;
+} | {
+    ok: false;
+    refusal: ScopeSetRefusal;
+};
+/**
+ * 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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"}