서버 연동

백엔드가 할 일은 둘이다 — 유저 토큰에 서명하는 것, 방·메시지·유저를 REST로 다루는 것. TypeScript에는 이 둘을 감싼 @kispi/chat/server가 있고, 다른 언어는 같은 일을 직접 한다. 아래 탭에서 언어를 고른다.

둘 다 sk_ 하나로 한다.

유저 토큰 규격

형식 표준 JWT. 서명 알고리즘은 HS256 고정이다. 다른 알고리즘과 none은 거절한다
서명 키 sk_ 문자열 전체를 UTF-8 바이트로 쓴다. 접두사를 떼거나 디코드하지 않는다
헤더 {"alg":"HS256","typ":"JWT","kid":"…"} — kid는 선택이다. sk_<키 id>_<토큰>의 둘째 조각이 13자 Crockford Base32([0-9A-HJKMNP-TV-Z]{13})일 때만 그 값을 달고, 아니면 달지 않는다. kid가 없으면 엔진이 앱의 폐기되지 않은 sk_를 모두 시도한다

클레임:

클레임
sub 필수 서비스의 유저 id. UTF-8 128바이트 이하. anon:으로 시작하면 거절한다
iat 필수 발급 시각(정수 초). 지금 + 60초보다 미래면 거절한다. 반올림하거나 캐시하지 않는다
exp 필수 만료(정수 초). exp - iat이 86400초(24시간)를 넘으면 자르지 않고 거절한다
name 권장 접속할 때마다 이 값으로 덮어쓴다. 256바이트에서 잘려 저장된다
avatar 선택 2048바이트에서 잘려 저장된다
meta 선택 JSON 객체. 유저의 meta.provider 블록을 통째로 바꾼다(깊은 병합이 아니다). 유저가 직접 쓴 다른 meta 키는 건드리지 않는다. 클레임의 JSON이 2048바이트를 넘으면 무시되고 이전 provider 블록이 그대로 남는다. 클레임을 안 주면 이전 블록도 그대로다

aud·iss·nbf는 요구하지 않는다. 어느 앱인지는 토큰이 아니라 브라우저가 접속할 때 함께 보내는 pk_가 정한다. 검증이 실패하면 이유를 가리지 않고 401 unauthorized 하나로 답한다 — 서명이 틀렸는지 만료됐는지 구별해 주지 않는다.

Go는 github.com/golang-jwt/jwt/v5, Kotlin은 com.auth0:java-jwt를 쓴다. 나머지는 표준 라이브러리로 충분하다.

ts
import { createChatServer } from '@kispi/chat/server'

const chat = createChatServer({ secretKey: process.env.CHAT_SECRET_KEY! })
const token = chat.token({ userId: 'u_42', name: '한나', ttlSeconds: 3600 })
python
import base64, hmac, hashlib, json, re, time

KID = re.compile(r"[0-9A-HJKMNP-TV-Z]{13}")  # Crockford Base32 13자

def b64u(b): return base64.urlsafe_b64encode(b).rstrip(b"=").decode()

def chat_token(sk, user_id, name, ttl=3600, avatar=None, meta=None):
    parts = sk.split("_")
    header = {"alg": "HS256", "typ": "JWT"}
    if len(parts) >= 3 and KID.fullmatch(parts[1]): header["kid"] = parts[1]
    iat = int(time.time())
    claims = {"sub": user_id, "name": name, "iat": iat, "exp": iat + ttl}
    if avatar: claims["avatar"] = avatar
    if meta: claims["meta"] = meta
    enc = lambda o: b64u(json.dumps(o, separators=(",", ":")).encode())
    signing_input = f"{enc(header)}.{enc(claims)}"
    sig = hmac.new(sk.encode(), signing_input.encode(), hashlib.sha256).digest()
    return f"{signing_input}.{b64u(sig)}"
go
var kidPattern = regexp.MustCompile(`^[0-9A-HJKMNP-TV-Z]{13}$`) // Crockford Base32 13자

