@aastar/sdk 0.24.2 → 0.26.0

package/dist/kms.d.cts

@@ -334,7 +334,28 @@ interface RunCeremonyOptions {
     rpId?: string;
     origin?: string;
     signCount?: number;
+    /**
+     * The 32-byte payload digest being authorized (e.g. the SignHash hash). When set,
+     * the WebAuthn challenge is bound to it as `SHA-256(nonce ‖ payload)` instead of the
+     * raw nonce — this is the "what you see is what you sign" (WYSIWYS) commitment the
+     * TA verifies (AirAccount #68). REQUIRED once the KMS runs in strict mode
+     * (`--features strict-challenge`); in the default transition mode the raw nonce is
+     * still accepted. Omit only for non-signing ceremonies (none today). Accepts a
+     * Uint8Array or a `0x` hex string.
+     */
+    payload?: Uint8Array | `0x${string}`;
 }
+/**
+ * Compute the WYSIWYS-bound WebAuthn challenge for a signing ceremony:
+ * `base64url( SHA-256( decode(nonce) ‖ payload ) )`.
+ *
+ * `nonce` is the base64url challenge from BeginAuthentication; `payload` is the 32-byte
+ * digest about to be signed (the SignHash hash). The KMS/TA recomputes this exact value
+ * and rejects the signature if it doesn't match (AirAccount #68). Use this in a browser
+ * frontend that builds its own WebAuthn assertion for a device passkey, so the per-call
+ * `webAuthnAssertion` it sends commits to the operation hash.
+ */
+declare function commitChallenge(nonceBase64Url: string, payload: Uint8Array | `0x${string}`): string;
 /**
  * Run a full WebAuthn challenge-binding ceremony (AirAccount #49):
  *   1. fetch a one-time TA challenge from the `begin` endpoint,
@@ -446,6 +467,71 @@ interface KmsEip712FieldValue {
     name: string;
     value: unknown;
 }
+/**
+ * Compute the standard EIP-712 digest for a KMS typed-data request — the same value the
+ * KMS hashes host-side, and the payload to commit to in the WebAuthn ceremony (WYSIWYS,
+ * AirAccount #68). Converts the KMS wire format (`types` = array of struct defs, `message`
+ * = array of `{name,value}`) into viem's `hashTypedData` input. `EIP712Domain` is dropped
+ * from `types` (viem derives it from `domain`).
+ */
+declare function eip712Digest(params: {
+    domain: KmsEip712Domain;
+    primaryType: string;
+    types: KmsEip712TypeDef[];
+    message: KmsEip712FieldValue[];
+}): `0x${string}`;
+/**
+ * Compute the KMS "mint" digest — the WYSIWYS commitment payload for the key-minting
+ * ceremonies (AirAccount #115): `create_agent_key` (`agent`) / `create_p256_session_key`
+ * (`p256`). Mirrors the TA byte-for-byte (`ta/src/main.rs` agent_mint_digest /
+ * p256_session_mint_digest), verified against the locked test vectors on aastar-sdk#135:
+ *
+ *   mint_digest = SHA-256( tag ‖ walletId[16B UUID] ‖ index[u32 BE] ‖ ttlSecs[i64 BE] ‖ SHA-256(subject) )
+ *
+ * Pass the result as the ceremony `payload` (the ceremony binds `challenge =
+ * SHA-256(nonce ‖ mint_digest)` via {@link commitChallenge}).
+ *
+ * NOTE on `index`: the agent/session index is allocated server-side
+ * (`next_agent_index_for_wallet`), so the caller must supply the index the KMS will assign
+ * (e.g. the current count for a new key) — a mismatch fails closed under strict mode.
+ * `subject` is the JWT `sub` (typically the human key id); `ttlSecs` the JWT lifetime.
+ */
+declare function mintDigest(p: {
+    kind: "agent" | "p256";
+    walletId: string;
+    index: number;
+    ttlSecs: number | bigint;
+    subject: string;
+}): `0x${string}`;
+/**
+ * Compute the grant-session `final_hash` — the value the TA signs and the WYSIWYS commitment
+ * payload for the grant ceremony (AirAccount #112). Equals the contract's `buildGrantHash()` /
+ * `buildP256GrantHash()` output byte-for-byte (`SessionKeyValidator._buildGrantHash` already
+ * applies `inner.toEthSignedMessageHash()`); verified against the live contract (E2E oracle).
+ * `inner = keccak256(abi.encode(domainTag, chainId,
+ * verifyingContract, account, <sessionKey | keyX,keyY>, expiry, contractScope, selectorScope,
+ * velocityLimit, velocityWindow, callTargetsHash, selectorsHash, nonce))` with
+ * `callTargetsHash = keccak256(abi.encodePacked(callTargets))`,
+ * `selectorsHash = keccak256(abi.encodePacked(selectorAllowlist))`; then EIP-191-prefixed.
+ */
+declare function grantSessionFinalHash(p: {
+    chainId: number;
+    verifyingContract: string;
+    account: string;
+    expiry: number;
+    contractScope: string;
+    selectorScope: string;
+    velocityLimit: number;
+    velocityWindow: number;
+    callTargets: string[];
+    selectorAllowlist: string[];
+    nonce: number | bigint | string;
+} & ({
+    sessionKey: string;
+} | {
+    keyX: string;
+    keyY: string;
+})): `0x${string}`;
 interface KmsSignTypedDataRequest {
     keyId: string;
     hdPath?: string;
@@ -666,6 +752,20 @@ declare class KmsManager {
         WebAuthn?: WebAuthnAssertion;
         Passkey?: LegacyPasskeyAssertion;
     }): Promise<KmsChangePasskeyResponse>;
