@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

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

@@ -9,7 +9,7 @@ import {
   assertConnectionOwner,
 } from './index.js';
 import { resolveAuthenticatedOwner } from './owner.js';
-import { sealToken, vaultConfigured } from './vault.js';
+import { decryptSecret, sealToken, vaultConfigured } from './vault.js';
 
 function json(data, status = 200) {
   return new Response(JSON.stringify(data), {
@@ -22,6 +22,35 @@ function redirect(location) {
   return new Response(null, { status: 302, headers: { location } });
 }
 
+function settingsRedirect(url, result, error = '', returnTo = '') {
+  const destination = returnTo ? new URL(returnTo) : new URL('/settings/integrations', url.origin);
+  destination.searchParams.set('connection', 'cloudflare');
+  destination.searchParams.set('result', result);
+  if (error) destination.searchParams.set('error', error);
+  return redirect(destination.toString());
+}
+
+function resolveReturnTo(url) {
+  const raw = url.searchParams.get('return_to') || '';
+  if (!raw) return '';
+  try {
+    const destination = new URL(raw, url.origin);
+    return destination.origin === url.origin ? destination.toString() : '';
+  } catch {
+    return '';
+  }
+}
+
+async function deleteOAuthState(env, state) {
+  if (env.DB) {
+    await env.DB.prepare(
+      `DELETE FROM agentsam_cloudflare_oauth_state WHERE state = ?`,
+    ).bind(state).run();
+  } else if (env.oauthState instanceof Map) {
+    env.oauthState.delete(state);
+  }
+}
+
 export function isCloudflareConnectionPath(pathname) {
   return pathname === '/api/connections/cloudflare'
     || pathname === '/api/connections/cloudflare/start'
@@ -47,10 +76,58 @@ async function ensureTables(env) {
     state TEXT PRIMARY KEY,
     owner_id TEXT NOT NULL,
     code_verifier TEXT NOT NULL,
-    created_at INTEGER
+    created_at INTEGER,
+    return_to TEXT
+  )`).run();
+  await env.DB.prepare(`CREATE TABLE IF NOT EXISTS integration_resources (
+    id TEXT PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    connection_id TEXT NOT NULL,
+    provider TEXT NOT NULL,
+    resource_type TEXT NOT NULL,
+    provider_resource_id TEXT,
+    name TEXT,
+    url TEXT,
+    metadata_json TEXT DEFAULT '{}',
+    synced_at TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
   )`).run();
 }
 
+async function seedKnownCloudflareResources(env, ownerId, connectionId, cloudflareAccountId) {
+  if (!env?.DB?.prepare || !cloudflareAccountId) return;
+  let configuredScopes = {};
+  try { configuredScopes = JSON.parse(env.AGENTSAM_RESOURCE_SCOPE_JSON || '{}'); } catch { configuredScopes = {}; }
+  const resources = [
+    { key: 'agentsam-sdk', type: 'worker', id: 'agentsam-sdk', name: 'AgentSam SDK / Local Studio' },
+    { key: 'agentsam-cad-creator', type: 'worker', id: 'agentsam-cad-creator', name: 'AgentSam CAD Creator' },
+    { key: 'agentsam-client-cms-editor', type: 'worker', id: 'agentsam-client-cms-editor', name: 'AgentSam Client CMS Editor' },
+    { key: 'fuelnfreetime', type: 'worker', id: 'fuelnfreetime', name: 'Fuel & Free Time', metadata: {
+      zone_id: '816a5d2284103e4481987ceeb16c2ca9',
+      d1_database_id: '9fd6ff92-e407-4b51-8b01-3c93f3845bb2',
+      r2_bucket: 'fuelnfreetime',
+      ...(configuredScopes.fuelnfreetime || {}),
+    } },
+  ];
+  const statements = resources.map((resource) => env.DB.prepare(`
+    INSERT OR REPLACE INTO integration_resources (
+      id, tenant_id, connection_id, provider, resource_type, provider_resource_id,
+      name, metadata_json, synced_at, updated_at
+    ) VALUES (?, ?, ?, 'cloudflare', ?, ?, ?, ?, datetime('now'), datetime('now'))
+  `).bind(
+    `ires_cf_${cloudflareAccountId}_${resource.key}`,
+    ownerId,
+    connectionId,
+    resource.type,
+    resource.id,
+    resource.name,
+    JSON.stringify({ cloudflare_account_id: cloudflareAccountId, ...(resource.metadata || {}) }),
+  ));
+  if (typeof env.DB.batch === 'function') await env.DB.batch(statements);
+  else for (const statement of statements) await statement.run();
+}
+
 export async function handleCloudflareConnectionRequest(request, env) {
   const url = new URL(request.url);
   const client = resolveCloudflareOAuthClient(env);
@@ -98,7 +175,9 @@ export async function handleCloudflareConnectionRequest(request, env) {
     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`,
+         FROM agentsam_cloudflare_connections
+         WHERE owner_id = ? AND status = 'connected'
+         ORDER BY updated_at DESC LIMIT 1`,
       ).bind(ownerId).first();
       if (row) {
         connection = {
@@ -122,12 +201,17 @@ export async function handleCloudflareConnectionRequest(request, env) {
     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(/=+$/, '');
+    const returnTo = resolveReturnTo(url);
     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();
+        `DELETE FROM agentsam_cloudflare_oauth_state WHERE created_at < unixepoch() - 600`,
+      ).run();
+      await env.DB.prepare(
+        `INSERT INTO agentsam_cloudflare_oauth_state (state, owner_id, code_verifier, created_at, return_to)
+         VALUES (?, ?, ?, unixepoch(), ?)`,
+      ).bind(state, ownerId, verifier, returnTo || null).run();
     } else if (env.oauthState instanceof Map) {
-      env.oauthState.set(state, { ownerId, verifier });
+      env.oauthState.set(state, { ownerId, verifier, returnTo });
     }
     const redirectUri = `${url.origin}${CLOUDFLARE_CALLBACK_PATH}`;
     const authorize = buildAuthorizeUrl({
@@ -136,47 +220,77 @@ export async function handleCloudflareConnectionRequest(request, env) {
       state,
       codeChallenge: challenge,
     });
+    // Browser navigation → 302 to Cloudflare. XHR/fetch (Integrations UI) → JSON.
+    const accept = String(request.headers.get('accept') || '');
+    const mode = String(request.headers.get('sec-fetch-mode') || '');
+    const wantsJson = accept.includes('application/json')
+      || mode === 'cors'
+      || request.headers.get('x-agentsam-oauth') === 'json';
+    if (!wantsJson) {
+      return Response.redirect(authorize, 302);
+    }
     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') || '';
+    const providerError = url.searchParams.get('error') || '';
     let stored = null;
     if (env.DB) {
       stored = await env.DB.prepare(
-        `SELECT owner_id, code_verifier FROM agentsam_cloudflare_oauth_state WHERE state = ?`,
+        `SELECT owner_id, code_verifier, created_at, return_to
+         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) stored = { owner_id: stored.ownerId, code_verifier: stored.verifier, return_to: stored.returnTo || '' };
     }
     if (!stored) {
+      // A callback without a one-time PKCE state is forged or expired. Keep
+      // this as an explicit 403 instead of redirecting into a misleading UI.
       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);
+      return settingsRedirect(url, 'error', 'cloudflare_connection_forbidden', stored.return_to || '');
+    }
+    const createdAt = Number(stored.created_at || 0);
+    const now = Math.floor(Date.now() / 1000);
+    if (createdAt && now - createdAt > 10 * 60) {
+      await deleteOAuthState(env, state);
+      return settingsRedirect(url, 'error', 'oauth_state_expired', stored.return_to || '');
     }
+    await deleteOAuthState(env, state);
+    if (providerError) {
+      return settingsRedirect(url, 'error', providerError, stored.return_to || '');
+    }
+    if (!code) {
+      return settingsRedirect(url, 'error', 'authorization_code_missing', stored.return_to || '');
+    }
+    // This is Cloudflare's public PKCE client (Token Authentication Method:
+    // None). Do not add client_secret, even if an obsolete Worker binding is
+    // present; a mixed-auth exchange is rejected by Cloudflare.
+    const tokenParams = {
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: `${url.origin}${CLOUDFLARE_CALLBACK_PATH}`,
+      client_id: String(env.CLOUDFLARE_OAUTH_CLIENT_ID),
+      code_verifier: stored.code_verifier,
+    };
     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,
-      }),
+      body: new URLSearchParams(tokenParams),
     });
     if (!tokenRes.ok) {
-      return json({ ok: false, error: 'token_exchange_failed' }, 502);
+      console.error('cloudflare_token_exchange_failed', tokenRes.status);
+      return settingsRedirect(url, 'error', 'token_exchange_failed', stored.return_to || '');
     }
     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);
