@noeos/verification-engine 0.0.0

package/dist/esm/framing/frame-parser.js

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: Apache-2.0
+import { types } from "node:util";
+import { failure } from "../domain/operation-result.js";
+import { DiagnosticCollector } from "../validation/diagnostic-collector.js";
+import { decodeUtf8 } from "../validation/utf8-validation.js";
+const MAGIC = "NOEOSVE1";
+const HEADER_LENGTH = 13;
+const KIND_NAMES = Object.freeze({
+    1: "content",
+    2: "record",
+    3: "link",
+    4: "evidence",
+});
+const TYPE_NAMES = Object.freeze({
+    1: "bytes",
+    2: "utf8",
+    3: "uint64",
+    4: "none",
+});
+export function parseFrame(input, limits) {
+    if (types.isProxy(input) || !(input instanceof Uint8Array))
+        return frameFailure("FRAME_LENGTH_INVALID", limits);
+    if (input.length > limits.maxPayloadBytes)
+        return frameFailure("INPUT_LIMIT_EXCEEDED", limits);
+    if (input.length < HEADER_LENGTH)
+        return frameFailure("FRAME_LENGTH_INVALID", limits);
+    const view = new DataView(input.buffer, input.byteOffset, input.byteLength);
+    for (let index = 0; index < MAGIC.length; index += 1) {
+        if (view.getUint8(index) !== MAGIC.charCodeAt(index))
+            return frameFailure("FRAME_MAGIC_INVALID", limits);
+    }
+    const kind = KIND_NAMES[view.getUint8(8)];
+    if (kind === undefined)
+        return frameFailure("FRAME_KIND_UNKNOWN", limits);
+    if (view.getUint8(9) !== 0 || view.getUint8(10) !== 1)
+        return frameFailure("FRAME_VERSION_UNSUPPORTED", limits);
+    const fieldCount = view.getUint16(11);
+    let offset = HEADER_LENGTH;
+    let previousTag = 0;
+    const fields = [];
+    for (let index = 0; index < fieldCount; index += 1) {
+        if (offset + 11 > input.length)
+            return frameFailure("FRAME_LENGTH_INVALID", limits);
+        const tag = view.getUint16(offset);
+        offset += 2;
+        const expected = expectedField(kind, tag);
+        if (tag === 0 || expected === undefined)
+            return frameFailure("FRAME_FIELD_UNKNOWN", limits);
+        if (tag === previousTag)
+            return frameFailure("FRAME_FIELD_DUPLICATE", limits);
+        if (tag < previousTag)
+            return frameFailure("FRAME_FIELD_ORDER_INVALID", limits);
+        previousTag = tag;
+        const typeCode = view.getUint8(offset);
+        offset += 1;
+        const type = TYPE_NAMES[typeCode];
+        if (type === undefined)
+            return frameFailure("FRAME_FIELD_TYPE_INVALID", limits);
+        const length = readUint64(view, offset);
+        if (length === undefined)
+            return frameFailure("FRAME_LENGTH_INVALID", limits);
+        offset += 8;
+        if (length > input.length - offset)
+            return frameFailure("FRAME_LENGTH_INVALID", limits);
+        if (!expected.types.includes(type))
+            return frameFailure("FRAME_FIELD_TYPE_INVALID", limits);
+        const value = readValue(tag, type, input.subarray(offset, offset + length), limits);
+        if (!value.ok)
+            return value;
+        fields.push(value.value);
+        offset += length;
+    }
+    if (offset !== input.length)
+        return frameFailure("FRAME_TRAILING_DATA", limits);
+    const expectedFields = expectedFieldsFor(kind);
+    if (fields.length !== expectedFields.length) {
+        return frameFailure("FRAME_FIELD_MISSING", limits);
+    }
+    return {
+        ok: true,
+        value: Object.freeze({ kind, protocolVersion: 1, fields: Object.freeze(fields) }),
+        diagnostics: Object.freeze([]),
+    };
+}
+function expectedFieldsFor(kind) {
+    const text = ["utf8"];
+    const bytes = ["bytes"];
+    const uint64 = ["uint64"];
+    if (kind === "content")
+        return [
+            { tag: 1, types: text },
+            { tag: 2, types: text },
+            { tag: 3, types: text },
+            { tag: 4, types: bytes },
+        ];
+    if (kind === "record")
+        return [
+            { tag: 1, types: text },
+            { tag: 2, types: text },
+            { tag: 3, types: text },
+            { tag: 4, types: text },
+            { tag: 5, types: text },
+            { tag: 6, types: uint64 },
+            { tag: 7, types: bytes },
+        ];
+    if (kind === "link")
+        return [
+            { tag: 1, types: text },
+            { tag: 2, types: text },
+            { tag: 3, types: text },
+            { tag: 4, types: uint64 },
+            { tag: 5, types: text },
+            { tag: 6, types: bytes },
+            { tag: 7, types: ["none", "bytes"] },
+        ];
+    return [
+        { tag: 1, types: text },
+        { tag: 2, types: text },
+        { tag: 3, types: bytes },
+    ];
+}
+function expectedField(kind, tag) {
+    return expectedFieldsFor(kind).find((field) => field.tag === tag);
+}
+function readValue(tag, type, value, limits) {
+    if (type === "none") {
+        if (value.length !== 0)
+            return frameFailure("FRAME_LENGTH_INVALID", limits);
+        return { ok: true, value: { tag, type: "none" }, diagnostics: Object.freeze([]) };
+    }
+    if (type === "bytes")
+        return {
+            ok: true,
+            value: { tag, type: "bytes", value: Uint8Array.from(value) },
+            diagnostics: Object.freeze([]),
+        };
+    if (type === "utf8") {
+        const decoded = decodeUtf8(value);
+        if (!decoded.ok)
+            return frameFailure("UTF8_INVALID", limits);
+        return {
+            ok: true,
+            value: { tag, type: "utf8", value: decoded.value },
+            diagnostics: Object.freeze([]),
+        };
+    }
+    if (value.length !== 8)
+        return frameFailure("FRAME_LENGTH_INVALID", limits);
+    const number = readUint64(new DataView(value.buffer, value.byteOffset, value.byteLength), 0);
+    if (number === undefined)
+        return frameFailure("FRAME_LENGTH_INVALID", limits);
+    return {
+        ok: true,
+        value: { tag, type: "uint64", value: number },
+        diagnostics: Object.freeze([]),
+    };
+}
+function readUint64(view, offset) {
+    let value = 0n;
+    for (let index = 0; index < 8; index += 1)
+        value = (value << 8n) | BigInt(view.getUint8(offset + index));
+    if (value > BigInt(Number.MAX_SAFE_INTEGER))
+        return undefined;
+    return Number(value);
+}
+function frameFailure(code, limits) {
+    const collector = new DiagnosticCollector(limits);
+    collector.addCode(code, "input");
+    return failure(collector.finish());
+}

