@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

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;
+}

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

@@ -0,0 +1,223 @@
+import {
+  CLOUDFLARE_CALLBACK_PATH,
+  CLOUDFLARE_OAUTH_TOKEN_URL,
+  CLOUDFLARE_OAUTH_REVOKE_URL,
+  buildAuthorizeUrl,
+  cloudflareConnectionSafeStatus,
+  resolveCloudflareOAuthClient,
+  requestedCloudflareScopes,
+  assertConnectionOwner,
+} from './index.js';
+import { resolveAuthenticatedOwner } from './owner.js';
+import { sealToken, vaultConfigured } from './vault.js';
+
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+  });
+}
+
+function redirect(location) {
+  return new Response(null, { status: 302, headers: { location } });
+}
+
+export function isCloudflareConnectionPath(pathname) {
+  return pathname === '/api/connections/cloudflare'
+    || pathname === '/api/connections/cloudflare/start'
+    || pathname === CLOUDFLARE_CALLBACK_PATH
+    || pathname === '/api/connections/cloudflare/disconnect';
+}
+
+async function ensureTables(env) {
+  if (!env?.DB?.prepare) return;
+  await env.DB.prepare(`CREATE TABLE IF NOT EXISTS agentsam_cloudflare_connections (
+    connection_id TEXT PRIMARY KEY,
+    owner_id TEXT NOT NULL,
+    cloudflare_account_id TEXT,
+    scopes TEXT,
+    status TEXT,
+    access_token_encrypted TEXT,
+    refresh_token_encrypted TEXT,
+    created_at INTEGER,
+    updated_at INTEGER,
+    expires_at INTEGER
+  )`).run();
+  await env.DB.prepare(`CREATE TABLE IF NOT EXISTS agentsam_cloudflare_oauth_state (
+    state TEXT PRIMARY KEY,
+    owner_id TEXT NOT NULL,
+    code_verifier TEXT NOT NULL,
+    created_at INTEGER
+  )`).run();
+}
+
+export async function handleCloudflareConnectionRequest(request, env) {
+  const url = new URL(request.url);
+  const client = resolveCloudflareOAuthClient(env);
+  if (request.method === 'OPTIONS') {
+    return new Response(null, { status: 204 });
+  }
+
+  let body = {};
+  if (request.method === 'POST') {
+    body = await request.json().catch(() => ({}));
+  }
+
+  const isCallback = url.pathname === CLOUDFLARE_CALLBACK_PATH && request.method === 'GET';
+  let ownerId = '';
+  try {
+    ownerId = await resolveAuthenticatedOwner(request, env, url, body);
+  } catch (err) {
+    if (!isCallback || err.code === 'untrusted_owner_hint') {
+      const code = err.code || 'unauthenticated';
+      return json({ ok: false, error: code }, code === 'untrusted_owner_hint' ? 400 : 401);
+    }
+  }
+
+  if (!client.productionReady) {
+    if (url.pathname === '/api/connections/cloudflare' && request.method === 'GET') {
+      return json({
+        ok: true,
+        ...cloudflareConnectionSafeStatus(env, null, ownerId),
+      });
+    }
+    if (url.pathname === '/api/connections/cloudflare/start') {
+      return json({
+        ok: false,
+        error: 'not_configured',
+        message: 'real Cloudflare OAuth client still required',
+        fixture: client.fixture,
+      }, 503);
+    }
+  }
+
+  await ensureTables(env);
+
+  if (url.pathname === '/api/connections/cloudflare' && request.method === 'GET') {
+    let connection = null;
+    if (env.DB) {
+      const row = await env.DB.prepare(
+        `SELECT connection_id, owner_id, cloudflare_account_id, scopes, status, created_at, updated_at, expires_at
+         FROM agentsam_cloudflare_connections WHERE owner_id = ? LIMIT 1`,
+      ).bind(ownerId).first();
+      if (row) {
+        connection = {
+          connectionId: row.connection_id,
+          ownerId: row.owner_id,
+          cloudflareAccountId: row.cloudflare_account_id,
+          scopes: row.scopes ? String(row.scopes).split(' ') : [],
+          status: row.status,
+          createdAt: row.created_at,
+          updatedAt: row.updated_at,
+          expiresAt: row.expires_at,
+        };
+      }
+    }
+    return json({ ok: true, ...cloudflareConnectionSafeStatus(env, connection, ownerId) });
+  }
+
+  if (url.pathname === '/api/connections/cloudflare/start' && request.method === 'GET') {
+    const state = crypto.randomUUID().replace(/-/g, '');
+    const verifierBytes = crypto.getRandomValues(new Uint8Array(32));
+    const verifier = btoa(String.fromCharCode(...verifierBytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    const challenge = btoa(String.fromCharCode(...new Uint8Array(digest))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    if (env.DB) {
+      await env.DB.prepare(
+        `INSERT INTO agentsam_cloudflare_oauth_state (state, owner_id, code_verifier, created_at) VALUES (?, ?, ?, unixepoch())`,
+      ).bind(state, ownerId, verifier).run();
+    } else if (env.oauthState instanceof Map) {
+      env.oauthState.set(state, { ownerId, verifier });
+    }
+    const redirectUri = `${url.origin}${CLOUDFLARE_CALLBACK_PATH}`;
+    const authorize = buildAuthorizeUrl({
+      clientId: String(env.CLOUDFLARE_OAUTH_CLIENT_ID),
+      redirectUri,
+      state,
+      codeChallenge: challenge,
+    });
+    return json({ ok: true, authorize_url: authorize, callback: CLOUDFLARE_CALLBACK_PATH });
+  }
+
+  if (url.pathname === CLOUDFLARE_CALLBACK_PATH && request.method === 'GET') {
+    const code = url.searchParams.get('code') || '';
+    const state = url.searchParams.get('state') || '';
+    let stored = null;
+    if (env.DB) {
+      stored = await env.DB.prepare(
+        `SELECT owner_id, code_verifier FROM agentsam_cloudflare_oauth_state WHERE state = ?`,
+      ).bind(state).first();
+    } else if (env.oauthState instanceof Map) {
+      stored = env.oauthState.get(state);
+      if (stored) stored = { owner_id: stored.ownerId, code_verifier: stored.verifier };
+    }
+    if (!stored) {
+      return json({ ok: false, error: 'cloudflare_connection_forbidden' }, 403);
+    }
+    if (!ownerId) ownerId = stored.owner_id;
+    if (stored.owner_id !== ownerId) {
+      return json({ ok: false, error: 'cloudflare_connection_forbidden' }, 403);
+    }
+    const tokenRes = await fetch(CLOUDFLARE_OAUTH_TOKEN_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: `${url.origin}${CLOUDFLARE_CALLBACK_PATH}`,
+        client_id: String(env.CLOUDFLARE_OAUTH_CLIENT_ID),
+        client_secret: String(env.CLOUDFLARE_OAUTH_CLIENT_SECRET),
+        code_verifier: stored.code_verifier,
+      }),
+    });
+    if (!tokenRes.ok) {
+      return json({ ok: false, error: 'token_exchange_failed' }, 502);
+    }
+    const tokens = await tokenRes.json();
+    const connectionId = `cfconn_${crypto.randomUUID().replace(/-/g, '').slice(0, 16)}`;
+    if (tokens.access_token && !vaultConfigured(env)) {
+      return json({ ok: false, error: 'vault_unavailable' }, 503);
+    }
+    const aad = `cloudflare-connection:${ownerId}`;
+    let accessEnc = null;
+    let refreshEnc = null;
+    try {
+      accessEnc = await sealToken(env, tokens.access_token, aad);
+      refreshEnc = await sealToken(env, tokens.refresh_token, aad);
+    } catch (err) {
+      return json({ ok: false, error: err.code || 'vault_unavailable' }, 503);
+    }
+    if (env.DB) {
+      await env.DB.prepare(
+        `INSERT INTO agentsam_cloudflare_connections (
+           connection_id, owner_id, cloudflare_account_id, scopes, status,
+           access_token_encrypted, refresh_token_encrypted, created_at, updated_at, expires_at
+         ) VALUES (?, ?, ?, ?, 'connected', ?, ?, unixepoch(), unixepoch(), ?)`,
+      ).bind(
+        connectionId,
+        ownerId,
+        tokens.account_id || null,
+        (tokens.scope || requestedCloudflareScopes().join(' ')),
+        accessEnc,
+        refreshEnc,
+        tokens.expires_in ? Math.floor(Date.now() / 1000) + Number(tokens.expires_in) : null,
+      ).run();
+    }
+    return redirect(`/agentsam?connection=cloudflare`);
+  }
+
+  if (url.pathname === '/api/connections/cloudflare/disconnect' && request.method === 'POST') {
+    if (env.DB) {
+      const row = await env.DB.prepare(
+        `SELECT connection_id, owner_id FROM agentsam_cloudflare_connections WHERE owner_id = ?`,
+      ).bind(ownerId).first();
+      if (row) {
+        assertConnectionOwner({ ownerId: row.owner_id, connectionId: row.connection_id }, ownerId);
+        await env.DB.prepare(`DELETE FROM agentsam_cloudflare_connections WHERE owner_id = ?`).bind(ownerId).run();
+      }
+    }
+    return json({ ok: true, status: 'not_configured' });
+  }
+
+  return json({ ok: false, error: 'not_found' }, 404);
+}

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

