@axiom-lattice/pg-stores 1.0.68 → 1.0.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "1.0.68",
+  "version": "1.0.69",
   "description": "PG stores implementation for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -22,8 +22,8 @@
   "dependencies": {
     "pg": "^8.16.3",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "2.1.77",
-    "@axiom-lattice/protocols": "2.1.39"
+    "@axiom-lattice/core": "2.1.78",
+    "@axiom-lattice/protocols": "2.1.40"
   },
   "devDependencies": {
     "@types/node": "^20.11.24",

package/src/createPgStoreConfig.ts

@@ -20,6 +20,7 @@ import { PostgreSQLEvalStore } from "./stores/PostgreSQLEvalStore";
 import { ThreadMessageQueueStore } from "./stores/ThreadMessageQueueStore";
 import { ChannelBindingStore } from "./stores/ChannelBindingStore";
 import { PostgreSQLChannelInstallationStore } from "./stores/PostgreSQLChannelInstallationStore";
+import { PostgreSQLA2AApiKeyStore } from "./stores/PostgreSQLA2AApiKeyStore";
 import { PostgreSQLScheduleStorage } from "./stores/PostgreSQLScheduleStorage";
 
 export function createPgStoreConfig(connectionString: string) {
@@ -42,6 +43,7 @@ export function createPgStoreConfig(connectionString: string) {
     assistant: new PostgreSQLAssistantStore(opts),
     workflowTracking: new PostgreSQLWorkflowTrackingStore(optsAuto),
     threadMessageQueue: new ThreadMessageQueueStore(optsAuto),
+    a2aApiKey: new PostgreSQLA2AApiKeyStore(optsAuto),
     schedule: new PostgreSQLScheduleStorage(opts),
   };
 }

package/src/index.ts

@@ -39,6 +39,7 @@ export * from "./migrations/metrics_config_migrations";
 export * from "./migrations/mcp_server_config_migrations";
 export * from "./migrations/workspace_migrations";
 export * from "./migrations/project_migrations";
+export * from "./migrations/add_project_config_column";
 export * from "./migrations/user_migrations";
 export * from "./migrations/tenant_migrations";
 export * from "./migrations/thread_message_queue_migrations";
@@ -46,11 +47,13 @@ export * from "./migrations/channel_identity_mapping_migration";
 export * from "./migrations/channel_installation_migrations";
 export * from "./migrations/channel_installations_alter_migration";
 export * from "./migrations/channel_bindings_migration";
+export * from "./migrations/a2a_api_key_migration";
 export * from "./migrations/workflow_tracking_migrations";
 export * from "./stores/ChannelBindingStore";
 export * from "./stores/ThreadMessageQueueStore";
 export * from "./stores/ChannelIdentityMappingStore";
 export * from "./stores/PostgreSQLChannelInstallationStore";
+export * from "./stores/PostgreSQLA2AApiKeyStore";
 export * from "./stores/PostgreSQLWorkflowTrackingStore";
 export * from "./stores/PostgreSQLEvalStore";
 export * from "./migrations/eval_migrations";
@@ -71,6 +74,7 @@ export { PostgreSQLUserTenantLinkStore } from "./stores/PostgreSQLUserTenantLink
 export { ChannelBindingStore } from "./stores/ChannelBindingStore";
 export { ChannelIdentityMappingStore } from "./stores/ChannelIdentityMappingStore";
 export { PostgreSQLChannelInstallationStore } from "./stores/PostgreSQLChannelInstallationStore";
+export { PostgreSQLA2AApiKeyStore } from "./stores/PostgreSQLA2AApiKeyStore";
 export { PostgreSQLWorkflowTrackingStore } from "./stores/PostgreSQLWorkflowTrackingStore";
 export { PostgreSQLEvalStore } from "./stores/PostgreSQLEvalStore";
 

package/src/migrations/a2a_api_key_migration.ts

@@ -0,0 +1,36 @@
+import type { Migration } from "./migration";
+import type { PoolClient } from "pg";
+
+export const createA2AApiKeysTable: Migration = {
+  version: 130,
+  name: "create_a2a_api_keys_table",
+  up: async (client: PoolClient) => {
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS lattice_a2a_api_keys (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        key_value TEXT NOT NULL UNIQUE,
+        tenant_id VARCHAR(255) NOT NULL,
+        project_id VARCHAR(255),
+        workspace_id VARCHAR(255),
+        label VARCHAR(255),
+        enabled BOOLEAN NOT NULL DEFAULT true,
+        created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+        updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+      )
+    `);
+
+    await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_lattice_a2a_keys_tenant
+      ON lattice_a2a_api_keys(tenant_id)
+    `);
+
+    await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_lattice_a2a_keys_value
+      ON lattice_a2a_api_keys(key_value)
+      WHERE enabled = true
+    `);
+  },
+  down: async (client: PoolClient) => {
+    await client.query("DROP TABLE IF EXISTS lattice_a2a_api_keys");
+  },
+};

package/src/migrations/add_project_config_column.ts

@@ -0,0 +1,34 @@
+/**
+ * Migration: Add config column to lattice_projects
+ *
+ * Adds a JSONB `config` column to the `lattice_projects` table for storing
+ * application-specific project configuration. Also creates a GIN index for
+ * efficient JSONB queries.
+ */
+
+import { PoolClient } from "pg";
+import { Migration } from "./migration";
+
+/** Adds config JSONB column + GIN index to lattice_projects */
+export const addProjectConfigColumn: Migration = {
+  version: 24,
+  name: "add_project_config_column",
+  up: async (client: PoolClient) => {
+    await client.query(`
+      ALTER TABLE lattice_projects
+      ADD COLUMN IF NOT EXISTS config JSONB
+    `);
+
+    await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_lattice_projects_config 
+      ON lattice_projects USING GIN (config)
+    `);
+  },
+  down: async (client: PoolClient) => {
+    await client.query("DROP INDEX IF EXISTS idx_lattice_projects_config");
+    await client.query(`
+      ALTER TABLE lattice_projects
+      DROP COLUMN IF EXISTS config
+    `);
+  },
+};

