@every-app/sdk 0.3.0-rc.14 → 0.3.0-rc.15

package/dist/internal/oauthPresets.d.ts

@@ -1,13 +1,17 @@
 /**
- * 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.
+ * The OAuth providers, as presets: ready `oauth2-user` specs in the JSON
+ * shape `everyapp provider add` takes. Every OAuth provider a Gateway
+ * serves is a `providers` row, and a preset is that row's spec, written
+ * when an app whose manifest names the preset's id is deployed or
+ * installed, or when an operator adds it (`everyapp provider add
+ * google-workspace`, the Admin dialog, `everyapp_provider_add` with
+ * `preset`). An operator may `provider show` and edit the row's copy. No
+ * gateway reserves a preset's setting names until its row is written.
+ * What differs between providers is data here: 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 reads a provider id to decide
+ * anything.
  *
  * Each preset parses with `parseProviderSpec` (oauthPresets.test.ts) and
  * names a console where the client is made, the API hosts the token is
@@ -15,18 +19,351 @@
  * 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.
+ *
+ * A row is a copy: changing a preset here changes no Gateway that has
+ * written its row already. A change that must reach them ships with a D1
+ * data migration (as 0032 wrote the first rows) that rewrites the rows
+ * still equal to the old spec and moves `bound_to` (and a pasted client's
+ * `oauth_clients.bound_to`) from the old binding key to the new one, so
+ * the client keeps being read and `isPresetRow` keeps matching.
  */
+import type { CapabilityLookup } from "./capabilities.js";
 import { type RegistrableCapability } from "./providerSpec.js";
 /** A preset's spec as JSON: the shape of ./oauthSpec.ts. */
 export type OAuthPresetSpec = Readonly<Record<string, unknown>>;
