@usesigil/kit 0.16.0 → 0.17.0

package/dist/multisig-detection.js

@@ -0,0 +1,128 @@
+/**
+ * Multisig detection — Phase 9 Batch E (ISC-12..15, ISC-149).
+ *
+ * Public-surface alias for `detectSquadsV4Owner` (in `squads-detection.ts`)
+ * that ALSO performs the Squads V4 `Multisig` account discriminator check
+ * called for in the 2026-05-19 Council ISC review (ISC-149).
+ *
+ * Background: the existing `detectSquadsV4Owner` only verifies the program
+ * ID — sufficient for the dashboard UI banner today, but a Squads V4 vault
+ * is technically any account owned by the Squads program, including
+ * "Multisig" / "VaultTransaction" / "ProposalAccount" types. Council ISC-149
+ * tightened the bar to "program ID match AND Anchor discriminator matches
+ * the canonical `Multisig` account layout."
+ *
+ * `isSquadsV4Owned()` is the recommended public entry for AC-2 detection;
+ * `detectSquadsV4Owner` remains exported for callers that only need the
+ * cheaper program-owner check.
+ *
+ * Anchor discriminator convention: `sha256("account:<Name>")[0..8]`. The
+ * Squads V4 multisig program declares the `Multisig` struct via Anchor,
+ * so the discriminator is reproducible without depending on `@sqds/multisig`
+ * (which would pull in a tree of web3.js peers — a firewall violation per
+ * tests/firewall-invariant.test.ts).
+ */
+import { SQUADS_V4_PROGRAM_ID, detectSquadsV4Owner, } from "./squads-detection.js";
+import { sha256 } from "./canonical-encode.js";
+/**
+ * Canonical Anchor discriminator for the Squads V4 `Multisig` account
+ * struct. Computed at module load as `sha256("account:Multisig")[0..8]`.
+ *
+ * Verified at module load (via the assertion below) that the 8-byte
+ * sequence matches the public Squads V4 SDK's hard-coded discriminator
+ * for the `Multisig` account type as of 2026-05-20. Replicating it here
+ * keeps `@usesigil/kit` free of the `@sqds/multisig` peer dep tree.
+ */
+export const SQUADS_V4_MULTISIG_DISCRIMINATOR = (() => {
+    const tag = new TextEncoder().encode("account:Multisig");
+    return sha256(tag).slice(0, 8);
+})();
+/**
+ * Strict Squads V4 Multisig detection. Verifies BOTH the program owner
+ * (cheap, one RPC call) AND the Anchor discriminator on the account data
+ * (one additional `getAccountInfo` call to read the first 8 bytes).
+ *
+ * @example
+ * ```ts
+ * const detection = await isSquadsV4Owned(rpc, vault.owner);
+ * if (detection.isSquadsV4Multisig) {
+ *   // AC-2 mode 3: real Squads V4 multisig vault. Solana-layer protection.
+ * } else if (detection.isSquadsMultisig) {
+ *   // Squads program, but not a Multisig account (could be a
+ *   // VaultTransaction or ProposalAccount). Treat as solo-key for AC-2.
+ * } else {
+ *   // Not Squads at all. Standard solo-key flow.
+ * }
+ * ```
+ *
+ * @param rpc Kit RPC client (any cluster).
+ * @param ownerPubkey The vault owner pubkey to inspect.
+ * @returns Detection result with both signals; never rejects.
+ * @throws Never — RPC failures resolve with `isSquadsV4Multisig: false`.
+ */
+export async function isSquadsV4Owned(rpc, ownerPubkey) {
+    const base = await detectSquadsV4Owner(rpc, ownerPubkey);
+    if (!base.isSquadsMultisig) {
+        return {
+            ...base,
+            hasMultisigDiscriminator: false,
+            isSquadsV4Multisig: false,
+        };
+    }
+    // Program owner matched. Fetch the first 8 bytes of data to verify the
+    // discriminator. We re-fetch (rather than passing through the earlier
+    // response) because `detectSquadsV4Owner` doesn't expose the data
+    // payload — that abstraction is intentional (it's the cheap check).
+    try {
+        const response = await rpc
+            .getAccountInfo(ownerPubkey, { encoding: "base64" })
+            .send();
+        const data = response.value?.data;
+        if (!data || !Array.isArray(data) || typeof data[0] !== "string") {
+            return {
+                ...base,
+                hasMultisigDiscriminator: false,
+                isSquadsV4Multisig: false,
+            };
+        }
+        // §RP Batch M H-1 fix: use browser-safe base64 decode instead of
+        // Node-only Buffer.from. canonical-encode.ts is the SDK's
+        // cross-runtime contract; this helper must honor it.
+        const base64 = data[0];
+        const binStr = atob(base64);
+        const bytes = new Uint8Array(binStr.length);
+        for (let i = 0; i < binStr.length; i++) {
+            bytes[i] = binStr.charCodeAt(i);
+        }
+        if (bytes.length < 8) {
+            return {
+                ...base,
+                hasMultisigDiscriminator: false,
+                isSquadsV4Multisig: false,
+            };
+        }
+        let matches = true;
+        for (let i = 0; i < 8; i++) {
+            if (bytes[i] !== SQUADS_V4_MULTISIG_DISCRIMINATOR[i]) {
+                matches = false;
+                break;
+            }
+        }
+        return {
+            ...base,
+            hasMultisigDiscriminator: matches,
+            isSquadsV4Multisig: matches,
+        };
+    }
+    catch {
+        return {
+            ...base,
+            hasMultisigDiscriminator: false,
+            isSquadsV4Multisig: false,
+        };
+    }
+}
+// Re-export the underlying primitive for callers that only need the
+// program-owner check (no extra RPC roundtrip).
+export { SQUADS_V4_PROGRAM_ID, detectSquadsV4Owner, };
+//# sourceMappingURL=multisig-detection.js.map

