@axiom-lattice/pg-stores 1.0.13 → 1.0.14

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/pg-stores@1.0.13 build /home/runner/work/agentic/agentic/packages/pg-stores
+> @axiom-lattice/pg-stores@1.0.14 build /home/runner/work/agentic/agentic/packages/pg-stores
 > tsup src/index.ts --format cjs,esm --dts --sourcemap
 
 CLI Building entry: src/index.ts
@@ -8,13 +8,13 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-ESM dist/index.mjs     43.66 KB
-ESM dist/index.mjs.map 81.24 KB
-ESM ⚡️ Build success in 191ms
-CJS dist/index.js     45.25 KB
-CJS dist/index.js.map 82.54 KB
-CJS ⚡️ Build success in 193ms
+CJS dist/index.js     66.95 KB
+CJS dist/index.js.map 124.96 KB
+CJS ⚡️ Build success in 229ms
+ESM dist/index.mjs     64.94 KB
+ESM dist/index.mjs.map 122.78 KB
+ESM ⚡️ Build success in 231ms
 DTS Build start
-DTS ⚡️ Build success in 7129ms
-DTS dist/index.d.ts  11.40 KB
-DTS dist/index.d.mts 11.40 KB
+DTS ⚡️ Build success in 10174ms
+DTS dist/index.d.ts  18.81 KB
+DTS dist/index.d.mts 18.81 KB

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @axiom-lattice/pg-stores
 
+## 1.0.14
+
+### Patch Changes
+
+- faf1bad: update team and more
+- Updated dependencies [faf1bad]
+  - @axiom-lattice/core@2.1.24
+  - @axiom-lattice/protocols@2.1.14
+
 ## 1.0.13
 
 ### Patch Changes

package/README_DATABASE_CONFIG.md

