@almadar/integrations 2.25.0 → 2.27.0

package/dist/runtime/index.js

@@ -1,6 +1,8 @@
 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';
@@ -11,8 +13,6 @@ 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';
@@ -39,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");
@@ -56,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];
@@ -78,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({
@@ -267,7 +405,7 @@ var IntegrationFactory = class {
    */
   async execute(integration, action, params, context) {
     const instance = this.get(integration, context?.principal);
-    return await instance.execute(action, params);
+    return await instance.execute(action, params, context);
   }
   /**
    * Check if integration is configured
@@ -330,6 +468,7 @@ function getInstalledCredentialStore() {
 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";
@@ -774,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
     });
@@ -856,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 {
@@ -888,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,
@@ -1298,20 +1446,53 @@ 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");
+    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;
     }
-    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
+    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)
     });
-    this.client = google.drive({ version: "v3", auth });
-    this.logger.info("Drive integration initialized", { delegated: Boolean(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);
@@ -1363,7 +1544,7 @@ var DriveIntegration = class extends BaseIntegration {
     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({
+    const response = await this.readClient().files.list({
       q: clauses.join(" and "),
       pageSize: maxResults || 100,
       fields: "files(id, name, mimeType, size, modifiedTime, webViewLink)"
@@ -1381,11 +1562,11 @@ var DriveIntegration = class extends BaseIntegration {
   }
   async getFile(params) {
     const fileId = params.fileId;
-    const meta = await this.client.files.get({
+    const meta = await this.readClient().files.get({
       fileId,
       fields: "id, name, mimeType, size"
     });
-    const content = await this.client.files.get(
+    const content = await this.readClient().files.get(
       { fileId, alt: "media" },
       { responseType: "arraybuffer" }
     );
@@ -1401,10 +1582,11 @@ var DriveIntegration = class extends BaseIntegration {
   async uploadFile(params) {
     const { name, content, mimeType, folderId } = params;
     const { bytes, contentType } = decodeContent(content);
-    const response = await this.client.files.create({
+    const parent = folderId || this.defaultFolderId;
+    const response = await this.writeClient().files.create({
       requestBody: {
         name,
-        parents: folderId ? [folderId] : void 0
+        parents: parent ? [parent] : void 0
       },
       media: {
         mimeType: mimeType || contentType || "application/octet-stream",
@@ -1420,11 +1602,12 @@ var DriveIntegration = class extends BaseIntegration {
   }
   async createFolder(params) {
     const { name, parentId } = params;
-    const response = await this.client.files.create({
+    const parent = parentId || this.defaultFolderId;
+    const response = await this.writeClient().files.create({
       requestBody: {
         name,
         mimeType: "application/vnd.google-apps.folder",
-        parents: parentId ? [parentId] : void 0
+        parents: parent ? [parent] : void 0
       },
       fields: "id, name"
     });
@@ -1432,7 +1615,7 @@ var DriveIntegration = class extends BaseIntegration {
   }
   async shareFile(params) {
     const { fileId, email, role } = params;
-    const response = await this.client.permissions.create({
+    const response = await this.readClient().permissions.create({
       fileId,
       requestBody: {
         type: "user",
@@ -3446,6 +3629,27 @@ var PROVIDER_AUTH_URLS = {
 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);
@@ -3457,8 +3661,8 @@ var OAuthIntegration = class extends BaseIntegration {
     this.refreshIndex = /* @__PURE__ */ new Map();
     /** Maps access token -> mock user session */
     this.sessions = /* @__PURE__ */ new Map();
-    /** Maps state -> pending OIDC authorization (real backend) */
-    this.pending = /* @__PURE__ */ new Map();
+    /** 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 */
@@ -3468,6 +3672,9 @@ var OAuthIntegration = class extends BaseIntegration {
       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);
     if (!validation.valid) {
@@ -3559,17 +3766,17 @@ var OAuthIntegration = class extends BaseIntegration {
       parameters.prompt = "consent";
     }
     const authUrl = oidc.buildAuthorizationUrl(configuration, parameters);
-    this.pending.set(state, { provider, redirectUri, pkceVerifier });
+    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 = this.pending.get(state);
+    const pendingAuth = await this.pendingStore().take(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);
@@ -3756,131 +3963,10 @@ var OAuthIntegration = class extends BaseIntegration {
 };
 registerIntegration("oauth", OAuthIntegration);
 
-// 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_]*$/;
+var ROLE_GATED_ACTIONS = /* @__PURE__ */ new Set(["set", "remove", "test", "rotate"]);
+var DEFAULT_ADMIN_ROLES = ["admin", "owner"];
 function isProbeService(service) {
   return service in serviceProbes;
 }
@@ -3889,7 +3975,20 @@ var CredentialsIntegration = class extends BaseIntegration {
     super(config);
     this.logger.info("Credentials integration initialized (tenant credential store surface)");
   }
-  async execute(action, params) {
+  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 {
@@ -3917,8 +4016,16 @@ var CredentialsIntegration = class extends BaseIntegration {
           data = await this.remove(params.service, params.envVar);
           break;
         case "test":
-          data = await this.test(params.service);
+          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}`);
       }
@@ -3931,6 +4038,11 @@ var CredentialsIntegration = class extends BaseIntegration {
       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] ?? [];
   }
@@ -3950,6 +4062,10 @@ var CredentialsIntegration = class extends BaseIntegration {
       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]));
@@ -3959,7 +4075,7 @@ var CredentialsIntegration = class extends BaseIntegration {
       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 fromEnv = this.storeFirst() ? void 0 : process.env[envVar];
         const source = fromStore ? "store" : fromEnv ? "env" : "none";
         entries.push({
           service,
@@ -4003,7 +4119,7 @@ var CredentialsIntegration = class extends BaseIntegration {
     this.assertSettable(service, envVar);
     return { removed: await store.remove(envVar) };
   }
-  async test(service) {
+  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;
@@ -4018,7 +4134,7 @@ var CredentialsIntegration = class extends BaseIntegration {
     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);
+    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` };
     }
@@ -4248,10 +4364,16 @@ var StorageIntegration = class extends BaseIntegration {
     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 })
+        new ListObjectsV2Command({
+          Bucket: bucket,
+          Prefix: prefix || void 0,
+          MaxKeys: maxKeys,
+          ContinuationToken: continuationToken
+        })
       );
       return {
         keys: (response.Contents ?? []).map((entry) => ({
@@ -4259,9 +4381,8 @@ var StorageIntegration = class extends BaseIntegration {
           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)
+        truncated: Boolean(response.IsTruncated),
+        ...response.IsTruncated && response.NextContinuationToken !== void 0 ? { nextToken: response.NextContinuationToken } : {}
       };
     }
     const bucketPrefix = `${bucket}/`;
@@ -4276,7 +4397,14 @@ var StorageIntegration = class extends BaseIntegration {
       });
     }
     results.sort((a, b) => a.key.localeCompare(b.key));
-    return { keys: results.slice(0, maxKeys), 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: page,
+      truncated,
+      ...truncated ? { nextToken: String(offset + maxKeys) } : {}
+    };
   }
   async deleteObject(params) {
     const bucket = this.bucketOf(params);
@@ -5128,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)) {
@@ -5157,6 +5298,7 @@ var RuntimeIntegrationManager = class {
   constructor() {
     this.credentialStore = null;
     this.storeEnvBase = null;
+    this.storeFirst = false;
     this.factory = new IntegrationFactory();
     this.installNotConfiguredFallback();
     installActiveFactory(this.factory);
@@ -5172,16 +5314,51 @@ var RuntimeIntegrationManager = class {
   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();
   }
-  /** Re-derive configs from base env + warmed store values; drop stale instances. */
+  /** 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.invalidate();
-    this.configureFromEnv({ ...this.storeEnvBase, ...this.credentialStore.snapshotEnv() });
+    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
@@ -5290,11 +5467,15 @@ var RuntimeIntegrationManager = class {
         }
       });
     }
-    if (env.GOOGLE_DRIVE_SA_KEY) {
+    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_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 || ""
         }
       });
     }
@@ -5334,7 +5515,12 @@ var RuntimeIntegrationManager = class {
         }
       });
     }
-    this.factory.configure("credentials", { env: {} });
+    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 || "",