access: the users endpoints

/admin/users: list, add (one or several), remove, disable, grant and
revoke capabilities; each one change, refused if it would lock its
writer out. Capabilities as the store's paths name them.

Auth plan M1.

1 files changed, 180 insertions, 0 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 49e0042..5bf5a50 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -38,6 +38,12 @@ tags:
     description: |
       Replacing the swarm's document with a new epoch (compaction, replacement,
       import), and what happened to local writes that a remake couldn't place.
+  - name: Users
+    description: |
+      The swarm's users and what each may do (docs/access.md): reading needs `read` on
+      `_continuum/users`, changing `write` on it (in a swarm without a registry, being in
+      `protocol-writers`). A change that would keep its maker from managing users is
+      refused (`409`).
   - name: Debug
     description: Test hooks, only with `--debug-api`.
 
@@ -727,6 +733,152 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthorized'
 
+  /admin/users:
+    get:
+      tags: [Users]
+      summary: List the users
+      responses:
+        '200':
+          description: Whether the swarm has a registry, and every user's entry (docs/access.md) with its `name` and whether it may manage users (`manages`).
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  registry: { type: boolean }
+                  users:
+                    type: array
+                    items: { $ref: '#/components/schemas/User' }
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: May not read `_continuum/users`.
+    post:
+      tags: [Users]
+      summary: Add several users at once
+      description: |
+        By name, each with the capabilities `POST /admin/users/{name}` takes; none of
+        them may exist yet. How a swarm without a registry gets one: then the caller
+        must be among them, with `write` on `_continuum`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties:
+                type: object
+                properties:
+                  caps:
+                    type: array
+                    items: { $ref: '#/components/schemas/CapabilityRequest' }
+            example:
+              alice: { caps: [{ path: [], rights: [read, write] }, { path: [_continuum], rights: [read, write] }] }
+              bob: { caps: [{ path: [], rights: [read, write] }] }
+      responses:
+        '201': { description: Added. }
+        '400': { description: A name that isn't one, a capability that isn't one, or nobody. }
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403': { description: May not manage users. }
+        '409': { description: A user exists, or the caller wouldn't manage users in a new registry. }
+
+  /admin/users/{name}:
+    parameters:
+      - { name: name, in: path, required: true, schema: { type: string } }
+    get:
+      tags: [Users]
+      summary: One user
+      responses:
+        '200':
+          description: Its entry.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/User' }
+        '404': { description: No such user. }
+    post:
+      tags: [Users]
+      summary: Add a user
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                caps:
+                  type: array
+                  items: { $ref: '#/components/schemas/CapabilityRequest' }
+            example: { caps: [{ path: [servers, eu], rights: [read] }] }
+      responses:
+        '201': { description: Added. }
+        '400': { description: Not a user name, or a capability that isn't one. }
+        '403': { description: May not manage users. }
+        '409': { description: The user exists. }
+    delete:
+      tags: [Users]
+      summary: Remove a user
+      description: Disabling it (`PUT …/disabled`) keeps who wrote what readable, and is usually the better choice.
+      responses:
+        '204': { description: Removed. }
+        '403': { description: May not manage users. }
+        '404': { description: No such user. }
+        '409': { description: It would keep the caller from managing users. }
+
+  /admin/users/{name}/disabled:
+    parameters:
+      - { name: name, in: path, required: true, schema: { type: string } }
+    put:
+      tags: [Users]
+      summary: Disable or enable a user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { type: boolean }
+      responses:
+        '204': { description: Done. }
+        '403': { description: May not manage users. }
+        '404': { description: No such user. }
+        '409': { description: It would keep the caller from managing users. }
+
+  /admin/users/{name}/caps:
+    parameters:
+      - { name: name, in: path, required: true, schema: { type: string } }
+    post:
+      tags: [Users]
+      summary: Grant a capability
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/CapabilityRequest' }
+      responses:
+        '201':
+          description: Granted, under this ID.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id: { type: string }
+        '400': { description: A capability that isn't one. }
+        '403': { description: May not manage users. }
+        '404': { description: No such user. }
+
+  /admin/users/{name}/caps/{id}:
+    parameters:
+      - { name: name, in: path, required: true, schema: { type: string } }
+      - { name: id, in: path, required: true, schema: { type: string } }
+    delete:
+      tags: [Users]
+      summary: Revoke a capability
+      responses:
+        '204': { description: Revoked. }
+        '403': { description: May not manage users. }
+        '404': { description: No such capability. }
+        '409': { description: It would keep the caller from managing users. }
+
   /admin/dashboard:
     get:
       tags: [Admin]
@@ -1485,6 +1637,34 @@ components:
             $ref: '#/components/schemas/Error'
 
   schemas:
+    CapabilityRequest:
+      type: object
+      required: [path, rights]
+      properties:
+        path:
+          type: array
+          items: { type: string }
+          description: Segments, as the store's API takes them (`[]`, all of the swarm's data; `["_continuum"]`, protocol data).
+        rights:
+          type: array
+          items: { type: string, enum: [read, write] }
+    User:
+      type: object
+      properties:
+        name: { type: string }
+        since: { type: integer, description: Unix ms. }
+        by: { type: string, description: 'Who added it: `user:<name>`, or a node ID.' }
+        disabled: { type: boolean }
+        manages: { type: boolean, description: Whether it may manage users. }
+        caps:
+          type: object
+          additionalProperties:
+            type: object
+            properties:
+              path: { type: array, items: { type: string } }
+              rights: { type: array, items: { type: string } }
+              by: { type: string }
+              since: { type: integer }
     Error:
       type: object
       required: [error]