func chatToken(sk, userID, name string, ttl time.Duration) (string, error) {
	now := time.Now()
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
		"sub":  userID,
		"name": name,
		"iat":  now.Unix(),
		"exp":  now.Add(ttl).Unix(),
	})
	if parts := strings.Split(sk, "_"); len(parts) >= 3 && kidPattern.MatchString(parts[1]) {
		token.Header["kid"] = parts[1]
	}
	return token.SignedString([]byte(sk))
}
kotlin
private val KID = Regex("^[0-9A-HJKMNP-TV-Z]{13}$") // Crockford Base32 13자

fun chatToken(sk: String, userId: String, name: String, ttlSeconds: Long = 3600): String {
    val now = Instant.now()
    val builder = JWT.create()
        .withSubject(userId)
        .withClaim("name", name)
        .withIssuedAt(now)
        .withExpiresAt(now.plusSeconds(ttlSeconds))
    sk.split("_").let { if (it.size >= 3 && KID.matches(it[1])) builder.withKeyId(it[1]) }
    return builder.sign(Algorithm.HMAC256(sk))
}

서버 API

방·메시지·유저를 다루는 창구는 REST 하나다. TypeScript SDK는 그것을 감싼 것이라, 아래 세 탭은 같은 엔드포인트를 부르는 세 가지 방법이다. 모든 라우트의 요청·응답·에러는 REST API 레퍼런스에 있다.

@kispi/chat/server의 표면 전체다. 메시지 수정, 검색(q), 유저 목록 필터, 유저 영구 삭제(purge)는 SDK에 메서드가 없으니 REST를 직접 부른다. 방 영구 삭제는 rooms.delete(roomId, {purge: true})다.

그룹 메서드
최상위 token({userId, name, avatar?, meta?, ttlSeconds?}), guest({credential?, name, avatar?, meta?, ttlSeconds?}) — 둘 다 로컬 서명이다
rooms list({type?, cursor?, limit?}), ensure({key?, type, name?, meta?, members?}), ensureDM([a, b]), get, update, delete(roomId, {purge?}), custom(roomId, payload), presence(roomId, {full?}), members.list/add/remove
messages send(roomId, {sender, text?, kind?, attachments?, appMeta?, replyTo?, threadId?, clientMessageId?}), list(roomId, {before?, after?, limit?}), delete
users list({cursor?, limit?}), update(userId, {name?, avatar?, meta?}), withdraw(userId, {purgeMessages?}), purgeMessages(userId), ban(userId, {until, reason?}), unban(userId), revokeTokens(userId), disconnect(userId, {connectionId?, reason?})
events list({after?, limit?}) — 놓친 웹훅을 따라잡는다
webhooks verify(headers, rawBody, {now?, tolerance?})
ts
const chat = createChatServer({ secretKey: process.env.CHAT_SECRET_KEY! })
const room = await chat.rooms.ensure({ key: 'lobby', type: 'public' })
await chat.messages.send(room.id, {
  sender: { id: 'system', name: '공지' },
  text: '점검 10분 전입니다'
})

주소는 https://api.chat.gravex.app이다. 인증은 Authorization: Bearer sk_…이고, 바디가 있으면 Content-Type: application/json을 함께 보낸다.

