# Admin

## Summary

SCN Chat gets an admin area in the web app, and the database starts holding the settings that used to live in `config.yml`. This spec builds the foundation the other admin specs sit on: a store for admin settings, a built-in `admin` role seeded from the environment, the admin area itself, and user access control. Roles move from `config.yml` into the database. A role's members can be listed one by one, matched by the PDS they use or their handle's domain, or decided by a plugin, such as one that checks an external membership system. A registration setting decides who can create an account: anyone, members of chosen roles, or only people an admin adds. Once someone has an account they keep it whatever the setting says, until an admin or a plugin suspends it. Anyone turned away is told why and given their DID to pass to an admin. Someone who signs in from a shared chat link gets a viewer session that can open shared chats and nothing else.

This is the first of three specs. [[admin-plugins]] moves plugins and admin models into the admin area, and [[admin-settings]] moves the remaining settings and removes `config.yml`.

## Motivation

Until now anyone with an atproto account could sign in, and a server had no way to limit that. SCN Chat is a community project, so servers differ: some are open to anyone, some only to a community's members, and some only to people an admin picks. Admin models and the admin's web search engine are gated by role either way, so an open server doesn't pay for strangers. Keeping roles as DID lists in `config.yml` doesn't scale either: every change means editing a file and restarting the server, and the admin has to find each person's DID by hand.

A community running its own PDS, or handing out handles under its own domain, wants all of its people let in without listing anyone. Explicit members cover everyone else. Some communities already decide membership elsewhere. SCN members apply through a public record and are approved by admins in HappyView, and the server should honor that without an admin copying each approval by hand. Plugins can therefore act as role sources. Groups are otherwise kept in a plain internal schema for now. Once an atproto group model settles, likely on spaces, roles migrate to it, either directly or through a role source plugin.

Sharing must keep working on a closed server. A shared chat is read with the viewer's own credential, so the viewer has to sign in, and the owner shouldn't need the viewer to be a member of the server first.

Settings follow one rule, learned from Open WebUI, which takes defaults from environment variables and then stores them in its database, so later changes to the environment are silently ignored. Here each setting lives in exactly one place. Values the server needs before the database is open, and secrets that protect the database, stay in the environment. Everything an admin changes while the server runs lives in the database and is edited in the admin area.

## Design

### Settings store

A generic key-value table holds admin settings that are not plugin instances or models:

```
app_setting (key text primary key, value_json text, updated_at, updated_by)
```

Each key has a zod schema in `apps/server/src/settings/schemas.ts`. Values are validated on write and on read. A stored value that fails its schema fails loudly: startup stops, naming the key. A migration must convert stored values whenever a schema changes incompatibly. Adding a field with a default needs no migration, because the default applies on read.

`apps/server/src/settings/store.ts` exports a `SettingsStore` that loads every key at startup and keeps the current values in memory, since there is one server process. `get(key)` returns the current value, or the schema's defaults when nothing is stored. `set(key, value, adminDid)` validates, writes, updates the in-memory copy, and notifies subscribers, so code that needs to react to a change, such as a scheduler, can subscribe. Every write is logged at info with the key and the admin's DID, and never the value.

This spec adds one key, `access`. [[admin-settings]] adds the rest.

### Bootstrap admins

`ADMIN_DIDS` in `.env` is a comma-separated list of DIDs. It is required: startup fails when it is empty or holds an invalid DID, since otherwise nobody could ever reach the admin area. The listed DIDs always hold the `admin` role, always have access, and cannot be removed in the admin area, which shows them as coming from the environment. This keeps an admin from locking everyone out.

### Roles

Roles move from `config.yml` to the database, and the `roles` section of `config.yml` is removed.

```
role (name text primary key, description text, pds_hosts_json text, handle_domains_json text, created_at, updated_at)
role_member (role, did, added_at, added_by), primary key (role, did)
```