package/src/migrations/migration.ts

@@ -1,5 +1,30 @@
 /**
  * Migration system for database schema management
+ *
+ * ## Migration Version Rules
+ *
+ * Version numbers are globally unique across all migrations applied to the same
+ * database. They are NOT auto-assigned — you must pick one manually.
+ *
+ * ### Numbering scheme
+ *
+ * | Range   | Purpose                              |
+ * |---------|--------------------------------------|
+ * | 1–99    | Core table creation + column changes |
+ * | 100+    | Independent feature modules          |
+ *
+ * ### How to pick a version
+ *
+ * 1. Run `grep -rn "version:" src/migrations/ | sort -t: -k3 -n` to list all versions
+ * 2. For a core column change: find the next unused number in the 1–99 range
+ * 3. For a new feature module: find the next unused number in the 100+ range
+ * 4. Verify your chosen version is NOT in the grep output
+ *
+ * @remarks
+ * - Migrations are sorted and applied in version order on startup
+ * - The version must be strictly greater than any migration it depends on
+ * - Use `IF NOT EXISTS` / `IF EXISTS` in SQL to keep migrations idempotent
+ * - A version number collision will cause one migration to be silently skipped
  */
 
 import { Pool, PoolClient } from "pg";

package/src/stores/PostgreSQLA2AApiKeyStore.ts

