Release: Nightly -> Demo (build.cloudflare.dev)

[AshishKumar4]

Summary

This release introduces WebSocket ticket-based authentication for the SDK, enabling secure, token-free WebSocket connections from non-browser environments. It also includes SDK improvements for better runtime compatibility, comprehensive documentation updates, and test infrastructure enhancements.

Changes

Authentication System

• Add WebSocket ticket-based authentication (worker/middleware/auth/ticketAuth.ts)
• Add ticket creation endpoint (POST /api/ws-ticket) for generating short-lived, single-use tickets
• Add WsTicketManager utility for in-memory ticket storage with automatic expiration
• Integrate ticket auth into routeAuth.ts middleware as an alternative to JWT auth for WebSocket connections
• Update CodingAgentController to support dual auth strategies (ticket vs JWT)

SDK Improvements

• Remove Node.js WebSocket polyfill dependency - now requires native WebSocket (Node 22+, Bun, browsers, CF Workers)
• Add getWsTicket() method to HttpClient for ticket-based WebSocket auth
• Update BuildSession.connect() to fetch fresh tickets on connect/reconnect
• Add HTTP retry logic with configurable backoff
• Bump version to 0.0.4

Testing

• Add comprehensive test server (sdk/test/test-server.ts) using Miniflare
• Update WebSocket routing and session tests to use new test infrastructure
• Add new dev dependencies: miniflare, wrangler, @cloudflare/workers-types

Documentation

• Complete README rewrite with compatibility matrix, API documentation, and examples
• Add TypeScript type exports documentation

Motivation

The SDK previously required browser-style WebSocket connections with cookies/headers for authentication. This PR enables SDK usage from server-side environments (CLI tools, automation scripts, Cloudflare Workers) where traditional browser authentication patterns don't work. Tickets provide a secure, short-lived authentication mechanism that doesn't expose long-lived tokens in WebSocket URLs.

Security Considerations

• Tickets are single-use (consumed on connection)
• 15-second TTL with automatic cleanup
• Ownership verification required before ticket creation
• Ticket format validation with distinct prefixes (tk_ for agents, tkv_ for vault)
• Stored in DO memory only (not persisted to database)

Testing

• Unit tests: cd sdk && bun test
• Integration tests: cd sdk && VIBESDK_INTEGRATION_API_KEY=xxx bun run test:integration
• New test server validates ticket auth flow

Breaking Changes

• SDK now requires native WebSocket support (Node.js 22+, Bun, browsers, Cloudflare Workers)
• Removed @cf-vibesdk/sdk/node export (Node WebSocket factory no longer needed)
• ws package moved to optional dependency

[github-actions]

Claude finished @AshishKumar4's task in 2m 2s —— View job

---

Code Quality & Security Review (Critical Path)

Recommendation: APPROVE

PR Summary

This release introduces WebSocket ticket-based authentication for SDK usage, enabling secure connections from non-browser environments. It includes SDK improvements for native WebSocket support (Node 22+), comprehensive documentation, and enhanced test infrastructure.

PR Description

• Updated: Yes
• Notes: Added comprehensive summary covering all changes, security considerations, and breaking changes

Addressed Issues

• None explicitly linked (release PR from nightly to release-live)

---

Security Analysis

Ticket Authentication System

Reviewed Files:

• worker/middleware/auth/ticketAuth.ts
• worker/utils/wsTicketManager.ts
• worker/api/controllers/ticket/controller.ts
• worker/middleware/auth/routeAuth.ts

Aspect	Status	Notes
Single-use tickets	OK	Tickets deleted immediately on consumption (ticketAuth.ts:39-40)
Short TTL	OK	15-second expiry with auto-cleanup (controller.ts:16, wsTicketManager.ts:20-25)
Ownership verification	OK	verifyOwnership() checks app ownership before ticket creation (controller.ts:27-39)
Token format validation	OK	Distinct prefixes and regex patterns prevent token confusion (ticketAuth.ts:24-27, 76-89)
Memory-only storage	OK	Tickets stored in DO memory via WsTicketManager, not persisted to DB
Timing attacks	OK	Token comparison uses standard Map operations (acceptable for this use case)

Authentication Flow

Positive Findings:

• Ticket auth requires prior JWT authentication to create tickets (ticketRoutes.ts:16)
• Invalid tickets are rejected immediately with 403 (routeAuth.ts:191-192)
• Origin validation skipped only for ticket auth (appropriate since tickets are origin-agnostic)
• Rate limiting applied at ticket creation, not consumption (prevents abuse)

No Critical Issues Found

---

Code Quality

Severity	Count	Notes
Critical	0	-
High	0	-
Medium	1	See below
Low	2	See below

Medium

Console.log in production code (routeAuth.ts:95)

console.log('requirement', requirement, 'for user', user);

This appears to be debug logging that should be removed or converted to structured logging.

Low

1. Missing type annotation (session.ts:191-196): The followUp options parameter could benefit from explicit type extraction for better API documentation.

2. Magic number (wsTicketManager.ts:24): The +1000ms buffer for cleanup could be extracted to a named constant for clarity.

---

SDK Changes Review

Change	Status	Notes
Native WebSocket requirement	OK	Good decision - simplifies codebase, aligns with modern runtimes
Ticket-based reconnect	OK	getUrl provider fetches fresh ticket on each reconnect (session.ts:137-141)
HTTP retry logic	OK	Proper exponential backoff with jitter
Version bump to 0.0.4	OK	Appropriate for breaking changes
README rewrite	OK	Comprehensive documentation with examples

---

Testing

• New test server using Miniflare for realistic WebSocket testing
• Updated session and routing tests
• Integration tests available with API key

Recommended manual testing:

1. SDK build workflow from non-browser environment
2. WebSocket reconnection with ticket refresh
3. Ticket expiration edge cases

---

Final Recommendation

APPROVE - This PR implements a well-designed ticket authentication system with proper security controls:

• Single-use, short-lived tickets with automatic cleanup
• Ownership verification before ticket creation
• Clear separation between ticket auth (SDK) and JWT auth (browser)
• No secrets or tokens exposed in persistent storage

The only actionable item is removing the debug console.log in routeAuth.ts:95.