fix(harness): per-session anonymous token prevents session hijacking

[sabbour-squad-backend]

Closes #1079

🤖 Created by sabbour-squad-backend

Summary

Anonymous users no longer share a single oid='anonymous' identity for session ownership. Each anonymous session now gets a cryptographic bearer token that must be presented on subsequent requests. An attacker who guesses a sessionId cannot resume someone else's session without the token.

Changes

• packages/harness/src/runtime/session.ts — Added anonTokenHash field on Session, plus generateAnonSessionToken(), validateAnonSessionToken(), isAnonymousSession(), and getOrCreateSessionResult() helpers. Anonymous session TTL reduced to 10 min.
• packages/harness/src/runtime/sse.ts — Added session_token SSE event type (10 events total).
• packages/web/api/src/functions/converse.ts — On new anonymous session: generates token, sends it via session_token SSE event + X-Anon-Session-Token header. On resumed anonymous session: validates X-Anon-Session-Token header, rejects 403 if invalid.
• packages/harness/src/index.ts — Exports new session helpers.
• Test mocks updated in converse.test.ts and converse-hydration.test.ts.

Security design

• Token entropy: 32 bytes of crypto.randomBytes, base64url-encoded
• Storage: SHA-256 hash stored on session (not the raw token)
• Validation: timingSafeEqual prevents timing side-channels
• Belt-and-suspenders: Anonymous session TTL reduced from 30 min → 10 min
• No impact on authenticated users: Token flow only activates when oid === 'anonymous'

Testing

• 19 new unit tests covering token generation, validation, attack scenarios, and TTL
• All 27 existing converse/hydration tests pass with updated mocks
• Full suite: 1272 passed, 2 pre-existing failures (unrelated React component tests)

Docs and changeset

• Changeset added
• docs-site/docs/ updated (N/A — internal API security hardening)
• docs-site/docs/architecture/v2-implementation-brief.md updated (N/A)
• docs-site/docs/extending/api-endpoints.md — new session_token SSE event type and X-Anon-Session-Token header should be documented (follow-up)
• Pack docs updated (N/A)
• Tests added

[github-actions]

👀 Squad review trail

Current head: 4205830
Last update: New commits landed; the visible trail now points at the current head.
Gate path: Standard path — leela:approved + zapp:approved + nibbler:approved are required on the current head, plus one of docs:approved or docs:not-applicable for the docs gate.
Gate snapshot: ⏳ Missing docs marker (one of docs:approved or docs:not-applicable) on the current head, plus leela:approved + zapp:approved.
Reviewer labels

• Leela: ⏳ awaiting leela:approved
• Zapp: ⏳ awaiting zapp:approved
• Nibbler: ✅ approved via nibbler:approved
• Docs: ⏳ awaiting docs:approved or docs:not-applicable
  Active labels
• nibbler:approved — Code quality review approved

This sticky comment is maintained automatically so label-based squad review leaves an on-PR rationale even when the gate itself is status-check driven.

[sabbour-squad-lead]

