Feat: Client SDK for vibesdk

[AshishKumar4]

Summary

This PR introduces a full TypeScript Client SDK (@cf-vibesdk/sdk) for programmatic interaction with the VibeSDK platform, enabling headless automation, CI/CD integration, and third-party tooling.

Changes

• SDK Package (/sdk/): Complete TypeScript client implementation

  • VibeClient, PhasicClient, AgenticClient - High-level client classes
  • BuildSession - Session management with WebSocket connection
  • WorkspaceStore - Local file state synchronization
  • SessionStateStore - Reactive state management
  • Auto-reconnect WebSocket with exponential backoff + jitter
  • Node.js support via ws package shim

• Backend Auth (/worker/api/controllers/auth/):

  • New POST /api/auth/exchange-api-key endpoint for API key → JWT exchange
  • 15-minute short-lived access tokens for SDK sessions
  • Input validation (256 char limit, base64url pattern matching)

• Security Middleware:

  • WebSocket origin check updated to allow Bearer token auth without Origin header (for server-side SDKs)
  • CSRF validation correctly bypasses for Bearer/X-API-Key authenticated requests

• Testing:

  • Integration tests excluded from pre-commit hooks via env flag
  • New test:integration script for SDK E2E testing

Motivation

Enables programmatic access to VibeSDK for:

• Automated app generation in CI/CD pipelines
• Third-party integrations and tooling
• Headless/scripted workflows

Testing

# Unit tests
cd sdk && bun run test

# Integration tests (requires local platform + API key)
VIBESDK_INTEGRATION_API_KEY=<key> bun run test:integration

Breaking Changes

None - additive changes only.

Related Issues

None identified.

[github-actions]

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

---

Code Quality & Security Review (Critical Path)

Recommendation: APPROVE

PR Summary

This PR introduces a full TypeScript Client SDK (@cf-vibesdk/sdk) for programmatic interaction with the VibeSDK platform, along with backend authentication changes to support API key exchange for short-lived JWTs.

PR Description

• Updated: Yes
• Notes: Generated comprehensive description covering SDK features, backend auth changes, and testing instructions.

Addressed Issues

None identified.

---

Security Analysis

Severity	Finding
--	No critical or high severity issues found

Positive Security Patterns Observed:

1. API Key Exchange Hardening (worker/api/controllers/auth/controller.ts:562-636)

   • Input size validation (256 char max) prevents hash DoS
   • Regex pattern validation (/^[A-Za-z0-9_-]+$/) rejects malformed keys early
   • Short-lived JWTs (15 min expiration) limit token exposure window
   • User account status checks (deleted, inactive, suspended, locked)
   • Consistent error messages prevent user enumeration

2. WebSocket Security (worker/middleware/security/websocket.ts:9-18)

   • Correctly allows Bearer token auth without Origin header for server-side SDK clients
   • Falls back to origin validation for browser clients
   • Maintains existing CORS protection for web contexts

3. CSRF Bypass Logic (worker/services/csrf/CsrfService.ts:107-116)

   • Correctly skips CSRF validation for Bearer/X-API-Key authenticated requests
   • CSRF is only relevant for ambient cookie-based auth; explicit credentials don't need it

4. Token Caching (sdk/src/http.ts:33-44)

   • 30-second skew buffer prevents clock drift issues
   • Tokens cached in memory (appropriate for server-side SDK)

---

Code Quality Analysis

Severity	Count	Details
Critical	0	--
High	0	--
Medium	2	Minor type safety concerns
Low	2	Style/documentation

Medium:

1. Type Casts in State Store (sdk/src/state.ts:120,124,128,132,136,140)

   • Uses as any casts for phase info extraction
   • Impact: Reduces type safety for phase message handling
   • Suggestion: Consider adding proper type guards or narrowing

2. Extensible Record Type (sdk/src/types.ts:66)

   export type AppDetails = Record<string, unknown> & { ... }

   • Acceptable pattern for extensible APIs but reduces type safety

Low:

1. Integration Test Fetch Wrapper (sdk/test/integration/integration.test.ts:32-34)

   • Redundant fetch wrapper that just calls fetch
   • Minor - doesn't affect functionality

2. Empty Export Block (sdk/src/index.ts:41)

   • Trailing empty line after exports (cosmetic)

---

Architecture Review

SDK Design - Well Structured:

• Clean separation: VibeClient (HTTP) → BuildSession (WebSocket) → WorkspaceStore/SessionStateStore
• Event emitter pattern with typed events (TypedEmitter<AgentEventMap>)
• Auto-reconnect with exponential backoff + jitter (thundering herd prevention)
• Wait primitives (session.wait.deployable()) provide clean async APIs

Type Safety:

• Proper re-export of platform types from protocol.ts
• No use of any in public APIs (internal casts are contained)
• Discriminated unions for state (GenerationState, PhaseState, etc.)

---

Testing

• Unit tests: Present in sdk/test/ covering HTTP, NDJSON, WebSocket routing
• Integration tests: Properly excluded from pre-commit via env flag
• Run integration: VIBESDK_INTEGRATION_API_KEY=<key> bun run test:integration

---

Final Recommendation

APPROVE - This is a well-designed SDK with appropriate security measures. The API key exchange flow follows security best practices (short-lived tokens, input validation, account status checks). Minor type safety improvements could be made but don't block the PR.

---