bknd-setup-auth

name	bknd-setup-auth
description	Use when initializing or configuring the Bknd authentication system. Covers enabling auth, configuring password strategy, setting up JWT and cookie options, defining roles, and production security settings.

Setup Authentication

Initialize and configure the Bknd authentication system with strategies, JWT, cookies, and roles.

Prerequisites

• Bknd project initialized
• Code-first configuration (auth config is code-only)
• For OAuth: provider credentials (client ID, client secret)

When to Use UI Mode

• Viewing current auth configuration
• Toggling strategies on/off
• Testing auth endpoints via admin panel

UI steps: Admin Panel > Auth > Settings

Note: Full auth configuration requires code mode. UI only shows/toggles existing settings.

When to Use Code Mode

• Initial authentication setup
• Configuring JWT secrets and expiry
• Setting up password hashing
• Defining roles and permissions
• Production security hardening

Code Approach

Step 1: Enable Auth with Minimal Config

Start with basic password authentication:

import { serve } from "bknd/adapter/bun";
import { em, entity, text } from "bknd";

const schema = em({
  posts: entity("posts", { title: text().required() }),
});

serve({
  connection: { url: "file:data.db" },
  config: {
    data: schema.toJSON(),
    auth: {
      enabled: true,
    },
  },
});

This enables:

