@rei-standard/amsg-server 2.6.0-next.2 → 2.6.0-next.21

package/dist/index.mjs

@@ -1,8 +1,36 @@
 import {
+  CORS_ALLOW_HEADERS,
+  CORS_ALLOW_METHODS,
+  CRED_ID_MAX_LENGTH,
+  CRED_PUT_BATCH_MAX,
+  CRED_REFS_MAX_ENTRIES,
+  CRED_ROWS_PER_USER_MAX,
+  DEFAULT_CLAIM_LEASE_MS,
+  DEFAULT_HEARTBEAT_LEASE_TTL_MS,
+  DEFAULT_LEASE_HEARTBEAT_MS,
+  DEFAULT_MAX_REQUEST_BODY_BYTES,
+  DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE,
+  DEFAULT_MAX_TOOL_ITERATIONS,
+  DEFAULT_TOTAL_TIMEOUT_MS,
+  DeploymentConfigError,
+  MAX_PUSH_PAYLOAD_BYTES,
+  MAX_TASK_PAYLOAD_BYTES,
+  MIN_SCHEDULE_LEAD_MS,
+  NonRetryableError,
+  PUSH_ENVELOPE_RESERVED_BYTES,
+  SCHEMA_VERSION,
+  WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,
+  WEB_PUSH_MAX_BODY_BYTES,
+  advanceOccurrence,
+  base64UrlToBytes,
+  bytesToBase64Url,
   createCancelMessageHandler,
   createD1Adapter,
+  createGetMessageHandler,
   createGetUserKeyHandler,
+  createLlmCredentialsHandler,
   createMessagesHandler,
+  createPushSubscriptionHandler,
   createScheduleMessageHandler,
   createSingleUserCloudflareWorker,
   createSingleUserServer,
@@ -12,18 +40,39 @@ import {
   decryptPayload,
   deriveUserEncryptionKey,
   encryptForStorage,
+  ensureSchema,
   getHeader,
+  getSchemaVersion,
+  hasChatCredRef,
+  isNonRetryableError,
+  isValidCredId,
   isValidISO8601,
+  isValidTimeZoneId,
   isValidUUID,
   isValidUUIDv4,
   isValidUrl,
+  measurePushPayload,
+  nextFutureOccurrence,
   parseJsonBody,
+  planNextOccurrence,
+  readRequestBody,
+  resolveLlmCredential,
   runScheduledTick,
+  runTask,
+  sanitizeErrorSummary,
+  summarizeErrorCause,
+  supportsLlmCredentialsStore,
+  timingSafeEqualBytes,
+  utf8,
+  utf8Decode,
   validateAvatarUrl,
+  validateCredRefs,
+  validateCredValue,
   validateLlmMessagesArray,
   validateScheduleMessagePayload,
   validateSplitPattern
-} from "./chunk-PVNLB6TF.mjs";
+} from "./chunk-KOJQVOYS.mjs";
+import "./chunk-GN44PST5.mjs";
 
 // src/server/adapters/factory.js
 async function createAdapter(config) {
@@ -39,11 +88,11 @@ async function createAdapter(config) {
   }
   switch (config.driver) {
     case "neon": {
-      const { NeonAdapter } = await import("./neon-CU5N3CSW.mjs");
+      const { NeonAdapter } = await import("./neon-ZIMHALYI.mjs");
       return new NeonAdapter(config.connectionString);
     }
     case "pg": {
-      const { PgAdapter } = await import("./pg-QO6NKTGL.mjs");
+      const { PgAdapter } = await import("./pg-QGC2XHUT.mjs");
       return new PgAdapter(config.connectionString);
     }
     default:
@@ -212,14 +261,6 @@ function createSendNotificationsHandler(ctx) {
 // src/server/tenant/blob-store.js
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypto";
 var inMemoryNamespaces = /* @__PURE__ */ new Map();
-function base64UrlEncode(input) {
-  return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
-}
-function base64UrlDecode(input) {
-  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
-  const padLength = (4 - normalized.length % 4) % 4;
-  return Buffer.from(normalized + "=".repeat(padLength), "base64");
-}
 function getKekBuffer(kek) {
   const value = String(kek || "").trim();
   if (!value) {
@@ -233,16 +274,16 @@ function encryptConfig(config, kekBuffer) {
   const plaintext = Buffer.from(JSON.stringify(config), "utf8");
   const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
   const authTag = cipher.getAuthTag();
-  return `v1.${base64UrlEncode(iv)}.${base64UrlEncode(authTag)}.${base64UrlEncode(ciphertext)}`;
+  return `v1.${bytesToBase64Url(iv)}.${bytesToBase64Url(authTag)}.${bytesToBase64Url(ciphertext)}`;
 }
 function decryptConfig(encrypted, kekBuffer) {
   const parts = String(encrypted || "").split(".");
   if (parts.length !== 4 || parts[0] !== "v1") {
     throw new Error("INVALID_TENANT_CONFIG");
   }
-  const iv = base64UrlDecode(parts[1]);
-  const authTag = base64UrlDecode(parts[2]);
-  const ciphertext = base64UrlDecode(parts[3]);
+  const iv = base64UrlToBytes(parts[1]);
+  const authTag = base64UrlToBytes(parts[2]);
+  const ciphertext = base64UrlToBytes(parts[3]);
   const decipher = createDecipheriv("aes-256-gcm", kekBuffer, iv);
   decipher.setAuthTag(authTag);
   const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
@@ -308,17 +349,9 @@ function createTenantBlobStore(options) {
 import { createHash as createHash2, randomBytes as randomBytes2, randomUUID } from "crypto";
 
 // src/server/tenant/token.js
-import { createHmac, timingSafeEqual } from "crypto";
-function base64UrlEncode2(input) {
-  return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
-}
-function base64UrlDecode2(input) {
-  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
-  const padLength = (4 - normalized.length % 4) % 4;
-  return Buffer.from(normalized + "=".repeat(padLength), "base64");
-}
+import { createHmac } from "crypto";
 function sign(input, secret) {
-  return base64UrlEncode2(createHmac("sha256", secret).update(input).digest());
+  return bytesToBase64Url(createHmac("sha256", secret).update(input).digest());
 }
 function nowEpochSeconds() {
   return Math.floor(Date.now() / 1e3);
@@ -334,8 +367,8 @@ function createTenantToken(params, secret) {
     v: 1
   };
   const header = { alg: "HS256", typ: "JWT" };
-  const encodedHeader = base64UrlEncode2(JSON.stringify(header));
-  const encodedPayload = base64UrlEncode2(JSON.stringify(payload));
+  const encodedHeader = bytesToBase64Url(utf8(JSON.stringify(header)));
+  const encodedPayload = bytesToBase64Url(utf8(JSON.stringify(payload)));
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const signature = sign(signingInput, secret);
   return `${signingInput}.${signature}`;
@@ -351,20 +384,20 @@ function verifyTenantToken(token, secret, options = {}) {
   const [encodedHeader, encodedPayload, receivedSignature] = parts;
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const expectedSignature = sign(signingInput, secret);
-  let receivedBuffer;
-  let expectedBuffer;
+  let receivedBytes;
+  let expectedBytes;
   try {
-    receivedBuffer = base64UrlDecode2(receivedSignature);
-    expectedBuffer = base64UrlDecode2(expectedSignature);
+    receivedBytes = base64UrlToBytes(receivedSignature);
+    expectedBytes = base64UrlToBytes(expectedSignature);
   } catch {
     throw new Error("INVALID_TENANT_AUTH");
   }
-  if (receivedBuffer.length !== expectedBuffer.length || !timingSafeEqual(receivedBuffer, expectedBuffer)) {
+  if (!timingSafeEqualBytes(receivedBytes, expectedBytes)) {
     throw new Error("INVALID_TENANT_AUTH");
   }
   let payload;
   try {
-    payload = JSON.parse(base64UrlDecode2(encodedPayload).toString("utf8"));
+    payload = JSON.parse(utf8Decode(base64UrlToBytes(encodedPayload)));
   } catch {
     throw new Error("INVALID_TENANT_AUTH");
   }
@@ -438,8 +471,17 @@ function createTenantContextManager(options) {
   async function getOrCreateAdapter(dbConfig) {
     const cacheKey = `${dbConfig.driver}:${dbConfig.connectionString}`;
     if (!adapterCache.has(cacheKey)) {
-      const adapter = await adapterFactory(dbConfig);
-      adapterCache.set(cacheKey, adapter);
+      const created = (async () => {
+        const adapter = await adapterFactory(dbConfig);
+        if (typeof adapter.initSchema === "function") {
+          await adapter.initSchema();
+        }
+        return adapter;
+      })().catch((error) => {
+        adapterCache.delete(cacheKey);
+        throw error;
+      });
+      adapterCache.set(cacheKey, created);
     }
     return adapterCache.get(cacheKey);
   }
@@ -567,6 +609,10 @@ async function createReiServer(config) {
       privateKey: vapid.privateKey || ""
     },
     webpush: webpushModule,
+    // 分片传输的限额（与 installReiSW 的 multipart 同一份）。instant 消息在
+    // schedule-message 里就地投递、定时消息走 send-notifications 的 tick，两条路
+    // 都从这个 ctx 展开，所以配一次两边都认。
+    multipart: config.multipart || null,
     tenant: {
       initSecret
     },
@@ -580,11 +626,37 @@ async function createReiServer(config) {
       sendNotifications: createSendNotificationsHandler(ctx),
       updateMessage: createUpdateMessageHandler(ctx),
       cancelMessage: createCancelMessageHandler(ctx),
-      messages: createMessagesHandler(ctx)
+      messages: createMessagesHandler(ctx),
+      getMessage: createGetMessageHandler(ctx),
+      pushSubscription: createPushSubscriptionHandler(ctx),
+      llmCredentials: createLlmCredentialsHandler(ctx)
     }
   };
 }
 export {
+  CORS_ALLOW_HEADERS,
+  CORS_ALLOW_METHODS,
+  CRED_ID_MAX_LENGTH,
+  CRED_PUT_BATCH_MAX,
+  CRED_REFS_MAX_ENTRIES,
+  CRED_ROWS_PER_USER_MAX,
+  DEFAULT_CLAIM_LEASE_MS,
+  DEFAULT_HEARTBEAT_LEASE_TTL_MS,
+  DEFAULT_LEASE_HEARTBEAT_MS,
+  DEFAULT_MAX_REQUEST_BODY_BYTES,
+  DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE,
+  DEFAULT_MAX_TOOL_ITERATIONS,
+  DEFAULT_TOTAL_TIMEOUT_MS,
+  DeploymentConfigError,
+  MAX_PUSH_PAYLOAD_BYTES,
+  MAX_TASK_PAYLOAD_BYTES,
+  MIN_SCHEDULE_LEAD_MS,
+  NonRetryableError,
+  PUSH_ENVELOPE_RESERVED_BYTES,
+  SCHEMA_VERSION,
+  WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,
+  WEB_PUSH_MAX_BODY_BYTES,
+  advanceOccurrence,
   createAdapter,
   createD1Adapter,
   createReiServer,
@@ -596,12 +668,29 @@ export {
   decryptPayload,
   deriveUserEncryptionKey,
   encryptForStorage,
+  ensureSchema,
+  getSchemaVersion,
+  hasChatCredRef,
+  isNonRetryableError,
+  isValidCredId,
   isValidISO8601,
+  isValidTimeZoneId,
   isValidUUID,
   isValidUUIDv4,
   isValidUrl,
+  measurePushPayload,
+  nextFutureOccurrence,
+  planNextOccurrence,
+  readRequestBody,
+  resolveLlmCredential,
   runScheduledTick,
+  runTask,
+  sanitizeErrorSummary,
+  summarizeErrorCause,
+  supportsLlmCredentialsStore,
   validateAvatarUrl,
+  validateCredRefs,
+  validateCredValue,
   validateLlmMessagesArray,
   validateScheduleMessagePayload,
   validateSplitPattern,

package/dist/lib/agentic-fire.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 默认 messageId / sessionId 里掺的名义触发时刻后缀（`@<epoch-ms>`）。
+ *
+ * 循环任务跨天复用同一条任务行，id 只用 task.id 的话，离线设备一次性收到
+ * 多天积压的推送（push TTL 有四周）时会在 service worker 端互相去重、在
+ * 收件箱按 messageId 覆盖，几天的消息只剩一条。掺入名义触发时刻后每个
+ * occurrence 一套 id；同一 occurrence 的重试仍是同一套——重投已送达的段
+ * 会被去重，这正是想要的。行上没有可解析的 next_send_at（比如直接喂进来
+ * 的内存任务对象）时返回 ''，等价于旧格式。
+ *
+ * @param {{ next_send_at?: string }} task
+ * @returns {string}
+ */
+export function occurrenceSuffix(task: {
+    next_send_at?: string;
+}): string;
+/**
+ * 本次触发的名义时刻（epoch 毫秒）。行上没有可解析的 next_send_at（比如直接
+ * 喂进来的内存任务对象）时返回 null。
+ *
+ * @param {{ next_send_at?: string }} task
+ * @returns {number|null}
+ */
+export function occurrenceMsOf(task: {
+    next_send_at?: string;
+}): number | null;
+/**
+ * Does this task need the LLM at fire time? Fixed text never does, so it
+ * always stays on the legacy path regardless of hooks.
+ *
+ * @param {Object} decryptedPayload
+ * @returns {boolean}
+ */
+export function taskNeedsLlm(decryptedPayload: any): boolean;
+/**
+ * Frozen, credential-free view of the task for hook authors.
+ *
+ * nextSendAt 是这条任务原本的触发时刻。run-tick 领取任务时写的是 lease_until，
+ * next_send_at 那一列不动，所以这里给出去的和库里的是同一个值——宿主拿它当
+ * 时间锚点（窗口判断、缓存键）时对得上。
+ *
+ * 导出给 run-tick 用：`serializeBy` 要从任务内容里取分组 key，拿到的就该是
+ * 这一份（凭据剔掉、和 onBeforeFire 的 ctx.task 同一个形状），宿主不用为了
+ * 分组再学第二套字段。
+ */
+export function buildHookTask(task: any, decryptedPayload: any): Readonly<{
+    id: any;
+    uuid: any;
+    nextSendAt: any;
+    retryCount: any;
+}>;
+/**
+ * Try the hook-driven fire path for one task.
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').TaskRow} args.task
+ * @param {Object} args.decryptedPayload - decrypted task payload (has credentials; they stop here)
+ * @param {string} args.userKey - per-user storage key (for readState decryption)
+ * @param {Object} args.ctx - processor ctx ({ db, webpush, vapid, hooks, maxToolIterations, totalTimeoutMs, maxScheduledTasksPerFire })
+ * @returns {Promise<{ handled: false } | { handled: true, result: { success: true, messagesSent: number, status: 'finished'|'skipped', iterations: number } }>}
+ *   `handled: false` → caller falls back to the legacy frozen-prompt path
+ *   (onBeforeFire returned null).
+ *   `onBeforeFire` may also return `{ skip: true }` to complete the fire
+ *   before the first LLM call → `status: 'skipped', iterations: 0`, same
+ *   success handling as the post-LLM skip-push path.
+ *   Failures (timeout / loop exceeded / config errors) throw — the caller's
+ *   existing error handling turns them into task retry/failure.
+ *
+ *   收尾回执：onBeforeFire 一旦被调用，上面每一种结局（含抛错）都会调一次
+ *   `ctx.onFireSettled`，见 notifyFireSettled。
+ */
+export function runAgenticFire({ task, decryptedPayload, userKey, ctx }: {
+    task: import("../adapters/interface.js").TaskRow;
+    decryptedPayload: any;
+    userKey: string;
+    ctx: any;
+}): Promise<{
+    handled: false;
+} | {
+    handled: true;
+    result: {
+        success: true;
+        messagesSent: number;
+        status: "finished" | "skipped";
+        iterations: number;
+    };
+}>;
+export const DEFAULT_MAX_TOOL_ITERATIONS: 5;
+export const DEFAULT_TOTAL_TIMEOUT_MS: 240000;
+export const DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE: 2;
+export const MIN_SCHEDULE_LEAD_MS: 60000;
+/**
+ * 把任务的调度身份投影进一条 push。
+ *
+ * 客户端收到推送时要知道「这是哪条任务、哪一次触发、它还会不会再来」——不然
+ * 角色在 fire 里自排的任务客户端从没见过，只能靠猜。这三个字段由库统一补，
+ * 宿主不用再往 metadata 里抄一遍（抄漏一个就够坏事了）。
+ *
+ * 放在 push 顶层，和 messageId / sessionId / timestamp / messageIndex /
+ * totalMessages 一样，不塞进 metadata：metadata 是宿主自己的地盘，库往里写
+ * 会和宿主的键打架。
+ *
+ * @param {Object} push - 待发送的 push（原地补字段）
+ * @param {Object} task - 数据库任务行
+ * @param {Object} decryptedPayload
+ * @param {number|null} occurrenceMs
+ */
+export function stampTaskIdentity(push: any, task: any, decryptedPayload: any, occurrenceMs: number | null): void;

package/dist/lib/client-state-store.d.ts

@@ -0,0 +1,80 @@
+/** value 的 UTF-8 字节数——各处限额判断用的都是这个口径。 */
+export function stateValueBytes(value: any): number;
+/**
+ * 把 `clientStateTtl` 配置（`{ 命名空间: 天数 }`）算成清理指令。
+ *
+ * 一个命名空间出两条：它自己，加上它的切片命名空间（大值分块存在那儿，见
+ * lib/state-chunks.js）。两边共用同一个截止时刻——同一次写入的根行和切片行
+ * `updated_at` 相同，所以要么一起留、要么一起走，不会留下半截数据。
+ *
+ * 天数不是正数的条目跳过并告警（每个键只说一次）：配错了就该看得见，但不能
+ * 让 cron 每分钟刷一条。
+ *
+ * @param {Record<string, number>|null|undefined} ttl - `{ 命名空间: 天数 }`；天数可带小数
+ * @param {number} now - 当前时刻（epoch 毫秒）
+ * @returns {Array<{ namespace: string, updatedBefore: number }>}
+ *   `updatedBefore` 是 epoch 毫秒：这个命名空间下 `updated_at` 早于它的条目该清掉。
+ */
+export function planClientStateCleanup(ttl: Record<string, number> | null | undefined, now: number): Array<{
+    namespace: string;
+    updatedBefore: number;
+}>;
+/**
+ * 把逻辑条目写进 client_state。条目要么是覆盖写（`value` 是字符串），要么是
+ * 删除（`value` 为 `null`）：
+ *
+ *   - 覆盖写：≤ 200KB 单行存；超过的切片跨行存（见 lib/state-chunks.js）。
+ *     同一批里先清掉这个 key 上次写入留下的切片行，所以覆盖成更小的值、或者
+ *     块数变少，都不会留下尾巴。
+ *   - 删除：根行按精确 key 删，切片行按 key 前缀删，一个 key 的数据清干净。
+ *
+ * 两者都受同一套 last-write-wins 约束：`updatedAt` 比库里已有值旧的写入
+ * （或删除）不生效，陈旧批次盖不掉新数据。
+ *
+ * 条件写护栏：条目可带可选的 `version`（毫秒时间戳或单调递增整数）。带了它，
+ * 比较用的就是这个值而不是 `updatedAt`——同一个 key 有多个写入方时（例如
+ * fire_pack 由常规 flush 和 instant-chat 两条路径写），谁的**内容**新谁赢，
+ * 而不是谁的请求后到谁赢：慢网下晚到的旧包带着旧 `version`，盖不掉先到的新
+ * 包。护栏值落在行的 updated_at 列上（client_state 的比较列本来就是它），
+ * 没带 `version` 的写入照旧按 `updatedAt` 比。
+ *
+ * 条目本身的合法性（namespace / key 字符、value 大小）由调用方先校验好：
+ * HTTP handler 逐条拒绝并把原因回给客户端，`writeState()` 直接抛错给 hook。
+ *
+ * @param {Object} args
+ * @param {{ upsertClientState: Function }} args.db
+ * @param {string} args.userId
+ * @param {CryptoKey|string} args.userKey - 该用户的存储密钥（value 用它加密）
+ * @param {Array<{ namespace: string, key: string, value: string|null, updatedAt: number, version?: number }>} args.entries
+ *   `version`（可选）：条件写护栏值，见文件头。带了它，这条的 last-write-wins
+ *   比较用它（写进行的 updated_at 列）；没带照旧用 `updatedAt`。
+ * @returns {Promise<{ upserted: number, skipped: number, deleted: number, skippedEntries: Array<{ namespace: string, key: string }> }>}
+ *   `upserted` / `skipped` 按逻辑条目计（切片行不计）；`deleted` 是请求删除的
+ *   key 数，不代表这些 key 原本一定存在。`skippedEntries` 逐条列出被
+ *   last-write-wins 拦下的 key（适配器不回 outcomes 时为空数组——分不清是哪条）。
+ */
+export function writeClientStateEntries({ db, userId, userKey, entries }: {
+    db: {
+        upsertClientState: Function;
+    };
+    userId: string;
+    userKey: CryptoKey | string;
+    entries: Array<{
+        namespace: string;
+        key: string;
+        value: string | null;
+        updatedAt: number;
+        version?: number;
+    }>;
+}): Promise<{
+    upserted: number;
+    skipped: number;
+    deleted: number;
+    skippedEntries: Array<{
+        namespace: string;
+        key: string;
+    }>;
+}>;
+export const MAX_STATE_ENTRIES_PER_BATCH: 200;
+export const MAX_NAMESPACE_CHARS: 128;
+export const MAX_KEY_CHARS: 256;

package/dist/lib/constant-time.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Portable constant-time string comparison.
+ *
+ * Runs identically on Node (tests) and Cloudflare Workers (prod). We avoid
+ * both node:crypto's timingSafeEqual (undefined on Workers historically) and
+ * crypto.subtle.timingSafeEqual (absent on Node). Instead we HMAC-SHA256 both
+ * inputs under one fresh random key, then compare the two digests. Because the
+ * key is random per call, an attacker can't precompute or replay a stable
+ * timing oracle; digests are a fixed 32 bytes, so the XOR-accumulate compare
+ * runs the same number of steps regardless of input length, with no early-out.
+ *
+ * globalThis.crypto (Web Crypto) is available on Node >= 20 and on Workers.
+ */
+export function constantTimeEqual(a: any, b: any): Promise<boolean>;

package/dist/lib/db-errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Database error helpers.
+ */
+/**
+ * Check whether an error is caused by a unique-constraint violation.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isUniqueViolation(error: unknown): boolean;

package/dist/lib/encryption.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Derive a user-specific encryption key from the master key.
+ *
+ * @param {string} userId    - Unique user identifier.
+ * @param {string} masterKey - 64-char hex master key.
+ * @returns {Promise<string>} 64-char hex key.
+ */
+export function deriveUserEncryptionKey(userId: string, masterKey: string): Promise<string>;
+/**
+ * Decrypt a client-encrypted request body (AES-256-GCM, base64 encoded).
+ *
+ * @param {{ iv: string, authTag: string, encryptedData: string }} encryptedPayload
+ * @param {string} encryptionKey - 64-char hex key.
+ * @returns {Promise<Object>} Decrypted JSON object.
+ */
+export function decryptPayload(encryptedPayload: {
+    iv: string;
+    authTag: string;
+    encryptedData: string;
+}, encryptionKey: string): Promise<any>;
+/**
+ * Encrypt a JSON payload for API transfer (AES-256-GCM, base64 encoded).
+ *
+ * @param {string|Object} payload
+ * @param {string} encryptionKey - 64-char hex key.
+ * @returns {Promise<{ iv: string, authTag: string, encryptedData: string }>}
+ */
+export function encryptPayload(payload: string | any, encryptionKey: string): Promise<{
+    iv: string;
+    authTag: string;
+    encryptedData: string;
+}>;
+/**
+ * Encrypt data for database storage (hex encoded, colon-separated).
+ *
+ * @param {string} text          - Plaintext string.
+ * @param {string} encryptionKey - 64-char hex key.
+ * @returns {Promise<string>} Format: iv:authTag:encryptedData
+ */
+export function encryptForStorage(text: string, encryptionKey: string): Promise<string>;
+/**
+ * Decrypt data from database storage format.
+ *
+ * @param {string} encryptedText - Format: iv:authTag:encryptedData
+ * @param {string} encryptionKey - 64-char hex key.
+ * @returns {Promise<string>} Plaintext string.
+ */
+export function decryptFromStorage(encryptedText: string, encryptionKey: string): Promise<string>;