+declare const PRESETS: {
+    readonly "google-workspace": {
+        readonly id: "google-workspace";
+        readonly name: "Google";
+        readonly description: "Gmail, Calendar, Drive, Search Console, Analytics and the other Google APIs, as the person who connects.";
+        readonly docs: "https://console.cloud.google.com/apis/credentials";
+        readonly api: "https://developers.google.com/identity/protocols/oauth2/scopes";
+        readonly hosts: readonly ["gmail.googleapis.com", "www.googleapis.com", "searchconsole.googleapis.com", "analyticsdata.googleapis.com", "analyticsadmin.googleapis.com", "openidconnect.googleapis.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth";
+            readonly tokenUrl: "https://oauth2.googleapis.com/token";
+            readonly revokeUrl: "https://oauth2.googleapis.com/revoke";
+            readonly clientId: "GOOGLE_WORKSPACE_CLIENT_ID";
+            readonly clientSecret: "GOOGLE_WORKSPACE_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: true;
+            readonly scopeSeparator: "space";
+            readonly scopePrefix: "https://www.googleapis.com/auth/";
+            readonly authorizeParams: {
+                readonly access_type: "offline";
+                readonly prompt: "consent";
+            };
+            readonly identity: {
+                readonly url: "https://openidconnect.googleapis.com/v1/userinfo";
+                readonly label: "email";
+                readonly id: "sub";
+                readonly scopes: readonly ["openid", "email"];
+            };
+            readonly tolerated: readonly ["profile", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/userinfo.profile"];
+        };
+        readonly 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.";
+    };
+    readonly "microsoft-365": {
+        readonly id: "microsoft-365";
+        readonly name: "Microsoft 365";
+        readonly description: "Outlook mail and calendar, OneDrive and the rest of Microsoft Graph, as the person who connects.";
+        readonly docs: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade";
+        readonly api: "https://learn.microsoft.com/graph/permissions-reference";
+        readonly hosts: readonly ["graph.microsoft.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
+            readonly tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token";
+            readonly clientId: "MICROSOFT_365_CLIENT_ID";
+            readonly clientSecret: "MICROSOFT_365_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: true;
+            readonly scopeSeparator: "space";
+            readonly scopePrefix: "https://graph.microsoft.com/";
+            readonly identity: {
+                readonly url: "https://graph.microsoft.com/v1.0/me";
+                readonly label: "userPrincipalName";
+                readonly id: "id";
+                readonly scopes: readonly ["User.Read", "offline_access"];
+            };
+            readonly tolerated: readonly ["openid", "profile", "email"];
+        };
+        readonly 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.";
+    };
+    readonly slack: {
+        readonly id: "slack";
+        readonly name: "Slack";
+        readonly description: "Channels, members and messages, as the Slack app.";
+        readonly docs: "https://api.slack.com/apps";
+        readonly api: "https://api.slack.com/scopes";
+        readonly hosts: readonly ["slack.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://slack.com/oauth/v2/authorize";
+            readonly tokenUrl: "https://slack.com/api/oauth.v2.access";
+            readonly revokeUrl: "https://slack.com/api/auth.revoke";
+            readonly clientId: "SLACK_CLIENT_ID";
+            readonly clientSecret: "SLACK_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: false;
+            readonly scopeSeparator: "comma";
+            readonly identity: {
+                readonly url: "https://slack.com/api/auth.test";
+                readonly label: "team";
+                readonly id: "team_id";
+            };
+        };
+        readonly hint: "A Slack app with the Gateway's callback as its redirect URL and the bot scopes your apps list. The Gateway takes its Client ID and Client Secret, not a bot token (xoxb-).";
+    };
+    readonly "github-oauth": {
+        readonly id: "github-oauth";
+        readonly name: "GitHub";
+        readonly description: "Repositories, issues, pull requests and the person's profile.";
+        readonly docs: "https://github.com/settings/developers";
+        readonly api: "https://docs.github.com/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps";
+        readonly hosts: readonly ["api.github.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://github.com/login/oauth/authorize";
+            readonly tokenUrl: "https://github.com/login/oauth/access_token";
+            readonly revokeUrl: "https://api.github.com/applications/{client_id}/grant";
+            readonly revokeMethod: "DELETE";
+            readonly clientId: "GITHUB_OAUTH_CLIENT_ID";
+            readonly clientSecret: "GITHUB_OAUTH_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: true;
+            readonly scopeSeparator: "comma";
+            readonly tokenHeaders: {
+                readonly Accept: "application/json";
+            };
+            readonly identity: {
+                readonly url: "https://api.github.com/user";
+                readonly label: "login";
+                readonly id: "id";
+            };
+        };
+        readonly hint: "Register an OAuth App (not a GitHub App) and paste its client id and secret. GitHub's `repo` scope is read and write.";
+    };
+    readonly "notion-oauth": {
+        readonly id: "notion-oauth";
+        readonly name: "Notion";
+        readonly description: "Pages and databases the person shares with the integration.";
+        readonly docs: "https://www.notion.so/my-integrations";
+        readonly api: "https://developers.notion.com/reference";
+        readonly hosts: readonly ["api.notion.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://api.notion.com/v1/oauth/authorize";
+            readonly tokenUrl: "https://api.notion.com/v1/oauth/token";
+            readonly clientId: "NOTION_OAUTH_CLIENT_ID";
+            readonly clientSecret: "NOTION_OAUTH_CLIENT_SECRET";
+            readonly inject: "basic";
+            readonly pkce: false;
+            readonly scopeSeparator: "space";
+            readonly authorizeParams: {
+                readonly owner: "user";
+            };
+        };
+        readonly hint: "Notion has no scopes: an app lists scopes: [] and the person picks the pages to share on Notion's consent screen. Make the integration public to get a client id and secret. Apps send `Notion-Version` on every call.";
+    };
+    readonly "linear-oauth": {
+        readonly id: "linear-oauth";
+        readonly name: "Linear";
+        readonly description: "Issues, projects and teams, over Linear's GraphQL API.";
+        readonly docs: "https://linear.app/settings/api/applications";
+        readonly api: "https://developers.linear.app/docs/oauth/authentication";
+        readonly hosts: readonly ["api.linear.app"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://linear.app/oauth/authorize";
+            readonly tokenUrl: "https://api.linear.app/oauth/token";
+            readonly revokeUrl: "https://api.linear.app/oauth/revoke";
+            readonly clientId: "LINEAR_OAUTH_CLIENT_ID";
+            readonly clientSecret: "LINEAR_OAUTH_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: false;
+            readonly scopeSeparator: "comma";
+        };
+        readonly hint: "Linear's scopes are read, write, issues:create and comments:create; its API is GraphQL over POST.";
+    };
+    readonly "gitlab-oauth": {
+        readonly id: "gitlab-oauth";
+        readonly name: "GitLab";
+        readonly description: "Projects, merge requests and issues on gitlab.com.";
+        readonly docs: "https://gitlab.com/-/user_settings/applications";
+        readonly api: "https://docs.gitlab.com/integration/oauth_provider/#view-all-authorized-applications";
+        readonly hosts: readonly ["gitlab.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://gitlab.com/oauth/authorize";
+            readonly tokenUrl: "https://gitlab.com/oauth/token";
+            readonly revokeUrl: "https://gitlab.com/oauth/revoke";
+            readonly clientId: "GITLAB_OAUTH_CLIENT_ID";
+            readonly clientSecret: "GITLAB_OAUTH_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: true;
+            readonly scopeSeparator: "space";
+            readonly identity: {
+                readonly url: "https://gitlab.com/api/v4/user";
+                readonly label: "username";
+                readonly id: "id";
+                readonly scopes: readonly ["read_user"];
+            };
+        };
+        readonly hint: "A self-managed GitLab needs a custom provider with its own host in place of gitlab.com.";
+    };
+    readonly atlassian: {
+        readonly id: "atlassian";
+        readonly name: "Atlassian (Jira and Confluence)";
+        readonly description: "Jira issues and Confluence pages on the sites the person grants.";
+        readonly docs: "https://developer.atlassian.com/console/myapps/";
+        readonly api: "https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/";
+        readonly hosts: readonly ["api.atlassian.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://auth.atlassian.com/authorize";
+            readonly tokenUrl: "https://auth.atlassian.com/oauth/token";
+            readonly clientId: "ATLASSIAN_CLIENT_ID";
+            readonly clientSecret: "ATLASSIAN_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: false;
+            readonly scopeSeparator: "space";
+            readonly authorizeParams: {
+                readonly audience: "api.atlassian.com";
+                readonly prompt: "consent";
+            };
+            readonly identity: {
+                readonly url: "https://api.atlassian.com/me";
+                readonly label: "email";
+                readonly id: "account_id";
+                readonly scopes: readonly ["read:me", "offline_access"];
+            };
+        };
+        readonly hint: "Calls go to api.atlassian.com/ex/jira/<cloud id>/… ; the cloud id comes from /oauth/token/accessible-resources.";
+    };
+    readonly "hubspot-oauth": {
+        readonly id: "hubspot-oauth";
+        readonly name: "HubSpot";
+        readonly description: "CRM contacts, companies and deals.";
+        readonly docs: "https://developers.hubspot.com/";
+        readonly api: "https://developers.hubspot.com/docs/api/working-with-oauth";
+        readonly hosts: readonly ["api.hubapi.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://app.hubspot.com/oauth/authorize";
+            readonly tokenUrl: "https://api.hubapi.com/oauth/v1/token";
+            readonly clientId: "HUBSPOT_OAUTH_CLIENT_ID";
+            readonly clientSecret: "HUBSPOT_OAUTH_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: false;
+            readonly scopeSeparator: "space";
+        };
+        readonly hint: "The app's scopes in HubSpot's developer console must include the scopes apps list, or HubSpot refuses the authorize URL.";
+    };
+    readonly zoom: {
+        readonly id: "zoom";
+        readonly name: "Zoom";
+        readonly description: "The person's meetings and recordings.";
+        readonly docs: "https://marketplace.zoom.us/develop/create";
+        readonly api: "https://developers.zoom.us/docs/integrations/oauth-scopes-overview/";
+        readonly hosts: readonly ["api.zoom.us"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://zoom.us/oauth/authorize";
+            readonly tokenUrl: "https://zoom.us/oauth/token";
+            readonly revokeUrl: "https://zoom.us/oauth/revoke";
+            readonly clientId: "ZOOM_CLIENT_ID";
+            readonly clientSecret: "ZOOM_CLIENT_SECRET";
+            readonly inject: "basic";
+            readonly pkce: true;
+            readonly scopeSeparator: "space";
+            readonly identity: {
+                readonly url: "https://api.zoom.us/v2/users/me";
+                readonly label: "email";
+                readonly id: "id";
+                readonly scopes: readonly ["user:read:user"];
+            };
+        };
+        readonly hint: "A General app with user-managed OAuth, using Zoom's granular scope names.";
+    };
+    readonly dropbox: {
+        readonly id: "dropbox";
+        readonly name: "Dropbox";
+        readonly description: "Files and folders in the person's Dropbox.";
+        readonly docs: "https://www.dropbox.com/developers/apps";
+        readonly api: "https://developers.dropbox.com/oauth-guide";
+        readonly hosts: readonly ["api.dropboxapi.com", "content.dropboxapi.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://www.dropbox.com/oauth2/authorize";
+            readonly tokenUrl: "https://api.dropboxapi.com/oauth2/token";
+            readonly revokeUrl: "https://api.dropboxapi.com/2/auth/token/revoke";
+            readonly clientId: "DROPBOX_OAUTH_CLIENT_ID";
+            readonly clientSecret: "DROPBOX_OAUTH_CLIENT_SECRET";
+            readonly inject: "form";
+            readonly pkce: true;
+            readonly scopeSeparator: "space";
+            readonly authorizeParams: {
+                readonly token_access_type: "offline";
+            };
+            readonly tolerated: readonly ["account_info.read"];
+        };
+        readonly hint: "`token_access_type=offline` is what yields a refresh token.";
+    };
+    readonly spotify: {
+        readonly id: "spotify";
+        readonly name: "Spotify";
+        readonly description: "The person's library, playlists and listening.";
+        readonly docs: "https://developer.spotify.com/dashboard";
+        readonly api: "https://developer.spotify.com/documentation/web-api/concepts/scopes";
+        readonly hosts: readonly ["api.spotify.com"];
+        readonly auth: {
+            readonly kind: "oauth2-user";
+            readonly authorizeUrl: "https://accounts.spotify.com/authorize";
+            readonly tokenUrl: "https://accounts.spotify.com/api/token";
+            readonly clientId: "SPOTIFY_CLIENT_ID";
+            readonly clientSecret: "SPOTIFY_CLIENT_SECRET";
+            readonly inject: "basic";
+            readonly pkce: true;
+            readonly scopeSeparator: "space";
+            readonly identity: {
+                readonly url: "https://api.spotify.com/v1/me";
+                readonly label: "display_name";
+                readonly id: "id";
+            };
+        };
+    };
+};
+/** The id of an OAuth provider the SDK ships a preset for (`google-workspace`, `github-oauth`, ...). */
+export type OAuthPresetId = keyof typeof PRESETS;
+/** Every preset by id, in the order the picker shows them. */
 export declare const OAUTH_PRESETS: Readonly<Record<string, OAuthPresetSpec>>;
+/** The setup guide for OAuth provider `id`'s client, when its preset has one (`setup` in an app's settings report). */
+export declare function oauthSetupGuide(id: string): string | undefined;
 /** 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;
+/**
+ * Whether `capability`, a Gateway's row for `id`, is that preset's: its
+ * client would go to the preset's endpoints and hosts under the preset's
+ * setting names (the same binding key). Adding the preset again takes the
+ * client for such a row; a row of another spec under a preset's id is the
+ * operator's own and is never taken for the preset.
+ */
+export declare function isPresetRow(id: string, capability: RegistrableCapability): boolean;
+/**
+ * The preset ids among `ids` (an app's capabilities) that `lookup` (a
+ * Gateway's registry) doesn't have: the rows a deploy or an install
+ * writes from their presets before it checks the manifest.
+ */
+export declare function unregisteredPresetIds(ids: Iterable<string>, lookup: Pick<CapabilityLookup, "get">): string[];
+/**
+ * `lookup` with every preset it lacks, as the row it would be: what a
+ * local run (`everyapp dev`) and a check made before a Gateway is asked
+ * read, since a deploy writes the row of any preset an app names.
+ */
+export declare function withOAuthPresets(lookup: CapabilityLookup): CapabilityLookup;
+export {};
 //# sourceMappingURL=oauthPresets.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"oauthPresets.d.ts","sourceRoot":"","sources":["../../src/internal/oauthPresets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,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,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwUuC,CAAC;AAErD,wGAAwG;AACxG,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,OAAO,CAAC;AAEjD,8DAA8D;AAC9D,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAW,CAAC;AAShF,uHAAuH;AACvH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE9D;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,sHAAsH;AACtH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAUpE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAMT;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EACrB,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,GACpC,MAAM,EAAE,CAIV;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAQ3E"}

package/dist/internal/oauthPresets.js

@@ -1,23 +1,115 @@
-/**
- * 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 { providerBindingKey } from "./providerRegistry.js";
 import { parseProviderSpec, } from "./providerSpec.js";
-export const OAUTH_PRESETS = {
+const PRESETS = {
+    // 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",
+            // A disconnect revokes the grant: POST form `token=` (RFC 7009), the
+            // refresh token once the access token has expired.
+            revokeUrl: "https://oauth2.googleapis.com/revoke",
+            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. The Gateway takes its Client ID and Client Secret, not a bot token (xoxb-).",
+    },
     "github-oauth": {
         id: "github-oauth",
         name: "GitHub",
@@ -232,6 +324,18 @@ export const OAUTH_PRESETS = {
         },
     },
 };
+/** Every preset by id, in the order the picker shows them. */
+export const OAUTH_PRESETS = PRESETS;
+/** The everyapp skill's guides for a preset's client, where one exists. */
+const SETUP_GUIDES = {
+    "google-workspace": "setup/google.md",
+    "microsoft-365": "setup/microsoft-365.md",
+    slack: "setup/slack.md",
+};
+/** The setup guide for OAuth provider `id`'s client, when its preset has one (`setup` in an app's settings report). */
+export function oauthSetupGuide(id) {
+    return SETUP_GUIDES[id];
+}
 /** The preset ids, in the order the picker shows them. */
 export function oauthPresetIds() {
     return Object.keys(OAUTH_PRESETS);
@@ -247,7 +351,36 @@ export function oauthPreset(id) {
     }
     return parsed.capability;
 }
-/** Whether `capability` is an OAuth provider the Gateway runs the flow for. */
-export function isOAuthProvider(capability) {
-    return capability?.mode === "oauth_client" && capability.flow !== undefined;
+/**
+ * Whether `capability`, a Gateway's row for `id`, is that preset's: its
+ * client would go to the preset's endpoints and hosts under the preset's
+ * setting names (the same binding key). Adding the preset again takes the
+ * client for such a row; a row of another spec under a preset's id is the
+ * operator's own and is never taken for the preset.
+ */
+export function isPresetRow(id, capability) {
+    const preset = oauthPreset(id);
+    return (preset !== null &&
+        providerBindingKey(capability) === providerBindingKey(preset));
+}
+/**
+ * The preset ids among `ids` (an app's capabilities) that `lookup` (a
+ * Gateway's registry) doesn't have: the rows a deploy or an install
+ * writes from their presets before it checks the manifest.
+ */
+export function unregisteredPresetIds(ids, lookup) {
+    return [...new Set(ids)].filter((id) => Object.hasOwn(OAUTH_PRESETS, id) && lookup.get(id) === undefined);
+}
+/**
+ * `lookup` with every preset it lacks, as the row it would be: what a
+ * local run (`everyapp dev`) and a check made before a Gateway is asked
+ * read, since a deploy writes the row of any preset an app names.
+ */
+export function withOAuthPresets(lookup) {
+    const presets = oauthPresetIds().filter((id) => !lookup.get(id));
+    return {
+        get: (id) => lookup.get(id) ??
+            (presets.includes(id) ? (oauthPreset(id) ?? undefined) : undefined),
+        ids: () => [...lookup.ids(), ...presets],
+    };
 }

package/dist/internal/oauthSpec.d.ts

@@ -1,7 +1,6 @@
 /**
  * The `oauth2-user` half of a provider spec: a registered OAuth provider,
- * a preset (./oauthPresets.ts) or a built-in one (./oauthBuiltIns.ts), as
- * JSON, turned into an {@link OAuthClientCapability} whose `flow` the
+ * one written from a preset (./oauthPresets.ts), as JSON, turned into an {@link OAuthClientCapability} whose `flow` the
  * Gateway runs. `parseProviderSpec` (./providerSpec.ts) hands the common
  * fields here once it sees `auth.kind: "oauth2-user"`. Nothing here reads
  * a value: a spec names Gateway settings, never holds one.
@@ -12,11 +11,8 @@
  * identity URL with the scopes it needs, and the scopes a token may carry
  * beyond what was asked (`tolerated`). Which scopes an app gets is its own
  * `everyapp.config.ts`, never the spec.
- *
- * Only type imports from ./capabilities.ts: the catalog builds its
- * built-in entries with {@link oauthCapabilityFromSpec} at load.
  */
-import type { OAuthClientCapability, OAuthClientInjection, OAuthScopeSeparator } from "./capabilities.js";
+import type { OAuthClientCapability } from "./capabilities.js";
 export interface SpecProblem {
     path: string;
     message: string;
@@ -55,46 +51,6 @@ export interface ParsedOAuthSpec {
  * the capability with its `flow`.
  */
 export declare function parseOAuthUserSpec(input: Record<string, unknown>, common: OAuthSpecCommon, problems: SpecProblem[]): ParsedOAuthSpec | undefined;
-/** The JSON shape of an `oauth2-user` spec, as the built-ins and presets write it. */
-export interface OAuthSpecJson {
-    readonly id: string;
-    readonly name: string;
-    readonly description?: string;
-    readonly docs: string;
-    readonly api?: string;
-    readonly hosts: readonly string[];
-    readonly auth: {
-        readonly kind: "oauth2-user";
-        readonly authorizeUrl: string;
-        readonly tokenUrl: string;
-        readonly revokeUrl?: string;
-        readonly revokeMethod?: "POST" | "DELETE";
-        readonly clientId: string;
-        readonly clientSecret?: string;
-        readonly inject?: OAuthClientInjection;
-        readonly pkce?: boolean;
-        readonly scopeSeparator?: OAuthScopeSeparator;
-        readonly scopePrefix?: string;
-        readonly authorizeParams?: Readonly<Record<string, string>>;
-        readonly tokenHeaders?: Readonly<Record<string, string>>;
-        readonly identity?: {
-            readonly url: string;
-            readonly label: string;
-            readonly id?: string;
-            readonly scopes?: readonly string[];
-        };
-        readonly tolerated?: readonly string[];
-    };
-    readonly hint?: string;
-    readonly example?: string;
-    readonly tags?: readonly string[];
-}
-/**
- * A spec already known to be good (a built-in, checked by its test) as
- * its capability, without the parse: what the catalog runs at load, where
- * calling the full parser would be an import cycle.
- */
-export declare function oauthCapabilityFromSpec(spec: OAuthSpecJson): OAuthClientCapability;
 /**
  * The JSON spec of an OAuth capability (`provider show`, a preset's round
  * trip): `parseProviderSpec` of it gives the capability back.