package/dist/esm/framing/frame-types.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/esm/hashing/hash-adapter.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { strict as assert } from "node:assert";
+import { types } from "node:util";
+import { failure, success } from "../domain/operation-result.js";
+import { DiagnosticCollector } from "../validation/diagnostic-collector.js";
+import { digestLength } from "../validation/digest-validation.js";
+import { validateAlgorithmId } from "../validation/algorithm-validation.js";
+import { Digest as DigestValue } from "../domain/digest.js";
+const NODE_ALGORITHMS = Object.freeze({
+    "sha-256": "sha256",
+    "sha-384": "sha384",
+    "sha-512": "sha512",
+});
+export function createHashSink(algorithm, limits) {
+    void limits;
+    const validated = validateAlgorithmId(algorithm);
+    if (!validated.ok)
+        return validated;
+    return success(new NodeHashSink(validated.value));
+}
+export function hashBytes(algorithm, input, limits) {
+    const sinkResult = createHashSink(algorithm, limits);
+    if (!sinkResult.ok)
+        return sinkResult;
+    if (types.isProxy(input) || !(input instanceof Uint8Array))
+        return hashFailure("INPUT_TYPE_INVALID", limits);
+    if (input.length > limits.maxPayloadBytes)
+        return hashFailure("INPUT_LIMIT_EXCEEDED", limits);
+    sinkResult.value.update(input);
+    return success(sinkResult.value.digest());
+}
+export function hashValidatedBytes(algorithm, input) {
+    const sink = new NodeHashSink(algorithm);
+    sink.update(input);
+    return success(sink.digest());
+}
+export function hashChunks(algorithm, chunks, limits) {
+    const sinkResult = createHashSink(algorithm, limits);
+    if (!sinkResult.ok)
+        return sinkResult;
+    let total = 0;
+    try {
+        for (const chunk of chunks) {
+            if (types.isProxy(chunk) || !(chunk instanceof Uint8Array))
+                return hashFailure("INPUT_TYPE_INVALID", limits);
+            if (chunk.length > limits.maxPayloadBytes - total)
+                return hashFailure("INPUT_LIMIT_EXCEEDED", limits);
+            total += chunk.length;
+            sinkResult.value.update(chunk);
+        }
+        return success(sinkResult.value.digest());
+    }
+    catch {
+        return hashFailure("NORMALIZATION_FAILED", limits);
+    }
+}
+class NodeHashSink {
+    algorithm;
+    hash;
+    finalized = false;
+    constructor(algorithm) {
+        this.algorithm = algorithm;
+        this.hash = createHash(NODE_ALGORITHMS[algorithm]);
+    }
+    update(value) {
+        if (this.finalized)
+            throw new Error("hash already finalized");
+        this.hash.update(value);
+    }
+    digest() {
+        if (this.finalized)
+            throw new Error("hash already finalized");
+        this.finalized = true;
+        const bytes = this.hash.digest();
+        assert.equal(bytes.length, digestLength(this.algorithm), "unexpected digest length");
+        return DigestValue.fromValidated(this.algorithm, bytes);
+    }
+}
+function hashFailure(code, limits) {
+    const collector = new DiagnosticCollector(limits);
+    collector.addCode(code, "input");
+    return failure(collector.finish());
+}