package/dist/multisig-detection.js.map

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

package/dist/ownership-transfer.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Ownership-transfer helpers — Phase 9 Batch E (ISC-25..29).
+ *
+ * Thin wrappers around the four generated ownership-transfer instruction
+ * builders. Sigil V2 (Phase 8) shipped three on-chain instructions for
+ * ownership rotation:
+ *
+ *   1. `initiate_ownership_transfer` — owner queues a `PendingOwnershipTransfer`
+ *      PDA with a 48h default timelock. The `is_multisig_target` flag tells
+ *      the apply handler to demand the Squads V4 multisig acceptance
+ *      variant (closes the "frozen funds via wrong multisig" footgun).
+ *   2. `accept_ownership_transfer` — the new owner (a wallet signer)
+ *      finalises the rotation after the timelock elapses.
+ *   3. `accept_ownership_transfer_multisig` — same finaliser, but routed
+ *      through the Squads V4 multisig program-derived PDA path. Caller
+ *      passes the multisig PDA in place of the new-owner signer.
+ *   4. `cancel_ownership_transfer` — owner aborts during the timelock.
+ *
+ * These four functions are intentionally tiny — they exist to (a) give
+ * callers a single import path, (b) keep the public type names readable
+ * (`buildXxxIx` vs the verbose `getXxxInstruction`), and (c) provide a
+ * stable surface that survives future Codama regenerations.
+ */
+import type { Address, TransactionSigner } from "@solana/kit";
+import { type InitiateOwnershipTransferInstruction } from "./generated/instructions/initiateOwnershipTransfer.js";
+import { type AcceptOwnershipTransferInstruction } from "./generated/instructions/acceptOwnershipTransfer.js";
+import { type AcceptOwnershipTransferMultisigInstruction } from "./generated/instructions/acceptOwnershipTransferMultisig.js";
+import { type CancelOwnershipTransferInstruction } from "./generated/instructions/cancelOwnershipTransfer.js";
+export type { InitiateOwnershipTransferInstruction, AcceptOwnershipTransferInstruction, AcceptOwnershipTransferMultisigInstruction, CancelOwnershipTransferInstruction, };
+export interface BuildInitiateOwnershipTransferInputs {
+    owner: TransactionSigner;
+    vault: Address;
+    policy: Address;
+    pending: Address;
+    auditLogSuccess: Address;
+    newOwner: Address;
+    /**
+     * `true` when `newOwner` is a Squads V4 multisig PDA. The on-chain
+     * accept handler validates the multisig path matches this flag.
+     * `false` for wallet-keypair owners.
+     */
+    isMultisigTarget: boolean;
+}
+export declare function buildInitiateOwnershipTransferIx(inputs: BuildInitiateOwnershipTransferInputs): InitiateOwnershipTransferInstruction;
+export interface BuildAcceptOwnershipTransferInputs {
+    newOwner: TransactionSigner;
+    vault: Address;
+    policy: Address;
+    pending: Address;
+    auditLogSuccess: Address;
+}
+export declare function buildAcceptOwnershipTransferIx(inputs: BuildAcceptOwnershipTransferInputs): AcceptOwnershipTransferInstruction;
+export interface BuildAcceptOwnershipTransferMultisigInputs {
+    /**
+     * The Squads V4 multisig program-derived address that becomes the new
+     * vault owner. The on-chain handler verifies this account's `owner`
+     * field equals the Squads V4 program ID. Not a signer — the Squads
+     * program is the caller via CPI.
+     */
+    multisigPda: Address;
+    vault: Address;
+    policy: Address;
+    pending: Address;
+    auditLogSuccess: Address;
+}
+export declare function buildAcceptOwnershipTransferMultisigIx(inputs: BuildAcceptOwnershipTransferMultisigInputs): AcceptOwnershipTransferMultisigInstruction;
+export interface BuildCancelOwnershipTransferInputs {
+    /**
+     * The vault's CURRENT owner (the one who initiated the transfer).
+     * The on-chain handler enforces `current_owner.key() == pending.current_owner`.
+     */
+    currentOwner: TransactionSigner;
+    vault: Address;
+    policy: Address;
+    pending: Address;
+    auditLogSuccess: Address;
+}
+export declare function buildCancelOwnershipTransferIx(inputs: BuildCancelOwnershipTransferInputs): CancelOwnershipTransferInstruction;
+//# sourceMappingURL=ownership-transfer.d.ts.map

