@ottochain/sdk 2.3.0 → 2.5.0

package/dist/esm/schema/guard-lint.js

@@ -0,0 +1,337 @@
+/**
+ * Regression-prevention lint for OttoChain std-app fiber definitions.
+ *
+ * Purpose
+ * -------
+ * Catch — at *authoring* time — the classes of SDK↔chain drift that the chain
+ * accepts structurally but then silently mis-parses, drops, or evaluates to a
+ * dead (always-true / always-false / always-throw) guard. Without this lint
+ * those mistakes ship as live, exploitable holes or as silent data corruption
+ * because nothing in `defineFiberApp` / `toProtoDefinition` rejects them.
+ *
+ * The drift classes (cross-referenced to docs/reviews/fiber-app-alignment-audit-2026-06.md):
+ *
+ *   A1 — `$timestamp` (and any non-injected `$`-key). `ReservedKeys` injects ONLY
+ *        `$ordinal`, `$lastSnapshotHash`, `$epochProgress`. `{"var":"$timestamp"}`
+ *        resolves to null → `0` in numeric contexts → deadline guards die silently.
+ *
+ *   A2 — Nonexistent JLVM opcodes used as operator tags: `size`, `getKey`,
+ *        `setKey`, `deleteKey`. metakit decodes an unknown single-key object as a
+ *        LITERAL Map, not an operator, so the guard is always-true/false and the
+ *        effect writes a junk key. (Canonical good set: `KNOWN_OPERATORS`.)
+ *
+ *   A3 — SDK directives the chain's `toProtoDefinition` silently drops:
+ *        transition-level `emits` / `spawns`, and object-form `dependencies`
+ *        entries `{machine,instanceRef,requiredState}` (chain parses `Set[UUID]`).
+ *        Authors believe these gate/emit; on-chain they evaporate.
+ *
+ *   per-context — `{"var":"witness.*"}` in a fiber TRANSITION. `witness` is only
+ *        injected in ASSET-guard contexts; a transition gets `event` (the proof
+ *        rides under `event.witness.*`). Reading `witness.*` resolves to null →
+ *        fail-closed (zk gate un-passable) or silently bypassed.
+ *
+ *   leading-dot — `{"var":".foo"}` resolves to null on chain.
+ *
+ * This is a STANDALONE validator. It is deliberately NOT wired into
+ * `defineFiberApp` / `toProtoDefinition`: doing so would break the build until
+ * every app is remediated. Run it via `scripts/lint-apps.mjs`.
+ */
+import { KNOWN_OPERATORS as KNOWN_OPERATORS_TYPED } from '@constellation-network/metagraph-sdk-jlvm';
+/**
+ * Canonical set of valid JLVM operator tags, imported from metakit (the same
+ * `KNOWN_OPERATORS` the on-chain evaluator is built from). Widened to
+ * `ReadonlySet<string>` so we can membership-test arbitrary object keys.
+ */
+const KNOWN_OPERATORS = KNOWN_OPERATORS_TYPED;
+/** Stable rule codes — referenced by tests and by report tooling. */
+export const LINT_CODES = {
+    UNKNOWN_RESERVED_VAR: 'unknown-reserved-var', // rule 1 (A1)
+    UNKNOWN_OPERATOR: 'unknown-operator', // rule 2 (A2)
+    WITNESS_IN_TRANSITION: 'witness-in-transition', // rule 3
+    DROPPED_DIRECTIVE: 'dropped-directive', // rule 4 (A3)
+    LEADING_DOT_VAR: 'leading-dot-var', // rule 5
+};
+// =============================================================================
+// Rule data
+// =============================================================================
+/**
+ * The ONLY `$`-prefixed keys the engine injects (`ReservedKeys`). Anything else
+ * (`$timestamp`, `$now`, ...) resolves to null on chain.
+ */
+export const INJECTED_RESERVED_VARS = new Set(['$ordinal', '$lastSnapshotHash', '$epochProgress']);
+/**
+ * Tags that LOOK like opcodes and appear in real definitions but are NOT valid
+ * JLVM operators — metakit mis-decodes each as a literal Map. These are always
+ * flagged as errors regardless of position (they are not plausible data fields).
+ * Mapped to the correct replacement opcode for the message.
+ */
+export const KNOWN_BAD_OPERATORS = new Map([
+    ['size', 'length (collections) or count; for a Map use length[keys[...]]'],
+    ['getKey', 'get (value) / has (membership)'],
+    ['setKey', 'merge (or restructure the field as an array appended with cat/merge)'],
+    ['deleteKey', 'filter the collection (model the field as an array of records)'],
+]);
+/**
+ * Structural keys that JSON-Logic uses as single-key objects but are NOT
+ * operator tags. Used to avoid false-positive "unknown operator" warnings.
+ * `var` is the data-access form; the rest are common rule scaffolding seen in
+ * std apps that are handled by the evaluator or are intentional literals.
+ */
+const NON_OPERATOR_SINGLE_KEYS = new Set([
+    'var', // data access — handled explicitly
+]);
+/**
+ * Recursively lint a single JSON-Logic expression (a guard or an effect, or any
+ * sub-node). Walks every nested operand. Pushes a {@link LintViolation} for each
+ * rule-1 / rule-2 / rule-3 / rule-5 hit found at or below `node`.
+ *
+ * `inDataLiteral` tracks whether `node` sits in a position the evaluator treats
+ * as DATA rather than as an expression to evaluate (e.g. the 2nd operand of
+ * `merge`/`cat`, or a value nested inside such an operand). In a data-literal
+ * position an unknown single-key object is a legitimate field map, so the
+ * *generic* unknown-operator warning is suppressed there — but `$`-var keys,
+ * leading-dot vars, witness reads, and the known-BAD opcode tags are still
+ * flagged (those are bugs wherever they appear).
+ */
+export function lintGuardExpression(node, ctx, path, inDataLiteral = false) {
+    const out = [];
+    // Arrays: walk each element, preserving the data-literal flag.
+    if (Array.isArray(node)) {
+        node.forEach((child, i) => {
+            out.push(...lintGuardExpression(child, ctx, `${path}[${i}]`, inDataLiteral));
+        });
+        return out;
+    }
+    // Primitives carry no structure to lint.
+    if (node === null || typeof node !== 'object') {
+        return out;
+    }
+    const obj = node;
+    const keys = Object.keys(obj);
+    // ---- `var` access: rules 1, 3, 5 -------------------------------------
+    if (keys.length === 1 && keys[0] === 'var') {
+        const ref = obj.var;
+        // The reference may be a string, or `[path, default]`, or (rarely) a
+        // nested expression; only string refs carry the patterns we check.
+        const refStr = typeof ref === 'string' ? ref : Array.isArray(ref) && typeof ref[0] === 'string' ? ref[0] : undefined;
+        if (refStr !== undefined) {
+            // rule 1 — unknown reserved `$`-key
+            if (refStr.startsWith('$') && !INJECTED_RESERVED_VARS.has(refStr)) {
+                out.push({
+                    app: ctx.app,
+                    transition: ctx.transition,
+                    severity: 'error',
+                    code: LINT_CODES.UNKNOWN_RESERVED_VAR,
+                    message: `{"var":"${refStr}"} references a reserved key the engine never injects. ` +
+                        `Only ${[...INJECTED_RESERVED_VARS].join(', ')} are injected; ` +
+                        `"${refStr}" resolves to null (→ 0 in numeric contexts, defeating deadline guards). ` +
+                        `Use $ordinal and model time fields as ordinal deltas/bounds.`,
+                    path: `${path}.var`,
+                });
+            }
+            // rule 5 — leading-dot relative path
+            if (refStr.startsWith('.')) {
+                out.push({
+                    app: ctx.app,
+                    transition: ctx.transition,
+                    severity: 'error',
+                    code: LINT_CODES.LEADING_DOT_VAR,
+                    message: `{"var":"${refStr}"} uses a leading-dot relative path, which resolves to null on chain. ` +
+                        `Use the bare element field name ("${refStr.slice(1)}") inside map/filter/some scopes.`,
+                    path: `${path}.var`,
+                });
+            }
+            // rule 3 — `witness.*` read inside a fiber transition
+            if (ctx.flagWitness && (refStr === 'witness' || refStr.startsWith('witness.'))) {
+                out.push({
+                    app: ctx.app,
+                    transition: ctx.transition,
+                    severity: 'error',
+                    code: LINT_CODES.WITNESS_IN_TRANSITION,
+                    message: `{"var":"${refStr}"} reads the 'witness' context, which is injected ONLY in asset-guard ` +
+                        `contexts — never in a fiber transition (the engine injects 'event'). It resolves to null ` +
+                        `→ the zk gate is un-passable (fail-closed). Read 'event.${refStr}' instead, or move the ` +
+                        `semi-private guard onto the asset mintPolicy/burnPolicy.`,
+                    path: `${path}.var`,
+                });
+            }
+        }
+        // The `var` default operand (ref[1]) may itself be an expression; walk it.
+        if (Array.isArray(ref) && ref.length > 1) {
+            out.push(...lintGuardExpression(ref[1], ctx, `${path}.var[1]`, inDataLiteral));
+        }
+        return out;
+    }
+    // ---- single-key object: candidate operator (rule 2) ------------------
+    if (keys.length === 1) {
+        const tag = keys[0];
+        const operand = obj[tag];
+        // rule 2a — known-BAD opcode tag. Always an error (these are never plausible
+        // data field names, and metakit silently mis-decodes them as a literal Map).
+        if (KNOWN_BAD_OPERATORS.has(tag)) {
+            out.push({
+                app: ctx.app,
+                transition: ctx.transition,
+                severity: 'error',
+                code: LINT_CODES.UNKNOWN_OPERATOR,
+                message: `'${tag}' is not a JLVM operator — metakit decodes {"${tag}":...} as a literal Map, ` +
+                    `so this guard is always-true/false and any effect writes a junk key. ` +
+                    `Use ${KNOWN_BAD_OPERATORS.get(tag)}.`,
+                path: `${path}.${tag}`,
+            });
+            // Still descend into the operand (it may carry further violations).
+            out.push(...lintGuardExpression(operand, ctx, `${path}.${tag}`, inDataLiteral));
+            return out;
+        }
+        // Recognized operator: descend. `merge`/`cat` 2nd+ operands are DATA literals
+        // (field maps to write), so mark them to suppress the generic op warning below.
+        if (KNOWN_OPERATORS.has(tag)) {
+            const literalDataOp = tag === 'merge' || tag === 'cat';
+            if (literalDataOp && Array.isArray(operand)) {
+                operand.forEach((child, i) => {
+                    // First operand is the base collection (an expression); the rest are
+                    // the literal field maps merged/appended onto it.
+                    out.push(...lintGuardExpression(child, ctx, `${path}.${tag}[${i}]`, i > 0 ? true : inDataLiteral));
+                });
+            }
+            else {
+                out.push(...lintGuardExpression(operand, ctx, `${path}.${tag}`, inDataLiteral));
+            }
+            return out;
+        }
+        // rule 2b (heuristic warn) — an unknown single-key tag that LOOKS like an
+        // operator (no spaces, not `var`, not a known data scaffold) and is NOT in a
+        // data-literal position. Keep this a WARNING to hold false positives low:
+        // in a data-literal position a one-key object is a legitimate `{field: ...}`.
+        if (!inDataLiteral &&
+            !NON_OPERATOR_SINGLE_KEYS.has(tag) &&
+            !tag.includes(' ') &&
+            !tag.startsWith('$') &&
+            !tag.startsWith('_') // reserved effect directives (_emit/_spawn/...) are handled structurally
+        ) {
+            out.push({
+                app: ctx.app,
+                transition: ctx.transition,
+                severity: 'warn',
+                code: LINT_CODES.UNKNOWN_OPERATOR,
+                message: `single-key object {"${tag}":...} in an expression position has a key that is not a known ` +
+                    `JLVM operator. If '${tag}' was meant as an operator it will mis-decode as a literal Map; ` +
+                    `if it is a literal field, ignore. Known operators: see KNOWN_OPERATORS.`,
+                path: `${path}.${tag}`,
+            });
+        }
+        out.push(...lintGuardExpression(operand, ctx, `${path}.${tag}`, inDataLiteral));
+        return out;
+    }
+    // ---- multi-key object: a DATA literal (a field map). Descend into values,
+    // marking children as data-literal so their inner one-key objects are not
+    // mistaken for operators. (`$`/leading-dot/witness `var`s inside are still
+    // flagged by the recursion.)
+    for (const k of keys) {
+        out.push(...lintGuardExpression(obj[k], ctx, `${path}.${k}`, true));
+    }
+    return out;
+}
+// =============================================================================
+// Transition-level structural rules (rule 4 / A3)
+// =============================================================================
+function isObjectDependency(dep) {
+    return typeof dep === 'object' && dep !== null && !Array.isArray(dep);
+}
+function lintTransitionStructure(t, app, transition, path) {
+    const out = [];
+    const raw = t;
+    // rule 4a — transition-level `emits`
+    if (raw.emits !== undefined) {
+        out.push({
+            app,
+            transition,
+            severity: 'error',
+            code: LINT_CODES.DROPPED_DIRECTIVE,
+            message: `transition-level 'emits' is silently dropped by toProtoDefinition (the chain Transition has ` +
+                `no such field). Emit from INSIDE the effect result under the reserved key '_emit' ` +
+                `({name,data,destination}), or '_triggers' for a state-changing cross-machine call.`,
+            path: `${path}.emits`,
+        });
+    }
+    // rule 4b — transition-level `spawns`
+    if (raw.spawns !== undefined) {
+        out.push({
+            app,
+            transition,
+            severity: 'error',
+            code: LINT_CODES.DROPPED_DIRECTIVE,
+            message: `transition-level 'spawns' is silently dropped by toProtoDefinition — the child machine is ` +
+                `never created. Spawn from INSIDE the effect result under the reserved key '_spawn' ` +
+                `(with a full inline definition, a distinct childId, and initialData).`,
+            path: `${path}.spawns`,
+        });
+    }
+    // rule 4c — object-form `dependencies` entries (chain accepts Set[UUID] only)
+    if (Array.isArray(t.dependencies)) {
+        t.dependencies.forEach((dep, i) => {
+            if (isObjectDependency(dep)) {
+                out.push({
+                    app,
+                    transition,
+                    severity: 'error',
+                    code: LINT_CODES.DROPPED_DIRECTIVE,
+                    message: `dependencies[${i}] is an object ({machine,instanceRef,requiredState}); the chain parses ` +
+                        `'dependencies' as Set[UUID] and drops the object, so 'requiredState' gating NEVER happens. ` +
+                        `Pass a bare fiber-UUID string and assert machines.<uuid>.currentStateId=="<state>" in the guard.`,
+                    path: `${path}.dependencies[${i}]`,
+                });
+            }
+        });
+    }
+    return out;
+}
+// =============================================================================
+// Top-level entry point
+// =============================================================================
+function appLabel(def) {
+    const m = def.metadata;
+    if (!m)
+        return undefined;
+    if (m.app && m.type)
+        return `${m.app}/${m.type}`;
+    return m.name ?? m.app ?? m.type ?? undefined;
+}
+/**
+ * Lint a complete fiber app definition. Walks every transition guard + effect
+ * (rules 1/2/3/5) and every transition's structural directives (rule 4), plus a
+ * light pass over `states` to catch stray reserved-key / operator drift embedded
+ * in state metadata. Returns ALL violations (errors and warnings); callers
+ * decide the exit policy (e.g. fail on any `error`).
+ */
+export function lintFiberApp(def) {
+    const out = [];
+    const app = appLabel(def);
+    // Transitions.
+    (def.transitions ?? []).forEach((t, i) => {
+        const transition = t.eventName ?? `${t.from}->${t.to}`;
+        const tPath = `transitions[${i}]`;
+        const ctx = { app, transition, flagWitness: true };
+        if (t.guard !== undefined) {
+            out.push(...lintGuardExpression(t.guard, ctx, `${tPath}.guard`));
+        }
+        if (t.effect !== undefined) {
+            out.push(...lintGuardExpression(t.effect, ctx, `${tPath}.effect`));
+        }
+        out.push(...lintTransitionStructure(t, app, transition, tPath));
+    });
+    // States — usually inert metadata, but guard against reserved-key drift here
+    // too (states never run in an asset context, so witness reads would be bugs).
+    Object.entries(def.states ?? {}).forEach(([name, state]) => {
+        const ctx = { app, transition: `state:${name}`, flagWitness: true };
+        out.push(...lintGuardExpression(state, ctx, `states.${name}`));
+    });
+    return out;
+}
+/**
+ * Convenience: lint many apps at once, returning a flat list. Each app's
+ * violations already carry its `app` label.
+ */
+export function lintFiberApps(defs) {
+    return defs.flatMap((d) => lintFiberApp(d));
+}

