diff --git a/docs/legacy-js-sdk/deprecation-notice.md b/docs/legacy-js-sdk/deprecation-notice.md deleted file mode 100644 index 850a92d0..00000000 --- a/docs/legacy-js-sdk/deprecation-notice.md +++ /dev/null @@ -1,14 +0,0 @@ -:::danger Warning -This is documentation for the deprecated legacy JavaScript library, [c2pa-js-legacy](https://github.com/contentauth/c2pa-js-legacy). **This library is no longer maintained or supported**. Instead use the [new JavaScript web library](/docs/js-sdk/js-landing.mdx). -::: - - -:::note Legacy JavaScript library documentation -- [Quick start](/docs/legacy-js-sdk/getting-started/quick-start) -- [Architecture](/docs/legacy-js-sdk/getting-started/architecture.mdx) -- [Examples](/docs/legacy-js-sdk/guides/examples.mdx) -- [Hosting assets](/docs/legacy-js-sdk/guides/hosting.mdx) -- [Viewing manifest data](/docs/legacy-js-sdk/guides/viewing-provenance.mdx) - - [Selectors](/docs/legacy-js-sdk/guides/selectors.mdx) - - [Validation](/docs/legacy-js-sdk/guides/validation.mdx) -::: \ No newline at end of file diff --git a/docs/legacy-js-sdk/getting-started/architecture.mdx b/docs/legacy-js-sdk/getting-started/architecture.mdx deleted file mode 100644 index 5f7c72e1..00000000 --- a/docs/legacy-js-sdk/getting-started/architecture.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -id: architecture -title: 'Legacy JavaScript library: Architecture' -hide_table_of_contents: true ---- - -import { TransformWrapper, TransformComponent } from 'react-zoom-pan-pinch'; -import Deprecation from '../deprecation-notice.md'; - - - -:::tip -Zoom in by double-clicking or scrolling with your mouse or trackpad. Move the diagram by clicking and dragging. -::: - - - - - - diff --git a/docs/legacy-js-sdk/getting-started/legacy-js-sdk-redirect.mdx b/docs/legacy-js-sdk/getting-started/legacy-js-sdk-redirect.mdx deleted file mode 100644 index 8aabeeda..00000000 --- a/docs/legacy-js-sdk/getting-started/legacy-js-sdk-redirect.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -id: overview -title: Redirect ---- - -import { Redirect } from '@docusaurus/router'; - - - -This page will be redirected to `https://opensource.contentauthenticity.org/docs/js-sdk/js-landing`. diff --git a/docs/legacy-js-sdk/getting-started/quick-start.mdx b/docs/legacy-js-sdk/getting-started/quick-start.mdx deleted file mode 100644 index 1f52eb3f..00000000 --- a/docs/legacy-js-sdk/getting-started/quick-start.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -id: quick-start -title: 'Legacy JavaScript library: Quick start' ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import Deprecation from '../deprecation-notice.md'; - - - -## Prerequisites - -You must install [Node.js](https://nodejs.org/) for package management and TypeScript compilation. - -#### macOS - -To install Node.js on macOS: - -1. **Install Homebrew:** The easiest way to install Node.js on your macOS system is by using [Homebrew](https://brew.sh/). Follow the instructions on the Homebrew page to install it. -1. **Install Node.js:** Once you have installed Homebrew, open a terminal and enter this command: - -``` -brew install node@16 -``` - -:::note -For more advanced JavaScript development, instead of Homebrew, use [nvm](https://github.com/nvm-sh/nvm) to quickly install and use different versions of Node.js. -::: - -## Bringing in the JavaScript library - -You can bring in the JavaScript library by using a content delivery network (CDN) or by hosting the files yourself. - -### Using a CDN - -The quickest way to get up and running is to use a CDN such as [jsDelivr](https://www.jsdelivr.com/). One of the big advantages of using a CDN is that it provides all the required static assets, so you don't have to host them. The CDN also delivers the files at the edge, which enables faster downloads to your users. - -For example: - -```js -const version = '0.24.2'; -{ - wasmSrc: `https://cdn.jsdelivr.net/npm/c2pa@${version}/dist/assets/wasm/toolkit_bg.wasm`, - workerSrc: `https://cdn.jsdelivr.net/npm/c2pa@${version}/dist/c2pa.worker.min.js`, -} -``` - -:::caution -The version numbers provided in the CDN URLs _must_ be the same in all of the places you reference the library. To make it easy, use a variable that provides the version as shown in the example. -::: - -### Using a package manager - -You can also bring in the library with a package manager, such as `npm`, `pnpm`, or `yarn`. This way, all of the client side code is hosted with your app and there are no external dependencies. For example, using `npm`: - -```bash -npm install c2pa -``` - -#### Static assets - -When loading via a package manager, the library needs access to two externally-hosted assets so it can "lazy load" them: - -- `c2pa/dist/assets/wasm/toolkit_bg.wasm` - the WebAssembly binary -- `c2pa/dist/c2pa.worker.min.js` - the Web Worker script - -:::note -Be sure to configure your server to send proper `Content-Type` headers for these files. For more information, see [Hosting](../guides/hosting). -::: diff --git a/docs/legacy-js-sdk/guides/examples.mdx b/docs/legacy-js-sdk/guides/examples.mdx deleted file mode 100644 index 18a2a30a..00000000 --- a/docs/legacy-js-sdk/guides/examples.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: examples -title: Legacy JavaScript examples ---- - -import Deprecation from '../deprecation-notice.md'; - - - -JavaScript examples are in **[contentauth/c2pa-js-examples](https://github.com/contentauth/c2pa-js-examples)**. The examples are mirrored from the [examples directory in the contentauth/c2pa-js repository](https://github.com/contentauth/c2pa-js/tree/main/examples). - -:::note -The JavaScript library uses a number of modern JavaScript technologies such as WebAssembly (Wasm) and Web Workers. To understand the JavaScript examples, you should be familiar with these technologies, [TypeScript](https://www.typescriptlang.org/) and at least one bundler tool such as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), or [Vite](https://vitejs.dev/). -::: - -Additionally, the JavaScript examples use TypeScript for type safety. | diff --git a/docs/legacy-js-sdk/guides/hosting.mdx b/docs/legacy-js-sdk/guides/hosting.mdx deleted file mode 100644 index 520d595f..00000000 --- a/docs/legacy-js-sdk/guides/hosting.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -id: hosting -title: 'Legacy JavaScript library: Hosting C2PA assets' ---- - -import Deprecation from '../deprecation-notice.md'; - - - -## Cross-origin (CORS) support - -Processing images from a URL or DOM selector requires the -client to download the source image for processing. If the image is not on the [same origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) as the site running the JavaScript library, the server hosting the images must return the following HTTP response headers for cross-origin resource sharing [(CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS): - -- [`Access-Control-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) must either return the origin of the server running the JavaScript library, or `*` to allow all origins from requests without credentials. -- [`Access-Control-Allow-Methods`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods) must include at least the `GET` method. -- [`Access-Control-Allow-Headers`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) must include include `Range` to support [Range requests](#range-requests), in addition to the `Accept-Ranges: bytes` header itself. - -The vast majority of major CDNs and hosting providers allow customizing these headers. - -### Range requests - -Since images can be quite large, the JavaScript library uses [HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests) to download the first part of the file (by default, the first 64KB). It then tests if C2PA manifest data exists in this downloaded fragment; if it does, the download proceeds and the JavaScript library processes the rest of the file. This avoids downloading potentially large amounts of data if an image does not contain a manifest. - -For this feature to work, the server hosting the images must support HTTP range requests. To check, open -your terminal and enter the following command (assuming you have [curl](https://curl.se/) installed): - -```shell -curl -I http://assets.mycdn.com/images/image01.jpg - -HTTP/1.1 200 OK -... -Accept-Ranges: bytes -Content-Length: 86405 -``` - -If the response contains `Accept-Ranges: bytes`, then your server is set up to take advantage of this feature. - -If the response contains `Accept-Ranges: none` or no `Accept-Ranges` field in the header, the JavaScript library will automatically re-request the image without the `Range` header, forcing a full download of the file. - -## Library assets - -To reduce the initial bundle size, serve both the Web Worker script and the WebAssembly binary as separate -requests. If you are using a build system, this means you must export them as static assets. For -examples of configuring popular build systems, see the [Quick start guide](../getting-started/quick-start.mdx#bringing-in-the-javascript-library). - -To host the library yourself, expose the static asset files with the following response headers to avoid errors with some browsers: - -- `c2pa/dist/assets/wasm/toolkit_bg.wasm`: Serve with `Content-Type: application/wasm` response header. -- `c2pa/dist/c2pa.worker.min.js`: Serve with `Content-Type: text/javascript` response header. - -Then pass these URLs to the `createC2pa` function; for example: - -``` -const c2pa = await createC2pa({ - wasmSrc: 'https://your_static_asset_uri/toolkit_bg.wasm', - workerSrc: 'https://your_static_asset_uri/c2pa.worker.min.js', - }) -``` - -Where `your_static_asset_uri` is the URI where you're serving the library asset files. - -:::caution -When hosting the library files, make sure you are using the correct version number that aligns with the version of the library you're using. -::: diff --git a/docs/legacy-js-sdk/guides/selectors.mdx b/docs/legacy-js-sdk/guides/selectors.mdx deleted file mode 100644 index 0869b42f..00000000 --- a/docs/legacy-js-sdk/guides/selectors.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -id: selectors -title: 'Legacy JavaScript library: Selectors' ---- - -import Deprecation from '../deprecation-notice.md'; - - - -[Selectors](https://github.com/contentauth/c2pa-js/tree/main/packages/c2pa/src/selectors) are convenience functions that return useful data from manifest objects. The selector functions are: - -- `selectEditsAndActivity` - Returns a formatted list of manifest edits and activity. -- `selectProducer` - Returns information on the producer of an asset. -- `selectSocialAccounts` - Returns social accounts associated with the producer of a manifest, if available. - -For instance, you can use `selectProducer` to get information on the producer of an asset as follows: - -```typescript -import { selectProducer } from 'c2pa'; - -const producer = selectProducer(manifest); -``` - -Without using a selector, finding this information requires locating the `stds.schema-org.CreativeWork` assertion and having familiarity with its structure. As you can see, the code is much more complicated: - -```typescript -function selectProducer(manifest) { - const cwAssertion = manifest.assertions.get('stds.schema-org.CreativeWork'); - return assertion.author?.find((x) => !x.hasOwnProperty('@id')); -} -``` - -Some selectors may involve complex, possibly asynchronous operations. For example, `selectEditsAndActivity` abstracts a complex operation involving multiple manifest assertions and remote resources to return a formatted list of edits and activity described within a manifest: - -```typescript -import { selectEditsAndActivity } from 'c2pa'; - -const editsAndActivity = await selectEditsAndActivity(manifest); -``` - -The result is an `editsAndActivity` object such as this: - -```js -[ - { - id: 'COLOR_ADJUSTMENTS', - icon: 'https://cai-assertions.adobe.com/icons/color-palette-dark.svg', - label: 'Color adjustments', - description: 'Changed tone, saturation, etc.', - }, - { - id: 'IMPORT', - icon: 'https://cai-assertions.adobe.com/icons/import-dark.svg', - label: 'Imported assets', - description: 'Added images, videos, etc.', - }, - { - id: 'TRANSFORM', - icon: 'https://cai-assertions.adobe.com/icons/group-dark.svg', - label: 'Size and position adjustments', - description: 'Changed size, orientation, direction, or position', - }, -]; -``` diff --git a/docs/legacy-js-sdk/guides/validation.mdx b/docs/legacy-js-sdk/guides/validation.mdx deleted file mode 100644 index 4470925c..00000000 --- a/docs/legacy-js-sdk/guides/validation.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -id: validation -title: 'Legacy JavaScript library: Validation & errors' ---- - -import Deprecation from '../deprecation-notice.md'; - - - -Part of processing an asset involves [validating the manifests](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_validation) that it contains. During validation, errors can occur in the active manifest and in ingredients. - -## Validation errors in the active manifest - -When `c2pa.read` loads C2PA assets, it validates the current manifest and assigns any [failure codes](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_failure_codes) to the `manifestStore.validationStatus` array. - -Manifest validation errors can occur when: - -- The bits of an asset were edited after it was signed. -- A claim or assertion was missing or tampered with. -- The manifest was signed with an invalid credential. - -## Validation errors in ingredients - -Ingredients are validated when they are imported into an asset. The results of this are stored in the manifest in the ingredient's [`validationStatus`](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_existing_manifests) object, which contains both [success](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_success_codes) and [failure](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_failure_codes) codes that represent the results of all of the validation checks that took place. - -Access validation errors in ingredients in JavaScript code as follows: - -```typescript -manifest.ingredients.forEach((ingredient) => { - console.log('validationStatus', data.ingredient.validationStatus); -}); -``` - -:::note -The `validationStatus` array only reports failure `validationStatus` codes since success codes are informational only. -::: - -## Asset processing errors - -Errors can also occur when trying to process an asset, which will throw a JavaScript error when calling `c2pa.read`. Capture these errors by surrounding `c2pa.read` in a `try...catch` block. For example: - -```typescript -try { - const { manifestStore } = await c2pa.read(sampleImage); - console.log('manifestStore', manifestStore); -} catch (err) { - console.error('Error reading image:', err); -} -``` - -Errors have a name that corresponds with an [`c2pa::Error` enum variant](https://docs.rs/c2pa/latest/c2pa/enum.Error.html), surrounded with `C2pa()`, for instance `C2pa(UnsupportedType)`. - -Events that can cause an error include passing in an asset that: - -- Is not a supported file type (for example, `image/jpeg`, `image/png`). -- Contains corrupted data. diff --git a/docs/legacy-js-sdk/guides/viewing-provenance.mdx b/docs/legacy-js-sdk/guides/viewing-provenance.mdx deleted file mode 100644 index 1acd0c2a..00000000 --- a/docs/legacy-js-sdk/guides/viewing-provenance.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -id: viewing-manifest-data -title: 'Legacy JavaScript library: Viewing manifest data' ---- - -import Deprecation from '../deprecation-notice.md'; - - - -## Initializing the library - -The way that you import `wasmSrc` and `workerSrc` varies depending on the build system you use. For more information, see [Quick start](../getting-started/quick-start.mdx#bringing-in-the-javascript-library). - -## Viewing manifest data - -If the input provided to `c2pa.read` has a C2PA manifest and was processed without errors, the returned `c2paReadResult` contains a `manifestStore`. - -The `manifestStore` object contains a few properties: - -- **manifests**: An object containing _all_ manifests found in an asset, keyed by UUID. -- **activeManifest**: A pointer to the latest `manifest` in the manifest store. Effectively the "parent" manifest, this is the likely starting point when inspecting an asset's C2PA data. -- **validationStatus**: A list of any validation errors the library generated when processing an asset. See [Validation](./validation.mdx) for more information. - -`Manifest` objects contain properties pertaining to an asset's provenance, along with convenient interfaces for accessing assertion data and generating a thumbnail. diff --git a/docs/legacy-js-sdk/overview.mdx b/docs/legacy-js-sdk/overview.mdx deleted file mode 100644 index 706130e4..00000000 --- a/docs/legacy-js-sdk/overview.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: old-js-overview -title: Legacy JavaScript library ---- - -import Deprecation from './deprecation-notice.md'; - - - -The CAI legacy JavaScript library performs only **read** operations on C2PA manifests. - -## What you should already know - -:::info -The JavaScript library is intended for experienced JavaScript developers. It uses a number of modern JavaScript technologies, as detailed below. To use the library, you should be familiar with these technologies, and at least one popular build and bundler tool such as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), or [Vite](https://vitejs.dev/). -::: - -### Technologies that the library uses - -The JavaScript library uses several modern browser technologies, including: - -- [WebAssembly](https://webassembly.org/) -- [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) -- [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) -- [Typed arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) -- [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) - -## Overview - -The JavaScript library is a monorepo containing the following packages intended for client use: - -- [**c2pa**](https://opensource.contentauthenticity.org/docs/js-sdk/api/c2pa) is the main package used for loading and verifying manifests. This package runs all of the processing logic on the client using a [WebAssembly](https://webassembly.org/) module and exposes a [TypeScript](https://www.typescriptlang.org/)-compatible API for easy integration. -- **c2pa-wc** provides UI components designed with input from the C2PA UX working group. It enables users to get up and running with standard UI patterns quickly and easily in any front-end environment. -- **@contentauth/react** provides a hooks interface for React components to quickly get manifest and thumbnail data in your React app. - -To learn how to use these libraries, see the [Quick start](quick-start). - -Additionally, the library includes the following supporting packages that are _not_ intended for separate use: - -- **@cai/toolkit** contains the WebAssembly module, data binding functions, and related build tools. The `c2pa` package consumes this library under the hood. The WebAssembly module handles manifest parsing and validation. -- **@cai/detector** provides a high-performance binary scanner to quickly detect if C2PA manifest data exists in a file. The `c2pa` package also consumes this library. - -## Features - -Key features of the JavaScript library include: - -- **Developer friendly**: Full TypeScript support and robust debugging support using the [debug](https://github.com/debug-js/debug) library make integration easy. -- **Performance**: The processing code of the library uses a high-performance [WebAssembly](https://developer.mozilla.org/en-US/docs/WebAssembly) binary. Additionally, the library offloads processing tasks to a configurable Web Worker pool to enable parallelization and avoid blocking a web application's main thread. -- **Lazy loading and processing**: Since images can be quite large, the library inspects the start of an asset file for C2PA manifest data before requesting the entire file, [if the server supports it](../guides/hosting#range-requests). The library will download the rest of the asset only if it finds the metadata marker. Additionally, it delays loading the WebAssembly binary until it makes the first processing request. -- **Adherence to the C2PA specification**: The library strives to maintain compliance with the [C2PA specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html) as much as possible, and the web components follow the [C2PA user experience guidance](https://c2pa.org/specifications/specifications/1.0/ux/UX_Recommendations.html) recommendations. -- **Security and encryption**: The library handles all [validation](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_validation) via the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) and passes any validation errors back to the client. It supports all ECDSA and RSASSA-PSS algorithms listed in the [C2PA specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_digital_signatures). - :::caution - The JavaScript library does not currently support Ed25519 signatures. - :::caution -- **Framework-agnostic**: The UI components are [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) that use the [Lit library](https://lit.dev/). Because of this, you can use them in [React, Vue, Angular, Svelte](https://custom-elements-everywhere.com/), or even vanilla JavaScript. - -## Browser support - -The JavaScript library uses several [modern browser technologies](#technologies-that-the-library-uses). -Because of these requirements, **the library is not supported on any version of Internet Explorer and on a few less-used mobile browsers**. The chart below from [caniuse.com](https://caniuse.com/wasm,webworkers,cryptography,typedarrays,fetch) summarizes the browsers and versions that support the library. - -![CAI JavaScript library browser support](../../static/img/caniuse.png) - -:::info -This chart is accurate as of July, 2025. For the most up-to-date browser support information, see [caniuse.com](https://caniuse.com/wasm,webworkers,cryptography,typedarrays,fetch). -::: - -## Debugging - -The JavaScript library uses the [debug-js](https://github.com/debug-js/debug) library to get debug-level information under the `c2pa` namespace. - -To view debug messages in the console, use your browser's inspector, go to the Console tab, and enter: - -```js -localStorage.debug = 'c2pa:*'; -``` - -The debugging information includes millisecond timing differences so you can get an idea of how long different events take. - -:::note -Debug calls and statements are stripped out of minified production builds to reduce file size. -::: - -To turn off debugging, enter: - -```js -localStorage.debug = false; -``` diff --git a/docs/legacy-js-sdk/temp-new-sdk.md b/docs/legacy-js-sdk/temp-new-sdk.md deleted file mode 100644 index c2a5008d..00000000 --- a/docs/legacy-js-sdk/temp-new-sdk.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: js-lib-v2 -title: New JavaScript library ---- - -There is a new [JavaScript web library](https://github.com/contentauth/c2pa-js/tree/main/packages/c2pa-web) for applications that run in a web browser environment. - -We are working on adding documentation. Please bear with us! -