@@ -0,0 +1,217 @@
+# DatabaseConfigStore 实现说明
+
+## 概述
+
+`DatabaseConfigStore` 是用于存储和管理数据库连接配置的持久化存储方案，支持多租户隔离和密码自动加密。
+
+## 特性
+
+- ✅ **多租户隔离**: 基于 `tenant_id` 字段实现租户级别的数据隔离
+- ✅ **密码加密存储**: 使用 AES-256-GCM 自动加密数据库密码
+- ✅ **自动解密**: 读取配置时自动解密密码，调用方透明
+- ✅ **两种存储实现**: InMemory（开发）和 PostgreSQL（生产）
+- ✅ **集成 SqlDatabaseManager**: 可直接从 Store 加载配置到连接管理器
+
+## 快速开始
+
+### 1. 使用 InMemory 存储（默认）
+
+```typescript
+import { storeLatticeManager } from '@axiom-lattice/core';
+import type { DatabaseConfig } from '@axiom-lattice/protocols';
+
+// 获取默认的 InMemory Store
+const store = await storeLatticeManager.getStoreLattice('default', 'database').store;
+
+// 创建配置
+await store.createConfig('tenant-1', 'config-1', {
+  key: 'main-db',
+  config: {
+    type: 'postgres',
+    host: 'localhost',
+    port: 5432,
+    database: 'mydb',
+    user: 'admin',
+    password: 'secret',
+  },
+  name: 'Main Database',
+});
+
+// 获取配置
+const config = await store.getConfigByKey('tenant-1', 'main-db');
+console.log(config?.config.password); // 密码已自动解密
+```
+
+### 2. 使用 PostgreSQL 存储
+
+```typescript
+import { PostgreSQLDatabaseConfigStore } from '@axiom-lattice/pg-stores';
+
+const pgStore = new PostgreSQLDatabaseConfigStore({
+  poolConfig: process.env.DATABASE_URL,
+  autoMigrate: true,
+});
+
+// 使用方式与 InMemory 相同
+await pgStore.createConfig('tenant-1', 'config-1', {
+  key: 'main-db',
+  config: { /* ... */ },
+});
+```
+
+### 3. 集成到 SqlDatabaseManager
+
+```typescript
+import { sqlDatabaseManager } from '@axiom-lattice/core';
+
+// 从 Store 加载所有配置并注册
+await sqlDatabaseManager.loadConfigsFromStore(store, 'tenant-1');
+
+// 现在可以使用注册的数据库
+const db = sqlDatabaseManager.getDatabase('main-db');
+const tables = await db.listTables();
+```
+
+## 环境变量
+
+### LATTICE_ENCRYPTION_KEY（推荐设置）
+
+用于加密敏感数据的全局密钥。
+
+```bash
+# .env 文件
+LATTICE_ENCRYPTION_KEY="your-secret-key-at-least-32-characters-long"
+```
+
+**注意**:
+- 未设置时使用默认密钥（会输出警告）
+- 生产环境**必须**设置此变量
+- 密钥丢失将导致无法解密已存储的密码
+
+## 表结构
+
+PostgreSQL 实现会创建以下表：
+
+```sql
+CREATE TABLE lattice_database_configs (
+  id VARCHAR(255) NOT NULL,
+  tenant_id VARCHAR(255) NOT NULL,
+  key VARCHAR(255) NOT NULL,
+  name VARCHAR(255),
+  description TEXT,
+  config JSONB NOT NULL,          -- 密码字段加密存储
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  
+  PRIMARY KEY (tenant_id, id),
+  CONSTRAINT uk_lattice_database_configs_tenant_key UNIQUE (tenant_id, key)
+);
+```
+
+## 核心接口
+
+### DatabaseConfigEntry
+
+```typescript
+interface DatabaseConfigEntry {
+  id: string;
+  tenantId: string;
+  key: string;
+  config: DatabaseConfig;  // 密码已解密
+  name?: string;
+  description?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### DatabaseConfigStore
+
+```typescript
+interface DatabaseConfigStore {
+  getAllConfigs(tenantId: string): Promise<DatabaseConfigEntry[]>;
+  getConfigById(tenantId: string, id: string): Promise<DatabaseConfigEntry | null>;
+  getConfigByKey(tenantId: string, key: string): Promise<DatabaseConfigEntry | null>;
+  createConfig(tenantId: string, id: string, data: CreateDatabaseConfigRequest): Promise<DatabaseConfigEntry>;
+  updateConfig(tenantId: string, id: string, updates: Partial<UpdateDatabaseConfigRequest>): Promise<DatabaseConfigEntry | null>;
+  deleteConfig(tenantId: string, id: string): Promise<boolean>;
+  hasConfig(tenantId: string, id: string): Promise<boolean>;
+}
+```
+
+## 加密方案
+
+- **算法**: AES-256-GCM
+- **密钥派生**: PBKDF2 (100,000 次迭代)
+- **存储格式**: `salt:iv:ciphertext:authTag` (Base64 编码)
+- **解密时机**: Store 层 `getConfig*()` 方法返回时自动解密
+
+## 最佳实践
+
+### 1. 生产环境配置
+
+```typescript
+// 使用 PostgreSQL Store
+const store = new PostgreSQLDatabaseConfigStore({
+  poolConfig: process.env.DATABASE_URL,
+  autoMigrate: true,
+});
+
+// 确保设置了加密密钥
+if (!process.env.LATTICE_ENCRYPTION_KEY) {
+  throw new Error('LATTICE_ENCRYPTION_KEY must be set in production');
+}
+```
+
+### 2. 应用启动时加载配置
+
+```typescript
+async function initializeApp() {
+  const store = new PostgreSQLDatabaseConfigStore({ /* ... */ });
+  
+  // 加载所有租户的数据库配置
+  const tenants = ['tenant-1', 'tenant-2'];
+  for (const tenantId of tenants) {
+    await sqlDatabaseManager.loadConfigsFromStore(store, tenantId);
+  }
+}
+```
+
+### 3. 密钥管理
+
+```bash
+# 生成安全密钥 (推荐)
+openssl rand -base64 32
+
+# 或使用 Node.js
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+## 示例代码
+
+查看完整示例：`packages/pg-stores/examples/database-config-store.example.ts`
+
+## 文件结构
+
+```
+packages/
+├── protocols/src/
+│   └── DatabaseConfigStoreProtocol.ts      # 协议接口定义
+├── core/src/
+│   ├── util/encryption.ts                  # 通用加密工具
+│   └── store_lattice/
+│       ├── StoreLatticeManager.ts          # Store 管理器（已添加 database 类型）
+│       └── InMemoryDatabaseConfigStore.ts  # InMemory 实现
+└── pg-stores/src/
+    ├── stores/
+    │   └── PostgreSQLDatabaseConfigStore.ts # PostgreSQL 实现
+    └── migrations/
+        └── database_config_migrations.ts    # 数据库迁移
+```
+
+## 注意事项
+
+1. **密码解密**: Store 层返回的配置中密码已解密，请妥善保管
+2. **多租户**: 所有操作都需要传入 `tenantId` 参数
+3. **唯一性**: `(tenant_id, key)` 组合必须唯一
+4. **加密密钥**: 生产环境务必设置 `LATTICE_ENCRYPTION_KEY`

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { PoolConfig, PoolClient, Pool } from 'pg';
-import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, SkillStore, Skill, CreateSkillRequest } from '@axiom-lattice/protocols';
-export { Assistant, AssistantStore, CreateAssistantRequest, CreateSkillRequest, CreateThreadRequest, ScheduleExecutionType, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, Skill, SkillStore, Thread, ThreadStore } from '@axiom-lattice/protocols';
+import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, SkillStore, Skill, CreateSkillRequest, DatabaseConfigStore, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, WorkspaceStore, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, ProjectStore, Project, CreateProjectRequest, UpdateProjectRequest } from '@axiom-lattice/protocols';
+export { Assistant, AssistantStore, CreateAssistantRequest, CreateDatabaseConfigRequest, CreateProjectRequest, CreateSkillRequest, CreateThreadRequest, CreateWorkspaceRequest, DatabaseConfig, DatabaseConfigEntry, DatabaseConfigStore, DatabaseType, Project, ProjectStore, ScheduleExecutionType, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, Skill, SkillStore, StorageType, Thread, ThreadStore, UpdateDatabaseConfigRequest, UpdateProjectRequest, UpdateWorkspaceRequest, Workspace, WorkspaceStore } from '@axiom-lattice/protocols';
 
 /**
  * PostgreSQL implementation of ThreadStore
@@ -347,6 +347,229 @@ declare class PostgreSQLSkillStore implements SkillStore {
     getSubSkills(parentSkillName: string): Promise<Skill[]>;
 }
 
+/**
+ * PostgreSQL implementation of DatabaseConfigStore
+ */
+
+/**
+ * PostgreSQL DatabaseConfigStore options
+ */
+interface PostgreSQLDatabaseConfigStoreOptions {
+    /**
+     * PostgreSQL connection pool configuration
+     * Can be a connection string or PoolConfig object
+     */
+    poolConfig: string | PoolConfig;
+    /**
+     * Whether to run migrations automatically on initialization
+     * @default true
+     */
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL implementation of DatabaseConfigStore
+ *
+ * Features:
+ * - Multi-tenant isolation via tenant_id
+ * - Automatic password encryption/decryption
+ * - Unique constraint on (tenant_id, key)
+ */
+declare class PostgreSQLDatabaseConfigStore implements DatabaseConfigStore {
+    private pool;
+    private migrationManager;
+    private initialized;
+    private initPromise;
+    constructor(options: PostgreSQLDatabaseConfigStoreOptions);
+    /**
+     * Initialize the store and run migrations
+     * Uses a promise-based lock to prevent concurrent initialization
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get all database configurations for a tenant
+     */
+    getAllConfigs(tenantId: string): Promise<DatabaseConfigEntry[]>;
+    /**
+     * Get all database configurations across all tenants
+     */
+    getAllConfigsWithoutTenant(): Promise<DatabaseConfigEntry[]>;
+    /**
+     * Get database configuration by ID
+     */
+    getConfigById(tenantId: string, id: string): Promise<DatabaseConfigEntry | null>;
+    /**
+     * Get database configuration by business key
+     */
+    getConfigByKey(tenantId: string, key: string): Promise<DatabaseConfigEntry | null>;
+    /**
+     * Create a new database configuration
+     */
+    createConfig(tenantId: string, id: string, data: CreateDatabaseConfigRequest): Promise<DatabaseConfigEntry>;
+    /**
+     * Update an existing database configuration
+     */
+    updateConfig(tenantId: string, id: string, updates: Partial<UpdateDatabaseConfigRequest>): Promise<DatabaseConfigEntry | null>;
+    /**
+     * Delete a database configuration by ID
+     */
+    deleteConfig(tenantId: string, id: string): Promise<boolean>;
+    /**
+     * Check if configuration exists
+     */
+    hasConfig(tenantId: string, id: string): Promise<boolean>;
+    /**
+     * Dispose resources and close the connection pool
+     */
+    dispose(): Promise<void>;
+    /**
+     * Ensure store is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Map database row to DatabaseConfigEntry object
+     * Automatically decrypts password if present
+     */
+    private mapRowToEntry;
+    /**
+     * Encrypt password in config before storing
+     */
+    private encryptPasswordInConfig;
+}
+
+/**
+ * PostgreSQL implementation of WorkspaceStore
+ */
+
+/**
+ * PostgreSQL WorkspaceStore options
+ */
+interface PostgreSQLWorkspaceStoreOptions {
+    /**
+     * PostgreSQL connection pool configuration
+     * Can be a connection string or PoolConfig object
+     */
+    poolConfig: string | PoolConfig;
+    /**
+     * Whether to run migrations automatically on initialization
+     * @default true
+     */
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL implementation of WorkspaceStore
+ */
+declare class PostgreSQLWorkspaceStore implements WorkspaceStore {
+    private pool;
+    private migrationManager;
+    private initialized;
+    private ownsPool;
+    constructor(options: PostgreSQLWorkspaceStoreOptions);
+    /**
+     * Dispose resources and close the connection pool
+     * Should be called when the store is no longer needed
+     */
+    dispose(): Promise<void>;
+    /**
+     * Initialize the store and run migrations
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure store is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Map database row to Workspace object
+     */
+    private mapRowToWorkspace;
+    /**
+     * Get all workspaces for a tenant
+     */
+    getAllWorkspaces(tenantId: string): Promise<Workspace[]>;
+    /**
+     * Get a workspace by ID for a specific tenant
+     */
+    getWorkspaceById(tenantId: string, id: string): Promise<Workspace | null>;
+    /**
+     * Create a new workspace
+     */
+    createWorkspace(tenantId: string, id: string, data: CreateWorkspaceRequest): Promise<Workspace>;
+    /**
+     * Update an existing workspace
+     */
+    updateWorkspace(tenantId: string, id: string, updates: UpdateWorkspaceRequest): Promise<Workspace | null>;
+    /**
+     * Delete a workspace by ID
+     */
+    deleteWorkspace(tenantId: string, id: string): Promise<boolean>;
+}
+
+/**
+ * PostgreSQL implementation of ProjectStore
+ */
+
+/**
+ * PostgreSQL ProjectStore options
+ */
+interface PostgreSQLProjectStoreOptions {
+    /**
+     * PostgreSQL connection pool configuration
+     * Can be a connection string or PoolConfig object
+     */
+    poolConfig: string | PoolConfig;
+    /**
+     * Whether to run migrations automatically on initialization
+     * @default true
+     */
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL implementation of ProjectStore
+ */
+declare class PostgreSQLProjectStore implements ProjectStore {
+    private pool;
+    private migrationManager;
+    private initialized;
+    private ownsPool;
+    constructor(options: PostgreSQLProjectStoreOptions);
+    /**
+     * Dispose resources and close the connection pool
+     * Should be called when the store is no longer needed
+     */
+    dispose(): Promise<void>;
+    /**
+     * Initialize the store and run migrations
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure store is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Map database row to Project object
+     */
+    private mapRowToProject;
+    /**
+     * Get all projects for a specific workspace
+     */
+    getProjectsByWorkspace(tenantId: string, workspaceId: string): Promise<Project[]>;
+    /**
+     * Get a project by ID for a specific tenant
+     */
+    getProjectById(tenantId: string, id: string): Promise<Project | null>;
+    /**
+     * Create a new project
+     */
+    createProject(tenantId: string, workspaceId: string, id: string, data: CreateProjectRequest): Promise<Project>;
+    /**
+     * Update an existing project
+     */
+    updateProject(tenantId: string, id: string, updates: UpdateProjectRequest): Promise<Project | null>;
+    /**
+     * Delete a project by ID
+     */
+    deleteProject(tenantId: string, id: string): Promise<boolean>;
+}
+
 /**
  * Migration system for database schema management
  */
@@ -430,4 +653,31 @@ declare const createScheduledTasksTable: Migration;
  */
 declare const createSkillsTable: Migration;
 
-export { type Migration, MigrationManager, PostgreSQLAssistantStore, type PostgreSQLAssistantStoreOptions, PostgreSQLScheduleStorage, type PostgreSQLScheduleStorageOptions, PostgreSQLSkillStore, type PostgreSQLSkillStoreOptions, PostgreSQLThreadStore, type PostgreSQLThreadStoreOptions, createAssistantsTable, createScheduledTasksTable, createSkillsTable, createThreadsTable };
+/**
+ * Database configuration table migrations
+ */
+
+/**
+ * Initial migration: Create database configs table
+ */
+declare const createDatabaseConfigsTable: Migration;
+
+/**
+ * Workspace table migrations
+ */
+
+/**
+ * Initial migration: Create workspaces table
+ */
+declare const createWorkspacesTable: Migration;
+
+/**
+ * Project table migrations
+ */
+
+/**
+ * Initial migration: Create projects table
+ */
+declare const createProjectsTable: Migration;
+
+export { type Migration, MigrationManager, PostgreSQLAssistantStore, type PostgreSQLAssistantStoreOptions, PostgreSQLDatabaseConfigStore, type PostgreSQLDatabaseConfigStoreOptions, PostgreSQLProjectStore, type PostgreSQLProjectStoreOptions, PostgreSQLScheduleStorage, type PostgreSQLScheduleStorageOptions, PostgreSQLSkillStore, type PostgreSQLSkillStoreOptions, PostgreSQLThreadStore, type PostgreSQLThreadStoreOptions, PostgreSQLWorkspaceStore, type PostgreSQLWorkspaceStoreOptions, createAssistantsTable, createDatabaseConfigsTable, createProjectsTable, createScheduledTasksTable, createSkillsTable, createThreadsTable, createWorkspacesTable };