package/dist/esm/hashing/hash-frame.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+import { hashBytes, hashValidatedBytes } from "./hash-adapter.js";
+export function hashFrame(algorithm, frame, limits) {
+    if (!frame.ok)
+        return frame;
+    return hashBytes(algorithm, frame.value, limits);
+}
+export function hashTrustedFrame(algorithm, frame) {
+    if (!frame.ok)
+        return frame;
+    return hashValidatedBytes(algorithm, frame.value);
+}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+export { DIAGNOSTIC_CODES } from "./contracts/generated.js";
+export { createEngine, EngineConfigurationError } from "./api/engine.js";
+export { BUILTIN_PROFILES } from "./profiles.js";
+export { CHAIN_SUMMARY_EVIDENCE_SCHEMA, DIAGNOSTIC_SCHEMA, LINK_EVIDENCE_SCHEMA, RECORD_EVIDENCE_SCHEMA, } from "./api/types.js";

package/dist/esm/normalization/byte-sink.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+import { copyBytes } from "../domain/byte-view.js";
+const UTF8_ENCODER = new TextEncoder();
+export class ByteArraySink {
+    maximum;
+    buffer = new Uint8Array(0);
+    written = 0;
+    constructor(maximum, initialCapacity = 0) {
+        this.maximum = maximum;
+        if (!Number.isSafeInteger(initialCapacity) || initialCapacity < 0) {
+            throw new RangeError("invalid initial sink capacity");
+        }
+        const capacity = Math.min(maximum, Math.max(0, initialCapacity));
+        if (capacity > 0)
+            this.buffer = new Uint8Array(capacity);
+    }
+    get byteLength() {
+        return this.written;
+    }
+    write(value) {
+        this.ensureCapacity(value.length);
+        this.buffer.set(value, this.written);
+        this.written += value.length;
+    }
+    writeByte(value) {
+        if (!Number.isInteger(value) || value < 0 || value > 0xff)
+            throw new RangeError("byte value out of range");
+        this.ensureCapacity(1);
+        this.buffer[this.written++] = value;
+    }
+    writeAscii(value) {
+        this.ensureCapacity(value.length);
+        for (let index = 0; index < value.length; index += 1) {
+            const code = value.charCodeAt(index);
+            if (code > 0x7f)
+                throw new RangeError("non-ASCII value");
+            this.buffer[this.written++] = code;
+        }
+    }
+    writeText(value) {
+        this.write(UTF8_ENCODER.encode(value));
+    }
+    toBytes() {
+        return copyBytes(this.buffer.subarray(0, this.written));
+    }
+    /** Internal ownership transfer; the returned view is never exposed to callers. */
+    takeBytes() {
+        const bytes = this.buffer.subarray(0, this.written);
+        this.buffer = new Uint8Array(0);
+        this.written = 0;
+        return bytes;
+    }
+    ensureCapacity(additional) {
+        if (additional > this.maximum - this.written)
+            throw new RangeError("byte sink limit exceeded");
+        const required = this.written + additional;
+        if (required <= this.buffer.length)
+            return;
+        let capacity = Math.max(256, this.buffer.length);
+        while (capacity < required)
+            capacity = Math.min(this.maximum, capacity * 2);
+        const expanded = new Uint8Array(capacity);
+        expanded.set(this.buffer.subarray(0, this.written));
+        this.buffer = expanded;
+    }
+}

