@portalshq/capability-identity 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# @portalshq/capability-identity
+
+## 0.2.1
+
+- Implement typed explicit auth-gateway sync with subject matching and clear unsupported-store errors.
+- Refresh existing application profiles without inventing required private identity fields;
+  provision central profiles while preserving existing suspension, issuer, email, and preferences.
+- Bundle the canonical proto in the built package, add configurable proto paths and RPC deadlines,
+  preserve gRPC status errors, and close connections idempotently.
+- Ship atomic, concurrency-serialized central provisioning and non-destructive legacy upgrades.
+  Align preference reads and history conflict keys with the actual central schema.
+- Add real gRPC transport, isolated PostgreSQL, sync/error, migration upgrade/rollback, and
+  public-export tests. Enforce 95% runtime-source coverage thresholds.
+- Document deployment, migrations, the full interface, troubleshooting, and custom-store ownership.
+  No bears-live-app migration is performed.
+
+## 0.2.0
+
+### Minor Changes
+
+- bacf537: Promote identity from stub to usable: verified access-token resolution, PostgreSQL-backed cross-channel interaction history stamped with the transaction clock, and bounded identifiers and reads.
+
+## 0.1.3
+
+### Patch Changes
+
+- 749ad63: Standardize public npm publishing and repository metadata for releases through
+  GitHub Actions trusted publishing. Remove recursive publish lifecycle hooks.
+- Updated dependencies [749ad63]
+  - @portalshq/contracts@0.0.5
+
+## 0.1.2
+
+### Patch Changes
+
+- aff6c1d: Standardize public npm publishing and repository metadata for releases through
+  GitHub Actions trusted publishing. Remove recursive publish lifecycle hooks.
+- Updated dependencies [aff6c1d]
+  - @portalshq/contracts@0.0.4
+
+## 0.1.1
+
+### Patch Changes
+
+- 8884dd5: feat: add ESM build infrastructure to all packages
+- Updated dependencies [8884dd5]
+  - @portalshq/contracts@0.0.3

package/README.md

@@ -1,33 +1,205 @@
 # @portalshq/capability-identity
 
-**Reusable agent module:** [integration guide](../../../docs/package-agents/identity.md)
+Server-side verified identity and cross-channel history. Requires Node.js 22 and PostgreSQL 14+.
 
-Verified application identity and persistent cross-channel interaction history.
+`IdentityProvider` verifies credentials before identity/history operations. Both PostgreSQL
+adapters require an active local account for those operations. Profile sync and soft-key
+validation are explicit trusted-server operations: they do **not** verify access tokens or
+establish authorization. Never expose sync with an arbitrary browser-supplied user ID.
 
-## Exported shape
+## Setup and deployment
 
-- `AudienceIdentity`: `userId` and `displayName`.
-- `ChannelInteraction`: soft `channelId` and `sessionId` cross-database keys.
-- `ChannelHistoryEntry`: a `ChannelInteraction` plus the stored interaction time.
-- `IdentityProvider`: `getIdentity()`, `recordInteraction()`, `getHistory()` — each verifies an access token first.
-- `IdentityStore`: persistence contract, so applications can substitute their own storage.
-- `PostgresIdentityStore`: adapter for Portals `application_users` and `application_user_channel_history`.
-- `QueryRunner`: the minimal `pg.Pool` surface the adapter needs.
+Install this package and `pg` in a server application. Choose one adapter:
 
-## Setup
+| Adapter | Ownership | Profile sync |
+| --- | --- | --- |
+| `ApplicationIdentityStore` | Existing application-owned accounts | Updates existing profiles; refuses missing accounts |
+| `CentralIdentityStore` | Dedicated shared identity database | Creates missing profiles; updates existing profiles |
+| Custom `IdentityStore` | Application-defined persistence | Optional `SyncableIdentityStore` capability |
 
-Portals operators apply `frontend/migrations/015_application_user_channel_history.sql`; creator
-applications do not own or run this migration. Construct the provider with a token verifier that
-validates the credential server-side and returns an active `application_users.id`, plus a
-`PostgresIdentityStore`. Never let a browser-supplied user ID be the verifier's result.
+Auth-gateway supplies only `userId` and `displayName`. Sync never changes an existing
+account's status, email, encrypted identity, preferences, or issuer. Application account
+creation must go through the application's provisioning flow: its schema requires
+`email_hash` and `identity_ciphertext`, which auth-gateway does not provide.
 
-## Limits
+Configure `AUTH_GATEWAY_ADDRESS` (`host:port`), `AUTH_GATEWAY_RESOURCE_ID`,
+`AUTH_GATEWAY_TLS=true` for TLS, and `CENTRAL_DATABASE_URL` or `DATABASE_URL`.
+Environment variables are read by the application, not implicitly by this package.
+Use database TLS and least-privilege runtime credentials; run migrations separately with
+DDL credentials. Stop accepting requests before closing the gRPC client and database pool.
 
-- Interaction time is the storage transaction clock, so a caller cannot backdate or forward-date history.
-- `channelId` and `sessionId` are 1–128 characters, enforced in code and by the table.
-- `getHistory` reads at most `DEFAULT_HISTORY_ENTRIES` (100) rows and clamps any request to `MAX_HISTORY_ENTRIES` (500).
+```typescript
+import pg from "pg";
+import {
+  CentralIdentityStore, IdentityProvider, createAuthGatewayClient,
+} from "@portalshq/capability-identity";
 
-## Tests
+const pool = new pg.Pool({ connectionString: process.env.CENTRAL_DATABASE_URL });
+const gateway = createAuthGatewayClient({
+  address: process.env.AUTH_GATEWAY_ADDRESS!,
+  useTls: process.env.AUTH_GATEWAY_TLS === "true",
+  timeout: 5000,
+});
+const provider = new IdentityProvider(
+  async (token) => (await gateway.verifyUser(token)).userId,
+  new CentralIdentityStore(pool),
+);
+// token comes from the authenticated request; provisioning/sync is a separate trusted flow.
+// const identity = await provider.getIdentity(token);
+// await provider.recordInteraction(token, { channelId: "channel-1", sessionId: "session-1" });
+// const history = await provider.getHistory(token, 25);
+```
 