- **Built-in roles.** `user` is implicit, held by everyone who has signed in, and is never stored. `admin` is created by the migration and cannot be deleted. Neither can be renamed.
- **Names.** Role names match `^[a-z][a-z0-9-]*$` and cannot be changed after creation, since settings and models refer to roles by name.
- **Members.** A role's members come from the sources below, and a DID holds the role if any of them matches:
  - **Explicit members** in `role_member`. The admin adds them by handle or DID, and the server resolves a handle to its DID when it is added. People who have never signed in can be added ahead of time.
  - **PDS hosts** in `pds_hosts_json`, a list of hostnames such as `pds.commonscomputer.com`. A DID matches when the host of its PDS URL, from its DID document, equals one of them exactly.
  - **Handle domains** in `handle_domains_json`, a list of domains such as `commonscomputer.com`. A DID matches when its verified handle is the domain or ends in `.` plus the domain. Only the owner of a domain can hand out handles under it, and the server only stores handles that resolve back to the same DID, so the match can't be claimed by someone outside the domain.
  - **Role sources** registered by plugins, described below.
- **Deleting.** Deleting a role is refused while access or any admin model names it, and the error lists them.

`apps/server/src/auth/roles.ts` becomes a `Roles` service. `rolesFor({ did, handle, pdsUrl })` returns `user`, `admin` when the DID is in `ADMIN_DIDS`, every role whose database sources match, and every role the plugin role sources grant. It reads the database and asks the role sources on every call, so a change applies on the user's next request without a new login. The PDS URL and handle come from the `account` row, which sign-in updates, or from identity resolution during sign-in, before the row exists.

### Role sources

A plugin can decide role membership from outside the database by registering a role source in `setup`:

```ts
interface RoleSource {
  id: string // unique among role sources, like other registries
  rolesFor(identity: { did: string; handle?: string; pdsUrl: string }): Promise<string[]>
}

ctx.roleSources.register(source)
```

- **When it runs.** Every `rolesFor` call asks every role source, so a source is consulted at sign-in, before the access check, and on every request. A grant or revocation in the external system applies on the user's next request.
- **Caching** belongs to the plugin. Core doesn't remember a source's answers, so a source backed by a remote service caches inside the plugin, for as long as it judges safe.
- **Failures.** Core gives each call 2 seconds. A source that throws or times out contributes no roles for that call, and core logs a warning with the source ID and the DID. A plugin that wants to ride out an outage of its backend keeps its last good answer itself.
- **Names.** A source can only grant roles that exist. Unknown names and `admin` are ignored with a warning, so admin rights only ever come from the database and `ADMIN_DIDS`. A plugin that grants a role takes the role name as an option, so the admin picks it.
- **Plugin runtime.** Role sources live in the plugin host alongside providers and tools, so in [[admin-plugins]] they come from the current runtime, and saving a plugin's options changes them without a restart.
- **The admin area** shows a role granted by a source with the source's ID, and it can't be removed there.

### Registration

The `access` setting decides who can create an account:

```ts
access: {
  registration: 'open' | 'invite' | 'closed' // default 'open'
  inviteRoles: string[] // default [], used by 'invite'
}
```

| Mode | Who can create an account |
|---|---|
| `open` | Anyone with an atproto account. |
| `invite` | Anyone holding a role in `inviteRoles`, from any role source, and anyone an admin added. |
| `closed` | Only people an admin added. |

Creating an account means a first full sign-in, which records the account and runs the login hook. Admins can always create one. Every name in `inviteRoles` must be an existing role, checked on save.

**Access follows the account.** A user has full access to the chat app when they are an admin, or have an account that is neither viewer-only nor suspended. Changing the mode, or a user losing a role, doesn't take access away from anyone who already has an account. Removing someone is a suspension.

### Added users

An admin adds a person by handle or DID, and that person can then create an account in any mode. That is what makes `closed` usable, and it's a shortcut in `invite` mode.

```
account_invite (did text primary key, added_by, added_at)
```

