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.
- graphcore/__init__.py +5 -0
- graphcore/agent_frontend/__init__.py +8 -0
- graphcore/agent_frontend/api.py +69 -0
- graphcore/agent_frontend/base/__init__.py +11 -0
- graphcore/agent_frontend/base/views.py +167 -0
- graphcore/agent_frontend/client.py +31 -0
- graphcore/agent_frontend/context.py +157 -0
- graphcore/agent_frontend/errors.py +12 -0
- graphcore/agent_frontend/loading.py +54 -0
- graphcore/agent_frontend/registry.py +42 -0
- graphcore/agent_frontend/render.py +207 -0
- graphcore/agent_frontend/server.py +103 -0
- graphcore/agent_frontend/signatures.py +35 -0
- graphcore/agent_frontend/testing.py +45 -0
- graphcore/agent_frontend/tests/__init__.py +0 -0
- graphcore/agent_frontend/tests/fakes.py +114 -0
- graphcore/agent_frontend/tests/test_frontend.py +447 -0
- graphcore/agent_frontend/tests/test_loading.py +83 -0
- graphcore/agent_frontend/tests/test_server.py +109 -0
- graphcore/agent_frontend/tools.py +137 -0
- graphcore/api/__init__.py +4 -0
- graphcore/api/graph_api.py +378 -0
- graphcore/api/predicate_codec.py +81 -0
- graphcore/api/tests/__init__.py +0 -0
- graphcore/api/tests/test_changed_entities.py +109 -0
- graphcore/api/tests/test_graph_api.py +290 -0
- graphcore/api/tests/test_graph_api_access.py +94 -0
- graphcore/api/tests/test_graph_api_grants.py +90 -0
- graphcore/api/tests/test_predicate_codec.py +83 -0
- graphcore/api/tests/test_subtree_query.py +79 -0
- graphcore/apps.py +71 -0
- graphcore/auth/__init__.py +1 -0
- graphcore/auth/authn/README.md +178 -0
- graphcore/auth/authn/__init__.py +3 -0
- graphcore/auth/authn/authenticator.py +120 -0
- graphcore/auth/authn/onboarding.py +105 -0
- graphcore/auth/authn/principals.py +20 -0
- graphcore/auth/authn/resource_metadata.py +43 -0
- graphcore/auth/authn/service_accounts.py +96 -0
- graphcore/auth/authn/testing.py +96 -0
- graphcore/auth/authn/tests/__init__.py +0 -0
- graphcore/auth/authn/tests/test_authenticator.py +145 -0
- graphcore/auth/authn/tests/test_onboarding.py +145 -0
- graphcore/auth/authn/tests/test_service_accounts.py +180 -0
- graphcore/auth/authn/users.py +59 -0
- graphcore/auth/authz/__init__.py +0 -0
- graphcore/auth/authz/access_port.py +120 -0
- graphcore/auth/authz/adapter/__init__.py +0 -0
- graphcore/auth/authz/adapter/default_access_adapter.py +556 -0
- graphcore/auth/authz/adapter/tests/__init__.py +0 -0
- graphcore/auth/authz/adapter/tests/test_default_adapter.py +543 -0
- graphcore/auth/authz/adapter/tests/test_entity_write_hooks.py +207 -0
- graphcore/auth/authz/adapter/tests/test_group_types.py +70 -0
- graphcore/auth/authz/adapter/tests/test_sync_support.py +209 -0
- graphcore/auth/authz/defaults.py +26 -0
- graphcore/auth/authz/kernel_policy.py +191 -0
- graphcore/auth/authz/kernel_writes.py +31 -0
- graphcore/auth/authz/lookups.py +25 -0
- graphcore/auth/authz/policy.py +403 -0
- graphcore/auth/authz/tests/__init__.py +0 -0
- graphcore/auth/authz/tests/test_can_contain.py +150 -0
- graphcore/auth/authz/tests/test_contained_by.py +167 -0
- graphcore/auth/authz/tests/test_creation.py +391 -0
- graphcore/auth/authz/tests/test_delete_permission.py +82 -0
- graphcore/auth/authz/tests/test_granted_to_me.py +160 -0
- graphcore/auth/authz/tests/test_integration.py +637 -0
- graphcore/auth/authz/tests/test_invites.py +184 -0
- graphcore/auth/authz/tests/test_kernel_policy.py +140 -0
- graphcore/auth/authz/tests/test_lockout.py +132 -0
- graphcore/auth/authz/tests/test_policy.py +329 -0
- graphcore/auth/authz/tests/test_primitives.py +73 -0
- graphcore/auth/authz/tests/test_principal_creation.py +62 -0
- graphcore/bootstrap/__init__.py +0 -0
- graphcore/bootstrap/deployment.py +67 -0
- graphcore/bootstrap/signals.py +16 -0
- graphcore/bootstrap/tests/__init__.py +0 -0
- graphcore/bootstrap/tests/test_deployment_seed.py +154 -0
- graphcore/broadcast/__init__.py +4 -0
- graphcore/broadcast/broadcaster.py +201 -0
- graphcore/broadcast/channels.py +56 -0
- graphcore/broadcast/tests/__init__.py +0 -0
- graphcore/broadcast/tests/test_broadcaster.py +444 -0
- graphcore/celery.py +14 -0
- graphcore/docs/AGENT_FRONTEND_TDD.md +389 -0
- graphcore/docs/ARCHITECTURE_PRINCIPLES.md +152 -0
- graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +1379 -0
- graphcore/docs/ENTITY_REFERENCE_TDD.md +561 -0
- graphcore/docs/GRAPHAPI_FRONT_DOOR.md +173 -0
- graphcore/docs/RUNTIME.md +90 -0
- graphcore/docs/SCHEDULING_TDD.md +244 -0
- graphcore/docs/STRATEGY_EXECUTION_TDD.md +1043 -0
- graphcore/docs/VIEW_ENTITY_TDD.md +522 -0
- graphcore/docs/VIEW_SYSTEM_TDD.md +307 -0
- graphcore/docs/__init__.py +0 -0
- graphcore/docs/doc_topics.py +97 -0
- graphcore/docs/docs_discovery.py +64 -0
- graphcore/docs/public_api.py +56 -0
- graphcore/domain/__init__.py +0 -0
- graphcore/domain/entity/Entity.py +204 -0
- graphcore/domain/entity/__init__.py +0 -0
- graphcore/domain/entity/deployment/Deployment.py +25 -0
- graphcore/domain/entity/deployment/__init__.py +0 -0
- graphcore/domain/entity/grant/Grant.py +31 -0
- graphcore/domain/entity/grant/__init__.py +0 -0
- graphcore/domain/entity/group/Group.py +48 -0
- graphcore/domain/entity/group/README.md +88 -0
- graphcore/domain/entity/group/__init__.py +0 -0
- graphcore/domain/entity/invite/Invite.py +31 -0
- graphcore/domain/entity/invite/__init__.py +0 -0
- graphcore/domain/entity/request_template/RequestTemplate.py +48 -0
- graphcore/domain/entity/request_template/__init__.py +0 -0
- graphcore/domain/entity/request_template/tests/__init__.py +0 -0
- graphcore/domain/entity/request_template/tests/test_request_template.py +52 -0
- graphcore/domain/entity/service_account/ServiceAccount.py +41 -0
- graphcore/domain/entity/service_account/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/StrategyRequest.py +61 -0
- graphcore/domain/entity/strategy_request/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/tests/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/tests/test_strategy_request_entity.py +35 -0
- graphcore/domain/entity/tests/__init__.py +0 -0
- graphcore/domain/entity/tests/test_entity.py +227 -0
- graphcore/domain/entity/tests/test_grant_group_entities.py +36 -0
- graphcore/domain/entity/tests/test_write_once_fields.py +98 -0
- graphcore/domain/entity/user/User.py +39 -0
- graphcore/domain/entity/user/__init__.py +0 -0
- graphcore/domain/entity/user/tests/__init__.py +0 -0
- graphcore/domain/entity/user/tests/test_user_entity.py +33 -0
- graphcore/domain/entity/view/View.py +37 -0
- graphcore/domain/entity/view/__init__.py +0 -0
- graphcore/domain/entity/view/position.py +78 -0
- graphcore/domain/entity/view/tests/__init__.py +0 -0
- graphcore/domain/entity/view/tests/test_position.py +71 -0
- graphcore/domain/entity/view/tests/test_view_entity.py +134 -0
- graphcore/domain/strategy/BaseStrategy.py +759 -0
- graphcore/domain/strategy/DeploymentStrategies.py +55 -0
- graphcore/domain/strategy/GrantStrategies.py +189 -0
- graphcore/domain/strategy/GroupStrategies.py +193 -0
- graphcore/domain/strategy/InviteStrategies.py +84 -0
- graphcore/domain/strategy/RequestTemplateStrategies.py +126 -0
- graphcore/domain/strategy/ViewStrategies.py +219 -0
- graphcore/domain/strategy/__init__.py +0 -0
- graphcore/domain/strategy/runner.py +84 -0
- graphcore/domain/strategy/session.py +56 -0
- graphcore/domain/strategy/tests/BaseStrategyTest.py +167 -0
- graphcore/domain/strategy/tests/__init__.py +0 -0
- graphcore/domain/strategy/tests/test_BaseStrategies.py +870 -0
- graphcore/domain/strategy/tests/test_grant_strategies.py +245 -0
- graphcore/domain/strategy/tests/test_group_strategies.py +99 -0
- graphcore/domain/strategy/tests/test_runner.py +220 -0
- graphcore/domain/strategy/tests/test_strategy_locks.py +446 -0
- graphcore/domain/strategy/tests/test_utils.py +95 -0
- graphcore/domain/strategy/tests/test_view_strategies.py +436 -0
- graphcore/errors.py +145 -0
- graphcore/execution/README.md +97 -0
- graphcore/execution/StrategyExecutorService.py +333 -0
- graphcore/execution/__init__.py +0 -0
- graphcore/execution/dispatcher.py +19 -0
- graphcore/execution/environments/__init__.py +0 -0
- graphcore/execution/environments/celery.py +59 -0
- graphcore/execution/environments/in_process.py +55 -0
- graphcore/execution/local_session.py +117 -0
- graphcore/execution/redis_run_events.py +74 -0
- graphcore/execution/requests.py +22 -0
- graphcore/execution/run_events.py +85 -0
- graphcore/execution/strategy_context.py +54 -0
- graphcore/execution/tasks.py +34 -0
- graphcore/execution/tests/__init__.py +5 -0
- graphcore/execution/tests/contract.py +171 -0
- graphcore/execution/tests/support.py +310 -0
- graphcore/execution/tests/test_dispatchers.py +76 -0
- graphcore/execution/tests/test_executor.py +368 -0
- graphcore/execution/tests/test_local_session.py +95 -0
- graphcore/execution/tests/test_reconcile_runs.py +134 -0
- graphcore/execution/tests/test_run_events.py +106 -0
- graphcore/execution/tests/test_strategy_context.py +62 -0
- graphcore/gateway/__init__.py +1 -0
- graphcore/gateway/remote.py +35 -0
- graphcore/gateway/tests/__init__.py +0 -0
- graphcore/gateway/tests/test_remote.py +30 -0
- graphcore/graph/EntityService.py +710 -0
- graphcore/graph/__init__.py +0 -0
- graphcore/graph/entity_cache.py +152 -0
- graphcore/graph/tests/__init__.py +4 -0
- graphcore/graph/tests/test_EntityService.py +908 -0
- graphcore/graph/tests/test_EntityService_list.py +170 -0
- graphcore/graph/tests/test_EntityService_model_resolution.py +339 -0
- graphcore/graph/tests/test_EntityService_referrers.py +236 -0
- graphcore/graph/tests/test_EntityService_routing.py +119 -0
- graphcore/graph/tests/test_dependent_on.py +141 -0
- graphcore/graph/tests/test_engine_is_type_agnostic.py +25 -0
- graphcore/graph/tests/test_engine_resolves_read_permission.py +93 -0
- graphcore/graph/tests/test_entity_cache.py +159 -0
- graphcore/graph/tests/test_null_entity_cache.py +12 -0
- graphcore/management/__init__.py +0 -0
- graphcore/management/commands/__init__.py +0 -0
- graphcore/management/commands/dev_reset.py +18 -0
- graphcore/management/commands/graphcore_createadmin.py +65 -0
- graphcore/management/commands/graphcore_policy.py +59 -0
- graphcore/management/commands/graphcore_status.py +98 -0
- graphcore/management/tests/__init__.py +0 -0
- graphcore/management/tests/test_createadmin.py +78 -0
- graphcore/management/tests/test_policy_command.py +46 -0
- graphcore/management/tests/test_status_command.py +85 -0
- graphcore/migrations/0001_initial.py +186 -0
- graphcore/migrations/0002_invite.py +26 -0
- graphcore/migrations/__init__.py +0 -0
- graphcore/models.py +11 -0
- graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +396 -0
- graphcore/persistence/__init__.py +6 -0
- graphcore/persistence/django/__init__.py +0 -0
- graphcore/persistence/django/backends.py +43 -0
- graphcore/persistence/django/bindings.py +28 -0
- graphcore/persistence/django/cache.py +38 -0
- graphcore/persistence/django/compiler.py +214 -0
- graphcore/persistence/django/identity.py +18 -0
- graphcore/persistence/django/models.py +252 -0
- graphcore/persistence/django/repository.py +525 -0
- graphcore/persistence/django/tests/__init__.py +0 -0
- graphcore/persistence/django/tests/test_backends.py +68 -0
- graphcore/persistence/django/tests/test_compiler.py +269 -0
- graphcore/persistence/django/tests/test_repository.py +472 -0
- graphcore/persistence/django/tests/test_shared_column.py +120 -0
- graphcore/persistence/django/tests/test_threads.py +50 -0
- graphcore/persistence/django/tests/test_update_shape.py +175 -0
- graphcore/persistence/django/threads.py +38 -0
- graphcore/persistence/repository.py +172 -0
- graphcore/persistence/tests/__init__.py +0 -0
- graphcore/persistence/tests/contract.py +688 -0
- graphcore/persistence/tests/evaluate.py +51 -0
- graphcore/persistence/tests/fixtures.py +32 -0
- graphcore/persistence/tests/memory.py +263 -0
- graphcore/persistence/tests/test_memory_repository.py +10 -0
- graphcore/persistence/tests/test_query_types.py +127 -0
- graphcore/public/__init__.py +9 -0
- graphcore/public/api.py +9 -0
- graphcore/public/apps.py +10 -0
- graphcore/public/auth/__init__.py +1 -0
- graphcore/public/auth/grants.py +7 -0
- graphcore/public/auth/onboarding.py +8 -0
- graphcore/public/auth/perms.py +7 -0
- graphcore/public/auth/policy.py +10 -0
- graphcore/public/auth/roles.py +8 -0
- graphcore/public/auth/subjects.py +7 -0
- graphcore/public/entities/__init__.py +32 -0
- graphcore/public/errors.py +19 -0
- graphcore/public/persistence/__init__.py +44 -0
- graphcore/public/persistence/django.py +24 -0
- graphcore/public/scheduling.py +23 -0
- graphcore/public/strategies/__init__.py +85 -0
- graphcore/public/test_settings.py +16 -0
- graphcore/public/testing.py +47 -0
- graphcore/registry/EntityDirectory.py +246 -0
- graphcore/registry/README.md +147 -0
- graphcore/registry/StrategyDirectory.py +308 -0
- graphcore/registry/TYPE_METADATA_PLACEMENT.md +66 -0
- graphcore/registry/__init__.py +0 -0
- graphcore/registry/app_discovery.py +108 -0
- graphcore/registry/decorators.py +77 -0
- graphcore/registry/discovery.py +111 -0
- graphcore/registry/registry.py +79 -0
- graphcore/registry/tests/__init__.py +0 -0
- graphcore/registry/tests/test_agent_frontend_discovery.py +56 -0
- graphcore/registry/tests/test_app_config.py +36 -0
- graphcore/registry/tests/test_discovery.py +147 -0
- graphcore/registry/tests/test_entity_directory_storage.py +73 -0
- graphcore/registry/tests/test_import_package.py +87 -0
- graphcore/registry/tests/test_principal_flag.py +67 -0
- graphcore/registry/tests/test_strategy_directory.py +29 -0
- graphcore/routes/__init__.py +116 -0
- graphcore/routes/tests/__init__.py +0 -0
- graphcore/routes/tests/test_routes.py +90 -0
- graphcore/runtime.py +243 -0
- graphcore/scheduling/__init__.py +0 -0
- graphcore/scheduling/beat_scheduler.py +164 -0
- graphcore/scheduling/beat_tasks.py +63 -0
- graphcore/scheduling/scheduler.py +37 -0
- graphcore/scheduling/tests/__init__.py +0 -0
- graphcore/scheduling/tests/contract.py +136 -0
- graphcore/scheduling/tests/memory.py +42 -0
- graphcore/scheduling/tests/test_beat_scheduler.py +87 -0
- graphcore/scheduling/tests/test_memory_scheduler.py +15 -0
- graphcore/scheduling/tests/test_ticks.py +143 -0
- graphcore/tasks.py +9 -0
- graphcore/test_settings.py +78 -0
- graphcore/testing/__init__.py +0 -0
- graphcore/testing/case.py +112 -0
- graphcore/testing/runner.py +32 -0
- graphcore/testing/settings.py +26 -0
- graphcore/testing/tests/__init__.py +0 -0
- graphcore/testing/tests/agent_view_fixture.py +19 -0
- graphcore/testing/tests/test_case_and_runner.py +219 -0
- graphcore/testing/tests/test_settings_for_apps.py +50 -0
- graphcore/tests/__init__.py +0 -0
- graphcore/tests/ids.py +14 -0
- graphcore/tests/public_api_manifest.py +102 -0
- graphcore/tests/runs.py +7 -0
- graphcore/tests/test_app_discovery.py +90 -0
- graphcore/tests/test_composition_boundaries.py +231 -0
- graphcore/tests/test_docs_discovery.py +108 -0
- graphcore/tests/test_no_print.py +70 -0
- graphcore/tests/test_packaging.py +64 -0
- graphcore/tests/test_public_api_boundaries.py +229 -0
- graphcore/tests/test_public_api_contract.py +62 -0
- graphcore/tests/test_public_api_docs.py +28 -0
- graphcore/tests/test_runtime.py +42 -0
- graphcore/tests/test_shared_type_boundaries.py +128 -0
- graphcore/tests/test_shared_types.py +144 -0
- graphcore/tests/test_test_settings.py +45 -0
- graphcore/transport/__init__.py +0 -0
- graphcore/transport/agent_asgi.py +68 -0
- graphcore/transport/agent_client.py +85 -0
- graphcore/transport/channel_layer.py +68 -0
- graphcore/transport/consumers.py +507 -0
- graphcore/transport/routing.py +6 -0
- graphcore/transport/tests/__init__.py +0 -0
- graphcore/transport/tests/test_agent_client.py +31 -0
- graphcore/transport/tests/test_api_views.py +733 -0
- graphcore/transport/tests/test_channel_layer.py +96 -0
- graphcore/transport/tests/test_consumers.py +963 -0
- graphcore/transport/tests/test_resource_metadata.py +67 -0
- graphcore/transport/urls.py +29 -0
- graphcore/transport/views.py +358 -0
- graphcore/types/__init__.py +4 -0
- graphcore/types/access.py +114 -0
- graphcore/types/api.py +76 -0
- graphcore/types/entities.py +100 -0
- graphcore/types/entity_id.py +85 -0
- graphcore/types/execution.py +41 -0
- graphcore/types/identity.py +20 -0
- graphcore/types/onboarding.py +20 -0
- graphcore/types/query.py +116 -0
- graphcore/types/schedules.py +91 -0
- graphcore/types/strategy.py +73 -0
- graphcore/types/tests/__init__.py +0 -0
- graphcore/types/tests/test_entity_id.py +50 -0
- graphcore/urls.py +5 -0
- graphcore_kernel-0.1.0.dist-info/METADATA +94 -0
- graphcore_kernel-0.1.0.dist-info/RECORD +343 -0
- graphcore_kernel-0.1.0.dist-info/WHEEL +5 -0
- graphcore_kernel-0.1.0.dist-info/entry_points.txt +2 -0
- graphcore_kernel-0.1.0.dist-info/licenses/LICENSE +202 -0
- graphcore_kernel-0.1.0.dist-info/licenses/NOTICE +2 -0
- 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.
|