-`npm test` runs the provider and store unit tests. The PostgreSQL integration suite runs only when
-`IDENTITY_TEST_DATABASE_URL` points at a scratch database, because it creates and drops its own tables.
+See the [integration guide](docs/integration-guide.md) for provisioning, profile sync,
+custom-store migration, and a complete runnable example.
+
+## Database migration
+
+### Central database
+
+Run only on a dedicated central identity database, before deploying application code:
+
+```typescript
+import pg from "pg";
+import { runCentralMigrations } from "@portalshq/capability-identity";
+const pool = new pg.Pool({ connectionString: process.env.CENTRAL_DATABASE_URL });
+try { await runCentralMigrations(pool); } finally { await pool.end(); }
+```
+
+The versioned `sql/001_central_identity.sql` ships in the npm package. The runner applies
+it atomically with a transaction-scoped advisory lock and can be rerun or called concurrently.
+It creates `users`, `user_preferences` (JSONB values by key), `channel_apps`,
+`channel_schedules`, `channel_sessions`, and `user_channel_history` with history indexes.
+It does not open or close the supplied pool. PostgreSQL errors propagate to the caller.
+Manual alternative: execute that SQL in a transaction with `psql -v ON_ERROR_STOP=1 --single-transaction`.
+
+The migration also upgrades the previously distributed central schema: adds active/suspended
+status, allows missing issuer information and optional legacy `app_id` on history, and adds
+the conflict key used by the store. Channel and session IDs must be globally scoped across
+applications; history is unique on `(user_id, channel_id, session_id)`. Legacy `app_id`
+values and metadata are retained. The store does not populate the channel registries.
+
+Back up before upgrading. Existing duplicate soft keys, null sessions, or blank/oversized
+identifiers cause migration failure and full rollback. Reconcile these records explicitly
+according to your application's identity rules, then rerun. The migration never deletes
+history to resolve ambiguity. There is no destructive automatic down migration.
+
+### Application database
+
+Portals operators provision application accounts and apply
+`frontend/migrations/015_application_user_channel_history.sql` in the platform repository.
+Creator applications do not run platform migrations. `PostgresIdentityStore` remains an
+alias of `ApplicationIdentityStore`. Application sync requires the schema's `updated_at`
+column and never synthesizes the private identity fields required for account creation.
+
+## Public interface
+
+```typescript
+interface AudienceIdentity {
+  userId: string;
+  displayName: string;
+  email?: string;
+  preferences?: Record<string, unknown>;
+}
+interface ChannelInteraction { channelId: string; sessionId: string }
+interface ChannelHistoryEntry extends ChannelInteraction {
+  lastInteractionAt: string;
+  metadata?: Record<string, unknown>;
+}
+interface IdentityStore {
+  getIdentity(userId: string): Promise<AudienceIdentity | undefined>;
+  recordInteraction(userId: string, interaction: ChannelInteraction): Promise<void>;
+  getHistory(userId: string, limit: number): Promise<readonly ChannelHistoryEntry[]>;
+}
+interface SyncableIdentityStore extends IdentityStore {
+  syncFromAuthGateway(userId: string, displayName: string): Promise<void>;
+}
+```
+
+- `new IdentityProvider(verifyAccessToken, store)`: verifier is `(token: string) => Promise<string>`;
+  it must validate credentials server-side and return the verified subject ID.
+- `provider.getIdentity(accessToken): Promise<AudienceIdentity>`: rejects unknown/suspended accounts.
+- `provider.recordInteraction(accessToken, interaction): Promise<void>`: validates soft IDs,
+  then verifies the account and writes using the database clock.
+- `provider.getHistory(accessToken, limit = 100): Promise<readonly ChannelHistoryEntry[]>`:
+  requires a positive integer and clamps to 500. Results are newest first.
+- `provider.syncFromAuthGateway(userId, gateway, resourceId): Promise<void>`: requires a
+  `getUserInfo` client and a sync-capable store, rejects mismatched subjects and propagates
+  upstream/storage errors. IDs must be nonblank and at most 128 trimmed characters.
+- `provider.validateSoftKey(table, key, centralPool): Promise<boolean>`: parameterized lookup
+  for `users`, `channel_apps`, or `channel_schedules` only. Invalid table names throw;
+  missing rows/database errors return false. Existence does not imply an active account.
+- `new ApplicationIdentityStore(pool)` / `new CentralIdentityStore(pool)`: implement the
+  sync-capable interface. Callers using adapters directly must validate IDs and history limits;
+  `IdentityProvider` supplies that validation. Neither adapter owns the pool lifecycle.
+- `centralStore.updateUserInfo(userId, displayName): Promise<void>`: legacy update-only
+  method, silently leaves a missing user untouched. Prefer explicit sync for provisioning.
+- `runCentralMigrations(pool): Promise<void>`: central provisioning described above.
+- `QueryRunner`: `query(text: string, values?: unknown[])` returning a promise of
+  `{ rowCount: number | null; rows: Record<string, unknown>[] }`; compatible with `pg.Pool`.
+- `createAuthGatewayClient({ address, useTls?, timeout?, protoPath? }): AuthGatewayClient`:
+  requires a nonblank address; timeout is a finite positive per-call deadline, default 5000ms.
+  Uses the bundled proto unless overridden. Default transport is insecure for private/local
+  use; enable TLS for deployment. Proto load errors are synchronous.
+- Client methods: `verifyUser(token)`, `getUserInfo(resourceId, userId)`, and
+  `getUserId(resourceId, displayName)` return `Promise<UserInfo>`; `UserInfo` contains
+  `userId` and `displayName`. Malformed/missing identities reject; gRPC errors retain their
+  `code` and `details`. `close(): void` is idempotent; later calls reject.
+- Constants: `MAX_IDENTIFIER_LENGTH=128`, `DEFAULT_HISTORY_ENTRIES=100`,
+  `MAX_HISTORY_ENTRIES=500`, and `INACTIVE_ACCOUNT_ERROR`.
+
+Interactions upsert without moving timestamps backwards. Account eligibility and writes
+are checked in one statement. Concurrent changes follow PostgreSQL statement snapshot
+semantics; credential revocation and suspension are not a distributed transaction.
+The PostgreSQL adapters return only channel ID, session ID, and timestamp in history;
+optional metadata is reserved for custom adapters. Central preferences come from
+`user_preferences`; application preferences/email remain application-owned.
+
+## Testing and packaging
+
+From the repository root:
+
+```sh
+npm run build --workspace=@portalshq/capability-identity
+npm run typecheck --workspace=@portalshq/capability-identity
+npm test --workspace=@portalshq/capability-identity
+npm run test:coverage --workspace=@portalshq/capability-identity
+```
+
+Coverage enforces at least 95% statements, branches, functions, and lines for all published
+TypeScript source. Build tooling is validated separately by building and inspecting the pack.
+The real local gRPC transport suite needs permission to bind localhost. Build copies the
+repository's canonical proto to `src/proto` and `dist/proto`; the latter ships with the package.
+Clean checkouts without the lore submodule build from the checked-in protocol snapshot.
+The source snapshot also lets tests run before building. Updating the canonical proto
+requires a build and committing the refreshed source copy. Installed consumers need neither
+the repository nor the canonical proto path.
+
+Database suites use explicit non-production connection variables:
+`IDENTITY_TEST_DATABASE_URL` and `IDENTITY_CENTRAL_TEST_DATABASE_URL`.
+The application suite drops/recreates its named tables and **must use a disposable database**.
+The central suite uses randomly named schemas and removes only those schemas.
+Without URLs, database suites skip. The deployed gateway suite additionally requires
+`AUTH_GATEWAY_ADDRESS`, `AUTH_GATEWAY_RESOURCE_ID`, and
+`IDENTITY_AUTH_GATEWAY_TEST_TOKEN`; supply a dedicated test identity and TLS setting.
+It verifies the token, both lookups, and invalid-credential rejection without writing profiles.
+
+## Troubleshooting
+
+| Symptom | Resolution |
+| --- | --- |
+| Inactive account error | Verify subject-to-local-account mapping and local status; sync does not reactivate accounts. |
+| Application account must be provisioned | Run the application's account-creation flow before syncing its profile. |
+| Store does not support sync | Implement `SyncableIdentityStore`, or omit explicit sync for a custom cache. |
+| Central missing columns/conflict constraint | Apply the packaged central migration using DDL credentials before deploying. |
+| Migration fails on duplicate/null/invalid history | Back up and reconcile legacy records; failures roll back, preserving evidence. |
+| Proto not found | Rebuild from the repository or reinstall the published package; check custom `protoPath`. |
+| `UNAVAILABLE` / `DEADLINE_EXCEEDED` | Check address, reachability, TLS, and per-call timeout. Retry only under your caller's policy. |
+| `UNAUTHENTICATED` | Refresh/reject the credential; never fall back to a browser-supplied user ID. |
+| Soft-key lookup returns false | Check registry data and connectivity; database failures deliberately fail closed. |
+
+## Release validation
+
+Version 0.2.1 adds profile synchronization, packaged proto assets, central schema provisioning,
+and the tests and guides above. Local PostgreSQL and gRPC transport tests are separate from
+deployed auth-gateway acceptance. See `CHANGELOG.md` for the release record.