+      return settingsRedirect(url, 'error', 'vault_unavailable', stored.return_to || '');
     }
     const aad = `cloudflare-connection:${ownerId}`;
     let accessEnc = null;
@@ -185,10 +299,16 @@ export async function handleCloudflareConnectionRequest(request, env) {
       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);
+      return settingsRedirect(url, 'error', err.code || 'vault_unavailable', stored.return_to || '');
     }
     if (env.DB) {
-      await env.DB.prepare(
+      const removePrevious = env.DB.prepare(
+        `UPDATE agentsam_cloudflare_connections
+         SET status = 'superseded', access_token_encrypted = NULL,
+             refresh_token_encrypted = NULL, updated_at = unixepoch()
+         WHERE owner_id = ? AND status = 'connected'`,
+      ).bind(ownerId);
+      const insertConnection = 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
@@ -201,22 +321,52 @@ export async function handleCloudflareConnectionRequest(request, env) {
         accessEnc,
         refreshEnc,
         tokens.expires_in ? Math.floor(Date.now() / 1000) + Number(tokens.expires_in) : null,
-      ).run();
+      );
+      if (typeof env.DB.batch === 'function') {
+        await env.DB.batch([removePrevious, insertConnection]);
+      } else {
+        await removePrevious.run();
+        await insertConnection.run();
+      }
+      await seedKnownCloudflareResources(env, ownerId, connectionId, tokens.account_id || null);
     }
