@almadar/integrations 2.23.0 → 2.25.0

package/dist/index.js

@@ -1,16 +1,22 @@
 import { createLogger } from '@almadar/logger';
 import { integratorsRegistry } from '@almadar/core/patterns';
+import { randomBytes, createCipheriv, createDecipheriv, createHmac, createHash } from 'crypto';
 import Stripe from 'stripe';
 import { google } from 'googleapis';
 import twilio from 'twilio';
 import sgMail from '@sendgrid/mail';
 import { Resend } from 'resend';
+import webpush from 'web-push';
+import { Readable } from 'stream';
 import { getAvailableProvider, LLMClient, EmbeddingClient } from '@almadar/llm';
 import { z } from 'zod';
 import { execSync, spawn } from 'child_process';
 import { mkdtempSync, writeFileSync, rmSync, promises } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import * as oidc from 'openid-client';
+import { S3Client, PutObjectCommand, GetObjectCommand, ListObjectsV2Command, DeleteObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { Pool } from 'pg';
 
 // src/types.ts
@@ -221,56 +227,80 @@ function getRegisteredIntegrations() {
 }
 
 // src/factory.ts
+function instanceKey(name, principal) {
+  return principal ? `${name}\0${principal}` : name;
+}
 var IntegrationFactory = class {
   constructor() {
     this.instances = /* @__PURE__ */ new Map();
     this.configs = /* @__PURE__ */ new Map();
   }
   /**
-   * Configure an integration (doesn't instantiate yet)
+   * Configure an integration (doesn't instantiate yet). A `principal` scopes
+   * the config to that principal; the app-wide config (no principal) is the
+   * fallback for every principal.
    */
-  configure(name, config) {
-    this.configs.set(name, { name, ...config });
+  configure(name, config, principal) {
+    this.configs.set(instanceKey(name, principal), { name, ...config });
   }
   /**
-   * Get or create an integration instance
+   * Get or create an integration instance. Principal-scoped lookups fall
+   * back to the app-wide config when no per-principal config exists.
    */
-  get(name) {
-    if (this.instances.has(name)) {
-      return this.instances.get(name);
+  get(name, principal) {
+    const key = instanceKey(name, principal);
+    const cached = this.instances.get(key);
+    if (cached) {
+      return cached;
     }
     const Constructor = getIntegration(name);
     if (!Constructor) {
       throw new Error(`Unknown integration: ${name}. Make sure it's imported.`);
     }
-    const config = this.configs.get(name);
+    const config = this.configs.get(key) ?? this.configs.get(name);
     if (!config) {
       throw new Error(
         `Integration not configured: ${name}. Call configure() first.`
       );
     }
     const instance = new Constructor(config);
-    this.instances.set(name, instance);
+    this.instances.set(key, instance);
     return instance;
   }
   /**
    * Execute an action on an integration
    */
-  async execute(integration, action, params) {
-    const instance = this.get(integration);
+  async execute(integration, action, params, context) {
+    const instance = this.get(integration, context?.principal);
     return await instance.execute(action, params);
   }
   /**
    * Check if integration is configured
    */
-  isConfigured(name) {
-    return this.configs.has(name);
+  isConfigured(name, principal) {
+    return this.configs.has(instanceKey(name, principal)) || this.configs.has(name);
   }
   /**
    * Register an integration instance directly (used by mock infrastructure)
    */
-  registerInstance(name, instance) {
-    this.instances.set(name, instance);
+  registerInstance(name, instance, principal) {
+    this.instances.set(instanceKey(name, principal), instance);
+  }
+  /**
+   * Drop the cached instance(s) for a name so the next `get` rebuilds from
+   * the current config — how a credential change goes live without restart.
+   * Configs are kept; without a name, every instance is dropped.
+   */
+  invalidate(name) {
+    if (name === void 0) {
+      this.instances.clear();
+      return;
+    }
+    for (const key of this.instances.keys()) {
+      if (key === name || key.startsWith(`${name}\0`)) {
+        this.instances.delete(key);
+      }
+    }
   }
   /**
    * Clear all instances (useful for testing)
@@ -297,6 +327,157 @@ function resetIntegrationFactory() {
   _factory?.reset();
   _factory = null;
 }
+var CREDENTIAL_ENTITY_TYPE = "AlmadarIntegrationCredential";
+var CREDENTIAL_MASTER_KEY_ENV = "ALMADAR_CREDENTIAL_MASTER_KEY";
+var ENCRYPTION_ALGORITHM = "aes-256-gcm";
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.length > 0;
+}
+var CredentialStore = class {
+  constructor(adapter, masterKey) {
+    this.byEnvVar = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+    this.warmed = false;
+    this.adapter = adapter;
+    const key = masterKey ?? process.env[CREDENTIAL_MASTER_KEY_ENV];
+    const valid = typeof key === "string" && /^[0-9a-fA-F]{64}$/.test(key);
+    if (!valid && process.env.NODE_ENV === "production") {
+      throw new Error(
+        `${CREDENTIAL_MASTER_KEY_ENV} must be a 64-character hex string (32 bytes) in production \u2014 generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+      );
+    }
+    this.masterKeyHex = valid ? key : void 0;
+  }
+  /** True when a valid master key is present (writes and decryption enabled). */
+  get enabled() {
+    return this.masterKeyHex !== void 0;
+  }
+  /** Subscribe to credential changes; returns an unsubscribe function. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  notify() {
+    for (const listener of this.listeners) listener();
+  }
+  encrypt(plaintext) {
+    if (!this.masterKeyHex) {
+      throw new Error(`${CREDENTIAL_MASTER_KEY_ENV} is not configured \u2014 cannot store credentials`);
+    }
+    const iv = randomBytes(12);
+    const cipher = createCipheriv(ENCRYPTION_ALGORITHM, Buffer.from(this.masterKeyHex, "hex"), iv);
+    let ciphertext = cipher.update(plaintext, "utf8", "hex");
+    ciphertext += cipher.final("hex");
+    return { ciphertext, iv: iv.toString("hex"), authTag: cipher.getAuthTag().toString("hex") };
+  }
+  decrypt(ciphertext, ivHex, authTagHex) {
+    if (!this.masterKeyHex) {
+      throw new Error(`${CREDENTIAL_MASTER_KEY_ENV} is not configured \u2014 cannot decrypt credentials`);
+    }
+    const decipher = createDecipheriv(
+      ENCRYPTION_ALGORITHM,
+      Buffer.from(this.masterKeyHex, "hex"),
+      Buffer.from(ivHex, "hex")
+    );
+    decipher.setAuthTag(Buffer.from(authTagHex, "hex"));
+    let plaintext = decipher.update(ciphertext, "hex", "utf8");
+    plaintext += decipher.final("utf8");
+    return plaintext;
+  }
+  /**
+   * Load and decrypt every stored row into memory. Returns the number of
+   * resolvable credentials. Without a master key nothing decrypts (rows are
+   * left in place, resolution falls through to env).
+   */
+  async warm() {
+    this.byEnvVar.clear();
+    this.warmed = true;
+    if (!this.enabled) return 0;
+    const rows = await this.adapter.list(CREDENTIAL_ENTITY_TYPE);
+    for (const row of rows) {
+      const { id, service, envVar, ciphertext, iv, authTag } = row;
+      if (!isNonEmptyString(id) || !isNonEmptyString(service) || !isNonEmptyString(envVar) || !isNonEmptyString(ciphertext) || !isNonEmptyString(iv) || !isNonEmptyString(authTag)) {
+        continue;
+      }
+      const value = this.decrypt(ciphertext, iv, authTag);
+      this.byEnvVar.set(envVar, {
+        id,
+        service,
+        envVar,
+        value,
+        last4: value.slice(-4),
+        updatedAt: typeof row.updatedAt === "number" ? row.updatedAt : 0
+      });
+    }
+    return this.byEnvVar.size;
+  }
+  /** Resolve one credential by env-var name (warmed values only). */
+  resolve(envVar) {
+    return this.byEnvVar.get(envVar)?.value;
+  }
+  /** All warmed values as an env-shaped map, for merging over the process env. */
+  snapshotEnv() {
+    const env = {};
+    for (const [envVar, entry] of this.byEnvVar) env[envVar] = entry.value;
+    return env;
+  }
+  /** Masked entries for display — never includes plaintext. */
+  entries() {
+    return Array.from(this.byEnvVar.values()).map(({ service, envVar, last4, updatedAt }) => ({ service, envVar, last4, updatedAt })).sort((a, b) => a.service.localeCompare(b.service) || a.envVar.localeCompare(b.envVar));
+  }
+  /** Upsert one credential (encrypts, persists, re-warms the entry, notifies). */
+  async set(service, envVar, value) {
+    if (!this.warmed) await this.warm();
+    const { ciphertext, iv, authTag } = this.encrypt(value);
+    const updatedAt = Date.now();
+    const existing = this.byEnvVar.get(envVar);
+    const data = { service, envVar, ciphertext, iv, authTag, updatedAt };
+    let id;
+    if (existing) {
+      id = existing.id;
+      await this.adapter.update(CREDENTIAL_ENTITY_TYPE, id, data);
+    } else {
+      ({ id } = await this.adapter.create(CREDENTIAL_ENTITY_TYPE, data));
+    }
+    const entry = { id, service, envVar, value, last4: value.slice(-4), updatedAt };
+    this.byEnvVar.set(envVar, entry);
+    this.notify();
+    const { service: s, envVar: e, last4, updatedAt: u } = entry;
+    return { service: s, envVar: e, last4, updatedAt: u };
+  }
+  /** Delete one credential row; resolution falls back to env afterwards. */
+  async remove(envVar) {
+    if (!this.warmed) await this.warm();
+    const existing = this.byEnvVar.get(envVar);
+    if (!existing) return false;
+    await this.adapter.delete(CREDENTIAL_ENTITY_TYPE, existing.id);
+    this.byEnvVar.delete(envVar);
+    this.notify();
+    return true;
+  }
+};
+
+// src/credentials/resolver.ts
+var installedStore = null;
+var activeFactory = null;
+function installActiveFactory(factory) {
+  activeFactory = factory;
+}
+function getActiveFactory() {
+  return activeFactory;
+}
+function installCredentialStore(store) {
+  installedStore = store;
+}
+function getInstalledCredentialStore() {
+  return installedStore;
+}
+function uninstallCredentialStore() {
+  installedStore = null;
+}
+function resolveCredentialRef(ref, env = process.env) {
+  return installedStore?.resolve(ref) ?? env[ref];
+}
 var STRIPE_API_VERSION = "2025-02-24.acacia";
 function priceToTier(priceId, prices) {
   if (priceId === prices.solo) return "solo";
@@ -874,40 +1055,1020 @@ var TwilioIntegration = class extends BaseIntegration {
       status: message.status
     };
   }
-  async sendWhatsApp(params) {
-    const { to, body } = params;
-    this.logger.debug("Sending WhatsApp message", { to: String(to ?? "") });
-    const message = await this.client.messages.create({
-      from: `whatsapp:${this.phoneNumber}`,
-      to: `whatsapp:${to}`,
-      body
+  async sendWhatsApp(params) {
+    const { to, body } = params;
+    this.logger.debug("Sending WhatsApp message", { to: String(to ?? "") });
+    const message = await this.client.messages.create({
+      from: `whatsapp:${this.phoneNumber}`,
+      to: `whatsapp:${to}`,
+      body
+    });
+    return {
+      sid: message.sid,
+      status: message.status
+    };
+  }
+};
+registerIntegration("twilio", TwilioIntegration);
+var EmailIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    this.provider = config.env.PROVIDER || "sendgrid";
+    this.fromEmail = config.env.FROM_EMAIL || "noreply@example.com";
+    if (this.provider === "sendgrid") {
+      const apiKey = config.env.SENDGRID_API_KEY;
+      if (!apiKey) {
+        throw new Error("SENDGRID_API_KEY not configured");
+      }
+      sgMail.setApiKey(apiKey);
+    } else if (this.provider === "resend") {
+      const apiKey = config.env.RESEND_API_KEY;
+      if (!apiKey) {
+        throw new Error("RESEND_API_KEY not configured");
+      }
+      this.resendClient = new Resend(apiKey);
+    }
+    this.logger.info(`Email integration initialized (${this.provider})`);
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    let retries = 0;
+    try {
+      let data;
+      switch (action) {
+        case "send":
+          data = await this.executeWithRetry(() => this.send(params));
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime, retries)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  async send(params) {
+    const { to, subject, body, from } = params;
+    this.logger.debug("Sending email", { to: String(to), subject: String(subject), provider: this.provider });
+    if (this.provider === "sendgrid") {
+      return await this.sendViaSendGrid(
+        to,
+        subject,
+        body,
+        from || this.fromEmail
+      );
+    } else if (this.provider === "resend") {
+      return await this.sendViaResend(
+        to,
+        subject,
+        body,
+        from || this.fromEmail
+      );
+    }
+    throw new Error(`Unknown email provider: ${this.provider}`);
+  }
+  async sendViaSendGrid(to, subject, body, from) {
+    const msg = {
+      to,
+      from,
+      subject,
+      html: body
+    };
+    const response = await sgMail.send(msg);
+    return {
+      id: response[0].headers["x-message-id"],
+      status: "sent"
+    };
+  }
+  async sendViaResend(to, subject, body, from) {
+    if (!this.resendClient) {
+      throw new Error("Resend client not initialized");
+    }
+    const response = await this.resendClient.emails.send({
+      from,
+      to,
+      subject,
+      html: body
+    });
+    return {
+      id: response.data?.id,
+      status: "sent"
+    };
+  }
+};
+registerIntegration("email", EmailIntegration);
+var WebhookIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    this.signingSecret = config.env.WEBHOOK_SIGNING_SECRET || "";
+    this.timeoutMs = Number(config.env.WEBHOOK_TIMEOUT_MS) || 1e4;
+    this.logger.info("Webhook integration initialized");
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    let retries = 0;
+    try {
+      let data;
+      switch (action) {
+        case "send":
+          data = await this.executeWithRetry(() => this.send(params));
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime, retries)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  async send(params) {
+    const { url, event, payload, secret } = params;
+    const body = JSON.stringify({
+      event,
+      payload: payload ?? {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Almadar-Event": event
+    };
+    const signingSecret = secret || this.signingSecret;
+    if (signingSecret) {
+      headers["X-Almadar-Signature"] = "sha256=" + createHmac("sha256", signingSecret).update(body).digest("hex");
+    }
+    this.logger.debug("Sending webhook", { url: String(url), event: String(event) });
+    const startTime = Date.now();
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (response.status >= 500) {
+      throw new Error(`Webhook endpoint returned ${response.status}`);
+    }
+    return {
+      status: response.status,
+      ok: response.ok,
+      durationMs: Date.now() - startTime
+    };
+  }
+};
+registerIntegration("webhook", WebhookIntegration);
+function isParamRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
+}
+function toSubscription(value) {
+  if (isParamRecord(value)) {
+    const { endpoint, keys } = value;
+    if (typeof endpoint === "string" && isParamRecord(keys)) {
+      const { p256dh, auth } = keys;
+      if (typeof p256dh === "string" && typeof auth === "string") {
+        return { endpoint, keys: { p256dh, auth } };
+      }
+    }
+  }
+  throw new Error("push.send: subscription must be { endpoint, keys: { p256dh, auth } }");
+}
+var PushIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    this.vapidPublicKey = config.env.VAPID_PUBLIC_KEY || "";
+    this.vapidPrivateKey = config.env.VAPID_PRIVATE_KEY || "";
+    this.vapidSubject = config.env.VAPID_SUBJECT || "";
+    this.logger.info("Push integration initialized");
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    let retries = 0;
+    try {
+      let data;
+      switch (action) {
+        case "send":
+          data = await this.executeWithRetry(() => this.send(params));
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime, retries)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  async send(params) {
+    const { subscription, title, body, url, icon } = params;
+    const sub = toSubscription(subscription);
+    const payload = JSON.stringify({
+      title,
+      body,
+      url: url || void 0,
+      icon: icon || void 0
+    });
+    this.logger.debug("Sending push notification", { endpoint: sub.endpoint });
+    try {
+      const response = await webpush.sendNotification(sub, payload, {
+        vapidDetails: {
+          subject: this.vapidSubject,
+          publicKey: this.vapidPublicKey,
+          privateKey: this.vapidPrivateKey
+        }
+      });
+      return { statusCode: response.statusCode, ok: true, expired: false };
+    } catch (error) {
+      if (error instanceof webpush.WebPushError) {
+        if (error.statusCode >= 500) {
+          throw new Error(`Push endpoint returned ${error.statusCode}`);
+        }
+        return {
+          statusCode: error.statusCode,
+          ok: false,
+          expired: error.statusCode === 404 || error.statusCode === 410
+        };
+      }
+      throw error;
+    }
+  }
+};
+registerIntegration("push", PushIntegration);
+
+// src/integrations/calendar/webhooks.ts
+function header(headers, name) {
+  const direct = headers[name] ?? headers[name.toLowerCase()];
+  if (direct !== void 0) return direct;
+  const found = Object.keys(headers).find((k) => k.toLowerCase() === name.toLowerCase());
+  return (found !== void 0 ? headers[found] : void 0) ?? "";
+}
+function parseCalendarPushNotification(headers, expectedToken) {
+  const channelId = header(headers, "x-goog-channel-id");
+  const resourceId = header(headers, "x-goog-resource-id");
+  const resourceState = header(headers, "x-goog-resource-state");
+  if (!channelId || !resourceId || !resourceState) {
+    return { error: "missing-headers" };
+  }
+  if (expectedToken && header(headers, "x-goog-channel-token") !== expectedToken) {
+    return { error: "bad-token" };
+  }
+  return {
+    type: "calendar.changed",
+    channelId,
+    resourceId,
+    resourceState,
+    messageNumber: Number(header(headers, "x-goog-message-number")) || 0
+  };
+}
+function googleCalendarHookProvider(expectedToken) {
+  return (input) => {
+    const parsed = parseCalendarPushNotification(input.headers, expectedToken);
+    if ("error" in parsed) return { error: parsed.error };
+    if (parsed.resourceState === "sync") return { ack: true };
+    return {
+      event: "CAL_REMOTE_CHANGED",
+      payload: {
+        channelId: parsed.channelId,
+        resourceId: parsed.resourceId,
+        resourceState: parsed.resourceState
+      }
+    };
+  };
+}
+var CalendarIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    const rawKey = config.env.GOOGLE_CALENDAR_SA_KEY;
+    if (!rawKey) {
+      throw new Error("GOOGLE_CALENDAR_SA_KEY not configured");
+    }
+    const keyJson = rawKey.trim().startsWith("{") ? rawKey : Buffer.from(rawKey, "base64").toString("utf8");
+    const key = JSON.parse(keyJson);
+    const subject = config.env.GOOGLE_CALENDAR_SUBJECT || void 0;
+    const auth = new google.auth.JWT({
+      email: key.client_email,
+      key: key.private_key,
+      scopes: ["https://www.googleapis.com/auth/calendar"],
+      subject
+    });
+    this.client = google.calendar({ version: "v3", auth });
+    this.defaultCalendarId = config.env.GOOGLE_CALENDAR_ID || "primary";
+    this.logger.info("Calendar integration initialized", {
+      delegated: Boolean(subject)
+    });
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    let retries = 0;
+    try {
+      let data;
+      switch (action) {
+        case "listEvents":
+          data = await this.executeWithRetry(() => this.listEvents(params));
+          break;
+        case "createEvent":
+          data = await this.executeWithRetry(() => this.createEvent(params));
+          break;
+        case "updateEvent":
+          data = await this.executeWithRetry(() => this.updateEvent(params));
+          break;
+        case "deleteEvent":
+          data = await this.executeWithRetry(() => this.deleteEvent(params));
+          break;
+        case "freeBusy":
+          data = await this.executeWithRetry(() => this.freeBusy(params));
+          break;
+        case "watch":
+          data = await this.executeWithRetry(() => this.watch(params));
+          break;
+        case "stopWatch":
+          data = await this.executeWithRetry(() => this.stopWatch(params));
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime, retries)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  calendarId(params) {
+    return params.calendarId || this.defaultCalendarId;
+  }
+  toEventTime(value) {
+    return value.length === 10 ? { date: value } : { dateTime: value };
+  }
+  fromEventTime(time) {
+    return time?.dateTime ?? time?.date ?? "";
+  }
+  async listEvents(params) {
+    const { timeMin, timeMax, syncToken, maxResults } = params;
+    const response = await this.client.events.list({
+      calendarId: this.calendarId(params),
+      // Incremental sync: a syncToken supersedes the window params (the API
+      // rejects combining them).
+      ...syncToken ? { syncToken } : {
+        timeMin: timeMin || void 0,
+        timeMax: timeMax || void 0,
+        singleEvents: true,
+        orderBy: "startTime"
+      },
+      maxResults: maxResults || 250
+    });
+    const items = response.data.items ?? [];
+    return {
+      events: items.map((event) => ({
+        id: event.id ?? "",
+        summary: event.summary ?? "",
+        description: event.description ?? "",
+        location: event.location ?? "",
+        start: this.fromEventTime(event.start ?? void 0),
+        end: this.fromEventTime(event.end ?? void 0),
+        status: event.status ?? "",
+        updated: event.updated ?? ""
+      })),
+      nextSyncToken: response.data.nextSyncToken ?? null
+    };
+  }
+  resolveEnd(start, end, durationMinutes) {
+    if (end) return end;
+    if (start.length === 10) {
+      const next = new Date(Date.parse(start) + 24 * 60 * 6e4);
+      return next.toISOString().slice(0, 10);
+    }
+    if (durationMinutes && durationMinutes > 0) {
+      return new Date(Date.parse(start) + durationMinutes * 6e4).toISOString();
+    }
+    throw new Error("createEvent requires `end` or a positive `durationMinutes`");
+  }
+  async createEvent(params) {
+    const { summary, description, location, start, end, durationMinutes } = params;
+    const response = await this.client.events.insert({
+      calendarId: this.calendarId(params),
+      requestBody: {
+        summary,
+        description: description || void 0,
+        location: location || void 0,
+        start: this.toEventTime(start),
+        end: this.toEventTime(
+          this.resolveEnd(start, end || void 0, durationMinutes || void 0)
+        )
+      }
+    });
+    return {
+      id: response.data.id ?? "",
+      status: response.data.status ?? "",
+      htmlLink: response.data.htmlLink ?? ""
+    };
+  }
+  async updateEvent(params) {
+    const { eventId, summary, description, location, start, end } = params;
+    const requestBody = {};
+    if (typeof summary === "string") requestBody.summary = summary;
+    if (typeof description === "string") requestBody.description = description;
+    if (typeof location === "string") requestBody.location = location;
+    if (typeof start === "string" && start) requestBody.start = this.toEventTime(start);
+    if (typeof end === "string" && end) requestBody.end = this.toEventTime(end);
+    const response = await this.client.events.patch({
+      calendarId: this.calendarId(params),
+      eventId,
+      requestBody
+    });
+    return {
+      id: response.data.id ?? "",
+      status: response.data.status ?? ""
+    };
+  }
+  async deleteEvent(params) {
+    const { eventId } = params;
+    await this.client.events.delete({
+      calendarId: this.calendarId(params),
+      eventId
+    });
+    return { id: eventId, deleted: true };
+  }
+  async freeBusy(params) {
+    const { timeMin, timeMax } = params;
+    const id = this.calendarId(params);
+    const response = await this.client.freebusy.query({
+      requestBody: {
+        timeMin,
+        timeMax,
+        items: [{ id }]
+      }
+    });
+    const busy = response.data.calendars?.[id]?.busy ?? [];
+    return {
+      busy: busy.map((slot) => ({ start: slot.start ?? "", end: slot.end ?? "" }))
+    };
+  }
+  async watch(params) {
+    const { channelId, address, ttlSeconds } = params;
+    const response = await this.client.events.watch({
+      calendarId: this.calendarId(params),
+      requestBody: {
+        id: channelId,
+        type: "web_hook",
+        address,
+        params: ttlSeconds ? { ttl: String(ttlSeconds) } : void 0
+      }
+    });
+    return {
+      channelId: response.data.id ?? channelId,
+      resourceId: response.data.resourceId ?? "",
+      expiration: response.data.expiration ?? ""
+    };
+  }
+  async stopWatch(params) {
+    const { channelId, resourceId } = params;
+    await this.client.channels.stop({
+      requestBody: {
+        id: channelId,
+        resourceId
+      }
+    });
+    return { stopped: true };
+  }
+};
+registerIntegration("calendar", CalendarIntegration);
+function decodeContent(content) {
+  const dataUrlMatch = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(content);
+  if (dataUrlMatch) {
+    const [, mime, isB64, body] = dataUrlMatch;
+    const bytes = isB64 ? Buffer.from(body, "base64") : Buffer.from(decodeURIComponent(body), "utf8");
+    return { bytes, contentType: mime || null };
+  }
+  return { bytes: Buffer.from(content, "utf8"), contentType: null };
+}
+var DriveIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    const rawKey = config.env.GOOGLE_DRIVE_SA_KEY;
+    if (!rawKey) {
+      throw new Error("GOOGLE_DRIVE_SA_KEY not configured");
+    }
+    const keyJson = rawKey.trim().startsWith("{") ? rawKey : Buffer.from(rawKey, "base64").toString("utf8");
+    const key = JSON.parse(keyJson);
+    const subject = config.env.GOOGLE_DRIVE_SUBJECT || void 0;
+    const auth = new google.auth.JWT({
+      email: key.client_email,
+      key: key.private_key,
+      scopes: ["https://www.googleapis.com/auth/drive"],
+      subject
+    });
+    this.client = google.drive({ version: "v3", auth });
+    this.logger.info("Drive integration initialized", { delegated: Boolean(subject) });
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    try {
+      let data;
+      switch (action) {
+        case "listFiles":
+          data = await this.executeWithRetry(() => this.listFiles(params));
+          break;
+        case "getFile":
+          data = await this.executeWithRetry(() => this.getFile(params));
+          break;
+        case "uploadFile":
+          data = await this.executeWithRetry(() => this.uploadFile(params));
+          break;
+        case "createFolder":
+          data = await this.executeWithRetry(() => this.createFolder(params));
+          break;
+        case "shareFile":
+          data = await this.executeWithRetry(() => this.shareFile(params));
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  async listFiles(params) {
+    const { folderId, query, maxResults } = params;
+    const clauses = ["trashed = false"];
+    if (folderId) clauses.push(`'${String(folderId).replace(/'/g, "\\'")}' in parents`);
+    if (query) clauses.push(String(query));
+    const response = await this.client.files.list({
+      q: clauses.join(" and "),
+      pageSize: maxResults || 100,
+      fields: "files(id, name, mimeType, size, modifiedTime, webViewLink)"
+    });
+    return {
+      files: (response.data.files ?? []).map((file) => ({
+        id: file.id ?? "",
+        name: file.name ?? "",
+        mimeType: file.mimeType ?? "",
+        size: Number(file.size ?? 0),
+        modifiedTime: file.modifiedTime ?? "",
+        webViewLink: file.webViewLink ?? ""
+      }))
+    };
+  }
+  async getFile(params) {
+    const fileId = params.fileId;
+    const meta = await this.client.files.get({
+      fileId,
+      fields: "id, name, mimeType, size"
+    });
+    const content = await this.client.files.get(
+      { fileId, alt: "media" },
+      { responseType: "arraybuffer" }
+    );
+    const bytes = Buffer.from(content.data);
+    return {
+      id: meta.data.id ?? fileId,
+      name: meta.data.name ?? "",
+      mimeType: meta.data.mimeType ?? "application/octet-stream",
+      content: bytes.toString("base64"),
+      size: bytes.length
+    };
+  }
+  async uploadFile(params) {
+    const { name, content, mimeType, folderId } = params;
+    const { bytes, contentType } = decodeContent(content);
+    const response = await this.client.files.create({
+      requestBody: {
+        name,
+        parents: folderId ? [folderId] : void 0
+      },
+      media: {
+        mimeType: mimeType || contentType || "application/octet-stream",
+        body: Readable.from(bytes)
+      },
+      fields: "id, name, webViewLink"
+    });
+    return {
+      id: response.data.id ?? "",
+      name: response.data.name ?? name,
+      webViewLink: response.data.webViewLink ?? ""
+    };
+  }
+  async createFolder(params) {
+    const { name, parentId } = params;
+    const response = await this.client.files.create({
+      requestBody: {
+        name,
+        mimeType: "application/vnd.google-apps.folder",
+        parents: parentId ? [parentId] : void 0
+      },
+      fields: "id, name"
+    });
+    return { id: response.data.id ?? "", name: response.data.name ?? name };
+  }
+  async shareFile(params) {
+    const { fileId, email, role } = params;
+    const response = await this.client.permissions.create({
+      fileId,
+      requestBody: {
+        type: "user",
+        role: role || "reader",
+        emailAddress: email
+      },
+      fields: "id"
+    });
+    return { shared: true, permissionId: response.data.id ?? "" };
+  }
+};
+registerIntegration("drive", DriveIntegration);
+
+// src/integrations/metaAds/index.ts
+var GRAPH_BASE = "https://graph.facebook.com/v21.0";
+var MetaAdsIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    this.accessToken = config.env.META_ACCESS_TOKEN || "";
+    if (!this.accessToken) {
+      throw new Error("META_ACCESS_TOKEN not configured");
+    }
+    this.defaultAccountId = config.env.META_AD_ACCOUNT_ID || "";
+    this.logger.info("Meta Ads integration initialized");
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    try {
+      let data;
+      switch (action) {
+        case "getSpend":
+          data = await this.executeWithRetry(() => this.getSpend(params));
+          break;
+        case "listCampaigns":
+          data = await this.executeWithRetry(() => this.listCampaigns(params));
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  accountId(params) {
+    const id = params.accountId || this.defaultAccountId;
+    if (!id) {
+      throw new Error("No ad account: pass `accountId` or set META_AD_ACCOUNT_ID");
+    }
+    return id.startsWith("act_") ? id : `act_${id}`;
+  }
+  async graphGet(path, query) {
+    const url = new URL(`${GRAPH_BASE}/${path}`);
+    for (const [key, value] of Object.entries(query)) {
+      url.searchParams.set(key, value);
+    }
+    url.searchParams.set("access_token", this.accessToken);
+    const response = await fetch(url, { signal: AbortSignal.timeout(15e3) });
+    if (response.status >= 500) {
+      throw new Error(`Meta Graph API returned ${response.status}`);
+    }
+    const body = await response.json();
+    if (!response.ok) {
+      throw new Error(`Meta Graph API error: ${body.error?.message ?? response.status}`);
+    }
+    return body.data ?? body;
+  }
+  async getSpend(params) {
+    const { since, until } = params;
+    const rows = await this.graphGet(`${this.accountId(params)}/insights`, {
+      fields: "spend,impressions,clicks,account_currency",
+      time_range: JSON.stringify({ since, until }),
+      level: "account"
+    });
+    const row = Array.isArray(rows) ? rows[0] : void 0;
+    return {
+      spend: Number(row?.spend ?? 0),
+      currency: row?.account_currency ?? "",
+      impressions: Number(row?.impressions ?? 0),
+      clicks: Number(row?.clicks ?? 0)
+    };
+  }
+  async listCampaigns(params) {
+    const { status } = params;
+    const rows = await this.graphGet(`${this.accountId(params)}/campaigns`, {
+      fields: "id,name,status,daily_budget",
+      ...status ? { effective_status: JSON.stringify([status]) } : {}
+    });
+    return {
+      campaigns: (Array.isArray(rows) ? rows : []).map((row) => ({
+        id: row.id ?? "",
+        name: row.name ?? "",
+        status: row.status ?? "",
+        // Meta reports budgets in minor units (cents).
+        dailyBudget: Number(row.daily_budget ?? 0) / 100
+      }))
+    };
+  }
+};
+registerIntegration("metaAds", MetaAdsIntegration);
+
+// src/integrations/accounting/index.ts
+var AccountingIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    this.logger.info("Accounting integration initialized (generic CSV export)");
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    try {
+      let data;
+      switch (action) {
+        case "exportInvoices":
+          data = this.exportRows(params.invoices, INVOICE_COLUMNS, "invoices");
+          break;
+        case "exportJournal":
+          data = this.exportRows(params.entries, JOURNAL_COLUMNS, "journal");
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  exportRows(rowsValue, columns, kind) {
+    if (!Array.isArray(rowsValue)) {
+      throw new Error(`${kind} export requires an array of rows`);
+    }
+    const lines = [columns.join(",")];
+    for (const row of rowsValue) {
+      if (row === null || typeof row !== "object" || Array.isArray(row) || row instanceof Date) {
+        throw new Error(`${kind} export: every row must be an object`);
+      }
+      const record = row;
+      lines.push(columns.map((column) => csvCell(record[column])).join(","));
+    }
+    const stamp = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    return {
+      content: lines.join("\r\n") + "\r\n",
+      filename: `${kind}-export-${stamp}.csv`,
+      count: rowsValue.length
+    };
+  }
+};
+var INVOICE_COLUMNS = ["id", "number", "customer", "issuedAt", "dueAt", "currency", "net", "tax", "gross", "status"];
+var JOURNAL_COLUMNS = ["date", "account", "description", "debit", "credit", "reference"];
+function csvCell(value) {
+  if (value === void 0 || value === null) return "";
+  const raw = value instanceof Date ? value.toISOString() : String(value);
+  return /[",\r\n]/.test(raw) ? `"${raw.replace(/"/g, '""')}"` : raw;
+}
+registerIntegration("accounting", AccountingIntegration);
+
+// src/integrations/banking/index.ts
+var GC_BASE = "https://bankaccountdata.gocardless.com/api/v2";
+var BankingIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    this.accessToken = null;
+    this.accessTokenExpiresAt = 0;
+    this.secretId = config.env.GOCARDLESS_SECRET_ID || "";
+    this.secretKey = config.env.GOCARDLESS_SECRET_KEY || "";
+    if (!this.secretId || !this.secretKey) {
+      throw new Error("GOCARDLESS_SECRET_ID / GOCARDLESS_SECRET_KEY not configured");
+    }
+    this.logger.info("Banking integration initialized (GoCardless Bank Account Data)");
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    try {
+      let data;
+      switch (action) {
+        case "createRequisition":
+          data = await this.executeWithRetry(() => this.createRequisition(params));
+          break;
+        case "listAccounts":
+          data = await this.executeWithRetry(() => this.listAccounts(params));
+          break;
+        case "listTransactions":
+          data = await this.executeWithRetry(() => this.listTransactions(params));
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  async token() {
+    if (this.accessToken && Date.now() < this.accessTokenExpiresAt - 6e4) {
+      return this.accessToken;
+    }
+    const response = await fetch(`${GC_BASE}/token/new/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({ secret_id: this.secretId, secret_key: this.secretKey }),
+      signal: AbortSignal.timeout(15e3)
+    });
+    if (!response.ok) {
+      throw new Error(`GoCardless token request failed: ${response.status}`);
+    }
+    const body = await response.json();
+    this.accessToken = body.access;
+    this.accessTokenExpiresAt = Date.now() + body.access_expires * 1e3;
+    return this.accessToken;
+  }
+  async gcRequest(path, init2) {
+    const response = await fetch(`${GC_BASE}${path}`, {
+      method: init2?.method ?? "GET",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${await this.token()}`
+      },
+      body: init2?.body === void 0 ? void 0 : JSON.stringify(init2.body),
+      signal: AbortSignal.timeout(2e4)
+    });
+    if (response.status >= 500) {
+      throw new Error(`GoCardless returned ${response.status}`);
+    }
+    const body = await response.json();
+    if (!response.ok) {
+      throw new Error(`GoCardless error ${response.status}: ${JSON.stringify(body).slice(0, 300)}`);
+    }
+    return body;
+  }
+  async createRequisition(params) {
+    const { institutionId, redirectUrl, reference } = params;
+    const body = await this.gcRequest("/requisitions/", {
+      method: "POST",
+      body: {
+        institution_id: institutionId,
+        redirect: redirectUrl,
+        reference: reference || void 0
+      }
     });
+    return { requisitionId: body.id ?? "", link: body.link ?? "" };
+  }
+  async listAccounts(params) {
+    const { requisitionId } = params;
+    const body = await this.gcRequest(`/requisitions/${requisitionId}/`);
+    return { accounts: body.accounts ?? [] };
+  }
+  async listTransactions(params) {
+    const { accountId, dateFrom, dateTo } = params;
+    const query = new URLSearchParams();
+    if (dateFrom) query.set("date_from", dateFrom);
+    if (dateTo) query.set("date_to", dateTo);
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    const body = await this.gcRequest(`/accounts/${accountId}/transactions/${suffix}`);
     return {
-      sid: message.sid,
-      status: message.status
+      transactions: (body.transactions?.booked ?? []).map((tx) => ({
+        id: tx.transactionId ?? tx.internalTransactionId ?? "",
+        amount: Number(tx.transactionAmount?.amount ?? 0),
+        currency: tx.transactionAmount?.currency ?? "",
+        date: tx.bookingDate ?? "",
+        description: tx.remittanceInformationUnstructured ?? "",
+        counterparty: tx.creditorName ?? tx.debtorName ?? ""
+      }))
     };
   }
 };
-registerIntegration("twilio", TwilioIntegration);
-var EmailIntegration = class extends BaseIntegration {
+registerIntegration("banking", BankingIntegration);
+
+// src/integrations/esign/index.ts
+var EsignIntegration = class extends BaseIntegration {
   constructor(config) {
     super(config);
-    this.provider = config.env.PROVIDER || "sendgrid";
-    this.fromEmail = config.env.FROM_EMAIL || "noreply@example.com";
-    if (this.provider === "sendgrid") {
-      const apiKey = config.env.SENDGRID_API_KEY;
-      if (!apiKey) {
-        throw new Error("SENDGRID_API_KEY not configured");
-      }
-      sgMail.setApiKey(apiKey);
-    } else if (this.provider === "resend") {
-      const apiKey = config.env.RESEND_API_KEY;
-      if (!apiKey) {
-        throw new Error("RESEND_API_KEY not configured");
-      }
-      this.resendClient = new Resend(apiKey);
+    if (!config.env.DOCUSIGN_BASE_URL || !config.env.DOCUSIGN_ACCESS_TOKEN) {
+      throw new Error("DOCUSIGN_BASE_URL / DOCUSIGN_ACCESS_TOKEN not configured");
     }
-    this.logger.info(`Email integration initialized (${this.provider})`);
+    this.logger.info("E-sign integration initialized (DocuSign)");
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
@@ -924,12 +2085,17 @@ var EmailIntegration = class extends BaseIntegration {
       };
     }
     const startTime = Date.now();
-    let retries = 0;
     try {
       let data;
       switch (action) {
-        case "send":
-          data = await this.executeWithRetry(() => this.send(params));
+        case "sendEnvelope":
+          data = await this.executeWithRetry(() => this.sendEnvelope(params));
+          break;
+        case "getEnvelopeStatus":
+          data = await this.executeWithRetry(() => this.getEnvelopeStatus(params));
+          break;
+        case "downloadDocument":
+          data = await this.executeWithRetry(() => this.downloadDocument(params));
           break;
         default:
           throw new Error(`Unknown action: ${action}`);
@@ -937,62 +2103,81 @@ var EmailIntegration = class extends BaseIntegration {
       return {
         success: true,
         data,
-        metadata: this.createMetadata(action, Date.now() - startTime, retries)
+        metadata: this.createMetadata(action, Date.now() - startTime)
       };
     } catch (error) {
       return this.handleError(action, error);
     }
   }
-  async send(params) {
-    const { to, subject, body, from } = params;
-    this.logger.debug("Sending email", { to: String(to), subject: String(subject), provider: this.provider });
-    if (this.provider === "sendgrid") {
-      return await this.sendViaSendGrid(
-        to,
-        subject,
-        body,
-        from || this.fromEmail
-      );
-    } else if (this.provider === "resend") {
-      return await this.sendViaResend(
-        to,
-        subject,
-        body,
-        from || this.fromEmail
-      );
+  async dsRequest(path, init2) {
+    const base = this.config.env.DOCUSIGN_BASE_URL.replace(/\/$/, "");
+    const response = await fetch(`${base}${path}`, {
+      method: init2?.method ?? "GET",
+      headers: {
+        Accept: init2?.raw ? "application/pdf" : "application/json",
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.env.DOCUSIGN_ACCESS_TOKEN}`
+      },
+      body: init2?.body === void 0 ? void 0 : JSON.stringify(init2.body),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (response.status >= 500) {
+      throw new Error(`DocuSign returned ${response.status}`);
     }
-    throw new Error(`Unknown email provider: ${this.provider}`);
+    if (!response.ok) {
+      const detail = await response.text();
+      throw new Error(`DocuSign error ${response.status}: ${detail.slice(0, 300)}`);
+    }
+    if (init2?.raw) {
+      return Buffer.from(await response.arrayBuffer());
+    }
+    return response.json();
   }
-  async sendViaSendGrid(to, subject, body, from) {
-    const msg = {
-      to,
-      from,
-      subject,
-      html: body
-    };
-    const response = await sgMail.send(msg);
-    return {
-      id: response[0].headers["x-message-id"],
-      status: "sent"
-    };
+  async sendEnvelope(params) {
+    const { recipientEmail, recipientName, documentName, documentContent, emailSubject } = params;
+    const rawContent = documentContent;
+    const base64 = rawContent.startsWith("data:") ? rawContent.slice(rawContent.indexOf(",") + 1) : rawContent;
+    const body = await this.dsRequest("/envelopes", {
+      method: "POST",
+      body: {
+        emailSubject: emailSubject || `Please sign: ${documentName}`,
+        status: "sent",
+        documents: [
+          {
+            documentBase64: base64,
+            name: documentName,
+            fileExtension: String(documentName).split(".").pop() || "pdf",
+            documentId: "1"
+          }
+        ],
+        recipients: {
+          signers: [
+            {
+              email: recipientEmail,
+              name: recipientName,
+              recipientId: "1",
+              routingOrder: "1"
+            }
+          ]
+        }
+      }
+    });
+    return { envelopeId: body.envelopeId ?? "", status: body.status ?? "sent" };
   }
-  async sendViaResend(to, subject, body, from) {
-    if (!this.resendClient) {
-      throw new Error("Resend client not initialized");
-    }
-    const response = await this.resendClient.emails.send({
-      from,
-      to,
-      subject,
-      html: body
+  async getEnvelopeStatus(params) {
+    const { envelopeId } = params;
+    const body = await this.dsRequest(`/envelopes/${envelopeId}`);
+    return { status: body.status ?? "", completedAt: body.completedDateTime ?? "" };
+  }
+  async downloadDocument(params) {
+    const { envelopeId } = params;
+    const bytes = await this.dsRequest(`/envelopes/${envelopeId}/documents/combined`, {
+      raw: true
     });
-    return {
-      id: response.data?.id,
-      status: "sent"
-    };
+    return { content: bytes.toString("base64"), documentName: `envelope-${envelopeId}.pdf` };
   }
 };
-registerIntegration("email", EmailIntegration);
+registerIntegration("esign", EsignIntegration);
 var LLMIntegration = class extends BaseIntegration {
   constructor(config) {
     super(config);
@@ -2563,25 +3748,35 @@ var OtelIntegration = class extends BaseIntegration {
   }
 };
 registerIntegration("otel", OtelIntegration);
-
-// src/integrations/oauth/index.ts
 var PROVIDER_AUTH_URLS = {
   google: "https://accounts.google.com/o/oauth2/v2/auth",
   github: "https://github.com/login/oauth/authorize",
   auth0: "https://auth.example.com/authorize"
 };
+var PROVIDER_ISSUERS = {
+  google: "https://accounts.google.com"
+};
 var OAuthIntegration = class extends BaseIntegration {
   constructor(config) {
     super(config);
-    /** Maps state token -> provider for pending authorization flows */
+    /** Maps state token -> provider for pending MOCK authorization flows */
     this.states = /* @__PURE__ */ new Map();
-    /** Maps access token -> token set */
+    /** Maps access token -> token set (mock backend) */
     this.tokens = /* @__PURE__ */ new Map();
-    /** Maps refresh token -> access token for refresh lookups */
+    /** Maps refresh token -> access token for refresh lookups (mock backend) */
     this.refreshIndex = /* @__PURE__ */ new Map();
     /** Maps access token -> mock user session */
     this.sessions = /* @__PURE__ */ new Map();
-    this.logger.info("OAuth integration initialized (mock backend)");
+    /** Maps state -> pending OIDC authorization (real backend) */
+    this.pending = /* @__PURE__ */ new Map();
+    /** Maps access token -> ID-token subject, for userinfo subject checks */
+    this.subjects = /* @__PURE__ */ new Map();
+    /** Discovered issuer configurations, keyed by issuer URL */
+    this.discovered = /* @__PURE__ */ new Map();
+    this.real = config.env.OAUTH_MODE !== "mock" && Boolean(config.env.OAUTH_CLIENT_ID) && Boolean(config.env.OAUTH_CLIENT_SECRET);
+    this.logger.info(
+      this.real ? "OAuth integration initialized (OIDC backend via openid-client)" : "OAuth integration initialized (mock backend)"
+    );
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
@@ -2602,19 +3797,19 @@ var OAuthIntegration = class extends BaseIntegration {
       let data;
       switch (action) {
         case "authorize":
-          data = await this.executeWithRetry(() => this.authorize(params));
+          data = await this.executeWithRetry(() => this.real ? this.oidcAuthorize(params) : this.authorize(params));
           break;
         case "token":
-          data = await this.executeWithRetry(() => this.token(params));
+          data = await this.executeWithRetry(() => this.real ? this.oidcToken(params) : this.token(params));
           break;
         case "refresh":
-          data = await this.executeWithRetry(() => this.refresh(params));
+          data = await this.executeWithRetry(() => this.real ? this.oidcRefresh(params) : this.refresh(params));
           break;
         case "revoke":
-          data = await this.executeWithRetry(() => this.revoke(params));
+          data = await this.executeWithRetry(() => this.real ? this.oidcRevoke(params) : this.revoke(params));
           break;
         case "userinfo":
-          data = await this.executeWithRetry(() => this.userinfo(params));
+          data = await this.executeWithRetry(() => this.real ? this.oidcUserinfo(params) : this.userinfo(params));
           break;
         default:
           throw new Error(`Unknown action: ${action}`);
@@ -2629,7 +3824,119 @@ var OAuthIntegration = class extends BaseIntegration {
     }
   }
   // ---------------------------------------------------------------------------
-  // Helpers
+  // OIDC backend (openid-client)
+  // ---------------------------------------------------------------------------
+  issuerFor(provider) {
+    const configured = this.config.env.OIDC_ISSUER_URL;
+    if (configured) return configured;
+    const issuer = PROVIDER_ISSUERS[provider];
+    if (!issuer) {
+      throw new Error(
+        `Provider "${provider}" has no OIDC issuer \u2014 set OIDC_ISSUER_URL to an OIDC-compliant issuer, or use OAUTH_MODE=mock`
+      );
+    }
+    return issuer;
+  }
+  async configurationFor(provider) {
+    const issuer = this.issuerFor(provider);
+    const cached = this.discovered.get(issuer);
+    if (cached) return cached;
+    const configuration = await oidc.discovery(
+      new URL(issuer),
+      this.config.env.OAUTH_CLIENT_ID,
+      this.config.env.OAUTH_CLIENT_SECRET
+    );
+    this.discovered.set(issuer, configuration);
+    return configuration;
+  }
+  async oidcAuthorize(params) {
+    const provider = params.provider;
+    const scopes = params.scopes;
+    const redirectUri = params.redirectUri || this.config.env.OAUTH_REDIRECT_URI;
+    const configuration = await this.configurationFor(provider);
+    const state = oidc.randomState();
+    const pkceVerifier = oidc.randomPKCECodeVerifier();
+    const codeChallenge = await oidc.calculatePKCECodeChallenge(pkceVerifier);
+    const parameters = {
+      redirect_uri: redirectUri,
+      scope: scopes.join(" "),
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256"
+    };
+    if (provider === "google") {
+      parameters.access_type = "offline";
+      parameters.prompt = "consent";
+    }
+    const authUrl = oidc.buildAuthorizationUrl(configuration, parameters);
+    this.pending.set(state, { provider, redirectUri, pkceVerifier });
+    return { authUrl: authUrl.toString(), state };
+  }
+  async oidcToken(params) {
+    const code = params.code;
+    const state = params.state;
+    const pendingAuth = this.pending.get(state);
+    if (!pendingAuth) {
+      throw new Error(`Invalid or expired state token: ${state}`);
+    }
+    this.pending.delete(state);
+    const configuration = await this.configurationFor(pendingAuth.provider);
+    const callbackUrl = new URL(pendingAuth.redirectUri);
+    callbackUrl.searchParams.set("code", code);
+    callbackUrl.searchParams.set("state", state);
+    const tokens = await oidc.authorizationCodeGrant(configuration, callbackUrl, {
+      expectedState: state,
+      pkceCodeVerifier: pendingAuth.pkceVerifier
+    });
+    const claims = tokens.claims();
+    if (claims?.sub) {
+      this.subjects.set(tokens.access_token, claims.sub);
+    }
+    return {
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token ?? "",
+      expiresIn: tokens.expires_in ?? 3600,
+      tokenType: "bearer"
+    };
+  }
+  async oidcRefresh(params) {
+    const refreshToken = params.refreshToken;
+    const configuration = await this.configurationFor("google");
+    const tokens = await oidc.refreshTokenGrant(configuration, refreshToken);
+    const claims = tokens.claims();
+    if (claims?.sub) {
+      this.subjects.set(tokens.access_token, claims.sub);
+    }
+    return {
+      accessToken: tokens.access_token,
+      expiresIn: tokens.expires_in ?? 3600
+    };
+  }
+  async oidcRevoke(params) {
+    const token = params.token;
+    const configuration = await this.configurationFor("google");
+    await oidc.tokenRevocation(configuration, token);
+    this.subjects.delete(token);
+    return { revoked: true };
+  }
+  async oidcUserinfo(params) {
+    const accessToken = params.accessToken;
+    const configuration = await this.configurationFor("google");
+    const subject = this.subjects.get(accessToken);
+    const info = await oidc.fetchUserInfo(
+      configuration,
+      accessToken,
+      subject ?? oidc.skipSubjectCheck
+    );
+    return {
+      sub: info.sub,
+      email: typeof info.email === "string" ? info.email : "",
+      name: typeof info.name === "string" ? info.name : "",
+      picture: typeof info.picture === "string" ? info.picture : ""
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Mock backend helpers
   // ---------------------------------------------------------------------------
   /** Generate a random hex token of the given byte length. */
   generateToken(bytes = 32) {
@@ -2650,7 +3957,7 @@ var OAuthIntegration = class extends BaseIntegration {
     };
   }
   // ---------------------------------------------------------------------------
-  // Actions
+  // Mock backend actions
   // ---------------------------------------------------------------------------
   async authorize(params) {
     const provider = params.provider;
@@ -2759,19 +4066,333 @@ var OAuthIntegration = class extends BaseIntegration {
 };
 registerIntegration("oauth", OAuthIntegration);
 
-// src/integrations/storage/index.ts
+// src/contracts.ts
+var serviceCredentials = {
+  stripe: [
+    { envVar: "STRIPE_SECRET_KEY", required: true, description: "Stripe secret API key" },
+    { envVar: "STRIPE_WEBHOOK_SECRET", required: false, description: "Webhook endpoint signing secret" }
+  ],
+  youtube: [
+    { envVar: "YOUTUBE_API_KEY", required: true, description: "YouTube Data API key" }
+  ],
+  twilio: [
+    { envVar: "TWILIO_ACCOUNT_SID", required: true, description: "Twilio account SID" },
+    { envVar: "TWILIO_AUTH_TOKEN", required: true, description: "Twilio auth token" },
+    { envVar: "TWILIO_PHONE_NUMBER", required: false, description: "Default sender phone number" }
+  ],
+  email: [
+    { envVar: "SENDGRID_API_KEY", required: false, description: "SendGrid API key (use this OR RESEND_API_KEY)" },
+    { envVar: "RESEND_API_KEY", required: false, description: "Resend API key (use this OR SENDGRID_API_KEY)" },
+    { envVar: "FROM_EMAIL", required: false, description: "Default sender email address" }
+  ],
+  webhook: [
+    { envVar: "WEBHOOK_SIGNING_SECRET", required: false, description: "Default HMAC-SHA256 signing secret (per-call secret overrides)" },
+    { envVar: "WEBHOOK_TIMEOUT_MS", required: false, description: "Per-request timeout (ms, default 10000)" }
+  ],
+  push: [
+    { envVar: "VAPID_PUBLIC_KEY", required: true, description: "VAPID public key (web-push generate-vapid-keys)" },
+    { envVar: "VAPID_PRIVATE_KEY", required: true, description: "VAPID private key" },
+    { envVar: "VAPID_SUBJECT", required: true, description: "VAPID subject (mailto: or https: contact URI)" }
+  ],
+  calendar: [
+    { envVar: "GOOGLE_CALENDAR_SA_KEY", required: true, description: "Google service-account key JSON (raw or base64) with calendar scope; store in Secret Manager, bind as env" },
+    { envVar: "GOOGLE_CALENDAR_SUBJECT", required: false, description: "Workspace user to impersonate (domain-wide delegation); empty = act as the service account" },
+    { envVar: "GOOGLE_CALENDAR_ID", required: false, description: "Default calendar id (default: primary)" }
+  ],
+  drive: [
+    { envVar: "GOOGLE_DRIVE_SA_KEY", required: true, description: "Google service-account key JSON (raw or base64) with drive scope; store in Secret Manager, bind as env" },
+    { envVar: "GOOGLE_DRIVE_SUBJECT", required: false, description: "Workspace user to impersonate (domain-wide delegation); empty = act as the service account" }
+  ],
+  metaAds: [
+    { envVar: "META_ACCESS_TOKEN", required: true, description: "Meta Graph API access token (Marketing API, ads_read)" },
+    { envVar: "META_AD_ACCOUNT_ID", required: false, description: "Default ad account id (act_\u2026); per-call accountId overrides" }
+  ],
+  accounting: [],
+  banking: [
+    { envVar: "GOCARDLESS_SECRET_ID", required: true, description: "GoCardless Bank Account Data secret id" },
+    { envVar: "GOCARDLESS_SECRET_KEY", required: true, description: "GoCardless Bank Account Data secret key" }
+  ],
+  esign: [
+    { envVar: "DOCUSIGN_BASE_URL", required: true, description: "DocuSign REST base (e.g. https://demo.docusign.net/restapi/v2.1/accounts/<accountId>)" },
+    { envVar: "DOCUSIGN_ACCESS_TOKEN", required: true, description: "DocuSign OAuth access token (JWT grant rotation is the deployment concern)" }
+  ],
+  llm: [
+    { envVar: "ANTHROPIC_API_KEY", required: false, description: "Anthropic API key (use this OR OPENAI_API_KEY)" },
+    { envVar: "OPENAI_API_KEY", required: false, description: "OpenAI API key (use this OR ANTHROPIC_API_KEY)" }
+  ],
+  "llm-integration": [
+    { envVar: "ANTHROPIC_API_KEY", required: false, description: "Anthropic API key" },
+    { envVar: "OPENAI_API_KEY", required: false, description: "OpenAI API key" }
+  ],
+  ml: [
+    { envVar: "MASAR_URL", required: true, description: "Base URL of the deployed model-serving orbital" },
+    { envVar: "MASAR_ML_TRAIT", required: true, description: "Kebab-case trait name the serving orbital exposes its /events route under" }
+  ],
+  deepagent: [
+    { envVar: "DEEPAGENT_API_URL", required: true, description: "DeepAgent server URL" },
+    { envVar: "DEEPAGENT_API_KEY", required: false, description: "DeepAgent API key" }
+  ],
+  github: [
+    { envVar: "GITHUB_TOKEN", required: true, description: "GitHub personal access token" },
+    { envVar: "GITHUB_OWNER", required: false, description: "Default repository owner" },
+    { envVar: "GITHUB_REPO", required: false, description: "Default repository name" }
+  ],
+  docker: [
+    { envVar: "DOCKER_HOST", required: false, description: "Docker daemon host URL" }
+  ],
+  storage: [
+    { envVar: "STORAGE_ACCESS_KEY_ID", required: true, description: "S3-compatible access key id" },
+    { envVar: "STORAGE_SECRET_ACCESS_KEY", required: true, description: "S3-compatible secret access key" },
+    { envVar: "STORAGE_BUCKET", required: true, description: "Default bucket name" },
+    { envVar: "STORAGE_REGION", required: false, description: "Region (default us-east-1)" },
+    { envVar: "STORAGE_ENDPOINT", required: false, description: "Custom S3-compatible endpoint (R2/MinIO/\u2026); empty = AWS S3" },
+    { envVar: "STORAGE_PUBLIC_URL_BASE", required: false, description: "Base URL for public-acl object links; empty = endpoint-derived" }
+  ],
+  queue: [
+    { envVar: "QUEUE_URL", required: true, description: "Message queue connection URL" }
+  ],
+  redis: [
+    { envVar: "REDIS_URL", required: true, description: "Redis connection URL" }
+  ],
+  oauth: [
+    { envVar: "OAUTH_CLIENT_ID", required: true, description: "OIDC client ID" },
+    { envVar: "OAUTH_CLIENT_SECRET", required: true, description: "OIDC client secret" },
+    { envVar: "OAUTH_REDIRECT_URI", required: false, description: "OIDC redirect URI (default per-call param)" },
+    { envVar: "OIDC_ISSUER_URL", required: false, description: "OIDC issuer URL (default https://accounts.google.com)" }
+  ],
+  credentials: [
+    { envVar: "ALMADAR_CREDENTIAL_MASTER_KEY", required: false, description: "AES-256 master key (64-char hex) enabling the hosted credential store \u2014 hold it alone in the platform secret store" }
+  ],
+  otel: [
+    { envVar: "OTEL_EXPORTER_OTLP_ENDPOINT", required: true, description: "OpenTelemetry collector endpoint" },
+    { envVar: "OTEL_SERVICE_NAME", required: false, description: "Service name for traces" }
+  ],
+  cli: [],
+  // No fixed env vars — connection strings are resolved per-query from the
+  // caller-supplied connectionRef, so credentials cannot be declared statically.
+  database: [],
+  wikimedia: [
+    { envVar: "WIKIMEDIA_USER_AGENT", required: false, description: "Descriptive User-Agent for the Wikipedia API" },
+    { envVar: "WIKIMEDIA_TIMEOUT_MS", required: false, description: "Per-request timeout (ms)" }
+  ],
+  iconify: [
+    { envVar: "ICONIFY_USER_AGENT", required: false, description: "User-Agent for the Iconify API" },
+    { envVar: "ICONIFY_TIMEOUT_MS", required: false, description: "Per-request timeout (ms)" }
+  ],
+  arxiv: [
+    { envVar: "ARXIV_TIMEOUT_MS", required: false, description: "Per-request timeout (ms)" }
+  ]
+};
+var serviceProbes = {
+  calendar: { action: "listEvents", params: { maxResults: 1 } },
+  drive: { action: "listFiles", params: { maxResults: 1 } },
+  metaAds: { action: "listCampaigns", params: {} }
+};
+
+// src/integrations/credentials/index.ts
+var ENV_VAR_NAME = /^[A-Z][A-Z0-9_]*$/;
+function isProbeService(service) {
+  return service in serviceProbes;
+}
+var CredentialsIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    this.logger.info("Credentials integration initialized (tenant credential store surface)");
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    try {
+      let data;
+      switch (action) {
+        case "list":
+          data = this.list(typeof params.service === "string" ? params.service : void 0);
+          break;
+        case "set":
+          data = await this.set(params.service, params.envVar, params.value);
+          break;
+        case "remove":
+          data = await this.remove(params.service, params.envVar);
+          break;
+        case "test":
+          data = await this.test(params.service);
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  declaredFor(service) {
+    return serviceCredentials[service] ?? [];
+  }
+  assertSettable(service, envVar) {
+    if (service === "database") {
+      if (!ENV_VAR_NAME.test(envVar)) {
+        throw new Error(`"${envVar}" is not a well-formed connection reference (expected an env-var name)`);
+      }
+      return;
+    }
+    const declared = this.declaredFor(service);
+    if (declared.length === 0) {
+      throw new Error(`Service "${service}" declares no credentials`);
+    }
+    if (!declared.some((c) => c.envVar === envVar)) {
+      const valid = declared.map((c) => c.envVar).join(", ");
+      throw new Error(`"${envVar}" is not a declared credential of "${service}" (declared: ${valid})`);
+    }
+  }
+  list(serviceFilter) {
+    const store = getInstalledCredentialStore();
+    const stored = new Map((store?.entries() ?? []).map((e) => [`${e.service}\0${e.envVar}`, e]));
+    const entries = [];
+    for (const [service, declared] of Object.entries(serviceCredentials)) {
+      if (serviceFilter && service !== serviceFilter) continue;
+      for (const { envVar, required, description } of declared) {
+        const fromStore = stored.get(`${service}\0${envVar}`);
+        stored.delete(`${service}\0${envVar}`);
+        const fromEnv = process.env[envVar];
+        const source = fromStore ? "store" : fromEnv ? "env" : "none";
+        entries.push({
+          service,
+          envVar,
+          required,
+          description,
+          configured: source !== "none",
+          source,
+          last4: fromStore ? fromStore.last4 : fromEnv ? fromEnv.slice(-4) : ""
+        });
+      }
+    }
+    for (const e of stored.values()) {
+      if (serviceFilter && e.service !== serviceFilter) continue;
+      entries.push({
+        service: e.service,
+        envVar: e.envVar,
+        required: false,
+        description: "Stored connection reference",
+        configured: true,
+        source: "store",
+        last4: e.last4
+      });
+    }
+    return { enabled: store?.enabled ?? false, entries };
+  }
+  async set(service, envVar, value) {
+    const store = getInstalledCredentialStore();
+    if (!store) {
+      throw new Error("No credential store is installed on this host \u2014 set credentials via the environment");
+    }
+    this.assertSettable(service, envVar);
+    const entry = await store.set(service, envVar, value);
+    return { saved: true, service, envVar, last4: entry.last4 };
+  }
+  async remove(service, envVar) {
+    const store = getInstalledCredentialStore();
+    if (!store) {
+      throw new Error("No credential store is installed on this host");
+    }
+    this.assertSettable(service, envVar);
+    return { removed: await store.remove(envVar) };
+  }
+  async test(service) {
+    const declared = this.declaredFor(service);
+    const missing = declared.filter((c) => c.required && !resolveCredentialRef(c.envVar)).map((c) => c.envVar);
+    const configured = missing.length === 0;
+    if (!configured) {
+      return { service, configured, missing, probed: false, ok: false, message: `Missing required credentials: ${missing.join(", ")}` };
+    }
+    const factory = getActiveFactory();
+    const probe = isProbeService(service) ? serviceProbes[service] : void 0;
+    if (!factory || !probe) {
+      return { service, configured, missing, probed: false, ok: true, message: "Credentials present (no live probe declared for this service)" };
+    }
+    if (!factory.isConfigured(service)) {
+      return { service, configured, missing, probed: false, ok: false, message: "Credentials present but the service is not configured on this host \u2014 restart or re-save a credential" };
+    }
+    const result = await factory.execute(service, probe.action, probe.params);
+    if (!result.success) {
+      return { service, configured, missing, probed: true, ok: false, message: result.error?.message ?? `Probe ${probe.action} failed` };
+    }
+    const echoed = result.data !== null && typeof result.data === "object" && "_mock" in result.data;
+    if (echoed) {
+      return { service, configured, missing, probed: false, ok: false, message: "Probe was mock-echoed \u2014 the service is not actually configured" };
+    }
+    return { service, configured, missing, probed: true, ok: true, message: `Probe ${probe.action} succeeded` };
+  }
+};
+registerIntegration("credentials", CredentialsIntegration);
+function isParamRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
+}
+function toFilePayload(value) {
+  if (!isParamRecord2(value)) return null;
+  const { name, size, type, content } = value;
+  if (typeof name !== "string") return null;
+  return {
+    name,
+    size: typeof size === "number" ? size : 0,
+    type: typeof type === "string" ? type : "application/octet-stream",
+    content: typeof content === "string" ? content : void 0
+  };
+}
+function decodeContent2(content) {
+  const dataUrlMatch = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(content);
+  if (dataUrlMatch) {
+    const [, mime, isB64, body] = dataUrlMatch;
+    const bytes = isB64 ? Buffer.from(body, "base64") : Buffer.from(decodeURIComponent(body), "utf8");
+    return { bytes, contentType: mime || null };
+  }
+  return { bytes: Buffer.from(content, "utf8"), contentType: null };
+}
 var StorageIntegration = class extends BaseIntegration {
   constructor(config) {
     super(config);
     this.objects = /* @__PURE__ */ new Map();
-    const storageUrl = config.env.STORAGE_URL;
-    if (storageUrl) {
-      this.logger.warn(
-        "STORAGE_URL is configured but real storage client is not yet implemented. Falling back to in-memory store.",
-        { storageUrl }
-      );
+    this.s3 = null;
+    this.defaultBucket = config.env.STORAGE_BUCKET || "";
+    this.publicUrlBase = config.env.STORAGE_PUBLIC_URL_BASE || "";
+    const accessKeyId = config.env.STORAGE_ACCESS_KEY_ID || "";
+    const secretAccessKey = config.env.STORAGE_SECRET_ACCESS_KEY || "";
+    if (accessKeyId && secretAccessKey) {
+      const endpoint = config.env.STORAGE_ENDPOINT || void 0;
+      this.s3 = new S3Client({
+        region: config.env.STORAGE_REGION || "us-east-1",
+        endpoint,
+        // Path-style is what MinIO/R2-style endpoints expect.
+        forcePathStyle: Boolean(endpoint),
+        credentials: { accessKeyId, secretAccessKey }
+      });
+      this.logger.info("Storage integration initialized (S3 backend)", {
+        endpoint: endpoint ?? "aws",
+        bucket: this.defaultBucket
+      });
+    } else {
+      if (process.env.NODE_ENV === "production") {
+        throw new Error(
+          "Storage credentials missing in production (STORAGE_ACCESS_KEY_ID / STORAGE_SECRET_ACCESS_KEY) \u2014 refusing the in-memory fallback. See SECRETS.md."
+        );
+      }
+      this.logger.warn("Storage integration initialized (in-memory backend \u2014 dev only, nothing persists)");
     }
-    this.logger.info("Storage integration initialized (in-memory backend)");
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
@@ -2821,107 +4442,182 @@ var StorageIntegration = class extends BaseIntegration {
   // ---------------------------------------------------------------------------
   // Helpers
   // ---------------------------------------------------------------------------
-  /** Build a composite key from bucket and object key. */
+  bucketOf(params) {
+    return params.bucket || this.defaultBucket;
+  }
   compositeKey(bucket, key) {
     return `${bucket}/${key}`;
   }
-  /** Generate a deterministic etag from content. */
-  generateEtag(content) {
-    const raw = typeof content === "string" ? content : JSON.stringify(content);
-    let hash = 0;
-    for (let i = 0; i < raw.length; i++) {
-      const ch = raw.charCodeAt(i);
-      hash = (hash << 5) - hash + ch | 0;
+  generateEtag(bytes) {
+    return `"${createHash("md5").update(bytes).digest("hex")}"`;
+  }
+  /** Resolve the upload inputs from either admitted shape. */
+  resolveUpload(params) {
+    const file = toFilePayload(params.file);
+    if (file) {
+      const maxSize = typeof params.maxSize === "number" ? params.maxSize : 0;
+      if (maxSize > 0 && file.size > maxSize) {
+        throw new Error(`Upload rejected: ${file.name} is ${file.size} bytes (max ${maxSize})`);
+      }
+      if (!file.content) {
+        throw new Error(
+          `Upload rejected: file payload for '${file.name}' carries no content \u2014 the uploader must include the base64 data URL`
+        );
+      }
+      const { bytes: bytes2, contentType: contentType2 } = decodeContent2(file.content);
+      const safeName = file.name.replace(/[^A-Za-z0-9._-]/g, "_");
+      return {
+        key: `${Date.now()}-${safeName}`,
+        bytes: bytes2,
+        contentType: contentType2 ?? file.type,
+        acl: params.acl === "public" ? "public-read" : void 0
+      };
+    }
+    const key = params.key;
+    const content = params.content;
+    if (!key || content === void 0 || content === null) {
+      throw new Error("upload requires either `file` (with content) or the `key` + `content` pair");
     }
-    return `"${Math.abs(hash).toString(16).padStart(8, "0")}"`;
+    const raw = typeof content === "string" ? content : JSON.stringify(content);
+    const { bytes, contentType } = decodeContent2(raw);
+    return {
+      key,
+      bytes,
+      contentType: params.contentType || contentType || "application/octet-stream",
+      acl: params.acl === "public" ? "public-read" : void 0
+    };
   }
-  /** Compute the byte size of content. */
-  computeSize(content) {
-    if (typeof content === "string") {
-      return new TextEncoder().encode(content).byteLength;
+  publicUrl(bucket, key) {
+    if (this.publicUrlBase) {
+      return `${this.publicUrlBase.replace(/\/$/, "")}/${key}`;
+    }
+    const endpoint = this.config.env.STORAGE_ENDPOINT;
+    if (endpoint) {
+      return `${endpoint.replace(/\/$/, "")}/${bucket}/${key}`;
     }
-    return JSON.stringify(content).length;
+    const region = this.config.env.STORAGE_REGION || "us-east-1";
+    return `https://${bucket}.s3.${region}.amazonaws.com/${key}`;
   }
   // ---------------------------------------------------------------------------
   // Actions
   // ---------------------------------------------------------------------------
   async upload(params) {
-    const bucket = params.bucket;
-    const key = params.key;
-    const content = params.content;
-    const contentType = params.contentType ?? "application/octet-stream";
-    const metadata = params.metadata ?? {};
-    this.logger.debug("Storage UPLOAD", { bucket, key, contentType });
-    const size = this.computeSize(content);
-    const etag = this.generateEtag(content);
-    const obj = {
-      content,
-      contentType,
-      size,
-      metadata,
-      lastModified: Date.now(),
-      etag
-    };
-    this.objects.set(this.compositeKey(bucket, key), obj);
-    return { key, bucket, size, etag };
+    const bucket = this.bucketOf(params);
+    const { key, bytes, contentType, acl } = this.resolveUpload(params);
+    const etag = this.generateEtag(bytes);
+    this.logger.debug("Storage UPLOAD", { bucket, key, contentType, size: bytes.length });
+    if (this.s3) {
+      await this.s3.send(
+        new PutObjectCommand({
+          Bucket: bucket,
+          Key: key,
+          Body: bytes,
+          ContentType: contentType,
+          ACL: acl
+        })
+      );
+    } else {
+      this.objects.set(this.compositeKey(bucket, key), {
+        content: bytes.toString("base64"),
+        contentType,
+        size: bytes.length,
+        metadata: params.metadata ?? {},
+        lastModified: Date.now(),
+        etag
+      });
+    }
+    const url = acl === "public-read" ? this.publicUrl(bucket, key) : (await this.signUrl(bucket, key, "get", 3600)).url;
+    return { key, bucket, size: bytes.length, etag, id: key, url };
   }
   async download(params) {
-    const bucket = params.bucket;
+    const bucket = this.bucketOf(params);
     const key = params.key;
     this.logger.debug("Storage DOWNLOAD", { bucket, key });
+    if (this.s3) {
+      const response = await this.s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+      const bytes = Buffer.from(await response.Body.transformToByteArray());
+      return {
+        content: bytes.toString("base64"),
+        contentType: response.ContentType ?? "application/octet-stream",
+        size: bytes.length,
+        metadata: {}
+      };
+    }
     const obj = this.objects.get(this.compositeKey(bucket, key));
     if (!obj) {
       throw new Error(`Object not found: ${bucket}/${key}`);
     }
     return {
-      content: obj.content,
+      content: String(obj.content),
       contentType: obj.contentType,
       size: obj.size,
       metadata: obj.metadata
     };
   }
   async list(params) {
-    const bucket = params.bucket;
+    const bucket = this.bucketOf(params);
     const prefix = params.prefix ?? "";
     const maxKeys = params.maxKeys ?? 1e3;
     this.logger.debug("Storage LIST", { bucket, prefix, maxKeys });
+    if (this.s3) {
+      const response = await this.s3.send(
+        new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix || void 0, MaxKeys: maxKeys })
+      );
+      return {
+        keys: (response.Contents ?? []).map((entry) => ({
+          key: entry.Key ?? "",
+          size: entry.Size ?? 0,
+          lastModified: entry.LastModified?.getTime() ?? 0
+        })),
+        // Continuation tokens are unrepresentable in the result type (ledger
+        // I-11) — surface the clamp honestly.
+        truncated: Boolean(response.IsTruncated)
+      };
+    }
     const bucketPrefix = `${bucket}/`;
     const fullPrefix = `${bucket}/${prefix}`;
     const results = [];
     for (const [compositeKey, obj] of this.objects) {
       if (!compositeKey.startsWith(fullPrefix)) continue;
-      const objectKey = compositeKey.slice(bucketPrefix.length);
       results.push({
-        key: objectKey,
+        key: compositeKey.slice(bucketPrefix.length),
         size: obj.size,
         lastModified: obj.lastModified
       });
     }
     results.sort((a, b) => a.key.localeCompare(b.key));
-    const truncated = results.length > maxKeys;
-    return {
-      keys: results.slice(0, maxKeys),
-      truncated
-    };
+    return { keys: results.slice(0, maxKeys), truncated: results.length > maxKeys };
   }
   async deleteObject(params) {
-    const bucket = params.bucket;
+    const bucket = this.bucketOf(params);
     const key = params.key;
     this.logger.debug("Storage DELETE", { bucket, key });
+    if (this.s3) {
+      await this.s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+      return { deleted: true };
+    }
     const existed = this.objects.has(this.compositeKey(bucket, key));
     this.objects.delete(this.compositeKey(bucket, key));
     return { deleted: existed };
   }
+  async signUrl(bucket, key, operation, expiresIn) {
+    const expiresAt = Date.now() + expiresIn * 1e3;
+    if (this.s3) {
+      const command = operation === "put" ? new PutObjectCommand({ Bucket: bucket, Key: key }) : new GetObjectCommand({ Bucket: bucket, Key: key });
+      const url2 = await getSignedUrl(this.s3, command, { expiresIn });
+      return { url: url2, expiresAt };
+    }
+    const token = createHash("sha256").update(`${bucket}/${key}/${expiresAt}`).digest("hex").slice(0, 16);
+    const url = `https://storage.mock.local/${bucket}/${key}?X-Amz-Algorithm=MOCK-HMAC-SHA256&X-Amz-Expires=${expiresIn}&X-Amz-SignedHeaders=host&X-Amz-Signature=${token}&operation=${operation}`;
+    return { url, expiresAt };
+  }
   async getSignedUrl(params) {
-    const bucket = params.bucket;
+    const bucket = this.bucketOf(params);
     const key = params.key;
     const expiresIn = params.expiresIn ?? 3600;
     const operation = params.operation ?? "get";
     this.logger.debug("Storage GET_SIGNED_URL", { bucket, key, expiresIn, operation });
-    const expiresAt = Date.now() + expiresIn * 1e3;
-    const token = Math.random().toString(36).slice(2, 18);
-    const url = `https://storage.mock.local/${bucket}/${key}?X-Amz-Algorithm=MOCK-HMAC-SHA256&X-Amz-Expires=${expiresIn}&X-Amz-SignedHeaders=host&X-Amz-Signature=${token}&operation=${operation}`;
-    return { url, expiresAt };
+    return this.signUrl(bucket, key, operation, expiresIn);
   }
 };
 registerIntegration("storage", StorageIntegration);
@@ -3428,10 +5124,10 @@ var DatabaseIntegration = class extends BaseIntegration {
   }
   /** Resolve (and cache) the driver for a connection reference. */
   driverFor(connectionRef) {
-    const connectionString = process.env[connectionRef];
+    const connectionString = resolveCredentialRef(connectionRef);
     if (!connectionString) {
       throw new IntegrationError(
-        `Connection reference "${connectionRef}" is not set in the environment`,
+        `Connection reference "${connectionRef}" is not set in the credential store or environment`,
         "AUTH_ERROR"
       );
     }
@@ -3683,6 +5379,6 @@ var ArxivIntegration = class extends BaseIntegration {
 };
 registerIntegration("arxiv", ArxivIntegration);
 
-export { ArxivIntegration, BaseIntegration, CLIIntegration, ConsoleLogger, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, EmailIntegration, GitHubIntegration, IconifyIntegration, IntegrationError, IntegrationFactory, LLMIntegration, MLIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, WikimediaIntegration, YouTubeIntegration, assertReadOnlySelect, getIntegration, getIntegrationFactory, getRegisteredIntegrations, isKnownIntegration, registerIntegration, resetIntegrationFactory, validateParams, verifyAndParseStripeEvent, withRetry };
+export { AccountingIntegration, ArxivIntegration, BankingIntegration, BaseIntegration, CLIIntegration, CREDENTIAL_ENTITY_TYPE, CREDENTIAL_MASTER_KEY_ENV, CalendarIntegration, ConsoleLogger, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, GitHubIntegration, IconifyIntegration, IntegrationError, IntegrationFactory, LLMIntegration, MLIntegration, MetaAdsIntegration, OAuthIntegration, OtelIntegration, PushIntegration, QueueIntegration, RedisIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, assertReadOnlySelect, getActiveFactory, getInstalledCredentialStore, getIntegration, getIntegrationFactory, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, resetIntegrationFactory, resolveCredentialRef, uninstallCredentialStore, validateParams, verifyAndParseStripeEvent, withRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map