@usesigil/kit 0.15.0 → 0.17.0

package/dist/canonical-encode.js

@@ -0,0 +1,141 @@
+/**
+ * Canonical Borsh-style encoder primitives — shared utilities.
+ *
+ * APPEND-ONLY DISCIPLINE. The TA-19 policy preview digest
+ * (`policy/compute-policy-preview-digest.ts`) and the AL3 SealInput intent
+ * digest (`seal/intent-digest.ts`, Phase 9 Batch I) both depend on these
+ * primitives being byte-stable across SDK versions. Adding a new primitive
+ * is fine; CHANGING the byte layout of an existing one would break every
+ * downstream cross-impl Rust↔TS hash and silently invalidate every
+ * previously-signed policy preview digest.
+ *
+ * Mirrors the Rust-side conventions used by `solana_program::hash::hash`
+ * over Borsh-encoded structs:
+ *   - Little-endian for all multi-byte integers (u16/u32/u64).
+ *   - Vec<T> = u32 LE length prefix ++ flat element bytes (no per-element
+ *     framing).
+ *   - bool encoded as u8 (0 or 1; the canonical Borsh wire format).
+ *   - Pubkey = raw 32 bytes (base58 decoded).
+ *   - SHA-256 over the canonical-encoded byte string.
+ *
+ * Primitives are deliberately small, stateless, and side-effect-free so
+ * they can be unit-tested in isolation and reused without surprises.
+ */
+import { sha256 as nobleSha256 } from "@noble/hashes/sha2";
+// ── Base58 decode (no external dep) ─────────────────────────────────────────
+//
+// Solana pubkeys are base58 strings; we need the raw 32 bytes. The SDK has
+// many base58 helpers downstream but importing from `kit-adapter` here would
+// create a cycle (kit-adapter imports from `core/` which is consumed by
+// digest helpers). Inline a small standard-Bitcoin-alphabet decoder.
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const BASE58_INDEX = (() => {
+    const r = Object.create(null);
+    for (let i = 0; i < BASE58_ALPHABET.length; i++) {
+        r[BASE58_ALPHABET[i]] = i;
+    }
+    return r;
+})();
+/**
+ * Decode a Solana base58 pubkey to its 32-byte raw form. Throws on any
+ * input that doesn't decode to exactly 32 bytes (catches malformed
+ * pubkeys before they corrupt the canonical encoding).
+ *
+ * @throws Error if `s` is empty, contains an invalid base58 character,
+ *   or decodes to a byte length other than 32.
+ */
+export function base58Decode32(s) {
+    if (s.length === 0) {
+        throw new Error("base58Decode32: empty input");
+    }
+    let leadingZeros = 0;
+    while (leadingZeros < s.length && s[leadingZeros] === "1") {
+        leadingZeros++;
+    }
+    // Big integer mode: walk digits, base-256 carry.
+    const bytes = [];
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        const v = BASE58_INDEX[c];
+        if (v === undefined) {
+            throw new Error(`base58Decode32: invalid char '${c}'`);
+        }
+        let carry = v;
+        for (let j = 0; j < bytes.length; j++) {
+            carry += bytes[j] * 58;
+            bytes[j] = carry & 0xff;
+            carry >>>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>>= 8;
+        }
+    }
+    // bytes is little-endian; reverse and prepend leading zeros.
+    const out = new Uint8Array(leadingZeros + bytes.length);
+    for (let i = 0; i < bytes.length; i++) {
+        out[leadingZeros + (bytes.length - 1 - i)] = bytes[i];
+    }
+    if (out.length !== 32) {
+        throw new Error(`base58Decode32: expected 32-byte pubkey, got ${out.length} bytes`);
+    }
+    return out;
+}
+// ── Cursor writers ──────────────────────────────────────────────────────────
+//
+// Each writer takes a DataView + offset and returns the new offset. The
+// `DataView` interface is browser- and Node-portable. All multi-byte integers
+// are little-endian (matching `solana_program` + Borsh canonical encoding).
+/** Write u8 (single byte). Returns new offset. */
+export function writeU8(view, offset, v) {
+    view.setUint8(offset, v & 0xff);
+    return offset + 1;
+}
+/** Write u16 little-endian. Returns new offset. */
+export function writeU16Le(view, offset, v) {
+    view.setUint16(offset, v, true);
+    return offset + 2;
+}
+/** Write u32 little-endian. Returns new offset. */
+export function writeU32Le(view, offset, v) {
+    view.setUint32(offset, v, true);
+    return offset + 4;
+}
+/** Write u64 little-endian. Returns new offset. */
+export function writeU64Le(view, offset, v) {
+    view.setBigUint64(offset, v, true);
+    return offset + 8;
+}
+/** Write a bool as a single 0/1 byte. Returns new offset. */
+export function writeBool(view, offset, v) {
+    view.setUint8(offset, v ? 1 : 0);
+    return offset + 1;
+}
+// ── SHA-256 hasher ──────────────────────────────────────────────────────────
+/**
+ * SHA-256 over the input bytes. Backed by `@noble/hashes/sha256` — pure
+ * JS, browser- and Bun-compatible, byte-identical to Node's `node:crypto`
+ * for the same input (TA-19 cross-impl fixture suite verifies this).
+ *
+ * Phase 9 Batch I switched the backend from `node:crypto` to noble so AL3
+ * intent-digest can ship the same primitive across Node, Bun, and the
+ * browser without runtime-conditional imports.
+ */
+export function sha256(input) {
+    return nobleSha256(input);
+}
+/**
+ * Constant-time digest comparison (true if `a` and `b` are byte-equal).
+ * Uses XOR-accumulate with no early exit so timing leaks don't reveal
+ * which prefix matched. Used by cosign + policy-digest verification.
+ */
+export function digestsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let acc = 0;
+    for (let i = 0; i < a.length; i++) {
+        acc |= (a[i] ^ b[i]) & 0xff;
+    }
+    return acc === 0;
+}
+//# sourceMappingURL=canonical-encode.js.map