APPROVED — Security fix is cryptographically sound (32-byte entropy, SHA-256 hash, timing-safe validation, 10-min TTL, zero auth'd impact). Unit tests comprehensive (19 new tests, 1272 total pass). E2E failures appear transient (deploy also failed). Architecture ready for merge pending gate.

[github-actions]

✅ Leela recorded a architecture approved via leela:approved on head 8d9c334.

This native review mirrors the label-driven squad gate for visibility only.
Merge eligibility still comes from the squad/review-gate status check and the current approval labels.

[github-actions]

✅ Zapp recorded a security approved via zapp:approved on head 8d9c334.

This native review mirrors the label-driven squad gate for visibility only.
Merge eligibility still comes from the squad/review-gate status check and the current approval labels.

[sabbour-squad-lead]

✅ Security Review Approved

PR #1143: Anonymous Session Security

✅ Token Generation: randomBytes(32) — 256 bits cryptographic entropy
✅ Token Storage: SHA-256 hashed (one-way), raw token not stored
✅ Validation: timingSafeEqual() — constant-time comparison, no timing leaks
✅ TTL Enforcement: 10 minutes server-side, enforced in cleanup loop
✅ Replay Prevention: Session cleanup after TTL expiry; token tied to sessionId
✅ Resume Validation: X-Anon-Session-Token header validated on every resume (403 if invalid)
✅ Attack Scenarios: All tested (guessing, token substitution, OID mismatch, generation)

Session hijacking attack mitigated effectively. Recommendation: APPROVED for merge.

[sabbour-squad-lead]

🤖 Nibbler Code Review — PR #1143

⚠️ NEEDS REVISION (crypto error handling)

Summary

The core security mechanism is correct and well-designed. However, crypto failure handling is missing, which could cause server crashes (unrecoverable service denial). Address this before merge.

Critical Issue

Crypto Failure Unhandled

File: packages/harness/src/runtime/session.ts:194-198 (generateAnonSessionToken)
Severity: Medium

export function generateAnonSessionToken(session: Session): string {
  const token = randomBytes(32).toString('base64url');  // ❌ No try-catch
  session.anonTokenHash = createHash('sha256').update(token).digest('base64url');
  return token;
}

Problem: randomBytes and createHash can throw if:

• Entropy sources unavailable (insufficient system randomness)
• FIPS mode enforces restrictions
• Crypto algorithm unavailable

If either call fails, the exception propagates uncaught, crashing the server and denying service to all users.

Fix: Wrap in try-catch, log error, and either throw a custom error or fall back to rejecting anonymous sessions:

export function generateAnonSessionToken(session: Session): string {
  try {
    const token = randomBytes(32).toString('base64url');
    session.anonTokenHash = createHash('sha256').update(token).digest('base64url');
    return token;
  } catch (err) {
    logger.error('Crypto failure in token generation', err);
    throw new Error('ANON_TOKEN_GENERATION_FAILED');
  }
}

Test Coverage Assessment

• ✅ Test count verified: 19 tests (all passing)
• ✅ Token generation produces unique, non-empty base64url tokens
• ✅ SHA-256 hashing (one-way storage) correct
• ✅ timingSafeEqual used for timing-safe comparison
• ✅ Empty/null/undefined tokens rejected
• ✅ Missing hash handled (fresh session)
• ✅ Authenticated sessions skip token flow
• ✅ 10-min TTL enforced in cleanup
• ✅ Replay prevention (old token invalid after regeneration)
• ✅ Cross-user resume blocked (SESSION_OID_MISMATCH)
• ✅ SSE session_token event emitted
• ✅ Header validation returns 403 on invalid token
• ❌ Missing: Test for crypto failure handling (mocked randomBytes/createHash failure)
• ⚠️ Gap: Malformed base64url header test (e.g., invalid characters) — handled by try-catch in validateAnonSessionToken but untested

Security Assessment

• ✅ Token entropy adequate (256 bits = 32 bytes)
• ✅ Hash storage correct (SHA-256, base64url encoded)
• ✅ Timing-safe comparison prevents side-channels
• ✅ Fail-closed on validation (403 response)
• ❌ Crypto failure path causes service denial

Recommendations

1. BLOCKING: Add try-catch around crypto calls in generateAnonSessionToken
2. OPTIONAL: Add test for mocked crypto failure using vi.mock to verify error handling
3. OPTIONAL: Add test for malformed base64url header to verify graceful rejection

After addressing the try-catch, this PR is safe to merge. The rest of the security design is solid. ✅

[sabbour-squad-frontend]

Addressed in c66be0e: Wrapped crypto calls in try-catch — on entropy failure, throws typed AnonTokenGenerationError which the converse endpoint catches and returns 503 with Retry-After: 5 header instead of crashing. Three new tests added for the failure path (randomBytes failure, createHash failure, healthy-after-failure).

[sabbour-squad-lead]

✅ Nibbler Re-Review — APPROVED

Crypto error handling fix confirmed:
• ✅ try-catch wraps both randomBytes() and createHash() in generateAnonSessionToken()
• ✅ Typed AnonTokenGenerationError with cause field captures underlying crypto error
• ✅ Converse endpoint catches AnonTokenGenerationError → returns 503 with Retry-After: 5
• ✅ 3 comprehensive failure-path tests: randomBytes failure, createHash failure, normal success case
• ✅ Session hash not mutated on failure (fail-safe semantics)

The server will no longer crash on entropy exhaustion or other crypto failures during anonymous session token generation. Clients receive a safe 503 with retry hint.

Applying nibbler:approved label.

[github-actions]

✅ Nibbler recorded a code quality approved via nibbler:approved on head c66be0e.

This native review mirrors the label-driven squad gate for visibility only.
Merge eligibility still comes from the squad/review-gate status check and the current approval labels.

[github-actions]

Docs & changeset gate

• ✅ changeset added (.changeset/*.md)
• ℹ️ docs-site/docs/ not updated — consider updating if user-facing behavior or UI changed
• ℹ️ docs-site/docs/extending/api-endpoints.md not updated — consider updating if the API surface changed

Changeset present. Good.

---

Hard gate for user-facing package changes without docs or changeset. ✅ = done, ⚠️ = likely needed, ℹ️ = optional or bypassed.