@superblocksteam/shared 0.9607.2 → 0.9608.0

package/src/errors/http.ts

@@ -10,6 +10,18 @@ export class HttpError extends Error {
   }
 }
 
+/**
+ * An upstream failure that may resolve on its own, so the caller is invited to try again.
+ * `retryAfterSeconds` is surfaced to HTTP clients as the Retry-After response header.
+ */
+export abstract class RetryableHttpError extends HttpError {
+  retryAfterSeconds?: number;
+  constructor(status: number, message: string, title: string, retryAfterSeconds?: number) {
+    super(status, message, title);
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+}
+
 export class BadRequestError extends HttpError {
   constructor(message: string) {
     super(400, message, 'Bad request');
@@ -53,9 +65,9 @@ export class NotImplementedError extends HttpError {
   }
 }
 
-export class BadGatewayError extends HttpError {
-  constructor(message: string) {
-    super(502, message, 'Bad gateway');
+export class BadGatewayError extends RetryableHttpError {
+  constructor(message: string, retryAfterSeconds?: number) {
+    super(502, message, 'Bad gateway', retryAfterSeconds);
   }
 }
 
@@ -96,9 +108,15 @@ export class FailedDependencyError extends HttpError {
   }
 }
 
-export class ServiceUnavailableError extends HttpError {
-  constructor(message?: string) {
-    super(503, message || 'Service Unavailable', 'Service Unavailable');
+export class ServiceUnavailableError extends RetryableHttpError {
+  constructor(message?: string, retryAfterSeconds?: number) {
+    super(503, message || 'Service Unavailable', 'Service Unavailable', retryAfterSeconds);
+  }
+}
+
+export class GatewayTimeoutError extends RetryableHttpError {
+  constructor(message?: string, retryAfterSeconds?: number) {
+    super(504, message || 'Gateway timeout', 'Gateway timeout', retryAfterSeconds);
   }
 }
 

package/src/index.ts

@@ -27,4 +27,6 @@ export * from './tracing/errorSanitizer.js';
 export * from './jwt/index.js';
 export * from './org-features/index.js';
 export * from './database-lifecycle/index.js';
+export * from './database-lifecycle/appDatabaseCompatibility.js';
 export * from './database-lifecycle/edit-lifecycle-capability.js';
+export * from './environment-compatibility/appEnvironmentCompatibility.js';

package/src/plugins/templates/restApiIntegration.ts

@@ -67,6 +67,8 @@ export const RestApiIntegrationPlugin: Plugin = {
       },
       ...authSections({
         startVersion: RestApiIntegrationPluginVersions.V1,
+        pkceStartVersion: RestApiIntegrationPluginVersions.V16,
+        confidentialPkceStartVersion: RestApiIntegrationPluginVersions.V17,
         pluginId: ExtendedIntegrationPluginId.REST_API,
         pluginName: 'REST API',
         enabledMethods: {

package/src/plugins/templates/shared/auth.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from 'vitest';
+
+import {
+  ExtendedIntegrationPluginId,
+  FormComponentType,
+  FormItem,
+  getDisplayName,
+  getRowItemsFromSectionItem,
+  IntegrationAuthType
+} from '../../../types/index.js';
+import { authSections } from './auth.js';
+
+const buildAuthFields = (pkceStartVersion?: string, confidentialPkceStartVersion?: string): FormItem[] =>
+  authSections({
+    startVersion: '0.0.1',
+    pkceStartVersion,
+    confidentialPkceStartVersion,
+    pluginId: ExtendedIntegrationPluginId.REST_API,
+    pluginName: 'REST API',
+    // Matches the REST API integration, the only plugin that offers PKCE.
+    enabledMethods: { basic: true, firebase: true, oauth: true, bearer: true, apiKey: true }
+  }).flatMap((section) => section.items.flatMap((item) => getRowItemsFromSectionItem(item)));
+
+const findOrdinaryClientSecret = (fields: FormItem[]): FormItem | undefined =>
+  fields.find(
+    (field) =>
+      field.name === 'authConfig.clientSecret' &&
+      field.display?.show?.authType?.includes(IntegrationAuthType.OAUTH2_CODE) &&
+      field.display.show['authConfig.usePkce']?.includes('false')
+  );
+
+describe('PKCE display conditions', () => {
+  test('shows the client secret for every way the PKCE marker can be unset', () => {
+    const show = findOrdinaryClientSecret(buildAuthFields('0.0.16'))?.display?.show;
+
+    // `display.show` compares String(value), so each of these is a form value
+    // that means "PKCE is off" and must keep the field visible.
+    expect(show?.['authConfig.usePkce']).toEqual(expect.arrayContaining(['', '0', 'false', 'null', 'undefined']));
+  });
+
+  test('shows an optional client secret directly after the client ID for confidential PKCE clients', () => {
+    const publicFields = buildAuthFields('0.0.16');
+    const fields = buildAuthFields('0.0.16', '0.0.17');
+    const clientIdIndex = fields.findIndex(
+      (field) => field.name === 'authConfig.clientId' && field.display?.show?.authType?.includes(IntegrationAuthType.OAUTH2_CODE)
+    );
+    const clientSecretIndex = fields.findIndex(
+      (field) => field.name === 'authConfig.clientSecret' && !field.hidden && field.display?.show?.['authConfig.usePkce']?.includes('true')
+    );
+    const clientSecret = fields[clientSecretIndex];
+    const clientAuthMethod = fields.find(
+      (field) =>
+        field.name === 'authConfig.clientAuthMethod' && !field.hidden && field.display?.show?.['authConfig.usePkce']?.includes('true')
+    );
+
+    expect(
+      publicFields.find(
+        (field) =>
+          field.name === 'authConfig.clientSecret' && !field.hidden && field.display?.show?.['authConfig.usePkce']?.includes('true')
+      )
+    ).toBeUndefined();
+    expect(clientSecretIndex).toBe(clientIdIndex + 1);
+    expect(clientSecret?.startVersion).toBe('0.0.17');
+    expect(clientSecret?.rules).toEqual([{ required: false }]);
+    expect(clientSecret?.tooltip).toEqual({
+      markdownText: 'Only required for confidential OAuth clients.'
+    });
+    expect(fields.some((field) => field.name === 'authConfig.usePkceClientSecret')).toBe(false);
+    expect(clientAuthMethod?.display?.show?.['authConfig.usePkce']).toEqual(['1', 'true']);
+  });
+
+  test('leaves the condition off plugins that do not offer PKCE', () => {
+    const clientSecret = buildAuthFields().find(
+      (field) => field.name === 'authConfig.clientSecret' && field.display?.show?.authType?.includes(IntegrationAuthType.OAUTH2_CODE)
+    );
+
+    expect(clientSecret?.display?.show).toBeDefined();
+    expect(clientSecret?.display?.show?.['authConfig.usePkce']).toBeUndefined();
+    expect(clientSecret?.rules).toEqual([{ required: true, message: 'Client secret is required' }]);
+  });
+});
+
+describe('PKCE field clearing', () => {
+  test('leaves client credential fields clearable so switching auth type still empties them', () => {
+    // cleanFormData skips any item marked doNotClearOnDependenciesChange, so a
+    // marked field survives every dependency change, including switching the
+    // auth type to Basic or None. That leaked authConfig.clientAuthMethod into
+    // payloads that should not have an authConfig at all. Keeping the value
+    // across PKCE toggles is done with the hidden preservation items below
+    // instead.
+    const fields = buildAuthFields('0.0.16', '0.0.17');
+
+    for (const name of ['authConfig.clientSecret', 'authConfig.clientAuthMethod']) {
+      const items = fields.filter((field) => field.name === name);
+      expect(items.length).toBeGreaterThan(0);
+      for (const item of items) {
+        expect(item.doNotClearOnDependenciesChange).toBeUndefined();
+      }
+    }
+  });
+
+  test('keeps confidential credentials when only public PKCE is supported', () => {
+    const fields = buildAuthFields('0.0.16', '0.0.17');
+
+    for (const name of ['authConfig.clientSecret', 'authConfig.clientAuthMethod']) {
+      const preservation = fields.find(
+        (field) =>
+          field.name === name &&
+          field.startVersion === '0.0.16' &&
+          field.hidden === true &&
+          field.display?.show?.['authConfig.usePkce']?.includes('true')
+      );
+      expect(preservation, name).toBeDefined();
+    }
+  });
+});
+
+describe('PKCE dropdown option', () => {
+  test('labels itself off the ordinary authorization code option', () => {
+    const authTypeField = buildAuthFields('0.0.16').find((field) => field.name === 'authType');
+    const options = 'options' in authTypeField! ? authTypeField.options : [];
+    const pkceOption = options.find((option) => option.key === `${IntegrationAuthType.OAUTH2_CODE}-pkce`);
+
+    // Naming it by hand let it drift to "OAuth2.0" while every sibling said
+    // "OAuth2".
+    expect(pkceOption?.displayName).toBe(`${getDisplayName(IntegrationAuthType.OAUTH2_CODE)} (with PKCE)`);
+  });
+});
+
+describe('OAuth connect button', () => {
+  test('sends the PKCE marker along with the rest of the auth config', () => {
+    // No shipped plugin has both the connect button and PKCE today: the button
+    // needs oauth2BringYourOwn or oauth2SuperblocksClient, and PKCE is REST API
+    // only. Build a plugin with both so the forwarding contract is pinned down
+    // before some plugin ends up in that combination.
+    const fields = authSections({
+      startVersion: '0.0.1',
+      pkceStartVersion: '0.0.16',
+      pluginId: ExtendedIntegrationPluginId.REST_API,
+      pluginName: 'REST API',
+      enabledMethods: {
+        oauth: true,
+        oauth2BringYourOwn: {
+          tokenUrl: 'https://provider.example.com/token',
+          authorizationUrl: 'https://provider.example.com/authorize',
+          revokeTokenUrl: 'https://provider.example.com/revoke',
+          iconUrl: 'https://provider.example.com/icon.png'
+        }
+      }
+    }).flatMap((section) => section.items.flatMap((item) => getRowItemsFromSectionItem(item)));
+
+    const forwardedValues = fields.flatMap((field) =>
+      field.name === 'oauth-connect-button' && field.componentType === FormComponentType.BUTTON ? (field.valuesFromContext ?? []) : []
+    );
+
+    // The button forwards exactly these form values to the connect saga, and
+    // the saga decides whether to run PKCE from the marker. Leave it out and
+    // the saga can never see PKCE as enabled.
+    expect(forwardedValues).toContain('authConfig.usePkce');
+    expect(forwardedValues).not.toContain('authConfig.usePkceClientSecret');
+  });
+});

package/src/plugins/templates/shared/auth.ts

@@ -84,6 +84,26 @@ type OAuth2Config = {
 
 type OAuth2HostedClientConfig = OAuth2Config & { clientId: string };
 
+/**
+ * Every value `authConfig.usePkce` can hold while PKCE is off. `display.show`
+ * matches on the stringified form value, so a spelling missing from this list
+ * hides the field it guards instead of showing it.
+ */
+const PKCE_OFF_MARKERS = ['', '0', 'false', 'null', 'undefined'];
+const PKCE_ON_MARKERS = ['1', 'true'];
+const CLIENT_AUTH_METHOD_OPTIONS: DropdownOption[] = [
+  {
+    displayName: 'Send client credentials in body',
+    key: ClientAuthMethod.POST,
+    value: ClientAuthMethod.POST
+  },
+  {
+    displayName: 'Send as Basic Auth header',
+    key: ClientAuthMethod.BASIC,
+    value: ClientAuthMethod.BASIC
+  }
+];
+
 const AUTH_METHODS_TO_TYPES = {
   basic: IntegrationAuthType.BASIC,
   firebase: IntegrationAuthType.FIREBASE,
@@ -103,6 +123,8 @@ const AUTH_METHODS_TO_TYPES = {
 
 export const authSections = ({
   startVersion,
+  pkceStartVersion,
+  confidentialPkceStartVersion,
   endVersion,
   pluginId,
   pluginName,
@@ -115,6 +137,8 @@ export const authSections = ({
   prependItems = []
 }: {
   startVersion: string;
+  pkceStartVersion?: string;
+  confidentialPkceStartVersion?: string;
   endVersion?: string;
   pluginId: ExtendedIntegrationPluginId;
   pluginName: string;
@@ -171,10 +195,11 @@ export const authSections = ({
         {
           name: isProto ? 'connection.auth.method.case' : 'authType',
           label: 'Authentication',
+          secondaryName: pkceStartVersion ? 'authConfig.usePkce' : undefined,
           startVersion: startVersion,
           componentType: FormComponentType.DROPDOWN,
           initialValue: authTypeInitialValue,
-          options: authTypeOptions({ enabledMethods, allowNone, isProto, apiKeyFormDisplayName }),
+          options: authTypeOptions({ enabledMethods, allowNone, apiKeyFormDisplayName, pkceStartVersion }),
           disabled: !allowNone && enabledMethodKeys.length === 1
         }
       ],
@@ -789,6 +814,24 @@ export const authSections = ({
             }
           }
         } as FormItem,
+        ...(confidentialPkceStartVersion
+          ? [
+              {
+                ...BASE_CLIENT_SECRET,
+                startVersion: confidentialPkceStartVersion,
+                rules: [{ required: false }],
+                tooltip: {
+                  markdownText: 'Only required for confidential OAuth clients.'
+                },
+                display: {
+                  show: {
+                    authType: [IntegrationAuthType.OAUTH2_CODE],
+                    'authConfig.usePkce': PKCE_ON_MARKERS
+                  }
+                }
+              } as FormItem
+            ]
+          : []),
         {
           ...BASE_CLIENT_ID,
           startVersion,
@@ -804,10 +847,29 @@ export const authSections = ({
           startVersion,
           display: {
             show: {
-              authType: [IntegrationAuthType.OAUTH2_PASSWORD, IntegrationAuthType.OAUTH2_CLIENT_CREDS, IntegrationAuthType.OAUTH2_CODE]
+              authType: [IntegrationAuthType.OAUTH2_PASSWORD, IntegrationAuthType.OAUTH2_CLIENT_CREDS, IntegrationAuthType.OAUTH2_CODE],
+              ...(pkceStartVersion ? { 'authConfig.usePkce': PKCE_OFF_MARKERS } : {})
             }
           }
         } as FormItem,
+        ...(pkceStartVersion
+          ? [
+              {
+                // Keep a confidential client's stored secret if the current
+                // agent only supports public PKCE.
+                ...BASE_CLIENT_SECRET,
+                startVersion: pkceStartVersion,
+                hidden: true,
+                rules: [{ required: false }],
+                display: {
+                  show: {
+                    authType: [IntegrationAuthType.OAUTH2_CODE],
+                    'authConfig.usePkce': PKCE_ON_MARKERS
+                  }
+                }
+              } as FormItem
+            ]
+          : []),
         {
           ...BASE_CLIENT_SECRET,
           startVersion,
@@ -883,24 +945,69 @@ export const authSections = ({
           startVersion: startVersion,
           componentType: FormComponentType.DROPDOWN,
           initialValue: ClientAuthMethod.POST,
-          options: [
-            {
-              displayName: 'Send client credentials in body',
-              key: ClientAuthMethod.POST,
-              value: ClientAuthMethod.POST
-            },
-            {
-              displayName: 'Send as Basic Auth header',
-              key: ClientAuthMethod.BASIC,
-              value: ClientAuthMethod.BASIC
-            }
-          ],
+          options: CLIENT_AUTH_METHOD_OPTIONS,
           display: {
             show: {
-              authType: [IntegrationAuthType.OAUTH2_CODE]
+              authType: [IntegrationAuthType.OAUTH2_CODE],
+              ...(pkceStartVersion ? { 'authConfig.usePkce': PKCE_OFF_MARKERS } : {})
             }
           }
         },
+        ...(confidentialPkceStartVersion
+          ? [
+              {
+                label: 'Client authentication',
+                name: 'authConfig.clientAuthMethod',
+                startVersion: confidentialPkceStartVersion,
+                componentType: FormComponentType.DROPDOWN,
+                initialValue: ClientAuthMethod.POST,
+                options: CLIENT_AUTH_METHOD_OPTIONS,
+                display: {
+                  show: {
+                    authType: [IntegrationAuthType.OAUTH2_CODE],
+                    'authConfig.usePkce': PKCE_ON_MARKERS
+                  }
+                }
+              } satisfies FormItem
+            ]
+          : []),
+        ...(pkceStartVersion
+          ? [
+              {
+                // Keep the stored method if the current agent only supports
+                // public PKCE. No initial value avoids writing a default into
+                // configs that never chose one.
+                label: 'Client authentication',
+                name: 'authConfig.clientAuthMethod',
+                startVersion: pkceStartVersion,
+                componentType: FormComponentType.DROPDOWN,
+                hidden: true,
+                options: CLIENT_AUTH_METHOD_OPTIONS,
+                display: {
+                  show: {
+                    authType: [IntegrationAuthType.OAUTH2_CODE],
+                    'authConfig.usePkce': PKCE_ON_MARKERS
+                  }
+                }
+              } satisfies FormItem
+            ]
+          : []),
+        ...(pkceStartVersion
+          ? [
+              {
+                label: '',
+                name: 'authConfig.usePkce',
+                startVersion: pkceStartVersion,
+                componentType: FormComponentType.CHECKBOX,
+                hidden: true,
+                display: {
+                  show: {
+                    authType: [IntegrationAuthType.OAUTH2_CODE]
+                  }
+                }
+              } satisfies FormItem
+            ]
+          : []),
         {
           label: 'Send state parameter',
           name: 'authConfig.sendOAuthState',
@@ -1361,6 +1468,7 @@ export const authSections = ({
             'authConfig.authorizationUrl',
             'authConfig.refreshTokenFromServer',
             'authConfig.clientAuthMethod',
+            'authConfig.usePkce',
             'dynamicWorkflowConfiguration.enabled',
             'dynamicWorkflowConfiguration.workflowId'
           ],
@@ -1467,13 +1575,13 @@ function apiKeyAuthOptions(pluginId: ExtendedIntegrationPluginId): DropdownOptio
 function authTypeOptions({
   enabledMethods,
   allowNone = true,
-  isProto = false,
-  apiKeyFormDisplayName
+  apiKeyFormDisplayName,
+  pkceStartVersion
 }: {
   enabledMethods: AuthMethods;
   allowNone?: boolean;
-  isProto?: boolean;
   apiKeyFormDisplayName?: string;
+  pkceStartVersion?: string;
 }): DropdownOption[] {
   const options: DropdownOption[] = allowNone
     ? [
@@ -1537,6 +1645,15 @@ function authTypeOptions({
       value: IntegrationAuthType.OAUTH2_CODE,
       key: IntegrationAuthType.OAUTH2_CODE
     });
+    if (pkceStartVersion) {
+      options.push({
+        displayName: `${getDisplayName(IntegrationAuthType.OAUTH2_CODE)} (with PKCE)`,
+        value: IntegrationAuthType.OAUTH2_CODE,
+        key: `${IntegrationAuthType.OAUTH2_CODE}-pkce`,
+        secondaryValue: true,
+        startVersion: pkceStartVersion
+      });
+    }
     options.push({
       displayName: getDisplayName(IntegrationAuthType.OAUTH2_IMPLICIT),
       value: IntegrationAuthType.OAUTH2_IMPLICIT,

package/src/plugins/templates/shared/restapiintegration.ts

@@ -8,5 +8,7 @@ export const RestApiIntegrationPluginVersions = {
   V7: '0.0.7',
   V8: '0.0.8',
   V13: '0.0.13',
-  V14: '0.0.14'
+  V14: '0.0.14',
+  V16: '0.0.16',
+  V17: '0.0.17'
 };

package/src/socket/dist-entry.test.ts

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Gateway (and the CLI esbuild bundle Cursor MCP loads) resolve
+ * `@superblocksteam/shared` to this package's Node entry (`dist/`), not
+ * `src/`. A stale dist that predates SocketHeartbeat makes Cursor MCP crash
+ * with: "does not provide an export named 'SocketHeartbeat'". Rebuild shared
+ * before Gateway and the CLI after changing this export.
+ */
+describe('Node package entry', () => {
+  it('exports SocketHeartbeat as a named binding Gateway can import', async () => {
+    const require = createRequire(path.join(process.cwd(), 'package.json'));
+    let entry: string;
+    try {
+      entry = require.resolve('@superblocksteam/shared');
+    } catch {
+      return;
+    }
+    if (!existsSync(entry)) {
+      return;
+    }
+    const shared = await import(entry);
+    expect(typeof shared.SocketHeartbeat).toBe('function');
+  });
+});