feat: Add support for kvstore client (#495)

* add package

* include kvstore client in defender-sdk index

* add kv store local example

* include action credentials when initializing client

examples/key-value-store-local/index.js

@@ -0,0 +1,15 @@
+const { Defender } = require('@openzeppelin/defender-sdk');
+
+async function main() {
+  const store = Defender.localKVStoreClient({ path: './store.json' });
+  await store.put('key', 'value!');
+
+  const value = await store.get('key');
+  console.log(value);
+
+  await store.del('key');
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}

examples/key-value-store-local/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@openzeppelin/defender-sdk-example-key-value-store-local",
+  "version": "1.14.2",
+  "private": true,
+  "main": "index.js",
+  "author": "OpenZeppelin Defender <[email protected]>",
+  "license": "MIT",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@openzeppelin/defender-sdk": "1.14.2"
+  }
+}

examples/key-value-store-local/store.json

@@ -0,0 +1 @@
+{}

packages/base/src/api/api.ts

@@ -1,4 +1,3 @@
-import { CognitoUserSession } from 'amazon-cognito-identity-js';
 import axios, { AxiosError, AxiosInstance } from 'axios';
 import https from 'https';
 

packages/base/src/index.ts

@@ -1,6 +1,7 @@
 export { createApi, createAuthenticatedApi } from './api/api';
 export { authenticate } from './api/auth';
 export { BaseApiClient, RetryConfig, AuthConfig } from './api/client';
+export { BaseActionClient } from './action';
 export * from './utils/network';
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires

packages/defender-sdk/package.json

@@ -29,7 +29,8 @@
     "@openzeppelin/defender-sdk-notification-channel-client": "^1.14.2",
     "@openzeppelin/defender-sdk-relay-signer-client": "^1.14.2",
     "@openzeppelin/defender-sdk-network-client": "^1.14.2",