package/dist/auth-gateway-client.d.ts

@@ -0,0 +1,19 @@
+export interface UserInfo {
+    userId: string;
+    displayName: string;
+}
+export interface AuthGatewayClient {
+    verifyUser(token: string): Promise<UserInfo>;
+    getUserInfo(resourceId: string, userId: string): Promise<UserInfo>;
+    getUserId(resourceId: string, displayName: string): Promise<UserInfo>;
+    close(): void;
+}
+export interface AuthGatewayClientConfig {
+    address: string;
+    /** Enable TLS outside a trusted private network. */
+    useTls?: boolean;
+    /** Per-call deadline in milliseconds, defaults to 5000. */
+    timeout?: number;
+    protoPath?: string;
+}
+export declare function createAuthGatewayClient(config: AuthGatewayClientConfig): AuthGatewayClient;

package/dist/auth-gateway-client.js

@@ -0,0 +1,41 @@
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { fileURLToPath } from "node:url";
+export function createAuthGatewayClient(config) {
+    if (!config.address.trim())
+        throw new TypeError("Auth-gateway address is required.");
+    const timeout = config.timeout ?? 5000;
+    if (!Number.isFinite(timeout) || timeout <= 0)
+        throw new TypeError("Timeout must be positive and finite.");
+    const definition = protoLoader.loadSync(config.protoPath ?? fileURLToPath(new URL("./proto/auth_api.proto", import.meta.url)), {
+        keepCase: true, longs: String, enums: String, defaults: true, oneofs: true,
+    });
+    const methods = definition["epic_urc.UrcAuthApi"];
+    const descriptor = grpc.loadPackageDefinition(definition);
+    const namespace = descriptor.epic_urc;
+    const Constructor = namespace.UrcAuthApi;
+    const client = new Constructor(config.address, config.useTls ? grpc.credentials.createSsl() : grpc.credentials.createInsecure());
+    let closed = false;
+    async function call(method, request, expectedId) {
+        if (closed)
+            throw new Error("Auth-gateway client is closed.");
+        const response = await new Promise((resolve, reject) => {
+            client.makeUnaryRequest(`/epic_urc.UrcAuthApi/${method}`, (value) => methods[method].requestSerialize(value), (value) => methods[method].responseDeserialize(value), request, new grpc.Metadata(), { deadline: Date.now() + timeout }, (error, result) => error ? reject(error) : resolve(result ?? {}));
+        });
+        const candidates = Array.isArray(response.user_info) ? response.user_info : response.user_info ? [response.user_info] : [];
+        const user = expectedId ? candidates.find((candidate) => candidate.user_id === expectedId) : candidates[0];
+        if (!user || typeof user.user_id !== "string" || !user.user_id.trim() || typeof user.display_name !== "string") {
+            throw new Error(`Auth-gateway ${method} returned no valid user info`);
+        }
+        return { userId: user.user_id, displayName: user.display_name };
+    }
+    return {
+        verifyUser: (token) => call("VerifyUser", { target_user: { user_token: token }, requirements: [] }),
+        getUserInfo: (resourceId, userId) => call("GetUserInfo", { resource_id: resourceId, user_id: [userId] }, userId),
+        getUserId: (resourceId, displayName) => call("GetUserId", { resource_id: resourceId, user_display_name: displayName }),
+        close: () => { if (!closed) {
+            closed = true;
+            client.close();
+        } },
+    };
+}

