@every-app/sdk 0.3.0-rc.5 → 0.3.0-rc.6

package/dist/internal/oauthSpec.js

@@ -264,6 +264,62 @@ function routes(value, path, hosts, problems) {
     });
     return out;
 }
+/** The fields one scope set may carry, in a spec's `scopeSets` or an overlay. */
+const SCOPE_SET_FIELDS = ["label", "access", "scopes", "userScopes", "routes"];
+/**
+ * One scope set (`{ label, access, scopes, userScopes?, routes? }`) at
+ * `at`, its routes on `hosts` alone; undefined when a field is wrong,
+ * every problem reported. `overlay`: a set added to a built-in client
+ * must name a scope and say what it unlocks (a set with no routes unlocks
+ * nothing on the held-token path); a spec's own set may leave both empty
+ * (Notion's sets carry no scope string).
+ */
+export function parseScopeSet(raw, at, hosts, problems, { overlay = false } = {}) {
+    if (!isRecord(raw)) {
+        problems.push({ path: at, message: "must be { label, access, scopes }" });
+        return undefined;
+    }
+    for (const field of Object.keys(raw)) {
+        if (!SCOPE_SET_FIELDS.includes(field)) {
+            problems.push({ path: `${at}.${field}`, message: "unknown field" });
+        }
+    }
+    const label = printable(raw["label"], `${at}.label`, problems, 80);
+    if (raw["label"] === undefined) {
+        problems.push({ path: `${at}.label`, message: "required" });
+    }
+    const access = raw["access"];
+    if (access !== "read" && access !== "write") {
+        problems.push({ path: `${at}.access`, message: "must be read or write" });
+    }
+    const scopes = scopeList(raw["scopes"], `${at}.scopes`, problems);
+    if (raw["scopes"] === undefined) {
+        problems.push({ path: `${at}.scopes`, message: "required" });
+    }
+    else if (overlay && scopes && scopes.length === 0) {
+        problems.push({ path: `${at}.scopes`, message: "must list a scope" });
+    }
+    const userScopes = scopeList(raw["userScopes"], `${at}.userScopes`, problems);
+    const parsedRoutes = routes(raw["routes"], `${at}.routes`, hosts, problems);
+    if (overlay && (!parsedRoutes || parsedRoutes.length === 0)) {
+        problems.push({
+            path: `${at}.routes`,
+            message: "required: at least one { host, paths } the set unlocks, on one of the client's API hosts",
+        });
+    }
+    if (label === undefined ||
+        (access !== "read" && access !== "write") ||
+        scopes === undefined) {
+        return undefined;
+    }
+    return {
+        label,
+        access,
+        scopes,
+        ...(userScopes === undefined ? {} : { userScopes }),
+        routes: parsedRoutes ?? [],
+    };
+}
 function scopeSets(value, hosts, problems) {
     if (!isRecord(value)) {
         problems.push({
@@ -290,43 +346,101 @@ function scopeSets(value, hosts, problems) {
             });
             continue;
         }
-        if (!isRecord(raw)) {
-            problems.push({ path: at, message: "must be { label, access, scopes }" });
-            continue;
-        }
-        for (const field of Object.keys(raw)) {
-            if (!["label", "access", "scopes", "userScopes", "routes"].includes(field)) {
-                problems.push({ path: `${at}.${field}`, message: "unknown field" });
-            }
-        }
-        const label = printable(raw["label"], `${at}.label`, problems, 80);
-        if (raw["label"] === undefined) {
-            problems.push({ path: `${at}.label`, message: "required" });
-        }
-        const access = raw["access"];
-        if (access !== "read" && access !== "write") {
-            problems.push({ path: `${at}.access`, message: "must be read or write" });
-        }
-        const scopes = scopeList(raw["scopes"], `${at}.scopes`, problems);
-        if (raw["scopes"] === undefined) {
-            problems.push({ path: `${at}.scopes`, message: "required" });
+        const set = parseScopeSet(raw, at, hosts, problems);
+        if (set)
+            out[name] = set;
+    }
+    return out;
+}
+/** The fields a scope-set overlay carries: a set's, with its `name` and the client it belongs to. */
+const OVERLAY_FIELDS = ["provider", "name", ...SCOPE_SET_FIELDS];
+/**
+ * A scope set an operator adds to a built-in OAuth client
+ * (`everyapp provider scope-set add google-workspace gmail-send.json`):
+ * `{ "name": "gmail.send", "label", "access", "scopes", "routes" }`, held
+ * to the rules a built-in set is (the set's shape, routes on the client's
+ * `api` hosts alone, anchored `posts`) plus two of its own: `access` is
+ * said outright (a write set is never implied by its scopes) and `routes`
+ * is required. A `provider` field, when present, must be `id`. The name
+ * may not be one of the client's own sets: an overlay adds, never
+ * replaces. Nothing here reads a value.
+ */
+export function parseScopeSetOverlay(input, client) {
+    const problems = [];
+    if (!isRecord(input)) {
+        return {
+            ok: false,
+            problems: [{ path: "(root)", message: "must be a JSON object" }],
+        };
+    }
+    for (const field of Object.keys(input)) {
+        if (!OVERLAY_FIELDS.includes(field)) {
+            problems.push({ path: field, message: "unknown field" });
         }
-        const userScopes = scopeList(raw["userScopes"], `${at}.userScopes`, problems);
-        const parsedRoutes = routes(raw["routes"], `${at}.routes`, hosts, problems);
-        if (label === undefined ||
-            (access !== "read" && access !== "write") ||
-            scopes === undefined) {
+    }
+    const policy = client.capability.scopePolicy;
+    if (!policy) {
+        problems.push({
+            path: "(root)",
+            message: `${client.id} has no scope sets: the whole client is the grant`,
+        });
+    }
+    if (input["provider"] !== undefined && input["provider"] !== client.id) {
+        problems.push({
+            path: "provider",
+            message: `is ${String(input["provider"])}, not ${client.id}`,
+        });
+    }
+    const name = input["name"];
+    if (typeof name !== "string" || !SCOPE_SET_NAME.test(name)) {
+        problems.push({
+            path: "name",
+            message: "required: identity, or <area>.<access> in lowercase (gmail.send)",
+        });
+    }
+    else if (policy && Object.hasOwn(policy.sets, name)) {
+        problems.push({
+            path: "name",
+            message: `${name} is one of ${client.id}'s own sets; an overlay adds a set, never replaces one`,
+        });
+    }
+    // The set's own fields alone: an unknown one was reported above.
+    const fields = Object.fromEntries(Object.entries(input).filter(([field]) => SCOPE_SET_FIELDS.includes(field)));
+    const set = parseScopeSet(fields, "(set)", client.capability.api, problems, {
+        overlay: true,
+    });
+    if (problems.length > 0 || !set || typeof name !== "string") {
+        return { ok: false, problems };
+    }
+    return { ok: true, name, set };
+}
+/**
+ * `capability` with `sets` added to its scope policy: the sets after the
+ * client's own, in the order given, and each set's scopes added to the
+ * authorize URL's list (what the operator's client must be allowed), as
+ * `parseOAuthUserSpec` builds it. A name the client already has is left
+ * as the client's (the registry refuses such an overlay before this).
+ */
+export function withScopeSets(capability, sets) {
+    const policy = capability.scopePolicy;
+    if (!policy)
+        return capability;
+    const merged = { ...policy.sets };
+    const scopes = [...capability.authorize.scopes];
+    for (const [name, set] of Object.entries(sets)) {
+        if (Object.hasOwn(merged, name))
             continue;
+        merged[name] = set;
+        for (const scope of set.scopes) {
+            if (!scopes.includes(scope))
+                scopes.push(scope);
         }
-        out[name] = {
-            label,
-            access,
-            scopes,
-            ...(userScopes === undefined ? {} : { userScopes }),
-            routes: parsedRoutes ?? [],
-        };
     }
-    return out;
+    return {
+        ...capability,
+        authorize: { ...capability.authorize, scopes },
+        scopePolicy: { ...policy, sets: merged },
+    };
 }
 function identity(value, hosts, problems) {
     if (value === undefined)
@@ -551,7 +665,6 @@ export function parseOAuthUserSpec(input, common, problems) {
         authorize: { url: authorize.url, scopes: union },
         scopePolicy: policy,
         api: [...common.hosts],
-        redirectPaths: [],
         flow,
         ...(common.readMethods === undefined
             ? {}

package/dist/internal/protocol.d.ts

@@ -103,6 +103,11 @@ export interface IdentitySubject {
     email: string;
     orgId: string;
     orgRole: string;
+    /**
+     * The organization's name as its owners set it (`org_name`), so an app
+     * can show "Acme" rather than an id. Left out when the minter has none.
+     */
+    orgName?: string;
 }
 /**
  * A member's role in the organization, as the identity token carries it.
@@ -122,6 +127,13 @@ export interface EveryAppUser {
     email: string;
     orgId: string;
     orgRole: OrgRole;
+    /**
+     * The organization's display name (the `org_name` claim), as its owners
+     * set it: trimmed, at most 64 characters, no control characters. Show
+     * it; never key data by it (names change, `orgId` doesn't). Undefined
+     * when the token carries none.
+     */
+    orgName?: string;
     channel: IdentityChannel;
     /** The acting principal (user, or `mcp:<client>` / agent). */
     actor: IdentityActor;
@@ -138,6 +150,8 @@ export interface IdentityClaims extends JWTPayload {
     email: string;
     org_id: string;
     org_role: string;
+    /** The organization's display name; absent when the minter had none. */
+    org_name?: string;
     chan: IdentityChannel;
     act: IdentityActor;
     scopes: string[];

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

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

package/dist/internal/protocol.js

@@ -107,6 +107,7 @@ export function identitySubjectToClaims(subject, opts) {
         email: subject.email,
         org_id: subject.orgId,
         org_role: subject.orgRole,
+        ...(subject.orgName ? { org_name: subject.orgName } : {}),
         chan: opts.channel ?? "web",
         act: opts.actor ?? { sub: subject.sub },
         scopes: opts.scopes ?? ["*"],
@@ -141,6 +142,11 @@ export function identityClaimsToEveryAppUser(payload) {
     if (!sub || !email || !orgId || !orgRole) {
         throw new ProtocolClaimsError("identity token missing required claims");
     }
+    // Display only, so a token without it (or with a malformed one) is still
+    // an identity: the app falls back to no name.
+    const orgName = typeof payload.org_name === "string" && payload.org_name
+        ? payload.org_name
+        : undefined;
     const chan = payload.chan ?? "web";
     const act = payload.act ?? { sub };
     const scopes = Array.isArray(payload.scopes)
@@ -152,6 +158,7 @@ export function identityClaimsToEveryAppUser(payload) {
         email,
         orgId,
         orgRole: toOrgRole(orgRole),
+        ...(orgName ? { orgName } : {}),
         channel: chan,
         actor: { sub: act.sub ?? sub },
         scopes,

package/dist/internal/providerRegistry.d.ts

@@ -19,8 +19,19 @@
  *    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 } from "./capabilities.js";
+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 {
@@ -39,6 +50,33 @@ export interface ProviderRow {
     /** 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
@@ -85,6 +123,12 @@ export interface ProviderRegistry extends CapabilityLookup {
     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 {
     /**
@@ -93,6 +137,8 @@ export interface ProviderRegistryOptions {
      * 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;
@@ -148,6 +194,20 @@ export declare function resolveProviderRow(row: ProviderRow, context: {
     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.

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

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

package/dist/internal/providerRegistry.js

@@ -19,9 +19,21 @@
  *    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";
 /**
@@ -35,6 +47,15 @@ import { describeSpecProblems, parseProviderSpec, PROVIDER_ID, } from "./provide
  * 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",
@@ -47,7 +68,15 @@ export function providerBindingKey(capability) {
             hosts: [...capability.api].sort(),
         });
     }
-    const auth = Object.fromEntries(Object.entries(capability.auth)
+    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,
@@ -55,11 +84,6 @@ export function providerBindingKey(capability) {
             ? 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"]);
@@ -179,6 +203,8 @@ export function checkProviderRow(id, capability, context) {
 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,
@@ -244,12 +270,92 @@ export function resolveProviderRow(row, context) {
         ? { 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();
@@ -305,6 +411,21 @@ export function providerRegistry(rows = [], options = {}) {
         },
         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. */

package/dist/internal/providerSpec.d.ts

@@ -6,30 +6,37 @@
  * JSON into an {@link ApiKeyCapability} or names every problem; nothing
  * here reads a value: a spec names Gateway settings, never holds one.
  *
- * Two kinds parse: API-key providers (`auth.kind` bearer, header, query
- * or basic) and OAuth providers (`auth.kind` oauth2-user, the half in
+ * 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). An AI provider is a catalog
- * entry only; the parser says so rather than guessing.
+ * 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 ApiKeyCapability, type OAuthClientCapability } from "./capabilities.js";
+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, or an OAuth provider with a `flow`. */
-export type RegistrableCapability = ApiKeyCapability | OAuthClientCapability;
+/** 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;

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

@@ -1 +1 @@
-{"version":3,"file":"providerSpec.d.ts","sourceRoot":"","sources":["../../src/internal/providerSpec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAIL,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;AAoF/E,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qFAAqF;AACrF,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAE7E,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,CAgNpE;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,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiDzB;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAC5B,UAAU,EAAE,qBAAqB,GAChC,SAAS,MAAM,EAAE,CAEnB"}
+{"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"}