package/dist/canonical-encode.js.map

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

package/dist/cosign-helper.d.ts

@@ -0,0 +1,264 @@
+/**
+ * G4 (audit close) — TA-09 client-side cosign helper.
+ *
+ * Closes the G4 gate of Phase 6: the on-chain TA-09 cosign workflow is
+ * implemented at `queue_policy_update.rs` (handler lines 286-328) and
+ * re-validated at `apply_pending_policy.rs` (handler lines 70-84), but the
+ * SDK previously had NO client-side path to PRODUCE a valid cosign session +
+ * digest. This file ships that path.
+ *
+ * Usage (illustrative — non-Kit caller):
+ *
+ *   import { buildCosignBundle } from "@usesigil/kit";
+ *
+ *   const bundle = buildCosignBundle({
+ *     cosignSessionPubkey: cosigner.address,
+ *     ownerSigner: owner,            // unused at digest time — see note below
+ *     dailySpendingCapUsd: 800_000_000n,  // raise from 500_000_000 → elevated
+ *   });
+ *
+ *   await queuePolicyUpdate({
+ *     ...args,
+ *     cosignSession: bundle.cosignSession,
+ *     newPolicyPreviewDigest: previewDigest, // separate TA-19 digest
+ *     // cosign digest IS NOT a queue arg — the on-chain handler RECOMPUTES
+ *     // it from the queue args + cosign_session pubkey and stores the
+ *     // result on PendingPolicyUpdate. Apply re-validates by recomputing.
+ *   });
+ *
+ * Why the helper exists if the cosign digest isn't a queue arg:
+ *   - The on-chain handler classifies an "elevated mutation" via comparing
+ *     `Option::Some(new) > live` (raises) / `new.contains(p) where !live.contains(p)`
+ *     (expansions). If you're queueing what you BELIEVE is elevated, this
+ *     helper produces the digest you EXPECT the on-chain handler to store,
+ *     so your client can:
+ *       (a) sanity-check elevation up-front before submitting a tx (and ask
+ *           the user for the cosigner signature explicitly), and
+ *       (b) compare against `PendingPolicyUpdate.cosignDigest` after queue,
+ *           catching any silent SDK encoder drift.
+ *   - The cosign session pubkey IS a queue arg (`cosign_session: Pubkey`).
+ *     For elevated mutations the handler rejects `Pubkey::default()` with
+ *     `ErrCosignRequired`, and ALSO requires the corresponding signer in
+ *     `remaining_accounts` with `is_signer == true`.
+ *
+ * G3 + G6 elevation triggers — what counts as "elevated" (all bound by this
+ * digest as of Round 2 B4 F-1, 2026-05-19):
+ *   - raises_daily_cap = daily_spending_cap_usd: Some(new) > live
+ *   - raises_max_tx = max_transaction_amount_usd: Some(new) > live
+ *   - expands_destinations = allowed_destinations: any new pubkey not in live
+ *     OR new.len() > live.len()
+ *   - expands_protocols = protocols: any new pubkey not in live OR
+ *     new.len() > live.len()
+ *   - lowers_floor = stable_balance_floor: Some(new) < live           (G3)
+ *   - raises_per_recipient_cap = per_recipient_daily_cap_usd:
+ *     Some(new) > live                                                (G3)
+ *   - disables_protocol_caps = has_protocol_caps: Some(false) while live=true (G3)
+ *   - shrinks_or_raises_caps = protocol_caps: any entry mutated       (G3)
+ *   - disables_cosign = cosign_required: Some(false) while live=true  (G6)
+ *
+ * Round 2 B4 F-1 fix (2026-05-19): the cosign digest binding now extends to
+ * ALL G3 + G6 triggers. Previously the digest only bound positions 1-5
+ * (cosign_session, daily/max-tx caps, destinations, protocols) — the G3/G6
+ * elevation triggers ELEVATED the queue but were NOT bound by this digest
+ * (they were bound only by TA-19 policy_preview_digest). That left a gap:
+ * a tampered SDK or discriminator-collision attack on the pending PDA
+ * could mutate those triggers between queue and apply without producing a
+ * cosign-digest mismatch. With the extension, every elevation trigger is
+ * now bound by BOTH the cosign digest (intent) and TA-19 (byte safety).
+ *
+ * Phase 4 PEN-CROSS-3 pattern reference:
+ *   PEN-CROSS-3 introduced sibling-handler digest binding (constraints/post-
+ *   assertion flips). The same defense-in-depth pattern applies here: the
+ *   on-chain TA-09 handler recomputes the cosign digest at BOTH queue (queue
+ *   binding) AND apply (re-validation). A rogue program with the same
+ *   discriminator on the pending PDA cannot rewrite args between queue and
+ *   apply without producing a digest mismatch.
+ *
+ * @see `programs/sigil/src/utils/cosign_digest.rs` — canonical Rust impl
+ * @see `programs/sigil/src/instructions/queue_policy_update.rs:286-328` —
+ *      queue-time gate + digest binding
+ * @see `programs/sigil/src/instructions/apply_pending_policy.rs:70-84` —
+ *      apply-time re-validation
+ * @see `sdk/kit/src/policy/compute-cosign-digest.ts` — SDK-side digest helper
+ */
+import type { Address, TransactionSigner } from "./kit-adapter.js";
+/**
+ * CANONICAL `cosign_session` ARG CONTRACT — Round 2 §RP-2 B4 F-3 (2026-05-19).
+ *
+ * Every Sigil instruction that supports the cosign opt-in path accepts a
+ * `cosign_session: Pubkey` argument. This contract documents what a non-Codama
+ * SDK consumer MUST pass to avoid the silent rejection path the on-chain
+ * handler took as of Round 2 B4 F-3 Option A:
+ *
+ *   • NON-ELEVATED queue (the default for every mutation that does NOT
+ *     raise daily_cap / max_tx, expand destinations / protocols, lower
+ *     stable_balance_floor, raise per_recipient_daily_cap_usd, disable
+ *     protocol_caps, mutate protocol_caps entries, or disable cosign):
+ *       Pass `Pubkey::default()` — the SystemProgram pubkey
+ *       `11111111111111111111111111111111` (32 zero bytes).
+ *       Do NOT include any cosigner in `remaining_accounts`.
+ *
+ *   • ELEVATED queue (raising daily_cap, expanding destinations, etc. — see
+ *     the full trigger list in the `CosignArgs` JSDoc below):
+ *       Pass a REAL session pubkey (non-default AND distinct from owner),
+ *       AND include that session pubkey in `remaining_accounts` with
+ *       `is_signer == true`.
+ *       Use {@link buildCosignBundle} to mirror the on-chain digest the
+ *       handler will recompute + store on `PendingPolicyUpdate`.
+ *
+ *   • REJECT path: passing a non-default `cosign_session` on a non-elevated
+ *     queue surfaces `InvalidPermissions` (6088). This is INTENTIONAL —
+ *     the on-chain handler refuses to silently downgrade a caller's
+ *     declared intent. See Round 2 §RP-2 B4 F-3 Option A rationale in
+ *     `queue_policy_update.rs` (and the corresponding test fixtures in
+ *     `tests/policy-digest-invariant.ts`).
+ *
+ * This contract applies to: `queue_policy_update`, `queue_agent_permissions`,
+ * and any future queue handler that takes a `cosign_session` arg. The Codama
+ * generated client surfaces this as a typed `Address` field; hand-rolled
+ * builders MUST follow the contract above to avoid `InvalidPermissions`.
+ */
+/**
+ * Arguments for {@link buildCosignBundle}. Mirrors the elevated-mutation
+ * subset of `queue_policy_update` args.
+ */
+export interface CosignArgs {
+    /**
+     * The cosigning session pubkey to bind into the digest. MUST be:
+     *   1. Distinct from the owner's pubkey (handler rejects same-key cosign
+     *      under `ErrCosignRequired` — same-key collapses the two-signer gate),
+     *   2. Non-default (i.e. NOT `11111111111111111111111111111111`), and
+     *   3. Present in the queue transaction's `remaining_accounts` with
+     *      `is_signer == true`.
+     *
+     * The caller is responsible for (3) — this helper produces the digest, the
+     * tx builder includes the signer.
+     *
+     * See the "CANONICAL `cosign_session` ARG CONTRACT" block above for the
+     * non-elevated vs elevated vs reject paths. Round 2 §RP-2 B4 F-3 (2026-05-19).
+     */
+    cosignSessionPubkey: Address;
+    /**
+     * The owner who will sign the queue tx. Currently UNUSED by digest
+     * derivation (the cosign digest binds the cosign_session pubkey, not the
+     * owner — owner authority is established by Solana's `is_signer` check on
+     * the owner account). Accepted as a constructor arg for symmetry with the
+     * full queue signing surface and to surface the "two distinct signers"
+     * requirement at the type level.
+     */
+    ownerSigner: TransactionSigner;
+    /**
+     * Pending `daily_spending_cap_usd` (6-decimal USDC face value).
+     * Raising this beyond the live policy value ELEVATES the queue.
+     * Bound by THIS cosign digest.
+     */
+    dailySpendingCapUsd?: bigint | null;
+    /**
+     * Pending `max_transaction_amount_usd` (6-decimal USDC face value).
+     * Raising this beyond the live policy value ELEVATES the queue.
+     * Bound by THIS cosign digest.
+     */
+    maxTransactionAmountUsd?: bigint | null;
+    /**
+     * Pending `allowed_destinations`. Adding any pubkey not in live (or
+     * growing the list) ELEVATES the queue. Bound by THIS cosign digest.
+     *
+     * NOTE: order matters — the on-chain handler treats `[A, B]` and `[B, A]`
+     * as DIFFERENT digests (ordered encoding). Always pass destinations in the
+     * same order the owner signed.
+     */
+    allowedDestinations?: readonly Address[] | null;
+    /**
+     * Pending `protocols`. Adding any pubkey not in live (or growing the list)
+     * ELEVATES the queue. Bound by THIS cosign digest. Same ordering caveat as
+     * `allowedDestinations`.
+     */
+    protocols?: readonly Address[] | null;
+    /**
+     * Pending `stable_balance_floor` (6-decimal USDC face value). LOWERING
+     * this below the live policy value ELEVATES the queue (G3 audit fix
+     * 2026-05-18). Round 2 B4 F-1: now BOUND by this cosign digest at
+     * canonical position 6.
+     */
+    stableBalanceFloor?: bigint | null;
+    /**
+     * Pending `per_recipient_daily_cap_usd` (6-decimal USDC face value).
+     * RAISING this above the live policy value ELEVATES the queue (G3 audit
+     * fix 2026-05-18). Round 2 B4 F-1: now BOUND by this cosign digest at
+     * canonical position 7.
+     */
+    perRecipientDailyCapUsd?: bigint | null;
+    /**
+     * Pending `has_protocol_caps` flag. Setting this to `false` while the
+     * live policy is `true` ELEVATES the queue (disabling protocol caps
+     * entirely). Round 2 B4 F-1: BOUND by this cosign digest at canonical
+     * position 8.
+     */
+    hasProtocolCaps?: boolean | null;
+    /**
+     * Pending `protocol_caps` Vec<u64> arg (6-decimal USDC face values,
+     * parallel to `protocols`). Mutating individual caps (shrink-to-zero or
+     * raise) ELEVATES the queue. Round 2 B4 F-1: BOUND by this cosign digest
+     * at canonical position 9. Same ordering caveat as `protocols` (parallel
+     * arrays — order is load-bearing).
+     */
+    protocolCaps?: readonly bigint[] | null;
+    /**
+     * Pending `cosign_required` flag. Setting this to `false` while the live
+     * policy is `true` ELEVATES the queue (G6 one-way ratchet — disabling
+     * cosign requires cosign). Round 2 B4 F-1: BOUND by this cosign digest
+     * at canonical position 10.
+     */
+    cosignRequired?: boolean | null;
+}
+/**
+ * Bundle produced by {@link buildCosignBundle}. Pass `cosignSession` as the
+ * `cosign_session` queue arg; the on-chain handler will recompute and store
+ * `cosignDigest` on `PendingPolicyUpdate.cosignDigest` (the SDK consumer can
+ * fetch + compare for a defense-in-depth sanity check after the queue tx
+ * lands).
+ */
+export interface CosignBundle {
+    /**
+     * The cosigning session pubkey, same as {@link CosignArgs.cosignSessionPubkey}.
+     * Pass this directly as the `cosign_session` arg to `queue_policy_update`.
+     */
+    cosignSession: Address;
+    /**
+     * The 32-byte SHA-256 digest the on-chain handler will recompute + store.
+     * Equal to the on-chain `compute_cosign_digest` over the same inputs.
+     *
+     * The caller does NOT pass this directly to `queue_policy_update` — the
+     * on-chain handler recomputes it from the queue args + cosign_session.
+     * Use this to:
+     *   (a) sanity-check what the on-chain handler WILL store, and
+     *   (b) compare to `PendingPolicyUpdate.cosignDigest` after queue to catch
+     *       SDK encoder drift.
+     */
+    cosignDigest: Uint8Array;
+}
+/**
+ * Produce a cosign session + digest bundle for an elevated `queue_policy_update`.
+ *
+ * Pass the same elevated-mutation fields you intend to send to
+ * `queue_policy_update`. The helper:
+ *   1. Validates that the cosign session is non-default and distinct from
+ *      the owner.
+ *   2. Computes the canonical cosign digest mirroring the on-chain
+ *      `compute_cosign_digest` byte-for-byte.
+ *   3. Returns the bundle.
+ *
+ * IMPORTANT: this helper does NOT enforce that the mutation IS elevated. The
+ * on-chain handler does that detection. If you call this for a non-elevated
+ * mutation, the bundle is technically valid but the handler will set
+ * `pending.cosign_digest = [0u8; 32]` and `pending.cosign_session =
+ * Pubkey::default()` instead of binding to the cosigner. Use the bundle when
+ * you have already determined elevation is required, e.g. via an SDK-side
+ * elevation check before constructing the tx.
+ *
+ * @throws if `cosignSessionPubkey` is `11111111111111111111111111111111` (default)
+ * @throws if `cosignSessionPubkey` equals `ownerSigner.address`
+ * @throws if any address fails base58 decoding to 32 bytes
+ */
+export declare function buildCosignBundle(args: CosignArgs): CosignBundle;
+//# sourceMappingURL=cosign-helper.d.ts.map

