@chipi-stack/backend 14.16.0 → 14.17.0

package/dist/index.js

@@ -173,9 +173,9 @@ function assertValidV2Snip12Envelope(envelope) {
   }
   return envelope[1];
 }
-function _tryDecodeShortString(felt) {
+function _tryDecodeShortString(felt2) {
   try {
-    return starknet.shortString.decodeShortString("0x" + felt.toString(16));
+    return starknet.shortString.decodeShortString("0x" + felt2.toString(16));
   } catch {
     return null;
   }
@@ -199,14 +199,20 @@ function buildThresholdEnvelope(args) {
       );
     }
     seenOwners.add(key);
-    out.push(BigInt(env.length));
-    for (const felt of env) {
-      if (felt < 0n) {
+    if (env.length < 3) {
+      throw new Error(
+        `THRESH: inner envelope ${i} must have at least [tag, owner_id, kind_tag]; got ${env.length} felts`
+      );
+    }
+    const frame = env.slice(1);
+    out.push(BigInt(frame.length));
+    for (const felt2 of frame) {
+      if (felt2 < 0n) {
         throw new RangeError(
           `THRESH: envelope ${i} contains negative felt (cannot serialize as felt252)`
         );
       }
-      out.push(felt);
+      out.push(felt2);
     }
   }
   return out;
@@ -239,15 +245,26 @@ function parseThresholdEnvelope(envelope) {
         `THRESH: inner ${i} would overflow envelope (env_len ${envLen}, cursor ${cursor}, total ${envelope.length})`
       );
     }
-    const inner = envelope.slice(cursor, cursor + envLen);
-    for (const felt of inner) {
-      if (felt < 0n) {
+    const frame = envelope.slice(cursor, cursor + envLen);
+    for (const felt2 of frame) {
+      if (felt2 < 0n) {
         throw new RangeError(
           `THRESH: inner ${i} contains negative felt (cannot serialize as felt252)`
         );
       }
     }
-    const ownerId = assertValidV2Snip12Envelope(inner);
+    const ownerId = frame[0];
+    if (ownerId >= 0x100000000n) {
+      if (ownerId === V2_THRESHOLD_TAG) {
+        throw new Error(
+          `THRESH: inner ${i}: nested threshold envelopes are not allowed; inner frames are [owner_id, kind_tag, ...payload]`
+        );
+      }
+      throw new Error(
+        `THRESH: inner ${i} owner_id 0x${ownerId.toString(16)} is not a u32; inner frames are [owner_id, kind_tag, ...payload] with no V2_SNIP12 tag`
+      );
+    }
+    const inner = [V2_SNIP12_TAG, ...frame];
     const key = ownerId.toString();
     if (seenOwners.has(key)) {
       throw new Error(
@@ -550,6 +567,7 @@ var init_stark = __esm({
 var execute_paymaster_raw_exports = {};
 __export(execute_paymaster_raw_exports, {
   executeShhhSponsoredRaw: () => executeShhhSponsoredRaw,
+  newOeNonce: () => newOeNonce,
   resolveShhhChainId: () => resolveShhhChainId,
   serializeExecuteFromOutsideV2Calldata: () => serializeExecuteFromOutsideV2Calldata
 });
@@ -887,13 +905,26 @@ function unwrapPrepareResponse(response) {
     apiMessage ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing"
   );
 }
+function feltEquals(value, expected) {
+  try {
+    return BigInt(value) === expected;
+  } catch {
+    return false;
+  }
+}
 function normalizeSignature(signature) {
   if (Array.isArray(signature)) {
     if (signature.length < 2) {
       throw new Error(`Array signature must have at least 2 elements, got ${signature.length}`);
     }
-    const r = signature[0];
-    const s = signature[1];
+    const isArgentSingle = signature.length === 5 && feltEquals(signature[0], 1n) && feltEquals(signature[1], 0n);
+    if (signature.length !== 2 && !isArgentSingle) {
+      throw new Error(
+        `Unsupported ${signature.length}-felt signature: expected [r, s] or Argent [1, 0, pubkey, r, s].`
+      );
+    }
+    const r = isArgentSingle ? signature[3] : signature[0];
+    const s = isArgentSingle ? signature[4] : signature[1];
     if (r == null || s == null) {
       throw new Error(`Signature elements must not be null/undefined. Got r=${r}, s=${s}`);
     }
@@ -1608,7 +1639,10 @@ var ChipiWallets = class {
           publicKey,
           walletType,
           starkKeyPubAX,
-          ...customClassHash && { classHash: customClassHash },
+          // The class the address above was computed with. SHHH always
+          // names it: chipi-back's default for clients that name none is
+          // the class SDKs up to 14.16 used (V8.4), not ours.
+          ...(customClassHash || isShhh) && { classHash: accountClassHash },
           // SHHH: tell chipi-back which signer kind + pubkey felts
           // produced this deployment so it can validate against the
           // expected SHHH constructor shape and populate the new
@@ -1620,6 +1654,11 @@ var ChipiWallets = class {
         }
       });
       const { typedData: typedData2, accountClassHash: accountClassHashResponse } = typedDataResponse;
+      if (isShhh && (!accountClassHashResponse || BigInt(accountClassHashResponse) !== BigInt(accountClassHash))) {
+        throw new Error(
+          `prepare-creation returned class ${accountClassHashResponse ?? "(none)"}, but the wallet address was computed with ${accountClassHash}. Not deploying.`
+        );
+      }
       let userSignaturePayload;
       if (isShhh) {
         userSignaturePayload = {
@@ -2138,14 +2177,14 @@ function normalizeEntrypoints(entrypoints) {
   return entrypoints.map((entry) => {
     const value = String(entry).trim();
     if (HEX_FELT.test(value) || DECIMAL_FELT.test(value)) {
-      const felt = BigInt(value);
-      if (felt >= FIELD_PRIME) {
+      const felt2 = BigInt(value);
+      if (felt2 >= FIELD_PRIME) {
         throw new shared.ChipiSessionError(
           `Session entrypoint ${value} is not a valid felt (>= field prime).`,
           shared.SESSION_ERRORS.SESSION_ENTRYPOINT_NOT_ALLOWED
         );
       }
-      return starknet.num.toHex(felt);
+      return starknet.num.toHex(felt2);
     }
     if (CAIRO_IDENTIFIER.test(value)) {
       return starknet.hash.getSelectorFromName(value);
@@ -3979,6 +4018,504 @@ var signTypedDataArray = async ({
   return [r, s];
 };
 
+// src/shhh/execute-external-owner.ts
+init_oe();
+init_execute_paymaster_raw();
+init_stark();
+
+// src/shhh/signers/stark-snip12.ts
+init_compute_wallet_address();
+init_oe();
+var ROLE_OWNER = BigInt(starknet.shortString.encodeShortString("OWNER"));
+var ROLE_GUARDIAN = BigInt(starknet.shortString.encodeShortString("GUARDIAN"));
+var OP_ADD_OWNER = BigInt(starknet.shortString.encodeShortString("ADD_OWNER"));
+var OP_REMOVE_OWNER = BigInt(starknet.shortString.encodeShortString("REMOVE_OWNER"));
+var OP_ROTATE_OWNER = BigInt(starknet.shortString.encodeShortString("ROTATE_OWNER"));
+var OP_SET_THRESHOLD = BigInt(starknet.shortString.encodeShortString("SET_THRESHOLD"));
+var OP_ADD_VERIFIER_CLASS = BigInt(starknet.shortString.encodeShortString("ADD_VERIFIER"));
+var TIMELOCK_SECONDS = {
+  ADD_OWNER: 172800,
+  // 48h
+  REMOVE_OWNER: 86400,
+  // 24h
+  ROTATE_OWNER: 86400,
+  // 24h
+  SET_THRESHOLD: 172800,
+  // 48h
+  ADD_VERIFIER: 172800,
+  // 48h
+  REMOVE_VERIFIER: 86400,
+  // 24h
+  ADD_GUARDIAN: 86400,
+  // 24h
+  REMOVE_GUARDIAN: 86400,
+  // 24h
+  RECOVERY: 604800
+  // 7d — `TIMELOCK_RECOVERY`, the headline UX gate
+};
+var DEFAULT_OP_EXPIRY_SECONDS = 1209600;
+function _felt2(x, field = "felt") {
+  const v = typeof x === "bigint" ? x : BigInt(x);
+  if (v < 0n) {
+    throw new RangeError(`${field} must be a non-negative felt; got ${v.toString()}`);
+  }
+  return v;
+}
+function _encodeOwnerInput(input) {
+  if (input.weight < 0) {
+    throw new RangeError(`NewOwnerInput.weight must be non-negative; got ${input.weight}`);
+  }
+  const kindFelt = _felt2(BigInt(starknet.shortString.encodeShortString(input.kind)), "kind");
+  const roleFelt = input.role === "OWNER" ? ROLE_OWNER : ROLE_GUARDIAN;
+  const pubkey = input.pubkeyBytes.map((p, i) => _felt2(p, `pubkeyBytes[${i}]`));
+  return [
+    kindFelt,
+    BigInt(pubkey.length),
+    ...pubkey,
+    roleFelt,
+    BigInt(input.weight),
+    _felt2(BigInt(starknet.shortString.encodeShortString(input.label)), "label")
+  ];
+}
+function _call(walletAddress, entrypoint, calldata) {
+  for (let i = 0; i < calldata.length; i++) {
+    if (calldata[i] < 0n) {
+      throw new RangeError(
+        `calldata[${i}] must be a non-negative felt; got ${calldata[i].toString()}`
+      );
+    }
+  }
+  return {
+    contractAddress: typeof walletAddress === "bigint" ? "0x" + walletAddress.toString(16) : walletAddress,
+    entrypoint,
+    calldata: calldata.map((v) => "0x" + v.toString(16))
+  };
+}
+function buildProposeAddOwnerCall(args) {
+  const calldata = [BigInt(args.proposer), ..._encodeOwnerInput(args.newOwner)];
+  return _call(args.walletAddress, "propose_add_owner", calldata);
+}
+function buildExecuteAddOwnerCall(args) {
+  const calldata = [_felt2(args.opId), ..._encodeOwnerInput(args.newOwner)];
+  return _call(args.walletAddress, "execute_add_owner", calldata);
+}
+function buildProposeRemoveOwnerCall(args) {
+  return _call(args.walletAddress, "propose_remove_owner", [
+    BigInt(args.proposer),
+    BigInt(args.ownerId)
+  ]);
+}
+function buildExecuteRemoveOwnerCall(args) {
+  return _call(args.walletAddress, "execute_remove_owner", [
+    _felt2(args.opId),
+    BigInt(args.ownerId)
+  ]);
+}
+function buildProposeRotateOwnerCall(args) {
+  return _call(args.walletAddress, "propose_rotate_owner", [
+    BigInt(args.proposer),
+    BigInt(args.ownerId),
+    BigInt(args.newPubkeyBytes.length),
+    ...args.newPubkeyBytes
+  ]);
+}
+function buildExecuteRotateOwnerCall(args) {
+  return _call(args.walletAddress, "execute_rotate_owner", [
+    _felt2(args.opId),
+    BigInt(args.ownerId),
+    BigInt(args.newPubkeyBytes.length),
+    ...args.newPubkeyBytes
+  ]);
+}
+function buildProposeSetThresholdCall(args) {
+  return _call(args.walletAddress, "propose_set_threshold", [
+    BigInt(args.proposer),
+    BigInt(args.newThreshold)
+  ]);
+}
+function buildExecuteSetThresholdCall(args) {
+  return _call(args.walletAddress, "execute_set_threshold", [
+    _felt2(args.opId),
+    BigInt(args.newThreshold)
+  ]);
+}
+function buildCancelPendingOpCall(args) {
+  return _call(args.walletAddress, "cancel_pending_op", [_felt2(args.opId)]);
+}
+function _verifierClassHash(kind, classHash) {
+  const h = classHash ?? shared.SHHH_VERIFIER_CLASS_HASHES[kind];
+  if (!h) throw new Error(`No verifier class hash known for kind "${kind}".`);
+  return _felt2(h, "classHash");
+}
+function buildProposeAddVerifierClassCall(args) {
+  const kindFelt = BigInt(starknet.shortString.encodeShortString(args.kind));
+  return _call(args.walletAddress, "propose_add_verifier_class", [
+    BigInt(args.proposer),
+    kindFelt,
+    _verifierClassHash(args.kind, args.classHash)
+  ]);
+}
+function buildExecuteAddVerifierClassCall(args) {
+  const kindFelt = BigInt(starknet.shortString.encodeShortString(args.kind));
+  return _call(args.walletAddress, "execute_add_verifier_class", [
+    _felt2(args.opId),
+    kindFelt,
+    _verifierClassHash(args.kind, args.classHash)
+  ]);
+}
+function buildInitiateRecoveryCall(args) {
+  const calldata = [BigInt(args.proposer), ..._encodeOwnerInput(args.newOwner)];
+  return _call(args.walletAddress, "initiate_recovery", calldata);
+}
+function buildCancelRecoveryCall(args) {
+  return _call(args.walletAddress, "cancel_recovery", [BigInt(args.ownerId)]);
+}
+function buildFinalizeRecoveryCall(args) {
+  return _call(args.walletAddress, "finalize_recovery", _encodeOwnerInput(args.newOwner));
+}
+var VIEW_SELECTORS = {
+  get_pending_op: starknet.hash.getSelectorFromName("get_pending_op"),
+  get_pending_recovery: starknet.hash.getSelectorFromName("get_pending_recovery"),
+  get_owner: starknet.hash.getSelectorFromName("get_owner")
+};
+function _toSecondsBigInt(value, field) {
+  if (typeof value === "bigint") return value;
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${field} must be a finite timestamp; got ${value}`);
+  }
+  return BigInt(Math.floor(value));
+}
+function isReadyToExecute(validAfterSecs, nowSecs) {
+  return _toSecondsBigInt(nowSecs, "nowSecs") >= _toSecondsBigInt(validAfterSecs, "validAfterSecs");
+}
+function secondsUntilExecutable(validAfterSecs, nowSecs) {
+  const remaining = _toSecondsBigInt(validAfterSecs, "validAfterSecs") - _toSecondsBigInt(nowSecs, "nowSecs");
+  return remaining <= 0n ? 0 : Number(remaining);
+}
+function _decodeShort(value) {
+  const v = BigInt(value);
+  return v === 0n ? "" : starknet.shortString.decodeShortString(starknet.num.toHex(v));
+}
+function _view(provider, walletAddress, entrypoint, calldata = []) {
+  return provider.callContract({
+    contractAddress: typeof walletAddress === "bigint" ? starknet.num.toHex(walletAddress) : walletAddress,
+    entrypoint,
+    calldata: calldata.map((v) => starknet.num.toHex(BigInt(v)))
+  });
+}
+async function readShhhOwners(provider, walletAddress) {
+  const [countFelt] = await _view(provider, walletAddress, "owner_count");
+  const count = Number(BigInt(countFelt));
+  const owners = [];
+  for (let id = 0; id < count; id++) {
+    owners.push(decodeShhhOwnerRecord(id, await _view(provider, walletAddress, "get_owner", [id])));
+  }
+  return owners;
+}
+function decodeShhhOwnerRecord(ownerId, felts) {
+  if (felts.length < 9) {
+    throw new Error(`get_owner returned ${felts.length} felts; expected 9 (OwnerRecord).`);
+  }
+  return {
+    ownerId,
+    kind: _decodeShort(felts[0]),
+    pubkeyHash: BigInt(felts[1]),
+    role: _decodeShort(felts[4]),
+    weight: Number(BigInt(felts[5])),
+    addedAt: Number(BigInt(felts[6])),
+    label: _decodeShort(felts[7]),
+    revoked: BigInt(felts[8]) !== 0n
+  };
+}
+async function readVerifierClass(provider, walletAddress, kind) {
+  const [h] = await _view(provider, walletAddress, "get_verifier_class", [
+    BigInt(starknet.shortString.encodeShortString(kind))
+  ]);
+  return BigInt(h ?? 0);
+}
+async function readPendingRecovery(provider, walletAddress) {
+  const r = await _view(provider, walletAddress, "get_pending_recovery");
+  return {
+    initiatedAt: Number(BigInt(r[0])),
+    validAfter: Number(BigInt(r[1])),
+    newOwnerHash: BigInt(r[2]),
+    isActive: BigInt(r[3]) !== 0n
+  };
+}
+var OP_PROPOSED_KEY = BigInt(starknet.hash.getSelectorFromName("OpProposed"));
+function parseOpProposedEvents(events, walletAddress) {
+  const wallet = walletAddress === void 0 ? void 0 : BigInt(walletAddress);
+  return events.filter(
+    (e) => e.keys.length >= 3 && BigInt(e.keys[0]) === OP_PROPOSED_KEY && (wallet === void 0 || e.from_address !== void 0 && BigInt(e.from_address) === wallet)
+  ).map((e) => ({
+    opId: BigInt(e.keys[1]),
+    opKind: _decodeShort(e.keys[2]),
+    proposer: Number(BigInt(e.data[0])),
+    payload: BigInt(e.data[1]),
+    validAfter: Number(BigInt(e.data[2])),
+    expiresAt: Number(BigInt(e.data[3]))
+  }));
+}
+
+// src/shhh/signers/stark-snip12.ts
+var STARK_SNIP12_KIND_TAG = "STARK_SNIP12";
+var STARK_KIND_TAG_FELT2 = BigInt(starknet.shortString.encodeShortString("STARK"));
+var V2_SNIP12_FELT = BigInt(starknet.shortString.encodeShortString("V2_SNIP12"));
+function domainChainId(chainId) {
+  if (typeof chainId === "string" && !chainId.startsWith("0x")) return chainId;
+  return starknet.shortString.decodeShortString(toFeltHex(chainId));
+}
+function felt(value) {
+  return BigInt(value);
+}
+function starkSnip12ApprovalTypedData(params) {
+  return {
+    types: {
+      StarknetDomain: [
+        { name: "name", type: "shortstring" },
+        { name: "version", type: "shortstring" },
+        { name: "chainId", type: "shortstring" },
+        { name: "revision", type: "shortstring" }
+      ],
+      Approval: [
+        { name: "Wallet", type: "ContractAddress" },
+        { name: "Hash", type: "felt" }
+      ]
+    },
+    primaryType: "Approval",
+    domain: {
+      name: "Shhh",
+      version: "1",
+      chainId: domainChainId(params.chainId ?? "SN_MAIN"),
+      revision: "1"
+    },
+    message: {
+      Wallet: normalizeStarknetAddress(params.walletAddress),
+      Hash: toFeltHex(params.messageHash)
+    }
+  };
+}
+function starkSnip12ApprovalHash(params) {
+  const td = starkSnip12ApprovalTypedData(params);
+  return BigInt(starknet.typedData.getMessageHash(td, normalizeStarknetAddress(params.signerAddress)));
+}
+function starkSnip12PubkeyFelts(starkPubkey, signerAddress) {
+  const pub = felt(starkPubkey);
+  const account = BigInt(normalizeStarknetAddress(signerAddress));
+  if (pub === 0n || account === 0n) {
+    throw new Error("starkSnip12PubkeyFelts: the key and the account address must be non-zero.");
+  }
+  return [pub, account];
+}
+function starkSnip12OwnerCommitment(starkPubkey, signerAddress) {
+  return ownerCommitment(
+    BigInt(starknet.shortString.encodeShortString(STARK_SNIP12_KIND_TAG)),
+    starkSnip12PubkeyFelts(starkPubkey, signerAddress)
+  );
+}
+function parseStarknetWalletSignature(signature) {
+  const sig = signature.map((v) => felt(v));
+  if (sig.length === 2) return { r: sig[0], s: sig[1] };
+  if (sig.length === 5 && sig[0] === 1n && sig[1] === 0n) {
+    return { pubkey: sig[2], r: sig[3], s: sig[4] };
+  }
+  if (sig.length === 5 && sig[0] === V2_SNIP12_FELT && sig[2] === STARK_KIND_TAG_FELT2) {
+    return { shhhOwnerId: sig[1], r: sig[3], s: sig[4] };
+  }
+  throw new Error(
+    `This wallet returned a ${sig.length}-felt signature that isn't a single STARK key (multisig, hardware or passkey signers aren't supported as a SHHH co-owner yet).`
+  );
+}
+function starkVerifyX(r, s, msgHash, pubkeyX) {
+  const x = pubkeyX.toString(16).padStart(64, "0");
+  const sig = new starknet.ec.starkCurve.Signature(r, s);
+  for (const prefix of ["02", "03"]) {
+    try {
+      if (starknet.ec.starkCurve.verify(sig, toFeltHex(msgHash), prefix + x)) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function verifyStarkSnip12Approval(params) {
+  const { r, s } = parseStarknetWalletSignature(params.signature);
+  const h = starkSnip12ApprovalHash(params);
+  return starkVerifyX(r, s, h, felt(params.starkPubkey));
+}
+function buildStarkSnip12Envelope(params) {
+  if (params.ownerIndex < 0n || params.ownerIndex >= 0x100000000n) {
+    throw new Error(
+      `buildStarkSnip12Envelope: ownerIndex ${params.ownerIndex} is out of u32 range. Pass the owner's index in the owner_set, not its commitment.`
+    );
+  }
+  const { r, s } = parseStarknetWalletSignature(params.signature);
+  return wrapV2Snip12Envelope({
+    ownerId: params.ownerIndex,
+    kindTag: STARK_SNIP12_KIND_TAG,
+    payload: [r, s]
+  });
+}
+function recoverStarkKeys(r, s, msgHash) {
+  const out = [];
+  for (const bit of [0, 1]) {
+    try {
+      const point = new starknet.ec.starkCurve.Signature(r, s).addRecoveryBit(bit).recoverPublicKey(msgHash.toString(16).padStart(64, "0"));
+      out.push(point.toAffine().x);
+    } catch {
+    }
+  }
+  return out;
+}
+async function tryCall(provider, contractAddress, entrypoint, calldata = []) {
+  try {
+    return await provider.callContract({ contractAddress, entrypoint, calldata });
+  } catch {
+    return null;
+  }
+}
+async function resolveStarkSnip12Signer(params) {
+  const signer = normalizeStarknetAddress(params.signerAddress);
+  const parsed = parseStarknetWalletSignature(params.signature);
+  const approvalHash = starkSnip12ApprovalHash(params);
+  const candidates = [];
+  if (parsed.pubkey !== void 0) candidates.push(parsed.pubkey);
+  if (parsed.shhhOwnerId !== void 0) {
+    const felts = await tryCall(params.provider, signer, "get_owner", [
+      toFeltHex(parsed.shhhOwnerId)
+    ]);
+    const record = felts && felts.length >= 9 ? decodeShhhOwnerRecord(0, felts) : null;
+    if (record && !record.revoked && record.kind === "STARK" && record.role === "OWNER") {
+      for (const key2 of recoverStarkKeys(parsed.r, parsed.s, approvalHash)) {
+        if (ownerCommitment(STARK_KIND_TAG_FELT2, [key2]) === record.pubkeyHash) candidates.push(key2);
+      }
+    }
+    if (candidates.length === 0) {
+      throw new Error(
+        `Couldn't confirm the Chipi wallet's signer: owner ${parsed.shhhOwnerId} of ${signer} is not an active STARK owner whose key made this signature.`
+      );
+    }
+  }
+  if (params.deploymentData && normalizeStarknetAddress(params.deploymentData.address) === signer) {
+    const cls = normalizeStarknetAddress(params.deploymentData.class_hash);
+    const cd = params.deploymentData.calldata;
+    if (cls === COUNTERFACTUAL_ACCOUNT_CLASSES.OPENZEPPELIN_V3 && cd.length === 1) {
+      candidates.push(felt(cd[0]));
+    }
+    if (cls === COUNTERFACTUAL_ACCOUNT_CLASSES.ARGENT_V0_4 && cd.length === 3) {
+      candidates.push(felt(cd[1]));
+    }
+  }
+  if (candidates.length === 0) {
+    const oz = await tryCall(params.provider, signer, "get_public_key");
+    if (oz && oz.length >= 1) candidates.push(felt(oz[0]));
+  }
+  if (candidates.length === 0) {
+    const signers = await tryCall(params.provider, signer, "get_signers");
+    if (signers && signers.length >= 1) {
+      const starkLen = Number(BigInt(signers[0]));
+      const rest = signers.slice(1 + starkLen);
+      const onlyStark = rest.every((v) => BigInt(v) === 0n);
+      if (starkLen === 1 && onlyStark) candidates.push(felt(signers[1]));
+    }
+  }
+  const key = candidates.find((k) => starkVerifyX(parsed.r, parsed.s, approvalHash, k));
+  if (key === void 0) {
+    throw new Error(
+      "Couldn't confirm which key signs for this wallet. It may use a hardware or passkey signer, a multisig, or an account type we don't read yet."
+    );
+  }
+  return { starkPubkey: key, pubkeyFelts: starkSnip12PubkeyFelts(key, signer) };
+}
+
+// src/shhh/execute-external-owner.ts
+function prepareExternalOwnerExecution(params) {
+  const walletAddress = normalizeStarknetAddress(params.walletAddress);
+  const outsideExecution = buildOutsideExecution({
+    nonce: params.nonce ?? newOeNonce(),
+    calls: params.calls,
+    caller: exports.ANY_CALLER_FELT
+  });
+  const chainId = resolveShhhChainId({ override: params.chainId });
+  const messageHash = computeOeHash(outsideExecution, walletAddress, chainId);
+  const typedData2 = starkSnip12ApprovalTypedData({ walletAddress, messageHash, chainId });
+  return { walletAddress, outsideExecution, messageHash, typedData: typedData2, chainId };
+}
+async function submitExternalOwnerExecution(params) {
+  const { prepared } = params;
+  if (params.signer && !verifyStarkSnip12Approval({
+    walletAddress: prepared.walletAddress,
+    messageHash: prepared.messageHash,
+    signerAddress: params.signer.address,
+    starkPubkey: params.signer.starkPubkey,
+    signature: params.signature,
+    chainId: prepared.chainId
+  })) {
+    throw new Error(
+      "The signature doesn't match this wallet's registered key. Sign with the same wallet and account you added."
+    );
+  }
+  const envelope = buildStarkSnip12Envelope({
+    signature: params.signature,
+    ownerIndex: BigInt(params.ownerIndex)
+  });
+  const calldata = serializeExecuteFromOutsideV2Calldata({
+    outsideExecution: prepared.outsideExecution,
+    signature: envelope
+  });
+  const response = await params.client.post({
+    endpoint: "/transactions/execute-sponsored-raw",
+    bearerToken: params.bearerToken,
+    body: {
+      accountAddress: prepared.walletAddress,
+      calldata,
+      ...params.externalUserId ? { externalUserId: params.externalUserId } : {}
+    }
+  });
+  if (!response?.transactionHash) {
+    throw new Error(
+      "execute-sponsored-raw response missing transactionHash. Check the chipi-back logs for upstream paymaster errors."
+    );
+  }
+  return response.transactionHash;
+}
+async function executeShhhWithExternalSigner(params) {
+  const prepared = prepareExternalOwnerExecution(params);
+  const signature = await params.signTypedData(prepared.typedData);
+  return submitExternalOwnerExecution({ ...params, prepared, signature });
+}
+async function executeShhhWithStarkKey(params) {
+  const walletAddress = normalizeStarknetAddress(params.walletAddress);
+  const outsideExecution = buildOutsideExecution({
+    nonce: params.nonce ?? newOeNonce(),
+    calls: params.calls,
+    caller: exports.ANY_CALLER_FELT
+  });
+  const chainId = resolveShhhChainId({ override: params.chainId });
+  const messageHash = computeOeHash(outsideExecution, walletAddress, chainId);
+  const signature = buildStarkEnvelope({
+    privateKey: params.privateKey,
+    messageHash,
+    ownerIndex: BigInt(params.ownerIndex)
+  });
+  const calldata = serializeExecuteFromOutsideV2Calldata({ outsideExecution, signature });
+  const response = await params.client.post({
+    endpoint: "/transactions/execute-sponsored-raw",
+    bearerToken: params.bearerToken,
+    body: {
+      accountAddress: walletAddress,
+      calldata,
+      signerKind: "STARK",
+      ...params.externalUserId ? { externalUserId: params.externalUserId } : {}
+    }
+  });
+  if (!response?.transactionHash) {
+    throw new Error(
+      "execute-sponsored-raw response missing transactionHash. Check the chipi-back logs for upstream paymaster errors."
+    );
+  }
+  return response.transactionHash;
+}
+
 // src/chipi-sdk.ts
 var ChipiSDK = class {
   constructor(config) {
@@ -4004,6 +4541,7 @@ var ChipiSDK = class {
     this.getUsdAmount = this.getUsdAmount.bind(this);
     this.signTypedData = this.signTypedData.bind(this);
     this.signTypedDataArray = this.signTypedDataArray.bind(this);
+    this.executeWithExternalSigner = this.executeWithExternalSigner.bind(this);
     this.createPaymasterAdapter = this.createPaymasterAdapter.bind(this);
     this.createX402Facilitator = this.createX402Facilitator.bind(this);
   }
@@ -4140,6 +4678,39 @@ var ChipiSDK = class {
   async signTypedDataArray({ params }) {
     return signTypedDataArray({ params });
   }
+  /**
+   * Run calls on a SHHH wallet, signed by an external Starknet wallet that is
+   * one of its `STARK_SNIP12` owners (Bramble, Braavos, Ready/Argent, OZ, or
+   * another Chipi wallet). The wallet signs an `Approval` typed data through
+   * `signTypedData` (its `wallet_signTypedData`); Chipi's paymaster relays the
+   * outside execution gaslessly. Returns the tx hash: wait for it.
+   *
+   * @example
+   * ```typescript
+   * // Bramble approves an agent session on the user's Chipi wallet.
+   * const bramble = window.starknet_bramble;
+   * const txHash = await sdk.executeWithExternalSigner({
+   *   params: {
+   *     walletAddress: wallet.publicKey,
+   *     ownerIndex: 1, // Bramble's index in the wallet's owner set
+   *     calls: buildSessionSetupCalls(wallet.publicKey, sessionConfig, policies),
+   *     signTypedData: (typedData) =>
+   *       bramble.request({ type: "wallet_signTypedData", params: typedData }),
+   *   },
+   *   bearerToken,
+   * });
+   * ```
+   */
+  async executeWithExternalSigner({
+    params,
+    bearerToken
+  }) {
+    return executeShhhWithExternalSigner({
+      ...params,
+      client: this.client,
+      bearerToken: this.resolveBearerToken(bearerToken)
+    });
+  }
   /**
    * Transfer tokens
    */
@@ -4689,13 +5260,20 @@ function createStarknetSignInTypedData(params) {
   };
 }
 var MAX_SKEW_SECONDS = 60;
+var SIWS_CHAIN_ID_FELT = BigInt(starknet.shortString.encodeShortString(SIWS_CHAIN_ID));
+function isMainnetChainId(chainId) {
+  if (chainId === SIWS_CHAIN_ID) return true;
+  if (typeof chainId === "bigint") return chainId === SIWS_CHAIN_ID_FELT;
+  if (typeof chainId !== "string" || !/^(0x[0-9a-f]+|[0-9]+)$/i.test(chainId)) return false;
+  return BigInt(chainId) === SIWS_CHAIN_ID_FELT;
+}
 async function verifyStarknetSignIn(params) {
   const { typedData: typedData2, signature, provider, expected, deploymentData } = params;
   const raw = typedData2?.message;
   if (!raw || !Array.isArray(signature) || signature.length === 0) {
     return { ok: false, reason: "MALFORMED" };
   }
-  if (typedData2.domain?.chainId !== SIWS_CHAIN_ID) return { ok: false, reason: "WRONG_CHAIN" };
+  if (!isMainnetChainId(typedData2.domain?.chainId)) return { ok: false, reason: "WRONG_CHAIN" };
   let canonical;
   let message;
   try {
@@ -4735,6 +5313,22 @@ init_snip12_hash();
 init_compute_wallet_address();
 init_oe();
 init_stark();
+function isClassHashNotFound(err) {
+  const e = err;
+  if (e?.baseError?.code === 28 || e?.code === 28) return true;
+  return /class hash not found/i.test(e?.message ?? String(err));
+}
+async function isShhhVerifierDeclared(provider, kind, classHash = shared.SHHH_VERIFIER_CLASS_HASHES[kind]) {
+  try {
+    await provider.getClassByHash(classHash);
+    return true;
+  } catch (err) {
+    if (isClassHashNotFound(err)) return false;
+    throw err;
+  }
+}
+
+// src/shhh/index.ts
 init_ed25519();
 
 // src/shhh/signers/eip191.ts
@@ -5402,150 +5996,6 @@ async function buildJwtAppleSubEnvelopeFromTestKey(params) {
   });
   return { envelope, pubkey, idToken };
 }
-var ROLE_OWNER = BigInt(starknet.shortString.encodeShortString("OWNER"));
-var ROLE_GUARDIAN = BigInt(starknet.shortString.encodeShortString("GUARDIAN"));
-var OP_ADD_OWNER = BigInt(starknet.shortString.encodeShortString("ADD_OWNER"));
-var OP_REMOVE_OWNER = BigInt(starknet.shortString.encodeShortString("REMOVE_OWNER"));
-var OP_ROTATE_OWNER = BigInt(starknet.shortString.encodeShortString("ROTATE_OWNER"));
-var OP_SET_THRESHOLD = BigInt(starknet.shortString.encodeShortString("SET_THRESHOLD"));
-var TIMELOCK_SECONDS = {
-  ADD_OWNER: 172800,
-  // 48h
-  REMOVE_OWNER: 86400,
-  // 24h
-  ROTATE_OWNER: 86400,
-  // 24h
-  SET_THRESHOLD: 172800,
-  // 48h
-  ADD_VERIFIER: 172800,
-  // 48h
-  REMOVE_VERIFIER: 86400,
-  // 24h
-  ADD_GUARDIAN: 86400,
-  // 24h
-  REMOVE_GUARDIAN: 86400,
-  // 24h
-  RECOVERY: 604800
-  // 7d — `TIMELOCK_RECOVERY`, the headline UX gate
-};
-var DEFAULT_OP_EXPIRY_SECONDS = 1209600;
-function _felt2(x, field = "felt") {
-  const v = typeof x === "bigint" ? x : BigInt(x);
-  if (v < 0n) {
-    throw new RangeError(`${field} must be a non-negative felt; got ${v.toString()}`);
-  }
-  return v;
-}
-function _encodeOwnerInput(input) {
-  if (input.weight < 0) {
-    throw new RangeError(`NewOwnerInput.weight must be non-negative; got ${input.weight}`);
-  }
-  const kindFelt = _felt2(BigInt(starknet.shortString.encodeShortString(input.kind)), "kind");
-  const roleFelt = input.role === "OWNER" ? ROLE_OWNER : ROLE_GUARDIAN;
-  const pubkey = input.pubkeyBytes.map((p, i) => _felt2(p, `pubkeyBytes[${i}]`));
-  return [
-    kindFelt,
-    BigInt(pubkey.length),
-    ...pubkey,
-    roleFelt,
-    BigInt(input.weight),
-    _felt2(BigInt(starknet.shortString.encodeShortString(input.label)), "label")
-  ];
-}
-function _call(walletAddress, entrypoint, calldata) {
-  for (let i = 0; i < calldata.length; i++) {
-    if (calldata[i] < 0n) {
-      throw new RangeError(
-        `calldata[${i}] must be a non-negative felt; got ${calldata[i].toString()}`
-      );
-    }
-  }
-  return {
-    contractAddress: typeof walletAddress === "bigint" ? "0x" + walletAddress.toString(16) : walletAddress,
-    entrypoint,
-    calldata: calldata.map((v) => "0x" + v.toString(16))
-  };
-}
-function buildProposeAddOwnerCall(args) {
-  const calldata = [BigInt(args.proposer), ..._encodeOwnerInput(args.newOwner)];
-  return _call(args.walletAddress, "propose_add_owner", calldata);
-}
-function buildExecuteAddOwnerCall(args) {
-  const calldata = [_felt2(args.opId), ..._encodeOwnerInput(args.newOwner)];
-  return _call(args.walletAddress, "execute_add_owner", calldata);
-}
-function buildProposeRemoveOwnerCall(args) {
-  return _call(args.walletAddress, "propose_remove_owner", [
-    BigInt(args.proposer),
-    BigInt(args.ownerId)
-  ]);
-}
-function buildExecuteRemoveOwnerCall(args) {
-  return _call(args.walletAddress, "execute_remove_owner", [
-    _felt2(args.opId),
-    BigInt(args.ownerId)
-  ]);
-}
-function buildProposeRotateOwnerCall(args) {
-  return _call(args.walletAddress, "propose_rotate_owner", [
-    BigInt(args.proposer),
-    BigInt(args.ownerId),
-    BigInt(args.newPubkeyBytes.length),
-    ...args.newPubkeyBytes
-  ]);
-}
-function buildExecuteRotateOwnerCall(args) {
-  return _call(args.walletAddress, "execute_rotate_owner", [
-    _felt2(args.opId),
-    BigInt(args.ownerId),
-    BigInt(args.newPubkeyBytes.length),
-    ...args.newPubkeyBytes
-  ]);
-}
-function buildProposeSetThresholdCall(args) {
-  return _call(args.walletAddress, "propose_set_threshold", [
-    BigInt(args.proposer),
-    BigInt(args.newThreshold)
-  ]);
-}
-function buildExecuteSetThresholdCall(args) {
-  return _call(args.walletAddress, "execute_set_threshold", [
-    _felt2(args.opId),
-    BigInt(args.newThreshold)
-  ]);
-}
-function buildCancelPendingOpCall(args) {
-  return _call(args.walletAddress, "cancel_pending_op", [_felt2(args.opId)]);
-}
-function buildInitiateRecoveryCall(args) {
-  const calldata = [BigInt(args.proposer), ..._encodeOwnerInput(args.newOwner)];
-  return _call(args.walletAddress, "initiate_recovery", calldata);
-}
-function buildCancelRecoveryCall(args) {
-  return _call(args.walletAddress, "cancel_recovery", [BigInt(args.ownerId)]);
-}
-function buildFinalizeRecoveryCall(args) {
-  return _call(args.walletAddress, "finalize_recovery", _encodeOwnerInput(args.newOwner));
-}
-var VIEW_SELECTORS = {
-  get_pending_op: starknet.hash.getSelectorFromName("get_pending_op"),
-  get_pending_recovery: starknet.hash.getSelectorFromName("get_pending_recovery"),
-  get_owner: starknet.hash.getSelectorFromName("get_owner")
-};
-function _toSecondsBigInt(value, field) {
-  if (typeof value === "bigint") return value;
-  if (!Number.isFinite(value)) {
-    throw new TypeError(`${field} must be a finite timestamp; got ${value}`);
-  }
-  return BigInt(Math.floor(value));
-}
-function isReadyToExecute(validAfterSecs, nowSecs) {
-  return _toSecondsBigInt(nowSecs, "nowSecs") >= _toSecondsBigInt(validAfterSecs, "validAfterSecs");
-}
-function secondsUntilExecutable(validAfterSecs, nowSecs) {
-  const remaining = _toSecondsBigInt(validAfterSecs, "validAfterSecs") - _toSecondsBigInt(nowSecs, "nowSecs");
-  return remaining <= 0n ? 0 : Number(remaining);
-}
 
 // src/shhh/index.ts
 init_threshold();
@@ -5656,6 +6106,7 @@ exports.ChipiTreasury = ChipiTreasury;
 exports.ChipiWallets = ChipiWallets;
 exports.DEFAULT_OP_EXPIRY_SECONDS = DEFAULT_OP_EXPIRY_SECONDS;
 exports.OP_ADD_OWNER = OP_ADD_OWNER;
+exports.OP_ADD_VERIFIER_CLASS = OP_ADD_VERIFIER_CLASS;
 exports.OP_REMOVE_OWNER = OP_REMOVE_OWNER;
 exports.OP_ROTATE_OWNER = OP_ROTATE_OWNER;
 exports.OP_SET_THRESHOLD = OP_SET_THRESHOLD;
@@ -5665,6 +6116,7 @@ exports.SIWS_CHAIN_ID = SIWS_CHAIN_ID;
 exports.SIWS_DOMAIN_NAME = SIWS_DOMAIN_NAME;
 exports.SIWS_DOMAIN_VERSION = SIWS_DOMAIN_VERSION;
 exports.STARKNET_SIGNATURE_VALID = STARKNET_SIGNATURE_VALID;
+exports.STARK_SNIP12_KIND_TAG = STARK_SNIP12_KIND_TAG;
 exports.SessionTxVerifier = SessionTxVerifier;
 exports.ShhhAccount = ShhhAccount;
 exports.TIMELOCK_SECONDS = TIMELOCK_SECONDS;
@@ -5681,6 +6133,7 @@ exports.buildEd25519EnvelopeFromSignature = buildEd25519EnvelopeFromSignature;
 exports.buildEip191EnvelopeFromPrivateKey = buildEip191EnvelopeFromPrivateKey;
 exports.buildEip191EnvelopeFromSignature = buildEip191EnvelopeFromSignature;
 exports.buildExecuteAddOwnerCall = buildExecuteAddOwnerCall;
+exports.buildExecuteAddVerifierClassCall = buildExecuteAddVerifierClassCall;
 exports.buildExecuteRemoveOwnerCall = buildExecuteRemoveOwnerCall;
 exports.buildExecuteRotateOwnerCall = buildExecuteRotateOwnerCall;
 exports.buildExecuteSetThresholdCall = buildExecuteSetThresholdCall;
@@ -5691,6 +6144,7 @@ exports.buildJwtAppleSubEnvelopeFromTokenResponse = buildJwtAppleSubEnvelopeFrom
 exports.buildMigrationCalls = buildMigrationCalls;
 exports.buildOutsideExecution = buildOutsideExecution;
 exports.buildProposeAddOwnerCall = buildProposeAddOwnerCall;
+exports.buildProposeAddVerifierClassCall = buildProposeAddVerifierClassCall;
 exports.buildProposeRemoveOwnerCall = buildProposeRemoveOwnerCall;
 exports.buildProposeRotateOwnerCall = buildProposeRotateOwnerCall;
 exports.buildProposeSetThresholdCall = buildProposeSetThresholdCall;
@@ -5699,6 +6153,7 @@ exports.buildRevokeSessionKeyCall = buildRevokeSessionKeyCall;
 exports.buildSessionSetupCalls = buildSessionSetupCalls;
 exports.buildSetSpendingPolicyCall = buildSetSpendingPolicyCall;
 exports.buildStarkEnvelope = buildStarkEnvelope;
+exports.buildStarkSnip12Envelope = buildStarkSnip12Envelope;
 exports.buildThresholdEnvelope = buildThresholdEnvelope;
 exports.buildWebAuthnEnvelopeFromAssertion = buildWebAuthnEnvelopeFromAssertion;
 exports.buildWebAuthnEnvelopeFromPrivateKey = buildWebAuthnEnvelopeFromPrivateKey;
@@ -5719,11 +6174,14 @@ exports.eip191OwnerPubkeyParam = eip191OwnerPubkeyParam;
 exports.eip191PubkeyFelts = eip191PubkeyFelts;
 exports.estimateThresholdGasOverhead = estimateThresholdGasOverhead;
 exports.executeShhhSponsoredRaw = executeShhhSponsoredRaw;
+exports.executeShhhWithExternalSigner = executeShhhWithExternalSigner;
+exports.executeShhhWithStarkKey = executeShhhWithStarkKey;
 exports.hashCall = hashCall;
 exports.hashCalls = hashCalls;
 exports.hashOutsideExecutionStruct = hashOutsideExecutionStruct;
 exports.hashStarknetDomain = hashStarknetDomain;
 exports.isReadyToExecute = isReadyToExecute;
+exports.isShhhVerifierDeclared = isShhhVerifierDeclared;
 exports.isThinkDecision = isThinkDecision;
 exports.isValidStarknetSignature = isValidStarknetSignature;
 exports.jwtAppleSubHash = jwtAppleSubHash;
@@ -5739,8 +6197,15 @@ exports.ownerCommitment = ownerCommitment;
 exports.parseAppleIdToken = parseAppleIdToken;
 exports.parseDerEcdsaSignature = parseDerEcdsaSignature;
 exports.parseEip191Signature = parseEip191Signature;
+exports.parseOpProposedEvents = parseOpProposedEvents;
+exports.parseStarknetWalletSignature = parseStarknetWalletSignature;
 exports.parseThresholdEnvelope = parseThresholdEnvelope;
+exports.prepareExternalOwnerExecution = prepareExternalOwnerExecution;
+exports.readPendingRecovery = readPendingRecovery;
+exports.readShhhOwners = readShhhOwners;
+exports.readVerifierClass = readVerifierClass;
 exports.resolveShhhChainId = resolveShhhChainId;
+exports.resolveStarkSnip12Signer = resolveStarkSnip12Signer;
 exports.secondsUntilExecutable = secondsUntilExecutable;
 exports.serializeExecuteFromOutsideV2Calldata = serializeExecuteFromOutsideV2Calldata;
 exports.signBootstrapMessage = signBootstrapMessage;
@@ -5749,8 +6214,14 @@ exports.signTypedDataArray = signTypedDataArray;
 exports.snip12HashToHexAsciiBytes = snip12HashToHexAsciiBytes;
 exports.starkOwnerId = starkOwnerId;
 exports.starkPubkeyFelts = starkPubkeyFelts;
+exports.starkSnip12ApprovalHash = starkSnip12ApprovalHash;
+exports.starkSnip12ApprovalTypedData = starkSnip12ApprovalTypedData;
+exports.starkSnip12OwnerCommitment = starkSnip12OwnerCommitment;
+exports.starkSnip12PubkeyFelts = starkSnip12PubkeyFelts;
+exports.submitExternalOwnerExecution = submitExternalOwnerExecution;
 exports.submitViaAccount = submitViaAccount;
 exports.validateSpendingPolicyConfig = validateSpendingPolicyConfig;
+exports.verifyStarkSnip12Approval = verifyStarkSnip12Approval;
 exports.verifyStarknetSignIn = verifyStarknetSignIn;
 exports.verifyUndeployedStarknetSignature = verifyUndeployedStarknetSignature;
 exports.waitForTransaction = waitForTransaction;