The row is deleted when the person creates their account. Adding a DID that already has a full account is refused, since they already have access. An added person who hasn't signed in yet can be removed again.

### Suspension

A suspended account keeps its data and its OAuth session but loses access, so the server stops acting for it. Its owner can still sign in to view chats shared with them. The `account` table gains `suspended_at`, `suspended_by`, and `suspended_reason`, all null when the account isn't suspended. `suspended_by` is an admin's DID, or `plugin:<id>` for a plugin.

- **Admins** suspend and restore accounts on the Users page, with an optional reason.
- **Plugins** call `ctx.accounts.suspend(did, { reason })` and `ctx.accounts.restore(did)`, so a plugin that tracks membership elsewhere can act on a revocation. Core doesn't suspend anyone by itself. Both return whether an account changed.
- **Admins can't be suspended**, by an admin or a plugin, so nobody can lock the admins out. Remove the admin role first. Suspending someone who has no account is a no-op.
- **Reasons are admin notes.** They are shown on the Users page and never to the suspended user, so they can hold internal details.
- **The Users page** shows who suspended an account and why, and an admin can restore any suspension, including a plugin's. A plugin that still disagrees can suspend the account again.

### Viewers

Anyone can sign in to view a chat shared with them, whether or not they have access. A user who signs in without access, through a share link, becomes a viewer:

- **Shared routes.** A viewer can reach `GET /api/me`, `POST /api/logout`, and the `/api/shared` routes from the sharing spec, and nothing else. The owner's PDS still decides whether they may see the chat.
- **No setup.** A viewer's sign-in skips the login hook, so the server creates no settings space for them, doesn't register for their notifications, and never syncs, stores, or runs turns for them.
- **Account flag.** The `account` table gains `viewer_only`, set when an account is created by a viewer sign-in, and cleared when they create a full account, which runs the login hook. A viewer who later may create an account is asked to sign in again, so the login hook always runs before they use the chat app.

### Checking access

Access is checked in three places:

- **Sign-in.** `GET /oauth/callback` resolves the identity, as it does today, then decides before it creates or updates the account or a web session:
  - An admin, or an existing full account that isn't suspended, signs in as today.
  - Anyone else who may create an account under the current mode creates it: the sign-in clears `viewer_only`, runs the login hook, and deletes their `account_invite` row.
  - Anyone else whose `next` parameter is a share path, `/s/<ownerDid>/<skey>`, signs in as a viewer and returns to the shared chat.
  - Anyone else has their new OAuth session revoked and goes back to the login page with a message. No account row is created for them.
- **Every `/api` request.** The session middleware resolves the account, then checks access for every route a viewer can't reach. A user without full access gets 403 `{ error: 'AccessDenied', message }`. Their web session is kept, so shared chats still open. The web app shows the message, with sign-out and sign-in buttons, in place of the chat app on every route except shared chats.
- **Background work.** The turn runner doesn't start a turn for a user without full access, and logs the skip at info. The sync scheduler, discovery, and notification registration skip them the same way.

The messages, which name the user's DID so they can pass it to an admin:

| Situation | Message |
|---|---|
| Suspended | "Your account has been suspended. Contact an admin for details." |
| A viewer who may now create an account | "Sign in again to start using chat." |
| `invite` mode | "This server is invite-only. Ask an admin to add you, and give them your DID: did:plc:..." |
| `closed` mode | "This server isn't taking new accounts. Ask an admin to add you, and give them your DID: did:plc:..." |

### Admin checks

`requireAdmin` middleware guards every `/api/admin` route and returns 403 `{ error: 'Forbidden' }` when the user doesn't hold `admin`. `GET /api/me` gains `admin: boolean`, `access`, and `accessMessage`, the message a viewer sees, or null.

### Admin API

