storj/satellite/console/wasm/README.md
Yingrong Zhao 2ce3170bb4 satellite/console/wasm: expose method to add caveats in the browser
This PR does the following three things:
    1. Defines a high-level interface for this wasm package
        - All return value from this package will be wrapped with an
          result object that contains a value field and an error field
    2. Exposes two new functions to allow users to add permissions for a
       given API key
        - newPermission()
        - setAPIKeyPermission()
    3. Adds API documentation for the newly added API functions

Change-Id: Id995189702b369bba18fa344bef4ddfb0f3f1f44
2020-11-10 20:10:53 +00:00

182 lines
5.2 KiB
Markdown

# Using WebAssembly in Storj
In order to use the uplink library from the browser, we can compile the uplink library to WebAssembly (wasm).
### Setup
To generate wasm code that can create access grants in the web browser, run the following from the storj/wasm directory:
```
$ GOOS=js GOARCH=wasm go build -o access.wasm access.go
```
The `access.wasm` code can then be loaded into the browser in a script tag in an html page. Also needed is a JavaScript support file which ships with golang.
To copy the JavaScript support file, run:
```
$ cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" .
```
Ref: [Golang WebAssembly docs](https://github.com/golang/go/wiki/WebAssembly)
The HTML file should include the following:
```
<script type="text/javascript" src="/path/to/wasm_exec.js"></script>
<script>
const go = new Go();
WebAssembly.instantiateStreaming(
fetch("/path/to/access.wasm"), go.importObject).then(
(result) => {
go.run(result.instance);
});
</script>
```
Additionally, the HTTP `Content-Security-Policy (CSP) script-src` directive will need to be modified to allow wasm code to be executed.
See: [WebAssembly Content Security Policy docs](https://github.com/WebAssembly/content-security-policy/blob/master/proposals/CSP.md)
### Usage
#### function newPermission
```js
function newPermission()
```
- **Returns:**
```js
{
value: {
AllowDownload: false,
AllowUpload: false,
AllowDelete: false,
AllowList: false,
NotBefore: "0001-01-01T00:00:00Z",
NotAfter: "0001-01-01T00:00:00Z",
},
error: ""
}
```
- **Usage:**
newPermission creates a new Permission object with all available permission settings set to default value.
- **Example:**
```js
var permission = newPermission().value;
permission.AllowedDownload = true;
```
### function setAPIKeyPermission
```js
function setAPIKeyPermission(apiKey, buckets, permission)
```
- **Arguments**
Accepts three arguments: `apiKey`, `buckets` and `permission`
- **apiKey**
- **Type:** `String`
- **Details:**
This parameter is required
- **buckets**
- **Type:** `Array`
- **Details:**
An array of bucket names that restrict the api key to only contain enough information to allow access to just those buckets.
If no bucket names are provided, meaning an empty array, then all buckets are allowed.
This parameter is required.
- **permission**
- **Type:** `Object`
- **Details:**
An object that defines what actions can be used for a given api key.
It should be constructed by calling `newPermission`
See also: https://github.com/storj/uplink/blob/b8e0f0a90665143a8ce975d92530737130874f5a/access.go#L46
This parameter is required.
- **Returns**
```js
{
value: "restricted-api-key",
error: ""
}
```
- if an error message is returned, `value` will be set to an empty string.
- **Usage**
Creates a new api key with specific permissions.
- **Example**
```js
var apiKey = "super-secret-key";
var buckets = ["test-bucket"];
var permission = newPermission().value
permission.allowUpload = true
var restrictedAPIKey = setAPIKeyPermission(apiKey, buckets, permission)
```
### function generateAccessGrant
```js
function generateAccessGrant(satelliteNodeURL, apiKey, encryptionPassphrase, projectID)
```
- **Arguments**
Accepts four arguments: `satelliteNodeURL`, `apiKey`, `encryptionPassphrase` and `projectID`
- **satelliteNodeURL**
- **Type:** `String`
- **Details:**
A string that contains satellite node id and satellite address.
Example: 12tDhBcuMevundiuZPQJd613iW5vCdFtkRDBjBEfjdVtv1hbfCL@127.0.0.1:10000
This parameter is required
- **apiKey**
- **Type:** `String`
- **Details:**
This parameter is required
- **encryptionPassphrase**
- **Type:** `String`
- **Details:**
A string that's used for encryption.
This parameter is required.
- **projectID**
- **Type:** `String`
- **Details:**
A project-based salt for determinitic key derivation.
Currently it's referring to a project ID. However, it might change in the future to have more randomness.
This parameter is required.
- **Returns**
```js
{
value: "access-grant",
error: ""
}
```
- if an error message is returned, `value` will be set to an empty string.
- **Usage**
Creates a new api key with specific permissions.
- **Example**
```js
var satelliteNodeURL = "12tDhBcuMevundiuZPQJd613iW5vCdFtkRDBjBEfjdVtv1hbfCL@127.0.0.1:10000"
var apiKey = "super-secret-key";
var passphrase = "123";
var projectID = "project-id"
var result = generateAccessGrant(satelliteNodeURL, apiKey, passphrase, projectID);
if (result.err != "") {
// something went wrong
}
var access = result.value
```