Skip to content
Open
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
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
17 changes: 12 additions & 5 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,19 @@ 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; a same-org caller may see a request-only entry when its
join policy permits requests.
- 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 Down
100 changes: 79 additions & 21 deletions server/auth/authz.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@
A namespace classified `restricted` is the one exception to
"additive": every default that widens a read — the org-readable code rule,
`visibility=public`, a wildcard claim, a service account inheriting its
creator's grant, a platform role — is switched off there, and a read needs
BOTH a token that names the namespace AND a live direct grant.
creator's grant — is switched off there, and a read needs BOTH a token that
names the namespace AND a live direct grant. A platform administrator using
its own unscoped authority may also read a configured repository, subject to
the restricted serving kill switch and classification availability.
"""

from __future__ import annotations
Expand Down Expand Up @@ -66,11 +68,23 @@ class _Unknown(Enum):
_UNKNOWN_GRANT = _Unknown.GRANT


def is_own_platform_admin(auth: AuthInfo) -> bool:
"""Platform authority belongs to the unscoped principal itself, never a
delegated token or the subject a trusted caller acts for."""
return (
not auth.has_ns_roles()
and not auth.impersonated_by
and not auth.creator
and not auth.parents
and auth.has_role(Role.PLATFORM_ADMIN)
)


def may_act_in_org(auth: AuthInfo, org: str) -> bool:
"""Whether `auth` may act in `org` at all: a token of that org, an
org-wide (`*`) token, or a platform admin. The one cross-org rule — the
transports and every handler's same-org check ask this; a restricted
namespace still refuses every other org (`_check_restricted`)."""
transports and every handler's same-org check ask this. Restricted
non-repository data still requires the namespace's own org."""
return auth.org in ("*", org) or auth.has_role(Role.PLATFORM_ADMIN)


Expand Down Expand Up @@ -219,6 +233,7 @@ async def check_authorized(
row_scoped: bool = False,
known_grant: Role | None | _Unknown = _UNKNOWN_GRANT,
grants: GrantMap | None = None,
allow_repository_read: bool = True,
) -> None:
"""Raise PermissionError if `auth` lacks `required_role` or access to `(org,
namespace)`. Consults `loom.namespace_grants` as a fallback when the JWT role alone
Expand Down Expand Up @@ -269,28 +284,24 @@ async def check_authorized(
await _check_delegated(auth, required_role, org, namespace, known_grant, grants)
return

# A restricted namespace is decided here and nowhere
# below — none of the widening rules that follow may apply to it.
# Restricted reads retain their safety guards before repository admission.
if org is not None and namespace is not None and await may_be_restricted(org, namespace):
await _check_restricted(auth, required_role, org, namespace, grants)
await _check_restricted(
auth,
required_role,
org,
namespace,
grants,
allow_repository_read=allow_repository_read,
)
return

# Code namespaces are org-shared reference data, not anyone's memory. When
# the deployment says so (LOOM_CODE_ORG_READABLE / per-entry org_readable)
# every authenticated principal of that org reads it with the token it
# already holds — scoped or flat, no grant, no re-mint. Writes (refresh,
# watermark repair) stay grant-driven. Otherwise code namespaces follow
# the ordinary rules: a grant (joined) or a token naming the namespace.
# The directory row's visibility never widens reads — `join_policy = open`
# means joinable in one click, not readable unjoined.
if (
required_role.value <= Role.VIEWER.value
and org is not None
org is not None
and namespace is not None
and (auth.org == org or auth.has_role(Role.PLATFORM_ADMIN))
# A service's end user is no member of the org's code.
and not principal_id(auth.subject, USER)
and await is_org_readable_code_namespace(org, namespace)
and await _standard_code_read(
auth, required_role, org, namespace, allow_repository_read=allow_repository_read
)
):
return

Expand Down Expand Up @@ -543,6 +554,43 @@ def _scoped_role(
return role


async def _standard_code_read(
auth: AuthInfo,
required_role: Role,
org: str,
namespace: str,
*,
allow_repository_read: bool,
) -> bool:
"""Read exceptions for code after restricted safety guards have run.