package/dist/esm/schema/guards.js

@@ -0,0 +1,228 @@
+/**
+ * Canonical authorization-guard builders — bind "who may act" to the CHAIN-VERIFIED signer of the op,
+ * never to an attacker-supplied payload field.
+ *
+ * The forgeable anti-pattern (security audit class F1): `{"===":[{"var":"event.agent"}, {"var":"state.party"}]}`.
+ * The fiber engine injects `event` as the RAW transition payload (ContextProvider: `EVENT -> payload`),
+ * so `event.agent` is whatever the submitter wrote — a different party's address forges authorization.
+ * The chain ALSO injects `proofs` = `[{address, id, signature}]` where `address = id.toAddress` (the
+ * VERIFIED signer addresses). Authorization must bind to THAT. For ASSET ops (mint/burn/morphism) the
+ * context has no `event`/`proofs`; it injects `signers` (an array of verified address strings) instead.
+ *
+ * Use these so the safe pattern is consistent, greppable, and impossible to get subtly wrong.
+ */
+/**
+ * FIBER-transition authorization: the pinned `partyVar` (a `state` path holding an address, e.g.
+ * `"state.borrower"`) MUST be among the op's verified signers (`proofs[].address`). The replay-safe
+ * replacement for `{"===":[{"var":"event.agent"}, {"var":partyVar}]}`.
+ */
+export const signerIsParty = (partyVar) => ({
+    in: [{ var: partyVar }, { map: [{ var: 'proofs' }, { var: 'address' }] }],
+});
+/** FIBER-transition authorization where ANY of the pinned parties signed (e.g. borrower OR lender). */
+export const signerIsAnyParty = (partyVars) => ({
+    or: partyVars.map(signerIsParty),
+});
+/**
+ * FIBER-transition authorization where the actor must be a MEMBER of a pinned set: at least one
+ * VERIFIED signer is in the `setVar` array (e.g. `"state.signers"`, `"state.members"`, `"state.oracles"`).
+ * The replay-safe replacement for `{"in":[{"var":"event.agent"}, {"var":setVar}]}`.
+ */
+export const signerInSet = (setVar) => ({
+    some: [{ map: [{ var: 'proofs' }, { var: 'address' }] }, { in: [{ var: '' }, { var: setVar }] }],
+});
+/**
+ * FIBER-transition ANTI-SELF guard: NO verified signer is the pinned party (e.g. a proposal author may
+ * not vote on their own proposal). The replay-safe replacement for `{"!==":[{"var":"event.agent"}, {"var":partyVar}]}`.
+ */
+export const signerIsNotParty = (partyVar) => ({
+    '!': [signerIsParty(partyVar)],
+});
+/**
+ * FIBER-transition authorization / dedup over a state MAP keyed by address: at least one VERIFIED signer
+ * is a key in `mapVar` (e.g. `"state.members"`, `"state.balances"`). The replay-safe replacement for the
+ * forgeable `{"getKey":[{"var":mapVar}, {"var":"event.agent"}]}` membership/presence check (note metakit
+ * has no `getKey`; use `get`/`has`). For a "no signer has acted yet" dedup, negate: `{"!":[signerHasEntry(...)]}`.
+ * For a per-actor VALUE threshold (e.g. balance >= N), build the `some` directly:
+ * `{"some":[{"map":[proofs,address]},{">=":[{"get":[mapVar,{"var":""}]}, N]}]}`.
+ */
+export const signerHasEntry = (mapVar) => ({
+    some: [{ map: [{ var: 'proofs' }, { var: 'address' }] }, { has: [{ var: mapVar }, { var: '' }] }],
+});
+/**
+ * ASSET-op authorization (mintPolicy / burnPolicy / MorphismSpec.guard): the address at `addressVar`
+ * (e.g. `"holder.Wallet.address"`) MUST be among the op's verified `signers`. The asset context has no
+ * `event` or `proofs` — it injects `signers` directly.
+ */
+export const assetSignerIs = (addressVar) => ({
+    in: [{ var: addressVar }, { var: 'signers' }],
+});
+/**
+ * EFFECT-KEY BINDING: prove the event's claimed actor (`actorVar`, default `event.agent`) is a
+ * CHAIN-VERIFIED signer, so that field is SAFE to use as a dynamic map key / array element in the
+ * EFFECT (`{"set":[map,{"var":"event.agent"},v]}`, `{"cat":[arr,[{"var":"event.agent"}]]}`).
+ *
+ * This is the coupling clause for the map-write remediation: a guard may authorize via membership /
+ * balance / reputation, but if the EFFECT writes under `event.agent` WITHOUT this clause, an attacker
+ * sets `event.agent` to a victim's address and writes under the victim's key (security class S1).
+ * Pair it with the authorization check expressed on the SAME `actorVar` — together they prove the actor
+ * both signed and is authorized, and the effect can only write under that one verified key.
+ * Structurally identical to {@link signerIsParty}; named for intent + greppability at write sites.
+ */
+export const actorIsSigner = (actorVar = 'event.agent') => signerIsParty(actorVar);
+/**
+ * EFFECT-KEY-BINDING membership: the event's claimed actor (`actorVar`, default `event.agent`) is BOTH
+ * a CHAIN-VERIFIED signer AND a member of the pinned set `setVar` (e.g. `"state.signers"`,
+ * `"state.members"`). Use when the EFFECT writes a map/array keyed by that actor and authorization is
+ * set-membership. It proves the EXACT actor whose key is written both signed and is authorized — closing
+ * the S1 forge AND the subtler gap {@link signerInSet} leaves open: `signerInSet` only proves SOME
+ * verified signer is a member, so an op co-signed by an authorized signer could still write a DIFFERENT
+ * verified-but-unauthorized address as the key (padding a signature/vote tally). `actorInSet` pins both
+ * to the same `actorVar`.
+ */
+export const actorInSet = (setVar, actorVar = 'event.agent') => ({
+    and: [actorIsSigner(actorVar), { in: [{ var: actorVar }, { var: setVar }] }],
+});
+/**
+ * EFFECT-KEY-BINDING map membership: the claimed actor (`actorVar`, default `event.agent`) is BOTH a
+ * CHAIN-VERIFIED signer AND a key in the pinned state MAP `mapVar` (e.g. `"state.members"`,
+ * `"state.balances"`). The map analog of {@link actorInSet} — use it when the membership set is a dict
+ * keyed by address, where `in` does not apply and `has` checks key presence. Use when the EFFECT writes
+ * `mapVar` (or a per-actor tally) keyed by that actor: it proves the EXACT written key both signed and
+ * is an authorized member, closing the vote/signature-stuffing gap that bare {@link signerHasEntry}
+ * leaves open (which only proves SOME verified signer is a key, not that the written key is).
+ */
+export const actorHasEntry = (mapVar, actorVar = 'event.agent') => ({
+    and: [actorIsSigner(actorVar), { has: [{ var: mapVar }, { var: actorVar }] }],
+});
+/**
+ * IDENTITY-REGISTRY reputation gate: at least one VERIFIED signer has a reputation in the registry map
+ * at `repMapVar` (a declared-dependency read, e.g. `"machines.<registryDep>.state.reputations"`, shaped
+ * `{ <address>: int }`) that is `>=` the bar read from `thresholdVar` (a state path, e.g.
+ * `"state.voteThreshold"`). A missing entry reads as null → 0 numerically, so unregistered signers
+ * fail-closed for any positive bar. The replay-safe replacement for the forgeable
+ * `{">=":[{"var":"event.agentReputation"}, bar]}` (security class S1). See
+ * docs/design/app-hardening-identity-integration.md §3–§4.1.
+ */
+export const signerHasReputation = (repMapVar, thresholdVar) => ({
+    some: [
+        { map: [{ var: 'proofs' }, { var: 'address' }] },
+        {
+            '>=': [{ get: [{ var: repMapVar }, { var: '' }] }, { var: thresholdVar }],
+        },
+    ],
+});
+/**
+ * IDENTITY-REGISTRY role gate: at least one VERIFIED signer holds an active role attestation, i.e. is a
+ * key in the registry's flat per-role map at `roleMapVar` (a declared-dependency read, e.g.
+ * `"machines.<registryDep>.state.arbiters"` / `".slashers"` / `".issuers"` / `".boardMembers"`, each
+ * shaped `{ <address>: true }`). The replay-safe replacement for bare `event.judicialRuling` / role
+ * escapes and `{"==":[1,1]}` missing-auth (security class S2). Roles are FLAT per-role maps (not a
+ * nested `roles[addr][ROLE]`) because metakit `get`/`has` on a null inner map ERROR rather than
+ * returning null; a flat map keeps the read total + fail-closed. See app-hardening §4.2.
+ */
+export const signerHasRole = (roleMapVar) => signerHasEntry(roleMapVar);
+/**
+ * DYNAMIC identity-registry reputation gate — for when the registry instance is bound at RUNTIME via the
+ * fiber-engine `_addDependency` directive (#24) rather than hardcoded into the `machines.<uuid>` path.
+ * `registryIdVar` is a state/event path holding the registry fiber id (e.g. `"state.registryId"`); the
+ * read addresses `machines[<that id>].state.reputations[<signer>]` with dynamic `get`s. Guarded by a
+ * presence check so an UNBOUND registry yields a clean `false` (fail-closed) instead of an evaluation
+ * error. REQUIRES the registry dependency to have been added in a PRIOR transition (`_addDependency`),
+ * because the `machines` context is built before the effect runs (two-phase: bind, then read).
+ */
+export const signerHasReputationVia = (registryIdVar, thresholdVar) => ({
+    if: [
+        { has: [{ var: 'machines' }, { var: registryIdVar }] },
+        {
+            some: [
+                { map: [{ var: 'proofs' }, { var: 'address' }] },
+                {
+                    '>=': [
+                        {
+                            get: [
+                                {
+                                    get: [
+                                        {
+                                            get: [{ get: [{ var: 'machines' }, { var: registryIdVar }] }, 'state'],
+                                        },
+                                        'reputations',
+                                    ],
+                                },
+                                { var: '' },
+                            ],
+                        },
+                        { var: thresholdVar },
+                    ],
+                },
+            ],
+        },
+        false,
+    ],
+});
+/**
+ * DYNAMIC identity-registry role gate — the runtime-bound (`_addDependency`, #24) counterpart of
+ * {@link signerHasRole}. `registryIdVar` is a state/event path holding the registry fiber id;
+ * `roleField` is the registry's flat per-role state map name (`"arbiters"` / `"slashers"` / `"issuers"` /
+ * `"boardMembers"` — see REGISTRY_ROLE_MAP). Reads `machines[<id>].state.<roleField>[<signer>]`, guarded
+ * by a presence check so an UNBOUND registry yields a clean `false`. Same two-phase requirement as
+ * {@link signerHasReputationVia}.
+ */
+export const signerHasRoleVia = (registryIdVar, roleField) => ({
+    if: [
+        { has: [{ var: 'machines' }, { var: registryIdVar }] },
+        {
+            some: [
+                { map: [{ var: 'proofs' }, { var: 'address' }] },
+                {
+                    has: [
+                        {
+                            get: [
+                                {
+                                    get: [{ get: [{ var: 'machines' }, { var: registryIdVar }] }, 'state'],
+                                },
+                                roleField,
+                            ],
+                        },
+                        { var: '' },
+                    ],
+                },
+            ],
+        },
+        false,
+    ],
+});
+/**
+ * CROSS-FIBER STATE GATE — assert a RUNTIME-bound dependency fiber is in a required lifecycle state. The
+ * replay-safe replacement for the dropped object-form dependency
+ * `{machine, instanceRef, requiredState}` (which the chain silently drops — `requiredState` gating never
+ * happens). `refVar` is a state/event path holding the dependency's fiber id; reads
+ * `machines[<refVar>].currentStateId == requiredState`, guarded by a presence check so an UNBOUND
+ * dependency yields a clean `false` (fail-closed). TWO-PHASE (#24): the dependency fiber must have been
+ * bound by an `_addDependency` in a PRIOR transition (the `machines` context is built before the effect),
+ * so a single gated transition is split into a bind step then this assert step. See
+ * docs/design/app-hardening-identity-integration.md §5–§6.
+ */
+/**
+ * EFFECT-KEY-BINDING dedup over an ARRAY of records: no existing element of the array at `arrayVar`
+ * (e.g. `"state.submissions"`, shaped `[ { addr, value }, … ]`) has its `field` (default `"addr"`)
+ * equal to the actor at `actorVar` (default `"event.agent"`). The array analog of the map-keyed
+ * `{"!":[has(...)]}` dedup — used where the collection is an append-only array of `{addr,…}` records
+ * (there is no `(array,string)` key check, but `none` over the array with a per-element `===` is total).
+ *
+ * The bare-element callback context inside `none` sees each record map directly, so `{get:[{var:""},field]}`
+ * is a valid `(map,string)` read. Pair with an `actorIsSigner`/`actorHasEntry` clause on the same
+ * `actorVar` (the dedup proves "not yet present", not "is the verified signer").
+ */
+export const actorNotInArray = (arrayVar, field = 'addr', actorVar = 'event.agent') => ({
+    none: [{ var: arrayVar }, { '===': [{ get: [{ var: '' }, field] }, { var: actorVar }] }],
+});
+export const depInState = (refVar, requiredState) => ({
+    if: [
+        { has: [{ var: 'machines' }, { var: refVar }] },
+        {
+            '==': [{ get: [{ get: [{ var: 'machines' }, { var: refVar }] }, 'currentStateId'] }, requiredState],
+        },
+        false,
+    ],
+});

