@pikku/core 0.12.4 → 0.12.6

package/src/wirings/oauth2/oauth2-client.ts

@@ -0,0 +1,335 @@
+import type { OAuth2Token, OAuth2AppCredential } from './oauth2.types.js'
+import type { OAuth2CredentialConfig } from '../secret/secret.types.js'
+import type { SecretService } from '../../services/secret-service.js'
+
+/**
+ * OAuth2 client that acts as a service.
+ * Created once in createSingletonServices, handles token caching and refresh internally.
+ * Functions use it directly via oauth.request().
+ *
+ * @example
+ * ```typescript
+ * // In services.ts
+ * export const createSingletonServices = async (config, { secrets }) => {
+ *   return {
+ *     slackOAuth: new OAuth2Client(
+ *       { tokenSecretId: 'SLACK_TOKENS', authorizationUrl: '...', tokenUrl: '...', scopes: [] },
+ *       'SLACK_APP_CREDS',
+ *       secrets
+ *     ),
+ *   }
+ * }
+ *
+ * // In function
+ * export const postMessage = pikkuFunc(async ({ slackOAuth }, { channel, text }) => {
+ *   const response = await slackOAuth.request('https://slack.com/api/chat.postMessage', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ channel, text }),
+ *   })
+ *   return response.json()
+ * })
+ * ```
+ */
+const DEFAULT_TIMEOUT_MS = 30000
+
+/**
+ * Helper to fetch with a timeout using AbortController.
+ */
+async function fetchWithTimeout(
+  url: string,
+  options: RequestInit,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS
+): Promise<Response> {
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+
+  try {
+    return await fetch(url, {
+      ...options,
+      signal: controller.signal,
+    })
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+export class OAuth2Client {
+  private cachedToken: OAuth2Token | null = null
+  private cachedAppCredential: OAuth2AppCredential | null = null
+  private refreshPromise: Promise<OAuth2Token> | null = null
+
+  constructor(
+    private oauth2Config: OAuth2CredentialConfig,
+    private appCredentialSecretId: string,
+    private secrets: SecretService
+  ) {}
+
+  /**
+   * Make an authenticated request. Handles token caching and 401 refresh.
+   */
+  async request(
+    url: string,
+    options?: RequestInit,
+    timeoutMs: number = DEFAULT_TIMEOUT_MS
+  ): Promise<Response> {
+    const token = await this.getAccessToken()
+
+    const response = await fetchWithTimeout(
+      url,
+      {
+        ...options,
+        headers: {
+          ...options?.headers,
+          Authorization: `Bearer ${token}`,
+        },
+      },
+      timeoutMs
+    )
+
+    // Auto-retry on 401 after refresh
+    if (response.status === 401) {
+      const newToken = await this.refreshAndGetToken()
+      return fetchWithTimeout(
+        url,
+        {
+          ...options,
+          headers: {
+            ...options?.headers,
+            Authorization: `Bearer ${newToken}`,
+          },
+        },
+        timeoutMs
+      )
+    }
+
+    return response
+  }
+
+  /**
+   * Get cached token or load from secrets.
+   */
+  async getAccessToken(): Promise<string> {
+    // Return cached token if valid
+    if (this.cachedToken) {
+      if (this.isTokenValid(this.cachedToken)) {
+        return this.cachedToken.accessToken
+      }
+      // Token expired, try to refresh
+      if (this.cachedToken.refreshToken) {
+        return this.refreshAndGetToken()
+      }
+      // Token expired and no refresh token available
+      throw new Error('OAuth2 token expired and no refresh token available')
+    }
+
+    // Load from secrets
+    const token = await this.secrets.getSecretJSON<OAuth2Token>(
+      this.oauth2Config.tokenSecretId
+    )
+    this.cachedToken = token
+
+    // Check if loaded token is expired and needs refresh
+    if (!this.isTokenValid(token)) {
+      if (token.refreshToken) {
+        return this.refreshAndGetToken()
+      }
+      // Token expired and no refresh token available
+      throw new Error('OAuth2 token expired and no refresh token available')
+    }
+
+    return token.accessToken
+  }
+
+  /**
+   * Refresh token and update cache.
+   * Uses a promise lock to prevent concurrent refresh attempts.
+   */
+  private async refreshAndGetToken(): Promise<string> {
+    // If already refreshing, wait for that to complete
+    if (this.refreshPromise) {
+      const token = await this.refreshPromise
+      return token.accessToken
+    }
+
+    // Start refresh
+    this.refreshPromise = this.doRefreshToken()
+
+    try {
+      const token = await this.refreshPromise
+      this.cachedToken = token
+      return token.accessToken
+    } finally {
+      this.refreshPromise = null
+    }
+  }
+
+  /**
+   * Perform the actual token refresh.
+   */
+  private async doRefreshToken(): Promise<OAuth2Token> {
+    if (!this.cachedToken?.refreshToken) {
+      throw new Error('No refresh token available')
+    }
+
+    const appCredential = await this.getAppCredential()
+
+    const params = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: this.cachedToken.refreshToken,
+      client_id: appCredential.clientId,
+    })
+
+    if (appCredential.clientSecret) {
+      params.set('client_secret', appCredential.clientSecret)
+    }
+
+    const response = await fetchWithTimeout(this.oauth2Config.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: params.toString(),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Token refresh failed: ${response.status}`)
+    }
+
+    const data = await response.json()
+
+    if (!data.access_token || typeof data.access_token !== 'string') {
+      throw new Error('Invalid token response: missing access_token')
+    }
+
+    const token: OAuth2Token = {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token || this.cachedToken.refreshToken,
+      expiresAt: data.expires_in
+        ? Date.now() + data.expires_in * 1000
+        : undefined,
+      tokenType: data.token_type || 'Bearer',
+      scope: data.scope,
+    }
+
+    // Cache and persist the refreshed token
+    this.cachedToken = token
+    await this.secrets.setSecretJSON(this.oauth2Config.tokenSecretId, token)
+
+    return token
+  }
+
+  /**
+   * Check if token is valid (not expired).
+   */
+  private isTokenValid(token: OAuth2Token): boolean {
+    if (!token.expiresAt) {
+      return true // No expiry info, assume valid
+    }
+    // Add 60 second buffer to account for clock skew
+    return token.expiresAt > Date.now() + 60000
+  }
+
+  /**
+   * Get app credentials (cached).
+   */
+  private async getAppCredential(): Promise<OAuth2AppCredential> {
+    if (this.cachedAppCredential) {
+      return this.cachedAppCredential
+    }
+    this.cachedAppCredential =
+      await this.secrets.getSecretJSON<OAuth2AppCredential>(
+        this.appCredentialSecretId
+      )
+    return this.cachedAppCredential
+  }
+
+  // ========================================
+  // CLI-only methods (for pikku oauth connect)
+  // ========================================
+
+  /**
+   * Generate OAuth2 authorization URL.
+   * Used by CLI during `pikku oauth connect`.
+   */
+  async getAuthorizationUrl(
+    state: string,
+    redirectUri: string
+  ): Promise<string> {
+    const appCredential = await this.getAppCredential()
+
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id: appCredential.clientId,
+      redirect_uri: redirectUri,
+      scope: this.oauth2Config.scopes.join(' '),
+      state,
+    })
+
+    // Add PKCE if enabled
+    // Note: code_verifier should be stored and passed to exchangeCode
+    // For now, PKCE implementation is simplified
+
+    // Add any additional params
+    if (this.oauth2Config.additionalParams) {
+      for (const [key, value] of Object.entries(
+        this.oauth2Config.additionalParams
+      )) {
+        params.set(key, value)
+      }
+    }
+
+    return `${this.oauth2Config.authorizationUrl}?${params.toString()}`
+  }
+
+  /**
+   * Exchange authorization code for tokens.
+   * Used by CLI during `pikku oauth connect`.
+   */
+  async exchangeCode(code: string, redirectUri: string): Promise<OAuth2Token> {
+    const appCredential = await this.getAppCredential()
+
+    const params = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: redirectUri,
+      client_id: appCredential.clientId,
+    })
+
+    if (appCredential.clientSecret) {
+      params.set('client_secret', appCredential.clientSecret)
+    }
+
+    const response = await fetchWithTimeout(this.oauth2Config.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: params.toString(),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Token exchange failed: ${response.status}`)
+    }
+
+    const data = await response.json()
+
+    if (!data.access_token || typeof data.access_token !== 'string') {
+      throw new Error('Invalid token response: missing access_token')
+    }
+
+    const token: OAuth2Token = {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      expiresAt: data.expires_in
+        ? Date.now() + data.expires_in * 1000
+        : undefined,
+      tokenType: data.token_type || 'Bearer',
+      scope: data.scope,
+    }
+
+    // Cache the token
+    this.cachedToken = token
+
+    return token
+  }
+}

