@uwmd/core 1.7.0 → 1.9.0

package/dist/module-runtime.js

@@ -0,0 +1,167 @@
+// Module runtime: actually *running* what a module manifest declares.
+//
+// Until now the module system registered manifests and stopped there. A
+// manifest's `calculations` were reachable only by a host that pulled them out
+// and evaluated them itself; its `validations` were shape-checked at load and
+// then never executed by anything; its `sections` were declared and never
+// looked for. Every assumption in the types was unverified, because nothing
+// consumed them (RFC 0006 §Motivation).
+//
+// This file is the consumer. Three functions, in dependency order:
+//
+//   evaluateModuleCalculations  — the module's calcs, in declaration order,
+//                                 each seeing the ones before it
+//   checkModuleSections         — declared `required: true` sections present
+//   validateAgainstModules      — the module's `validations`, plus the above
+//
+// **No new evaluation machinery.** A validation `rule` is a safe expression in
+// exactly the §VIII.1 grammar the calc engine already parses, so it runs
+// through `evaluateCalc` like any other declaration. A module that could
+// evaluate rules the calc engine cannot would be a second, unsandboxed
+// expression language reachable from a third-party manifest, which is the one
+// thing the module system must never become.
+import { evaluateCalc } from './calc/index.js';
+/**
+ * Evaluate every calculation the applicable modules declare, in declaration
+ * order, threading each result into the next as `prior_results`.
+ *
+ * Order matters and is the manifest's: `revpar_index` divides by `revpar`, so
+ * `revpar` must already be in `prior_results` when it runs. Sorting or
+ * parallelizing would break that for no gain — and a module author who orders
+ * their declarations wrongly gets a `CALC-REF` error naming the missing id,
+ * which is a better failure than a silent `null`.
+ */
+export function evaluateModuleCalculations(parsed, registry, options = {}) {
+    const outcomes = [];
+    const prior = {};
+    for (const manifest of applicableModules(parsed, registry, options)) {
+        for (const decl of manifest.calculations ?? []) {
+            const result = evaluateCalc(decl, { parsed, prior_results: prior, locale: 'en-US' });
+            outcomes.push({ module_id: manifest.id, result });
+            // Only successful results are published. This is principle rather than
+            // effect: an unresolved identifier already evaluates to `null` (§VIII.2),
+            // so a dependent sees `null` either way — but presenting a failed
+            // computation's value as a value is a different claim, and one this
+            // runtime should never make.
+            //
+            // The effect the null-propagation DOES have is that a broken calc
+            // degrades its dependents to `null`, which is indistinguishable from
+            // "inputs absent". `validateAgainstModules` reports the original failure
+            // as `MOD-CALC-ERROR` precisely so the cause is visible; without that,
+            // one typo in a formula quietly disables every rule downstream of it.
+            if (result.ok)
+                prior[decl.id] = result.value;
+        }
+    }
+    return outcomes;
+}
+/**
+ * Run the applicable modules' `validations` and section requirements.
+ *
+ * A rule is an assertion of what must be TRUE. It fires an issue when it
+ * evaluates to `false` — and, deliberately, **not** when it evaluates to
+ * `null`. Null is the calc engine's "the inputs are absent", and a document
+ * that simply does not carry `hotel_brand` has not violated a rule about
+ * franchise fees; it has said nothing about them. Reporting absence as
+ * violation would make every module rule fire on every partial file, which is
+ * most files most of the time.
+ *
+ * A rule that fails to *evaluate* — an unknown function, an unusable argument —
+ * is reported under `MOD-RULE-ERROR` rather than swallowed, and a module
+ * *calculation* that fails is reported under `MOD-CALC-ERROR`. A silently
+ * skipped rule is a rule the author believes is protecting them.
+ */
+export function validateAgainstModules(parsed, registry, options = {}) {
+    const issues = [];
+    const modules = applicableModules(parsed, registry, options);
+    for (const manifest of modules) {
+        issues.push(...checkModuleSections(parsed, manifest));
+    }
+    const prior = {};
+    for (const { module_id, result } of evaluateModuleCalculations(parsed, registry, options)) {
+        if (result.ok) {
+            prior[result.calc_id] = result.value;
+            continue;
+        }
+        // A module calc that cannot evaluate is reported, not just skipped. Its
+        // dependents will resolve to `null` and their rules will fall silent, so
+        // this issue is often the only trace that anything went wrong.
+        issues.push({
+            code: 'MOD-CALC-ERROR',
+            severity: 'error',
+            message: `Module '${module_id}' calculation '${result.calc_id}' failed to evaluate: [${result.error?.code}] ${result.error?.message}`,
+            remediation: `Fix the formula in '${module_id}'. Any rule that reads '${result.calc_id}' is silently inconclusive until it is corrected.`,
+        });
+    }
+    for (const manifest of modules) {
+        for (const rule of manifest.validations ?? []) {
+            issues.push(...runRule(parsed, manifest, rule, prior));
+        }
+    }
+    return issues;
+}
+/**
+ * Sections a module declares `required: true` must be present.
+ *
+ * Only presence. Validating a section's contents against its declared JSON
+ * Schema would need a JSON Schema validator, and `@uwmd/core` takes no such
+ * dependency — see the layering invariant. The schema in the manifest is
+ * normative and a host that already has a validator SHOULD apply it; core
+ * checks the part it can check honestly rather than shipping a
+ * half-implemented subset of JSON Schema that quietly accepts what a real
+ * validator would reject.
+ */
+export function checkModuleSections(parsed, manifest) {
+    const issues = [];
+    for (const section of manifest.sections ?? []) {
+        if (!section.required)
+            continue;
+        if (parsed.sections[section.id] === undefined) {
+            issues.push({
+                code: 'MOD-SECTION-MISSING',
+                severity: 'error',
+                section: section.id,
+                message: `Module '${manifest.id}' requires section '${section.id}' (${section.display_name}), which is missing.`,
+                remediation: `Add a '${section.id}' block, or stop loading '${manifest.id}' for this document.`,
+            });
+        }
+    }
+    return issues;
+}
+function runRule(parsed, manifest, rule, prior) {
+    const result = evaluateCalc({ id: rule.code, label: rule.code, formula: rule.rule, deterministic: true }, { parsed, prior_results: prior, locale: 'en-US' });
+    if (!result.ok) {
+        return [
+            {
+                code: 'MOD-RULE-ERROR',
+                severity: 'error',
+                message: `Module '${manifest.id}' rule '${rule.code}' failed to evaluate: [${result.error?.code}] ${result.error?.message}`,
+                remediation: `Fix the rule expression in '${manifest.id}', or stop loading the module until it is corrected.`,
+            },
+        ];
+    }
+    // Absent inputs (`null`) are not violations — see the doc comment above.
+    if (result.value !== false)
+        return [];
+    return [
+        {
+            code: rule.code,
+            severity: rule.severity,
+            message: rule.message,
+            // Named so a reader can tell a module's finding from a built-in one
+            // without memorizing which prefixes belong to whom.
+            remediation: `Reported by module '${manifest.id}'.`,
+        },
+    ];
+}
+/**
+ * Modules that apply to this document: those declaring its asset class, plus
+ * those declaring none at all (which a manifest uses to mean "any class").
+ */
+function applicableModules(parsed, registry, options) {
+    const assetClass = options.assetClass ?? parsed.frontmatter?.asset_class;
+    return registry.modules.filter((m) => m.asset_classes === undefined ||
+        m.asset_classes.length === 0 ||
+        (assetClass !== undefined && m.asset_classes.includes(assetClass)));
+}
+//# sourceMappingURL=module-runtime.js.map