package/dist/central-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Central database identity store.
+ *
+ * This store is for central Portals identity data (users table in central database).
+ * For app-specific user data, use ApplicationIdentityStore.
+ *
+ * The central database contains cross-app identity data shared across all Portals applications.
+ */
+import { type AudienceIdentity, type ChannelHistoryEntry, type ChannelInteraction, type SyncableIdentityStore } from "./identity-provider.js";
+import type { QueryRunner } from "./postgres-store.js";
+/**
+ * Central database identity store.
+ *
+ * This store queries the central database users table for cross-app identity.
+ * The central database schema is defined in central-schema.sql.
+ */
+export declare class CentralIdentityStore implements SyncableIdentityStore {
+    private readonly pool;
+    constructor(pool: QueryRunner);
+    getIdentity(userId: string): Promise<AudienceIdentity | undefined>;
+    /**
+     * Record interaction in central database channel history.
+     *
+     * The active-account check and write share one PostgreSQL statement snapshot.
+     * GREATEST keeps the newest interaction when
+     * concurrent transactions commit out of order.
+     */
+    recordInteraction(userId: string, interaction: ChannelInteraction): Promise<void>;
+    getHistory(userId: string, limit: number): Promise<readonly ChannelHistoryEntry[]>;
+    /**
+     * Update user information in central database.
+     *
+     * This is used by syncFromAuthGateway to update user data from auth-gateway.
+     * Note: Auth-gateway only provides user_id and display_name. Email and
+     * preferences must be managed by the application.
+     */
+    syncFromAuthGateway(userId: string, displayName: string): Promise<void>;
+    updateUserInfo(userId: string, displayName: string): Promise<void>;
+}

package/dist/central-store.js

@@ -0,0 +1,78 @@
+/**
+ * Central database identity store.
+ *
+ * This store is for central Portals identity data (users table in central database).
+ * For app-specific user data, use ApplicationIdentityStore.
+ *
+ * The central database contains cross-app identity data shared across all Portals applications.
+ */
+import { INACTIVE_ACCOUNT_ERROR, } from "./identity-provider.js";
+/**
+ * Central database identity store.
+ *
+ * This store queries the central database users table for cross-app identity.
+ * The central database schema is defined in central-schema.sql.
+ */
+export class CentralIdentityStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async getIdentity(userId) {
+        const result = await this.pool.query(`SELECT u.id, u.display_name, u.email,
+       (SELECT jsonb_object_agg(key, value) FROM user_preferences WHERE user_id = u.id) AS preferences
+       FROM users u WHERE id = $1 AND status = 'active'`, [userId]);
+        const row = result.rows[0];
+        if (!row)
+            return undefined;
+        return {
+            userId: String(row.id),
+            displayName: String(row.display_name),
+            email: row.email ? String(row.email) : undefined,
+            preferences: row.preferences ? row.preferences : undefined,
+        };
+    }
+    /**
+     * Record interaction in central database channel history.
+     *
+     * The active-account check and write share one PostgreSQL statement snapshot.
+     * GREATEST keeps the newest interaction when
+     * concurrent transactions commit out of order.
+     */
+    async recordInteraction(userId, interaction) {
+        const result = await this.pool.query(`INSERT INTO user_channel_history (user_id, channel_id, session_id, last_interaction_at)
+       SELECT $1, $2, $3, now()
+       WHERE EXISTS (SELECT 1 FROM users WHERE id = $1 AND status = 'active')
+       ON CONFLICT (user_id, channel_id, session_id) DO UPDATE
+       SET last_interaction_at = GREATEST(user_channel_history.last_interaction_at, EXCLUDED.last_interaction_at)`, [userId, interaction.channelId, interaction.sessionId]);
+        if (!result.rowCount)
+            throw new Error(INACTIVE_ACCOUNT_ERROR);
+    }
+    async getHistory(userId, limit) {
+        const result = await this.pool.query(`SELECT channel_id, session_id, last_interaction_at
+       FROM user_channel_history
+       WHERE user_id = $1 ORDER BY last_interaction_at DESC LIMIT $2`, [userId, limit]);
+        return result.rows.map(historyFromRow);
+    }
+    /**
+     * Update user information in central database.
+     *
+     * This is used by syncFromAuthGateway to update user data from auth-gateway.
+     * Note: Auth-gateway only provides user_id and display_name. Email and
+     * preferences must be managed by the application.
+     */
+    async syncFromAuthGateway(userId, displayName) {
+        await this.pool.query(`INSERT INTO users (id, display_name) VALUES ($1, $2)
+       ON CONFLICT (id) DO UPDATE SET display_name = EXCLUDED.display_name, updated_at = now()`, [userId, displayName]);
+    }
+    async updateUserInfo(userId, displayName) {
+        await this.pool.query("UPDATE users SET display_name = $2, updated_at = now() WHERE id = $1", [userId, displayName]);
+    }
+}
+function historyFromRow(row) {
+    return {
+        channelId: String(row.channel_id),
+        sessionId: String(row.session_id),
+        lastInteractionAt: new Date(row.last_interaction_at).toISOString(),
+    };
+}

package/dist/identity-provider.d.ts

