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

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauthBuiltIns.d.ts","sourceRoot":"","sources":["../../src/internal/oauthBuiltIns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8GvB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,oBAAoB,CAAC"}

package/dist/internal/oauthBuiltIns.js

@@ -0,0 +1,122 @@
+/**
+ * The OAuth providers every Gateway has built in, as `oauth2-user` specs:
+ * the same JSON shape as the presets (./oauthPresets.ts) and a registered
+ * row (`everyapp provider add`). What differs between Google, Microsoft
+ * and Slack is here as data: the endpoints, the API hosts, how scopes are
+ * separated and prefixed, the extra authorize parameters, how the account
+ * is named, and the scopes a token may carry beyond what the app asked.
+ * No code anywhere reads a provider id to decide anything.
+ *
+ * Pure data with no imports, so the catalog (./capabilities.ts) can build
+ * its entries from it without an import cycle. Each spec parses with
+ * `parseProviderSpec` and round-trips through `oauthSpecOf`
+ * (oauthBuiltIns.test.ts).
+ */
+export const BUILT_IN_OAUTH_SPECS = {
+    // One Google Cloud project's OAuth client: Gmail, Calendar, Search
+    // Console, Analytics and any other Google API an app names a scope for.
+    "google-workspace": {
+        id: "google-workspace",
+        name: "Google",
+        description: "Gmail, Calendar, Drive, Search Console, Analytics and the other Google APIs, as the person who connects.",
+        docs: "https://console.cloud.google.com/apis/credentials",
+        api: "https://developers.google.com/identity/protocols/oauth2/scopes",
+        hosts: [
+            "gmail.googleapis.com",
+            "www.googleapis.com",
+            "searchconsole.googleapis.com",
+            "analyticsdata.googleapis.com",
+            "analyticsadmin.googleapis.com",
+            "openidconnect.googleapis.com",
+        ],
+        auth: {
+            kind: "oauth2-user",
+            authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+            tokenUrl: "https://oauth2.googleapis.com/token",
+            clientId: "GOOGLE_WORKSPACE_CLIENT_ID",
+            clientSecret: "GOOGLE_WORKSPACE_CLIENT_SECRET",
+            inject: "form",
+            pkce: true,
+            scopeSeparator: "space",
+            // An app writes `gmail.modify`; the authorize URL carries the full
+            // `https://www.googleapis.com/auth/gmail.modify`.
+            scopePrefix: "https://www.googleapis.com/auth/",
+            // A refresh token needs `access_type=offline`; `prompt=consent`
+            // makes Google issue one on every connect.
+            authorizeParams: { access_type: "offline", prompt: "consent" },
+            identity: {
+                url: "https://openidconnect.googleapis.com/v1/userinfo",
+                label: "email",
+                id: "sub",
+                scopes: ["openid", "email"],
+            },
+            // Google answers `email` and `profile` as the userinfo URLs, and may
+            // add `profile` beside `openid`.
+            tolerated: [
+                "profile",
+                "https://www.googleapis.com/auth/userinfo.email",
+                "https://www.googleapis.com/auth/userinfo.profile",
+            ],
+        },
+        hint: "A Web application OAuth client in Google Cloud, with the Gateway's callback as its redirect URI and the scopes your apps list on its consent screen.",
+    },
+    // The multi-tenant Entra endpoints: register the client for accounts in
+    // any organization and personal accounts.
+    "microsoft-365": {
+        id: "microsoft-365",
+        name: "Microsoft 365",
+        description: "Outlook mail and calendar, OneDrive and the rest of Microsoft Graph, as the person who connects.",
+        docs: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade",
+        api: "https://learn.microsoft.com/graph/permissions-reference",
+        hosts: ["graph.microsoft.com"],
+        auth: {
+            kind: "oauth2-user",
+            authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+            tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+            clientId: "MICROSOFT_365_CLIENT_ID",
+            clientSecret: "MICROSOFT_365_CLIENT_SECRET",
+            inject: "form",
+            pkce: true,
+            scopeSeparator: "space",
+            // An app writes `Mail.Read`; Graph's scopes are fully qualified on
+            // the wire and may come back either way.
+            scopePrefix: "https://graph.microsoft.com/",
+            identity: {
+                url: "https://graph.microsoft.com/v1.0/me",
+                label: "userPrincipalName",
+                id: "id",
+                // `offline_access` is what makes Entra issue a refresh token.
+                scopes: ["User.Read", "offline_access"],
+            },
+            tolerated: ["openid", "profile", "email"],
+        },
+        hint: "An app registration in Entra for accounts in any organization and personal accounts, with the Gateway's callback as a Web redirect URI. If two apps share this client with different scopes, Microsoft may hand back both apps' scopes and the Gateway refuses the token: give each app its own client.",
+    },
+    // A Slack app's bot token: the top-level token of `oauth.v2.access`.
+    slack: {
+        id: "slack",
+        name: "Slack",
+        description: "Channels, members and messages, as the Slack app.",
+        docs: "https://api.slack.com/apps",
+        api: "https://api.slack.com/scopes",
+        hosts: ["slack.com"],
+        auth: {
+            kind: "oauth2-user",
+            authorizeUrl: "https://slack.com/oauth/v2/authorize",
+            tokenUrl: "https://slack.com/api/oauth.v2.access",
+            revokeUrl: "https://slack.com/api/auth.revoke",
+            clientId: "SLACK_CLIENT_ID",
+            clientSecret: "SLACK_CLIENT_SECRET",
+            inject: "form",
+            // Slack refuses `code_challenge`.
+            pkce: false,
+            scopeSeparator: "comma",
+            identity: {
+                url: "https://slack.com/api/auth.test",
+                label: "team",
+                id: "team_id",
+            },
+        },
+        hint: "A Slack app with the Gateway's callback as its redirect URL and the bot scopes your apps list.",
+    },
+};

