@ottochain/sdk 2.3.0 → 2.5.0

package/dist/types/schema/fiber-app.d.ts

@@ -105,6 +105,269 @@ export interface Transition<TState extends string = string, TEvent extends strin
     dependencies?: readonly (string | DependencySpec)[];
     emits?: readonly (string | EmitSpec)[];
 }
+/**
+ * `allowedEffects` element — the 5 `EffectKind` families, UPPERCASE on the wire
+ * (`enumeratum` `Uppercase` mixin). Chain: `EffectKind` in `FiberPolicy.scala`.
+ */
+export type EffectKind = 'TRIGGER' | 'SPAWN' | 'EMIT' | 'TRANSFER' | 'DEPENDENCY';
+/**
+ * `spawnOwnerPolicy` — UPPERCASE (`enumeratum` `Uppercase`). Chain: `SpawnOwnerPolicy`
+ * (`Explicit` / `SubsetOfParent` / `InheritParent` ⇒ `"EXPLICIT"` / `"SUBSETOFPARENT"`
+ * / `"INHERITPARENT"`).
+ */
+export type SpawnOwnerPolicy = 'EXPLICIT' | 'SUBSETOFPARENT' | 'INHERITPARENT';
+/**
+ * `dependencyPolicy.mode` — UPPERCASE (`enumeratum` `Uppercase`). Chain: `DependencyMode`
+ * (`Open` / `Allowlist` / `Frozen`). REQUIRED on the wire (Scala defaults it to `Open`,
+ * but the `customizableEncoder` always encodes the value).
+ */
+export type DependencyMode = 'OPEN' | 'ALLOWLIST' | 'FROZEN';
+/**
+ * `transferPolicy` — recipient allowlist for `_transferAsset`. Chain: `TransferPolicy`
+ * (`Option[Set[UUID]]` fibers, `Option[Set[Address]]` wallets). Each field is OPTIONAL;
+ * an absent field ⇒ that recipient class is unconstrained (and is `dropNulls`-stripped).
+ */
+export interface TransferPolicy {
+    /** Fiber UUIDs permitted to receive a transfer. */
+    allowedRecipientFibers?: readonly string[];
+    /** DAG wallet addresses permitted to receive a transfer. */
+    allowedRecipientWallets?: readonly string[];
+}
+/**
+ * `dependencyPolicy` — dynamic-dependency posture. Chain: `DependencyPolicy`
+ * (`mode: DependencyMode`, `allowed: Option[Set[UUID]]`). `mode` is REQUIRED; `allowed`
+ * is meaningful only when `mode === 'ALLOWLIST'` and is `dropNulls`-stripped otherwise.
+ */
+export interface DependencyPolicy {
+    /** Posture: `OPEN` (any target) / `ALLOWLIST` (only `allowed`) / `FROZEN` (no new). */
+    mode: DependencyMode;
+    /** Fiber UUIDs permitted as dependency targets (meaningful only under `ALLOWLIST`). */
+    allowed?: readonly string[];
+}
+/**
+ * `migrationAuthority` — who may authorize a `Governed` migration. Chain:
+ * `MigrationAuthority`, a DISJOINT-FIELD discriminated union (no tag key): the `Signers`
+ * arm carries `addresses`, the `Role` arm carries `registryFiberId` + `roleField`. The
+ * presence of disjoint fields is the discriminator (same as the chain decoder's `.or`).
+ */
+export type MigrationAuthority = {
+    /** VERIFIED signer DAG addresses permitted to authorize the migration (`Signers`). */
+    addresses: readonly string[];
+} | {
+    /** Registry fiber UUID whose role-map is consulted (`Role`). */
+    registryFiberId: string;
+    /** Field/key in that fiber's state holding the `{<address>: true}` role map (`Role`). */
+    roleField: string;
+};
+/**
+ * `upgradePolicy` — the upgrade-path constitution. Chain: `UpgradePolicy`. The three
+ * bare variants encode as LOWERCASE tag STRINGS (`"immutable"` / `"appendOnly"` /
+ * `"arbitrary"`); the `Governed` arm encodes as the object `{ authority: <MigrationAuthority> }`.
+ *
+ * NOTE: this lowercase `"immutable"` is the upgradePolicy DIAL VALUE — distinct from the
+ * policy-level variant tag `"Immutable"` (capital-I), a different construct added in a
+ * later change.
+ */
+export type UpgradePolicy = 'immutable' | 'appendOnly' | 'arbitrary' | {
+    /** Authority that may consent to a `Governed` migration. */
+    authority: MigrationAuthority;
+};
+/**
+ * `transitionPolicy` — WHO may drive a transition on this fiber. Chain: `TransitionPolicy`
+ * (chain PR #194), a bare tag STRING with three ranked levels:
+ *
+ *   - `"Open"` — anyone may drive a transition; the transition's `guard` is the only gate.
+ *     This is the chain DEFAULT when the dial is ABSENT, so omitting it is byte-identical
+ *     to the legacy (pre-#194) behaviour.
+ *   - `"OwnersOrParticipants"` — only the fiber's owners or its declared participants.
+ *   - `"Owners"` — only the fiber's owners.
+ *
+ * Absent ⇒ `"Open"` (chain `transitionPolicy: Option[TransitionPolicy] = None`,
+ * `dropNulls`-stripped). The chain joins this to the tighten-only upgrade lattice, so an
+ * upgrade may only RAISE the level (`Open < OwnersOrParticipants < Owners`); LOOSENING it
+ * (including dropping the dial on a fiber that had it set) is rejected as `CombineRejected`.
+ */
+export type TransitionPolicy = 'Open' | 'OwnersOrParticipants' | 'Owners';
+/**
+ * `compatibleWith` — the inclusive-min / exclusive-max SemVer bridge window a migration
+ * may target. Chain: `VersionRange` (`min: Option[SemVer]`, `max: Option[SemVer]`). Each
+ * bound is a SemVer STRING (`"1.2.3"`); an absent bound is unconstrained on that side and
+ * is `dropNulls`-stripped.
+ */
+export interface VersionRange {
+    /** Inclusive lower bound, e.g. `"1.0.0"` (absent ⇒ unconstrained below). */
+    min?: string;
+    /** Exclusive upper bound, e.g. `"2.0.0"` (absent ⇒ unconstrained above). */
+    max?: string;
+}
+/**
+ * `FiberPolicy` — the constitution a definition declares for the fibers it spawns.
+ *
+ * This MIRRORS the chain ADT `FiberPolicy = Unconstrained | Immutable | Constrained(<dials>)`
+ * (chain branch `feat/fiber-policy-adt`). The representation here is chosen for
+ * BYTE-FOR-BYTE wire parity with the chain, because a `StateMachineDefinition` is
+ * signed verbatim by the SDK (`batchSign(dropNulls(...))`) and re-encoded + verified
+ * by the chain. The rule is:
+ *
+ *   - **`Unconstrained`** ⇒ there is **NO `policy` key** on the wire definition at all.
+ *     In the SDK this is the DEFAULT and is represented by simply OMITTING `policy`
+ *     (i.e. `policy === undefined`).
+ *   - **`Immutable`** ⇒ the definition is permanently locked; `policy` is the bare JSON
+ *     STRING `"Immutable"` (EXACT casing, capital-I) — NOT an object. Semantically this is
+ *     the upgradePolicy DIAL set to its LOWERCASE `"immutable"` value with no other dial
+ *     set, and the chain collapses that exact `Constrained` into the `Immutable` variant.
+ *     See {@link immutable} and the canonical collapse in {@link projectFiberPolicy}.
+ *   - **`Constrained(dials)`** ⇒ `policy` is a bare object of ONLY the dials that are
+ *     SET. Unset dials are absent (the chain `dropNulls`-strips them; so does the SDK
+ *     at sign time). A `Constrained` with no dials set is wire-indistinguishable from
+ *     `Unconstrained`, so `toProtoDefinition` collapses it back to "no policy key".
+ *
+ * All 15 dials are optional. Provide any subset.
+ */
+export interface FiberPolicyDials {
+    /** Whether the fiber may reproduce itself (spawn instances of its own definition). Wire: boolean. */
+    selfReproducing?: boolean;
+    /**
+     * Allow-list of effect families this fiber's transitions may produce, as a SET of the 5
+     * UPPERCASE {@link EffectKind} tokens (`"TRIGGER" | "SPAWN" | "EMIT" | "TRANSFER" |
+     * "DEPENDENCY"`). Order is not significant; duplicates are collapsed by the chain's `Set`.
+     * Chain: `allowedEffects: Option[Set[EffectKind]]`.
+     */
+    allowedEffects?: readonly EffectKind[];
+    /**
+     * Who/what may own fibers this one spawns — an UPPERCASE {@link SpawnOwnerPolicy} token
+     * (`"EXPLICIT" | "SUBSETOFPARENT" | "INHERITPARENT"`). Chain: `spawnOwnerPolicy: Option[SpawnOwnerPolicy]`.
+     */
+    spawnOwnerPolicy?: SpawnOwnerPolicy;
+    /** Maximum spawn-generation depth (descendant chain length). Wire: number. */
+    maxGenerations?: number;
+    /** Maximum number of children a single transition may spawn. Wire: number. */
+    maxSpawnFanout?: number;
+    /** SET of caller fiber UUIDs permitted to drive transitions on this fiber. Wire: string[]. */
+    acceptedCallers?: readonly string[];
+    /** SET of state ids that are sealed (no transition may fire from them). Wire: string[]. */
+    sealedStates?: readonly string[];
+    /**
+     * WHO may drive a transition on this fiber — a {@link TransitionPolicy} bare tag
+     * (`"Open" | "OwnersOrParticipants" | "Owners"`). Absent ⇒ `"Open"` (guard-only, the
+     * chain default); set `"Owners"`/`"OwnersOrParticipants"` to gate transitions by identity
+     * in ADDITION to the guard. Chain: `transitionPolicy: Option[TransitionPolicy]` (chain PR #194).
+     */
+    transitionPolicy?: TransitionPolicy;
+    /**
+     * Recipient allowlist for `_transferAsset` — the {@link TransferPolicy} object
+     * `{ allowedRecipientFibers?: uuid[], allowedRecipientWallets?: DAG-address[] }`.
+     * Chain: `transferPolicy: Option[TransferPolicy]`.
+     */
+    transferPolicy?: TransferPolicy;
+    /**
+     * Dynamic-dependency policy — the {@link DependencyPolicy} object `{ mode, allowed? }`
+     * where `mode` is the REQUIRED UPPERCASE {@link DependencyMode}. Chain:
+     * `dependencyPolicy: Option[DependencyPolicy]`.
+     */
+    dependencyPolicy?: DependencyPolicy;
+    /**
+     * In-place upgrade/migration posture — an {@link UpgradePolicy}: a LOWERCASE bare tag
+     * (`"immutable" | "appendOnly" | "arbitrary"`) OR the `Governed` object
+     * `{ authority: <MigrationAuthority> }`. Chain: `upgradePolicy: Option[UpgradePolicy]`.
+     */
+    upgradePolicy?: UpgradePolicy;
+    /** Self-declared SemVer of this definition as a STRING `"major.minor.patch"` (e.g. `"1.2.3"`). Chain: `version: Option[SemVer]`. */
+    version?: string;
+    /**
+     * Migration bridge window — the {@link VersionRange} object `{ min?: semver, max?: semver }`
+     * naming the successor versions this definition declares it will migrate TO. Chain:
+     * `compatibleWith: Option[VersionRange]`.
+     */
+    compatibleWith?: VersionRange;
+    /** SET of (ERC-165-style) interface identifiers this definition advertises. Wire: string[]. */
+    interfaces?: readonly string[];
+    /**
+     * Authority permitted to authorize a `Governed` migration — a {@link MigrationAuthority}:
+     * `{ addresses: DAG-address[] }` (Signers) OR `{ registryFiberId: uuid, roleField: string }`
+     * (Role), discriminated by disjoint fields. Chain: `migrationAuthority: Option[MigrationAuthority]`.
+     */
+    migrationAuthority?: MigrationAuthority;
+}
+/**
+ * The wire (and authoring) tag for the `Immutable` policy VARIANT: the bare JSON string
+ * `"Immutable"`. EXACT casing, capital-I — this is the POLICY-LEVEL variant name and is
+ * DISTINCT from the `upgradePolicy` dial VALUE `"immutable"` (lowercase). The chain emits
+ * exactly this capital-I string for `Immutable`, so the SDK must too, byte-for-byte.
+ */
+export declare const IMMUTABLE_POLICY: "Immutable";
+export type ImmutablePolicy = typeof IMMUTABLE_POLICY;
+/**
+ * Wire form of a `FiberPolicy`. Mirrors the chain ADT's non-`Unconstrained` arms:
+ *
+ *   - a bare object of the SET dials — the `Constrained` arm. Unset dials are stripped at
+ *     projection time (and again by `dropNulls` at sign time), so this object matches the
+ *     chain's `dropNulls`-stripped `Constrained` encoding exactly; OR
+ *   - the bare JSON string `"Immutable"` — the {@link ImmutablePolicy} arm.
+ *
+ * (`Unconstrained` has no wire representation: it is the absence of the `policy` key.)
+ */
+export type FiberPolicy = FiberPolicyDials | ImmutablePolicy;
+/**
+ * The canonical UNCONSTRAINED policy: omission. Provided as a named export for
+ * readability at call sites — `policy: unconstrained()` documents intent, and projects
+ * to NO `policy` key (identical to leaving `policy` off entirely).
+ */
+export declare function unconstrained(): undefined;
+/**
+ * The canonical IMMUTABLE policy: the definition is permanently locked. Projects to the
+ * bare JSON string `"Immutable"` ({@link IMMUTABLE_POLICY}), the chain's `Immutable`
+ * variant tag. Semantically equivalent to `constrained({ upgradePolicy: 'immutable' })`
+ * with no other dial set — which `constrained()`/`projectFiberPolicy()` collapse to the
+ * same string for wire parity (see {@link constrained}).
+ *
+ * @example
+ * ```ts
+ * const def = defineFiberApp({ ...spec, policy: immutable() });
+ * ```
+ */
+export declare function immutable(): ImmutablePolicy;
+/**
+ * Build a CONSTRAINED `FiberPolicy` from any subset of the 15 dials.
+ *
+ * Pass only the dials you want to set. Dials left `undefined`/`null` are dropped so the
+ * result is a clean, minimal object that serializes identically to the chain's
+ * `dropNulls`-stripped `Constrained`. If NO dial is effectively set, this returns
+ * `undefined` (an empty constraint == `Unconstrained`), which projects to no `policy`
+ * key — preserving wire parity.
+ *
+ * CANONICAL COLLAPSE: `constrained({ upgradePolicy: 'immutable' })` with NO other dial set
+ * collapses to the bare string `"Immutable"` ({@link IMMUTABLE_POLICY}), because the chain
+ * collapses that exact `Constrained` into the `Immutable` variant. NOTE the casing: the
+ * collapse triggers on the chain's LOWERCASE upgradePolicy dial value `"immutable"`, and
+ * the result is the capital-I policy-variant tag `"Immutable"`. Signing the dials object
+ * `{ "upgradePolicy": "immutable" }` instead would diverge the canonical (the chain
+ * re-encodes it as `"Immutable"`) and break the create signature. Adding ANY other dial
+ * keeps it a dials object.
+ *
+ * @example
+ * ```ts
+ * const policy = constrained({
+ *   selfReproducing: false,
+ *   maxGenerations: 3,
+ *   allowedEffects: ['EMIT', 'TRANSFER'],
+ *   sealedStates: ['ARCHIVED'],
+ * });
+ * ```
+ */
+export declare function constrained(dials: FiberPolicyDials): FiberPolicy | undefined;
+/**
+ * Project an authoring `policy` value onto the wire form. Returns one of:
+ *   - `undefined` when the policy is (effectively) `Unconstrained` — i.e. omit the `policy`
+ *     key entirely;
+ *   - the bare string `"Immutable"` ({@link IMMUTABLE_POLICY}) for the `Immutable` variant
+ *     (also the collapse of a lone LOWERCASE `upgradePolicy: 'immutable'`); or
+ *   - the minimal `Constrained` dials object otherwise.
+ *
+ * Centralizes the omit-on-unconstrained AND the Immutable-collapse parity rules so every
+ * projection path (`toProtoDefinition`, the genesis manifest) stays consistent.
+ */
+export declare function projectFiberPolicy(policy: FiberPolicy | undefined): FiberPolicy | undefined;
 export interface FiberAppMetadata {
     name: string;
     app: string;
@@ -125,6 +388,16 @@ export interface CrossReferences {
 }
 export interface FiberAppDefinition<TState extends string = string, TEvent extends string = string> {
     metadata: FiberAppMetadata;
+    /**
+     * Fiber constitution. Mirrors the chain ADT `FiberPolicy = Unconstrained | Immutable |
+     * Constrained(<dials>)`. OMIT this field (the default) for `Unconstrained` — the projected
+     * wire definition then has NO `policy` key. Set it to `immutable()` to permanently lock the
+     * definition (projects to the bare string `"Immutable"`). Set it to a `constrained({...})`
+     * object to declare a subset of the 15 dials; unset dials are stripped so the wire form
+     * matches the chain's `dropNulls`-stripped `Constrained` byte-for-byte (and a lone
+     * `upgradePolicy: 'immutable'` collapses to `"Immutable"`).
+     */
+    policy?: FiberPolicy;
     /** Schema for fiber creation inputs (user-provided) */
     createSchema?: {
         required?: readonly string[];
@@ -192,10 +465,17 @@ export interface ProtoStateMachineDefinition {
         eventName: string;
         guard?: unknown;
         effect?: unknown;
-        dependencies?: unknown[];
-        emits?: unknown[];
+        dependencies: string[];
     }>;
     metadata?: Record<string, unknown>;
+    /**
+     * Fiber constitution. PRESENT for `Constrained` (a bare object of the SET dials) and for
+     * `Immutable` (the bare string `"Immutable"`); ABSENT for `Unconstrained`. This
+     * omit-on-unconstrained rule is the wire parity contract: the chain emits no `policy` key
+     * for `Unconstrained`, so neither may the SDK, or the signature breaks (HTTP 400). See
+     * {@link projectFiberPolicy}.
+     */
+    policy?: FiberPolicy;
 }
 /**
  * Extract proto-compatible StateMachineDefinition from a FiberAppDefinition.

package/dist/types/schema/guard-lint.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 type { FiberAppDefinition } from './fiber-app.js';
+export type LintSeverity = 'error' | 'warn';
+export interface LintViolation {
+    /** App identifier (`metadata.app/metadata.type` or `metadata.name`), when known. */
+    app?: string;
+    /** `eventName` (or `from→to`) of the offending transition, when applicable. */
+    transition?: string;
+    severity: LintSeverity;
+    /** Stable machine-readable rule code (see {@link LINT_CODES}). */
+    code: string;
+    /** Human-readable explanation including the correct alternative. */
+    message: string;
+    /** JSON-ish path to the offending node, e.g. `transitions[3].guard.or[0].var`. */
+    path: string;
+}
+/** Stable rule codes — referenced by tests and by report tooling. */
+export declare const LINT_CODES: {
+    readonly UNKNOWN_RESERVED_VAR: "unknown-reserved-var";
+    readonly UNKNOWN_OPERATOR: "unknown-operator";
+    readonly WITNESS_IN_TRANSITION: "witness-in-transition";
+    readonly DROPPED_DIRECTIVE: "dropped-directive";
+    readonly LEADING_DOT_VAR: "leading-dot-var";
+};
+/**
+ * The ONLY `$`-prefixed keys the engine injects (`ReservedKeys`). Anything else
+ * (`$timestamp`, `$now`, ...) resolves to null on chain.
+ */
+export declare const INJECTED_RESERVED_VARS: ReadonlySet<string>;
+/**
+ * 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 declare const KNOWN_BAD_OPERATORS: ReadonlyMap<string, string>;
+interface WalkContext {
+    app?: string;
+    transition?: string;
+    /**
+     * When true, this transition expression runs in a context where `witness` is
+     * NOT injected (a fiber transition guard/effect). Reading `witness.*` here is
+     * a bug (rule 3). Asset-guard contexts would set this false (not walked here).
+     */
+    flagWitness: boolean;
+}
+/**
+ * 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 declare function lintGuardExpression(node: unknown, ctx: WalkContext, path: string, inDataLiteral?: boolean): LintViolation[];
+/**
+ * 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 declare function lintFiberApp(def: FiberAppDefinition): LintViolation[];
+/**
+ * Convenience: lint many apps at once, returning a flat list. Each app's
+ * violations already carry its `app` label.
+ */
+export declare function lintFiberApps(defs: readonly FiberAppDefinition[]): LintViolation[];
+export {};

