graphcore-kernel 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (343) hide show
  1. graphcore/__init__.py +5 -0
  2. graphcore/agent_frontend/__init__.py +8 -0
  3. graphcore/agent_frontend/api.py +69 -0
  4. graphcore/agent_frontend/base/__init__.py +11 -0
  5. graphcore/agent_frontend/base/views.py +167 -0
  6. graphcore/agent_frontend/client.py +31 -0
  7. graphcore/agent_frontend/context.py +157 -0
  8. graphcore/agent_frontend/errors.py +12 -0
  9. graphcore/agent_frontend/loading.py +54 -0
  10. graphcore/agent_frontend/registry.py +42 -0
  11. graphcore/agent_frontend/render.py +207 -0
  12. graphcore/agent_frontend/server.py +103 -0
  13. graphcore/agent_frontend/signatures.py +35 -0
  14. graphcore/agent_frontend/testing.py +45 -0
  15. graphcore/agent_frontend/tests/__init__.py +0 -0
  16. graphcore/agent_frontend/tests/fakes.py +114 -0
  17. graphcore/agent_frontend/tests/test_frontend.py +447 -0
  18. graphcore/agent_frontend/tests/test_loading.py +83 -0
  19. graphcore/agent_frontend/tests/test_server.py +109 -0
  20. graphcore/agent_frontend/tools.py +137 -0
  21. graphcore/api/__init__.py +4 -0
  22. graphcore/api/graph_api.py +378 -0
  23. graphcore/api/predicate_codec.py +81 -0
  24. graphcore/api/tests/__init__.py +0 -0
  25. graphcore/api/tests/test_changed_entities.py +109 -0
  26. graphcore/api/tests/test_graph_api.py +290 -0
  27. graphcore/api/tests/test_graph_api_access.py +94 -0
  28. graphcore/api/tests/test_graph_api_grants.py +90 -0
  29. graphcore/api/tests/test_predicate_codec.py +83 -0
  30. graphcore/api/tests/test_subtree_query.py +79 -0
  31. graphcore/apps.py +71 -0
  32. graphcore/auth/__init__.py +1 -0
  33. graphcore/auth/authn/README.md +178 -0
  34. graphcore/auth/authn/__init__.py +3 -0
  35. graphcore/auth/authn/authenticator.py +120 -0
  36. graphcore/auth/authn/onboarding.py +105 -0
  37. graphcore/auth/authn/principals.py +20 -0
  38. graphcore/auth/authn/resource_metadata.py +43 -0
  39. graphcore/auth/authn/service_accounts.py +96 -0
  40. graphcore/auth/authn/testing.py +96 -0
  41. graphcore/auth/authn/tests/__init__.py +0 -0
  42. graphcore/auth/authn/tests/test_authenticator.py +145 -0
  43. graphcore/auth/authn/tests/test_onboarding.py +145 -0
  44. graphcore/auth/authn/tests/test_service_accounts.py +180 -0
  45. graphcore/auth/authn/users.py +59 -0
  46. graphcore/auth/authz/__init__.py +0 -0
  47. graphcore/auth/authz/access_port.py +120 -0
  48. graphcore/auth/authz/adapter/__init__.py +0 -0
  49. graphcore/auth/authz/adapter/default_access_adapter.py +556 -0
  50. graphcore/auth/authz/adapter/tests/__init__.py +0 -0
  51. graphcore/auth/authz/adapter/tests/test_default_adapter.py +543 -0
  52. graphcore/auth/authz/adapter/tests/test_entity_write_hooks.py +207 -0
  53. graphcore/auth/authz/adapter/tests/test_group_types.py +70 -0
  54. graphcore/auth/authz/adapter/tests/test_sync_support.py +209 -0
  55. graphcore/auth/authz/defaults.py +26 -0
  56. graphcore/auth/authz/kernel_policy.py +191 -0
  57. graphcore/auth/authz/kernel_writes.py +31 -0
  58. graphcore/auth/authz/lookups.py +25 -0
  59. graphcore/auth/authz/policy.py +403 -0
  60. graphcore/auth/authz/tests/__init__.py +0 -0
  61. graphcore/auth/authz/tests/test_can_contain.py +150 -0
  62. graphcore/auth/authz/tests/test_contained_by.py +167 -0
  63. graphcore/auth/authz/tests/test_creation.py +391 -0
  64. graphcore/auth/authz/tests/test_delete_permission.py +82 -0
  65. graphcore/auth/authz/tests/test_granted_to_me.py +160 -0
  66. graphcore/auth/authz/tests/test_integration.py +637 -0
  67. graphcore/auth/authz/tests/test_invites.py +184 -0
  68. graphcore/auth/authz/tests/test_kernel_policy.py +140 -0
  69. graphcore/auth/authz/tests/test_lockout.py +132 -0
  70. graphcore/auth/authz/tests/test_policy.py +329 -0
  71. graphcore/auth/authz/tests/test_primitives.py +73 -0
  72. graphcore/auth/authz/tests/test_principal_creation.py +62 -0
  73. graphcore/bootstrap/__init__.py +0 -0
  74. graphcore/bootstrap/deployment.py +67 -0
  75. graphcore/bootstrap/signals.py +16 -0
  76. graphcore/bootstrap/tests/__init__.py +0 -0
  77. graphcore/bootstrap/tests/test_deployment_seed.py +154 -0
  78. graphcore/broadcast/__init__.py +4 -0
  79. graphcore/broadcast/broadcaster.py +201 -0
  80. graphcore/broadcast/channels.py +56 -0
  81. graphcore/broadcast/tests/__init__.py +0 -0
  82. graphcore/broadcast/tests/test_broadcaster.py +444 -0
  83. graphcore/celery.py +14 -0
  84. graphcore/docs/AGENT_FRONTEND_TDD.md +389 -0
  85. graphcore/docs/ARCHITECTURE_PRINCIPLES.md +152 -0
  86. graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +1379 -0
  87. graphcore/docs/ENTITY_REFERENCE_TDD.md +561 -0
  88. graphcore/docs/GRAPHAPI_FRONT_DOOR.md +173 -0
  89. graphcore/docs/RUNTIME.md +90 -0
  90. graphcore/docs/SCHEDULING_TDD.md +244 -0
  91. graphcore/docs/STRATEGY_EXECUTION_TDD.md +1043 -0
  92. graphcore/docs/VIEW_ENTITY_TDD.md +522 -0
  93. graphcore/docs/VIEW_SYSTEM_TDD.md +307 -0
  94. graphcore/docs/__init__.py +0 -0
  95. graphcore/docs/doc_topics.py +97 -0
  96. graphcore/docs/docs_discovery.py +64 -0
  97. graphcore/docs/public_api.py +56 -0
  98. graphcore/domain/__init__.py +0 -0
  99. graphcore/domain/entity/Entity.py +204 -0
  100. graphcore/domain/entity/__init__.py +0 -0
  101. graphcore/domain/entity/deployment/Deployment.py +25 -0
  102. graphcore/domain/entity/deployment/__init__.py +0 -0
  103. graphcore/domain/entity/grant/Grant.py +31 -0
  104. graphcore/domain/entity/grant/__init__.py +0 -0
  105. graphcore/domain/entity/group/Group.py +48 -0
  106. graphcore/domain/entity/group/README.md +88 -0
  107. graphcore/domain/entity/group/__init__.py +0 -0
  108. graphcore/domain/entity/invite/Invite.py +31 -0
  109. graphcore/domain/entity/invite/__init__.py +0 -0
  110. graphcore/domain/entity/request_template/RequestTemplate.py +48 -0
  111. graphcore/domain/entity/request_template/__init__.py +0 -0
  112. graphcore/domain/entity/request_template/tests/__init__.py +0 -0
  113. graphcore/domain/entity/request_template/tests/test_request_template.py +52 -0
  114. graphcore/domain/entity/service_account/ServiceAccount.py +41 -0
  115. graphcore/domain/entity/service_account/__init__.py +0 -0
  116. graphcore/domain/entity/strategy_request/StrategyRequest.py +61 -0
  117. graphcore/domain/entity/strategy_request/__init__.py +0 -0
  118. graphcore/domain/entity/strategy_request/tests/__init__.py +0 -0
  119. graphcore/domain/entity/strategy_request/tests/test_strategy_request_entity.py +35 -0
  120. graphcore/domain/entity/tests/__init__.py +0 -0
  121. graphcore/domain/entity/tests/test_entity.py +227 -0
  122. graphcore/domain/entity/tests/test_grant_group_entities.py +36 -0
  123. graphcore/domain/entity/tests/test_write_once_fields.py +98 -0
  124. graphcore/domain/entity/user/User.py +39 -0
  125. graphcore/domain/entity/user/__init__.py +0 -0
  126. graphcore/domain/entity/user/tests/__init__.py +0 -0
  127. graphcore/domain/entity/user/tests/test_user_entity.py +33 -0
  128. graphcore/domain/entity/view/View.py +37 -0
  129. graphcore/domain/entity/view/__init__.py +0 -0
  130. graphcore/domain/entity/view/position.py +78 -0
  131. graphcore/domain/entity/view/tests/__init__.py +0 -0
  132. graphcore/domain/entity/view/tests/test_position.py +71 -0
  133. graphcore/domain/entity/view/tests/test_view_entity.py +134 -0
  134. graphcore/domain/strategy/BaseStrategy.py +759 -0
  135. graphcore/domain/strategy/DeploymentStrategies.py +55 -0
  136. graphcore/domain/strategy/GrantStrategies.py +189 -0
  137. graphcore/domain/strategy/GroupStrategies.py +193 -0
  138. graphcore/domain/strategy/InviteStrategies.py +84 -0
  139. graphcore/domain/strategy/RequestTemplateStrategies.py +126 -0
  140. graphcore/domain/strategy/ViewStrategies.py +219 -0
  141. graphcore/domain/strategy/__init__.py +0 -0
  142. graphcore/domain/strategy/runner.py +84 -0
  143. graphcore/domain/strategy/session.py +56 -0
  144. graphcore/domain/strategy/tests/BaseStrategyTest.py +167 -0
  145. graphcore/domain/strategy/tests/__init__.py +0 -0
  146. graphcore/domain/strategy/tests/test_BaseStrategies.py +870 -0
  147. graphcore/domain/strategy/tests/test_grant_strategies.py +245 -0
  148. graphcore/domain/strategy/tests/test_group_strategies.py +99 -0
  149. graphcore/domain/strategy/tests/test_runner.py +220 -0
  150. graphcore/domain/strategy/tests/test_strategy_locks.py +446 -0
  151. graphcore/domain/strategy/tests/test_utils.py +95 -0
  152. graphcore/domain/strategy/tests/test_view_strategies.py +436 -0
  153. graphcore/errors.py +145 -0
  154. graphcore/execution/README.md +97 -0
  155. graphcore/execution/StrategyExecutorService.py +333 -0
  156. graphcore/execution/__init__.py +0 -0
  157. graphcore/execution/dispatcher.py +19 -0
  158. graphcore/execution/environments/__init__.py +0 -0
  159. graphcore/execution/environments/celery.py +59 -0
  160. graphcore/execution/environments/in_process.py +55 -0
  161. graphcore/execution/local_session.py +117 -0
  162. graphcore/execution/redis_run_events.py +74 -0
  163. graphcore/execution/requests.py +22 -0
  164. graphcore/execution/run_events.py +85 -0
  165. graphcore/execution/strategy_context.py +54 -0
  166. graphcore/execution/tasks.py +34 -0
  167. graphcore/execution/tests/__init__.py +5 -0
  168. graphcore/execution/tests/contract.py +171 -0
  169. graphcore/execution/tests/support.py +310 -0
  170. graphcore/execution/tests/test_dispatchers.py +76 -0
  171. graphcore/execution/tests/test_executor.py +368 -0
  172. graphcore/execution/tests/test_local_session.py +95 -0
  173. graphcore/execution/tests/test_reconcile_runs.py +134 -0
  174. graphcore/execution/tests/test_run_events.py +106 -0
  175. graphcore/execution/tests/test_strategy_context.py +62 -0
  176. graphcore/gateway/__init__.py +1 -0
  177. graphcore/gateway/remote.py +35 -0
  178. graphcore/gateway/tests/__init__.py +0 -0
  179. graphcore/gateway/tests/test_remote.py +30 -0
  180. graphcore/graph/EntityService.py +710 -0
  181. graphcore/graph/__init__.py +0 -0
  182. graphcore/graph/entity_cache.py +152 -0
  183. graphcore/graph/tests/__init__.py +4 -0
  184. graphcore/graph/tests/test_EntityService.py +908 -0
  185. graphcore/graph/tests/test_EntityService_list.py +170 -0
  186. graphcore/graph/tests/test_EntityService_model_resolution.py +339 -0
  187. graphcore/graph/tests/test_EntityService_referrers.py +236 -0
  188. graphcore/graph/tests/test_EntityService_routing.py +119 -0
  189. graphcore/graph/tests/test_dependent_on.py +141 -0
  190. graphcore/graph/tests/test_engine_is_type_agnostic.py +25 -0
  191. graphcore/graph/tests/test_engine_resolves_read_permission.py +93 -0
  192. graphcore/graph/tests/test_entity_cache.py +159 -0
  193. graphcore/graph/tests/test_null_entity_cache.py +12 -0
  194. graphcore/management/__init__.py +0 -0
  195. graphcore/management/commands/__init__.py +0 -0
  196. graphcore/management/commands/dev_reset.py +18 -0
  197. graphcore/management/commands/graphcore_createadmin.py +65 -0
  198. graphcore/management/commands/graphcore_policy.py +59 -0
  199. graphcore/management/commands/graphcore_status.py +98 -0
  200. graphcore/management/tests/__init__.py +0 -0
  201. graphcore/management/tests/test_createadmin.py +78 -0
  202. graphcore/management/tests/test_policy_command.py +46 -0
  203. graphcore/management/tests/test_status_command.py +85 -0
  204. graphcore/migrations/0001_initial.py +186 -0
  205. graphcore/migrations/0002_invite.py +26 -0
  206. graphcore/migrations/__init__.py +0 -0
  207. graphcore/models.py +11 -0
  208. graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +396 -0
  209. graphcore/persistence/__init__.py +6 -0
  210. graphcore/persistence/django/__init__.py +0 -0
  211. graphcore/persistence/django/backends.py +43 -0
  212. graphcore/persistence/django/bindings.py +28 -0
  213. graphcore/persistence/django/cache.py +38 -0
  214. graphcore/persistence/django/compiler.py +214 -0
  215. graphcore/persistence/django/identity.py +18 -0
  216. graphcore/persistence/django/models.py +252 -0
  217. graphcore/persistence/django/repository.py +525 -0
  218. graphcore/persistence/django/tests/__init__.py +0 -0
  219. graphcore/persistence/django/tests/test_backends.py +68 -0
  220. graphcore/persistence/django/tests/test_compiler.py +269 -0
  221. graphcore/persistence/django/tests/test_repository.py +472 -0
  222. graphcore/persistence/django/tests/test_shared_column.py +120 -0
  223. graphcore/persistence/django/tests/test_threads.py +50 -0
  224. graphcore/persistence/django/tests/test_update_shape.py +175 -0
  225. graphcore/persistence/django/threads.py +38 -0
  226. graphcore/persistence/repository.py +172 -0
  227. graphcore/persistence/tests/__init__.py +0 -0
  228. graphcore/persistence/tests/contract.py +688 -0
  229. graphcore/persistence/tests/evaluate.py +51 -0
  230. graphcore/persistence/tests/fixtures.py +32 -0
  231. graphcore/persistence/tests/memory.py +263 -0
  232. graphcore/persistence/tests/test_memory_repository.py +10 -0
  233. graphcore/persistence/tests/test_query_types.py +127 -0
  234. graphcore/public/__init__.py +9 -0
  235. graphcore/public/api.py +9 -0
  236. graphcore/public/apps.py +10 -0
  237. graphcore/public/auth/__init__.py +1 -0
  238. graphcore/public/auth/grants.py +7 -0
  239. graphcore/public/auth/onboarding.py +8 -0
  240. graphcore/public/auth/perms.py +7 -0
  241. graphcore/public/auth/policy.py +10 -0
  242. graphcore/public/auth/roles.py +8 -0
  243. graphcore/public/auth/subjects.py +7 -0
  244. graphcore/public/entities/__init__.py +32 -0
  245. graphcore/public/errors.py +19 -0
  246. graphcore/public/persistence/__init__.py +44 -0
  247. graphcore/public/persistence/django.py +24 -0
  248. graphcore/public/scheduling.py +23 -0
  249. graphcore/public/strategies/__init__.py +85 -0
  250. graphcore/public/test_settings.py +16 -0
  251. graphcore/public/testing.py +47 -0
  252. graphcore/registry/EntityDirectory.py +246 -0
  253. graphcore/registry/README.md +147 -0
  254. graphcore/registry/StrategyDirectory.py +308 -0
  255. graphcore/registry/TYPE_METADATA_PLACEMENT.md +66 -0
  256. graphcore/registry/__init__.py +0 -0
  257. graphcore/registry/app_discovery.py +108 -0
  258. graphcore/registry/decorators.py +77 -0
  259. graphcore/registry/discovery.py +111 -0
  260. graphcore/registry/registry.py +79 -0
  261. graphcore/registry/tests/__init__.py +0 -0
  262. graphcore/registry/tests/test_agent_frontend_discovery.py +56 -0
  263. graphcore/registry/tests/test_app_config.py +36 -0
  264. graphcore/registry/tests/test_discovery.py +147 -0
  265. graphcore/registry/tests/test_entity_directory_storage.py +73 -0
  266. graphcore/registry/tests/test_import_package.py +87 -0
  267. graphcore/registry/tests/test_principal_flag.py +67 -0
  268. graphcore/registry/tests/test_strategy_directory.py +29 -0
  269. graphcore/routes/__init__.py +116 -0
  270. graphcore/routes/tests/__init__.py +0 -0
  271. graphcore/routes/tests/test_routes.py +90 -0
  272. graphcore/runtime.py +243 -0
  273. graphcore/scheduling/__init__.py +0 -0
  274. graphcore/scheduling/beat_scheduler.py +164 -0
  275. graphcore/scheduling/beat_tasks.py +63 -0
  276. graphcore/scheduling/scheduler.py +37 -0
  277. graphcore/scheduling/tests/__init__.py +0 -0
  278. graphcore/scheduling/tests/contract.py +136 -0
  279. graphcore/scheduling/tests/memory.py +42 -0
  280. graphcore/scheduling/tests/test_beat_scheduler.py +87 -0
  281. graphcore/scheduling/tests/test_memory_scheduler.py +15 -0
  282. graphcore/scheduling/tests/test_ticks.py +143 -0
  283. graphcore/tasks.py +9 -0
  284. graphcore/test_settings.py +78 -0
  285. graphcore/testing/__init__.py +0 -0
  286. graphcore/testing/case.py +112 -0
  287. graphcore/testing/runner.py +32 -0
  288. graphcore/testing/settings.py +26 -0
  289. graphcore/testing/tests/__init__.py +0 -0
  290. graphcore/testing/tests/agent_view_fixture.py +19 -0
  291. graphcore/testing/tests/test_case_and_runner.py +219 -0
  292. graphcore/testing/tests/test_settings_for_apps.py +50 -0
  293. graphcore/tests/__init__.py +0 -0
  294. graphcore/tests/ids.py +14 -0
  295. graphcore/tests/public_api_manifest.py +102 -0
  296. graphcore/tests/runs.py +7 -0
  297. graphcore/tests/test_app_discovery.py +90 -0
  298. graphcore/tests/test_composition_boundaries.py +231 -0
  299. graphcore/tests/test_docs_discovery.py +108 -0
  300. graphcore/tests/test_no_print.py +70 -0
  301. graphcore/tests/test_packaging.py +64 -0
  302. graphcore/tests/test_public_api_boundaries.py +229 -0
  303. graphcore/tests/test_public_api_contract.py +62 -0
  304. graphcore/tests/test_public_api_docs.py +28 -0
  305. graphcore/tests/test_runtime.py +42 -0
  306. graphcore/tests/test_shared_type_boundaries.py +128 -0
  307. graphcore/tests/test_shared_types.py +144 -0
  308. graphcore/tests/test_test_settings.py +45 -0
  309. graphcore/transport/__init__.py +0 -0
  310. graphcore/transport/agent_asgi.py +68 -0
  311. graphcore/transport/agent_client.py +85 -0
  312. graphcore/transport/channel_layer.py +68 -0
  313. graphcore/transport/consumers.py +507 -0
  314. graphcore/transport/routing.py +6 -0
  315. graphcore/transport/tests/__init__.py +0 -0
  316. graphcore/transport/tests/test_agent_client.py +31 -0
  317. graphcore/transport/tests/test_api_views.py +733 -0
  318. graphcore/transport/tests/test_channel_layer.py +96 -0
  319. graphcore/transport/tests/test_consumers.py +963 -0
  320. graphcore/transport/tests/test_resource_metadata.py +67 -0
  321. graphcore/transport/urls.py +29 -0
  322. graphcore/transport/views.py +358 -0
  323. graphcore/types/__init__.py +4 -0
  324. graphcore/types/access.py +114 -0
  325. graphcore/types/api.py +76 -0
  326. graphcore/types/entities.py +100 -0
  327. graphcore/types/entity_id.py +85 -0
  328. graphcore/types/execution.py +41 -0
  329. graphcore/types/identity.py +20 -0
  330. graphcore/types/onboarding.py +20 -0
  331. graphcore/types/query.py +116 -0
  332. graphcore/types/schedules.py +91 -0
  333. graphcore/types/strategy.py +73 -0
  334. graphcore/types/tests/__init__.py +0 -0
  335. graphcore/types/tests/test_entity_id.py +50 -0
  336. graphcore/urls.py +5 -0
  337. graphcore_kernel-0.1.0.dist-info/METADATA +94 -0
  338. graphcore_kernel-0.1.0.dist-info/RECORD +343 -0
  339. graphcore_kernel-0.1.0.dist-info/WHEEL +5 -0
  340. graphcore_kernel-0.1.0.dist-info/entry_points.txt +2 -0
  341. graphcore_kernel-0.1.0.dist-info/licenses/LICENSE +202 -0
  342. graphcore_kernel-0.1.0.dist-info/licenses/NOTICE +2 -0
  343. graphcore_kernel-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,1379 @@