용도 라우트
방 get-or-create PUT /v1/rooms {key?, type, name?, meta?, members?} — 201 생성, 200 기존
DM PUT /v1/rooms {type: "dm", members: [a, b]}
방 목록 GET /v1/rooms?type=&cursor=&limit= — type을 생략하면 public·channel이고, sk_는 private·dm도 쉼표로 이어 줄 수 있다(type=private,dm). 새 방부터, limit 기본 50·최대 100
방 조회·수정·삭제 GET·PATCH·DELETE /v1/rooms/{roomId}, GET /v1/rooms/by-key/{key}
방 영구 삭제 DELETE /v1/rooms/{roomId}?purge=true — 202
메시지 보내기 POST /v1/rooms/{roomId}/messages {clientMessageId, sender: {id, name, avatar?}, kind?, body: {text?, attachments?}, appMeta?, replyTo?, threadId?}
히스토리·검색 GET /v1/rooms/{roomId}/messages?before=&after=&limit=&view=&q=
메시지 수정 PATCH /v1/rooms/{roomId}/messages/{messageId} {body: {text?, attachments?}} — 200 + 메시지 객체
메시지 삭제 DELETE /v1/rooms/{roomId}/messages/{messageId} — 204
저장되지 않는 제어 신호 POST /v1/rooms/{roomId}/custom {payload}
멤버 GET /v1/rooms/{roomId}/members, PUT·DELETE /v1/rooms/{roomId}/members/{userId} {role?}
presence GET /v1/rooms/{roomId}/presence?full=true — 빈 방은 {count: 0}
유저 프로필 PUT /v1/users/{userId} {name?, avatar?, meta?}
밴·해제 PUT /v1/users/{userId}/ban {until, reason?}(until은 unix 밀리초, 필수), DELETE …/ban
메시지 거두기 DELETE /v1/users/{userId}/messages
탈퇴(익명화) DELETE /v1/users/{userId}, 메시지까지 거두려면 ?purge_messages=true
유저 영구 삭제 DELETE /v1/users/{userId}?purge=true — 탈퇴한 유저만, 202
토큰 무효화 POST /v1/users/{userId}/revoke-tokens
강제 종료 POST /v1/users/{userId}/disconnect
유저 목록 GET /v1/users?cursor=&limit=&q=&status=&last_seen_after=&last_seen_before=&created_after=&created_before=&bots=
놓친 이벤트 GET /v1/events?after=&limit=
앱 전체 내려받기 GET /v1/export — NDJSON 스트림. 유저·방·멤버·메시지·리액션·읽음 위치가 들어 있고 첨부 파일은 없다. 마지막 줄이 {"type":"end",…}가 아니면 불완전한 파일이다. 앱당 동시에 하나(409), 서버가 바쁘면 429. sk_ 전용
bash
# 방 get-or-create. 있으면 200, 새로 만들면 201이고 몸통은 같다
curl -X PUT https://api.chat.gravex.app/v1/rooms \
  -H "Authorization: Bearer $CHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "lobby", "type": "public"}'

# 시스템 메시지 보내기. sender와 clientMessageId가 필수다
curl -X POST https://api.chat.gravex.app/v1/rooms/$ROOM_ID/messages \
  -H "Authorization: Bearer $CHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientMessageId": "c_1",
       "sender": {"id": "system", "name": "공지"},
       "body": {"text": "점검 10분 전입니다"}}'

sender와 clientMessageId는 서버에서 메시지를 보낼 때 필수다. 쿼리 파라미터는 스네이크 케이스(purge_messages)이고 JSON 필드는 카멜 케이스다.

users.*는 그 사람이 한 번이라도 접속한 뒤에만 통한다. 유저는 접속으로 생긴다.

히스토리 조회와 검색

  • 응답은 seq 오름차순이고 limit은 최대 100이다. before·after는 seq다.
  • view를 생략하면 스레드 답글까지 방 전체이고, main은 본 타임라인만, thread:<루트 메시지 id>는 그 스레드만 준다. 그 밖의 값은 400이다.
  • q는 그 방 안의 본문(body.text) 검색이다. 부분 일치이고 대소문자를 가리지 않으며 삭제된 메시지는 걸리지 않는다. q는 sk_만 쓰고 유저 토큰으로 주면 403이며, 공백뿐인 q는 400이다. 검색 결과의 seq는 이어지지 않는다 — 걸리지 않은 메시지가 빠진 것이므로 누락 감지에 쓰지 않는다.

메시지 수정과 삭제

