《移动游戏产品的架构·商业化与发行工程》2.2 登录态、令牌刷新与多端互踢

// file: src/biz/login-session.ts
// tier: L1
// verify: node --test test/biz/login-session.test.ts

export type DevicePolicy = "single" | "max_two";
export type SessionStatus = "active" | "revoked" | "rotated";

export const ACCESS_TTL_MS = 2 * 60 * 60 * 1000;
export const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000;

export interface SessionRecord {
  readonly sessionId: string;
  readonly familyId: string;
  readonly playerId: string;
  readonly deviceId: string;
  readonly accessToken: string;
  readonly refreshToken: string;
  readonly issuedAt: number;
  readonly accessExpiresAt: number;
  readonly refreshExpiresAt: number;
  readonly status: SessionStatus;
  readonly revokedReason?: string;
}

export interface SessionLedger {
  readonly sequence: number;
  readonly sessions: Readonly<Record<string, SessionRecord>>;
  readonly byAccess: Readonly<Record<string, string>>;
  readonly byRefresh: Readonly<Record<string, string>>;
}

export interface LoginRequest {
  readonly playerId: string;
  readonly deviceId: string;
  readonly nowMs: number;
}

export interface LoginResult {
  readonly ledger: SessionLedger;
  readonly session: SessionRecord;
  readonly kicked: readonly SessionRecord[];
}

export type AuthFailure = "INVALID_ACCESS" | "ACCESS_EXPIRED" | "SESSION_REVOKED";
export type AuthResult =
  | { readonly ok: true; readonly session: SessionRecord }
  | { readonly ok: false; readonly code: AuthFailure };

export type RefreshFailure =
  | "INVALID_REFRESH"
  | "REFRESH_EXPIRED"
  | "SESSION_REVOKED"
  | "REFRESH_REUSE";
export type RefreshResult =
  | { readonly ok: true; readonly ledger: SessionLedger; readonly session: SessionRecord }
  | { readonly ok: false; readonly code: RefreshFailure; readonly ledger: SessionLedger };

export class SessionError extends Error {
  readonly code: string;

  constructor(code: string, message: string) {
    super(message);
    this.name = "SessionError";
    this.code = code;
  }
}

function fail(code: string, message: string): never {
  throw new SessionError(code, message);
}

function requireText(value: string, field: string): string {
  const trimmed = value.trim();
  if (trimmed.length === 0) {
    fail("INVALID_REQUEST", `${field} must not be empty`);
  }
  return trimmed;
}

function requireTime(nowMs: number): number {
  if (!Number.isFinite(nowMs) || nowMs < 0) {
    fail("INVALID_TIME", "nowMs must be a non-negative finite number");
  }
  return nowMs;
}

function setSession(ledger: SessionLedger, record: SessionRecord): SessionLedger {
  return { ...ledger, sessions: { ...ledger.sessions, [record.sessionId]: record } };
}

function appendSession(ledger: SessionLedger, record: SessionRecord): SessionLedger {
  return {
    sequence: ledger.sequence + 1,
    sessions: { ...ledger.sessions, [record.sessionId]: record },
    byAccess: { ...ledger.byAccess, [record.accessToken]: record.sessionId },
    byRefresh: { ...ledger.byRefresh, [record.refreshToken]: record.sessionId },
  };
}

function revoke(record: SessionRecord, reason: string): SessionRecord {
  return { ...record, status: "revoked", revokedReason: reason };
}

export function emptyLedger(): SessionLedger {
  return { sequence: 0, sessions: {}, byAccess: {}, byRefresh: {} };
}

export function activeSessionsFor(ledger: SessionLedger, playerId: string): SessionRecord[] {
  return Object.values(ledger.sessions)
    .filter((session) => session.playerId === playerId && session.status === "active")
    .sort((a, b) => a.issuedAt - b.issuedAt || a.sessionId.localeCompare(b.sessionId));
}

