@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/packages/connectors/cloudflare/src/scope-catalog.js

@@ -0,0 +1,345 @@
+/**
+ * Cloudflare OAuth scope catalog — every Local Studio picker scope (~315).
+ *
+ * These ARE offerable permissions. Organize via feature packs / permission
+ * products (`permission-options.js`). Default mint stays least-privilege
+ * (baseline + selected packs). Users may explicitly opt into the full set with
+ * pack \`all\` or \`requestedCloudflareScopes({ all: true })\`.
+ *
+ * Source: AgentSam Local Studio Cloudflare OAuth scope picker.
+ */
+
+export const CLOUDFLARE_ALL_SCOPES = Object.freeze([
+  // Developer Platform
+  'agent-memory.write',
+  'browser-rendering.read',
+  'browser-rendering.write',
+  'cf-agents.read',
+  'cf-agents.write',
+  'cloud-connector.read',
+  'cloud-connector.write',
+  'cloudchamber.read',
+  'cloudchamber.write',
+  'constellation.read',
+  'constellation.write',
+  'd1.read',
+  'd1.write',
+  'flagship.evaluate',
+  'flagship.read',
+  'flagship.write',
+  'query-cache.read',
+  'query-cache.write',
+  'k2.read',
+  'k2.write',
+  'k2.consume',
+  'k2.produce',
+  'mcp-portals.read',
+  'mcp-portals.write',
+  'messaging.edit',
+  'messaging.read',
+  'cfspeed.read',
+  'cfspeed.write',
+  'page.read',
+  'page.write',
+  'pipelines.read',
+  'pipelines.send',
+  'pipelines.write',
+  'pubsub.read',
+  'pubsub.write',
+  'queues.read',
+  'queues.write',
+  'realtime.write',
+  'realtime.admin',
+  'realtime.read',
+  'secrets-store.read',
+  'secrets-store.write',
+  'vectorize.read',
+  'vectorize.write',
+  'workers-ci.read',
+  'workers-ci.write',
+  'containers.read',
+  'containers.write',
+  'workers-kv-storage.read',
+  'workers-kv-storage.write',
+  'workers-observability.read',
+  'workers-observability-telemetry.write',
+  'workers-observability.write',
+  'r2-catalog.read',
+  'r2-catalog.write',
+  'r2-catalog-sql.read',
+  'workers-r2-bucket-item.read',
+  'workers-r2-bucket-item.write',
+  'workers-r2.read',
+  'workers-r2.write',
+  'workers-routes.read',
+  'workers-routes.write',
+  'workers-scripts.read',
+  'workers-scripts.write',
+  'workers-tail.read',
+  // AI & Machine Learning
+  'aiaudit.read',
+  'aiaudit.write',
+  'aig.read',
+  'aig.run',
+  'aig.write',
+  'ai-search.index',
+  'ai-search.read',
+  'ai-search.run',
+  'ai-search.write',
+  'agw.read',
+  'agw.run',
+  'agw.write',
+  'rag.read',
+  'rag.write',
+  'rag.run',
+  'firewall-for-ai.read',
+  'firewall-for-ai.write',
+  'websearch.read',
+  'websearch.run',
+  'websearch.write',
+  'ai-model.read',
+  'ai-model.write',
+  'ai.read',
+  'ai.write',
+  // DNS & Zones
+  'account-dns-settings.read',
+  'account-dns-settings.write',
+  'dns-firewall.read',
+  'dns-firewall.write',
+  'dns.read',
+  'dns-view.read',
+  'dns-view.write',
+  'dns.write',
+  'registrar-domains.admin',
+  'registrar-domains.read',
+  'registrar-sandbox-domains.admin',
+  'registrar-sandbox-domains.read',
+  'zone-custom-asset.read',
+  'zone-custom-asset.write',
+  'zone-dns-settings.read',
+  'zone-dns-settings.write',
+  'zone.read',
+  'zone-settings.read',
+  'zone-settings.write',
+  'zone-versioning.read',
+  'zone-versioning.write',
+  'zone.write',
+  // App Security
+  'fraud-detection-pii.read',
+  'account-firewall-access-rules.read',
+  'account-firewall-access-rules.write',
+  'account-security-center-insights.read',
+  'account-security-center-insights.write',
+  'account-waf.read',
+  'account-waf.write',
+  'request-tracer.read',
+  'reports-application-security-report.read',
+  'bot-management-feedback.read',
+  'bot-management-feedback.write',
+  'bot-management.read',
+  'bot-management.write',
+  'http-applications.read',
+  'http-applications.write',
+  'http-ddos-managed-ruleset.read',
+  'http-ddos-managed-ruleset.write',
+  'tag.read',
+  'tag.write',
+  'url-scanner.read',
+  'url-scanner.write',
+  'zone-security-center-insights.read',
+  'zone-security-center-insights.write',
+  'zone-waf.read',
+  'zone-waf.write',
+  // Rules & Configuration
+  'account-custom-error-rules.read',
+  'account-custom-error-rules.write',
+  'account-custom-pages.read',
+  'account-custom-pages.write',
+  'account-rule-lists.read',
+  'account-rule-lists.write',
+  'account-rulesets.read',
+  'account-rulesets.write',
+  'config-settings.read',
+  'config-settings.write',
+  'custom-errors.read',
+  'custom-errors.write',
+  'custom-pages.read',
+  'custom-pages.write',
+  'dynamic-redirect.read',
+  'dynamic-redirect.write',
+  'managed-headers.read',
+  'managed-headers.write',
+  'mass-url-redirects.read',
+  'mass-url-redirects.write',
+  'origin.read',
+  'origin.write',
+  'payments-gateway.read',
+  'payments-gateway.write',
+  // Cloudflare One / Zero Trust
+  'access-app.read',
+  'access-app.revoke',
+  'access-app.write',
+  'access.read',
+  'zone-access.read',
+  'access.revoke',
+  'zone-access.revoke',
+  'access.write',
+  'zone-access.write',
+  'access-audit-log.read',
+  'access-custom-page.read',
+  'access-custom-page.write',
+  'access-device-posture.read',
+  'access-device-posture.write',
+  'access-group.read',
+  'access-group.write',
+  'access-idp.read',
+  'access-idp.write',
+  'access-key.read',
+  'access-key.write',
+  'access-certificate.read',
+  'access-certificate.write',
+  'access-org.read',
+  'access-org.revoke',
+  'access-org.write',
+  'access-acct.read',
+  'access-acct.revoke',
+  'access-acct.write',
+  'access-policy.read',
+  'access-policy.write',
+  'access-policy-test.read',
+  'access-policy-test.write',
+  'access-saml-certificate.read',
+  'access-saml-certificate.write',
+  'access-scim-log.read',
+  'access-population.read',
+  'access-population.write',
+  'access-ssh-auditing.read',
+  'access-ssh-auditing.write',
+  'access-service-token.read',
+  'access-service-token.write',
+  'access-tag.read',
+  'access-tag.write',
+  'access-users.read',
+  'access-users.write',
+  'casb.read',
+  'casb.write',
+  'teams-cds-compute-account.read',
+  'teams-cds-compute-account.write',
+  'teams-dex.read',
+  'teams-dex.write',
+  'teams-connector-cloudflared.monitoring',
+  'teams-connector-warp.read',
+  'teams-connector-warp.write',
+  'teams-connector-cloudflared.read',
+  'teams-connector-cloudflared.write',
+  'teams-connectors.read',
+  'teams-connectors.write',
+  'teams-networks.read',
+  'teams-networks.write',
+  'argotunnel.read',
+  'argotunnel.write',
+  'teams-secure.location',
+  'dls.read',
+  'dls.write',
+  'teams.read',
+  'teams.report',
+  'teams-resilience.read',
+  'teams-resilience.write',
+  'teams.write',
+  'teams-pii.read',
+  'access-seats.write',
+  // Analytics & Logs
+  'account-analytics.read',
+  'analytics.read',
+  'intel.read',
+  'intel.write',
+  'account-logs.read',
+  'logs.read',
+  'account-logs.write',
+  'logs.write',
+  'radar.read',
+  'zone-observability.read',
+  'zone-observability.write',
+  // Network Services
+  'account-waiting-rooms.read',
+  'connectivity-directory.admin',
+  'connectivity-directory.bind',
+  'connectivity-directory.read',
+  'ip-prefix-bgp-on-demand.write',
+  'ip-prefix.read',
+  'ip-prefix.write',
+  'load-balancers-account.read',
+  'load-balancers-account.write',
+  'load-balancers.read',
+  'load-balancers.write',
+  'load-balancing-monitors-and-pools.read',
+  'load-balancing-monitors-and-pools.write',
+  'pcaps-api.read',
+  'pcaps-api.write',
+  'magic-firewall.read',
+  'magic-firewall.write',
+  'magic-transit.read',
+  'magic-transit.write',
+  'magic-wan.read',
+  'magic-wan.write',
+  'waiting-rooms.read',
+  'waiting-rooms.write',
+  'web3-hostnames.read',
+  'web3-hostnames.write',
+  // Media
+  'calls.read',
+  'calls.write',
+  'images.read',
+  'images.write',
+  'moq.read',
+  'moq.write',
+  'stream.read',
+  'stream.write',
+  // Email & Messaging
+  'cloud-email-security.read',
+  'cloud-email-security.write',
+  'email-routing-account-rule.read',
+  'email-routing-address.read',
+  'email-routing-address.write',
+  'email-routing-rule.read',
+  'email-routing-rule.write',
+  'email-routing-suppression.read',
+  'email-routing-suppression.write',
+  'email-security-dmarcreports.write',
+  'email-sending.read',
+  'email-sending.write',
+  // Cache & Performance
+  'account-ssl-and-certificates.read',
+  'account-ssl-and-certificates.write',
+  'cache.purge',
+  'cache-settings.read',
+  'cache-settings.write',
+  'ssl-and-certificates.read',
+  'ssl-and-certificates.write',
+  // Account & Billing
+  'account-api-gateway.write',
+  'account-api-gateway.read',
+  'account-custom-asset.read',
+  'account-custom-asset.write',
+  'account-settings.read',
+  'account-settings.write',
+  'apps.write',
+  'integration.write',
+  'memberships.read',
+  'memberships.write',
+  'notifications.read',
+  'notifications.write',
+  'scim-provisioning.write',
+  'user-details.read',
+  // Other
+  'artifacts.read',
+  'artifacts.write',
+  'resource-library.read',
+  'resource-library.write',
+  'resource-sharing.read',
+  'offline_access',
+]);
+
+export function isKnownCloudflareScope(scope) {
+  return CLOUDFLARE_ALL_SCOPES.includes(String(scope || '').trim());
+}