| Route | Purpose |
|---|---|
| `GET /api/admin/users?q=&cursor=` | Accounts, 50 at a time, newest activity first. Each has the DID, handle, storage mode, whether it is a viewer, its suspension, roles, and each role's source, including role sources, which are asked for each listed account, plus created and last-active times. `q` matches the start of a handle or DID. |
| `POST /api/admin/users` | Add a person from `{ identifier }`, a handle or DID, so they can create an account. |
| `GET /api/admin/invites`, `DELETE /api/admin/invites/:did` | People added who haven't created an account yet, and removing one. |
| `POST /api/admin/users/:did/suspend`, `POST /api/admin/users/:did/restore` | Suspend an account with an optional `{ reason }`, or restore it. |
| `GET /api/admin/roles` | Every role, with its description, explicit members with their handles, PDS hosts, and handle domains. `admin` also lists the DIDs from the environment, marked as such. |
| `POST /api/admin/roles` | Create a role from `{ name, description }`. |
| `PATCH /api/admin/roles/:name` | Change `description`, `pdsHosts`, or `handleDomains`. Hosts and domains must be valid hostnames. |
| `DELETE /api/admin/roles/:name` | Delete a role, refused for built-in roles and roles still in use. |
| `POST /api/admin/roles/:name/members` | Add a member from `{ identifier }`, a handle or DID. A handle that doesn't resolve is a 400 naming it. |
| `DELETE /api/admin/roles/:name/members/:did` | Remove an explicit member. Refused for DIDs from `ADMIN_DIDS`. |
| `GET /api/admin/access`, `PUT /api/admin/access` | Read and change the `access` setting. |

Writes are validated with zod, and a failure is a 400 with `{ error: 'InvalidRequest', issues: [{ path, message }] }`, so forms can show each message next to its field. That shape is shared by every admin form in the admin specs.

### Admin area

The web app gets an admin area at `/admin`, visible only to admins. It reuses the settings layout: a sidebar in the same style as the chat list, linking back to the chats and to each section, with only the current section shown. Non-admins who open an `/admin` route are redirected to `/`. The settings sidebar shows an "Admin" link for admins.

Sections in this spec:

- **Users** (`/admin/users`, the default). A form to add a person by handle or DID, the list of people added who haven't signed in yet, a search box, and a table of accounts with their handle, DID, storage mode, roles, last activity, and suspension, with viewers marked, and a "Load more" button. Each row can add the user to a role, remove them from one they hold explicitly, and suspend or restore them. Roles that come from a PDS host, handle domain, or role source are shown with their source but can't be removed there.
- **Roles** (`/admin/roles`). One block per role: its description, explicit members with a remove button, an input to add a member by handle or DID, and the PDS hosts and handle domains, one per line. A form at the end creates a role.
- **Access** (`/admin/access`). The registration mode, a checkbox per role for `inviteRoles`, shown in `invite` mode, and a Save button.

The UI stays as bare as the rest of the web app.

### Environment

| Variable | Purpose |
|---|---|
| `ADMIN_DIDS` | Comma-separated DIDs that always hold `admin`. Required. |

### Docs

`docs/architecture.md` gains a section on the admin area, access and viewers, and the split between environment and database settings. `docs/plugins.md` and the plugins spec document `ctx.roleSources.register`, and `setupForTest` records role sources like other registrations. `docs/deployment.md` explains `ADMIN_DIDS` and that a new server is open until an admin changes the registration mode. `docs/plugins.md` and the plugins spec document `ctx.accounts`. The sharing spec notes that viewers don't need access.

## Scope Boundaries

- No anonymous viewing. Viewers sign in, since the owner's PDS only grants reads to a user.
- No invite codes or links, and no sign-up requests for admins to approve.
- No suspending accounts automatically in core. A plugin can do it.
- No per-role limits on usage, quotas, or billing.
- No audit log table. Admin changes are written to the server log.
- No built-in roles from atproto lists, follows, or external group services. A role source plugin can provide them, and none ships with this spec.
- No caching of role source answers in core.
- No separate admin permissions. Every admin can change everything.
- No settings export or import.
- No multi-process deployments. The settings store assumes one server process.

