Merge pull request #972 from LIT-Protocol/feature/jss-35-naga-js-sdk-wrapped-keys-implementation

Feature/jss 35 naga js sdk wrapped keys implementation

Author: Ansonhkg

.changeset/cold-dancers-push.md

@@ -0,0 +1,16 @@
+---
+'@lit-protocol/wrapped-keys-lit-actions': minor
+'@lit-protocol/auth-services': minor
+'@lit-protocol/auth-helpers': minor
+'@lit-protocol/wrapped-keys': minor
+'@lit-protocol/lit-client': minor
+'@lit-protocol/artillery': minor
+'@lit-protocol/constants': minor
+'@lit-protocol/contracts': minor
+'@lit-protocol/networks': minor
+'@lit-protocol/crypto': minor
+'@lit-protocol/auth': minor
+'@lit-protocol/e2e': minor
+---
+
+Introduce wrapped-keys support to v8 so applications can generate, import, export, and sign with encrypted keys across EVM and Solana without exposing private key material. New `auth` package APIs include `validateDelegationAuthSig`, `generatePkpDelegationAuthSig`, `generateEoaDelegationAuthSig`, `createPkpAuthContextFromPreGenerated`, and `createPkpSessionSigs`. New `wrapped-keys` APIs include `generatePrivateKey`, `importPrivateKey`, `exportPrivateKey`, `listEncryptedKeyMetadata`, `getEncryptedKey`, `storeEncryptedKey`, `storeEncryptedKeyBatch`, `batchGeneratePrivateKeys`, `signMessageWithEncryptedKey`, and `signTransactionWithEncryptedKey`. See the updated docs (guides/server-sessions, sdk-reference/wrapped-keys, and the new auth references) for end-to-end examples. [PR](https://github.com/LIT-Protocol/js-sdk/pull/972)

.changeset/config.json

@@ -7,8 +7,5 @@
   "access": "public",
   "baseBranch": "naga",
   "updateInternalDependencies": "minor",
-  "ignore": [
-    "@lit-protocol/wrapped-keys",
-    "@lit-protocol/wrapped-keys-lit-actions"
-  ]
+  "ignore": []
 }

docs/docs.json

@@ -80,7 +80,8 @@
             "pages": [
               "sdk/auth-context-consumption/pkp-sign",
               "sdk/auth-context-consumption/execute-js",
-              "sdk/auth-context-consumption/encrypt-and-decrypt"
+              "sdk/auth-context-consumption/encrypt-and-decrypt",
+              "sdk/auth-context-consumption/wrapped-keys"
             ]
           },
           {
@@ -110,14 +111,35 @@
               {
                 "group": "@lit-protocol/auth",
                 "pages": [
-                  "sdk/sdk-reference/auth/functions/createAuthManager"
+                  "sdk/sdk-reference/auth/functions/createAuthManager",
+                  "sdk/sdk-reference/auth/functions/generatePkpDelegationAuthSig",
+                  "sdk/sdk-reference/auth/functions/generateEoaDelegationAuthSig",
+                  "sdk/sdk-reference/auth/functions/validateDelegationAuthSig",
+                  "sdk/sdk-reference/auth/functions/createPkpAuthContextFromPreGenerated",
+                  "sdk/sdk-reference/auth/functions/createPkpSessionSigs"
                 ]
               },
               {
                 "group": "@lit-protocol/networks",
                 "pages": [
                   "sdk/sdk-reference/networks/functions/withOverrides"
                 ]
+              },
+              {
+                "group": "@lit-protocol/wrapped-keys",
+                "pages": [
+                  "sdk/sdk-reference/wrapped-keys/index",
+                  "sdk/sdk-reference/wrapped-keys/functions/generatePrivateKey",
+                  "sdk/sdk-reference/wrapped-keys/functions/exportPrivateKey",
+                  "sdk/sdk-reference/wrapped-keys/functions/importPrivateKey",
+                  "sdk/sdk-reference/wrapped-keys/functions/getEncryptedKey",
+                  "sdk/sdk-reference/wrapped-keys/functions/listEncryptedKeyMetadata",
+                  "sdk/sdk-reference/wrapped-keys/functions/storeEncryptedKey",
+                  "sdk/sdk-reference/wrapped-keys/functions/storeEncryptedKeyBatch",
+                  "sdk/sdk-reference/wrapped-keys/functions/batchGeneratePrivateKeys",
+                  "sdk/sdk-reference/wrapped-keys/functions/signMessageWithEncryptedKey",
+                  "sdk/sdk-reference/wrapped-keys/functions/signTransactionWithEncryptedKey"
+                ]
               }
             ]
           },
