Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version

## Unreleased

- **Roles with permissions.** Viewer, editor and owner are now sets of permissions (read, edit, import, process,
curate, share, publish, remove, members, manage), and admins make custom roles from them in Admin → Roles, given per
namespace like the built-in ones. Existing access is unchanged. Someone who manages members but isn't an admin gives
only roles they hold all of ([Access](docs/access.md#roles-and-permissions)).

- **Invite and remove people.** Making an account in Admin → People now emails the sign-in link as an invitation when
mail is set up, and the link is still shown to share yourself. **Remove for good** ends every way someone signs in,
takes their roles and their private chats, notes and views, and keeps what they shared under their name; their email
Expand Down
34 changes: 34 additions & 0 deletions docs/access.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,40 @@ publishes them. Permission doesn't open the workspace: that stays with the names

In the matrix, view and edit permission open the same pages; Lens has one permission for both.

## Roles and permissions

A role in a namespace is a set of **permissions**. Every role reads; the rest are what it may change:

| Permission | Allows | Built-in roles with it |
|---|---|---|
| `read` | see, search, listen and chat; write your own notes | viewer, editor, owner |
| `edit` | edit transcripts, catalogue records, tags, fields, collections, and notes and comments for everyone | editor, owner |
| `import` | add recordings, documents and images: uploads, imports, RDF | editor, owner |
| `process` | reprocess, run pipelines, workflows, routines and batches | editor, owner |
| `curate` | rename and merge speakers, faces, entities and topics; change the graph | editor, owner |
| `share` | make, list and revoke share links | editor, owner |
| `publish` | set access, open parts and featured; give permission on recordings; answer access requests | owner |
| `remove` | delete recordings and move them to another namespace | owner |
| `members` | give people roles in the namespace | owner |
| `manage` | namespace settings: metadata profile, notifications, import hooks, IP groups, the assistant, vaults | owner |

**Viewer**, **editor** and **owner** are built in and can't change, so access people already had stays as it was.
Admins make **custom roles** in Admin → Roles (`POST /api/v1/roles` with a name, a label and permissions) and give
them per namespace like the built-in ones: in People's role grid, a namespace's members, or
`PUT /api/v1/namespaces/<name>/members`. A change to a custom role holds for everyone with it at once; a role someone
holds can't be deleted. Making, changing and deleting roles is audited as `role.create`, `role.update` and
`role.delete`.

The permissions above are checked as named. A custom role also counts as the largest built-in role whose
permissions it all has (its **rank**, shown in Admin → Roles), and the checks that still ask for a rank give it
that much: the notebook, comment threads, collection roles and the pages a namespace's members see. So a custom role
never does more than its permissions, but may do less than them there until those checks move to permissions too.

Someone with the `members` permission who isn't an admin gives only roles whose permissions they hold all of, and
changes only people whose role they hold all of: they can't promote themselves or take out an owner. Collection roles
(below) stay viewer, editor and admin. API tokens and apps keep their read or write scope on top of the role: a
read-only token can't use a role's write permissions. `GET /api/v1/auth/me` lists your permissions in each namespace.

## Collection roles

Every recording lives in a collection of its namespace ([API](api.md#collections-of-a-namespace)), and people can be
Expand Down
6 changes: 5 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,11 @@ PATCH /api/v1/users/{uid}
DELETE /api/v1/users/{uid} remove for good (authentication.md#removing-someone)
POST /api/v1/users/{uid}/signin-link ?email=true also emails it
GET /api/v1/namespaces/{name}/members
PUT /api/v1/namespaces/{name}/members
PUT /api/v1/namespaces/{name}/members {email | account, role}: built-in or custom; null removes
GET /api/v1/roles the permissions and every role (access.md#roles-and-permissions)
POST /api/v1/roles admins: {name, label, description, permissions}
PATCH /api/v1/roles/{name} admins: a custom role's label, description, permissions
DELETE /api/v1/roles/{name} admins: a custom role nobody holds
```

## admin
Expand Down
3 changes: 2 additions & 1 deletion docs/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
There is no public sign-up. The first admin is created with a one-time **setup code** that the API prints in its log
on first start (or `lens users add you@example.com --admin`, or `LENS_ADMIN_EMAIL` in `.env`). On a fresh install the
web app then opens a short setup wizard ([Configuration](configuration.md#first-run-setup)). Admins then add people and
give them roles per namespace: viewer, editor or owner.
give them roles per namespace: viewer, editor, owner, or a custom role made of permissions
([Access](access.md#roles-and-permissions)).

## Signing in: passkeys

Expand Down
24 changes: 20 additions & 4 deletions fastapi_backend/app/api/deps.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
from app.core import security
from app.domain import access as acc
from app.domain import auth, graph_history, hierarchy, ipgroups, oauth, store
from app.domain import roles as rl
from app.domain.store import DB

Config = dict[str, Any]
Expand All @@ -51,7 +52,8 @@ class Principal:
via: Literal["access", "token", "oauth"] # a signed-in session, an API token, or an app given access (OAuth)
scope: Literal["read", "write"] = "write"
sid: str | None = None
roles: dict[int, str] = field(default_factory=dict)
roles: dict[int, str] = field(default_factory=dict) # as built-in roles: a custom role counts as its rank
perms: dict[int, frozenset[str]] = field(default_factory=dict) # what each namespace role allows (roles.py)
collections: dict[int, dict[int, str]] = field(default_factory=dict) # roles on collections: {space: {collection: role}}
resource: str | None = None # an app's token: the server it was given for (RFC 8707), when the app named one

Expand Down Expand Up @@ -93,7 +95,8 @@ def _resolve(request: Request, db: DB) -> Principal | None:
if u and claims:
p = Principal(u["id"], u["email"], u.get("name"), bool(u.get("admin")), "access", "write", claims.sid)
if p:
p.roles = auth.roles(db, {"id": p.id, "admin": p.admin})
p.perms = auth.permissions(db, {"id": p.id, "admin": p.admin})
p.roles = {sid: rl.rank(perms) for sid, perms in p.perms.items()}
p.collections = {} if p.admin else hierarchy.roles_of(db, p.id)
request.state.principal = p
return p
Expand Down Expand Up @@ -162,12 +165,20 @@ def readable(self) -> set[int] | None:
def editable(self) -> list[int]:
return sorted(s for s in self.roles if auth.allows(self.roles, s, "editor"))

def can(self, sid: int, perm: str) -> bool:
"""Whether this person's role in namespace `sid` has a permission (roles.py)."""
return bool(self.user) and perm in self.user.perms.get(sid, frozenset()) # type: ignore[union-attr]

def need(self, sid: int, role: str = "viewer") -> None:
"""A role (viewer, editor, owner: at least that rank) or a permission (roles.PERMISSIONS) in namespace `sid`."""
if not self.user:
raise HTTPException(401, "sign in first", headers={"WWW-Authenticate": "Bearer"})
if not auth.allows(self.roles, sid, "viewer"):
raise HTTPException(404, "not found")
if not auth.allows(self.roles, sid, role):
if role in rl.PERMISSIONS:
if not self.can(sid, role):
raise HTTPException(403, f"needs the {role} permission in this namespace")
elif not auth.allows(self.roles, sid, role):
raise HTTPException(403, f"needs {role} access to this namespace")

def collection_role(self, sid: int, cid: int | None) -> str | None:
Expand All @@ -193,7 +204,12 @@ def need_in(self, sid: int, cid: int | None, role: str = "viewer") -> None:
have = self.rank_in(sid, cid)
if not have:
raise HTTPException(404, "not found")
if have < auth.ROLES[role]:
if role in rl.PERMISSIONS:
# the namespace role's permission, or a collection role ranking as the built-in role that first has it
coll = hierarchy.ROLES.get(self.collection_role(sid, cid) or "", 0)
if not self.can(sid, role) and coll < auth.ROLES[rl.minimum(role)]:
raise HTTPException(403, f"needs the {role} permission for this recording")
elif have < auth.ROLES[role]:
raise HTTPException(403, f"needs {role} access to this recording")

def partial(self) -> dict[int, list[int]]:
Expand Down
1 change: 1 addition & 0 deletions fastapi_backend/app/api/v1/routes/auth.py
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,7 @@ def me(user: CurrentUser, db: Db) -> Me:
return Me(
user=UserPublic(**(auth.active_account(db, user.id) or {})),
roles=roles,
permissions={names.get(k, str(k)): sorted(v) for k, v in user.perms.items()},
partial=partial,
via=user.via,
scope=user.scope,
Expand Down
6 changes: 3 additions & 3 deletions fastapi_backend/app/api/v1/routes/comments.py
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ def list_highlights(rid: int, user: CurrentUser, acl: Acl, db: Db) -> list[Highl
def create_highlight(rid: int, body: HighlightCreate, user: Writer, acl: Acl, db: Db) -> Highlight:
"""Mark a passage (`t0`–`t1`, with the `quote` picked in the text) in a `colour` (yellow, green, blue or red),
with a `label`: editors of the resource. Up to 1,000 on a resource."""
rec = _recording(acl, db, rid, "editor")
rec = _recording(acl, db, rid, "edit")
with domain_errors():
hid = highlights.create(
db, rid, rec["space"], user.id, body.t0, body.t1, body.quote, body.colour, body.label, rec.get("duration_ms")
Expand All @@ -194,7 +194,7 @@ def create_highlight(rid: int, body: HighlightCreate, user: Writer, acl: Acl, db
@router.patch("/highlights/{hid}")
def update_highlight(rid: int, hid: int, body: HighlightUpdate, user: Writer, acl: Acl, db: Db) -> Highlight:
"""Change its colour or its label (an empty label clears it): editors of the resource."""
rec = _recording(acl, db, rid, "editor")
rec = _recording(acl, db, rid, "edit")
_highlight(db, rid, hid)
if body.colour is None and body.label is None:
raise HTTPException(400, "change the colour or the label")
Expand All @@ -206,7 +206,7 @@ def update_highlight(rid: int, hid: int, body: HighlightUpdate, user: Writer, ac
@router.delete("/highlights/{hid}")
def delete_highlight(rid: int, hid: int, user: Writer, acl: Acl, db: Db) -> Ok:
"""Delete it: editors of the resource. Audited (`highlight.delete`)."""
_recording(acl, db, rid, "editor")
_recording(acl, db, rid, "edit")
h = _highlight(db, rid, hid)
highlights.delete(db, hid)
auth.audit(db, user.as_audit(), "highlight.delete", f"recording:{rid}", {"highlight": hid, "writer": h["account"] == user.id})
Expand Down
2 changes: 1 addition & 1 deletion fastapi_backend/app/api/v1/routes/content_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ def get_recording_content_type(rid: int, acl: Acl, db: Db) -> RecordingContentTy
@router.put("/recordings/{rid}/content-type")
def set_recording_content_type(rid: int, body: RecordingContentTypeSet, user: Writer, acl: Acl, db: Db) -> RecordingContentType:
"""Choose the resource's subtype (null: recognise it from the file again). Editors. New runs use its pipeline."""
acl.recording(rid, "editor")
acl.recording(rid, "edit")
try:
content_types.choose(db, rid, body.content_type)
except ValueError as e:
Expand Down
26 changes: 13 additions & 13 deletions fastapi_backend/app/api/v1/routes/entities.py
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ def get_entity_timeline(user: CurrentUser, acl: Acl, db: Db, ids: str, by: str =
@router.post("/entities/retype")
def retype_entities(body: EntityRetype, request: Request, user: Writer, acl: Acl, db: Db) -> Ok:
for i in body.ids:
_entity_space(db, acl, i, "editor")
_entity_space(db, acl, i, "curate")
with domain_errors():
ents.retype(db, body.ids, body.type)
auth.audit(db, user.as_audit(), "entity.retype", None, {"ids": body.ids, "type": body.type})
Expand All @@ -164,7 +164,7 @@ def retype_entities(body: EntityRetype, request: Request, user: Writer, acl: Acl
@router.post("/entities/merge")
def merge_entities(body: EntityMerge, request: Request, user: Writer, acl: Acl, db: Db) -> EntityMerged:
for i in [body.keep, *body.others]:
_entity_space(db, acl, i, "editor")
_entity_space(db, acl, i, "curate")
with domain_errors():
mid = ents.merge(db, body.keep, body.others, user.email)
auth.audit(db, user.as_audit(), "entity.merge", f"entity:{body.keep}", {"others": body.others})
Expand All @@ -177,7 +177,7 @@ def undo_entity_merge(mid: int, request: Request, user: Writer, acl: Acl, db: Db
m = db.one("SELECT space FROM $r", r=R("entity_merge", mid))
if not m:
raise HTTPException(404, "not found")
acl.need(m["space"], "editor")
acl.need(m["space"], "curate")
with domain_errors():
ents.undo_merge(db, mid)
auth.audit(db, user.as_audit(), "entity.merge.undo", f"entity_merge:{mid}")
Expand All @@ -188,8 +188,8 @@ def undo_entity_merge(mid: int, request: Request, user: Writer, acl: Acl, db: Db
@router.post("/entities/not-same")
def mark_entities_not_same(body: EntityNotSame, user: Writer, acl: Acl, db: Db) -> Ok:
"""Stop suggesting that these two are the same."""
_entity_space(db, acl, body.a, "editor")
_entity_space(db, acl, body.b, "editor")
_entity_space(db, acl, body.a, "curate")
_entity_space(db, acl, body.b, "curate")
ents.not_same(db, body.a, body.b)
auth.audit(db, user.as_audit(), "entity.not_same", None, {"a": body.a, "b": body.b})
return Ok()
Expand Down Expand Up @@ -235,7 +235,7 @@ def get_entity_connections(eid: int, user: CurrentUser, acl: Acl, db: Db) -> dic
@router.post("/entities/{eid}/rename")
def rename_entity(eid: int, body: EntityRename, request: Request, user: Writer, acl: Acl, db: Db) -> dict[str, Any]:
"""Rename; with `correct`, also fix the transcript lines (re-analysing the recordings). `dry_run` previews the lines."""
_entity_space(db, acl, eid, "editor")
_entity_space(db, acl, eid, "curate")
with domain_errors():
out = ents.rename(db, eid, body.name, body.keep_alias, body.correct, body.dry_run)
if not body.dry_run:
Expand All @@ -248,7 +248,7 @@ def rename_entity(eid: int, body: EntityRename, request: Request, user: Writer,
@router.patch("/entities/{eid}")
def update_entity(eid: int, body: EntityUpdate, request: Request, user: Writer, acl: Acl, db: Db) -> EntityDetail:
"""Describe the entity (what it is, in your words), say how else it's said, or put it on (or off) the fixed list."""
sid = _entity_space(db, acl, eid, "editor")
sid = _entity_space(db, acl, eid, "curate")
changes = body.model_dump(exclude_unset=True)
with domain_errors():
if "description" in changes:
Expand All @@ -270,7 +270,7 @@ def update_entity(eid: int, body: EntityUpdate, request: Request, user: Writer,
@router.delete("/entities/{eid}")
def delete_entity(eid: int, request: Request, user: Writer, acl: Acl, db: Db) -> Ok:
"""Take a defined entity that nothing mentions off the fixed list."""
_entity_space(db, acl, eid, "editor")
_entity_space(db, acl, eid, "curate")
with domain_errors():
ents.remove(db, eid)
auth.audit(db, user.as_audit(), "entity.delete", f"entity:{eid}", None)
Expand All @@ -296,7 +296,7 @@ def define_entity(name: str, body: EntityDefine, request: Request, user: Writer,
@router.post("/entities/{eid}/hide")
def hide_entity(eid: int, request: Request, user: Writer, acl: Acl, db: Db, body: EntityHide | None = None) -> Ok:
body = body or EntityHide()
_entity_space(db, acl, eid, "editor")
_entity_space(db, acl, eid, "curate")
with domain_errors():
ents.hide(db, eid, body.hidden, body.reason)
action = "entity.hide" if body.hidden else "entity.restore"
Expand All @@ -309,8 +309,8 @@ def hide_entity(eid: int, request: Request, user: Writer, acl: Acl, db: Db, body
def link_entity(eid: int, body: EntityLinkRequest, request: Request, user: Writer, acl: Acl, db: Db) -> Ok:
"""Say an entity in another namespace is the same thing (they stay separate; the graph joins them)."""
other = body.with_
_entity_space(db, acl, eid, "editor")
_entity_space(db, acl, other, "editor")
_entity_space(db, acl, eid, "curate")
_entity_space(db, acl, other, "curate")
with domain_errors():
ents.link(db, eid, other)
auth.audit(db, user.as_audit(), "entity.link", f"entity:{eid}", {"with": other})
Expand All @@ -320,7 +320,7 @@ def link_entity(eid: int, body: EntityLinkRequest, request: Request, user: Write

@router.delete("/entities/{eid}/link/{other}")
def unlink_entity(eid: int, other: int, request: Request, user: Writer, acl: Acl, db: Db) -> Ok:
_entity_space(db, acl, eid, "editor")
_entity_space(db, acl, eid, "curate")
ents.unlink(db, eid, other)
auth.audit(db, user.as_audit(), "entity.unlink", f"entity:{eid}", {"with": other})
_changed(request)
Expand All @@ -333,7 +333,7 @@ def move_mention(mention: str, body: MentionMove, request: Request, user: Writer
m = db.one("SELECT space FROM $r", r=R("mentions", mention))
if not m:
raise HTTPException(404, "not found")
acl.need(m["space"], "editor")
acl.need(m["space"], "curate")
try:
tid = ents.move_mention(db, mention, body.target, body.new_name, body.new_type or "TERM", body.remove)
except (ValueError, KeyError) as e:
Expand Down
4 changes: 2 additions & 2 deletions fastapi_backend/app/api/v1/routes/fields.py
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ def get_resource_fields(rid: int, acl: Acl, user: CurrentUser, db: Db) -> FieldV
def save_resource_fields(rid: int, body: FieldValuesUpdate, acl: Acl, user: Writer, db: Db, cfg: Cfg) -> FieldValues:
"""Set or clear (null) the resource's values for the fields named; the others keep theirs. Editors. Kept in its
metadata history (so a revert puts them back) and audited as `fields.save`."""
rec = acl.recording(rid, "editor")
rec = acl.recording(rid, "edit")
defs, row = fieldmod.resource_fields(db, rid)
with domain_errors():
after = fieldmod.merged(row, defs, _changes(body))
Expand Down Expand Up @@ -238,7 +238,7 @@ def get_file_fields(rid: int, fid: int, acl: Acl, user: CurrentUser, db: Db) ->
@router.put("/recordings/{rid}/files/{fid}/fields")
def save_file_fields(rid: int, fid: int, body: FieldValuesUpdate, acl: Acl, user: Writer, db: Db) -> FieldValues:
"""Set or clear (null) the file's values for the fields named. Editors of the resource; audited as `fields.save`."""
rec = acl.recording(rid, "editor")
rec = acl.recording(rid, "edit")
row = _file_row(db, rid, fid)
defs = fieldmod.applying(db, rec["space"], "file", rec.get("collection"))
with domain_errors():
Expand Down
2 changes: 1 addition & 1 deletion fastapi_backend/app/api/v1/routes/files.py
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ async def _receive(request: Request, cfg: dict[str, Any]) -> pathlib.Path:


def _editor(acl: Access, rid: int) -> dict[str, Any]:
return acl.recording(rid, "editor")
return acl.recording(rid, "edit")


@router.post("", openapi_extra=CHUNK)
Expand Down
2 changes: 1 addition & 1 deletion fastapi_backend/app/api/v1/routes/graph.py
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ def propose_graph_change(request: Request, body: ChangeAsk, user: Writer, acl: A
except KeyError:
raise HTTPException(404, "not found") from None
for r in rows:
acl.need(r["space"], "editor")
acl.need(r["space"], "curate")
origin = {"by": user.email, "via": user.via}
try:
cid, status = organize.propose(db, body.kind, ids[0], ids[1], body.reason, origin, body.apply, user.email)
Expand Down
2 changes: 1 addition & 1 deletion fastapi_backend/app/api/v1/routes/graph_history.py
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ def graph_rollback(request: Request, body: RollbackAsk, user: Writer, acl: Acl,
if editable is not None and not editable:
raise HTTPException(403, "rolling back needs editor access to a namespace")
if body.namespace:
spaces: set[int] | None = {acl.namespace(body.namespace, "editor")}
spaces: set[int] | None = {acl.namespace(body.namespace, "curate")}
else:
spaces = editable
try:
Expand Down
Loading
Loading