README.md

onetimesecret-api

A thin Javascript wrapper around the OneTimeSecret API.

OneTimeSecret is an open-source secret-sharing service that ensures that secrets can be shared securely and are only read once. The service can be accessed via the webpage, or via API. This project provides a thin Javascript wrapper for the API that makes it easy to use the service or a self-hosted server in any Javascript project. You can find the source code in the OneTimeSecret Github.

The module is published on NPM as onetimesecret-api.

Dependencies

• Node.js: 8 and 10+

Installation

yarn add onetimesecret-api

or

npm install onetimesecret-api

Usage

The API wrapper is implemented for asynchronous control flow using promises. For most calls the promise resolves into a Javascript object containing all attributes provided by the server. Configuration or server errors are thrown and have to be handled by the caller. Only the most important attributes of a call are documented here, please check out the API description for the full documentation.

In order to use the API the API class must be imported and setup to get a handler.

OneTimeSecretApi(<username>, <api_key>, [<options>])

• <username>: username specified during sign-up at the OneTimeSecret Service, or your server of choice (if defined in the <options>)
• <password>: Password or API key created for your account
• <options>: additional api options
  • <url>: server url of a custom server
  • <apiVersion>: API version to use (currently only "v1"). ApiVersion provides a list of supported API versions
• Returns instance of the API
• Throws InputError if <username> or <password> is missing

Example:

import {OneTimeSecretApi} from "onetimesecret-api";

const ots = new OneTimeSecretApi("tom@example.com", "04821d62");

or

import {OneTimeSecretApi} from "onetimesecret-api";

const ots = new OneTimeSecretApi(
    "tom@example.com",
    "04821d62",
    { url: "https://www.my-ots-server.com", apiVersion: "v1" });

or

import {InputError, OneTimeSecretApi} from "onetimesecret-api";

try {
    const ots = new OneTimeSecretApi();
} catch(error) {
    if (error instanceof InputError) {
        console.error("Username or password missing");
    } else {
        console.error(`Unknown error: ${error}`);
    }
}

Status

Request the server status as boolean.

status() -> boolean

• Returns boolean state of server
• Throws
  • InternalServerError: unspecified internal server error
  • NotAuthorizedError: invalid username or password
  • RateLimitedError: account has been rate limited due to many requests
  • TimeoutError: request timeout

Example:

ots.status()
.then((status) => {
    console.log(`Status: ${status}`);
})
.catch((error) => {
    console.error(`Error: ${error}`);
});

Share

Encrypt and share a secret.

share(<secret>, [<options>]) -> object

• <secret>: the secret to share (depending on your account type 1k to 10k length)
• <options>: additional api options of type ApiOptionsShare
  • <passphrase>: passphrase that will be required to read the secret
  • <ttl>: time in seconds after which the secret will be automatically be deleted ("burned")
  • <recipient>: email address of the person the secret should be sent to by the server
• Returns a promise that provides an ApiResponseShare object. The returned object contains all of the metadata of the newly created secret. Important values:
  • secret_key: the secret key that is used to share the secret
  • share_link: the share link of the secret that is supposed to be be shared
  • metadata_key: key used to manage the secret; this key must remain private
• Throws
  • InputError: no secret provided
  • InternalServerError: unspecified internal server error
  • NetworkError: network request failed
  • NotFoundError: the call isn't supported by the server
  • NotAuthorizedError: invalid username or password
  • RateLimitedError: account has been rate limited due to many requests
  • TimeoutError: request timeout

Examples:

ots.share('My very special secret')
.then((response) => {
    console.log(`Secret key: ${response.secret_key}`);
})
catch((error) => {
    console.error(`Error: ${error}`);
});

or

ots.share('My very special secret', { ttl: 3600 })
.then((response) => {
    console.log(`Secret key: ${response.secret_key}`);
})
.catch((error) => {
    console.error(`Error: ${error}`);
});

Generate

Generate a short, encrypted secret and share it.

generate([<options>]) -> object

• <options>: additional api options of type ApiOptionsGenerate
  • <passphrase>: passphrase that will be required to read the secret
  • <ttl>: time in seconds after which the secret will be automatically be deleted ("burned")
  • <recipient>: email address of the person the secret should be sent to by the server
• Returns a promise that provides an ApiResponseGenerate object. The returned object contains all of the metadata of the newly created secret. Important values:
  • secret_key: the secret key that is used to share the secret
  • share_link: the share link of the secret that is supposed to be be shared
  • metadata_key: key used to manage the secret; this key must remain private