-    return redirect(`/agentsam?connection=cloudflare`);
+    return settingsRedirect(url, 'connected', '', stored.return_to || '');
   }
 
   if (url.pathname === '/api/connections/cloudflare/disconnect' && request.method === 'POST') {
+    let providerRevoked = false;
     if (env.DB) {
       const row = await env.DB.prepare(
-        `SELECT connection_id, owner_id FROM agentsam_cloudflare_connections WHERE owner_id = ?`,
+        `SELECT connection_id, owner_id, access_token_encrypted
+         FROM agentsam_cloudflare_connections
+         WHERE owner_id = ? AND status = 'connected'
+         ORDER BY updated_at DESC LIMIT 1`,
       ).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();
+        if (row.access_token_encrypted) {
+          try {
+            const token = await decryptSecret(env, row.access_token_encrypted, `cloudflare-connection:${ownerId}`);
+            const revokeParams = new URLSearchParams({ token, client_id: String(env.CLOUDFLARE_OAUTH_CLIENT_ID) });
+            const revokeResponse = await fetch(CLOUDFLARE_OAUTH_REVOKE_URL, {
+              method: 'POST',
+              headers: { 'content-type': 'application/x-www-form-urlencoded' },
+              body: revokeParams,
+            });
+            providerRevoked = revokeResponse.ok;
+          } catch (error) {
+            console.error('cloudflare_token_revoke_failed', String(error?.message || error));
+          }
+        }
+        await env.DB.prepare(`
+          UPDATE agentsam_cloudflare_connections
+          SET status = 'revoked', access_token_encrypted = NULL,
+              refresh_token_encrypted = NULL, expires_at = unixepoch(), updated_at = unixepoch()
+          WHERE connection_id = ? AND owner_id = ?
+        `).bind(row.connection_id, ownerId).run();
       }
     }
