@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/packages/identity/src/adapters/sqlite/index.js

@@ -0,0 +1,322 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  IDENTITY_STORE_SCHEMA_VERSION,
+  IdentitySchemaError,
+} from '../../contracts/identity-store.js';
+import { newAccountIdentityId, newAuthEventId, newAuthUserId, newSessionId, nowUnix } from '../cloudflare-d1/ids.js';
+import { SESSION_POLICY } from '../../core/constants.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const SQLITE_MIGRATIONS_DIR = path.resolve(HERE, '../../../migrations/sqlite');
+
+/**
+ * Apply identity.core + identity.oauth-client (+ optional oauth-server) to a
+ * D1-shaped db ({ prepare().bind().run|first|all }).
+ *
+ * @param {{ prepare: Function }} db
+ * @param {{ includeOAuthServer?: boolean }} [opts]
+ */
+export async function applySqliteIdentityMigrations(db, opts = {}) {
+  const files = [
+    '001_identity_core.sql',
+    '002_identity_oauth_client.sql',
+  ];
+  if (opts.includeOAuthServer) {
+    files.push('003_identity_oauth_server.sql');
+    files.push('004_identity_oauth_consent_catalog.sql');
+  }
+
+  for (const file of files) {
+    const sql = fs.readFileSync(path.join(SQLITE_MIGRATIONS_DIR, file), 'utf8');
+    if (typeof db.exec === 'function') {
+      db.exec(sql);
+      continue;
+    }
+    // D1-shaped: run statement-by-statement (no multi-exec).
+    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) {
+      await db.prepare(statement).run();
+    }
+  }
+}
+
+async function hashValue(value) {
+  const v = String(value || '').trim();
+  if (!v) return null;
+  const bytes = new TextEncoder().encode(v);
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+async function requireSchema(db) {
+  let row;
+  try {
+    row = await db.prepare(
+      `SELECT value FROM identity_schema_meta WHERE key = 'schema_version' LIMIT 1`,
+    ).bind().first();
+  } catch (err) {
+    throw new IdentitySchemaError(
+      'IDENTITY_SCHEMA_MIGRATION_REQUIRED',
+      'identity.core migrations not applied — run applySqliteIdentityMigrations()',
+      { cause: String(err?.message || err) },
+    );
+  }
+  const version = Number(row?.value || 0);
+  if (version < IDENTITY_STORE_SCHEMA_VERSION) {
+    throw new IdentitySchemaError(
+      'IDENTITY_SCHEMA_MIGRATION_REQUIRED',
+      `identity schema_version=${version}, required=${IDENTITY_STORE_SCHEMA_VERSION}`,
+      { version, required: IDENTITY_STORE_SCHEMA_VERSION },
+    );
+  }
+}
+
+/**
+ * Local SQLite IdentityStore — full offline identity, no Cloudflare/IAM.
+ * @param {{ prepare: Function }} db D1-shaped binding (see createLocalSqliteDatabase)
+ * @param {{ sessionTtlSeconds?: number, skipSchemaCheck?: boolean }} [options]
+ */
+export function createSqliteIdentityAdapter(db, options = {}) {
+  if (!db?.prepare) throw new Error('sqlite_identity_adapter_requires_db');
+  const sessionTtlSeconds = options.sessionTtlSeconds ?? SESSION_POLICY.browser.ttlSeconds;
+  let schemaReady = Boolean(options.skipSchemaCheck);
+
+  async function ensure() {
+    if (schemaReady) return;
+    await requireSchema(db);
+    schemaReady = true;
+  }
+
+  return Object.freeze({
+    schemaVersion: IDENTITY_STORE_SCHEMA_VERSION,
+    sessionTtlSeconds,
+    backend: 'sqlite',
+
+    async findUserByEmail(email) {
+      await ensure();
+      const row = await db.prepare(
+        `SELECT id, email, display_name, password_hash, salt, status, created_at, updated_at
+         FROM identity_users WHERE email = ? COLLATE NOCASE LIMIT 1`,
+      ).bind(String(email || '').trim().toLowerCase()).first();
+      return row || null;
+    },
+
+    async findUserById(userId) {
+      await ensure();
+      const row = await db.prepare(
+        `SELECT id, email, display_name, password_hash, salt, status, created_at, updated_at
+         FROM identity_users WHERE id = ? LIMIT 1`,
+      ).bind(userId).first();
+      return row || null;
+    },
+
+    async createUser({ email, passwordHash, salt, displayName }) {
+      await ensure();
+      const id = newAuthUserId();
+      const ts = nowUnix();
+      const normalizedEmail = String(email || '').trim().toLowerCase();
+      await db.prepare(
+        `INSERT INTO identity_users (id, email, display_name, password_hash, salt, status, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, 'active', ?, ?)`,
+      ).bind(id, normalizedEmail, displayName || null, passwordHash || null, salt || null, ts, ts).run();
+      return this.findUserById(id);
+    },
+
+    async updateUserPassword(userId, passwordHash, salt) {
+      await ensure();
+      const ts = nowUnix();
+      await db.prepare(
+        `UPDATE identity_users SET password_hash = ?, salt = ?, updated_at = ? WHERE id = ?`,
+      ).bind(passwordHash, salt, ts, userId).run();
+    },
+
+    async findUserByProvider(provider, providerSubject) {
+      await ensure();
+      const row = await db.prepare(
+        `SELECT u.id, u.email, u.display_name, u.password_hash, u.salt, u.status, u.created_at, u.updated_at
+         FROM identity_external_accounts ea
+         JOIN identity_users u ON u.id = ea.user_id
+         WHERE ea.provider = ? AND ea.provider_subject = ?
+         LIMIT 1`,
+      ).bind(provider, providerSubject).first();
+      return row || null;
+    },
+
+    async upsertProviderIdentity({ accountId, provider, providerSubject, email }) {
+      await ensure();
+      const existing = await db.prepare(
+        `SELECT id FROM identity_external_accounts WHERE provider = ? AND provider_subject = ? LIMIT 1`,
+      ).bind(provider, providerSubject).first();
+      const ts = nowUnix();
+      if (existing?.id) {
+        await db.prepare(
+          `UPDATE identity_external_accounts SET user_id = ?, email = ?, updated_at = ? WHERE id = ?`,
+        ).bind(accountId, email || null, ts, existing.id).run();
+        return existing.id;
+      }
+      const id = newAccountIdentityId();
+      await db.prepare(
+        `INSERT INTO identity_external_accounts (id, user_id, provider, provider_subject, email, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      ).bind(id, accountId, provider, providerSubject, email || null, ts, ts).run();
+      return id;
+    },
+
+    async createSession({ userId, email, provider, providerSubject, displayName }) {
+      await ensure();
+      const id = newSessionId();
+      const ts = nowUnix();
+      const expiresAt = ts + sessionTtlSeconds;
+      await db.prepare(
+        `INSERT INTO identity_sessions
+         (id, user_id, email, provider, provider_subject, display_name, expires_at, created_at, last_active_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      ).bind(
+        id, userId, email || null, provider || 'email', providerSubject || null,
+        displayName || null, expiresAt, ts, ts,
+      ).run();
+      return {
+        id, user_id: userId, email, provider: provider || 'email',
+        provider_subject: providerSubject || null, display_name: displayName || null,
+        expires_at: expiresAt, created_at: ts,
+      };
+    },
+
+    async getSession(sessionId) {
+      await ensure();
+      const row = await db.prepare(
+        `SELECT id, user_id, email, provider, provider_subject, display_name, expires_at, revoked_at, created_at, last_active_at
+         FROM identity_sessions WHERE id = ? LIMIT 1`,
+      ).bind(sessionId).first();
+      if (!row || row.revoked_at || row.expires_at <= nowUnix()) return null;
+      return row;
+    },
+
+    async revokeSession(sessionId, reason = 'logout') {
+      await ensure();
+      const ts = nowUnix();
+      await db.prepare(
+        `UPDATE identity_sessions SET revoked_at = ?, last_active_at = ? WHERE id = ? AND revoked_at IS NULL`,
+      ).bind(ts, ts, sessionId).run();
+      return { ok: true, reason };
+    },
+
+    async createOAuthTransaction({ state, provider, codeVerifier, returnTo, appId, ttlSeconds = 600 }) {
+      await ensure();
+      if (!appId) {
+        throw new IdentitySchemaError(
+          'OAUTH_TRANSACTION_APP_ID_REQUIRED',
+          'OAuth transactions must include app_id — refusing to create orphan auth state',
+        );
+      }
+      const ts = nowUnix();
+      await db.prepare(
+        `INSERT INTO identity_oauth_transactions
+         (state, provider, code_verifier, return_to, app_id, expires_at, created_at, consumed_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, NULL)`,
+      ).bind(state, provider, codeVerifier, returnTo || null, appId, ts + ttlSeconds, ts).run();
+    },
+
+    /** @deprecated Use createOAuthTransaction */
+    async saveOAuthState(input) {
+      return this.createOAuthTransaction({
+        ...input,
+        returnTo: input.redirectTo ?? input.returnTo,
+        appId: input.appId,
+      });
+    },
+
+    async consumeOAuthTransaction(state) {
+      await ensure();
+      const row = await db.prepare(
+        `SELECT state, provider, code_verifier, return_to, app_id, expires_at, created_at, consumed_at
+         FROM identity_oauth_transactions WHERE state = ? LIMIT 1`,
+      ).bind(state).first();
+      if (!row) return null;
+      const ts = nowUnix();
+      await db.prepare(
+        `UPDATE identity_oauth_transactions SET consumed_at = ? WHERE state = ?`,
+      ).bind(ts, state).run();
+      await db.prepare(`DELETE FROM identity_oauth_transactions WHERE state = ?`).bind(state).run();
+      if (row.consumed_at) return null;
+      if (row.expires_at <= ts) return null;
+      if (!row.app_id) {
+        throw new IdentitySchemaError(
+          'IDENTITY_SCHEMA_MIGRATION_REQUIRED',
+          'OAuth transaction missing app_id — refuse silent pre-app_id semantics',
+        );
+      }
+      return {
+        state: row.state,
+        provider: row.provider,
+        code_verifier: row.code_verifier,
+        redirect_to: row.return_to,
+        return_to: row.return_to,
+        app_id: row.app_id,
+        expires_at: row.expires_at,
+        created_at: row.created_at,
+        consumed_at: ts,
+      };
+    },
+
+    /** @deprecated Use consumeOAuthTransaction */
+    async consumeOAuthState(state) {
+      return this.consumeOAuthTransaction(state);
+    },
+
+    async logAuthEvent({
+      userId, accountId, eventType, status = 'ok', provider,
+      session, capabilities, activity, client, metadata, request,
+    }) {
+      try {
+        await ensure();
+        const ip = request?.headers?.get?.('cf-connecting-ip') || request?.headers?.get?.('x-forwarded-for') || '';
+        const ua = request?.headers?.get?.('user-agent') || '';
+        const [ipHash, uaHash] = await Promise.all([hashValue(ip), hashValue(ua)]);
+        const envelope = {
+          ...(metadata && typeof metadata === 'object' ? metadata : {}),
+          ...(accountId ? { accountId } : {}),
+          ...(session ? { session } : {}),
+          ...(capabilities ? { capabilities } : {}),
+          ...(activity ? { activity } : {}),
+          ...(client ? { client } : {}),
+        };
+        await db.prepare(
+          `INSERT INTO identity_auth_events
+           (id, user_id, event_type, status, provider, metadata_json, ip_hash, user_agent_hash, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        ).bind(
+          newAuthEventId(), userId || null, eventType, status, provider || null,
+          JSON.stringify(envelope), ipHash, uaHash, nowUnix(),
+        ).run();
+      } catch {
+        /* never break auth on audit failure */
+      }
+    },
+
+    async countAuthActivity(userId) {
+      await ensure();
+      if (!userId) return { loginCount: 0, activeSessionCount: 0, lastLoginAt: null };
+      const logins = await db.prepare(
+        `SELECT COUNT(*) AS c, MAX(created_at) AS last_at
+         FROM identity_auth_events
+         WHERE user_id = ? AND event_type = 'login' AND status = 'ok'`,
+      ).bind(userId).first();
+      const sessions = await db.prepare(
+        `SELECT COUNT(*) AS c FROM identity_sessions
+         WHERE user_id = ? AND revoked_at IS NULL AND expires_at > ?`,
+      ).bind(userId, nowUnix()).first();
+      return {
+        loginCount: Number(logins?.c || 0),
+        activeSessionCount: Number(sessions?.c || 0),
+        lastLoginAt: logins?.last_at != null ? Number(logins.last_at) : null,
+      };
+    },
+  });
+}

package/packages/identity/src/app/verify-app.js

@@ -0,0 +1,95 @@
+/**
+ * Verify agentsam.app.v1 auth + route + shell contracts.
+ * Fail package verification — never ship unresolved shells/routes.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { IDENTITY_ROUTE_IDS, REQUIRED_AUTH_ROUTE_IDS } from '../contracts/route-ids.js';
+import { projectionFromAppManifest, createRouteRegistry } from '../contracts/route-projection.js';
+import { IdentityRoutingError } from '../contracts/identity-store.js';
+
+/**
+ * @param {object} manifest
+ * @param {{ appRoot?: string, requireShellFiles?: boolean }} [opts]
+ * @returns {{ ok: true, projection: object } | { ok: false, errors: string[] }}
+ */
+export function verifyAppAuthContract(manifest, opts = {}) {
+  const errors = [];
+  const appId = String(manifest?.id || '').trim();
+  if (!appId) errors.push('manifest.id required');
+  if (manifest?.schema !== 'agentsam.app.v1') {
+    errors.push('manifest.schema must be agentsam.app.v1');
+  }
+
+  if (!manifest?.auth) {
+    errors.push('auth-capable apps must declare auth { entry, oauth? }');
+  } else {
+    if (!manifest.auth.entry?.authenticated && !manifest.routes?.entry) {
+      errors.push('auth.entry.authenticated or routes.entry required');
+    }
+    if (!manifest.auth.entry?.login && !manifest.routes?.paths?.[IDENTITY_ROUTE_IDS.LOGIN]
+      && !manifest.routes?.[IDENTITY_ROUTE_IDS.LOGIN]) {
+      errors.push('auth.entry.login (→ identity.login) required');
+    }
+    if (!manifest.auth.entry?.failure && !manifest.auth.entry?.login) {
+      errors.push('auth.entry.failure or auth.entry.login required for recovery');
+    }
+  }
+
+  let projection = null;
+  try {
+    projection = projectionFromAppManifest(manifest);
+    const registry = createRouteRegistry([projection]);
+    registry.assertAuthCapable(appId);
+  } catch (err) {
+    errors.push(err?.message || String(err));
+  }
+
+  if (opts.requireShellFiles !== false && opts.appRoot && projection) {
+    for (const [, entry] of projection.routes) {
+      if (!entry.shell) continue;
+      const shellPath = path.resolve(opts.appRoot, entry.shell);
+      if (!fs.existsSync(shellPath)) {
+        errors.push(`declared shell missing: ${entry.shell}`);
+      }
+    }
+    const runtimeShell = manifest.runtime?.shell;
+    const assetRoot = manifest.runtime?.assetRoot || 'dist';
+    if (runtimeShell) {
+      const shellPath = path.resolve(opts.appRoot, assetRoot, runtimeShell);
+      // Only enforce when dist exists (post-build). Pre-build: skip if assetRoot absent.
+      if (fs.existsSync(path.resolve(opts.appRoot, assetRoot)) && !fs.existsSync(shellPath)) {
+        errors.push(`runtime.shell missing after build: ${assetRoot}/${runtimeShell}`);
+      }
+    }
+  }
+
+  for (const mount of manifest.routes?.mounts || []) {
+    if (!mount.path?.startsWith('/')) {
+      errors.push(`invalid mount path: ${mount.path}`);
+    }
+  }
+
+  if (errors.length) return { ok: false, errors };
+  return { ok: true, projection, requiredRouteIds: [...REQUIRED_AUTH_ROUTE_IDS] };
+}
+
+/**
+ * @param {string} appRoot directory containing agentsam.app.json
+ */
+export function verifyAppPackage(appRoot, opts = {}) {
+  const manifestPath = path.join(appRoot, 'agentsam.app.json');
+  if (!fs.existsSync(manifestPath)) {
+    return { ok: false, errors: [`missing ${manifestPath}`] };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (err) {
+    return { ok: false, errors: [`invalid JSON: ${err.message}`] };
+  }
+  return verifyAppAuthContract(manifest, { ...opts, appRoot });
+}
+
+export { IdentityRoutingError };

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

@@ -4,12 +4,13 @@
  * Browser login sessions and reusable API credentials are intentionally
  * separate: login sessions are opaque, machine-local session state while
  * AGENTSAM_API_KEY is an explicit delegated account credential.
+ *
+ * Namespaces (do not collapse):
+ *   PLATFORM issuer  → IAM_OAUTH_ISSUER (account API)
+ *   APP host         → agentsam.app.json hosts[] (e.g. local-studio)
+ * Never treat Local Studio host origin as an alias of IAM_OAUTH_ISSUER.
  */
 
-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',
@@ -17,8 +18,23 @@ export const AGENTSAM_AUTH_ENV = Object.freeze({
   iamClientSecret: 'IAM_CLIENT_SECRET',
   apiKey: 'AGENTSAM_API_KEY',
   bridgeKey: 'AGENTSAM_BRIDGE_KEY',
+  googleClientId: 'GOOGLE_CLIENT_ID',
+  googleClientSecret: 'GOOGLE_CLIENT_SECRET',
+  googleDesktopClientId: 'GOOGLE_DESKTOP_CLIENT_ID',
+  googleDesktopClientSecret: 'GOOGLE_DESKTOP_CLIENT_SECRET',
+  githubClientId: 'GITHUB_CLIENT_ID',
+  githubClientSecret: 'GITHUB_CLIENT_SECRET',
+  cloudflareOauthClientId: 'CLOUDFLARE_OAUTH_CLIENT_ID',
+  cloudflareOauthClientSecret: 'CLOUDFLARE_OAUTH_CLIENT_SECRET',
 });
 
+/**
+ * Hosted AgentSam platform compatibility issuer — not an APP host and never a
+ * portable Local Studio default. Portable apps use packages/identity locally
+ * unless an installation explicitly selects a remote IAM adapter.
+ */
+export const PLATFORM_ACCOUNT_ISSUER = 'https://inneranimalmedia.com';
+
 export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
   version: 2,
   authority: 'agentsam-sdk',
@@ -27,6 +43,7 @@ export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
     origin: AGENTSAM_AUTH_ENV.iamOrigin,
     clientId: AGENTSAM_AUTH_ENV.iamClientId,
     clientSecret: AGENTSAM_AUTH_ENV.iamClientSecret,
+    defaultIssuer: PLATFORM_ACCOUNT_ISSUER,
   }),
   apiKey: Object.freeze({
     env: AGENTSAM_AUTH_ENV.apiKey,
@@ -55,11 +72,14 @@ function normalizeOrigin(value) {
   return clean(value).replace(/\/+$/, '');
 }
 
-/** Resolve canonical IAM issuer. IAM_OAUTH_ISSUER wins; IAM_ORIGIN is compatibility only. */
+/**
+ * Resolve PLATFORM account issuer.
+ * Order: explicit → IAM_OAUTH_ISSUER → IAM_ORIGIN → PLATFORM_ACCOUNT_ISSUER.
+ * Does not read APP host origins.
+ */
 export function resolveIamIssuer(env = {}, explicit = '') {
-  return normalizeOrigin(
-    explicit || env?.IAM_OAUTH_ISSUER || env?.IAM_ORIGIN || DEFAULT_IAM_OAUTH_ISSUER,
-  );
+  return normalizeOrigin(explicit || env?.IAM_OAUTH_ISSUER || env?.IAM_ORIGIN || '')
+    || PLATFORM_ACCOUNT_ISSUER;
 }
 
 /** @deprecated Use resolveIamIssuer. Same resolution order as issuer. */

package/packages/identity/src/contracts/external-identity.js

@@ -1,6 +1,6 @@
 /**
  * Portable external identity shape — storage-agnostic.
- * Adapters map this into application-specific account_identities rows.
+ * Adapters map this into account_identities rows that point at accounts (SSOT).
  */
 
 /** @typedef {import('../provider-contract.js').NormalizedExternalIdentity} NormalizedExternalIdentity */

package/packages/identity/src/contracts/identity-store.js

@@ -0,0 +1,115 @@
+/**
+ * Portable IdentityStore contract.
+ * Adapters (SQLite, D1, Postgres) implement this — the identity service never
+ * imports Cloudflare/D1 APIs directly for product logic.
+ */
+
+/**
+ * @typedef {object} IdentityUser
+ * @property {string} id
+ * @property {string} email
+ * @property {string|null} [display_name]
+ * @property {string|null} [password_hash]
+ * @property {string|null} [salt]
+ * @property {string} [status]
+ * @property {number} created_at
+ * @property {number} updated_at
+ */
+
+/**
+ * @typedef {object} IdentitySession
+ * @property {string} id
+ * @property {string} user_id
+ * @property {string|null} [email]
+ * @property {string|null} [provider]
+ * @property {string|null} [provider_subject]
+ * @property {string|null} [display_name]
+ * @property {number} expires_at
+ * @property {number|null} [revoked_at]
+ * @property {number} created_at
+ * @property {number|null} [last_active_at]
+ */
+
+/**
+ * @typedef {object} OAuthTransaction
+ * @property {string} state
+ * @property {string} provider
+ * @property {string} code_verifier
+ * @property {string|null} [return_to]
+ * @property {string} app_id
+ * @property {number} expires_at
+ * @property {number} created_at
+ * @property {number|null} [consumed_at]
+ */
+
+/**
+ * @typedef {object} AuthEventInput
+ * @property {string} [userId]
+ * @property {string} [accountId]
+ * @property {string} eventType
+ * @property {string} [status]
+ * @property {string} [provider]
+ * @property {object} [session]
+ * @property {object} [capabilities]
+ * @property {object} [activity]
+ * @property {object} [client]
+ * @property {object} [metadata]
+ * @property {Request} [request]
+ */
+
+/**
+ * @typedef {object} IdentityStore
+ * @property {number} schemaVersion
+ * @property {(email: string) => Promise<IdentityUser|null>} findUserByEmail
+ * @property {(userId: string) => Promise<IdentityUser|null>} findUserById
+ * @property {(input: { email: string, passwordHash?: string|null, salt?: string|null, displayName?: string|null }) => Promise<IdentityUser>} createUser
+ * @property {(userId: string, passwordHash: string, salt: string) => Promise<void>} updateUserPassword
+ * @property {(provider: string, providerSubject: string) => Promise<IdentityUser|null>} findUserByProvider
+ * @property {(input: { accountId: string, provider: string, providerSubject: string, email?: string|null }) => Promise<string>} upsertProviderIdentity
+ * @property {(input: { userId: string, email?: string|null, provider?: string, providerSubject?: string|null, displayName?: string|null }) => Promise<IdentitySession>} createSession
+ * @property {(sessionId: string) => Promise<IdentitySession|null>} getSession
+ * @property {(sessionId: string, reason?: string) => Promise<{ ok: true, reason: string }>} revokeSession
+ * @property {(input: { state: string, provider: string, codeVerifier: string, returnTo?: string|null, appId: string, ttlSeconds?: number }) => Promise<void>} createOAuthTransaction
+ * @property {(state: string) => Promise<OAuthTransaction|null>} consumeOAuthTransaction
+ * @property {(input: AuthEventInput) => Promise<void>} logAuthEvent
+ * @property {(userId: string) => Promise<{ loginCount: number, activeSessionCount: number, lastLoginAt: number|null }>} [countAuthActivity]
+ */
+
+export const IDENTITY_STORE_SCHEMA_VERSION = 1;
+
+export const IDENTITY_PACKS = Object.freeze({
+  CORE: 'identity.core',
+  OAUTH_CLIENT: 'identity.oauth-client',
+  OAUTH_SERVER: 'identity.oauth-server',
+});
+
+/**
+ * Structured routing / schema failures — never silently redirect to "/".
+ */
+export class IdentityRoutingError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} [message]
+   * @param {Record<string, unknown>} [details]
+   */
+  constructor(code, message, details = {}) {
+    super(message || code);
+    this.name = 'IdentityRoutingError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class IdentitySchemaError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} [message]
+   * @param {Record<string, unknown>} [details]
+   */
+  constructor(code, message, details = {}) {
+    super(message || code);
+    this.name = 'IdentitySchemaError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/packages/identity/src/contracts/provider.js

@@ -3,6 +3,7 @@
 export const IdentityProviders = Object.freeze([
   'email',
   'google',
+  'google_desktop',
   'github',
   'gcp',
   'inneranimalmedia',

package/packages/identity/src/contracts/route-ids.js

@@ -0,0 +1,30 @@
+/**
+ * Portable identity semantics — IDs only.
+ * Concrete HTTP paths are host/app projections (defineRouteProjection).
+ */
+
+export const IDENTITY_ROUTE_IDS = Object.freeze({
+  LOGIN: 'identity.login',
+  SIGNUP: 'identity.signup',
+  RESET: 'identity.reset',
+  RECOVERY: 'identity.recovery',
+
+  AUTH_LOGIN: 'identity.api.login',
+  AUTH_SIGNUP: 'identity.api.signup',
+  AUTH_LOGOUT: 'identity.api.logout',
+  AUTH_ME: 'identity.api.me',
+
+  OAUTH_START: 'identity.oauth.start',
+  OAUTH_CALLBACK: 'identity.oauth.callback',
+
+  APP_AUTHENTICATED: 'app.authenticated',
+  APP_HOME: 'app.home',
+});
+
+/** Required semantic routes for any auth-capable AgentSam app. */
+export const REQUIRED_AUTH_ROUTE_IDS = Object.freeze([
+  IDENTITY_ROUTE_IDS.LOGIN,
+  IDENTITY_ROUTE_IDS.RECOVERY,
+  IDENTITY_ROUTE_IDS.APP_AUTHENTICATED,
+  IDENTITY_ROUTE_IDS.OAUTH_CALLBACK,
+]);