export function login(
  ledger: SessionLedger,
  request: LoginRequest,
  policy: DevicePolicy,
): LoginResult {
  const playerId = requireText(request.playerId, "playerId");
  const deviceId = requireText(request.deviceId, "deviceId");
  const nowMs = requireTime(request.nowMs);
  const active = activeSessionsFor(ledger, playerId);
  const sameDevice = active.filter((session) => session.deviceId === deviceId);
  const others = active.filter((session) => session.deviceId !== deviceId);

  let next: SessionLedger = {
    ...ledger,
    sessions: { ...ledger.sessions },
    byAccess: { ...ledger.byAccess },
    byRefresh: { ...ledger.byRefresh },
  };
  const kicked: SessionRecord[] = [];

  for (const session of sameDevice) {
    next = setSession(next, revoke(session, "replaced"));
  }

  const keepForOtherDevices = policy === "single" ? 0 : 1;
  const excess = Math.max(0, others.length - keepForOtherDevices);
  for (const session of others.slice(0, excess)) {
    const revoked = revoke(session, "device_policy");
    next = setSession(next, revoked);
    kicked.push(revoked);
  }

  const sequence = ledger.sequence + 1;
  const session: SessionRecord = {
    sessionId: `s-${sequence}`,
    familyId: `f-${sequence}`,
    playerId,
    deviceId,
    accessToken: `at-${sequence}`,
    refreshToken: `rt-${sequence}`,
    issuedAt: nowMs,
    accessExpiresAt: nowMs + ACCESS_TTL_MS,
    refreshExpiresAt: nowMs + REFRESH_TTL_MS,
    status: "active",
  };
  next = appendSession(next, session);

  return { ledger: next, session, kicked };
}

export function authenticate(
  ledger: SessionLedger,
  accessToken: string,
  nowMs: number,
): AuthResult {
  const time = requireTime(nowMs);
  const sessionId = ledger.byAccess[accessToken];
  if (sessionId === undefined) {
    return { ok: false, code: "INVALID_ACCESS" };
  }
  const session = ledger.sessions[sessionId];
  if (session === undefined) {
    return { ok: false, code: "INVALID_ACCESS" };
  }
  if (session.status !== "active") {
    return { ok: false, code: "SESSION_REVOKED" };
  }
  if (time >= session.accessExpiresAt) {
    return { ok: false, code: "ACCESS_EXPIRED" };
  }
  return { ok: true, session };
}

export function refresh(
  ledger: SessionLedger,
  refreshToken: string,
  nowMs: number,
): RefreshResult {
  const time = requireTime(nowMs);
  let next: SessionLedger = {
    ...ledger,
    sessions: { ...ledger.sessions },
    byAccess: { ...ledger.byAccess },
    byRefresh: { ...ledger.byRefresh },
  };

  const sessionId = ledger.byRefresh[refreshToken];
  if (sessionId === undefined) {
    return { ok: false, code: "INVALID_REFRESH", ledger: next };
  }
  const current = ledger.sessions[sessionId];
  if (current === undefined) {
    return { ok: false, code: "INVALID_REFRESH", ledger: next };
  }

  if (current.status === "rotated") {
    for (const record of Object.values(next.sessions)) {
      if (record.familyId === current.familyId && record.status === "active") {
        next = setSession(next, revoke(record, "refresh_reuse"));
      }
    }
    return { ok: false, code: "REFRESH_REUSE", ledger: next };
  }
  if (current.status === "revoked") {
    return { ok: false, code: "SESSION_REVOKED", ledger: next };
  }
  if (time >= current.refreshExpiresAt) {
    return { ok: false, code: "REFRESH_EXPIRED", ledger: next };
  }

  next = setSession(next, { ...current, status: "rotated", revokedReason: "rotated" });
  const sequence = next.sequence + 1;
  const rotated: SessionRecord = {
    sessionId: `s-${sequence}`,
    familyId: current.familyId,
    playerId: current.playerId,
    deviceId: current.deviceId,
    accessToken: `at-${sequence}`,
    refreshToken: `rt-${sequence}`,
    issuedAt: time,
    accessExpiresAt: time + ACCESS_TTL_MS,
    refreshExpiresAt: time + REFRESH_TTL_MS,
    status: "active",
  };
  next = appendSession(next, rotated);

  return { ok: true, ledger: next, session: rotated };
}

export function formatSession(session: SessionRecord): string {
  return `${session.sessionId} player=${session.playerId} device=${session.deviceId} status=${session.status} access=${session.accessToken} refresh=${session.refreshToken}`;
}

export function formatLoginResult(result: LoginResult): string {
  const devices = result.kicked.map((session) => session.deviceId).join(",") || "none";
  return `${formatSession(result.session)} kicked=${devices}`;
}