@kispi/chat 0.1.2 → 0.2.1

package/dist/server/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var server_exports = {};
 __export(server_exports, {
   DefaultTokenTtlSeconds: () => DefaultTokenTtlSeconds,
+  GuestIdPrefix: () => GuestIdPrefix,
   MaxTokenTtlSeconds: () => MaxTokenTtlSeconds,
   SignatureToleranceMs: () => SignatureToleranceMs,
   createChatServer: () => createChatServer
@@ -34,6 +35,8 @@ var ChatError = class extends Error {
   retryAfterMs;
   /** The consumer's own code, when a before_publish hook denied this. */
   appCode;
+  /** The HTTP status, when this came from a REST call. */
+  status;
   constructor(code, message, extra) {
     super(message);
     this.name = "ChatError";
@@ -90,12 +93,15 @@ var ServerRest = class {
   }
 };
 
+// src/server/guest.ts
+var import_node_crypto2 = require("crypto");
+
 // src/server/jwt.ts
 var import_node_crypto = require("crypto");
 function signHS256(header, claims, secret) {
   const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}`;
-  const mac = (0, import_node_crypto.createHmac)("sha256", secret).update(signingInput).digest();
-  return `${signingInput}.${mac.toString("base64url")}`;
+  const mac2 = (0, import_node_crypto.createHmac)("sha256", secret).update(signingInput).digest();
+  return `${signingInput}.${mac2.toString("base64url")}`;
 }
 function macMatches(expected, given) {
   return expected.length === given.length && (0, import_node_crypto.timingSafeEqual)(expected, given);
@@ -104,6 +110,32 @@ function b64url(s) {
   return Buffer.from(s, "utf8").toString("base64url");
 }
 
+// src/server/guest.ts
+var GuestIdPrefix = "g_";
+var CredentialVersion = "g1";
+var MacLabel = "kispi-chat/guest/v1\n";
+var MinGuestSecretLength = 32;
+function newGuestId() {
+  return `${GuestIdPrefix}${(0, import_node_crypto2.randomBytes)(16).toString("base64url")}`;
+}
+function signGuestCredential(secret, userId) {
+  return `${CredentialVersion}.${userId}.${mac(secret, userId).toString("base64url")}`;
+}
+function verifyGuestCredential(secrets, credential) {
+  const parts = credential.split(".");
+  if (parts.length !== 3) return void 0;
+  const [version, userId, given] = parts;
+  if (version !== CredentialVersion || !userId.startsWith(GuestIdPrefix)) return void 0;
+  const givenMac = Buffer.from(given, "base64url");
+  for (const [i, secret] of secrets.entries()) {
+    if (macMatches(mac(secret, userId), givenMac)) return { userId, secretIndex: i };
+  }
+  return void 0;
+}
+function mac(secret, userId) {
+  return (0, import_node_crypto2.createHmac)("sha256", secret).update(MacLabel + userId).digest();
+}
+
 // src/server/token.ts
 var MaxTokenTtlSeconds = 24 * 60 * 60;
 var DefaultTokenTtlSeconds = 60 * 60;
@@ -135,7 +167,7 @@ function tokenClaims(input, now) {
 }
 
 // src/server/webhooks.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 var SignatureToleranceMs = 5 * 60 * 1e3;
 var EventBeforePublish = "before_publish";
 function verifyWebhook(secret, headers, rawBody, options = {}) {
@@ -173,7 +205,7 @@ function verifyWebhook(secret, headers, rawBody, options = {}) {
   if (age > tolerance) {
     throw new Error(`webhook: signature is ${Math.round(age / 1e3)}s old, tolerance is ${tolerance / 1e3}s`);
   }
-  const expected = (0, import_node_crypto2.createHmac)("sha256", secret).update(`${timestamp}
+  const expected = (0, import_node_crypto3.createHmac)("sha256", secret).update(`${timestamp}
 ${event}
 ${delivery}
 ${rawBody}`).digest();
@@ -207,13 +239,29 @@ function createChatServer(options) {
     throw new TypeError("keyId is required: it becomes the token's kid, which tells the server which key signed it");
   }
   const rest = new ServerRest(options.url, options.secretKey, options.fetch ?? globalThis.fetch.bind(globalThis));
+  const guestSecrets = options.guestSecret === void 0 ? [] : typeof options.guestSecret === "string" ? [options.guestSecret] : options.guestSecret;
+  for (const secret of guestSecrets) {
+    if (secret.length < MinGuestSecretLength) {
+      throw new RangeError(`guestSecret must be at least ${MinGuestSecretLength} characters`);
+    }
+  }
+  const sign = (input) => signHS256({ alg: "HS256", typ: "JWT", kid: options.keyId }, tokenClaims(input, /* @__PURE__ */ new Date()), options.secretKey);
   return {
-    token(input) {
-      return signHS256(
-        { alg: "HS256", typ: "JWT", kid: options.keyId },
-        tokenClaims(input, /* @__PURE__ */ new Date()),
-        options.secretKey
-      );
+    token: sign,
+    guest(input) {
+      const signer = guestSecrets[0];
+      if (signer === void 0) {
+        throw new TypeError("guestSecret was not given to createChatServer, so guest credentials cannot be signed");
+      }
+      const { credential, ...claims } = input;
+      const verified = credential ? verifyGuestCredential(guestSecrets, credential) : void 0;
+      const userId = verified?.userId ?? newGuestId();
+      return {
+        userId,
+        credential: verified !== void 0 && verified.secretIndex === 0 ? credential : signGuestCredential(signer, userId),
+        token: sign({ ...claims, userId }),
+        created: verified === void 0
+      };
     },
     rooms: {
       ensure: (input) => rest.call("PUT", "/v1/rooms", input),
@@ -305,6 +353,7 @@ function createChatServer(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DefaultTokenTtlSeconds,
+  GuestIdPrefix,
   MaxTokenTtlSeconds,
   SignatureToleranceMs,
   createChatServer

package/dist/server/index.d.cts

@@ -39,6 +39,24 @@ type VerifyOptions = {
     tolerance?: number;
 };
 
+/**
+ * Guest identities without a database.
+ *
+ * 비로그인 방문자에게 안정적인 id를 주려면 브라우저가 무언가를 들고 있다가
+ * 돌려줘야 한다. 그것이 **id 자체**이면 안 된다 — `sender.id`는 방의 모든
+ * 메시지에 실려 공개되므로, 백엔드가 "돌려받은 id를 그대로 서명"하면 누구나
+ * 남의 메시지에서 id를 복사해 그 게스트로 말할 수 있다. 그래서 브라우저가 드는
+ * 것은 id에 대한 MAC이 붙은 자격증명이고, id는 그 안에서 꺼낸다. MAC은 소비자
+ * 백엔드만 아는 비밀로 만들고 검증하므로 저장소가 필요 없다.
+ *
+ * 비밀을 `sk_`에서 유도하지 않는 이유: `sk_`는 유출되면 돌리는 키이고, 돌리는
+ * 순간 모든 게스트가 새 사람이 된다(자기 메시지·읽음 커서를 잃는다). 게스트
+ * 신원의 수명은 키의 수명과 무관해야 하므로 비밀을 따로 받고, 배열로 받아
+ * 교체 중에도 옛 자격증명을 받아 준다.
+ */
+/** Every guest id starts with this, so it cannot collide with a member id that does not. */
+declare const GuestIdPrefix = "g_";
+
 type ChatServerOptions = {
     /** The chat server's base URL, e.g. `https://chat.example.com`. */
     url: string;
@@ -56,6 +74,15 @@ type ChatServerOptions = {
     keyId: string;
     /** Needed only by `webhooks.verify`. */
     webhookSecret?: string;
+    /**
+     * Needed only by `guest()`: the secret guest credentials are signed with,
+     * at least 32 characters, kept only on your backend.
+     *
+     * An array while rotating: the first signs, every one verifies, and a
+     * credential verified by an older one is re-issued under the first --
+     * same `userId` -- so guests migrate on their next visit.
+     */
+    guestSecret?: string | readonly string[];
     /** Defaults to the global. */
     fetch?: typeof globalThis.fetch;
 };
@@ -82,9 +109,33 @@ type ServerSendInput = {
     replyTo?: string;
     threadId?: string;
 };
+type GuestInput = Omit<TokenInput, 'userId'> & {
+    /** What `guest()` returned last time, as the browser kept it. Missing or invalid means a new guest. */
+    credential?: string | null;
+};
+type GuestIdentity = {
+    /** `g_…`. Public -- it is `sender.id` on every message -- and never proof of anything. */
+    userId: string;
+    /** Give this back to the browser to keep, and take it back next time. This is the proof. */
+    credential: string;
+    /** A user token for `userId`, as `token()` would sign it. */
+    token: string;
+    /** True when a new guest was issued (no credential, or one that did not verify). */
+    created: boolean;
+};
 type ChatServer = {
     /** Signs a user token locally. No network call. */
     token: (input: TokenInput) => string;
+    /**
+     * Issues or resumes a guest: verifies `credential` and signs a token for
+     * the guest id inside it, or mints a new guest when there is none. No
+     * network call and no storage. Needs `guestSecret`.
+     *
+     * **Never sign a user id the browser sends back.** A guest id is public,
+     * so re-signing it lets anyone speak as any guest. Only the credential
+     * proves who a guest is.
+     */
+    guest: (input: GuestInput) => GuestIdentity;
     rooms: {
         /** get-or-create. The same call whether the room exists or not. */
         ensure: (input: EnsureRoomInput) => Promise<{
@@ -205,4 +256,4 @@ type ChatServer = {
 };
 declare function createChatServer(options: ChatServerOptions): ChatServer;
 
-export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, MaxTokenTtlSeconds, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };
+export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, GuestIdPrefix, type GuestIdentity, type GuestInput, MaxTokenTtlSeconds, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };

package/dist/server/index.d.ts

@@ -39,6 +39,24 @@ type VerifyOptions = {
     tolerance?: number;
 };
 
+/**
+ * Guest identities without a database.
+ *
+ * 비로그인 방문자에게 안정적인 id를 주려면 브라우저가 무언가를 들고 있다가
+ * 돌려줘야 한다. 그것이 **id 자체**이면 안 된다 — `sender.id`는 방의 모든
+ * 메시지에 실려 공개되므로, 백엔드가 "돌려받은 id를 그대로 서명"하면 누구나
+ * 남의 메시지에서 id를 복사해 그 게스트로 말할 수 있다. 그래서 브라우저가 드는
+ * 것은 id에 대한 MAC이 붙은 자격증명이고, id는 그 안에서 꺼낸다. MAC은 소비자
+ * 백엔드만 아는 비밀로 만들고 검증하므로 저장소가 필요 없다.
+ *
+ * 비밀을 `sk_`에서 유도하지 않는 이유: `sk_`는 유출되면 돌리는 키이고, 돌리는
+ * 순간 모든 게스트가 새 사람이 된다(자기 메시지·읽음 커서를 잃는다). 게스트
+ * 신원의 수명은 키의 수명과 무관해야 하므로 비밀을 따로 받고, 배열로 받아
+ * 교체 중에도 옛 자격증명을 받아 준다.
+ */
+/** Every guest id starts with this, so it cannot collide with a member id that does not. */
+declare const GuestIdPrefix = "g_";
+
 type ChatServerOptions = {
     /** The chat server's base URL, e.g. `https://chat.example.com`. */
     url: string;
@@ -56,6 +74,15 @@ type ChatServerOptions = {
     keyId: string;
     /** Needed only by `webhooks.verify`. */
     webhookSecret?: string;
+    /**
+     * Needed only by `guest()`: the secret guest credentials are signed with,
+     * at least 32 characters, kept only on your backend.
+     *
+     * An array while rotating: the first signs, every one verifies, and a
+     * credential verified by an older one is re-issued under the first --
+     * same `userId` -- so guests migrate on their next visit.
+     */
+    guestSecret?: string | readonly string[];
     /** Defaults to the global. */
     fetch?: typeof globalThis.fetch;
 };
@@ -82,9 +109,33 @@ type ServerSendInput = {
     replyTo?: string;
     threadId?: string;
 };
+type GuestInput = Omit<TokenInput, 'userId'> & {
+    /** What `guest()` returned last time, as the browser kept it. Missing or invalid means a new guest. */
+    credential?: string | null;
+};
+type GuestIdentity = {
+    /** `g_…`. Public -- it is `sender.id` on every message -- and never proof of anything. */
+    userId: string;
+    /** Give this back to the browser to keep, and take it back next time. This is the proof. */
+    credential: string;
+    /** A user token for `userId`, as `token()` would sign it. */
+    token: string;
+    /** True when a new guest was issued (no credential, or one that did not verify). */
+    created: boolean;
+};
 type ChatServer = {
     /** Signs a user token locally. No network call. */
     token: (input: TokenInput) => string;
+    /**
+     * Issues or resumes a guest: verifies `credential` and signs a token for
+     * the guest id inside it, or mints a new guest when there is none. No
+     * network call and no storage. Needs `guestSecret`.
+     *
+     * **Never sign a user id the browser sends back.** A guest id is public,
+     * so re-signing it lets anyone speak as any guest. Only the credential
+     * proves who a guest is.
+     */
+    guest: (input: GuestInput) => GuestIdentity;
     rooms: {
         /** get-or-create. The same call whether the room exists or not. */
         ensure: (input: EnsureRoomInput) => Promise<{
@@ -205,4 +256,4 @@ type ChatServer = {
 };
 declare function createChatServer(options: ChatServerOptions): ChatServer;
 
-export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, MaxTokenTtlSeconds, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };
+export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, GuestIdPrefix, type GuestIdentity, type GuestInput, MaxTokenTtlSeconds, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };

package/dist/server/index.js

@@ -1,6 +1,6 @@
 import {
   errorFrom
-} from "../chunk-T3QOUFOM.js";
+} from "../chunk-5QQRM7BH.js";
 
 // src/server/api.ts
 var ServerRest = class {
@@ -36,12 +36,15 @@ var ServerRest = class {
   }
 };
 
+// src/server/guest.ts
+import { createHmac as createHmac2, randomBytes } from "crypto";
+
 // src/server/jwt.ts
 import { createHmac, timingSafeEqual } from "crypto";
 function signHS256(header, claims, secret) {
   const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}`;
-  const mac = createHmac("sha256", secret).update(signingInput).digest();
-  return `${signingInput}.${mac.toString("base64url")}`;
+  const mac2 = createHmac("sha256", secret).update(signingInput).digest();
+  return `${signingInput}.${mac2.toString("base64url")}`;
 }
 function macMatches(expected, given) {
   return expected.length === given.length && timingSafeEqual(expected, given);
@@ -50,6 +53,32 @@ function b64url(s) {
   return Buffer.from(s, "utf8").toString("base64url");
 }
 
+// src/server/guest.ts
+var GuestIdPrefix = "g_";
+var CredentialVersion = "g1";
+var MacLabel = "kispi-chat/guest/v1\n";
+var MinGuestSecretLength = 32;
+function newGuestId() {
+  return `${GuestIdPrefix}${randomBytes(16).toString("base64url")}`;
+}
+function signGuestCredential(secret, userId) {
+  return `${CredentialVersion}.${userId}.${mac(secret, userId).toString("base64url")}`;
+}
+function verifyGuestCredential(secrets, credential) {
+  const parts = credential.split(".");
+  if (parts.length !== 3) return void 0;
+  const [version, userId, given] = parts;
+  if (version !== CredentialVersion || !userId.startsWith(GuestIdPrefix)) return void 0;
+  const givenMac = Buffer.from(given, "base64url");
+  for (const [i, secret] of secrets.entries()) {
+    if (macMatches(mac(secret, userId), givenMac)) return { userId, secretIndex: i };
+  }
+  return void 0;
+}
+function mac(secret, userId) {
+  return createHmac2("sha256", secret).update(MacLabel + userId).digest();
+}
+
 // src/server/token.ts
 var MaxTokenTtlSeconds = 24 * 60 * 60;
 var DefaultTokenTtlSeconds = 60 * 60;
@@ -81,7 +110,7 @@ function tokenClaims(input, now) {
 }
 
 // src/server/webhooks.ts
-import { createHmac as createHmac2 } from "crypto";
+import { createHmac as createHmac3 } from "crypto";
 var SignatureToleranceMs = 5 * 60 * 1e3;
 var EventBeforePublish = "before_publish";
 function verifyWebhook(secret, headers, rawBody, options = {}) {
@@ -119,7 +148,7 @@ function verifyWebhook(secret, headers, rawBody, options = {}) {
   if (age > tolerance) {
     throw new Error(`webhook: signature is ${Math.round(age / 1e3)}s old, tolerance is ${tolerance / 1e3}s`);
   }
-  const expected = createHmac2("sha256", secret).update(`${timestamp}
+  const expected = createHmac3("sha256", secret).update(`${timestamp}
 ${event}
 ${delivery}
 ${rawBody}`).digest();
@@ -153,13 +182,29 @@ function createChatServer(options) {
     throw new TypeError("keyId is required: it becomes the token's kid, which tells the server which key signed it");
   }
   const rest = new ServerRest(options.url, options.secretKey, options.fetch ?? globalThis.fetch.bind(globalThis));
+  const guestSecrets = options.guestSecret === void 0 ? [] : typeof options.guestSecret === "string" ? [options.guestSecret] : options.guestSecret;
+  for (const secret of guestSecrets) {
+    if (secret.length < MinGuestSecretLength) {
+      throw new RangeError(`guestSecret must be at least ${MinGuestSecretLength} characters`);
+    }
+  }
+  const sign = (input) => signHS256({ alg: "HS256", typ: "JWT", kid: options.keyId }, tokenClaims(input, /* @__PURE__ */ new Date()), options.secretKey);
   return {
-    token(input) {
-      return signHS256(
-        { alg: "HS256", typ: "JWT", kid: options.keyId },
-        tokenClaims(input, /* @__PURE__ */ new Date()),
-        options.secretKey
-      );
+    token: sign,
+    guest(input) {
+      const signer = guestSecrets[0];
+      if (signer === void 0) {
+        throw new TypeError("guestSecret was not given to createChatServer, so guest credentials cannot be signed");
+      }
+      const { credential, ...claims } = input;
+      const verified = credential ? verifyGuestCredential(guestSecrets, credential) : void 0;
+      const userId = verified?.userId ?? newGuestId();
+      return {
+        userId,
+        credential: verified !== void 0 && verified.secretIndex === 0 ? credential : signGuestCredential(signer, userId),
+        token: sign({ ...claims, userId }),
+        created: verified === void 0
+      };
     },
     rooms: {
       ensure: (input) => rest.call("PUT", "/v1/rooms", input),
@@ -250,6 +295,7 @@ function createChatServer(options) {
 }
 export {
   DefaultTokenTtlSeconds,
+  GuestIdPrefix,
   MaxTokenTtlSeconds,
   SignatureToleranceMs,
   createChatServer

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@kispi/chat",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Client SDK for the chat server: one WebSocket, many rooms, ordered history.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "README.en.md"
   ],
   "exports": {
     ".": {