vibecheck/packages/api

vibecheck-api

NestJS backend for VibeCheck result verification. Provides session management, nonce-based challenge-response, and replay attack prevention.

Note

: This package is private and not published to npm. It is deployed as a standalone service.

Setup

cd packages/api
bun install

Environment Variables

PORT=4100
DATABASE_POSTGRES_HOST=localhost
DATABASE_POSTGRES_PORT=25451
DATABASE_POSTGRES_USER=vibecheck
DATABASE_POSTGRES_PASSWORD=secure_password
DATABASE_POSTGRES_NAME=vibecheck
NODE_ENV=development

Running

# Development (hot reload)
bun run dev

# Production build
bun run build

# Production start
bun run start

Endpoints

Method	Path	Description
POST	/sessions	Create a new verification session with nonce
POST	/sessions/:id/verify	Submit signed liveness result for verification
GET	/sessions/:id/status	Check verification status of a session
GET	/health	Health check
GET	/wasm-hash	WASM binary integrity hash

Session Flow

1. Create session: Client requests POST /sessions, receives sessionId and nonce
2. Client-side check: VibeCheck core runs liveness detection, signs result with nonce via HMAC
3. Verify result: Client submits signed result to POST /sessions/:id/verify
4. Query status: Application backend queries GET /sessions/:id/status to confirm verification

Security

• Nonce-based challenge-response: Each session gets a unique nonce to prevent replay attacks
• Single-use sessions: Nonces are consumed on verification and cannot be reused
• Session expiry: Sessions expire after 5 minutes
• Rate limiting: Built-in throttling via @nestjs/throttler
• WASM integrity: Server can verify client WASM binary hash

Integration

Applications discover VibeCheck via service registry:

import { getServiceRegistry } from '@lilith/service-registry';

const registry = getServiceRegistry();
const vibeCheckPort = registry.getPort('vibecheck'); // 4100

See the full Integration Guide for frontend and backend integration patterns.

Documentation

• API Reference
• Architecture Overview
• Integration Guide

License

MIT