1
+ # Authorization
2
+
3
+ ## Introduction
4
+
5
+ Authorization governs who may read an entity, who may invoke a strategy on
6
+ it, and who may change access itself. The system provides per-entity
7
+ granular access control, out-of-the-box sharing with correct defaults for
8
+ any newly registered entity type, and swappable authorization decision
9
+ machinery over grant facts that live in the graph itself. Registering an
10
+ entity type and its strategies produces a correctly locked-down type with
11
+ no authorization code; one `policy.define` call makes it shareable or
12
+ changes any of its defaults.
13
+
14
+ The design separates three concerns that must not collapse into one:
15
+ authentication (who is calling — outside this document's scope), the
16
+ authorization contract every adapter must satisfy (this document), and the
17
+ default adapter's implementation of that contract.
18
+
19
+ ## Definitions
20
+
21
+
22
+ | Term | Definition |
23
+ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
24
+ | **Principal** | The authenticated caller of a request, backed by an entity type registered `principal=True`: `principal_entity_id`, optionally `iss`/`sub`/`token`. The only identity object passed through the system. Principals can act and are the only entities eligible to own resources. |
25
+ | **Subject** | Anything that can receive a grant: a user, a group (`Group` or a subclass), the well-known `PUBLIC` subject, or a capability such as a share link. Every principal is also a subject; not every subject is a principal — a group never authenticates. |
26
+ | **Owner** | The `principal=True` entity named by a resource's persisted `owner` field. Ownership confers implicit, non-revocable `Admin` on that resource. A group and `PUBLIC` are subjects but not principals and cannot be owners. |
27
+ | **Resource** | The entity a question or a grant is about. |
28
+ | **Perm** | A typed capability token, the vocabulary of authorization questions. Built-in: `Read`, `Write`, `Delete`, `ManageAccess`, `Create`. Applications define additional perms by subclassing `Perm`, or `CreatePermission` for a create permission that must be held explicitly. An adapter denies any perm it does not recognize. |
29
+ | **Role** | A named bundle of perms, the vocabulary of grants: `Role(name, perms)`. Roles and their perm definitions are registry facts that every adapter must honor. Role identity is by name. |
30
+ | **Grant** | A stored fact: `(resource, subject, role)`, persisted as a `Grant` contained by its resource. At most one grant exists per `(resource, subject)`; granting again with a different role replaces the prior role for that pair. |
31
+ | **AccessChange** | Not stored — a transient signal the adapter derives from a grant entity write (via its `entity_saved`/`entities_deleted` hooks) carrying what just changed: resource, subject, old role, new role, and the resource's type. Drives cache invalidation and live-update delivery; see Port consumers. |
32
+ | **Scope** | An entity of a type defined `shareable=True`. Grants attach to scopes and the share surface operates on scopes. A scope passes its grants and owner-implicit `Admin` to every entity it contains; a type's `can_contain` limits what can be placed inside it. Every entity is also governed directly by its own persisted owner. |
33
+ | **PUBLIC** | The well-known subject implicitly included in every authenticated principal's subject set. |
34
+ | **AccessPort** | The authorization contract: the interface every adapter implements, and the only surface the rest of the system calls to ask authorization questions or interpret grants. Grant *mutation* is not on the port — grants are entities, mutated through kernel strategies like any other write. |
35
+ | **AccessAdapter** | A concrete implementation of `AccessPort`. Exactly one is active per deployment, selected by configuration. Its store is a derived index over grant entities and containment, rebuildable from the graph — never the system of record. |
36
+ | **Containment** | The parent/child structural relationship among entities, stored once, on the child: `Entity.parent_id` (single parent) plus an ordering `sibling_position`. `children_ids` is a derived, ordered, read-only projection over `parent_id` — never a stored column, never independently mutable. `Entity.set_parent` and `ReparentChild` mutate the *child's* `parent_id`; a caller with `save_entity` never writes it any other way. It is the *only* graph relation that establishes scope coverage; `refs`, backlinks, and other related-entity links never grant access. |
37
+ | **Group membership** | The roster relation between a group entity (a subject) and the principals who belong to it. Relates *subjects to subjects* — a principal to the groups covering it — and is unrelated to containment, which relates *resources to resources*. A grant made to a group covers every principal who is a member of that group, at the time of the check; membership is not inherited through containment and does not itself grant anything until a group holds a grant. |
38
+ | `Group` | The kernel group type: a pure subject with a name, an optional key, and a roster, no other content. Defined `shareable=True, can_contain=[Grant]`. A group is `Group` or a subclass of it; an application's own group type subclasses it. |
39
+ | `Grant` | The kernel entity type that persists a grant: `(subject_id, role)`, contained by the resource it grants on. Has no owner, and is read with `ManageAccess` on that resource. The system of record for all access facts; see Grant storage. |
40
+ | `Deployment` | The single, kernel-seeded entity that represents the deployment as a party that grants authority: an authority anchor, never a container. Defined `shareable=True, can_contain=[Grant]`: it holds only its own grants, so its grants reach nothing else. Grants on it are the identity-based policy. See Identity-based policy. |
41
+ | **Top-level entity** | An entity with `parent_id` null. The creation rule checks its create permission on the `Deployment` in place of a parent. A create strategy makes one when its request has no target. |
42
+ | `Create` | Kernel perm: create entities inside the entity it is held on; held on the `Deployment`, create top-level entities. Held by `editor` and `member`, implied for `admin`. |
43
+ | `member` | Kernel role on the `Deployment`: `{Read, Create}`. Granted to `PUBLIC` at bootstrap, so every authenticated principal holds it until an administrator revokes that grant. |
44
+ | `graphcore.admins` | The kernel-seeded group holding `admin` on the `Deployment` and on itself. Membership is what makes a principal a deployment administrator. |
45
+ | **Group key** | An optional, stable, immutable identifier on a group (`<app_id>.<name>`), unique per deployment. Code and configuration refer to groups by key; graph data refers to them by entity id. |
46
+ | `CreatePermission` | Base class for a type's own create permission (`define(create=...)`) that ownership and `ManageAccess` do not imply. |
47
+ | **Lockout rule** | No change may leave an entity with nobody who can manage access to it. See Enforcement. |
48
+ | `Invite` | A kernel entity contained by a shareable resource: the hash of a link secret and a role. Redeeming the link as a signed-in principal grants that principal the role. See Invites. |
49
+ | **Onboarding** | What a new principal receives when it is first created: group memberships and deployment roles the kernel applies itself, and strategy requests run as the new principal. Produced by principal-created hooks. |
50
+
51
+
52
+
53
+
54
+ ## Requirements
55
+
56
+ 1. **Per-entity granularity.** Every authorization question and every grant
57
+ is scoped to a specific entity.
58
+ 2. **Correct defaults with minimal authorization code.** Registering an
59
+ entity type and a strategy on it produces a type that is readable/writable
60
+ according to role and safe against unauthorized mutation. A single
61
+ `policy.define(Type, shareable=True)` makes it shareable as a unit with
62
+ its contained entities; every other policy for the type is an argument
63
+ of that same call.
64
+ 3. **Sharing follows containment.** Granting access to a scope grants access
65
+ to everything it contains, including entities created after the grant.
66
+ Sharing is never expressed by copying access data onto individual
67
+ entities.
68
+ 4. **Adapter swappability.** The authorization *decision machinery* is
69
+ replaceable behind `AccessPort`: how grant facts are indexed and evaluated
70
+ (in-process, Postgres, SpiceDB) is adapter choice. Grant facts themselves
71
+ are not adapter choice — they are entities in the graph, the system of
72
+ record in every deployment; an adapter's store is a derived index rebuilt
73
+ from the graph. Applications built against the kernel's perm and role
74
+ vocabulary keep working unmodified against any adapter that honors that
75
+ vocabulary. See Grant storage for what this deliberately rules out.
76
+ 5. **Adapter extensibility without swapping.** The default adapter supports
77
+ application-defined perms, application-defined roles, and per-strategy
78
+ authorization requirements as configuration, without code changes to the
79
+ default adapter itself.
80
+ 6. **Absolute mutation guarantee.** No entity is persisted or deleted except
81
+ through a check that cannot be bypassed by strategy code, including
82
+ strategy code that is generated at runtime or that overrides framework
83
+ methods.
84
+ 7. **Principal-only ownership.** Every persisted owner names a
85
+ `principal=True` entity. Groups and `PUBLIC` receive access through grants;
86
+ they never own resources.
87
+ 8. **Live-delivery parity.** A connected principal receives updates through
88
+ every access path that can make an entity readable: public type policy,
89
+ grants on its access cover, direct ownership, and ownership of a covering
90
+ shareable scope. Delivery must not enumerate every entity a principal owns
91
+ when the connection opens.
92
+ 9. **Operator authority over top-level creation.** Which principals may
93
+ create entities that have no parent is decided by grants on the
94
+ deployment, which no principal can issue to itself.
95
+ 10. **Zero-configuration default, revocable.** A new deployment lets every
96
+ authenticated principal create top-level entities; an administrator can
97
+ revoke that default without code changes.
98
+ 11. **Onboarding without code and with code.** What a newly created
99
+ principal receives is configurable by administrators as graph data, and
100
+ extensible by applications as code.
101
+ 12. **Onboarding cannot bypass enforcement.** Application onboarding code
102
+ never runs with the persistence check disabled.
103
+ 13. **No implicit authority for kernel-seeded entities.** Entities the kernel
104
+ seeds have no owner; every right over them is a visible, revocable grant.
105
+
106
+
107
+
108
+ ## Architecture
109
+
110
+
111
+
112
+ ### Kernel primitives
113
+
114
+ ```python
115
+ class Perm:
116
+ """Base for typed permission tokens. Unrecognized perms are denied."""
117
+ admin_implied: ClassVar[bool] = True # a ManageAccess-bearing role satisfies this perm
118
+
119
+ @dataclass(frozen=True)
120
+ class Read(Perm): pass
121
+
122
+ @dataclass(frozen=True)
123
+ class Write(Perm): pass
124
+
125
+ @dataclass(frozen=True)
126
+ class Delete(Perm): pass
127
+
128
+ @dataclass(frozen=True)
129
+ class ManageAccess(Perm): pass
130
+
131
+
132
+ @dataclass(frozen=True)
133
+ class Role:
134
+ name: str
135
+ perms: frozenset[Perm] = frozenset()
136
+ # Equality and hash are by name; perms are the registered definition.
137
+
138
+ def allows(self, perm: Perm) -> bool:
139
+ return perm in self.perms or (perm.admin_implied and ManageAccess() in self.perms)
140
+
141
+ VIEWER = Role('viewer', perms={Read()})
142
+ EDITOR = Role('editor', perms={Read(), Write(), Delete()})
143
+ ADMIN = Role('admin', perms={Read(), Write(), Delete(), ManageAccess()})
144
+ ```
145
+
146
+ Deleting content is an editing operation, so `Editor` bundles `Delete`.
147
+ Deleting or granting *access itself* is administration, so only `Admin`
148
+ bundles `ManageAccess`. `Admin` is `Editor` plus `ManageAccess`.
149
+
150
+ **`ManageAccess` implies application-defined perms by default.** A role
151
+ satisfies a perm it holds outright, and a role carrying `ManageAccess` also
152
+ satisfies any perm whose `admin_implied` is `True` (the default). This is
153
+ what makes `Admin` the top of the role lattice, so a subject's single grant
154
+ per resource never forces a choice between administering a resource and
155
+ acting on it. It is also the honest model: whoever can manage access can
156
+ grant themselves any role, so denying an admin a perm is friction, not a
157
+ control. An application that nevertheless wants a perm held explicitly —
158
+ a distinct duty an admin takes on by grant rather than by office — declares
159
+ `admin_implied = False` on that perm. `Role.allows` is the single place this
160
+ rule lives; adapters evaluate roles through it rather than testing
161
+ `perm in role.perms` directly.
162
+
163
+ ### The AccessPort
164
+
165
+ ```python
166
+ from graphcore.types.identity import Principal
167
+ from graphcore.types.access import AccessChange, GrantInfo, Perm, Role
168
+
169
+
170
+ class AccessPort(ABC):
171
+
172
+ # --- decisions ---
173
+ async def allows(self, principal: Principal, perm: Perm, entity_id: str) -> bool:
174
+ """Whether principal holds exactly perm on the entity. The port
175
+ knows no per-type policy: the engine resolves a type's read or
176
+ delete permission (policy.define(read=..., delete=...)) and asks
177
+ for that perm."""
178
+ async def read_filters(self, principal: Principal, perms: Iterable[Perm]) -> dict[Perm, Predicate]:
179
+ """Per perm, a predicate over entity fields selecting what principal
180
+ holds it on — predicate pushdown, the row-level-security pattern
181
+ relational stores already support well, so the engine conjoins it
182
+ with its own criteria and keeps paging, ordering and filtering
183
+ entirely in storage instead of loading the principal's full
184
+ readable closure into memory first. One call answers every perm
185
+ from one load of the principal's grants and owned scopes. The
186
+ predicates are written in the neutral query vocabulary
187
+ (graphcore/types/query.py), so the port speaks no ORM at all.
188
+ Filtering a candidate id set is the engine's job: it conjoins the
189
+ read predicate with InValues('entity_id', ids)."""
190
+
191
+ # --- grant interpretation (mutation is kernel strategies; see Grant storage) ---
192
+ async def available_roles(self, resource_id: str) -> list[Role]:
193
+ """The roles grantable on this resource. Takes a resource id, not a
194
+ type, purely because every other caller of this port — including
195
+ GraphAPI and the share dialog — has an entity id in hand, never a
196
+ Python class; the adapter resolves the type via the registry
197
+ internally. Roles do not vary per instance in v1: this returns the
198
+ same list for every instance of a type. The resource_id parameter is
199
+ kept (rather than accepting a type) so a future adapter or a future
200
+ instance-conditioned rule can specialize without a signature change."""
201
+ async def list_grants(self, principal, resource_id: str) -> list[GrantInfo]:
202
+ """Each entry carries subject, role, and provenance: direct,
203
+ inherited-from-<scope>, owner, or type-policy. GraphAPI calls it
204
+ only for a caller holding ManageAccess on the resource."""
205
+
206
+ # --- sync support ---
207
+ async def granted_resources(self, principal, *, include_public: bool = True) -> set[str]:
208
+ """Resource ids the principal holds a grant on themselves, directly
209
+ or via group membership — irrespective of whether those resources
210
+ are scopes. Called at connect time to decide which channels to
211
+ subscribe to, and with include_public=False by list_entities to
212
+ resolve EntityFilter.granted_to_me (grants to PUBLIC excluded)."""
213
+ async def owner_principals(self, resource_ids: set[str]) -> set[str]:
214
+ """The persisted owner principal ids for these resources. Called
215
+ once per save with the entity's cover, so owner fan-out is
216
+ proportional to cover depth rather than the owner's entity count."""
217
+ async def scopes(self, entity_id: str, ancestor_ids: tuple[str, ...]) -> set[str]:
218
+ """entity_id plus every shareable ancestor whose grants cover this
219
+ entity — the channels an update to this entity must reach. Called
220
+ once per save, to decide where to publish. Takes ancestor_ids
221
+ explicitly, rather than an entity object, because the caller
222
+ (publishing a just-deleted entity) may only have a lightweight
223
+ stand-in for it, never a real entity — but always these two fields."""
224
+ async def holders(self, perm: Perm, scope_ids: set[str]) -> tuple[set[str], bool]:
225
+ """(principal_ids, everyone): the owners of these scopes when Admin
226
+ implies perm, and the subjects of grants on them whose role allows
227
+ perm — a group expanded one level to its members, PUBLIC as
228
+ everyone. Live fan-out for a type whose read permission is not
229
+ Read, which the Read-carrying scope channels cannot deliver."""
230
+ async def covers(self, subject_id: str, principal_ids: list[str]) -> set[str]:
231
+ """Which of these principal ids the subject resolves to — itself,
232
+ or via one level of group membership. Called on each AccessChange
233
+ with only the currently-connected principals' ids, so delivery
234
+ checks a small connected set instead of expanding a roster; the
235
+ group expansion this reuses is the same cached subject-set the
236
+ decision methods maintain."""
237
+
238
+ # --- entity-write checks (the lockout rule; see Enforcement) ---
239
+ async def check_save(self, entity: Entity, existing: Entity) -> None:
240
+ """Raise Forbidden if this update would leave a resource with nobody
241
+ who can manage access to it."""
242
+ async def check_delete(self, entity_ids: set[str]) -> None:
243
+ """Raise Forbidden if deleting these entities together would leave a
244
+ surviving resource with nobody who can manage access to it."""
245
+
246
+ # --- entity-write notification ---
247
+ async def entity_saved(self, entity: Entity, previous: Entity | None) -> AccessChange | None:
248
+ """Called by EntityService once a save has committed. previous is
249
+ the entity exactly as it stood before this write (None for a newly
250
+ created entity), carried on the repository's SaveReceipt. No-op for most entities; lets an adapter react to
251
+ entity-level state it tracks its own cache against (e.g. a group's
252
+ member_ids) without EntityService knowing anything about what the
253
+ adapter tracks. When the written entity is a Grant, the
254
+ adapter diffs previous/entity and returns the AccessChange for the
255
+ broadcaster; None otherwise."""
256
+ async def prepare_delete(self, entity_ids: list[str]) -> object:
257
+ """Called by EntityService before a delete, while the rows exist.
258
+ Returns an opaque plan: whatever the adapter needs to react to the
259
+ delete (the default adapter hydrates the grants and groups)."""
260
+ async def entities_deleted(self, plan: object) -> list[AccessChange]:
261
+ """Called by EntityService once that delete has committed. Returns
262
+ the revoke-shaped AccessChange for each deleted grant."""
263
+
264
+
265
+ @dataclass(frozen=True)
266
+ class AccessChange:
267
+ """Derived by the adapter's entity_saved/entities_deleted hooks from a
268
+ grant entity write. Carries what just changed, for whoever reacts to it
269
+ — the adapter's own cache invalidation and the broadcaster's channel
270
+ join/leave and access notifications. Never persisted itself; it is a
271
+ signal, not a record."""
272
+ resource_id: str
273
+ subject_id: str
274
+ old_role: Role | None # None on a grant to a subject with no prior role
275
+ new_role: Role | None # None on revoke
276
+ ```
277
+
278
+ `AccessChange` carries the resource, subject, and old/new role for a grant
279
+ mutation. It is the signal consumed by cache invalidation and by live-update
280
+ delivery when a grant changes.
281
+
282
+ `AccessPort` speaks only Principal, Perm, Role, entities, and subject ids. It
283
+ never speaks groups, storage, or delivery mechanics, and names no concrete
284
+ entity type — those are adapter detail (`docs/ARCHITECTURE_PRINCIPLES.md`,
285
+ rule 7).
286
+
287
+ ### Inheritance
288
+
289
+ Effective access on an entity is the union of its owner's implicit `Admin`,
290
+ grants on the entity itself, and grants plus owner-implicit `Admin` on every
291
+ scope that contains it transitively. Union only: access
292
+ never shrinks by adding an ancestor, there is no deny rule, and no scope may
293
+ mark a contained entity as private relative to its own grants. A direct
294
+ grant on a non-scope entity is permitted as an additive exception; it can
295
+ only add access, never remove it.
296
+
297
+ Containment defines the inheritance policy, and the containment chain is a
298
+ column: the repository maintains `ancestor_ids` on every entity row under the
299
+ invariant `ancestor_ids(e) = ancestor_ids(parent) + [parent_id]`, recomputed
300
+ on create and on every `parent_id` change for the whole subtree (without
301
+ bumping the descendants' `version`). An adapter therefore answers
302
+ authorization from entity fields rather than by walking the tree on every
303
+ check, and needs no derived index of its own.
304
+
305
+ `cover(e) = {e} ∪ {a ∈ ancestor_ids(e) : type(a) is shareable}`. A grant is
306
+ contained by its resource, so the resource is in the grant's cover. Grants
307
+ are only permitted on shareable types, so a grant found
308
+ anywhere in that set is by construction a grant on a scope; owner-derived
309
+ scopes are filtered by the policy's `shareable` in the access layer. The
310
+ repository never learns what "shareable" means.
311
+
312
+ Reading is then a plain predicate over entity fields, which is what
313
+ `read_filters` returns per perm and `EntityService` hands to the
314
+ repository in one statement:
315
+
316
+ ```
317
+ AnyOf((
318
+ InValues('entity_type_id', public_types_for(perm)),
319
+ Equal('owner', principal), # when ADMIN.allows(perm)
320
+ InValues('entity_id', held),
321
+ ContainsAny('ancestor_ids', held),
322
+ ))
323
+ ```
324
+
325
+ where `held` is the shareable scopes the principal owns, union the
326
+ resources of grants whose resolved role allows `perm` for the subject set
327
+ `{principal} ∪ groups(principal) ∪ {PUBLIC}`.
328
+
329
+ The engine builds the read predicate: it groups the registered types by
330
+ their read permission (`policy.define(read=...)`, default `Read`), asks
331
+ `read_filters` for each permission once, and when every type is read with
332
+ `Read` uses that clause alone; otherwise it is an `AnyOf` of
333
+ `AllOf((InValues('entity_type_id', ids), clause(perm)))`, one per read
334
+ permission. The predicate language has no `NotIn`, so every registered type
335
+ id is listed under its permission. `get_entity` asks `allows` for the
336
+ entity's own read permission; `get_entities`, `list_entities` and
337
+ `referrers` use the predicate.
338
+
339
+ `EntityFilter.granted_to_me` narrows a listing to what is shared with the
340
+ caller: `list_entities` adds `InValues('entity_id', granted_resources(principal,
341
+ include_public=False))` beside the read predicate. Grants to the caller and
342
+ to groups they belong to count; grants to `PUBLIC`, ownership, and entities
343
+ reached only through containment do not. One share of a scope lists the
344
+ scope once, however many entities it contains.
345
+
346
+ ### Ordering
347
+
348
+ Sibling order is a field on the *child*, `sibling_position: float`, not a
349
+ list on the parent — so reordering, like every other containment write,
350
+ only ever persists the child. Containment (`parent_id`) and order
351
+ (`sibling_position`) are independent operations on two dedicated
352
+ strategies, both targeting the child being moved: `ReparentChild`
353
+ sets `parent_id` (to a new parent, or `null` to detach), and
354
+ `ReorderChild` sets `sibling_position` among the child's current
355
+ siblings. `ReorderChild` computes the moved child's new
356
+ `sibling_position` as the midpoint of its new neighbors' positions (or
357
+ `neighbor ± 1` at either end of the sibling list); when that gap is
358
+ exhausted (`< 1e-9`), it rebalances every sibling to integer positions in
359
+ one pass and retries. The parent is never written by either strategy:
360
+ `children_ids` (parent-ordered by `sibling_position`, then `created_at`,
361
+ `entity_id` for ties) is re-derived on the next read, and the touched-set
362
+ pipeline (see Port consumers) invalidates and republishes the parent so
363
+ subscribers still see the new state without a parent-row write or a version
364
+ bump.
365
+
366
+ ### Groups
367
+
368
+ A group is `Group` or a subclass of it; there is no registration
369
+ flag. `member_ids` is not a base field: it is a column of the group table.
370
+ The adapter expands a principal into its groups by reverse lookup over
371
+ `member_ids` (GIN-indexed on PostgreSQL), in a query pinned to the group
372
+ types, which the compiler requires for a child-table column. The same
373
+ subclass test serves validation (rejecting a grant to a subject that is not
374
+ a group or a principal) and discoverability (the entity directory's `group`
375
+ key drives a share dialog's "invite a team" picker).
376
+
377
+ A group is a subject, not a principal. It can receive grants but cannot
378
+ authenticate, act, or appear in an entity's `owner` field. The principal who
379
+ creates a group owns the group entity itself; the group's members gain no
380
+ access to that entity merely by joining its roster.
381
+
382
+ Being a group and being shareable are independent, and **combining them
383
+ on a single type is safe only when that type carries no shareable content of
384
+ its own.** On a content-bearing scope (a `Workspace`, a `Project`), doing so
385
+ reintroduces the self-stamp conflation this design already rejected: sharing
386
+ the scope and joining its roster would both plausibly mean "let this person
387
+ in," with no way for a user to tell why two different actions exist for what
388
+ looks like one outcome. On a group, there is no second meaning to collide
389
+ with — a group's only "content" is its own name and roster, so sharing it
390
+ (governing who administers it) and adding someone to it (extending who its
391
+ grants elsewhere apply to) stay two clearly different actions with two
392
+ clearly different effects.
393
+
394
+ The kernel ships one default group type built on exactly this pattern, so
395
+ most applications never need to define their own:
396
+
397
+ ```python
398
+ @register_entity()
399
+ class Group(Entity):
400
+ """Pure subject: a name and a roster, nothing else."""
401
+ write_once_fields = ('key',)
402
+
403
+ name: str # typed class fields — unreachable by the
404
+ key: str | None # generic attribute strategies
405
+ member_ids: list[str]
406
+
407
+ @register_strategy(Group)
408
+ class ModifyGroup(Strategy):
409
+ """Updates the group's own fields — today just name, extendable to
410
+ future fields without a new strategy per field."""
411
+ async def apply(self):
412
+ self.entity.name = self.strategy_request.param_config['name']
413
+ self.entity = await self.save_entity(self.entity)
414
+ return self.strategy_request, self.entity
415
+
416
+ @register_strategy(Group)
417
+ class AddMember(Strategy):
418
+ async def apply(self):
419
+ self.entity.add_member(self.strategy_request.param_config['principal_id'])
420
+ self.entity = await self.save_entity(self.entity)
421
+ return self.strategy_request, self.entity
422
+
423
+ @register_strategy(Group)
424
+ class RemoveMember(Strategy):
425
+ async def apply(self):
426
+ self.entity.remove_member(self.strategy_request.param_config['principal_id'])
427
+ self.entity = await self.save_entity(self.entity)
428
+ return self.strategy_request, self.entity
429
+
430
+ # kernel_policy.py, for its built-in types
431
+ policy.define(
432
+ Group,
433
+ shareable=True,
434
+ can_contain=[Grant],
435
+ strategies={
436
+ ModifyGroup: Write(),
437
+ AddMember: ManageAccess(),
438
+ RemoveMember: ManageAccess(),
439
+ # plus the grant, read, create, and delete strategies
440
+ },
441
+ other_strategies=False,
442
+ )
443
+ ```
444
+
445
+ The roster needs all three enforcement tiers, because a roster change is an
446
+ access change — membership extends the group's grants elsewhere to the new
447
+ member. `member_ids` is a typed class field, so no generic attribute
448
+ strategy can express a roster write; the allowlist is exhaustive, so no
449
+ undeclared strategy can persist a `Group` at all (the strategy-aware
450
+ persistence check denies a rogue strategy's inline roster edit); and the
451
+ membership strategies require `ManageAccess`, so only the group's admins
452
+ can act through the one permitted path.
453
+
454
+ No new perm or role is needed: the default `Viewer`/`Editor`/`Admin` roles
455
+ already express the right split. `Viewer` sees the name and roster; `Editor`
456
+ can rename the group (`ModifyGroup`, default `Write`) but cannot change
457
+ membership; `Admin` bundles `ManageAccess`, which gates both the membership
458
+ strategies and further grants of `Admin` on the group. The creator of a
459
+ `Group` is its owner and so holds `Admin` implicitly (see Enforcement,
460
+ Creation), letting them immediately manage both
461
+ who else administers the group and who is on its roster — two distinct
462
+ actions, reached through two distinct mechanisms: `grant(principal, group, alice_id, ADMIN)` makes Alice an administrator of the group itself;
463
+ `AddMember` makes Bob a member, which extends whatever grants the
464
+ group holds *elsewhere* to also cover him. Neither is a shortcut for the
465
+ other.
466
+
467
+ Applications needing extra fields on a group (e.g. an `Org` with a
468
+ billing plan) subclass `Group`, which gives the subclass the policy,
469
+ the strategies and every behavior the adapter gives groups (see
470
+ `domain/entity/group/README.md`). An application that needs group behavior
471
+ on a type that cannot subclass `Group` writes its own adapter. Nested groups (a group whose members include
472
+ another group) are out of v1: the subject expansion in `allows` and
473
+ `read_filters` resolves one level of membership only.
474
+
475
+ ### Grant storage: grants are entities
476
+
477
+ Grants are persisted as `Grant` records — kernel entities carrying
478
+ `(subject_id, role)`, each **contained by the resource it grants on**. This
479
+ is the contract, not a default-adapter storage detail: GraphCore is built on
480
+ entities, and building authorization out of them means grants get
481
+ persistence, versioning, live broadcast, and views from the same machinery
482
+ as everything else, instead of a parallel data model with hand-written
483
+ client logic beside it.
484
+
485
+ Containment placement is what makes the model need no special cases:
486
+
487
+ - **Mutation authorization falls out of inheritance.** Changing a grant
488
+ requires `ManageAccess` on the resource; a `Grant` contained by the
489
+ resource inherits the resource's grants, so the ordinary check against the
490
+ grant entity *is* that rule. Grants have no owner (`Grant.ownerless`),
491
+ so creating a grant confers nothing: once its creator stops holding
492
+ `ManageAccess` on the resource, they can no longer read, change or revoke it.
493
+ - **Visibility is `ManageAccess`.** `Grant` is defined
494
+ `read=ManageAccess()`, so only those who can manage access to the resource
495
+ read its grant rows, list them (`GraphAPI.list_grants`), or receive them in
496
+ `get_access`. Grant saves reach the principals holding `ManageAccess` on the
497
+ resource (`AccessPort.holders`), on their own channels, never the resource's
498
+ Read-carrying scope channel. A grant's tombstone carries only its id, so it
499
+ goes to both routes. Grant *ids* stay visible to the resource's readers,
500
+ through its `children_ids` (see Trade-offs).
501
+ - **Lifecycle falls out of containment.** Deleting a scope deletes its
502
+ grants.
503
+
504
+ **The adapter is the derived index, never the record.** Adapters answer
505
+ `allows`/`read_filters` from an index they maintain, kept current through
506
+ the same `entity_saved`/`entities_deleted` hooks used for group roster
507
+ diffs — a `Grant` save is the trigger to update the index. The index
508
+ is disposable: wiped, it rebuilds from the graph. A SpiceDB adapter is this
509
+ same shape — grant entities and containment edges projected into
510
+ relationship tuples, evaluation delegated to SpiceDB. Truth flows one
511
+ direction only: graph → index. One hygiene rule follows: an adapter warming
512
+ or rebuilding its index reads grant entities through an unchecked internal
513
+ path, never through the authorized read path it itself serves.
514
+
515
+ A second rule follows from the index being fed only by committed writes:
516
+ **authorization decisions are functions of persisted facts, never of the
517
+ in-memory object handed to a strategy** — strategy code can set an
518
+ in-memory entity's fields to anything, so decisions about an entity that
519
+ does not yet exist are really decisions against its persisted parent's
520
+ state. (Propagation is the deliberate exception: `scopes(entity)` uses
521
+ last-known in-memory state so a just-deleted entity can still fan out.)
522
+
523
+ **What this deliberately rules out:** an adapter that delegates decisions at
524
+ check time to an external *authority* holding access facts GraphCore has no
525
+ record of (a central IAM answering `allows` directly). If a fact is not a
526
+ `Grant`, the system does not know it: nothing broadcasts, no channel
527
+ is joined, the share surface shows nothing. External access systems
528
+ integrate by *syncing into* grant entities (with sync's usual staleness
529
+ window), not by being consulted per check.
530
+
531
+ **Grants mutate through strategies, like everything else.** Since
532
+ `Grant` is a real entity, the strategies-are-the-only-writes invariant
533
+ applies to it. The kernel ships the grant strategies: creation targets the
534
+ *resource* and requires `ManageAccess` on it; role-change and revoke target
535
+ the `Grant` and require `ManageAccess`, which the grant entity
536
+ inherits from its resource. These strategies own semantic validation —
537
+ subject exists and is a principal or a group, the role is registered
538
+ for the resource's type, at most one grant per `(resource, subject)`.
539
+ `GraphAPI.grant`/`revoke` are sugar that dispatch them. Two rules close the
540
+ generic-strategy gaps:
541
+
542
+ - **Typed fields.** `Grant` carries `subject_id` and `role` as class
543
+ fields, not attributes (see the two-tier convention in
544
+ ARCHITECTURE_PRINCIPLES.md) — the generic attribute strategies cannot
545
+ express a grant mutation at all.
546
+ - **Instantiation follows the allowlist.** A strategy may create an entity
547
+ of type `T` only if it appears in `T`'s allowed-strategies list.
548
+ `Grant` allowlists only the kernel grant strategies, so the generic
549
+ create strategy cannot mint one. The invocation check alone would not
550
+ catch this, because create targets the *parent* — without this rule an
551
+ `Editor` could create a grant naming themselves `Admin`.
552
+
553
+ **Deletion and cascades.** Directly targeting a grant entity with the
554
+ generic delete fails `Grant`'s allowlist at both invocation and
555
+ persistence — an `Editor` cannot revoke-by-delete, whether by dispatching a
556
+ delete at a grant or by inline-deleting one from rogue strategy code. Yet a
557
+ scope's grants still die when the scope is deleted, because cascades are
558
+ authorized at the root and the containment closure is computed by the
559
+ persistence chokepoint itself, with no per-descendant checks (see
560
+ Enforcement, Cascades). That an `Editor` deleting a scope also erases its
561
+ access records is accepted: the resource is gone, and grants on nothing
562
+ govern nothing.
563
+
564
+ `AccessChange` **is derived, not returned.** With grants as ordinary
565
+ writes, the adapter observes them the same way it observes roster changes:
566
+ `entity_saved`/`entities_deleted` on a `Grant` diff prior and new state
567
+ and return the `AccessChange` (`None` for non-grant writes), which
568
+ `GraphAPI` routes to the broadcaster. One trigger, one pipeline: every
569
+ access change is an entity write. `list_grants` remains on the port because
570
+ provenance (direct vs inherited-from-scope vs type-policy) is computed, not
571
+ stored. And entity storage still cannot notify the newly granted subject —
572
+ by definition not yet subscribed to any channel the grant's save fans out
573
+ to; delivering the `AccessChange` remains the broadcaster's job.
574
+
575
+ ### Enforcement
576
+
577
+ One rule, evaluated at two points, forms the system's complete guarantee.
578
+ The rule is always about the triple *(principal, strategy, entity)* — never
579
+ about the principal and entity alone — because the threat the design must
580
+ defeat is *laundering*: strategy code is arbitrary, so a strategy targeting
581
+ an innocent entity can load any other entity through the read path, mutate
582
+ it in memory, and save it. Any check that consults only the strategy's
583
+ declared target is bypassed by exactly that move. Enforcement therefore
584
+ follows the write, not the declaration.
585
+
586
+ **The invocation check.** The executor runs this before `apply()`, for every
587
+ dispatch — including a strategy dispatched from inside another strategy.
588
+ Strategy code cannot route around it, because code only becomes a running
589
+ strategy through the executor:
590
+
591
+ ```text
592
+ can_execute(principal, strategy, target) =
593
+ strategy ∈ allowed_strategies(type(target or deployment))
594
+ ∧ allows(principal, read_permission(type(target or deployment)), target or deployment)
595
+ ∧ allows(principal, required_permission(type(target or deployment), strategy), target or deployment)
596
+ ```
597
+
598
+ You can't act on what you can't read, so every strategy needs the target
599
+ type's read permission first. `target_entity_id` is required unless the
600
+ strategy is on the deployment's allowlist; a request with no target is
601
+ authorized against the deployment, as an entity with no parent is at
602
+ creation, and the strategy runs with no entity. `required_permission` is `Write` for a mutating strategy
603
+ and the type's read permission for a strategy declared
604
+ `read_only_strategy = True`, unless the type's policy overrides it. For
605
+ read-only strategies (below) this is the only gate; for mutating strategies
606
+ it is the early, per-dispatch evaluation of the same rule persistence
607
+ enforces authoritatively.
608
+
609
+ **The persistence check.** `EntityService` is the only path by which an
610
+ entity is ever saved or deleted — no strategy, adapter, or transport writes
611
+ to storage any other way. The executor establishes which strategy is
612
+ executing (strategy code cannot alter this), and every save is checked
613
+ against the type policy of **the entity actually being written**, not the
614
+ strategy's declared target:
615
+
616
+ ```text
617
+ persist-save(entity) requires:
618
+ current_strategy ∈ allowed_strategies(type(entity))
619
+ ∧ allows(principal, required_permission(type(entity), current_strategy), entity)
620
+ ```
621
+
622
+ *How* `current_strategy` *is known:* a `ContextVar` owned by the execution
623
+ layer. The executor sets it immediately around `apply()` and resets it via
624
+ the set-token, so nested dispatch restores the outer strategy;
625
+ `EntityService` reads it at the chokepoint. No kernel API accepts a
626
+ strategy identity as an argument — there is nothing for strategy code to
627
+ pass or misstate. `ContextVar` is asyncio- and thread-scoped (each task and
628
+ thread carries its own copy), so concurrent executions never observe each
629
+ other's value; the CPU-bound offload path propagates it with the copied
630
+ context. A write observed with no strategy context is either one of the
631
+ documented kernel-internal paths (identity bootstrap) or a bug to surface
632
+ loudly. This is an in-process integrity mechanism, not a sandbox: code that
633
+ would deliberately overwrite the variable is the same trust class as code
634
+ that bypasses `EntityService` for raw storage — governed by the
635
+ code-installation trust decision, and, for runtime-generated strategies,
636
+ by eventual out-of-process execution against the `GraphAPI` boundary,
637
+ where these same checks bind a caller that cannot reach around them.
638
+
639
+ With the default `required_permission` of `Write`, an undeclared type
640
+ behaves exactly as a blanket write check. But the check is now
641
+ strategy-aware, which closes the laundering hole: it is impossible to
642
+ persist an entity from inside a strategy that the entity's type does not
643
+ allow, and a perm-gated strategy's requirement follows every entity it
644
+ writes. A role need not carry `Write` to persist through a strategy whose
645
+ required permission is something else — a
646
+ `Role('publish-only', perms={Read(), Publish()})` can persist a document
647
+ *through* `PublishDocument` (whose required permission is
648
+ `Publish`) and through nothing else (the `PUBLISHER` under Type policy adds
649
+ `Write` on top to also permit ordinary editing — a choice, not a
650
+ requirement). The
651
+ approval-record pattern (modeling a restricted effect as a write to a
652
+ separate entity the actor holds `Write` on) remains available but is no
653
+ longer forced.
654
+
655
+ Note what perms still never do: gate *fields*. Field-level control is the
656
+ composition of the typed path (class fields are unreachable by the generic
657
+ attribute strategies), the allowlist (one declared strategy is the only
658
+ code path that touches the field), and the permission `define` requires for
659
+ that strategy. The unit of protection is always type × strategy, never a field.
660
+
661
+ **The deletion check.** The root's type names the permission deleting it
662
+ requires (`policy.define(delete=...)`, default `Delete`):
663
+
664
+ ```text
665
+ persist-delete(root) requires:
666
+ current_strategy ∈ allowed_strategies(type(root))
667
+ ∧ allows(principal, delete_permission(type(root)), root)
668
+ ```
669
+
670
+ `Grant` is defined `delete=ManageAccess()`, so revoking a grant needs
671
+ `ManageAccess` at the chokepoint itself, whichever allowed strategy deletes
672
+ it.
673
+
674
+ **Cascades are authorized at the root, and computed at the chokepoint.**
675
+ Strategy code does not submit lists of entities to delete; it submits a
676
+ single root. The persistence layer itself computes the containment closure
677
+ from *persisted* parent/child state and deletes it, checking only the root
678
+ with the rule above. Descendants are not individually checked: in the
679
+ containment tree a child's existence is subordinate to its parent's, so
680
+ whoever may delete the parent takes the subtree — which is also what lets a
681
+ scope's `Grant` children die with it even though the deleting strategy
682
+ is not in their allowlist (the accepted "grants on nothing govern nothing"
683
+ consequence). Both halves are load-bearing: per-descendant checks would
684
+ wrongly block the cascade on types like `Grant`, and a
685
+ strategy-supplied delete list would let a targeted delete masquerade as
686
+ cascade cleanup. A strategy needing to delete several unrelated entities
687
+ makes several root-checked calls.
688
+
689
+ **Read-only strategies never persist, by declaration.**
690
+ A strategy that never mutates its target sets `read_only_strategy = True`.
691
+ That single flag is the declaration: invocation then requires the type's
692
+ read permission by default (no permission declared for it), and the executor does not call
693
+ `save_entity` after `apply()` at all, so a `Viewer` never risks a spurious
694
+ `Forbidden` from a save the strategy was never going to need. Should such a
695
+ strategy reach a chokepoint anyway — its own `apply()` calling `save_entity`,
696
+ or `EntityService` directly — the write is refused outright, as is a delete,
697
+ for every principal including the resource's owner. That refusal is
698
+ deliberately not a perm check: `required_permission`'s read-only fallback is
699
+ the type's read permission, the very perm the caller needed to invoke the strategy, so treating a
700
+ misdeclared strategy's save as a permission question would let any `Viewer`
701
+ land a real write. The declaration is a contract the chokepoint enforces, not
702
+ one the author is trusted to honor. A permission in the type's `strategies`
703
+ still overrides when a read-only strategy must require something else.
704
+ The flag is not inferred
705
+ from `required_permission` or from diffing entity state before and after
706
+ `apply()`: inferring read-only from `required_permission` would be wrong for
707
+ a strategy that legitimately requires `Read` to invoke but still needs to
708
+ persist something (rare, but the two concepts — what's needed to invoke,
709
+ versus whether this run persists — stay independent: that strategy is listed
710
+ with `Read()` in the type's `strategies` and leaves `read_only_strategy` false);
711
+ diffing state would be wrong in the other direction, since a strategy that
712
+ mutates and reverts within `apply()` would diff to "unchanged" despite
713
+ being a genuinely mutating strategy that simply no-opped this time.
714
+ `read_only_strategy` defaults `False`; ordinary mutating strategies declare
715
+ nothing and are unaffected.
716
+
717
+ **Saving the target.** Strategies load and save entities only through
718
+ `self.get_entity` / `self.save_entity`, which record each entity's last
719
+ persisted state. After `apply()` the executor saves the returned target only
720
+ if it differs from that state (`Strategy.is_unsaved`), so a strategy that
721
+ already saved its target, or never changed it, causes no second save or
722
+ version bump, and changes made after the strategy's own save are still
723
+ persisted. Calling `entity_service.save_entity` directly bypasses the record
724
+ and causes a redundant save. This diff decides only whether to persist; it is
725
+ never used to infer `read_only_strategy`, which the executor honors first.
726
+
727
+ **Creation.** One rule governs every new entity, whatever strategy writes
728
+ it and wherever it goes:
729
+
730
+ ```text
731
+ persist-create(entity) requires:
732
+ creatable(type(entity))
733
+ ∧ current_strategy ∈ allowed_strategies(type(entity))
734
+ ∧ allows(principal, create_permission(type(entity)), entity.parent_id or deployment)
735
+ ```
736
+
737
+ `create_permission` is the type's `create` (default `Create`, which
738
+ `editor` holds and `admin` implies). An entity with no parent is created
739
+ on the deployment's authority; nothing else about top-level entities is
740
+ special.
741
+
742
+ Placement is the target. `CreateEntity` and `CreateGroup`
743
+ create inside their target, or at the top level when the request has no
744
+ target. The strategies never look at the target's type to decide placement,
745
+ so targeting the deployment asks to place the entity inside it, which
746
+ containment refuses. A type whose `create` is a `CreatePermission` subclass needs that
747
+ permission held explicitly: owning or administering the parent does not
748
+ imply it, so a member cannot get around a restricted type by creating it
749
+ inside something they own.
750
+
751
+ `creatable=False` (the default for `principal=True` types) refuses the
752
+ create outright unless the write is kernel-internal. `User` rows come
753
+ only from sign-in, registration, and the test helpers, all through one
754
+ kernel function (see Identity-based policy, Onboarding); the
755
+ `Deployment` comes only from seeding.
756
+
757
+ No grant is written at creation: the creator administers a new scope
758
+ because the scope's persisted `owner` — a kernel field stamped at creation,
759
+ not mutable by strategies — holds `Admin` implicitly. Owner-implicit `Admin`
760
+ is derived policy, the same species as `PUBLIC` and a type's `public`
761
+ permissions: no grant row exists, `list_grants` reports it with provenance
762
+ `owner`, and it cannot be revoked. This is also what makes creation need no
763
+ bootstrap: the first `Grant` on a scope is written at first *share*,
764
+ by the owner.
765
+
766
+ **Containment.** A type's `can_contain` (see Type policy) names the types
767
+ that may be placed directly inside it, and a type's `contained_by` names
768
+ the types it may be placed directly inside; a type with `contained_by` is
769
+ never top-level. `EntityService.save_to_db` checks both on every create and
770
+ every change of `parent_id`, before any authorization and for
771
+ kernel-internal writes too, because they are structural rules, not access
772
+ decisions; a refused placement raises `InvalidRequest`.
773
+
774
+ **Write-once fields.** A type's `write_once_fields` (entity metadata, e.g.
775
+ `Group`'s `key`) cannot change once they hold a value; the same
776
+ chokepoint refuses the write with `InvalidRequest`.
777
+
778
+ **Moves.** Persisting a change to `parent_id` needs the strategy's
779
+ permission on the entity and on the old parent, and the create rule for
780
+ the new parent (or the deployment, when moving to the top level): an entity
781
+ may only enter a place where it could have been created. Otherwise a direct
782
+ grant on the entity itself (an additive exception, never routed through its
783
+ container) could detach it from a container the mover has no standing on,
784
+ and a restricted type could be created where it is allowed and then moved
785
+ where it is not.
786
+
787
+ **The lockout rule.** No change may leave an entity with nobody who can
788
+ manage access to it. Before a strategy's write commits, the persistence
789
+ check hands the write to the port (`check_save` for an update,
790
+ `check_delete` for a delete), and the adapter refuses it with `Forbidden`
791
+ unless some principal would still hold `ManageAccess` on each affected
792
+ entity:
793
+
794
+ - changing or revoking a grant: its resource;
795
+ - removing members from a group: every resource the group holds a grant on;
796
+ - deleting grants or groups (including inside a deleted subtree): their
797
+ resources, except those being deleted in the same operation.
798
+
799
+ An owner, the owner of a shareable ancestor, or any grant whose role
800
+ allows `ManageAccess` to `PUBLIC`, a principal, or a group with at least one
801
+ member counts. Entities with owners therefore never trip the rule; in
802
+ practice it protects the deployment and seeded groups, whose owner is null.
803
+ It replaces any fixed list of protected grants: the administrators group can
804
+ be demoted once another group administers the deployment, and not before.
805
+ Kernel-internal writes are exempt, which is what lets `graphcore createadmin
806
+ --remove --force` act as the operator's override.
807
+
808
+ The persistence chokepoint stamps every new entity with the authenticated
809
+ principal's entity id and ignores any caller-supplied owner value. A type
810
+ declaring `ownerless = True` (`Grant`) never gets an owner. The
811
+ identity path that creates a principal's root entity supplies that same new
812
+ principal id. Existing owners are immutable at this chokepoint. Consequently,
813
+ every persisted owner names a `principal=True` entity; groups and `PUBLIC`
814
+ cannot enter the ownership path. The one exception is kernel seeding, which
815
+ writes kernel-internally with no principal and leaves `owner` null: the
816
+ `Deployment`, `graphcore.admins`, and application-declared groups. A
817
+ null owner matches no principal, so those entities are governed by grants
818
+ alone.
819
+
820
+ **Kernel-internal writes.** `kernel_internal_context()` makes the
821
+ persistence check return early for every save and delete inside it, and the
822
+ context propagates into everything awaited within. It is used only at these
823
+ call sites, and application code is never called while it is open:
824
+
825
+ | Call site | Purpose |
826
+ |---|---|
827
+ | `auth/authn/principals.py` (`create_principal`) | minting a principal on first sign-in, or in the test helpers |
828
+ | `auth/authn/authenticator.py` username resync | refreshing the username from the token's `preferred_username` on an existing `User` |
829
+ | `auth/authn/onboarding.py` | applying the memberships and deployment grants named by onboarding (fixed kernel code; hook code runs outside the context) |
830
+ | `bootstrap/deployment.py` | seeding the `Deployment`, `graphcore.admins`, declared groups, and their default grants |
831
+ | `management/commands/graphcore_createadmin.py` | adding or removing `graphcore.admins` members from the command line |
832
+ | `execution/StrategyExecutorService.py` | saving and deleting strategy request records (executor bookkeeping) |
833
+ | `public/testing.py` | test fixtures |
834
+
835
+ **Grant mutation.** Grants are `Grant` records mutated only through
836
+ the kernel grant strategies, each requiring `ManageAccess` on the resource —
837
+ via the ordinary inherited check against the grant entity or its resource.
838
+ Generic strategies cannot reach around this: typed class fields put grant
839
+ state beyond the attribute strategies, and the instantiation rule puts
840
+ creation beyond the generic create (see Grant storage).
841
+
842
+ ### Type policy
843
+
844
+ An application declares each type's authorization in one call, from the
845
+ configurator its `GraphCoreAppConfig.graphcore_authorization` names.
846
+ Discovery runs configurators after entity and strategy registration and
847
+ before the policy closes.
848
+
849
+ A type's authorization is plain CRUD on the type, read and enforced by the
850
+ engine, which asks the port only whether a principal holds a given perm:
851
+
852
+ | | Declared by | Default |
853
+ |---|---|---|
854
+ | **Create** | `create` | `Create()` |
855
+ | **Read** | `read` | `Read()` |
856
+ | **Update** | per-strategy permissions in `strategies` | `Write()`, or the type's read permission for a read-only strategy |
857
+ | **Delete** | `delete` | `Delete()` |
858
+
859
+ ```python
860
+ @dataclass(frozen=True)
861
+ class Publish(Perm):
862
+ description: ClassVar[str] = 'Publish a document'
863
+
864
+ PUBLISHER = Role('publisher', perms=frozenset({Read(), Write(), Publish()}))
865
+
866
+ def configure(policy: AccessPolicy) -> None:
867
+ policy.define(
868
+ DocumentHub,
869
+ shareable=True,
870
+ roles=[*DEFAULT_ROLES, PUBLISHER],
871
+ strategies={PublishDocument: Publish(), SetTitle: Write()},
872
+ )
873
+ ```
874
+
875
+ | Argument | Meaning | Default |
876
+ |---|---|---|
877
+ | `shareable` | The type can hold grants. | `False` |
878
+ | `roles` | The complete list of roles grantable on it. Other apps add roles with `extend`. | `viewer`, `editor`, `admin` (`DEFAULT_ROLES`) |
879
+ | `strategies` | `{Strategy: Perm}`: the permission each listed strategy requires on this type. Every entry states its permission. | `{}` |
880
+ | `other_strategies` | `False` makes the keys of `strategies` an allowlist: only the strategies listed in this call may target or write the type. | `True` |
881
+ | `create` | Permission needed on the parent (or on the deployment, with no parent) to create one. | `Create()` |
882
+ | `creatable` | `False`: only kernel code creates it. | `True`; `False` for `principal=True` types |
883
+ | `public` | Permissions every signed-in principal holds on every entity of the type, with no grant rows; reported with provenance `type-policy`. | `()` |
884
+ | `read` | The permission reading an entity of the type requires, and invoking any strategy on it. The engine asks for it on every read (see Inheritance) and at invocation. | `Read()` |
885
+ | `delete` | The permission deleting an entity of the type, and everything it contains, requires (see Enforcement, the deletion check). | `Delete()` |
886
+ | `can_contain` | The types that may be placed directly inside an entity of the type, subclasses included; `[]` allows none. Checked on every write (see Enforcement, Containment). | `None` (any) |
887
+ | `contained_by` | The types an entity of the type may be placed directly inside, subclasses included. When set, the entity is never top-level; `[]` is rejected (use `creatable=False`). Checked on every write (see Enforcement, Containment). | `None` (any parent or none) |
888
+
889
+ Rules that apply to every argument:
890
+
891
+ - **Defaults and inheritance.** An argument not passed is taken from the
892
+ nearest base class that passed it, else its default. `strategies` merges
893
+ instead: a subtype's entries override its base classes' per strategy. A
894
+ strategy with no permission anywhere needs the type's read permission if
895
+ it is declared `read_only_strategy = True`, otherwise `Write`.
896
+ - **One call per type, by its owner.** `define` may be called once per type,
897
+ and only from the app whose id prefixes the type's `entity_type_id`.
898
+ - **Adding to another app's type.** `policy.extend(Type, roles=[...])` adds
899
+ roles to a type another app defines; their names must start with the
900
+ declaring app's id. Duplicate role names on a type are refused when the
901
+ policy closes, so configurator order does not matter.
902
+ `policy.extend(Type, strategies={Strategy: Perm})` adds the declaring app's
903
+ own strategies, and only those, to the type's allowlist even when it is
904
+ closed. This is how an app's strategy runs without a target, which is
905
+ authorized against `Deployment`.
906
+ - **Reading it back.** `policy.describe(Type)` returns the complete,
907
+ resolved `EffectivePolicy`; `graphcore policy [type_id]` prints it for every
908
+ registered type. `GraphAPI.describe_entities` publishes the parts
909
+ clients need (`shareable`, `roles`, `public_permissions`).
910
+ - **Allowlists are exhaustive.** With `other_strategies=False`, a strategy
911
+ not listed cannot target or write the type, built-ins included. A
912
+ non-exhaustive allowlist would be bypassed by any strategy registered on a
913
+ base type.
914
+
915
+ **What a role grant gives, and what a strategy needs.** A grant says which
916
+ permissions a subject holds on a resource and on what it contains. What a subject can *do* with those permissions is set by
917
+ the policy of each type it acts on: which strategies may run there and what
918
+ each requires. An `editor` on a workspace holds `Read`, `Write`, `Delete`,
919
+ and `Create` across it, but can run on a contained document only the
920
+ strategies the document type allows, and only those whose required
921
+ permission `editor` includes.
922
+
923
+ Type-wide `public` permissions are not the per-entity visibility control.
924
+ Per-entity authenticated-public read is an ordinary direct grant to the
925
+ well-known `PUBLIC` subject (`'*'`), normally with the `viewer` role.
926
+ `User` is the one kernel type with `public=[Read()]`, unless the
927
+ deployment sets `GRAPHCORE_PUBLIC_USER_READ = False`.
928
+
929
+ Policy closes once applications finish loading; nothing can be declared
930
+ afterward. This is what makes the persistence check's guarantee hold
931
+ against strategy code generated after load: such code cannot widen its own
932
+ authorization by changing policy.
933
+
934
+ `principal` is declared at entity registration (`register_entity`),
935
+ because it says what kind of thing an entity is. A group is `Group`
936
+ or a subclass; see Groups for combining a group with `shareable`.
937
+
938
+ ### Identity-based policy
939
+
940
+ Everything above answers one question: may principal P do perm on entity
941
+ E. Authority flows from E's owner and from grants on E or a containing
942
+ scope, and every grant is issued by someone who already holds authority on
943
+ that resource. Users are therefore protected from each other, but an
944
+ operator has no say over what a user may start: every operation that has a
945
+ target entity is already governed by that entity's policy, so the only
946
+ uncovered case is an operation with no natural target, which in practice
947
+ is creating an entity at the top level. Identity-based policy closes that
948
+ gap with the machinery that already exists, by giving the deployment itself
949
+ an entity to hold grants.
950
+
951
+ **The deployment entity.** Each deployment has exactly one
952
+ `Deployment`. Its id is well-known, `gc://<backend_id>/000000000000`,
953
+ so it follows from the backend identity with no lookup; it is exposed as
954
+ `Runtime.deployment_entity_id` and in the identity document
955
+ (`docs/ENTITY_REFERENCE_TDD.md`), and clients target it for what acts on
956
+ the deployment itself: its grants and new-user settings. The kernel defines it like
957
+ any other type:
958
+
959
+ ```python
960
+ policy.define(
961
+ Deployment,
962
+ shareable=True, can_contain=[Grant], creatable=False,
963
+ roles=[MEMBER, ADMIN],
964
+ strategies={CreateEntity: Create(), CreateGroup: Create(),
965
+ SetViewState: Create(), CreateView: Create(),
966
+ SetNewUserDefaults: ManageAccess(), CreateGrant: ManageAccess()},
967
+ other_strategies=False,
968
+ )
969
+ ```
970
+
971
+ `can_contain=[Grant]` keeps everything but its own grants out of the
972
+ deployment, so `PUBLIC → member` never reaches content: the deployment is an
973
+ authority anchor, never a container. A create with no target is
974
+ authorized by it and creates at the top level; targeting it with a create,
975
+ or moving an entity under it, is refused. Its grants are read with `ManageAccess`, so only administrators see
976
+ who holds what on the deployment. It offers no content roles; `member` is
977
+ `{Read, Create}`. Its allowlist keeps generic strategies (delete, reparent,
978
+ attribute writes) off it whatever role someone holds. Creating at the top
979
+ level is the ordinary creation rule with the deployment in place of a
980
+ parent. The only thing the kernel does for the deployment and no other
981
+ entity is create it at bootstrap.
982
+
983
+ **Principals contain nothing.** `User` is defined with
984
+ `can_contain=[]`, so no entity is ever stored under a principal. What a
985
+ user creates at the top level is owned by them and has no parent; their
986
+ page views are top-level views owned by them (`docs/VIEW_ENTITY_TDD.md`).
987
+
988
+ Bootstrap writes two grants on the deployment: `PUBLIC → member`, which
989
+ keeps the zero-configuration default of anyone may create, and
990
+ `graphcore.admins → admin`. Revoking the `PUBLIC` grant is how a deployment
991
+ is locked down.
992
+
993
+ **Administrators.** A deployment administrator is a member of
994
+ `graphcore.admins`, a kernel-seeded group with a null owner that holds
995
+ `admin` on the deployment and on itself. The lockout rule keeps
996
+ administration from being lost: the group's role cannot be lowered, its
997
+ last member removed, or the group deleted while it is the only thing
998
+ administering the deployment. `graphcore createadmin <user>` adds a member
999
+ from the command line (kernel-internal) and restores the group's `admin`
1000
+ grant on the deployment; after that, administrators add each other by
1001
+ editing the group. The same command is the operator's recovery path.
1002
+
1003
+ **Restricting a type.** An application decides who may create a type with
1004
+ the type's `create` argument and a role that holds it:
1005
+
1006
+ ```python
1007
+ @dataclass(frozen=True)
1008
+ class CreateWorkspace(CreatePermission):
1009
+ description: ClassVar[str] = 'Create workspaces'
1010
+
1011
+ WORKSPACE_CREATOR = Role(
1012
+ 'myapp.workspace_creator', perms=frozenset({Read(), Create(), CreateWorkspace()}),
1013
+ description='Can create workspaces',
1014
+ )
1015
+
1016
+ def configure(policy: AccessPolicy) -> None:
1017
+ policy.define(Workspace, shareable=True, create=CreateWorkspace())
1018
+ policy.extend(Deployment, roles=[WORKSPACE_CREATOR])
1019
+ ```
1020
+
1021
+ Granted on the deployment, the role lets its holders create workspaces at
1022
+ the top level. `CreatePermission` is not implied by ownership, so nobody
1023
+ creates a workspace inside another entity unless they hold `CreateWorkspace`
1024
+ there. The role also carries `Create`, because the generic create strategy
1025
+ requires it on its target.
1026
+
1027
+ **Groups and keys.** A group may carry a `key`, unique per deployment and
1028
+ immutable once set. Applications declare groups in code with
1029
+ `policy.declare_group(key=..., name=...)`; seeding creates each one with a
1030
+ null owner and an `admin` grant to `graphcore.admins`. Code, configuration,
1031
+ and hooks refer to groups by key, because entity ids differ between
1032
+ environments and do not exist until seeding. Graph data refers to groups by
1033
+ id: an administrator picks a concrete group. `CreateGroup` creates
1034
+ a group under any entity that can contain one (requires `Create` on the
1035
+ target), or at the top level with no target.
1036
+ A group inside a scope inherits the scope's grants, so the scope's admins
1037
+ manage its roster. Whatever the parent, only a deployment administrator
1038
+ (`ManageAccess` on the deployment) may set a key or ask for the group to be
1039
+ administered by `graphcore.admins`. Whoever holds `Delete` on a group may delete it: its
1040
+ creator, and administrators for groups they administer. Grants elsewhere
1041
+ that name a deleted group as their subject remain and grant nothing.
1042
+
1043
+ **Seeding.** A `post_migrate` receiver seeds the deployment after the
1044
+ store's identity exists. Each entity is ensured by its stable identity (the
1045
+ `Deployment`'s singleton row, a group's key), and its default grants
1046
+ are written only by the run that created it. A later run therefore never
1047
+ re-grants what an administrator revoked, and concurrent runs cannot
1048
+ duplicate grants, which have no database uniqueness constraint. A declared
1049
+ group that an administrator deletes is recreated on the next migrate,
1050
+ empty; removing the declaration is how an application retires one. A
1051
+ recreated `graphcore.admins` is also granted `admin` on an existing
1052
+ deployment, so the recreated group administers it.
1053
+ Seeding writes through a store-only runtime (`bootstrap_runtime`: no entity
1054
+ cache, no channel layer), because `migrate` may run where only the database
1055
+ is reachable; nothing it creates can already be cached or watched.
1056
+
1057
+ **Onboarding.** Every principal is created by one kernel function,
1058
+ `create_principal`. After it commits, the kernel runs each installed app's
1059
+ principal-created hook, declared as `graphcore_principal_created` on the app
1060
+ config, after its own default hook. A hook receives the new principal and
1061
+ the deployment entity and returns:
1062
+
1063
+ ```python
1064
+ Onboarding(
1065
+ groups=['myapp.staff'], # group keys: memberships the kernel applies
1066
+ group_ids=[], # group ids: likewise
1067
+ roles=['member'], # deployment roles the kernel grants directly
1068
+ requests=[...], # strategy requests run as the new principal
1069
+ )
1070
+ ```
1071
+
1072
+ The kernel default hook reads the deployment's `new_user_group_ids` and
1073
+ `new_user_roles`, which administrators set with
1074
+ `SetNewUserDefaults`. The split keeps enforcement intact: hook code
1075
+ runs outside any kernel-internal context and only *names* groups and roles,
1076
+ which the kernel applies with fixed code; anything else a hook wants done
1077
+ is a strategy request executed as the new principal, under every ordinary
1078
+ check. Unknown keys and roles are logged and skipped, and a failing hook
1079
+ never blocks sign-in; the principal simply receives less, which the
1080
+ administrator panel shows as a member with no access.
1081
+
1082
+ **Federation.** Principals materialized from a cooperating deployment are
1083
+ authenticated, so they are in `PUBLIC` and receive `member` under the
1084
+ default grant. A deployment that should not let them create grants
1085
+ `member` to a local group instead of `PUBLIC`.
1086
+
1087
+ ### Invites
1088
+
1089
+ An invite is a link that turns into an ordinary grant for whoever signs in
1090
+ with it. It is how a person shares a scope with someone who may not have an
1091
+ account yet: the recipient signs in or registers, and the link is redeemed
1092
+ as the principal they end up as.
1093
+
1094
+ `Invite` is a kernel entity contained by the resource it invites to, with
1095
+ the same policy shape as `Grant`: no owner, created, read, and deleted with
1096
+ `ManageAccess` on the resource, permitted only under a shareable type,
1097
+ deleted with its resource. A shareable type that restricts `can_contain`
1098
+ lists `Invite` to be invitable.
1099
+
1100
+ | Field | Meaning |
1101
+ | --- | --- |
1102
+ | `role_name` | The role granted on redemption; must be registered for the resource's type. |
1103
+ | `token_hash` | Hex SHA-256 of the link secret. The secret itself is never stored. |
1104
+ | `expires_at` | Epoch seconds after which redemption is refused. Default 7 days out, at most 30. |
1105
+ | `max_uses` | Distinct principals that may redeem it. Default 1. |
1106
+ | `redeemed_by` | Principal ids that have redeemed it. |
1107
+
1108
+ **The secret.** The link carries `<invite_id>.<secret>`, where the secret is
1109
+ 32 random bytes. Storage keeps only `sha256(secret)`; redemption loads the
1110
+ invite by id, hashes the presented secret, and compares the two in constant
1111
+ time. A fast hash is enough: the secret is random, not a password, so it
1112
+ cannot be guessed whatever the hash costs. Anyone who can read invite rows,
1113
+ a backup, or the request history learns nothing that redeems one.
1114
+
1115
+ **Creating.** `CreateInvite` targets the resource, requires `ManageAccess`,
1116
+ and takes `role_name`, `token_hash`, and optionally `expires_in_seconds` and
1117
+ `max_uses`. It takes the hash, never the secret, because strategy requests
1118
+ are persisted. `GraphAPI.create_invite` generates the secret, runs
1119
+ `CreateInvite` with its hash, and returns the token, the only copy of the
1120
+ secret:
1121
+
1122
+ ```
1123
+ POST graphcore/api/invites/ {"resource_id": ..., "role_name": "editor", "max_uses": 1}
1124
+ -> 200 {"invite_entity_id": ..., "token": "<invite_id>.<secret>"}
1125
+ ```
1126
+
1127
+ Revoking an invite is deleting it (`DeleteEntity`, `ManageAccess`).
1128
+
1129
+ **Redeeming is a kernel endpoint, not a strategy.** The redeemer holds no
1130
+ access to the invite or its resource, so a strategy would either widen
1131
+ invite visibility or run application-reachable code with kernel authority.
1132
+ Redemption is instead a fixed kernel write, like onboarding:
1133
+
1134
+ ```
1135
+ POST graphcore/api/invites/redeem/ {"token": "<invite_id>.<secret>"}
1136
+ -> 200 {"resource_id": ..., "entity_type_id": ...}
1137
+ ```
1138
+
1139
+ The caller must be an authenticated principal. `GraphAPI.redeem_invite`
1140
+ loads the invite through the unchecked internal path, checks the hash,
1141
+ expiry, and use count, then inside `kernel_internal_context()` appends the
1142
+ principal to `redeemed_by` and writes the grant with `kernel_writes.grant`.
1143
+ The use is claimed before the grant, so concurrent redemptions of a last use
1144
+ lose on the invite's version, before any grant exists. A principal who has
1145
+ already redeemed it, already holds a direct grant on the resource, or can
1146
+ manage access to it gets the resource back with nothing changed and nothing
1147
+ used up, so an invite never downgrades anyone. Every refusal is the same
1148
+ 404, so the endpoint does not reveal which invites exist.
1149
+
1150
+ **The link.** Clients build `{app_origin}/invite#<token>` (`inviteUrl` in
1151
+ the kernel frontend). The token travels in the fragment, so it never
1152
+ reaches a server log or a `Referer` header.
1153
+
1154
+ **Sign-in and registration.** The kernel frontend's `InviteRoute`, mounted
1155
+ at `INVITE_ROUTE` outside any sign-in gate (`GraphCoreApp` does this),
1156
+ redeems as soon as a principal is signed in and hands the result to the
1157
+ application's `onRedeemed(invite)`, by default opening the resource's
1158
+ entity page. Signed out, it starts the ordinary OIDC sign-in, whose
1159
+ `returnTo` state carries the full URL, fragment included, back to the route.
1160
+ If the issuer's discovery document lists `create` in
1161
+ `prompt_values_supported` (OIDC Initiating User Registration), the route
1162
+ offers a separate "Create account" that sends `prompt=create`; otherwise it
1163
+ offers one "Continue", and the person registers from the issuer's own login
1164
+ page. Redemption is the same step for a new and an existing account, and
1165
+ nothing about it depends on the identity provider beyond standard OIDC.
1166
+
1167
+ Invites always redeem into a grant to a principal. Access without an
1168
+ account would need a capability subject on the adapter's read path; see
1169
+ Open items.
1170
+
1171
+ ### Authoring examples
1172
+
1173
+ An entity type with no sharing customization needs no authorization code:
1174
+
1175
+ ```python
1176
+ @register_entity
1177
+ class Note(Entity):
1178
+ pass
1179
+
1180
+ @register_strategy(Note)
1181
+ class SetTitle(Strategy):
1182
+ async def apply(self):
1183
+ self.entity.set_attribute('title', self.strategy_request.param_config['title'])
1184
+ self.entity = await self.save_entity(self.entity)
1185
+ return self.strategy_request, self.entity
1186
+ ```
1187
+
1188
+ A `Note` is governed by the scope that contains it. A `Viewer` of that
1189
+ scope can read the note and cannot run `SetTitle`. An `Editor` can run
1190
+ it, because `Editor` carries `Write` and the strategy's default required
1191
+ permission is `Write`. Only an `Admin` can change who has access to the
1192
+ scope.
1193
+
1194
+ An entity type with a custom role keeps the same domain code; only its type
1195
+ policy differs:
1196
+
1197
+ ```python
1198
+ @register_entity()
1199
+ class DocumentHub(Entity):
1200
+ pass
1201
+
1202
+ @register_strategy(Document)
1203
+ class PublishDocument(Strategy):
1204
+ async def apply(self):
1205
+ self.entity.publish()
1206
+ self.entity = await self.save_entity(self.entity)
1207
+ return self.strategy_request, self.entity
1208
+
1209
+ # type policy for DocumentHub, shown above under Type policy
1210
+ ```
1211
+
1212
+ A principal holding `PUBLISHER` on a `DocumentHub` may run
1213
+ `PublishDocument` on any document the hub contains — including
1214
+ documents created after the grant — and may also run `SetTitle`,
1215
+ because `PUBLISHER` carries `Write`. A principal holding `editor` on the same
1216
+ hub may run `SetTitle` but not `PublishDocument`, because
1217
+ `editor` does not carry `Publish`. A principal holding `admin` (by grant, or
1218
+ as the hub's owner) may run both: `Publish` leaves `admin_implied` at its
1219
+ default, so `ManageAccess` satisfies it. Had the application declared
1220
+ `admin_implied = False` on `Publish`, the admin would need a `PUBLISHER`
1221
+ grant like anyone else — which, holding `ManageAccess`, they can give
1222
+ themselves.
1223
+
1224
+ ### Port consumers
1225
+
1226
+ Three components call the port, each using a disjoint slice of it, and the
1227
+ port's shape follows directly from that split. How the three compose — and
1228
+ everything about delivery mechanics, channels, and the migration to
1229
+ `GraphAPI` as the sole mutation front door.
1230
+
1231
+ - `GraphAPI` calls the grant-interpretation methods (`available_roles`,
1232
+ `list_grants`) for the share surface, `list_grants` only for a caller
1233
+ holding `ManageAccess` on the resource: `get_access` returns the grants to a
1234
+ manager and an empty list to anyone else. Grant *mutation* never enters the
1235
+ port from above: `GraphAPI.grant`/`revoke` dispatch the kernel grant
1236
+ strategies, and those writes reach the port only as the entity writes its
1237
+ hooks observe.
1238
+ - `EntityService` calls the decision methods (`allows`, `read_filters`)
1239
+ with the perms the type policy names to enforce, the lockout checks
1240
+ (`check_save` on an update, `check_delete` before a delete) inside the
1241
+ persistence check, and the lifecycle hooks after every committed write:
1242
+ `entity_saved` after a save, and `prepare_delete` before a delete (while
1243
+ the rows exist) with `entities_deleted(plan)` after it. It is the right
1244
+ caller of the hooks because it holds the prior in-memory state and knows
1245
+ when a commit succeeded. `EntityService` names no concrete entity type
1246
+ (`docs/ARCHITECTURE_PRINCIPLES.md`, rule 7); everything type-specific is
1247
+ behind these methods. Most entities no-op here — the default adapter only
1248
+ reacts when the entity carries state its own caches depend on. The one
1249
+ built-in case is a group: on save, the adapter diffs `member_ids` between
1250
+ `previous` and `entity`, and busts its cached subject-set expansion for the
1251
+ symmetric difference of old and new members. On delete, `prepare_delete`
1252
+ hydrates the doomed grants and groups, and `entities_deleted` busts the
1253
+ former members' caches and returns each grant's revoke.
1254
+ - **The broadcaster** calls the sync-support methods: `granted_resources`
1255
+ at connect time, `scopes` and `owner_principals` per committed write,
1256
+ `holders` per write of a type whose read permission is not `Read` (grants),
1257
+ and `covers` per `AccessChange`. For a revoke it skips a principal who
1258
+ still reads the resource, asking `allows` for the read permission of the
1259
+ type the change's `resource_type_id` names (`Read` when unknown); the
1260
+ adapter emits one revoke per removed member and resource without deciding
1261
+ that itself. These answer where changes fan out and whom they touch
1262
+ from the same grant facts the decision methods read — which is why they
1263
+ live on this port rather than in the broadcaster: the broadcaster owns
1264
+ delivery mechanics but never learns what a grant, group, or scope means.
1265
+
1266
+ One trigger, one pipeline: every change — content or access — is an entity
1267
+ write. The hooks give the adapter its index maintenance; when the written
1268
+ entity is a `Grant` they additionally return an `AccessChange`, which
1269
+ `GraphAPI` routes to the broadcaster to adjust channel subscriptions for
1270
+ affected principals.
1271
+
1272
+ Worked example, fan-out: Bob holds an `Editor` grant on `DocumentHub`. On
1273
+ connect, `granted_resources(bob)` returns `{DocumentHub}`, so Bob subscribes
1274
+ to `scope_{DocumentHub}` and `PUBLIC`. Later, `Document X` — a child of
1275
+ `DocumentHub`, no grants of its own — is saved. `scopes(document_x)` returns
1276
+ `{document_x, DocumentHub}`, so the update publishes to both channels; Bob's
1277
+ subscription to the latter delivers it. Nothing enumerated "who can read
1278
+ Document X" to make that happen — and the same property means a fresh grant
1279
+ on `DocumentHub` covers its entire subtree with a single channel join.
1280
+
1281
+ Worked example, owner fan-out: Alice owns `DocumentHub`, so her socket joins
1282
+ the stable `owner_{alice}` channel when it connects. `Document X` is owned by
1283
+ Bob but contained by `DocumentHub`. When it is saved,
1284
+ `scopes(document_x)` returns `{document_x, DocumentHub}` and
1285
+ `owner_principals(...)` returns `{bob, alice}`. The update publishes to both
1286
+ stable owner channels as well as the scope channels. Alice receives it as
1287
+ the covering scope's owner and Bob receives it as the entity's direct owner.
1288
+ Creating another entity requires no new owner subscription and connection
1289
+ setup never enumerates either principal's entities.
1290
+
1291
+ Worked example, invalidation: Alice is added to `Group` `Engineering`
1292
+ via `AddMember`. `EntityService` saves the group, then calls
1293
+ `entity_saved(engineering, previous)`. The adapter diffs `member_ids`, finds
1294
+ Alice in the symmetric difference, and busts her cached subject-set — so a
1295
+ check running immediately after (`allows(alice, Write(), some_doc)`)
1296
+ recomputes her groups instead of answering from a stale cache that predates
1297
+ her membership.
1298
+
1299
+ ### Trade-offs
1300
+
1301
+ - **Enforcement rides on the executor's strategy context.** The persistence
1302
+ check trusts the executor's record of which strategy is running; that
1303
+ context (like the executor itself) must remain outside strategy code's
1304
+ reach. An unconditional `Write`/`Delete` floor with no strategy awareness
1305
+ would be simpler but laundering-prone, and could not express perm-gated
1306
+ roles without `Write`.
1307
+ - **Exhaustive allowlists carry a maintenance cost.** Adding a new strategy to
1308
+ an application requires updating every type policy that declares an
1309
+ allowlist for a type the strategy targets. This cost is accepted because a
1310
+ non-exhaustive allowlist can be bypassed by strategies registered on base
1311
+ types.
1312
+ - `revoke` **does not reach inherited access.** Removing a grant on an entity
1313
+ has no effect on access inherited from a containing scope; access must be
1314
+ revoked at the scope that grants it. `list_grants` provenance makes the
1315
+ source of any grant visible so this is never ambiguous to a user.
1316
+ - **Owner-implicit `Admin` is exactly `Admin`, not a superuser.** The
1317
+ owner branch of `allows` evaluates `ADMIN.allows(perm)` — the same rule a
1318
+ granted admin gets — so an `admin_implied = False` perm is denied to the
1319
+ owner too unless they hold it by grant. A blanket owner short-circuit would
1320
+ be simpler but would make the opt-out unenforceable on the one subject
1321
+ most likely to hold every other perm.
1322
+ - **An owner cannot be demoted.** Owner-implicit `Admin` is not a grant row,
1323
+ so other admins cannot revoke it; removing it means transferring ownership.
1324
+ Accepted deliberately: it also guarantees no scope is ever left without an
1325
+ administrator. Ownership transfer is an open item.
1326
+ - **No check-time delegation to external authorities.** Grant truth lives in
1327
+ the graph; a deployment whose access facts must remain solely in a central
1328
+ IAM (zero local copies, zero staleness) is not supported. Such systems
1329
+ integrate by syncing into grant entities instead. This trade buys the entire
1330
+ live-update, share-surface, and rebuild-from-graph story; see Grant storage.
1331
+
1332
+
1333
+ - **One deployment entity for every application.** Applications share a
1334
+ single authority anchor, so their deployment roles are namespaced by app
1335
+ id. Per-application anchors would allow per-application administrators,
1336
+ at the cost of more structure.
1337
+ - **The zero-configuration default is permissive.** `PUBLIC → member` keeps
1338
+ new deployments working with no setup; a deployment that needs approval
1339
+ must revoke it.
1340
+ - **Groups created from the administrator panel keep their creator as
1341
+ owner.** They also grant `admin` to `graphcore.admins`, but the creator's
1342
+ implicit `Admin` remains until ownership transfer exists.
1343
+ - **The lockout rule costs a lookup per access change.** Every grant change,
1344
+ roster shrink, and deletion of grants or groups asks whether a manager
1345
+ remains on each affected resource. Accepted because access changes are rare
1346
+ next to reads, and a fixed list of protected grants would be one more
1347
+ special case to learn.
1348
+ - **Grant ids are visible to a resource's readers.** A grant is a child of
1349
+ its resource, so its id appears in the resource's `children_ids` for anyone
1350
+ who can read the resource, though the grant itself reads as a forbidden
1351
+ tombstone. Filtering `children_ids` per reader would cost a decision per
1352
+ child on every read; an id reveals only that some grant exists.
1353
+ - **Viewers do not see collaborators.** Only those who can manage access to
1354
+ a resource see who has access to it. A viewer's share panel says so instead
1355
+ of listing grants. Showing everyone the grant list would be simpler, but
1356
+ leaks who else was given access to anyone given any access.
1357
+ - **Grant fan-out is per holder.** A grant save goes to the owner channel of
1358
+ each principal holding `ManageAccess` on its resource, computed per write,
1359
+ because the scope channels carry `Read`. Accepted because grant writes are
1360
+ rare.
1361
+
1362
+
1363
+
1364
+ ### Open items
1365
+
1366
+ - The subject and grant model for non-interactive principals (scheduled
1367
+ executions reconstructing an identity-only principal) and for a
1368
+ kernel-internal service principal.
1369
+ - Nested groups (a group whose members include another group) — explicitly
1370
+ out of v1; see Groups.
1371
+ - Capability-based subjects (e.g. a link granting read access without an
1372
+ account) as a subject kind distinct from principals and groups.
1373
+ - Ownership transfer: the operation that changes a scope's `owner`, who may
1374
+ invoke it, and how it interacts with owner-implicit `Admin`.
1375
+ - Removing grants that name a deleted group as their subject, as part of a
1376
+ general reference-cleanup mechanism.
1377
+ - Scope-owned contents: letting a shareable scope own what is created inside
1378
+ it, so removing someone from a tenant removes their authority over what they
1379
+ created there.