@superblocksteam/shared 0.9615.3 → 0.9616.0

package/src/database-lifecycle/index.ts

@@ -44,6 +44,7 @@ export const LIFECYCLE_OPERATIONS = [
   'complete_import_upload',
   'prepare_import_prefix_upload',
   'inspect_import_prefix',
+  'restore_import_data',
   'describe_schema'
 ] as const;
 export const GENERIC_IMPORT_OPERATIONS = ['prepare_import_upload', 'complete_import_upload'] as const;
@@ -53,7 +54,10 @@ export const GENERIC_IMPORT_OPERATIONS = ['prepare_import_upload', 'complete_imp
 export const POOL_SCOPED_LIFECYCLE_OPERATIONS = ['ensure_physical_database_instance', 'retire_physical_database_instance'] as const;
 export const DATABASE_LIFECYCLE_MANAGED_BY = 'database_lifecycle';
 export const NATIVE_DB_AUTH_DESCRIPTOR_VERSION = 3 as const;
-export const NATIVE_DB_CONNECTOR_ROLE_NAME_PREFIX = 'superblocks-native-db-connector';
+// Cloud-prem connector roles are named superblocks-app-db-connector-<agent>
+// (terraform-aws-superblocks modules/app-db-prereqs). User-supplied integrations
+// may not use that prefix.
+export const APP_DB_CONNECTOR_ROLE_NAME_PREFIX = 'superblocks-app-db-connector';
 export const NATIVE_DB_IAM_AUTH_MODE = 'aws_iam_role' as const;
 export const NATIVE_DB_IDENTIFIER_HASH_DOMAIN = 'superblocks-native-db:v1';
 export const DATABASE_LIFECYCLE_CAPABILITY_MANAGED_IAM_V1 = 'managed-IAM-v1';
@@ -224,6 +228,8 @@ export type LifecycleImportPayload = {
   kind?: LifecycleImportKind;
   objectKey?: string;
   parts?: LifecycleImportPart[];
+  prefixChecksumSha256?: string;
+  prefixSizeBytes?: number;
   partSizeBytes?: number;
   sha256?: string;
   sizeBytes?: number;

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

@@ -8,7 +8,7 @@ import {
   getRowItemsFromSectionItem,
   IntegrationAuthType
 } from '../../../types/index.js';
-import { authSections } from './auth.js';
+import { authSections, ClientAuthMethod } from './auth.js';
 
 const buildAuthFields = (pkceStartVersion?: string, confidentialPkceStartVersion?: string): FormItem[] =>
   authSections({
@@ -127,6 +127,25 @@ describe('PKCE dropdown option', () => {
   });
 });
 
+describe('client credentials client authentication', () => {
+  test('offers a Basic-vs-body dropdown for the client credentials grant, defaulting to the Basic header', () => {
+    const clientAuthMethod = buildAuthFields().find(
+      (field) =>
+        field.name === 'authConfig.clientAuthMethod' && field.display?.show?.authType?.includes(IntegrationAuthType.OAUTH2_CLIENT_CREDS)
+    );
+
+    expect(clientAuthMethod?.componentType).toBe(FormComponentType.DROPDOWN);
+    // Existing client credentials integrations authenticate with the Basic
+    // header, so the default must stay Basic to leave them unchanged.
+    expect(clientAuthMethod?.initialValue).toBe(ClientAuthMethod.BASIC);
+    // The client credentials grant has no PKCE variant, so the dropdown must
+    // not leak into the authorization code sections.
+    expect(clientAuthMethod?.display?.show?.authType).toEqual([IntegrationAuthType.OAUTH2_CLIENT_CREDS]);
+    const options = clientAuthMethod && 'options' in clientAuthMethod ? clientAuthMethod.options : [];
+    expect(options.map((option) => option.value)).toEqual(expect.arrayContaining([ClientAuthMethod.BASIC, ClientAuthMethod.POST]));
+  });
+});
+
 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
@@ -160,3 +179,102 @@ describe('OAuth connect button', () => {
     expect(forwardedValues).not.toContain('authConfig.usePkceClientSecret');
   });
 });