@@ -1,3 +1,5 @@
+import type { AuthGatewayClient } from "./auth-gateway-client.js";
+import type { QueryRunner } from "./postgres-store.js";
 /**
  * One identity per audience member, scoped to read across every channel
  * they've ever touched. This is the "Netflix history, but spanning every
@@ -8,6 +10,8 @@
 export interface AudienceIdentity {
     userId: string;
     displayName: string;
+    email?: string;
+    preferences?: Record<string, unknown>;
 }
 /** Soft cross-database key; the matching channel row may live elsewhere. */
 export interface ChannelInteraction {
@@ -16,6 +20,7 @@ export interface ChannelInteraction {
 }
 export interface ChannelHistoryEntry extends ChannelInteraction {
     lastInteractionAt: string;
+    metadata?: Record<string, unknown>;
 }
 /** Matches the identifier bounds in the platform migration. */
 export declare const MAX_IDENTIFIER_LENGTH = 128;
@@ -27,7 +32,10 @@ export interface IdentityStore {
     recordInteraction(userId: string, interaction: ChannelInteraction): Promise<void>;
     getHistory(userId: string, limit: number): Promise<readonly ChannelHistoryEntry[]>;
 }
-/** Must validate the credential and return an active application user ID. */
+export interface SyncableIdentityStore extends IdentityStore {
+    syncFromAuthGateway(userId: string, displayName: string): Promise<void>;
+}
+/** Must validate the credential and return its verified subject ID. */
 export type VerifyAccessToken = (accessToken: string) => Promise<string>;
 export declare class IdentityProvider {
     private readonly verifyAccessToken;
@@ -37,4 +45,32 @@ export declare class IdentityProvider {
     /** Interaction time is the storage transaction's clock, never the caller's. */
     recordInteraction(accessToken: string, interaction: ChannelInteraction): Promise<void>;
     getHistory(accessToken: string, limit?: number): Promise<readonly ChannelHistoryEntry[]>;
+    /**
+     * On-demand sync from auth-gateway.
+     *
+     * Explicitly call this to sync user data from auth-gateway to the local store.
+     * This is not called automatically on every request to avoid unnecessary network calls.
+     *
+     * Note: Auth-gateway UserInfo only contains user_id and display_name.
+     * Email and preferences are not available from auth-gateway and must be managed
+     * by the application itself.
+     *
+     * @param userId - The user ID to sync
+     * @param authGatewayClient - Auth-gateway gRPC client
+     * @param resourceId - The resource ID (application identifier)
+     */
+    syncFromAuthGateway(userId: string, authGatewayClient: Pick<AuthGatewayClient, "getUserInfo">, resourceId: string): Promise<void>;
+    /**
+     * Validate a soft key reference to a central database table.
+     *
+     * Used to validate cross-database references when databases are separate instances.
+     * This is an application-level validation because PostgreSQL foreign keys don't
+     * work across database instances.
+     *
+     * @param table - The table name to validate against (e.g., "users")
+     * @param key - The key value to validate (e.g., user ID)
+     * @param centralPool - PostgreSQL pool for central database connection
+     * @returns true if the key exists in the central database, false otherwise
+     */
+    validateSoftKey(table: string, key: string, centralPool: QueryRunner): Promise<boolean>;
 }

package/dist/identity-provider.js

@@ -28,6 +28,59 @@ export class IdentityProvider {
         const identity = await this.getIdentity(accessToken);
         return this.store.getHistory(identity.userId, historyLimit(limit));
     }
+    /**
+     * On-demand sync from auth-gateway.
+     *
+     * Explicitly call this to sync user data from auth-gateway to the local store.
+     * This is not called automatically on every request to avoid unnecessary network calls.
+     *
+     * Note: Auth-gateway UserInfo only contains user_id and display_name.
+     * Email and preferences are not available from auth-gateway and must be managed
+     * by the application itself.
+     *
+     * @param userId - The user ID to sync
+     * @param authGatewayClient - Auth-gateway gRPC client
+     * @param resourceId - The resource ID (application identifier)
+     */
+    async syncFromAuthGateway(userId, authGatewayClient, resourceId) {
+        assertIdentifier(userId, "userId");
+        assertIdentifier(resourceId, "resourceId");
+        if (!("syncFromAuthGateway" in this.store) || typeof this.store.syncFromAuthGateway !== "function") {
+            throw new Error("Identity store does not support auth-gateway sync.");
+        }
+        const userInfo = await authGatewayClient.getUserInfo(resourceId, userId);
+        if (userInfo.userId !== userId || typeof userInfo.displayName !== "string") {
+            throw new Error("Auth-gateway returned an invalid or mismatched identity.");
+        }
+        await this.store.syncFromAuthGateway(userId, userInfo.displayName);
+    }
+    /**
+     * Validate a soft key reference to a central database table.
+     *
+     * Used to validate cross-database references when databases are separate instances.
+     * This is an application-level validation because PostgreSQL foreign keys don't
+     * work across database instances.
+     *
+     * @param table - The table name to validate against (e.g., "users")
+     * @param key - The key value to validate (e.g., user ID)
+     * @param centralPool - PostgreSQL pool for central database connection
+     * @returns true if the key exists in the central database, false otherwise
+     */
+    async validateSoftKey(table, key, centralPool) {
+        // Validate table name to prevent SQL injection
+        const allowedTables = ["users", "channel_apps", "channel_schedules"];
+        if (!allowedTables.includes(table)) {
+            throw new Error(`Invalid table name for soft key validation: ${table}`);
+        }
+        try {
+            const result = await centralPool.query(`SELECT 1 FROM ${table} WHERE id = $1 LIMIT 1`, [key]);
+            return result.rowCount !== null && result.rowCount > 0;
+        }
+        catch (error) {
+            console.error(`[identity] Failed to validate soft key in table ${table}:`, error);
+            return false;
+        }
+    }
 }
 function assertIdentifier(value, field) {
     const trimmed = value?.trim() ?? "";

package/dist/index.d.ts

@@ -1,2 +1,5 @@
 export * from "./identity-provider.js";
 export * from "./postgres-store.js";
+export { CentralIdentityStore } from "./central-store.js";
+export * from "./auth-gateway-client.js";
+export { runCentralMigrations } from "./migrations.js";

package/dist/index.js

@@ -1,2 +1,5 @@
 export * from "./identity-provider.js";
 export * from "./postgres-store.js";
+export { CentralIdentityStore } from "./central-store.js";
+export * from "./auth-gateway-client.js";
+export { runCentralMigrations } from "./migrations.js";

package/dist/migrations.d.ts

@@ -0,0 +1,6 @@
+import type { QueryRunner } from "./postgres-store.js";
+/** Apply on a dedicated central database. A single query is one atomic transaction.
+ * Safe to rerun; an advisory transaction lock serializes concurrent provisioning.
+ * Never run on an application database.
+ */
+export declare function runCentralMigrations(pool: QueryRunner): Promise<void>;

package/dist/migrations.js

@@ -0,0 +1,12 @@
+import { readFile } from "node:fs/promises";
+/** Apply on a dedicated central database. A single query is one atomic transaction.
+ * Safe to rerun; an advisory transaction lock serializes concurrent provisioning.
+ * Never run on an application database.
+ */
+export async function runCentralMigrations(pool) {
+    const sql = await readFile(new URL("../sql/001_central_identity.sql", import.meta.url), "utf8");
+    await pool.query(`DO $identity_migration$ BEGIN
+PERFORM pg_advisory_xact_lock(761830214);
+${sql}
+END $identity_migration$;`);
+}

package/dist/postgres-store.d.ts

@@ -1,4 +1,4 @@
-import { type AudienceIdentity, type ChannelHistoryEntry, type ChannelInteraction, type IdentityStore } from "./identity-provider.js";
+import { type AudienceIdentity, type ChannelHistoryEntry, type ChannelInteraction, type SyncableIdentityStore } from "./identity-provider.js";
 /** Minimal shape of `pg.Pool`, so the published types need no pg typings. */
 export interface QueryRunner {
     query(text: string, values?: unknown[]): Promise<{
@@ -6,15 +6,28 @@ export interface QueryRunner {
         rows: Array<Record<string, unknown>>;
     }>;
 }
-export declare class PostgresIdentityStore implements IdentityStore {
+/**
+ * Application-specific identity store.
+ *
+ * This store is for app-specific user data (application_users table).
+ * For central database user data, use CentralIdentityStore.
+ */
+export declare class ApplicationIdentityStore implements SyncableIdentityStore {
     private readonly pool;
     constructor(pool: QueryRunner);
+    /** Profile refresh only: account creation requires application-owned identity fields. */
+    syncFromAuthGateway(userId: string, displayName: string): Promise<void>;
     getIdentity(userId: string): Promise<AudienceIdentity | undefined>;
     /**
-     * The active-account check and the write are one statement, so a suspension
-     * can never land between them. GREATEST keeps the newest interaction when
+     * The active-account check and write share one PostgreSQL statement snapshot.
+     * GREATEST keeps the newest interaction when
      * concurrent transactions commit out of order.
      */
     recordInteraction(userId: string, interaction: ChannelInteraction): Promise<void>;
     getHistory(userId: string, limit: number): Promise<readonly ChannelHistoryEntry[]>;
 }
+/**
+ * Legacy PostgresIdentityStore - renamed to ApplicationIdentityStore for clarity.
+ * Kept for backward compatibility.
+ */
+export declare const PostgresIdentityStore: typeof ApplicationIdentityStore;

package/dist/postgres-store.js

@@ -1,17 +1,29 @@
 import { INACTIVE_ACCOUNT_ERROR, } from "./identity-provider.js";
-export class PostgresIdentityStore {
+/**
+ * Application-specific identity store.
+ *
+ * This store is for app-specific user data (application_users table).
+ * For central database user data, use CentralIdentityStore.
+ */
+export class ApplicationIdentityStore {
     pool;
     constructor(pool) {
         this.pool = pool;
     }
+    /** Profile refresh only: account creation requires application-owned identity fields. */
+    async syncFromAuthGateway(userId, displayName) {
+        const result = await this.pool.query("UPDATE application_users SET display_name = $2, updated_at = now() WHERE id = $1", [userId, displayName]);
+        if (!result.rowCount)
+            throw new Error("Application account must be provisioned before profile sync.");
+    }
     async getIdentity(userId) {
         const result = await this.pool.query("SELECT id, display_name FROM application_users WHERE id = $1 AND status = 'active'", [userId]);
         const row = result.rows[0];
         return row ? { userId: String(row.id), displayName: String(row.display_name) } : undefined;
     }
     /**
-     * The active-account check and the write are one statement, so a suspension
-     * can never land between them. GREATEST keeps the newest interaction when
+     * The active-account check and write share one PostgreSQL statement snapshot.
+     * GREATEST keeps the newest interaction when
      * concurrent transactions commit out of order.
      */
     async recordInteraction(userId, interaction) {
@@ -30,6 +42,11 @@ export class PostgresIdentityStore {
         return result.rows.map(historyFromRow);
     }
 }
+/**
+ * Legacy PostgresIdentityStore - renamed to ApplicationIdentityStore for clarity.
+ * Kept for backward compatibility.
+ */
+export const PostgresIdentityStore = ApplicationIdentityStore;
 function historyFromRow(row) {
     return {
         channelId: String(row.channel_id),

package/dist/proto/auth_api.proto

@@ -0,0 +1,170 @@
+syntax = "proto3";
+
+package epic_urc;
+
+service UrcAuthApi {
+  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse) {};
+  rpc StartAuthSession(StartAuthSessionRequest)
+      returns (StartAuthSessionResponse) {};
+  rpc GetAuthSession(GetAuthSessionRequest) returns (GetAuthSessionResponse) {};
+  rpc RefreshAuthSession(RefreshAuthSessionRequest)
+      returns (RefreshAuthSessionResponse) {};
+  rpc RevokeAuthSession(RevokeAuthSessionRequest)
+      returns (RevokeAuthSessionResponse) {};
+  rpc VerifyUser(VerifyUserRequest)
+      returns (VerifyUserResponse) {};
+
+  // For external authentication token login
+  rpc ExchangeExternalTokenForUserToken(ExchangeExternalTokenForUserTokenRequest) returns (ExchangeExternalTokenForUserTokenResponse) {};
+
+  // For API key login
+  rpc ExchangeAPIKeyForUserToken(ExchangeAPIKeyForUserTokenRequest) returns (ExchangeAPIKeyForUserTokenResponse) {};
+
+  // For token exchange
+  rpc ExchangeUserTokenForMultiresourceToken(
+      ExchangeUserTokenForMultiresourceTokenRequest)
+      returns (ExchangeUserTokenForMultiresourceTokenResponse) {};
+
+  // For permission checks
+  rpc CheckUserPermission(CheckUserPermissionRequest)
+      returns (CheckUserPermissionResponse) {};
+  rpc LookupUserPermissions(LookupUserPermissionsRequest)
+      returns (LookupUserPermissionsResponse) {};
+
+  // User metadata
+  rpc GetUserInfo(GetUserInfoRequest) returns (GetUserInfoResponse) {};
+  rpc GetUserId(GetUserIdRequest) returns (GetUserIdResponse) {};
+  rpc GetProviderUserId(GetProviderUserIdRequest) returns (GetProviderUserIdResponse) {};
+}
+
+message TargetUser {
+  oneof user {
+    string user_token = 1;
+  }
+}
+
+message HealthCheckRequest {}
+
+message HealthCheckResponse { string status = 1; }
+
+message StartAuthSessionRequest { string client_state = 1; }
+
+message StartAuthSessionResponse {
+  string session_code = 1;
+  string login_url = 2;
+}
+
+message GetAuthSessionRequest {
+  string session_code = 1;
+  string client_state = 2;
+}
+
+message GetAuthSessionResponse { optional UserToken user_token = 1; }
+
+message RefreshAuthSessionRequest {}
+
+message RefreshAuthSessionResponse { optional UserToken user_token = 1; }
+
+message RevokeAuthSessionRequest {}
+
+message RevokeAuthSessionResponse {}
+
+// Verify the target is compliant with the given Product Name as registered in `ucs-auth-api` config
+message VerifyCompliance {
+  string product_name = 1;
+}
+message VerifyRequirement {
+  reserved 1; // deprecated token
+  oneof requirement {
+    VerifyCompliance compliance = 2;
+  };
+}
+
+message VerifyUserRequest {
+  TargetUser target_user = 1;
+  repeated VerifyRequirement requirements = 2;
+}
+message VerifyUserResponse {
+  UserInfo user_info = 1;
+}
+
+message ExchangeExternalTokenForUserTokenRequest { string external_token = 1; string token_type = 2; }
+
+message ExchangeExternalTokenForUserTokenResponse { optional UserToken user_token = 1; }
+
+message ExchangeAPIKeyForUserTokenRequest { string api_key = 1; }
+
+message ExchangeAPIKeyForUserTokenResponse { optional UserToken user_token = 1; }
+
+message UserToken {
+  string user_token = 1;
+  int64 expires_at = 2; // Epoch
+  string user_id = 3;   // URC user ID
+  string user_name = 4; // Display name
+  optional string refresh_token = 5; // Opaque rotating refresh credential; only present on auth-session creation/refresh
+}
+
+message ResourcePermission {
+  string resource_id = 1;
+  repeated string permission = 2;
+}
+
+message ExchangeUserTokenForMultiresourceTokenRequest {
+  repeated string resource_id = 1;
+}
+
+message ExchangeUserTokenForMultiresourceTokenResponse { UserToken token = 1; }
+
+message CheckUserPermissionRequest {
+  repeated string resource_id = 1;
+  optional TargetUser target_user = 2;
+}
+
+message CheckUserPermissionResponse {
+  repeated ResourcePermission allowed_resource_permission = 1;
+  repeated ResourcePermission denied_resource_permission = 2;
+}
+
+message LookupUserPermissionsRequest {
+  string resource_filter = 1;
+  optional string context_filter = 2;
+  optional int32 page_size = 3;
+  optional string page_token = 4;
+}
+
+message LookupUserPermissionsResponse {
+  repeated ResourcePermission resource_permission = 1;
+  optional string next_page_token = 2;
+}
+
+message GetUserInfoRequest {
+  string resource_id = 1;
+  repeated string user_id = 2;
+}
+
+message UserInfo {
+  string user_id = 1;
+  string display_name = 2;
+}
+
+message GetUserInfoResponse {
+  repeated UserInfo user_info = 1;
+}
+
+message GetUserIdRequest {
+  string resource_id = 1;
+  string user_display_name = 2;
+}
+
+message GetUserIdResponse {
+  UserInfo user_info = 1;
+}
+
+message GetProviderUserIdRequest {
+  string user_id = 1;
+}
+
+message GetProviderUserIdResponse {
+  string user_id = 1;
+  string provider_user_id = 2;
+}

package/docs/integration-guide.md

@@ -0,0 +1,113 @@
+# Identity integration guide
+
+## Choose the owning database
+
+Use the central adapter when this application owns shared identity provisioning. Use the
+application adapter when Portals has already created an application account. A custom
+`IdentityStore` is appropriate for consumers that only cache sightings and delegate history
+to the platform. Keep token verification on the server in every case.
+
+The storage seam has two concrete adapters; both expose the same profile-sync capability.
+The provider handles upstream subject matching once, so callers do not implement store-specific
+fallbacks. Unsupported custom stores fail explicitly instead of silently ignoring sync.
+
+## Central setup: runnable server-side example
+
+Install `pg` and this package. Configure the central database URL, auth-gateway address,
+resource ID, and TLS. Run central provisioning with DDL credentials before serving traffic.
+This example accepts a **server-obtained test token** and explicitly provisions its verified
+subject. It is an onboarding operation, not middleware to run on every request.
+
+```typescript
+import pg from "pg";
+import {
+  CentralIdentityStore, IdentityProvider, createAuthGatewayClient, runCentralMigrations,
+} from "@portalshq/capability-identity";
+
+const pool = new pg.Pool({ connectionString: process.env.CENTRAL_DATABASE_URL });
+const gateway = createAuthGatewayClient({
+  address: process.env.AUTH_GATEWAY_ADDRESS!,
+  useTls: process.env.AUTH_GATEWAY_TLS === "true",
+  timeout: 5000,
+});
+try {
+  await runCentralMigrations(pool); // deployment setup; use a separate DDL role in production
+  const provider = new IdentityProvider(
+    async (token) => (await gateway.verifyUser(token)).userId,
+    new CentralIdentityStore(pool),
+  );
+  const token = process.env.IDENTITY_AUTH_GATEWAY_TEST_TOKEN!;
+  const verified = await gateway.verifyUser(token);
+  await provider.syncFromAuthGateway(verified.userId, gateway, process.env.AUTH_GATEWAY_RESOURCE_ID!);
+  const identity = await provider.getIdentity(token);
+  await provider.recordInteraction(token, { channelId: "example:channel", sessionId: "example:session" });
+  const history = await provider.getHistory(token, 25);
+  console.log(identity.displayName, history.length);
+} finally {
+  gateway.close();
+  await pool.end();
+}
+```
+
+Application setup uses `new ApplicationIdentityStore(pool)` with the same provider.
+Provision the account through Portals before calling sync. Never fill required encrypted
+identity fields with empty strings or invented data just to make an insert succeed.
+Both adapters preserve suspended status during profile updates.
+
+## Verification and request handling
+
+Extract the request credential, validate it through `verifyUser`, and let `IdentityProvider`
+check the local active account. Return an authentication/authorization failure when verification
+or active-account lookup fails. Treat database and gateway availability errors according to
+your request error policy; do not translate outages into successful anonymous identities.
+Use gRPC error `code` for classification. The package performs no automatic retries.
+
+Run sync in a trusted onboarding/admin flow with a verified subject or an operator-authorized
+subject. `getUserInfo` is a metadata lookup, not proof that the requesting caller owns that ID.
+Soft references only establish existence and cannot approve commercial or access transitions.
+
+## Existing central schema upgrade
+
+Back up, stop incompatible writers, and run `runCentralMigrations` on the central database.
+The migration is repeatable, serializes concurrent runs, and rolls back all changes on failure.
+Existing issuer/email/preferences/history data stays intact. Legacy history with duplicate
+`(user_id, channel_id, session_id)` values across apps must be reconciled by the operator.
+Null sessions and invalid soft IDs must also be resolved explicitly. Globally namespace channel
+and session IDs when different applications previously reused them. Verify the resulting
+history before restarting writers. Do not run the central migration on the platform application
+database or an unrelated database with a table called `users`.
+
+For SQL-only deployment, run the package's `sql/001_central_identity.sql` using
+`psql -v ON_ERROR_STOP=1 --single-transaction`; serialize manual deployments yourself.
+The TypeScript runner handles serialization automatically. No migration runs on import.
+
+## Moving from custom stores
+
+First establish whether the custom store owns identities or is merely a cache. For an owning
+store, back up and map subject IDs without changing them; provision required account fields
+through the owning application's workflow. Import history preserving its original timestamps
+in an operator-controlled migration. `recordInteraction` intentionally cannot backdate events.
+Switch the provider's adapter only after comparing identities, active status, and history.
+
+For a cache, retain its existing `IdentityStore` implementation. Implement profile sync only
+if it has a meaningful persistent effect; an unsupported sync operation should fail explicitly.
+Do not replace a consumer cache with an authoritative store just to reuse a class.
+
+### bears-live-app assessment
+
+No bears-live-app migration is included. The described `AudienceViewerStore` pattern—cache
+viewers on sight, delegate authoritative verification and history to the platform—is compatible
+with the custom-store seam. It serves a different ownership role from either PostgreSQL adapter.
+The implementation was not found in this checkout, so its exact behavior is not verified here.
+Before changing that application, review its actual token validation and platform-history path.
+
+## Operational checklist
+
+Use TLS to the gateway outside a trusted private network, TLS to the database, a finite call
+deadline, and separate migration/runtime database roles. Monitor failed lookups and syncs
+without logging credentials. Close the client and pool during graceful shutdown. Back up
+before legacy migration; restore from backup if an incompatible release must be rolled back.
+No package build, test, or migration runner provisions a remote production database implicitly.
+
+See the [README](../README.md) for the complete interface, environment settings, troubleshooting,
+and commands for PostgreSQL, gRPC, and coverage verification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portalshq/capability-identity",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/portalshq/portals-cloud.git",
@@ -12,19 +12,28 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "sql",
+    "docs",
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json && node scripts/copy-proto.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run"
+    "test": "npm run build && vitest run",
+    "test:coverage": "npm run build && vitest run --coverage"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.11.3",
+    "@grpc/proto-loader": "^0.7.13"
   },
   "devDependencies": {
     "typescript": "^5.5.0",
     "@types/node": "^20.0.0",
     "@types/pg": "^8.15.5",
     "pg": "^8.16.3",
-    "vitest": "^3.2.7"
+    "vitest": "^3.2.7",
+    "@vitest/coverage-v8": "^3.2.7"
   },
   "publishConfig": {
     "access": "public",

package/sql/001_central_identity.sql

@@ -0,0 +1,93 @@
+-- Central database schema for cross-app identity
+-- This schema is for the central Portals database that stores user data
+-- shared across all applications.
+
+-- User registry (all apps)
+CREATE TABLE IF NOT EXISTS users (
+  id text PRIMARY KEY,  -- auth-gateway subject_id
+  display_name text NOT NULL,
+  email text,
+  status text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended')),
+  preferred_username text,
+  idp text,  -- auth-gateway issuer
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- User preferences (all apps)
+CREATE TABLE IF NOT EXISTS user_preferences (
+  user_id text NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  key text NOT NULL,
+  value jsonb NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (user_id, key)
+);
+
+-- Channel registry (all apps)
+CREATE TABLE IF NOT EXISTS channel_apps (
+  id text PRIMARY KEY,  -- App ID
+  name text NOT NULL,
+  tenant_id text NOT NULL,  -- For cross-app analytics
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- Channel schedules (all apps)
+CREATE TABLE IF NOT EXISTS channel_schedules (
+  id text PRIMARY KEY,
+  app_id text NOT NULL REFERENCES channel_apps(id) ON DELETE CASCADE,
+  channel_id text NOT NULL,
+  schedule jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- Channel sessions (all apps)
+CREATE TABLE IF NOT EXISTS channel_sessions (
+  id text PRIMARY KEY,
+  app_id text NOT NULL REFERENCES channel_apps(id) ON DELETE CASCADE,
+  channel_id text NOT NULL,
+  starts_at timestamptz NOT NULL,
+  ends_at timestamptz NOT NULL,
+  metadata jsonb,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- Cross-app user history (for analytics)
+CREATE TABLE IF NOT EXISTS user_channel_history (
+  id bigserial PRIMARY KEY,
+  user_id text NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  app_id text REFERENCES channel_apps(id) ON DELETE CASCADE,
+  channel_id text NOT NULL,
+  session_id text NOT NULL,
+  last_interaction_at timestamptz NOT NULL DEFAULT now(),
+  metadata jsonb,
+  UNIQUE (user_id, channel_id, session_id)
+);
+
+CREATE INDEX IF NOT EXISTS user_channel_history_user_idx ON user_channel_history(user_id);
+CREATE INDEX IF NOT EXISTS user_channel_history_app_idx ON user_channel_history(app_id);
+
+-- Upgrade the previously distributed schema without deleting historical data.
+ALTER TABLE users ADD COLUMN IF NOT EXISTS status text NOT NULL DEFAULT 'active'
+  CHECK (status IN ('active', 'suspended'));
+ALTER TABLE users ALTER COLUMN idp DROP NOT NULL;
+ALTER TABLE user_channel_history ALTER COLUMN app_id DROP NOT NULL;
+-- Duplicate legacy soft keys must be reconciled by an operator before upgrading.
+-- A unique-index failure rolls back the entire migration; history is never discarded.
+CREATE UNIQUE INDEX IF NOT EXISTS user_channel_history_soft_key_idx
+  ON user_channel_history(user_id, channel_id, session_id);
+CREATE INDEX IF NOT EXISTS user_channel_history_recent_idx
+  ON user_channel_history(user_id, last_interaction_at DESC);
+
+ALTER TABLE user_channel_history ALTER COLUMN session_id SET NOT NULL;
+DO $history_constraints$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'user_channel_history'::regclass AND conname = 'identity_history_channel_length') THEN
+    ALTER TABLE user_channel_history ADD CONSTRAINT identity_history_channel_length
+      CHECK (length(btrim(channel_id)) BETWEEN 1 AND 128);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'user_channel_history'::regclass AND conname = 'identity_history_session_length') THEN
+    ALTER TABLE user_channel_history ADD CONSTRAINT identity_history_session_length
+      CHECK (length(btrim(session_id)) BETWEEN 1 AND 128);
+  END IF;
+END $history_constraints$;