# Auth And RBAC

This page describes the current AIBS auth and RBAC model.

AIBS is an independent product, but this phase reuses the configured
OpenSearch/Logserver identity store for credentials and user records. AIBS does
not treat a generic Logserver administrator as an AIBS administrator by default.
Product access is explicit.

## Identity Source

Login uses the configured OpenSearch/Logserver credentials:

- standard OpenSearch Security authinfo responses are supported
- Logserver clusters can authenticate through `/_logserver/login`
- successful authentication is not enough to enter AIBS

The authenticated principal must have AIBS product access:

- `aibs-access`: may enter AIBS
- `aibs-admin`: may administer AIBS product users, but only when combined with
  `aibs-access`

The product intentionally keeps these roles separate from generic Logserver
roles such as `admin` or `gui-access`.

## Sessions

Successful login creates an opaque server-side session id stored in an
HTTP-only browser cookie.

Current limits:

- sessions have a fixed TTL
- sessions are process-local memory
- run a single API worker until a persistent session store is implemented

`X-AIBS-User-Id` is only accepted when `AIBS_AUTH_DEV_MODE=true`. Production
and demo non-dev mode ignore that header.

## First Admin Bootstrap

Before first non-dev login, bootstrap one AIBS admin:

```powershell
python -m pdm run python -m aibs_backend.interfaces.cli.bootstrap_admin --username <admin-user>
```

Behavior:

- if the user exists, the CLI idempotently grants missing `aibs-access` and
  `aibs-admin`
- if the user does not exist, the CLI prompts for a masked password and creates
  the user with both AIBS roles
- if the user has only `aibs-admin`, the CLI normalizes the user to both
  `aibs-access` and `aibs-admin`
- the CLI loads `.env` before reading `AIBS_OPENSEARCH_*`
- passwords are not printed

Without this bootstrap, a valid Logserver user without `aibs-access` should get
`403 AIBS_ACCESS_REQUIRED`. That is expected behavior, not a bad password.

## Product User Management

AIBS admins manage product users through:

```text
/api/aibs/admin/users
```

Only principals with both `aibs-access` and `aibs-admin` may use these routes.

Current capabilities:

- list AIBS users
- optionally include non-AIBS directory users
- fetch one directory user
- create a user with `aibs-access`
- optionally create the user as an AIBS admin
- grant or revoke `aibs-access`
- grant or revoke `aibs-admin`
- reset a user's password
- disable a user where the backing directory supports it

Safety rules:

- the last enabled AIBS admin cannot be removed or disabled
- AIBS role mutations preserve non-AIBS roles returned by the directory
- user-directory operations emit structured audit logs
- password complexity is currently delegated to the backing identity store

## Workspace Roles

Workspace membership is separate from product access.

Product roles answer "can this person enter/administer AIBS?" Workspace roles
answer "what can this person do in this workspace?"

Workspace roles:

- `owner`: full workspace control, including delete and ownership changes
- `admin`: manage workspace state, documents, and non-owner members
- `member`: upload/process documents and ask questions
- `viewer`: read workspace state and ask questions

Important boundary:

- `aibs-admin` does not automatically grant access to every workspace
- workspace visibility comes from workspace membership
- workspace deletion remains owner-only

## Workspace Member Management

Workspace owners and admins can manage non-owner members.

Current member-add behavior:

- the preferred request field is `username`
- `user_id` remains as a deprecated compatibility field
- username-based member add resolves through the AIBS user directory
- unknown usernames are rejected with a typed directory-not-found error
- the stored membership uses the directory record's canonical `user_id` and
  username
- if both `username` and `user_id` are supplied, they must refer to the same
  directory user

This closes the old ghost-membership gap where free-form text could create a
workspace member that was not a real product user.

Owner rules:

- only an owner may add another owner
- only an owner may demote or remove an owner
- the workspace must keep at least one owner

Admin rules:

- workspace admins can add/change/remove `admin`, `member`, and `viewer`
  memberships
- workspace admins cannot delete the workspace
- workspace admins cannot change ownership

Viewer rules:

- viewers may read workspace state and ask questions
- viewers may not upload, process, manage members, archive, rename, or delete
  the workspace

## Frontend Visibility

The frontend should treat backend authorization as source of truth.

Current UI shape:

- logged-in user menu exposes Settings and Log out
- Settings includes:
  - General
  - Prompt Library
  - Integrations
  - User management only for AIBS admins
- workspace member management lives in the workspace details surface
- access-only users do not see product user administration

Backend routes still enforce the same boundary even if the frontend hides or
shows a control incorrectly.

## Known Deferrals

Not solved in this phase:

- persistent session store
- distributed lock for multi-process last-admin protection
- dedicated audit table
- password complexity policy owned by AIBS
- full external identity-provider abstraction beyond the current
  OpenSearch/Logserver provider
- production-grade metadata persistence replacing local JSON records