Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
3cbeb29
Platform administrators can read every registered repository
zlareb1 Nov 19, 2026
f1ef4a5
Repository read authority preserves member write scope
zlareb1 Nov 19, 2026
272a52d
Repository read authority retains provisioning checks
zlareb1 Nov 20, 2026
963e4a7
Match the repository parser fixture to explicit settings
zlareb1 Nov 20, 2026
b8495d5
Scope person-query observations to the decision task
zlareb1 Nov 20, 2026
0835996
Describe request-only repository metadata accurately
zlareb1 Nov 20, 2026
ea20225
Cleanup tests measure their shared idle deadline
zlareb1 Nov 20, 2026
fb304c6
Bound JSON encoder setup in Cell proof regression cases
zlareb1 Nov 20, 2026
5f0dd0d
Compare Cell proof defaults in one canonical mapping
zlareb1 Nov 20, 2026
7405fa3
Document restricted repository viewer authority
zlareb1 Nov 21, 2026
3ddc292
Fixture failures report workbook dataset counts
zlareb1 Nov 21, 2026
3e6a4bd
Ingestion fixture failures expose bounded retry causes
zlareb1 Nov 21, 2026
c0f1d98
Retry diagnostics read at most four cause links
zlareb1 Nov 21, 2026
e80fe85
Compose repository administration reads with current main
zlareb1 Nov 21, 2026
9e9b7f8
Include retrieval failure observations in repository administration c…
zlareb1 Nov 21, 2026
496e651
Compose current documentation with the reviewed change
zlareb1 Nov 21, 2026
8d35929
Compose the reviewed scanner action pin with the change
zlareb1 Nov 21, 2026
1078980
Compose the reviewed test prerequisites with the change
zlareb1 Nov 21, 2026
ea03b5d
Merge current main into Platform administrators can read every regist…
zlareb1 Nov 21, 2026
67272c8
Merge current main into PR #993 composition
zlareb1 Nov 21, 2026
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
47 changes: 39 additions & 8 deletions docs/architecture/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,13 +276,17 @@ authenticated call, from `gates.authorize` in both transports:
creator holds that role somewhere in the org, and on a namespace needs its own claim to reach
the role and the creator's live grant to reach it too (`_check_delegated`; restricted
namespaces also take the restricted gate). Nothing below applies to it.
3. A restricted namespace goes to the restricted gate only.
4. A viewer read of an org-readable code namespace (`LOOM_CODE_ORG_READABLE` or the
3. A restricted namespace goes to the restricted gate, including its repository read
exception below.
4. An authenticated platform administrator using its own unscoped authority reads every
configured or registered repository, including closed and restricted entries. Deployment
tenancy still applies. This authority does not admit writes or any other namespace kind.
5. A viewer read of an org-readable code namespace (`LOOM_CODE_ORG_READABLE` or the
entry's `org_readable`) passes for any principal of that org.
5. A scoped token's `ns_roles` decide for the namespaces they name, in the token's org
6. A scoped token's `ns_roles` decide for the namespaces they name, in the token's org
only. Grants are not consulted for them, except viewer reads of a code namespace.
6. A token acts in its own org only (or `*`, or as platform admin).
7. A flat token's roles apply to every namespace its claims cover. Otherwise a live grant
7. A token acts in its own org only (or `*`, or as platform admin).
8. A flat token's roles apply to every namespace its claims cover. Otherwise a live grant
in `loom.namespace_grants` decides: unrevoked and `active` (`grant_sql.LIVE_GRANT`); a
`pending` join request grants nothing. A service account with no grant reads its
creator's. A grant raises a flat token's role, never lowers it. A failed read of
Expand Down Expand Up @@ -333,16 +337,43 @@ foreign row and a missing row look the same.
### Restricted namespaces

A namespace classified `restricted` (in `loom.namespaces` or its repository entry; either
restricts) turns off every widening rule (`_check_restricted` in `server/auth/authz.py`).
A call passes only when all of these hold:
restricts) uses `_check_restricted` in `server/auth/authz.py`. Except for the repository
read authority below, a call passes only when all of these hold:

- the token's org is the namespace's (`*` does not count);
- the token names the namespace literally;
- the token's own role reaches the op's;
- a live direct grant for the token's own subject reaches it (a service account does not
inherit its creator's grant).

No org-readable rule, `visibility=public`, `org_admin` or `platform_admin` bypasses it. A
An authenticated `platform_admin` using its own unscoped authority reads every repository
that `NamespaceDirectory.code_entry` recognizes in the current configuration or registry
snapshot. This includes restricted, approval and closed repositories across the orgs the
deployment holds. `authz.is_own_platform_admin` excludes scoped tokens, delegated tokens
and impersonated subjects, even when their flat roles contain `platform_admin`. Namespace
`admin` and `org_admin` confer no such authority. A name beginning with `code-` confers
nothing without a repository entry.

Repository indexes are deployment reference data, so platform administrators need a read
authority independent of repository membership. Requiring a separate claim and direct
grant for each repository would make this authority depend on token refreshes and grant
provisioning. The exception is limited to viewer reads: writes, refreshes, registration,
grant management and every non-repository namespace keep their existing checks. Collection
and mirror boundaries run before repository admission; a repository read does not expose
its document mirrors or internal data.

The member-write fallback checks the ordinary read rules without the platform read
exception. A live viewer grant alone cannot widen a token's restricted write scope.

Classification must remain available, `restricted_serve=false` refuses restricted reads
even for platform administrators, and tenancy and token verification still run first.
Revoked or unverifiable credentials gain no authority. HTTP, MCP, row-scoped checks and
repository listings share this decision through `check_authorized`. The listing returns
actual heads and counts only after that gate admits the read. Restricted-access audit
behavior also applies to platform administrators. No schema or stored-grant migration is
needed. Auth-off behavior is unchanged.

No org-readable rule, `visibility=public` or `org_admin` bypasses the restricted gate. A
refusal is the generic "cannot access". If the classification cannot be read, access is
denied.

Expand Down
12 changes: 8 additions & 4 deletions docs/concepts/identities-and-namespaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,10 +117,14 @@ refuses joins.
A **restricted** namespace (`classification=restricted` on its directory row, or on its
entry in `LOOM_CODE_REPOS_JSON`) admits a call only when the token belongs to the
namespace's org, names the namespace literally (not through `*`), holds a role there that
reaches the operation's role, and the token's own subject holds a live direct grant. No
org-readable rule, public visibility, wildcard, inherited service-account grant,
`org_admin` or `platform_admin` bypasses it, and a refusal does not reveal whether the
namespace exists. Fan-outs, context packs and rollups skip restricted namespaces the
reaches the operation's role, and the token's own subject holds a live direct grant.
An authenticated platform administrator using its own unscoped authority can also read
registered repositories, including restricted ones, subject to deployment tenancy and
the restricted serving kill switch. This does not extend to scoped or delegated tokens,
impersonation, writes or other namespace kinds
([repository read authority](../architecture/security.md#restricted-namespaces)). No
org-readable rule, public visibility, wildcard, inherited service-account grant or
`org_admin` bypasses restriction, and a refusal does not reveal whether the namespace exists. Fan-outs, context packs and rollups skip restricted namespaces the
caller cannot read, and each admitted request is audited. The step-by-step setup is in
[Tokens and grants](../guides/tokens-and-grants.md#restricted-namespaces-classificationrestricted).

Expand Down
10 changes: 7 additions & 3 deletions docs/features/code-index/repositories.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,14 +205,18 @@ until `loom code backfill` runs. Every setting is in the
Code namespaces follow the usual grant rules
([identities and namespaces](../../concepts/identities-and-namespaces.md),
[tokens and grants](../../guides/tokens-and-grants.md)): a token must name the code
namespace (or `*`), or the call fails with `AUTH_INSUFFICIENT`. Three switches change
that:
namespace (or `*`), or the call fails with `AUTH_INSUFFICIENT`. An unscoped,
undelegated, non-impersonating platform administrator may use its own platform role
for viewer reads of registered repositories without namespace claims or grants,
including restricted repositories. Writes retain their existing grant checks.
`LOOM_RESTRICTED_SERVE=false` refuses every restricted read, including administrator
reads. Three switches change ordinary namespace access:

| Switch | Effect |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOOM_CODE_ORG_READABLE=true`, or the entry's `org_readable` | every authenticated principal of the org reads without a grant (default off); writes stay grant-driven |
| `LOOM_CODE_REPO_PUBLIC=true`, or the entry's `public` | the namespace registers `join_policy=open` and discoverable, so any org member joins as a reader at once; otherwise the policy is `approval` |
| `classification: "restricted"` (entry, or `code.repo.set_access`) | never org-readable or public; a maintainer approves each reader, and every read needs a token naming the namespace plus a live direct grant |
| `classification: "restricted"` (entry, or `code.repo.set_access`) | never org-readable or public; ordinary readers need maintainer approval, a token naming the namespace and a live direct grant |

A `code.repo.set_access` row wins over the configured classification and join policy
and survives restarts. `code.refresh` (writer) and the admin ops always need a grant.
Expand Down
29 changes: 20 additions & 9 deletions docs/guides/tokens-and-grants.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ of the token. This guide holds the procedures;

```bash
loom mint-token --subject my-bot --org acme --namespaces support --roles writer --ttl-days 30 --save
# /home/you/.loom/token
# ~/.loom/token
```

`loom` ships with the server package and the Docker image, not with the SDK; in a container
Expand Down Expand Up @@ -472,12 +472,21 @@ read or write passes only when **all** hold:
4. a live **direct** grant for the token's own subject reaches it (a service account does
not inherit its creator's grant).

No org-readable rule, `visibility=public`, `org_admin` or `platform_admin` bypasses this. A
refusal is the generic "cannot access" message, so it does not reveal whether the namespace
exists. If the classification cannot be read, access is denied.
An authenticated platform administrator using its own unscoped authority can read every
registered repository, including restricted entries. This authority remains subject to
deployment tenancy, token validity, classification availability and `LOOM_RESTRICTED_SERVE`.
It does not extend to scoped or delegated tokens, impersonated subjects, writes or other
namespace kinds ([repository read authority](../architecture/security.md#restricted-namespaces)).
No org-readable rule, `visibility=public` or `org_admin` bypasses restriction. A refusal is
the generic "cannot access" message, so it does not reveal whether the namespace exists.
If the classification cannot be read, access is denied.

- Search fan-out, context packs and org-wide rollups skip the restricted namespaces the
caller cannot read, and `code.repos` hides them.
caller cannot read. `code.repos` returns readable metadata only when its authorization
gate admits the repository. It can also return permitted join, access-request or adoption
metadata with `readable: false`; those rows omit populated index counts and watermarks
and do not authorize code reads. Other inaccessible entries are omitted. See
[repository listing and access](../features/code-index/repositories.md#who-can-read).
- Each request admitted to the restricted namespace it names writes a
`namespace.restricted_access` audit row before the answer
(`LOOM_RESTRICTED_AUDIT_INLINE=false` writes it beside the request instead,
Expand All @@ -502,11 +511,13 @@ exists. If the classification cannot be read, access is denied.
- `LOOM_RESTRICTED_SERVE=false` refuses every restricted read while ingest continues.

> **Warning:** `loom mint-token` signs locally and is not checked against grants. Whoever
> holds the signing key can mint any token; the direct-grant check at request time is what
> still protects a restricted namespace.
> holds the signing key can mint any token. Restricted access normally also requires a
> live direct grant. An unscoped, undelegated, non-impersonating platform administrator
> may view registered repositories without namespace claims or grants; direct grants do
> not limit that repository-viewer authority. Protect the signing key.

**To give a reader access, do both:** a direct grant on the subject, and a token that names
the namespace.
**To give an ordinary namespace reader access, do both:** a direct grant on the subject,
and a token that names the namespace.

```bash
# as an admin of the namespace
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ Authentication, tokens and identity providers.
| `LOOM_JWT_END_USER_ISSUERS_JSON` | `str` | `''` | | The services that sign a short-lived token per end user (a chat app in front of Loom): JSON (or base64 JSON) {issuer: {"orgs": [...], "jwks_url": "https://…", "keys": {kid: RS256 public PEM}}}. `orgs` lists the orgs its tokens may name (exact names, or `prefix*`); its keys come from `jwks_url` (fetched every `jwt_end_user_jwks_refresh_seconds`) and/or `keys`. A key here verifies only its own issuer's tokens, and only as an end user (`sub: user:<id>`, one listed `org`, an optional `agent: agent:<id>`), never any other token. Empty: no end-user tokens. A non-loopback bind refuses an inline RSA key under 2048 bits (a key fetched from `jwks_url` is not checked). |
| `LOOM_JWT_END_USER_MAX_TTL_SECONDS` | `int` | `300` | | The longest an end-user token may live, from its `iat` to its `exp`. |
| `LOOM_JWT_END_USER_JWKS_REFRESH_SECONDS` | `float` | `300.0` | | Seconds between fetches of each end-user issuer's `jwks_url`; a key it rotates in is honoured from the next fetch. |
| `LOOM_RESTRICTED_SERVE` | `bool` | `True` | | Kill switch for restricted namespaces. True: served to a principal whose token names the namespace AND who holds a live direct grant. False: every read is refused while ingest continues. |
| `LOOM_RESTRICTED_SERVE` | `bool` | `True` | | Kill switch for restricted namespaces. True requires a token naming the namespace and a live direct grant, except registered-repository viewer reads by an unscoped, undelegated, non-impersonating platform administrator. False refuses every restricted read while ingest continues. |
| `LOOM_RESTRICTED_AUDIT_INLINE` | `bool` | `True` | | Wait for the `namespace.restricted_access` audit row of each admitted restricted read before answering; false writes it beside the answer, lost if the process dies first. |
| `LOOM_CORS_ORIGINS` | `str` | `''` | | Comma-separated origin list. "*" allows all (acceptable when auth_required=True). Empty disables CORS entirely. |
| `LOOM_MAX_REQUEST_BYTES` | `int` | `33554432` | | Request-body cap, bytes, enforced by ASGI middleware before any parser (413 PAYLOAD_TOO_LARGE); uvicorn has no limit of its own. 0 disables. |
Expand Down
7 changes: 4 additions & 3 deletions loom.example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -891,9 +891,10 @@ settings:
# honoured from the next fetch. [restart]
# jwt_end_user_jwks_refresh_seconds: 300.0

# Kill switch for restricted namespaces. True: served to a principal whose token names
# the namespace AND who holds a live direct grant. False: every read is refused while
# ingest continues. [restart]
# Kill switch for restricted namespaces. True requires a token naming the namespace
# and a live direct grant, except registered-repository viewer reads by an unscoped,
# undelegated, non-impersonating platform administrator. False refuses every
# restricted read while ingest continues. [restart]
# restricted_serve: true

# Wait for the `namespace.restricted_access` audit row of each admitted restricted
Expand Down
2 changes: 1 addition & 1 deletion schemas/loom-settings.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -6329,7 +6329,7 @@
"restricted_serve": {
"default": true,
"type": "boolean",
"description": "Kill switch for restricted namespaces. True: served to a principal whose token names the namespace AND who holds a live direct grant. False: every read is refused while ingest continues."
"description": "Kill switch for restricted namespaces. True requires a token naming the namespace and a live direct grant, except registered-repository viewer reads by an unscoped, undelegated, non-impersonating platform administrator. False refuses every restricted read while ingest continues."
},
"retention_agent_events_days": {
"default": 0,
Expand Down
6 changes: 4 additions & 2 deletions scripts/gates/testsupport/cell_trigger/capture.py
Original file line number Diff line number Diff line change
Expand Up @@ -256,8 +256,10 @@ def expected(self, row, audit, context, *, api, metadata, driver):
"workload semantic/active",
)
need(row["confidence"] == 1.0, "workload confidence")
for field, default in self.p["sparse_defaults"].items():
equal(row[field], default)
equal(
{field: row[field] for field in self.p["sparse_defaults"]},
self.p["sparse_defaults"],
)
need(
row["value"] == json.dumps(payload(key)) and row["content_sha256"] == content_hash(key),
"exact stored payload/hash",
Expand Down
Loading