package/dist/esm/signing.js

@@ -0,0 +1,74 @@
+/**
+ * DataUpdate Signing Wrappers — dropNulls applied internally
+ *
+ * Metakit (>= 1.8) computes content hashes by recursively dropping
+ * null-valued OBJECT fields (array nulls are preserved) before RFC 8785
+ * canonicalization (`JsonBinaryCodec.dropNulls`). This makes
+ * `Option = None` indistinguishable from an absent field, so schema
+ * evolution never changes prior hashes.
+ *
+ * The upstream `@constellation-network/metagraph-sdk` signs over the
+ * payload as-is, so a payload containing explicit nulls would be signed
+ * over different bytes than the metagraph hashes — and the node rejects
+ * the signature (HTTP 400).
+ *
+ * These wrappers shadow the upstream dataUpdate signing surface and apply
+ * `dropNulls` internally, unconditionally. Standard-mode signing
+ * (currency transactions etc.) is passed through unchanged.
+ */
+import { signDataUpdate as baseSignDataUpdate, createSignedObject as baseCreateSignedObject, addSignature as baseAddSignature, batchSign as baseBatchSign, } from '@constellation-network/metagraph-sdk';
+import { dropNulls } from './ottochain/drop-nulls.js';
+function resolveMode(options = {}) {
+    if (options.mode)
+        return options.mode;
+    if (options.isDataUpdate)
+        return 'dataUpdate';
+    return 'standard';
+}
+/**
+ * Sign data as a DataUpdate, hashing over null-dropped canonical bytes.
+ *
+ * Applies `dropNulls` internally so that explicit-null and absent optional
+ * fields produce identical signatures, matching metakit's content-hash rule
+ * (drop null object fields, preserve array nulls, then RFC 8785).
+ */
+export function signDataUpdate(data, privateKey) {
+    return baseSignDataUpdate(dropNulls(data), privateKey);
+}
+/**
+ * Create a signed object. In `dataUpdate` mode the signature is computed
+ * over the null-dropped canonical bytes (the returned `value` is the
+ * caller's original payload, untouched).
+ */
+export function createSignedObject(value, privateKey, options = {}) {
+    if (resolveMode(options) === 'dataUpdate') {
+        const signed = baseCreateSignedObject(dropNulls(value), privateKey, options);
+        return { ...signed, value };
+    }
+    return baseCreateSignedObject(value, privateKey, options);
+}
+/**
+ * Add an additional signature to an existing signed object. In
+ * `dataUpdate` mode the new signature is computed over the null-dropped
+ * canonical bytes of `signed.value`.
+ */
+export function addSignature(signed, privateKey, options) {
+    const mode = options ? resolveMode(options) : (signed.mode ?? 'standard');
+    if (mode === 'dataUpdate') {
+        const result = baseAddSignature({ ...signed, value: dropNulls(signed.value) }, privateKey, options);
+        return { ...result, value: signed.value };
+    }
+    return baseAddSignature(signed, privateKey, options);
+}
+/**
+ * Create a signed object with multiple signatures at once. In
+ * `dataUpdate` mode all signatures are computed over the null-dropped
+ * canonical bytes (the returned `value` is the caller's original payload).
+ */
+export function batchSign(value, privateKeys, options = {}) {
+    if (resolveMode(options) === 'dataUpdate') {
+        const signed = baseBatchSign(dropNulls(value), privateKeys, options);
+        return { ...signed, value };
+    }
+    return baseBatchSign(value, privateKeys, options);
+}