@@ -0,0 +1,187 @@
+import { Pool } from "pg";
+import type { PoolConfig } from "pg";
+import type {
+  A2AApiKeyStore,
+  A2AApiKeyRecord,
+  CreateA2AApiKeyInput,
+  A2AApiKeyEntry,
+} from "@axiom-lattice/protocols";
+import { MigrationManager } from "../migrations/migration";
+import { createA2AApiKeysTable } from "../migrations/a2a_api_key_migration";
+import { encrypt, decrypt } from "@axiom-lattice/core";
+import { randomUUID } from "crypto";
+
+export interface PostgreSQLA2AApiKeyStoreOptions {
+  poolConfig: string | PoolConfig;
+  autoMigrate?: boolean;
+}
+
+type KeyRow = {
+  id: string;
+  key_value: string;
+  tenant_id: string;
+  project_id: string | null;
+  workspace_id: string | null;
+  label: string | null;
+  enabled: boolean;
+  created_at: Date;
+  updated_at: Date;
+};
+
+function generateApiKey(): string {
+  return `a2a_${randomUUID().replace(/-/g, "")}`;
+}
+
+function mapRowToRecord(row: KeyRow): A2AApiKeyRecord {
+  return {
+    id: row.id,
+    key: decrypt(row.key_value),
+    tenantId: row.tenant_id,
+    projectId: row.project_id || undefined,
+    workspaceId: row.workspace_id || undefined,
+    label: row.label || undefined,
+    enabled: row.enabled,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export class PostgreSQLA2AApiKeyStore implements A2AApiKeyStore {
+  private pool: Pool;
+  private migrationManager: MigrationManager;
+  private initialized = false;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(options: PostgreSQLA2AApiKeyStoreOptions) {
+    this.pool =
+      typeof options.poolConfig === "string"
+        ? new Pool({ connectionString: options.poolConfig })
+        : new Pool(options.poolConfig);
+
+    this.migrationManager = new MigrationManager(this.pool);
+    this.migrationManager.register(createA2AApiKeysTable);
+
+    if (options.autoMigrate !== false) {
+      this.initialize().catch((error) => {
+        console.error("Failed to initialize PostgreSQLA2AApiKeyStore:", error);
+        throw error;
+      });
+    }
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+    if (this.initPromise) return this.initPromise;
+    this.initPromise = (async () => {
+      try {
+        await this.migrationManager.migrate();
+        this.initialized = true;
+      } finally {
+        this.initPromise = null;
+      }
+    })();
+    return this.initPromise;
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (!this.initialized) await this.initialize();
+  }
+
+  async findByKey(key: string): Promise<A2AApiKeyRecord | null> {
+    await this.ensureInitialized();
+    const all = await this.pool.query<KeyRow>(
+      `SELECT * FROM lattice_a2a_api_keys WHERE enabled = true`,
+    );
+    for (const row of all.rows) {
+      if (decrypt(row.key_value) === key) return mapRowToRecord(row);
+    }
+    return null;
+  }
+
+  async list(params: { tenantId?: string; limit?: number; offset?: number }): Promise<A2AApiKeyRecord[]> {
+    await this.ensureInitialized();
+    const limit = params.limit || 100;
+    const offset = params.offset || 0;
+    if (params.tenantId) {
+      const result = await this.pool.query<KeyRow>(
+        `SELECT * FROM lattice_a2a_api_keys WHERE tenant_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`,
+        [params.tenantId, limit, offset],
+      );
+      return result.rows.map(mapRowToRecord);
+    }
+    const result = await this.pool.query<KeyRow>(
+      `SELECT * FROM lattice_a2a_api_keys ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
+      [limit, offset],
+    );
+    return result.rows.map(mapRowToRecord);
+  }
+
+  async create(input: CreateA2AApiKeyInput): Promise<A2AApiKeyRecord> {
+    await this.ensureInitialized();
+    const key = generateApiKey();
+    const result = await this.pool.query<KeyRow>(
+      `INSERT INTO lattice_a2a_api_keys (key_value, tenant_id, project_id, workspace_id, label)
+       VALUES ($1, $2, $3, $4, $5) RETURNING *`,
+      [encrypt(key), input.tenantId, input.projectId || null, input.workspaceId || null, input.label || null],
+    );
+    const record = mapRowToRecord(result.rows[0]);
+    record.key = key;
+    return record;
+  }
+
+  async disable(id: string): Promise<A2AApiKeyRecord> {
+    await this.ensureInitialized();
+    const result = await this.pool.query<KeyRow>(
+      `UPDATE lattice_a2a_api_keys SET enabled = false, updated_at = NOW() WHERE id = $1 RETURNING *`,
+      [id],
+    );
+    if (result.rows.length === 0) throw new Error(`A2A API key not found: ${id}`);
+    return mapRowToRecord(result.rows[0]);
+  }
+
+  async enable(id: string): Promise<A2AApiKeyRecord> {
+    await this.ensureInitialized();
+    const result = await this.pool.query<KeyRow>(
+      `UPDATE lattice_a2a_api_keys SET enabled = true, updated_at = NOW() WHERE id = $1 RETURNING *`,
+      [id],
+    );
+    if (result.rows.length === 0) throw new Error(`A2A API key not found: ${id}`);
+    return mapRowToRecord(result.rows[0]);
+  }
+
+  async rotate(id: string): Promise<A2AApiKeyRecord> {
+    await this.ensureInitialized();
+    const key = generateApiKey();
+    const result = await this.pool.query<KeyRow>(
+      `UPDATE lattice_a2a_api_keys SET key_value = $1, updated_at = NOW() WHERE id = $2 RETURNING *`,
+      [encrypt(key), id],
+    );
+    if (result.rows.length === 0) throw new Error(`A2A API key not found: ${id}`);
+    const record = mapRowToRecord(result.rows[0]);
+    record.key = key;
+    return record;
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.ensureInitialized();
+    await this.pool.query(`DELETE FROM lattice_a2a_api_keys WHERE id = $1`, [id]);
+  }
+
+  async loadIntoMap(): Promise<Map<string, A2AApiKeyEntry>> {
+    await this.ensureInitialized();
+    const result = await this.pool.query<KeyRow>(
+      `SELECT * FROM lattice_a2a_api_keys WHERE enabled = true`,
+    );
+    const map = new Map<string, A2AApiKeyEntry>();
+    for (const row of result.rows) {
+      const key = decrypt(row.key_value);
+      map.set(key, {
+        key,
+        tenantId: row.tenant_id,
+        projectId: row.project_id || undefined,
+        workspaceId: row.workspace_id || undefined,
+      });
+    }
+    return map;
+  }
+}

package/src/stores/PostgreSQLProjectStore.ts

@@ -12,6 +12,7 @@ import {
 } from "@axiom-lattice/protocols";
 import { MigrationManager } from "../migrations/migration";
 import { createProjectsTable } from "../migrations/project_migrations";
+import { addProjectConfigColumn } from "../migrations/add_project_config_column";
 
 /**
  * PostgreSQL ProjectStore options
@@ -49,6 +50,7 @@ export class PostgreSQLProjectStore implements ProjectStore {
 
     this.migrationManager = new MigrationManager(this.pool);
     this.migrationManager.register(createProjectsTable);
+    this.migrationManager.register(addProjectConfigColumn);
 
     // Auto-migrate by default
     if (options.autoMigrate !== false) {
@@ -99,6 +101,7 @@ export class PostgreSQLProjectStore implements ProjectStore {
     workspace_id: string;
     name: string;
     description: string | null;
+    config: unknown | null;
     created_at: Date;
     updated_at: Date;
   }): Project {
@@ -108,6 +111,7 @@ export class PostgreSQLProjectStore implements ProjectStore {
       workspaceId: row.workspace_id,
       name: row.name,
       description: row.description || undefined,
+      config: row.config as Record<string, unknown> || undefined,
       createdAt: row.created_at,
       updatedAt: row.updated_at,
     };
@@ -125,11 +129,12 @@ export class PostgreSQLProjectStore implements ProjectStore {
       workspace_id: string;
       name: string;
       description: string | null;
+      config: unknown | null;
       created_at: Date;
       updated_at: Date;
     }>(
       `
-      SELECT id, tenant_id, workspace_id, name, description, created_at, updated_at
+      SELECT id, tenant_id, workspace_id, name, description, config, created_at, updated_at
       FROM lattice_projects
       WHERE tenant_id = $1 AND workspace_id = $2
       ORDER BY created_at DESC
@@ -152,11 +157,12 @@ export class PostgreSQLProjectStore implements ProjectStore {
       workspace_id: string;
       name: string;
       description: string | null;
+      config: unknown | null;
       created_at: Date;
       updated_at: Date;
     }>(
       `
-      SELECT id, tenant_id, workspace_id, name, description, created_at, updated_at
+      SELECT id, tenant_id, workspace_id, name, description, config, created_at, updated_at
       FROM lattice_projects
       WHERE id = $1 AND tenant_id = $2
     `,
@@ -185,15 +191,16 @@ export class PostgreSQLProjectStore implements ProjectStore {
 
     await this.pool.query(
       `
-      INSERT INTO lattice_projects (id, tenant_id, workspace_id, name, description, created_at, updated_at)
-      VALUES ($1, $2, $3, $4, $5, $6, $7)
+      INSERT INTO lattice_projects (id, tenant_id, workspace_id, name, description, config, created_at, updated_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
       ON CONFLICT (id, tenant_id) DO UPDATE SET
         workspace_id = EXCLUDED.workspace_id,
         name = EXCLUDED.name,
         description = EXCLUDED.description,
+        config = EXCLUDED.config,
         updated_at = EXCLUDED.updated_at
     `,
-      [id, tenantId, workspaceId, data.name, data.description || null, now, now]
+      [id, tenantId, workspaceId, data.name, data.description || null, data.config || null, now, now]
     );
 
     return {
@@ -202,6 +209,7 @@ export class PostgreSQLProjectStore implements ProjectStore {
       workspaceId,
       name: data.name,
       description: data.description,
+      config: data.config,
       createdAt: now,
       updatedAt: now,
     };
@@ -209,6 +217,10 @@ export class PostgreSQLProjectStore implements ProjectStore {
 
   /**
    * Update an existing project
+   *
+   * @remarks
+   * - The `config` field uses **replace** semantics: if provided, it completely
+   *   overwrites the existing config. To preserve the current config, omit this field.
    */
   async updateProject(
     tenantId: string,
@@ -238,6 +250,11 @@ export class PostgreSQLProjectStore implements ProjectStore {
       updateValues.push(updates.description || null);
     }
 
+    if (updates.config !== undefined) {
+      updateFields.push(`config = $${paramIndex++}`);
+      updateValues.push(updates.config || null);
+    }
+
     if (updateFields.length === 0) {
       // No fields to update
       return existing;