## Edge Cases and Decisions

- `ADMIN_DIDS` is the one role source in the environment, so a broken database state or a mistaken edit can't lock every admin out.
- A new server is open, since servers run by different communities want different things, and an open server is what most people expect when they try it.
- The mode only decides who can create an account. Access follows the account, so changing the mode never cuts anyone off, and a lost role doesn't either. Removing someone is an explicit suspension, by an admin or a plugin.
- A plugin acts on a revocation elsewhere by suspending the account, on its own schedule. Vetoing access on every request instead would mean an outage of the plugin's backend either locked members out or let revoked people in.
- Admins always have access and can't be suspended.
- The suspended message is fixed. Sign-in errors travel in the login page's query string, so they end up in browser history and proxy logs, and a reason could hold internal details or text from a plugin's external system.
- A suspended user keeps their OAuth session and their data. The server only stops acting for them, and they can still view chats shared with them.
- A user turned away at sign-in has their OAuth session revoked, so the server never holds tokens for people it turned away. Viewers keep theirs, since reading a shared chat needs it.
- The access check happens at the callback, not before the redirect, because only the callback proves which DID signed in.
- Only a share path in `next` makes a viewer, so the login page never creates one.
- A viewer who later may create an account must sign in again, so the login hook creates their settings space before they use the chat app.
- PDS host matching uses the PDS from the DID document. Handle domains match the verified handle stored at each sign-in, so someone who moves to a handle outside the domain keeps the role until they next sign in.
- Role names are fixed at creation, since other settings refer to them by name.
- Admin error messages are shown to the admin as they are, so `InvalidBody` carries the message without a prefix, and its `issues` with the field paths.
- The users list pages with an offset cursor. Accounts are few enough that keyset paging isn't worth it.
- The user search matches the lowercased query against handles and DIDs with `LIKE`, escaping `%` and `_`.
- Role sources are asked on every check instead of storing what they grant, so a revocation in the external system applies without anyone removing a stored membership.
- A failing role source grants nothing, so an outage can lock its members out once the plugin's own cache runs out. Granting stale roles from core would hide the outage and keep revoked users in.
- Role sources can't grant `admin`, so a plugin can't hand out admin rights.
- An added person's row is kept until they create an account, so adding someone in `open` mode, where they don't need it, does no harm.
- Deleting a role that a plugin's options name isn't checked, since core can't tell which options are role names. The source's grants of it are then ignored with a warning.

## Acceptance Criteria

Settings store:

- [ ] A setting that was never stored reads as its schema's defaults.
- [ ] A write that fails the schema is refused, and a valid write is visible to `get` at once and notifies subscribers.
- [ ] A stored value that fails its schema stops startup, naming the key.

Bootstrap admins:

- [ ] Startup fails when `ADMIN_DIDS` is empty or holds an invalid DID.
- [ ] A DID in `ADMIN_DIDS` holds `admin`, has access whatever the registration mode says, and can't be removed through the API.

Roles:

- [ ] `rolesFor` returns `user`, plus every role whose explicit members, PDS hosts, or handle domains match.
- [ ] A PDS host matches the host of the PDS URL exactly, and not a subdomain.
- [ ] A handle domain matches the domain itself and its subdomains, and not a name that only ends with the same letters.
- [ ] Adding a member by handle stores the handle's DID, and a handle that doesn't resolve is a 400.
- [ ] A role change applies on the user's next request without a new login.
- [ ] Creating a role with an invalid name is refused, and built-in roles can't be deleted.
- [ ] Deleting a role named by access or an admin model is refused, listing what names it.

Role sources:

- [ ] Roles a source grants are included in `rolesFor`, and count as invite roles at sign-in.
- [ ] A source's change in answer applies on the user's next request.
- [ ] A source that throws or takes longer than 2 seconds contributes no roles and logs a warning, and the other sources still count.
- [ ] Unknown role names and `admin` from a source are ignored with a warning.
- [ ] Registering two role sources with the same ID fails, like other registries.
- [ ] The users list shows roles from a source with the source's ID, and doesn't offer to remove them.