package/dist/esm/normalization/jcs-profile.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+import { ProfileId } from "../domain/identifiers.js";
+import { ProfileVersion } from "../domain/version.js";
+import { success } from "../domain/operation-result.js";
+import { validateJsonValue } from "../validation/json-value-validation.js";
+import { ByteArraySink } from "./byte-sink.js";
+const JCS_PROFILE_ID = ProfileId.fromValidated("dev.noeos.jcs");
+const JCS_PROFILE_VERSION = ProfileVersion.fromValidated("1.0.0");
+const EMPTY = "";
+export const jcsProfile = Object.freeze({
+    id: JCS_PROFILE_ID,
+    version: JCS_PROFILE_VERSION,
+    inputKind: "json",
+    validate(input, limits) {
+        return validateJsonValue(input, limits);
+    },
+    normalize(input, sink) {
+        writeValue(input, sink);
+        return success(Object.freeze({ byteLength: sink.byteLength }));
+    },
+});
+function writeValue(value, sink) {
+    if (value === null) {
+        writeAscii("null", sink);
+        return;
+    }
+    if (typeof value === "boolean") {
+        writeAscii(value ? "true" : "false", sink);
+        return;
+    }
+    if (typeof value === "number") {
+        writeText(numberToJcs(value), sink);
+        return;
+    }
+    if (typeof value === "string") {
+        writeJsonString(value, sink);
+        return;
+    }
+    if (isJsonArray(value)) {
+        writeArray(value, sink);
+        return;
+    }
+    writeObject(value, sink);
+}
+function isJsonArray(value) {
+    return Array.isArray(value);
+}
+function writeArray(value, sink) {
+    writeAscii("[", sink);
+    for (let index = 0; index < value.length; index += 1) {
+        if (index > 0)
+            writeAscii(",", sink);
+        const item = value[index];
+        if (item === undefined)
+            throw new TypeError("invalid JSON array");
+        writeValue(item, sink);
+    }
+    writeAscii("]", sink);
+}
+function writeObject(value, sink) {
+    const keys = Object.keys(value).sort(compareUtf16);
+    writeAscii("{", sink);
+    let first = true;
+    for (const key of keys) {
+        if (!first)
+            writeAscii(",", sink);
+        first = false;
+        const item = value[key];
+        if (item === undefined)
+            throw new TypeError("invalid JSON object");
+        writeJsonString(key, sink);
+        writeAscii(":", sink);
+        writeValue(item, sink);
+    }
+    writeAscii("}", sink);
+}
+function writeJsonString(value, sink) {
+    let escaped = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit <= 0x1f || codeUnit === 0x22 || codeUnit === 0x5c) {
+            escaped = true;
+            break;
+        }
+    }
+    if (!escaped) {
+        writeAscii('"', sink);
+        writeText(value, sink);
+        writeAscii('"', sink);
+        return;
+    }
+    writeText(stringToJcs(value), sink);
+}
+function stringToJcs(value) {
+    let output = '"';
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        switch (codeUnit) {
+            case 0x08:
+                output += "\\b";
+                break;
+            case 0x09:
+                output += "\\t";
+                break;
+            case 0x0a:
+                output += "\\n";
+                break;
+            case 0x0c:
+                output += "\\f";
+                break;
+            case 0x0d:
+                output += "\\r";
+                break;
+            case 0x22:
+                output += '\\"';
+                break;
+            case 0x5c:
+                output += "\\\\";
+                break;
+            default:
+                if (codeUnit <= 0x1f)
+                    output += `\\u${codeUnit.toString(16).padStart(4, "0")}`;
+                else
+                    output += value.charAt(index);
+        }
+    }
+    return `${output}"`;
+}
+function numberToJcs(value) {
+    if (Object.is(value, -0))
+        return "0";
+    if (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))) {
+        throw new TypeError("invalid JSON number");
+    }
+    return JSON.stringify(value);
+}
+function writeText(value, sink) {
+    if (sink instanceof ByteArraySink)
+        sink.writeText(value);
+    else
+        sink.write(new TextEncoder().encode(value));
+}
+function writeAscii(value, sink) {
+    if (sink instanceof ByteArraySink)
+        sink.writeAscii(value);
+    else
+        sink.write(new TextEncoder().encode(value || EMPTY));
+}
+function compareUtf16(left, right) {
+    return left < right ? -1 : 1;
+}

