@slates/provider 1.0.0-rc.27 → 1.0.0-rc.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/provider",
-  "version": "1.0.0-rc.27",
+  "version": "1.0.0-rc.29",
   "publishConfig": {
     "access": "public"
   },

package/src/action/getFileUrlTool.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AuthConfigSecretRedactor } from '../auth/redact';
+import { AuthConfigSecretRedactor, isUrlEmbeddedCredential } from '../auth/redact';
 import type { SlateContext } from '../context/context';
 import type { SlateSpecification } from '../specification/specification';
 import { tool } from './tool';
@@ -42,6 +42,7 @@ export let getFileUrlTool = <ConfigType extends {}, AuthType extends {}>(
       return {
         output: {
           ...output,
+          url: redactor.redactEmbedded(output.url, isUrlEmbeddedCredential),
           ...(output.headers ? { headers: redactor.redactEmbedded(output.headers) } : {}),
           ...(output.query ? { query: redactor.redactEmbedded(output.query) } : {})
         },

package/src/action/triggerGroup.ts

@@ -31,6 +31,39 @@ export type SlateTriggerGroupPollHandler<ConfigType extends {}, AuthType extends
   updatedState?: any;
 }>;
 
+export interface SlateGatewayEvent {
+  payload: any;
+  idempotencyKey?: string;
+}
+
+export type SlateTriggerGroupGatewayConnectHandler<
+  ConfigType extends {},
+  AuthType extends {}
+> = (
+  context: SlateContext<ConfigType, AuthType, { state: any | null }>
+) => Promise<{ url: string; state?: any }>;
+
+/** `closed` is set, with no frames, when the socket closed unexpectedly. */
+export type SlateTriggerGroupGatewayReceiveHandler<
+  ConfigType extends {},
+  AuthType extends {}
+> = (
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    { state: any | null; frames: string[]; closed?: { code: number; reason: string } | null }
+  >
+) => Promise<{
+  state?: any;
+  send?: string[];
+  events?: SlateGatewayEvent[];
+  /** With `expectsAck`, the hub reconnects when no `heartbeatAcked` arrives before the next beat. */
+  heartbeat?: { intervalMs: number; frame: string; expectsAck?: boolean } | null;
+  /** Set when `frames` included the provider's heartbeat acknowledgement. */
+  heartbeatAcked?: boolean;
+  close?: { reconnect: boolean; reason?: string } | null;
+}>;
+
 export type SlateWebhookTargetListHandler<ConfigType extends {}, AuthType extends {}> = (
   context: SlateContext<ConfigType, AuthType, { pageToken: any | null }>
 ) => Promise<{
@@ -121,6 +154,14 @@ export interface SlateTriggerGroupPollingParameters<
   pollEvents: SlateTriggerGroupPollHandler<ConfigType, AuthType>;
 }
 
+export interface SlateTriggerGroupGatewayParameters<
+  ConfigType extends {},
+  AuthType extends {}
+> {
+  connect: SlateTriggerGroupGatewayConnectHandler<ConfigType, AuthType>;
+  receive: SlateTriggerGroupGatewayReceiveHandler<ConfigType, AuthType>;
+}
+
 export interface SlateTriggerGroupWebhookAutoRegistrationParameters<
   ConfigType extends {},
   AuthType extends {}
@@ -164,9 +205,10 @@ export interface SlateTriggerGroupParameters<
   AuthType extends {},
   InputType extends {} = Record<string, unknown>
 > extends SlateTriggerGroupCreateParameters<InputType> {
-  source: 'polling' | 'webhook';
+  source: 'polling' | 'webhook' | 'gateway';
   polling?: SlateTriggerGroupPollingParameters<ConfigType, AuthType>;
   webhook?: SlateTriggerGroupWebhookParameters<ConfigType, AuthType>;
+  gateway?: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>;
   routingMatchers: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>;
 }
 
@@ -227,6 +269,10 @@ export class SlateTriggerGroup<
     return this._params.webhook;
   }
 
+  get gateway() {
+    return this._params.gateway;
+  }
+
   get routingMatchers() {
     return this._params.routingMatchers;
   }
