feat: adds wallet authentication to sign DK

docs/specs/clients/sign/README.md

@@ -1,16 +1,16 @@
 # Sign API Overview
 
-## Description
+### Description
 
 Sign API establishes a session between a dapp and a wallet in order to expose a set of blockchain accounts that can sign transactions and/or messages using a secure remote JSON-RPC transport with methods and events.
 
-## Context
+### Context
 
 In v1.0 the session and pairing were coupled which meant that a URI was shared to retrieve the session proposal and it established the pairing simultaneously. However that also meant that a new session would require establishing a pairing again.
 
 In v2.0 the session and pairing are decoupled which means that a URI is shared to construct a pairing proposal and only after settling the pairing then the dapp can propose a session using that pairing.
 
-### Problem
+#### Problem
 
 Given the new pattern with v2.0 protocol we have a far more interactive protocol that negotiates the pairing exclusively for session proposal transmission. This is very useful because a pairing can be proposed independently from the session and they exist in parallel.
 
@@ -20,6 +20,28 @@ This swipe puts the dapp (usually in a browser window) on the background which m
 
 Thus if the dapp never receives the pairing response that means it also will never publish the session proposal meaning that the wallet is redirected with the URI but won’t prompt the user for approval.
 
-### Goal
+#### Goal
 
 The solution is to find a protocol change that inherits the same capability of v1.0 to propose session and pairing simultaneously but also persists the decoupled property of v2.0 protocol
+
+## Wallet Authentication Overview
+
+### Description
+
+Sign API provides a simple and lean interface to enable applications to authenticate wallet users to login/signin into applications with their wallets by automatically signing an authentication message.
+
+### Context
+
+Sign API's wallet authentication would be used for wallet users to login in a single step into existing websites or applications that would normally require an email and password login or a social login such as Facebook, Google, etc
+
+Sign API's wallet authentication is a one-click passwordless authentication provider for any website or application.
+
+### Goals
+
+A user can login or sign-in into any website or application with their blockchain account.
+
+An app does not need to maintain a persisted connection with the wallet once authenticated.
+
+A wallet can evaluate all auth parameters requested to format the message independently.
+
+An authentication message can be used to access resources through OAuth 2.0 or OpenID.

docs/specs/clients/sign/client-api.md

@@ -9,7 +9,7 @@ abstract class Client {
     metadata?: AppMetadata;
   }): Promise<void>;
 
-  // for proposer to create a session 
+  // for proposer to create a session
   public abstract connect(params: {
     requiredNamespaces: Map<string, ProposalNamespace>;
     relays?: RelayProtocolOptions[];
@@ -74,6 +74,24 @@ abstract class Client {
     reason: Reason;
   }): Promise<void>;
 
+  // ---------- Wallet Authentication Methods ----------------------------------------------- //
+
+  // for proposer to create an authenticated pairing
+  public abstract authenticate(params: {
+    chains:[],
+    pairingTopic?: string;
+  }): Promise<{ uri: string }>;
+
+
+   // respond to wallet authentication request
+  public abstract respondSessionAuthenticated(params: RespondParams, iss: string): Promise<boolean>;
+
+  // query all pending authentication requests
+  public abstract getPendingAuthRequests(): Promise<Record<number, PendingRequest>>;
+
+  // format payload to message string
+  public abstract formatAuthMessage(payload: PayloadParams, iss: string): Promise<string>;
+
 
   // ---------- Events ----------------------------------------------- //
 
@@ -88,5 +106,13 @@ abstract class Client {
 
   // subscribe to session delete
   public abstract on("session_delete", (sessionDelete: { id: number, topic: string }) => {}): void;
+
+  // ---------- Wallet Authentication Events ----------------------------------------------- //
+
+  // wallets to subscribe to session authenticated
+  public abstract on("session_authenticated", (sessionAuthenticated: SessionAuthenticated) => {}): void;
+
+  // apps to subscribe to session authenticated response
+  public abstract on("session_authenticated_response", (response: Response) => {}): void;
 }
 ```

docs/specs/clients/sign/data-structures.md

@@ -1,8 +1,10 @@
 # Data Structures
 
+## Sign Data Structures
+
 In this document we define data structures and definitions used in the v2.0-rc protocol
 
-## Relay
+### Relay
 
 Relay is defined by the transport protocol used for the two clients to publish and subscribe messages between each other.
 
@@ -13,7 +15,7 @@ Relay is defined by the transport protocol used for the two clients to publish a
 }
 ```
 
-## Session
+### Session
 
 Session is a topic encrypted by a symmetric key derived using a key agreement established after an approved proposal and it has a controller participant that can update its accounts, methods, events and expiry.
 
@@ -61,7 +63,7 @@ Session is a topic encrypted by a symmetric key derived using a key agreement es
 }
 ```
 
-## Proposal
+### Proposal
 
 Proposal is sent by the proposer client to be approved or rejected by the responder who is assumed to be the controller of the resulting session and will respond with its public key to derive the future topic and symKey.
 
@@ -89,7 +91,7 @@ Proposal is sent by the proposer client to be approved or rejected by the respon
 }
 ```
 
-## Response
+### Response
 
 Response is sent by the responder client and can either be an approval or rejection to the proposal made and if approved will be followed by a settlement request on the new topic derived from the hashed symmetric key from the key agreement
 
