bknd-assign-permissions

What this skill does

# Assign Permissions

Configure detailed permissions for roles using simple strings, extended format with effects, and conditional policies.

## Prerequisites

- Bknd project with code-first configuration
- Auth enabled (`auth: { enabled: true }`)
- Guard enabled (`guard: { enabled: true }`)
- At least one role defined (see **bknd-create-role**)

## When to Use UI Mode

- Viewing current role permissions
- Quick permission checks

**UI steps:** Admin Panel > Auth > Roles > Select role

**Note:** Permission assignment requires code mode. UI is read-only.

## When to Use Code Mode

- Assigning permissions to roles
- Adding permission effects (allow/deny)
- Creating conditional policies
- Entity-specific permission rules

## Code Approach

### Step 1: Simple Permission Strings

Assign basic permissions as string array:

```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,
      guard: { enabled: true },
      roles: {
        editor: {
          implicit_allow: false,
          permissions: [
            "data.entity.read",    // Read any entity
            "data.entity.create",  // Create in any entity
            "data.entity.update",  // Update any entity
            // No delete permission
          ],
        },
      },
    },
  },
});
```

### Available Permissions

| Permission | Filterable | Description |
|------------|------------|-------------|
| `data.entity.read` | Yes | Read entity records |
| `data.entity.create` | Yes | Create new records |
| `data.entity.update` | Yes | Update existing records |
| `data.entity.delete` | Yes | Delete records |
| `data.database.sync` | No | Sync database schema |
| `data.raw.query` | No | Execute raw SELECT |
| `data.raw.mutate` | No | Execute raw INSERT/UPDATE/DELETE |

**Filterable** means you can add conditions/filters via policies.

### Step 2: Extended Permission Format

Use objects for explicit allow/deny effects:

```typescript
{
  roles: {
    moderator: {
      implicit_allow: false,
      permissions: [
        { permission: "data.entity.read", effect: "allow" },
        { permission: "data.entity.update", effect: "allow" },
        { permission: "data.entity.delete", effect: "deny" },  // Explicit deny
      ],
    },
  },
}
```

### Permission Effects

| Effect | Description |
|--------|-------------|
| `allow` | Grant the permission (default) |
| `deny` | Explicitly block the permission |

**Deny overrides allow** - useful when `implicit_allow: true` but you want to block specific actions.

### Step 3: Conditional Policies

Add policies for fine-grained control:

```typescript
{
  roles: {
    content_editor: {
      implicit_allow: false,
      permissions: [
        {
          permission: "data.entity.read",
          effect: "allow",
          policies: [
            {
              description: "Only read posts and comments",
              condition: { entity: { $in: ["posts", "comments"] } },
              effect: "allow",
            },
          ],
        },
        {
          permission: "data.entity.create",
          effect: "allow",
          policies: [
            {
              condition: { entity: { $in: ["posts", "comments"] } },
              effect: "allow",
            },
          ],
        },
      ],
    },
  },
}
```

### Policy Structure

```typescript
{
  description?: string,      // Human-readable (optional)
  condition?: ObjectQuery,   // When policy applies
  effect: "allow" | "deny" | "filter",
  filter?: ObjectQuery,      // Row filter (for effect: "filter")
}
```

### Policy Effects

| Effect | Purpose |
|--------|---------|
| `allow` | Grant when condition met |
| `deny` | Block when condition met |
| `filter` | Apply row-level filter to results |

### Condition Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `$eq` | Equal | `{ entity: { $eq: "posts" } }` |
| `$ne` | Not equal | `{ entity: { $ne: "users" } }` |
| `$in` | In array | `{ entity: { $in: ["posts", "comments"] } }` |
| `$nin` | Not in array | `{ entity: { $nin: ["users", "secrets"] } }` |
| `$gt` | Greater than | `{ age: { $gt: 18 } }` |
| `$gte` | Greater or equal | `{ level: { $gte: 5 } }` |
| `$lt` | Less than | `{ count: { $lt: 100 } }` |
| `$lte` | Less or equal | `{ priority: { $lte: 3 } }` |

### Step 4: Variable Placeholders

Reference runtime context with `@variable`:

| Placeholder | Description |
|-------------|-------------|
| `@user.id` | Current user's ID |
| `@user.email` | Current user's email |
| `@user.role` | Current user's role |
| `@entity` | Current entity name |
| `@id` | Current record ID |

Example - user can only update their own profile:

```typescript
{
  permissions: [
    {
      permission: "data.entity.update",
      effect: "allow",
      policies: [
        {
          condition: { entity: "users", "@id": "@user.id" },
          effect: "allow",
        },
      ],
    },
  ],
}
```

### Step 5: Entity-Specific Permissions

Grant different permissions per entity:

```typescript
{
  roles: {
    blog_author: {
      implicit_allow: false,
      permissions: [
        // Full CRUD on posts
        {
          permission: "data.entity.read",
          effect: "allow",
          policies: [{ condition: { entity: "posts" }, effect: "allow" }],
        },
        {
          permission: "data.entity.create",
          effect: "allow",
          policies: [{ condition: { entity: "posts" }, effect: "allow" }],
        },
        {
          permission: "data.entity.update",
          effect: "allow",
          policies: [{ condition: { entity: "posts" }, effect: "allow" }],
        },
        {
          permission: "data.entity.delete",
          effect: "allow",
          policies: [{ condition: { entity: "posts" }, effect: "allow" }],
        },

        // Read-only on categories
        {
          permission: "data.entity.read",
          effect: "allow",
          policies: [{ condition: { entity: "categories" }, effect: "allow" }],
        },
      ],
    },
  },
}
```

## Common Patterns

### Read-Only Role

```typescript
{
  roles: {
    viewer: {
      implicit_allow: false,
      permissions: ["data.entity.read"],
    },
  },
}
```

### CRUD Without Delete

```typescript
{
  roles: {
    contributor: {
      implicit_allow: false,
      permissions: [
        "data.entity.read",
        "data.entity.create",
        "data.entity.update",
        { permission: "data.entity.delete", effect: "deny" },
      ],
    },
  },
}
```

### Admin with Restricted Raw Access

```typescript
{
  roles: {
    admin: {
      implicit_allow: true,  // Allow all by default
      permissions: [
        // But deny raw database access
        { permission: "data.raw.query", effect: "deny" },
        { permission: "data.raw.mutate", effect: "deny" },
      ],
    },
  },
}
```

### Multi-Entity Role

```typescript
{
  roles: {
    content_manager: {
      implicit_allow: false,
      permissions: [
        // Content entities: full CRUD
        {
          permission: "data.entity.read",
          effect: "allow",
          policies: [{
            condition: { entity: { $in: ["posts", "pages", "comments", "media"] } },
            effect: "allow",
          }],
        },
        {
          permission: "data.entity.create",
          effect: "allow",
          policies: [{
            condition: { entity: { $in: ["posts", "pages", "comments", "media"] } },
            effect: "allow",
          }],
        },
        {
          permission: "data.entity.update",
          effect: "allow",
          policies: [{
            condition: { entity: { $in: ["posts", "pages", "comments", "media"] } },
            effect: "allow",
          }],
        },
        {
          permission: "data.entity.del