@@ -237,9 +283,10 @@ export class SlateTriggerGroupBuilder<
   AuthType extends {},
   InputType extends {} = Record<string, unknown>
 > {
-  #source: 'polling' | 'webhook' | null = null;
+  #source: 'polling' | 'webhook' | 'gateway' | null = null;
   #polling: SlateTriggerGroupPollingParameters<ConfigType, AuthType> | null = null;
   #webhook: SlateTriggerGroupWebhookParameters<ConfigType, AuthType> | null = null;
+  #gateway: SlateTriggerGroupGatewayParameters<ConfigType, AuthType> | null = null;
   #routingMatchers: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType> | null =
     null;
 
@@ -302,6 +349,20 @@ export class SlateTriggerGroupBuilder<
     return this;
   }
 
+  /** Receive events over a platform-managed persistent connection (e.g. a WebSocket gateway). */
+  gateway(
+    props: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>
+  ): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType> {
+    if (this.#source) {
+      throw new SlateDeclarationError('Trigger group invocation is already defined');
+    }
+
+    this.#source = 'gateway';
+    this.#gateway = { connect: props.connect, receive: props.receive };
+
+    return this;
+  }
+
   routingMatchers(
     handler: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>
   ): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType> {
@@ -312,7 +373,7 @@ export class SlateTriggerGroupBuilder<
   build(): SlateTriggerGroup<ConfigType, AuthType, InputType> {
     if (!this.#source) {
       throw new SlateDeclarationError(
-        'Trigger group invocation (polling or webhook) is not defined'
+        'Trigger group invocation (polling, webhook, or gateway) is not defined'
       );
     }
     if (!this.#routingMatchers) {
@@ -324,6 +385,7 @@ export class SlateTriggerGroupBuilder<
       source: this.#source,
       polling: this.#polling ?? undefined,
       webhook: this.#webhook ?? undefined,
+      gateway: this.#gateway ?? undefined,
       routingMatchers: this.#routingMatchers
     });
   }

package/src/auth/redact.test.ts

@@ -141,6 +141,35 @@ describe('AuthConfigSecretRedactor.redactEmbedded', () => {
   });
 });
 
+describe('AuthConfigSecretRedactor filters', () => {
+  let authConfig = { token: 'secret-token', accountId: '123456', username: 'secret-token' };
+  let onlyToken = (_secret: string, path: string) => path === 'token';
+
+  it('limits whole-value replacement to fields that pass the filter', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+
+    expect(redactor.redact(['123456', 'secret-token'], onlyToken)).toEqual([
+      '123456',
+      '$$MT$secret$authConfig$token'
+    ]);
+    expect(
+      redactor.redactEmbedded(['123456', 'secret-token'], () => false, onlyToken)
+    ).toEqual(['123456', '$$MT$secret$authConfig$token']);
+    expect(redactor.redactEmbedded('id 123456 / secret-token', onlyToken, onlyToken)).toBe(
+      'id 123456 / $$MT$secret$authConfig$token$$'
+    );
+  });
+
+  it('keeps replacing every field, last path first, without a filter', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+
+    expect(redactor.redact(['123456', 'secret-token'])).toEqual([
+      '$$MT$secret$authConfig$accountId',
+      '$$MT$secret$authConfig$username'
+    ]);
+  });
+});
+
 describe('redactUrlAttachmentSecrets', () => {
   let authConfig = { token: '123SECRET', nested: { token2: 'also_secret' } };
 
@@ -167,7 +196,7 @@ describe('redactUrlAttachmentSecrets', () => {
     ]);
   });
 
