Enterprise-Knowledge-Base/docs/rbac.md

# Tenant RBAC Guide

How WeKnora enforces who-can-do-what inside a tenant, how to roll the
feature out without breaking existing deployments, and how to audit
the system once it is on.

> Status: shipped behind a feature flag (`tenant.enable_rbac`,
> default `false`). Schema and `tenant_members` rows are populated
> on every install; enforcement is opt-in.

## Why this exists

Before #1303 every authenticated user with `X-API-Key` or a JWT was
effectively an Admin in their tenant. That's fine for a single-user
self-host, but as soon as a tenant has more than one human (e.g. a
small team sharing a knowledge base) you need to draw lines around:

- who may delete a knowledge base or revoke an API key (Admins);
- who may upload documents and edit their own KB (Contributors);
- who may only read and ask questions (Viewers).

RBAC layers a **per-tenant role matrix** on top of the existing JWT /
API-key auth so all three states are first-class.

## The role matrix

Every tenant member has exactly one role, stored in `tenant_members.role`:

| Role          | Typical use                                  | Notable powers |
|---------------|----------------------------------------------|----------------|
| `viewer`      | Read-only consumer (chat, search, browse).   | None — reads only. |
| `contributor` | Upload + edit **own** KBs / agents.          | Can mutate resources whose `creator_id` matches their user ID. Cannot touch other contributors' resources. |
| `admin`       | Tenant-wide operator.                        | Can mutate any resource in the tenant; manages members; configures shared infrastructure (Ollama, parser, storage, etc.). |
| `owner`       | Tenant founder.                              | Same as Admin, plus may delete the tenant and cannot be demoted by another Admin. Exactly one Owner per tenant after backfill. |

Higher roles inherit lower roles' permissions. The hierarchy is
`viewer < contributor < admin < owner`.

### Special cases the auth layer still handles

- **Cross-tenant superusers** (`User.CanAccessAllTenants` + the
  `enable_cross_tenant_access` flag + `X-Tenant-ID` header) get an
  Admin-level pass into the target tenant without needing a row in
  `tenant_members`. Used by org-level operators who administer many
  tenants.
- **API-key callers** (`X-API-Key` synthetic users) are pinned to
  Admin in the tenant the key belongs to. This preserves every
  scripted-integration use case except tenant deletion (which still
  requires Owner).
- **Orphan tenants** (zero `tenant_members` rows — typically
  API-key-only tenants) auto-promote the first authenticating human
  to Owner. Prevents lock-out after a fresh install.

## How enforcement is gated

Two routes a request can take:

```text
                           ┌─────────────────────┐
JWT / API-key ──► auth ──► │  tenant_members     │
                           │  lookup → role      │
                           └─────────┬───────────┘
                                     │
                            ┌────────┴────────┐
                            │ EnableRBAC?     │
                            └────────┬────────┘
                                     │
            ┌────────────────────────┴────────────────────────┐
            │                                                 │
            ▼                                                 ▼
  ┌──────────────────────┐                          ┌──────────────────────┐
  │   false (default)    │                          │   true               │
  │   role logged but    │                          │   role enforced;     │
  │   not enforced;      │                          │   denials emit a 403 │
  │   ownership lookups  │                          │   AND a durable row  │
  │   skipped entirely   │                          │   in audit_logs      │
  └──────────────────────┘                          └──────────────────────┘
```

When `tenant.enable_rbac=false` (the shipped default):

- `RequireRole` middleware logs the would-be reject and lets the
  request through (`[rbac] role insufficient (logged but not
  enforced) ...`). Use these logs to audit your role assignments
  *before* flipping the flag.
- `RequireOwnershipOrRole` short-circuits before even running its
  creator-lookup closure, so the dormant rollout window incurs zero
  extra DB roundtrips on hot mutation paths.
- `audit_logs` only records member-management events
  (`rbac.member_added` etc.). Access-denied rows start landing only
  when enforcement is on.

