@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

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

@@ -52,16 +52,7 @@ describe('cloudflare connector', () => {
   });
 
   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 oauthState = new Map();
     const response = await handleCloudflareConnectionRequest(
       new Request('https://agentsam.example/api/connections/cloudflare/start?return_to=https://untrusted.example/after', {
         headers: {
@@ -70,19 +61,17 @@ describe('cloudflare connector', () => {
         },
       }),
       {
-        DB,
+        oauthState,
         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);
+    const body = await response.json();
+    assert.equal(body.ok, true);
+    assert.equal(oauthState.size, 1);
+    const stored = [...oauthState.values()][0];
+    assert.equal(stored.returnTo, '');
   });
 
   it('redirects browser starts to Cloudflare authorization', async () => {
@@ -108,9 +97,15 @@ describe('cloudflare connector', () => {
   });
 
   it('consumes callback state and stores only encrypted OAuth tokens', async () => {
-    const now = Math.floor(Date.now() / 1000);
     const calls = [];
-    const statements = [];
+    const oauthState = new Map([
+      ['state_123', {
+        ownerId: 'user_123',
+        verifier: 'verifier',
+        returnTo: '',
+        createdAt: Math.floor(Date.now() / 1000),
+      }],
+    ]);
     const DB = {
       prepare(sql) {
         const statement = {
@@ -121,9 +116,6 @@ describe('cloudflare connector', () => {
             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() {
@@ -131,7 +123,6 @@ describe('cloudflare connector', () => {
             return { success: true };
           },
         };
-        statements.push(statement);
         return statement;
       },
       async batch(batchStatements) {
@@ -146,7 +137,7 @@ describe('cloudflare connector', () => {
       return new Response(JSON.stringify({
         access_token: 'access-plaintext',
         refresh_token: 'refresh-plaintext',
-        account_id: 'account_123',
+        account_id: 'abc123abc123abc123abc123abc123ab',
         scope: 'd1.read workers-scripts.write',
         expires_in: 3600,
       }), { status: 200, headers: { 'content-type': 'application/json' } });
@@ -157,6 +148,7 @@ describe('cloudflare connector', () => {
         new Request('https://agentsam.example/api/connections/cloudflare/callback?code=code_123&state=state_123'),
         {
           DB,
+          oauthState,
           CLOUDFLARE_OAUTH_CLIENT_ID: 'real-client-id',
           CLOUDFLARE_OAUTH_CLIENT_SECRET: 'obsolete-secret-must-not-be-sent',
           VAULT_MASTER_KEY: '01234567890123456789012345678901',
@@ -167,11 +159,15 @@ describe('cloudflare connector', () => {
         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');
+      assert.equal(oauthState.has('state_123'), false);
+      const insert = calls.find((call) => call.sql.includes('INSERT INTO user_oauth_tokens'));
+      assert.ok(insert, 'expected user_oauth_tokens insert (SSOT)');
+      // With vault: plaintext args are null; ciphertext is not plaintext tokens.
+      assert.equal(insert.args[3], null); // access_token plaintext
+      assert.equal(insert.args[4], null); // refresh_token plaintext
+      assert.notEqual(insert.args[5], 'access-plaintext'); // access_token_encrypted
+      assert.notEqual(insert.args[6], 'refresh-plaintext'); // refresh_token_encrypted
+      assert.equal(calls.some((call) => call.sql.includes('agentsam_cloudflare_connections')), false);
     } finally {
       globalThis.fetch = originalFetch;
     }

package/packages/connectors/cloudflare/tests/oauth-persist.test.mjs

@@ -0,0 +1,125 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  resolveCloudflareAccountId,
+  unionScopes,
+  upsertCloudflareUserOauthToken,
+} from '../src/oauth-persist.js';
+
+describe('oauth-persist spine', () => {
+  it('unions scopes without duplicates', () => {
+    assert.deepEqual(
+      unionScopes(['d1.read', 'offline_access'], ['d1.read', 'workers-scripts.write']).sort(),
+      ['d1.read', 'offline_access', 'workers-scripts.write'].sort(),
+    );
+  });
+
+  it('requires explicit selection when Cloudflare exposes multiple accounts', async () => {
+    const result = await resolveCloudflareAccountId('token', {
+      fetchImpl: async () => ({
+        ok: true,
+        async json() {
+          return {
+            result: [
+              { id: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', name: 'A' },
+              { id: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', name: 'B' },
+            ],
+          };
+        },
+      }),
+    });
+    assert.equal(result?.error, 'cloudflare_account_selection_required');
+    assert.equal(result?.accounts?.length, 2);
+  });
+
+  it('rejects provider labels and synthetic values as account identifiers', async () => {
+    const result = await upsertCloudflareUserOauthToken(
+      { DB: { prepare() { throw new Error('should not query'); } } },
+      { userId: 'au_1', accessToken: 'token', accountId: 'Cloudflare' },
+    );
+    assert.equal(result.ok, false);
+    assert.equal(result.error, 'cloudflare_account_identifier_required');
+  });
+
+  it('upserts with client_id provenance and scope union (no connected_via_app)', async () => {
+    const rows = new Map();
+    const sqlSeen = [];
+    const env = {
+      VAULT_MASTER_KEY: 'test-vault-material',
+      DB: {
+        prepare(sql) {
+          sqlSeen.push(String(sql));
+          return {
+            bind(...args) {
+              return {
+                async first() {
+                  if (String(sql).includes('SELECT')) {
+                    return rows.get(`${args[0]}|${args[2]}`) || null;
+                  }
+                  return null;
+                },
+                async run() {
+                  if (String(sql).includes('INSERT')) {
+                    // Encrypted-only path: plaintext [3]/[4] are null; ciphertext [5]/[6].
+                    const key = `${args[0]}|${args[2]}`;
+                    const prior = rows.get(key);
+                    rows.set(key, {
+                      scopes: args[7],
+                      scope: args[7],
+                      metadata_json: args[11],
+                      access_token: args[3],
+                      refresh_token: args[4],
+                      created_at: prior?.created_at || args[12],
+                    });
+                  }
+                  return { success: true };
+                },
+              };
+            },
+          };
+        },
+      },
+    };
+
+    const r1 = await upsertCloudflareUserOauthToken(env, {
+      userId: 'au_1',
+      accessToken: 'tok1',
+      scopes: 'd1.read offline_access',
+      accountId: 'abc123abc123abc123abc123abc123ab',
+      clientId: 'c0704bd7a7aab7216b362603e1985499',
+      capabilitySet: ['cloudflare.d1'],
+    });
+    assert.equal(r1.ok, true);
+    assert.equal(r1.status, 'connected');
+    assert.equal(r1.provenance.connected_via_client_id, 'c0704bd7a7aab7216b362603e1985499');
+    assert.equal(r1.provenance.connected_via_app, undefined);
+
+    rows.set('au_1|abc123abc123abc123abc123abc123ab', {
+      scopes: 'd1.read offline_access',
+      scope: 'd1.read offline_access',
+      metadata_json: JSON.stringify({
+        cloudflare_account_id: 'abc123abc123abc123abc123abc123ab',
+        connected_via_client_id: 'c0704bd7a7aab7216b362603e1985499',
+        connected_via_app: 'should_be_stripped',
+      }),
+      access_token: 'tok1',
+      refresh_token: null,
+      created_at: 1,
+    });
+
+    const r2 = await upsertCloudflareUserOauthToken(env, {
+      userId: 'au_1',
+      accessToken: 'tok2',
+      scopes: 'workers-scripts.write',
+      accountId: 'abc123abc123abc123abc123abc123ab',
+      clientId: 'c0704bd7a7aab7216b362603e1985499',
+      capabilitySet: ['cloudflare.workers'],
+    });
+    assert.equal(r2.ok, true);
+    assert.ok(r2.scopes.includes('d1.read'));
+    assert.ok(r2.scopes.includes('workers-scripts.write'));
+    const upsertSql = sqlSeen.find((sql) => sql.includes('ON CONFLICT(user_id, provider, account_identifier)'));
+    assert.match(upsertSql || '', /last_refresh_error_code = NULL/);
+    assert.match(upsertSql || '', /refresh_failure_count = 0/);
+  });
+});

package/packages/heuristic-theme/README.md

@@ -1,9 +1,9 @@
-# @inneranimalmedia/heuristic-theme
+# @inneranimalmedia/theme-heuristic
 
 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";
+import { createStorefrontShellTheme } from "@inneranimalmedia/theme-heuristic";
 
 const theme = createStorefrontShellTheme();
 ```

package/packages/heuristic-theme/package.json

@@ -1,6 +1,6 @@
 {
-  "name": "@inneranimalmedia/heuristic-theme",
-  "version": "0.1.0",
+  "name": "@inneranimalmedia/theme-heuristic",
+  "version": "2.6.7",
   "description": "Stock AgentSam CMS storefront shell theme contract (heuristic-theme).",
   "type": "module",
   "main": "./src/index.js",
@@ -21,5 +21,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/heuristic-theme"
+  }
 }

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

@@ -14,11 +14,11 @@ export function createHeuristicThemeProductRow({ accountId, repositoryId = null
     status: "wired",
     repository_id: repositoryId,
     canonical_path: "packages/heuristic-theme",
-    package_name: "@inneranimalmedia/heuristic-theme",
+    package_name: "@inneranimalmedia/theme-heuristic",
     metadata: {
       origin: "gallery_mount",
       normalization_state: "wired",
-      package: "@inneranimalmedia/heuristic-theme",
+      package: "@inneranimalmedia/theme-heuristic",
       preview_kind: "live",
       capabilities: ["theme.storefront.shell"],
       app_manifest: null,

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

@@ -32,7 +32,7 @@ export function createStorefrontShellTheme() {
       { type: "footer", label: "Footer" },
     ],
     metadata: {
-      package: "@inneranimalmedia/heuristic-theme",
+      package: "@inneranimalmedia/theme-heuristic",
       capability: "theme.storefront.shell",
       deterministic: true,
       demoSite: "demo",

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

@@ -10,7 +10,7 @@ test("createStorefrontShellTheme returns stable stock contract", () => {
   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.equal(theme.metadata.package, "@inneranimalmedia/theme-heuristic");
   assert.deepEqual(createStorefrontShellTheme(), theme);
 });
 

package/packages/identity/.agentsam/features/oauth-login-portal/agentsam.feature.json

@@ -5,7 +5,7 @@
   "kind": "integration",
   "status": "extracted",
   "package": {
-    "name": "@inneranimalmedia/agentsam-sdk-identity",
+    "name": "@inneranimalmedia/agentsam-identity",
     "version": "2.6.3",
     "directory": "packages/identity"
   },

package/packages/identity/.agentsam/features/oauth-login-portal/providers.json

@@ -5,7 +5,9 @@
   "providers": [
     {
       "id": "inneranimalmedia",
-      "aliases": ["iam"],
+      "aliases": [
+        "iam"
+      ],
       "oauth_provider_key": "iam",
       "kind": "oidc",
       "status": "ready",
@@ -35,7 +37,27 @@
       "required_configuration": [
         "GOOGLE_CLIENT_ID",
         "GOOGLE_CLIENT_SECRET"
-      ]
+      ],
+      "notes": "Web browser OAuth (confidential client). For Desktop/CLI PKCE use google_desktop."
+    },
+    {
+      "id": "google_desktop",
+      "aliases": [
+        "google-desktop"
+      ],
+      "kind": "oauth",
+      "status": "ready",
+      "implementation": "src/providers/google",
+      "capabilities": [
+        "identity.oauth.authorize",
+        "identity.oauth.desktop_exchange",
+        "identity.profile.resolve"
+      ],
+      "required_configuration": [
+        "GOOGLE_DESKTOP_CLIENT_ID"
+      ],
+      "optional_configuration": [],
+      "notes": "Desktop/public PKCE client (Console type Desktop app). Uses system browser + loopback redirect and no embedded client secret."
     },
     {
       "id": "github",
@@ -61,7 +83,7 @@
         "identity.oauth.authorize",
         "identity.profile.resolve"
       ],
-      "notes": "Contract + authorize URL only — exchange not implemented."
+      "notes": "Contract + authorize URL only \u2014 exchange not implemented."
     },
     {
       "id": "email",
@@ -90,7 +112,25 @@
       "optional_configuration": [
         "CLOUDFLARE_OAUTH_CLIENT_SECRET"
       ],
-      "notes": "Registered in identityProviders. Client secret optional for PKCE-only clients."
+      "notes": "Cloudflare sign-in (same Worker secrets as the Cloudflare resource connector). Client secret optional for PKCE-only clients (Token Authentication Method = None)."
+    },
+    {
+      "id": "chatgpt",
+      "aliases": [
+        "openai",
+        "chatgpt-hosted"
+      ],
+      "kind": "hosted_headers",
+      "status": "ready",
+      "registered": true,
+      "implementation": "src/providers/chatgpt",
+      "capabilities": [
+        "identity.hosted.headers",
+        "identity.profile.resolve",
+        "cms.auth_host"
+      ],
+      "required_configuration": [],
+      "notes": "ChatGPT / OpenAI Apps SDK hosted identity. Reads oai-authenticated-* request headers and normalizes to NormalizedExternalIdentity (provider=chatgpt). Not classic OAuth client credentials — use createChatGptCmsAuthHost for /cms protection."
     }
   ]
 }

package/packages/identity/.agentsam/features/oauth-login-portal/resources.json

@@ -4,13 +4,19 @@
   "engine": "d1",
   "migration_sources": [
     "src/migrations/0001_identity_core.sql",
-    "src/migrations/0002_company.sql"
+    "src/migrations/0002_company.sql",
+    "src/migrations/0003_accounts_ssot.sql"
   ],
-  "notes": "Migration files remain the schema authority. This JSON is an index/contract only.",
+  "notes": "Migration files remain the schema authority. accounts is the account SSOT; account_identities is IdP linkage only.",
   "tables": [
+    {
+      "name": "accounts",
+      "purpose": "account SSOT (row of record)",
+      "source": "src/migrations/0001_identity_core.sql"
+    },
     {
       "name": "auth_users",
-      "purpose": "canonical user identity",
+      "purpose": "login principal (1:1 with accounts.id in portable scaffold)",
       "source": "src/migrations/0001_identity_core.sql"
     },
     {
@@ -21,7 +27,7 @@
     },
     {
       "name": "account_identities",
-      "purpose": "external identity/provider mapping",
+      "purpose": "IdP linkage only (provider + subject → accounts.id) — not the account SSOT",
       "owner_column": "account_id",
       "source": "src/migrations/0001_identity_core.sql"
     },

package/packages/identity/.agentsam/features/oauth-login-portal/routes.json

@@ -39,12 +39,32 @@
       "access": "public",
       "provider": "google"
     },
+    {
+      "path": "/api/oauth/google/callback",
+      "kind": "api",
+      "access": "public",
+      "provider": "google"
+    },
+    {
+      "path": "/api/oauth/google/desktop-exchange",
+      "method": "POST",
+      "kind": "api",
+      "access": "public",
+      "provider": "google_desktop",
+      "notes": "CLI/desktop PKCE broker — loopback redirect_uri only"
+    },
     {
       "path": "/api/oauth/github/start",
       "kind": "api",
       "access": "public",
       "provider": "github"
     },
+    {
+      "path": "/api/oauth/github/callback",
+      "kind": "api",
+      "access": "public",
+      "provider": "github"
+    },
     {
       "path": "/api/oauth/inneranimalmedia/start",
       "kind": "api",

package/packages/identity/README.md

@@ -20,14 +20,14 @@ identity.login(request);   // alpha: throws until Identity Service adapter is wi
 identity.session.fromRequest(request);  // alpha: throws until adapter is wired
 ```
 
-**Alpha scope:** contracts, D1 adapter, Worker router, `agentsam identity init` scaffold (`app/frontend` + `backend` + migrations), and `agentsam identity preview`. Default OAuth: minted `IAM_CLIENT_ID` + `IAM_CLIENT_SECRET`. Developer Google/GitHub BYOK still supported when those env pairs are set.
+**Alpha scope:** contracts, D1 adapter, Worker router, `agentsam identity init` scaffold (`app/frontend` + `backend` + migrations), and `agentsam identity preview`. Default OAuth: minted `IAM_CLIENT_ID` + `IAM_CLIENT_SECRET`. BYOK options: Google web, Google Desktop (`GOOGLE_DESKTOP_CLIENT_ID`), GitHub, Cloudflare (`CLOUDFLARE_OAUTH_CLIENT_*`). **Stock CMS sign-in picker:** Cloudflare · Google · Inner Animal Media · ChatGPT (`hosted_headers` via Apps SDK). **Account SSOT:** `accounts` (not `account_identities` — that table is IdP linkage only).
 
 ## Layout
 
 ```
 src/
   core/           identity · sessions · accounts · recovery
-  providers/      google · github · gcp · email
+  providers/      google · github · gcp · email · iam · cloudflare · chatgpt
   oauth/          authorize/callback (extract from IAM — next sprint)
   adapters/       inneranimalmedia · cloudflare-d1
   contracts/

package/packages/identity/backend/README.md

@@ -11,7 +11,7 @@ Worker-side identity: providers, OAuth finalize, sessions, adapters.
 | `oauth/callback.js` | `src/core/auth/oauth-finalize.js` → `finalizeInboundOAuth` | **bulletproof path** |
 | `oauth/authorize.js` | `src/api/auth.js` OAuth start handlers | PKCE + state — next sprint |
 | `core/session-service.js` | `src/core/auth.js` | cookie, `createLoginSession`, revoke |
-| `core/account-linking.js` | `ensureIdentityPlaneBeforeSession`, `ensureAppUser` | account_identities |
+| `core/account-linking.js` | `ensureIdentityPlaneBeforeSession`, `ensureAppUser` | **accounts** SSOT + account_identities (IdP link) |
 | `adapters/inneranimalmedia/*` | D1 writes in auth side-effects | tenant/workspace stays adapter-only |
 
 ## Rule

package/packages/identity/migrations/D1_SCHEMA_MAPPING.md

@@ -1,31 +1,35 @@
-# Identity schema mapping — portable ↔ Cloudflare D1
+# Identity schema mapping — portable ↔ Cloudflare D1 (IAM compat)
 
 Portable SQLite (`packages/identity/migrations/sqlite/`) is the product schema.
-The D1 adapter maps existing hosted table names without requiring a big-bang rename.
+The IAM-compat adapter maps existing hosted table names without requiring a big-bang rename.
 
-| Portable (SQLite) | Hosted D1 (current) | Notes |
+| Portable (SQLite / portable D1) | Hosted D1 (IAM compat) | Notes |
 |---|---|---|
-| `identity_users` | `auth_users` | Same columns |
-| `identity_external_accounts` | `account_identities` | `user_id` ↔ `account_id` |
-| `identity_sessions` | `auth_sessions` | Same columns |
-| `identity_auth_events` | `auth_event_log` | Same columns |
-| `identity_oauth_transactions` | `identity_oauth_states` → migrate to `identity_oauth_transactions` | Requires `app_id NOT NULL`; no silent pre-app_id fallback |
-| `identity_provider_connections` | (new / connector tables) | `credential_ref` → vault/KMS; never store raw tokens in D1 rows |
+| `identity_users` / account plane | **`accounts`** + `auth_users` | **Account SSOT** — row of record |
+| `identity_external_accounts` | `account_identities` | IdP linkage only |
+| `identity_sessions` (+ `type`) | `auth_sessions` (+ `type`) | browser / desktop |
+| `identity_auth_events` | `auth_event_log` | Same semantics |
+| `identity_oauth_transactions` (+ native cols) | `identity_oauth_states` | Requires `app_id NOT NULL`; native cols optional |
+| `identity_native_handoffs` | `identity_native_handoffs` | Single-use desktop pickup |
+| `identity_companies` | `company` | Branding / host resolution |
+| `identity_provider_connections` | `identity_provider_connections` (or connector tables) | `credential_ref` only — never raw secrets |
 | `identity_app_registry` | cache of `agentsam.app.json` | Disk manifests remain SSOT |
 | `identity_route_registry` | projection cache | Disk manifests remain SSOT |
 | `identity_oauth_clients` … | optional `identity.oauth-server` pack | Only if product is an AS |
 
+Password recovery is **not** a portable core table. It uses `createPasswordResetService` with an injected `{get,put,delete}` store. Optional `identity.recovery` pack may exist later.
+
 ## Schema version
 
-Both adapters read `identity_schema_meta.schema_version` (SQLite) or
-`PRAGMA`/meta row. Missing `app_id` on OAuth transactions is an
-`IdentitySchemaError('IDENTITY_SCHEMA_MIGRATION_REQUIRED')`, not a soft
-downgrade.
+Portable adapters read `identity_schema_meta.schema_version`. Lane 1 requires version **2** (after `005_identity_company_native.sql`). Missing `app_id` on OAuth transactions is an `IdentitySchemaError`, not a soft downgrade.
 
 ## Packs
 
 | Pack | Apply when |
 |---|---|
-| `identity.core` | Always (local + hosted) |
+| `identity.core` | Always (local + hosted portable) |
 | `identity.oauth-client` | Signing into external IdPs |
 | `identity.oauth-server` | Product issues its own codes/tokens |
+
+Family manifest: `packages/identity/schema/agentsam.identity/manifest.json`
+Generic contract: `protocol/database/agentsam.schema-pack.v1.schema.json`

package/packages/identity/migrations/apply-portable.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** Package-owned portable SQL SSOT (resolves inside installed npm package). */
+export const PORTABLE_IDENTITY_MIGRATIONS_DIR = path.resolve(HERE, 'sqlite');
+
+/** @deprecated Prefer PORTABLE_IDENTITY_MIGRATIONS_DIR */
+export const SQLITE_MIGRATIONS_DIR = PORTABLE_IDENTITY_MIGRATIONS_DIR;
+
+export const IDENTITY_SCHEMA_PACK_MANIFEST_PATH = path.resolve(
+  HERE,
+  '../schema/agentsam.identity/manifest.json',
+);
+
+/**
+ * Resolve the agentsam.identity pack-family manifest from the installed package.
+ * @returns {{ manifest: object, manifestPath: string, sqlDir: string }}
+ */
+export function resolveIdentitySchemaPack() {
+  const manifestPath = IDENTITY_SCHEMA_PACK_MANIFEST_PATH;
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  return {
+    manifest,
+    manifestPath,
+    sqlDir: PORTABLE_IDENTITY_MIGRATIONS_DIR,
+  };
+}
+
+function listPortableMigrationFiles(opts = {}) {
+  const files = [
+    '001_identity_core.sql',
+    '002_identity_oauth_client.sql',
+    '005_identity_company_native.sql',
+  ];
+  if (opts.includeOAuthServer) {
+    files.push('003_identity_oauth_server.sql');
+    files.push('004_identity_oauth_consent_catalog.sql');
+  }
+  return files;
+}
+
+function isIgnorableMigrationError(err) {
+  const msg = String(err?.message || err || '').toLowerCase();
+  return (
+    msg.includes('duplicate column')
+    || msg.includes('already exists')
+    || msg.includes('duplicate column name')
+  );
+}
+
+async function runSql(db, sql) {
+  if (typeof db.exec === 'function') {
+    try {
+      db.exec(sql);
+      return;
+    } catch (err) {
+      // Multi-statement exec may fail mid-file on duplicate ALTER; fall through to statements.
+      if (!isIgnorableMigrationError(err) && !/alter table/i.test(sql)) throw err;
+    }
+  }
+  const stripped = sql.replace(/\/\*[\s\S]*?\*\//g, '');
+  const statements = stripped
+    .split(';')
+    .map((s) => s.replace(/--[^\n]*/g, '').trim())
+    .filter(Boolean);
+  for (const statement of statements) {
+    try {
+      if (typeof db.exec === 'function' && !db.prepare) {
+        db.exec(statement);
+      } else {
+        await db.prepare(statement).run();
+      }
+    } catch (err) {
+      if (isIgnorableMigrationError(err)) continue;
+      throw err;
+    }
+  }
+}
+
+/**
+ * Apply portable agentsam.identity SQL pack to a SQLite or D1-shaped target.
+ * Same SQL sources for both; executor differs by driver API.
+ *
+ * @param {{ prepare?: Function, exec?: Function }} target
+ * @param {{ includeOAuthServer?: boolean }} [opts]
+ */
+export async function applyPortableIdentityMigrations(target, opts = {}) {
+  if (!target || (typeof target.exec !== 'function' && typeof target.prepare !== 'function')) {
+    throw new Error('applyPortableIdentityMigrations_requires_db_target');
+  }
+  const files = listPortableMigrationFiles(opts);
+  for (const file of files) {
+    const sqlPath = path.join(PORTABLE_IDENTITY_MIGRATIONS_DIR, file);
+    const sql = fs.readFileSync(sqlPath, 'utf8');
+    await runSql(target, sql);
+  }
+}
+
+/**
+ * Stable compatibility alias — same portable pack, same sources.
+ * @param {{ prepare?: Function, exec?: Function }} db
+ * @param {{ includeOAuthServer?: boolean }} [opts]
+ */
+export async function applySqliteIdentityMigrations(db, opts = {}) {
+  return applyPortableIdentityMigrations(db, opts);
+}