databoxsystems2/arbiter repository overview

⁠Databox Arbiter

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.

If you are a Databox app or driver developer, skip to the relevant API documentation⁠.

Further background info for Databox platform here⁠.

For debug purposes:

⁠Installation

git clone https://github.com/tsh2/core-arbiter.git
cd core-arbiter
npm install

⁠Usage

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

⁠API Endpoints

All request bodies should be application/json.

⁠CM-facing

(for Databox core-component developers)

⁠/status

⁠Description

Method: GET

An endpoint required by the CM to signify if a container needs configuration. Can respond with (active|standby).

⁠Response

• 200: active

⁠/cm/upsert-container-info

⁠Description

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 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.

⁠Parameters

• name: Container name (required every time)
• type: Container type (driver|store|app)
• key: Container arbiter key

⁠Response

⁠Success

• 200: [JSON-formatted updated container record]

⁠Error

• 401:
  • Missing API key (see description above)
  • Unauthorized: Arbiter key invalid

⁠/cm/delete-container-info

⁠Description

Method: POST

Deletes a containers record by name.

NB: CM arbiter key MUST be provided as per 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.

⁠Parameters

• name: Container name

⁠Response

⁠Success

• 200

⁠Error

• 401:
  • Missing API key (see description above)
  • Unauthorized: Arbiter key invalid
• 400: Missing parameters

⁠/cm/grant-container-permissions

⁠Description

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 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.

⁠Parameters

• 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).

⁠Response

⁠Success

• 200: [JSON array of route caveats after modification]

⁠Error

• 401:
  • Missing API key (see description above)
  • Unauthorized: Arbiter key invalid
• 400: Missing parameters

⁠/cm/revoke-container-permissions

⁠Description

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 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.

⁠Parameters

• 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.

⁠Response

⁠Success

• 200:
  • [JSON array of route caveats after modification]
  • null (if all permissions are revoked)

⁠Error

• 401:
  • Missing API key (see description above)
  • Unauthorized: Arbiter key invalid
• 400: Missing parameters

⁠Store-facing

(for Databox developers)

⁠/store/secret

⁠Description

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 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⁠.

⁠Parameters

⁠Response

⁠Success

• 200: [Alphanumeric secret for verifying container macaroons]

⁠Error

• 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

⁠Container-facing

(For Databox app and/or driver developers)

⁠/cat

⁠Description

Method: GET

Serves a top-level Hypercat⁠ catalogue.

NB: Container arbiter key (see developer guide) MUST be provided as per 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 the Hypercat 3.0 specs⁠.

⁠Response

⁠Success

• 200: [JSON-encoded Hypercat catalogue]

⁠Error

• 401: Missing API key (see description above)

⁠/token

⁠Description

Method: POST

Provides store tokens for containers.

NB: Container arbiter key (see developer guide) MUST be provided as per 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⁠.

⁠Parameters

• 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

⁠Response

⁠Success

• 200: [Serialzed macaroon]

⁠Error

• 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