bknd-create-user

What this skill does

# Create User

Create new user accounts in Bknd via seed functions, SDK, REST API, or admin panel.

## Prerequisites

- Bknd project running (local or deployed)
- Auth module enabled (`auth.enabled: true`)
- Password strategy configured (enabled by default)
- For role assignment: roles defined in auth config

## When to Use UI Mode

- Creating admin/test users during development
- Manual user management by non-technical admins
- One-off user creation

**UI steps:** Admin Panel > Auth > Users > Click "+" > Fill email/password > Select role > Save

## When to Use Code Mode

- Seeding initial admin users on first deploy
- Programmatic user creation in server code
- User registration flows in your frontend
- Automated user provisioning

## Code Approach

### Method 1: Seed Function (Recommended for Initial Users)

Create users on first app startup via seed function:

```typescript
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,
      jwt: { secret: process.env.JWT_SECRET || "dev-secret" },
      roles: {
        admin: { implicit_allow: true },
        user: { implicit_allow: false },
      },
    },
  },
  options: {
    seed: async (ctx) => {
      // Create admin user on first run
      await ctx.app.module.auth.createUser({
        email: "[email protected]",
        password: "securepassword123",
        role: "admin",
      });
      console.log("Admin user created");
    },
  },
});
```

**Seed function notes:**
- Runs only on first startup when database is empty
- Has full access to `ctx.app.module.auth`
- Ideal for creating initial admin accounts

### Method 2: Server-Side createUser()

Create users programmatically in server code (plugins, flows, custom endpoints):

```typescript
import { getApi } from "bknd";

// In a plugin, flow, or custom endpoint handler
async function createAdminUser(app) {
  const user = await app.module.auth.createUser({
    email: "[email protected]",
    password: "securepassword123",
    role: "admin",
  });

  console.log("Created user:", user.id, user.email);
  return user;
}

// With additional fields (if users entity has custom fields)
async function createUserWithProfile(app) {
  const user = await app.module.auth.createUser({
    email: "[email protected]",
    password: "password123",
    role: "user",
    name: "John Doe",        // Custom field
    avatar: "https://...",   // Custom field
  });
  return user;
}
```

**createUser() signature:**
```typescript
type CreateUserPayload = {
  email: string;      // Required: user email
  password: string;   // Required: plain text (will be hashed)
  role?: string;      // Optional: must exist in auth.roles
  [key: string]: any; // Additional fields for users entity
};

// Returns the created user record
async createUser(payload: CreateUserPayload): Promise<User>
```

### Method 3: SDK Registration (Client-Side)

For user self-registration via your frontend:

```typescript
import { Api } from "bknd";

const api = new Api({
  host: "http://localhost:7654",
  storage: localStorage,  // For token persistence
});

// Register new user
const { ok, data, error } = await api.auth.register("password", {
  email: "[email protected]",
  password: "securepassword123",
});

if (ok) {
  console.log("Registered:", data.user);
  console.log("Token:", data.token);
  // User is now logged in, token stored in localStorage
} else {
  console.error("Registration failed:", error);
}
```

**Registration notes:**
- Requires `auth.allow_register: true` (default)
- Assigns `auth.default_role_register` role automatically
- Returns JWT token (user is logged in after registration)
- Only accepts email/password; additional fields need separate update

### Method 4: REST API Registration

```bash
# Register via REST API
curl -X POST http://localhost:7654/api/auth/password/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "securepassword123"}'
```

**Response:**
```json
{
  "user": {
    "id": 1,
    "email": "[email protected]",
    "role": "user"
  },
  "token": "eyJhbGciOiJIUzI1NiIs..."
}
```

### Method 5: Data API (Admin Creating Users)

Admins can create users directly via data API (requires auth + admin role):

```typescript
// As authenticated admin
const { ok, data } = await api.data.createOne("users", {
  email: "[email protected]",
  strategy: "password",
  strategy_value: "HASHED_PASSWORD",  // Must be pre-hashed!
  role: "user",
});
```

**Warning:** Data API requires pre-hashed password. Use `createUser()` or registration instead for proper password handling.

## React Integration

### Registration Form

```tsx
import { useApp } from "bknd/react";
import { useState } from "react";

function RegisterForm() {
  const { api } = useApp();
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setLoading(true);
    setError(null);

    const { ok, data, error: apiError } = await api.auth.register("password", {
      email,
      password,
    });

    setLoading(false);

    if (ok) {
      console.log("Registered:", data.user);
      // Redirect to dashboard or show success
    } else {
      setError(apiError?.message || "Registration failed");
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        required
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
        minLength={8}
        required
      />
      <button type="submit" disabled={loading}>
        {loading ? "Creating account..." : "Register"}
      </button>
      {error && <p className="error">{error}</p>}
    </form>
  );
}
```

### Using useAuth Hook

```tsx
import { useAuth } from "@bknd/react";

function AuthStatus() {
  const { user, isLoading, register, logout } = useAuth();

  if (isLoading) return <div>Loading...</div>;

  if (!user) {
    return (
      <button onClick={() => register("password", {
        email: "[email protected]",
        password: "password123"
      })}>
        Create Account
      </button>
    );
  }

  return (
    <div>
      <p>Welcome, {user.email}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}
```

## Configuration Options

### Enable/Disable Registration

```typescript
{
  auth: {
    enabled: true,
    allow_register: true,  // Set to false to disable self-registration
    default_role_register: "user",  // Role assigned on registration
  },
}
```

### Password Requirements

```typescript
{
  auth: {
    strategies: {
      password: {
        type: "password",
        enabled: true,
        config: {
          hashing: "bcrypt",   // "plain" | "sha256" | "bcrypt"
          rounds: 4,           // bcrypt rounds (1-10)
          minLength: 8,        // Minimum password length
        },
      },
    },
  },
}
```

### Define Roles for Assignment

```typescript
{
  auth: {
    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,
        permissions: [
          { permission: "data.posts.read", effect: "allow" },
        ],
      },
    },
    default_role_regist