@slates/provider 1.0.0-rc.2 → 1.0.0-rc.20

package/src/auth/oauth.ts

@@ -0,0 +1,150 @@
+import { createApiServiceError } from '../error/api';
+
+export type OAuthTokenResponse = {
+  access_token?: unknown;
+  refresh_token?: unknown;
+  expires_in?: unknown;
+  [key: string]: unknown;
+};
+
+export type OAuthRefreshTokenFallbackMode = 'nullish' | 'falsy';
+
+export type OAuthExpiresAtOptions = {
+  nowMs?: number;
+  providerLabel?: string;
+  operation?: string;
+  required?: boolean;
+  expiresInType?: 'number' | 'numberLike';
+  message?: string;
+};
+
+export type NormalizeOAuthTokenResponseOptions = OAuthExpiresAtOptions & {
+  previousRefreshToken?: string;
+  refreshTokenFallbackMode?: OAuthRefreshTokenFallbackMode;
+  accessTokenMessage?: string;
+  expiresInMessage?: string;
+};
+
+let isOAuthTokenResponse = (value: unknown): value is OAuthTokenResponse =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+let formatOAuthTokenResponseMessage = (
+  fieldLabel: string,
+  providerLabel = 'OAuth provider',
+  operation = 'token response'
+) => `${providerLabel} OAuth ${operation} did not return ${fieldLabel}.`;
+
+export let getOAuthExpiresAtFromExpiresIn = (
+  expiresIn: unknown,
+  options: OAuthExpiresAtOptions = {}
+) => {
+  let {
+    nowMs = Date.now(),
+    providerLabel,
+    operation,
+    required = false,
+    expiresInType = 'numberLike',
+    message
+  } = options;
+
+  if (expiresIn === undefined || expiresIn === null || expiresIn === '') {
+    if (required) {
+      throw createApiServiceError(
+        message ??
+          formatOAuthTokenResponseMessage(
+            'a valid expires_in value',
+            providerLabel,
+            operation
+          ),
+        { reason: 'oauth_token_response' }
+      );
+    }
+
+    return undefined;
+  }
+
+  let seconds =
+    typeof expiresIn === 'number'
+      ? expiresIn
+      : expiresInType === 'numberLike' && typeof expiresIn === 'string'
+        ? Number(expiresIn)
+        : Number.NaN;
+
+  if (!Number.isFinite(seconds)) {
+    throw createApiServiceError(
+      message ??
+        formatOAuthTokenResponseMessage('a valid expires_in value', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  return new Date(nowMs + seconds * 1000).toISOString();
+};
+
+let getRefreshToken = (
+  refreshToken: unknown,
+  previousRefreshToken: string | undefined,
+  fallbackMode: OAuthRefreshTokenFallbackMode
+) => {
+  if (typeof refreshToken === 'string') {
+    if (fallbackMode === 'falsy' && !refreshToken) {
+      return previousRefreshToken;
+    }
+
+    return refreshToken;
+  }
+
+  if (fallbackMode === 'falsy' && !refreshToken) {
+    return previousRefreshToken;
+  }
+
+  return refreshToken === undefined || refreshToken === null
+    ? previousRefreshToken
+    : undefined;
+};
+
+export let normalizeOAuthTokenResponse = (
+  data: unknown,
+  options: NormalizeOAuthTokenResponseOptions = {}
+) => {
+  let {
+    providerLabel,
+    operation,
+    previousRefreshToken,
+    refreshTokenFallbackMode = 'nullish',
+    accessTokenMessage,
+    expiresInMessage,
+    ...expiresAtOptions
+  } = options;
+
+  if (!isOAuthTokenResponse(data)) {
+    throw createApiServiceError(
+      accessTokenMessage ??
+        formatOAuthTokenResponseMessage('a token response object', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  if (typeof data.access_token !== 'string' || !data.access_token) {
+    throw createApiServiceError(
+      accessTokenMessage ??
+        formatOAuthTokenResponseMessage('an access token', providerLabel, operation),
+      { reason: 'oauth_token_response' }
+    );
+  }
+
+  return {
+    token: data.access_token,
+    refreshToken: getRefreshToken(
+      data.refresh_token,
+      previousRefreshToken,
+      refreshTokenFallbackMode
+    ),
+    expiresAt: getOAuthExpiresAtFromExpiresIn(data.expires_in, {
+      ...expiresAtOptions,
+      providerLabel,
+      operation,
+      message: expiresInMessage
+    })
+  };
+};

package/src/auth/redact.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import type { SlateAttachment } from '../action/attachment';
+import { AuthConfigSecretRedactor, redactUrlAttachmentSecrets } from './redact';
+
+describe('AuthConfigSecretRedactor', () => {
+  let authConfig = { token: '123SECRET', nested: { token2: 'also_secret' } };
+
+  it('redacts values that match a secret to placeholders', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+
+    expect(
+      redactor.redact({
+        headers: { Authorization: 'Bearer 123SECRET' },
+        query: { key: 'also_secret' }
+      })
+    ).toEqual({
+      headers: { Authorization: 'Bearer 123SECRET' }, // whole-value match only, not substring
+      query: { key: '$$MT$secret$authConfig$nested.token2' }
+    });
+  });
+
+  it('redacts a bare string value', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+    expect(redactor.redact('123SECRET')).toBe('$$MT$secret$authConfig$token');
+  });
+
+  it('leaves non-secret strings untouched', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+    expect(redactor.redact('https://example.com/file.pdf')).toBe(
+      'https://example.com/file.pdf'
+    );
+  });
+
+  it('recurses through arrays and nested objects', () => {
+    let redactor = new AuthConfigSecretRedactor(authConfig);
+    expect(redactor.redact({ list: ['also_secret', 'plain'] })).toEqual({
+      list: ['$$MT$secret$authConfig$nested.token2', 'plain']
+    });
+  });
+
+  it('never registers an empty-string secret', () => {
+    let redactor = new AuthConfigSecretRedactor({ token: '' });
+    expect(redactor.redact({ a: '', b: '' })).toEqual({ a: '', b: '' });
+  });
+
+  it('is a no-op when there is no auth config', () => {
+    let redactor = new AuthConfigSecretRedactor(undefined);
+    expect(redactor.redact({ a: 'b' })).toEqual({ a: 'b' });
+  });
+});
+
+describe('redactUrlAttachmentSecrets', () => {
+  let authConfig = { token: '123SECRET', nested: { token2: 'also_secret' } };
+
+  let urlAttachment = (
+    overrides: Partial<Extract<SlateAttachment['content'], { type: 'url' }>> = {}
+  ): SlateAttachment => ({
+    mimeType: 'application/pdf',
+    content: { type: 'url', url: 'https://example.com/file.pdf', ...overrides }
+  });
+
+  it('redacts headers and query on url attachments', () => {
+    let attachments: SlateAttachment[] = [
+      urlAttachment({
+        headers: { Authorization: 'Bearer 123SECRET' },
+        query: { key: 'also_secret' }
+      })
+    ];
+
+    expect(redactUrlAttachmentSecrets(attachments, authConfig)).toEqual([
+      urlAttachment({
+        headers: { Authorization: 'Bearer 123SECRET' },
+        query: { key: '$$MT$secret$authConfig$nested.token2' }
+      })
+    ]);
+  });
+
+  it('leaves url attachments with no headers/query untouched', () => {
+    let attachments = [urlAttachment()];
+    expect(redactUrlAttachmentSecrets(attachments, authConfig)).toEqual(attachments);
+  });
+
+  it('leaves content and upload_reference attachments untouched', () => {
+    let attachments: SlateAttachment[] = [
+      {
+        mimeType: 'text/plain',
+        content: { type: 'content', encoding: 'utf-8', content: 'hi' }
+      },
+      { content: { type: 'upload_reference', referenceId: 'ref_1' } }
+    ];
+
+    expect(redactUrlAttachmentSecrets(attachments, authConfig)).toEqual(attachments);
+  });
+
+  it('is a no-op when there is no auth config', () => {
+    let attachments = [urlAttachment({ headers: { Authorization: 'Bearer 123SECRET' } })];
+    expect(redactUrlAttachmentSecrets(attachments, undefined)).toBe(attachments);
+  });
+
+  it('passes an undefined attachment list through unchanged', () => {
+    expect(redactUrlAttachmentSecrets(undefined, authConfig)).toBeUndefined();
+  });
+});

package/src/auth/redact.ts

@@ -0,0 +1,111 @@
+import type { SlateAttachment } from '../action/attachment';
+
+/**
+ * Placeholder prefix used to mark a redacted auth-config secret. Must match the hub's
+ * AuthConfigSecretSerializer (oss/src/slates/apps/hub/src/lib/secretSerializer.ts) exactly --
+ * the hub resolves these placeholders back to live secret values when it proxies an attachment.
+ */
+export let AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX = '$$MT$secret$authConfig$';
+
+/**
+ * Walks an auth config object and replaces any string value that exactly matches one of its
+ * leaf values with a `$$MT$secret$authConfig$<path>` placeholder. Literal, whole-value
+ * substitution only -- not a substring scan, and not a heuristic key-name/value-shape guess
+ * like the http trace redactor in '../axios/trace'.
+ */
+export class AuthConfigSecretRedactor {
+  private readonly secretToPlaceholder = new Map<string, string>();
+
+  public constructor(authConfig: Record<string, unknown> | undefined) {
+    if (authConfig) this.buildSecretMap(authConfig);
+  }
+
+  public redact<T>(value: T): T {
+    return this.transform(value, stringValue => {
+      return this.secretToPlaceholder.get(stringValue) ?? stringValue;
+    });
+  }
+
+  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('.')}`
+      );
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        this.buildSecretMap(item, [...path, String(index)]);
+      });
+
+      return;
+    }
+
+    if (this.isPlainObject(value)) {
+      Object.entries(value).forEach(([key, nestedValue]) => {
+        this.buildSecretMap(nestedValue, [...path, key]);
+      });
+    }
+  }
+
+  private transform<T>(value: T, transformString: (value: string) => string): T {
+    if (typeof value === 'string') {
+      return transformString(value) as T;
+    }
+
+    if (Array.isArray(value)) {
+      return value.map(item => this.transform(item, transformString)) as T;
+    }
+
+    if (this.isPlainObject(value)) {
+      let result: Record<string, unknown> = {};
+
+      Object.entries(value).forEach(([key, nestedValue]) => {
+        result[key] = this.transform(nestedValue, transformString);
+      });
+
+      return result as T;
+    }
+
+    return value;
+  }
+
+  private isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+  }
+}
+
+/**
+ * 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.
+ */
+export let redactUrlAttachmentSecrets = (
+  attachments: SlateAttachment[] | undefined,
+  authConfig: Record<string, unknown> | undefined
+): SlateAttachment[] | undefined => {
+  if (!authConfig || !attachments) return attachments;
+
+  let redactor = new AuthConfigSecretRedactor(authConfig);
+
+  return attachments.map(attachment => {
+    if (attachment.content.type !== 'url') return attachment;
+    if (!attachment.content.headers && !attachment.content.query) return attachment;
+
+    return {
+      ...attachment,
+      content: {
+        ...attachment.content,
+        headers: attachment.content.headers
+          ? redactor.redact(attachment.content.headers)
+          : undefined,
+        query: attachment.content.query ? redactor.redact(attachment.content.query) : undefined
+      }
+    };
+  });
+};

package/src/auth/types.ts

@@ -1,4 +1,7 @@
-import z from 'zod';
+import type z from 'zod';
+import type { SlateAuthDocsReference } from '../docs';
+
+type SlateAuthCallbackConfig = Record<string, any>;
 
 export type SlateAuthWithOauth<
   InputType extends {},
@@ -19,12 +22,14 @@ export type SlateAuthWithOauth<
     scope: string;
   }[];
 
+  docs?: SlateAuthDocsReference[];
+
   inputSchema?: z.ZodType<InputType>;
 
   onInputChanged?: (params: {
     previousInput: InputType | null;
     newInput: InputType;
-  }) => Promise<{ input?: InputType } | void>;
+  }) => Promise<{ input?: InputType } | undefined>;
 
   getDefaultInput?: () => Promise<InputType>;
 
@@ -35,9 +40,11 @@ export type SlateAuthWithOauth<
     clientId: string;
     clientSecret: string;
     scopes: string[];
+    config?: SlateAuthCallbackConfig;
   }) => Promise<{
     url: string;
     input?: InputType;
+    callbackState?: Record<string, any>;
   }>;
 
   handleCallback: (ctx: {
@@ -48,9 +55,13 @@ export type SlateAuthWithOauth<
     clientId: string;
     clientSecret: string;
     scopes: string[];
+    callbackParams?: Record<string, string>;
+    callbackState: Record<string, any>;
+    config?: SlateAuthCallbackConfig;
   }) => Promise<{
     output: OutputType;
     input?: InputType;
+    scopes?: string[];
   }>;
 
   handleTokenRefresh?: (ctx: {
@@ -59,12 +70,18 @@ export type SlateAuthWithOauth<
     clientId: string;
     clientSecret: string;
     scopes: string[];
+    config?: SlateAuthCallbackConfig;
   }) => Promise<{
     output: OutputType;
     input?: InputType;
   }>;
 
-  getProfile?: (ctx: { output: OutputType; input: InputType; scopes: string[] }) => Promise<{
+  getProfile?: (ctx: {
+    output: OutputType;
+    input: InputType;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+  }) => Promise<{
     profile: Record<string, any>;
   }>;
 };
@@ -77,16 +94,26 @@ export type SlateAuthWithToken<InputType extends {}, OutputType extends { token?
 
   inputSchema?: z.ZodType<InputType>;
 
-  getOutput: (ctx: { input: InputType }) => Promise<{ output: OutputType }>;
+  docs?: SlateAuthDocsReference[];
+
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
+    output: OutputType;
+    scopes?: string[];
+  }>;
 
   onInputChanged?: (params: {
     previousInput: InputType;
     newInput: InputType;
-  }) => Promise<{ input?: InputType } | void>;
+  }) => Promise<{ input?: InputType } | undefined>;
 
   getDefaultInput?: () => Promise<InputType>;
 
-  getProfile?: (ctx: { output: OutputType; input: InputType }) => Promise<{
+  getProfile?: (ctx: {
+    output: OutputType;
+    input: InputType;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+  }) => Promise<{
     profile: Record<string, any>;
   }>;
 };
@@ -99,16 +126,26 @@ export type SlateAuthWithServiceAccount<InputType extends {}, OutputType extends
 
   inputSchema?: z.ZodType<InputType>;
 
-  getOutput: (ctx: { input: InputType }) => Promise<{ output: OutputType }>;
+  docs?: SlateAuthDocsReference[];
+
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
+    output: OutputType;
+    scopes?: string[];
+  }>;
 
   onInputChanged?: (params: {
     previousInput: InputType;
     newInput: InputType;
-  }) => Promise<{ input?: InputType } | void>;
+  }) => Promise<{ input?: InputType } | undefined>;
 
   getDefaultInput?: () => Promise<InputType>;
 
-  getProfile?: (ctx: { output: OutputType; input: InputType }) => Promise<{
+  getProfile?: (ctx: {
+    output: OutputType;
+    input: InputType;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+  }) => Promise<{
     profile: Record<string, any>;
   }>;
 };
@@ -121,21 +158,43 @@ export type SlateAuthWithCustomData<InputType extends {}, OutputType extends {}>
 
   inputSchema?: z.ZodType<InputType>;
 
-  getOutput: (ctx: { input: InputType }) => Promise<{ output: OutputType }>;
+  docs?: SlateAuthDocsReference[];
+
+  getOutput: (ctx: { input: InputType; config?: SlateAuthCallbackConfig }) => Promise<{
+    output: OutputType;
+    scopes?: string[];
+  }>;
+
+  handleTokenRefresh?: (ctx: {
+    output: OutputType;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+  }) => Promise<{
+    output: OutputType;
+    input?: InputType;
+  }>;
 
   onInputChanged?: (params: {
     previousInput: InputType;
     newInput: InputType;
-  }) => Promise<{ input?: InputType } | void>;
+  }) => Promise<{ input?: InputType } | undefined>;
 
   getDefaultInput?: () => Promise<InputType>;
 
-  getProfile?: (ctx: { output: OutputType; input: InputType }) => Promise<{
+  getProfile?: (ctx: {
+    output: OutputType;
+    input: InputType;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+  }) => Promise<{
     profile: Record<string, any>;
   }>;
 };
 
-export type SlateAuthWithNone<InputType extends {}, OutputType extends {}> = {
+export type SlateAuthWithNone<_InputType extends {}, _OutputType extends {}> = {
   type: 'auth.none';
 
   name: string;

package/src/axios/http.test.ts

@@ -0,0 +1,83 @@
+import type { AxiosResponse } from 'axios';
+import { describe, expect, it } from 'vitest';
+import { createAuthenticatedAxios, requestAxios, requestAxiosData } from './index';
+
+describe('createAuthenticatedAxios', () => {
+  it('sets auth and JSON headers while preserving caller headers', () => {
+    let client = createAuthenticatedAxios({
+      baseURL: 'https://example.test',
+      authHeader: {
+        value: 'Bearer token'
+      },
+      headers: {
+        Accept: 'application/json'
+      }
+    });
+
+    expect(client.defaults.baseURL).toBe('https://example.test');
+    expect(client.defaults.headers.Authorization).toBe('Bearer token');
+    expect(client.defaults.headers['Content-Type']).toBe('application/json');
+    expect(client.defaults.headers.Accept).toBe('application/json');
+  });
+
+  it('allows custom auth header names and disabling content type defaults', () => {
+    let client = createAuthenticatedAxios({
+      authHeader: {
+        name: 'X-API-Key',
+        value: 'secret'
+      },
+      contentType: false
+    });
+
+    expect(client.defaults.headers['X-API-Key']).toBe('secret');
+    expect(client.defaults.headers['Content-Type']).toBeUndefined();
+  });
+});
+
+describe('requestAxios helpers', () => {
+  it('returns full responses or response data', async () => {
+    let response = {
+      config: {} as AxiosResponse<{ ok: boolean }>['config'],
+      data: { ok: true },
+      headers: {},
+      status: 200,
+      statusText: 'OK'
+    };
+
+    await expect(
+      requestAxios(
+        'get thing',
+        async () => response,
+        error => error
+      )
+    ).resolves.toBe(response);
+    await expect(
+      requestAxiosData(
+        'get thing',
+        async () => response,
+        error => error
+      )
+    ).resolves.toEqual({ ok: true });
+  });
+
+  it('maps failures with the operation name', async () => {
+    let upstream = new Error('upstream failed');
+    let mapped = new Error('mapped failure');
+    let seenOperation: string | undefined;
+
+    await expect(
+      requestAxiosData(
+        'create thing',
+        async () => {
+          throw upstream;
+        },
+        (_error, operation) => {
+          seenOperation = operation;
+          return mapped;
+        }
+      )
+    ).rejects.toBe(mapped);
+
+    expect(seenOperation).toBe('create thing');
+  });
+});