@chipi-stack/backend 14.8.0 → 14.10.0

package/dist/index.d.mts

@@ -8,7 +8,7 @@ import { ChipiTransactions } from './transactions.mjs';
 import { ChipiSkuPurchases } from './skuPurchases.mjs';
 import { ChipiSkus } from './skus.mjs';
 import { C as ChipiClient } from './client-CqD_yGH0.mjs';
-import { Call } from 'starknet';
+import { Call, ProviderInterface, Account } from 'starknet';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).
@@ -202,7 +202,7 @@ declare class ChipiSessions {
      * Set a spending policy for a session key + token pair.
      *
      * This executes a sponsored transaction (using owner signature) to call
-     * `set_spending_policy` on the CHIPI wallet contract.
+     * `set_spending_policy` on the wallet contract (CHIPI v29 or SHHH V8.4).
      *
      * The contract enforces these limits automatically during `__execute__()` on
      * ERC-20 operations (transfer, approve, increase_allowance) made by the session.
@@ -254,7 +254,7 @@ declare class ChipiSessions {
      * Remove a spending policy for a session key + token pair.
      *
      * This executes a sponsored transaction (using owner signature) to call
-     * `remove_spending_policy` on the CHIPI wallet contract.
+     * `remove_spending_policy` on the wallet contract (CHIPI v29 or SHHH V8.4).
      *
      * After removal, the session key has no spending limits for this token.
      *
@@ -292,10 +292,11 @@ declare class ChipiExchanges {
  *
  * Auth model (decision §11.2 — owner-signature-as-authorization):
  *   - propose / sign: `pk_` (the public api key) PLUS the owner's V2_SNIP12
- *     envelope (already inside the proposal body) AND the owner's STARK
- *     `ownerPubkey`. chipi-back's OwnerSignatureVerifier proves the request
- *     came from a current on-chain owner, so no secret is needed — these are
- *     safe to call from the browser.
+ *     envelope (already inside the proposal body) AND the owner's
+ *     `ownerPubkey` (kind-specific — see {@link ForTreasuryConfig.ownerPubkey}).
+ *     chipi-back's OwnerSignatureVerifier proves the request came from a
+ *     current on-chain owner, so no secret is needed — these are safe to
+ *     call from the browser.
  *   - execute / list / allowance: `sk_` (a secret key bearer). execute relays
  *     through the paymaster and meters; reads are org-private. Call these from
  *     a server (a Next.js route handler / your backend), never the browser.
@@ -324,9 +325,13 @@ interface TreasuryProposal {
     }[] | null;
     /** Human label for an action ("Vote YES on Proposal #5"). */
     title?: string | null;
-    /** Arbitrary integrator context. chipi-back has no column for it today, so
-     *  it is absent on every proposal it returns (kept for contract parity). */
+    /** Arbitrary integrator context persisted with the proposal (chipi-back
+     *  #301, `meta Json?`) — e.g. `{ poolId }`, read by the approver app's
+     *  `renderContext`. Null on payments and pre-#301 rows. */
     meta?: Record<string, string | number> | null;
+    /** App-level risk tier the proposal was filed under (chipi-back #302;
+     *  null = none). */
+    risk?: "ROUTINE" | "SENSITIVE" | null;
     oeMessageHash: string;
     oeNonce: string | null;
     /** chipi-back persists only `oeExecuteBefore`; the OE `executeAfter` is
@@ -349,9 +354,13 @@ interface ProposeBody {
         entrypoint: string;
         calldata: string[];
     }[];
-    /** Arbitrary integrator context. NOTE: not persisted by chipi-back today
-     *  (no column) — the global ValidationPipe strips it. Kept for parity. */
+    /** Arbitrary integrator context persisted with the proposal (chipi-back
+     *  #301). Flat string|number values, bounded server-side: ≤16 keys, key
+     *  ≤40 chars, string values ≤200 chars. */
     meta?: Record<string, string | number>;
+    /** Template risk tier (chipi-back #302): when the treasury configured the
+     *  matching quorum, the server overrides requiredApprovals at propose. */
+    risk?: "ROUTINE" | "SENSITIVE";
     oeMessageHash: string;
     oeNonce: string;
     oeExecuteBefore: string;
@@ -379,7 +388,7 @@ interface MultisigAllowance {
     [key: string]: unknown;
 }
 /**
- * A transport bound to one treasury + the local owner's STARK pubkey.
+ * A transport bound to one treasury + the local owner's public key.
  * Structurally compatible with `@chipi-stack/chipi-react`'s `MultisigTransport`.
  */
 interface TreasuryTransport {
@@ -395,8 +404,20 @@ interface TreasuryTransport {
 interface ForTreasuryConfig {
     /** The org treasury id (the multisig wallet's row id in chipi-back). */
     treasuryId: string;
-    /** The local owner's STARK public key (one 0x-hex felt). Sent with propose /
-     *  sign so the backend can verify the envelope commits to a current owner. */
+    /**
+     * The local owner's public key, sent with propose / sign so the backend can
+     * verify the envelope commits to a current on-chain owner. Kind-specific
+     * format (must match the `signerKind` of the envelopes this transport sends):
+     *   - STARK: one 0x-hex felt (the stark key) — `starkPubkeyFelts(pub)[0]`.
+     *   - WEBAUTHN_P256: `"0x<x>,0x<y>"` (full 32-byte BE P-256 coordinates) —
+     *     use `webauthnOwnerPubkeyParam(pubkey)`.
+     *   - EIP191_SECP256K1 (MetaMask): `"0x<x>,0x<y>"` (full 32-byte BE
+     *     secp256k1 coordinates) — use `eip191OwnerPubkeyParam(pubkey)`.
+     *   - ED25519 (Phantom): `"0x<low>,0x<high>"` (LE u128 halves of the
+     *     32-byte key) — use `ed25519OwnerPubkeyParam(publicKey)`.
+     * NOTE: the coordinate-based kinds take the FULL x/y values, never the
+     * 4-felt `*PubkeyFelts` form (the backend rejects more than 2 values).
+     */
     ownerPubkey: string;
     /** A secret key (`sk_`) for execute / list / allowance. Falls back to the
      *  SDK's configured `apiSecretKey`. Required only for those three; propose /
@@ -622,6 +643,14 @@ declare class ChipiSDK {
     signTypedData({ params }: {
         params: SignTypedDataParams;
     }): Promise<SignTypedDataResult>;
+    /**
+     * Sign SNIP-12 typed data and return the full signature span (felt strings) —
+     * the shape a dApp's `wallet_signTypedData` expects. Wallet-type aware:
+     * SHHH returns the V2_SNIP12 owner envelope; standard accounts return [r, s].
+     */
+    signTypedDataArray({ params }: {
+        params: SignTypedDataParams;
+    }): Promise<string[]>;
     /**
      * Transfer tokens
      */
@@ -781,6 +810,23 @@ declare class ChipiBrowserSDK extends ChipiSDK {
 declare const signTypedData: ({ params, }: {
     params: SignTypedDataParams;
 }) => Promise<SignTypedDataResult>;
+/**
+ * Sign SNIP-12 typed data and return the full signature SPAN as felt strings —
+ * the shape a dApp's `wallet_signTypedData` expects (wallet-api `Signature`).
+ *
+ * Wallet-type aware (this is the part the plain `signTypedData` {r,s} can't do):
+ * - **SHHH V8.4**: `__validate__` is disabled and the account verifies a
+ *   V2_SNIP12 envelope `[V2_SNIP12, owner_id, 'STARK', r, s]`. We hash the
+ *   typed data per SNIP-12, sign with the STARK owner key, and wrap it so the
+ *   account's `is_valid_signature` accepts it. Purely local (no API call).
+ * - **READY / standard**: a bare `[r, s]` from `account.signMessage`.
+ *
+ * Phase 0 covers the primary STARK owner (ownerIndex 0). WebAuthn-rooted
+ * owners (interactive passkey assertion) are a follow-up.
+ */
+declare const signTypedDataArray: ({ params, }: {
+    params: SignTypedDataParams;
+}) => Promise<string[]>;
 
 declare const encryptPrivateKey: (privateKey: string, password: string) => string;
 declare const decryptPrivateKey: (encryptedPrivateKey: string, password: string) => string;
@@ -1254,6 +1300,15 @@ declare function ed25519OwnerId(publicKey: Uint8Array): bigint;
  * order — what the Cairo `kind == ED25519` branch reads.
  */
 declare function ed25519PubkeyFelts(publicKey: Uint8Array): bigint[];
+/**
+ * The `ownerPubkey` string for the treasury coordination endpoints
+ * (`sdk.treasury.forTreasury({ ownerPubkey })`): `"0x<low>,0x<high>"` —
+ * the comma-joined `ed25519PubkeyFelts` halves. chipi-back's
+ * OwnerSignatureVerifier parses exactly this shape for ED25519 owners,
+ * so use this helper rather than hand-formatting (the LE-halves split is
+ * easy to get backwards).
+ */
+declare function ed25519OwnerPubkeyParam(publicKey: Uint8Array): string;
 /**
  * Build a V2_SNIP12 envelope for the Ed25519 kind. Async because the
  * underlying Garaga WASM must be initialized; subsequent calls reuse
@@ -1374,6 +1429,15 @@ declare function eip191PubkeyFelts(pubkey: Eip191Pubkey): bigint[];
  * owner_id = owner_commitment(EIP191_tag, [x.low, x.high, y.low, y.high]).
  */
 declare function eip191OwnerId(pubkey: Eip191Pubkey): bigint;
+/**
+ * The `ownerPubkey` string for the treasury coordination endpoints
+ * (`sdk.treasury.forTreasury({ ownerPubkey })`): `"0x<x>,0x<y>"` — the
+ * FULL 32-byte BE coordinates of the uncompressed secp256k1 point, NOT
+ * the 4 `eip191PubkeyFelts` halves. chipi-back's OwnerSignatureVerifier
+ * splits the coordinates into commitment felts itself; sending the
+ * 4-felt form fails its DTO validation (max 2 comma-joined values).
+ */
+declare function eip191OwnerPubkeyParam(pubkey: Eip191Pubkey): string;
 /**
  * Parse a 65-byte `personal_sign`/`eth_sign` signature hex string into
  * the Cairo-shaped envelope payload `[r.low, r.high, s.low, s.high, y_parity]`.
@@ -1482,6 +1546,14 @@ declare function parseDerEcdsaSignature(der: Uint8Array): {
 };
 declare function webauthnPubkeyFelts(pub: WebAuthnPubkey): bigint[];
 declare function webauthnOwnerId(pub: WebAuthnPubkey): bigint;
+/**
+ * The `ownerPubkey` string for the treasury coordination endpoints
+ * (`sdk.treasury.forTreasury({ ownerPubkey })`): `"0x<x>,0x<y>"` — the
+ * FULL 32-byte BE P-256 coordinates, NOT the 4 `webauthnPubkeyFelts`
+ * halves. chipi-back's OwnerSignatureVerifier splits the coordinates
+ * into commitment felts itself.
+ */
+declare function webauthnOwnerPubkeyParam(pub: WebAuthnPubkey): string;
 /**
  * Production / browser flow. The caller has run
  * `navigator.credentials.get({ publicKey: { challenge: msgBe32, ... } })`
@@ -2386,4 +2458,118 @@ declare function executeShhhSponsoredRaw(params: {
     chainId?: bigint | string;
 }): Promise<string>;
 
-export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryProposal, type TreasuryProposalSignature, type TreasuryTransport, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, webauthnOwnerId, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };
+/**
+ * ShhhAccount — ergonomic drop-in adapter for signing as a SHHH V8.4
+ * owner from a raw owner private key.
+ *
+ * Why this exists: a SHHH account is account-abstracted and its
+ * `__validate__` is DISABLED (shhh-wallet-cairo `src/account.cairo`
+ * panics with `'SHHH: __validate__ disabled'`), so the standard
+ * starknet.js path — `new Account(provider, addr, key).execute(calls)`
+ * — does NOT work. The only authorized execution path is
+ * `execute_from_outside_v2`: you sign an OutsideExecution and submit it.
+ *
+ * This wrapper hides that plumbing so a holder of an exported STARK
+ * owner key can write the familiar:
+ *
+ *     const account = new ShhhAccount(provider, address, privateKey, {
+ *       submit: submitViaAccount(fundedRelayer),
+ *     });
+ *     const { transactionHash } = await account.execute(calls);
+ *
+ * It signs the OE with the owner key (ownerIndex 0 = primary) and
+ * broadcasts via the configured `submit` strategy — either a funded
+ * Starknet account you control (fully self-sovereign, no Chipi servers)
+ * or a paymaster relay (gasless). If you don't configure `submit`, call
+ * `signExecution()` and broadcast the calldata yourself.
+ *
+ * Scope: STARK-kind owners. Other signer kinds (Ed25519 / EIP-191 /
+ * WebAuthn) have their own envelope builders; this adapter targets the
+ * exported-private-key use case, which is always a STARK owner.
+ */
+
+/**
+ * How a signed `execute_from_outside_v2` calldata is broadcast. The
+ * account itself can never pay gas (`__validate__` is disabled), so the
+ * broadcaster is always a separate party: a funded relayer you control,
+ * or a paymaster service. It only pays gas — it is NOT the signer.
+ */
+type ShhhSubmit = (input: {
+    accountAddress: string;
+    calldata: string[];
+}) => Promise<{
+    transactionHash: string;
+}>;
+interface ShhhAccountOptions {
+    /**
+     * Owner index into the wallet's owner_set. Defaults to `0n` (the
+     * primary owner — what an exported private key controls). Override
+     * for additional owners added via `propose_add_owner`.
+     */
+    ownerIndex?: bigint;
+    /**
+     * Chain id used for SNIP-12 hashing. Defaults to Starknet mainnet
+     * (Chipi is mainnet-only). A wrong value makes the account reject the
+     * signature on chain.
+     */
+    chainId?: bigint | string;
+    /** Broadcast strategy. Omit to sign-only via {@link ShhhAccount.signExecution}. */
+    submit?: ShhhSubmit;
+}
+interface ShhhSignedExecution {
+    /** The OutsideExecution that was signed. */
+    outsideExecution: OutsideExecution;
+    /** The owner signature envelope `[V2_SNIP12, owner_id, 'STARK', r, s]`. */
+    signature: bigint[];
+    /** The SNIP-12 message hash that was signed. */
+    messageHash: bigint;
+    /** Flat felt calldata for the `execute_from_outside_v2` selector. */
+    calldata: string[];
+}
+interface ShhhExecuteOptions {
+    /** Override the replay nonce. Default: `(Date.now() << 24) | random24`. */
+    nonce?: bigint | string;
+    /**
+     * How long (seconds from now) the OE stays valid. Default: the account
+     * max (~2h). The builder backdates `execute_after` by a 60s clock-skew
+     * buffer, and the account caps the total window at 2h, so the usable
+     * max here is `MAX_OE_VALIDITY_WINDOW_SECONDS - 60` (7140s). Values
+     * above that throw with a clear message rather than a cryptic builder
+     * error.
+     */
+    validForSeconds?: number;
+}
+declare class ShhhAccount {
+    /** The provider, exposed for convenience (e.g. `account.provider.waitForTransaction`). */
+    readonly provider: ProviderInterface;
+    readonly address: string;
+    readonly ownerIndex: bigint;
+    readonly chainId: bigint | string;
+    private readonly privateKey;
+    private readonly submitFn?;
+    constructor(provider: ProviderInterface, address: string, privateKey: bigint | string, options?: ShhhAccountOptions);
+    /**
+     * Build + sign an OutsideExecution for `calls` and return the
+     * serialized `execute_from_outside_v2` calldata (plus the underlying
+     * pieces). Use this when you want to broadcast the calldata yourself.
+     */
+    signExecution(calls: Call[], options?: ShhhExecuteOptions): Promise<ShhhSignedExecution>;
+    /**
+     * Sign `calls` and broadcast them via the configured `submit` strategy.
+     * Mirrors starknet.js `Account.execute` ergonomically. Returns the
+     * transaction hash without waiting for inclusion — use
+     * `provider.waitForTransaction(transactionHash)` if you need to block.
+     */
+    execute(calls: Call[], options?: ShhhExecuteOptions): Promise<{
+        transactionHash: string;
+    }>;
+}
+/**
+ * Self-sovereign submit strategy: relay the signed OE through any funded
+ * Starknet account you control. The funded account only pays gas — it is
+ * NOT the signer, and never sees the SHHH owner key. This is the path
+ * that needs no Chipi servers at all.
+ */
+declare function submitViaAccount(funded: Account): ShhhSubmit;
+
+export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, ShhhAccount, type ShhhAccountOptions, type ShhhExecuteOptions, type ShhhSignedExecution, type ShhhSubmit, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryProposal, type TreasuryProposalSignature, type TreasuryTransport, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519OwnerPubkeyParam, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191OwnerPubkeyParam, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, signTypedDataArray, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, submitViaAccount, webauthnOwnerId, webauthnOwnerPubkeyParam, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { ChipiTransactions } from './transactions.js';
 import { ChipiSkuPurchases } from './skuPurchases.js';
 import { ChipiSkus } from './skus.js';
 import { C as ChipiClient } from './client-CqD_yGH0.js';
-import { Call } from 'starknet';
+import { Call, ProviderInterface, Account } from 'starknet';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).
@@ -202,7 +202,7 @@ declare class ChipiSessions {
      * Set a spending policy for a session key + token pair.
      *
      * This executes a sponsored transaction (using owner signature) to call
-     * `set_spending_policy` on the CHIPI wallet contract.
+     * `set_spending_policy` on the wallet contract (CHIPI v29 or SHHH V8.4).
      *
      * The contract enforces these limits automatically during `__execute__()` on
      * ERC-20 operations (transfer, approve, increase_allowance) made by the session.
@@ -254,7 +254,7 @@ declare class ChipiSessions {
      * Remove a spending policy for a session key + token pair.
      *
      * This executes a sponsored transaction (using owner signature) to call
-     * `remove_spending_policy` on the CHIPI wallet contract.
+     * `remove_spending_policy` on the wallet contract (CHIPI v29 or SHHH V8.4).
      *
      * After removal, the session key has no spending limits for this token.
      *
@@ -292,10 +292,11 @@ declare class ChipiExchanges {
  *
  * Auth model (decision §11.2 — owner-signature-as-authorization):
  *   - propose / sign: `pk_` (the public api key) PLUS the owner's V2_SNIP12
- *     envelope (already inside the proposal body) AND the owner's STARK
- *     `ownerPubkey`. chipi-back's OwnerSignatureVerifier proves the request
- *     came from a current on-chain owner, so no secret is needed — these are
- *     safe to call from the browser.
+ *     envelope (already inside the proposal body) AND the owner's
+ *     `ownerPubkey` (kind-specific — see {@link ForTreasuryConfig.ownerPubkey}).
+ *     chipi-back's OwnerSignatureVerifier proves the request came from a
+ *     current on-chain owner, so no secret is needed — these are safe to
+ *     call from the browser.
  *   - execute / list / allowance: `sk_` (a secret key bearer). execute relays
  *     through the paymaster and meters; reads are org-private. Call these from
  *     a server (a Next.js route handler / your backend), never the browser.
@@ -324,9 +325,13 @@ interface TreasuryProposal {
     }[] | null;
     /** Human label for an action ("Vote YES on Proposal #5"). */
     title?: string | null;
-    /** Arbitrary integrator context. chipi-back has no column for it today, so
-     *  it is absent on every proposal it returns (kept for contract parity). */
+    /** Arbitrary integrator context persisted with the proposal (chipi-back
+     *  #301, `meta Json?`) — e.g. `{ poolId }`, read by the approver app's
+     *  `renderContext`. Null on payments and pre-#301 rows. */
     meta?: Record<string, string | number> | null;
+    /** App-level risk tier the proposal was filed under (chipi-back #302;
+     *  null = none). */
+    risk?: "ROUTINE" | "SENSITIVE" | null;
     oeMessageHash: string;
     oeNonce: string | null;
     /** chipi-back persists only `oeExecuteBefore`; the OE `executeAfter` is
@@ -349,9 +354,13 @@ interface ProposeBody {
         entrypoint: string;
         calldata: string[];
     }[];
-    /** Arbitrary integrator context. NOTE: not persisted by chipi-back today
-     *  (no column) — the global ValidationPipe strips it. Kept for parity. */
+    /** Arbitrary integrator context persisted with the proposal (chipi-back
+     *  #301). Flat string|number values, bounded server-side: ≤16 keys, key
+     *  ≤40 chars, string values ≤200 chars. */
     meta?: Record<string, string | number>;
+    /** Template risk tier (chipi-back #302): when the treasury configured the
+     *  matching quorum, the server overrides requiredApprovals at propose. */
+    risk?: "ROUTINE" | "SENSITIVE";
     oeMessageHash: string;
     oeNonce: string;
     oeExecuteBefore: string;
@@ -379,7 +388,7 @@ interface MultisigAllowance {
     [key: string]: unknown;
 }
 /**
- * A transport bound to one treasury + the local owner's STARK pubkey.
+ * A transport bound to one treasury + the local owner's public key.
  * Structurally compatible with `@chipi-stack/chipi-react`'s `MultisigTransport`.
  */
 interface TreasuryTransport {
@@ -395,8 +404,20 @@ interface TreasuryTransport {
 interface ForTreasuryConfig {
     /** The org treasury id (the multisig wallet's row id in chipi-back). */
     treasuryId: string;
-    /** The local owner's STARK public key (one 0x-hex felt). Sent with propose /
-     *  sign so the backend can verify the envelope commits to a current owner. */
+    /**
+     * The local owner's public key, sent with propose / sign so the backend can
+     * verify the envelope commits to a current on-chain owner. Kind-specific
+     * format (must match the `signerKind` of the envelopes this transport sends):
+     *   - STARK: one 0x-hex felt (the stark key) — `starkPubkeyFelts(pub)[0]`.
+     *   - WEBAUTHN_P256: `"0x<x>,0x<y>"` (full 32-byte BE P-256 coordinates) —
+     *     use `webauthnOwnerPubkeyParam(pubkey)`.
+     *   - EIP191_SECP256K1 (MetaMask): `"0x<x>,0x<y>"` (full 32-byte BE
+     *     secp256k1 coordinates) — use `eip191OwnerPubkeyParam(pubkey)`.
+     *   - ED25519 (Phantom): `"0x<low>,0x<high>"` (LE u128 halves of the
+     *     32-byte key) — use `ed25519OwnerPubkeyParam(publicKey)`.
+     * NOTE: the coordinate-based kinds take the FULL x/y values, never the
+     * 4-felt `*PubkeyFelts` form (the backend rejects more than 2 values).
+     */
     ownerPubkey: string;
     /** A secret key (`sk_`) for execute / list / allowance. Falls back to the
      *  SDK's configured `apiSecretKey`. Required only for those three; propose /
@@ -622,6 +643,14 @@ declare class ChipiSDK {
     signTypedData({ params }: {
         params: SignTypedDataParams;
     }): Promise<SignTypedDataResult>;
+    /**
+     * Sign SNIP-12 typed data and return the full signature span (felt strings) —
+     * the shape a dApp's `wallet_signTypedData` expects. Wallet-type aware:
+     * SHHH returns the V2_SNIP12 owner envelope; standard accounts return [r, s].
+     */
+    signTypedDataArray({ params }: {
+        params: SignTypedDataParams;
+    }): Promise<string[]>;
     /**
      * Transfer tokens
      */
@@ -781,6 +810,23 @@ declare class ChipiBrowserSDK extends ChipiSDK {
 declare const signTypedData: ({ params, }: {
     params: SignTypedDataParams;
 }) => Promise<SignTypedDataResult>;
+/**
+ * Sign SNIP-12 typed data and return the full signature SPAN as felt strings —
+ * the shape a dApp's `wallet_signTypedData` expects (wallet-api `Signature`).
+ *
+ * Wallet-type aware (this is the part the plain `signTypedData` {r,s} can't do):
+ * - **SHHH V8.4**: `__validate__` is disabled and the account verifies a
+ *   V2_SNIP12 envelope `[V2_SNIP12, owner_id, 'STARK', r, s]`. We hash the
+ *   typed data per SNIP-12, sign with the STARK owner key, and wrap it so the
+ *   account's `is_valid_signature` accepts it. Purely local (no API call).
+ * - **READY / standard**: a bare `[r, s]` from `account.signMessage`.
+ *
+ * Phase 0 covers the primary STARK owner (ownerIndex 0). WebAuthn-rooted
+ * owners (interactive passkey assertion) are a follow-up.
+ */
+declare const signTypedDataArray: ({ params, }: {
+    params: SignTypedDataParams;
+}) => Promise<string[]>;
 
 declare const encryptPrivateKey: (privateKey: string, password: string) => string;
 declare const decryptPrivateKey: (encryptedPrivateKey: string, password: string) => string;
@@ -1254,6 +1300,15 @@ declare function ed25519OwnerId(publicKey: Uint8Array): bigint;
  * order — what the Cairo `kind == ED25519` branch reads.
  */
 declare function ed25519PubkeyFelts(publicKey: Uint8Array): bigint[];
+/**
+ * The `ownerPubkey` string for the treasury coordination endpoints
+ * (`sdk.treasury.forTreasury({ ownerPubkey })`): `"0x<low>,0x<high>"` —
+ * the comma-joined `ed25519PubkeyFelts` halves. chipi-back's
+ * OwnerSignatureVerifier parses exactly this shape for ED25519 owners,
+ * so use this helper rather than hand-formatting (the LE-halves split is
+ * easy to get backwards).
+ */
+declare function ed25519OwnerPubkeyParam(publicKey: Uint8Array): string;
 /**
  * Build a V2_SNIP12 envelope for the Ed25519 kind. Async because the
  * underlying Garaga WASM must be initialized; subsequent calls reuse
@@ -1374,6 +1429,15 @@ declare function eip191PubkeyFelts(pubkey: Eip191Pubkey): bigint[];
  * owner_id = owner_commitment(EIP191_tag, [x.low, x.high, y.low, y.high]).
  */
 declare function eip191OwnerId(pubkey: Eip191Pubkey): bigint;
+/**
+ * The `ownerPubkey` string for the treasury coordination endpoints
+ * (`sdk.treasury.forTreasury({ ownerPubkey })`): `"0x<x>,0x<y>"` — the
+ * FULL 32-byte BE coordinates of the uncompressed secp256k1 point, NOT
+ * the 4 `eip191PubkeyFelts` halves. chipi-back's OwnerSignatureVerifier
+ * splits the coordinates into commitment felts itself; sending the
+ * 4-felt form fails its DTO validation (max 2 comma-joined values).
+ */
+declare function eip191OwnerPubkeyParam(pubkey: Eip191Pubkey): string;
 /**
  * Parse a 65-byte `personal_sign`/`eth_sign` signature hex string into
  * the Cairo-shaped envelope payload `[r.low, r.high, s.low, s.high, y_parity]`.
@@ -1482,6 +1546,14 @@ declare function parseDerEcdsaSignature(der: Uint8Array): {
 };
 declare function webauthnPubkeyFelts(pub: WebAuthnPubkey): bigint[];
 declare function webauthnOwnerId(pub: WebAuthnPubkey): bigint;
+/**
+ * The `ownerPubkey` string for the treasury coordination endpoints
+ * (`sdk.treasury.forTreasury({ ownerPubkey })`): `"0x<x>,0x<y>"` — the
+ * FULL 32-byte BE P-256 coordinates, NOT the 4 `webauthnPubkeyFelts`
+ * halves. chipi-back's OwnerSignatureVerifier splits the coordinates
+ * into commitment felts itself.
+ */
+declare function webauthnOwnerPubkeyParam(pub: WebAuthnPubkey): string;
 /**
  * Production / browser flow. The caller has run
  * `navigator.credentials.get({ publicKey: { challenge: msgBe32, ... } })`
@@ -2386,4 +2458,118 @@ declare function executeShhhSponsoredRaw(params: {
     chainId?: bigint | string;
 }): Promise<string>;
 
-export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryProposal, type TreasuryProposalSignature, type TreasuryTransport, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, webauthnOwnerId, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };
+/**
+ * ShhhAccount — ergonomic drop-in adapter for signing as a SHHH V8.4
+ * owner from a raw owner private key.
+ *
+ * Why this exists: a SHHH account is account-abstracted and its
+ * `__validate__` is DISABLED (shhh-wallet-cairo `src/account.cairo`
+ * panics with `'SHHH: __validate__ disabled'`), so the standard
+ * starknet.js path — `new Account(provider, addr, key).execute(calls)`
+ * — does NOT work. The only authorized execution path is
+ * `execute_from_outside_v2`: you sign an OutsideExecution and submit it.
+ *
+ * This wrapper hides that plumbing so a holder of an exported STARK
+ * owner key can write the familiar:
+ *
+ *     const account = new ShhhAccount(provider, address, privateKey, {
+ *       submit: submitViaAccount(fundedRelayer),
+ *     });
+ *     const { transactionHash } = await account.execute(calls);
+ *
+ * It signs the OE with the owner key (ownerIndex 0 = primary) and
+ * broadcasts via the configured `submit` strategy — either a funded
+ * Starknet account you control (fully self-sovereign, no Chipi servers)
+ * or a paymaster relay (gasless). If you don't configure `submit`, call
+ * `signExecution()` and broadcast the calldata yourself.
+ *
+ * Scope: STARK-kind owners. Other signer kinds (Ed25519 / EIP-191 /
+ * WebAuthn) have their own envelope builders; this adapter targets the
+ * exported-private-key use case, which is always a STARK owner.
+ */
+
+/**
+ * How a signed `execute_from_outside_v2` calldata is broadcast. The
+ * account itself can never pay gas (`__validate__` is disabled), so the
+ * broadcaster is always a separate party: a funded relayer you control,
+ * or a paymaster service. It only pays gas — it is NOT the signer.
+ */
+type ShhhSubmit = (input: {
+    accountAddress: string;
+    calldata: string[];
+}) => Promise<{
+    transactionHash: string;
+}>;
+interface ShhhAccountOptions {
+    /**
+     * Owner index into the wallet's owner_set. Defaults to `0n` (the
+     * primary owner — what an exported private key controls). Override
+     * for additional owners added via `propose_add_owner`.
+     */
+    ownerIndex?: bigint;
+    /**
+     * Chain id used for SNIP-12 hashing. Defaults to Starknet mainnet
+     * (Chipi is mainnet-only). A wrong value makes the account reject the
+     * signature on chain.
+     */
+    chainId?: bigint | string;
+    /** Broadcast strategy. Omit to sign-only via {@link ShhhAccount.signExecution}. */
+    submit?: ShhhSubmit;
+}
+interface ShhhSignedExecution {
+    /** The OutsideExecution that was signed. */
+    outsideExecution: OutsideExecution;
+    /** The owner signature envelope `[V2_SNIP12, owner_id, 'STARK', r, s]`. */
+    signature: bigint[];
+    /** The SNIP-12 message hash that was signed. */
+    messageHash: bigint;
+    /** Flat felt calldata for the `execute_from_outside_v2` selector. */
+    calldata: string[];
+}
+interface ShhhExecuteOptions {
+    /** Override the replay nonce. Default: `(Date.now() << 24) | random24`. */
+    nonce?: bigint | string;
+    /**
+     * How long (seconds from now) the OE stays valid. Default: the account
+     * max (~2h). The builder backdates `execute_after` by a 60s clock-skew
+     * buffer, and the account caps the total window at 2h, so the usable
+     * max here is `MAX_OE_VALIDITY_WINDOW_SECONDS - 60` (7140s). Values
+     * above that throw with a clear message rather than a cryptic builder
+     * error.
+     */
+    validForSeconds?: number;
+}
+declare class ShhhAccount {
+    /** The provider, exposed for convenience (e.g. `account.provider.waitForTransaction`). */
+    readonly provider: ProviderInterface;
+    readonly address: string;
+    readonly ownerIndex: bigint;
+    readonly chainId: bigint | string;
+    private readonly privateKey;
+    private readonly submitFn?;
+    constructor(provider: ProviderInterface, address: string, privateKey: bigint | string, options?: ShhhAccountOptions);
+    /**
+     * Build + sign an OutsideExecution for `calls` and return the
+     * serialized `execute_from_outside_v2` calldata (plus the underlying
+     * pieces). Use this when you want to broadcast the calldata yourself.
+     */
+    signExecution(calls: Call[], options?: ShhhExecuteOptions): Promise<ShhhSignedExecution>;
+    /**
+     * Sign `calls` and broadcast them via the configured `submit` strategy.
+     * Mirrors starknet.js `Account.execute` ergonomically. Returns the
+     * transaction hash without waiting for inclusion — use
+     * `provider.waitForTransaction(transactionHash)` if you need to block.
+     */
+    execute(calls: Call[], options?: ShhhExecuteOptions): Promise<{
+        transactionHash: string;
+    }>;
+}
+/**
+ * Self-sovereign submit strategy: relay the signed OE through any funded
+ * Starknet account you control. The funded account only pays gas — it is
+ * NOT the signer, and never sees the SHHH owner key. This is the path
+ * that needs no Chipi servers at all.
+ */
+declare function submitViaAccount(funded: Account): ShhhSubmit;
+
+export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, ShhhAccount, type ShhhAccountOptions, type ShhhExecuteOptions, type ShhhSignedExecution, type ShhhSubmit, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryProposal, type TreasuryProposalSignature, type TreasuryTransport, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519OwnerPubkeyParam, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191OwnerPubkeyParam, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, signTypedDataArray, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, submitViaAccount, webauthnOwnerId, webauthnOwnerPubkeyParam, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };