@equalfi/ski 0.1.1 → 0.1.2

package/README.md

@@ -15,6 +15,39 @@ pnpm dlx @equalfi/ski
 - Stores the password in your OS keychain (one prompt) via @napi-rs/keyring
 - Prints the session key address to paste into the UI
 
+## Runtime helper (for agents)
+This package also exposes helpers to execute calls via `executeWithRuntimeValidation` using the session key.
+
+```js
+const { loadSessionWallet, buildRuntimeAuthorization, executeWithRuntimeValidation } = require('@equalfi/ski');
+
+const wallet = await loadSessionWallet('position-1');
+// build runtime authorization
+const data = '0x...'; // ABI-encoded call (e.g., nonce())
+const { authorization } = await buildRuntimeAuthorization({
+  moduleAddress: '0xSessionKeyValidationModule',
+  account: '0xTBA',
+  entityId: 7,
+  sender: wallet.address,
+  value: 0n,
+  data,
+  sessionWallet: wallet,
+  chainId: 31337,
+});
+
+// or send directly
+await executeWithRuntimeValidation({
+  rpcUrl: 'http://127.0.0.1:8545',
+  tbaAddress: '0xTBA',
+  moduleAddress: '0xSessionKeyValidationModule',
+  entityId: 7,
+  data,
+  value: 0n,
+  sessionWallet: wallet,
+  chainId: 31337,
+});
+```
+
 ## Notes
 - Default label is `position-<tokenId>`
 - If the key already exists, it asks before overwriting

package/bin/cli.js

@@ -5,15 +5,12 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 const prompts = require('prompts');
-const { Entry } = require('@napi-rs/keyring');
-const { Wallet } = require('ethers');
+const { createSessionKey } = require('../lib/session');
 