@@ -0,0 +1,80 @@
+/**
+ * AES-256-GCM token vault matching apps/local-studio/backend/worker encryptSecret.
+ * Connector tokens are server-only. Never return plaintext on status routes.
+ */
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+function b64ToBytes(value) {
+  const bin = atob(value);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i += 1) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function bytesToB64(bytes) {
+  let bin = '';
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin);
+}
+
+export function vaultConfigured(env = {}) {
+  return Boolean(env.VAULT_MASTER_KEY || env.VAULT_KEY);
+}
+
+async function importVaultKey(env) {
+  const raw = env.VAULT_MASTER_KEY || env.VAULT_KEY;
+  if (!raw) throw new Error('VAULT_MASTER_KEY missing');
+  let keyBytes;
+  try {
+    keyBytes = b64ToBytes(raw);
+  } catch {
+    keyBytes = enc.encode(raw);
+  }
+  if (keyBytes.byteLength === 32) {
+    // ok
+  } else if (keyBytes.byteLength > 32) {
+    keyBytes = keyBytes.slice(0, 32);
+  } else {
+    const hash = await crypto.subtle.digest('SHA-256', keyBytes);
+    keyBytes = new Uint8Array(hash);
+  }
+  return crypto.subtle.importKey('raw', keyBytes, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+
+export async function encryptSecret(env, plaintext, aad) {
+  const key = await importVaultKey(env);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const cipher = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv, additionalData: enc.encode(aad || '') },
+    key,
+    enc.encode(plaintext),
+  );
+  const packed = new Uint8Array(iv.byteLength + cipher.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(cipher), iv.byteLength);
+  return bytesToB64(packed);
+}
+
+export async function decryptSecret(env, packedB64, aad) {
+  const key = await importVaultKey(env);
+  const packed = b64ToBytes(packedB64);
+  const iv = packed.slice(0, 12);
+  const data = packed.slice(12);
+  const plain = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv, additionalData: enc.encode(aad || '') },
+    key,
+    data,
+  );
+  return dec.decode(plain);
+}
+
+export async function sealToken(env, plaintext, aad) {
+  if (!plaintext) return null;
+  if (!vaultConfigured(env)) {
+    const err = new Error('vault_unavailable');
+    err.code = 'vault_unavailable';
+    throw err;
+  }
+  return encryptSecret(env, plaintext, aad);
+}

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

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  assertConnectionOwner,
+  cloudflareConnectionSafeStatus,
+  resolveCloudflareOAuthClient,
+} from '../src/index.js';
+
+describe('cloudflare connector', () => {
+  it('reports not_configured when credentials are absent', () => {
+    const client = resolveCloudflareOAuthClient({});
+    assert.equal(client.status, 'not_configured');
+    assert.equal(client.configured, false);
+    assert.equal(client.productionReady, false);
+  });
+
+  it('loads fake fixtures without treating them as production authority', () => {
+    const client = resolveCloudflareOAuthClient({
+      CLOUDFLARE_OAUTH_CLIENT_ID: 'sillynotreal',
+      CLOUDFLARE_OAUTH_CLIENT_SECRET: 'sillynotreal-secret',
+    });
+    assert.equal(client.configured, true);
+    assert.equal(client.fixture, true);
+    assert.equal(client.productionReady, false);
+    assert.equal(client.status, 'fixture');
+  });
+
+  it('never includes secrets in safe status output', () => {
+    const status = cloudflareConnectionSafeStatus({
+      CLOUDFLARE_OAUTH_CLIENT_ID: 'sillynotreal',
+      CLOUDFLARE_OAUTH_CLIENT_SECRET: 'sillynotreal-secret',
+    });
+    const blob = JSON.stringify(status);
+    assert.equal(blob.includes('sillynotreal-secret'), false);
+    assert.equal(status.secret, 'configured');
+    assert.equal(status.configured, false);
+  });
+
+  it('denies cross-account connection access', () => {
+    const record = { ownerId: 'sam', connectionId: 'c1' };
+    assert.throws(() => assertConnectionOwner(record, 'connor'), /cloudflare_connection_forbidden/);
+    assert.equal(assertConnectionOwner(record, 'sam').connectionId, 'c1');
+  });
+});