Registration and access:

- [ ] A fresh install is open, and anyone can create an account.
- [ ] In `invite` mode, holders of an invite role and added people can create an account, and anyone else is turned away with the invite-only message naming their DID.
- [ ] In `closed` mode, only added people and admins can create an account, and anyone else is turned away with the closed message.
- [ ] A turned-away user's OAuth session is revoked and no account row is created.
- [ ] An existing account keeps access when the mode changes and when it loses a role.
- [ ] Creating an account deletes the added person's row.
- [ ] `inviteRoles` naming a role that doesn't exist is refused.
- [ ] The turn runner doesn't start a turn for a user without full access, and the sync scheduler and discovery skip them.

Added users and suspension:

- [ ] An admin adds a person by handle or DID, and adding someone who already has an account is refused.
- [ ] An added person who hasn't signed in can be removed.
- [ ] A suspended account gets 403 `AccessDenied` with the suspended message, never its reason, keeps its web session for shared chats, and gets no turns or sync.
- [ ] A suspended user who signs in from the login page is turned away with the suspended message, and from a share link gets a viewer session.
- [ ] Restoring an account gives it access again on its next request.
- [ ] Admins can't be suspended, by an admin or a plugin.
- [ ] `ctx.accounts.suspend` and `restore` change the account, record `plugin:<id>`, and return whether an account changed.

Viewers:

- [ ] A user who may not create an account and signs in with a share path in `next` gets a viewer session and returns to the shared chat.
- [ ] A viewer can open a chat shared with them and gets 403 `AccessDenied` from every other route except `/api/me` and logout.
- [ ] A viewer sign-in creates no settings space and runs no sync.
- [ ] `GET /api/me` reports `access: 'viewer'` for a viewer and `'full'` for a user with access.
- [ ] A viewer who may now create an account is told to sign in again, and that sign-in runs the login hook and clears the flag.
- [ ] A user with access who signs in through a share link gets a full session.

Admin API and area:

- [ ] Every `/api/admin` route returns 403 for a user who isn't an admin.
- [ ] `GET /api/me` includes `admin`.
- [ ] A write that fails validation returns 400 with the issue paths and messages.
- [ ] The users list pages 50 at a time and filters by handle or DID prefix.
- [ ] The admin area redirects non-admins to `/`, and the settings sidebar shows the Admin link only to admins.
- [ ] The roles section adds and removes members, and saves PDS hosts and handle domains.
- [ ] The access section saves the registration mode and invite roles.
- [ ] The users section adds people, removes added people, and suspends and restores accounts.
- [ ] The web app shows the access message in place of the chat app for viewers, and still opens shared chats.

## Files

- `apps/server/src/settings/store.ts`, `apps/server/src/settings/schemas.ts`
- `apps/server/src/auth/roles.ts`, `apps/server/src/auth/access.ts`, `apps/server/src/auth/accounts.ts`, `apps/server/src/auth/invites.ts`
- `packages/plugin-api/src/index.ts`, `packages/plugin-api/src/testing.ts`, `apps/server/src/plugins/host.ts`
- `apps/server/src/auth/routes.ts`, `apps/server/src/auth/web-session.ts`
- `apps/server/src/admin/routes.ts`
- `apps/server/src/turns/runner.ts`, `apps/server/src/sync/scheduler.ts`
- `apps/server/src/config.ts`, `apps/server/src/server.ts`
- `apps/server/src/db/migrations/0007_admin.ts`, `apps/server/src/db/migrations/0009_registration.ts`
- `apps/web/src/pages/AdminPage.tsx`, `apps/web/src/pages/SettingsPage.tsx`, `apps/web/src/App.tsx`
- `.env.example`, `docs/architecture.md`, `docs/deployment.md`, `docs/plugins.md`, `specs/sharing.md`, `specs/plugins.md`