PATCH는 메시지의 body를 통째로 바꾸고 editedAt을 찍는다. seq는 움직이지 않고 방에는 message.updated가 나간다. body가 없으면 400이고, 이미 삭제된 메시지는 404다.

  • sk_로 부르면 누가 쓴 메시지든(시스템 메시지 포함) 고치고, 수정 가능 시간도 적용되지 않는다.
  • 유저 토큰으로 부르면 본인이 쓴 메시지만, 앱의 수정 가능 시간(editWindowMs, 기본은 제한 없음) 안에서만 고친다. 방 owner·admin도 남의 메시지는 고치지 못하고 지우기만 한다. 밴된 유저는 banned다.
  • 속도는 유저마다 초당 2회(editPerSecond)다. sk_ 호출은 세지 않는다.

브라우저 SDK의 Room에는 수정·삭제 메서드가 없고 서버 SDK에는 messages.delete만 있다. 수정은 REST를 직접 부른다. 시스템 메시지나 모더레이션 수정은 백엔드에서 sk_로 부르고, 유저가 자기 메시지를 고치는 화면은 브라우저가 유저 토큰으로 직접 부르면 된다(Authorization: Bearer <유저 토큰>과 X-Chat-Key: pk_…를 함께 보낸다). 작성자와 수정 가능 시간은 엔진이 검사한다.

DELETE는 행을 남기고 본문을 비우는 tombstone이다. seq는 그대로이고 방에는 message.deleted가 나간다. 이미 지워진 메시지를 다시 지워도 204다. 유저 토큰으로는 본인 메시지와, 방 owner·admin이 남의 메시지를 지우는 모더레이션만 된다.

삭제의 종류

하려는 일 호출 남는 것
메시지 하나 지우기 DELETE /v1/rooms/{roomId}/messages/{messageId} 행과 seq, 보낸 사람 이름. 본문만 비운다
한 사람의 메시지 전부 거두기 DELETE /v1/users/{userId}/messages 위와 같다. 계정은 그대로다
탈퇴 DELETE /v1/users/{userId} 이름은 "탈퇴한 사용자", 아바타와 meta는 비워진다. 유저 행과 외부 id는 남고 메시지도 그대로다
탈퇴 + 메시지 거두기 DELETE /v1/users/{userId}?purge_messages=true 계정은 탈퇴 상태로 남고, 메시지 본문과 메시지에 찍힌 이름이 지워진다
유저 영구 삭제 DELETE /v1/users/{userId}?purge=true 유저 행·리액션·읽음 커서·멤버십·밴이 사라지고 메시지의 이름도 비워진다. 메시지 행과 sender.id는 남는다
방 삭제 DELETE /v1/rooms/{roomId} 방이 보이지 않게 되고 key는 비워져 같은 key로 다시 만들 수 있다. 메시지 행은 남는다
방 영구 삭제 DELETE /v1/rooms/{roomId}?purge=true 방과 그 안의 모든 메시지가 사라진다
  • 탈퇴(withdraw)는 익명화일 뿐 삭제가 아니다. 유저 행이 남고, 탈퇴만으로는 메시지 본문과 그 메시지에 찍힌 이름도 남는다. SDK의 users.withdraw(userId, {purgeMessages})가 이것이다.
  • 개인정보 삭제 요청에는 purge까지 간다. 순서는 ① DELETE /v1/users/{userId}?purge_messages=true를 응답의 purgeCapped가 false가 될 때까지 부르고, ② DELETE /v1/users/{userId}?purge=true를 부른다. ②는 탈퇴하지 않은 유저에게 409다.
  • purge는 되돌릴 수 없다. 요청은 202로 접수되고 엔진이 배치로 지운다. sk_ 전용이며 유저 토큰은 403이다. 같은 대상에 진행 중인 작업이 있으면 같은 작업으로 접수된다. 유저 purge 뒤에는 그 외부 id를 다시 쓸 수 있게 되는데, 남은 옛 메시지의 sender.id가 같은 문자열을 들고 있으므로 새 사람에게 옛 id를 재사용하지 않는다.
  • 방 purge는 SDK의 rooms.delete(roomId, {purge: true})가 202의 job을 돌려준다(0.8.2부터). 유저 purge는 SDK에 메서드가 없으니 REST를 직접 부른다.
  • purge가 true나 false가 아니면 400이다.

