JavaScript SDK
Installation
Our JavaScript SDK is distributed via npm and can be installed using your favorite package manager.
npm install @capeprivacy/cape-sdk
If you are using yarn:
yarn add @capeprivacy/cape-sdk
Or if you are using pnpm:
pnpm add @capeprivacy/cape-sdk
Import the SDK
There are three ways to import the Cape SDK into your project.
ES module style: Use the
import
statement (recommended):import { Cape } from "@capeprivacy/cape-sdk";
CommonJS style: Use the
const
statement:const { Cape } = require("@capeprivacy/cape-sdk");
Script tag: Use the
script
tag in an HTML document:<script type="module">
import { Cape } from "https://cdn.skypack.dev/@capeprivacy/cape-sdk";
</script>
Initialization
The Cape SDK exposes a single class Cape
which is used to initialize the SDK. The Cape
constructor can be initialized with the following object:
Property | Type | Description |
---|---|---|
authToken | string | undefined | Your account auth token which can be used to call any function. If a functionToken is not provided, the authToken is required. |
functionToken | string | undefined | The function token used to call a single Cape function. This token is generated via the Cape CLI. |
checkDate | Date | undefined | Enable a specific date to check the certificate against. |
verbose | boolean | undefined | Whether or not to log Cape SDK logs to the console. |
Example Usage
const cape = new Cape({ functionToken: "YOUR_FUNCTION_TOKEN" });
cape.run
cape.run
is used to run a function one time. It will open an enclave, send the data to the enclave, and then return the result. This method is useful if you do not need to manage the lifecycle of the enclave yourself. cape.run
takes a single Object
as an argument with the following properties:
async cape.run(config: Object): Promise<string>
Parameter | Type | Description |
---|---|---|
config | Object | The configuration object to run the function. |
Property | Type | Description |
---|---|---|
id | string | The ID of the function to run. |
data | string | string[] | number | number[] | Buffer | ArrayBuffer | Uint8Array | Uint16Array | Uint32Array | Record<string, unknown> | Record<string, unknown>[] | The data to send to the enclave. |
Example Usage
import { Cape } from "@capeprivacy/cape-sdk";
const cape = new Cape({ functionToken: "YOUR_FUNCTION_TOKEN" });
try {
const result = await cape.run({
id: "YOUR_FUNCTION_ID",
data: "YOUR_DATA",
});
console.log(result);
} catch (error) {
console.error("Unexpected error occurred:", error);
}
cape.connect
cape.connect
is used to set up the connection to an enclave. This method will open a connection with an enclave and remains open until cape.disconnect
is called. This method isn't meant to be used by itself, but instead to be used in conjunction with cape.invoke
and cape.disconnect
to give you fine-grained control over the lifecycle of the enclave.
Please note that there is a 60-second inactivity timeout on the enclave connection. You may need to monitor the connection status and reconnect if there is a significant wait between inputs.
interface ConnectArgs {
id: string
}
async cape.connect(config: Object): Promise<void>
Parameter | Type | Description |
---|---|---|
config | Object | The configuration object to connect to the enclave. |
Property | Type | Description |
---|---|---|
id | string | The ID of the function to run. |
cape.invoke
cape.invoke
invokes the function within the enclave. This method differs from cape.run
as it does not open a new enclave, but instead uses the enclave that was opened by cape.connect
. This method is useful if you need to call a function multiple times and want to avoid the overhead of opening a new enclave each time.
async cape.invoke(config: Object): Promise<string>
Parameter | Type | Description |
---|---|---|
config | Object | The configuration object to invoke a function in the enclave. |
Property | Type | Description |
---|---|---|
data | string | string[] | number | number[] | Buffer | ArrayBuffer | Uint8Array | Uint16Array | Uint32Array | Record<string, unknown> | Record<string, unknown>[] | The data to send to the enclave. |
Example Usage
import { Cape } from "@capeprivacy/cape-sdk";
const cape = new Cape({ functionToken: "YOUR_FUNCTION_TOKEN" });
try {
await cape.connect({ id: "YOUR_FUNCTION_ID" });
const results = await Promise.all([
cape.invoke({ data: "YOUR_DATA_1" }),
cape.invoke({ data: "YOUR_DATA_2" }),
cape.invoke({ data: "YOUR_DATA_3" }),
]);
console.log(results);
} catch (error) {
console.error("Unexpected error occurred:", error);
} finally {
cape.disconnect();
}
cape.encrypt
cape.encrypt
encrypts user-provided data in string format for use exclusively inside the enclave. The input is first AES encrypted and then RSA encrypted with the retrieved publickey provided through the attestation process. Only the key retrival process require connecting to an enclave.
import { Cape } from "@capeprivacy/cape-sdk";
const cape = new Cape({ functionToken: "YOUR_FUNCTION_TOKEN" });
async cape.encrypt(input: string): Promise<string>
Parameter | Type | Description |
---|---|---|
config | Object | The configuration object to invoke a function in the enclave. |
Property | Type | Description |
---|---|---|
input | string | User provided input to be encrypted for running in an enclave. |
cape.disconnect
cape.disconnect
disconnects the connection with the enclave. This method must be called when manually managing the lifecycle of the enclave.
cape.disconnect(): void