@aelionsdk/material-sdk 0.1.0-beta.1

package/dist/package-limits.js

@@ -0,0 +1,202 @@
+export const MATERIAL_PACKAGE_MAX_FILES = 256;
+export const MATERIAL_PACKAGE_MAX_FILE_BYTES = 32 * 1024 * 1024;
+export const MATERIAL_PACKAGE_MAX_MANIFEST_BYTES = 256 * 1024;
+export const MATERIAL_PACKAGE_MAX_BYTES = 64 * 1024 * 1024;
+export const MATERIAL_PACKAGE_MAX_ARCHIVE_BYTES = 65 * 1024 * 1024;
+const ZIP_UINT16_MAX = 0xffff;
+const ZIP_UINT32_MAX = 0xffffffff;
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+/* eslint-disable @typescript-eslint/unbound-method -- captured built-in accessors are invoked with Reflect.apply below */
+const typedArrayByteLengthGetter_ = Object.getOwnPropertyDescriptor(typedArrayPrototype, 'byteLength')?.get;
+const typedArrayNameGetter_ = Object.getOwnPropertyDescriptor(typedArrayPrototype, Symbol.toStringTag)?.get;
+const mapSizeGetter_ = Object.getOwnPropertyDescriptor(Map.prototype, 'size')?.get;
+/* eslint-enable @typescript-eslint/unbound-method */
+if (typedArrayByteLengthGetter_ === undefined ||
+    typedArrayNameGetter_ === undefined ||
+    mapSizeGetter_ === undefined) {
+    throw new Error('Required built-in collection accessors are unavailable');
+}
+const typedArrayByteLengthGetter = typedArrayByteLengthGetter_;
+const typedArrayNameGetter = typedArrayNameGetter_;
+const mapSizeGetter = mapSizeGetter_;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- receiver supplied via Reflect.apply
+const mapEntries = Map.prototype.entries;
+const pathEncoder = new TextEncoder();
+export const DEFAULT_MATERIAL_PACKAGE_BYTE_LIMITS = Object.freeze({
+    maxFiles: MATERIAL_PACKAGE_MAX_FILES,
+    maxFileBytes: MATERIAL_PACKAGE_MAX_FILE_BYTES,
+    maxManifestBytes: MATERIAL_PACKAGE_MAX_MANIFEST_BYTES,
+    maxPackageBytes: MATERIAL_PACKAGE_MAX_BYTES,
+    maxArchiveBytes: MATERIAL_PACKAGE_MAX_ARCHIVE_BYTES,
+});
+function invalid(message) {
+    throw new TypeError(`MATERIAL_PACKAGE_INVALID: ${message}`);
+}
+function transportField(record, key) {
+    if (record === null || typeof record !== 'object')
+        invalid('package must be an object');
+    let descriptor;
+    try {
+        descriptor = Object.getOwnPropertyDescriptor(record, key);
+    }
+    catch {
+        invalid(`package field ${key} is inaccessible`);
+    }
+    if (descriptor === undefined || !('value' in descriptor)) {
+        invalid(`package field ${key} must be an own data property`);
+    }
+    return descriptor.value;
+}
+export function materialPackageBudgetExceeded(scope, actual, limit) {
+    throw new RangeError(`MATERIAL_PACKAGE_BUDGET_EXCEEDED: ${scope} is ${actual} bytes; limit is ${limit} bytes`);
+}
+function limit(name, value, maximum) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > maximum) {
+        throw new RangeError(`MATERIAL_PACKAGE_LIMIT_INVALID: ${name} must be a non-negative safe integer no greater than ${maximum}`);
+    }
+    return value;
+}
+export function resolveMaterialPackageByteLimits(options = {}) {
+    return Object.freeze({
+        maxFiles: limit('maxFiles', options.maxFiles ?? DEFAULT_MATERIAL_PACKAGE_BYTE_LIMITS.maxFiles, ZIP_UINT16_MAX),
+        maxFileBytes: limit('maxFileBytes', options.maxFileBytes ?? DEFAULT_MATERIAL_PACKAGE_BYTE_LIMITS.maxFileBytes, ZIP_UINT32_MAX),
+        maxManifestBytes: limit('maxManifestBytes', options.maxManifestBytes ?? DEFAULT_MATERIAL_PACKAGE_BYTE_LIMITS.maxManifestBytes, ZIP_UINT32_MAX),
+        maxPackageBytes: limit('maxPackageBytes', options.maxPackageBytes ?? DEFAULT_MATERIAL_PACKAGE_BYTE_LIMITS.maxPackageBytes, ZIP_UINT32_MAX),
+        maxArchiveBytes: limit('maxArchiveBytes', options.maxArchiveBytes ?? DEFAULT_MATERIAL_PACKAGE_BYTE_LIMITS.maxArchiveBytes, ZIP_UINT32_MAX),
+    });
+}
+export function addMaterialPackageBytes(total, value, scope) {
+    if (!Number.isSafeInteger(total) || total < 0 || !Number.isSafeInteger(value) || value < 0) {
+        invalid(`${scope} byte length is not a non-negative safe integer`);
+    }
+    const next = total + value;
+    if (!Number.isSafeInteger(next))
+        invalid(`${scope} byte total exceeds safe integer range`);
+    return next;
+}
+export function materialUint8ArrayByteLength(value, scope) {
+    let name;
+    let byteLength;
+    try {
+        name = Reflect.apply(typedArrayNameGetter, value, []);
+        byteLength = Reflect.apply(typedArrayByteLengthGetter, value, []);
+    }
+    catch {
+        invalid(`${scope} must be a genuine Uint8Array`);
+    }
+    if (name !== 'Uint8Array' || !Number.isSafeInteger(byteLength) || Number(byteLength) < 0) {
+        invalid(`${scope} must be a genuine Uint8Array with a safe byte length`);
+    }
+    return Number(byteLength);
+}
+export function copyMaterialBytes(value, expectedByteLength, scope) {
+    const actualByteLength = materialUint8ArrayByteLength(value, scope);
+    if (actualByteLength !== expectedByteLength)
+        invalid(`${scope} changed during snapshot`);
+    const output = new Uint8Array(actualByteLength);
+    try {
+        Uint8Array.prototype.set.call(output, value);
+    }
+    catch {
+        invalid(`${scope} could not be snapshotted`);
+    }
+    return output;
+}
+function materialMapSize(value) {
+    let size;
+    try {
+        size = Reflect.apply(mapSizeGetter, value, []);
+    }
+    catch {
+        invalid('files must be a genuine Map');
+    }
+    if (!Number.isSafeInteger(size) || Number(size) < 0)
+        invalid('files has an invalid size');
+    return Number(size);
+}
+function materialMapEntries(value) {
+    try {
+        return Reflect.apply(mapEntries, value, []);
+    }
+    catch {
+        invalid('files must be a genuine Map');
+    }
+}
+function isWellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const trailing = value.charCodeAt(index + 1);
+            if (!(trailing >= 0xdc00 && trailing <= 0xdfff))
+                return false;
+            index += 1;
+        }
+        else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            return false;
+        }
+    }
+    return true;
+}
+export function validMaterialPackagePath(path) {
+    if (typeof path !== 'string' || !isWellFormedUnicode(path))
+        return false;
+    const segments = path.split('/');
+    return (path.length > 0 &&
+        pathEncoder.encode(path).byteLength <= 512 &&
+        !path.startsWith('/') &&
+        !path.includes('\\') &&
+        !path.includes('\0') &&
+        segments.every(segment => segment.length > 0 && segment !== '.' && segment !== '..'));
+}
+export function inspectPackedMaterialPackage(packed, options = {}) {
+    const integrity = transportField(packed, 'integrity');
+    if (typeof integrity !== 'string' || !/^sha256:[0-9a-f]{64}$/u.test(integrity)) {
+        invalid('integrity must be a sha256 digest');
+    }
+    const limits = resolveMaterialPackageByteLimits(options);
+    const manifestBytes = transportField(packed, 'manifestBytes');
+    const manifestByteLength = materialUint8ArrayByteLength(manifestBytes, 'manifestBytes');
+    if (manifestByteLength > limits.maxManifestBytes) {
+        materialPackageBudgetExceeded('manifestBytes', manifestByteLength, limits.maxManifestBytes);
+    }
+    const archiveBytes = transportField(packed, 'archiveBytes');
+    const archiveByteLength = materialUint8ArrayByteLength(archiveBytes, 'archiveBytes');
+    if (archiveByteLength > limits.maxArchiveBytes) {
+        materialPackageBudgetExceeded('archiveBytes', archiveByteLength, limits.maxArchiveBytes);
+    }
+    const packedFiles = transportField(packed, 'files');
+    const size = materialMapSize(packedFiles);
+    if (size > limits.maxFiles) {
+        throw new RangeError(`MATERIAL_PACKAGE_BUDGET_EXCEEDED: package has ${size} files; limit is ${limits.maxFiles}`);
+    }
+    const files = [];
+    let packageBytes = 0;
+    for (const [path, data] of materialMapEntries(packedFiles)) {
+        if (typeof path !== 'string' || !validMaterialPackagePath(path)) {
+            invalid('unsafe file path');
+        }
+        if (path === 'signature.json')
+            invalid('signature.json is a reserved payload path');
+        const byteLength = materialUint8ArrayByteLength(data, `file ${path}`);
+        const fileLimit = path === 'manifest.json' ? limits.maxManifestBytes : limits.maxFileBytes;
+        if (byteLength > fileLimit)
+            materialPackageBudgetExceeded(`file ${path}`, byteLength, fileLimit);
+        packageBytes = addMaterialPackageBytes(packageBytes, byteLength, `file ${path}`);
+        if (packageBytes > limits.maxPackageBytes) {
+            materialPackageBudgetExceeded('package files', packageBytes, limits.maxPackageBytes);
+        }
+        files.push({ path, data: data, byteLength });
+    }
+    if (files.length !== size)
+        invalid('files changed during budget inspection');
+    return {
+        limits,
+        integrity: integrity,
+        manifestBytes,
+        manifestByteLength,
+        archiveBytes,
+        archiveByteLength,
+        files,
+        packageBytes,
+    };
+}

package/dist/package-shape.d.ts

@@ -0,0 +1,6 @@
+import type { MaterialGraph } from '@aelionsdk/material-compiler';
+import { type MaterialDefinition, type MaterialPackageManifest } from './types.js';
+export declare function assertMaterialPackageManifestShape(value: unknown): asserts value is MaterialPackageManifest;
+export declare function assertMaterialDefinitionShape(value: unknown): asserts value is MaterialDefinition;
+export declare function assertMaterialGraphShape(value: unknown): asserts value is MaterialGraph;
+//# sourceMappingURL=package-shape.d.ts.map

package/dist/package-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-shape.d.ts","sourceRoot":"","sources":["../src/package-shape.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC7B,MAAM,YAAY,CAAC;AAkapB,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,KAAK,IAAI,uBAAuB,CAsE1C;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,kBAAkB,CAuMjG;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAyCvF"}