diff options
Diffstat (limited to 'docs/openapi.yaml')
| -rw-r--r-- | docs/openapi.yaml | 180 |
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] |