-    return json({ ok: true, status: 'not_configured' });
+    return json({ ok: true, status: 'not_configured', provider_revoked: providerRevoked });
   }
 
   return json({ ok: false, error: 'not_found' }, 404);

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

@@ -5,6 +5,7 @@ import {
   cloudflareConnectionSafeStatus,
   resolveCloudflareOAuthClient,
 } from '../src/index.js';
+import { handleCloudflareConnectionRequest } from '../src/routes.js';
 
 describe('cloudflare connector', () => {
   it('reports not_configured when credentials are absent', () => {
@@ -17,7 +18,6 @@ describe('cloudflare connector', () => {
   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);
@@ -32,7 +32,7 @@ describe('cloudflare connector', () => {
     });
     const blob = JSON.stringify(status);
     assert.equal(blob.includes('sillynotreal-secret'), false);
-    assert.equal(status.secret, 'configured');
+    assert.equal(status.token_auth_method, 'none_pkce');
     assert.equal(status.configured, false);
   });
 
@@ -41,4 +41,139 @@ describe('cloudflare connector', () => {
     assert.throws(() => assertConnectionOwner(record, 'connor'), /cloudflare_connection_forbidden/);
     assert.equal(assertConnectionOwner(record, 'sam').connectionId, 'c1');
   });
+
+  it('supports a production PKCE client with no client secret', () => {
+    const client = resolveCloudflareOAuthClient({
+      CLOUDFLARE_OAUTH_CLIENT_ID: 'real-client-id',
+    });
+    assert.equal(client.productionReady, true);
+    assert.equal(client.clientIdConfigured, true);
+    assert.equal(client.tokenAuthMethod, 'none_pkce');
+  });
+
+  it('keeps connector return paths same-origin', async () => {
+    const calls = [];
+    const DB = {
+      prepare(sql) {
+        return {
+          args: [],
+          bind(...args) { this.args = args; return this; },
+          async run() { calls.push({ sql, args: this.args }); return { success: true }; },
+        };
+      },
+    };
+    const response = await handleCloudflareConnectionRequest(
+      new Request('https://agentsam.example/api/connections/cloudflare/start?return_to=https://untrusted.example/after', {
+        headers: {
+          authorization: 'Bearer fixture',
+          accept: 'application/json',
+        },
+      }),
+      {
+        DB,
+        fixtureSessions: new Map([['fixture', 'user_123']]),
+        CLOUDFLARE_OAUTH_CLIENT_ID: 'real-client-id',
+      },
+    );
+    assert.equal(response.status, 200);
+    assert.equal(
+      calls.some((call) => call.sql.includes('DELETE FROM agentsam_cloudflare_oauth_state WHERE created_at < unixepoch() - 600')),
+      true,
+    );
+    const stateInsert = calls.find((call) => call.sql.includes('INSERT INTO agentsam_cloudflare_oauth_state'));
+    assert.ok(stateInsert);
+    assert.equal(stateInsert.args.at(-1), null);
+  });
+
+  it('redirects browser starts to Cloudflare authorization', async () => {
+    const oauthState = new Map();
+    const response = await handleCloudflareConnectionRequest(
+      new Request('https://agentsam.example/api/connections/cloudflare/start', {
+        headers: { authorization: 'Bearer fixture' },
+      }),
+      {
+        fixtureSessions: new Map([['fixture', 'user_123']]),
+        oauthState,
+        CLOUDFLARE_OAUTH_CLIENT_ID: 'real-client-id',
+      },
+    );
+
+    assert.equal(response.status, 302);
+    const location = new URL(response.headers.get('location'));
+    assert.equal(location.origin, 'https://dash.cloudflare.com');
+    assert.equal(location.pathname, '/oauth2/auth');
+    assert.equal(location.searchParams.get('client_id'), 'real-client-id');
+    assert.equal(location.searchParams.get('redirect_uri'), 'https://agentsam.example/api/connections/cloudflare/callback');
+    assert.equal(oauthState.size, 1);
+  });
+
+  it('consumes callback state and stores only encrypted OAuth tokens', async () => {
+    const now = Math.floor(Date.now() / 1000);
+    const calls = [];
+    const statements = [];
+    const DB = {
+      prepare(sql) {
+        const statement = {
+          sql,
+          args: [],
+          bind(...args) {
+            this.args = args;
+            return this;
+          },
+          async first() {
+            if (sql.includes('agentsam_cloudflare_oauth_state')) {
+              return { owner_id: 'user_123', code_verifier: 'verifier', created_at: now };
+            }
+            return null;
+          },
+          async run() {
+            calls.push({ sql, args: this.args });
+            return { success: true };
+          },
+        };
+        statements.push(statement);
+        return statement;
+      },
+      async batch(batchStatements) {
+        for (const statement of batchStatements) await statement.run();
+        return batchStatements.map(() => ({ success: true }));
+      },
+    };
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (_input, init) => {
+      const body = new URLSearchParams(init.body);
+      assert.equal(body.get('client_secret'), null);
+      return new Response(JSON.stringify({
+        access_token: 'access-plaintext',
+        refresh_token: 'refresh-plaintext',
+        account_id: 'account_123',
+        scope: 'd1.read workers-scripts.write',
+        expires_in: 3600,
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    };
+
+    try {
+      const response = await handleCloudflareConnectionRequest(
+        new Request('https://agentsam.example/api/connections/cloudflare/callback?code=code_123&state=state_123'),
+        {
+          DB,
+          CLOUDFLARE_OAUTH_CLIENT_ID: 'real-client-id',
+          CLOUDFLARE_OAUTH_CLIENT_SECRET: 'obsolete-secret-must-not-be-sent',
+          VAULT_MASTER_KEY: '01234567890123456789012345678901',
+        },
+      );
+      assert.equal(response.status, 302);
+      assert.equal(
+        response.headers.get('location'),
+        'https://agentsam.example/settings/integrations?connection=cloudflare&result=connected',
+      );
+      assert.equal(calls.some((call) => call.sql.includes('DELETE FROM agentsam_cloudflare_oauth_state')), true);
+      const insert = calls.find((call) => call.sql.includes('INSERT INTO agentsam_cloudflare_connections'));
+      assert.ok(insert);
+      assert.notEqual(insert.args[4], 'access-plaintext');
+      assert.notEqual(insert.args[5], 'refresh-plaintext');
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
 });

package/packages/heuristic-theme/README.md

@@ -0,0 +1,11 @@
+# @inneranimalmedia/heuristic-theme
+
+Stock AgentSam CMS storefront shell theme. Exports a deterministic theme contract consumed by CMS presets and `theme.storefront.shell`.
+
+```js
+import { createStorefrontShellTheme } from "@inneranimalmedia/heuristic-theme";
+
+const theme = createStorefrontShellTheme();
+```
+
+Historical gallery demos live in `apps/theme-gallery-preview` — this package owns the reusable stock contract, not donor site archives.

package/packages/heuristic-theme/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@inneranimalmedia/heuristic-theme",
+  "version": "0.1.0",
+  "description": "Stock AgentSam CMS storefront shell theme contract (heuristic-theme).",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./theme": "./src/theme.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22 <25"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/packages/heuristic-theme/src/index.js

@@ -0,0 +1,2 @@
+export { createStorefrontShellTheme } from "./theme.js";
+export { createHeuristicThemeProductRow } from "./registry.js";

package/packages/heuristic-theme/src/registry.js

@@ -0,0 +1,36 @@
+import { createStorefrontShellTheme } from "./theme.js";
+
+/**
+ * Durable agentsam_products payload for the stock heuristic theme.
+ * Caller resolves repository_id against live code_repositories before UPSERT.
+ */
+export function createHeuristicThemeProductRow({ accountId, repositoryId = null } = {}) {
+  const theme = createStorefrontShellTheme();
+  return {
+    account_id: accountId || null,
+    slug: theme.slug,
+    name: theme.displayName,
+    kind: "theme",
+    status: "wired",
+    repository_id: repositoryId,
+    canonical_path: "packages/heuristic-theme",
+    package_name: "@inneranimalmedia/heuristic-theme",
+    metadata: {
+      origin: "gallery_mount",
+      normalization_state: "wired",
+      package: "@inneranimalmedia/heuristic-theme",
+      preview_kind: "live",
+      capabilities: ["theme.storefront.shell"],
+      app_manifest: null,
+      help_root: "docs/",
+    },
+    capability: "theme.storefront.shell",
+    relationships: [
+      {
+        relationship_type: "packaged_as",
+        target_type: "sdk-package",
+        target_slug: "heuristic-theme",
+      },
+    ],
+  };
+}

package/packages/heuristic-theme/src/theme.js

@@ -0,0 +1,41 @@
+/** @typedef {{ id: string, slug: string, displayName: string, version: string, kind: string, surfaces: string[], slots: Record<string, string[]>, tokens: Record<string, string>, sections: Array<{ type: string, label: string }>, metadata: Record<string, unknown> }} StorefrontShellTheme */
+
+/**
+ * Deterministic stock CMS storefront shell theme contract.
+ * @returns {StorefrontShellTheme}
+ */
+export function createStorefrontShellTheme() {
+  return {
+    id: "theme.storefront.shell",
+    slug: "heuristic-theme",
+    displayName: "Heuristic Theme",
+    version: "0.1.0",
+    kind: "storefront-shell",
+    surfaces: ["cms.editor", "cms.preview", "theme.gallery"],
+    slots: {
+      shell: ["header", "main", "footer"],
+      page: ["hero", "products", "content", "footer"],
+      navigation: ["brand", "links", "cta"],
+    },
+    tokens: {
+      "--color-bg": "#F9F7F2",
+      "--color-ink": "#101014",
+      "--color-accent": "#1e6a6f",
+      "--color-muted": "#8a8a95",
+      "--font-display": "\"Iowan Old Style\", \"Palatino Linotype\", Palatino, serif",
+      "--font-body": "ui-sans-serif, system-ui, -apple-system, sans-serif",
+      "--radius-control": "8px",
+    },
+    sections: [
+      { type: "hero", label: "Editorial hero" },
+      { type: "products", label: "Product grid" },
+      { type: "footer", label: "Footer" },
+    ],
+    metadata: {
+      package: "@inneranimalmedia/heuristic-theme",
+      capability: "theme.storefront.shell",
+      deterministic: true,
+      demoSite: "demo",
+    },
+  };
+}

package/packages/heuristic-theme/test/theme.test.mjs

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createStorefrontShellTheme } from "../src/index.js";
+
+test("createStorefrontShellTheme returns stable stock contract", () => {
+  const theme = createStorefrontShellTheme();
+  assert.equal(theme.id, "theme.storefront.shell");
+  assert.equal(theme.slug, "heuristic-theme");
+  assert.equal(theme.kind, "storefront-shell");
+  assert.ok(theme.surfaces.includes("cms.editor"));
+  assert.ok(theme.slots.shell.includes("header"));
+  assert.equal(theme.tokens["--color-accent"], "#1e6a6f");
+  assert.equal(theme.metadata.package, "@inneranimalmedia/heuristic-theme");
+  assert.deepEqual(createStorefrontShellTheme(), theme);
+});
+
+import { createHeuristicThemeProductRow } from "../src/index.js";
+
+test("createHeuristicThemeProductRow emits D1-ready product identity", () => {
+  const row = createHeuristicThemeProductRow({ accountId: "acct_demo", repositoryId: "repo_sdk" });
+  assert.equal(row.slug, "heuristic-theme");
+  assert.equal(row.kind, "theme");
+  assert.equal(row.status, "wired");
+  assert.equal(row.metadata.capabilities[0], "theme.storefront.shell");
+  assert.equal(row.canonical_path, "packages/heuristic-theme");
+});