package/dist/types/schema/guards.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+/** A JSON-Logic guard expression (plain JSON). */
+export type GuardRule = Record<string, unknown>;
+/**
+ * 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 declare const signerIsParty: (partyVar: string) => GuardRule;
+/** FIBER-transition authorization where ANY of the pinned parties signed (e.g. borrower OR lender). */
+export declare const signerIsAnyParty: (partyVars: string[]) => GuardRule;
+/**
+ * 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 declare const signerInSet: (setVar: string) => GuardRule;
+/**
+ * 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 declare const signerIsNotParty: (partyVar: string) => GuardRule;
+/**
+ * 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 declare const signerHasEntry: (mapVar: string) => GuardRule;
+/**
+ * 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 declare const assetSignerIs: (addressVar: string) => GuardRule;
+/**
+ * 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 declare const actorIsSigner: (actorVar?: string) => GuardRule;
+/**
+ * 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 declare const actorInSet: (setVar: string, actorVar?: string) => GuardRule;
+/**
+ * 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 declare const actorHasEntry: (mapVar: string, actorVar?: string) => GuardRule;
+/**
+ * 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 declare const signerHasReputation: (repMapVar: string, thresholdVar: string) => GuardRule;
+/**
+ * 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 declare const signerHasRole: (roleMapVar: string) => GuardRule;
+/**
+ * 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 declare const signerHasReputationVia: (registryIdVar: string, thresholdVar: string) => GuardRule;
+/**
+ * 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 declare const signerHasRoleVia: (registryIdVar: string, roleField: string) => GuardRule;
+/**
+ * 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 declare const actorNotInArray: (arrayVar: string, field?: string, actorVar?: string) => GuardRule;
+export declare const depInState: (refVar: string, requiredState: string) => GuardRule;

package/dist/types/signing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { SignatureProof, Signed, SigningOptions } from '@constellation-network/metagraph-sdk';
+/**
+ * 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 declare function signDataUpdate<T>(data: T, privateKey: string): SignatureProof;
+/**
+ * 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 declare function createSignedObject<T>(value: T, privateKey: string, options?: SigningOptions): Signed<T>;
+/**
+ * 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 declare function addSignature<T>(signed: Signed<T>, privateKey: string, options?: SigningOptions): Signed<T>;
+/**
+ * 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 declare function batchSign<T>(value: T, privateKeys: string[], options?: SigningOptions): Signed<T>;