feat(browse): pty-session-lease registry — stable sessionId + lease lifecycle

Foundation for Commit 2 of the long-lived-sidebar PR. Separates two
concerns that pre-v1.44 were conflated under one token:

  * sessionId — stable, non-secret identifier for a single PTY session.
    Safe to log, safe in URLs, safe in DevTools. Identifies "this terminal,"
    not "you're allowed to use this terminal."
  * lease — server-side bookkeeping that maps sessionId → expiresAt.
    Re-attach within the lease window resumes the same PTY; expiry tears
    it down.

The companion attach-token primitive (short-lived 30s bearer) reuses the
existing browse/src/pty-session-cookie.ts module unchanged — the lease
adds a name-space alongside, it doesn't replace anything.

Codex outside-voice (T1 of the eng review) flagged the original D4
"token IS sessionId" design as conflating identity with auth. The fix
is this lease registry: re-attach URLs carry the stable sessionId
(loggable), the short-lived attachToken stays out of logs.

API:
  * mintLease() → { sessionId, expiresAt }
  * validateLease(sessionId) → { ok: true, expiresAt } | { ok: false }
  * refreshLease(sessionId) — validate-first, never resurrects expired
    leases. Security-critical: the 30-min TTL is what bounds blast
    radius for a leaked attachToken whose lease should have GC'd.
  * revokeLease(sessionId) — explicit dispose path.
  * leaseCount() — observability helper.
  * __resetLeases() — test-only.

TTL env knob (GSTACK_PTY_LEASE_TTL_MS) lets v1.44 e2e tests compress
the detach window to 1s instead of waiting 30 minutes per assertion.

Server.ts wiring + /pty-session shape change + /pty-restart + /pty-dispose
+ /pty-session/reattach all land in subsequent commits in this branch.

Test (browse/test/pty-session-lease.test.ts):
  * 8 cases pinning mint uniqueness, validate-first refresh contract,
    revoke idempotency, null/undefined tolerance, and the negative case
    that refresh never resurrects a revoked lease (same code path as
    expired-and-pruned).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

browse/src/pty-session-lease.ts