-const SERVICE = 'equalfi-ski';
-const SKILL_ID = 'equalfi';
 const DEFAULT_ENTITY_ID = 7;
 
 const resolvePaths = (label) => {
-  const baseDir = path.join(os.homedir(), '.openclaw', 'keys', SKILL_ID);
+  const baseDir = path.join(os.homedir(), '.openclaw', 'keys', 'equalfi');
   return {
     baseDir,
     keystorePath: path.join(baseDir, `${label}.json`),
@@ -21,12 +18,6 @@ const resolvePaths = (label) => {
   };
 };
 
-const keychainAccount = (label) => `session-key:${SKILL_ID}:${label}`;
-
-async function ensureDir(dir) {
-  await fs.mkdir(dir, { recursive: true });
-}
-
 async function fileExists(p) {
   try {
     await fs.access(p);
@@ -61,8 +52,7 @@ async function main() {
   const label = `position-${response.tokenId}`;
   const entityId = Number(response.entityId ?? DEFAULT_ENTITY_ID);
 
-  const { baseDir, keystorePath, metaPath } = resolvePaths(label);
-  await ensureDir(baseDir);
+  const { keystorePath } = resolvePaths(label);
 
   if (await fileExists(keystorePath)) {
     const confirm = await prompts({
@@ -77,44 +67,19 @@ async function main() {
     }
   }
 
-  const wallet = Wallet.createRandom();
-  const password = crypto.randomBytes(32).toString('hex');
-  const keystore = await wallet.encrypt(password);
-
-  await fs.writeFile(keystorePath, keystore);
-  await fs.writeFile(
-    metaPath,
-    JSON.stringify(
-      {
-        address: wallet.address,
-        chainId: null,
-        skillId: SKILL_ID,
-        agentLabel: label,
-        positionTokenId: response.tokenId,
-        entityId,
-        createdAt: new Date().toISOString(),
-        keychainService: SERVICE,
-        keychainAccount: keychainAccount(label),
-      },
-      null,
-      2
-    )
-  );
-
+  let created;
   try {
-    const entry = new Entry(SERVICE, keychainAccount(label));
-    entry.setPassword(password);
+    created = await createSessionKey({ label, entityId, allowOverwrite: true });
   } catch (err) {
-    console.error('Failed to store key in OS keychain:', err?.message || err);
-    console.error('Keystore saved, but you must secure the password manually.');
+    console.error('Failed to create session key:', err?.message || err);
     return;
   }
 
   console.log('\n✅ Session key created');
-  console.log(`Address: ${wallet.address}`);
+  console.log(`Address: ${created.address}`);
   console.log(`Label:   ${label}`);
   console.log(`Entity:  ${entityId}`);
-  console.log(`Stored:  ${keystorePath}`);
+  console.log(`Stored:  ${created.keystorePath}`);
   console.log('\nPaste the address into the UI session key field and install the module/policy.');
 }
 

package/lib/index.js

@@ -0,0 +1 @@
+module.exports = require('./session');

package/lib/session.js

@@ -0,0 +1,152 @@
+const fs = require('fs/promises');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { Entry } = require('@napi-rs/keyring');
+const { Wallet, Contract, JsonRpcProvider, AbiCoder, keccak256, toUtf8Bytes, getBytes } = require('ethers');
+
+const SERVICE = 'equalfi-ski';
+const SKILL_ID = 'equalfi';
+
+const resolvePaths = (label) => {
+  const baseDir = path.join(os.homedir(), '.openclaw', 'keys', SKILL_ID);
+  return {
+    baseDir,
+    keystorePath: path.join(baseDir, `${label}.json`),
+    metaPath: path.join(baseDir, `${label}.meta.json`),
+  };
+};
+
+const keychainAccount = (label) => `session-key:${SKILL_ID}:${label}`;
+
+async function ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function moduleEntity(module, entityId) {
+  const clean = module.toLowerCase().replace(/^0x/, '');
+  const entityHex = BigInt(entityId).toString(16).padStart(8, '0');
+  return `0x${clean}${entityHex}`; // bytes24
+}
+
+async function createSessionKey({ label, entityId = 7, allowOverwrite = false }) {
+  const { baseDir, keystorePath, metaPath } = resolvePaths(label);
+  await ensureDir(baseDir);
+
+  if (!allowOverwrite && (await fileExists(keystorePath))) {
+    throw new Error(`Key already exists for ${label}.`);
+  }
+
+  const wallet = Wallet.createRandom();
+  const password = crypto.randomBytes(32).toString('hex');
+  const keystore = await wallet.encrypt(password);
+
+  await fs.writeFile(keystorePath, keystore);
+  await fs.writeFile(
+    metaPath,
+    JSON.stringify(
+      {
+        address: wallet.address,
+        chainId: null,
+        skillId: SKILL_ID,
+        agentLabel: label,
+        entityId,
+        createdAt: new Date().toISOString(),
+        keychainService: SERVICE,
+        keychainAccount: keychainAccount(label),
+      },
+      null,
+      2
+    )
+  );
+
+  const entry = new Entry(SERVICE, keychainAccount(label));
+  entry.setPassword(password);
+
+  return { address: wallet.address, keystorePath, metaPath };
+}
+
+async function loadSessionWallet(label) {
+  const { keystorePath } = resolvePaths(label);
+  const entry = new Entry(SERVICE, keychainAccount(label));
+  const password = entry.getPassword();
+  if (!password) {
+    throw new Error(`Missing keychain entry for ${label}`);
+  }
+  const keystore = await fs.readFile(keystorePath, 'utf8');
+  const wallet = await Wallet.fromEncryptedJson(keystore, password);
+  return wallet;
+}
+
+function buildRuntimeAuthorization({
+  moduleAddress,
+  account,
+  entityId,
+  sender,
+  value = 0n,
+  data,
+  sessionWallet,
+  replayProtection,
+  chainId,
+}) {
+  const moduleEnt = moduleEntity(moduleAddress, entityId);
+  const replay = replayProtection || `0x${crypto.randomBytes(32).toString('hex')}`;
+  const coder = AbiCoder.defaultAbiCoder();
+  const tag = keccak256(toUtf8Bytes('AGENT_WALLET_SESSION_RUNTIME_V1'));
+  const payload = coder.encode(
+    ['bytes32','uint256','address','address','uint32','address','uint256','bytes32','bytes32'],
+    [tag, BigInt(chainId), moduleAddress, account, entityId, sender, BigInt(value), keccak256(data), replay]
+  );
+  const payloadHash = keccak256(payload);
+  const signature = sessionWallet.signMessageSync ? sessionWallet.signMessageSync(getBytes(payloadHash)) : sessionWallet.signMessage(getBytes(payloadHash));
+  const moduleAuth = coder.encode(['address','bytes32','bytes'], [sessionWallet.address, replay, signature]);
+  const authorization = coder.encode(['bytes24','bytes'], [moduleEnt, moduleAuth]);
+  return { authorization, replayProtection: replay, signature, moduleEntity: moduleEnt };
+}
+
+async function executeWithRuntimeValidation({
+  rpcUrl,
+  tbaAddress,
+  moduleAddress,
+  entityId,
+  data,
+  value = 0n,
+  sessionWallet,
+  chainId,
+}) {
+  const provider = new JsonRpcProvider(rpcUrl);
+  const wallet = sessionWallet.connect(provider);
+  const { authorization } = await buildRuntimeAuthorization({
+    moduleAddress,
+    account: tbaAddress,
+    entityId,
+    sender: wallet.address,
+    value,
+    data,
+    sessionWallet: wallet,
+    chainId,
+  });
+
+  const tba = new Contract(
+    tbaAddress,
+    ['function executeWithRuntimeValidation(bytes data, bytes authorization) payable returns (bytes)'],
+    wallet
+  );
+  return tba.executeWithRuntimeValidation(data, authorization, { value });
+}
+
+module.exports = {
+  createSessionKey,
+  loadSessionWallet,
+  buildRuntimeAuthorization,
+  executeWithRuntimeValidation,
+};

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@equalfi/ski",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "EqualFi Session Key Installer (interactive CLI)",
   "license": "MIT",
+  "main": "lib/index.js",
   "bin": {
     "ski": "bin/cli.js"
   },
   "files": [
     "bin",
+    "lib",
     "README.md"
   ],
   "engines": {