Platform authority reads every repository. Org-readable entries also admit
the org's authenticated principals with their existing tokens. A service's
end user is no member of its org's code. Directory visibility affects joining,
never reading. Writes keep the ordinary claim and grant checks.
"""
if allow_repository_read and _platform_repository_read(auth, required_role, org, namespace):
return True
return (
required_role.value <= Role.VIEWER.value
and (auth.org == org or auth.has_role(Role.PLATFORM_ADMIN))
and not principal_id(auth.subject, USER)
and await is_org_readable_code_namespace(org, namespace)
)


def _platform_repository_read(
auth: AuthInfo, required_role: Role, org: str, namespace: str
) -> bool:
"""Repository read authority, independent of claims and membership. The
caller checks tenancy and restricted safety guards before admitting it."""
return (
is_own_platform_admin(auth)
and not is_mirror_name(namespace)
and _code_namespace_read(required_role, org, namespace)
)


def _code_namespace_read(required_role: Role, org: str, namespace: str) -> bool:
"""A read of a configured code namespace, which a scoped token leaves to
the grant check. On a repository the join IS the read: a code index is
Expand Down Expand Up @@ -598,6 +646,8 @@ async def _check_restricted(
org: str,
namespace: str,
grants: GrantMap | None = None,
*,
allow_repository_read: bool = True,
) -> None:
"""The two-factor gate for restricted namespaces. Raises PermissionError unless:

Expand All @@ -609,6 +659,8 @@ async def _check_restricted(
4. a live DIRECT grant for the token's subject reaches `required_role`
(no service-account → creator inheritance).

A platform administrator's own unscoped authority also admits repository
viewer reads after the kill switch and classification check, within held orgs.
The refusal text is the generic "cannot access" line so a caller learns
nothing about whether the namespace exists or why it was refused.
`LOOM_RESTRICTED_SERVE=false` refuses everyone (kill switch: the plane
Expand All @@ -625,6 +677,12 @@ async def _check_restricted(
except ClassificationUnavailable as e:
note_unreadable()
raise refusal from e
if allow_repository_read and _platform_repository_read(auth, required_role, org, namespace):
from server.auth import tenancy

# restricted_allows also calls this gate directly, outside check_authorized.
await tenancy.ensure_held(org, auth)
return
if auth.org != org:
raise refusal
if not names_namespace(auth, org, namespace):
Expand Down
5 changes: 4 additions & 1 deletion server/code/app/member_writes.py
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,10 @@ async def code_member_may_write(
if not subject or await _lookup_grant(org, namespace, subject) is None:
return False
try:
await check_authorized(auth, Role.VIEWER, org=org, namespace=namespace)
# Membership writes retain token ceilings even when platform authority reads more.
await check_authorized(
auth, Role.VIEWER, org=org, namespace=namespace, allow_repository_read=False
)
except (PermissionError, IdentityIncompleteError):
return False
return True
Expand Down
4 changes: 1 addition & 3 deletions server/code/app/repo_admin.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,13 +68,11 @@ def _is_platform_admin() -> bool:
call is no platform admin's (an MCP endpoint in `open` mode takes one that
sends no bearer)."""
from server.auth.context import current_auth
from server.operations.base import Role

auth = current_auth()
if auth is None:
return not settings.auth_actually_required()
flat = not auth.has_ns_roles() and not auth.impersonated_by
return flat and auth.has_role(Role.PLATFORM_ADMIN)
return authz.is_own_platform_admin(auth)


def _require_platform_admin() -> None:
Expand Down
8 changes: 5 additions & 3 deletions tests/unit/test_authz_restricted_namespace.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
"""Restricted namespaces: a read needs a token that names the
namespace AND a live direct grant. Every widening rule — org-readable code,
visibility=public, wildcard claims, service-account inheritance, platform
roles — is off there, and the directory lookup fails closed."""
visibility=public, wildcard claims and service-account inheritance — is off
there. Platform authority admits only registered repository reads; the
directory lookup fails closed."""

from __future__ import annotations

Expand Down Expand Up @@ -155,7 +156,8 @@ async def test_other_org_is_refused(restricted) -> None:


@pytest.mark.asyncio
async def test_platform_admin_has_no_content_bypass(restricted) -> None:
async def test_platform_admin_needs_two_factors_outside_registered_repositories(restricted) -> None:
# A directory-only namespace is not a registered repository, despite its code prefix.
await _denied(_flat(namespaces=("*",), roles=(Role.PLATFORM_ADMIN,)))
restricted["grants"][(ORG, NS, "alice@x")] = Role.VIEWER
await authz.check_authorized(
Expand Down
Loading