@rei-standard/amsg-server 2.0.1 → 2.1.1

package/README.md

@@ -50,6 +50,10 @@ const rei = await createReiServer({
 // GET  /api/v1/messages             -> rei.handlers.messages.GET
 ```
 
+## 关于 `messageType: 'instant'`
+
+> **Note**：新代码的 instant 消息请用 [@rei-standard/amsg-instant](../instant/README.md)，跳过本端点的"建任务 → 处理 → 删任务" DB 来回。本端点的 `instant` 分支为兼容保留，行为不变、不会有运行时警告。
+
 ## AI 接口 `apiUrl` 约束
 
 当 `messageType` 为 `prompted` / `auto`，或 `instant` 使用 AI 配置时：

package/dist/index.cjs

@@ -100,7 +100,7 @@ function validateScheduleMessagePayload(payload) {
   if (payload.uuid && !isValidUUID(payload.uuid)) {
     return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["uuid (invalid UUID format)"] } };
   }
-  if (payload.messageSubtype && !["chat", "forum", "moment"].includes(payload.messageSubtype)) {
+  if (payload.messageSubtype !== void 0 && payload.messageSubtype !== null && typeof payload.messageSubtype !== "string") {
     return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["messageSubtype"] } };
   }
   return { valid: true };
@@ -554,7 +554,7 @@ function buildAiRequestBody(payload) {
 function normalizeAiApiUrl(apiUrl) {
   if (typeof apiUrl !== "string" || !apiUrl.trim()) {
     throw new Error(
-      "Invalid apiUrl: apiUrl is required. Please provide a full chat endpoint URL (for example: https://api.openai.com/v1/chat/completions)."
+      "Invalid apiUrl: apiUrl is required. Please provide a chat endpoint URL (for example: https://api.openai.com or https://api.openai.com/v1/chat/completions)."
     );
   }
   const trimmedApiUrl = apiUrl.trim();
@@ -563,10 +563,17 @@ function normalizeAiApiUrl(apiUrl) {
     parsedUrl = new URL(trimmedApiUrl);
   } catch (e3) {
     throw new Error(
-      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL that points to a full chat endpoint.`
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
     );
   }
-  parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, "") || "/";
+  let path = parsedUrl.pathname.replace(/\/+$/, "") || "/";
+  if (/\/chat\/completions$/.test(path)) {
+  } else if (path === "/") {
+    path = "/v1/chat/completions";
+  } else if (/\/v\d+$/.test(path)) {
+    path = `${path}/chat/completions`;
+  }
+  parsedUrl.pathname = path;
   return parsedUrl.toString();
 }
 
@@ -1235,15 +1242,21 @@ function verifyTenantToken(token, secret, options = {}) {
   const [encodedHeader, encodedPayload, receivedSignature] = parts;
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const expectedSignature = sign(signingInput, secret);
-  const receivedBuffer = Buffer.from(receivedSignature);
-  const expectedBuffer = Buffer.from(expectedSignature);
+  let receivedBuffer;
+  let expectedBuffer;
+  try {
+    receivedBuffer = base64UrlDecode2(receivedSignature);
+    expectedBuffer = base64UrlDecode2(expectedSignature);
+  } catch (e4) {
+    throw new Error("INVALID_TENANT_AUTH");
+  }
   if (receivedBuffer.length !== expectedBuffer.length || !_crypto.timingSafeEqual.call(void 0, receivedBuffer, expectedBuffer)) {
     throw new Error("INVALID_TENANT_AUTH");
   }
   let payload;
   try {
     payload = JSON.parse(base64UrlDecode2(encodedPayload).toString("utf8"));
-  } catch (e4) {
+  } catch (e5) {
     throw new Error("INVALID_TENANT_AUTH");
   }
   if (!payload || typeof payload !== "object" || payload.v !== 1) {
@@ -1300,7 +1313,7 @@ function parseTokenFromUrl(url) {
   try {
     const parsed = new URL(url, "https://dummy.local");
     return String(parsed.searchParams.get("token") || "").trim();
-  } catch (e5) {
+  } catch (e6) {
     return "";
   }
 }

package/dist/index.d.cts

@@ -174,7 +174,14 @@ function validateScheduleMessagePayload(payload) {
   if (payload.uuid && !isValidUUID(payload.uuid)) {
     return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['uuid (invalid UUID format)'] } };
   }
-  if (payload.messageSubtype && !['chat', 'forum', 'moment'].includes(payload.messageSubtype)) {
+  // messageSubtype is a free-form string tag forwarded to SW-side push payload
+  // for classification. Only the type is enforced; the taxonomy is the
+  // consumer's call (previously the enum was chat/forum/moment).
+  if (
+    payload.messageSubtype !== undefined &&
+    payload.messageSubtype !== null &&
+    typeof payload.messageSubtype !== 'string'
+  ) {
     return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['messageSubtype'] } };
   }
 