• Password strategy (default)
• Auto-created users entity
• JWT-based sessions
• /api/auth/* endpoints

Step 2: Configure JWT Settings

JWT tokens authenticate API requests. Configure for security:

{
  auth: {
    enabled: true,
    jwt: {
      secret: process.env.JWT_SECRET,  // Required in production
      alg: "HS256",                     // Algorithm: HS256, HS384, HS512
      expires: 604800,                  // Expiry in seconds (7 days)
      issuer: "my-app",                 // Optional issuer claim
      fields: ["id", "email", "role"],  // Fields included in token
    },
  },
}

JWT options:

Option	Type	Default	Description
secret	string	""	Signing secret (256-bit minimum for production)
alg	string	"HS256"	Algorithm: HS256, HS384, HS512
expires	number	-	Token expiry in seconds
issuer	string	-	Token issuer claim (iss)
fields	string[]	["id", "email", "role"]	User fields in payload

Step 3: Configure Cookie Settings

Auth cookies store JWT tokens for browser sessions:

{
  auth: {
    enabled: true,
    jwt: { secret: process.env.JWT_SECRET },
    cookie: {
      secure: true,           // HTTPS only (set false for local dev)
      httpOnly: true,         // Block JavaScript access
      sameSite: "lax",        // CSRF protection: "strict" | "lax" | "none"
      expires: 604800,        // Cookie expiry in seconds (7 days)
      path: "/",              // Cookie path scope
      renew: true,            // Auto-extend on requests
      pathSuccess: "/",       // Redirect after login
      pathLoggedOut: "/",     // Redirect after logout
    },
  },
}

Cookie options:

Option	Type	Default	Description
secure	boolean	true	HTTPS-only flag
httpOnly	boolean	true	Block JS access
sameSite	string	"lax"	CSRF protection
expires	number	604800	Expiry in seconds
renew	boolean	true	Auto-extend expiry
pathSuccess	string	"/"	Post-login redirect
pathLoggedOut	string	"/"	Post-logout redirect

Step 4: Configure Password Strategy

Set up password hashing and requirements:

{
  auth: {
    enabled: true,
    jwt: { secret: process.env.JWT_SECRET },
    strategies: {
      password: {
        type: "password",
        enabled: true,
        config: {
          hashing: "bcrypt",   // "plain" | "sha256" | "bcrypt"
          rounds: 4,           // bcrypt rounds (1-10)
          minLength: 8,        // Minimum password length
        },
      },
    },
  },
}

Hashing options:

Option	Security	Performance	Use Case
plain	None	Fastest	Development only, never production
sha256	Good	Fast	Default, suitable for most cases
bcrypt	Best	Slower	Recommended for production

Step 5: Define Roles

Configure roles for authorization:

{
  auth: {
    enabled: true,
    jwt: { secret: process.env.JWT_SECRET },
    roles: {
      admin: {
        implicit_allow: true,  // Can do everything
      },
      editor: {
        implicit_allow: false,
        permissions: [
          { permission: "data.posts.read", effect: "allow" },
          { permission: "data.posts.create", effect: "allow" },
          { permission: "data.posts.update", effect: "allow" },
        ],
      },
      user: {
        implicit_allow: false,
        is_default: true,  // Default role for new registrations
        permissions: [
          { permission: "data.posts.read", effect: "allow" },
        ],
      },
    },
    default_role_register: "user",  // Role assigned on registration
  },
}

Step 6: Configure Registration

Control user self-registration:

{
  auth: {
    enabled: true,
    allow_register: true,           // Enable/disable registration
    default_role_register: "user",  // Role for new users
    entity_name: "users",           // User entity name (default: "users")
    basepath: "/api/auth",          // Auth API base path
  },
}

Full Production Example

Complete auth setup with security best practices:

import { serve, type BunBkndConfig } from "bknd/adapter/bun";
import { em, entity, text, date } from "bknd";

const schema = em({
  users: entity("users", {
    email: text().required().unique(),
    name: text(),
    avatar: text(),
    created_at: date({ default_value: "now" }),
  }),
  posts: entity("posts", {
    title: text().required(),
    content: text(),
  }),
});

type Database = (typeof schema)["DB"];
declare module "bknd" {
  interface DB extends Database {}
}

const config: BunBkndConfig = {
  connection: { url: process.env.DB_URL || "file:data.db" },
  config: {
    data: schema.toJSON(),
    auth: {
      enabled: true,
      basepath: "/api/auth",
      entity_name: "users",
      allow_register: true,
      default_role_register: "user",

      // JWT configuration
      jwt: {
        secret: process.env.JWT_SECRET!,
        alg: "HS256",
        expires: 604800,  // 7 days
        issuer: "my-app",
        fields: ["id", "email", "role"],
      },

      // Cookie configuration
      cookie: {
        secure: process.env.NODE_ENV === "production",
        httpOnly: true,
        sameSite: "lax",
        expires: 604800,
        renew: true,
        pathSuccess: "/dashboard",
        pathLoggedOut: "/login",
      },

      // Password strategy
      strategies: {
        password: {
          type: "password",
          enabled: true,
          config: {
            hashing: "bcrypt",
            rounds: 4,
            minLength: 8,
          },
        },
      },

      // Roles
      roles: {
        admin: {
          implicit_allow: true,
        },
        editor: {
          implicit_allow: false,
          permissions: [
            { permission: "data.posts.read", effect: "allow" },
            { permission: "data.posts.create", effect: "allow" },
            { permission: "data.posts.update", effect: "allow" },
            { permission: "data.posts.delete", effect: "allow" },
          ],
        },
        user: {
          implicit_allow: false,
          is_default: true,
          permissions: [
            { permission: "data.posts.read", effect: "allow" },
          ],
        },
      },
    },
  },
  options: {
    seed: async (ctx) => {
      // Create initial admin on first run
      const adminExists = await ctx.em.repo("users").findOne({
        where: { email: { $eq: "[e-mail]" } },
      });

      if (!adminExists) {
        await ctx.app.module.auth.createUser({
          email: "[e-mail]",
          password: process.env.ADMIN_PASSWORD || "changeme123",
          role: "admin",
        });
        console.log("Admin user created");
      }
    },
  },
};

serve(config);

Auth Endpoints

After setup, these endpoints are available:

Method	Path	Description
POST	/api/auth/password/login	Login with email/password
POST	/api/auth/password/register	Register new user
GET	/api/auth/me	Get current user
POST	/api/auth/logout	Log out (clear cookie)
GET	/api/auth/strategies	List enabled strategies

Environment Variables

Recommended env vars for auth:

# .env
JWT_SECRET=your-256-bit-secret-minimum-32-characters-long
ADMIN_PASSWORD=secure-initial-admin-password

Generate a secure secret:

# Generate 64-character random string
openssl rand -hex 32

Development vs Production

Setting	Development	Production
jwt.secret	Can use placeholder	Required, strong secret
cookie.secure	false	true (HTTPS only)
strategies.password.config.hashing	sha256	bcrypt
allow_register	true	Consider false for closed systems

Dev config shortcut:

const isDev = process.env.NODE_ENV !== "production";

{
  auth: {
    enabled: true,
    jwt: {
      secret: isDev ? "dev-secret-not-for-production" : process.env.JWT_SECRET!,
      expires: isDev ? 86400 * 30 : 604800,  // 30 days dev, 7 days prod
    },
    cookie: {
      secure: !isDev,
    },
    strategies: {
      password: {
        type: "password",
        config: {
          hashing: isDev ? "sha256" : "bcrypt",
        },
      },
    },
  },
}

Common Pitfalls

Missing JWT Secret in Production

Problem: Cannot sign JWT without secret error

Fix: Set JWT secret via environment variable:

{
  auth: {
    jwt: {
      secret: process.env.JWT_SECRET,  // Never hardcode in production
    },
  },
}

Cookie Not Set (HTTPS Issues)

Problem: Auth cookie not set in browser

Fix: Set secure: false for local development:

{
  auth: {
    cookie: {
      secure: process.env.NODE_ENV === "production",  // false for localhost
    },
  },
}

Role Not Found

Problem: Role "admin" not found when creating users

Fix: Define roles before referencing them:

{
  auth: {
    roles: {
      admin: { implicit_allow: true },  // Define first
      user: { implicit_allow: false },
    },
    default_role_register: "user",  // Now can reference
  },
}

Registration Disabled

Problem: Registration not allowed error

Fix: Enable registration:

{
  auth: {
    allow_register: true,  // Default is true, but check if explicitly disabled
  },
}

Weak Password Hashing

Problem: Using plain or sha256 in production

Fix: Use bcrypt for production:

{
  auth: {
    strategies: {
      password: {
        config: {
          hashing: "bcrypt",
          rounds: 4,  // Balance security and performance
        },
      },
    },
  },
}

Verification

After setup, verify auth works:

1. Check enabled strategies:

curl http://localhost:7654/api/auth/strategies

2. Register a test user:

curl -X POST http://localhost:7654/api/auth/password/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "password": "password123"}'

3. Login:

curl -X POST http://localhost:7654/api/auth/password/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "password": "password123"}'

4. Check current user (with token):

curl http://localhost:7654/api/auth/me \
  -H "Authorization: Bearer <token-from-login>"

Security Checklist

Before deploying to production:

• Set strong jwt.secret (256-bit minimum)
• Use hashing: "bcrypt" for password strategy
• Set cookie.secure: true (HTTPS only)
• Set cookie.httpOnly: true (default)
• Set cookie.sameSite: "lax" or "strict"
• Configure jwt.expires (don't leave unlimited)
• Review allow_register setting
• Create admin user via seed (not via public registration)
• Store secrets in environment variables

DOs and DON'Ts

DO:

• Use environment variables for secrets
• Use bcrypt hashing in production
• Set JWT expiry times
• Define roles before assigning them
• Test auth flow after configuration changes

DON'T:

• Hardcode JWT secrets in code
• Use plain hashing in production
• Skip setting cookie.secure in production
• Leave registration open if not needed
• Forget to create initial admin user

Related Skills

• bknd-create-user - Create user accounts programmatically
• bknd-login-flow - Implement login/logout functionality
• bknd-registration - Set up user registration flows
• bknd-oauth-setup - Configure OAuth providers (Google, GitHub)
• bknd-create-role - Define roles for authorization
• bknd-session-handling - Manage user sessions