Skip to content

Commit

Permalink
Merge pull request #41 from contentauth/edit-docs
Browse files Browse the repository at this point in the history
README and docs edit and cleanup
  • Loading branch information
crandmck authored Nov 16, 2023
2 parents 05f2c50 + 42baf19 commit b7518ec
Show file tree
Hide file tree
Showing 37 changed files with 443 additions and 741 deletions.
124 changes: 78 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,45 +1,78 @@
# c2pa-node
# C2PA Node.js

**c2pa-node:** Node.js bindings for C2PA
The [c2pa-node](https://github.com/contentauth/c2pa-node) repository implements a Node.js API that can:
- Read and validate C2PA data from media files in [supported formats](https://opensource.contentauthenticity.org/docs/rust-sdk/#supported-file-formats).
- Add signed manifests to media files in [supported formats](https://opensource.contentauthenticity.org/docs/rust-sdk/#supported-file-formats).

## Installing c2pa-node
**WARNING**: This is an early prerelease version of this library. There may be bugs and unimplemented features, and the API is subject to change.

Installing c2pa-node requires a [supported version of Node and Rust](https://github.com/neon-bindings/neon#platform-support).
[nvm](https://github.com/nvm-sh/nvm) is a good tool for managing multiple versions of Node on your machine, and you can install
Rust by [visiting this link](https://www.rust-lang.org/tools/install).
<div style={{display: 'none'}}>

### Installing for usage in a client app
Contents:

- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Installing for use in a client app](#installing-for-use-in-a-client-app)
- [Building custom binaries](#building-custom-binaries)
- [Installing for project contributions](#installing-for-project-contributions)
- [Testing](#testing)
- [Usage](#usage)
- [Creating a c2pa object](#creating-a-c2pa-object)
- [Reading a manifest](#reading-a-manifest)
- [Creating a manifest](#creating-a-manifest)
- [Adding an ingredient](#adding-an-ingredient)
- [Signing a manifest](#signing-a-manifest)
- [API documentation](#api-documentation)

</div>

## Installation

### Prerequisites

You must install:
- A [supported version of Node](https://github.com/neon-bindings/neon#platform-support).
- [Rust](https://www.rust-lang.org/tools/install)

If you need to manage multiple versions of Node on your machine, use a tool such as [nvm](https://github.com/nvm-sh/nvm).

### Installing for use in a client app

Using npm:

```sh
# npm
$ npm install c2pa-node
# yarn
```

Using Yarn:

```sh
$ yarn add c2pa-node
# pnpm
```

Using pnpm:

```sh
$ pnpm add c2pa-node
```

This will pull down the latest Rust SDK and build it as a binding locally, hence the need for Rust to be locally installed.
This command downloads the latest Rust SDK and builds it as a binding locally (which is why Rust must be locally installed).

**Note:** We will be working on creating binary releases so that you will not need Rust installed on your machine in the future.
**Note**: In the future, CAI may create binary releases so you won't need to install Rust on your machine.

#### Building custom binaries
### Building custom binaries

You may need to build custom binaries for platforms or architectures that do not have Rust tooling installed. You can
prebuild a binary on the platform or architecture you would like to run on. To do this, you can run the following
on the system or VM you want to build the binary for (this needs to have the [Rust toolchain installed](https://www.rust-lang.org/tools/install)):
For platforms or architectures that do not have Rust tooling installed, you may need to build custom binaries. To pre-build a binary, [install the Rust toolchain](https://www.rust-lang.org/tools/install) and then run the following commands on the target system or VM:

```sh
# in c2pa-node
$ cd c2pa-node
$ pnpm install
$ pnpm build:rust
```

Then, you can copy the binary to a place that is accessible by your application (in this example, it is `/path/to/my/application/resources`) and set the path to the `c2pa.node` module via the `C2PA_LIBRARY_PATH` environment variable:
Then, you can copy the binary to a place that is accessible by your application (in this example, it is `/path/to/my/application/resources`) and set the path to the `c2pa.node` module via the `C2PA_LIBRARY_PATH` environment variable. Enter these commands:

```sh
# in your application using c2pa-node
$ cd /path/to/my/application
$ mkdir resources
$ cp /path/to/c2pa-node/generated/c2pa.node resources/c2pa.node
Expand All @@ -48,11 +81,11 @@ $ npm install c2pa-node
$ npm start
```

**Important:** `C2PA_LIBRARY_PATH` _must_ be set while both **installing** or **adding** c2pa-node to your app to avoid building the Rust code. It is _also_ required to be set while **running** your app so that it loads the bindings from the correct location.
**Important:** `C2PA_LIBRARY_PATH` _must_ be set while both **installing** or **adding** c2pa-node to your app to avoid building the Rust code. It must _also_ be set while **running** your app so that it loads the bindings from the correct location.

### Installing for development / contributions
### Installing for project contributions

You can install the project with npm. In the project directory, run:
If you want to contribute to this project, install the project with npm. In the project directory, enter these commands:

```sh
# Switch to the supported version of Node.js for building
Expand All @@ -65,11 +98,19 @@ $ pnpm install
$ pnpm run build
```

## Quick start
### Testing

After installation, run the test suite by entering this command:

### Creating a `c2pa` object
```sh
$ pnpm test
```

You will need to instantiate a `c2pa` object by using [`createC2pa()`](docs/modules.md#createc2pa):
## Usage

### Creating a c2pa object

Instantiate a `c2pa` object by using [`createC2pa()`](https://github.com/contentauth/c2pa-node/blob/main/docs/README.md#createc2pa):

```ts
import { createC2pa } from 'c2pa-node';
Expand All @@ -79,7 +120,7 @@ const c2pa = createC2pa();

### Reading a manifest

You can read a manifest by using the `c2pa.read()` function:
Use the `c2pa.read()` function to read a manifest; for example:

```ts
import { createC2pa } from 'c2pa-node';
Expand All @@ -104,7 +145,7 @@ read('my-c2pa-file.jpg', 'image/jpeg');

### Creating a manifest

To create a manifest, you can pass in the claim information to a [`ManifestBuilder`](docs/classes//ManifestBuilder.md).
To create a manifest, pass the claim information to the [`ManifestBuilder`](https://github.com/contentauth/c2pa-node/blob/main/docs/classes/ManifestBuilder.md) object constructor; for example:

```ts
import { ManifestBuilder } from 'c2pa-node';
Expand Down Expand Up @@ -137,16 +178,15 @@ const manifest = new ManifestBuilder({

### Adding an ingredient

You can use `c2pa.createIngredient()` to load ingredient data for inclusion into a manifest. This can be stored on a backend
if necessary and loaded in at signing time without the need for the original ingredient if it is no longer available.
Use `c2pa.createIngredient()` to load ingredient data for inclusion into a manifest. You can store the ingredient data on the backend and load it at signing time if necessary (for example if the original ingredient is no longer available); for example:

```ts
// Create the ingredient asset from a buffer
const ingredientAssetFromBuffer = {
buffer: await readFile('my-ingredient.jpg'),
mimeType: 'image/jpeg',
};
// or from a file
// Or load from a file
const ingredientAssetFromFile = {
path: resolve('my-ingredient.jpg'),
};
Expand All @@ -162,15 +202,13 @@ manifest.addIngredient(ingredient);

### Signing a manifest

You can use the `c2pa.sign()` method to sign an ingredient, either locally if you have a signing certificate and key
available, or by using a remote signing API.
Use the `c2pa.sign()` method to sign an ingredient, either locally if you have a signing certificate and key available, or by using a remote signing API.

#### Signing buffers

If you have file data loaded into memory, you can sign them using a buffer.
If you have an asset file's data loaded into memory, you can sign the the asset using a buffer.

**Note:** This is currently only supported for `image/jpeg` and `image/png` data. All other file types should use
the file-based approach below.
**NOTE**: Signing using a buffer is currently supported only for `image/jpeg` and `image/png` data. For all other file types, use the [file-based approach](#signing-files) .

```ts
import { readFile } from 'node:fs/promises';
Expand All @@ -195,8 +233,7 @@ sign(asset, manifest);

#### Signing files

You can pass in a file path to be signed to avoid loading entire assets into memory, or if a certain file type doesn't
have in-memory support.
To avoid loading the entire asset into memory (or for file types other than JPEG and PNG that don't support in-memory signing), pass in the file path to the asset file to sign it; for example:

```ts
import { resolve } from 'node:path';
Expand Down Expand Up @@ -226,7 +263,7 @@ sign(asset, manifest);

#### Local signing

If you have a signing certificate and key, you can sign locally using a local signer:
If you have a signing certificate and key, you can sign locally using a local signer; for example:

```ts
import { readFile } from 'node:fs/promises';
Expand Down Expand Up @@ -266,7 +303,7 @@ sign(asset, manifest);

#### Remote signing

If you have a service that you want to use for signing, you can use that to sign remotely:
If you have access to a web service that performs signing, you can use it to sign remotely; for example:

```ts
import { readFile } from 'node:fs/promises';
Expand Down Expand Up @@ -315,12 +352,7 @@ sign(asset, manifest);

## API documentation

[Click here](docs/modules.md) to view the API documentation.

## Testing
For the API documentation, see the [`/docs/` directory](https://github.com/contentauth/c2pa-node/blob/main/docs/README.md).

After installation, you can run the test suite by running:
**WARNING**: The API is subject to change in this early prerelease library.

```sh
$ pnpm test
```
Loading

0 comments on commit b7518ec

Please sign in to comment.