Chore/base configurations

source/parser/ajv/ajv-types.ts

@@ -0,0 +1,33 @@
+/**
+ * This code is inspired by and adapted from:
+ * https://github.com/bitauth/libauth
+ */
+export type AjvError<Keyword = string, Params = { [paramName: string]: number | string }> = {
+    keyword: Keyword;
+    instancePath: string;
+    schemaPath: string;
+    params: Params;
+    message: string;
+};
+
+export type XOAjvError =
+    | AjvError<'additionalProperties', { additionalProperty: string }>
+    | AjvError<'required', { missingProperty: string }>
+    | AjvError<'type', { type: string }>;
+
+/**
+ * Note: these types cover only XO use cases; other `ajv` error types are
+ * possible using other settings.
+ */
+export type AjvValidator<T = unknown> = {
+    (
+        data: unknown,
+        dataCxt?: {
+            instancePath?: string;
+            parentData: unknown;
+            parentDataProperty: unknown;
+            rootData?: unknown;
+        },
+    ): data is T;
+    errors?: XOAjvError[] | null;
+};

source/parser/ajv/ajv-utils.ts

@@ -0,0 +1,60 @@
+/**
+ * This code is inspired from https://github.com/bitauth/libauth
+ */
+
+import { lossyNormalize } from '@bitauth/libauth';
+import type { AjvValidator, XOAjvError } from './ajv-types.ts';
+import { FailedToParseTemplateError } from '../../errors.ts';
+
+const errorsToDescription = (errors: XOAjvError[]): string => {
+    // TODO: translate instancePath and make errors more descriptive.
+
+    const descriptions = errors.map((error) => `${error.instancePath}: ${error.message}`).join(',');
+
+    return descriptions;
+};
+
+/**
+ * Given an untrusted JSON string or object, verify that
+ * the untrusted value is of the expected shape. Note, this method first
+ * normalizes all characters in the input using `Normalization Form KC`
+ * (Compatibility Decomposition, followed by Canonical Composition).
+ *
+ * @param {unknown} jsonOrObject - The JSON string or object to parse
+ * @returns {T} The parsed object
+ * @throws {FailedToParseTemplateError} If JSON parsing fails
+ */
+export const parseJson = <T>(jsonOrObject: unknown): T => {
+    try {
+        // If the JSON object is a string, use it directly.
+        const stringified = typeof jsonOrObject === 'string' ? jsonOrObject : JSON.stringify(jsonOrObject);
+
+        // Normalize the JSON string using `Normalization Form KC` (Compatibility Decomposition, followed by Canonical Composition).
+        const normalized = lossyNormalize(stringified);
+
+        // Parse the normalized JSON string into the expected type.
+        const parsed = JSON.parse(normalized);
+
+        // Return the parsed object.
+        return parsed;
+    } catch (error) {
+        // Error wrapping. If the JSON parsing fails, throw an error.
+        throw new FailedToParseTemplateError(error instanceof Error ? error.message : String(error));
+    }
+};
+
+/**
+ * Validates a parsed object against an AJV schema.
+ *
+ * @param parsed - The parsed object to validate
+ * @param validator - The AJV validator function
+ * @returns The validated object if valid, or an error message string if invalid
+ */
+export const validateSchema = <T>(parsed: unknown, validator: AjvValidator<T>): T | string => {
+    if (validator(parsed)) {
+        return parsed;
+    }
+
+    // If the object is invalid, return the error message.
+    return errorsToDescription(validator.errors ?? []);
+};

source/parser/xo-template.ts

@@ -0,0 +1,51 @@
+/**
+ * This code is inspired by and adapted from:
+ * https://github.com/bitauth/libauth
+ */
+
+import type { XOTemplate } from '@xo-cash/types';
+import type { AjvValidator } from './ajv/ajv-types.ts';
+import { parseJson, validateSchema } from './ajv/ajv-utils.ts';
+import { InvalidTemplateError } from '../errors.ts';
+import xoTemplateValidator from './ajv/validate-xo-template.js';
+
+/**
+ * Safely parse and validate a XO template, returning either an
+ * error message as a string or a valid {@link XOTemplate}. The
+ * template may be provided either as an untrusted JSON string or as a
+ * pre-parsed object.
+ *
+ * This method validates both the structure and the contents of a template:
+ * - All properties and sub-properties are verified to be of the expected type.
+ * - The template contains no unknown properties.
+ * - The ID of each entity, script, and scenario is confirmed to be unique.
+ * - Script IDs referenced by entities and other scripts (via `unlocks`) are
+ *   confirmed to exist.
+ * - The derivation paths of each HdKey are validated against each other.
+ *
+ * This method does not perform the following:
+ * - TODO: Validate the CashAssembly contents of scripts (by
+ * attempting compilation, evaluating {@link XOTemplateScriptTest}s,
+ * or testing scenario generation).
+ * - TODO: Perform search to verify references.
+ *
+ * @param {unknown} untrustedJsonOrObject - the JSON string or object to validate as a
+ * XO template
+ * @returns {XOTemplate} The parsed and validated template
+ * @throws {InvalidTemplateError} If the template is invalid
+ */
+export const parseTemplate = (untrustedJsonOrObject: unknown): XOTemplate => {
+    // Parse the JSON string or object into an unknown object.
+    const parsed = parseJson<unknown>(untrustedJsonOrObject);
+
+    // Validate the unknown object against the XO template schema.
+    const templateOrError = validateSchema(parsed, xoTemplateValidator as AjvValidator<XOTemplate>);
+
+    // If the template is invalid, throw an error.
+    if (typeof templateOrError === 'string') {
+        throw new InvalidTemplateError(templateOrError);
+    }
+
+    // Return the validated template.
+    return templateOrError;
+};