package/dist/module-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-runtime.js","sourceRoot":"","sources":["../src/module-runtime.ts"],"names":[],"mappings":"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"}

package/dist/module-signing.d.ts

@@ -0,0 +1,85 @@
+import type { ModuleManifest, ModuleSignature, ProtocolError } from './protocol.js';
+/** The one scheme protocol 1.x implements. See `ModuleSignature.scheme`. */
+export declare const MODULE_SIGNATURE_SCHEME: "uwmd-keystore";
+/**
+ * The exact bytes a module signature covers: RFC 8785 canonical JSON of the
+ * manifest with `signature` removed.
+ *
+ * Removed rather than nulled, so that signing a manifest and then verifying it
+ * produce byte-identical input — the failure mode where a signature verifies
+ * before it is attached and not after.
+ */
+export declare function moduleSigningPayload(manifest: ModuleManifest): string;
+export type ModuleSignatureFailure = 
+/** The manifest carries no `signature` at all. */
+'missing'
+/** `scheme` names something this verifier does not implement. */
+ | 'unsupported_scheme'
+/** `signature` is present but structurally invalid. */
+ | 'malformed'
+/** `kid` names a key the host's store does not hold. */
+ | 'unknown_key'
+/** The signature did not validate over the canonical manifest. */
+ | 'invalid';
+export type ModuleSignatureVerdict = {
+    ok: true;
+    kid: string;
+    identity?: string;
+} | {
+    ok: false;
+    reason: ModuleSignatureFailure;
+    error: ProtocolError;
+};
+/**
+ * Supplied by `@uwmd/signing`. Mirrors `BlockSignatureVerifier` rather than
+ * reusing it, because a module signature carries a `scheme` a block signature
+ * has no concept of; collapsing them would mean one of the two lies about its
+ * input.
+ */
+export interface ModuleSignatureVerifier {
+    verify(payload: string, signature: ModuleSignature): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: 'unknown_kid' | 'bad_signature' | 'malformed';
+    }>;
+}
+export interface VerifyModuleSignatureOptions {
+    /** Without one, only the structural checks run and the verdict is `malformed`-or-better. */
+    verifier?: ModuleSignatureVerifier;
+    /**
+     * Identity allow-list. When set, a valid signature whose `identity` is absent
+     * or unlisted is refused.
+     *
+     * Note what this can and cannot do: `identity` is a claim inside the signed
+     * bytes, so a signature proves the *key holder* asserted it, never that the
+     * assertion is true. It is only as good as the host's decision to bind that
+     * `kid` to that identity in its key store.
+     */
+    allowedIdentities?: readonly string[];
+}
+/**
+ * Verify a module manifest's signature.
+ *
+ * The three refusals a host must keep apart are `missing` (nothing was
+ * claimed), `unknown_key` (something was claimed and this host cannot check
+ * it), and `invalid` (something was claimed and it is false). They call for
+ * three different responses — decide a policy, load a key, reject the module —
+ * and a verifier that reports them as one verdict makes all three
+ * indistinguishable at the point where the host has to act.
+ */
+export declare function verifyModuleSignature(manifest: ModuleManifest, options?: VerifyModuleSignatureOptions): Promise<ModuleSignatureVerdict>;
+/**
+ * Structural checks, run before any cryptography.
+ *
+ * Separated out because they are the part a host can run with no key store at
+ * all, and because a malformed signature deserves its own code: telling an
+ * author "this did not verify" when the real problem is a missing `signed_at`
+ * sends them looking for tampering that never happened.
+ */
+export declare function checkSignatureShape(signature: unknown): {
+    ok: false;
+    reason: ModuleSignatureFailure;
+    error: ProtocolError;
+} | null;
+//# sourceMappingURL=module-signing.d.ts.map