+
+describe('OAuth client credentials method', () => {
+  const buildFields = (enabledMethods: Parameters<typeof authSections>[0]['enabledMethods']): FormItem[] =>
+    authSections({
+      startVersion: '0.0.1',
+      pluginId: ExtendedIntegrationPluginId.REST_API,
+      pluginName: 'Provider',
+      enabledMethods
+    }).flatMap((section) => section.items.flatMap((item) => getRowItemsFromSectionItem(item)));
+
+  test('keeps the token URL template-owned and offers no Connect', () => {
+    // The orchestrator posts the client secret to whatever tokenUrl is stored, so the value has
+    // to come from the template rather than the form, and there is no user to send anywhere.
+    const fields = buildFields({
+      oauth2ClientCredentials: { tokenUrl: 'https://provider.example.com/token', startVersion: '0.0.18' }
+    });
+
+    expect(fields).toContainEqual(
+      expect.objectContaining({ name: 'authConfig.tokenUrl', hidden: true, initialValue: 'https://provider.example.com/token' })
+    );
+    expect(fields.filter((field) => field.componentType === FormComponentType.BUTTON)).toEqual([]);
+  });
+
+  test('withholds the method and every field of it from agents older than its start version', () => {
+    // An agent below the start version mints the token but never puts it on the request, so the
+    // option must not be selectable there and nothing of the method may render; the form refuses
+    // a save whose selected option the agent does not support.
+    const fields = buildFields({ oauth2ClientCredentials: { tokenUrl: 'https://provider.example.com/token', startVersion: '0.0.18' } });
+    const authType = fields.find((field) => field.name === 'authType');
+
+    expect(authType).toEqual(
+      expect.objectContaining({
+        options: expect.arrayContaining([
+          expect.objectContaining({ value: IntegrationAuthType.OAUTH2_CLIENT_CREDS, startVersion: '0.0.18' })
+        ])
+      })
+    );
+    const methodFields = fields.filter(
+      (field) =>
+        field.display?.show?.authType?.includes(IntegrationAuthType.OAUTH2_CLIENT_CREDS) || field.name === 'authConfig.sendBearerHeader'
+    );
+    expect(methodFields.length).toBeGreaterThan(0);
+    expect(methodFields.every((field) => field.startVersion === '0.0.18')).toBe(true);
+  });
+
+  test('keys its token by configuration from the form onward', () => {
+    // A pre-save Test Connection sends the form's auth config straight to the orchestrator, before
+    // the server can pin anything. Without a datasource scope in it, the token lands under the
+    // client-id key, which every tenant that chose the same identifier shares.
+    const fields = buildFields({ oauth2ClientCredentials: { tokenUrl: 'https://provider.example.com/token', startVersion: '0.0.18' } });
+    const tokenScope = fields.find((field) => field.name === 'authConfig.tokenScope');
+
+    expect(tokenScope).toEqual(
+      expect.objectContaining({
+        hidden: true,
+        initialValue: 'datasource',
+        display: { show: { authType: [IntegrationAuthType.OAUTH2_CLIENT_CREDS] } }
+      })
+    );
+  });
+
+  test('marks the token for the Authorization header, which the legacy oauth method never does', () => {
+    // The orchestrator sees a native OpenAPI step as a plain REST API step, so the template has
+    // to say which of the two it is. It reads the marker as a boolean; a string 'true' is unset.
+    expect(
+      buildFields({ oauth2ClientCredentials: { tokenUrl: 'https://provider.example.com/token', startVersion: '0.0.18' } })
+    ).toContainEqual(expect.objectContaining({ name: 'authConfig.sendBearerHeader', hidden: true, initialValue: true }));
+    expect(buildFields({ oauth: true }).map((field) => field.name)).not.toContain('authConfig.sendBearerHeader');
+  });
+
+  const authorizationCodeMethod = {
+    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'
+  };
+
+  test.each([
+    ['oauth2BringYourOwn', { oauth2BringYourOwn: authorizationCodeMethod }],
+    ['oauth2SuperblocksClient', { oauth2SuperblocksClient: { ...authorizationCodeMethod, clientId: 'hosted-client' } }]
+  ])('refuses a template whose %s method disagrees with it on the token URL', (_name, authorizationCode) => {
+    // Every OAuth method stores its endpoint in the same field. Let them differ and whichever
+    // hidden item the form reads last decides where the client secret is sent.
+    expect(() =>
+      buildFields({
+        ...authorizationCode,
+        oauth2ClientCredentials: { tokenUrl: 'https://provider.example.com/other-token', startVersion: '0.0.18' }
+      })
+    ).toThrow('different token URLs');
+  });
+
+  test('refuses a template that also offers the grant through the legacy oauth method', () => {
+    // Both methods put the same auth type in the dropdown and gate the same fields on it, so the
+    // form would show two of everything.
+    expect(() =>
+      buildFields({ oauth: true, oauth2ClientCredentials: { tokenUrl: 'https://provider.example.com/token', startVersion: '0.0.18' } })
+    ).toThrow('twice');
+  });
+});

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

