velvet-auth is a production-ready authentication plugin specifically designed for Elysia.js applications running on Bun. It provides a comprehensive solution for common authentication patterns, including JWT rotation, secure password hashing using native Argon2id (via `Bun.password`), and session management with RESP-compatible stores like Redis for refresh token invalidation and JTI blacklisting. The current stable version is 0.1.9, with frequent minor releases addressing bug fixes and introducing improvements. Key differentiators include its tight integration with Bun's native features, an adapter pattern for database and email provider flexibility, and a focus on type safety with Zod validation. It aims to reduce boilerplate for setting up robust auth stacks in the Bun/Elysia ecosystem.
npm install velvet-authVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to integrate `velvet-auth` into an Elysia application, showing the setup of `UserStoreAdapter` and `EmailAdapter` mocks, and mounting the `velvetAuth` plugin with essential JWT and Redis configuration. It also includes a basic Elysia route to confirm server operation.
Ensure that `createAuthGuard` is composed only where the `user` context is explicitly intended to be available. Review any complex app compositions to verify the correct scope of `ctx.user`.
Generate a strong, long (>=32 characters) cryptographic secret for `jwt.secret`. Use environment variables (e.g., `process.env.JWT_SECRET!`) to manage it securely, especially in production environments.
Ensure client-side password validation logic aligns with the server-side `config.password` rules to prevent registration failures due to policy violations. Inform users about password requirements during registration.
Ensure your project is running on Bun version >= 1.0. This package is not compatible with other JavaScript runtimes.
Update your `velvetAuth` configuration to provide a `jwt.secret` that is at least 32 characters long. Example: `{ jwt: { secret: process.env.JWT_SECRET || 'your-long-and-secure-secret-key-here' } }`Ensure your project is executed using Bun (e.g., `bun run start`) and that your Bun version is >= 1.0.
Verify that your Redis server is running and accessible at the configured `redis.url` (default `redis://localhost:6379`). Check firewall rules and Redis server status. You can configure the URL via `velvetAuth({ redis: { url: 'your_redis_url' } })` or `process.env.REDIS_URL`.Ensure you are using `createAuthGuard()` on the routes where `ctx.user` is expected. Example: `app.group('/protected', (app) => app.use(createAuthGuard()).get('/', (ctx) => ctx.user))`.