Init auth a session guide

Author: spacesailor24

hacker-guides/_getting-started/README.md

@@ -3,7 +3,10 @@
 
 The Lit SDK is a set of libraries that enable various functionalities of the Lit Protocol. Each package is available on npm, and can be installed with your preferred JavaScript package manager.
 
-- [Documentation](#documentation)
+<!-- omit in toc -->
+## Table of Contents
+
+- [Lit Documentation](#lit-documentation)
 - [Core Terminology](#core-terminology)
   - [Lit Node Client](#lit-node-client)
   - [Lit Network](#lit-network)
@@ -20,7 +23,7 @@ The Lit SDK is a set of libraries that enable various functionalities of the Lit
 - [Next Steps](#next-steps)
 
 
-## Documentation
+## Lit Documentation
 
 - [Lit Documentation](https://developer.litprotocol.com)
   - This is the main source of information for the Lit Protocol. It contains guides, reference documentation, and other resources for developers.

hacker-guides/_getting-started/authenticating-a-session/.env.example

@@ -0,0 +1 @@
+ETHEREUM_PRIVATE_KEY=

hacker-guides/_getting-started/authenticating-a-session/.mocharc.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json.schemastore.org/mocharc.json",
+  "require": "tsx"
+}

hacker-guides/_getting-started/authenticating-a-session/README.md

@@ -0,0 +1,125 @@
+<!-- omit in toc -->
+# Authenticating a Session with Lit
+
+In order to use your [Lit Resources and their corresponding abilities](../README.md#lit-resources-and-abilities), you need to authenticate yourself with the Lit Network. After your identity has been authenticated, the Lit nodes can then verify whether you have the necessary permissions to access a given Lit Resource and its associated abilities when you make requests to the Lit Network (such as decrypting data, signing transactions with a PKP, or executing a Lit Action).
+
+As covered [here](../README.md#session-signatures) in the Getting Started `README`, Sessions are the means by which you authenticate with the Lit Network to interact with Lit Resources securely without repeatedly signing transactions with your wallet. This guide will walk you through the process of authenticating a session, which involves:
+
+1. Generating a Session Key Pair
+2. Creating an Authentication Signature to authorize your Session Key to use Lit Resources you have access to
+3. Requesting the Lit network to generate Session Signatures for your Session, authorizing it to perform actions with the specified Lit Resources
+
+<!-- omit in toc -->
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Running the Code Example](#running-the-code-example)
+  - [Requirements](#requirements)
+  - [Steps](#steps)
+  - [Expected Output](#expected-output)
+- [Understanding the Code](#understanding-the-code)
+  - [Creating an Ethers Signer](#creating-an-ethers-signer)
+  - [Requesting Session Signatures](#requesting-session-signatures)
+
+
+## Prerequisites
+
+- Understanding of Lit core terminology and concepts covered [here](../README.md#core-terminology)
+- Understanding of the [Connecting to the Lit Network](../connecting-to-lit/README.md) guide
+
+## Running the Code Example
+
+### Requirements
+
+- [Node.js](https://nodejs.org/en)
+- [Yarn](https://yarnpkg.com/getting-started)
+- `@lit-protocol/constants`
+- `@lit-protocol/lit-node-client`
+- `@lit-protocol/auth-helpers`
+
+### Steps
+
+1. `yarn` to install the dependencies
+2. `yarn test` to run the code example
+
+### Expected Output
+
+After running the code example, you should see output in your terminal indicating that a connection to the Lit Network was successfully established, and that session signatures were successfully generated for the requested session:
+
+```bash
+[Lit-JS-SDK v6.11.0] [2024-11-15T05:58:06.815Z] [DEBUG] [core] signatures: {
+  'https://15.235.83.220:7470': {
+    sig: 'cadda38603f3cc62b83f043ede4fd758a9aee7363aa8c0b510658aa43d0e955942e63629029117f89973999956c4d2c20f666cc7af124661ebaeb1d4cf7bc00f',
+    derivedVia: 'litSessionSignViaNacl',
+    signedMessage: `{"sessionKey":"963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5","resourceAbilityRequests":[{"resource":{"resource":"*","resourcePrefix":"lit-accesscontrolcondition"},"ability":"access-control-condition-decryption"}],"capabilities":[{"sig":"0x3a18598d9dbcb4c3f588d3948803f34397790f6b3ea1620913e353a002fb5526032aad72400635419346ca91a9bcfcd36cbdfc5b0f5080ecc48ded6ccfe6da7b1b","derivedVia":"web3.eth.personal.sign","signedMessage":"localhost wants you to sign in with your Ethereum account:\\n0xA89543a7145C68E52a4D584f1ceb123605131211\\n\\nThis is a test statement.  You can put anything you want here. I further authorize the stated URI to perform the following actions on my behalf: (1) 'Threshold': 'Decryption' for 'lit-accesscontrolcondition://*'.\\n\\nURI: lit:session:963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5\\nVersion: 1\\nChain ID: 1\\nNonce: 0x23f22526f00d01dc505e291881a44a8c74664f76cdaa2662b8af1ae54c9b4725\\nIssued At: 2024-11-15T05:58:06.757Z\\nExpiration Time: 2024-11-15T06:08:06.728Z\\nResources:\\n- urn:recap:eyJhdHQiOnsibGl0LWFjY2Vzc2NvbnRyb2xjb25kaXRpb246Ly8qIjp7IlRocmVzaG9sZC9EZWNyeXB0aW9uIjpbe31dfX0sInByZiI6W119","address":"0xA89543a7145C68E52a4D584f1ceb123605131211"}],"issuedAt":"2024-11-15T05:58:06.778Z","expiration":"2024-11-15T06:08:06.728Z","nodeAddress":"https://15.235.83.220:7470"}`,
+    address: '963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5',
+    algo: 'ed25519'
+  },
+  'https://15.235.83.220:7472': {
+    sig: 'fccb3a82b02f1f3c9ba66fc8b3a61b0404875baf95449c76727529970105b3d96a2de9869a6cefd7c510ee8ecc55d7345e2b469f30ae59511579c703d2ab3a0c',
+    derivedVia: 'litSessionSignViaNacl',
+    signedMessage: `{"sessionKey":"963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5","resourceAbilityRequests":[{"resource":{"resource":"*","resourcePrefix":"lit-accesscontrolcondition"},"ability":"access-control-condition-decryption"}],"capabilities":[{"sig":"0x3a18598d9dbcb4c3f588d3948803f34397790f6b3ea1620913e353a002fb5526032aad72400635419346ca91a9bcfcd36cbdfc5b0f5080ecc48ded6ccfe6da7b1b","derivedVia":"web3.eth.personal.sign","signedMessage":"localhost wants you to sign in with your Ethereum account:\\n0xA89543a7145C68E52a4D584f1ceb123605131211\\n\\nThis is a test statement.  You can put anything you want here. I further authorize the stated URI to perform the following actions on my behalf: (1) 'Threshold': 'Decryption' for 'lit-accesscontrolcondition://*'.\\n\\nURI: lit:session:963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5\\nVersion: 1\\nChain ID: 1\\nNonce: 0x23f22526f00d01dc505e291881a44a8c74664f76cdaa2662b8af1ae54c9b4725\\nIssued At: 2024-11-15T05:58:06.757Z\\nExpiration Time: 2024-11-15T06:08:06.728Z\\nResources:\\n- urn:recap:eyJhdHQiOnsibGl0LWFjY2Vzc2NvbnRyb2xjb25kaXRpb246Ly8qIjp7IlRocmVzaG9sZC9EZWNyeXB0aW9uIjpbe31dfX0sInByZiI6W119","address":"0xA89543a7145C68E52a4D584f1ceb123605131211"}],"issuedAt":"2024-11-15T05:58:06.778Z","expiration":"2024-11-15T06:08:06.728Z","nodeAddress":"https://15.235.83.220:7472"}`,
+    address: '963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5',
+    algo: 'ed25519'
+  },
+  'https://15.235.83.220:7471': {
+    sig: 'b1e0d8fd8d09c3392b540126418ee9a8d8dbbabdd4d0c368832d612b1f51dadcd5f02bf5ca19dbd0251a3986ad5ddb514fc1f7e1753f8a6a979adf45fbbbd901',
+    derivedVia: 'litSessionSignViaNacl',
+    signedMessage: `{"sessionKey":"963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5","resourceAbilityRequests":[{"resource":{"resource":"*","resourcePrefix":"lit-accesscontrolcondition"},"ability":"access-control-condition-decryption"}],"capabilities":[{"sig":"0x3a18598d9dbcb4c3f588d3948803f34397790f6b3ea1620913e353a002fb5526032aad72400635419346ca91a9bcfcd36cbdfc5b0f5080ecc48ded6ccfe6da7b1b","derivedVia":"web3.eth.personal.sign","signedMessage":"localhost wants you to sign in with your Ethereum account:\\n0xA89543a7145C68E52a4D584f1ceb123605131211\\n\\nThis is a test statement.  You can put anything you want here. I further authorize the stated URI to perform the following actions on my behalf: (1) 'Threshold': 'Decryption' for 'lit-accesscontrolcondition://*'.\\n\\nURI: lit:session:963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5\\nVersion: 1\\nChain ID: 1\\nNonce: 0x23f22526f00d01dc505e291881a44a8c74664f76cdaa2662b8af1ae54c9b4725\\nIssued At: 2024-11-15T05:58:06.757Z\\nExpiration Time: 2024-11-15T06:08:06.728Z\\nResources:\\n- urn:recap:eyJhdHQiOnsibGl0LWFjY2Vzc2NvbnRyb2xjb25kaXRpb246Ly8qIjp7IlRocmVzaG9sZC9EZWNyeXB0aW9uIjpbe31dfX0sInByZiI6W119","address":"0xA89543a7145C68E52a4D584f1ceb123605131211"}],"issuedAt":"2024-11-15T05:58:06.778Z","expiration":"2024-11-15T06:08:06.728Z","nodeAddress":"https://15.235.83.220:7471"}`,
+    address: '963d6551d36a8b5be53d8959d45141764dbfd3c00649f56bc00433ef09db75f5',
+    algo: 'ed25519'
+  }
+}
+[Lit-JS-SDK v6.11.0] [2024-11-15T05:58:06.816Z] [DEBUG] [core] The request time is at: 2024-11-15T05:58:06.816Z
+* Outer expiration:
+    * Issued at: 2024-11-15T05:58:06.778Z
+    * Expiration: 2024-11-15T06:08:06.728Z
+    * Duration: 9 minutes, 59.950 seconds
+    * Status: ✅ Not expired (valid for 9 minutes, 59.912 seconds)
+* Capabilities:
+    * Capability 1 (web3.eth.personal.sign):
+        * Issued at: 2024-11-15T05:58:06.757Z
+        * Expiration: 2024-11-15T06:08:06.728Z
+        * Duration: 9 minutes, 59.971 seconds
+        * Status: ✅ Not expired (valid for 9 minutes, 59.912 seconds)
+        * Attenuation:
+            * lit-accesscontrolcondition://*
+              * Threshold/Decryption
+```
+
+## Understanding the Code
+
+The following code from [./src/index.ts](./src/index.ts) does the following:
+
+### Creating an Ethers Signer
+
+```typescript
+const ethersSigner = new ethers.Wallet(
+  ETHEREUM_PRIVATE_KEY,
+  new ethers.providers.JsonRpcProvider(LIT_RPC.CHRONICLE_YELLOWSTONE)
+);
+```
+
+The wallet that corresponds to `ETHEREUM_PRIVATE_KEY` would be your dev wallet that has permission to decrypt some data, sign with a PKP that it controls, or would be paying for the execution of a Lit Action (payment is not required for the Lit DatilDev network, so you don't need to worry about it for the hackathon).
+
+As we'll cover further below, the `ethersSigner` is used to generate an Authentication Signature which is a [ERC-5573](https://eips.ethereum.org/EIPS/eip-5573) message that specifies what Lit Resources and corresponding abilities the Session will be authorized to use.
+
+### Requesting Session Signatures
+
+After connecting an instance of `LitNodeClient` to the Lit Network, the code calls the `getSessionSigs` method to request the Lit network to generate session signatures for the session.
+
+This method takes in an object with the following properties:
+
+- **chain**: Corresponds to the signature schema and message format you're requesting the session to be authenticated with. This should almost always be `ethereum`.
+- **expiration**: The date and time at which the session will no longer be valid.
+  - It's recommended that you set this value to be as soon as possible, to minimize the amount of time that the session is valid for in case it gets compromised.
+- **resourceAbilityRequests**: An array of objects that specify the Lit Resources and abilities you're requesting the session to be authorized to use.
+- **authNeededCallback**: A function that you implement that generates an Authentication Signature for the session.
+
+As a result of executing `getSessionSigs`, the Lit SDK will generate the ephemeral session key pair, execute the `authNeededCallback` function to generate an Authentication Signature, and submit the request to the Lit Network to generate session signatures.
+
+Upon receiving the request, each Lit node in the network will independently authenticate the Authentication Signature, deriving the corresponding Ethereum address, and use that address to check if it has the authority to delegate the specified Lit Resources and abilities to the session.
+
+If a node determines that the Authentication Signature is valid and authorized to delegate the `resourceAbilityRequests` to the session, it will generate a Session Signature indicating that the session is authenticated and authorized to use the specified Lit Resources and abilities.
+
+After a threshold of nodes have generated Session Signatures, the Lit Network will send the Session Signatures back to your client. You will then use these Session Signatures to interact with the Lit Network, as we'll cover in other code examples in this guide.

hacker-guides/_getting-started/authenticating-a-session/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "nodejs",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "test": "npx @dotenvx/dotenvx run -- mocha test/**/*.spec.ts"
+  },
+  "dependencies": {
+    "@dotenvx/dotenvx": "^0.44.1",
+    "@lit-protocol/auth-helpers": "^6.11.0",
+    "@lit-protocol/constants": "^6.11.0",
+    "@lit-protocol/lit-node-client": "^6.11.0",
+    "ethers": "v5"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.16",
+    "@types/chai-json-schema": "^1.4.10",
+    "@types/mocha": "^10.0.6",
+    "chai": "^5.1.1",
+    "chai-json-schema": "^1.5.1",
+    "mocha": "^10.4.0",
+    "tsc": "^2.0.4",
+    "tsx": "^4.12.0",
+    "typescript": "^5.4.5"
+  }
+}

hacker-guides/_getting-started/authenticating-a-session/src/index.ts

@@ -0,0 +1,66 @@
+import { LitNodeClient } from "@lit-protocol/lit-node-client";
+import { LIT_RPC, LitNetwork } from "@lit-protocol/constants";
+import {
+  createSiweMessage,
+  generateAuthSig,
+  LitAbility,
+  LitAccessControlConditionResource,
+} from "@lit-protocol/auth-helpers";
+import { ethers } from "ethers";
+
+import { getEnv } from "./utils";
+
+const ETHEREUM_PRIVATE_KEY = getEnv("ETHEREUM_PRIVATE_KEY");
+
+export const runExample = async () => {
+  let litNodeClient: LitNodeClient;
+
+  try {
+    const ethersSigner = new ethers.Wallet(
+      ETHEREUM_PRIVATE_KEY,
+      new ethers.providers.JsonRpcProvider(LIT_RPC.CHRONICLE_YELLOWSTONE)
+    );
+
+    litNodeClient = new LitNodeClient({
+      litNetwork: LitNetwork.DatilDev,
+      debug: true,
+    });
+    await litNodeClient.connect();
+
+    const sessionSignatures = await litNodeClient.getSessionSigs({
+      chain: "ethereum",
+      expiration: new Date(Date.now() + 1000 * 60 * 10).toISOString(), // 10 minutes
+      resourceAbilityRequests: [
+        {
+          resource: new LitAccessControlConditionResource("*"),
+          ability: LitAbility.AccessControlConditionDecryption,
+        },
+      ],
+      authNeededCallback: async ({
+        uri,
+        expiration,
+        resourceAbilityRequests,
+      }) => {
+        const toSign = await createSiweMessage({
+          uri,
+          expiration,
+          resources: resourceAbilityRequests,
+          walletAddress: await ethersSigner.getAddress(),
+          nonce: await litNodeClient.getLatestBlockhash(),
+          litNodeClient,
+        });
+
+        return await generateAuthSig({
+          signer: ethersSigner,
+          toSign,
+        });
+      },
+    });
+
+    return sessionSignatures;
+  } catch (error) {
+    console.error(error);
+  } finally {
+    litNodeClient!.disconnect();
+  }
+};

hacker-guides/_getting-started/authenticating-a-session/src/utils.ts

@@ -0,0 +1,8 @@
+export const getEnv = (name: string): string => {
+  const env = process.env[name];
+  if (env === undefined || env === "")
+    throw new Error(
+      `${name} ENV is not defined, please define it in the .env file`
+    );
+  return env;
+};

hacker-guides/_getting-started/authenticating-a-session/test/index.spec.ts

@@ -0,0 +1,31 @@
+import { expect, use } from "chai";
+import chaiJsonSchema from "chai-json-schema";
+
+import { runExample } from "../src";
+
+use(chaiJsonSchema);
+
+describe("getSessionSigsViaAuthSig", () => {
+  const sessionSigResponseSchema = {
+    type: "object",
+    patternProperties: {
+      "^https://\\d+\\.\\d+\\.\\d+\\.\\d+:\\d+$": {
+        type: "object",
+        properties: {
+          sig: { type: "string" },
+          derivedVia: { type: "string" },
+          signedMessage: { type: "string" },
+          address: { type: "string" },
+          algo: { type: "string" },
+        },
+        required: ["sig", "derivedVia", "signedMessage", "address", "algo"],
+      },
+    },
+    additionalProperties: false,
+  };
+
+  it("Attempting to get session signatures...", async () => {
+    const sessionSignatures = await runExample();
+    expect(sessionSignatures).to.be.jsonSchema(sessionSigResponseSchema);
+  }).timeout(120_000);
+});