@@ -113,7 +115,7 @@ Response is sent by the responder client and can either be an approval or reject
 }
 ```
 
-## Settlement
+### Settlement
 
 Settlement is sent by the responder after approval and it's broadcasted right after the response on the new topic derived from the hashed symmetric key from the key agreement
 
@@ -161,7 +163,7 @@ Settlement is sent by the responder after approval and it's broadcasted right af
 }
 ```
 
-## Verify Context
+### Verify Context
 
 Verify Context is appended to Session Proposals and Session Requests to provide metadata that was constructed internally by the client that is relevant to the specific proposal or request
 
@@ -175,8 +177,10 @@ Verify Context is appended to Session Proposals and Session Requests to provide
 }
 ```
 
-## Namespace Config
+### Namespace Config
+
 Namespace Config is set within the setNamespaceConfig method that is a part of the Sign client. It defines Special and Supported Namespaces and must be called after initialization of the SDK and before approve session method.
+
 ```jsonc
 {
    "supportedNamespaces": {
@@ -195,3 +199,134 @@ Namespace Config is set within the setNamespaceConfig method that is a part of t
   }
 }
 ```
+
+## Wallet Authentication Data Structures
+
+### Request Params
+
+```typescript
+interface RequestParams {
+  chains: string[];
+  domain: string;
+  aud: string;
+  nonce: string;
+  type?: string;
+  nbf?: string;
+  exp?: string;
+  statement?: string;
+  requestId?: string;
+  resources?: string[];
+  pairingTopic;
+}
+```
+
+### Respond Params
+
+```typescript
+type RespondParams = ResultResponse | ErrorResponse;
+```
+
+### Payload Params (partial Cacao)
+
+Used for requester to authenticate wallet
+
+```typescript
+interface PayloadParams {
+  type: string; // same as Cacao Header type (t)
+  chains: string[];
+  domain: string;
+  aud: string;
+  version: string;
+  nonce: string;
+  iat: string;
+  nbf?: string;
+  exp?: string;
+  statement?: string;
+  requestId?: string;
+  resources?: string[];
+}
+```
+
+### Response
+
+```typescript
+type Response = Cacao | ErrorResponse;
+```
+
+### Pending Request
+
+```typescript
+interface PendingRequest {
+  id: number;
+  pairingTopic: String;
+  payloadParams: PayloadParams;
+}
+```
+
+### Cacao Header ([CAIP-74](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-74.md))
+
+```typescript
+interface CacaoHeader {
+  t: string;
+}
+```
+
+### Cacao Payload ([CAIP-74](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-74.md))
+
+```typescript
+interface CacaoPayload {
+  iss: string;
+  domain: string;
+  aud: string;
+  version: string;
+  nonce: string;
+  iat: string;
+  nbf?: string;
+  exp?: string;
+  statement?: string;
+  requestId?: string;
+  resources?: string[];
+}
+```
+
+### Cacao Signature ([CAIP-74](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-74.md))
+
+```typescript
+interface CacaoSignature {
+  t: string;
+  s: string;
+  m?: string;
+}
+```
+
+### Cacao ([CAIP-74](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-74.md))
+
+```typescript
+interface Cacao {
+  h: CacaoHeader;
+  p: CacaoPayload;
+  s: CacaoSignature;
+}
+```
+
+### Result Response
+
+```typescript
+// signatures is an array of signed CACAOs for each requested chain
+interface ResultResponse {
+  id: number;
+  signatures: CacaoSignature[];
+}
+```
+
+### Error Response
+
+```typescript
+interface ErrorResponse {
+  id: number;
+  error: {
+    code: number;
+    message: string;
+  };
+}
+```

docs/specs/clients/sign/error-codes.md

@@ -1,6 +1,6 @@
 # Error Codes
 
-## INVALID
+### INVALID
 
 ```sh
 case .invalidMethod: return 1001
@@ -10,7 +10,7 @@ case .invalidExtendRequest: return 1004
 case .invalidSessionSettleRequest: return 1005
 ```
 
-## UNAUTHORIZED
+### UNAUTHORIZED
 
 ```sh
 case .unauthorizedMethod: return 3001
@@ -20,13 +20,13 @@ case .unauthorizedExtendRequest: return 3004
 case .unauthorizedChain: return 3005
 ```
 
-## EIP-1193
+### EIP-1193
 
 ```sh
 case .userRejectedRequest return 4001
 ```
 
-## REJECTED (CAIP-25)
+### REJECTED (CAIP-25)
 
 ```sh
 case .userRejected return 5000
@@ -41,21 +41,41 @@ case .unsupportedAccounts: return 5103
 case .unsupportedNamespaceKey: return 5104
 ```
 
-## REASON
+### REASON
 
 ```sh
 case .userDisconnected: return 6000
 ```
 
-## FAILURE
+### FAILURE
 
 ```sh
 case .sessionSettlementFailed: return 7000
 case .noSessionForTopic: return 7001
 ```
 
-## SESSION REQUEST
+### SESSION REQUEST
 
 ```sh
 case .sessionRequestExpired: return 8000
 ```
+
+## Wallet Authentication Error Codes
+
+### VALIDATION
+
+```sh
+case .malformedResponseParams return 11001
+case .malformedRequestParams return 11002
+case .messageCompromised return 11003
+case .signatureVerificationFailed return 11004
+case .requestExpired: return 11005
+case .missingIssuer return 11006
+```
+
+### REJECTED
+
+```sh
+case .userRejectedRequest return 12001
+case .userDisconnected: return 12002
+```