@quantiya/codevibe-core

Core library for CodeVibe plugins — shared keychain, crypto, AppSync, authentication, session lifecycle, and network-resilience functionality. Used by @quantiya/codevibe-claude-plugin, @quantiya/codevibe-gemini-plugin, and @quantiya/codevibe-codex-plugin.

Current version: 1.0.3

Installation

npm install @quantiya/codevibe-core

Features

• Keychain Management — Secure storage for device keys and OAuth tokens using native keychain (macOS Keychain, Linux libsecret, Windows Credential Manager)
• Cryptographic Services — E2E encryption using ECDH P-256 and AES-256-GCM, with dedicated helpers for event content, metadata, and binary attachments
• AppSync Client — GraphQL API and WebSocket subscriptions for AWS AppSync, with automatic token refresh
• Two-phase WebSocket reconnection — exponential backoff (1s→60s) for 10 attempts, then persistent 5-minute retry indefinitely. Survives laptop sleep, network drops, DNS blips, and extended outages without ever giving up.
• Session heartbeat system — startHeartbeat(sessionId) sends updateSession({ lastHeartbeatAt }) every 2 minutes so mobile clients can show desktop connectivity status (green/red dot with 5-minute staleness threshold)
• Centralized session lifecycle — resumeOrCreateSession() is the single source of truth for session fingerprint matching, reuse, and per-device ECDH session key distribution. Used identically by all three plugins.
• WSL-aware networking — auto-detects WSL via /proc/sys/kernel/osrelease and applies IPv4-first DNS ordering to work around broken WSL IPv6 stacks. Zero behavioral change on macOS, native Linux, and Windows.
• Diagnostic fetch wrapper — fetchWithDiagnostics() unpacks undici's generic "fetch failed" errors into detailed platform-specific messages (DNS failures, TLS clock skew, corporate MITM proxies, etc.) so failures are debuggable without trawling logs.
• Cross-platform browser launcher — AuthService opens the user's default browser during OAuth login via wslview → cmd.exe → powershell.exe → xdg-open fallback chain on Linux/WSL, native open on macOS, cmd /c start on Windows. Always prints the sign-in URL to stdout as a copy-paste fallback if automatic launching fails.
• Authentication CLI — Browser-based OAuth login/logout commands (Sign in with Apple / Sign in with Google via Cognito)
• Prompt Parser — Extracts numbered options from tmux pane snapshots so plugins can forward the exact options a CLI offers to mobile clients without hardcoding
• Shared TypeScript types — Events, sessions, attachments, encryption structures used across all plugins

CLI Usage

# Sign in via browser (opens Cognito Hosted UI)
codevibe login

# Sign out
codevibe logout

# Check authentication status
codevibe status

# Reset device identity (destructive - old sessions become inaccessible)
codevibe reset-device

# Use specific environment
codevibe --env development login

API Usage

Keychain Manager

import { keychainManager, DeviceIdentity } from '@quantiya/codevibe-core';

// Get or create device identity (stored in native keychain)
const identity = await keychainManager.getOrCreateDeviceIdentity();
console.log(identity.deviceId, identity.publicKey);

// Get OAuth tokens
const tokens = await keychainManager.getTokens('production');
if (tokens) {
  console.log(tokens.email, tokens.userId);
}

Crypto Service

import { cryptoService } from '@quantiya/codevibe-core';

// Generate key pair
const keyPair = cryptoService.generateKeyPair();

// Generate session key
const sessionKey = cryptoService.generateSessionKey();

// Encrypt content
const encrypted = cryptoService.encryptContent('Hello World', sessionKey);

// Decrypt content
const decrypted = cryptoService.decryptContent(encrypted, sessionKey);

AppSync Client

import { AppSyncClient, loadConfig } from '@quantiya/codevibe-core';

// Load environment configuration
loadConfig('production');

// Create client
const client = new AppSyncClient('production');

// Authenticate with stored tokens
const authenticated = await client.authenticateWithStoredTokens();
if (!authenticated) {
  console.log('Run "codevibe login" first');
  process.exit(1);
}

// Create session
const session = await client.createSession({
  userId: client.getCurrentUserId(),
  agentType: 'CLAUDE',
  projectPath: '/path/to/project',
});

// Subscribe to events
const unsubscribe = client.subscribeToEvents(session.sessionId, (event) => {
  console.log('Event received:', event);
});

// Clean up
unsubscribe();

Auth Service

import { authService, loadConfig } from '@quantiya/codevibe-core';

// Set environment
loadConfig('production');
authService.setEnvironment('production');

// Login (opens browser)
const tokens = await authService.login();

// Check status
const status = await authService.getStatus();
console.log(status.authenticated, status.tokens?.email);

// Logout
await authService.logout();

Keychain Storage

All sensitive data is stored in the native system keychain:

• Service Name: ai.quantiya.app.codevibe
• Device Identity: Stored as device-identity account
• Tokens: Stored as tokens-{environment} accounts (e.g., tokens-production)

This ensures:

• Data persists across terminal sessions
• Data is encrypted at rest by the OS
• Data survives plugin reinstalls/updates
• Device identity is shared across all CodeVibe plugins

Security

• Device keys are ECDH P-256 key pairs
• Session keys are 256-bit AES keys
• Content is encrypted with AES-256-GCM
• Session keys are encrypted per-device using ECDH
• OAuth tokens are stored securely in native keychain

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Local development with plugin
npm link
cd ../codevibe-claude-plugin
npm link @quantiya/codevibe-core

License

MIT