@vibe-kit/auth

@vibe-kit/auth

OAuth authentication utilities for VibeKit that work in both Node.js and browser environments.

Features

• Environment-Specific Builds: Separate Node.js and browser-compatible builds
• OAuth Authentication: Complete OAuth 2.0 flow with PKCE support
• Token Management: Automatic token refresh and secure storage
• Web Integration: Browser-compatible authentication for web applications
• CLI Support: Command-line authentication flow with browser launching

Installation

npm install @vibe-kit/auth

Usage

Node.js Environment

For Node.js applications (CLI tools, servers, etc.), use the Node.js-specific import:

import { ClaudeAuth } from '@vibe-kit/auth/node';

// Start OAuth flow (opens browser automatically)
const token = await ClaudeAuth.authenticate();

// Check if authenticated
const isAuthenticated = await ClaudeAuth.isAuthenticated();

// Get valid token (auto-refresh if needed)
const accessToken = await ClaudeAuth.getValidToken();

// Verify authentication
const isValid = await ClaudeAuth.verify();

// Get authentication status
const status = await ClaudeAuth.getStatus();

// Logout
await ClaudeAuth.logout();

Browser Environment

For browser/web applications, use the browser-safe import:

import { ClaudeWebAuth, LocalStorageTokenStorage } from '@vibe-kit/auth/browser';
// OR use the default import which is browser-safe:
// import { ClaudeAuth, LocalStorageTokenStorage } from '@vibe-kit/auth';

// Create storage
const storage = new LocalStorageTokenStorage();
const auth = new ClaudeWebAuth(storage);

// Create authorization URL
const { url, state, codeVerifier } = ClaudeWebAuth.createAuthorizationUrl();

// Open URL in browser for user authentication
window.open(url, '_blank');

// After user authorizes and provides the code#state string:
const authCode = 'code123#state456'; // From user input
const token = await auth.authenticate(authCode, codeVerifier, state);

// Check authentication status
const isAuthenticated = await auth.isAuthenticated();

// Get valid token (auto-refresh if needed)
const accessToken = await auth.getValidToken();

Using with VibeKit SDK

The auth package is completely separate from the SDK. Get your token and pass it as the API key:

import { VibeKit } from '@vibe-kit/sdk';
import { ClaudeAuth } from '@vibe-kit/auth/node'; // For Node.js

// Authenticate and get token
let accessToken = await ClaudeAuth.getValidToken();
if (!accessToken) {
  await ClaudeAuth.authenticate();
  accessToken = await ClaudeAuth.getValidToken();
}

// Use token with VibeKit
const vibekit = new VibeKit();
const agent = await vibekit.withAgent("claude", {
  providerApiKey: accessToken, // Pass OAuth token as API key
  model: "claude-sonnet-4-20250514"
});

const result = await agent.generateCode("Create a hello world function");

For browser applications:

import { VibeKit } from '@vibe-kit/sdk';
import { ClaudeWebAuth, LocalStorageTokenStorage } from '@vibe-kit/auth/browser';

const storage = new LocalStorageTokenStorage();
const auth = new ClaudeWebAuth(storage);

// Get token (assumes user is already authenticated)
const accessToken = await auth.getValidToken();
if (!accessToken) {
  // Handle authentication flow...
}

// Use with VibeKit
const vibekit = new VibeKit();
const agent = await vibekit.withAgent("claude", {
  providerApiKey: accessToken,
  model: "claude-sonnet-4-20250514"
});

Token Import/Export (Node.js only)

import { ClaudeAuth } from '@vibe-kit/auth/node';

// Export token in different formats
const envToken = await ClaudeAuth.exportToken('env');
const jsonToken = await ClaudeAuth.exportToken('json');
const fullToken = await ClaudeAuth.exportToken('full');

// Import from various sources
await ClaudeAuth.importToken({ fromEnv: true });
await ClaudeAuth.importToken({ fromFile: './token.json' });
await ClaudeAuth.importToken({ refreshToken: 'your-refresh-token' });

Types

interface OAuthToken {
  access_token: string;
  token_type: string;
  expires_in?: number;
  refresh_token?: string;
  scope?: string;
  created_at: number;
}

Storage Options

• MemoryTokenStorage: In-memory storage for server-side use
• LocalStorageTokenStorage: Browser localStorage (client-side only)
• CookieTokenStorage: Cookie-based storage for SSR applications

Security

• Tokens are stored with restricted file permissions (CLI)
• Automatic token refresh prevents expired token usage
• PKCE (Proof Key for Code Exchange) for secure OAuth flows
• State parameter validation prevents CSRF attacks

Environment Compatibility

• Node.js: Use @vibe-kit/auth/node for full functionality including file system access and browser launching
• Browser: Use @vibe-kit/auth/browser or default import for browser-safe functionality
• Universal: The default import provides browser-safe functionality that works everywhere

Migration from Previous Versions

If you were using the old unified import and experiencing browser compatibility issues:

// Old (caused browser compatibility issues)
import { ClaudeAuth } from '@vibe-kit/auth';
await ClaudeAuth.authenticate(); // Would fail in browser due to Node.js imports

// New - Node.js
import { ClaudeAuth } from '@vibe-kit/auth/node';
await ClaudeAuth.authenticate(); // Works in Node.js

// New - Browser
import { ClaudeWebAuth, LocalStorageTokenStorage } from '@vibe-kit/auth/browser';
const storage = new LocalStorageTokenStorage();
const auth = new ClaudeWebAuth(storage);
const { url, state, codeVerifier } = ClaudeWebAuth.createAuthorizationUrl();
// Handle authentication flow...

Standalone CLI Usage

The auth package can be used independently for authentication:

// Node.js applications
import { authenticate, getValidToken } from '@vibe-kit/auth/node';

// Browser applications  
import { ClaudeWebAuth } from '@vibe-kit/auth/browser';

Note: CLI authentication commands have been moved out of the main VibeKit CLI to keep packages separate and environment-specific.