package/dist/module-signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-signing.d.ts","sourceRoot":"","sources":["../src/module-signing.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGpF,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,EAAG,eAAwB,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAGrE;AAID,MAAM,MAAM,sBAAsB;AAChC,kDAAkD;AAChD,SAAS;AACX,iEAAiE;GAC/D,oBAAoB;AACtB,uDAAuD;GACrD,WAAW;AACb,wDAAwD;GACtD,aAAa;AACf,kEAAkE;GAChE,SAAS,CAAC;AAEd,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAExE;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,eAAe,GACzB,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,aAAa,GAAG,eAAe,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC;CACjG;AAED,MAAM,WAAW,4BAA4B;IAC3C,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAsCD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,sBAAsB,CAAC,CA+CjC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,OAAO,GACjB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAAG,IAAI,CAmC5E"}

package/dist/module-signing.js

@@ -0,0 +1,136 @@
+// Module manifest signatures (protocol §X.1, RFC 0002).
+//
+// A module manifest is executable surface: it declares calculations whose
+// formulas the calc engine evaluates and validations that can flip a deal from
+// blocking to advisory. A host that loads one from npm, a URL, or a colleague's
+// directory has, without this, no way to ask "is this the manifest the author
+// published?"
+//
+// The layering is the same one block signatures use, for the same reason. Core
+// owns the crypto-free half — the canonical bytes a signature covers, the
+// structural checks, and the verdict taxonomy — while the algorithms live in
+// `@uwmd/signing` and arrive through an injected verifier. Reading and loading a
+// module must never require cryptography.
+//
+// Advisory by design: the protocol fixes what "signature valid" *means* so two
+// hosts agree, and leaves what to *do* about an unsigned or invalid module to
+// host policy (§X.1.4).
+import { canonicalizeExact } from './integrity-canonical.js';
+import { UW_SIGNATURE_ALGORITHMS } from './types.js';
+/** The one scheme protocol 1.x implements. See `ModuleSignature.scheme`. */
+export const MODULE_SIGNATURE_SCHEME = 'uwmd-keystore';
+/**
+ * The exact bytes a module signature covers: RFC 8785 canonical JSON of the
+ * manifest with `signature` removed.
+ *
+ * Removed rather than nulled, so that signing a manifest and then verifying it
+ * produce byte-identical input — the failure mode where a signature verifies
+ * before it is attached and not after.
+ */
+export function moduleSigningPayload(manifest) {
+    const { signature: _omitted, ...rest } = manifest;
+    return canonicalizeExact(rest);
+}
+const CODES = {
+    missing: 'PROTO-MOD-068',
+    unsupported_scheme: 'PROTO-MOD-069',
+    malformed: 'PROTO-MOD-070',
+    unknown_key: 'PROTO-MOD-071',
+    invalid: 'PROTO-MOD-072',
+};
+const REMEDIATIONS = {
+    missing: 'Sign the manifest, or relax the host policy to accept unsigned modules (signatures are advisory at the protocol level).',
+    unsupported_scheme: `Re-sign under the '${MODULE_SIGNATURE_SCHEME}' scheme, or use a host that implements the named scheme.`,
+    malformed: 'Re-sign the manifest; the signature object is not a well-formed ModuleSignature.',
+    unknown_key: 'Add the signing key to the host key store under that kid, or re-sign with a key the host trusts.',
+    invalid: 'The manifest changed after it was signed. Restore the published manifest, or re-sign the version you intend to ship.',
+};
+function fail(reason, message) {
+    return {
+        ok: false,
+        reason,
+        error: {
+            category: 'module',
+            code: CODES[reason],
+            message,
+            pointer: 'signature',
+            remediation: REMEDIATIONS[reason],
+        },
+    };
+}
+/**
+ * Verify a module manifest's signature.
+ *
+ * The three refusals a host must keep apart are `missing` (nothing was
+ * claimed), `unknown_key` (something was claimed and this host cannot check
+ * it), and `invalid` (something was claimed and it is false). They call for
+ * three different responses — decide a policy, load a key, reject the module —
+ * and a verifier that reports them as one verdict makes all three
+ * indistinguishable at the point where the host has to act.
+ */
+export async function verifyModuleSignature(manifest, options = {}) {
+    const signature = manifest.signature;
+    if (signature === undefined) {
+        return fail('missing', `Module '${manifest.id}' carries no signature.`);
+    }
+    const structural = checkSignatureShape(signature);
+    if (structural)
+        return structural;
+    if (!options.verifier) {
+        return fail('unknown_key', `Module '${manifest.id}' is signed by key '${signature.kid}', but this host has no signature backend to check it with.`);
+    }
+    const verdict = await options.verifier.verify(moduleSigningPayload(manifest), signature);
+    if (!verdict.ok) {
+        if (verdict.reason === 'unknown_kid') {
+            return fail('unknown_key', `Module '${manifest.id}' is signed by key '${signature.kid}', which this host's key store does not hold.`);
+        }
+        return fail('invalid', `Module '${manifest.id}' signature did not verify (${verdict.reason}).`);
+    }
+    if (options.allowedIdentities) {
+        const identity = signature.identity;
+        if (identity === undefined || !options.allowedIdentities.includes(identity)) {
+            return fail('invalid', `Module '${manifest.id}' is validly signed by '${signature.kid}' but its identity ${identity === undefined ? 'is absent' : `'${identity}' is not`} on this host's allow-list.`);
+        }
+    }
+    return {
+        ok: true,
+        kid: signature.kid,
+        ...(signature.identity !== undefined ? { identity: signature.identity } : {}),
+    };
+}
+/**
+ * Structural checks, run before any cryptography.
+ *
+ * Separated out because they are the part a host can run with no key store at
+ * all, and because a malformed signature deserves its own code: telling an
+ * author "this did not verify" when the real problem is a missing `signed_at`
+ * sends them looking for tampering that never happened.
+ */
+export function checkSignatureShape(signature) {
+    if (typeof signature !== 'object' || signature === null || Array.isArray(signature)) {
+        return fail('malformed', 'signature must be an object.');
+    }
+    const sig = signature;
+    if (sig['scheme'] !== MODULE_SIGNATURE_SCHEME) {
+        return fail('unsupported_scheme', `signature.scheme must be '${MODULE_SIGNATURE_SCHEME}' (got ${JSON.stringify(sig['scheme'])}).`);
+    }
+    if (typeof sig['alg'] !== 'string' ||
+        !UW_SIGNATURE_ALGORITHMS.includes(sig['alg'])) {
+        return fail('malformed', `signature.alg must be one of ${UW_SIGNATURE_ALGORITHMS.join(', ')}.`);
+    }
+    for (const key of ['kid', 'sig', 'signed_at']) {
+        if (typeof sig[key] !== 'string' || sig[key].length === 0) {
+            return fail('malformed', `signature.${key} must be a non-empty string.`);
+        }
+    }
+    if (sig['identity'] !== undefined && typeof sig['identity'] !== 'string') {
+        return fail('malformed', 'signature.identity, when present, must be a string.');
+    }
+    for (const key of Object.keys(sig)) {
+        if (!['scheme', 'alg', 'kid', 'sig', 'signed_at', 'identity'].includes(key)) {
+            return fail('malformed', `signature has unknown key '${key}'.`);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=module-signing.js.map

package/dist/module-signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-signing.js","sourceRoot":"","sources":["../src/module-signing.ts"],"names":[],"mappings":"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"}

package/dist/modules.d.ts

@@ -1,4 +1,5 @@
 import { type ModuleLoadResult, type ModuleManifest, type ProtocolError, type ViewerTier } from './protocol.js';
+import { type ModuleSignatureVerifier } from './module-signing.js';
 export interface ModuleRegistry {
     modules: readonly ModuleManifest[];
     byId: ReadonlyMap<string, ModuleManifest>;
@@ -11,14 +12,55 @@ export interface LoadModuleOptions {
     formatVersion?: string;
     alreadyLoaded?: readonly ModuleManifest[];
 }
+/**
+ * What a host does about module signatures (§X.1.4, RFC 0002).
+ *
+ * - `ignore` — do not look. The default, and what every host did before RFC
+ *   0002; a signature is carried through untouched.
+ * - `verify-if-present` — an unsigned module loads, but a *bad* signature
+ *   refuses. The pragmatic setting during adoption: it never punishes an
+ *   author who has not signed yet, and never lets a broken claim through.
+ * - `require` — an unsigned module refuses too.
+ *
+ * `verify-if-present` and `require` both refuse on `unknown_key`, and that is
+ * deliberate: a host that cannot check a signature has not established the
+ * module is safe, and treating "I have no key for this" as success would make
+ * the whole policy decorative.
+ */
+export type ModuleSignaturePolicy = 'ignore' | 'verify-if-present' | 'require';
+export interface LoadModuleAsyncOptions extends LoadModuleOptions {
+    /** Defaults to `ignore`. */
+    signaturePolicy?: ModuleSignaturePolicy;
+    /** Supplied by `@uwmd/signing`. Absent under a checking policy means every signed module refuses. */
+    signatureVerifier?: ModuleSignatureVerifier;
+    /** Optional identity allow-list; see `VerifyModuleSignatureOptions`. */
+    allowedIdentities?: readonly string[];
+}
 export interface CreateModuleRegistryOptions extends LoadModuleOptions {
     modules: readonly ModuleManifest[];
 }
+export interface CreateModuleRegistryAsyncOptions extends LoadModuleAsyncOptions {
+    modules: readonly ModuleManifest[];
+}
 export declare class ModuleRegistryError extends Error {
     readonly errors: readonly ProtocolError[];
     constructor(errors: readonly ProtocolError[]);
 }
 export declare function loadModuleManifest(candidate: unknown, opts?: LoadModuleOptions): ModuleLoadResult;
+/**
+ * `loadModuleManifest` plus a signature-policy gate.
+ *
+ * Separate and async for the same reason `applyEditAsync` is: verification
+ * needs Web Crypto, which is async, and the synchronous loader is on a path
+ * plenty of hosts call where signatures are none of their business. A host that
+ * does not check signatures keeps the sync function and pays nothing.
+ *
+ * Structural validation runs first regardless of policy — a manifest that is
+ * not a valid manifest should say so, not report a signature problem.
+ */
+export declare function loadModuleManifestAsync(candidate: unknown, opts?: LoadModuleAsyncOptions): Promise<ModuleLoadResult>;
+/** `createModuleRegistry` with the same signature-policy gate. */
+export declare function createModuleRegistryAsync(opts: CreateModuleRegistryAsyncOptions): Promise<ModuleRegistry>;
 export declare function createModuleRegistry(opts: CreateModuleRegistryOptions): ModuleRegistry;
 export declare function getModuleCalculationsForAssetClass(registry: ModuleRegistry, asset_class: string): import("./protocol.js").ModuleCalcDecl[];
 //# sourceMappingURL=modules.d.ts.map

package/dist/modules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modules.d.ts","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAgEvB,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC,CAAC;IAC7D,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;CACjE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,2BAA4B,SAAQ,iBAAiB;IACpE,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;gBAE9B,MAAM,EAAE,SAAS,aAAa,EAAE;CAK7C;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,OAAO,EAClB,IAAI,GAAE,iBAAsB,GAC3B,gBAAgB,CAMlB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,cAAc,CAoDtF;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,MAAM,4CAKpB"}
+{"version":3,"file":"modules.d.ts","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAiE7B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC,CAAC;IAC7D,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;CACjE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,mBAAmB,GAAG,SAAS,CAAC;AAE/E,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,4BAA4B;IAC5B,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,qGAAqG;IACrG,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,2BAA4B,SAAQ,iBAAiB;IACpE,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,gCAAiC,SAAQ,sBAAsB;IAC9E,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;gBAE9B,MAAM,EAAE,SAAS,aAAa,EAAE;CAK7C;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,OAAO,EAClB,IAAI,GAAE,iBAAsB,GAC3B,gBAAgB,CAMlB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,OAAO,EAClB,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAe3B;AAED,kEAAkE;AAClE,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,cAAc,CAAC,CAWzB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,cAAc,CAoDtF;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,MAAM,4CAKpB"}

package/dist/modules.js

@@ -8,6 +8,8 @@
 import { parseExpression } from './calc/parser.js';
 import { MAX_ROUND_TO } from './calc/quantize.js';
 import { FORMAT_VERSION, PROTOCOL_VERSION, } from './protocol.js';
+import { parseAssetClass } from './asset-class.js';
+import { checkSignatureShape, verifyModuleSignature, } from './module-signing.js';
 import { ASSET_CLASSES } from './types.js';
 const TIERS = [
     'tier-1-reader',
@@ -43,7 +45,8 @@ const MANIFEST_KEYS = [
     'manifest_version', 'id', 'name', 'version', 'description', 'authors', 'license',
     'requires_protocol', 'requires_format', 'requires_tier', 'asset_classes',
     'deal_stages', 'sections', 'calculations', 'validations', 'thresholds',
-    'view_models', 'ui', 'agent_layers', 'depends_on',
+    'view_models', 'ui', 'agent_layers', 'depends_on', 'signature',
+    'declares_asset_classes',
 ];
 const SECTION_KEYS = ['id', 'display_name', 'schema', 'required'];
 const CALC_KEYS = ['id', 'label', 'formula', 'unit', 'round_to', 'deterministic'];
@@ -78,6 +81,48 @@ export function loadModuleManifest(candidate, opts = {}) {
         ? { ok: false, errors }
         : { ok: true, manifest: freezeManifest(manifest), errors: [] };
 }
+/**
+ * `loadModuleManifest` plus a signature-policy gate.
+ *
+ * Separate and async for the same reason `applyEditAsync` is: verification
+ * needs Web Crypto, which is async, and the synchronous loader is on a path
+ * plenty of hosts call where signatures are none of their business. A host that
+ * does not check signatures keeps the sync function and pays nothing.
+ *
+ * Structural validation runs first regardless of policy — a manifest that is
+ * not a valid manifest should say so, not report a signature problem.
+ */
+export async function loadModuleManifestAsync(candidate, opts = {}) {
+    const base = loadModuleManifest(candidate, opts);
+    if (!base.ok || !base.manifest)
+        return base;
+    const policy = opts.signaturePolicy ?? 'ignore';
+    if (policy === 'ignore')
+        return base;
+    const manifest = base.manifest;
+    if (manifest.signature === undefined && policy === 'verify-if-present')
+        return base;
+    const verdict = await verifyModuleSignature(manifest, {
+        ...(opts.signatureVerifier ? { verifier: opts.signatureVerifier } : {}),
+        ...(opts.allowedIdentities ? { allowedIdentities: opts.allowedIdentities } : {}),
+    });
+    return verdict.ok ? base : { ok: false, errors: [verdict.error] };
+}
+/** `createModuleRegistry` with the same signature-policy gate. */
+export async function createModuleRegistryAsync(opts) {
+    const errors = [];
+    for (const candidate of opts.modules) {
+        const result = await loadModuleManifestAsync(candidate, opts);
+        if (!result.ok)
+            errors.push(...result.errors);
+    }
+    // Refuse before building anything. A registry assembled from a set that
+    // included a module the policy rejects would be a registry the host was told
+    // not to have, whatever it did with the error list afterwards.
+    if (errors.length > 0)
+        throw new ModuleRegistryError(errors);
+    return createModuleRegistry(opts);
+}
 export function createModuleRegistry(opts) {
     const loaded = [];
     const errors = [];
@@ -152,6 +197,15 @@ function validateModuleManifest(manifest, opts) {
     if (!Array.isArray(manifest.authors) || manifest.authors.length === 0 || !manifest.authors.every((a) => typeof a === 'string' && a.length > 0)) {
         errors.push(moduleError('PROTO-MOD-005', 'Module authors must be a non-empty string array.', 'authors'));
     }
+    // Shape-check `signature` regardless of policy. A host that ignores
+    // signatures still must not accept a manifest carrying a malformed one:
+    // "ignore" is a decision not to *verify*, not a licence to admit nonsense
+    // into a frozen manifest other code will read.
+    if (manifest.signature !== undefined) {
+        const shape = checkSignatureShape(manifest.signature);
+        if (shape)
+            errors.push(shape.error);
+    }
     if (!TIERS.includes(manifest.requires_tier)) {
         errors.push(moduleError('PROTO-MOD-006', 'Module requires_tier is not a valid viewer tier.', 'requires_tier'));
     }
@@ -174,6 +228,7 @@ function validateModuleManifest(manifest, opts) {
             }
         }
     }
+    validateDeclaredAssetClasses(errors, manifest);
     if (manifest.deal_stages !== undefined) {
         if (!Array.isArray(manifest.deal_stages)) {
             errors.push(moduleError('PROTO-MOD-010', 'deal_stages must be an array.', 'deal_stages'));
@@ -564,6 +619,71 @@ function boundLength(errors, value, key, min, max) {
         errors.push(moduleError('PROTO-MOD-065', `${key} must be between ${min} and ${max} characters (got ${value.length}).`, key));
     }
 }
+const ASSET_CLASS_DECL_KEYS = [
+    'id', 'display_name', 'fallback', 'required_sections', 'optional_sections',
+];
+/**
+ * Validate `declares_asset_classes` (§X.2, RFC 0003).
+ *
+ * The identifier grammar is enforced here rather than only at document-parse
+ * time, so a module that would introduce an unusable class is refused at load
+ * — before any file references it and produces a confusing failure two layers
+ * away from the cause.
+ */
+function validateDeclaredAssetClasses(errors, manifest) {
+    const declarations = manifest.declares_asset_classes;
+    if (declarations === undefined)
+        return;
+    if (!Array.isArray(declarations)) {
+        errors.push(moduleError('PROTO-MOD-073', 'declares_asset_classes must be an array.', 'declares_asset_classes'));
+        return;
+    }
+    const seen = new Set();
+    for (const [idx, raw] of declarations.entries()) {
+        const pointer = `declares_asset_classes[${idx}]`;
+        if (!isRecord(raw)) {
+            errors.push(moduleError('PROTO-MOD-073', 'Each declaration must be an object.', pointer));
+            continue;
+        }
+        rejectUnknownKeys(errors, raw, ASSET_CLASS_DECL_KEYS, pointer);
+        const id = raw['id'];
+        if (typeof id !== 'string') {
+            errors.push(moduleError('PROTO-MOD-074', 'declaration id must be a string.', `${pointer}.id`));
+        }
+        else {
+            const identity = parseAssetClass(id);
+            if (!identity.ok) {
+                errors.push(moduleError('PROTO-MOD-074', identity.error.message, `${pointer}.id`));
+            }
+            else if (identity.kind === 'builtin') {
+                // Declaring a builtin is not an extension, it is a redefinition. The
+                // `asset_classes` field is how a module *enhances* one.
+                errors.push(moduleError('PROTO-MOD-074', `'${id}' is a builtin asset class; use asset_classes to enhance it rather than declares_asset_classes to redefine it.`, `${pointer}.id`));
+            }
+            else if (seen.has(id)) {
+                errors.push(moduleError('PROTO-MOD-075', `Asset class '${id}' is declared more than once by this module.`, `${pointer}.id`));
+            }
+            else {
+                seen.add(id);
+            }
+        }
+        if (typeof raw['display_name'] !== 'string' || raw['display_name'].length === 0) {
+            errors.push(moduleError('PROTO-MOD-076', 'declaration display_name must be a non-empty string.', `${pointer}.display_name`));
+        }
+        const fallback = raw['fallback'];
+        if (fallback !== undefined && !ASSET_CLASSES.includes(fallback)) {
+            errors.push(moduleError('PROTO-MOD-077', `declaration fallback must be a builtin asset class (got ${JSON.stringify(fallback)}).`, `${pointer}.fallback`));
+        }
+        for (const key of ['required_sections', 'optional_sections']) {
+            const value = raw[key];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value) || !value.every((v) => typeof v === 'string' && v.length > 0)) {
+                errors.push(moduleError('PROTO-MOD-078', `${key} must be an array of non-empty section ids.`, `${pointer}.${key}`));
+            }
+        }
+    }
+}
 function freezeManifest(manifest) {
     return Object.freeze({
         ...manifest,
@@ -576,6 +696,9 @@ function freezeManifest(manifest) {
         view_models: manifest.view_models ? Object.freeze([...manifest.view_models]) : undefined,
         agent_layers: manifest.agent_layers ? Object.freeze([...manifest.agent_layers]) : undefined,
         depends_on: manifest.depends_on ? Object.freeze([...manifest.depends_on]) : undefined,
+        declares_asset_classes: manifest.declares_asset_classes
+            ? Object.freeze([...manifest.declares_asset_classes])
+            : undefined,
     });
 }
 function isRecord(value) {