@almadar/integrations 2.24.0 → 2.26.0

package/dist/runtime/index.js

@@ -1,17 +1,22 @@
 import { createLogger } from '@almadar/logger';
 import { integratorsRegistry } from '@almadar/core/patterns';
+import { createHmac, createHash } from 'crypto';
+import { mkdtempSync, writeFileSync, rmSync, promises } from 'fs';
+import { join } from 'path';
 import Stripe2 from 'stripe';
 import { google } from 'googleapis';
 import twilio from 'twilio';
 import sgMail from '@sendgrid/mail';
 import { Resend } from 'resend';
-import { createHmac } from 'crypto';
+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';
 import { createRequire } from 'module';
 
@@ -34,6 +39,133 @@ var IntegrationError = class extends Error {
     };
   }
 };
+
+// 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)" },
+    { envVar: "GOOGLE_CALENDAR_CHANNEL_TOKEN", required: false, description: "Watch-channel verification token \u2014 required to receive inbound calendar hooks (two-way sync)" }
+  ],
+  drive: [
+    { envVar: "GOOGLE_DRIVE_SA_KEY", required: false, description: "Google service-account key JSON (raw or base64) with drive scope \u2014 serves reads; 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" },
+    { envVar: "GOOGLE_DRIVE_REFRESH_TOKEN", required: false, description: "User OAuth refresh token (drive-consent.mjs) \u2014 serves writes; SA uploads are impossible on personal accounts (no SA storage quota)" },
+    { envVar: "GOOGLE_DRIVE_FOLDER_ID", required: false, description: "Default parent folder for uploads/new folders when the call names none" }
+  ],
+  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" },
+    { envVar: "ALMADAR_CREDENTIAL_MASTER_KEY_PREVIOUS", required: false, description: "Previous master key, present only during a rotation window \u2014 decrypts old rows until `credentials.rotate` re-encrypts them" }
+  ],
+  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: {} }
+};
 var ConsoleLogger = class {
   constructor(_level = "info") {
     this.log = createLogger("almadar:integrations");
@@ -51,6 +183,7 @@ var ConsoleLogger = class {
     this.log.error(message, meta);
   }
 };
+var RESERVED_ENVELOPE_KEYS = /* @__PURE__ */ new Set(["emit", "onSuccess", "onError", "timeout"]);
 function validateParams(integration, action, params) {
   const typedRegistry = integratorsRegistry;
   const registry = typedRegistry.integrators[integration];
@@ -73,6 +206,16 @@ function validateParams(integration, action, params) {
     };
   }
   const errors = [];
+  const declaredNames = new Set(actionDef.params.map((p) => p.name));
+  for (const key of Object.keys(params)) {
+    if (RESERVED_ENVELOPE_KEYS.has(key)) continue;
+    if (!declaredNames.has(key)) {
+      errors.push({
+        param: key,
+        message: `Unknown parameter: ${key} (declared: ${[...declaredNames].sort().join(", ")})`
+      });
+    }
+  }
   for (const paramDef of actionDef.params) {
     if (paramDef.required && !(paramDef.name in params)) {
       errors.push({
@@ -217,56 +360,80 @@ function getIntegration(name) {
 }
 
 // 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);
-    return await instance.execute(action, params);
+  async execute(integration, action, params, context) {
+    const instance = this.get(integration, context?.principal);
+    return await instance.execute(action, params, context);
   }
   /**
    * 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)
@@ -283,6 +450,26 @@ var IntegrationFactory = class {
   }
 };
 
+// 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 resolveCredentialRef(ref, env = process.env) {
+  return installedStore?.resolve(ref) ?? env[ref];
+}
+join(".almadar", "dev-credentials.json");
+
 // src/integrations/stripe/index.ts
 var STRIPE_API_VERSION = "2025-02-24.acacia";
 function isoFromUnix(seconds) {
@@ -726,10 +913,10 @@ var TwilioIntegration = class extends BaseIntegration {
     }
   }
   async sendSMS(params) {
-    const { to, body } = params;
+    const { to, body, from } = params;
     this.logger.debug("Sending SMS", { to: String(to ?? "") });
     const message = await this.client.messages.create({
-      from: this.phoneNumber,
+      from: from || this.phoneNumber,
       to,
       body
     });
@@ -808,31 +995,35 @@ var EmailIntegration = class extends BaseIntegration {
     }
   }
   async send(params) {
-    const { to, subject, body, from } = params;
+    const { to, subject, body, from, htmlBody, replyTo, templateId } = params;
     this.logger.debug("Sending email", { to: String(to), subject: String(subject), provider: this.provider });
+    const message = {
+      to,
+      subject,
+      body,
+      from: from || this.fromEmail,
+      htmlBody: htmlBody || void 0,
+      replyTo: replyTo || void 0,
+      templateId: templateId || void 0
+    };
     if (this.provider === "sendgrid") {
-      return await this.sendViaSendGrid(
-        to,
-        subject,
-        body,
-        from || this.fromEmail
-      );
+      return await this.sendViaSendGrid(message);
     } else if (this.provider === "resend") {
-      return await this.sendViaResend(
-        to,
-        subject,
-        body,
-        from || this.fromEmail
-      );
+      return await this.sendViaResend(message);
     }
     throw new Error(`Unknown email provider: ${this.provider}`);
   }
-  async sendViaSendGrid(to, subject, body, from) {
+  async sendViaSendGrid(message) {
     const msg = {
-      to,
-      from,
-      subject,
-      html: body
+      to: message.to,
+      from: message.from,
+      subject: message.subject,
+      // htmlBody present → it carries the HTML and body becomes the
+      // plain-text alternative; absent → body renders as HTML (legacy).
+      html: message.htmlBody ?? message.body,
+      ...message.htmlBody ? { text: message.body } : {},
+      ...message.replyTo ? { replyTo: message.replyTo } : {},
+      ...message.templateId ? { templateId: message.templateId } : {}
     };
     const response = await sgMail.send(msg);
     return {
@@ -840,15 +1031,20 @@ var EmailIntegration = class extends BaseIntegration {
       status: "sent"
     };
   }
-  async sendViaResend(to, subject, body, from) {
+  async sendViaResend(message) {
     if (!this.resendClient) {
       throw new Error("Resend client not initialized");
     }
+    if (message.templateId) {
+      throw new Error("templateId is not supported by the resend provider \u2014 use sendgrid or drop templateId");
+    }
     const response = await this.resendClient.emails.send({
-      from,
-      to,
-      subject,
-      html: body
+      from: message.from,
+      to: message.to,
+      subject: message.subject,
+      html: message.htmlBody ?? message.body,
+      ...message.htmlBody ? { text: message.body } : {},
+      ...message.replyTo ? { replyTo: message.replyTo } : {}
     });
     return {
       id: response.data?.id,
@@ -913,25 +1109,948 @@ var WebhookIntegration = class extends BaseIntegration {
     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)
+    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);
+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) {
+      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.saClient = google.drive({ version: "v3", auth });
+    } else {
+      this.saClient = null;
+    }
+    const refreshToken = config.env.GOOGLE_DRIVE_REFRESH_TOKEN;
+    const clientId = config.env.OAUTH_CLIENT_ID;
+    const clientSecret = config.env.OAUTH_CLIENT_SECRET;
+    if (refreshToken && clientId && clientSecret) {
+      const oauth2 = new google.auth.OAuth2(clientId, clientSecret);
+      oauth2.setCredentials({ refresh_token: refreshToken });
+      this.userClient = google.drive({ version: "v3", auth: oauth2 });
+    } else {
+      this.userClient = null;
+    }
+    if (!this.saClient && !this.userClient) {
+      throw new Error(
+        "Drive not configured \u2014 set GOOGLE_DRIVE_SA_KEY (reads) and/or GOOGLE_DRIVE_REFRESH_TOKEN + OAUTH_CLIENT_ID/SECRET (writes)"
+      );
+    }
+    this.defaultFolderId = config.env.GOOGLE_DRIVE_FOLDER_ID || void 0;
+    this.logger.info("Drive integration initialized", {
+      serviceAccount: this.saClient !== null,
+      userToken: this.userClient !== null,
+      delegated: Boolean(config.env.GOOGLE_DRIVE_SUBJECT)
+    });
+  }
+  /** Reads prefer the SA client (delegation-aware); user client covers its absence. */
+  readClient() {
+    const client = this.saClient ?? this.userClient;
+    if (!client) throw new Error("Drive not configured");
+    return client;
+  }
+  /** Writes REQUIRE the user client on personal accounts (SA has no storage quota); SA only as a Workspace fallback. */
+  writeClient() {
+    const client = this.userClient ?? this.saClient;
+    if (!client) throw new Error("Drive not configured");
+    return client;
+  }
+  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.readClient().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.readClient().files.get({
+      fileId,
+      fields: "id, name, mimeType, size"
+    });
+    const content = await this.readClient().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 parent = folderId || this.defaultFolderId;
+    const response = await this.writeClient().files.create({
+      requestBody: {
+        name,
+        parents: parent ? [parent] : 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 parent = parentId || this.defaultFolderId;
+    const response = await this.writeClient().files.create({
+      requestBody: {
+        name,
+        mimeType: "application/vnd.google-apps.folder",
+        parents: parent ? [parent] : 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.readClient().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 {
+      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("banking", BankingIntegration);
+
+// src/integrations/esign/index.ts
+var EsignIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    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("E-sign integration initialized (DocuSign)");
+  }
+  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 "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}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  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(`Webhook endpoint returned ${response.status}`);
+      throw new Error(`DocuSign returned ${response.status}`);
     }
-    return {
-      status: response.status,
-      ok: response.ok,
-      durationMs: Date.now() - startTime
-    };
+    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 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 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 { content: bytes.toString("base64"), documentName: `envelope-${envelopeId}.pdf` };
   }
 };
-registerIntegration("webhook", WebhookIntegration);
+registerIntegration("esign", EsignIntegration);
 var LLMIntegration = class extends BaseIntegration {
   constructor(config) {
     super(config);
@@ -2502,25 +3621,59 @@ 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 PENDING_GRANT_TTL_MS = 10 * 60 * 1e3;
+var InMemoryPendingGrantStore = class {
+  constructor() {
+    this.grants = /* @__PURE__ */ new Map();
+  }
+  async put(state, grant, ttlMs) {
+    this.grants.set(state, { grant, expiresAt: Date.now() + ttlMs });
+  }
+  async take(state) {
+    const entry = this.grants.get(state);
+    if (!entry) return null;
+    this.grants.delete(state);
+    return entry.expiresAt >= Date.now() ? entry.grant : null;
+  }
+  async sweep() {
+    const now = Date.now();
+    for (const [state, entry] of this.grants) {
+      if (entry.expiresAt < now) this.grants.delete(state);
+    }
+  }
+};
 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)");
+    /** Pending OIDC authorizations (real backend) — injectable, in-memory default. */
+    this.fallbackPending = new InMemoryPendingGrantStore();
+    /** 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)"
+    );
+  }
+  pendingStore() {
+    return this.fallbackPending;
   }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
@@ -2541,19 +3694,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}`);
@@ -2568,7 +3721,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);
+    await this.pendingStore().put(state, { provider, redirectUri, pkceVerifier }, PENDING_GRANT_TTL_MS);
+    void this.pendingStore().sweep();
+    return { authUrl: authUrl.toString(), state };
+  }
+  async oidcToken(params) {
+    const code = params.code;
+    const state = params.state;
+    const pendingAuth = await this.pendingStore().take(state);
+    if (!pendingAuth) {
+      throw new Error(`Invalid or expired state token: ${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) {
@@ -2589,7 +3854,7 @@ var OAuthIntegration = class extends BaseIntegration {
     };
   }
   // ---------------------------------------------------------------------------
-  // Actions
+  // Mock backend actions
   // ---------------------------------------------------------------------------
   async authorize(params) {
     const provider = params.provider;
@@ -2698,19 +3963,242 @@ var OAuthIntegration = class extends BaseIntegration {
 };
 registerIntegration("oauth", OAuthIntegration);
 
-// src/integrations/storage/index.ts
+// src/integrations/credentials/index.ts
+var ENV_VAR_NAME = /^[A-Z][A-Z0-9_]*$/;
+var ROLE_GATED_ACTIONS = /* @__PURE__ */ new Set(["set", "remove", "test", "rotate"]);
+var DEFAULT_ADMIN_ROLES = ["admin", "owner"];
+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, context) {
+    if (ROLE_GATED_ACTIONS.has(action)) {
+      const allowed = this.adminRoles();
+      if (!context?.role || !allowed.includes(context.role)) {
+        return {
+          success: false,
+          error: new IntegrationError(
+            `forbidden: "${action}" requires one of roles: ${allowed.join(", ")}`,
+            "AUTH_ERROR"
+          ),
+          metadata: this.createMetadata(action, 0)
+        };
+      }
+    }
+    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, context);
+          break;
+        case "rotate": {
+          const store = getInstalledCredentialStore();
+          if (!store) {
+            throw new Error("No credential store is installed on this host");
+          }
+          data = await store.rotate();
+          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);
+    }
+  }
+  adminRoles() {
+    const raw = this.config.env["ALMADAR_CREDENTIAL_ADMIN_ROLES"] || process.env["ALMADAR_CREDENTIAL_ADMIN_ROLES"] || "";
+    const roles = raw.split(",").map((r) => r.trim()).filter((r) => r.length > 0);
+    return roles.length > 0 ? roles : DEFAULT_ADMIN_ROLES;
+  }
+  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})`);
+    }
+  }
+  storeFirst() {
+    const flag = this.config.env["ALMADAR_CREDENTIALS_SOURCE"] || process.env["ALMADAR_CREDENTIALS_SOURCE"];
+    return flag === "store";
+  }
+  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 = this.storeFirst() ? void 0 : 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, context) {
+    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, context);
+    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);
@@ -2760,107 +4248,194 @@ 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;
+    const continuationToken = params.continuationToken;
     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,
+          ContinuationToken: continuationToken
+        })
+      );
+      return {
+        keys: (response.Contents ?? []).map((entry) => ({
+          key: entry.Key ?? "",
+          size: entry.Size ?? 0,
+          lastModified: entry.LastModified?.getTime() ?? 0
+        })),
+        truncated: Boolean(response.IsTruncated),
+        ...response.IsTruncated && response.NextContinuationToken !== void 0 ? { nextToken: response.NextContinuationToken } : {}
+      };
+    }
     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;
+    const offset = continuationToken !== void 0 ? Number.parseInt(continuationToken, 10) || 0 : 0;
+    const page = results.slice(offset, offset + maxKeys);
+    const truncated = offset + maxKeys < results.length;
     return {
-      keys: results.slice(0, maxKeys),
-      truncated
+      keys: page,
+      truncated,
+      ...truncated ? { nextToken: String(offset + 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);
@@ -3367,10 +4942,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"
       );
     }
@@ -3670,8 +5245,8 @@ var MockIntegration = class extends BaseIntegration {
 
 // src/runtime/effectHandler.ts
 function createCallServiceHandler(factory) {
-  const handler = async (service, action, params) => {
-    const result = await factory.execute(service, action, params || {});
+  const handler = async (service, action, params, context) => {
+    const result = await factory.execute(service, action, params || {}, context);
     if (!result.success) {
       throw result.error;
     }
@@ -3681,6 +5256,19 @@ function createCallServiceHandler(factory) {
 }
 
 // src/runtime/RuntimeIntegrationManager.ts
+var STORE_BOOTSTRAP_ENV_VARS = /* @__PURE__ */ new Set([
+  "ALMADAR_CREDENTIAL_MASTER_KEY",
+  "ALMADAR_CREDENTIAL_MASTER_KEY_PREVIOUS"
+]);
+function declaredCredentialEnvVars() {
+  const vars = /* @__PURE__ */ new Set();
+  for (const decls of Object.values(serviceCredentials)) {
+    for (const { envVar } of decls) {
+      if (!STORE_BOOTSTRAP_ENV_VARS.has(envVar)) vars.add(envVar);
+    }
+  }
+  return vars;
+}
 function generateMockFromShape(shape) {
   const data = {};
   for (const [key, type] of Object.entries(shape)) {
@@ -3708,8 +5296,69 @@ function generateMockFromShape(shape) {
 }
 var RuntimeIntegrationManager = class {
   constructor() {
+    this.credentialStore = null;
+    this.storeEnvBase = null;
+    this.storeFirst = false;
     this.factory = new IntegrationFactory();
     this.installNotConfiguredFallback();
+    installActiveFactory(this.factory);
+  }
+  /**
+   * W4: configure with the tenant credential store layered over the env —
+   * store → env → unconfigured. Installs the store as the process-wide
+   * `resolveCredentialRef` source, warms it, and re-configures whenever a
+   * credential changes (dropping cached instances so new keys go live
+   * without a restart). Mock mode short-circuits inside `configureFromEnv`
+   * exactly as before, so verify harnesses are unaffected.
+   */
+  async configureFromStore(store, envOverride) {
+    this.credentialStore = store;
+    this.storeEnvBase = envOverride ?? process.env;
+    this.storeFirst = this.storeEnvBase.ALMADAR_CREDENTIALS_SOURCE === "store";
+    installCredentialStore(store);
+    await store.warm();
+    if (this.storeFirst && store.enabled) {
+      await this.seedStoreFromEnv(store, this.storeEnvBase);
+    }
+    store.subscribe(() => this.refreshFromStore());
+    this.refreshFromStore();
+  }
+  /** Whether store-first custody (I-31) is active on this manager. */
+  get credentialsStoreFirst() {
+    return this.storeFirst;
+  }
+  /** Copy each declared credential present in env but absent from the store. */
+  async seedStoreFromEnv(store, env) {
+    const present = new Set(store.entries().map((e) => e.envVar));
+    for (const [service, decls] of Object.entries(serviceCredentials)) {
+      for (const { envVar } of decls) {
+        if (STORE_BOOTSTRAP_ENV_VARS.has(envVar)) continue;
+        const value = env[envVar];
+        if (value && !present.has(envVar)) {
+          await store.set(service, envVar, value);
+          present.add(envVar);
+        }
+      }
+    }
+  }
+  /**
+   * Re-derive configs from base env + warmed store values. `reset()` (not
+   * `invalidate()`): configs must go too, or a REMOVED credential's service
+   * resurrects from its stale config on the next `get()` — removal must
+   * revoke. `configureFromEnv` below rebuilds every configured service from
+   * the merged env.
+   */
+  refreshFromStore() {
+    if (!this.credentialStore || !this.storeEnvBase) return;
+    this.factory.reset();
+    let base = this.storeEnvBase;
+    if (this.storeFirst) {
+      const declared = declaredCredentialEnvVars();
+      base = Object.fromEntries(
+        Object.entries(this.storeEnvBase).filter(([key]) => !declared.has(key))
+      );
+    }
+    this.configureFromEnv({ ...base, ...this.credentialStore.snapshotEnv() });
   }
   /**
    * Wrap `factory.execute` so an unknown/unconfigured service echoes its
@@ -3720,15 +5369,18 @@ var RuntimeIntegrationManager = class {
    * events fire — only the two "not set up" errors (`Unknown integration`,
    * `Integration not configured`) are caught. Subsumes the broader wrapper
    * that previously lived inside `configureMockMode`.
+   *
+   * In production the fallback is OFF: a missing key must surface as the
+   * circuit's failure event and a degraded health check, never a fake success.
    */
   installNotConfiguredFallback() {
     const originalExecute = this.factory.execute.bind(this.factory);
-    this.factory.execute = async (integration, action, params) => {
+    this.factory.execute = async (integration, action, params, context) => {
       try {
-        return await originalExecute(integration, action, params);
+        return await originalExecute(integration, action, params, context);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        if (/Unknown integration|not configured/i.test(msg)) {
+        if (process.env.NODE_ENV !== "production" && /Unknown integration|not configured/i.test(msg)) {
           return {
             success: true,
             data: { ...params, _mock: true, _service: integration, _action: action },
@@ -3742,10 +5394,18 @@ var RuntimeIntegrationManager = class {
   /**
    * Configure from environment variables.
    * In mock mode (USE_MOCK_DATA=true), all services return realistic mock data.
+   *
+   * Pass an explicit env map to configure hermetically (verify harnesses,
+   * per-tenant resolution); defaults to `process.env`.
    */
-  configureFromEnv() {
-    const env = process.env;
-    if (env.USE_MOCK_DATA === "true") {
+  configureFromEnv(envOverride) {
+    const env = envOverride ?? process.env;
+    if (env.ALMADAR_INTEGRATIONS_MODE === "mock" || env.USE_MOCK_DATA === "true") {
+      if (env.NODE_ENV === "production") {
+        throw new Error(
+          "Mocked integrations are not permitted when NODE_ENV=production \u2014 unset ALMADAR_INTEGRATIONS_MODE/USE_MOCK_DATA."
+        );
+      }
       this.configureMockMode();
       return;
     }
@@ -3789,6 +5449,88 @@ var RuntimeIntegrationManager = class {
         }
       });
     }
+    if (env.VAPID_PUBLIC_KEY && env.VAPID_PRIVATE_KEY && env.VAPID_SUBJECT) {
+      this.factory.configure("push", {
+        env: {
+          VAPID_PUBLIC_KEY: env.VAPID_PUBLIC_KEY,
+          VAPID_PRIVATE_KEY: env.VAPID_PRIVATE_KEY,
+          VAPID_SUBJECT: env.VAPID_SUBJECT
+        }
+      });
+    }
+    if (env.GOOGLE_CALENDAR_SA_KEY) {
+      this.factory.configure("calendar", {
+        env: {
+          GOOGLE_CALENDAR_SA_KEY: env.GOOGLE_CALENDAR_SA_KEY,
+          GOOGLE_CALENDAR_SUBJECT: env.GOOGLE_CALENDAR_SUBJECT || "",
+          GOOGLE_CALENDAR_ID: env.GOOGLE_CALENDAR_ID || ""
+        }
+      });
+    }
+    if (env.GOOGLE_DRIVE_SA_KEY || env.GOOGLE_DRIVE_REFRESH_TOKEN && env.OAUTH_CLIENT_ID && env.OAUTH_CLIENT_SECRET) {
+      this.factory.configure("drive", {
+        env: {
+          GOOGLE_DRIVE_SA_KEY: env.GOOGLE_DRIVE_SA_KEY || "",
+          GOOGLE_DRIVE_SUBJECT: env.GOOGLE_DRIVE_SUBJECT || "",
+          GOOGLE_DRIVE_REFRESH_TOKEN: env.GOOGLE_DRIVE_REFRESH_TOKEN || "",
+          GOOGLE_DRIVE_FOLDER_ID: env.GOOGLE_DRIVE_FOLDER_ID || "",
+          OAUTH_CLIENT_ID: env.OAUTH_CLIENT_ID || "",
+          OAUTH_CLIENT_SECRET: env.OAUTH_CLIENT_SECRET || ""
+        }
+      });
+    }
+    if (env.META_ACCESS_TOKEN) {
+      this.factory.configure("metaAds", {
+        env: {
+          META_ACCESS_TOKEN: env.META_ACCESS_TOKEN,
+          META_AD_ACCOUNT_ID: env.META_AD_ACCOUNT_ID || ""
+        }
+      });
+    }
+    this.factory.configure("accounting", { env: {} });
+    if (env.GOCARDLESS_SECRET_ID && env.GOCARDLESS_SECRET_KEY) {
+      this.factory.configure("banking", {
+        env: {
+          GOCARDLESS_SECRET_ID: env.GOCARDLESS_SECRET_ID,
+          GOCARDLESS_SECRET_KEY: env.GOCARDLESS_SECRET_KEY
+        }
+      });
+    }
+    if (env.DOCUSIGN_BASE_URL && env.DOCUSIGN_ACCESS_TOKEN) {
+      this.factory.configure("esign", {
+        env: {
+          DOCUSIGN_BASE_URL: env.DOCUSIGN_BASE_URL,
+          DOCUSIGN_ACCESS_TOKEN: env.DOCUSIGN_ACCESS_TOKEN
+        }
+      });
+    }
+    if (env.OAUTH_CLIENT_ID && env.OAUTH_CLIENT_SECRET || env.OAUTH_MODE === "mock") {
+      this.factory.configure("oauth", {
+        env: {
+          OAUTH_CLIENT_ID: env.OAUTH_CLIENT_ID || "",
+          OAUTH_CLIENT_SECRET: env.OAUTH_CLIENT_SECRET || "",
+          OAUTH_REDIRECT_URI: env.OAUTH_REDIRECT_URI || "",
+          OIDC_ISSUER_URL: env.OIDC_ISSUER_URL || "",
+          OAUTH_MODE: env.OAUTH_MODE || ""
+        }
+      });
+    }
+    this.factory.configure("credentials", {
+      env: {
+        ALMADAR_CREDENTIAL_ADMIN_ROLES: env.ALMADAR_CREDENTIAL_ADMIN_ROLES || "",
+        ALMADAR_CREDENTIALS_SOURCE: env.ALMADAR_CREDENTIALS_SOURCE || ""
+      }
+    });
+    this.factory.configure("storage", {
+      env: {
+        STORAGE_ACCESS_KEY_ID: env.STORAGE_ACCESS_KEY_ID || "",
+        STORAGE_SECRET_ACCESS_KEY: env.STORAGE_SECRET_ACCESS_KEY || "",
+        STORAGE_BUCKET: env.STORAGE_BUCKET || "",
+        STORAGE_REGION: env.STORAGE_REGION || "",
+        STORAGE_ENDPOINT: env.STORAGE_ENDPOINT || "",
+        STORAGE_PUBLIC_URL_BASE: env.STORAGE_PUBLIC_URL_BASE || ""
+      }
+    });
     this.factory.configure("webhook", {
       env: {
         WEBHOOK_SIGNING_SECRET: env.WEBHOOK_SIGNING_SECRET || "",