@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/{src/lib → packages/agentsam-repository/src}/merkle/cloudflare-persistence.js

@@ -129,25 +129,15 @@ export function resolveWranglerMerklePersistence({
   };
 }
 
-function providerRepoId(git) {
-  const host = clean(git?.remoteHost).toLowerCase();
-  const fullName = clean(git?.repoFullName);
-  if (!fullName) return null;
-  if (host === 'github.com') return `github:${fullName}`;
-  if (host === 'gitlab.com') return `gitlab:${fullName}`;
-  if (host === 'bitbucket.org') return `bitbucket:${fullName}`;
-  return null;
-}
-
 function safeId(value) {
   return clean(value).replace(/[^A-Za-z0-9._-]+/g, '').slice(0, 96);
 }
 
-function snapshotIdFor({ snapshot, repoId, captureKind, deploymentId }) {
+function snapshotIdFor({ snapshot, repositoryId, captureKind, deploymentId }) {
   const deployment = safeId(deploymentId);
   if (captureKind === 'deploy' && deployment) return `mrs_dep_${deployment.toLowerCase()}`;
   const digest = createHash('sha256')
-    .update([repoId, snapshot.rootHash, snapshot.semantic?.rootHash || '', captureKind].join('\0'))
+    .update([repositoryId, snapshot.rootHash, snapshot.semantic?.rootHash || '', captureKind].join('\0'))
     .digest('hex');
   return `mrs_${digest.slice(0, 24)}`;
 }
@@ -167,8 +157,8 @@ function sqlInt(value) {
 export function buildMerklePersistencePlan({
   snapshot,
   root = process.cwd(),
-  ownerUserId,
-  repoId,
+  accountId,
+  repositoryId,
   source = 'local',
   captureKind = 'manual',
   connectionId = null,
@@ -180,24 +170,24 @@ export function buildMerklePersistencePlan({
   wrangler,
 } = {}) {
   if (!snapshot?.rootHash || !Array.isArray(snapshot?.entries)) throw new Error('merkle_snapshot_required');
-  const owner = clean(ownerUserId);
-  if (!owner) throw new Error('owner_user_id_required');
+  const account = clean(accountId);
+  const repository = clean(repositoryId);
+  if (!account) throw new Error('account_id_required');
+  if (!repository) throw new Error('repository_id_required');
   if (!CAPTURE_KINDS.has(captureKind)) throw new Error(`capture_kind_invalid:${captureKind}`);
   if (!SOURCES.has(source)) throw new Error(`source_invalid:${source}`);
   if (captureKind !== 'deploy' && !clean(connectionId) && !clean(runtimeLeaseId)) throw new Error('execution_provenance_required');
   let git = null;
   try { git = resolveGitContext({ cwd: root }); } catch { git = null; }
-  const resolvedRepoId = clean(repoId) || providerRepoId(git);
-  if (!resolvedRepoId) throw new Error('repo_id_required');
-  const snapshotId = snapshotIdFor({ snapshot, repoId: resolvedRepoId, captureKind, deploymentId });
+  const snapshotId = snapshotIdFor({ snapshot, repositoryId: repository, captureKind, deploymentId });
   const prefix = normalizeMerkleStoragePrefix(storagePrefix);
-  const storageKey = merkleSnapshotStorageKey({ ownerUserId: owner, repoId: resolvedRepoId, snapshotId, prefix });
+  const storageKey = merkleSnapshotStorageKey({ accountId: account, repositoryId: repository, snapshotId, prefix });
   const createdAt = Math.floor(Date.now() / 1000);
   const classifier = snapshot.semantic?.classifier || null;
   const row = {
     snapshot_id: snapshotId,
-    owner_user_id: owner,
-    repo_id: resolvedRepoId,
+    account_id: account,
+    repository_id: repository,
     repository: git?.remoteUrl || null,
     source,
     manifest_format: snapshot.format || 'agentsam-merkle',
@@ -235,7 +225,7 @@ export function buildMerklePersistencePlan({
 
 export function merklePersistenceUpsertSql(row) {
   return `INSERT INTO ${MERKLE_SNAPSHOT_TABLE} (
-  snapshot_id, owner_user_id, repo_id, repository, source,
+  snapshot_id, account_id, repository_id, repository, source,
   manifest_format, manifest_version, hash_algorithm, root_hash, policy_hash,
   resolved_commit_sha, resolved_tree_sha, git_branch, working_tree_dirty,
   connection_id, runtime_lease_id, storage_backend, storage_bucket, storage_key,
@@ -243,7 +233,7 @@ export function merklePersistenceUpsertSql(row) {
   capture_kind, deployment_id, worker_version_id, reference_label,
   created_at, persisted_at, metadata_root, classifier_format, classifier_version, classifier_source
 ) VALUES (
-  ${sqlText(row.snapshot_id)}, ${sqlText(row.owner_user_id)}, ${sqlText(row.repo_id)}, ${sqlText(row.repository)}, ${sqlText(row.source)},
+  ${sqlText(row.snapshot_id)}, ${sqlText(row.account_id)}, ${sqlText(row.repository_id)}, ${sqlText(row.repository)}, ${sqlText(row.source)},
   ${sqlText(row.manifest_format)}, ${sqlInt(row.manifest_version)}, ${sqlText(row.hash_algorithm)}, ${sqlText(row.root_hash)}, ${sqlText(row.policy_hash)},
   ${sqlText(row.resolved_commit_sha)}, ${sqlText(row.resolved_tree_sha)}, ${sqlText(row.git_branch)}, ${sqlInt(row.working_tree_dirty)},
   ${sqlText(row.connection_id)}, ${sqlText(row.runtime_lease_id)}, ${sqlText(row.storage_backend)}, ${sqlText(row.storage_bucket)}, ${sqlText(row.storage_key)},

package/{src/lib → packages/agentsam-repository/src}/merkle/index.js

@@ -10,6 +10,7 @@ export async function buildSemanticMetadata(...args) {
 export { validateSemanticMetadata, metadataRoot, FILEMETA_FORMAT, FILEMETA_VERSION } from './filemeta.js';
 
 export {
+  MERKLE_PERSISTENCE_SCHEMA_VERSION,
   MERKLE_SNAPSHOT_SCHEMA_SQL,
   MERKLE_SNAPSHOT_STORAGE_PREFIX,
   MERKLE_SNAPSHOT_TABLE,

package/{src/lib → packages/agentsam-repository/src}/merkle/persistence.js

@@ -27,15 +27,17 @@ export function normalizeMerkleStoragePrefix(value = MERKLE_SNAPSHOT_STORAGE_PRE
  * Provider-neutral object key. The host chooses which physical bucket is bound
  * to the logical WEBSITE_ASSETS role; the SDK never owns cloud credentials.
  */
-export function merkleSnapshotStorageKey({ ownerUserId, repoId, snapshotId, prefix = MERKLE_SNAPSHOT_STORAGE_PREFIX } = {}) {
-  return `${normalizeMerkleStoragePrefix(prefix)}/${safeSegment(ownerUserId, 'owner_user_id')}/${safeSegment(repoId, 'repo_id')}/${safeSegment(snapshotId, 'snapshot_id')}.json`;
+export const MERKLE_PERSISTENCE_SCHEMA_VERSION = 2;
+
+export function merkleSnapshotStorageKey({ accountId, repositoryId, snapshotId, prefix = MERKLE_SNAPSHOT_STORAGE_PREFIX } = {}) {
+  return `${normalizeMerkleStoragePrefix(prefix)}/${safeSegment(accountId, 'account_id')}/${safeSegment(repositoryId, 'repository_id')}/${safeSegment(snapshotId, 'snapshot_id')}.json`;
 }
 
 /** Portable D1/SQLite schema for hosts that opt into persisted Merkle snapshots. */
 export const MERKLE_SNAPSHOT_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${MERKLE_SNAPSHOT_TABLE} (
   snapshot_id TEXT PRIMARY KEY NOT NULL,
-  owner_user_id TEXT NOT NULL,
-  repo_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  repository_id TEXT NOT NULL,
   repository TEXT,
   source TEXT NOT NULL CHECK (source IN ('github','gitlab','bitbucket','local','upload')),
   manifest_format TEXT NOT NULL DEFAULT 'agentsam-merkle',

package/{src/lib → packages/agentsam-repository/src}/merkle/policy.js

@@ -2,6 +2,7 @@ import { comparePaths } from './hash.js';
 
 export const DEFAULT_IGNORES = Object.freeze([
   '.git', 'node_modules', 'dist', '.DS_Store', '.agentsam/cache', '.agentsam/merkle', '.agentsam/merkle.json',
+  '.agentsam/backups', '.agentsam/intelligence/archive',
 ]);
 export function validPath(value, allowRoot = false) {
   return typeof value === 'string' && ((allowRoot && value === '') || (value.length > 0 &&

package/packages/agentsam-repository/test/contracts.test.mjs

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  createRepositoryContract,
+  createRepositoryDependency,
+  createRepositoryIdentity,
+} from '../src/contracts.js';
+
+test('repository package owns account/repository graph normalization', () => {
+  const identity = createRepositoryIdentity({
+    repository_id: 'github:owner/repo',
+    full_name: 'owner/repo',
+    role: 'runtime',
+  });
+  assert.equal(identity.repository_id, 'github:owner/repo');
+  assert.equal(Object.hasOwn(identity, 'account_id'), false);
+
+  const contract = createRepositoryContract({
+    id: 'contract:runtime:v1',
+    account_id: 'au_test',
+    repository_id: identity.repository_id,
+    contract_key: 'runtime',
+    contract_version: '1',
+    contract_type: 'runtime',
+    contract_hash: `sha256:${'1'.repeat(64)}`,
+  });
+  assert.equal(contract.account_id, 'au_test');
+
+  const dependency = createRepositoryDependency({
+    id: 'dep:a:b',
+    account_id: 'au_test',
+    source_repository_id: 'github:owner/a',
+    target_repository_id: 'github:owner/b',
+    dependency_type: 'contract',
+    criticality: 'strict',
+    failure_policy: 'block_certification',
+  });
+  assert.equal(dependency.failure_policy, 'block_certification');
+  assert.throws(() => createRepositoryContract({ ...contract, workspace_id: 'ws_legacy' }), /legacy ownership field/);
+});

package/packages/agentsam-repository/test/git-context.test.mjs

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import test from 'node:test';
+import { normalizeGitRemote, resolveGitContext } from '../src/git-context.js';
+
+test('repository package derives resource identity from Git, not account environment', t => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-repository-git-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  execFileSync('git', ['init', '-q', root]);
+  execFileSync('git', ['-C', root, 'remote', 'add', 'origin', 'git@github.com:ExampleOrg/DemoRepo.git']);
+  const context = resolveGitContext({ cwd: root });
+  assert.equal(context.repoFullName, 'ExampleOrg/DemoRepo');
+  assert.equal(context.owner, 'ExampleOrg');
+  assert.equal(context.repo, 'DemoRepo');
+  assert.equal(context.revisionSha, null);
+});
+
+test('remote normalization supports HTTPS and SSH without ownership fields', () => {
+  assert.equal(normalizeGitRemote('https://github.com/Owner/Repo.git').repoFullName, 'Owner/Repo');
+  assert.equal(normalizeGitRemote('git@github.com:Owner/Repo.git').repoFullName, 'Owner/Repo');
+});

package/{test/merkle.test.mjs → packages/agentsam-repository/test/merkle-core.test.mjs}

@@ -3,11 +3,7 @@ import { test } from 'node:test';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { buildMerkleTree, saveSnapshot, readSnapshot, validateSnapshot, diffTrees, metadataRoot } from '../src/lib/merkle/index.js';
-
-const cli = fileURLToPath(new URL('../src/cli.js', import.meta.url));
+import { buildMerkleTree, saveSnapshot, readSnapshot, validateSnapshot, diffTrees, metadataRoot } from '../src/merkle/index.js';
 async function fixture(t) {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), 'agentsam-merkle-test-'));
   t.after(() => fs.rm(root, { recursive: true, force: true }));
@@ -17,8 +13,6 @@ async function write(root, name, content = name) {
   await fs.mkdir(path.dirname(path.join(root, name)), { recursive: true });
   await fs.writeFile(path.join(root, name), content);
 }
-function run(args, cwd) { return spawnSync(process.execPath, [cli, 'merkle', ...args], { cwd, encoding: 'utf8', timeout: 15000 }); }
-
 test('version 1 hashes match independent SHA-256 protocol vectors', async (t) => {
   const root = await fixture(t);
   assert.equal((await buildMerkleTree(root)).rootHash, 'sha256:6ce8ca443f3cf6c719c5cb9acc121403addf3f499eefa3db25edacf2c7fe0f94');
@@ -49,7 +43,7 @@ test('default ignores, explicit dist inclusion, literal exclusions, and empty-di
   const root = await fixture(t);
   await write(root, 'src/app.js');
   const first = await buildMerkleTree(root);
-  for (const name of ['.git/config', 'node_modules/pkg/file', 'dist/app.js', '.DS_Store', '.agentsam/cache/data', '.agentsam/merkle/old.json']) await write(root, name);
+  for (const name of ['.git/config', 'node_modules/pkg/file', 'dist/app.js', '.DS_Store', '.agentsam/cache/data', '.agentsam/merkle/old.json', '.agentsam/backups/pre-cleanup.bak', '.agentsam/intelligence/archive/20260912/repo_intelligence.json']) await write(root, name);
   await fs.mkdir(path.join(root, 'empty'));
   assert.equal(first.rootHash, (await buildMerkleTree(root)).rootHash);
   const withDist = await buildMerkleTree(root, { include: ['dist'] });
@@ -172,30 +166,6 @@ test('scan fails when a file disappears and honors cancellation', async (t) => {
   await assert.rejects(buildMerkleTree(root, { signal: controller.signal }), { name: 'AbortError' });
 });
 
-test('CLI snapshot/verify/diff supports JSON, moved roots, and distinct mismatch/error exit codes', async (t) => {
-  const root = await fixture(t), moved = await fixture(t);
-  await write(root, 'a.txt', 'hello'); await write(moved, 'a.txt', 'hello');
-  const saved = run(['snapshot', '.', '--json'], root);
-  assert.equal(saved.status, 0, saved.stderr);
-  const manifest = JSON.parse(saved.stdout);
-  assert.ok(manifest.output.endsWith('merkle.json'));
-  const matching = run(['verify', manifest.output, '--root', moved, '--json'], root);
-  assert.equal(matching.status, 0, matching.stderr);
-  assert.equal(JSON.parse(matching.stdout).equal, true);
-  await write(moved, 'a.txt', 'changed'); await write(moved, 'b.txt', 'new');
-  const changed = run(['verify', manifest.output, '--root', moved, '--json'], root);
-  assert.equal(changed.status, 1, changed.stderr);
-  assert.deepEqual(JSON.parse(changed.stdout).stats, { unchanged: 0, modified: 1, added: 1, removed: 0 });
-  const diff = run(['diff', root, moved, '--json'], root);
-  assert.equal(diff.status, 1, diff.stderr);
-  const invalid = run(['root', '.', '--typo', '--json'], root);
-  assert.equal(invalid.status, 2); assert.equal(invalid.stdout, '');
-  assert.match(JSON.parse(invalid.stderr).error, /Unknown option/);
-  const piped = run(['inspect', '.', '--tui'], root);
-  assert.equal(piped.status, 0, piped.stderr);
-  assert.ok(!piped.stdout.includes('\x1b'));
-});
-
 test('semantic index records execution domains, environment access, and resolved local imports as Merkle-bound evidence', async (t) => {
   const root = await fixture(t);
   await write(root, 'package.json', JSON.stringify({ name: 'boundary-fixture', version: '1.0.0' }));

package/{test → packages/agentsam-repository/test}/merkle-persistence.test.mjs

@@ -1,6 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  MERKLE_PERSISTENCE_SCHEMA_VERSION,
   MERKLE_SNAPSHOT_SCHEMA_SQL,
   MERKLE_SNAPSHOT_STORAGE_PREFIX,
   MERKLE_SNAPSHOT_TABLE,
@@ -9,15 +10,19 @@ import {
   merklePersistenceUpsertSql,
   merkleSnapshotStorageKey,
   resolveWranglerMerklePersistence,
-} from '../src/lib/merkle/index.js';
+} from '../src/merkle/index.js';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
 test('portable Merkle persistence names one table, prefix, and logical asset role', () => {
+  assert.equal(MERKLE_PERSISTENCE_SCHEMA_VERSION, 2);
   assert.equal(MERKLE_SNAPSHOT_TABLE, 'agentsam_fs_merkle_snapshots');
   assert.equal(MERKLE_SNAPSHOT_STORAGE_PREFIX, 'agentsam_fs_merkle_snapshots');
   assert.equal(MERKLE_WEBSITE_ASSETS_BINDING, 'WEBSITE_ASSETS');
+  assert.match(MERKLE_SNAPSHOT_SCHEMA_SQL, /account_id TEXT NOT NULL/);
+  assert.match(MERKLE_SNAPSHOT_SCHEMA_SQL, /repository_id TEXT NOT NULL/);
+  assert.doesNotMatch(MERKLE_SNAPSHOT_SCHEMA_SQL, /owner_user_id|\brepo_id\b/);
   assert.match(MERKLE_SNAPSHOT_SCHEMA_SQL, /metadata_root TEXT/);
   assert.match(MERKLE_SNAPSHOT_SCHEMA_SQL, /classifier_format TEXT/);
   assert.match(MERKLE_SNAPSHOT_SCHEMA_SQL, /storage_bucket TEXT/);
@@ -25,12 +30,12 @@ test('portable Merkle persistence names one table, prefix, and logical asset rol
 
 test('snapshot storage keys stay beneath the canonical prefix and encode repo identity', () => {
   const key = merkleSnapshotStorageKey({
-    ownerUserId: 'au_example',
-    repoId: 'github:owner/repo',
+    accountId: 'au_example',
+    repositoryId: 'github:owner/repo',
     snapshotId: 'mrs_example',
   });
   assert.equal(key, 'agentsam_fs_merkle_snapshots/au_example/github%3Aowner%2Frepo/mrs_example.json');
-  const escaped = merkleSnapshotStorageKey({ ownerUserId: '../oops', repoId: 'repo', snapshotId: 'snap' });
+  const escaped = merkleSnapshotStorageKey({ accountId: '../oops', repositoryId: 'repo', snapshotId: 'snap' });
   assert.ok(!escaped.includes('/../'));
   assert.ok(escaped.includes('..%2Foops'));
 });
@@ -63,7 +68,7 @@ test('persistence plan keeps content, policy, and metadata identities separate',
     },
   };
   const plan = buildMerklePersistencePlan({
-    snapshot, root: process.cwd(), ownerUserId: 'au_test', repoId: 'github:owner/repo', source: 'github',
+    snapshot, root: process.cwd(), accountId: 'au_test', repositoryId: 'github:owner/repo', source: 'github',
     captureKind: 'agent', connectionId: 'conn_test',
     wrangler: { storage_bucket: 'customer-assets', r2_binding: 'WEBSITE_ASSETS', database_name: 'customer-db', d1_binding: 'DB' },
   });
@@ -85,7 +90,7 @@ test('non-deploy persistence requires execution provenance', () => {
     policyHash: `sha256:${'2'.repeat(64)}`, entries: [], stats: { files: 0, directories: 0, symlinks: 0, bytes: 0 },
   };
   assert.throws(() => buildMerklePersistencePlan({
-    snapshot, root: process.cwd(), ownerUserId: 'au_test', repoId: 'github:owner/repo', captureKind: 'agent',
+    snapshot, root: process.cwd(), accountId: 'au_test', repositoryId: 'github:owner/repo', captureKind: 'agent',
     wrangler: { storage_bucket: 'customer-assets', r2_binding: 'WEBSITE_ASSETS', database_name: 'customer-db', d1_binding: 'DB' },
   }), /execution_provenance_required/);
 });

package/packages/connectors/cloudflare/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@inneranimalmedia/agentsam-connector-cloudflare",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  }
+}

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

@@ -0,0 +1,127 @@
+/**
+ * Cloudflare account connector (not an identity provider).
+ * Answers: what Cloudflare account has this authenticated AgentSam user authorized?
+ */
+
+export const CLOUDFLARE_OAUTH_AUTHORIZE_URL = 'https://dash.cloudflare.com/oauth2/auth';
+export const CLOUDFLARE_OAUTH_TOKEN_URL = 'https://dash.cloudflare.com/oauth2/token';
+export const CLOUDFLARE_CALLBACK_PATH = '/api/connections/cloudflare/callback';
+export const CLOUDFLARE_FIXTURE_CLIENT_ID = 'sillynotreal';
+export const CLOUDFLARE_FIXTURE_CLIENT_SECRET = 'sillynotreal-secret';
+
+export const CLOUDFLARE_OAUTH_REVOKE_URL = 'https://dash.cloudflare.com/oauth2/revoke';
+
+/** Smallest useful scopes mapped to Cloudflare API token permission names. */
+export const CLOUDFLARE_CAPABILITY_SCOPES = Object.freeze({
+  workers_deploy: {
+    scopes: ['workers-scripts.write'],
+    why: 'Deploy Workers for the connected account (Workers Scripts Edit).',
+  },
+  d1_inspect: {
+    scopes: ['d1.read'],
+    why: 'Inspect D1 databases bound to the deployable.',
+  },
+  r2_inspect: {
+    scopes: ['workers-r2-storage.read'],
+    why: 'Inspect R2 buckets bound to the deployable.',
+  },
+  worker_logs: {
+    scopes: ['workers-scripts.read'],
+    why: 'Read Worker script metadata/logs for postdeploy health.',
+  },
+});
+
+export function requestedCloudflareScopes() {
+  const set = new Set();
+  for (const cap of Object.values(CLOUDFLARE_CAPABILITY_SCOPES)) {
+    for (const scope of cap.scopes) set.add(scope);
+  }
+  return [...set];
+}
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function isFixtureCloudflareCredential(value) {
+  const v = clean(value);
+  return v === CLOUDFLARE_FIXTURE_CLIENT_ID || v === CLOUDFLARE_FIXTURE_CLIENT_SECRET;
+}
+
+export function resolveCloudflareOAuthClient(env = {}) {
+  const clientId = clean(env.CLOUDFLARE_OAUTH_CLIENT_ID);
+  const clientSecret = clean(env.CLOUDFLARE_OAUTH_CLIENT_SECRET);
+  const present = Boolean(clientId && clientSecret);
+  const fixture = isFixtureCloudflareCredential(clientId) || isFixtureCloudflareCredential(clientSecret);
+  if (!present) {
+    return {
+      configured: false,
+      productionReady: false,
+      fixture: false,
+      status: 'not_configured',
+      clientIdConfigured: Boolean(clientId),
+      secretConfigured: Boolean(clientSecret),
+    };
+  }
+  return {
+    configured: true,
+    productionReady: !fixture,
+    fixture,
+    status: fixture ? 'fixture' : 'ready',
+    clientIdConfigured: true,
+    secretConfigured: true,
+  };
+}
+
+export function cloudflareConnectionSafeStatus(env = {}, connection = null, ownerId = '') {
+  const client = resolveCloudflareOAuthClient(env);
+  const record = connection && connection.ownerId === ownerId ? connection : null;
+  return {
+    provider: 'cloudflare',
+    status: record ? 'connected' : client.status === 'ready' ? 'ready' : client.status,
+    configured: client.configured && client.productionReady,
+    fixture: client.fixture,
+    clientId: client.clientIdConfigured ? 'configured' : 'missing',
+    secret: client.secretConfigured ? 'configured' : 'missing',
+    callbackPath: CLOUDFLARE_CALLBACK_PATH,
+    connection: record
+      ? {
+          connection_id: record.connectionId,
+          owner: record.ownerId,
+          cloudflare_account_id: record.cloudflareAccountId || null,
+          scopes: record.scopes || [],
+          status: record.status,
+          created_at: record.createdAt,
+          updated_at: record.updatedAt,
+          expires_at: record.expiresAt || null,
+        }
+      : null,
+  };
+}
+
+export function assertConnectionOwner(connection, ownerId) {
+  if (!ownerId) {
+    const err = new Error('unauthenticated');
+    err.code = 'unauthenticated';
+    throw err;
+  }
+  if (!connection || connection.ownerId !== ownerId) {
+    const err = new Error('cloudflare_connection_forbidden');
+    err.code = 'cloudflare_connection_forbidden';
+    throw err;
+  }
+  return connection;
+}
+
+export function buildAuthorizeUrl({ clientId, redirectUri, state, codeChallenge, scopes }) {
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    state,
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+    scope: (scopes || requestedCloudflareScopes()).join(' '),
+  });
+  return `${CLOUDFLARE_OAUTH_AUTHORIZE_URL}?${params}`;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Cloudflare connection ownership is derived from authenticated AgentSam session.
+ * Browser-submitted account_id / user_id / owner_id / X-User-Id are never authority.
+ */
+
+const UNTRUSTED = new Set(['account_id', 'user_id', 'owner_id', 'workspace_id']);
+
+export function extractSessionToken(request) {
+  const auth = request.headers.get('authorization') || '';
+  if (/^bearer\s+/i.test(auth)) {
+    const token = auth.replace(/^bearer\s+/i, '').trim();
+    if (token && !token.startsWith('cf_') && token !== 'sillynotreal-secret') return token;
+  }
+  const cookie = request.headers.get('cookie') || '';
+  const match = cookie.match(/(?:^|;\s*)agentsam_session=([^;]+)/);
+  return match ? decodeURIComponent(match[1]).trim() : '';
+}
+
+export function rejectUntrustedOwnerHints(request, url, body = {}) {
+  const headerUser = (request.headers.get('x-user-id') || '').trim();
+  for (const key of UNTRUSTED) {
+    if (url.searchParams.get(key)) {
+      const err = new Error('untrusted_owner_hint');
+      err.code = 'untrusted_owner_hint';
+      throw err;
+    }
+    if (body && body[key]) {
+      const err = new Error('untrusted_owner_hint');
+      err.code = 'untrusted_owner_hint';
+      throw err;
+    }
+  }
+  // X-User-Id is vault v1 compatibility only and is never connector authority.
+  return { ignoredXUserId: Boolean(headerUser) };
+}
+
+export async function resolveAuthenticatedOwner(request, env, url, body) {
+  rejectUntrustedOwnerHints(request, url, body);
+  const sessionToken = extractSessionToken(request);
+  if (!sessionToken) {
+    const err = new Error('unauthenticated');
+    err.code = 'unauthenticated';
+    throw err;
+  }
+  if (env?.sessions instanceof Map) {
+    const owner = env.sessions.get(sessionToken);
+    if (!owner) {
+      const err = new Error('unauthenticated');
+      err.code = 'unauthenticated';
+      throw err;
+    }
+    return String(owner);
+  }
+  if (env?.DB?.prepare) {
+    const tables = [
+      ['agentsam_sessions', 'session_token', 'user_id'],
+      ['sessions', 'id', 'user_id'],
+      ['identity_sessions', 'session_token', 'user_id'],
+    ];
+    for (const [table, tokenCol, userCol] of tables) {
+      try {
+        const row = await env.DB.prepare(
+          `SELECT ${userCol} AS user_id FROM ${table} WHERE ${tokenCol} = ? LIMIT 1`,
+        )
+          .bind(sessionToken)
+          .first();
+        if (row?.user_id) return String(row.user_id);
+      } catch {
+        // table may not exist yet
+      }
+    }
+  }
+  const err = new Error('unauthenticated');
+  err.code = 'unauthenticated';
+  throw err;
+}