@@ -131,7 +153,8 @@
           {
             "group": "Guides",
             "pages": [
-              "guides/lit-action-sign-as-action"
+              "guides/lit-action-sign-as-action",
+              "guides/server-sessions"
             ]
           },
           {
@@ -223,4 +246,4 @@
       "discord": "https://litgateway.com/discord"
     }
   }
-}
+}

docs/guides/server-sessions.mdx

@@ -0,0 +1,126 @@
+---
+title: "Server Sessions"
+description: "Delegate a PKP to an ephemeral session key and hand that scoped capability to backend services that mint fresh session signatures on demand."
+---
+
+# Overview
+
+Some integrations need a backend or serverless worker to execute Lit actions long after a user has left the client. Instead of caching `pkpSessionSigs` (which expire quickly and can become invalid when nodes join or leave the network), you can delegate the PKP to a session key and send the **session keypair plus delegation auth signature** to the server. The server then recreates the auth context and generates short-lived session signatures immediately before each request.
+
+This pattern keeps the delegation scoped (resources and expiration are enforced by the delegation) while avoiding the flakiness that comes from reusing stale session signatures.
+
+# Workflow
+
+1. **Client generates a session keypair** with `generateSessionKeyPair()`.
+2. **Client creates a delegation auth signature** with `authManager.generatePkpDelegationAuthSig`, scoping the allowed [Lit resources](/sdk/resources/lit-resources-and-abilities) and expiration.
+3. **Client sends the bundle** { sessionKeyPair, delegationAuthSig, pkpPublicKey }` to the server over a secure channel.
+4. **Server restores an auth context** using `authManager.createPkpAuthContextFromPreGenerated`.
+5. **Server issues fresh session signatures on demand** (e.g., `authManager.createPkpSessionSigs`) immediately before calling SDK helpers such as the wrapped-keys API or `pkpSign`.
+
+# Client hand-off example
+
+```ts
+import {
+  createAuthManager,
+  generateSessionKeyPair,
+} from '@lit-protocol/auth';
+
+const sessionKeyPair = generateSessionKeyPair();
+
+const delegationAuthSig = await authManager.generatePkpDelegationAuthSig({
+  pkpPublicKey,
+  authData,
+  sessionKeyPair,
+  authConfig: {
+    resources: [
+      ['pkp-signing', '*'],
+      ['lit-action-execution', '*'],
+      ['access-control-condition-decryption', '*'],
+    ],
+    expiration: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+  },
+  litClient: litClient,
+});
+
+const envelope = JSON.stringify({
+  pkpPublicKey,
+  payload: Buffer.from(
+    JSON.stringify({ sessionKeyPair, delegationAuthSig }),
+    'utf8'
+  ).toString('base64url'),
+});
+```
+
+# Server restore example
+
+```ts
+import {
+  createAuthManager,
+  storagePlugins,
+  validateDelegationAuthSig,
+} from '@lit-protocol/auth';
+import { createLitClient } from '@lit-protocol/lit-client';
+
+const parsedEnvelope = JSON.parse(envelope) as {
+  pkpPublicKey: string;
+  payload: string;
+};
+
+const decodedPayload = JSON.parse(
+  Buffer.from(parsedEnvelope.payload, 'base64url').toString('utf8')
+) as {
+  sessionKeyPair: typeof sessionKeyPair;
+  delegationAuthSig: typeof delegationAuthSig;
+};
+
+validateDelegationAuthSig({
+  delegationAuthSig: decodedPayload.delegationAuthSig,
+  sessionKeyUri: decodedPayload.sessionKeyPair.publicKey,
+});
+
+const serverLitClient = await createLitClient({ network: resolvedNetwork });
+const serverAuthManager = createAuthManager({
+  storage: storagePlugins.localStorageNode({
+    appName: 'server-session-demo',
+    networkName: resolvedNetwork.name,
+    storagePath: './.server-session-cache',
+  }),
+});
+
+const authContext =
+  await serverAuthManager.createPkpAuthContextFromPreGenerated({
+    pkpPublicKey: parsedEnvelope.pkpPublicKey,
+    sessionKeyPair: decodedPayload.sessionKeyPair,
+    delegationAuthSig: decodedPayload.delegationAuthSig,
+  });
+
+// Only call this when the downstream API explicitly requires session sigs
+const pkpSessionSigs = await serverAuthManager.createPkpSessionSigs({
+  sessionKeyPair: decodedPayload.sessionKeyPair,
+  pkpPublicKey: parsedEnvelope.pkpPublicKey,
+  delegationAuthSig: decodedPayload.delegationAuthSig,
+  litClient: serverLitClient,
+});
+
+await serverLitClient.chain.ethereum.pkpSign({
+  authContext,
+  pubKey: parsedEnvelope.pkpPublicKey,
+  toSign: 'hello from server reuse',
+});
+```
+
+<Note>
+  Only call `createPkpSessionSigs` when the downstream API explicitly requires the session sigs (for example, the wrapped-keys service). 
+</Note>
+
+# Security considerations
+
+- **Treat the session keypair like a secret.** Whoever holds the private key can mint new session signatures until the delegation expires.
+- **Scope the delegation.** Restrict resources to the minimal [Lit resources](/sdk/resources/lit-resources-and-abilities) needed and set conservative expirations.
+- **Rotate on failure.** If a node joins or leaves the network the server can simply regenerate session signatures with the current handshake; if that fails, request a fresh delegation from the client.
+
+# When to use this pattern
+
+- Long-running workflows where session signatures might expire before all steps finish (e.g., Bitcoin transactions that need multiple confirmations).
+- Server-driven orchestration that must run without a browser tab staying open.
+- Integrations that want to avoid caching `pkpSessionSigs`, but still need durable delegated access.

docs/sdk/auth-context-consumption/wrapped-keys.mdx

@@ -0,0 +1,146 @@
+---
+title: "Wrapped Keys"
+description: "Manage generated or imported keys through Lit’s wrapped-keys service by delegating a PKP session and calling the specialised APIs for EVM and Solana."
+---
+
+# Overview
+
+Wrapped keys let you generate, import, store, and use non-PKP private keys while keeping them encrypted by the Lit Network. The `@lit-protocol/wrapped-keys` package exposes helper APIs that run curated Lit Actions via `executeJs` for you so that signed messages or transactions never leave the Lit node unless you explicitly export the key material.
+
+Unlike the Core API flows (`pkpSign`, `executeJs`, `encryptAndDecrypt`) that accept an `authContext` directly, the wrapped-keys APIs expect a PKP session signature bundle (`pkpSessionSigs`). This keeps the SDK compatible with the v7 infrastructure and Lambda/serverless deployments that pass session materials between runtimes. Mint the bundle with `authManager.createPkpSessionSigs` as shown below.
+
+# How the flow differs from other Core API methods
+
+- **Why generate a delegation auth sig?**  
+  You delegate your PKP to an ephemeral session key so the wrapped-keys Lit Actions can execute without presenting your long-lived auth credentials. The delegation constrains the permissions (`pkp-signing`, `lit-action-execution`, `access-control-condition-decryption`) and sets an expiry window, limiting blast radius if the session key is ever leaked. Refer to the [Lit resources guide](/sdk/resources/lit-resources-and-abilities) for the full catalogue of resource prefixes and abilities.
+
+- **Why supply PKP session signatures?**  
+  Wrapped-keys endpoints reuse the same session bundle across all networks (for example, Lambda functions in the v7 stack). Provide `pkpSessionSigs` produced by `authManager.createPkpSessionSigs` so the Lit nodes can verify the delegated permissions before executing the action.
+
+- **Controlling network spend**  
+  Because every wrapped-keys helper ultimately calls `executeJs`, you can supply an optional `userMaxPrice` to cap how much a caller is willing to pay for node execution (mirroring the parameter available on the core `executeJs` API).
+
+- **Optional: bundle Lit Action source**  
+  By default the SDK references IPFS CIDs. To remove the IPFS dependency, inject the Lit Action source code at runtime:
+
+  ```ts
+  import { api as wrappedKeysApi, config as wrappedKeysConfig } from '@lit-protocol/wrapped-keys';
+  import {
+    litActionRepository,
+    litActionRepositoryCommon,
+  } from '@lit-protocol/wrapped-keys-lit-actions';
+
+  wrappedKeysConfig.setLitActionsCode(litActionRepository);
+  wrappedKeysConfig.setLitActionsCodeCommon(litActionRepositoryCommon);
+  ```
+
+# Session material workflow
+
+```ts
+import { createAuthManager, generateSessionKeyPair } from '@lit-protocol/auth';
+import { api as wrappedKeysApi } from '@lit-protocol/wrapped-keys';
+
+const authManager = createAuthManager();
+const litClient = await createLitClient({ network: resolvedNetwork });
+
+// 1. Ephemeral signer that will front the PKP for wrapped-key actions
+const sessionKeyPair = generateSessionKeyPair();
+
+// 2. Delegate the PKP to the session key with explicit Lit resources and expiry
+const delegationAuthSig = await authManager.generatePkpDelegationAuthSig({
+  pkpPublicKey,
+  authData,
+  sessionKeyPair,
+  authConfig: {
+    resources: [
+      ['pkp-signing', '*'],
+      ['lit-action-execution', '*'],
+      ['access-control-condition-decryption', '*'],
+    ],
+    expiration: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+  },
+  litClient,
+});
+
+// 3. Produce the SessionSigsMap required by every wrapped-keys API call
+const pkpSessionSigs = await authManager.createPkpSessionSigs({
+  sessionKeyPair,
+  pkpPublicKey,
+  delegationAuthSig,
+  litClient,
+});
+
+// 4. Call wrapped-keys APIs with the session signatures
+const { id } = await wrappedKeysApi.generatePrivateKey({
+  pkpSessionSigs,
+  litClient,
+  network: 'evm',
+  memo: 'wallet for gasless relays',
+  userMaxPrice: 1000n, // optional cap on per-request spend
+});
+```
+
+<Note>
+  Wrapped-keys calls need `pkpSessionSigs` explicitly. Other Lit APIs that accept an `authContext` (for example `executeJs` or `pkpSign`) creates session signatures internally, so you do not need to export it when you are not touching wrapped keys.
+</Note>
+
+Need a backend to create fresh session signatures on demand? Follow the [server sessions guide](/guides/server-sessions) to delegate a session key and let the server recreate `pkpSessionSigs` per request.
+
+# Example usage
+
+## Generate and sign on EVM
+
+```ts
+const { id, generatedPublicKey } = await wrappedKeysApi.generatePrivateKey({
+  pkpSessionSigs,
+  litClient,
+  network: 'evm',
+  memo: 'lit',
+});
+
+// Export once if you need the raw private key 
+const { decryptedPrivateKey } = await wrappedKeysApi.exportPrivateKey({
+  pkpSessionSigs,
+  litClient,
+  network: 'evm',
+  id,
+});
+
+// Sign an EVM transaction without revealing the key outside the Lit nodes
+const serializedTx = await wrappedKeysApi.signTransactionWithEncryptedKey({
+  pkpSessionSigs,
+  litClient,
+  network: 'evm',
+  id,
+  unsignedTransaction: {
+    chain: 'yellowstone',
+    chainId: 175188,
+    toAddress: '0x0000000000000000000000000000000000000000',
+    value: '0',
+  },
+  broadcast: false,
+});
+```
+
+## Generate and sign on Solana
+
+```ts
+const { id, publicKey } = await wrappedKeysApi.generatePrivateKey({
+  pkpSessionSigs,
+  litClient,
+  network: 'solana',
+  memo: 'vault signer',
+});
+
+const signature = await wrappedKeysApi.signMessageWithEncryptedKey({
+  pkpSessionSigs,
+  litClient,
+  network: 'solana',
+  id,
+  messageToSign: 'hello from wrapped keys',
+});
+```
+
+# API catalogue
+
+See the full reference for every helper at [Wrapped Keys Reference](/sdk/sdk-reference/wrapped-keys/index).