package/dist/esm/normalization/normalize.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+import { failure } from "../domain/operation-result.js";
+import { ByteArraySink } from "./byte-sink.js";
+import { DiagnosticCollector } from "../validation/diagnostic-collector.js";
+export function normalizeToBytes(profile, input, limits) {
+    const validated = profile.validate(input, limits);
+    if (!validated.ok)
+        return validated;
+    const sink = new ByteArraySink(limits.maxPayloadBytes, initialCapacity(input));
+    try {
+        const normalized = profile.normalize(validated.value, sink, limits);
+        if (!normalized.ok)
+            return normalized;
+        if (normalized.value.byteLength !== sink.byteLength)
+            return normalizationFailure(limits);
+        const bytes = sink.takeBytes();
+        return {
+            ok: true,
+            value: Object.freeze({ bytes, stats: normalized.value }),
+            diagnostics: normalized.diagnostics,
+        };
+    }
+    catch {
+        return normalizationFailure(limits);
+    }
+}
+export function normalizeRegisteredToBytes(profile, input, limits) {
+    const sink = new ByteArraySink(limits.maxPayloadBytes, initialCapacity(input));
+    try {
+        const normalized = (profile.normalizeValidated ?? profile.normalize)(input, sink, limits);
+        if (!normalized.ok)
+            return normalized;
+        if (normalized.value.byteLength !== sink.byteLength)
+            return normalizationFailure(limits);
+        return {
+            ok: true,
+            value: Object.freeze({ bytes: sink.takeBytes(), stats: normalized.value }),
+            diagnostics: normalized.diagnostics,
+        };
+    }
+    catch {
+        return normalizationFailure(limits);
+    }
+}
+function normalizationFailure(limits) {
+    const collector = new DiagnosticCollector(limits);
+    collector.addCode("NORMALIZATION_FAILED", "normalization");
+    return failure(collector.finish());
+}
+function initialCapacity(input) {
+    return input instanceof Uint8Array ? input.length : 0;
+}