@@ -12,6 +12,7 @@ import {
   IntegrationAuthType,
   NewAuthType,
   OAUTH_CALLBACK_PATH,
+  RestApiFields,
   TokenScope
 } from '../../../types/index.js';
 import { RestApiIntegrationPluginVersions } from './restapiintegration.js';
@@ -54,6 +55,7 @@ export type AuthMethods = {
   tokenPrefixed?: boolean | { prefix: string };
   oauth2BringYourOwn?: OAuth2Config;
   oauth2SuperblocksClient?: OAuth2HostedClientConfig;
+  oauth2ClientCredentials?: OAuth2ClientCredentialsConfig;
   oauth2TokenExchange?: boolean;
   // controls proto defined auth components
   passwordGrantFlow?: boolean;
@@ -84,6 +86,21 @@ type OAuth2Config = {
 
 type OAuth2HostedClientConfig = OAuth2Config & { clientId: string };
 
+/**
+ * The client credentials grant needs nothing but a token endpoint: there is no authorization
+ * step, no user, nothing to revoke and no Connect button. The orchestrator mints the token from
+ * the client's own secret at execution time, so a template on this method serves executions that
+ * run with nobody signed in, such as workflows and scheduled jobs.
+ */
+type OAuth2ClientCredentialsConfig = {
+  tokenUrl: string;
+  defaultScope?: string;
+  // The first plugin version whose agent puts the minted token on the Authorization header for
+  // this method. Below it the option and its fields are hidden and a save is refused, because an
+  // older agent would mint the token and then send the request without it.
+  startVersion: 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
@@ -114,6 +131,7 @@ const AUTH_METHODS_TO_TYPES = {
   tokenPrefixed: IntegrationAuthType.TOKEN_PREFIXED,
   oauth2BringYourOwn: IntegrationAuthType.OAUTH2_CODE,
   oauth2SuperblocksClient: IntegrationAuthType.OAUTH2_CODE,
+  oauth2ClientCredentials: IntegrationAuthType.OAUTH2_CLIENT_CREDS,
   // those matches proto types auth.method.case
   passwordGrantFlow: NewAuthType.OAUTH2_PASSWORD_GRANT_FLOW,
   authorizationCodeFlow: NewAuthType.OAUTH2_AUTH_CODE_FLOW,
@@ -134,7 +152,8 @@ export const authSections = ({
   fieldNamesToHide = [],
   isProto = false,
   // allow caller to provide optional customized auth items
-  prependItems = []
+  prependItems = [],
+  authOptionsLdFlag
 }: {
   startVersion: string;
   pkceStartVersion?: string;
@@ -147,6 +166,8 @@ export const authSections = ({
   allowNone?: boolean;
   fieldNamesToHide?: string[];
   isProto?: boolean;
+  // Rollout gate on the Authentication dropdown: see DropdownFormItem.optionsLdFlag.
+  authOptionsLdFlag?: { ldFlag: string; keep: string[] };
   prependItems?: FormItem[];
 }): FormSection[] => {
   // Extract display name override before filtering methods
@@ -200,6 +221,7 @@ export const authSections = ({
           componentType: FormComponentType.DROPDOWN,
           initialValue: authTypeInitialValue,
           options: authTypeOptions({ enabledMethods, allowNone, apiKeyFormDisplayName, pkceStartVersion }),
+          ...(authOptionsLdFlag ? { optionsLdFlag: authOptionsLdFlag } : {}),
           disabled: !allowNone && enabledMethodKeys.length === 1
         }
       ],
@@ -924,6 +946,21 @@ export const authSections = ({
             }
           }
         } as FormItem,
+        {
+          label: 'Client authentication',
+          name: 'authConfig.clientAuthMethod',
+          startVersion: startVersion,
+          componentType: FormComponentType.DROPDOWN,
+          // Existing client credentials integrations authenticate with the
+          // Basic header, so the default stays Basic to leave them unchanged.
+          initialValue: ClientAuthMethod.BASIC,
+          options: CLIENT_AUTH_METHOD_OPTIONS,
+          display: {
+            show: {
+              authType: [IntegrationAuthType.OAUTH2_CLIENT_CREDS]
+            }
+          }
+        },
         {
           label: 'Share username/password across all users',
           name: 'authConfig.useFixedPasswordCreds',
@@ -1268,6 +1305,119 @@ export const authSections = ({
       fieldNamesToHide
     );
   }
+  if (enabledMethods.oauth2ClientCredentials) {
+    // The legacy `oauth` method already offers this grant, with a user-entered token URL, under
+    // the same auth type. Offering both would put two options with one key in the dropdown and
+    // two of every field behind it.
+    if (enabledMethods.oauth) {
+      throw new Error(`Plugin ${pluginId} offers the client credentials grant twice`);
+    }
+    // Every OAuth method stores its endpoint in the same field, so a template that offers more
+    // than one has to mean the same endpoint by it. Disagreeing would leave whichever hidden item
+    // the form reads last in charge of where the client secret is sent.
+    const otherTokenUrls = [enabledMethods.oauth2BringYourOwn?.tokenUrl, enabledMethods.oauth2SuperblocksClient?.tokenUrl].filter(
+      (url): url is string => url !== undefined
+    );
+    if (otherTokenUrls.some((url) => url !== enabledMethods.oauth2ClientCredentials?.tokenUrl)) {
+      throw new Error(`Plugin ${pluginId} gives its OAuth methods different token URLs`);
+    }
+    const clientCredentialsStartVersion = enabledMethods.oauth2ClientCredentials.startVersion;
+    addField(
+      authFields,
+      [
+        {
+          label: 'Access token URL',
+          name: 'authConfig.tokenUrl',
+          startVersion: clientCredentialsStartVersion,
+          componentType: FormComponentType.INPUT_TEXT,
+          hidden: true,
+          initialValue: enabledMethods.oauth2ClientCredentials.tokenUrl
+        },
+        {
+          // A native OpenAPI step reaches the orchestrator as a plain REST API step with no plugin
+          // id, so this is how the template says the token belongs on the Authorization header.
+          // The generic REST API integration's legacy `oauth` method leaves it unset: its users
+          // place `{{ oauth.token }}` in a header of their own choosing.
+          label: 'Send bearer header',
+          name: 'authConfig.sendBearerHeader',
+          startVersion: clientCredentialsStartVersion,
+          componentType: FormComponentType.CHECKBOX,
+          hidden: true,
+          initialValue: true
+        },
+        {
+          // The shared token cache keys a client-credentials token by configuration only under this
+          // scope; a client-id key would be shared by every tenant that chose the same identifier.
+          // The server pins the stored value as well, but a pre-save Test Connection sends the
+          // form's values straight to the orchestrator, so the form has to carry it too.
+          label: 'Share access token across all users',
+          name: 'authConfig.tokenScope',
+          startVersion: clientCredentialsStartVersion,
+          componentType: FormComponentType.INPUT_TEXT,
+          hidden: true,
+          initialValue: TokenScope.DATASOURCE,
+          display: {
+            show: {
+              authType: [IntegrationAuthType.OAUTH2_CLIENT_CREDS]
+            }
+          }
+        },
+        {
+          label: 'Client ID',
+          name: 'authConfig.clientId',
+          startVersion: clientCredentialsStartVersion,
+          componentType: FormComponentType.DYNAMIC_INPUT_TEXT,
+          placeholder: `Client ID`,
+          rules: [{ required: true, message: 'Client ID is required' }],
+          tooltip: {
+            markdownText: `The client identifier issued to the client during the application registration process.`
+          },
+          singleLine: true,
+          display: {
+            show: {
+              authType: [IntegrationAuthType.OAUTH2_CLIENT_CREDS]
+            }
+          }
+        },
+        {
+          label: 'Client secret',
+          name: 'authConfig.clientSecret',
+          startVersion: clientCredentialsStartVersion,
+          componentType: FormComponentType.INPUT_TEXT,
+          rules: [{ required: true, message: 'Client secret is required' }],
+          placeholder: `Client Secret`,
+          dataType: InputDataType.PASSWORD,
+          tooltip: {
+            markdownText: `The client secret issued to the client during the application registration process. This grant is for confidential clients only: the token is minted from the secret alone, with no user involved.`
+          },
+          singleLine: false,
+          display: {
+            show: {
+              authType: [IntegrationAuthType.OAUTH2_CLIENT_CREDS]
+            }
+          }
+        },
+        {
+          label: 'Scope',
+          name: 'authConfig.scope',
+          startVersion: clientCredentialsStartVersion,
+          componentType: FormComponentType.DYNAMIC_INPUT_TEXT,
+          placeholder: `e.g. read write`,
+          tooltip: {
+            markdownText: `The scope of access request. It may have multiple space-separated values.`
+          },
+          singleLine: true,
+          initialValue: enabledMethods.oauth2ClientCredentials.defaultScope,
+          display: {
+            show: {
+              authType: [IntegrationAuthType.OAUTH2_CLIENT_CREDS]
+            }
+          }
+        }
+      ],
+      fieldNamesToHide
+    );
+  }
   if (enabledMethods.oauth2SuperblocksClient) {
     addField(
       authFields,
@@ -1469,6 +1619,9 @@ export const authSections = ({
             'authConfig.refreshTokenFromServer',
             'authConfig.clientAuthMethod',
             'authConfig.usePkce',
+            // Resolves the tenant placeholder in the URLs above for providers that host each
+            // customer on their own subdomain.
+            RestApiFields.OPENAPI_TENANT_NAME,
             'dynamicWorkflowConfiguration.enabled',
             'dynamicWorkflowConfiguration.workflowId'
           ],
@@ -1500,7 +1653,9 @@ export const authSections = ({
             'authConfig.tokenUrl',
             'authConfig.authorizationUrl',
             'authConfig.refreshTokenFromServer',
-            'authConfig.revokeTokenUrl'
+            'authConfig.revokeTokenUrl',
+            // See the connect button.
+            RestApiFields.OPENAPI_TENANT_NAME
           ],
           display: {
             show: {
@@ -1683,6 +1838,14 @@ function authTypeOptions({
       key: IntegrationAuthType.OAUTH2_CODE
     });
   }
+  if (enabledMethods.oauth2ClientCredentials) {
+    options.push({
+      displayName: `OAuth2.0 - Client Credentials`,
+      value: IntegrationAuthType.OAUTH2_CLIENT_CREDS,
+      key: IntegrationAuthType.OAUTH2_CLIENT_CREDS,
+      startVersion: enabledMethods.oauth2ClientCredentials.startVersion
+    });
+  }
 
   // following is only used by proto based plugins
   // the keys are proto oneof case options

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

@@ -41,7 +41,9 @@ export const getNativeOpenApiPlugin = ({
   openApiSpecURL,
   headers,
   tenantInput,
-  isStreamable
+  isStreamable,
+  defaultAuthMethod,
+  authOptionsLdFlag
 }: {
   id: ExtendedIntegrationPluginId;
   name: string;
@@ -53,6 +55,12 @@ export const getNativeOpenApiPlugin = ({
   headers?: KVPair[];
   tenantInput?: TenantInput;
   isStreamable?: boolean;
+  // Which of `authMethods` a new integration starts on. Without it the initial value falls to
+  // whichever key happens to come first in the `authMethods` literal, which is not something a
+  // template should depend on.
+  defaultAuthMethod?: keyof AuthMethods;
+  // Rollout gate on the Authentication dropdown: see DropdownFormItem.optionsLdFlag.
+  authOptionsLdFlag?: { ldFlag: string; keep: string[] };
 }): Plugin => {
   if (authMethods.oauth2BringYourOwn) {
     oauth2BringYourOwnPluginIds.add(id);
@@ -89,7 +97,9 @@ export const getNativeOpenApiPlugin = ({
       // more.
       startVersion: RestApiIntegrationPluginVersions.V1, // TODO: Should really be a REST version bump.
       componentType: FormComponentType.DYNAMIC_INPUT_TEXT,
-      rules: [{ required: true, message: '' }]
+      // The message is what the form shows when Create is blocked on this field. Left empty, the
+      // save fails with nothing on screen; a method with no Connect step hits this first.
+      rules: [{ required: true, message: `${tenantInput?.label ?? 'Tenant'} is required` }]
     });
   }
 
@@ -128,7 +138,9 @@ export const getNativeOpenApiPlugin = ({
           pluginId: id,
           pluginName: name,
           enabledMethods: authMethods,
-          allowNone: false
+          defaultMethod: defaultAuthMethod,
+          allowNone: false,
+          authOptionsLdFlag
         })
       ]
     },

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

@@ -10,5 +10,7 @@ export const RestApiIntegrationPluginVersions = {
   V13: '0.0.13',
   V14: '0.0.14',
   V16: '0.0.16',
-  V17: '0.0.17'
+  V17: '0.0.17',
+  // First agent that puts a client-credentials token on the Authorization header itself.
+  V18: '0.0.18'
 };

package/src/plugins/templates/zendesk.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+
+import { getRowItemsFromSectionItem, IntegrationAuthType, resolveOpenApiTenantUrl, RestApiFields } from '../../types/index.js';
+import { RestApiIntegrationPluginVersions } from './shared/index.js';
+import { ZENDESK_OAUTH_ROLLOUT_FLAG, ZendeskPlugin } from './zendesk.js';
+
+const datasourceItems = ZendeskPlugin.datasourceTemplate?.sections.flatMap((section) => section.items.flatMap(getRowItemsFromSectionItem));
+
+const findDatasourceItem = (name: string) => datasourceItems?.find((item) => item.name === name);
+
+const resolveForTenant = (name: string) => resolveOpenApiTenantUrl(findDatasourceItem(name)?.initialValue as string, 'acme');
+
+describe('Zendesk datasource template', () => {
+  it('offers OAuth without withdrawing basic auth', () => {
+    // Zendesk does not switch API tokens off until 2027-04-30, so integrations already
+    // authenticating with one have to keep working alongside the new method.
+    expect(findDatasourceItem('authType')).toEqual(
+      expect.objectContaining({
+        options: expect.arrayContaining([
+          expect.objectContaining({ value: IntegrationAuthType.BASIC }),
+          expect.objectContaining({ value: IntegrationAuthType.OAUTH2_CODE })
+        ])
+      })
+    );
+  });
+
+  it('gates every method but the API token behind the rollout flag, as an allowlist', () => {
+    // Off, the form offers only basic auth and starts there; an auth method added later is
+    // hidden by construction rather than by remembering to list it.
+    expect(ZENDESK_OAUTH_ROLLOUT_FLAG).toBe('integrations.zendesk.oauth');
+    expect(findDatasourceItem('authType')).toEqual(
+      expect.objectContaining({ optionsLdFlag: { ldFlag: ZENDESK_OAUTH_ROLLOUT_FLAG, keep: [IntegrationAuthType.BASIC] } })
+    );
+  });
+
+  it('offers client credentials with only the inputs that grant needs', () => {
+    // Workflows and scheduled jobs run with nobody signed in, so they cannot click Connect. The
+    // grant is minted from the client's own secret, so the form asks for the client, its secret
+    // and a scope, and nothing that belongs to the authorization-code flow: no Connect or Revoke
+    // button, no callback URL, no token-sharing choice.
+    expect(findDatasourceItem('authType')).toEqual(
+      expect.objectContaining({
+        options: expect.arrayContaining([
+          // Gated on the first agent that puts the token on the Authorization header itself.
+          expect.objectContaining({ value: IntegrationAuthType.OAUTH2_CLIENT_CREDS, startVersion: RestApiIntegrationPluginVersions.V18 })
+        ])
+      })
+    );
+    const clientCredentialsItems = datasourceItems
+      ?.filter((item) => !item.hidden && item.display?.show?.authType?.includes(IntegrationAuthType.OAUTH2_CLIENT_CREDS))
+      .map((item) => item.name);
+    expect(clientCredentialsItems).toEqual(['authConfig.clientId', 'authConfig.clientSecret', 'authConfig.scope']);
+  });
+
+  it('tells the user when the tenant is missing', () => {
+    // Every OAuth URL hangs off the tenant, so a save without one has to fail, and the form shows
+    // the rule's message as the reason. With client credentials there is no Connect step to catch
+    // the omission earlier, so an empty message leaves Create failing with nothing on screen.
+    expect(findDatasourceItem(RestApiFields.OPENAPI_TENANT_NAME)).toEqual(
+      expect.objectContaining({ rules: [{ required: true, message: 'Zendesk tenant is required' }] })
+    );
+  });
+
+  it('starts a new integration on OAuth', () => {
+    // Zendesk stops issuing new API tokens on 2026-10-27, so basic auth is not a usable
+    // starting point for anyone configuring Zendesk from here on.
+    expect(findDatasourceItem('authType')?.initialValue).toBe(IntegrationAuthType.OAUTH2_CODE);
+  });
+
+  it('sends the tenant with the events that act on those endpoints', () => {
+    // The connect and revoke buttons carry a declared list of form values into their events, and
+    // the handlers resolve the placeholder from it. Without the tenant in that list every URL
+    // above reaches its handler unresolved.
+    const buttonNames = ['oauth-connect-button', 'oauth-revoke-shared-tokens-button'];
+
+    for (const name of buttonNames) {
+      expect(findDatasourceItem(name), name).toEqual(
+        expect.objectContaining({
+          valuesFromContext: expect.arrayContaining([RestApiFields.OPENAPI_TENANT_NAME])
+        })
+      );
+    }
+  });
+
+  it('points its OAuth endpoints at the configured tenant', () => {
+    // Every URL is per-subdomain, and the grant endpoint (/oauth/tokens) is a different path
+    // from the token management API (/api/v2/oauth/tokens) that revocation uses.
+    expect({
+      authorizationUrl: resolveForTenant('authConfig.authorizationUrl'),
+      tokenUrl: resolveForTenant('authConfig.tokenUrl'),
+      revokeTokenUrl: resolveForTenant('authConfig.revokeTokenUrl')
+    }).toEqual({
+      authorizationUrl: 'https://acme.zendesk.com/oauth/authorizations/new',
+      tokenUrl: 'https://acme.zendesk.com/oauth/tokens',
+      revokeTokenUrl: 'https://acme.zendesk.com/api/v2/oauth/tokens/current'
+    });
+  });
+});

package/src/plugins/templates/zendesk.ts

@@ -1,13 +1,53 @@
-import { ExtendedIntegrationPluginId, Plugin, SUPERBLOCKS_OPENAPI_TENANT_KEYWORD } from '../../types/index.js';
-import { getNativeOpenApiPlugin } from './shared/index.js';
+import { ExtendedIntegrationPluginId, IntegrationAuthType, Plugin, SUPERBLOCKS_OPENAPI_TENANT_KEYWORD } from '../../types/index.js';
+import { PUBLIC_INTEGRATIONS_LOGO_URL } from './constants.js';
+import { ClientAuthMethod, getNativeOpenApiPlugin, RestApiIntegrationPluginVersions } from './shared/index.js';
+
+// Zendesk gives every account its own subdomain, and its OAuth endpoints live under that
+// subdomain rather than a shared host. These URLs therefore carry the tenant placeholder: the
+// server resolves them into the stored configuration on save, and the browser resolves them
+// for a Connect that happens before the first save. Every other OAuth template here can
+// hardcode its endpoints.
+const ZENDESK_HOST = `https://${SUPERBLOCKS_OPENAPI_TENANT_KEYWORD}.zendesk.com`;
+
+// Kill switch for the OAuth rollout, read by the integration form only. Off, the Authentication
+// dropdown offers just the API token method and a new integration starts on it; execution never
+// consults it, so an integration already connected with OAuth keeps working. The UI flag table
+// (Flags.ts, INTEGRATIONS_ZENDESK_OAUTH) carries the same key.
+export const ZENDESK_OAUTH_ROLLOUT_FLAG = 'integrations.zendesk.oauth';
 
 export const ZendeskPlugin: Plugin = getNativeOpenApiPlugin({
   name: 'Zendesk',
   id: ExtendedIntegrationPluginId.ZENDESK,
   authMethods: {
-    basic: true
+    // Retained because Zendesk does not switch off API tokens until 2027-04-30 and existing
+    // integrations authenticate with one. New integrations default to OAuth, since Zendesk
+    // stops issuing API tokens well before then.
+    basic: true,
+    oauth2BringYourOwn: {
+      authorizationUrl: `${ZENDESK_HOST}/oauth/authorizations/new`,
+      tokenUrl: `${ZENDESK_HOST}/oauth/tokens`,
+      revokeTokenUrl: `${ZENDESK_HOST}/api/v2/oauth/tokens/current`,
+      // Zendesk reads client_id/client_secret from the token request body.
+      clientAuthMethod: ClientAuthMethod.POST,
+      iconUrl: `${PUBLIC_INTEGRATIONS_LOGO_URL}/zendesk.png`,
+      defaultScope: 'read write',
+      authorizationExtraParams: {
+        responseType: 'code'
+      }
+    },
+    // Workflows and scheduled jobs run with nobody signed in, so they need a token no one has to
+    // click Connect for. Zendesk issues one to a confidential client from its own secret, with
+    // no refresh token, from the same tenant endpoint the authorization-code exchange uses.
+    oauth2ClientCredentials: {
+      tokenUrl: `${ZENDESK_HOST}/oauth/tokens`,
+      defaultScope: 'read write',
+      // Agents before 0.0.18 mint the token but never put it on the request.
+      startVersion: RestApiIntegrationPluginVersions.V18
+    }
   },
-  serverURL: `https://${SUPERBLOCKS_OPENAPI_TENANT_KEYWORD}.zendesk.com`,
+  defaultAuthMethod: 'oauth2BringYourOwn',
+  authOptionsLdFlag: { ldFlag: ZENDESK_OAUTH_ROLLOUT_FLAG, keep: [IntegrationAuthType.BASIC] },
+  serverURL: ZENDESK_HOST,
   tenantInput: {
     label: 'Zendesk tenant',
     placeholder: 'acme',

package/src/socket/protocol.ts

@@ -200,6 +200,25 @@ export interface ServerMethods {
   };
   v2: {
     application: {
+      getRemediationFindings: ServerMethodSchema<
+        { applicationId: string; reviewFindingIds: string[]; includeDetails?: boolean },
+        {
+          findings: Array<{
+            id: string;
+            reviewRunId: string;
+            sourcePhase: string | null;
+            title?: string;
+            severity?: string;
+            primaryLocation?: { path: string; line: number | null };
+            suggestedFix?: string;
+            technicalSummary?: string;
+            advisoryId?: string;
+            packageName?: string;
+            installedVersion?: string;
+            fixedVersion?: string;
+          }>;
+        }
+      >;
       create: ServerMethodSchema<PostApplicationCreateRequestBody, IApplicationV2Dto>;
       clone: ServerMethodSchema<{ applicationId: string }, PostApplicationCloneResponseBody>;
       createBranch: ServerMethodSchema<