docs(api/adr): add ADR-011 authorisation at the edge and sweep refs

Author: RobertRosca

api/docs/adr/000-vertical-slice-architecture.md

@@ -83,7 +83,7 @@ damnit_api/
 │   ├── serialization.py, preview.py
 │   └── gql.py       #   Strawberry types + Query/Subscription contributions
 │
-├── auth/            # OIDC flow, sessions, tokens, users, authz policy
+├── auth/            # OIDC flow, sessions, tokens, users, authz policy; see ADR-011
 ├── contextfile/     # context-file (REST) endpoints
 ├── mymdc/           # MyMdC port
 ├── appdb/           # application-DB engine/session/models; see ADR-010

api/docs/adr/011-authorisation-at-the-edge.md

@@ -0,0 +1,42 @@
+---
+date: 2026-07-08
+---
+
+# ADR-011 - Authorisation at the edge
+
+## Context and Problem Statement
+
+Proposal-membership authorisation was scattered and pointed the wrong way. The single predicate lived in `metadata/services.py` (`_check_user_allowed`), and the metadata services called it inline before each operation. The GraphQL permission classes reached into that same private function - an `auth`-to-`metadata` import which, together with `metadata` importing `auth` for the `User` type, formed a dependency cycle that [ADR-000](000-vertical-slice-architecture.md) forbids (`metadata -> auth`).
+
+Domain services performing authorisation also couples them to the request. A service can then only be called where a `User` is in scope, and the same check runs redundantly at the resolver and in the service.
+
+Separately, an unauthenticated GraphQL request produced a 500 rather than a 401.
+
+## Considered Options
+
+- One policy in `auth/`, enforced only at the transport edges.
+- Keep the check inline in the domain services.
+- A single global authorisation middleware.
+
+## Decision Outcome
+
+Chosen option: "one policy in `auth/`, enforced at the edges", because it gives the membership decision a single home in the slice that owns identity and leaves the domain services authorisation-free.
+
+`auth/policy.py` owns `require_proposal_member(user, proposal_number)`. Enforcement happens only at the edges: Strawberry permission classes for GraphQL fields, and a Litestar guard (`proposal_member_guard`) wired onto the proposal-scoped REST routers in the composition root. Local mode composes the guard out ([ADR-008](008-local-mode-composition.md)). The permission classes live in `shared/permissions.py` as transport adapters over the policy, so any slice's GraphQL contribution can attach them without importing `auth`. Domain services take plain parameters.
+
+Authentication failures now raise `UnauthenticatedError`, which the error handler renders as a 401.
+
+### Consequences
+
+- Good: domain services are reusable and context-agnostic; the `auth <-> metadata` cycle is broken.
+- Good: authorisation has one auditable choke point per transport.
+- Bad: two edge mechanisms - the GraphQL permission classes and the REST guard - must stay in step.
+- Bad: the permission adapters put Strawberry types in `shared/`, which is otherwise framework-light.
+
+## Details
+
+Authentication (OIDC on server-side sessions) is unchanged; it is covered by the framework and session decisions in [ADR-006](006-litestar.md). This decision concerns authorisation and the authentication *edge*, the 401.
+
+The adapters live in `shared/permissions.py` rather than the `graphql/` transport package so that a slice depends only on `shared`, which is always an allowed direction, and never on the composition/transport package. The policy predicate stays in `auth/` because membership is identity: `auth -> proposals`/`metadata` is the one allowed cross-slice edge ([ADR-000](000-vertical-slice-architecture.md)), and `auth/policy.py` itself needs no `metadata` import.
+
+The 401 is a clean JSON body, not a redirect. A GraphQL request is an XHR call, so the single-page app performs the login redirect on a 401 rather than following a server redirect to the login page.

api/docs/architecture.md

@@ -20,7 +20,7 @@ For more information, see [ADR-000](adr/000-vertical-slice-architecture.md).
 | --------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------- |
 | `runs/`                           | Run/variable data - the core domain     | Domain models, repository interface + implementations (see [ADR-005](adr/005-repository-pattern.md)), serialisation, preview extraction, its GraphQL types and resolvers | Partial | `runs/` (repository, models, sqlite + csv backends); resolvers still in `graphql/queries.py`/`subscriptions.py` |
 | `proposals/`                      | Proposal metadata and lookup            | Proposal models, MyMdC-backed metadata services, path locator (see [ADR-004](adr/004-proposal-path-locator.md))            | Planned | `metadata/`                                                               |
-| `auth/`                           | Authentication and authorisation        | OAuth flow, sessions, token store, `User`, permission classes, the membership policy                                      | Partial | Policy still in `metadata/services.py`                                    |
+| `auth/`                           | Authentication and authorisation        | OAuth flow, sessions, token store, `User`, the membership policy (see [ADR-011](adr/011-authorisation-at-the-edge.md))     | Partial | Policy in `auth/policy.py`; permission adapters in `shared/permissions.py` |
 | `contextfile/`                    | Context-file viewing                    | File reading, watching, its routes                                                                                        | Done    | As-is                                                                     |
 | `graphql/`                        | GraphQL transport only                  | Schema assembly, context, directives, controller binding - no resolvers, no domain logic (see [ADR-007](adr/007-graphql-transport-only.md)) | Partial | Assembly still in `shared/gql.py`; resolvers still here                   |
 | `appdb/`                          | The app's own database (infrastructure) | Models, engine/session plumbing for `dw_api.sqlite` (see [ADR-010](adr/010-two-databases.md))                            | Partial | `_db/` (Advanced Alchemy `SQLAlchemyPlugin`); `metadata/repository.py`    |
@@ -56,15 +56,14 @@ The key rules are:
 2. **Composition root is the top:** it may import everything, but nothing is allowed to import it.
   - If importing a slice from the composition root forces a function-body import to avoid cycles, the type probably belongs in `core/`.
 3. **Composition root reads settings:** everything else receives configuration as parameters (see [ADR-003](adr/003-injected-settings.md)).
-4. **Authorisation applied at the edge:** routes and resolvers use dependencies and permission classes.
+4. **Authorisation applied at the edge:** routes and resolvers use dependencies and permission classes (see [ADR-011](adr/011-authorisation-at-the-edge.md)).
   - This means that services should not apply authorisation rules themselves.
 5. **No `if settings.is_local:` outside the composition root:** Local mode is selected by composition, not conditionals throughout the codebase (see [ADR-008](adr/008-local-mode-composition.md)).
 
 Note that these are currently only enforced by convention/review. Import linter/archetecture check tool is planned to be added.
 
 !!! warning "Current issues"
 
-    - `auth` <--> `metadata` import cycle
     - `shared/gql.py`'s import-everything role
     - Function-body imports working around circular imports
     - Imports 'across' many modules and their files

api/zensical.toml

@@ -21,6 +21,8 @@ nav = [
       "adr/007-graphql-transport-only.md",
       "adr/008-local-mode-composition.md",
       "adr/009-channels-subscriptions.md",
+      "adr/010-two-databases.md",
+      "adr/011-authorisation-at-the-edge.md",
     ]}
   ] },
   { "Development" = [