@@ -899,12 +906,27 @@ function buildAiRequestBody(payload) {
 }
 
 /**
- * Normalize AI API URL with minimal, non-breaking rules:
- * - trim whitespace
- * - remove redundant trailing slashes from pathname
- * - keep query string untouched
+ * Normalize AI API URL for OpenAI-compatible chat endpoints.
+ *
+ * **Keep in sync** with `@rei-standard/amsg-instant`'s
+ * `src/message-processor.js` `normalizeAiApiUrl` — same rules, same
+ * tests. The two packages share this logic but each carry their own copy
+ * to avoid an architectural dependency (server should not depend on the
+ * stateless worker package).
  *
- * Note: This function does NOT auto-append /v1 or /chat/completions.
+ * Rules (idempotent — running it twice equals running it once):
+ *   - Already ends with `/chat/completions`             → leave as-is.
+ *   - Bare host (no path or just `/`)                   → append `/v1/chat/completions`.
+ *   - Path ends with a version segment like `/v1`,
+ *     `/v2`, … (with or without trailing slash)         → append only
+ *     `/chat/completions`; never doubles `/v1` for
+ *     callers who already include it.
+ *   - Anything else (custom path that doesn't match the
+ *     OpenAI shape, e.g. `/v1/messages` for
+ *     Anthropic-style proxies)                          → leave as-is. The caller
+ *     knows their own routing.
+ *
+ * Query string is preserved verbatim.
  *
  * @param {string} apiUrl
  * @returns {string}
@@ -913,7 +935,8 @@ function normalizeAiApiUrl(apiUrl) {
   if (typeof apiUrl !== 'string' || !apiUrl.trim()) {
     throw new Error(
       'Invalid apiUrl: apiUrl is required. ' +
-      'Please provide a full chat endpoint URL (for example: https://api.openai.com/v1/chat/completions).'
+      'Please provide a chat endpoint URL ' +
+      '(for example: https://api.openai.com or https://api.openai.com/v1/chat/completions).'
     );
   }
 
@@ -924,12 +947,23 @@ function normalizeAiApiUrl(apiUrl) {
     parsedUrl = new URL(trimmedApiUrl);
   } catch {
     throw new Error(
-      `Invalid apiUrl: "${apiUrl}". ` +
-      'Please provide a valid absolute URL that points to a full chat endpoint.'
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
     );
   }
 
-  parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+  let path = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+
+  if (/\/chat\/completions$/.test(path)) ; else if (path === '/') {
+    // Bare host → assume OpenAI shape.
+    path = '/v1/chat/completions';
+  } else if (/\/v\d+$/.test(path)) {
+    // Path ends in `/v1`, `/v2`, … — caller already versioned the URL.
+    // Append only `/chat/completions`; never re-add `/v1`.
+    path = `${path}/chat/completions`;
+  }
+  // Any other custom path is left untouched on purpose.
+
+  parsedUrl.pathname = path;
   return parsedUrl.toString();
 }
 
@@ -1026,6 +1060,14 @@ function createScheduleMessageHandler(ctx) {
 
     const encryptedPayload = encryptForStorage(JSON.stringify(fullTaskData), userKey);
 
+    /**
+     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
+     *   This branch is kept for backward compatibility and the existing behavior
+     *   (create task → process → delete) is unchanged. The dedicated amsg-instant
+     *   package is stateless (no DB roundtrip), deployable to Cloudflare Workers,
+     *   and locks the encryption + push-payload contract behind a single version.
+     *   See packages/rei-standard-amsg/instant/README.md.
+     */
     // Instant type: check VAPID before creating the task to avoid orphaned rows
     if (payload.messageType === 'instant') {
       if (!ctx.vapid.email || !ctx.vapid.publicKey || !ctx.vapid.privateKey) {
@@ -1079,6 +1121,13 @@ function createScheduleMessageHandler(ctx) {
       return { status: 500, body: { success: false, error: { code: 'TASK_CREATE_FAILED', message: '创建任务失败' } } };
     }
 
+    /**
+     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
+     *   The "create-task → process-by-uuid → delete-task" sequence below is
+     *   preserved verbatim so existing clients keep working. New integrations
+     *   should call the dedicated amsg-instant endpoint instead — it skips this
+     *   DB round-trip entirely. See packages/rei-standard-amsg/instant/README.md.
+     */
     // Instant type: send immediately
     if (payload.messageType === 'instant') {
       try {
@@ -1792,8 +1841,17 @@ function verifyTenantToken(token, secret, options = {}) {
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const expectedSignature = sign(signingInput, secret);
 
-  const receivedBuffer = Buffer.from(receivedSignature);
-  const expectedBuffer = Buffer.from(expectedSignature);
+  // Compare raw HMAC bytes (decoded from base64url) rather than the
+  // encoded character bytes — semantically clearer and avoids the
+  // implicit-UTF-8 default of Buffer.from(string).
+  let receivedBuffer;
+  let expectedBuffer;
+  try {
+    receivedBuffer = base64UrlDecode(receivedSignature);
+    expectedBuffer = base64UrlDecode(expectedSignature);
+  } catch {
+    throw new Error('INVALID_TENANT_AUTH');
+  }
   if (
     receivedBuffer.length !== expectedBuffer.length ||
     !timingSafeEqual(receivedBuffer, expectedBuffer)

package/dist/index.d.ts

@@ -174,7 +174,14 @@ function validateScheduleMessagePayload(payload) {
   if (payload.uuid && !isValidUUID(payload.uuid)) {
     return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['uuid (invalid UUID format)'] } };
   }
-  if (payload.messageSubtype && !['chat', 'forum', 'moment'].includes(payload.messageSubtype)) {
+  // messageSubtype is a free-form string tag forwarded to SW-side push payload
+  // for classification. Only the type is enforced; the taxonomy is the
+  // consumer's call (previously the enum was chat/forum/moment).
+  if (
+    payload.messageSubtype !== undefined &&
+    payload.messageSubtype !== null &&
+    typeof payload.messageSubtype !== 'string'
+  ) {
     return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['messageSubtype'] } };
   }
 
@@ -899,12 +906,27 @@ function buildAiRequestBody(payload) {
 }
 
 /**
- * Normalize AI API URL with minimal, non-breaking rules:
- * - trim whitespace
- * - remove redundant trailing slashes from pathname
- * - keep query string untouched
+ * Normalize AI API URL for OpenAI-compatible chat endpoints.
+ *
+ * **Keep in sync** with `@rei-standard/amsg-instant`'s
+ * `src/message-processor.js` `normalizeAiApiUrl` — same rules, same
+ * tests. The two packages share this logic but each carry their own copy
+ * to avoid an architectural dependency (server should not depend on the
+ * stateless worker package).
  *
- * Note: This function does NOT auto-append /v1 or /chat/completions.
+ * Rules (idempotent — running it twice equals running it once):
+ *   - Already ends with `/chat/completions`             → leave as-is.
+ *   - Bare host (no path or just `/`)                   → append `/v1/chat/completions`.
+ *   - Path ends with a version segment like `/v1`,
+ *     `/v2`, … (with or without trailing slash)         → append only
+ *     `/chat/completions`; never doubles `/v1` for
+ *     callers who already include it.
+ *   - Anything else (custom path that doesn't match the
+ *     OpenAI shape, e.g. `/v1/messages` for
+ *     Anthropic-style proxies)                          → leave as-is. The caller
+ *     knows their own routing.
+ *
+ * Query string is preserved verbatim.
  *
  * @param {string} apiUrl
  * @returns {string}
@@ -913,7 +935,8 @@ function normalizeAiApiUrl(apiUrl) {
   if (typeof apiUrl !== 'string' || !apiUrl.trim()) {
     throw new Error(
       'Invalid apiUrl: apiUrl is required. ' +
-      'Please provide a full chat endpoint URL (for example: https://api.openai.com/v1/chat/completions).'
+      'Please provide a chat endpoint URL ' +
+      '(for example: https://api.openai.com or https://api.openai.com/v1/chat/completions).'
     );
   }
 
@@ -924,12 +947,23 @@ function normalizeAiApiUrl(apiUrl) {
     parsedUrl = new URL(trimmedApiUrl);
   } catch {
     throw new Error(
-      `Invalid apiUrl: "${apiUrl}". ` +
-      'Please provide a valid absolute URL that points to a full chat endpoint.'
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
     );
   }
 
-  parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+  let path = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+
+  if (/\/chat\/completions$/.test(path)) ; else if (path === '/') {
+    // Bare host → assume OpenAI shape.
+    path = '/v1/chat/completions';
+  } else if (/\/v\d+$/.test(path)) {
+    // Path ends in `/v1`, `/v2`, … — caller already versioned the URL.
+    // Append only `/chat/completions`; never re-add `/v1`.
+    path = `${path}/chat/completions`;
+  }
+  // Any other custom path is left untouched on purpose.
+
+  parsedUrl.pathname = path;
   return parsedUrl.toString();
 }
 
@@ -1026,6 +1060,14 @@ function createScheduleMessageHandler(ctx) {
 
     const encryptedPayload = encryptForStorage(JSON.stringify(fullTaskData), userKey);
 
+    /**
+     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
+     *   This branch is kept for backward compatibility and the existing behavior
+     *   (create task → process → delete) is unchanged. The dedicated amsg-instant
+     *   package is stateless (no DB roundtrip), deployable to Cloudflare Workers,
+     *   and locks the encryption + push-payload contract behind a single version.
+     *   See packages/rei-standard-amsg/instant/README.md.
+     */
     // Instant type: check VAPID before creating the task to avoid orphaned rows
     if (payload.messageType === 'instant') {
       if (!ctx.vapid.email || !ctx.vapid.publicKey || !ctx.vapid.privateKey) {
@@ -1079,6 +1121,13 @@ function createScheduleMessageHandler(ctx) {
       return { status: 500, body: { success: false, error: { code: 'TASK_CREATE_FAILED', message: '创建任务失败' } } };
     }
 
+    /**
+     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
+     *   The "create-task → process-by-uuid → delete-task" sequence below is
+     *   preserved verbatim so existing clients keep working. New integrations
+     *   should call the dedicated amsg-instant endpoint instead — it skips this
+     *   DB round-trip entirely. See packages/rei-standard-amsg/instant/README.md.
+     */
     // Instant type: send immediately
     if (payload.messageType === 'instant') {
       try {
@@ -1792,8 +1841,17 @@ function verifyTenantToken(token, secret, options = {}) {
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const expectedSignature = sign(signingInput, secret);
 
-  const receivedBuffer = Buffer.from(receivedSignature);
-  const expectedBuffer = Buffer.from(expectedSignature);
+  // Compare raw HMAC bytes (decoded from base64url) rather than the
+  // encoded character bytes — semantically clearer and avoids the
+  // implicit-UTF-8 default of Buffer.from(string).
+  let receivedBuffer;
+  let expectedBuffer;
+  try {
+    receivedBuffer = base64UrlDecode(receivedSignature);
+    expectedBuffer = base64UrlDecode(expectedSignature);
+  } catch {
+    throw new Error('INVALID_TENANT_AUTH');
+  }
   if (
     receivedBuffer.length !== expectedBuffer.length ||
     !timingSafeEqual(receivedBuffer, expectedBuffer)

package/dist/index.mjs

@@ -100,7 +100,7 @@ function validateScheduleMessagePayload(payload) {
   if (payload.uuid && !isValidUUID(payload.uuid)) {
     return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["uuid (invalid UUID format)"] } };
   }
-  if (payload.messageSubtype && !["chat", "forum", "moment"].includes(payload.messageSubtype)) {
+  if (payload.messageSubtype !== void 0 && payload.messageSubtype !== null && typeof payload.messageSubtype !== "string") {
     return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["messageSubtype"] } };
   }
   return { valid: true };
@@ -554,7 +554,7 @@ function buildAiRequestBody(payload) {
 function normalizeAiApiUrl(apiUrl) {
   if (typeof apiUrl !== "string" || !apiUrl.trim()) {
     throw new Error(
-      "Invalid apiUrl: apiUrl is required. Please provide a full chat endpoint URL (for example: https://api.openai.com/v1/chat/completions)."
+      "Invalid apiUrl: apiUrl is required. Please provide a chat endpoint URL (for example: https://api.openai.com or https://api.openai.com/v1/chat/completions)."
     );
   }
   const trimmedApiUrl = apiUrl.trim();
@@ -563,10 +563,17 @@ function normalizeAiApiUrl(apiUrl) {
     parsedUrl = new URL(trimmedApiUrl);
   } catch {
     throw new Error(
-      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL that points to a full chat endpoint.`
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
     );
   }
-  parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, "") || "/";
+  let path = parsedUrl.pathname.replace(/\/+$/, "") || "/";
+  if (/\/chat\/completions$/.test(path)) {
+  } else if (path === "/") {
+    path = "/v1/chat/completions";
+  } else if (/\/v\d+$/.test(path)) {
+    path = `${path}/chat/completions`;
+  }
+  parsedUrl.pathname = path;
   return parsedUrl.toString();
 }
 
@@ -1235,8 +1242,14 @@ function verifyTenantToken(token, secret, options = {}) {
   const [encodedHeader, encodedPayload, receivedSignature] = parts;
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const expectedSignature = sign(signingInput, secret);
-  const receivedBuffer = Buffer.from(receivedSignature);
-  const expectedBuffer = Buffer.from(expectedSignature);
+  let receivedBuffer;
+  let expectedBuffer;
+  try {
+    receivedBuffer = base64UrlDecode2(receivedSignature);
+    expectedBuffer = base64UrlDecode2(expectedSignature);
+  } catch {
+    throw new Error("INVALID_TENANT_AUTH");
+  }
   if (receivedBuffer.length !== expectedBuffer.length || !timingSafeEqual(receivedBuffer, expectedBuffer)) {
     throw new Error("INVALID_TENANT_AUTH");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-server",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "ReiStandard Active Messaging server SDK with pluggable database adapters",
   "repository": {
     "type": "git",