Add per-resource access control primitives and run scopes

[morgan-wowk]

Per-resource access control primitives: scopes, grant checks, a revisioned edit history, and run scopes inherited from a parent resource. Host apps register their resource types and a run-parent resolver.

oasis-backend registers one resource type, saved pipelines:

Scope	Includes
operate	run:cancel, run:annotate
edit	operate, plus pipeline:update (rename included)
manage	edit, plus pipeline:delete, pipeline:share

Owners and admins hold every scope. Runs inherit run:* from their saved pipeline. Starting a run isn't a scope: anyone can run a saved pipeline, as on prod today.

Solution

flowchart TD
  call["API call on a resource"] --> who{"caller is owner or admin?"}
  who -- yes --> allow["allowed"]
  who -- no --> grants["read extra_data.access_control.users"]
  grants --> expand["expand broad scopes: operate, edit, manage"]
  expand --> has{"scope present?"}
  has -- yes --> allow
  has -- no --> deny["403"]
  run["run action: cancel or annotate"] --> starter{"caller started the run?"}
  starter -- yes --> allow
  starter -- no --> parent["pipeline-id annotation to parent pipeline"]
  parent --> grants

Loading

API model

Module	Entry points
access_control/scopes.py	register_resource_type(name, operate, edit, manage), ResourceType.expand(scope=...)
access_control/checks.py	effective_scopes(...), require(...) raises NotAuthorizedError
access_control/edits.py	apply_users_edit(..., expected_revision) raises StaleRevisionError, latest_revision(access_control=...)
access_control/keys.py	Key: the extra_data.access_control field names
access_control/runs.py	RunScope, register_run_parent_resolver(resolver=..., annotation_keys=...), require_run_scope(...), require_annotation_change(...)

terminate checks run:cancel, and setting or deleting an annotation checks run:annotate. When no resolver is registered, the rule stays the run starter or an admin. Admins reach these through skip_user_check, as before.

Behaviour worth knowing:

• Re-registering a resource type with the same scopes does nothing. Re-registering it with different scopes raises ApiValidationError.
• NotAuthorizedError doesn't name the owner in its message. The owner is carried as .owner, and the host decides whether to show it.
• History keeps the newest 100 entries. The revision keeps counting from the last entry.
• apply_users_edit doesn't lock anything. It only checks the revision of the snapshot it is given. The caller must hold a row lock from the read through the write. A test shows two unlocked writers at the same revision both succeeding.
• Parent annotations can't be re-pointed by grantees. A resolver names the annotation keys it reads. Only the run's starter and admins can set or delete those keys, so someone granted run:annotate can't move a run to a pipeline that gives them more.

Data model

erDiagram
  resource ||--o| access_control : "extra_data"
  access_control ||--o{ user_grant : "users"
  access_control ||--o{ history_entry : "history"
  history_entry ||--|{ change : "changes"
  pipeline_run }o--o| resource : "RunParent resolver"
  resource {
    string id
    string owner
    json extra_data
  }
  pipeline_run {
    string id
    string created_by "run starter"
    json annotations
  }
  user_grant {
    string email
    string_list permissions
  }
  history_entry {
    int revision
    string changed_by
    datetime changed_at
  }
  change {
    string email
    string_list from
    string_list to
  }

Loading

Related

• tangle-ui: feat(access-control): share saved pipelines and honour inherited run scopes tangle-ui#2856
• oasis-backend: https://github.com/Shopify/oasis-backend/pull/745
• oasis-frontend: https://github.com/Shopify/oasis-frontend/pull/732

🤖 Generated with Claude Code

[yuechao-qin]

(AI Assisted)

Approve with changes. The scope model is small and fails closed, the tier expansion is right, and the three api_server_sql call sites are converted faithfully — NotAuthorizedError subclasses errors.PermissionError (checks.py:8), so no caller's except breaks. Two things block my sign-off rather than the merge, and both are library contract problems rather than bugs in the one host that exists today: expected_revision is advertised as concurrency control and is not, and the history it writes has no bound.

#	Severity	Topic
M1	🔶 major	expected_revision reads as optimistic concurrency control, but two writers at the same revision both succeed
M2	🔶 major	the history this module writes has no bound, and every authorization check pays for it
D1	🛠 design	run:submit is granted but enforced nowhere, in either repo
m1	🔹 minor	register_resource_type silently overwrites, while its sibling registrar guards against duplicates
m2	🔹 minor	the authorization failure message discloses the owner's email to a caller who just failed the check
m3	🔹 minor	every new call site builds a Caller without is_admin, so the admin branch in run_scopes is unreachable
N1	▫️ nit	run_scopes returns str elements on one branch and RunScope members on the other