The Databox Docker container that manages the flow of data by minting tokens and controlling store discovery. This code is not meant to be run on its own except for debug purposes. The live version is automatically pulled from https://databox.amar.io (see registry catalogue) as "databox-arbiter" and launched by the container manager.
If you are a Databox app or driver developer, skip to the relevant API documentation.
Further background info for Databox system devs here (NB: Outdated).
For debug purposes:
git clone https://github.com/me-box/databox-arbiter.git
cd databox-arbiter
npm install
This code should not be run as a standalone app, but rather in a Databox context. Unit tests to make sure it will work in that context can be run with:
npm test
Default port is 8080 (HTTPS only), but in case of lack of privileges, can be overridden using the PORT environment variable, i.e.:
PORT=8081 npm start
All request bodies should be application/json.
(for Databox developers)
Method: GET
An endpoint required by the CM to signify if a container needs configuration. Can respond with (active|standby).
- 200: active
Method: POST
Upserts the record of containers and the extent of their corresponding permissions (default none) maintained by the arbiter.
NB: CM arbiter key MUST be provided as per section 7.1 of the Hypercat 3.0 specs. The arbiter will not accept requests that don't include a key that matches that passed to it in the CM_KEY environment variable on launch.
- name: Container name (required every time)
- type: Container type (driver|store|app)
- key: Container arbiter key
- 200: [JSON-formatted updated container record]
- 401:
- Missing API key (see description above)
- Unauthorized: Arbiter key invalid
Method: POST
Deletes a containers record by name.
NB: CM arbiter key MUST be provided as per section 7.1 of the Hypercat 3.0 specs. The arbiter will not accept requests that don't include a key that matches that passed to it in the CM_KEY environment variable on launch.
- name: Container name
- 200
- 401:
- Missing API key (see description above)
- Unauthorized: Arbiter key invalid
- 400: Missing parameters
Method: POST
Adds permissions to the record of containers maintained by the arbiter for a particular route.
Routes are encoded into tokens (as macaroon caveats). Routes are made up of a target container, an API path, and an HTTP method. The arbiter is indifferent to methods, but for the majority of APIs, GET requests map to read operations, and POST requests map to write operations.
Paths are JSON-formatted whitelists of accessible endpoints formatted as defined here and are testable here. More information here. The arbiter will mint tokens to paths (exact or RegExp) that match granted path permissions following those RegExp rules.
NB: CM arbiter key MUST be provided as per section 7.1 of the Hypercat 3.0 specs. The arbiter will not accept requests that don't include a key that matches that passed to it in the CM_KEY environment variable on launch.
- name: Container name
- route:
- target: Target container hostname
- path: API path
- method: HTTP method
- caveats: String array of route-specific caveats (all optional, see here for explanations).
- 200: [JSON array of route caveats after modification]
- 401:
- Missing API key (see description above)
- Unauthorized: Arbiter key invalid
- 400: Missing parameters
Method: POST
Does the opposite of /cm/grant-container-permissions. If the specified path is a RegExp path, then all matches will be revoked, so use wildcards carefully.
NB: CM arbiter key MUST be provided as per section 7.1 of the Hypercat 3.0 specs. The arbiter will not accept requests that don't include a key that matches that passed to it in the CM_KEY environment variable on launch.
- name: Container name
- route:
- target: Target container hostname
- path: API path
- method: HTTP method
- caveats: String array of route-specific caveats to delete. If none specified, all permissions for this route are completely revoked.
- 200:
- [JSON array of route caveats after modification]
- null (if all permissions are revoked)
- 401:
- Missing API key (see description above)
- Unauthorized: Arbiter key invalid
- 400: Missing parameters
(for Databox developers)
Method: GET
Registers a store allowing the arbiter to mint macaroons for the store, and for the store to verify these macaroons independently.
NB: Container arbiter key (see developer guide) MUST be provided as per section 7.1 of the Hypercat 3.0 specs. Containers without proper authorization will not be able to discover certain items, or will be able to discover them but not access them. In the latter case, they are informed as per section 7.3.1.2 of the Hypercat 3.0 specs.
- 200: [Base64-encoded secret for verifying container macaroons]
- 401: Missing API key (see description above)
- 401: Invalid API key (see description above)
- 500: Container type unknown by arbiter
- 403: Container type [type] cannot use arbiter token minting capabilities as it is not a store type
- 500: Unable to register container (secret generation)
(For Databox app and/or driver developers)
Method: GET
Serves a top-level Hypercat catalogue.
NB: Container arbiter key (see developer guide) MUST be provided as per section 7.1 of the Hypercat 3.0 specs. Containers without proper authorization will not be able to discover certain items, or will be able to discover them but not access them. In the latter case, they are informed as per section 7.3.1.2 of the Hypercat 3.0 specs.
- 200: [JSON-encoded Hypercat catalogue]
- 401: Missing API key (see description above)
Method: POST
Provides store tokens for containers.
NB: Container arbiter key (see developer guide) MUST be provided as per section 7.1 of the Hypercat 3.0 specs. Containers without proper authorization will not be able to discover certain items, or will be able to discover them but not access them. In the latter case, they are informed as per section 7.3.1.2 of the Hypercat 3.0 specs.
- target: The unique hostname of the target container that will verify the provided macaroon
- path: API path for which the token should be minted for
- method: HTTP method for which the token should be minted for
- 200: [Serialzed macaroon]
- 401:
- Missing API key (see description above)
- Invalid API key
- Insufficient route permissions
- 400:
- Missing parameters
- Target [target] has not been approved for arbitering
- Target [target] has not registered itself for arbitering