유저 목록 필터

GET /v1/users는 아래 조건을 선택으로 받는다. 해석되지 않는 값은 400이고, 필터를 바꾸면 cursor를 버리고 첫 페이지부터 다시 받는다.

파라미터 값
q externalId 접두어 일치 또는 name 부분 일치. 대소문자를 가리지 않는다
status live, withdrawn, all(기본)
last_seen_after, last_seen_before RFC3339. 마지막 접속 시각의 범위
created_after, created_before RFC3339. 가입 시각의 범위
bots include(기본), exclude, only

시각 범위는 *_after는 포함, *_before는 제외다. 탈퇴한 유저도 목록에 나오고 deletedAt이 그 표시다.

방을 만들 때 고르는 타입:

타입 누가 읽나 누가 쓰나 찾는 법
public 누구나 누구나 키 또는 id. 탐색에 나온다
private 멤버만 멤버만 키 또는 id
channel 누구나 owner·admin만 키 또는 id. 탐색에 나온다
dm 두 사람만 두 사람만 두 사람의 조합. 키가 없다

방의 정본은 id다. key는 사람이 붙이는 별칭(lobby, order-1234)이고 브라우저는 chat.roomByKey(key)로 연다. key는 영문 대소문자·숫자와 _ . : -만 쓰는 1~128자 (^[A-Za-z0-9_.:-]{1,128}$)여야 한다. 한글이나 공백이 들어가면 PUT /v1/rooms와 PATCH가 400을 돌려주므로, 사람이 읽는 이름은 name에 둔다. dm 방에는 key가 없다. channel을 서버에서 만들면 owner가 없으므로, 유저 토큰으로 공지를 올릴 사람이 있어야 한다면 만든 뒤 멤버 API로 owner나 admin을 지정한다.

키 교체

sk_는 새 키 발급 → 백엔드 배포 → 확인 → 옛 키 폐기 순서로 바꾼다.

  1. 콘솔 키 화면에서 새 secret key를 누른다. 전체 값은 이 창에서만 보인다.
  2. 백엔드의 sk_를 새 값으로 바꾸고 배포한다. 이 시점에 두 키가 모두 살아 있다.
  3. 새 키로 서명한 토큰으로 접속이 되는지, 서버 API가 도는지 확인한다.
  4. 콘솔에서 옛 키를 폐기한다.

폐기를 먼저 하지 않는다. 옛 키를 먼저 끄면 그 키로 서명하던 백엔드가 그 순간 멈춘다.

배포한 뒤에도 브라우저에는 옛 키로 서명된 토큰이 남아 있다. 토큰의 kid가 가리키는 키를 엔진이 확인하므로, 옛 키를 폐기하지 않는 동안 그 토큰들은 그대로 동작한다. 토큰 수명이 한 바퀴 돌면(기본 1시간) 나가 있는 토큰이 전부 새 키로 갈린다 — 그때 폐기하면 아무도 튕기지 않는다. 더 빨리 폐기해도 옛 토큰은 다음 호출에서 새 토큰으로 갈린다.

pk_도 모양은 같다. 한 가지가 더 있다 — 허용 origin은 앱이 아니라 키마다 붙어 있다. 목록이 빈 pk_는 어떤 브라우저 페이지도 받지 못하므로, 새 키를 발급할 때 지금 키가 가진 origin을 그대로 넣는다. origin만 바꾸면 되는 경우에는 키를 바꾸지 않고 키 화면의 허용 origin 칸을 눌러 같은 키의 목록을 고친다.

폐기는 즉시 효력이 있고 되돌릴 수 없다. 키를 잃어도 데이터는 잃지 않는다 — 유저·방·메시지는 앱에 달려 있다.

운영과 개발은 키가 아니라 앱으로 가른다. 앱이 테넌트이므로 데이터의 경계도 앱이다. 앱을 둘 만들고 콘솔에서 프로덕션·개발 라벨을 붙인다.