package/packages/identity/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk-identity",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "private": true,
   "type": "module",
   "description": "Identity module for @inneranimalmedia/agentsam-sdk (workspace — publish via root SDK)",
+  "agentsam": {
+    "system": "identity",
+    "kind": "library",
+    "tags": [
+      "authentication",
+      "account-scoped"
+    ]
+  },
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -18,6 +26,7 @@
     "./contracts/session": "./src/contracts/session.js",
     "./contracts/provider": "./src/contracts/provider.js",
     "./contracts/external-identity": "./src/contracts/external-identity.js",
+    "./contracts/auth-config": "./src/contracts/auth-config.js",
     "./oauth/callback": "./src/oauth/callback.js",
     "./frontend/auth-portal/*": "./src/frontend/auth-portal/*"
   },

package/packages/identity/src/contracts/auth-config.js

@@ -0,0 +1,109 @@
+/**
+ * Canonical AgentSam identity/auth environment contract.
+ *
+ * The SDK owns these public names. Host applications consume this contract and
+ * may provide storage/verification adapters without inventing competing aliases.
+ *
+ * Canonical variables:
+ *   IAM_OAUTH_ISSUER      public authorization-server authority (issuer)
+ *   IAM_CLIENT_ID         OAuth client id
+ *   IAM_CLIENT_SECRET     OAuth client secret
+ *   IAM_ORIGIN            deprecated alias of IAM_OAUTH_ISSUER (migration window)
+ *   AGENTSAM_SDK_KEY      account/delegated sdk_* bearer
+ *   AGENTSAM_BRIDGE_KEY   machine/integration credential
+ *
+ * Migration-only fallbacks:
+ *   IAM_ORIGIN            -> IAM_OAUTH_ISSUER
+ *   AGENTSAM_SDK_TOKEN    -> AGENTSAM_SDK_KEY
+ */
+
+export const DEFAULT_IAM_OAUTH_ISSUER = 'https://inneranimalmedia.com';
+/** @deprecated Use DEFAULT_IAM_OAUTH_ISSUER. */
+export const DEFAULT_IAM_ORIGIN = DEFAULT_IAM_OAUTH_ISSUER;
+
+export const AGENTSAM_AUTH_ENV = Object.freeze({
+  iamIssuer: 'IAM_OAUTH_ISSUER',
+  iamOrigin: 'IAM_ORIGIN',
+  iamClientId: 'IAM_CLIENT_ID',
+  iamClientSecret: 'IAM_CLIENT_SECRET',
+  sdkKey: 'AGENTSAM_SDK_KEY',
+  bridgeKey: 'AGENTSAM_BRIDGE_KEY',
+});
+
+export const AGENTSAM_AUTH_LEGACY_ENV = Object.freeze({
+  iamOrigin: 'IAM_ORIGIN',
+  sdkKey: 'AGENTSAM_SDK_TOKEN',
+});
+
+export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
+  version: 1,
+  authority: 'agentsam-sdk',
+  iam: Object.freeze({
+    issuer: AGENTSAM_AUTH_ENV.iamIssuer,
+    origin: AGENTSAM_AUTH_ENV.iamOrigin,
+    clientId: AGENTSAM_AUTH_ENV.iamClientId,
+    clientSecret: AGENTSAM_AUTH_ENV.iamClientSecret,
+  }),
+  sdk: Object.freeze({
+    env: AGENTSAM_AUTH_ENV.sdkKey,
+    tokenPrefix: 'sdk_',
+    authorizationScheme: 'Bearer',
+    subject: 'account/delegated',
+    durableStore: 'agentsam_sdk_tokens',
+  }),
+  bridge: Object.freeze({
+    env: AGENTSAM_AUTH_ENV.bridgeKey,
+    subject: 'machine/integration',
+    sdkTokenType: 'integration',
+    userAuth: false,
+  }),
+  compatibility: Object.freeze({
+    iamOriginFallback: AGENTSAM_AUTH_LEGACY_ENV.iamOrigin,
+    iamIssuerCanonical: AGENTSAM_AUTH_ENV.iamIssuer,
+    sdkKeyFallback: AGENTSAM_AUTH_LEGACY_ENV.sdkKey,
+  }),
+});
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function normalizeOrigin(value) {
+  return clean(value).replace(/\/+$/, '');
+}
+
+/** Resolve canonical IAM issuer. IAM_OAUTH_ISSUER wins; IAM_ORIGIN is compatibility only. */
+export function resolveIamIssuer(env = {}, explicit = '') {
+  return normalizeOrigin(
+    explicit || env?.IAM_OAUTH_ISSUER || env?.IAM_ORIGIN || DEFAULT_IAM_OAUTH_ISSUER,
+  );
+}
+
+/** @deprecated Use resolveIamIssuer. Same resolution order as issuer. */
+export function resolveIamOrigin(env = {}, explicit = '') {
+  return resolveIamIssuer(env, explicit);
+}
+
+/** Resolve account/delegated SDK bearer; canonical name wins over legacy. */
+export function resolveSdkKey(env = {}, explicit = '') {
+  return clean(explicit || env?.AGENTSAM_SDK_KEY || env?.AGENTSAM_SDK_TOKEN);
+}
+
+/** Resolve machine/integration bridge credential. No user-SDK alias is accepted. */
+export function resolveBridgeKey(env = {}, explicit = '') {
+  return clean(explicit || env?.AGENTSAM_BRIDGE_KEY);
+}
+
+export function isSdkKey(value) {
+  return clean(value).startsWith(AGENTSAM_AUTH_CONTRACT.sdk.tokenPrefix);
+}
+
+/** Build the public bearer header for an SDK key. */
+export function buildSdkAuthorizationHeaders(key, headers = {}) {
+  const resolved = clean(key);
+  if (!isSdkKey(resolved)) throw new Error('AGENTSAM_SDK_KEY_required');
+  return {
+    ...headers,
+    Authorization: `Bearer ${resolved}`,
+  };
+}