@every-app/sdk 0.3.0-rc.2 → 0.3.0-rc.4

package/dist/internal/protocol.d.ts

@@ -39,6 +39,17 @@ export declare const GATEWAY_ERROR_HEADER = "x-everyapp-error";
  * from what browsers send.
  */
 export declare const ORG_HEADER = "x-everyapp-org";
+/**
+ * Which connection an app's call to an OAuth provider uses: the person's
+ * (`user`, the default when a person is behind the call) or the
+ * organization's (`organization`, the default for background work),
+ * docs/design/2026-10-oauth-providers.md section 7. Set by
+ * `integrationFetch({ account })`; the gateway reads it on the held-token
+ * branch and ignores it elsewhere.
+ */
+export declare const ACCOUNT_HEADER = "x-everyapp-account";
+/** The values {@link ACCOUNT_HEADER} may carry. */
+export type ConnectionAccount = "user" | "organization";
 /** 120-second lifetime — caps revocation staleness while surviving clock skew. */
 export declare const IDENTITY_TTL_SECONDS = 120;
 /** System tokens are minted per call and live at most a minute. */
@@ -63,6 +74,18 @@ export declare const ISSUER_ENV = "EVERYAPP_IDENTITY_ISSUER";
 export declare const SHARED_ENV = "EVERYAPP_SHARED";
 /** When set to `1` or `true` in the worker env, the dev identity kid is accepted. */
 export declare const DEV_ENV = "EVERYAPP_DEV";
+/**
+ * The organization an app's Worker is pinned to (a secret the deploy sends;
+ * in development the stub gateway's organization). `everyApp()` refuses an
+ * identity for any other organization; absent on a shared app's Workers.
+ */
+export declare const ORG_ID_ENV = "EVERY_APP_ORG_ID";
+/**
+ * The organization the dev gateway's seeded user belongs to. The same value
+ * as `@every-app/sdk/dev`'s, kept apart like {@link DEV_ISSUER} (the same
+ * test pins the two together).
+ */
+export declare const DEV_ORG_ID = "dev-org";
 /** `sub` claim the gateway mints public-route markers with. */
 export declare const PUBLIC_MARKER_SUB = "public";
 /** `sub` claim of gateway system tokens. */
@@ -81,12 +104,24 @@ export interface IdentitySubject {
     orgId: string;
     orgRole: string;
 }