When `tenant.enable_rbac=true`:

- Insufficient role → HTTP 403 + a durable
  `rbac.access_denied` row in `audit_logs` (subject to a 1-minute
  sliding-window dedup so probing clients can't fill the table).
- Ownership lookup runs and decides whether the caller is the
  resource creator. Genuine "row missing" (404) is surfaced as 404,
  not 403, so client diagnostics still work.

## Configuration

YAML (`config/config.yaml`):

```yaml
tenant:
  # Default false. Flip to true once role assignments have been audited.
  enable_rbac: false
  # Optional: leaves the existing cross-tenant superuser flag in place.
  enable_cross_tenant_access: false

auth:
  # self_serve (default) — anyone may register; new tenant + Owner
  #                       membership auto-created.
  # invite_only          — public registration is rejected; new users
  #                       enter only via /tenants/:id/members invitations.
  registration_mode: self_serve

audit:
  # Days of audit history retained. A daily background sweep deletes
  # rows older than this. Default 90 (set automatically when the
  # `audit:` section is omitted from the YAML); set to 0 to disable
  # the purge entirely (the table grows monotonically).
  retention_days: 90
```

Environment overrides (always win over YAML):

| Env var                              | YAML key                       | Values                       |
|--------------------------------------|--------------------------------|------------------------------|
| `WEKNORA_TENANT_ENABLE_RBAC`         | `tenant.enable_rbac`           | `true` / `false`             |
| `WEKNORA_AUTH_REGISTRATION_MODE`     | `auth.registration_mode`       | `self_serve` / `invite_only` |
| `WEKNORA_AUDIT_RETENTION_DAYS`       | `audit.retention_days`         | non-negative integer         |

The startup logger emits one line summarising both effective values
plus their override sources, so you can confirm at boot which mode
the deployment is in.

## Schema reference

### `tenant_members`

```sql
CREATE TABLE tenant_members (
    id          BIGSERIAL PRIMARY KEY,
    user_id     VARCHAR(36) NOT NULL,
    tenant_id   BIGINT      NOT NULL,
    role        VARCHAR(32) NOT NULL,  -- owner | admin | contributor | viewer
    status      VARCHAR(32) NOT NULL DEFAULT 'active',
    joined_at   TIMESTAMP WITH TIME ZONE,
    created_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);
CREATE UNIQUE INDEX idx_tenant_members_user_tenant_unique
    ON tenant_members(user_id, tenant_id) WHERE status = 'active';
```

A user belongs to a tenant by having an `active` row in this table.
The `(user_id, tenant_id)` uniqueness is conditional on `status =
'active'` so historical revoked rows do not block a re-invite.

### Per-resource ownership

Migration 000043 added two columns the role check leans on:

- `knowledge_bases.creator_id VARCHAR(36)` — backfilled to the tenant
  Owner for legacy rows. Empty string / NULL means "tenant-owned, no
  human creator" and only role ≥ min may mutate.
- `custom_agents.runnable_by_viewer BOOLEAN` — when true (default),
  Viewers can run the agent in chat without a role bump.

Sub-resources resolve up the ownership chain:

```
chunk_id ─► knowledge_id ─► kb_id ─► knowledge_bases.creator_id
```

Same for FAQ entries, generated questions, tags, and wiki pages.

### `audit_logs`

```sql
CREATE TABLE audit_logs (
    id              BIGSERIAL PRIMARY KEY,
    tenant_id       BIGINT       NOT NULL,
    actor_user_id   VARCHAR(36)  NOT NULL DEFAULT '',
    actor_role      VARCHAR(32)  NOT NULL DEFAULT '',
    action          VARCHAR(64)  NOT NULL,
    target_type     VARCHAR(32)  NOT NULL DEFAULT '',
    target_id       VARCHAR(64)  NOT NULL DEFAULT '',
    target_user_id  VARCHAR(36)  NOT NULL DEFAULT '',
    request_path    VARCHAR(512) NOT NULL DEFAULT '',
    request_method  VARCHAR(16)  NOT NULL DEFAULT '',
    outcome         VARCHAR(16)  NOT NULL DEFAULT 'success',
    details         JSONB        NOT NULL DEFAULT '{}'::JSONB,
    created_at      TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);
```

Built-in actions today:

| Action                       | Outcome              | When |
|------------------------------|----------------------|------|
| `rbac.member_added`          | success              | `POST /tenants/:id/members` succeeds |
| `rbac.member_removed`        | success              | `DELETE /tenants/:id/members/:user_id` succeeds |
| `rbac.member_role_changed`   | success              | `PUT /tenants/:id/members/:user_id` succeeds |
| `rbac.member_left`           | success              | `POST /tenants/:id/members/leave` succeeds |
| `rbac.access_denied`         | denied               | `RequireRole` / `RequireOwnershipOrRole` rejects (only when enforcement is on) |

The schema is intentionally generic so future PRs can add KB / agent /
chunk action constants without another migration.

A daily background goroutine (`AuditLogRetentionRunner`, `service/`)
sweeps rows older than `audit.retention_days`. The first sweep fires
~10 minutes after boot to stay out of the way of startup traffic; the
loop then runs every 24 h. The runner short-circuits when retention
is `0`, so disabling it costs zero DB round-trips.

## Route guards

Centralised in `internal/router/rbac.go` as `rbacGuards`:

| Guard                                    | What it requires |
|------------------------------------------|------------------|
| `g.Viewer()`                             | Tenant member, any role |
| `g.Contributor()`                        | role ≥ Contributor |
| `g.Admin()`                              | role ≥ Admin |
| `g.Owner()`                              | role = Owner |
| `g.OwnedKBOrAdmin()`                     | KB.creator_id == caller, OR Admin+ |
| `g.OwnedKBOrAdminFromKbIDParam()`        | Same, but reads `:kb_id` from a non-`:id` param |
| `g.OwnedAgentOrAdmin()`                  | CustomAgent.creator_id == caller, OR Admin+ |
| `g.OwnedKnowledgeKBOrAdmin()`            | Resolves `:knowledge_id` → KB.creator_id |
| `g.OwnedChunkKBOrAdmin()`                | Resolves `:chunk_id` → knowledge → KB.creator_id |
| `g.OwnedChunkKBOrAdminFromChunkID()`     | Same chain, but starts from a different param name |
| `g.OwnedWikiKBOrAdmin()`                 | Resolves wiki page → KB.creator_id |
| `g.PathTenantMatch()`                    | URL `:tenant_id` matches the auth context |
| `g.CrossTenant()`                        | Caller has cross-tenant access |

Read-only endpoints stay on `g.Viewer()`. Anything that mutates a
shared infrastructure resource (Ollama install, parser/storage check,
WeKnora Cloud credentials, web-search providers, vector stores,
chat-history config) goes on `g.Admin()`. Anything per-resource picks
the matching `Owned*OrAdmin` guard.

## Rollout playbook

The same playbook a self-host operator (or the Tencent/WeKnora repo
itself) should follow when promoting a deployment from "logged" to
"enforced":

1. **Upgrade.** `tenant.enable_rbac=false` (default) → schema lands,
   `tenant_members` is backfilled (one Owner per tenant, the rest
   Contributor), `creator_id` populated on every KB. No behaviour
   change yet.
2. **Audit the membership.** Call
   `GET /api/v1/tenants/:id/members` (Admin+) and confirm:
   - Exactly one Owner per tenant.
   - The right humans are Contributors, Viewers, etc. (matters most
     in tenants where many users share an API key today and got
     auto-promoted to Contributor by the backfill).
   - Adjust with `PUT /api/v1/tenants/:id/members/:user_id` /
     `DELETE` as needed. Every change writes an `audit_logs` row.
3. **Watch the dormant logs.** Tail the API logs for `[rbac] role
   insufficient (logged but not enforced)` lines. These tell you
   exactly which production calls *would* 403 if you flipped the
   flag now. Fix any user role that produces unexpected denials.
4. **Flip the flag.** Set `tenant.enable_rbac=true` (or
   `WEKNORA_TENANT_ENABLE_RBAC=true`). Restart the app. From this
   point on:
   - Insufficient role → 403.
   - `audit_logs` records every reject (subject to dedup).
5. **Optional — enable invite-only.** If you've moved off self-serve
   registration, set `auth.registration_mode=invite_only`. The
   Register tab disappears from `/login` and the server rejects
   `POST /auth/register` with 403.

### Rollback

If enforcement causes unexpected breakage:

```bash
# Flip the flag back via env (no restart-with-rebuild needed):
export WEKNORA_TENANT_ENABLE_RBAC=false
# Restart the app.
```

Membership rows and `creator_id` columns stay populated so re-enabling
later doesn't require another backfill. Migration 000043 / 000044
both ship `down.sql`s, but rolling those back drops `tenant_members`
and `audit_logs` entirely — only do that if you intend to remove the
feature for good.

## Frontend behaviour

The Pinia auth store exposes:

- `authStore.currentTenantRole` — `''` until membership resolves,
  then one of the four roles. Use the empty string as a "loading"
  signal; flashing a privileged button before the role is known is
  worse UX than waiting.
- `authStore.hasRole('admin')` etc. — convenience helpers that walk
  the hierarchy.

Every mutation surface in the UI is gated either by a role check or
by a per-resource ownership predicate (`isOwner` computed off
`kb.creator_id === authStore.user?.id`). This is the matching pair
to the backend guard — when a button would 403 on click, we hide the
button instead of letting the user discover it through a failed
request.

## Common questions

### "I upgraded and now everyone is a Contributor instead of an Admin."

The backfill picks **the earliest active user in each tenant** as
that tenant's Owner; everyone else becomes Contributor. If a single
human-shared account or API key created the tenant, you may need to
demote bots and re-promote your real Admin via
`PUT /api/v1/tenants/:id/members/:user_id`.

### "I flipped the flag and a script started getting 403."

Likely the script authenticates as a Viewer / Contributor instead of
the Admin you assumed. Check the JWT user, look up the matching
`tenant_members.role`, promote if appropriate. Or — if the script
should be tenant-wide — switch it to authenticate via `X-API-Key`,
which is pinned to Admin.

### "Why is the audit log not catching some 403s?"

Two reasons:

- Sliding-window dedup. The same `(actor, path, action)` tuple
  writes at most one durable row per minute. The full reject series
  is still in the perishable application log
  (`[rbac] role insufficient ...`).
- Enforcement off. `rbac.access_denied` only writes when
  `tenant.enable_rbac=true`. The dormant mode just emits the warning
  log; member-management events do still write durably.

### "Can I have per-route ACL more granular than role + creator?"

Not in v1. The matrix is intentionally a small fixed lattice
(Viewer < Contributor < Admin < Owner) with one ownership escape
hatch per resource. Anything finer (e.g. "viewer can see audit log
for their own actions") is a follow-up.

### "Where do I see the audit log in the UI?"

`Settings → Members → Audit Log` tab (Admin+ only). Cursor-paginated
chronological feed with action / outcome chips. Filter UI is a v2.

## Testing & observability

- `make test` covers `internal/middleware/rbac_test.go`,
  `internal/handler/rbac_lookups_test.go`,
  `internal/application/service/audit_log_test.go` and
  `internal/middleware/rbac_audit_test.go` (~25 cases).
- e2e smoke under both flag values is documented in #1303 PR
  series. The matrix that ships green: each role × each guarded
  route → expected status code.
- Langfuse / OTel spans carry the resolved `TenantRole` and
  `TenantID`, so a denied request shows up as a single trace with
  the role on it — no need to correlate logs and traces by hand.