@slates/provider-handler 1.0.0-rc.42 → 1.0.0-rc.44

package/src/spec.test.ts

@@ -1,4 +1,5 @@
 import { isServiceError } from '@lowerdeck/error';
+import { slatesTriggerGroup } from '@slates/proto';
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';
 import {
@@ -8,11 +9,14 @@ import {
   getExposedTriggerGroups,
   getMappableAction,
   getTriggersForGroup,
+  getWebhookDeliveryConfig,
+  getWebhookManualRegistration,
   isMappableTrigger,
   mapAction,
   mapAdapter,
   mapAuthMethod,
-  mapToolCategory
+  mapToolCategory,
+  mapTriggerGroup
 } from './spec';
 
 let baseAction = {
@@ -202,6 +206,92 @@ describe('adapter exposure', () => {
   });
 });
 
+describe('webhook registration config', () => {
+  let config = {
+    userConfigSchema: z.object({ secret: z.string().describe('Signing secret') }),
+    fullConfigSchema: z.object({ secret: z.string(), endpoint: z.string() }),
+    setup: async () => ({ webhookSetupDocument: '', partialWebhookRegistrationPayload: {} }),
+    finish: async () => ({ webhookRegistrationPayload: {} }),
+    authenticate: async () => ({ routingKeys: [] })
+  };
+  let schemas = {
+    userConfigSchema: {
+      type: 'object',
+      properties: { secret: { type: 'string', description: 'Signing secret' } },
+      required: ['secret']
+    },
+    fullConfigSchema: {
+      type: 'object',
+      properties: { secret: { type: 'string' }, endpoint: { type: 'string' } },
+      required: ['secret', 'endpoint']
+    }
+  };
+  let autoRegistration = {
+    webhookTargetList: async () => ({ targets: [], nextPageToken: null }),
+    webhookRegister: async () => ({
+      webhookRegistrationIdentifier: 'reg',
+      webhookRegistrationPayload: {}
+    }),
+    webhookUnregister: async () => {}
+  };
+  let group = (webhook: Record<string, unknown>): any => ({
+    key: 'group',
+    name: 'Group',
+    source: 'webhook',
+    webhook: { process: async () => ({ events: [] }), ...webhook }
+  });
+  let auto = group({ autoRegistration });
+  let manual = group({ manualRegistration: config });
+  let configured = group({ autoRegistration, deliveryConfig: config });
+
+  it('keeps plain automatic and manual groups serialised as before', () => {
+    expect(mapTriggerGroup(auto).invocation).toEqual({
+      type: 'webhook',
+      registration: { mode: 'auto' }
+    });
+    expect(mapTriggerGroup(manual).invocation).toMatchObject({
+      type: 'webhook',
+      registration: { mode: 'manual', ...schemas }
+    });
+    expect(
+      Object.keys((mapTriggerGroup(manual).invocation as any).registration).sort()
+    ).toEqual(['fullConfigSchema', 'mode', 'userConfigSchema']);
+  });
+
+  it('advertises the delivery config of an automatic group', () => {
+    let mapped = mapTriggerGroup(configured);
+    expect(mapped.invocation).toMatchObject({
+      type: 'webhook',
+      registration: { mode: 'auto', deliveryConfig: schemas }
+    });
+    expect(slatesTriggerGroup.parse(mapped).invocation).toEqual(mapped.invocation);
+  });
+
+  it('authenticates deliveries only for automatic groups with a delivery config', () => {
+    expect(getWebhookDeliveryConfig(configured)).toBe(config);
+    for (let unsupported of [
+      auto,
+      manual,
+      { key: 'group', name: 'Group', source: 'polling' } as any
+    ]) {
+      expect(() => getWebhookDeliveryConfig(unsupported)).toThrow(
+        'Trigger group does not support webhook delivery authentication: group'
+      );
+    }
+  });
+
+  it('serves setup and finish for manual groups and automatic groups with a delivery config', () => {
+    expect(getWebhookManualRegistration(manual)).toBe(config);
+    expect(getWebhookManualRegistration(configured)).toBe(config);
+    expect(() => getWebhookManualRegistration(auto)).toThrow(
+      'Trigger group does not support manual webhook registration: group'
+    );
+    expect(() =>
+      getWebhookManualRegistration({ key: 'poll', name: 'Poll', source: 'polling' } as any)
+    ).toThrow('Trigger group does not support manual webhook registration: poll');
+  });
+});
+
 describe('mapAuthMethod', () => {
   let slate: any = { spec: { auth: { outputSchema: z.object({ token: z.string() }) } } };
   let oauthMethod: any = {

package/src/spec.ts

@@ -266,7 +266,11 @@ export let getWebhookAutoRegistration = <ConfigType extends {}, AuthType extends
 export let getWebhookManualRegistration = <ConfigType extends {}, AuthType extends {}>(
   group: ReturnType<typeof getTriggerGroup<ConfigType, AuthType>>
 ) => {
-  if (group.source !== 'webhook' || !group.webhook?.manualRegistration) {
+  let registration =
+    group.source === 'webhook'
+      ? (group.webhook?.manualRegistration ?? group.webhook?.deliveryConfig)
+      : undefined;
+  if (!registration) {
     throw new ServiceError(
       badRequestError({
         message: `Trigger group does not support manual webhook registration: ${group.key}`
@@ -274,9 +278,31 @@ export let getWebhookManualRegistration = <ConfigType extends {}, AuthType exten
     );
   }
 
-  return group.webhook.manualRegistration;
+  return registration;
 };
 
+export let getWebhookDeliveryConfig = <ConfigType extends {}, AuthType extends {}>(
+  group: ReturnType<typeof getTriggerGroup<ConfigType, AuthType>>
+) => {
+  if (group.source !== 'webhook' || !group.webhook?.deliveryConfig) {
+    throw new ServiceError(
+      badRequestError({
+        message: `Trigger group does not support webhook delivery authentication: ${group.key}`
+      })
+    );
+  }
+
+  return group.webhook.deliveryConfig;
+};
+
+let mapWebhookConfigSchemas = (config: {
+  userConfigSchema: z.ZodType<any>;
+  fullConfigSchema: z.ZodType<any>;
+}) => ({
+  userConfigSchema: toJsonSchema(config.userConfigSchema),
+  fullConfigSchema: toJsonSchema(config.fullConfigSchema)
+});
+
 export let mapToolCategory = (category: SlateToolCategory): SlatesToolCategory => ({
   id: category.key,
   name: category.name,
@@ -307,6 +333,9 @@ export let mapTriggerGroup = <ConfigType extends {}, AuthType extends {}>(
   name: group.name,
   description: group.description,
   metadata: group.metadata,
+  ...(group.selectionSchema
+    ? { selectionSchema: toJsonSchema(group.selectionSchema, 'input') }
+    : {}),
   invocation:
     group.source === 'polling'
       ? {
@@ -317,16 +346,25 @@ export let mapTriggerGroup = <ConfigType extends {}, AuthType extends {}>(
         ? { type: 'gateway' }
         : {
             type: 'webhook',
+            ...(group.webhook?.expandWebhook ? { supportsExpansion: true } : {}),
+            ...(group.webhook?.autoRegistration?.webhookRenew
+              ? { supportsRenewal: true }
+              : {}),
+            ...(group.webhook?.reconcileIntervalSeconds !== undefined
+              ? { reconcileIntervalSeconds: group.webhook.reconcileIntervalSeconds }
+              : {}),
             registration: group.webhook?.manualRegistration
               ? {
                   mode: 'manual',
-                  userConfigSchema: toJsonSchema(
-                    group.webhook.manualRegistration.userConfigSchema
-                  ),
-                  fullConfigSchema: toJsonSchema(
-                    group.webhook.manualRegistration.fullConfigSchema
-                  )
+                  ...mapWebhookConfigSchemas(group.webhook.manualRegistration)
+                }
+              : {
+                  mode: 'auto',
+                  ...(group.webhook?.deliveryConfig
+                    ? {
+                        deliveryConfig: mapWebhookConfigSchemas(group.webhook.deliveryConfig)
+                      }
+                    : {})
                 }
-              : { mode: 'auto' }
           }
 });

package/src/validation.ts

@@ -26,8 +26,9 @@ export let validate = <T>(
   return result.data;
 };
 
-export let toJsonSchema = (schema: z.ZodType<any>) =>
+export let toJsonSchema = (schema: z.ZodType<any>, io: 'input' | 'output' = 'output') =>
   schema.toJSONSchema({
+    io,
     unrepresentable: 'any',
     override: ctx => {
       let def = ctx.zodSchema._zod.def;

package/src/webhookDeliveryAuthenticate.test.ts

@@ -0,0 +1,179 @@
+import { SLATES_PROTOCOL_VERSION, SlatesProviderProtoHandlerManager } from '@slates/proto';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { createProviderHandler } from './index';
+
+type Authentication = { routingKeys?: string[]; rejected?: { status: number } };
+
+let createManager = async (authenticate: (ctx: any) => Promise<Authentication>) => {
+  let contexts: {
+    auth: unknown;
+    config: unknown;
+    deliveryConfig: unknown;
+    request: Request;
+  }[] = [];
+  let autoRegistration = {
+    webhookTargetList: async () => ({ targets: [], nextPageToken: null }),
+    webhookRegister: async () => ({
+      webhookRegistrationIdentifier: 'reg',
+      webhookRegistrationPayload: {}
+    }),
+    webhookUnregister: async () => {}
+  };
+  let deliveryConfig = {
+    userConfigSchema: z.object({}),
+    fullConfigSchema: z.object({}),
+    setup: async () => ({ webhookSetupDocument: '', partialWebhookRegistrationPayload: {} }),
+    finish: async () => ({ webhookRegistrationPayload: {} }),
+    authenticate: async (ctx: any) => {
+      contexts.push({
+        auth: ctx.auth,
+        config: ctx.config,
+        deliveryConfig: ctx.input.deliveryConfig,
+        request: ctx.input.request
+      });
+      return authenticate(ctx);
+    }
+  };
+  let group = (key: string, webhook: Record<string, unknown>) => ({
+    key,
+    name: key,
+    description: undefined,
+    metadata: {},
+    source: 'webhook',
+    webhook: { process: async () => ({ events: [] }), ...webhook }
+  });
+  let slate = {
+    spec: { key: 'test', name: 'Test' },
+    adapters: [],
+    actions: [],
+    triggerGroups: [
+      group('configured', { autoRegistration, deliveryConfig }),
+      group('auto', { autoRegistration }),
+      group('manual', { manualRegistration: deliveryConfig }),
+      { key: 'poll', name: 'poll', source: 'polling', polling: { intervalSeconds: 600 } }
+    ]
+  };
+  let manager = await createProviderHandler(slate as any, []).run();
+
+  await SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    method: 'slates/hello',
+    params: { protocol: SLATES_PROTOCOL_VERSION }
+  });
+  await SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    method: 'slates/participant.set',
+    params: { participants: [] }
+  });
+  await SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    method: 'slates/hub.capabilities.set',
+    params: { capabilities: { triggers: true } }
+  });
+
+  return {
+    contexts,
+    authenticate: (params: Record<string, unknown> = {}) =>
+      SlatesProviderProtoHandlerManager.handleInput(manager, {
+        jsonrpc: '2.0',
+        id: 'authenticate',
+        method: 'slates/trigger_group.webhook.delivery_authenticate',
+        params: {
+          triggerGroupId: 'configured',
+          url: 'https://hub.example/receive/config?attempt=1',
+          method: 'POST',
+          headers: { authorization: 'Bearer token', 'content-type': 'application/json' },
+          body: { encoding: 'base64', content: btoa('{"message":{}}') },
+          deliveryConfig: { audience: 'https://hub.example/receive/config', extra: [1, 2] },
+          ...params
+        }
+      } as any)
+  };
+};
+
+describe('slates/trigger_group.webhook.delivery_authenticate', () => {
+  it('hands the received request and the saved config to the handler without credentials', async () => {
+    let { authenticate, contexts } = await createManager(async () => ({
+      routingKeys: ['mailbox:user@example.com', 'mailbox:other@example.com']
+    }));
+
+    expect(await authenticate()).toEqual({
+      jsonrpc: '2.0',
+      id: 'authenticate',
+      result: {
+        routingKeys: ['mailbox:user@example.com', 'mailbox:other@example.com'],
+        rejected: null
+      }
+    });
+    let [received] = contexts;
+    expect(received).toMatchObject({
+      auth: {},
+      config: {},
+      deliveryConfig: { audience: 'https://hub.example/receive/config', extra: [1, 2] }
+    });
+    expect(received!.request.url).toBe('https://hub.example/receive/config?attempt=1');
+    expect(received!.request.method).toBe('POST');
+    expect(Object.fromEntries(received!.request.headers)).toEqual({
+      authorization: 'Bearer token',
+      'content-type': 'application/json'
+    });
+    expect(await received!.request.text()).toBe('{"message":{}}');
+  });
+
+  it('reconstructs a request without a body', async () => {
+    let { authenticate, contexts } = await createManager(async () => ({ routingKeys: [] }));
+
+    await authenticate({ method: 'GET', headers: {}, body: null });
+    expect(contexts[0]!.request.method).toBe('GET');
+    expect(contexts[0]!.request.body).toBeNull();
+  });
+
+  it('acknowledges an authenticated request that addresses no registration', async () => {
+    let { authenticate } = await createManager(async () => ({ routingKeys: [] }));
+
+    expect(await authenticate()).toMatchObject({
+      result: { routingKeys: [], rejected: null }
+    });
+  });
+
+  it.each([
+    401, 403, 404, 503
+  ])('passes a rejection with status %i through without routing keys', async status => {
+    let { authenticate } = await createManager(async () => ({ rejected: { status } }));
+
+    expect(await authenticate()).toMatchObject({
+      result: { routingKeys: [], rejected: { status } }
+    });
+  });
+
+  it.each([
+    ['a status outside 400-599', { rejected: { status: 200 } }],
+    ['a fractional status', { rejected: { status: 401.5 } }],
+    ['no routing keys and no rejection', {}],
+    ['an empty routing key', { routingKeys: [''] }],
+    ['a routing key over 512 characters', { routingKeys: ['x'.repeat(513)] }],
+    ['more than 16 routing keys', { routingKeys: Array(17).fill('key') }]
+  ])('rejects a handler result with %s', async (_, result) => {
+    let { authenticate } = await createManager(async () => result);
+
+    expect(await authenticate()).toMatchObject({
+      error: { message: 'Webhook delivery authentication returned an invalid result' }
+    });
+  });
+
+  it.each([
+    'auto',
+    'manual',
+    'poll'
+  ])('rejects the %s group, which has no delivery config', async triggerGroupId => {
+    let { authenticate, contexts } = await createManager(async () => ({ routingKeys: [] }));
+
+    expect(await authenticate({ triggerGroupId })).toMatchObject({
+      error: {
+        message: `Trigger group does not support webhook delivery authentication: ${triggerGroupId}`
+      }
+    });
+    expect(contexts).toEqual([]);
+  });
+});

package/src/webhookSetup.test.ts

@@ -0,0 +1,179 @@
+import { SLATES_PROTOCOL_VERSION, SlatesProviderProtoHandlerManager } from '@slates/proto';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { createProviderHandler } from './index';
+
+let createManager = async () => {
+  let contexts: { operation: string; auth: unknown; config: unknown; input: unknown }[] = [];
+  let config = (finish = true) => ({
+    userConfigSchema: z.object({ secret: z.string() }),
+    fullConfigSchema: z.object({ secret: z.string(), endpoint: z.string() }),
+    setup: async (ctx: any) => {
+      contexts.push({
+        operation: 'setup',
+        auth: ctx.auth,
+        config: ctx.config,
+        input: ctx.input
+      });
+      return {
+        webhookSetupDocument: `Send events to ${ctx.input.webhookUrl}`,
+        partialWebhookRegistrationPayload: { endpoint: ctx.input.webhookUrl }
+      };
+    },
+    ...(finish
+      ? {
+          finish: async (ctx: any) => {
+            contexts.push({
+              operation: 'finish',
+              auth: ctx.auth,
+              config: ctx.config,
+              input: ctx.input
+            });
+            return {
+              webhookRegistrationPayload: {
+                ...ctx.input.partialWebhookRegistrationPayload,
+                ...ctx.input.userWebhookRegistrationPayload
+              }
+            };
+          }
+        }
+      : {})
+  });
+  let autoRegistration = {
+    webhookTargetList: async () => ({ targets: [], nextPageToken: null }),
+    webhookRegister: async () => ({
+      webhookRegistrationIdentifier: 'reg',
+      webhookRegistrationPayload: {}
+    }),
+    webhookUnregister: async () => {}
+  };
+  let group = (key: string, webhook: Record<string, unknown>) => ({
+    key,
+    name: key,
+    description: undefined,
+    metadata: {},
+    source: 'webhook',
+    webhook: { process: async () => ({ events: [] }), ...webhook }
+  });
+  let slate = {
+    spec: { key: 'test', name: 'Test' },
+    adapters: [],
+    actions: [],
+    triggerGroups: [
+      group('manual', { manualRegistration: config() }),
+      group('manual_without_finish', { manualRegistration: config(false) }),
+      group('configured', { autoRegistration, deliveryConfig: config() }),
+      group('auto', { autoRegistration }),
+      { key: 'poll', name: 'poll', source: 'polling', polling: { intervalSeconds: 600 } }
+    ]
+  };
+  let manager = await createProviderHandler(slate as any, []).run();
+
+  await SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    method: 'slates/hello',
+    params: { protocol: SLATES_PROTOCOL_VERSION }
+  });
+  await SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    method: 'slates/participant.set',
+    params: { participants: [] }
+  });
+  await SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    method: 'slates/hub.capabilities.set',
+    params: { capabilities: { triggers: true } }
+  });
+
+  let request = (method: string, params: Record<string, unknown>) =>
+    SlatesProviderProtoHandlerManager.handleInput(manager, {
+      jsonrpc: '2.0',
+      id: method,
+      method,
+      params
+    } as any);
+
+  return {
+    contexts,
+    setup: (triggerGroupId: string) =>
+      request('slates/trigger_group.webhook.manual_setup', {
+        triggerGroupId,
+        webhookUrl: 'https://receive.example/key'
+      }),
+    finish: (triggerGroupId: string) =>
+      request('slates/trigger_group.webhook.manual_finish', {
+        triggerGroupId,
+        webhookUrl: 'https://receive.example/key',
+        partialWebhookRegistrationPayload: { endpoint: 'https://receive.example/key' },
+        userWebhookRegistrationPayload: { secret: 'shared' }
+      })
+  };
+};
+
+describe('slates/trigger_group.webhook.manual_setup and manual_finish', () => {
+  it.each([
+    'manual',
+    'configured'
+  ])('serve the %s group with unchanged shapes and an empty context', async triggerGroupId => {
+    let { setup, finish, contexts } = await createManager();
+
+    expect(await setup(triggerGroupId)).toMatchObject({
+      result: {
+        webhookSetupDocument: 'Send events to https://receive.example/key',
+        partialWebhookRegistrationPayload: { endpoint: 'https://receive.example/key' }
+      }
+    });
+    expect(await finish(triggerGroupId)).toMatchObject({
+      result: {
+        webhookRegistrationPayload: {
+          endpoint: 'https://receive.example/key',
+          secret: 'shared'
+        }
+      }
+    });
+    expect(contexts).toEqual([
+      {
+        operation: 'setup',
+        auth: {},
+        config: {},
+        input: { webhookUrl: 'https://receive.example/key' }
+      },
+      {
+        operation: 'finish',
+        auth: {},
+        config: {},
+        input: {
+          webhookUrl: 'https://receive.example/key',
+          partialWebhookRegistrationPayload: { endpoint: 'https://receive.example/key' },
+          userWebhookRegistrationPayload: { secret: 'shared' }
+        }
+      }
+    ]);
+  });
+
+  it.each([
+    'auto',
+    'poll'
+  ])('reject the %s group, which has no setup to complete', async triggerGroupId => {
+    let { setup, finish, contexts } = await createManager();
+
+    for (let response of [await setup(triggerGroupId), await finish(triggerGroupId)]) {
+      expect(response).toMatchObject({
+        error: {
+          message: `Trigger group does not support manual webhook registration: ${triggerGroupId}`
+        }
+      });
+    }
+    expect(contexts).toEqual([]);
+  });
+
+  it('reject finish for a manual group that does not implement it', async () => {
+    let { finish } = await createManager();
+
+    expect(await finish('manual_without_finish')).toMatchObject({
+      error: {
+        message: 'Trigger group does not support manual webhook finish: manual_without_finish'
+      }
+    });
+  });
+});