-  it('only changes header and query values, preserving metadata and the original attachment', () => {
+  it('only changes credential values, preserving metadata and the original attachment', () => {
     let attachment: SlateAttachment = {
       mimeType: 'application/pdf',
       attachmentHash: 'file-hash',
@@ -187,6 +216,7 @@ describe('redactUrlAttachmentSecrets', () => {
         ...original,
         content: {
           ...original.content,
+          url: 'https://example.com/$$MT$secret$authConfig$token$$/file.pdf',
           headers: { Authorization: 'Bearer $$MT$secret$authConfig$token$$' },
           query: { key: '$$MT$secret$authConfig$nested.token2$$-suffix' }
         }
@@ -195,7 +225,35 @@ describe('redactUrlAttachmentSecrets', () => {
     expect(attachment).toEqual(original);
   });
 
-  it('leaves url attachments with no headers/query untouched', () => {
+  it('redacts a bot token embedded in the url path', () => {
+    let attachments = [
+      urlAttachment({ url: 'https://api.telegram.org/file/bot123:ABCDEFGH/photos/a.jpg' })
+    ];
+
+    expect(
+      redactUrlAttachmentSecrets(attachments, { token: '123:ABCDEFGH', botId: '12345678' })
+    ).toEqual([
+      urlAttachment({
+        url: 'https://api.telegram.org/file/bot$$MT$secret$authConfig$token$$/photos/a.jpg'
+      })
+    ]);
+  });
+
+  it('keeps non-credential and short auth values in the url', () => {
+    let attachments = [
+      urlAttachment({ url: 'https://example.com/AC12345678/12345678/abc/file.pdf' })
+    ];
+
+    expect(
+      redactUrlAttachmentSecrets(attachments, {
+        account_sid: 'AC12345678',
+        botId: '12345678',
+        token: 'abc'
+      })
+    ).toEqual(attachments);
+  });
+
+  it('leaves url attachments with no credentials untouched', () => {
     let attachments = [urlAttachment()];
     expect(redactUrlAttachmentSecrets(attachments, authConfig)).toEqual(attachments);
   });

package/src/auth/redact.ts

@@ -7,29 +7,52 @@ import type { SlateAttachment } from '../action/attachment';
  */
 export let AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX = '$$MT$secret$authConfig$';
 
+/** Decides whether an auth-config value (with its dotted path) may be replaced. */
+export type AuthConfigSecretFilter = (secret: string, path: string) => boolean;
+
+let ALWAYS: AuthConfigSecretFilter = () => true;
+
 /**
  * Maps auth-config string leaves to `$$MT$secret$authConfig$<path>` placeholders.
  * `redact` preserves whole-value substitution for HTTP traces; `redactEmbedded` also
  * replaces embedded values in attachment credentials, terminating those placeholders with `$$`.
+ * Both accept a `wholeValue` filter so diagnostics (traces, error text) can skip
+ * non-secret fields such as account IDs, emails, or subdomains; attachment callers keep
+ * the default, because the hub resolves every placeholder back to its value.
  */
 export class AuthConfigSecretRedactor {
-  private readonly secretToPlaceholder = new Map<string, string>();
+  // A value shared by several fields keeps every path, so a filter that rejects one
+  // field (e.g. `username`) can still match another (e.g. `token`) with the same value.
+  private readonly secretToPaths = new Map<string, string[]>();
 
   public constructor(authConfig: Record<string, unknown> | undefined) {
     if (authConfig) this.buildSecretMap(authConfig);
   }
 
-  public redact<T>(value: T): T {
+  public redact<T>(value: T, wholeValue: AuthConfigSecretFilter = ALWAYS): T {
     return this.transform(value, stringValue => {
-      return this.secretToPlaceholder.get(stringValue) ?? stringValue;
+      return this.placeholderFor(stringValue, wholeValue) ?? stringValue;
     });
   }
 
-  public redactEmbedded<T>(value: T): T {
-    if (this.secretToPlaceholder.size === 0) return value;
+  /**
+   * `embeddable` limits which secrets are also replaced inside longer strings;
+   * `wholeValue` limits which secrets replace a string that equals them exactly.
+   */
+  public redactEmbedded<T>(
+    value: T,
+    embeddable: AuthConfigSecretFilter = ALWAYS,
+    wholeValue: AuthConfigSecretFilter = ALWAYS
+  ): T {
+    let embeddedPlaceholders = new Map<string, string>();
+    for (let secret of this.secretToPaths.keys()) {
+      let placeholder = this.placeholderFor(secret, embeddable);
+      if (placeholder) embeddedPlaceholders.set(secret, placeholder);
+    }
+    if (embeddedPlaceholders.size === 0) return this.redact(value, wholeValue);
 
     let pattern = new RegExp(
-      [...this.secretToPlaceholder.keys()]
+      [...embeddedPlaceholders.keys()]
         .sort((a, b) => b.length - a.length)
         // Escape regex metacharacters so values match literally; $& inserts the matched character.
         .map(secret => secret.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
@@ -38,25 +61,34 @@ export class AuthConfigSecretRedactor {
     );
 
     return this.transform(value, stringValue => {
-      let exactPlaceholder = this.secretToPlaceholder.get(stringValue);
+      let exactPlaceholder = this.placeholderFor(stringValue, wholeValue);
       if (exactPlaceholder) return exactPlaceholder;
 
-      return stringValue.replace(
-        pattern,
-        secret => `${this.secretToPlaceholder.get(secret)}$$`
-      );
+      return stringValue.replace(pattern, secret => `${embeddedPlaceholders.get(secret)}$$`);
     });
   }
 
+  // The last registered path that passes the filter wins, matching the historical
+  // last-write-wins behavior when no filter is given.
+  private placeholderFor(value: string, filter: AuthConfigSecretFilter) {
+    let paths = this.secretToPaths.get(value);
+    if (!paths) return undefined;
+    for (let index = paths.length - 1; index >= 0; index--) {
+      let path = paths[index];
+      if (path !== undefined && filter(value, path))
+        return `${AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX}${path}`;
+    }
+    return undefined;
+  }
+
   private buildSecretMap(value: unknown, path: string[] = []): void {
     if (typeof value === 'string') {
       // Never register "" -- it would replace every empty header/query value with a placeholder.
       if (value.length === 0) return;
 
-      this.secretToPlaceholder.set(
-        value,
-        `${AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX}${path.join('.')}`
-      );
+      let paths = this.secretToPaths.get(value);
+      if (paths) paths.push(path.join('.'));
+      else this.secretToPaths.set(value, [path.join('.')]);
       return;
     }
 
@@ -102,10 +134,17 @@ export class AuthConfigSecretRedactor {
   }
 }
 
+// Credentials replaced inside URLs (e.g. Telegram's `/file/bot<token>/` path). Kept narrow:
+// a placeholder in a URL makes the hub proxy the download instead of handing out the link.
+let URL_CREDENTIAL_KEY = /^(?:.*[-_])?(?:token|secret|password|api[-_]?key)$/i;
+
+export let isUrlEmbeddedCredential = (secret: string, path: string) =>
+  secret.length >= 8 && URL_CREDENTIAL_KEY.test(path.split('.').pop() ?? '');
+
 /**
  * Applied to every finalized attachment list right before it's sent over
  * `slates/action.tool.invoke` (see @slates/provider-handler). Only `type: 'url'` attachments
- * carry headers/query -- content/upload_reference attachments pass through untouched.
+ * carry credentials -- content/upload_reference attachments pass through untouched.
  */
 export let redactUrlAttachmentSecrets = (
   attachments: SlateAttachment[] | undefined,
@@ -117,18 +156,15 @@ export let redactUrlAttachmentSecrets = (
 
   return attachments.map(attachment => {
     if (attachment.content.type !== 'url') return attachment;
-    if (!attachment.content.headers && !attachment.content.query) return attachment;
 
+    let { url, headers, query } = attachment.content;
     return {
       ...attachment,
       content: {
         ...attachment.content,
-        headers: attachment.content.headers
-          ? redactor.redactEmbedded(attachment.content.headers)
-          : undefined,
-        query: attachment.content.query
-          ? redactor.redactEmbedded(attachment.content.query)
-          : undefined
+        url: redactor.redactEmbedded(url, isUrlEmbeddedCredential),
+        ...(headers ? { headers: redactor.redactEmbedded(headers) } : {}),
+        ...(query ? { query: redactor.redactEmbedded(query) } : {})
       }
     };
   });