@zapwebp/core 1.1.1 → 1.1.2

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.
Files changed (45) hide show
  1. package/README.md +79 -51
  2. package/agent.json +180 -0
  3. package/package.json +8 -2
  4. package/src/cache.js +145 -0
  5. package/src/engine/decode.js +60 -0
  6. package/src/engine/encode.js +106 -0
  7. package/src/engine/pipeline.js +116 -0
  8. package/src/engine/transform.js +37 -0
  9. package/src/errors/index.js +34 -0
  10. package/src/formats/avif.js +1 -1
  11. package/src/formats/gif.js +8 -2
  12. package/src/formats/index.js +5 -0
  13. package/src/formats/jpeg.js +14 -3
  14. package/src/formats/png.js +1 -1
  15. package/src/formats/svg.js +76 -14
  16. package/src/formats/tiff.js +8 -2
  17. package/src/formats/webp.js +1 -1
  18. package/src/index.d.ts +286 -9
  19. package/src/index.js +951 -80
  20. package/src/journal/index.js +73 -0
  21. package/src/metadata/c2pa.js +3 -10
  22. package/src/metadata/chunk-stripper.js +235 -0
  23. package/src/metadata/exif.js +3 -11
  24. package/src/metadata/icc.js +3 -10
  25. package/src/metadata/png-text.js +3 -10
  26. package/src/metadata/registry.js +25 -2
  27. package/src/metadata/xmp.js +3 -16
  28. package/src/parallel.js +134 -0
  29. package/src/policy.js +95 -6
  30. package/src/registry/compression.js +84 -0
  31. package/src/registry/formats.js +30 -0
  32. package/src/registry/metadata.js +28 -0
  33. package/src/registry/transforms.js +76 -0
  34. package/src/report.js +404 -0
  35. package/src/safety/path.js +52 -0
  36. package/src/safety/runtime.js +66 -0
  37. package/src/safety/ssrf.js +9 -0
  38. package/src/safety/svg.js +66 -0
  39. package/src/signals.js +683 -0
  40. package/src/smart.js +351 -0
  41. package/src/team-policy.js +319 -0
  42. package/src/testing.d.ts +18 -0
  43. package/src/testing.js +114 -0
  44. package/src/tools.js +240 -0
  45. package/src/types.ts +68 -0