package/dist/esm/normalization/profile-registry.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+import { failure, success } from "../domain/operation-result.js";
+import { createDiagnostic } from "../validation/diagnostic-collector.js";
+import { jcsProfile } from "./jcs-profile.js";
+import { rawBytesProfile } from "./raw-bytes-profile.js";
+export class ProfileRegistry {
+    profiles = new Map();
+    constructor(additional = []) {
+        this.registerBuiltin(rawBytesProfile);
+        this.registerBuiltin(jcsProfile);
+        for (const profile of additional) {
+            const result = this.register(profile);
+            if (!result.ok)
+                throw new Error("profile registration conflict");
+        }
+    }
+    register(profile) {
+        const key = profileKey(profile.id, profile.version);
+        if (this.profiles.has(key)) {
+            return failure([createDiagnostic("PROFILE_VERSION_CONFLICT", "input")]);
+        }
+        this.profiles.set(key, eraseProfile(profile));
+        return success(undefined);
+    }
+    resolve(id, version) {
+        const profile = this.profiles.get(profileKey(id, version));
+        if (profile === undefined)
+            return failure([createDiagnostic("PROFILE_UNKNOWN", "input")]);
+        return success(profile);
+    }
+    resolveValidated(reference) {
+        const profile = this.profiles.get(`${reference.id}\u0000${reference.version}`);
+        if (profile === undefined)
+            return failure([createDiagnostic("PROFILE_UNKNOWN", "input")]);
+        return success(profile);
+    }
+    registerBuiltin(profile) {
+        this.profiles.set(profileKey(profile.id, profile.version), eraseProfile(profile));
+    }
+}
+function eraseProfile(profile) {
+    return Object.freeze({
+        id: profile.id,
+        version: profile.version,
+        inputKind: profile.inputKind,
+        validate: (input, limits) => profile.validate(input, limits),
+        normalize: (input, sink, limits) => {
+            const validated = profile.validate(input, limits);
+            if (!validated.ok)
+                return validated;
+            return profile.normalize(validated.value, sink, limits);
+        },
+        normalizeValidated: (input, sink, limits) => {
+            // The record service invokes this only after the profile validator succeeds.
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- erased generic at the trusted registry boundary
+            return profile.normalize(input, sink, limits);
+        },
+    });
+}
+function profileKey(id, version) {
+    return `${id.value}\u0000${version.value}`;
+}

package/dist/esm/normalization/profile.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/esm/normalization/raw-bytes-profile.js

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+import { types } from "node:util";
+import { ProfileId } from "../domain/identifiers.js";
+import { ProfileVersion } from "../domain/version.js";
+import { success } from "../domain/operation-result.js";
+import { failureWithCode } from "../validation/result-helpers.js";
+const RAW_PROFILE_ID = ProfileId.fromValidated("dev.noeos.raw-bytes");
+const RAW_PROFILE_VERSION = ProfileVersion.fromValidated("1.0.0");
+export const rawBytesProfile = Object.freeze({
+    id: RAW_PROFILE_ID,
+    version: RAW_PROFILE_VERSION,
+    inputKind: "bytes",
+    validate(input, limits) {
+        if (types.isProxy(input) || !(input instanceof Uint8Array))
+            return failureWithCode("INPUT_TYPE_INVALID", "input");
+        if (input.length > limits.maxPayloadBytes)
+            return failureWithCode("INPUT_LIMIT_EXCEEDED", "input");
+        return success(input);
+    },
+    normalize(input, sink) {
+        sink.write(input);
+        return success(Object.freeze({ byteLength: input.length }));
+    },
+});

package/dist/esm/profiles.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+/** @public */
+export const BUILTIN_PROFILES = Object.freeze([
+    Object.freeze({ id: "dev.noeos.raw-bytes", version: "1.0.0", inputKind: "bytes" }),
+    Object.freeze({ id: "dev.noeos.jcs", version: "1.0.0", inputKind: "json" }),
+]);