package/packages/connectors/cloudflare/src/vault.js

@@ -19,11 +19,11 @@ function bytesToB64(bytes) {
 }
 
 export function vaultConfigured(env = {}) {
-  return Boolean(env.VAULT_MASTER_KEY || env.VAULT_KEY);
+  return Boolean(env.VAULT_MASTER_KEY);
 }
 
 async function importVaultKey(env) {
-  const raw = env.VAULT_MASTER_KEY || env.VAULT_KEY;
+  const raw = env.VAULT_MASTER_KEY;
   if (!raw) throw new Error('VAULT_MASTER_KEY missing');
   let keyBytes;
   try {

package/packages/connectors/cloudflare/tests/capabilities.test.mjs

@@ -0,0 +1,276 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  requestedCloudflareScopes,
+  CLOUDFLARE_ALL_SCOPES,
+  CLOUDFLARE_BASELINE_SCOPES,
+  scopesForCapabilities,
+  assessCapabilityAuthorization,
+  CloudflareApiClient,
+  resolveCloudflareApiAuth,
+  resolveCloudflareCredential,
+  workflows,
+  scanner,
+  keyless,
+  pages,
+  snippets,
+  getCloudflareCapability,
+} from '../src/index.js';
+
+describe('cloudflare capability-scoped auth', () => {
+  it('does not request the full scope catalog by default', () => {
+    const scopes = requestedCloudflareScopes();
+    assert.ok(scopes.length < 20);
+    assert.ok(scopes.length >= CLOUDFLARE_BASELINE_SCOPES.length);
+    assert.deepEqual(scopes.sort(), [...CLOUDFLARE_BASELINE_SCOPES].sort());
+    assert.ok(!scopes.includes('url-scanner.write'));
+    assert.equal(CLOUDFLARE_ALL_SCOPES.length, 315);
+  });
+
+  it('offers every Local Studio scope via permission products + pack all', async () => {
+    const {
+      assertPermissionCatalogCoversAllScopes,
+      listCloudflarePermissionProducts,
+      scopesForFeaturePacks,
+      requestedCloudflareScopes: req,
+    } = await import('../src/index.js');
+    const cover = assertPermissionCatalogCoversAllScopes();
+    assert.equal(cover.ok, true);
+    assert.equal(cover.scopes, 315);
+    assert.ok(listCloudflarePermissionProducts().length >= 150);
+    const allPack = scopesForFeaturePacks(['all']);
+    assert.equal(allPack.length, 315);
+    assert.equal(req({ packs: ['all'] }).length, 315);
+    assert.equal(req({ all: true }).length, 315);
+  });
+
+  it('upgrades scopes only for requested capabilities', () => {
+    const scopes = scopesForCapabilities({
+      capabilities: ['cloudflare.url_scanner', 'cloudflare.workflows', 'cloudflare.pages'],
+    });
+    assert.ok(scopes.includes('url-scanner.write'));
+    assert.ok(scopes.includes('workers-scripts.write'));
+    assert.ok(scopes.includes('page.write'));
+    assert.ok(!scopes.includes('ssl-and-certificates.write'));
+  });
+
+  it('uses images.read/write from OAuth catalog', () => {
+    const cap = getCloudflareCapability('cloudflare.images');
+    assert.deepEqual(cap.oauthScopes, ['images.read', 'images.write']);
+  });
+
+  it('does not invent snippets OAuth scope', () => {
+    const cap = getCloudflareCapability('cloudflare.snippets');
+    assert.equal(cap.oauthScopes.length, 0);
+    assert.equal(cap.tokenRequired, true);
+  });
+
+  it('marks URL Scanner as needs_authorization when scopes missing', () => {
+    const a = assessCapabilityAuthorization('cloudflare.url_scanner', ['account-settings.read']);
+    assert.equal(a.status, 'needs_authorization');
+    assert.ok(a.missing_scopes.includes('url-scanner.write'));
+    assert.match(a.permissionLabel, /URL Scanner/);
+  });
+
+  it('treats Keyless as enterprise add-on (not default setup)', () => {
+    const cap = getCloudflareCapability('cloudflare.keyless_ssl');
+    assert.equal(cap.availability, 'enterprise_addon');
+    assert.match(cap.availabilityNote, /Enterprise/);
+  });
+});
+
+describe('credential authority', () => {
+  it('does not use CLOUDFLARE_IMAGES_API_TOKEN as generic API auth', () => {
+    const auth = resolveCloudflareApiAuth({
+      CLOUDFLARE_IMAGES_API_TOKEN: 'images-only-secret',
+      CLOUDFLARE_ACCOUNT_ID: 'acct',
+    });
+    assert.equal(auth.configured, false);
+    assert.equal(auth.apiToken, '');
+  });
+
+  it('Images-specific token only resolves for cloudflare.images capability', async () => {
+    const generic = await resolveCloudflareCredential({
+      env: { CLOUDFLARE_IMAGES_API_TOKEN: 'images-only', CLOUDFLARE_ACCOUNT_ID: 'acct' },
+      authMode: 'token',
+      capabilityId: 'cloudflare.workflows',
+    });
+    assert.equal(generic.bearerToken, null);
+
+    const images = await resolveCloudflareCredential({
+      env: { CLOUDFLARE_IMAGES_API_TOKEN: 'images-only', CLOUDFLARE_ACCOUNT_ID: 'acct' },
+      authMode: 'token',
+      capabilityId: 'cloudflare.images',
+    });
+    assert.equal(images.bearerToken, 'images-only');
+    assert.equal(images.source, 'images_api_token');
+  });
+
+  it('prefers CLOUDFLARE_API_TOKEN for generic operations', async () => {
+    const cred = await resolveCloudflareCredential({
+      env: {
+        CLOUDFLARE_API_TOKEN: 'general',
+        CLOUDFLARE_IMAGES_API_TOKEN: 'images-only',
+        CLOUDFLARE_ACCOUNT_ID: 'acct',
+      },
+      authMode: 'token',
+    });
+    assert.equal(cred.bearerToken, 'general');
+    assert.equal(cred.source, 'api_token');
+  });
+
+  it('loads oauth from user_oauth_tokens when plaintext access_token present', async () => {
+    const env = {
+      DB: {
+        prepare() {
+          return {
+            bind() { return this; },
+            async first() {
+              return {
+                id: 42,
+                user_id: 'au_test',
+                provider: 'cloudflare',
+                account_identifier: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                access_token: 'oauth-bearer',
+                scopes: 'account-settings.read page.read',
+                is_active: 1,
+              };
+            },
+          };
+        },
+      },
+    };
+    const cred = await resolveCloudflareCredential({
+      env,
+      ownerId: 'au_test',
+      authMode: 'oauth',
+    });
+    assert.equal(cred.source, 'oauth_connection');
+    assert.equal(cred.bearerToken, 'oauth-bearer');
+    assert.equal(cred.accountId, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+    assert.ok(cred.grantedScopes.includes('page.read'));
+  });
+});
+
+describe('cloudflare API families (mocked)', () => {
+  it('workflows.list hits real Cloudflare path', async () => {
+    const calls = [];
+    const client = new CloudflareApiClient({
+      apiToken: 'test-token',
+      accountId: 'acct_test',
+      fetchImpl: async (url, init) => {
+        calls.push({ url, method: init.method, auth: init.headers.Authorization });
+        return {
+          ok: true,
+          status: 200,
+          headers: new Map(),
+          text: async () => JSON.stringify({
+            success: true,
+            result: [{ name: 'site-release', id: 'wf1' }],
+            result_info: { count: 1 },
+          }),
+        };
+      },
+    });
+    const result = await workflows.workflowsList(client);
+    assert.equal(result.ok, true);
+    assert.equal(result.workflows[0].name, 'site-release');
+    assert.match(calls[0].url, /\/accounts\/acct_test\/workflows/);
+    assert.equal(calls[0].auth, 'Bearer test-token');
+  });
+
+  it('pages.list hits /pages/projects', async () => {
+    const client = new CloudflareApiClient({
+      apiToken: 'tok',
+      accountId: 'acct',
+      fetchImpl: async (url) => {
+        assert.match(url, /\/pages\/projects/);
+        return {
+          ok: true,
+          status: 200,
+          headers: { get: () => 'application/json', [Symbol.iterator]: function* () {} },
+          text: async () => JSON.stringify({ success: true, result: [{ name: 'demo' }] }),
+        };
+      },
+    });
+    const result = await pages.pagesList(client);
+    assert.equal(result.projects[0].name, 'demo');
+  });
+
+  it('snippet rules reconcile preserves foreign rules', () => {
+    const plan = snippets.reconcileSnippetRules(
+      [
+        { description: 'Customer hand rule', expression: 'true', enabled: true },
+        { description: '[AgentSam] old', expression: 'http.request.uri.path eq "/x"', enabled: true },
+      ],
+      [{ description: 'canonical host', snippet: 'canonical-host', expression: 'true', enabled: true }],
+    );
+    assert.equal(plan.foreign_preserved, 1);
+    assert.equal(plan.agentsam_rules, 1);
+    assert.equal(plan.next_count, 2);
+    assert.ok(plan.rules[1].description.startsWith('[AgentSam]'));
+    assert.equal(plan.rules[0].description, 'Customer hand rule');
+  });
+
+  it('scanner.scan posts to urlscanner/v2/scan', async () => {
+    const client = new CloudflareApiClient({
+      apiToken: 'tok',
+      accountId: 'acct',
+      fetchImpl: async (url, init) => {
+        assert.match(url, /\/urlscanner\/v2\/scan$/);
+        assert.equal(init.method, 'POST');
+        const body = JSON.parse(init.body);
+        assert.equal(body.url, 'https://example.com');
+        return {
+          ok: true,
+          status: 200,
+          headers: { get: () => 'application/json', [Symbol.iterator]: function* () {} },
+          text: async () => JSON.stringify({ success: true, result: { uuid: 'scan-1' } }),
+        };
+      },
+    });
+    const result = await scanner.scannerScan(client, 'https://example.com');
+    assert.equal(result.scan.uuid, 'scan-1');
+  });
+
+  it('403 returns permission remediation, not raw dump only', async () => {
+    const client = new CloudflareApiClient({
+      apiToken: 'tok',
+      accountId: 'acct',
+      fetchImpl: async () => ({
+        ok: false,
+        status: 403,
+        headers: { get: () => 'application/json', [Symbol.iterator]: function* () {} },
+        text: async () => JSON.stringify({
+          success: false,
+          errors: [{ message: 'Authentication error' }],
+        }),
+      }),
+    });
+    await assert.rejects(
+      () => scanner.scannerScan(client, 'https://example.com'),
+      (err) => {
+        assert.equal(err.code, 'cloudflare_permission_denied');
+        assert.equal(err.remediation.capability_id, 'cloudflare.url_scanner');
+        assert.match(err.remediation.permission_required, /URL Scanner/);
+        return true;
+      },
+    );
+  });
+
+  it('keyless status without zone stays advanced / non-mutating', async () => {
+    const client = new CloudflareApiClient({ apiToken: 'tok', accountId: 'acct' });
+    const result = await keyless.keylessStatus(client, null);
+    assert.equal(result.availability, 'enterprise_addon');
+    assert.equal(result.ok, false);
+    assert.match(result.learn, /Keyless/);
+  });
+
+  it('keyless rejects private key in create body', async () => {
+    const client = new CloudflareApiClient({ apiToken: 'tok', accountId: 'acct' });
+    await assert.rejects(
+      () => keyless.keylessCreate(client, 'zone1', { private_key: 'SECRET' }),
+      /private key must not be sent/i,
+    );
+  });
+});