• Throws
  • InternalServerError: unspecified internal server error
  • NetworkError: network request failed
  • NotFoundError: the call isn't supported by the server
  • NotAuthorizedError: invalid username or password
  • RateLimitedError: account has been rate limited due to many requests
  • TimeoutError: request timeout

Example:

ots.generate()
.then((response) => {
    console.log(`Secret key: ${response.secret_key}`);
})
.catch((error) => {
    console.error(`Error: ${error}`);
});

Retrieve secret

Retrieve a secret from the server. This call is used to get a secret someone else shared with you. If the secret was shared with a passphrase it has to be provided to the call in the options.

retrieveSecret(secret_key, [<options>]) -> object

• <secret_key>: secret key that was shared with you
• <options>: additional api options of type ApiOptionsRetrieveSecret
  • <passphrase>: passphrase that will be required to read the secret
• Returns a promise that provides an ApiResponseRetrieveSecret object. The returned object contains all the information of the secret you can access. Important values:
  • value: the secret shared with you
• Throws
  • InputError: no secret key provided
  • InternalServerError: unspecified internal server error
  • NetworkError: network request failed
  • NotFoundError: the call isn't supported by the server
  • NotAuthorizedError: invalid username or password
  • RateLimitedError: account has been rate limited due to many requests
  • TimeoutError: request timeout
  • UnknownSecretError: secret key not found

Example:

ots.retrieveSecret('hbo11uxhmg2gze0mlcmyf4x0qahawqa')
.then((response) => {
    console.log(`Secret value: ${response.value}`);
})
.catch((error) => {
    console.error(`Error: ${error}`);
});

Retrieve metadata

Retrieve metadata for a secret you created.

retrieveMetadata(metadata_key) -> object

• <metadata_key>: metadata key that was shared with you
• Returns a promise that provides an ApiResponseRetrieveMetadata object. The returned object contains all of the metadata of the newly created secret. Important values:
  • secret_key: the secret key that is used to share the secret
  • share_link: the share link of the secret that is supposed to be be shared
  • status: status of the secret, e.g. "new", "received", "burned", "viewed", ...
• Throws
  • InputError: no metadata key provided
  • InternalServerError: unspecified internal server error
  • NetworkError: network request failed
  • NotFoundError: the call isn't supported by the server
  • NotAuthorizedError: invalid username or password
  • RateLimitedError: account has been rate limited due to many requests
  • TimeoutError: request timeout
  • UnknownSecretError: metadata key not found

Example:

ots.retrieveMetadata('hbo11uxhmg2gze0mlcmyf4x0qahawqa')
.then((response) => {
    console.log(`Status: ${response.status}`);
})
.catch((error) => {
    console.error(`Error: ${error}`);
});

Burn secret

Destroy a secret you created.

burn(metadata_key) -> object

• <metadata_key>: metadata key that was shared with you
• Returns a promise that provides an ApiResponseBurn object. The returned object contains all of the metadata of the newly created secret. Important values:
  • secret_key: the secret key that is used to share the secret
  • status: status of the secret set to "burned"
• Throws
  • InputError: no metadata key provided
  • InternalServerError: unspecified internal server error
  • NetworkError: network request failed
  • NotFoundError: the call isn't supported by the server
  • NotAuthorizedError: invalid username or password
  • RateLimitedError: account has been rate limited due to many requests
  • TimeoutError: request timeout
  • UnknownSecretError: metadata key not found

Example:

ots.burn('raldp8yshsh42hyse')
.then((response) => {
    console.log(`Status: ${response.status}`);
})
.catch((error) => {
    console.error(`Error: ${error}`);
});

Retrieve recent secrets

Retrieve all recently created secrets and most of its metadata.

recentMetadata() -> Array[object]

• Returns a promise that provides an ApiResponseRecentMetadata object. The returned object contains a list if objects where each object represents a secret. It has a subset of attributes as described for retrieve_metadata.
• Throws
  • InternalServerError: unspecified internal server error
  • NetworkError: network request failed
  • NotFoundError: the call isn't supported by the server
  • NotAuthorizedError: invalid username or password
  • RateLimitedError: account has been rate limited due to many requests
  • TimeoutError: request timeout

Example:

ots.recentMetadata()
.then((response) => {
    console.log(`Secret 0 state: ${response[0].state}`);
})
.catch((error) => {
    console.error(`Error: ${error}`);
});

Release

1. Update and commit changes
2. Compile Javascript files: yarn build
3. Commit Javascript files
4. Publish to npm: yarn publish or npm publish