-    "@openzeppelin/defender-sdk-account-client": "^1.14.2"
+    "@openzeppelin/defender-sdk-account-client": "^1.14.2",
+    "@openzeppelin/defender-sdk-key-value-store-client": "^1.14.2"
   },
   "publishConfig": {
     "access": "public"

packages/defender-sdk/src/index.ts

@@ -6,13 +6,19 @@ import { DeployClient } from '@openzeppelin/defender-sdk-deploy-client';
 import { NotificationChannelClient } from '@openzeppelin/defender-sdk-notification-channel-client';
 import { NetworkClient } from '@openzeppelin/defender-sdk-network-client';
 import { AccountClient } from '@openzeppelin/defender-sdk-account-client';
+import { KeyValueStoreClient, LocalKeyValueStoreCreateParams } from '@openzeppelin/defender-sdk-key-value-store-client';
 
 import { Newable, ClientParams } from './types';
 import { ActionRelayerParams, Relayer as RelaySignerClient } from '@openzeppelin/defender-sdk-relay-signer-client';
 import { ListNetworkRequestOptions } from '@openzeppelin/defender-sdk-network-client/lib/models/networks';
 import { AuthConfig, Network, RetryConfig } from '@openzeppelin/defender-sdk-base-client';
 import https from 'https';
-import { isRelaySignerOptions } from './utils';
+import {
+  isActionKVStoreCredentials,
+  isActionRelayerCredentials,
+  isApiCredentials,
+  isRelaySignerOptions,
+} from './utils';
 
 export interface DefenderOptions {
   apiKey?: string;
@@ -24,12 +30,14 @@ export interface DefenderOptions {
   httpsAgent?: https.Agent;
   retryConfig?: RetryConfig;
   useCredentialsCaching?: boolean;
+  kvstoreARN?: string;
 }
 
 function getClient<T>(Client: Newable<T>, credentials: Partial<ClientParams> | ActionRelayerParams): T {
   if (
-    !('credentials' in credentials && 'relayerARN' in credentials) &&
-    !('apiKey' in credentials && 'apiSecret' in credentials)
+    !isActionRelayerCredentials(credentials) &&
+    !isApiCredentials(credentials) &&
+    !isActionKVStoreCredentials(credentials)
   ) {
     throw new Error(`API key and secret are required`);
   }
@@ -44,6 +52,7 @@ export class Defender {
   private relayerApiSecret: string | undefined;
   private actionCredentials: ActionRelayerParams | undefined;
   private actionRelayerArn: string | undefined;
+  private actionKVStoreArn: string | undefined;
   private httpsAgent?: https.Agent;
   private retryConfig?: RetryConfig;
   private authConfig?: AuthConfig;
@@ -56,6 +65,7 @@ export class Defender {
     // support for using relaySigner from Defender Actions
     this.actionCredentials = options.credentials;
     this.actionRelayerArn = options.relayerARN;
+    this.actionKVStoreArn = options.kvstoreARN;
     this.httpsAgent = options.httpsAgent;
     this.retryConfig = options.retryConfig;
     this.authConfig = {
@@ -165,4 +175,23 @@ export class Defender {
       ...(this.relayerApiSecret ? { apiSecret: this.relayerApiSecret } : undefined),
     });
   }
+
+  get keyValueStore() {
+    return getClient(KeyValueStoreClient, {
+      apiKey: this.apiKey,
+      apiSecret: this.apiSecret,
+      httpsAgent: this.httpsAgent,
+      retryConfig: this.retryConfig,
+      authConfig: this.authConfig,
+      ...(this.actionCredentials ? { credentials: this.actionCredentials } : undefined),
+      ...(this.actionKVStoreArn ? { kvstoreARN: this.actionKVStoreArn } : undefined),
+    });
+  }
+
+  static localKVStoreClient(params: LocalKeyValueStoreCreateParams) {
+    if (!params.path) {
+      throw new Error(`Must provide a path for local key-value store`);
+    }
+    return new KeyValueStoreClient(params);
+  }
 }

packages/defender-sdk/src/types.ts

@@ -9,4 +9,5 @@ export type ClientParams = {
   httpsAgent?: https.Agent;
   retryConfig?: RetryConfig;
   authConfig: AuthConfig;
+  path?: string;
 };

packages/defender-sdk/src/utils.ts

@@ -1,4 +1,6 @@
+import { ActionRelayerParams } from '@openzeppelin/defender-sdk-relay-signer-client';
 import { DefenderOptions } from '.';
+import { ClientParams } from './types';
 
 export function isRelaySignerOptions(options: DefenderOptions): boolean {
   return (
@@ -8,3 +10,15 @@ export function isRelaySignerOptions(options: DefenderOptions): boolean {
     options.relayerARN !== undefined
   );
 }
+
+export function isActionRelayerCredentials(credentials: Partial<ClientParams> | ActionRelayerParams): boolean {
+  return 'credentials' in credentials && 'relayerARN' in credentials;
+}
+
+export function isApiCredentials(credentials: Partial<ClientParams> | ActionRelayerParams): boolean {
+  return 'apiKey' in credentials && 'apiSecret' in credentials;
+}
+
+export function isActionKVStoreCredentials(credentials: Partial<ClientParams> | ActionRelayerParams): boolean {
+  return 'credentials' in credentials && 'kvstoreARN' in credentials;
+}

packages/kvstore/README.md

@@ -0,0 +1,65 @@
+# Defender Key-Value Store for Actions
+
+The [Defender Actions](https://docs.openzeppelin.com/defender/v2/module/actions) service allows you to run small code snippets on a regular basis or via webhooks that can make calls to the Ethereum network or to external APIs. Thanks to tight integration to Defender Relayers, you can use Actions to automate regular operations on your contracts.
+
+This client allows you to access a simple key-value data store from your Actions code, so you can persist data throughout executions and across different Actions.
+
+_Note that this package will not work outisde the Actions environment._
+
+## Installation
+
+This package is included in the latest Actions runtime environment, so you do not need to bundle it in your code. To install it for local development and typescript type completion, run:
+
+```bash
+npm install @openzeppelin/defender-sdk-key-value-store
+```
+
+```bash
+yarn add @openzeppelin/defender-sdk-key-value-store
+```
+
+## Usage
+
+You can interact with your key-value store through an instance of `Defender`, which is initialized with the payload injected in the your Action `handler` function. Once initialized, you can call `kvstore.get`, `kvstore.put`, or `kvstore.del`.
+
+```js
+const { Defender } = require('@openzeppelin/defender-sdk');
+
+exports.handler = async function (event) {
+  // Creates an instance of the key-value store client
+  const client = new Defender(event);
+
+  // Associates myValue to myKey
+  await client.keyValueStore.put('myKey', 'myValue');
+
+  // Returns myValue associated to myKey
+  const value = await client.keyValueStore.get('myKey');
+
+  // Deletes the entry for myKey
+  await client.keyValueStore.del('myKey');
+};
+```
+
+## Local development
+
+The Defender key-value store is only accessible from within an Action. To simplify local development, you can create an instance using `Defender.localKVStoreClient` providing an object with a `path` property. The client will use a local json file at that path for all operations.
+
+```js
+const { Defender } = require('@openzeppelin/defender-sdk');
+
+async function local() {
+  // Creates an instance of the client that will write to a local file
+  const store = Defender.localKVStoreClient({ path: '/tmp/foo/store.json' });
+
+  // The store.json file will contain { myKey: myValue }
+  await store.put('myKey', 'myValue');
+}
+```
+
+## Considerations
+
+- All data in the key-value store is persisted as strings, both keys and values.
+- Keys are limited to 1kb in size, and values to 300kb.
+- The data store is shared across all your Actions; consider prefixing the keys with a namespace if you want to have different data buckets.
+- A key-value entry is expired after 90 days of the last time it was `put` into the store.
+- The total number of key-value records in your store is determined by your Defender plan.

packages/kvstore/__mocks__/@aws-sdk/client-lambda.ts

@@ -0,0 +1,11 @@
+const Lambda = jest.fn(() => ({
+  invoke: jest.fn(() =>
+    Promise.resolve({
+      Payload: {
+        transformToString: () => JSON.stringify({ result: 'result' }),
+      },
+    }),
+  ),
+}));
+
+export { Lambda };

packages/kvstore/__mocks__/aws-sdk/clients/lambda.ts

@@ -0,0 +1,11 @@
+const mock = jest.fn(() => ({
+  invoke: jest.fn(() => ({
+    promise: jest.fn(() =>
+      Promise.resolve({
+        Payload: JSON.stringify({ result: 'result' }),
+      }),
+    ),
+  })),
+}));
+
+export default mock;

packages/kvstore/jest.config.js

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

packages/kvstore/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@openzeppelin/defender-sdk-key-value-store-client",
+  "version": "1.14.2",
+  "description": "",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "scripts": {
+    "build": "rm -rf lib && tsc",
+    "test": "npm run test:unit",
+    "test:unit": "jest --verbose --passWithNoTests --forceExit",
+    "watch": "tsc -w"
+  },
+  "files": [
+    "lib",
+    "!*.test.js",
+    "!*.test.js.map",
+    "!*.test.d.ts",
+    "!*__mocks__"
+  ],
+  "author": "OpenZeppelin Defender <[email protected]>",
+  "license": "MIT",
+  "dependencies": {
+    "@openzeppelin/defender-sdk-base-client": "^1.14.2",
+    "axios": "^1.7.2",
+    "lodash": "^4.17.21",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/kvstore/src/action.test.ts

@@ -0,0 +1,67 @@
+import { KeyValueStoreActionClient } from './action';
+import Lambda from '../__mocks__/aws-sdk/clients/lambda';
+import { Lambda as LambdaV3 } from '../__mocks__/@aws-sdk/client-lambda';
+jest.mock('node:process', () => ({
+  ...jest.requireActual('node:process'),
+  version: 'v16.0.3',
+}));
+
+type TestClient = Omit<KeyValueStoreActionClient, 'lambda'> & { lambda: typeof Lambda };
+
+describe('KeyValueStoreAutotaskClient', () => {
+  const credentials = {
+    AccessKeyId: 'keyId',
+    SecretAccessKey: 'accessKey',
+    SessionToken: 'token',
+  };
+
+  let client: TestClient;
+
+  beforeEach(async function () {
+    jest.mock('aws-sdk/clients/lambda', () => Lambda);
+    jest.mock('@aws-sdk/client-lambda', () => ({ Lambda: LambdaV3 }));
+    client = new KeyValueStoreActionClient({
+      credentials: JSON.stringify(credentials),
+      kvstoreARN: 'arn',
+    }) as unknown as TestClient;
+  });
+
+  describe('get', () => {
+    test('calls kvstore function', async () => {
+      ((client.lambda as any).invoke as jest.Mock).mockImplementationOnce(() => ({
+        promise: () => Promise.resolve({ Payload: JSON.stringify('myvalue') }),
+      }));
+
+      const result = await client.get('mykey');
+
+      expect(result).toEqual('myvalue');
+      expect((client.lambda as any).invoke).toBeCalledWith({
+        FunctionName: 'arn',
+        InvocationType: 'RequestResponse',
+        Payload: '{"action":"get","key":"mykey"}',
+      });
+    });
+  });
+
+  describe('del', () => {
+    test('calls kvstore function', async () => {
+      await client.del('mykey');
+      expect((client.lambda as any).invoke).toBeCalledWith({
+        FunctionName: 'arn',
+        InvocationType: 'RequestResponse',
+        Payload: '{"action":"del","key":"mykey"}',
+      });
+    });
+  });
+
+  describe('put', () => {
+    test('calls kvstore function', async () => {
+      await client.put('mykey', 'myvalue');
+      expect((client.lambda as any).invoke).toBeCalledWith({
+        FunctionName: 'arn',
+        InvocationType: 'RequestResponse',
+        Payload: '{"action":"put","key":"mykey","value":"myvalue"}',
+      });
+    });
+  });
+});

packages/kvstore/src/action.ts

@@ -0,0 +1,23 @@
+import { IKeyValueStoreClient, KeyValueStoreCreateParams, KeyValueStoreRequest } from './types';
+import { BaseActionClient } from '@openzeppelin/defender-sdk-base-client';
+
+export class KeyValueStoreActionClient extends BaseActionClient implements IKeyValueStoreClient {
+  public constructor(params: KeyValueStoreCreateParams) {
+    super(params.credentials, params.kvstoreARN);
+  }
+
+  public async get(key: string): Promise<string | undefined> {
+    const request: KeyValueStoreRequest = { action: 'get', key };
+    return this.execute(request);
+  }
+
+  public async put(key: string, value: string): Promise<void> {
+    const request: KeyValueStoreRequest = { action: 'put', key, value };
+    return this.execute(request);
+  }
+
+  public async del(key: string): Promise<void> {
+    const request: KeyValueStoreRequest = { action: 'del', key };
+    return this.execute(request);
+  }
+}