package/src/wirings/oauth2/oauth2.types.ts

@@ -0,0 +1,69 @@
+/**
+ * OAuth2 credential and token types.
+ */
+
+/**
+ * App credentials for OAuth2 (client ID and secret).
+ * These are typically set once and stored in the secret service.
+ */
+export type OAuth2AppCredential = {
+  clientId: string
+  clientSecret?: string // Optional for PKCE flows
+}
+
+/**
+ * OAuth2 token data returned from token endpoint.
+ */
+export type OAuth2Token = {
+  accessToken: string
+  refreshToken?: string
+  expiresAt?: number // Unix timestamp
+  tokenType: string
+  scope?: string
+}
+
+/**
+ * OAuth2-specific configuration that extends a credential.
+ * This is stored in SecretDefinitionMeta.oauth2 field.
+ */
+export type OAuth2Config = {
+  /** Where access/refresh tokens are stored */
+  tokenSecretId: string
+  /** OAuth2 authorization URL */
+  authorizationUrl: string
+  /** OAuth2 token exchange URL */
+  tokenUrl: string
+  /** Required scopes */
+  scopes: string[]
+  /** Use PKCE flow */
+  pkce?: boolean
+  /** Additional query parameters for authorization URL */
+  additionalParams?: Record<string, string>
+}
+
+/**
+ * Configuration for wireOAuth2Credential.
+ * Combines standard credential fields with OAuth2-specific config.
+ */
+export type CoreOAuth2Credential = {
+  /** Unique identifier for this credential */
+  name: string
+  /** Human-readable name for UI display */
+  displayName: string
+  /** Optional description for UI */
+  description?: string
+  /** Key used with SecretService to retrieve app credentials (clientId/clientSecret) */
+  secretId: string
+  /** Where access/refresh tokens are stored */
+  tokenSecretId: string
+  /** OAuth2 authorization URL */
+  authorizationUrl: string
+  /** OAuth2 token exchange URL */
+  tokenUrl: string
+  /** Required scopes */
+  scopes: string[]
+  /** Use PKCE flow */
+  pkce?: boolean
+  /** Additional query parameters for authorization URL */
+  additionalParams?: Record<string, string>
+}