@@ -0,0 +1,137 @@
+/**
+ * PTY session lease registry (v1.44+).
+ *
+ * Separates two concerns that pre-v1.44 were conflated under one token:
+ *
+ *  - **sessionId** — stable, non-secret identifier for a single PTY session.
+ *    Safe to log, safe to include in URLs and server access logs, safe to
+ *    keep in DevTools. Identifies "this terminal," not "you're allowed to
+ *    use this terminal."
+ *
+ *  - **attachToken** — secret, short-lived (30 s) bearer credential that
+ *    grants the WS upgrade for ONE attach attempt against a session. Minted
+ *    on every /pty-session and /pty-session/reattach call; revoked when
+ *    the WS upgrade consumes it. Kept out of logs.
+ *
+ *  - **lease** — server-side bookkeeping that maps sessionId → expiresAt.
+ *    Re-attach within the lease window resumes the same PTY (and replays
+ *    the ring buffer from terminal-agent). Lease expiry tears down the
+ *    session.
+ *
+ * Codex outside-voice (T1 of the eng review) pushed for this separation:
+ * "the auth token IS the session id" collapsed identity into a secret,
+ * meaning re-attach URLs and logs carry the bearer credential. The lease
+ * model fixes that without changing the user experience.
+ *
+ * Mint cadence:
+ *  - Initial /pty-session: mint sessionId + lease + attachToken (one round trip).
+ *  - /pty-session/reattach: validate sessionId/lease, mint fresh attachToken.
+ *  - /pty-restart: revoke old lease, mint fresh sessionId + lease + attachToken.
+ *  - /pty-dispose: revoke lease (and the terminal-agent disposes the PTY).
+ *
+ * Lease TTL is env-overridable so v1.44 e2e tests can compress detach
+ * windows to 1 s instead of waiting 30 minutes per assertion.
+ */
+import * as crypto from 'crypto';
+
+interface Lease {
+  createdAt: number;
+  expiresAt: number;
+}
+
+const LEASE_TTL_MS = parseInt(
+  process.env.GSTACK_PTY_LEASE_TTL_MS || `${30 * 60 * 1000}`,
+  10,
+); // 30 minutes default; covers idle-but-engaged user sessions
+const MAX_LEASES = 10_000;
+const leases = new Map<string, Lease>();
+
+/**
+ * Mint a fresh sessionId + lease. Returns the non-secret sessionId and
+ * the expiry timestamp (caller surfaces both to the client). Never throws.
+ */
+export function mintLease(): { sessionId: string; expiresAt: number } {
+  const sessionId = crypto.randomBytes(32).toString('base64url');
+  const now = Date.now();
+  const expiresAt = now + LEASE_TTL_MS;
+  leases.set(sessionId, { createdAt: now, expiresAt });
+  pruneExpired(now);
+  return { sessionId, expiresAt };
+}
+
+/**
+ * Check whether a lease is still valid (exists AND not expired). Returns
+ * the current expiresAt for valid leases; null otherwise. Lazily prunes
+ * stale entries.
+ */
+export function validateLease(sessionId: string | null | undefined): { ok: true; expiresAt: number } | { ok: false } {
+  if (!sessionId) return { ok: false };
+  const lease = leases.get(sessionId);
+  if (!lease) {
+    pruneExpired(Date.now());
+    return { ok: false };
+  }
+  if (Date.now() > lease.expiresAt) {
+    leases.delete(sessionId);
+    pruneExpired(Date.now());
+    return { ok: false };
+  }
+  return { ok: true, expiresAt: lease.expiresAt };
+}
+
+/**
+ * Extend the lease's expiresAt to `now + LEASE_TTL_MS`. Caller should
+ * gate refresh on `expiresAt - now < REFRESH_THRESHOLD` (D10 lazy
+ * refresh: avoid refreshing on every keepalive when the lease is
+ * comfortably far from expiry).
+ *
+ * Returns `{ ok: true, expiresAt }` on success, `{ ok: false }` if the
+ * lease is unknown or already expired (the agent must close the WS and
+ * surface auth-invalid). Critical security invariant: never resurrect
+ * an expired lease — the 30-min TTL is what bounds blast radius for a
+ * leaked attach token whose lease should have been GC'd.
+ */
+export function refreshLease(sessionId: string | null | undefined): { ok: true; expiresAt: number } | { ok: false } {
+  if (!sessionId) return { ok: false };
+  const lease = leases.get(sessionId);
+  if (!lease) return { ok: false };
+  const now = Date.now();
+  if (now > lease.expiresAt) {
+    leases.delete(sessionId);
+    return { ok: false };
+  }
+  lease.expiresAt = now + LEASE_TTL_MS;
+  return { ok: true, expiresAt: lease.expiresAt };
+}
+
+/**
+ * Drop a lease. Called on explicit dispose (/pty-dispose, /pty-restart,
+ * WS close with code 4001) and on session timeout in terminal-agent.
+ */
+export function revokeLease(sessionId: string | null | undefined): void {
+  if (!sessionId) return;
+  leases.delete(sessionId);
+}
+
+/** Returns the lease count — test + observability helper. */
+export function leaseCount(): number {
+  return leases.size;
+}
+
+/** Test-only reset. */
+export function __resetLeases(): void {
+  leases.clear();
+}
+
+function pruneExpired(now: number): void {
+  let checked = 0;
+  for (const [sessionId, lease] of leases) {
+    if (checked++ >= 20) break;
+    if (lease.expiresAt <= now) leases.delete(sessionId);
+  }
+  while (leases.size > MAX_LEASES) {
+    const first = leases.keys().next().value;
+    if (!first) break;
+    leases.delete(first);
+  }
+}