iosignal 6.1.0 → 6.1.2

package/README.ko.md

@@ -0,0 +1,269 @@
+# iosignal
+
+[English](README.md) | [한국어](README.ko.md)
+
+Node.js와 브라우저를 위한 실시간 메시징 라이브러리입니다. WebSocket 기반
+클라이언트·서버 통신, 태그 기반 발행/구독, RPC 서비스를 제공합니다.
+Node.js에서는 TCP 기반 `IOCongSocket`도 사용할 수 있습니다.
+
+## 설치
+
+```bash
+npm install iosignal
+```
+
+아래 Node.js 예제는 ESM 형식입니다. `.mjs` 파일로 저장하거나 프로젝트의
+`package.json`에 `"type": "module"`을 설정하세요.
+
+## 빠른 시작
+
+### 서버
+
+다음을 `server.mjs`로 저장하고 `node server.mjs`로 실행합니다.
+
+```js
+import { Server, replyService } from 'iosignal';
+
+const server = new Server({ port: 8080 });
+server.attach('reply', replyService);
+
+server.on('ready', () => {
+  console.log(`Listening on port ${server.port}`);
+});
+
+process.once('SIGINT', () => server.close());
+```
+
+이 예제는 인증 없는 로컬 개발용 서버입니다.
+
+### Node.js 클라이언트
+
+서버 실행 후 다음을 `client.mjs`로 저장하고 `node client.mjs`로 실행합니다.
+
+```js
+import { IO } from 'iosignal';
+
+const io = new IO('ws://localhost:8080');
+io.on('error', console.error);
+
+io.on('ready', async () => {
+  try {
+    const response = await io.call('reply', 'echo', 'Hello, iosignal!');
+    console.log(response.body);
+  } catch (error) {
+    console.error(error);
+  } finally {
+    io.stop();
+  }
+});
+```
+
+CommonJS에서도 공개 API를 사용할 수 있습니다.
+
+```js
+const { IO, Server, replyService } = require('iosignal');
+```
+
+## 발행과 구독
+
+연결이 준비되면 `subscribe()`로 태그를 구독하고 `signal()`로 메시지를 보냅니다.
+다음 클라이언트는 메시지를 계속 수신합니다.
+
+```js
+import { IO } from 'iosignal';
+
+const io = new IO('ws://localhost:8080');
+io.on('error', console.error);
+io.on('message', (tag, message) => {
+  console.log(tag, message);
+});
+io.on('ready', () => {
+  io.subscribe('room');
+  io.signal('room', 'Hello, subscribers!');
+});
+
+process.once('SIGINT', () => io.stop());
+```
+
+`signal(tag, ...args)`는 문자열, 바이너리, 객체 및 여러 인자를 지원합니다.
+`unsubscribe(tag)`로 구독을 해제할 수 있습니다.
+
+## 브라우저
+
+번들러를 사용하는 브라우저 프로젝트에서는 브라우저 전용 진입점을 가져옵니다.
+
+```js
+import IO from 'iosignal/io';
+
+const io = new IO('ws://localhost:8080');
+io.on('error', console.error);
+io.on('message', (tag, message) => console.log(tag, message));
+io.on('ready', () => {
+  io.subscribe('room');
+  io.signal('room', 'Hello from the browser!');
+});
+```
+
+브라우저 예제도 위 서버에 연결합니다. HTTPS 페이지에서는 TLS가 구성된
+`wss://` 서버 주소를 사용하세요. 사용이 끝나면 `io.stop()`으로 연결과 자동 재연결을 중단합니다.
+
+## 주요 API
+
+| API | 용도 |
+| --- | --- |
+| `Server` | WebSocket/TCP 서버 생성 |
+| `IO` | Node.js WebSocket 클라이언트; `iosignal/io`에서는 브라우저 클라이언트 |
+| `IOCongSocket` | Node.js TCP 클라이언트 |
+| `server.attach(name, service)` | RPC 서비스 등록 |
+| `io.call(service, command, ...args)` | RPC 요청 |
+| `io.subscribe(tag)` / `io.unsubscribe(tag)` | 태그 구독 / 해제 |
+| `io.signal(tag, ...args)` | 메시지 발행 |
+| `io.stop()` | 자동 재연결 중단 및 연결 정리 |
+| `server.close(callback)` | 서버 종료 |
+| `BohoAuth` | 서버 인증 관리자 |
+| `StringKeyProvider`, `FileKeyProvider`, `RedisKeyProvider` | 인증 키 공급자 |
+
+## boho를 이용한 인증과 암호통신
+
+IOSignal은 [boho](https://github.com/remocons/boho)를 사용하여 공유 키 기반
+인증과 메시지 암호화를 제공합니다. boho에는
+[Arduino 구현](https://github.com/remocons/boho-arduino)과 Node.js·브라우저용
+JavaScript 구현이 있어, 직접 만든 장치와 웹앱을 같은 방식으로 연결할 수 있습니다.
+
+### 왜 공유 키 기반의 boho인가요?
+
+Arduino 장치와 직접 개발한 웹앱, 관리 주체가 같은 서버에서는 양쪽 코드와
+최초 키 설정을 직접 관리할 수 있습니다. 제작 시 USB·직렬 연결로 장치별 키를
+기록하거나, 웹앱 사용자가 별도 경로로 받은 키를 입력하거나, 서버 사이에서
+기존 SSH·TLS 연결로 키를 배포할 수 있습니다.
+
+이처럼 안전한 키 설정 경로가 이미 있다면 사전 공유 대칭키로도 인증과 암호통신을
+설계할 수 있습니다. 인증기관 없이 통신할 상대를 정할 수 있으며, 이때 신뢰의
+기반은 키 설정 경로와 양쪽 프로그램입니다. 장치별 키, 안전한 보관과 교체·폐기
+방법은 여전히 필요합니다. 웹앱의 공개 JavaScript 번들에 공통 비밀 키를 넣는
+것은 안전한 키 배포가 아닙니다.
+
+boho는 이 환경을 위해 SHA-256 기반 키스트림, XOR 암호화, 공유 키 인증과
+바이너리 패킷을 묶습니다. 차별점은 암호 연산 자체의 새로움보다 **Arduino와
+JavaScript의 호환 구현을 IOSignal의 연결·메시지 전달에 활용할 수 있다는 점**입니다.
+
+### XOR와 해시 기반 ‘가상 OTP’
+
+XOR는 같은 값으로 두 번 연산하면 원래 값으로 돌아오는 단순한 연산입니다.
+
+```text
+암호화: 암호문 = 평문 XOR 키스트림
+복호화: 평문   = 암호문 XOR 키스트림
+```
+
+진짜 일회용 패드(One-Time Pad, OTP)는 평문과 독립적인 완전한 무작위 패드를
+데이터 길이만큼 준비하고, 비밀로 유지하며 한 번만 사용합니다. 이 조건에서는
+완전한 비밀성을 얻지만, 1MB 데이터마다 새로운 1MB 비밀 패드를 양쪽에 공급해야
+합니다. 같은 패드를 재사용하면 `C1 XOR C2 = P1 XOR P2`로 평문 사이의 관계가
+노출됩니다.
+
+boho는 데이터 길이만큼 패드를 저장하는 대신, 비밀 키와 메시지별 값에서
+SHA-256으로 키스트림을 생성합니다. 일반적인 `set_key` 경로는 다음과 같습니다.
+
+```text
+K   = SHA256(입력 키)
+B   = SHA256(K || salt12)
+S_i = SHA256(B || LE32(i))       // i = 1, 2, 3, …
+키스트림 = S_1 || S_2 || …      // 평문 길이만큼 사용
+```
+
+`||`는 바이트열 연결이고, `LE32`는 4바이트 little-endian 정수입니다.
+각 해시 출력은 32바이트입니다. `salt12`는 시각·카운터·nonce로 구성되며,
+수신자도 같은 값과 키를 사용해 키스트림을 재현합니다.
+
+‘가상 OTP’는 이 의사난수 키스트림을 설명하는 표현이며 진짜 OTP의 완전한
+비밀성을 뜻하지 않습니다. **공개된 랜덤 값만 해시하면 누구나 같은 출력을
+계산할 수 있으므로 공유 비밀 키가 필요합니다.** 같은 키와 `salt12`의 중복도
+피해야 합니다. XOR만으로 변조를 검출할 수 없어 boho는 데이터 패킷에
+`SHA256(K || salt12 || 평문)`의 앞 8바이트로 계산한 태그도 포함합니다.
+이 태그는 기존 코드의 명칭과 달리 표준 HMAC이 아닙니다.
+
+### TLS와 함께 이해하기
+
+일반적인 인증서 기반 TLS는 사전에 비밀을 공유하지 않은 상대와 인증·키 합의를
+수행하고 실제 데이터에는 대칭키를 사용합니다. 로그인하지 않은 웹 사용자도
+서버를 인증하고 암호화 연결을 만들 수 있지만, 네트워크 익명성을 제공하는 것은
+아닙니다. 임베디드 환경에서는 인증서·신뢰 루트·시각·갱신 관리와 핸드셰이크
+연산 및 버퍼가 부담이 될 수 있습니다. 키 설정 경로가 이미 있는 작은 시스템은
+이런 구성 중 일부를 줄일 수 있습니다.
+
+다만 TLS도 **PSK-only와 PSK+(EC)DHE**를 지원하므로 항상 제3자 인증서나 공개키
+교환이 필요한 것은 아닙니다.
+[TLS 1.3의 PSK 방식](https://www.rfc-editor.org/rfc/rfc8446.html#section-2.2)
+boho가 모든 환경에서 TLS나 표준 대칭키 구현보다 빠르거나 메모리를 덜 사용한다는
+뜻은 아니며 실제 비교에는 측정이 필요합니다.
+
+### 연결 암호화와 E2E 데이터 키
+
+```text
+Arduino 장치 ←→ IOSignal 서버 ←→ 브라우저 웹앱
+     └──────── 별도 E2E 데이터 키 ────────┘
+```
+
+연결 인증용 키는 각 클라이언트의 서버 접속 자격을 확인하는 데 사용합니다.
+중계 서버가 메시지 본문을 읽지 못하게 하려면 최종 송수신자만 공유하는 별도
+데이터 키로 `signal_e2e`를 사용하고, 수신 측에서 `decrypt_e2e`로 검증·복호화합니다.
+일반 연결 암호화만으로 종단간 암호화가 되는 것은 아닙니다. 서버는 E2E 메시지의
+전달에 필요한 라우팅 정보를 처리하며 트래픽 크기 등의 메타데이터도 남습니다.
+
+현재 JavaScript 구현의 `AUTO` 모드는 TLS를 사용하지 않고 boho 인증이 완료된
+경우 boho 연결 암호화를 사용합니다. E2E 본문 암호화는 연결 보호 여부와 별도입니다.
+위 빠른 시작의 인증 없는 로컬 예제는 boho 인증·암호화를 활성화한 예제가 아닙니다.
+
+일반 웹 배포에서는 HTTPS로 웹앱을 제공하고 WSS로 연결하면서 본문에 E2E를
+적용할 수 있습니다. 앱 코드가 변조되면 키와 평문도 노출될 수 있어 E2E에서도
+웹앱 코드 제공자에 대한 신뢰가 필요합니다. boho는 브라우저의 mixed content
+정책을 우회하지 않습니다.
+
+### 현재 구현의 적용 조건
+
+- 충분히 무작위인 키를 사용하세요. `set_key`의 SHA-256 한 번은 비밀번호용 느린 KDF가 아닙니다.
+- JavaScript는 `crypto.getRandomValues()`를 사용하지만 현재 Arduino 구현의 독립 패킷과 인증 요청의 클라이언트 nonce는 `micros()`에 기반합니다. 이는 암호학적 난수가 아니므로 재시작·장치·통신 방향을 포함해 같은 키와 `salt12`가 반복되지 않는지 검토해야 합니다.
+- boho 자체는 재전송 거부나 challenge 만료를 강제하지 않습니다. 유효한 태그만으로 메시지의 신선도나 명령 실행 권한이 보장되지 않으므로 호출 측과 응용 계층의 수신 정책을 확인해야 합니다.
+- boho는 SHA-256을 조합한 자체 프로토콜입니다. 표준 AEAD/TLS와 동일한 보안 보장이나 장기 키 유출 후 과거 통신을 보호하는 순방향 비밀성을 제공한다고 취급해서는 안 됩니다.
+
+## 소스 빌드 및 검증
+
+이 저장소의 개발·검증 환경은 Node.js 22와 npm 10을 사용합니다.
+
+```bash
+npm ci
+npm run verify
+```
+
+`verify`는 공개 파일 정책을 검사하고, `dist`를 삭제한 뒤 번들과 타입 선언을
+재생성합니다. 이어서 자동 테스트와 npm 패키지 포함 파일 검사를 수행합니다.
+
+빌드만 실행하려면 `npm run build`, 이미 빌드된 결과의 자동 테스트만 실행하려면
+`npm test`를 사용합니다.
+
+### 통신 자동 테스트
+
+```bash
+npm run build
+npm run test:integration
+```
+
+`test/integration/`은 공개 ESM·CommonJS 빌드 각각에 대해 실제 WebSocket 통신을 검사합니다.
+로컬 루프백(`127.0.0.1`)의 임시 포트를 사용하므로 외부 서버, Redis, 실제 인증키가 필요하지 않습니다.
+
+- 연결과 RPC 응답, 없는 명령 및 권한 거부
+- 두 클라이언트 간 문자열·객체·바이너리 발행/구독과 구독 해제
+- 인증 성공 및 암호화된 RPC 응답, 잘못된 인증 거부
+- 연결 종료 후 클라이언트 재사용과 서버 자원 정리
+
+`npm test`와 `npm run verify`에도 통신 검사가 포함됩니다. 테스트별 시간 제한과
+전체 테스트 파일 시간 제한을 두며, 종료 시 서버와 클라이언트를 정리합니다.
+실제 브라우저, TLS, TCP 전송 및 Redis 연동 검증은 이 통신 테스트 범위에 포함되지 않습니다.
+
+기존 `test/attach-services/`, `test/auth_server_client/`, `test/pubsub-counter/`,
+`test/subscribe-signal/`은 수동 예제입니다. 자동 실행하지 않으며, 일부는 별도 서버나 Redis가 필요합니다.
+
+## 라이선스
+
+패키지 라이선스: MIT.

package/README.md

@@ -1,23 +1,25 @@
 # iosignal
 
-Node.js와 브라우저를 위한 실시간 메시징 라이브러리입니다. WebSocket 기반
-클라이언트·서버 통신, 태그 기반 발행/구독, RPC 서비스를 제공합니다.
-Node.js에서는 TCP 기반 `IOCongSocket`도 사용할 수 있습니다.
+[English](README.md) | [한국어](README.ko.md)
 
-## 설치
+A real-time messaging library for Node.js and browsers, providing WebSocket
+client–server communication, tag-based publish/subscribe and RPC services.
+Node.js also supports TCP through `IOCongSocket`.
+
+## Installation
 
 ```bash
 npm install iosignal
 ```
 
-아래 Node.js 예제는 ESM 형식입니다. `.mjs` 파일로 저장하거나 프로젝트의
-`package.json`에 `"type": "module"`을 설정하세요.
+The Node.js examples below use ESM. Save them as `.mjs` files or set
+`"type": "module"` in your project's `package.json`.
 
-## 빠른 시작
+## Quick start
 
-### 서버
+### Server
 
-다음을 `server.mjs`로 저장하고 `node server.mjs`로 실행합니다.
+Save the following as `server.mjs` and run `node server.mjs`.
 
 ```js
 import { Server, replyService } from 'iosignal';
@@ -32,11 +34,12 @@ server.on('ready', () => {
 process.once('SIGINT', () => server.close());
 ```
 
-이 예제는 인증 없는 로컬 개발용 서버입니다.
+This is a local development server without authentication.
 
-### Node.js 클라이언트
+### Node.js client
 
-서버 실행 후 다음을 `client.mjs`로 저장하고 `node client.mjs`로 실행합니다.
+After starting the server, save the following as `client.mjs` and run
+`node client.mjs`.
 
 ```js
 import { IO } from 'iosignal';
@@ -56,16 +59,16 @@ io.on('ready', async () => {
 });
 ```
 
-CommonJS에서도 공개 API를 사용할 수 있습니다.
+The public API is also available from CommonJS.
 
 ```js
 const { IO, Server, replyService } = require('iosignal');
 ```
 
-## 발행과 구독
+## Publish and subscribe
 
-연결이 준비되면 `subscribe()`로 태그를 구독하고 `signal()`로 메시지를 보냅니다.
-다음 클라이언트는 메시지를 계속 수신합니다.
+Once connected, use `subscribe()` to subscribe to a tag and `signal()` to send
+messages. The following client keeps receiving messages.
 
 ```js
 import { IO } from 'iosignal';
@@ -83,12 +86,12 @@ io.on('ready', () => {
 process.once('SIGINT', () => io.stop());
 ```
 
-`signal(tag, ...args)`는 문자열, 바이너리, 객체 및 여러 인자를 지원합니다.
-`unsubscribe(tag)`로 구독을 해제할 수 있습니다.
+`signal(tag, ...args)` supports strings, binary data, objects and multiple
+arguments. Use `unsubscribe(tag)` to unsubscribe.
 
-## 브라우저
+## Browsers
 
-번들러를 사용하는 브라우저 프로젝트에서는 브라우저 전용 진입점을 가져옵니다.
+For browser projects using a bundler, import the browser-specific entry point.
 
 ```js
 import IO from 'iosignal/io';
@@ -102,62 +105,178 @@ io.on('ready', () => {
 });
 ```
 
-브라우저 예제도 위 서버에 연결합니다. HTTPS 페이지에서는 TLS가 구성된
-`wss://` 서버 주소를 사용하세요. 사용이 끝나면 `io.stop()`으로 연결과 자동 재연결을 중단합니다.
+This browser example connects to the same server above. From an HTTPS page,
+use a `wss://` server URL with TLS configured. When finished, call `io.stop()`
+to close the connection and stop automatic reconnection.
 
-## 주요 API
+## Main APIs
 
-| API | 용도 |
+| API | Purpose |
 | --- | --- |
-| `Server` | WebSocket/TCP 서버 생성 |
-| `IO` | Node.js WebSocket 클라이언트; `iosignal/io`에서는 브라우저 클라이언트 |
-| `IOCongSocket` | Node.js TCP 클라이언트 |
-| `server.attach(name, service)` | RPC 서비스 등록 |
-| `io.call(service, command, ...args)` | RPC 요청 |
-| `io.subscribe(tag)` / `io.unsubscribe(tag)` | 태그 구독 / 해제 |
-| `io.signal(tag, ...args)` | 메시지 발행 |
-| `io.stop()` | 자동 재연결 중단 및 연결 정리 |
-| `server.close(callback)` | 서버 종료 |
-| `BohoAuth` | 서버 인증 관리자 |
-| `StringKeyProvider`, `FileKeyProvider`, `RedisKeyProvider` | 인증 키 공급자 |
-
-## 소스 빌드 및 검증
-
-이 저장소의 개발·검증 환경은 Node.js 22와 npm 10을 사용합니다.
+| `Server` | Create a WebSocket/TCP server |
+| `IO` | Node.js WebSocket client; the browser client when imported from `iosignal/io` |
+| `IOCongSocket` | Node.js TCP client |
+| `server.attach(name, service)` | Register an RPC service |
+| `io.call(service, command, ...args)` | Make an RPC request |
+| `io.subscribe(tag)` / `io.unsubscribe(tag)` | Subscribe / unsubscribe |
+| `io.signal(tag, ...args)` | Publish a message |
+| `io.stop()` | Stop automatic reconnection and clean up the connection |
+| `server.close(callback)` | Shut down the server |
+| `BohoAuth` | Server authentication manager |
+| `StringKeyProvider`, `FileKeyProvider`, `RedisKeyProvider` | Authentication key providers |
+
+## Authentication and encrypted communication with Boho
+
+IOSignal uses [Boho](https://github.com/remocons/boho) for shared-key authentication
+and message encryption. Boho has an
+[Arduino implementation](https://github.com/remocons/boho-arduino) and a JavaScript
+implementation for Node.js and browsers, allowing DIY devices and web apps to use
+the same approach.
+
+### Why shared-key Boho?
+
+With Arduino devices, your own web apps and servers under common administration,
+you can control both endpoint code and initial key provisioning. Device-specific
+keys can be installed over USB/serial during setup, web app users can enter keys
+obtained through another channel, and servers can distribute keys through
+existing SSH/TLS connections.
+
+When a secure provisioning path already exists, pre-shared symmetric keys can
+support authentication and encrypted communication. You can establish peers
+without a certificate authority; trust rests on the provisioning path and
+endpoint software. Device-specific keys, secure storage, rotation and revocation
+are still necessary. Embedding a common secret in a public JavaScript bundle is
+not secure key distribution.
+
+Boho combines a SHA-256-based keystream, XOR encryption, shared-key authentication
+and binary packets for this environment. Its distinction is **compatible Arduino
+and JavaScript implementations integrated with IOSignal connections and message
+delivery**, rather than novelty in the cryptographic operations themselves.
+
+### XOR and a hash-based “virtual OTP”
+
+XOR is a simple operation that restores the original value when applied twice
+with the same value.
+
+```text
+Encryption: ciphertext = plaintext XOR keystream
+Decryption: plaintext  = ciphertext XOR keystream
+```
+
+A true one-time pad (OTP) uses a uniformly random pad independent of the
+plaintext, as long as the data, kept secret and used only once. This provides
+perfect secrecy, but requires supplying both endpoints with a new 1 MB secret
+pad for every 1 MB of data. Reusing a pad exposes `C1 XOR C2 = P1 XOR P2`, revealing
+a relationship between plaintexts.
+
+Instead of storing a pad as large as the data, Boho generates a SHA-256 keystream
+from a secret key and message-specific values. The usual `set_key` path is:
+
+```text
+K   = SHA256(input key)
+B   = SHA256(K || salt12)
+S_i = SHA256(B || LE32(i))       // i = 1, 2, 3, …
+keystream = S_1 || S_2 || …     // use only the plaintext length
+```
+
+`||` means byte concatenation; `LE32` is a four-byte little-endian integer. Each
+hash output is 32 bytes. `salt12` contains time, counter and nonce values, and
+the receiver reproduces the stream using the same values and key.
+
+“Virtual OTP” describes this pseudorandom stream, not the perfect secrecy of a
+true OTP. **Public random values alone can be hashed by anyone, so a shared secret
+key is required.** Repeating the same key and `salt12` must also be avoided. XOR
+alone does not detect tampering, so Boho data packets include the first eight
+bytes of `SHA256(K || salt12 || plaintext)` as a tag. Despite legacy names in the
+code, this tag is not standard HMAC.
+
+### Understanding the relationship with TLS
+
+Typical certificate-based TLS authenticates peers and establishes keys without a
+previously shared secret, then uses symmetric encryption for application data.
+Even web users who have not logged in can authenticate the server and establish
+an encrypted connection, but this does not provide network anonymity. On embedded
+devices, certificate, trust-root, clock and renewal management, handshake work
+and buffers can be burdensome. Small systems with an existing provisioning path
+may be able to omit some of this machinery.
+
+However, TLS supports **PSK-only and PSK with (EC)DHE**, so it does not always
+require third-party certificates or public-key exchange.
+[TLS 1.3 pre-shared keys](https://www.rfc-editor.org/rfc/rfc8446.html#section-2.2)
+This does not mean Boho is faster or uses less memory than every TLS or standard
+symmetric implementation; actual comparisons require measurement.
+
+### Connection encryption and E2E data keys
+
+```text
+Arduino device ←→ IOSignal server ←→ Browser app
+      └──────── Separate E2E data key ────────┘
+```
+
+Connection credentials establish each client's right to connect to the server.
+To keep a message body confidential from a relay, use `signal_e2e` with a separate
+data key held only by the final endpoints, then verify and decrypt it with
+`decrypt_e2e` at the receiver. Ordinary connection encryption is not automatically
+end-to-end encryption. The server processes routing information for E2E delivery,
+and metadata such as traffic sizes remains visible.
+
+The current JavaScript implementation's `AUTO` mode uses Boho connection
+encryption when TLS is not used and Boho authentication is complete. E2E body
+encryption is separate from connection protection. The unauthenticated local
+quick-start examples above do not enable Boho authentication/encryption.
+
+Normal web deployments can serve app code over HTTPS and connect over WSS while
+also applying E2E to message bodies. Modified app code can expose keys and
+plaintext, so E2E still requires trust in the app code provider. Boho does not
+bypass browser mixed content rules.
+
+### Conditions in the current implementation
+
+- Use sufficiently random keys. A single SHA-256 in `set_key` is not a slow password KDF.
+- JavaScript uses `crypto.getRandomValues()`, but current Arduino standalone-packet nonces and the authentication client nonce use `micros()`. This is not cryptographic randomness; consider repeated key/`salt12` combinations across restarts, devices and communication directions.
+- Boho itself does not enforce replay rejection or challenge expiry. A valid tag alone does not establish freshness or permission to execute a command; check receive policies in the caller and application layer.
+- Boho is a custom SHA-256-based protocol. Do not assume standard AEAD/TLS guarantees or forward secrecy protecting past traffic after a long-term key leak.
+
+## Building and verification
+
+This repository uses Node.js 22 and npm 10 for development and verification.
 
 ```bash
 npm ci
 npm run verify
 ```
 
-`verify`는 공개 파일 정책을 검사하고, `dist`를 삭제한 뒤 번들과 타입 선언을
-재생성합니다. 이어서 자동 테스트와 npm 패키지 포함 파일 검사를 수행합니다.
+`verify` checks the public-file policy, removes `dist` and rebuilds bundles and
+type declarations. It then runs automated tests and checks the npm package file
+list.
 
-빌드만 실행하려면 `npm run build`, 이미 빌드된 결과의 자동 테스트만 실행하려면
-`npm test`를 사용합니다.
+Use `npm run build` to build only, or `npm test` to test an existing build.
 
-### 통신 자동 테스트
+### Automated communication tests
 
 ```bash
 npm run build
 npm run test:integration
 ```
 
-`test/integration/`은 공개 ESM·CommonJS 빌드 각각에 대해 실제 WebSocket 통신을 검사합니다.
-로컬 루프백(`127.0.0.1`)의 임시 포트를 사용하므로 외부 서버, Redis, 실제 인증키가 필요하지 않습니다.
+`test/integration/` tests actual WebSocket communication for both public ESM and
+CommonJS builds. It uses temporary ports on local loopback (`127.0.0.1`), so it
+requires no external server, Redis instance or real authentication credentials.
 
-- 연결과 RPC 응답, 없는 명령 및 권한 거부
-- 두 클라이언트 간 문자열·객체·바이너리 발행/구독과 구독 해제
-- 인증 성공 및 암호화된 RPC 응답, 잘못된 인증 거부
-- 연결 종료 후 클라이언트 재사용과 서버 자원 정리
+- Connections, RPC responses, unknown commands and permission denial
+- String, object and binary publish/subscribe between two clients, including unsubscribe
+- Successful authentication and encrypted RPC responses, plus rejection of invalid authentication
+- Client reuse and server resource cleanup after disconnection
 
-`npm test`와 `npm run verify`에도 통신 검사가 포함됩니다. 테스트별 시간 제한과
-전체 테스트 파일 시간 제한을 두며, 종료 시 서버와 클라이언트를 정리합니다.
-실제 브라우저, TLS, TCP 전송 및 Redis 연동 검증은 이 통신 테스트 범위에 포함되지 않습니다.
+These communication checks are included in `npm test` and `npm run verify`.
+Individual tests and test files have time limits, and connections and servers
+are cleaned up on completion. Actual browsers, TLS, TCP transport and Redis
+integration are outside their scope.
 
-기존 `test/attach-services/`, `test/auth_server_client/`, `test/pubsub-counter/`,
-`test/subscribe-signal/`은 수동 예제입니다. 자동 실행하지 않으며, 일부는 별도 서버나 Redis가 필요합니다.
+Existing `test/attach-services/`, `test/auth_server_client/`,
+`test/pubsub-counter/` and `test/subscribe-signal/` are manual examples. They are
+not run automatically, and some require a separate server or Redis.
 
-## 라이선스
+## License
 
-패키지 라이선스: MIT.
+Package license: MIT.

package/dist/browser/esm/io.d.ts

@@ -41,6 +41,7 @@ declare class IOCore {
      * @type {string}
      */
     stateName: string;
+    _stateRevision: number;
     /**
      * Transmitted message counter.
      * @type {number}
@@ -408,8 +409,11 @@ declare class IOCore {
      * 1. 상태가 변경 될 때만 'change' 이벤트 호출된다.
      * 2. emitEventAndMessage 옵션 값이 지정되야 해당 이벤트 이름이 호출된다.
      *   보통 이벤트 이름과 동일하게 적거나 이벤트 상황 안내문을 넣는다.
+     * 3. 두 상태값 갱신 후 change, 개별 이벤트 순서로 호출한다.
+     *    콜백에서 다른 상태로 전이하면 이전 상태의 개별 이벤트는 생략한다.
+     * @returns {boolean} Whether this transition is still current after callbacks.
      */
-    stateChange(state: string, emitEventAndMessage?: string): void;
+    stateChange(state: string, emitEventAndMessage?: string): boolean;
 }
 type Buffer$1 = boho.Buffer;