package/dist/internal/oauthClient.d.ts

@@ -1,13 +1,13 @@
 /**
- * The `oauth_client` capability's wire rules (docs/capabilities.md "OAuth
- * clients"), shared by the gateway, which puts the operator's client on an
- * app's token request, and the SDK's local-dev fallback, which puts the
- * developer's own on it the same way.
+ * An OAuth provider's client as the gateway holds it in its settings
+ * (`everyapp secret set <CLIENT_ID> <CLIENT_SECRET>`); one an owner or
+ * admin pasted under Manage workspace → Providers is the gateway's own
+ * D1 row instead.
  */
-import { type CapabilitySettings, type OAuthClientCapability, type OAuthTokenEndpoint } from "./capabilities.js";
-/** The largest token request body the gateway reads: real ones are a few hundred bytes. */
+import type { CapabilitySettings, OAuthClientCapability } from "./capabilities.js";
+/** The largest token answer the gateway reads: real ones are a few kilobytes. */
 export declare const OAUTH_TOKEN_BODY_LIMIT: number;
-/** An OAuth client as the gateway (or `.dev.vars`) holds it. */
+/** An OAuth client as the gateway holds it. */
 export interface OAuthClientCredentials {
     clientId: string;
     /** Absent for a public client. */
@@ -15,49 +15,7 @@ export interface OAuthClientCredentials {
 }
 /**
  * The client `settings` hold for `capability`, or null until every setting
- * it needs is set: the id, the secret (unless it is a public client), and a
- * `hostSetting` that is an https origin when it is set at all.
+ * it needs is set: the id, and the secret unless it is a public client.
  */
 export declare function oauthClientCredentials(capability: OAuthClientCapability, settings: CapabilitySettings): OAuthClientCredentials | null;
-/** A token request: where it goes, its headers, its (buffered) body. */
-export interface TokenRequest {
-    url: URL;
-    headers: Headers;
-    body: string | null;
-}
-export type InjectedTokenRequest = ({
-    ok: true;
-} & TokenRequest) | {
-    ok: false;
-    problem: string;
-};
-/**
- * `request` with `client` put where `rule` says (the form body, HTTP Basic,
- * the query string or the JSON body), and every client credential the app
- * sent removed wherever it was: the `Authorization` header, and
- * `client_id`/`client_secret` (or the rule's names for them, in any case) in
- * the query string and the body. Bodies are re-serialised from their parsed
- * values, so a crafted body can't carry a second secret past the parser.
- * Token requests are form-encoded or JSON; anything else is refused.
- */
-export declare function injectClientCredentials(request: TokenRequest, rule: OAuthTokenEndpoint, client: OAuthClientCredentials): InjectedTokenRequest;
-/**
- * The grants the gateway completes: each ends in a user's own tokens. The
- * client-credentials grant, and anything else a network serves on the same
- * endpoint, would mint a token for the gateway's own application instead,
- * which on Meta, Discord, Twitch or Kick manages the application's
- * settings, its webhooks and every tenant's tokens.
- */
-export declare const USER_BOUND_GRANT_TYPES: ReadonlySet<string>;
-/**
- * A token request's `grant_type` as the app sent it, from its body or query
- * string, or null when it names none (Meta's code exchange). Never the
- * request's other fields.
- */
-export declare function requestedGrantType(request: TokenRequest): string | null;
-/**
- * A token request's `grant_type` for logs: one of the known grant types,
- * `other`, or null when it names none.
- */
-export declare function tokenGrantType(request: TokenRequest): string | null;
 //# sourceMappingURL=oauthClient.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"oauthClient.d.ts","sourceRoot":"","sources":["../../src/internal/oauthClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAY,CAAC;AAEhD,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,QAAQ,EAAE,kBAAkB,GAC3B,sBAAsB,GAAG,IAAI,CAW/B;AAMD,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAC5B,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,YAAY,CAAC,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAKnC;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,sBAAsB,GAC7B,oBAAoB,CAyFtB;AAaD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAOrD,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAUvE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAInE"}
+{"version":3,"file":"oauthClient.d.ts","sourceRoot":"","sources":["../../src/internal/oauthClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,QAAY,CAAC;AAEhD,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,QAAQ,EAAE,kBAAkB,GAC3B,sBAAsB,GAAG,IAAI,CAQ/B"}

package/dist/internal/oauthClient.js

@@ -1,16 +1,8 @@
-/**
- * The `oauth_client` capability's wire rules (docs/capabilities.md "OAuth
- * clients"), shared by the gateway, which puts the operator's client on an
- * app's token request, and the SDK's local-dev fallback, which puts the
- * developer's own on it the same way.
- */
-import { base64Utf8, oauthClientOrigin, } from "./capabilities.js";
-/** The largest token request body the gateway reads: real ones are a few hundred bytes. */
+/** The largest token answer the gateway reads: real ones are a few kilobytes. */
 export const OAUTH_TOKEN_BODY_LIMIT = 64 * 1024;
 /**
  * The client `settings` hold for `capability`, or null until every setting
- * it needs is set: the id, the secret (unless it is a public client), and a
- * `hostSetting` that is an https origin when it is set at all.
+ * it needs is set: the id, and the secret unless it is a public client.
  */
 export function oauthClientCredentials(capability, settings) {
     const clientId = settingValue(settings[capability.secrets.clientId]);
@@ -20,175 +12,8 @@ export function oauthClientCredentials(capability, settings) {
         : undefined;
     if (!clientId || (secretName && !clientSecret))
         return null;
-    if (capability.hostSetting && !oauthClientOrigin(capability, settings)) {
-        return null;
-    }
     return { clientId, ...(clientSecret ? { clientSecret } : {}) };
 }
 function settingValue(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
-const FORM = "application/x-www-form-urlencoded";
-const JSON_TYPE = "application/json";
-/**
- * `request` with `client` put where `rule` says (the form body, HTTP Basic,
- * the query string or the JSON body), and every client credential the app
- * sent removed wherever it was: the `Authorization` header, and
- * `client_id`/`client_secret` (or the rule's names for them, in any case) in
- * the query string and the body. Bodies are re-serialised from their parsed
- * values, so a crafted body can't carry a second secret past the parser.
- * Token requests are form-encoded or JSON; anything else is refused.
- */
-export function injectClientCredentials(request, rule, client) {
-    const idName = rule.params?.clientId ?? "client_id";
-    const secretName = rule.params?.clientSecret ?? "client_secret";
-    const credentialNames = new Set(["client_id", "client_secret", idName, secretName].map((name) => name.toLowerCase()));
-    const isCredential = (name) => credentialNames.has(name.toLowerCase());
-    const fields = [
-        [idName, client.clientId],
-        ...(client.clientSecret
-            ? [[secretName, client.clientSecret]]
-            : []),
-    ];
-    // The query keeps the app's other fields as they were sent.
-    const url = new URL(request.url);
-    const query = url.search
-        .slice(1)
-        .split("&")
-        .filter((pair) => {
-        const [name] = new URLSearchParams(pair).keys();
-        return pair !== "" && !(name !== undefined && isCredential(name));
-    });
-    if (rule.inject === "query") {
-        query.push(new URLSearchParams(fields).toString());
-    }
-    url.search = query.join("&");
-    const headers = new Headers(request.headers);
-    headers.delete("authorization");
-    headers.delete("content-length");
-    if (rule.inject === "basic") {
-        headers.set("authorization", `Basic ${base64Utf8(`${client.clientId}:${client.clientSecret ?? ""}`)}`);
-    }
-    const type = mediaType(headers.get("content-type"));
-    let body = request.body;
-    if (body === null || body === "") {
-        // Nothing the app sent; the form and JSON rules make the body.
-        if (rule.inject === "form") {
-            headers.set("content-type", FORM);
-            body = new URLSearchParams(fields).toString();
-        }
-        else if (rule.inject === "json") {
-            headers.set("content-type", JSON_TYPE);
-            body = JSON.stringify(Object.fromEntries(fields));
-        }
-    }
-    else if (type === FORM) {
-        if (rule.inject === "json") {
-            return { ok: false, problem: "This token endpoint takes a JSON body." };
-        }
-        const params = new URLSearchParams(body);
-        for (const name of new Set([...params.keys()].filter(isCredential))) {
-            params.delete(name);
-        }
-        if (rule.inject === "form") {
-            for (const [name, value] of fields)
-                params.set(name, value);
-        }
-        body = params.toString();
-    }
-    else if (type === JSON_TYPE) {
-        if (rule.inject === "form") {
-            return {
-                ok: false,
-                problem: `This token endpoint takes a form-encoded body (${FORM}).`,
-            };
-        }
-        const parsed = jsonObject(body);
-        if (!parsed) {
-            return { ok: false, problem: "The body is not a JSON object." };
-        }
-        for (const name of Object.keys(parsed)) {
-            if (isCredential(name))
-                delete parsed[name];
-        }
-        if (rule.inject === "json") {
-            for (const [name, value] of fields)
-                parsed[name] = value;
-        }
-        body = JSON.stringify(parsed);
-    }
-    else {
-        return {
-            ok: false,
-            problem: `A token request's body is form-encoded (${FORM}) or JSON (${JSON_TYPE}).`,
-        };
-    }
-    return { ok: true, url, headers, body };
-}
-/** The grant types logs may name; anything else is logged as `other`. */
-const GRANT_TYPES = new Set([
-    "authorization_code",
-    "refresh_token",
-    "client_credentials",
-    "fb_exchange_token",
-    "ig_exchange_token",
-    "th_exchange_token",
-    "urn:ietf:params:oauth:grant-type:token-exchange",
-]);
-/**
- * The grants the gateway completes: each ends in a user's own tokens. The
- * client-credentials grant, and anything else a network serves on the same
- * endpoint, would mint a token for the gateway's own application instead,
- * which on Meta, Discord, Twitch or Kick manages the application's
- * settings, its webhooks and every tenant's tokens.
- */
-export const USER_BOUND_GRANT_TYPES = new Set([
-    "authorization_code",
-    "refresh_token",
-    "fb_exchange_token",
-    "ig_exchange_token",
-    "th_exchange_token",
-    "urn:ietf:params:oauth:grant-type:token-exchange",
-]);
-/**
- * A token request's `grant_type` as the app sent it, from its body or query
- * string, or null when it names none (Meta's code exchange). Never the
- * request's other fields.
- */
-export function requestedGrantType(request) {
-    let value = null;
-    const type = mediaType(request.headers.get("content-type"));
-    if (request.body && type === FORM) {
-        value = new URLSearchParams(request.body).get("grant_type");
-    }
-    else if (request.body && type === JSON_TYPE) {
-        value = jsonObject(request.body)?.["grant_type"] ?? null;
-    }
-    value ??= request.url.searchParams.get("grant_type");
-    return typeof value === "string" && value ? value : null;
-}
-/**
- * A token request's `grant_type` for logs: one of the known grant types,
- * `other`, or null when it names none.
- */
-export function tokenGrantType(request) {
-    const value = requestedGrantType(request);
-    if (value === null)
-        return null;
-    return GRANT_TYPES.has(value) ? value : "other";
-}
-/** A Content-Type's media type, lowercased and without parameters. */
-function mediaType(contentType) {
-    return (contentType ?? "").split(";")[0].trim().toLowerCase();
-}
-function jsonObject(text) {
-    try {
-        const value = JSON.parse(text);
-        return value && typeof value === "object" && !Array.isArray(value)
-            ? value
-            : null;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/internal/oauthPresets.d.ts

@@ -0,0 +1,32 @@
+/**
+ * OAuth presets: ready `oauth2-user` specs, in the JSON shape `everyapp
+ * provider add` takes, for providers people most often want a "Connect"
+ * button for. A preset becomes a `providers` row when added (`everyapp
+ * provider add --oauth github-oauth`, the Admin dialog,
+ * `everyapp_provider_add` with `preset`), so an operator may `provider
+ * show` and edit a copy; nothing here is a hidden catalog entry, and no
+ * gateway reserves a preset's setting names until it is added. Google,
+ * Microsoft and Slack are built in (./oauthBuiltIns.ts) and are offered
+ * in the same picker.
+ *
+ * Each preset parses with `parseProviderSpec` (oauthPresets.test.ts) and
+ * names a console where the client is made, the API hosts the token is
+ * sent to, and how the provider spells scopes. Which scopes a connection
+ * holds is each app's `everyapp.config.ts`, never the preset. Endpoints
+ * were checked against the providers' docs on 2026-10-25; only GitHub's
+ * and Google's have been tried against a live connect.
+ */
+import { type RegistrableCapability } from "./providerSpec.js";
+/** A preset's spec as JSON: the shape of ./oauthSpec.ts. */
+export type OAuthPresetSpec = Readonly<Record<string, unknown>>;
+export declare const OAUTH_PRESETS: Readonly<Record<string, OAuthPresetSpec>>;
+/** The preset ids, in the order the picker shows them. */
+export declare function oauthPresetIds(): string[];
+/** A preset's parsed capability, for the picker's labels; throws for an unknown id (the test parses every preset). */
+export declare function oauthPreset(id: string): RegistrableCapability | null;
+/** Whether `capability` is an OAuth provider the Gateway runs the flow for. */
+export declare function isOAuthProvider(capability: {
+    mode: string;
+    flow?: unknown;
+} | undefined): boolean;
+//# sourceMappingURL=oauthPresets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauthPresets.d.ts","sourceRoot":"","sources":["../../src/internal/oauthPresets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAE3B,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEhE,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAwNnE,CAAC;AAEF,0DAA0D;AAC1D,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,sHAAsH;AACtH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAUpE;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAC7B,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GACvD,OAAO,CAET"}