package/dist/cosign-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosign-helper.d.ts","sourceRoot":"","sources":["../src/cosign-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;OAaG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAE7B;;;;;;;OAOG;IACH,WAAW,EAAE,iBAAiB,CAAC;IAY/B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAExC;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAEhD;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAStC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAExC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAExC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;OAUG;IACH,YAAY,EAAE,UAAU,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY,CA+ChE"}

package/dist/cosign-helper.js

@@ -0,0 +1,147 @@
+/**
+ * G4 (audit close) — TA-09 client-side cosign helper.
+ *
+ * Closes the G4 gate of Phase 6: the on-chain TA-09 cosign workflow is
+ * implemented at `queue_policy_update.rs` (handler lines 286-328) and
+ * re-validated at `apply_pending_policy.rs` (handler lines 70-84), but the
+ * SDK previously had NO client-side path to PRODUCE a valid cosign session +
+ * digest. This file ships that path.
+ *
+ * Usage (illustrative — non-Kit caller):
+ *
+ *   import { buildCosignBundle } from "@usesigil/kit";
+ *
+ *   const bundle = buildCosignBundle({
+ *     cosignSessionPubkey: cosigner.address,
+ *     ownerSigner: owner,            // unused at digest time — see note below
+ *     dailySpendingCapUsd: 800_000_000n,  // raise from 500_000_000 → elevated
+ *   });
+ *
+ *   await queuePolicyUpdate({
+ *     ...args,
+ *     cosignSession: bundle.cosignSession,
+ *     newPolicyPreviewDigest: previewDigest, // separate TA-19 digest
+ *     // cosign digest IS NOT a queue arg — the on-chain handler RECOMPUTES
+ *     // it from the queue args + cosign_session pubkey and stores the
+ *     // result on PendingPolicyUpdate. Apply re-validates by recomputing.
+ *   });
+ *
+ * Why the helper exists if the cosign digest isn't a queue arg:
+ *   - The on-chain handler classifies an "elevated mutation" via comparing
+ *     `Option::Some(new) > live` (raises) / `new.contains(p) where !live.contains(p)`
+ *     (expansions). If you're queueing what you BELIEVE is elevated, this
+ *     helper produces the digest you EXPECT the on-chain handler to store,
+ *     so your client can:
+ *       (a) sanity-check elevation up-front before submitting a tx (and ask
+ *           the user for the cosigner signature explicitly), and
+ *       (b) compare against `PendingPolicyUpdate.cosignDigest` after queue,
+ *           catching any silent SDK encoder drift.
+ *   - The cosign session pubkey IS a queue arg (`cosign_session: Pubkey`).
+ *     For elevated mutations the handler rejects `Pubkey::default()` with
+ *     `ErrCosignRequired`, and ALSO requires the corresponding signer in
+ *     `remaining_accounts` with `is_signer == true`.
+ *
+ * G3 + G6 elevation triggers — what counts as "elevated" (all bound by this
+ * digest as of Round 2 B4 F-1, 2026-05-19):
+ *   - raises_daily_cap = daily_spending_cap_usd: Some(new) > live
+ *   - raises_max_tx = max_transaction_amount_usd: Some(new) > live
+ *   - expands_destinations = allowed_destinations: any new pubkey not in live
+ *     OR new.len() > live.len()
+ *   - expands_protocols = protocols: any new pubkey not in live OR
+ *     new.len() > live.len()
+ *   - lowers_floor = stable_balance_floor: Some(new) < live           (G3)
+ *   - raises_per_recipient_cap = per_recipient_daily_cap_usd:
+ *     Some(new) > live                                                (G3)
+ *   - disables_protocol_caps = has_protocol_caps: Some(false) while live=true (G3)
+ *   - shrinks_or_raises_caps = protocol_caps: any entry mutated       (G3)
+ *   - disables_cosign = cosign_required: Some(false) while live=true  (G6)
+ *
+ * Round 2 B4 F-1 fix (2026-05-19): the cosign digest binding now extends to
+ * ALL G3 + G6 triggers. Previously the digest only bound positions 1-5
+ * (cosign_session, daily/max-tx caps, destinations, protocols) — the G3/G6
+ * elevation triggers ELEVATED the queue but were NOT bound by this digest
+ * (they were bound only by TA-19 policy_preview_digest). That left a gap:
+ * a tampered SDK or discriminator-collision attack on the pending PDA
+ * could mutate those triggers between queue and apply without producing a
+ * cosign-digest mismatch. With the extension, every elevation trigger is
+ * now bound by BOTH the cosign digest (intent) and TA-19 (byte safety).
+ *
+ * Phase 4 PEN-CROSS-3 pattern reference:
+ *   PEN-CROSS-3 introduced sibling-handler digest binding (constraints/post-
+ *   assertion flips). The same defense-in-depth pattern applies here: the
+ *   on-chain TA-09 handler recomputes the cosign digest at BOTH queue (queue
+ *   binding) AND apply (re-validation). A rogue program with the same
+ *   discriminator on the pending PDA cannot rewrite args between queue and
+ *   apply without producing a digest mismatch.
+ *
+ * @see `programs/sigil/src/utils/cosign_digest.rs` — canonical Rust impl
+ * @see `programs/sigil/src/instructions/queue_policy_update.rs:286-328` —
+ *      queue-time gate + digest binding
+ * @see `programs/sigil/src/instructions/apply_pending_policy.rs:70-84` —
+ *      apply-time re-validation
+ * @see `sdk/kit/src/policy/compute-cosign-digest.ts` — SDK-side digest helper
+ */
+import { computeCosignDigest } from "./policy/compute-cosign-digest.js";
+/**
+ * Produce a cosign session + digest bundle for an elevated `queue_policy_update`.
+ *
+ * Pass the same elevated-mutation fields you intend to send to
+ * `queue_policy_update`. The helper:
+ *   1. Validates that the cosign session is non-default and distinct from
+ *      the owner.
+ *   2. Computes the canonical cosign digest mirroring the on-chain
+ *      `compute_cosign_digest` byte-for-byte.
+ *   3. Returns the bundle.
+ *
+ * IMPORTANT: this helper does NOT enforce that the mutation IS elevated. The
+ * on-chain handler does that detection. If you call this for a non-elevated
+ * mutation, the bundle is technically valid but the handler will set
+ * `pending.cosign_digest = [0u8; 32]` and `pending.cosign_session =
+ * Pubkey::default()` instead of binding to the cosigner. Use the bundle when
+ * you have already determined elevation is required, e.g. via an SDK-side
+ * elevation check before constructing the tx.
+ *
+ * @throws if `cosignSessionPubkey` is `11111111111111111111111111111111` (default)
+ * @throws if `cosignSessionPubkey` equals `ownerSigner.address`
+ * @throws if any address fails base58 decoding to 32 bytes
+ */
+export function buildCosignBundle(args) {
+    // Pre-flight: the on-chain handler rejects default/owner-same cosign with
+    // ErrCosignRequired (6089). Surface the same failures at the SDK level
+    // with a clearer error message — better DX than digging through Anchor
+    // error codes after a failed simulation.
+    const defaultPubkey = "11111111111111111111111111111111";
+    if (args.cosignSessionPubkey === defaultPubkey) {
+        throw new Error("buildCosignBundle: cosignSessionPubkey is the default pubkey " +
+            "(11111111111111111111111111111111). The on-chain handler will reject " +
+            "this with ErrCosignRequired (6089). Pass a real session pubkey.");
+    }
+    if (args.cosignSessionPubkey ===
+        args.ownerSigner.address) {
+        throw new Error("buildCosignBundle: cosignSessionPubkey equals ownerSigner.address. " +
+            "The on-chain handler rejects same-key cosign with ErrCosignRequired " +
+            "(6089) because it collapses the two-signer gate. Use a distinct " +
+            "cosigning session pubkey.");
+    }
+    const digest = computeCosignDigest({
+        cosignSession: args.cosignSessionPubkey,
+        dailySpendingCapUsd: args.dailySpendingCapUsd ?? null,
+        maxTransactionAmountUsd: args.maxTransactionAmountUsd ?? null,
+        allowedDestinations: args.allowedDestinations ?? null,
+        protocols: args.protocols ?? null,
+        // Round 2 B4 F-1 (2026-05-19): the 5 new G3 + G6 elevation triggers are
+        // now BOUND by this cosign digest. Flow them through to mirror the
+        // on-chain handler's CosignDigestFields construction in
+        // `queue_policy_update.rs` (handler passes all 10 fields).
+        stableBalanceFloor: args.stableBalanceFloor ?? null,
+        perRecipientDailyCapUsd: args.perRecipientDailyCapUsd ?? null,
+        hasProtocolCaps: args.hasProtocolCaps ?? null,
+        protocolCaps: args.protocolCaps ?? null,
+        cosignRequired: args.cosignRequired ?? null,
+    });
+    return {
+        cosignSession: args.cosignSessionPubkey,
+        cosignDigest: digest,
+    };
+}
+//# sourceMappingURL=cosign-helper.js.map

package/dist/cosign-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosign-helper.js","sourceRoot":"","sources":["../src/cosign-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AA2LxE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAgB;IAChD,0EAA0E;IAC1E,uEAAuE;IACvE,uEAAuE;IACvE,yCAAyC;IACzC,MAAM,aAAa,GACjB,kCAAwD,CAAC;IAC3D,IAAI,IAAI,CAAC,mBAAmB,KAAK,aAAa,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,+DAA+D;YAC7D,uEAAuE;YACvE,iEAAiE,CACpE,CAAC;IACJ,CAAC;IACD,IACG,IAAI,CAAC,mBAAyC;QAC9C,IAAI,CAAC,WAAW,CAAC,OAA6B,EAC/C,CAAC;QACD,MAAM,IAAI,KAAK,CACb,qEAAqE;YACnE,sEAAsE;YACtE,kEAAkE;YAClE,2BAA2B,CAC9B,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,mBAAmB,CAAC;QACjC,aAAa,EAAE,IAAI,CAAC,mBAAmB;QACvC,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,IAAI;QACrD,uBAAuB,EAAE,IAAI,CAAC,uBAAuB,IAAI,IAAI;QAC7D,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,IAAI;QACrD,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;QACjC,wEAAwE;QACxE,mEAAmE;QACnE,wDAAwD;QACxD,2DAA2D;QAC3D,kBAAkB,EAAE,IAAI,CAAC,kBAAkB,IAAI,IAAI;QACnD,uBAAuB,EAAE,IAAI,CAAC,uBAAuB,IAAI,IAAI;QAC7D,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,IAAI;QAC7C,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI;QACvC,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,IAAI;KAC5C,CAAC,CAAC;IAEH,OAAO;QACL,aAAa,EAAE,IAAI,CAAC,mBAAmB;QACvC,YAAY,EAAE,MAAM;KACrB,CAAC;AACJ,CAAC"}