package/src/policy.js CHANGED
@@ -16,7 +16,11 @@ function resolvePolicy(customPolicy = {}, optionsFallback = {}) {
16
16
  let mode = qualityConfig.mode || (optionsFallback.lossless ? 'lossless' : undefined);
17
17
  if (!mode) mode = DEFAULT_CONVERSION_POLICY.quality.mode;
18
18
  if (!['lossy', 'lossless', 'auto'].includes(mode)) {
19
- throw new Error(`Policy quality.mode must be 'lossy', 'lossless', or 'auto' (received "${mode}").`);
19
+ throw new ZapwebpError({
20
+ code: 'E_INVALID_CONFIG',
21
+ message: `Policy quality.mode must be 'lossy', 'lossless', or 'auto' (received "${mode}").`,
22
+ fix: 'Set policy.quality.mode to "lossy", "lossless", or "auto".',
23
+ });
20
24
  }
21
25
 
22
26
  const defaultQuality = qualityConfig.default !== undefined
@@ -24,7 +28,11 @@ function resolvePolicy(customPolicy = {}, optionsFallback = {}) {
24
28
  : (optionsFallback.quality !== undefined ? Number(optionsFallback.quality) : DEFAULT_CONVERSION_POLICY.quality.default);
25
29
 
26
30
  if (!Number.isInteger(defaultQuality) || defaultQuality < 1 || defaultQuality > 100) {
27
- throw new Error('Policy quality.default must be an integer between 1 and 100.');
31
+ throw new ZapwebpError({
32
+ code: 'E_INVALID_CONFIG',
33
+ message: 'Policy quality.default must be an integer between 1 and 100.',
34
+ fix: 'Set policy.quality.default to an integer between 1 and 100.',
35
+ });
28
36
  }
29
37
 
30
38
  const perFormat = {};
@@ -40,24 +48,79 @@ function resolvePolicy(customPolicy = {}, optionsFallback = {}) {
40
48
 
41
49
  // 2. Limits
42
50
  const limitsConfig = policy.limits || {};
51
+ const minInputBytes = limitsConfig.minInputBytes !== undefined
52
+ ? Number(limitsConfig.minInputBytes)
53
+ : (optionsFallback.minInputBytes !== undefined ? Number(optionsFallback.minInputBytes) : undefined);
54
+
55
+ if (minInputBytes !== undefined && (!Number.isFinite(minInputBytes) || minInputBytes < 0)) {
56
+ throw new ZapwebpError({
57
+ code: 'E_INVALID_CONFIG',
58
+ message: 'Policy limits.minInputBytes must be a non-negative number.',
59
+ fix: 'Set limits.minInputBytes to 0 or a positive integer.',
60
+ });
61
+ }
62
+
43
63
  const maxInputBytes = limitsConfig.maxInputBytes !== undefined
44
64
  ? Number(limitsConfig.maxInputBytes)
45
65
  : (optionsFallback.maxBytes !== undefined ? Number(optionsFallback.maxBytes) : DEFAULT_CONVERSION_POLICY.limits.maxInputBytes);
46
66
 
47
67
  if (!Number.isFinite(maxInputBytes) || maxInputBytes <= 0) {
48
- throw new Error('Policy limits.maxInputBytes must be a positive number.');
68
+ throw new ZapwebpError({
69
+ code: 'E_INVALID_CONFIG',
70
+ message: 'Policy limits.maxInputBytes must be a positive number.',
71
+ fix: 'Set limits.maxInputBytes to a positive byte limit.',
72
+ });
73
+ }
74
+
75
+ if (minInputBytes !== undefined && minInputBytes > maxInputBytes) {
76
+ throw new ZapwebpError({
77
+ code: 'E_INVALID_CONFIG',
78
+ message: `Policy limits.minInputBytes (${minInputBytes}) cannot exceed maxInputBytes (${maxInputBytes}).`,
79
+ fix: 'Ensure minInputBytes is less than or equal to maxInputBytes.',
80
+ });
81
+ }
82
+
83
+ const minOutputBytes = limitsConfig.minOutputBytes !== undefined
84
+ ? Number(limitsConfig.minOutputBytes)
85
+ : (optionsFallback.minOutputBytes !== undefined ? Number(optionsFallback.minOutputBytes) : undefined);
86
+
87
+ if (minOutputBytes !== undefined && (!Number.isFinite(minOutputBytes) || minOutputBytes < 0)) {
88
+ throw new ZapwebpError({
89
+ code: 'E_INVALID_CONFIG',
90
+ message: 'Policy limits.minOutputBytes must be a non-negative number.',
91
+ fix: 'Set limits.minOutputBytes to 0 or a positive integer.',
92
+ });
49
93
  }
50
94
 
51
95
  const maxOutputBytes = limitsConfig.maxOutputBytes !== undefined
52
96
  ? Number(limitsConfig.maxOutputBytes)
53
97
  : (optionsFallback.maxOutputBytes !== undefined ? Number(optionsFallback.maxOutputBytes) : undefined);
54
98
 
99
+ if (maxOutputBytes !== undefined && (!Number.isFinite(maxOutputBytes) || maxOutputBytes <= 0)) {
100
+ throw new ZapwebpError({
101
+ code: 'E_INVALID_CONFIG',
102
+ message: 'Policy limits.maxOutputBytes must be a positive number.',
103
+ fix: 'Set limits.maxOutputBytes to a positive byte limit.',
104
+ });
105
+ }
106
+
107
+ if (minOutputBytes !== undefined && maxOutputBytes !== undefined && minOutputBytes > maxOutputBytes) {
108
+ throw new ZapwebpError({
109
+ code: 'E_INVALID_CONFIG',
110
+ message: `Policy limits.minOutputBytes (${minOutputBytes}) cannot exceed maxOutputBytes (${maxOutputBytes}).`,
111
+ fix: 'Ensure minOutputBytes is less than or equal to maxOutputBytes.',
112
+ });
113
+ }
114
+
55
115
  const targetOutputBytes = limitsConfig.targetOutputBytes !== undefined
56
116
  ? Number(limitsConfig.targetOutputBytes)
57
117
  : (optionsFallback.targetOutputBytes !== undefined ? Number(optionsFallback.targetOutputBytes) : undefined);
58
118
 
59
- // 3. Formats Allowlist / Denylist
119
+ // 3. Formats Allowlist / Denylist & Same-Format Action
60
120
  const formatsConfig = policy.formats || {};
121
+ const sameFormatRaw = formatsConfig.sameFormat || optionsFallback.sameFormat || DEFAULT_CONVERSION_POLICY.formats.sameFormat;
122
+ const sameFormat = ['passthrough', 'reencode', 'reject'].includes(sameFormatRaw) ? sameFormatRaw : 'passthrough';
123
+
61
124
  const normalizeList = (list, fallbackStr) => {
62
125
  if (Array.isArray(list)) {
63
126
  return list.map((f) => String(f).toLowerCase().trim() === 'jpg' ? 'jpeg' : String(f).toLowerCase().trim()).filter(Boolean);
@@ -74,7 +137,12 @@ function resolvePolicy(customPolicy = {}, optionsFallback = {}) {
74
137
  const accept = normalizeList(formatsConfig.accept, optionsFallback.accept);
75
138
  const reject = normalizeList(formatsConfig.reject, optionsFallback.reject);
76
139
 
77
- // 4. Advanced
140
+ // 4. Size Mode
141
+ const sizeConfig = policy.size || {};
142
+ const sizeModeRaw = sizeConfig.mode || optionsFallback.sizeMode || (optionsFallback.strict ? 'strict' : undefined) || DEFAULT_CONVERSION_POLICY.size.mode;
143
+ const sizeMode = ['strict', 'compress', 'flexible'].includes(sizeModeRaw) ? sizeModeRaw : 'compress';
144
+
145
+ // 5. Advanced
78
146
  const advancedConfig = policy.advanced || {};
79
147
  const effort = advancedConfig.effort !== undefined
80
148
  ? Number(advancedConfig.effort)
@@ -95,13 +163,19 @@ function resolvePolicy(customPolicy = {}, optionsFallback = {}) {
95
163
  perFormat,
96
164
  },
97
165
  limits: {
166
+ minInputBytes,
98
167
  maxInputBytes,
168
+ minOutputBytes,
99
169
  maxOutputBytes,
100
170
  targetOutputBytes,
101
171
  },
102
172
  formats: {
103
173
  accept,
104
174
  reject,
175
+ sameFormat,
176
+ },
177
+ size: {
178
+ mode: sizeMode,
105
179
  },
106
180
  advanced: {
107
181
  effort,
@@ -123,7 +197,22 @@ function resolvePolicy(customPolicy = {}, optionsFallback = {}) {
123
197
  function checkPolicyInput({ policy, data, detectedFormat }) {
124
198
  if (!policy || !data) return;
125
199
 
126
- // 1. Max Input Bytes (before decode memory allocation)
200
+ // 1. Min Input Bytes (before decode memory allocation)
201
+ if (policy.limits?.minInputBytes && data.length < policy.limits.minInputBytes) {
202
+ throw new ZapwebpError({
203
+ code: 'E_INPUT_TOO_SMALL',
204
+ message: `Input is ${data.length} bytes, minimum required is ${policy.limits.minInputBytes} bytes.`,
205
+ fix: 'Provide an image file meeting the minimum size requirement.',
206
+ inputBytes: data.length,
207
+ minBytes: policy.limits.minInputBytes,
208
+ suggestedFix: {
209
+ minInputBytes: data.length,
210
+ reason: 'Input is smaller than the minimum allowed ingress bytes.',
211
+ },
212
+ });
213
+ }
214
+
215
+ // 2. Max Input Bytes (before decode memory allocation)
127
216
  if (policy.limits?.maxInputBytes && data.length > policy.limits.maxInputBytes) {
128
217
  throw new ZapwebpError({
129
218
  code: 'E_INPUT_TOO_LARGE',
@@ -0,0 +1,84 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * @typedef {Object} CompressionHandler
5
+ * @property {string} name - Canonical compressor identifier
6
+ * @property {(image: any, options: any) => Promise<any>} compress - Compression executor
7
+ */
8
+
9
+ class CompressionRegistry {
10
+ constructor() {
11
+ /** @type {Map<string, CompressionHandler>} */
12
+ this._compressors = new Map();
13
+ }
14
+
15
+ /**
16
+ * Registers a compressor handler.
17
+ * @param {CompressionHandler} compressor
18
+ */
19
+ register(compressor) {
20
+ if (!compressor || typeof compressor !== 'object') {
21
+ throw new TypeError('Compressor must be an object.');
22
+ }
23
+ if (!compressor.name || typeof compressor.name !== 'string') {
24
+ throw new TypeError('Compressor must declare a string name.');
25
+ }
26
+ if (typeof compressor.compress !== 'function') {
27
+ throw new TypeError(`Compressor "${compressor.name}" must implement a compress() function.`);
28
+ }
29
+ this._compressors.set(compressor.name.toLowerCase(), compressor);
30
+ }
31
+
32
+ /**
33
+ * Retrieves a registered compressor by name.
34
+ * @param {string} [name='compressor']
35
+ * @returns {CompressionHandler | undefined}
36
+ */
37
+ getByName(name = 'compressor') {
38
+ if (!name) return undefined;
39
+ return this._compressors.get(String(name).toLowerCase());
40
+ }
41
+
42
+ /**
43
+ * Returns all registered compressors.
44
+ * @returns {CompressionHandler[]}
45
+ */
46
+ getAll() {
47
+ return Array.from(this._compressors.values());
48
+ }
49
+ }
50
+
51
+ const compressionRegistry = new CompressionRegistry();
52
+
53
+ /**
54
+ * Registers a compression handler in the core registry.
55
+ * @param {CompressionHandler} handler
56
+ */
57
+ function registerCompressor(handler) {
58
+ compressionRegistry.register(handler);
59
+ }
60
+
61
+ /**
62
+ * Gets a registered compressor by name.
63
+ * @param {string} [name='compressor']
64
+ * @returns {CompressionHandler | undefined}
65
+ */
66
+ function getCompressor(name = 'compressor') {
67
+ return compressionRegistry.getByName(name);
68
+ }
69
+
70
+ /**
71
+ * Gets all registered compressors.
72
+ * @returns {CompressionHandler[]}
73
+ */
74
+ function getCompressors() {
75
+ return compressionRegistry.getAll();
76
+ }
77
+
78
+ module.exports = {
79
+ CompressionRegistry,
80
+ compressionRegistry,
81
+ registerCompressor,
82
+ getCompressor,
83
+ getCompressors,
84
+ };
@@ -0,0 +1,30 @@
1
+ 'use strict';
2
+
3
+ const formats = require('../formats');
4
+
5
+ /**
6
+ * Registers a new format handler in the core format registry.
7
+ * @param {import('../types').FormatHandler} handler
8
+ */
9
+ function registerFormat(handler) {
10
+ formats.registry.register(handler);
11
+ }
12
+
13
+ /**
14
+ * Returns all canonical format names currently registered.
15
+ * @returns {string[]}
16
+ */
17
+ function getFormats() {
18
+ return formats.getAllHandlers().map((h) => h.name);
19
+ }
20
+
21
+ module.exports = {
22
+ registry: formats.registry,
23
+ registerFormat,
24
+ getFormats,
25
+ getHandlerByName: formats.getHandlerByName,
26
+ getHandlerByMime: formats.getHandlerByMime,
27
+ detectFormatHandler: formats.detectFormatHandler,
28
+ getAllHandlers: formats.getAllHandlers,
29
+ };
30
+
@@ -0,0 +1,28 @@
1
+ 'use strict';
2
+
3
+ const metadata = require('../metadata');
4
+
5
+ /**
6
+ * Registers a new metadata handler in the core metadata registry.
7
+ * @param {import('../types').MetadataHandler} handler
8
+ */
9
+ function registerMetadataHandler(handler) {
10
+ metadata.metadataRegistry.register(handler);
11
+ }
12
+
13
+ /**
14
+ * Returns all registered metadata handlers.
15
+ * @returns {import('../types').MetadataHandler[]}
16
+ */
17
+ function getMetadataHandlers() {
18
+ return metadata.metadataRegistry.getAll();
19
+ }
20
+
21
+ module.exports = {
22
+ metadataRegistry: metadata.metadataRegistry,
23
+ registerMetadataHandler,
24
+ getMetadataHandlers,
25
+ cleanBytes: metadata.cleanBytes,
26
+ detectMetadata: metadata.detectMetadata,
27
+ };
28
+
@@ -0,0 +1,76 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * @typedef {Object} TransformStep
5
+ * @property {string} name - Canonical transform step identifier
6
+ * @property {(image: import('../types').RawImage, options?: any) => Promise<import('../types').RawImage>} apply - Transformation executor
7
+ */
8
+
9
+ class TransformRegistry {
10
+ constructor() {
11
+ /** @type {Map<string, TransformStep>} */
12
+ this._transforms = new Map();
13
+ }
14
+
15
+ /**
16
+ * Registers a transform step.
17
+ * @param {TransformStep} transform
18
+ */
19
+ register(transform) {
20
+ if (!transform || typeof transform !== 'object') {
21
+ throw new TypeError('Transform step must be an object.');
22
+ }
23
+ if (!transform.name || typeof transform.name !== 'string') {
24
+ throw new TypeError('Transform step must declare a string name.');
25
+ }
26
+ if (typeof transform.apply !== 'function') {
27
+ throw new TypeError(`Transform step "${transform.name}" must implement an apply() function.`);
28
+ }
29
+ this._transforms.set(transform.name.toLowerCase(), transform);
30
+ }
31
+
32
+ /**
33
+ * Retrieves a registered transform by name.
34
+ * @param {string} name
35
+ * @returns {TransformStep | undefined}
36
+ */
37
+ getByName(name) {
38
+ if (!name) return undefined;
39
+ return this._transforms.get(String(name).toLowerCase());
40
+ }
41
+
42
+ /**
43
+ * Returns all registered transforms.
44
+ * @returns {TransformStep[]}
45
+ */
46
+ getAll() {
47
+ return Array.from(this._transforms.values());
48
+ }
49
+ }
50
+
51
+ const transformRegistry = new TransformRegistry();
52
+
53
+ /**
54
+ * Registers a new transform step in the core registry.
55
+ * @param {TransformStep} transform
56
+ */
57
+ function registerTransform(transform) {
58
+ transformRegistry.register(transform);
59
+ }
60
+
61
+ /**
62
+ * Gets all registered transforms.
63
+ * @returns {TransformStep[]}
64
+ */
65
+ function getTransforms() {
66
+ return transformRegistry.getAll();
67
+ }
68
+
69
+ module.exports = {
70
+ TransformRegistry,
71
+ transformRegistry,
72
+ registerTransform,
73
+ getTransforms,
74
+ getTransformByName: (name) => transformRegistry.getByName(name),
75
+ };
76
+