@sleep2agi/commhub-server 0.9.0-preview.69 → 0.9.0-preview.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.69",
+  "version": "0.9.0-preview.70",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/auth-sessions-http.test.ts

@@ -0,0 +1,250 @@
+// 登录会话:闲置过期 + 「登录设备」列表 + 退出其他设备。
+//
+// 生产上 user-login 令牌一次登录一条、从不过期也不回收,泄漏任何一条就等于那个账号(多为管理员)。
+// 这里的每一条在 main 上都是红的:main 没有闲置过期(旧令牌永远有效)、登录响应不带 token_id、
+// /api/auth/sessions* 端点不存在。正控:在用的会话、显式 API 令牌、节点令牌照常可用。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode, createToken } from "./auth.js";
+import { db, hashToken } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-sessions-"));
+let BASE = "";
+let hub: any = null;
+const PW = "SessionsPassw0rd!";
+let USER = "", userId = "", NET = "", ntok = "", apiToken = "";
+
+const auth = (t: string) => ({ Authorization: `Bearer ${t}` });
+async function call(token: string, method: string, path: string, body?: unknown, extra: Record<string, string> = {}) {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? auth(token) : {}), ...(body === undefined ? {} : { "Content-Type": "application/json" }), ...extra },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+async function loginAs(label?: string, ua = "anet-test-agent/1.0") {
+  const r = await call("", "POST", "/api/auth/login", { username: USER, password: PW, ...(label ? { client_label: label } : {}) }, { "User-Agent": ua });
+  expect(r.status).toBe(200);
+  return r.body as { token: string; token_id: string };
+}
+// 把某条令牌的「最近使用」拨回 days 天前(created_at 一起拨,模拟一条很早签发、之后没再用过的令牌)。
+function ageToken(token: string, days: number) {
+  db.run(
+    "UPDATE api_tokens SET last_used_at = datetime('now', ?1), created_at = datetime('now', ?1) WHERE token_hash = ?2",
+    [`-${days} days`, hashToken(token)],
+  );
+}
+function neverUsed(token: string, days: number) {
+  db.run("UPDATE api_tokens SET last_used_at = NULL, created_at = datetime('now', ?1) WHERE token_hash = ?2", [`-${days} days`, hashToken(token)]);
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  // 这里每个用例都真走 POST /api/auth/login 签发会话;默认的每 IP 登录限流会在第 ~20 次开始 429。
+  process.env.COMMHUB_LOGIN_IP_MAX = "1000";
+  delete process.env.COMMHUB_SESSION_IDLE_DAYS;
+  USER = `sess_user_${Date.now()}`;
+  const reg = register(USER, PW);
+  userId = reg.user!.user_id; NET = reg.network_id!;
+  const minted = createNetworkTokenForNode(userId, NET, "sess-node", "node_sess_1");
+  expect(minted.ok).toBe(true);
+  ntok = minted.token!;
+  const api = createToken(userId, "ci-script");
+  expect(api.ok).toBe(true);
+  apiToken = api.token!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("login / register identify the issued token", () => {
+  test("login returns token_id of the token it returned (and stays backward-compatible)", async () => {
+    const r = await call("", "POST", "/api/auth/login", { username: USER, password: PW });
+    expect(r.status).toBe(200);
+    expect(r.body.ok).toBe(true);
+    expect(typeof r.body.token).toBe("string");
+    expect(r.body.token_id).toMatch(/^tok_/);
+    const row = db.get<any>("SELECT token_id FROM api_tokens WHERE token_hash = ?1", hashToken(r.body.token));
+    expect(row.token_id).toBe(r.body.token_id);
+  });
+  test("register returns token_id", async () => {
+    const r = await call("", "POST", "/api/auth/register", { username: `sess_reg_${Date.now()}`, password: PW });
+    expect(r.status).toBe(200);
+    expect(r.body.token_id).toMatch(/^tok_/);
+    const row = db.get<any>("SELECT token_id, name FROM api_tokens WHERE token_hash = ?1", hashToken(r.body.token));
+    expect(row.token_id).toBe(r.body.token_id);
+    expect(row.name).toBe("user-login");
+  });
+});
+
+describe("sliding idle expiry (default 30 days)", () => {
+  test("a login token idle past the window is rejected with token_expired", async () => {
+    const s = await loginAs();
+    ageToken(s.token, 31);
+    const r = await call(s.token, "GET", "/api/auth/me");
+    expect(r.status).toBe(401);
+    expect(r.body.error).toBe("token_expired");
+    // 同一条 401 改写也覆盖走统一 requireAuth 的 REST 端点
+    const r2 = await call(s.token, "GET", "/api/sessions");
+    expect(r2.status).toBe(401);
+    expect(r2.body.error).toBe("token_expired");
+  });
+  test("a login token that was never used counts idle time from created_at", async () => {
+    const s = await loginAs();
+    neverUsed(s.token, 45);
+    const r = await call(s.token, "GET", "/api/auth/me");
+    expect(r.status).toBe(401);
+    expect(r.body.error).toBe("token_expired");
+  });
+  test("an old but recently used login token stays valid (the window slides)", async () => {
+    const s = await loginAs();
+    // 90 天前签发,2 天前还在用
+    db.run("UPDATE api_tokens SET created_at = datetime('now', '-90 days'), last_used_at = datetime('now', '-2 days') WHERE token_hash = ?1", [hashToken(s.token)]);
+    const r = await call(s.token, "GET", "/api/auth/me");
+    expect(r.status).toBe(200);
+    // 使用把 last_used_at 推到现在(超过节流间隔,必须写)
+    const row = db.get<any>("SELECT last_used_at >= datetime('now', '-60 seconds') AS fresh FROM api_tokens WHERE token_hash = ?1", hashToken(s.token));
+    expect(row.fresh).toBe(1);
+  });
+  test("last_used_at is written at most once per hour per token", async () => {
+    const s = await loginAs();
+    db.run("UPDATE api_tokens SET last_used_at = datetime('now', '-10 minutes') WHERE token_hash = ?1", [hashToken(s.token)]);
+    const before = db.get<any>("SELECT last_used_at FROM api_tokens WHERE token_hash = ?1", hashToken(s.token)).last_used_at;
+    expect((await call(s.token, "GET", "/api/auth/me")).status).toBe(200);
+    const after = db.get<any>("SELECT last_used_at FROM api_tokens WHERE token_hash = ?1", hashToken(s.token)).last_used_at;
+    expect(after).toBe(before);
+  });
+  test("a truly invalid token still says invalid, not expired", async () => {
+    const r = await call("utok_00000000000000000000000000000000", "GET", "/api/auth/me");
+    expect(r.status).toBe(401);
+    expect(r.body.error).not.toBe("token_expired");
+  });
+  test("node tokens and explicit API tokens never idle-expire", async () => {
+    neverUsed(ntok, 400);
+    neverUsed(apiToken, 400);
+    const n = await call(ntok, "GET", "/api/auth/me");
+    expect(n.status).toBe(200);
+    expect(n.body.credential.kind).toBe("node");
+    expect((await call(apiToken, "GET", "/api/auth/me")).status).toBe(200);
+  });
+  test("COMMHUB_SESSION_IDLE_DAYS configures the window; 0 disables it", async () => {
+    const s = await loginAs();
+    ageToken(s.token, 10);
+    process.env.COMMHUB_SESSION_IDLE_DAYS = "7";
+    try {
+      expect((await call(s.token, "GET", "/api/auth/me")).body.error).toBe("token_expired");
+      process.env.COMMHUB_SESSION_IDLE_DAYS = "0";
+      expect((await call(s.token, "GET", "/api/auth/me")).status).toBe(200);
+    } finally {
+      delete process.env.COMMHUB_SESSION_IDLE_DAYS;
+    }
+  });
+});
+
+describe("GET /api/auth/sessions", () => {
+  test("lists my live login sessions with label, user agent and is_current", async () => {
+    const a = await loginAs("Android · 0.2.150", "okhttp/4");
+    const b = await loginAs("macOS · 0.2.150", "Mozilla/5.0 (Macintosh)");
+    const dead = await loginAs("stale");
+    ageToken(dead.token, 40);
+    const r = await call(b.token, "GET", "/api/auth/sessions");
+    expect(r.status).toBe(200);
+    expect(r.body.idle_timeout_days).toBe(30);
+    expect(r.body.current_token_id).toBe(b.token_id);
+    const ids = r.body.sessions.map((x: any) => x.token_id);
+    expect(ids).toContain(a.token_id);
+    expect(ids).toContain(b.token_id);
+    expect(ids).not.toContain(dead.token_id);
+    const me = r.body.sessions.find((x: any) => x.token_id === b.token_id);
+    expect(me.is_current).toBe(true);
+    expect(me.client_label).toBe("macOS · 0.2.150");
+    expect(me.user_agent).toBe("Mozilla/5.0 (Macintosh)");
+    expect(typeof me.created_at).toBe("string");
+    const other = r.body.sessions.find((x: any) => x.token_id === a.token_id);
+    expect(other.is_current).toBe(false);
+    expect(other.client_label).toBe("Android · 0.2.150");
+    // 不泄漏令牌本身或哈希;API 令牌和节点令牌不在列表里
+    expect(JSON.stringify(r.body)).not.toContain("token_hash");
+    expect(JSON.stringify(r.body)).not.toContain(b.token);
+    expect(r.body.sessions.every((x: any) => x.name !== "ci-script" && !String(x.name).startsWith("node:"))).toBe(true);
+  });
+  test("node tokens get 403 user_token_required", async () => {
+    const r = await call(ntok, "GET", "/api/auth/sessions");
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe("user_token_required");
+  });
+  test("no token → 401", async () => {
+    expect((await call("", "GET", "/api/auth/sessions")).status).toBe(401);
+  });
+});
+
+describe("revoking sessions", () => {
+  test("revoke-others keeps the current token and leaves API and node tokens alone", async () => {
+    const keep = await loginAs("keep");
+    const other1 = await loginAs("other1");
+    const other2 = await loginAs("other2");
+    const r = await call(keep.token, "POST", "/api/auth/sessions/revoke-others");
+    expect(r.status).toBe(200);
+    expect(r.body.kept_token_id).toBe(keep.token_id);
+    expect(r.body.revoked).toBeGreaterThanOrEqual(2);
+    expect((await call(keep.token, "GET", "/api/auth/me")).status).toBe(200);
+    expect((await call(other1.token, "GET", "/api/auth/me")).status).toBe(401);
+    expect((await call(other2.token, "GET", "/api/auth/me")).status).toBe(401);
+    expect((await call(ntok, "GET", "/api/auth/me")).status).toBe(200);
+    expect((await call(apiToken, "GET", "/api/auth/me")).status).toBe(200);
+    const list = await call(keep.token, "GET", "/api/auth/sessions");
+    expect(list.body.sessions.map((x: any) => x.token_id)).toEqual([keep.token_id]);
+    const audit = db.get<any>("SELECT detail FROM audit_log WHERE action = 'sessions_revoked_others' AND target_id = ?1", keep.token_id);
+    expect(audit?.detail).toMatch(/^revoked=\d+$/);
+  });
+  test("revoke-others refuses node tokens and non-session tokens", async () => {
+    const r = await call(ntok, "POST", "/api/auth/sessions/revoke-others");
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe("user_token_required");
+    const s = await loginAs("survivor");
+    const viaApi = await call(apiToken, "POST", "/api/auth/sessions/revoke-others");
+    expect(viaApi.status).toBe(403);
+    expect(viaApi.body.error).toBe("session_token_required");
+    expect((await call(s.token, "GET", "/api/auth/me")).status).toBe(200);
+  });
+  test("DELETE /api/auth/sessions/:id revokes one other session", async () => {
+    const me = await loginAs("me");
+    const victim = await loginAs("victim");
+    const r = await call(me.token, "DELETE", `/api/auth/sessions/${victim.token_id}`);
+    expect(r.status).toBe(200);
+    expect(r.body.was_current).toBe(false);
+    expect((await call(victim.token, "GET", "/api/auth/me")).status).toBe(401);
+    expect((await call(me.token, "GET", "/api/auth/me")).status).toBe(200);
+    expect(db.get<any>("SELECT 1 AS x FROM audit_log WHERE action = 'session_revoked' AND target_id = ?1", victim.token_id)?.x).toBe(1);
+  });
+  test("DELETE of my own session is a logout", async () => {
+    const me = await loginAs("logout");
+    const r = await call(me.token, "DELETE", `/api/auth/sessions/${me.token_id}`);
+    expect(r.status).toBe(200);
+    expect(r.body.was_current).toBe(true);
+    expect((await call(me.token, "GET", "/api/auth/me")).status).toBe(401);
+  });
+  test("DELETE cannot reach API tokens, node tokens, or another user's session", async () => {
+    const me = await loginAs("guard");
+    const apiRow = db.get<any>("SELECT token_id FROM api_tokens WHERE token_hash = ?1", hashToken(apiToken));
+    const ntokRow = db.get<any>("SELECT token_id FROM api_tokens WHERE token_hash = ?1", hashToken(ntok));
+    expect((await call(me.token, "DELETE", `/api/auth/sessions/${apiRow.token_id}`)).status).toBe(404);
+    expect((await call(me.token, "DELETE", `/api/auth/sessions/${ntokRow.token_id}`)).status).toBe(404);
+    const stranger = register(`sess_stranger_${Date.now()}`, PW);
+    expect((await call(me.token, "DELETE", `/api/auth/sessions/${stranger.token_id}`)).status).toBe(404);
+    expect((await call(stranger.token!, "GET", "/api/auth/me")).status).toBe(200);
+    expect((await call(ntok, "DELETE", `/api/auth/sessions/${me.token_id}`)).status).toBe(403);
+    expect((await call(me.token, "GET", "/api/auth/me")).status).toBe(200);
+  });
+});

package/src/auth.ts

@@ -43,6 +43,7 @@ export interface AuthResult {
   error?: string;
   user?: AuthUser;
   token?: string;           // user token (utok_)
+  token_id?: string;        // api_tokens.token_id of `token` — lets a client tell which row in GET /api/auth/sessions is itself
   network_token?: string;   // network token (ntok_) for default network
   network_id?: string;
   // #261 P0-2 (2026-06-28): true when the logged-in user still has the
@@ -61,7 +62,7 @@ function validatePasswordStrength(password: string, label = "password"): string
   return null;
 }
 
-export function register(username: string, password: string, email?: string, displayName?: string, opts: { issueTokens?: boolean } = {}): AuthResult {
+export function register(username: string, password: string, email?: string, displayName?: string, opts: { issueTokens?: boolean; client?: SessionClientInfo } = {}): AuthResult {
   if (!username || username.length < 2) return { ok: false, error: "username must be at least 2 characters" };
   if (username.length > 50) return { ok: false, error: "username too long (max 50)" };
   if (!/^[a-zA-Z0-9_\-\u4e00-\u9fff]+$/.test(username)) return { ok: false, error: "username contains invalid characters" };
@@ -135,8 +136,8 @@ export function register(username: string, password: string, email?: string, dis
   const userToken = generateUserToken();
   const userTokenId = generateId("tok");
   db.run(
-    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-    [userTokenId, hashToken(userToken), userId, null, "user-login", "user"]
+    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, client_label, user_agent) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+    [userTokenId, hashToken(userToken), userId, null, "user-login", "user", cleanClientField(opts.client?.label, 64), cleanClientField(opts.client?.userAgent, 256)]
   );
 
   // Network token (ntok_) — bound to default network, for agent-node
@@ -151,12 +152,13 @@ export function register(username: string, password: string, email?: string, dis
     ok: true,
     user: { user_id: userId, username, display_name: displayName || username, email: email || null, role: isFirstUser ? "admin" : "user" },
     token: userToken,
+    token_id: userTokenId,
     network_token: networkToken,
     network_id: networkId,
   };
 }
 
-export function login(username: string, password: string): AuthResult {
+export function login(username: string, password: string, client: SessionClientInfo = {}): AuthResult {
   const user = db.get<any>(
     "SELECT user_id, username, password_hash, display_name, email, role, must_change_password FROM users WHERE username = ?1",
     username);
@@ -200,8 +202,8 @@ export function login(username: string, password: string): AuthResult {
   const userToken = generateUserToken();
   const tokenId = generateId("tok");
   db.run(
-    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-    [tokenId, hashToken(userToken), user.user_id, null, "user-login", "user"]
+    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, client_label, user_agent) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+    [tokenId, hashToken(userToken), user.user_id, null, "user-login", "user", cleanClientField(client.label, 64), cleanClientField(client.userAgent, 256)]
   );
 
   // Find default network
@@ -217,6 +219,7 @@ export function login(username: string, password: string): AuthResult {
     ok: true,
     user: { user_id: user.user_id, username: user.username, display_name: user.display_name, email: user.email, role: user.role },
     token,
+    token_id: tokenId,
     network_id: networkId,
     // #261 P0-2 — only include field when truthy (back-compat; old clients
     // don't see this field at all unless their account is flagged).
@@ -288,16 +291,64 @@ export function createNetworkTokenForNode(userId: string, networkId: string, nod
   return { ok: true, token, token_id: tokenId, ...(nodeId ? { node_id: nodeId } : {}) };
 }
 
+// ── 登录会话(login session)令牌 ──
+// 「会话令牌」= scope='user' 且不绑网络的 utok_:登录 / 注册签发的 user-login、改密码后换发的
+// password-change、管理员重置签发的 admin-reset。它们代表「某台设备上的一次登录」,
+// 由 GET /api/auth/sessions 列出、可被「退出其他设备」撤销,并且**闲置 N 天自动过期**(滑动窗口,
+// 以 last_used_at 计,从没用过的以 created_at 计)。
+// 不受影响:POST /api/auth/tokens 显式创建的 API 令牌(scope='full')、节点 / 网络令牌(network_id 非空)。
+// 它们是给脚本和节点长期用的凭据,由各自的管理入口撤销,不该因为一段时间没被用就失效。
+const SESSION_TOKEN_SQL = "scope = 'user' AND network_id IS NULL";
+// last_used_at 最多每小时写一次:每个请求都会解析令牌,原来每次都 UPDATE。
+// 以小时为粒度对一个以天计的闲置窗口没有影响。
+const LAST_USED_WRITE_INTERVAL_SECONDS = 3600;
+
+export type SessionClientInfo = { label?: unknown; userAgent?: unknown };
+
+function cleanClientField(value: unknown, max: number): string | null {
+  if (typeof value !== "string") return null;
+  const cleaned = value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, max);
+  return cleaned || null;
+}
+
+/** 会话令牌闲置多少天后过期;COMMHUB_SESSION_IDLE_DAYS,默认 30,0 = 关闭闲置过期。每次读,测试可以改。 */
+export function sessionIdleDays(): number {
+  const raw = process.env.COMMHUB_SESSION_IDLE_DAYS;
+  if (raw === undefined || raw.trim() === "") return 30;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 30;
+}
+
+// datetime('now', ?N) 的偏移参数;PgAdapter 把它译成 NOW() + $N::INTERVAL。
+function idleCutoffOffset(): string | null {
+  const days = sessionIdleDays();
+  return days > 0 ? `-${Math.round(days * 86400)} seconds` : null;
+}
+
+// 已按闲置过期的会话令牌:只有 resolveToken 拒绝之后才查,用来把 401 说清楚是「过期」而不是「无效」。
+export function isExpiredSessionToken(token: string): boolean {
+  const cutoff = idleCutoffOffset();
+  if (!token || !cutoff) return false;
+  const row = db.get<any>(
+    `SELECT token_id FROM api_tokens
+     WHERE token_hash = ?1 AND ${SESSION_TOKEN_SQL} AND revoked_at IS NULL
+       AND COALESCE(last_used_at, created_at) < datetime('now', ?2)`,
+    hashToken(token), cutoff);
+  return !!row;
+}
+
 export function resolveToken(token: string): { user: AuthUser; networkId: string | null; tokenName: string | null; tokenId: string | null } | null {
   const tHash = hashToken(token);
+  const cutoff = idleCutoffOffset();
   const row = db.get<any>(
     `SELECT t.token_id, t.user_id, t.network_id, t.scope, t.name AS token_name,
             u.username, u.display_name, u.email, u.role
      FROM api_tokens t JOIN users u ON t.user_id = u.user_id
      WHERE t.token_hash = ?1
        AND (t.expires_at IS NULL OR t.expires_at > datetime('now'))
-       AND t.revoked_at IS NULL`,
-    tHash);
+       AND t.revoked_at IS NULL${cutoff ? `
+       AND NOT (t.scope = 'user' AND t.network_id IS NULL AND COALESCE(t.last_used_at, t.created_at) < datetime('now', ?2))` : ""}`,
+    ...(cutoff ? [tHash, cutoff] : [tHash]));
 
   if (!row) return null;
 
@@ -306,8 +357,11 @@ export function resolveToken(token: string): { user: AuthUser; networkId: string
   // 在这里拒绝,所有 REST / MCP / SSE 路径一起生效(含升级前就签发、后来才被设为受限的令牌)。
   if (row.network_id && isAgentRestricted(row.user_id, row.network_id)) return null;
 
-  // Update last_used
-  db.run("UPDATE api_tokens SET last_used_at = datetime('now') WHERE token_hash = ?1", [tHash]);
+  // Update last_used(节流:见 LAST_USED_WRITE_INTERVAL_SECONDS)
+  db.run(
+    "UPDATE api_tokens SET last_used_at = datetime('now') WHERE token_id = ?1 AND (last_used_at IS NULL OR last_used_at < datetime('now', ?2))",
+    [row.token_id, `-${LAST_USED_WRITE_INTERVAL_SECONDS} seconds`]
+  );
 
   return {
     user: { user_id: row.user_id, username: row.username, display_name: row.display_name, email: row.email, role: row.role },
@@ -432,6 +486,47 @@ export function revokeOtherUserTokens(userId: string, exceptTokenId?: string | n
   return result.changes;
 }
 
+export type LoginSession = {
+  token_id: string;
+  name: string;
+  created_at: string;
+  last_used_at: string | null;
+  client_label: string | null;
+  user_agent: string | null;
+  is_current: boolean;
+};
+
+/** 我的登录会话(未过期、未撤销),最近使用的在前。 */
+export function listSessions(userId: string, currentTokenId: string | null): LoginSession[] {
+  const cutoff = idleCutoffOffset();
+  const rows = db.all<any>(
+    `SELECT token_id, name, created_at, last_used_at, client_label, user_agent FROM api_tokens
+     WHERE user_id = ?1 AND ${SESSION_TOKEN_SQL} AND revoked_at IS NULL${cutoff ? `
+       AND COALESCE(last_used_at, created_at) >= datetime('now', ?2)` : ""}
+     ORDER BY COALESCE(last_used_at, created_at) DESC, created_at DESC`,
+    ...(cutoff ? [userId, cutoff] : [userId]));
+  return rows.map((r) => ({
+    token_id: r.token_id,
+    name: r.name,
+    created_at: r.created_at,
+    last_used_at: r.last_used_at ?? null,
+    client_label: r.client_label ?? null,
+    user_agent: r.user_agent ?? null,
+    is_current: !!currentTokenId && r.token_id === currentTokenId,
+  }));
+}
+
+/** 撤销我的一个登录会话;可以是当前这个(= 退出登录)。不是会话令牌(API 令牌 / 节点令牌)时当作不存在。 */
+export function revokeSession(userId: string, tokenId: string): { ok: boolean; error?: string } {
+  const result = db.run(`DELETE FROM api_tokens WHERE token_id = ?1 AND user_id = ?2 AND ${SESSION_TOKEN_SQL}`, [tokenId, userId]);
+  return result.changes > 0 ? { ok: true } : { ok: false, error: "session_not_found" };
+}
+
+/** 退出其他所有设备:撤销我除当前之外的全部登录会话(含已闲置过期的)。API 令牌、节点令牌不动。 */
+export function revokeOtherSessions(userId: string, currentTokenId: string): number {
+  return db.run(`DELETE FROM api_tokens WHERE user_id = ?1 AND ${SESSION_TOKEN_SQL} AND token_id != ?2`, [userId, currentTokenId]).changes;
+}
+
 export function changePassword(userId: string, oldPassword: string, newPassword: string, currentTokenId?: string | null): { ok: boolean; error?: string; revoked?: number } {
   const passwordError = validatePasswordStrength(newPassword, "new password");
   if (passwordError) return { ok: false, error: passwordError };

package/src/db.ts

@@ -640,6 +640,9 @@ for (const ddl of [
   "ALTER TABLE api_tokens ADD COLUMN revoked_at TEXT",
   "ALTER TABLE api_tokens ADD COLUMN role TEXT",
   "ALTER TABLE api_tokens ADD COLUMN bound_node_id TEXT",
+  // 登录会话的设备标识(GET /api/auth/sessions 显示用):客户端自报的 client_label + 登录请求的 User-Agent。
+  "ALTER TABLE api_tokens ADD COLUMN client_label TEXT",
+  "ALTER TABLE api_tokens ADD COLUMN user_agent TEXT",
 ]) {
   try { db.exec(ddl); }
   catch (e: any) {

package/src/server.ts

@@ -20,7 +20,7 @@ import { canMessageAgent, isAgentRestricted, listAgentGrants, getAgentAccessMode
 import { validateAvatarUrl } from "./avatar-validate.js";
 import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-validate.js";
 import { daemonDefaultWorkdirRoot } from "./create-node-validate.js";
-import { register, login, resolveToken, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getNetworkHumans, getUserNetworkRole, addNetworkMember, adminCreateUser, listUsersWithMemberships, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
+import { register, login, resolveToken, isExpiredSessionToken, sessionIdleDays, listSessions, revokeSession, revokeOtherSessions, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getNetworkHumans, getUserNetworkRole, addNetworkMember, adminCreateUser, listUsersWithMemberships, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
 import { abortRename, cleanupCommittedRenameSessions, commitRename, prepareRename, resolveCanonicalAlias } from "./rename.js";
 import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
 import { clientRequestIdFromMeta, idempotentTaskId, idempotentTaskMatches, type StoredIdempotentTask } from "./task-idempotency.js";
@@ -260,6 +260,20 @@ function nodeMayRenameTxn(resolved: { networkId: string | null; tokenName: strin
   return self === txn.old_alias || self === txn.new_alias;
 }
 
+// 登录会话闲置过期(auth.ts sessionIdleDays):resolveToken 把过期令牌当作不存在,各端点于是回各自的
+// 401("invalid token" / "unauthorized" / "auth required" …)。客户端要据此提示「登录已过期」而不是
+// 「令牌无效」,所以在唯一的出口处统一改写:请求带的令牌恰好是一个已闲置过期的会话令牌时,
+// 401 的正文换成 { error: "token_expired" }。状态码不变;只在已经是 401 时才多查一次库。
+function explainExpiredSession(req: Request, res: Response | undefined): Response | undefined {
+  if (!res || res.status !== 401) return res;
+  const token = requestToken(req);
+  if (!token || !isExpiredSessionToken(token)) return res;
+  return withCors(req, Response.json(
+    { ok: false, error: "token_expired", message: "login session expired after inactivity; sign in again" },
+    { status: 401 },
+  ));
+}
+
 function userTokenRequired(req: Request): Response {
   return withCors(req, Response.json({ ok: false, error: "user_token_required", message: "this endpoint acts on a user account; node tokens cannot use it" }, { status: 403 }));
 }
@@ -848,7 +862,7 @@ return Bun.serve({
 
   async fetch(req, server) {
     // 2026-09-16 —— 所有 JSON/文本响应在客户端要求时 gzip(见 http-gzip.ts);SSE/流式/二进制原样。
-    return maybeGzipResponse(req, await (async (): Promise<Response | undefined> => {
+    return maybeGzipResponse(req, explainExpiredSession(req, await (async (): Promise<Response | undefined> => {
     const url = new URL(req.url, `http://localhost:${PORT}`);
 
     // ── CORS preflight ──
@@ -1134,7 +1148,7 @@ return Bun.serve({
       }
       try {
         const body = await req.json() as any;
-        const result = register(body.username, body.password, body.email, body.display_name);
+        const result = register(body.username, body.password, body.email, body.display_name, { client: { label: body.client_label, userAgent: req.headers.get("user-agent") } });
         if (result.ok) logAudit(result.user!.user_id, body.username, "register", "user", result.user!.user_id);
         return withCors(req, Response.json(result, { status: result.ok ? 200 : 400 }));
       } catch (e: any) {
@@ -1162,7 +1176,7 @@ return Bun.serve({
             { status: 429, headers: { "Retry-After": String(Math.ceil((lock.retryAfterMs ?? 1000) / 1000)) } }
           ));
         }
-        const result = login(body.username, body.password);
+        const result = login(body.username, body.password, { label: body.client_label, userAgent: req.headers.get("user-agent") });
         if (result.ok) {
           sharedLoginFailureLockout.recordSuccess(body.username);
           logAudit(result.user!.user_id, body.username, "login", "user", result.user!.user_id);
@@ -1354,6 +1368,46 @@ return Bun.serve({
       return withCors(req, Response.json(result, { status: result.ok ? 200 : 404 }));
     }
 
+    // ── 登录设备:列出 / 撤销我的登录会话(见 auth.ts「登录会话令牌」) ──
+    // 只接受用户令牌:节点令牌不是一次登录,也不能替签发它的人管账号(同 #2086)。
+    if (url.pathname === "/api/auth/sessions" && req.method === "GET") {
+      const token = requestToken(req, { allowQueryToken: false });
+      if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      const resolved = resolveToken(token);
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (isNodeCredential(resolved)) return userTokenRequired(req);
+      const sessions = listSessions(resolved.user.user_id, resolved.tokenId);
+      return withCors(req, Response.json({ ok: true, sessions, current_token_id: resolved.tokenId, idle_timeout_days: sessionIdleDays() }));
+    }
+
+    if (url.pathname === "/api/auth/sessions/revoke-others" && req.method === "POST") {
+      const token = requestToken(req, { allowQueryToken: false });
+      if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      const resolved = resolveToken(token);
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (isNodeCredential(resolved)) return userTokenRequired(req);
+      // 当前令牌必须是一次登录会话,否则「保留当前这个」无从说起(API 令牌调用会把所有会话都撤掉)。
+      const current = resolved.tokenId ? listSessions(resolved.user.user_id, resolved.tokenId).find((x) => x.is_current) : undefined;
+      if (!current) return withCors(req, Response.json({ ok: false, error: "session_token_required", message: "call this with a login session token" }, { status: 403 }));
+      const revoked = revokeOtherSessions(resolved.user.user_id, current.token_id);
+      logAudit(resolved.user.user_id, resolved.user.username, "sessions_revoked_others", "token", current.token_id, `revoked=${revoked}`);
+      return withCors(req, Response.json({ ok: true, revoked, kept_token_id: current.token_id }));
+    }
+
+    const sessionDeleteMatch = url.pathname.match(/^\/api\/auth\/sessions\/([^/]+)$/);
+    if (sessionDeleteMatch && req.method === "DELETE") {
+      const token = requestToken(req, { allowQueryToken: false });
+      if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      const resolved = resolveToken(token);
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (isNodeCredential(resolved)) return userTokenRequired(req);
+      const targetId = decodeURIComponent(sessionDeleteMatch[1]);
+      const result = revokeSession(resolved.user.user_id, targetId);
+      const self = targetId === resolved.tokenId;
+      if (result.ok) logAudit(resolved.user.user_id, resolved.user.username, "session_revoked", "token", targetId, self ? "self (logout)" : undefined);
+      return withCors(req, Response.json({ ...result, ...(result.ok ? { was_current: self } : {}) }, { status: result.ok ? 200 : 404 }));
+    }
+
     // ── V3: Network management ──
     if (url.pathname === "/api/networks" && req.method === "GET") {
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
@@ -3990,7 +4044,7 @@ Security: ${SECURITY_LABEL}
 `,
       { status: 200, headers: { "Content-Type": "text/plain; charset=utf-8" } }   // #426
     ));
-    })());
+    })()));
   },
 
   // ── WebSocket handler for tmux terminal streaming ──