diff options
Diffstat (limited to 'docs/access.md')
| -rw-r--r-- | docs/access.md | 53 |
1 files changed, 38 insertions, 15 deletions
diff --git a/docs/access.md b/docs/access.md index 519113c..db86e21 100644 --- a/docs/access.md +++ b/docs/access.md @@ -36,8 +36,8 @@ A swarm gets a registry from its start if its genesis node is given its first us `--bootstrap-users`: it records them, with the swarm ID, in its first change, each with everything (`[]` and `["_continuum"]`). Other users, of its `--htpasswd` or any node's, may do nothing until added (the genesis node warns of those of its `--htpasswd`). -Without it, the swarm has no registry, and is as swarms were before: users all alike -(An existing swarm, below), until someone gives it one. `--protocol-writers` counts in +Without it, the swarm has no registry: its users are all alike (A swarm without a +registry, below), until someone gives it one. `--protocol-writers` counts in both: without a registry, as who may write protocol data; with one, to set it right should nobody be left who may manage users (Keeping the swarm manageable, below). @@ -73,24 +73,47 @@ A user the node lets in but the registry doesn't have may do nothing (`403`). whole swarm (its members, its remakes, its users), so it is given apart, never by accident with the data. A user who may do both has both. -## An existing swarm +## Managing users -A swarm whose document has no registry (one from before it, `_continuum/users` -missing) goes on as before: every user a node lets in may read and write the swarm's -data and use the admin endpoints, and only those in `--protocol-writers` write -protocol data. It gets a registry once a protocol writer writes one, through the store: +Through `/admin/users` ([`openapi.yaml`](openapi.yaml), Users): looking needs `read` on +`_continuum/users`, changing `write` on it. Each change is one change to the document, +logged and named by who made it. `POST /admin/users` adds several at once (below). ```sh -curl -u alice --request PUT --header 'Content-Type: application/json' \ - --data '{"since": 0, "by": "user:alice", "disabled": false, - "caps": {"1": {"path": [], "rights": ["read", "write"]}, - "2": {"path": ["_continuum"], "rights": ["read", "write"]}}}' \ - http://localhost:3000/store/_continuum/users/alice +curl -u alice http://localhost:3000/admin/users # who, and what each may do +curl -u alice -X POST -H 'Content-Type: application/json' \ + --data '{"caps": [{"path": ["servers", "eu"], "rights": ["read"]}]}' \ + http://localhost:3000/admin/users/bob # add bob, reading servers/eu +curl -u alice -X POST -H 'Content-Type: application/json' \ + --data '{"path": [], "rights": ["read", "write"]}' \ + http://localhost:3000/admin/users/bob/caps # grant: answers its ID +curl -u alice -X DELETE http://localhost:3000/admin/users/bob/caps/ID # revoke it +curl -u alice -X PUT -H 'Content-Type: application/json' --data true \ + http://localhost:3000/admin/users/bob/disabled # disable bob ``` -From that write on, every node serves only the users the registry has, so the first -entry must be the writer's own, with `["_continuum"]` (a first write that isn't is -refused, `409`); add the other users the same way. +Disabling a user keeps who wrote what readable; removing it (`DELETE`) doesn't. The +registry is protocol data in the store too, so a user who may write `_continuum/users` +may also edit its entries there directly; the same checks apply. + +## A swarm without a registry + +In a swarm whose document has no registry (`_continuum/users`), started without +`--bootstrap-users`, every user a node lets in may read and write the swarm's data and +use the admin endpoints, and only those in `--protocol-writers` write protocol data. It +gets a registry once a protocol writer adds its users: + +```sh +curl -u alice -X POST -H 'Content-Type: application/json' --data '{ + "alice": {"caps": [{"path": [], "rights": ["read", "write"]}, + {"path": ["_continuum"], "rights": ["read", "write"]}]}, + "bob": {"caps": [{"path": [], "rights": ["read", "write"]}]} + }' http://localhost:3000/admin/users +``` + +From that change on, every node serves only the users the registry has, so the caller +must be among them, with `write` on `_continuum` (else `409`): list every node's users +first. ## Keeping the swarm manageable |