@cognitiveproof/softbinding-api-plugin-c2pa-manifest 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CognitiveProof
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,55 @@
1
- # Temporary Holding Version
1
+ # @cognitiveproof/softbinding-api-plugin-c2pa-manifest
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ C2PA Manifest Store reader for [`@cognitiveproof/softbinding-api-server`](https://github.com/Cognitive-Proof/c2pa-soft-binding-server): validates each manifest uploaded to `POST /v1/manifests` with [c2pa-rs](https://github.com/contentauth/c2pa-rs) (through [`@contentauth/c2pa-node`](https://www.npmjs.com/package/@contentauth/c2pa-node)) and reports its manifest id, its soft-binding blocks and whether its signer is trusted.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @cognitiveproof/softbinding-api-server @cognitiveproof/softbinding-api-plugin-c2pa-manifest
9
+ ```
10
+
11
+ Needs Node.js 22.12 or later. `@contentauth/c2pa-node` downloads a prebuilt native library from GitHub when it's installed, so the install step needs network access (see its README for `C2PA_LIBRARY_PATH` and `SKIP_BINARY_DOWNLOAD`).
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import fs from 'fs';
17
+ import { createServer } from '@cognitiveproof/softbinding-api-server';
18
+ import { createC2paManifestReader } from '@cognitiveproof/softbinding-api-plugin-c2pa-manifest';
19
+
20
+ const app = createServer({
21
+ readManifest: createC2paManifestReader({
22
+ trustAnchors: fs.readFileSync('C2PA-TRUST-LIST.pem', 'utf8'),
23
+ }),
24
+ });
25
+ ```
26
+
27
+ | Option | Default | Meaning |
28
+ | ---------------- | ------- | --------------------------------------------------------------------------------------------- |
29
+ | `trustAnchors` | none | PEM certificates that signing credentials are checked against, e.g. the C2PA trust list |
30
+ | `requireTrusted` | `false` | Refuse manifests whose signing credential isn't trusted, instead of storing them as untrusted |
31
+ | `allowExpired` | `true` | Accept a credential that has expired (without a trusted time stamp), as untrusted |
32
+
33
+ With a matcher registered for an algorithm (e.g. `io.iscc.v0` from `@cognitiveproof/softbinding-api-plugin-iscc`), the server indexes the manifest's soft bindings for that algorithm automatically.
34
+
35
+ ## What it accepts
36
+
37
+ Only the Manifest Store is uploaded, never the asset, so hard-binding failures (`assertion.dataHash.mismatch` and the other hash mismatches) are expected and tolerated. The upload is refused (`400`, with the C2PA status code) when:
38
+
39
+ - c2pa-rs can't read it, or bytes follow the Manifest Store's outer JUMBF box;
40
+ - it has no active manifest, or the active manifest's label is longer than 255 characters or not printable;
41
+ - the claim signature isn't verified, or the active manifest has any other validation failure, such as an assertion changed after signing (`assertion.hashedURI.mismatch`);
42
+ - an ingredient manifest was changed after signing;
43
+ - the signer isn't trusted and `requireTrusted` is set, or the credential expired and `allowExpired` is `false`.
44
+
45
+ Reading is offline: remote manifest fetching, OCSP and CAWG identity assertion decoding are turned off, so an upload can't make the server fetch URLs or DID documents it names.
46
+
47
+ ## Soft-binding values
48
+
49
+ Each block is reported with its `alg`, its value as base64 and its `scope` (omitted when empty). The C2PA specification defines the value as a byte string, which c2pa-rs reports as base64, and some writers produce an array of byte values, which is converted. Blocks whose value is plain text that isn't base64 (as some TrustMark assertions write it) are skipped.
50
+
51
+ ## Exports
52
+
53
+ - `createC2paManifestReader(options)`: the `ManifestReader`.
54
+ - `checkReport(report, options)`, `checkLength(data)`, `softBindings(assertions)`, `readerSettings(trustAnchors)`: the steps it applies, for use with your own c2pa-rs report.
55
+ - `InvalidManifestError`: thrown for a refused upload, with the status `code`.
@@ -0,0 +1,81 @@
1
+ import type { Settings } from '@contentauth/c2pa-utilities' with { 'resolution-mode': 'import' };
2
+ import type { ManifestInfo, SoftBindingBlock } from '@cognitiveproof/softbinding-api-plugin-types';
3
+ export declare const MEDIA_TYPE = "application/c2pa";
4
+ /** Longest manifest label accepted as a manifestId. */
5
+ export declare const MAX_ID_LENGTH = 255;
6
+ export interface C2paManifestReaderOptions {
7
+ /**
8
+ * PEM trust anchors that signing credentials are checked against, e.g. the
9
+ * C2PA trust list. Without any, every manifest is reported untrusted.
10
+ */
11
+ trustAnchors?: string;
12
+ /** Refuse manifests whose signing credential isn't trusted. Default: false. */
13
+ requireTrusted?: boolean;
14
+ /**
15
+ * Accept a signing credential that has expired (without a trusted time
16
+ * stamp), as untrusted. c2pa-rs doesn't report the claim signature as
17
+ * validated in that case. Default: true.
18
+ */
19
+ allowExpired?: boolean;
20
+ }
21
+ /** Thrown for an upload that isn't an acceptable Manifest Store; `code` is a C2PA status code or our own. */
22
+ export declare class InvalidManifestError extends Error {
23
+ readonly code: string;
24
+ constructor(code: string, message: string);
25
+ }
26
+ interface StatusEntry {
27
+ code: string;
28
+ }
29
+ /** The parts of a c2pa-rs Reader report this plugin looks at. */
30
+ export interface C2paReport {
31
+ active_manifest?: string;
32
+ manifests?: Record<string, {
33
+ assertions?: Array<{
34
+ label?: string;
35
+ data?: unknown;
36
+ }>;
37
+ }>;
38
+ validation_results?: {
39
+ activeManifest?: {
40
+ success?: StatusEntry[];
41
+ failure?: StatusEntry[];
42
+ };
43
+ ingredientDeltas?: Array<{
44
+ validationDeltas?: {
45
+ failure?: StatusEntry[];
46
+ };
47
+ }>;
48
+ };
49
+ }
50
+ /**
51
+ * c2pa-rs settings that keep reading offline: no remote manifests, OCSP or
52
+ * CAWG identity resolution (which would fetch DID documents from hosts the
53
+ * uploader names). `core` isn't in c2pa-node's Settings type but is passed
54
+ * through to c2pa-rs.
55
+ */
56
+ export declare function readerSettings(trustAnchors?: string): Settings;
57
+ /**
58
+ * Refuses bytes after the Manifest Store: the length its outer JUMBF box
59
+ * declares (LBox, or the 64-bit XLBox when LBox is 1) must be the upload's.
60
+ */
61
+ export declare function checkLength(data: Buffer): void;
62
+ /** Every block of every soft-binding assertion that names an algorithm and has a byte-string value. */
63
+ export declare function softBindings(assertions?: Array<{
64
+ label?: string;
65
+ data?: unknown;
66
+ }>): SoftBindingBlock[];
67
+ /** Applies the acceptance policy to a c2pa-rs report and summarises it. */
68
+ export declare function checkReport(report: C2paReport, options?: C2paManifestReaderOptions): ManifestInfo;
69
+ /**
70
+ * Builds a ManifestReader for `createServer({ readManifest })`.
71
+ *
72
+ * ```ts
73
+ * import { createC2paManifestReader } from '@cognitiveproof/softbinding-api-plugin-c2pa-manifest';
74
+ *
75
+ * createServer({
76
+ * readManifest: createC2paManifestReader({ trustAnchors: fs.readFileSync('C2PA-TRUST-LIST.pem', 'utf8') }),
77
+ * });
78
+ * ```
79
+ */
80
+ export declare function createC2paManifestReader(options?: C2paManifestReaderOptions): (data: Buffer) => Promise<ManifestInfo>;
81
+ export {};
package/dist/index.js ADDED
@@ -0,0 +1,188 @@
1
+ "use strict";
2
+ // A ManifestReader for createServer({ readManifest }) that validates uploaded
3
+ // C2PA Manifest Stores with c2pa-rs (through @contentauth/c2pa-node) and
4
+ // reports their manifest id and soft-binding blocks.
5
+ //
6
+ // The asset is never uploaded alongside its manifest, so hard-binding
7
+ // failures are expected and tolerated. A signing credential outside the trust
8
+ // anchors (or expired) is recorded as untrusted rather than refused, unless
9
+ // `requireTrusted` is set. Any other validation failure of the active
10
+ // manifest refuses the upload, so a tampered assertion — a soft binding
11
+ // among them — never reaches the store. So do bytes after the Manifest Store
12
+ // (c2pa-rs ignores them, but the server would store and serve them) and
13
+ // ingredient manifests changed after signing.
14
+ Object.defineProperty(exports, "__esModule", { value: true });
15
+ exports.InvalidManifestError = exports.MAX_ID_LENGTH = exports.MEDIA_TYPE = void 0;
16
+ exports.readerSettings = readerSettings;
17
+ exports.checkLength = checkLength;
18
+ exports.softBindings = softBindings;
19
+ exports.checkReport = checkReport;
20
+ exports.createC2paManifestReader = createC2paManifestReader;
21
+ // c2pa-node and c2pa-utilities are ESM-only. This package compiles to
22
+ // CommonJS with `module: node16`, which keeps these as native dynamic
23
+ // imports, loaded the first time a reader is used.
24
+ let modules;
25
+ function loadC2pa() {
26
+ modules ??= Promise.all([
27
+ import('@contentauth/c2pa-node'),
28
+ import('@contentauth/c2pa-utilities'),
29
+ ]);
30
+ return modules;
31
+ }
32
+ exports.MEDIA_TYPE = 'application/c2pa';
33
+ /** Longest manifest label accepted as a manifestId. */
34
+ exports.MAX_ID_LENGTH = 255;
35
+ const SIGNATURE_VALIDATED = 'claimSignature.validated';
36
+ const UNTRUSTED = 'signingCredential.untrusted';
37
+ const EXPIRED = 'signingCredential.expired';
38
+ // Failures caused by the missing asset: its hard binding can't be checked
39
+ // against a bare Manifest Store.
40
+ const HARD_BINDING_FAILURES = new Set([
41
+ 'assertion.dataHash.mismatch',
42
+ 'assertion.boxesHash.mismatch',
43
+ 'assertion.bmffHash.mismatch',
44
+ 'assertion.collectionHash.mismatch',
45
+ ]);
46
+ const SOFT_BINDING = 'c2pa.soft-binding';
47
+ /** Thrown for an upload that isn't an acceptable Manifest Store; `code` is a C2PA status code or our own. */
48
+ class InvalidManifestError extends Error {
49
+ code;
50
+ constructor(code, message) {
51
+ super(`${code}: ${message}`);
52
+ this.code = code;
53
+ this.name = 'InvalidManifestError';
54
+ }
55
+ }
56
+ exports.InvalidManifestError = InvalidManifestError;
57
+ /**
58
+ * c2pa-rs settings that keep reading offline: no remote manifests, OCSP or
59
+ * CAWG identity resolution (which would fetch DID documents from hosts the
60
+ * uploader names). `core` isn't in c2pa-node's Settings type but is passed
61
+ * through to c2pa-rs.
62
+ */
63
+ function readerSettings(trustAnchors) {
64
+ return {
65
+ verify: { verifyTrust: true, remoteManifestFetch: false, ocspFetch: false },
66
+ ...(trustAnchors ? { trust: { trustAnchors } } : {}),
67
+ core: { decodeIdentityAssertions: false, allowedNetworkHosts: [] },
68
+ };
69
+ }
70
+ /**
71
+ * Refuses bytes after the Manifest Store: the length its outer JUMBF box
72
+ * declares (LBox, or the 64-bit XLBox when LBox is 1) must be the upload's.
73
+ */
74
+ function checkLength(data) {
75
+ let length = data.length >= 4 ? data.readUInt32BE(0) : -1;
76
+ if (length === 1)
77
+ length = data.length >= 16 ? Number(data.readBigUInt64BE(8)) : -1;
78
+ if (length !== data.length) {
79
+ throw new InvalidManifestError('manifest.trailingData', 'The upload must be the Manifest Store alone, as one JUMBF superbox');
80
+ }
81
+ }
82
+ /** Raw-bytes base64 of a soft-binding block value, or undefined for one that isn't a byte string. */
83
+ function blockValue(value) {
84
+ if (Array.isArray(value) && value.every((b) => Number.isInteger(b) && b >= 0 && b < 256)) {
85
+ return value.length ? Buffer.from(value).toString('base64') : undefined;
86
+ }
87
+ if (typeof value === 'string' && /^[A-Za-z0-9+/]+={0,2}$/.test(value) && value.length % 4 === 0) {
88
+ return value;
89
+ }
90
+ return undefined;
91
+ }
92
+ function isObject(value) {
93
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
94
+ }
95
+ /** Every block of every soft-binding assertion that names an algorithm and has a byte-string value. */
96
+ function softBindings(assertions = []) {
97
+ const found = [];
98
+ for (const assertion of assertions) {
99
+ const label = assertion.label ?? '';
100
+ if (label !== SOFT_BINDING && !label.startsWith(`${SOFT_BINDING}__`))
101
+ continue;
102
+ const data = (assertion.data ?? {});
103
+ if (typeof data.alg !== 'string' || !data.alg || !Array.isArray(data.blocks))
104
+ continue;
105
+ for (const block of data.blocks) {
106
+ const value = blockValue(block?.value);
107
+ if (!value)
108
+ continue;
109
+ // An empty scope covers the whole asset, the same as none.
110
+ const scoped = isObject(block.scope) && Object.keys(block.scope).length > 0;
111
+ found.push({ alg: data.alg, value, ...(scoped ? { scope: block.scope } : {}) });
112
+ }
113
+ }
114
+ return found;
115
+ }
116
+ /** Applies the acceptance policy to a c2pa-rs report and summarises it. */
117
+ function checkReport(report, options = {}) {
118
+ const { requireTrusted = false, allowExpired = true } = options;
119
+ const label = report.active_manifest;
120
+ if (!label) {
121
+ throw new InvalidManifestError('manifest.missing', 'The Manifest Store has no active manifest');
122
+ }
123
+ // eslint-disable-next-line no-control-regex
124
+ if (label.length > exports.MAX_ID_LENGTH || /[\u0000-\u001f\u007f]/.test(label)) {
125
+ throw new InvalidManifestError('manifest.idInvalid', `The manifest id must be printable, at most ${exports.MAX_ID_LENGTH} characters`);
126
+ }
127
+ const active = report.validation_results?.activeManifest ?? {};
128
+ const failures = (active.failure ?? []).map((f) => f.code);
129
+ const successes = (active.success ?? []).map((s) => s.code);
130
+ const tolerated = new Set([
131
+ ...HARD_BINDING_FAILURES,
132
+ UNTRUSTED,
133
+ ...(allowExpired ? [EXPIRED] : []),
134
+ ]);
135
+ const refusing = failures.find((code) => !tolerated.has(code));
136
+ if (refusing)
137
+ throw new InvalidManifestError(refusing, 'The active manifest failed validation');
138
+ const expired = failures.includes(EXPIRED);
139
+ if (!successes.includes(SIGNATURE_VALIDATED) && !expired) {
140
+ throw new InvalidManifestError('claimSignature.missing', 'The claim signature of the active manifest is unverified');
141
+ }
142
+ const changed = (report.validation_results?.ingredientDeltas ?? [])
143
+ .flatMap((delta) => delta.validationDeltas?.failure ?? [])
144
+ .map((f) => f.code)
145
+ .find((code) => code.endsWith('.mismatch'));
146
+ if (changed)
147
+ throw new InvalidManifestError(changed, 'An ingredient manifest failed validation');
148
+ const trusted = !failures.includes(UNTRUSTED) && !expired;
149
+ if (requireTrusted && !trusted) {
150
+ throw new InvalidManifestError(UNTRUSTED, 'The signing credential is not trusted');
151
+ }
152
+ return {
153
+ manifestId: label,
154
+ bindings: softBindings(report.manifests?.[label]?.assertions),
155
+ trusted,
156
+ };
157
+ }
158
+ /**
159
+ * Builds a ManifestReader for `createServer({ readManifest })`.
160
+ *
161
+ * ```ts
162
+ * import { createC2paManifestReader } from '@cognitiveproof/softbinding-api-plugin-c2pa-manifest';
163
+ *
164
+ * createServer({
165
+ * readManifest: createC2paManifestReader({ trustAnchors: fs.readFileSync('C2PA-TRUST-LIST.pem', 'utf8') }),
166
+ * });
167
+ * ```
168
+ */
169
+ function createC2paManifestReader(options = {}) {
170
+ const settings = readerSettings(options.trustAnchors);
171
+ let context;
172
+ return async (data) => {
173
+ const [{ Reader }, { Context }] = await loadC2pa();
174
+ context ??= new Context(settings);
175
+ let report;
176
+ try {
177
+ const reader = await Reader.fromAsset({ buffer: data, mimeType: exports.MEDIA_TYPE }, context);
178
+ if (!reader)
179
+ throw new Error('No C2PA Manifest Store found');
180
+ report = reader.json();
181
+ }
182
+ catch (err) {
183
+ throw new InvalidManifestError('manifest.unreadable', err instanceof Error && err.message ? err.message : 'Not a C2PA Manifest Store');
184
+ }
185
+ checkLength(data);
186
+ return checkReport(report, options);
187
+ };
188
+ }
package/package.json CHANGED
@@ -1,6 +1,35 @@
1
1
  {
2
2
  "name": "@cognitiveproof/softbinding-api-plugin-c2pa-manifest",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "C2PA Manifest Store reader for the C2PA Soft Binding Resolution API server: validates uploads with c2pa-rs and reports their manifest id and soft bindings",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/Cognitive-Proof/c2pa-soft-binding-server.git",
9
+ "directory": "plugins/c2pa-manifest"
10
+ },
11
+ "main": "dist/index.js",
12
+ "types": "dist/index.d.ts",
13
+ "files": [
14
+ "dist"
15
+ ],
16
+ "engines": {
17
+ "node": ">=22.12"
18
+ },
19
+ "scripts": {
20
+ "build": "tsc",
21
+ "typecheck": "tsc --noEmit",
22
+ "test": "NODE_OPTIONS=--experimental-vm-modules jest"
23
+ },
24
+ "dependencies": {
25
+ "@cognitiveproof/softbinding-api-plugin-types": "^1.2.0",
26
+ "@contentauth/c2pa-node": "^0.12.0",
27
+ "@contentauth/c2pa-utilities": "^0.5.1"
28
+ },
29
+ "devDependencies": {
30
+ "@types/jest": "^30.0.0",
31
+ "jest": "^30.4.2",
32
+ "ts-jest": "^29.4.11",
33
+ "typescript": "^5.3.3"
34
+ }
35
+ }