@silencelaboratories/walletprovider-sdk 4.1.1 → 4.1.3

package/README.md

@@ -13,10 +13,11 @@ The client library for Silent Network Wallet Provider Service.
   - [Network Without Authentication](#network-without-authentication)
     - [Keygen](#keygen)
     - [Signgen](#signgen)
-  - [Network with Authentication](#network-with-authentication)
+  - [Network With Authentication](#network-with-authentication)
     - [Keygen](#keygen-1)
       - [Authenticate with EOA wallet](#authenticate-with-eoa-wallet)
       - [Authenticate with Passkey](#authenticate-with-passkey)
+    - [Policy](#policy)
     - [Signing](#signing)
     - [Key refresh](#key-refresh)
 - [Development](#development)
@@ -105,7 +106,7 @@ The example usage of different types is [shown here](https://github.com/silence-
   );
 ```
 
-## Network with Authentication
+## Network With Authentication
 ### Initialize the Client object
 Create the [WalletProviderServiceClient](./docs/classes/WalletProviderServiceClient.html), using [ClientConfig](./docs/types/ClientConfig.html). The `wpClient` will connect to the Wallet Provider Backend Service (WPBE).
 
@@ -137,80 +138,9 @@ We provide EOA authentication via [EOAAuth](./docs/classes/EOAAuth.html) module.
 
 ```
 
-Now you can generate a key, using the [generateKey](./docs/classes/NetworkSigner.html#generatekey) method. The method accepts optional Policy. No Policy means _allow all operations_.
+Now you can generate a key by calling the [generateKey](./docs/classes/NetworkSigner.html#generatekey) method. See [Policy](#policy) if you want to restrict what the generated key is allowed to sign.
 
-```ts
-const POLICY_ERC20_TRANSFER = new Policy({
-  version: '1.0',
-  description: 'Simple ERC20 transfer policy',
-  rules: [
-    new Rule({
-      description: 'ERC20 transferFrom: sender/recipient match and value < 10000',
-      chain_type: ChainType.Ethereum,
-      conditions: [
-        {
-          logic: Logic.And,
-          abi: {
-            name: 'transfer',
-            type: 'function',
-            inputs: [
-              {
-                name: 'to',
-                type: 'address',
-              },
-              {
-                name: 'amount',
-                type: 'uint256',
-              },
-            ],
-            outputs: [
-              {
-                name: '',
-                type: 'bool',
-              },
-            ],
-          },
-          group: [
-            {
-              transaction_type: TransactionType.Erc20,
-              transaction_attr: TransactionAttribute.Receiver,
-              operator: Operator.Eq,
-              value: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238',
-            },
-            {
-              transaction_type: TransactionType.Erc20,
-              transaction_attr: "to",
-              operator: Operator.Eq,
-              value: '0x1758f42af7026fbbb559dc60ece0de3ef81f665e',
-            },
-            {
-              transaction_type: TransactionType.Erc20,
-              transaction_attr: "amount",
-              operator: Operator.Lt,
-              value: 10000,
-            },
-          ],
-        },
-      ],
-    }),
-  ],
-});
-
-let signAlgs = ['secp256k1', 'ed25519'];
-
-// Generate new eph key, will be later used in sign requests
-const selectedEphSignAlg = 'secp256k1'; // Signing algorithm of Ephemeral Key
-const sk = generateEphPrivateKey(selectedEphSignAlg);
-const ephPK = getEphPublicKey(sk, selectedEphSignAlg);
-const ephId = uuidv4();
-
-const ephClaim = new EphKeyClaim(ephId, ephPK, selectedEphSignAlg, expireAt(60 * 60));
-
-// Generate keys for secp256k1, ed25519, and include Ephemeral Key, Policy in the request
-let resp: KeygenResponse[] = await sdk.generateKey(+threshold, +partiesNumber, signAlgs, ephClaim, POLICY_ERC20_TRANSFER);
-```
-
-Calling this method will cause to the Digital Wallet window to pop up, requesting the User to sign the request.
+Calling this method will cause the Digital Wallet window to pop up, requesting the User to sign the request.
 
 The returned response [KeygenResponse](./docs/interfaces/KeygenResponse.html) is a list of DKG results, each contains `keyId`, `publicKey` and `signAlg`. The `publicKey` is the public part of the key generated by Silent Network. The `signAlg` is the sign algorithm of the MPC key. Use the `keyId` in subsequent calls to sign.
 
@@ -272,6 +202,148 @@ Calling this method will prompt the device to request [Passkey User Verification
 
 The `sk` key can be later used in subsequent signgen requests.
 
+### Policy
+Use a [Policy](./docs/classes/Policy.html) when you want a key to sign only a constrained set of requests.
+
+Typical uses for policies:
+
+- Allow transfers only to specific recipients.
+- Cap the maximum amount for ERC-20, native-token, or SPL transfers.
+- Restrict signing to a specific contract function or chain.
+- Allow only specific EIP-191 messages or EIP-712 payloads.
+
+If you do not provide a policy, the key is created without signing restrictions.
+
+Policies are built from [Policy](./docs/classes/Policy.html), [Rule](./docs/classes/Rule.html), [ChainType](./docs/enums/ChainType.html), [TransactionType](./docs/enums/TransactionType.html), [TransactionAttribute](./docs/enums/TransactionAttribute.html), [Operator](./docs/enums/Operator.html), and optionally [Logic](./docs/enums/Logic.html).
+
+The structure is:
+
+- A `Policy` contains one or more ordered rules.
+- A `Rule` targets a chain and defines the conditions that must match.
+- A condition checks one transaction attribute, such as receiver, amount, chain ID, or message.
+- A condition group can share an ABI so the policy engine can decode calldata and validate function arguments such as `to` or `value`.
+
+Here is a common import set:
+
+```ts
+import {
+  Policy,
+  Rule,
+  ChainType,
+  Logic,
+  Operator,
+  TransactionType,
+  TransactionAttribute,
+} from '@silencelaboratories/walletprovider-sdk';
+```
+
+Example: allow only ERC-20 `transfer()` calls to a specific token contract, a specific recipient, and an amount below `10000`.
+
+```ts
+const erc20TransferPolicy = new Policy({
+  version: '1.0',
+  description: 'Simple ERC20 transfer policy',
+  rules: [
+    new Rule({
+      description: 'Allow transfer() to one recipient with value < 10000',
+      chain_type: ChainType.Ethereum,
+      conditions: [
+        {
+          logic: Logic.And,
+          abi: {
+            name: 'transfer',
+            type: 'function',
+            inputs: [
+              { name: 'to', type: 'address' },
+              { name: 'value', type: 'uint256' },
+            ],
+            outputs: [{ name: '', type: 'bool' }],
+          },
+          group: [
+            {
+              transaction_type: TransactionType.Erc20,
+              transaction_attr: TransactionAttribute.Receiver,
+              operator: Operator.Eq,
+              value: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238',
+            },
+            {
+              transaction_type: TransactionType.Erc20,
+              transaction_attr: 'to',
+              operator: Operator.Eq,
+              value: '0x1758f42af7026fbbb559dc60ece0de3ef81f665e',
+            },
+            {
+              transaction_type: TransactionType.Erc20,
+              transaction_attr: 'value',
+              operator: Operator.Lt,
+              value: 10000,
+            },
+          ],
+        },
+      ],
+    }),
+  ],
+});
+```
+
+Example: allow a Solana native transfer only to one recipient and only if the amount is at most `100`.
+
+```ts
+const solTransferPolicy = new Policy({
+  version: '1.0',
+  description: 'Solana transfer policy',
+  rules: [
+    new Rule({
+      description: 'Allow transfer to one address with value <= 100',
+      chain_type: ChainType.Solana,
+      conditions: [
+        {
+          transaction_type: TransactionType.NativeTransfer,
+          transaction_attr: TransactionAttribute.Receiver,
+          operator: Operator.Eq,
+          value: 'DGUiWE2kY5rEhPNrwCGygcyrWwLxJFrH7ApFep6A8rdF',
+        },
+        {
+          transaction_type: TransactionType.NativeTransfer,
+          transaction_attr: TransactionAttribute.NativeValue,
+          operator: Operator.Lte,
+          value: 100,
+        },
+      ],
+    }),
+  ],
+});
+```
+
+You can attach a policy during key generation:
+
+```ts
+const signAlgs = ['secp256k1', 'ed25519'];
+
+const selectedEphSignAlg = 'secp256k1';
+const sk = generateEphPrivateKey(selectedEphSignAlg);
+const ephPK = getEphPublicKey(sk, selectedEphSignAlg);
+const ephId = uuidv4();
+const ephClaim = new EphKeyClaim(ephId, ephPK, selectedEphSignAlg, expireAt(60 * 60));
+
+const resp: KeygenResponse[] = await sdk.generateKey(
+  +threshold,
+  +partiesNumber,
+  signAlgs,
+  ephClaim,
+  erc20TransferPolicy,
+);
+```
+
+You can also change or remove the policy later for an existing key:
+
+```ts
+await sdk.updatePolicy(selectedKeyId, solTransferPolicy);
+await sdk.deletePolicy(selectedKeyId);
+```
+
+In practice, a good pattern is to start with the smallest policy that supports your flow, test the exact transaction payloads your app produces, and only then broaden the rules if needed.
+
 ### Signing
 The full signing example is [here](https://github.com/silence-laboratories/walletprovider-sdk/blob/564cca4bb59658a6e477a59e8ea554a67c26b161/demo/src/routes/+page.svelte#L374).
 
@@ -372,4 +444,4 @@ npm run docs
 
 ```bash
 ./local_ci.sh
-```
+```

package/dist/auth/auth0JWTIssuer.d.ts

@@ -0,0 +1,63 @@
+import { Auth0Client } from '@auth0/auth0-spa-js';
+import { IJWTIssuer } from './JWTAuthentication';
+type Auth0TokenClient = Pick<Auth0Client, 'getTokenSilently' | 'getTokenWithPopup'> & Partial<Pick<Auth0Client, 'getUser' | 'isAuthenticated' | 'logout'>>;
+export type Auth0TokenCacheMode = 'on' | 'off' | 'cache-only';
+export type Auth0InteractiveTokenMode = 'silent' | 'popup' | 'silent-with-popup-fallback';
+/** Configuration for Auth0-backed JWT issuance in browser/WPFE flows.
+ * @public
+ */
+export type Auth0JWTIssuerConfig = {
+    /** Auth0 tenant domain, for example `dev-example.us.auth0.com`. */
+    domain: string;
+    /** Auth0 Single Page Application client ID. */
+    clientId: string;
+    /** Auth0 API identifier. This makes Auth0 return a JWT access token for MPCNode verification. */
+    audience: string;
+    /** OAuth scopes to request for the Silent Network API. */
+    scope?: string;
+    /** Redirect URI registered in Auth0. Defaults to `window.location.origin` in browsers. */
+    redirectUri?: string;
+    /** Auth0 cache mode for operation tokens. Defaults to `off` so every token is challenge-bound. */
+    cacheMode?: Auth0TokenCacheMode;
+    /** Token acquisition mode. Defaults to silent first, then popup if user interaction is required. */
+    interactiveMode?: Auth0InteractiveTokenMode;
+    /** Reuse an existing Auth0 client, useful for apps that already initialize Auth0 or for tests. */
+    auth0Client?: Auth0TokenClient;
+    /** Forwarded to Auth0 SPA SDK when this issuer creates the client. */
+    useRefreshTokens?: boolean;
+    /** Forwarded to Auth0 SPA SDK when this issuer creates the client. */
+    useRefreshTokensFallback?: boolean;
+};
+/** Auth0 implementation of `IJWTIssuer` for browser/WPFE social-login flows.
+ * @public
+ */
+export declare class Auth0JWTIssuer implements IJWTIssuer {
+    private readonly config;
+    private auth0Client;
+    private auth0ClientPromise;
+    constructor(config: Auth0JWTIssuerConfig);
+    /** Request a fresh Auth0 access token bound to the provided operation challenge. */
+    issueToken(challenge: string): Promise<string>;
+    /** Return whether Auth0 currently has an authenticated browser session.
+     * @public
+     */
+    isAuthenticated(): Promise<boolean>;
+    /** Return the Auth0 user profile for the current browser session.
+     * @public
+     */
+    getUser<TUser extends Record<string, unknown> = Record<string, unknown>>(): Promise<TUser | undefined>;
+    /** Log out the Auth0 browser session.
+     * @public
+     */
+    logout(options?: Parameters<Auth0Client['logout']>[0]): Promise<void>;
+    private validateInputs;
+    private getClient;
+    private buildClientOptions;
+    private getRedirectUri;
+    private buildAuthorizationParams;
+    private getToken;
+    private getTokenWithPopup;
+    private isInteractiveAuthError;
+    private validateTokenChallenge;
+}
+export {};

package/dist/builder/userAuth.d.ts

@@ -1,7 +1,6 @@
-import { AuthModule, AuthModuleParams, UserAuthentication } from '../auth/authentication';
-import { ApiVersion, RequestPayloadV1, RequestPayloadV2, Slug } from '../client/walletProviderServiceClientInterface';
-import { FinishPresignOpts, KeygenSetupOpts, SignSetupOpts } from '../setupMessage';
-import { AddEphKeyRequest, CreateStateControllerRequest, DeleteStateControllerRequest, KeyIdOfPolicy, KeyRefreshRequest, RegisterPasskeyRequest, RevokeEphKeyRequest, UpdatePolicyRequest } from '../client/networkRequest';
+import { AuthModule } from '../auth/authentication';
+import { ApiVersion, RequestPayloadV1, RequestPayloadV2, Slug, WpUserSignatures } from '../client/walletProviderServiceClientInterface';
+import { KeygenSetupOpts } from '../setupMessage';
 export type UserSignaturesOptionalParams = {
     challenge?: string | undefined;
 };
@@ -21,15 +20,5 @@ export declare class UserSignatures {
     setKeygenUserSigs(payload: KeygenSetupOpts[], challenges?: {
         [key: string]: string;
     }): Promise<void>;
-    setSigngenUserSigs(authParams: AuthModuleParams<SignSetupOpts>): Promise<void>;
-    setAddEphKeyUserSigs(authParams: AuthModuleParams<AddEphKeyRequest>): Promise<void>;
-    setRevokeEphKeyUserSigs(authParams: AuthModuleParams<RevokeEphKeyRequest>): Promise<void>;
-    setRegisterPasskeyUserSigs(authParams: AuthModuleParams<RegisterPasskeyRequest>): Promise<void>;
-    setKeyRefreshUserSigs(authParams: AuthModuleParams<KeyRefreshRequest>): Promise<void>;
-    setFinishPresignUserSigs(authParams: AuthModuleParams<FinishPresignOpts>): Promise<void>;
-    setUpdatePolicyUserSigs(authParams: AuthModuleParams<UpdatePolicyRequest>): Promise<void>;
-    setKeyIdOfPolicyUserSigs(authParams: AuthModuleParams<KeyIdOfPolicy>): Promise<void>;
-    setCreateStateControllerUserSigs(authParams: AuthModuleParams<CreateStateControllerRequest>): Promise<void>;
-    setDeleteStateControllerUserSigs(authParams: AuthModuleParams<DeleteStateControllerRequest>): Promise<void>;
-    build(slug: Slug, payload: RequestPayloadV1 | RequestPayloadV2, options?: UserSignaturesOptionalParams): Promise<Record<string, UserAuthentication>>;
+    build(slug: Slug, payload: RequestPayloadV1 | RequestPayloadV2, options?: UserSignaturesOptionalParams): Promise<WpUserSignatures>;
 }

package/dist/client/networkRequest.d.ts

@@ -140,3 +140,31 @@ export declare class DeleteStateControllerRequest implements EoaAuthPayload {
         }[];
     };
 }
+export declare class DryRunPolicyRequest implements EoaAuthPayload {
+    readonly key_id: string;
+    readonly message: string;
+    readonly signAlg: string;
+    readonly policy: string;
+    readonly state_controllers: string;
+    readonly initial_state_entries: string;
+    readonly evaluation_count: number;
+    constructor({ keyId, message, signAlg, policy, stateControllers, initialStateEntries, evaluationCount, }: {
+        keyId: string;
+        message: string;
+        signAlg: string;
+        policy: Policy | '';
+        stateControllers: string;
+        initialStateEntries: string;
+        evaluationCount?: number;
+    });
+    get eoaRequestSchema(): {
+        Request: {
+            name: string;
+            type: string;
+        }[];
+        DryRunPolicyRequest: {
+            name: string;
+            type: string;
+        }[];
+    };
+}

package/dist/client/networkResponse.d.ts

@@ -1,4 +1,4 @@
-import { StateControllerPartitionField, StateControllerWindowConfig } from '../policy';
+import { Action, PolicyStateController } from '../policy';
 /**
  * Response from the SDK for keygen. Receive plaintext response from network.
  * @public
@@ -101,14 +101,7 @@ export interface StateEntryResponse {
  * Response from the network for getting policy state controller request.
  * @public
  */
-export interface StateControllerResponse {
-    id: string;
-    key_id: string;
-    description: string;
-    method: string;
-    window_config: StateControllerWindowConfig;
-    partition_by: StateControllerPartitionField[];
-    referenced_by: string | null;
+export interface StateControllerResponse extends PolicyStateController {
     entries: StateEntryResponse[];
 }
 /**
@@ -125,4 +118,31 @@ export interface GetStateControllersResponse {
 export interface DeleteStateControllerResponse {
     status: string;
 }
+/**
+ * Response from the network for dry-run policy state entry changes.
+ * @public
+ */
+export interface DryRunPolicyStateEntry {
+    controller_id: string;
+    partition_key: number[];
+    window_start: string;
+    value: string;
+    base_version?: number | null;
+}
+/**
+ * Response from the network for dry-run policy request.
+ * @public
+ */
+export interface DryRunPolicyResponse {
+    policy_valid: boolean;
+    stateful: boolean;
+    evaluation_count: number;
+    results: {
+        evaluation_index: number;
+        evaluated_at?: string;
+        action: Action;
+        reasons?: string[];
+        state_changes?: DryRunPolicyStateEntry[];
+    }[];
+}
 export {};

package/dist/client/networkSigner.d.ts

@@ -7,7 +7,7 @@ import { Policy } from '../policy';
  * Supported signature algorithms for MPC signing.
  * @public
  */
-export type MPCSignAlgorithm = 'ed25519' | 'secp256k1';
+export type MPCSignAlgorithm = 'ed25519' | 'secp256k1' | 'mldsa44' | 'mldsa65' | 'mldsa87';
 /** The networkSigner contains an API to communicate with the Silent MPC Network. Call to sign and keygen require
  * the Auth module, that is used to prompt the User before executing the request.
  * @public

package/dist/client/walletProviderServiceClientInterface.d.ts

@@ -1,7 +1,7 @@
 import { AuthModule, UserAuthentication } from '../auth/authentication';
 import { KeygenResponse, SignResponse, AddEphKeyResponse, RegisterPasskeyResponse, RevokeEphKeyResponse, KeyRefreshResponse, UpdatePolicyResponse, DeletePolicyResponse } from './networkResponse';
 import { KeygenSetupOpts, SignSetupOpts, InitPresignOpts, FinishPresignOpts } from '../setupMessage';
-import { AddEphKeyRequest, CreateStateControllerRequest, KeyIdOfPolicy, DeleteStateControllerRequest, KeyRefreshRequest, RegisterPasskeyRequest, RevokeEphKeyRequest, UpdatePolicyRequest } from './networkRequest';
+import { AddEphKeyRequest, CreateStateControllerRequest, KeyIdOfPolicy, DeleteStateControllerRequest, KeyRefreshRequest, RegisterPasskeyRequest, RevokeEphKeyRequest, UpdatePolicyRequest, DryRunPolicyRequest } from './networkRequest';
 /**
  * The config used to create Wallet Provider Service backend client.
  * Please refer to {@link https://shipyard.rs/silencelaboratories/crates/wallet-provider-service | example backend service}
@@ -24,7 +24,10 @@ export type ClientConfig = {
  * @public
  */
 export type ApiVersion = 'v1' | 'v2';
-export type Signer = (challenge: string) => Promise<UserAuthentication>;
+export type WpChallengeMessage = string;
+export type WpResultMessage = string;
+export type WpUserSignatures = Record<string, UserAuthentication>;
+export type Signer = (challenge: WpChallengeMessage) => Promise<UserAuthentication>;
 /** Interface for client of  Wallet Provider Service
  * @public
  */
@@ -63,12 +66,13 @@ export interface IWalletProviderServiceClient {
         authModule: AuthModule;
     }): Promise<DeletePolicyResponse>;
 }
-export type Slug = 'signgen' | 'keygen' | 'keyRefresh' | 'quorumChange' | 'addEphemeralKey' | 'revokeEphemeralKey' | 'registerPasskey' | 'initPresign' | 'finishPresign' | 'updatePolicy' | 'deletePolicy' | 'getStateControllers' | 'createStateController' | 'deleteStateController';
+export type Slug = 'signgen' | 'keygen' | 'keyRefresh' | 'quorumChange' | 'addEphemeralKey' | 'revokeEphemeralKey' | 'registerPasskey' | 'initPresign' | 'finishPresign' | 'updatePolicy' | 'deletePolicy' | 'getStateControllers' | 'createStateController' | 'deleteStateController' | 'dryRunPolicy';
 export type RequestPayloadV1 = KeygenSetupOpts[] | KeyRefreshRequest | SignSetupOpts | AddEphKeyRequest | RevokeEphKeyRequest | RegisterPasskeyRequest | UpdatePolicyRequest | KeyIdOfPolicy | FinishPresignOpts;
-export type RequestPayloadV2 = KeygenSetupOpts[] | SignSetupOpts | AddEphKeyRequest | RevokeEphKeyRequest | InitPresignOpts | FinishPresignOpts | UpdatePolicyRequest | KeyIdOfPolicy | CreateStateControllerRequest | DeleteStateControllerRequest;
+export type RequestPayloadV2 = KeygenSetupOpts[] | SignSetupOpts | AddEphKeyRequest | RevokeEphKeyRequest | InitPresignOpts | FinishPresignOpts | UpdatePolicyRequest | KeyIdOfPolicy | CreateStateControllerRequest | DeleteStateControllerRequest | DryRunPolicyRequest;
+export type WpPayload = RequestPayloadV1 | RequestPayloadV2;
 export interface WpRequest {
-    payload: RequestPayloadV1 | RequestPayloadV2;
-    userSigs: Record<string, UserAuthentication> | undefined;
+    payload: WpPayload;
+    userSigs: WpUserSignatures | undefined;
 }
 /** Interface for client of  Wallet Provider Service
  * @public