package/src/wirings/oauth2/wire-oauth2-credential.ts

@@ -0,0 +1,23 @@
+import type { CoreOAuth2Credential } from './oauth2.types.js'
+
+/**
+ * No-op function for declaring OAuth2 credentials.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ *
+ * @example
+ * ```typescript
+ * wireOAuth2Credential({
+ *   name: 'slackOAuth',
+ *   displayName: 'Slack OAuth',
+ *   secretId: 'SLACK_OAUTH_APP',
+ *   tokenSecretId: 'SLACK_OAUTH_TOKENS',
+ *   authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+ *   tokenUrl: 'https://slack.com/api/oauth.v2.access',
+ *   scopes: ['chat:write', 'channels:read'],
+ * })
+ * ```
+ */
+export const wireOAuth2Credential = (_config: CoreOAuth2Credential): void => {
+  // No-op - metadata only, extracted by CLI via AST
+}

package/src/wirings/queue/index.ts

@@ -0,0 +1,31 @@
+export type {
+  ConfigValidationResult,
+  CoreQueueWorker,
+  JobOptions,
+  PikkuJobConfig,
+  PikkuWorkerConfig,
+  PikkuQueue,
+  QueueJob,
+  QueueJobStatus,
+  QueueService,
+  QueueWorkers,
+  QueueWorkersMeta,
+} from './queue.types.js'
+
+// Queue processor management
+export {
+  wireQueueWorker,
+  runQueueJob,
+  getQueueWorkers,
+  removeQueueWorker,
+  QueueJobDiscardedError,
+  QueueJobFailedError,
+} from './queue-runner.js'
+
+// Configuration validation
+export { validateWorkerConfig } from './validate-worker-config.js'
+export type { QueueConfigMapping } from './validate-worker-config.js'
+
+// Queue registration helper
+export { registerQueueWorkers } from './register-queue-helper.js'
+export type { QueueRegistrationCallback } from './register-queue-helper.js'