@kispi/chat 0.1.2 → 0.2.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   ChatError,
   errorFrom
-} from "./chunk-T3QOUFOM.js";
+} from "./chunk-5QQRM7BH.js";
 
 // src/emitter.ts
 var Emitter = class {
@@ -57,6 +57,16 @@ var Rest = class {
   }
   async call(method, path, body) {
     const token = await this.options.token();
+    try {
+      return await this.callWith(token, method, path, body);
+    } catch (err) {
+      if (!(err instanceof ChatError) || err.status !== 401 || this.options.refreshToken === void 0) throw err;
+      const fresh = await this.options.refreshToken().catch(() => void 0);
+      if (fresh === void 0 || fresh === token) throw err;
+      return this.callWith(fresh, method, path, body);
+    }
+  }
+  async callWith(token, method, path, body) {
     if (token === void 0) {
       throw new ChatError(
         "unauthorized",
@@ -78,6 +88,7 @@ var Rest = class {
     const parsed = text === "" ? void 0 : JSON.parse(text);
     if (!res.ok) {
       const err = errorFrom(parsed, `${method} ${path} failed with ${res.status}`);
+      err.status = res.status;
       throw err;
     }
     return parsed;
@@ -124,10 +135,24 @@ var Timeline = class {
    * rows into the new list.
    */
   epoch = 0;
+  /**
+   * `items` has been handed out -- by the getter or by `onChange`.
+   *
+   * 한 번 내준 배열은 다시 건드리지 않는다. 같은 배열을 제자리에서 고쳐
+   * 다시 내주면 Svelte `$state.raw`, React `useState`, Vue `shallowRef`처럼
+   * 참조가 바뀌어야 다시 그리는 쪽은 변화를 보지 못하고 화면이 멈춘다. 그래서
+   * 내준 뒤의 첫 변경은 복사본에서 한다(copy-on-write). 행 객체도 같은 규칙이라
+   * 바뀐 행만 새 객체다.
+   */
+  shared = false;
+  /** The `loadOlder` in flight, so a scroll handler firing twice asks once. */
+  older;
   constructor(options) {
     this.options = options;
   }
+  /** A new array whenever the list changes; never mutated once returned. */
   get messages() {
+    this.shared = true;
     return this.items;
   }
   /** The highest seq this timeline holds, hole or no hole. */
@@ -174,6 +199,7 @@ var Timeline = class {
     this.fills.clear();
     this.pendingDeletes.clear();
     this.items = [];
+    this.shared = false;
     this.changed();
   }
   /**
@@ -200,6 +226,7 @@ var Timeline = class {
     const page = [...messages].sort((a, b) => a.seq - b.seq);
     const top = page.at(-1)?.seq ?? 0;
     this.items = [...page, ...this.items.filter((m) => m.seq > top)];
+    this.shared = false;
     for (const m of this.items) {
       if (this.pendingDeletes.has(m.id)) this.applyDelete(m.id);
     }
@@ -234,6 +261,7 @@ var Timeline = class {
     if (at === -1) return;
     const current = this.items[at];
     if (current.deletedAt !== void 0) return;
+    this.own();
     this.items[at] = { ...current, ...message };
     this.changed();
   }
@@ -260,6 +288,7 @@ var Timeline = class {
     if (count <= 0) next = existing.filter((r) => r.emoji !== emoji);
     else if (slot === -1) next = [...existing, { emoji, count }];
     else next = existing.map((r, i) => i === slot ? { emoji, count } : r);
+    this.own();
     this.items[at] = { ...current, reactions: next };
     this.changed();
   }
@@ -268,6 +297,7 @@ var Timeline = class {
     const at = this.items.findIndex((m) => m.id === rootId);
     if (at === -1) return;
     const current = this.items[at];
+    this.own();
     this.items[at] = { ...current, thread: lastSeq === void 0 ? { count } : { count, lastSeq } };
     this.changed();
   }
@@ -275,6 +305,36 @@ var Timeline = class {
   remove(id) {
     if (!this.applyDelete(id)) this.pendingDeletes.add(id);
   }
+  /**
+   * Prepends the page just below the oldest message held.
+   *
+   * 스크롤을 올려 과거를 읽는 소비자가 `history()` 결과를 라이브 목록과 따로
+   * 들고 합치고, 중복을 걸러 내고, reset과 재접속을 따로 처리해야 했다. 같은
+   * 목록에 끼워 넣으면 그 일이 전부 이미 있는 규칙(seq 자리에 넣기, 같은 seq는
+   * 한 행, reset이면 epoch로 버리기)으로 끝난다.
+   *
+   * `hasMore`는 더 올라갈 것이 있는지다. 서버의 seq는 1부터 구멍 없이 붙으므로
+   * 맨 위가 1이거나 페이지가 덜 찼으면 끝이다(보존 기간이 지운 앞부분도 덜 찬
+   * 페이지로 드러난다). 한 번에 하나만 돈다 — 스크롤 핸들러가 두 번 불러도
+   * 요청은 하나다(진행 중인 호출과 같은 결과를 받으므로 뒤 호출의 `limit`은 쓰이지 않는다).
+   */
+  loadOlder(limit = this.options.pageSize ?? MaxPageSize) {
+    this.older ??= this.readOlder(Math.min(limit, MaxPageSize)).finally(() => {
+      this.older = void 0;
+    });
+    return this.older;
+  }
+  async readOlder(limit) {
+    const first = this.items[0];
+    if (first === void 0 || first.seq <= 1) return { messages: [], hasMore: false };
+    const epoch = this.epoch;
+    const page = await this.options.fetchRange({ after: 0, before: first.seq, limit });
+    if (this.epoch !== epoch) return { messages: [], hasMore: true };
+    for (const m of page) this.insert(m, false);
+    if (page.length > 0) this.changed();
+    const top = page[0];
+    return { messages: page, hasMore: page.length >= limit && top !== void 0 && top.seq > 1 };
+  }
   /**
    * Fetches everything between what we have and `upTo`.
    *
@@ -319,10 +379,11 @@ var Timeline = class {
     return run;
   }
   /** Inserts at the seq position, replacing an existing row with that seq. */
-  insert(message) {
+  insert(message, notify = true) {
     const pending = this.pendingDeletes.has(message.id);
     if (pending) this.pendingDeletes.delete(message.id);
     const withDelete = pending ? emptied(message) : message;
+    this.own();
     const at = this.items.findIndex((m) => m.seq >= withDelete.seq);
     if (at === -1) {
       this.items.push(withDelete);
@@ -332,17 +393,25 @@ var Timeline = class {
     } else {
       this.items.splice(at, 0, withDelete);
     }
-    this.changed();
+    if (notify) this.changed();
   }
   applyDelete(id) {
     const at = this.items.findIndex((m) => m.id === id);
     if (at === -1) return false;
     this.pendingDeletes.delete(id);
+    this.own();
     this.items[at] = emptied(this.items[at]);
     this.changed();
     return true;
   }
+  /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
+  own() {
+    if (!this.shared) return;
+    this.items = this.items.slice();
+    this.shared = false;
+  }
   changed() {
+    this.shared = true;
     this.options.onChange?.(this.items);
   }
 };
@@ -407,10 +476,27 @@ var Room = class extends Emitter {
       onChange: (messages) => this.emit("messages", messages)
     });
   }
-  /** Everything this client knows about the room, in seq order. */
+  /** Everything this client knows about the room, in seq order. A new array whenever it changes. */
   get messages() {
     return this.timeline.messages;
   }
+  /**
+   * Reads the page just before the oldest message held and **prepends it to
+   * `messages`**.
+   *
+   * The scroll-back call. Unlike `history()`, the rows join the room's own
+   * list, so ordering, de-duplication, deletes, reactions and reconnects
+   * apply to them like any other row, and the `messages` event fires once.
+   * A `reset` (or `reload()`) drops them with everything else; a read that
+   * lands after one is discarded rather than stitched onto the new list.
+   *
+   * `hasMore` is false once the top of the room -- or of its retention --
+   * is reached. Concurrent calls share one request.
+   */
+  async loadOlder(options = {}) {
+    await this.resolveId("loading older messages");
+    return this.timeline.loadOlder(options.limit);
+  }
   /**
    * Reloads recent history, discarding what is held.
    *
@@ -484,7 +570,8 @@ var Room = class extends Emitter {
    *
    * The list this room keeps is the live one; this is for a consumer
    * scrolling back, which owns its own window and does not want the
-   * bottom of the room rearranged under it.
+   * bottom of the room rearranged under it. **Scrolling the room's own
+   * list back is `loadOlder()`**, which keeps one list instead of two.
    *
    * `view` defaults to the server's, which is every message including
    * thread replies. **`view: 'main'` is a display filter, not a sync
@@ -493,7 +580,7 @@ var Room = class extends Emitter {
    */
   async history(options = {}) {
     const view = options.view === void 0 ? void 0 : typeof options.view === "string" ? options.view : `thread:${options.view.thread}`;
-    const page = await this.rest.get(`/v1/rooms/${this.requireId("reading history")}/messages`, {
+    const page = await this.rest.get(`/v1/rooms/${await this.resolveId("reading history")}/messages`, {
       before: options.before,
       after: options.after,
       limit: options.limit,
@@ -503,10 +590,10 @@ var Room = class extends Emitter {
   }
   /** Adds a reaction. Idempotent, like the frame. */
   async react(messageId, emoji) {
-    await this.chat.send("react", { roomId: this.requireId("reacting"), messageId, emoji, op: "add" });
+    await this.chat.send("react", { roomId: await this.resolveId("reacting"), messageId, emoji, op: "add" });
   }
   async unreact(messageId, emoji) {
-    await this.chat.send("react", { roomId: this.requireId("reacting"), messageId, emoji, op: "remove" });
+    await this.chat.send("react", { roomId: await this.resolveId("reacting"), messageId, emoji, op: "remove" });
   }
   /**
    * Moves this user's read cursor.
@@ -516,7 +603,7 @@ var Room = class extends Emitter {
    * way to know what happened. It is returned rather than swallowed.
    */
   async markRead(seq, options = {}) {
-    const data = { roomId: this.requireId("marking read"), seq };
+    const data = { roomId: await this.resolveId("marking read"), seq };
     if (options.threadId !== void 0) data["threadId"] = options.threadId;
     return await this.chat.send("read", data);
   }
@@ -543,15 +630,15 @@ var Room = class extends Emitter {
   }
   /** Joins a public or channel room. Idempotent. */
   async join() {
-    await this.rest.post(`/v1/rooms/${this.requireId("joining")}/join`);
+    await this.rest.post(`/v1/rooms/${await this.resolveId("joining")}/join`);
   }
   /** Leaves. Idempotent from the caller's side. */
   async leave() {
-    await this.rest.delete(`/v1/rooms/${this.requireId("leaving")}/members/me`);
+    await this.rest.delete(`/v1/rooms/${await this.resolveId("leaving")}/members/me`);
   }
   /** The full presence list, for rooms too large to send it in the ack. */
   async presenceList() {
-    return this.rest.get(`/v1/rooms/${this.requireId("reading presence")}/presence`, { full: "true" });
+    return this.rest.get(`/v1/rooms/${await this.resolveId("reading presence")}/presence`, { full: "true" });
   }
   /**
    * Who reacted, one row per (user, emoji) pair.
@@ -563,7 +650,7 @@ var Room = class extends Emitter {
    * most, and a full page still carries a cursor when more follows.
    */
   async reactionsOf(messageId, options = {}) {
-    return this.rest.get(`/v1/rooms/${this.requireId("reading reactions")}/messages/${messageId}/reactions`, {
+    return this.rest.get(`/v1/rooms/${await this.resolveId("reading reactions")}/messages/${messageId}/reactions`, {
       emoji: options.emoji,
       cursor: options.cursor,
       limit: options.limit
@@ -629,9 +716,22 @@ var Room = class extends Emitter {
     }
     return this.id;
   }
+  /**
+   * The room's id, waiting for a subscribe in flight to learn it.
+   *
+   * `roomByKey(k).subscribe()`를 await하지 않고 곧바로 `send`하는 것은 자연스러운
+   * 코드이고, 그때 id는 구독 ack가 와야 생긴다. 거절(`closed`)하면 소비자는
+   * "보내도 되는 때"를 알릴 신호를 따로 찾아야 한다 — 이미 날아가고 있는
+   * 구독을 기다리면 그 신호가 필요 없다. 구독이 실패하면 그 실패가 그대로
+   * 나간다. 구독한 적이 없으면 기다릴 것이 없으니 예전처럼 거절한다.
+   */
+  async resolveId(what) {
+    while (this.id === void 0 && this.subscribing !== void 0) await this.subscribing;
+    return this.requireId(what);
+  }
   /** Publishes and resolves when the server acks. */
   async send(input, options = {}) {
-    const roomId = this.requireId("sending");
+    const roomId = await this.resolveId("sending");
     const body = {};
     if (input.text !== void 0) body["text"] = input.text;
     if (input.entities !== void 0) body["entities"] = input.entities;
@@ -763,6 +863,7 @@ var ChatClient = class extends Emitter {
       url: options.restURL ?? restURLFrom(options.url),
       key: options.key,
       token: async () => this.lastToken,
+      refreshToken: () => this.refreshToken(),
       fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
     });
     this.setupLifecycle();
@@ -983,7 +1084,13 @@ var ChatClient = class extends Emitter {
   }
   async openOnce() {
     this.setState(this.attempt === 0 ? "connecting" : "reconnecting");
-    const authData = await this.authData();
+    let authData;
+    try {
+      authData = await this.authData();
+    } catch (err) {
+      this.scheduleReconnect();
+      throw err;
+    }
     if (this.closedByCaller) {
       throw new ChatError("closed", "the client was closed while connecting");
     }
@@ -1152,6 +1259,28 @@ var ChatClient = class extends Emitter {
     data["token"] = token;
     return data;
   }
+  /**
+   * REST가 401을 받았을 때 토큰을 새로 받는다.
+   *
+   * 소켓은 접속할 때 한 번 인증하고 그 뒤로는 토큰을 다시 보지 않지만, REST는
+   * 요청마다 본다. 그래서 한 시간짜리 토큰이면 한 시간 뒤 라이브는 멀쩡한데
+   * 히스토리·구멍 메우기만 401이 된다. 동시에 실패한 요청들이 `token()`을
+   * 각자 부르지 않도록 진행 중인 것 하나를 나눠 쓴다.
+   */
+  refreshToken() {
+    if (this.options.externalToken !== void 0) return Promise.resolve(void 0);
+    this.refreshing ??= (async () => {
+      try {
+        const token = await this.options.token();
+        this.lastToken = token;
+        return token;
+      } finally {
+        this.refreshing = void 0;
+      }
+    })();
+    return this.refreshing;
+  }
+  refreshing;
   failPending(err) {
     for (const [, waiter] of this.pending) waiter.reject(err);
     this.pending.clear();

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 };