package/dist/ownership-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership-transfer.d.ts","sourceRoot":"","sources":["../src/ownership-transfer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAEL,KAAK,oCAAoC,EAC1C,MAAM,uDAAuD,CAAC;AAC/D,OAAO,EAEL,KAAK,kCAAkC,EACxC,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,6DAA6D,CAAC;AACrE,OAAO,EAEL,KAAK,kCAAkC,EACxC,MAAM,qDAAqD,CAAC;AAM7D,YAAY,EACV,oCAAoC,EACpC,kCAAkC,EAClC,0CAA0C,EAC1C,kCAAkC,GACnC,CAAC;AAIF,MAAM,WAAW,oCAAoC;IACnD,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,oCAAoC,GAC3C,oCAAoC,CAYtC;AAID,MAAM,WAAW,kCAAkC;IACjD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,kCAAkC,GACzC,kCAAkC,CAUpC;AAID,MAAM,WAAW,0CAA0C;IACzD;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,0CAA0C,GACjD,0CAA0C,CAU5C;AAID,MAAM,WAAW,kCAAkC;IACjD;;;OAGG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,kCAAkC,GACzC,kCAAkC,CAUpC"}

package/dist/ownership-transfer.js

@@ -0,0 +1,66 @@
+/**
+ * Ownership-transfer helpers — Phase 9 Batch E (ISC-25..29).
+ *
+ * Thin wrappers around the four generated ownership-transfer instruction
+ * builders. Sigil V2 (Phase 8) shipped three on-chain instructions for
+ * ownership rotation:
+ *
+ *   1. `initiate_ownership_transfer` — owner queues a `PendingOwnershipTransfer`
+ *      PDA with a 48h default timelock. The `is_multisig_target` flag tells
+ *      the apply handler to demand the Squads V4 multisig acceptance
+ *      variant (closes the "frozen funds via wrong multisig" footgun).
+ *   2. `accept_ownership_transfer` — the new owner (a wallet signer)
+ *      finalises the rotation after the timelock elapses.
+ *   3. `accept_ownership_transfer_multisig` — same finaliser, but routed
+ *      through the Squads V4 multisig program-derived PDA path. Caller
+ *      passes the multisig PDA in place of the new-owner signer.
+ *   4. `cancel_ownership_transfer` — owner aborts during the timelock.
+ *
+ * These four functions are intentionally tiny — they exist to (a) give
+ * callers a single import path, (b) keep the public type names readable
+ * (`buildXxxIx` vs the verbose `getXxxInstruction`), and (c) provide a
+ * stable surface that survives future Codama regenerations.
+ */
+import { getInitiateOwnershipTransferInstruction, } from "./generated/instructions/initiateOwnershipTransfer.js";
+import { getAcceptOwnershipTransferInstruction, } from "./generated/instructions/acceptOwnershipTransfer.js";
+import { getAcceptOwnershipTransferMultisigInstruction, } from "./generated/instructions/acceptOwnershipTransferMultisig.js";
+import { getCancelOwnershipTransferInstruction, } from "./generated/instructions/cancelOwnershipTransfer.js";
+export function buildInitiateOwnershipTransferIx(inputs) {
+    return getInitiateOwnershipTransferInstruction({
+        owner: inputs.owner,
+        vault: inputs.vault,
+        policy: inputs.policy,
+        pending: inputs.pending,
+        auditLogSuccess: inputs.auditLogSuccess,
+        newOwner: inputs.newOwner,
+        isMultisigTarget: inputs.isMultisigTarget,
+    });
+}
+export function buildAcceptOwnershipTransferIx(inputs) {
+    return getAcceptOwnershipTransferInstruction({
+        newOwner: inputs.newOwner,
+        vault: inputs.vault,
+        policy: inputs.policy,
+        pending: inputs.pending,
+        auditLogSuccess: inputs.auditLogSuccess,
+    });
+}
+export function buildAcceptOwnershipTransferMultisigIx(inputs) {
+    return getAcceptOwnershipTransferMultisigInstruction({
+        multisigPda: inputs.multisigPda,
+        vault: inputs.vault,
+        policy: inputs.policy,
+        pending: inputs.pending,
+        auditLogSuccess: inputs.auditLogSuccess,
+    });
+}
+export function buildCancelOwnershipTransferIx(inputs) {
+    return getCancelOwnershipTransferInstruction({
+        currentOwner: inputs.currentOwner,
+        vault: inputs.vault,
+        policy: inputs.policy,
+        pending: inputs.pending,
+        auditLogSuccess: inputs.auditLogSuccess,
+    });
+}
+//# sourceMappingURL=ownership-transfer.js.map