+/**
+ * A member's role in the organization, as the identity token carries it.
+ * Owners and admins manage; anything the Gateway might mint that an app
+ * doesn't know is read as `member`.
+ */
+export type OrgRole = "owner" | "admin" | "member";
+/** `role` as an {@link OrgRole}: `owner` and `admin` as they are, anything else `member`. */
+export declare function toOrgRole(role: unknown): OrgRole;
+/** Whether `user` manages the organization: an owner or an admin. */
+export declare function isAdmin(user: {
+    orgRole: OrgRole | string;
+}): boolean;
 export interface EveryAppUser {
     /** User id (the `sub` claim). */
     id: string;
     email: string;
     orgId: string;
-    orgRole: string;
+    orgRole: OrgRole;
     channel: IdentityChannel;
     /** The acting principal (user, or `mcp:<client>` / agent). */
     actor: IdentityActor;

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

@@ -38,6 +38,15 @@ export const GATEWAY_ERROR_HEADER = "x-everyapp-error";
  * from what browsers send.
  */
 export const ORG_HEADER = "x-everyapp-org";
+/**
+ * Which connection an app's call to an OAuth provider uses: the person's
+ * (`user`, the default when a person is behind the call) or the
+ * organization's (`organization`, the default for background work),
+ * docs/design/2026-10-oauth-providers.md section 7. Set by
+ * `integrationFetch({ account })`; the gateway reads it on the held-token
+ * branch and ignores it elsewhere.
+ */
+export const ACCOUNT_HEADER = "x-everyapp-account";
 /** 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. */
@@ -62,10 +71,30 @@ export const ISSUER_ENV = "EVERYAPP_IDENTITY_ISSUER";
 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";
+/**
+ * The organization an app's Worker is pinned to (a secret the deploy sends;
+ * in development the stub gateway's organization). `everyApp()` refuses an
+ * identity for any other organization; absent on a shared app's Workers.
+ */
+export const ORG_ID_ENV = "EVERY_APP_ORG_ID";
+/**
+ * The organization the dev gateway's seeded user belongs to. The same value
+ * as `@every-app/sdk/dev`'s, kept apart like {@link DEV_ISSUER} (the same
+ * test pins the two together).
+ */
+export const DEV_ORG_ID = "dev-org";
 /** `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";
+/** `role` as an {@link OrgRole}: `owner` and `admin` as they are, anything else `member`. */
+export function toOrgRole(role) {
+    return role === "owner" || role === "admin" ? role : "member";
+}
+/** Whether `user` manages the organization: an owner or an admin. */
+export function isAdmin(user) {
+    return user.orgRole === "owner" || user.orgRole === "admin";
+}
 export class ProtocolClaimsError extends Error {
     constructor(message) {
         super(message);
@@ -122,7 +151,7 @@ export function identityClaimsToEveryAppUser(payload) {
         id: sub,
         email,
         orgId,
-        orgRole,
+        orgRole: toOrgRole(orgRole),
         channel: chan,
         actor: { sub: act.sub ?? sub },
         scopes,

package/dist/internal/providerRegistry.d.ts

@@ -20,7 +20,8 @@
  *    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";
+import { type Capability, type CapabilityLookup } 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;
@@ -42,13 +43,17 @@ export interface ProviderRow {
  * 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.
+ * 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: ApiKeyCapability): string;
+export declare function providerBindingKey(capability: RegistrableCapability): string;
 /** One registered row as `provider list` and `provider show` report it. */
 export interface RegisteredProvider {
     id: string;
-    capability: ApiKeyCapability;
+    capability: RegistrableCapability;
     /** Whether the row's key was set for the hosts and auth it has now. */
     bound: boolean;
     addedBy: string | null;
@@ -121,18 +126,24 @@ export declare function rowSecretProblem(id: string, name: string, taken: (name:
  * 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: {
+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: ApiKeyCapability;
+    capability: RegistrableCapability;
 } | {
     ok: false;
     refusal: RowRefusal;

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":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAE3B,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,IAAI,EAAE,OAAO,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,qBAAqB,GAAG,MAAM,CAgC5E;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,qBAAqB,CAAC;IAClC,uEAAuE;IACvE,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GACtB,uBAAuB,GACvB,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,CAAC;AAE5B,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,mFAAmF;IACnF,GAAG,IAAI,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,IAAI,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,6EAA6E;IAC7E,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,4EAA4E;IAC5E,eAAe,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,8DAA8D;IAC9D,IAAI,IAAI,SAAS,kBAAkB,EAAE,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC9C;AAOD,wHAAwH;AACxH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS7D;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAcD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,YAAY,GAClB,MAAM,GAAG,IAAI,CAYf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAC/B,MAAM,GAAG,IAAI,CAwBf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE;IACP,oCAAoC;IACpC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC9C,GACA,UAAU,GAAG,IAAI,CAuBnB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAmB5E;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE;IACP,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC9C,GAEC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,qBAAqB,CAAA;CAAE,GAC/C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAyCrC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,GAAE,SAAS,WAAW,EAAO,EACjC,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAqElB;AAED,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,EAAE,gBAAqC,CAAC"}

package/dist/internal/providerRegistry.js

@@ -28,9 +28,25 @@ import { describeSpecProblems, parseProviderSpec, PROVIDER_ID, } from "./provide
  * 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.
+ * 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 === "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(),
+        });
+    }
     const auth = Object.fromEntries(Object.entries(capability.auth)
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
         .map(([field, value]) => [
@@ -147,7 +163,7 @@ export function checkProviderRow(id, capability, context) {
             return { id, code: "PROVIDER_SECRET_TAKEN", message: problem };
         }
     }
-    for (const host of capability.hosts) {
+    for (const host of registrableHosts(capability)) {
         const problem = publicHostProblem(host) ?? context.refuseHost?.(host);
         if (problem) {
             return { id, code: "PROVIDER_HOST_REFUSED", message: problem };
@@ -155,6 +171,35 @@ export function checkProviderRow(id, capability, context) {
     }
     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];
+    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;

package/dist/internal/providerSpec.d.ts

@@ -6,15 +6,17 @@
  * 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.
+ * Two kinds parse: API-key providers (`auth.kind` bearer, header, query
+ * or basic) and 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.
  *
  * 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";
+import { 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. */
@@ -26,10 +28,12 @@ export interface ProviderSpecProblem {
     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;
 export type ParsedProviderSpec = {
     ok: true;
     id: string;
-    capability: ApiKeyCapability;
+    capability: RegistrableCapability;
 } | {
     ok: false;
     problems: ProviderSpecProblem[];
@@ -49,7 +53,7 @@ export declare function describeSpecProblems(problems: readonly ProviderSpecProb
  * 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>;
+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: ApiKeyCapability): readonly string[];
+export declare function writeMethodsOf(capability: RegistrableCapability): readonly string[];
 //# sourceMappingURL=providerSpec.d.ts.map

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

@@ -1 +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;AAgE/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,CA8KpE;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"}
+{"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"}

package/dist/internal/providerSpec.js

@@ -6,15 +6,18 @@
  * 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.
+ * Two kinds parse: API-key providers (`auth.kind` bearer, header, query
+ * or basic) and 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.
  *
  * 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 { DEFAULT_WRITE_METHODS, authSettingNames, } from "./capabilities.js";
+import { oauthSpecOf, parseOAuthUserSpec } from "./oauthSpec.js";
 /** A provider id: lowercase, a letter first, 2 to 40 characters. */
 export const PROVIDER_ID = /^[a-z][a-z0-9-]{1,39}$/;
 /** A Gateway setting name a provider may hold: upper case, 3 to 64 characters. */
@@ -80,7 +83,27 @@ const KNOWN_FIELDS = new Set([
     "example",
     "verified",
     "tags",
+    // An `oauth2-user` spec's own (./oauthSpec.ts).
+    "scopeSets",
+    "alwaysRequested",
+    "tolerated",
 ]);
+/** Fields an API-key spec has that an `oauth2-user` spec does not. */
+const API_KEY_ONLY_FIELDS = [
+    "hostSetting",
+    "data",
+    "secrets",
+    "accountWidePaths",
+    "smoke",
+    "cost",
+    "rate",
+    "verified",
+];
+const OAUTH_ONLY_FIELDS = [
+    "scopeSets",
+    "alwaysRequested",
+    "tolerated",
+];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -305,7 +328,7 @@ function auth(value, problems) {
         default:
             problems.push({
                 path: "auth.kind",
-                message: "must be bearer, header, query or basic (an OAuth client or an AI provider is a catalog entry, not a spec this gateway takes)",
+                message: "must be bearer, header, query, basic or oauth2-user (an AI provider is a catalog entry, not a spec this gateway takes)",
             });
             return undefined;
     }
@@ -537,6 +560,43 @@ function verified(value, problems) {
     });
     return undefined;
 }
+/** `access`, `readMethods` and `writeMethods`, shared by both kinds. */
+function grants(input, problems) {
+    const access = stringList(input["access"], "access", problems, {
+        max: 2,
+        each: (level, at) => {
+            if (level !== "read" && level !== "write") {
+                problems.push({ path: at, message: "must be read or write" });
+            }
+        },
+    });
+    if (access && access.length === 0) {
+        problems.push({ path: "access", message: "must list read, write or both" });
+    }
+    const readMethods = methods(input["readMethods"], "readMethods", problems);
+    // A write-only provider (a sender, a GraphQL API) reads with nothing:
+    // every call needs the write grant. Anything that offers read lists how.
+    if (readMethods &&
+        readMethods.length === 0 &&
+        (!Array.isArray(access) || access.includes("read"))) {
+        problems.push({
+            path: "readMethods",
+            message: "must list a method unless access is write alone",
+        });
+    }
+    const writeMethods = methods(input["writeMethods"], "writeMethods", problems);
+    return { access, readMethods, writeMethods };
+}
+function tagList(value, problems) {
+    return stringList(value, "tags", problems, {
+        max: 10,
+        each: (tag, at) => {
+            if (!TAG.test(tag)) {
+                problems.push({ path: at, message: "must be a lowercase word" });
+            }
+        },
+    });
+}
 /**
  * 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
@@ -563,10 +623,14 @@ export function parseProviderSpec(input) {
             message: "must be lowercase letters, digits and hyphens, a letter first, 2 to 40 characters (stripe)",
         });
     }
-    if (input["mode"] !== undefined && input["mode"] !== "api_key") {
+    const isOAuth = isRecord(input["auth"]) && input["auth"]["kind"] === "oauth2-user";
+    const expectedMode = isOAuth ? "oauth_client" : "api_key";
+    if (input["mode"] !== undefined && input["mode"] !== expectedMode) {
         problems.push({
             path: "mode",
-            message: "this gateway registers api_key providers; an AI provider or an OAuth client is a catalog entry",
+            message: isOAuth
+                ? "an oauth2-user spec's mode is oauth_client (or left out)"
+                : "this gateway registers api_key and oauth_client (auth.kind oauth2-user) providers; an AI provider is a catalog entry",
         });
     }
     const name = text(input["name"], "name", problems, { max: 64 });
@@ -595,6 +659,61 @@ export function parseProviderSpec(input) {
             }
         },
     });
+    if (isOAuth) {
+        const { access, readMethods, writeMethods } = grants(input, problems);
+        const hint = text(input["hint"], "hint", problems, { max: 500 });
+        const example = text(input["example"], "example", problems, { max: 200 });
+        const tags = tagList(input["tags"], problems);
+        // An OAuth provider: its token goes to `hosts` alone, so the API-key
+        // fields that shape a key's placement have no meaning here.
+        for (const field of API_KEY_ONLY_FIELDS) {
+            if (input[field] !== undefined) {
+                problems.push({
+                    path: field,
+                    message: "not a field of an oauth2-user spec",
+                });
+            }
+        }
+        if (input["hosts"] === undefined || (hosts && hosts.length === 0)) {
+            problems.push({
+                path: "hosts",
+                message: "required: at least one API host the token is sent to",
+            });
+        }
+        const parsed = typeof id === "string" &&
+            name !== undefined &&
+            docs !== undefined &&
+            hosts !== undefined
+            ? parseOAuthUserSpec(input, {
+                id,
+                name,
+                docs,
+                hosts,
+                ...(description === undefined ? {} : { description }),
+                ...(api === undefined ? {} : { reference: api }),
+                ...(access === undefined
+                    ? {}
+                    : { access: access }),
+                ...(readMethods === undefined ? {} : { readMethods }),
+                ...(writeMethods === undefined ? {} : { writeMethods }),
+                ...(hint === undefined ? {} : { hint }),
+                ...(example === undefined ? {} : { example }),
+                ...(tags === undefined ? {} : { tags }),
+            }, problems)
+            : undefined;
+        if (problems.length > 0 || !parsed || typeof id !== "string") {
+            return { ok: false, problems };
+        }
+        return { ok: true, id, capability: parsed.capability };
+    }
+    for (const field of OAUTH_ONLY_FIELDS) {
+        if (input[field] !== undefined) {
+            problems.push({
+                path: field,
+                message: "only an oauth2-user spec has it",
+            });
+        }
+    }
     const hostSetting = input["hostSetting"] === undefined
         ? undefined
         : secretName(input["hostSetting"], "hostSetting", problems);
@@ -628,29 +747,7 @@ export function parseProviderSpec(input) {
         ...(parsedAuth ? authSettingNames(parsedAuth) : []),
         ...(hostSetting === undefined ? [] : [hostSetting]),
     ], problems);
-    const access = stringList(input["access"], "access", problems, {
-        max: 2,
-        each: (level, at) => {
-            if (level !== "read" && level !== "write") {
-                problems.push({ path: at, message: "must be read or write" });
-            }
-        },
-    });
-    if (access && access.length === 0) {
-        problems.push({ path: "access", message: "must list read, write or both" });
-    }
-    const readMethods = methods(input["readMethods"], "readMethods", problems);
-    // A write-only provider (a sender, a GraphQL API) reads with nothing:
-    // every call needs the write grant. Anything that offers read lists how.
-    if (readMethods &&
-        readMethods.length === 0 &&
-        (!Array.isArray(access) || access.includes("read"))) {
-        problems.push({
-            path: "readMethods",
-            message: "must list a method unless access is write alone",
-        });
-    }
-    const writeMethods = methods(input["writeMethods"], "writeMethods", problems);
+    const { access, readMethods, writeMethods } = grants(input, problems);
     const paths = accountWidePaths(input["accountWidePaths"], problems);
     const hint = text(input["hint"], "hint", problems, { max: 500 });
     const smokeRequest = smoke(input["smoke"], hosts ?? [], problems);
@@ -658,14 +755,7 @@ export function parseProviderSpec(input) {
     const parsedRate = rate(input["rate"], problems);
     const example = text(input["example"], "example", problems, { max: 200 });
     const parsedVerified = verified(input["verified"], problems);
-    const tags = stringList(input["tags"], "tags", problems, {
-        max: 10,
-        each: (tag, at) => {
-            if (!TAG.test(tag)) {
-                problems.push({ path: at, message: "must be a lowercase word" });
-            }
-        },
-    });
+    const tags = tagList(input["tags"], problems);
     if (problems.length > 0 ||
         typeof id !== "string" ||
         name === undefined ||
@@ -712,6 +802,13 @@ export function describeSpecProblems(problems) {
  * gives the entry back.
  */
 export function providerSpecOf(id, capability) {
+    if (capability.mode === "oauth_client") {
+        const spec = oauthSpecOf(id, capability);
+        if (!spec) {
+            throw new Error(`${id} is a catalog OAuth client without a Gateway-owned flow: it has no spec`);
+        }
+        return spec;
+    }
     return {
         id,
         name: capability.label,

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

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

package/dist/internal/signInProviders.js

@@ -182,7 +182,7 @@ export const SIGN_IN_PROVIDERS = {
         emailClaim: "the ID token's `email` (else the userinfo endpoint's), counted as verified only when `email_verified` is true",
         setup: "setup/signin-oidc.md",
         notes: [
-            "Cloudflare Access has its own settings (CLOUDFLARE_ACCESS_OIDC_*, `everyapp access`): use those for Access, this for Okta, Entra ID, Google Workspace as an OIDC issuer, Keycloak, Auth0 and the like.",
+            "Cloudflare Access has its own settings (CLOUDFLARE_ACCESS_OIDC_*, `everyapp access`): use those for Access, this for Okta, Keycloak, Auth0, Authentik, Google Workspace as an OIDC issuer and the like. For Microsoft Entra ID use the `microsoft` provider: Entra's ID tokens carry no `email_verified`, so through this entry every sign-in would be refused as unverified.",
             "ID tokens must be signed with RS256 (every major provider's default).",
         ],
     },
@@ -230,9 +230,16 @@ export function signInProviderState(provider, isSet) {
     const set = provider.settings
         .filter((setting) => isSet(setting.name))
         .map((setting) => setting.name);
-    const missing = provider.settings
+    const unset = provider.settings
         .filter((setting) => setting.required && !isSet(setting.name))
         .map((setting) => setting.name);
-    const status = missing.length === 0 ? "on" : set.length === 0 ? "off" : "incomplete";
-    return { id: provider.id, status, missing, set };
+    const status = unset.length === 0 ? "on" : set.length === 0 ? "off" : "incomplete";
+    // `missing` names what a half-set provider still needs; a provider nobody
+    // started setting up isn't missing anything, it is off.
+    return {
+        id: provider.id,
+        status,
+        missing: status === "incomplete" ? unset : [],
+        set,
+    };
 }