+    /** Schedule key deletion, running the WebAuthn ceremony internally (raw-nonce). */
+    deleteKeyWithCeremony(params: {
+        KeyId: string;
+        PendingWindowInDays?: number;
+    }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer" | "payload">): Promise<KmsDeleteKeyResponse>;
+    /** Unfreeze a dormant key, running the WebAuthn ceremony internally (raw-nonce). */
+    unfreezeKeyWithCeremony(params: {
+        KeyId: string;
+    }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer" | "payload">): Promise<KmsUnfreezeKeyResponse>;
+    /** Rotate the bound passkey, running the WebAuthn ceremony internally (raw-nonce). */
+    changePasskeyWithCeremony(params: {
+        KeyId: string;
+        PasskeyPublicKey: string;
+    }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer" | "payload">): Promise<KmsChangePasskeyResponse>;
     /**
      * Sign a message or an EIP-155 transaction (WebAuthn-gated).
      * Provide exactly one of `Message` (hex) or `Transaction`. For a raw 32-byte
@@ -735,17 +835,36 @@ declare class KmsManager {
         DerivationPath: string;
     }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsDeriveAddressResponse>;
     /**
-     * Sign a message or EIP-155 transaction, running the challenge-binding ceremony
-     * internally. `params.KeyId` is required (it identifies the wallet to challenge).
+     * Sign a message or EIP-155 transaction via `/Sign`, running the ceremony internally.
+     * `params.KeyId` is required.
+     *
+     * ⚠️ STRICT MODE: unlike {@link signHashWithCeremony} / {@link signTypedDataWithCeremony},
+     * this does NOT auto-bind a payload commitment, because the TA derives the signed digest
+     * from `Message` / `Transaction` host-side (EIP-191 / RLP) and the SDK can't reproduce it
+     * byte-exactly for every input. So it sends the RAW nonce by default — which the KMS will
+     * REJECT once strict mode (#63) is on. For strict-safe signing either:
+     *   - pass `options.payload` = the exact digest the TA will sign (you computed it), or
+     *   - prefer {@link signHashWithCeremony} (commits to a known 32-byte hash).
      */
     signWithCeremony(params: Omit<KmsSignRequest, "WebAuthn" | "Passkey"> & {
         KeyId: string;
     }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsSignResponse>;
-    /** Sign a 32-byte digest, running the challenge-binding ceremony internally. */
+    /**
+     * Sign a 32-byte digest, running the challenge-binding ceremony internally.
+     * Binds the challenge to `hash` (WYSIWYS commitment, #68) by default — pass an
+     * explicit `options.payload` only to override.
+     */
     signHashWithCeremony(hash: string, target: {
         KeyId: string;
     }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsSignHashResponse>;
-    /** Sign EIP-712 typed data, running the challenge-binding ceremony internally. */
+    /**
+     * Sign EIP-712 typed data, running the challenge-binding ceremony internally.
+     * Auto-binds the WYSIWYS commitment (#68): the ceremony challenge is
+     * `SHA-256(nonce ‖ eip712Digest)`, where `eip712Digest` is the standard EIP-712
+     * digest the KMS hashes host-side — computed here via {@link eip712Digest} so the
+     * user's signature commits to the exact typed-data payload. Pass an explicit
+     * `options.payload` only to override.
+     */
     signTypedDataWithCeremony(params: Omit<KmsSignTypedDataRequest, "webAuthnAssertion">, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsSignTypedDataResponse>;
     /**
      * Sign a GRANT_SESSION_V2 hash, running the grant-session ceremony internally
@@ -769,37 +888,113 @@ declare class KmsManager {
      * challenge from {@link beginGrantSessionAuth} instead.)
      */
     beginWebAuthnAuth(keyId: string): Promise<KmsBeginAuthenticationResponse>;
+    /**
+     * Create a KMS signer that authorizes each signature with a LEGACY raw passkey
+     * assertion (reusable, no challenge consumption).
+     *
+     * @deprecated The KMS (v0.20.0+) rejects legacy raw passkey assertions for
+     * signing/mutating operations (`/SignHash` → 400, "no challenge binding —
+     * replayable"), unless `KMS_ALLOW_LEGACY_PASSKEY=1` is set on the KMS (test
+     * only). Prefer {@link createKmsSignerWithCeremony}, which runs a one-time
+     * challenge-bound WebAuthn ceremony per signature.
+     */
     createKmsSigner(keyId: string, address: string, assertionProvider: () => Promise<LegacyPasskeyAssertion>): KmsSigner;
+    /**
+     * Create a KMS signer that authorizes each signature with a one-time,
+     * challenge-bound WebAuthn ceremony (production-safe; replay-protected).
+     *
+     * Every `signMessage` call runs a FRESH ceremony (BeginAuthentication →
+     * authenticator assertion → `/SignHash` with the `WebAuthn` field), because the
+     * KMS consumes the challenge atomically (one challenge ⇒ one signature). A
+     * Tier-2/3 BLS transfer that needs N owner signatures therefore triggers N
+     * ceremonies — see {@link BLSSignatureService} (which now skips the unused
+     * userOpHash owner-ECDSA for tiered signatures, so Tier-2 needs only one).
+     *
+     * @param ceremonySigner authenticator that signs the WebAuthn challenge
+     *   (a browser passkey on the client, or {@link P256PasskeySigner} server-side).
+     */
+    createKmsSignerWithCeremony(keyId: string, address: string, ceremonySigner: PasskeyCeremonySigner, ceremonyOptions?: Omit<RunCeremonyOptions, "signer">, commitPayload?: boolean): KmsSigner;
 }
+/** How a {@link KmsSigner} authorizes each `/SignHash` call. */
+type KmsSignerAuth = {
+    mode: "legacy";
+    assertionProvider: () => Promise<LegacyPasskeyAssertion>;
+} | {
+    mode: "ceremony";
+    ceremonySigner: PasskeyCeremonySigner;
+    ceremonyOptions?: Omit<RunCeremonyOptions, "signer">;
+    /**
+     * Bind each ceremony challenge to the payload via `SHA-256(nonce ‖ hash)`
+     * (WYSIWYS, AirAccount #68). DEFAULT `true` — verified end-to-end against the live
+     * KMS (kms.aastar.io) once AirAccount#110 (host/TA challenge alignment) shipped; the
+     * KMS transition mode accepts it now and strict mode (#63) will REQUIRE it. Set
+     * `false` only to force the legacy raw-nonce challenge (not strict-safe).
+     */
+    commitPayload?: boolean;
+};
 /**
- * KMS-backed signer with Passkey assertion.
+ * KMS-backed signer (EIP-191 personal-sign over a digest).
  *
- * Each signing operation calls the `assertionProvider` to obtain a Legacy
- * Passkey assertion, which is then passed to KMS SignHash. The Legacy format
- * is reusable (no challenge consumption), enabling BLS dual-signing.
+ * Two authorization modes (see {@link KmsSignerAuth}):
+ *  - `ceremony` (preferred): each signature runs a fresh one-time WebAuthn
+ *    ceremony and calls KMS `SignHash` with the challenge-bound `WebAuthn` field
+ *    (replay-safe; what the KMS now requires).
+ *  - `legacy` (deprecated): each signature reuses a raw passkey assertion via
+ *    KMS `SignHash` `Passkey` field — rejected by KMS unless
+ *    `KMS_ALLOW_LEGACY_PASSKEY=1` (test only).
  *
  * Narrowed during the ethers -> viem migration: only the EIP-191 personal-sign
- * and address-read behaviour is actually consumed by the SDK, so the former
- * ethers.AbstractSigner surface (signTransaction / signTypedData / connect /
- * provider) has been dropped.
+ * and address-read behaviour is consumed by the SDK.
  */
 declare class KmsSigner {
     private readonly keyId;
     private readonly _address;
     private readonly kmsManager;
-    private readonly assertionProvider;
-    constructor(keyId: string, _address: string, kmsManager: KmsManager, assertionProvider: () => Promise<LegacyPasskeyAssertion>);
+    private readonly auth;
+    constructor(keyId: string, _address: string, kmsManager: KmsManager, auth: KmsSignerAuth);
     getAddress(): Promise<string>;
-    signMessage(message: string | Uint8Array): Promise<string>;
+    /**
+     * EIP-191 personal-sign over a digest. A string is hashed as UTF-8 text, a byte
+     * array as raw bytes — byte-identical to ethers `hashMessage`.
+     *
+     * @param webAuthnAssertion OPTIONAL pre-built, one-time ceremony assertion. Use
+     *   this in server flows where the passkey lives on the USER's device: the
+     *   frontend runs the BeginAuthentication ceremony and the backend forwards the
+     *   resulting `{ ChallengeId, Credential }` here. When supplied it takes
+     *   precedence over the signer's baked-in auth mode. Each assertion is one-time
+     *   (the KMS consumes the challenge), so a caller that needs N signatures must
+     *   supply N distinct assertions.
+     *
+     *   WYSIWYS (AirAccount #68): the frontend MUST build the assertion over the
+     *   payload-committed challenge `commitChallenge(nonce, hashOf(message))`, not the
+     *   raw nonce — otherwise a compromised host could swap the signed payload. The
+     *   raw-nonce assertion only works while the KMS runs in transition mode. (The
+     *   signer's own ceremony mode does this automatically.)
+     */
+    signMessage(message: string | Uint8Array, webAuthnAssertion?: WebAuthnAssertion): Promise<string>;
 }
 
 /**
- * Context for passing Passkey assertion data through the signing chain.
- * Used by KMS-backed signers to authenticate signing operations.
+ * Context for passing a LEGACY raw passkey assertion through the signing chain.
+ *
+ * @deprecated KMS v0.20.0+ rejects legacy raw passkey assertions for signing
+ * (no challenge binding → replayable). Prefer {@link WebAuthnCeremonyContext}.
  */
 interface PasskeyAssertionContext {
     assertion: LegacyPasskeyAssertion;
 }
+/**
+ * Context carrying a one-time, challenge-bound WebAuthn ceremony assertion
+ * (the replay-safe path the KMS now requires). In server transfer flows the
+ * passkey lives on the USER's device: the frontend runs the BeginAuthentication
+ * ceremony and the backend forwards the resulting `{ ChallengeId, Credential }`.
+ * Each assertion is one-time — a flow needing N signatures supplies N of them.
+ */
+interface WebAuthnCeremonyContext {
+    webAuthnAssertion: WebAuthnAssertion;
+}
+/** Either auth context accepted by a KMS-backed signer. */
+type SignerAuthContext = PasskeyAssertionContext | WebAuthnCeremonyContext;
 /**
  * Pluggable signer adapter — replaces NestJS AuthService wallet management.
  * Implement this to provide signing capabilities from your key management system.
@@ -817,9 +1012,11 @@ interface ISignerAdapter {
      * `account.signMessage({ raw: bytes })`). A `Uint8Array` (or raw `0x` hex) is
      * signed as raw bytes — callers pass a 32-byte digest, NOT UTF-8 text.
      *
-     * @param ctx optional Passkey assertion context for KMS-backed signers.
+     * @param ctx optional auth context for KMS-backed signers — a one-time
+     *   {@link WebAuthnCeremonyContext} (preferred) or a legacy
+     *   {@link PasskeyAssertionContext}.
      */
-    signMessage(userId: string, message: `0x${string}` | Uint8Array, ctx?: PasskeyAssertionContext): Promise<`0x${string}`>;
+    signMessage(userId: string, message: `0x${string}` | Uint8Array, ctx?: SignerAuthContext): Promise<`0x${string}`>;
     /**
      * Ensure a signer exists for the user (create on demand if needed).
      * Returns the signer's address.
@@ -1419,7 +1616,17 @@ declare class BLSSignatureService {
     /** Lazy-initialize BLSManager on first use. */
     private ensureInitialized;
     getActiveSignerNodes(): Promise<unknown[]>;
-    generateBLSSignature(userId: string, userOpHash: string, ctx?: PasskeyAssertionContext): Promise<BLSSignatureData>;
+    generateBLSSignature(userId: string, userOpHash: string, ctx?: SignerAuthContext, options?: {
+        /**
+         * Skip the owner ECDSA over `userOpHash` (`aaSignature`). The cumulative
+         * Tier-2 (algId 0x04) / Tier-3 (0x05) packings do NOT include it — they
+         * carry only `messagePointSignature` (owner intent comes from the P256
+         * passkey signature) — so computing it there is a wasted owner signature.
+         * Under the WebAuthn-ceremony KMS path that wasted signature is also a
+         * wasted user gesture, so tiered callers set this to `true`.
+         */
+        skipOwnerOpSignature?: boolean;
+    }): Promise<BLSSignatureData>;
     packSignature(blsData: BLSSignatureData): Promise<string>;
     /**
      * Generate a tiered signature based on the required tier level.
@@ -1441,7 +1648,7 @@ declare class BLSSignatureService {
         userOpHash: string;
         p256Signature?: string;
         guardianSigner?: GuardianSigner;
-        ctx?: PasskeyAssertionContext;
+        ctx?: SignerAuthContext;
     }): Promise<string>;
 }
 
@@ -1561,7 +1768,20 @@ interface ExecuteTransferParams {
      *  the gas token address appended to paymasterData. Used when the paymaster
      *  contract does not expose a public token() getter for auto-detection. */
     paymasterTokenAddress?: string;
+    /**
+     * LEGACY raw passkey assertion for KMS signing.
+     * @deprecated KMS v0.20.0+ rejects it (replayable). Use {@link webAuthnAssertion}.
+     */
     passkeyAssertion?: LegacyPasskeyAssertion;
+    /**
+     * One-time, challenge-bound WebAuthn ceremony assertion for KMS owner signing
+     * (replay-safe; what the KMS now requires). The frontend runs the
+     * BeginAuthentication ceremony with the user's device passkey and passes the
+     * resulting `{ ChallengeId, Credential }` here. The challenge is consumed once,
+     * so this authorizes exactly ONE owner signature — use the tiered path
+     * (`useAirAccountTiering: true`), which needs a single owner signature.
+     */
+    webAuthnAssertion?: WebAuthnAssertion;
     /** P256 passkey signature (64 bytes hex). Required for AirAccount Tier 2/3. */
     p256Signature?: string;
     /** Guardian signer instance. Required for AirAccount Tier 3. */
@@ -1639,7 +1859,7 @@ declare class WalletManager {
     private readonly signer;
     constructor(signer: ISignerAdapter);
     getAddress(userId: string): Promise<`0x${string}`>;
-    signMessage(userId: string, message: `0x${string}` | Uint8Array, ctx?: PasskeyAssertionContext): Promise<`0x${string}`>;
+    signMessage(userId: string, message: `0x${string}` | Uint8Array, ctx?: SignerAuthContext): Promise<`0x${string}`>;
     ensureSigner(userId: string): Promise<{
         address: `0x${string}`;
     }>;
@@ -1670,6 +1890,26 @@ declare class WalletManager {
  *
  * const account = await client.accounts.createAccount('user-123');
  * ```
+ *
+ * @example KMS-backed signing (production) — inject {@link KmsSignerAdapter} as the
+ * `signer`. This is the wiring seam that carries a per-call WebAuthn ceremony
+ * assertion (challenge-bound, replay-safe) from `executeTransfer` through to the
+ * KMS `/SignHash`. The `userId → { keyId, address }` mapping is app-specific.
+ * ```ts
+ * import { AirAccountServerClient, KmsManager, KmsSignerAdapter } from '@aastar/airaccount/server';
+ *
+ * const kms = new KmsManager({ kmsEndpoint, kmsApiKey, kmsEnabled: true });
+ * const client = new AirAccountServerClient({
+ *   ...rest,
+ *   signer: new KmsSignerAdapter(kms, async (userId) => lookupUserKey(userId)),
+ * });
+ * // Transfer with a one-time WebAuthn assertion (frontend ceremony) on the tiered path:
+ * await client.transfers.executeTransfer(userId, {
+ *   ...params,
+ *   useAirAccountTiering: true,
+ *   webAuthnAssertion, // { ChallengeId, Credential } from BeginAuthentication
+ * });
+ * ```
  */
 declare class AirAccountServerClient {
     readonly ethereum: EthereumProvider;
@@ -2952,7 +3192,15 @@ declare class KmsAgentService {
      * the caller supplies the resulting assertion in the request.
      */
     revokeAgentCredential(params: KmsRevokeAgentCredentialRequest): Promise<KmsRevokeAgentCredentialResponse>;
-    /** Mint an agent key, running the challenge-binding ceremony internally. */
+    /**
+     * Mint an agent key, running the challenge-binding ceremony internally.
+     *
+     * STRICT MODE (AirAccount #115): bind the mint params by passing `options.payload =
+     * mintDigest({ kind: "agent", walletId, index, ttlSecs, subject })` — `index` is the
+     * agent_index the KMS will assign (query it first), `subject` the JWT sub (human key id),
+     * `ttlSecs` the JWT lifetime. Without a payload the ceremony sends the raw nonce, which
+     * strict mode rejects.
+     */
     createAgentKeyWithCeremony(params: Omit<KmsCreateAgentKeyRequest, "webAuthnAssertion" | "passkeyAssertion">, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsCreateAgentKeyResponse>;
     /**
      * Refresh an agent credential, running the challenge-binding ceremony
@@ -3063,7 +3311,15 @@ declare class KmsSessionService {
      * the caller. Idempotent: revoking an already-revoked key still resolves.
      */
     revokeP256SessionKey(params: RevokeP256SessionKeyRequest): Promise<RevokeP256SessionKeyResponse>;
-    /** Create a P-256 session key, running the challenge-binding ceremony internally. */
+    /**
+     * Create a P-256 session key, running the challenge-binding ceremony internally.
+     *
+     * STRICT MODE (AirAccount #115): bind the mint params by passing `options.payload =
+     * mintDigest({ kind: "p256", walletId, index, ttlSecs, subject })` — `index` is the
+     * session_index the KMS will assign (query it first), `subject` the JWT sub (human key
+     * id), `ttlSecs` the JWT lifetime. Without a payload the ceremony sends the raw nonce,
+     * which strict mode rejects.
+     */
     createP256SessionKeyWithCeremony(params: Omit<CreateP256SessionKeyRequest, "webAuthnAssertion">, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<CreateP256SessionKeyResponse>;
     /**
      * Revoke a P-256 session key, running the challenge-binding ceremony internally.
@@ -3146,7 +3402,19 @@ declare class KmsPaymentSigner {
      * Sign an x402 payment authorization via `POST /kms/SignX402Payment`.
      */
     signX402Payment(params: KmsSignX402PaymentRequest, auth: KmsPaymentAuth): Promise<KmsPaymentSignatureResponse>;
-}
+    /** Sign a MicroPaymentChannel voucher, running the committed ceremony internally. */
+    signMicropaymentVoucherWithCeremony(params: KmsSignMicropaymentVoucherRequest, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer" | "payload">): Promise<KmsPaymentSignatureResponse>;
+    /** Sign a GToken EIP-3009 authorization, running the committed ceremony internally. */
+    signGTokenAuthorizationWithCeremony(params: KmsSignGTokenAuthorizationRequest, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer" | "payload">): Promise<KmsPaymentSignatureResponse>;
+    /** Sign an x402 payment, running the committed ceremony internally. */
+    signX402PaymentWithCeremony(params: KmsSignX402PaymentRequest, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer" | "payload">): Promise<KmsPaymentSignatureResponse>;
+}
+/** EIP-712 digest for a MicroPaymentChannel `Voucher` (domain MicroPaymentChannel/1.0.0). */
+declare function micropaymentVoucherDigest(p: KmsSignMicropaymentVoucherRequest): `0x${string}`;
+/** EIP-712 digest for a GToken EIP-3009 `TransferWithAuthorization` (domain GToken/1). */
+declare function gTokenAuthorizationDigest(p: KmsSignGTokenAuthorizationRequest): `0x${string}`;
+/** EIP-712 digest for an x402 `PaymentPayload` (domain SuperPaymaster/1). */
+declare function x402PaymentDigest(p: KmsSignX402PaymentRequest): `0x${string}`;
 
 /**
  * Liveness probe response. Returned by `GET /health` without auth — works even
@@ -3334,10 +3602,46 @@ declare class LocalWalletSigner implements ISignerAdapter {
     private readonly account;
     constructor(privateKey: string);
     getAddress(_userId: string): Promise<`0x${string}`>;
-    signMessage(_userId: string, message: `0x${string}` | Uint8Array, _ctx?: PasskeyAssertionContext): Promise<`0x${string}`>;
+    signMessage(_userId: string, message: `0x${string}` | Uint8Array, _ctx?: SignerAuthContext): Promise<`0x${string}`>;
     ensureSigner(_userId: string): Promise<{
         address: `0x${string}`;
     }>;
 }
 
-export { ACCOUNT_ABI, AGENT_SESSION_KEY_VALIDATOR_ABI, AIRACCOUNT_ABI, AIRACCOUNT_ADDRESSES, AIRACCOUNT_FACTORY_ABI, AIR_ACCOUNT_COMPOSITE_VALIDATOR_ABI, AIR_ACCOUNT_DELEGATE_ABI, AIR_ACCOUNT_DELEGATE_ADDRESS, ALG_ID, AccountManager, type AccountRecord, type ActiveRecovery, AgentRegistryService, type AgentReputationSummary, type AgentSessionConfig, type AgentSessionInfo, AirAccountServerClient, type AirAccountVersion, BLSSignatureData, BLSSignatureService, type BeginCeremonyResponse, type BindERC8004AgentWalletParams, type BlsConfigRecord, type BuildCredentialOptions, CALLDATA_PARSER_REGISTRY_ABI, ConsoleLogger, type CreateAgentAccountParams, type CreateP256SessionKeyRequest, type CreateP256SessionKeyResponse, DEFAULT_CREDENTIAL_ID, DEFAULT_KMS_ENDPOINT, DEFAULT_ORIGIN, DEFAULT_RP_ID, type DelegateInitParams, DvtPendingConfirmationError, type EIP7702Authorization, EIP7702DelegateService, ENTRYPOINT_ABI_V6, ENTRYPOINT_ABI_V7_V8, ENTRYPOINT_ADDRESSES, ERC20_ABI, ERC8004Service, ERC8004_ADDRESSES, EXECUTE_BATCH_SELECTOR, EXECUTE_SELECTOR, EXECUTE_USER_OP_SELECTOR, type EntryPointConfig, EntryPointVersion, type EntryPointVersionConfig, type EstimateGasParams, EthereumProvider, type ExecuteTransferParams, FACTORY_ABI_V6, FACTORY_ABI_V7_V8, FORCE_EXIT_MODULE_ABI, ForceExitService, type FullConfigGuardianParams, GLOBAL_GUARD_ABI, type GrantP256SessionParams, type GrantSessionParams, GuardChecker, type GuardState, GuardStateReader, GuardStatus, type ILogger, type ISignerAdapter, type IStorageAdapter, type InstallModuleParams, KmsAgentService, type KmsAttestationManifestResponse, type KmsAttestationProofResponse, type KmsAttestationResponse, type KmsBeginAuthenticationRequest, type KmsBeginAuthenticationResponse, type KmsBeginGrantSessionAuthRequest, type KmsBeginGrantSessionAuthResponse, type KmsBeginRegistrationRequest, type KmsBeginRegistrationResponse, type KmsChangePasskeyResponse, type KmsCompleteRegistrationRequest, type KmsCompleteRegistrationResponse, type KmsCreateAgentKeyRequest, type KmsCreateAgentKeyResponse, type KmsCreateKeyRequest, type KmsCreateKeyResponse, type KmsDeleteKeyResponse, type KmsDeriveAddressResponse, type KmsDescribeKeyResponse, type KmsEip712Domain, type KmsEip712FieldValue, type KmsEip712TypeDef, type KmsEthereumTransaction, type KmsGetPublicKeyResponse, type KmsHealthResponse, KmsHttpClient, type KmsHttpClientOptions, type KmsKeyStatusResponse, type KmsListKeysResponse, KmsManager, KmsMonitorService, type KmsPaymentAuth, type KmsPaymentSignatureResponse, KmsPaymentSigner, type KmsPurgeKeyResponse, type KmsQueueStatusResponse, type KmsRefreshAgentCredentialRequest, type KmsRefreshAgentCredentialResponse, type KmsRevokeAgentCredentialRequest, type KmsRevokeAgentCredentialResponse, type KmsRollbackCounterResponse, KmsSessionService, type KmsSignAgentRequest, type KmsSignAgentResponse, type KmsSignGTokenAuthorizationRequest, type KmsSignGrantSessionRequest, type KmsSignGrantSessionResponse, type KmsSignHashResponse, type KmsSignMicropaymentVoucherRequest, type KmsSignP256GrantSessionRequest, type KmsSignRequest, type KmsSignResponse, type KmsSignTypedDataRequest, type KmsSignTypedDataResponse, type KmsSignX402PaymentRequest, KmsSigner, type KmsStatsResponse, type KmsVersionResponse, type L2Type, L2_TYPE, type LegacyPasskeyAssertion, LocalWalletSigner, MAX_GUARDIANS, MODULE_TYPE, MemoryStorage, type MintAgentIdentityParams, ModuleManager, type ModuleTypeId, type OapdConfig, type P256GuardianKey, P256PasskeySigner, PackedUserOperation, type PasskeyAssertionContext, type PasskeyCeremonySigner, PaymasterManager, PaymasterPriceStalenessError, type PaymasterRecord, type PendingExit, type PendingWeightChange, PreCheckResult, type QueryAgentReputationParams, RECOVERY_THRESHOLD, RECOVERY_TIMELOCK_SECONDS, RecoveryService, type RevokeP256SessionKeyRequest, type RevokeP256SessionKeyResponse, type RunCeremonyOptions, SESSION_KEY_VALIDATOR_ABI, type SerializedGuardianSpec, type ServerConfig, type SessionInfo, SessionKeyService, type SetAgentWalletParams, type SignP256UserOpRequest, type SignP256UserOpResponse, SilentLogger, type SubmitAgentReputationParams, TIER_GUARD_HOOK_ABI, TierConfig, TierLevel$1 as TierLevel, type TokenBalance, type TokenGuardState, type TokenInfo, TokenService, TransferManager, type TransferRecord, type TransferResult, type UninstallModuleParams, UserOperation, VALIDATOR_ABI, WEIGHT_CHANGE_EXPIRY_SECONDS, WEIGHT_CHANGE_THRESHOLD, WEIGHT_CHANGE_TIMELOCK_SECONDS, WalletManager, type WebAuthnAssertion, type WebAuthnAuthenticationCredential, type WeightConfig, WeightedSignatureService, YAAAServerClient, base64UrlDecode, base64UrlEncode, beginAuthenticationChallenge, beginGrantSessionChallenge, buildAuthenticationCredential, buildAuthenticatorData, buildClientDataJSON, buildFullInitConfig, buildInstallModuleHash, buildUninstallModuleHash, computeOapdSalt, erc8004AddressesForChain, getOapdAddress, getOapdAddressWithChainId, initConfigFromRecord, initConfigToTuple, isExecuteUserOpWrapped, isOapdDeployed, isPendingConfirmation, packP256SessionSignature, packSecp256k1SessionSignature, runAuthenticationCeremony, runGrantSessionCeremony, runWebAuthnCeremony, sepoliaV07Config, serializeGuardianSpecs, toGuardianSpecs, validateConfig, wrapExecuteUserOp };
+/** Resolves an app user id to its KMS key + EOA address. App-specific mapping. */
+type KmsKeyResolver = (userId: string) => Promise<{
+    keyId: string;
+    address: `0x${string}`;
+}>;
+/**
+ * KMS-backed {@link ISignerAdapter} — the bridge between the SDK signing chain
+ * (BLS / transfer pass a {@link SignerAuthContext}) and the KMS `/SignHash` API.
+ *
+ * This is the concrete adapter the BLS/transfer services expect: it unpacks the
+ * per-call auth context and forwards it to the right KMS endpoint.
+ *  - {@link WebAuthnCeremonyContext} (preferred) → `signHashWithWebAuthn`
+ *    (one-time, challenge-bound; replay-safe — what KMS v0.20.0+ requires).
+ *  - {@link PasskeyAssertionContext} (legacy, @deprecated) → `signHash`
+ *    (rejected by KMS unless `KMS_ALLOW_LEGACY_PASSKEY=1`, test only).
+ *
+ * The frontend runs the BeginAuthentication ceremony with the user's device
+ * passkey and passes the resulting `{ ChallengeId, Credential }` down as
+ * `ctx.webAuthnAssertion`. Since each challenge is consumed once, a flow needing
+ * N signatures must pass N assertions — use the tiered transfer path, which needs
+ * only one owner signature.
+ *
+ * The `userId → { keyId, address }` mapping is app-specific; inject it via
+ * {@link KmsKeyResolver}.
+ */
+declare class KmsSignerAdapter implements ISignerAdapter {
+    private readonly kms;
+    private readonly resolveKey;
+    constructor(kms: KmsManager, resolveKey: KmsKeyResolver);
+    getAddress(userId: string): Promise<`0x${string}`>;
+    ensureSigner(userId: string): Promise<{
+        address: `0x${string}`;
+    }>;
+    signMessage(userId: string, message: `0x${string}` | Uint8Array, ctx?: SignerAuthContext): Promise<`0x${string}`>;
+}
+
+export { ACCOUNT_ABI, AGENT_SESSION_KEY_VALIDATOR_ABI, AIRACCOUNT_ABI, AIRACCOUNT_ADDRESSES, AIRACCOUNT_FACTORY_ABI, AIR_ACCOUNT_COMPOSITE_VALIDATOR_ABI, AIR_ACCOUNT_DELEGATE_ABI, AIR_ACCOUNT_DELEGATE_ADDRESS, ALG_ID, AccountManager, type AccountRecord, type ActiveRecovery, AgentRegistryService, type AgentReputationSummary, type AgentSessionConfig, type AgentSessionInfo, AirAccountServerClient, type AirAccountVersion, BLSSignatureData, BLSSignatureService, type BeginCeremonyResponse, type BindERC8004AgentWalletParams, type BlsConfigRecord, type BuildCredentialOptions, CALLDATA_PARSER_REGISTRY_ABI, ConsoleLogger, type CreateAgentAccountParams, type CreateP256SessionKeyRequest, type CreateP256SessionKeyResponse, DEFAULT_CREDENTIAL_ID, DEFAULT_KMS_ENDPOINT, DEFAULT_ORIGIN, DEFAULT_RP_ID, type DelegateInitParams, DvtPendingConfirmationError, type EIP7702Authorization, EIP7702DelegateService, ENTRYPOINT_ABI_V6, ENTRYPOINT_ABI_V7_V8, ENTRYPOINT_ADDRESSES, ERC20_ABI, ERC8004Service, ERC8004_ADDRESSES, EXECUTE_BATCH_SELECTOR, EXECUTE_SELECTOR, EXECUTE_USER_OP_SELECTOR, type EntryPointConfig, EntryPointVersion, type EntryPointVersionConfig, type EstimateGasParams, EthereumProvider, type ExecuteTransferParams, FACTORY_ABI_V6, FACTORY_ABI_V7_V8, FORCE_EXIT_MODULE_ABI, ForceExitService, type FullConfigGuardianParams, GLOBAL_GUARD_ABI, type GrantP256SessionParams, type GrantSessionParams, GuardChecker, type GuardState, GuardStateReader, GuardStatus, type ILogger, type ISignerAdapter, type IStorageAdapter, type InstallModuleParams, KmsAgentService, type KmsAttestationManifestResponse, type KmsAttestationProofResponse, type KmsAttestationResponse, type KmsBeginAuthenticationRequest, type KmsBeginAuthenticationResponse, type KmsBeginGrantSessionAuthRequest, type KmsBeginGrantSessionAuthResponse, type KmsBeginRegistrationRequest, type KmsBeginRegistrationResponse, type KmsChangePasskeyResponse, type KmsCompleteRegistrationRequest, type KmsCompleteRegistrationResponse, type KmsCreateAgentKeyRequest, type KmsCreateAgentKeyResponse, type KmsCreateKeyRequest, type KmsCreateKeyResponse, type KmsDeleteKeyResponse, type KmsDeriveAddressResponse, type KmsDescribeKeyResponse, type KmsEip712Domain, type KmsEip712FieldValue, type KmsEip712TypeDef, type KmsEthereumTransaction, type KmsGetPublicKeyResponse, type KmsHealthResponse, KmsHttpClient, type KmsHttpClientOptions, type KmsKeyResolver, type KmsKeyStatusResponse, type KmsListKeysResponse, KmsManager, KmsMonitorService, type KmsPaymentAuth, type KmsPaymentSignatureResponse, KmsPaymentSigner, type KmsPurgeKeyResponse, type KmsQueueStatusResponse, type KmsRefreshAgentCredentialRequest, type KmsRefreshAgentCredentialResponse, type KmsRevokeAgentCredentialRequest, type KmsRevokeAgentCredentialResponse, type KmsRollbackCounterResponse, KmsSessionService, type KmsSignAgentRequest, type KmsSignAgentResponse, type KmsSignGTokenAuthorizationRequest, type KmsSignGrantSessionRequest, type KmsSignGrantSessionResponse, type KmsSignHashResponse, type KmsSignMicropaymentVoucherRequest, type KmsSignP256GrantSessionRequest, type KmsSignRequest, type KmsSignResponse, type KmsSignTypedDataRequest, type KmsSignTypedDataResponse, type KmsSignX402PaymentRequest, KmsSigner, KmsSignerAdapter, type KmsSignerAuth, type KmsStatsResponse, type KmsVersionResponse, type L2Type, L2_TYPE, type LegacyPasskeyAssertion, LocalWalletSigner, MAX_GUARDIANS, MODULE_TYPE, MemoryStorage, type MintAgentIdentityParams, ModuleManager, type ModuleTypeId, type OapdConfig, type P256GuardianKey, P256PasskeySigner, PackedUserOperation, type PasskeyAssertionContext, type PasskeyCeremonySigner, PaymasterManager, PaymasterPriceStalenessError, type PaymasterRecord, type PendingExit, type PendingWeightChange, PreCheckResult, type QueryAgentReputationParams, RECOVERY_THRESHOLD, RECOVERY_TIMELOCK_SECONDS, RecoveryService, type RevokeP256SessionKeyRequest, type RevokeP256SessionKeyResponse, type RunCeremonyOptions, SESSION_KEY_VALIDATOR_ABI, type SerializedGuardianSpec, type ServerConfig, type SessionInfo, SessionKeyService, type SetAgentWalletParams, type SignP256UserOpRequest, type SignP256UserOpResponse, type SignerAuthContext, SilentLogger, type SubmitAgentReputationParams, TIER_GUARD_HOOK_ABI, TierConfig, TierLevel$1 as TierLevel, type TokenBalance, type TokenGuardState, type TokenInfo, TokenService, TransferManager, type TransferRecord, type TransferResult, type UninstallModuleParams, UserOperation, VALIDATOR_ABI, WEIGHT_CHANGE_EXPIRY_SECONDS, WEIGHT_CHANGE_THRESHOLD, WEIGHT_CHANGE_TIMELOCK_SECONDS, WalletManager, type WebAuthnAssertion, type WebAuthnAuthenticationCredential, type WebAuthnCeremonyContext, type WeightConfig, WeightedSignatureService, YAAAServerClient, base64UrlDecode, base64UrlEncode, beginAuthenticationChallenge, beginGrantSessionChallenge, buildAuthenticationCredential, buildAuthenticatorData, buildClientDataJSON, buildFullInitConfig, buildInstallModuleHash, buildUninstallModuleHash, commitChallenge, computeOapdSalt, eip712Digest, erc8004AddressesForChain, gTokenAuthorizationDigest, getOapdAddress, getOapdAddressWithChainId, grantSessionFinalHash, initConfigFromRecord, initConfigToTuple, isExecuteUserOpWrapped, isOapdDeployed, isPendingConfirmation, micropaymentVoucherDigest, mintDigest, packP256SessionSignature, packSecp256k1SessionSignature, runAuthenticationCeremony, runGrantSessionCeremony, runWebAuthnCeremony, sepoliaV07Config, serializeGuardianSpecs, toGuardianSpecs, validateConfig, wrapExecuteUserOp, x402PaymentDigest };