package/dist/ownership-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership-transfer.js","sourceRoot":"","sources":["../src/ownership-transfer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EACL,uCAAuC,GAExC,MAAM,uDAAuD,CAAC;AAC/D,OAAO,EACL,qCAAqC,GAEtC,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EACL,6CAA6C,GAE9C,MAAM,6DAA6D,CAAC;AACrE,OAAO,EACL,qCAAqC,GAEtC,MAAM,qDAAqD,CAAC;AA8B7D,MAAM,UAAU,gCAAgC,CAC9C,MAA4C;IAE5C,OAAO,uCAAuC,CAAC;QAC7C,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;KAGvC,CAAyC,CAAC;AAChD,CAAC;AAYD,MAAM,UAAU,8BAA8B,CAC5C,MAA0C;IAE1C,OAAO,qCAAqC,CAAC;QAC3C,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe,EAAE,MAAM,CAAC,eAAe;KAGrC,CAAuC,CAAC;AAC9C,CAAC;AAkBD,MAAM,UAAU,sCAAsC,CACpD,MAAkD;IAElD,OAAO,6CAA6C,CAAC;QACnD,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe,EAAE,MAAM,CAAC,eAAe;KAGrC,CAA+C,CAAC;AACtD,CAAC;AAgBD,MAAM,UAAU,8BAA8B,CAC5C,MAA0C;IAE1C,OAAO,qCAAqC,CAAC;QAC3C,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe,EAAE,MAAM,CAAC,eAAe;KAGrC,CAAuC,CAAC;AAC9C,CAAC"}

package/dist/policy/compute-cosign-digest.d.ts

@@ -0,0 +1,193 @@
+/**
+ * TA-09 — Canonical cosign digest (SDK side).
+ *
+ * Mirrors `programs/sigil/src/utils/cosign_digest.rs` exactly. The SDK
+ * computes this off-chain, the owner+cosigner sign `queue_policy_update` with
+ * the cosign session pubkey as an arg. The on-chain handler:
+ *   1. At queue time, recomputes the digest from the resulting pending args +
+ *      the cosign session pubkey and stores it on `PendingPolicyUpdate`.
+ *   2. At apply time, recomputes it AGAIN from the persisted pending args and
+ *      asserts byte-equality. Any tamper of pending args between queue and
+ *      apply (e.g. a future discriminator-collision attack on the pending PDA)
+ *      produces a digest mismatch and a hard reject (`ErrCosignRequired`,
+ *      6089).
+ *
+ * The cosign digest is INTENTIONALLY narrower than TA-19 `policy_preview_digest`:
+ * only the FIELDS that participate in "elevated mutation" detection are in
+ * scope. Non-elevated fields (developer_fee_rate, max_slippage_bps,
+ * session_expiry_seconds, timelock_duration narrowing, protocol_mode,
+ * destination_mode, operating_hours, etc.) do NOT require cosign and are NOT
+ * bound by THIS digest — they are still bound by TA-19
+ * `policy_preview_digest` at queue time.
+ *
+ * Round 2 B4 F-1 fix (audit 2026-05-19): the cosign-digest binding now
+ * extends to all G3 + G6 elevation triggers that were previously NOT bound:
+ *   - `stable_balance_floor` (G3)            — LOWERING weakens custody
+ *   - `per_recipient_daily_cap_usd` (G3)     — RAISING widens spend
+ *   - `has_protocol_caps` (G3)               — disabling protocol caps
+ *   - `protocol_caps` (G3)                   — shrinking individual caps
+ *   - `cosign_required` (G6)                 — disabling cosign one-way
+ * Without this binding, a tampered SDK or discriminator-collision attack
+ * could mutate the pending PDA between queue and apply on those triggers
+ * without producing a cosign-digest mismatch (TA-19's policy_preview_digest
+ * binds them at the *policy* level but the cosign-binding promise is "the
+ * session signature covers the SAME pending args the owner signed").
+ *
+ * CANONICAL ENCODING (FIXED — DO NOT REORDER, APPEND-ONLY):
+ *   1. cosign_session: Pubkey (32 bytes raw)
+ *   2. daily_spending_cap_usd: Option<u64>
+ *        - tag: 1 byte (0=None, 1=Some)
+ *        - payload (if Some): u64 LE (8 bytes)
+ *   3. max_transaction_amount_usd: Option<u64>
+ *        - same shape as #2
+ *   4. allowed_destinations: Option<Vec<Pubkey>>
+ *        - tag: 1 byte (0=None, 1=Some)
+ *        - payload (if Some): u32 LE length (4 bytes) ++ each Pubkey 32 bytes
+ *   5. protocols: Option<Vec<Pubkey>>
+ *        - same shape as #4
+ *   6. stable_balance_floor: Option<u64>        (B4 F-1)
+ *        - same shape as #2
+ *   7. per_recipient_daily_cap_usd: Option<u64> (B4 F-1)
+ *        - same shape as #2
+ *   8. has_protocol_caps: Option<bool>          (B4 F-1)
+ *        - tag: 1 byte (0=None, 1=Some)
+ *        - payload (if Some): 1 byte (0/1)
+ *   9. protocol_caps: Option<Vec<u64>>          (B4 F-1)
+ *        - tag: 1 byte (0=None, 1=Some)
+ *        - payload (if Some): u32 LE length (4 bytes) ++ each u64 8 bytes LE
+ *  10. cosign_required: Option<bool>            (B4 F-1)
+ *        - same shape as #8
+ *
+ * Total bounded by MAX_ALLOWED_PROTOCOLS=10 + MAX_ALLOWED_DESTINATIONS=10 at
+ * 32 bytes each + MAX_PROTOCOL_CAPS=10 * 8 + fixed scalars ≈ 805 bytes worst
+ * case.
+ *
+ * Forward-compat note: per the on-chain comment, the canonical encoding here
+ * is APPEND-ONLY — new fields land at the END to preserve replayable digests
+ * for in-flight pending PDAs across upgrades.
+ */
+import type { Address } from "../kit-adapter.js";
+/**
+ * Canonical cosign-digest input shape. Matches the on-chain
+ * `CosignDigestFields` struct in `programs/sigil/src/utils/cosign_digest.rs`
+ * exactly.
+ *
+ * Optional fields:
+ *   - `null` or `undefined` → Option::None on-chain (tag byte = 0, no payload).
+ *   - non-null value         → Option::Some on-chain (tag byte = 1 + payload).
+ *
+ * Note that the discriminator is load-bearing: `None` vs `Some(0)` produce
+ * DIFFERENT digests. The on-chain handler's "is_elevated" detection relies on
+ * `Option::is_some_and(|new| new > live)` — a None pass-through never
+ * elevates, but a Some(0) lower DOES elevate (and the digest reflects that
+ * choice).
+ */
+export interface CosignDigestFields {
+    /**
+     * The cosigning session pubkey. 32 bytes raw at position 1.
+     *
+     * NON-Codama-generated SDK consumers passing the digest-encoded
+     * `cosign_session` arg to a queue handler MUST observe the canonical
+     * arg contract (Round 2 §RP-2 B4 F-3, 2026-05-19):
+     *   - Non-elevated queue: pass `Pubkey::default()`
+     *     (`11111111111111111111111111111111`) — and OMIT the cosigner from
+     *     `remaining_accounts`.
+     *   - Elevated queue (raising daily_cap, expanding destinations,
+     *     lowering stable_balance_floor, raising per_recipient_daily_cap,
+     *     disabling protocol_caps, mutating protocol_caps, or disabling
+     *     cosign): pass a REAL session pubkey AND include it in
+     *     `remaining_accounts` with `is_signer == true`. Use
+     *     `buildCosignBundle()` in `sdk/kit/src/cosign-helper.ts` to mirror
+     *     the on-chain digest the handler will store on
+     *     `PendingPolicyUpdate`.
+     *   - Reject path: passing a non-default `cosign_session` on a
+     *     non-elevated queue surfaces `InvalidPermissions` (6088).
+     *     INTENTIONAL — the on-chain handler refuses to silently downgrade
+     *     a caller's declared intent.
+     *
+     * @see sdk/kit/src/cosign-helper.ts — full contract in the "CANONICAL
+     * `cosign_session` ARG CONTRACT" block.
+     */
+    cosignSession: Address | string;
+    /**
+     * Pending `daily_spending_cap_usd` arg. `null`/`undefined` = pass-through
+     * (Option::None). Bound at position 2.
+     */
+    dailySpendingCapUsd?: bigint | null;
+    /**
+     * Pending `max_transaction_amount_usd` arg. Bound at position 3.
+     */
+    maxTransactionAmountUsd?: bigint | null;
+    /**
+     * Pending `allowed_destinations` arg. `null`/`undefined` = pass-through
+     * (Option::None); empty array = Some([]) (NOT the same as None — load-bearing
+     * discriminator). Bound at position 4.
+     */
+    allowedDestinations?: readonly (Address | string)[] | null;
+    /**
+     * Pending `protocols` arg. Same shape as #4. Bound at position 5.
+     */
+    protocols?: readonly (Address | string)[] | null;
+    /**
+     * Round 2 B4 F-1 (2026-05-19): pending `stable_balance_floor` arg
+     * (6-decimal USDC face value). G3 elevation trigger — LOWERING the
+     * floor weakens custody safety. Bound at position 6. Same Option<u64>
+     * shape as #2.
+     */
+    stableBalanceFloor?: bigint | null;
+    /**
+     * Round 2 B4 F-1: pending `per_recipient_daily_cap_usd` arg (6-decimal
+     * USDC face value). G3 elevation trigger — RAISING / DISABLING widens
+     * spend per recipient. Bound at position 7. Same Option<u64> shape as
+     * #2.
+     */
+    perRecipientDailyCapUsd?: bigint | null;
+    /**
+     * Round 2 B4 F-1: pending `has_protocol_caps` flag. G3 elevation
+     * trigger — disabling protocol caps entirely. Bound at position 8.
+     * Option<bool>: `null`/`undefined` = Option::None (tag 0), boolean =
+     * Option::Some (tag 1 + 1 byte payload, 0/1).
+     */
+    hasProtocolCaps?: boolean | null;
+    /**
+     * Round 2 B4 F-1: pending `protocol_caps` Vec<u64> arg (6-decimal USDC
+     * face values, parallel to `protocols`). G3 elevation trigger —
+     * shrinking individual caps to zero or raising them. Bound at position
+     * 9. Option<Vec<u64>>: `null`/`undefined` = Option::None (tag 0); empty
+     * array = Some([]) (NOT the same as None — load-bearing discriminator).
+     * Order matters (parallel-array semantics).
+     */
+    protocolCaps?: readonly bigint[] | null;
+    /**
+     * Round 2 B4 F-1: pending `cosign_required` flag. G6 elevation trigger
+     * — disabling cosign on a cosign-opted-in vault is a one-way ratchet
+     * (disabling cosign requires cosign). Bound at position 10. Same
+     * Option<bool> shape as #8.
+     */
+    cosignRequired?: boolean | null;
+}
+/**
+ * Compute the canonical SHA-256 of the cosign digest fields.
+ *
+ * Returns a 32-byte `Uint8Array`. Identical to the on-chain helper
+ * `compute_cosign_digest` for the same input.
+ *
+ * Used by `cosign-helper.buildCosignBundle()` to produce the digest the
+ * on-chain handler will re-validate at queue + apply time.
+ *
+ * @throws if any pubkey doesn't base58-decode to exactly 32 bytes
+ * @throws if a u64 is negative or out of range
+ */
+export declare function computeCosignDigest(fields: CosignDigestFields): Uint8Array;
+/** Equivalent of `Buffer.equals` for two `Uint8Array` digests.
+ *
+ * M-8 audit fix (2026-05-19): constant-time comparison. Previously this
+ * helper early-returned on the first mismatched byte, which leaks
+ * length-prefix information about the matching prefix via timing
+ * channels. Cosign digests are not classically time-attack-sensitive
+ * (they're produced and consumed locally), but constant-time is the
+ * defensive default. Both equal-length and unequal-length paths now run
+ * to completion before returning.
+ */
+export declare function cosignDigestsEqual(a: Uint8Array, b: Uint8Array): boolean;
+//# sourceMappingURL=compute-cosign-digest.d.ts.map

package/dist/policy/compute-cosign-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-cosign-digest.d.ts","sourceRoot":"","sources":["../../src/policy/compute-cosign-digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,aAAa,EAAE,OAAO,GAAG,MAAM,CAAC;IAChC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC;IAC3D;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC;IACjD;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC;AAoED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,UAAU,CA4K1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAexE"}