@cubist-labs/cubesigner-sdk 0.3.29 → 0.4.24-0

package/README.md

@@ -39,6 +39,9 @@ cs login owner@example.com --env '<gamma|prod|...>'
 
 ## Getting started
 
+> [!TIP]
+> For migration from `v0.3.*` to `v0.4.*`, please see [MIGRATION.md](../../MIGRATION.md#v03-to-v04)
+
 In this section we are going to walk through a simple CubeSigner
 setup. We'll create a signing key, then sign some EVM
 transactions, and then add a security policy to restrict the kinds of
@@ -53,32 +56,30 @@ examples below.
 
 ```typescript
 import * as cs from "@cubist-labs/cubesigner-sdk";
-import { JsonFileSessionStorage, loadManagementSession } from "@cubist-labs/cubesigner-sdk-fs-storage";
+import { JsonFileSessionManager, defaultManagementSessionManager } from "@cubist-labs/cubesigner-sdk-fs-storage";
 import assert from "assert";
 ```
 
 ### Instantiate `CubeSignerClient`
 
 The first order of business is to create an instance of `CubeSignerClient`.
-We can do that by simply loading the management session token from the
+We can do that by simply loading a session token from the
 default location on disk (which is where the `cs login` command saves
 it):
 
 ```typescript
-const cubesigner = await loadManagementSession();
+const cubesigner = await cs.CubeSignerClient.create(defaultManagementSessionManager());
 ```
 
 Alternatively, a `CubeSignerClient` instance can be created by explicitly
 providing a session manager:
 
 ```typescript
-// Load session from a JSON file
-const fileStorage = new JsonFileSessionStorage<cs.SignerSessionData>(
+// Create a session manager backed by a JSON file
+const fileStorage = new JsonFileSessionManager(
   `${process.env.HOME}/.config/cubesigner/management-session.json`,
 );
-// Create a session manager for a management token
-const sessionMgr = await cs.SignerSessionManager.loadFromStorage(fileStorage);
-new cs.CubeSignerClient(sessionMgr);
+await cs.CubeSignerClient.create(fileStorage);
 ```
 
 ### Get `User` and `Org` info
@@ -87,13 +88,13 @@ We can now obtain some information about the logged-in user and the
 organization the user belongs to:
 
 ```typescript
-const me = await cubesigner.aboutMe();
+const me = await cubesigner.user();
 console.log(me);
 assert(me.user_id); // each user has a globally unique ID
 assert(me.org_ids); // IDs of all organizations this user is a member of
 assert(me.org_ids.length === 1); // assume that the user is a member of exactly one org
 
-const org = new cs.Org(cubesigner);
+const org = await cubesigner.org();
 assert(await org.enabled()); // assume that the org is enabled
 ```
 
@@ -117,41 +118,6 @@ assert(await secpKey.type(), cs.Secp256k1.Evm);
 console.log(`Created '${cs.Secp256k1.Evm}' key ${secpKey.id}`);
 ```
 
-### Create a `Role` and a `SignerSession`
-
-CubeSigner differentiates between _management_ and _signer_ sessions
-since managing keys (and an org) is often separate from using keys.
-
-Everything we've done so far has been using a management session. To
-sign a message with a key, we now need to create a signer
-session. Signer sessions are associated with roles (which we discuss
-in this section) or users (which we discuss [later](#create-a-session-for-an-oidc-user)).
-
-You can think of roles as groups
-that give certain users access to certain keys. To get started, let's
-create a `Role` and then simply call `createSession` on it:
-
-```typescript
-const role = await org.createRole();
-const sessionStorage = new cs.MemorySessionStorage<cs.SignerSessionData>();
-const session = await role.createSession(sessionStorage, "readme");
-console.log(`Created signer session for role '${role.id}'`);
-```
-
-Sessions have lifetimes, so they need to periodically refresh
-themselves to stay valid. When that happens, the refreshed session
-needs to be saved somewhere, which is why the `createSession` method
-requires an instance of `SessionStorage`. In this example, we don't
-plan to persist the session across multiple runs, so a simple
-in-memory storage suffices; otherwise, opting for
-`JsonFileSessionStorage` would be a better idea, i.e.,
-
-```typescript
-// this storage persists the signer session token to a file
-// named 'session.json' in the current working directory
-new JsonFileSessionStorage("session.json");
-```
-
 ### Sign an Ethereum transaction
 
 Let's create a dummy `EvmSignRequest`.
@@ -172,39 +138,44 @@ const eth1Request = <cs.EvmSignRequest>{
 
 It seems we have everything in place to sign this request with the
 previously created key. However, attempting to do so fails with `403
-Forbidden` saying something like `Role 'Role#... is not authorized to
-access key 'Key#...'`:
+Forbidden` saying something like `Session does not have the required scopes...`
 
 ```typescript
 try {
-  console.log("Trying to sign before adding key to role");
-  await session.signEvm(secpKey, eth1Request);
-  assert(false, "Must not be allowed to sign with key not in role");
+  console.log("Trying to sign with improper scopes");
+  await secpKey.signEvm(eth1Request);
+  assert(false, "Must not be allowed to sign without scopes");
 } catch (e) {
-  assert(`${e}`.includes("not authorized to access key"));
+  assert(`${e}`.includes("Session does not have required scopes"));
 }
 ```
 
-By default, a newly created role does not get to access any
-keys. Instead, keys have to be added to a role explicitly.
-After we do that, the `signEvm` call should succeed:
+By default, the sessions created by the CLI cannot perform signing operations. All sessions have a series of *scopes* which
+which determine what that session can be used for. We'll talk more about this later, but for now just know that we need a new session with the proper scopes:
 
 ```typescript
-console.log("Adding key to role, then signing an Ethereum transaction");
-await role.addKey(secpKey);
-let sig = await session.signEvm(secpKey, eth1Request);
+let signingClient = await cs.CubeSignerClient.create(
+  // declare the "sign:*" scope which allows us to sign using any keys the
+  // account has access to
+  await cubesigner.org().createSession("readme signing demo", ["sign:*"]));
+const signingKey = new cs.Key(signingClient, secpKey.cached);
+let sig = await signingKey.signEvm(eth1Request);
 console.log(sig.data());
 assert(sig.data().rlp_signed_tx);
 ```
 
 ### Using ethers.js instead of the SDK directly
 
+If your application uses ethers.js, you can configure it to use CubeSigner to
+sign transactions.
+
+
 ```typescript
 import { Signer } from "@cubist-labs/cubesigner-sdk-ethers-v6";
 import { ethers } from "ethers";
 
 // Create new Signer
-const ethersSigner = new Signer(secpKey.materialId, session);
+const ethersSigner = new Signer(secpKey.materialId, signingClient);
 assert((await ethersSigner.getAddress()) === ethers.getAddress(secpKey.materialId));
 // sign transaction as usual:
 console.log(
@@ -217,9 +188,32 @@ console.log(
 );
 ```
 
+
+### Access control with `Role`
+
+CubeSigner uses roles to control access to keys when more than one user wants to
+use them. You can think of roles as groups
+that give certain users access to certain keys. To get started, let's
+create a `Role` and then simply call `createSession` on it:
+
+```typescript
+// Create a role, implicitly adding ourselves as a member
+const role = await org.createRole();
+
+console.log("Adding key to role, then signing an Ethereum transaction");
+await role.addKey(secpKey);
+
+// Members of the role can create sessions which can only access keys in the role
+const roleClient = await cs.CubeSignerClient.create(
+  // Role sessions implicitly have the "sign:*" scope
+  await role.createSession("readme")
+);
+console.log(`Created client for role '${role.id}'`);
+```
+
 ### Set security policies
 
-When we add a `Secp256k1.Evm` key to a role (as we did above), a signer session
+When we add a `Secp256k1.Evm` key to a role (as we did above), a client
 associated with that role allows us to sign **any** Ethereum
 transaction with that key. If that seems too permissive, we can attach a security
 policy to restrict the allowed usages of this key in this role.
@@ -231,7 +225,8 @@ recipient, we can attach a `TxReceiver` policy to our key:
 console.log("Setting transaction receiver policy");
 await secpKey.setPolicy([{ TxReceiver: "0xff50ed3d0ec03ac01d4c79aad74928bff48a7b2b" }]);
 console.log("Signing transaction");
-sig = await session.signEvm(secpKey, eth1Request);
+const roleKey = new cs.Key(roleClient, secpKey.cached);
+sig = await roleKey.signEvm(eth1Request);
 assert(sig.data().rlp_signed_tx);
 ```
 
@@ -241,7 +236,7 @@ indeed gets rejected:
 ```typescript
 console.log("Signing a transaction to a different receiver must be rejected");
 try {
-  await session.signEvm(secpKey, {
+  await roleKey.signEvm({
     chain_id: 1,
     tx: <any>{
       ...eth1Request.tx,
@@ -259,16 +254,18 @@ try {
 > `Key::appendPolicy` instead of `Key::setPolicy` to append to
 > existing policies.
 
+
+
 ### Sign a raw blob
 
-The `SignerSession` class exposes the `signBlob` method, which signs
+The `CubeSignerClient` class exposes the `signBlob` method, which signs
 an arbitrary (raw, uninterpreted) bag of bytes with a given key. This
 operation, however, is not permitted by default; it is permanently
 disabled for `BLS` keys, and for other key types it can be enabled by
 attaching an `"AllowRawBlobSigning"` policy:
 
 ```typescript
-// Create a new Ed25519 key (e.g., for Cardano) and add it to our session role
+// Create a new Ed25519 key (e.g., for Cardano) and add it to our roleClient's role
 const edKey = await org.createKey(cs.Ed25519.Cardano);
 await role.addKey(edKey);
 console.log(`Created '${await edKey.type()}' key ${edKey.id} and added it to role ${role.id}`);
@@ -276,11 +273,12 @@ console.log(`Created '${await edKey.type()}' key ${edKey.id} and added it to rol
 // Sign raw blobs with our new ed key and the secp we created before
 for (const key of [edKey, secpKey]) {
   console.log(`Confirming that raw blob with ${await key.type()} is rejected by default`);
+  const roleKey = new cs.Key(roleClient, key.cached);
   const blobReq = <cs.BlobSignRequest>{
     message_base64: "L1kE9g59xD3fzYQQSR7340BwU9fGrP6EMfIFcyX/YBc=",
   };
   try {
-    await session.signBlob(key, blobReq);
+    await roleKey.signBlob(blobReq);
     assert(false, "Must be rejected by policy");
   } catch (e) {
     assert(`${e}`.includes("Raw blob signing not allowed"));
@@ -288,7 +286,7 @@ for (const key of [edKey, secpKey]) {
 
   console.log("Signing raw blob after adding 'AllowRawBlobSigning' policy");
   await key.appendPolicy(["AllowRawBlobSigning"]);
-  const blobSig = await session.signBlob(key, blobReq);
+  const blobSig = await roleKey.signBlob(blobReq);
   console.log(blobSig.data());
   assert(blobSig.data().signature);
 }
@@ -300,46 +298,68 @@ for (const key of [edKey, secpKey]) {
 Trying to sign an invalid message with a secp key will fail with
 `400 Bad Request` saying `Signature scheme: InvalidMessage`.
 
-### Load a signer session
+## Session Management
+
+In the above examples we've used 3 different sessions:
+
+1. A management session that we created using the CLI
+2. A signing session that we created using (1)
+3. A role session that we created used (1)
 
-If signing is all that your application needs to do, you can instantiate a
-`SignerSession` directly from a signer session token, without ever needing a
-management session.
+All `CubeSignerClient`s require a valid session in order to operate. In this section
+we'll dive into the specifics of sessions in the TypeScript SDK.
 
-First, get an existing token for a signer session:
+### Loading from disk
+If you already have an active session in `cs` (the CubeSigner CLI), you can
+load it into the TypeScript SDK with a simple helper (as we did earlier).
 
 ```typescript
-const token = await sessionStorage.retrieve();
-// alternatively, save this object to a file
+await cs.CubeSignerClient.create(defaultManagementSessionManager())
 ```
 
-or generate a new one from the command line:
+Or we can use the CLI to create our own session explicitly for our JavaScript client:
 
 ```bash
-cs token create --role-id $ROLE_ID --purpose MyPurpose --output json
+cs session create --role-id $ROLE_ID --scope sign-all --output json > session.json
 ```
 
-Next, create a `MemorySessionStorage` containing the previously
-exported signer token, and just load the session from it.
-
+Then we can load it like so:
 ```typescript
-const signerSession = await cs.SignerSession.loadSignerSession(
-  // alternatively, load 'token' from file or environment variable
-  new cs.MemorySessionStorage(token),
-);
+try {
+  await cs.CubeSignerClient.create(new JsonFileSessionManager("./session.json"));
+} catch {
+  console.error("Unable to find file")
+}
 ```
 
-Finally, use the new signer session to sign a transaction. To specify
-the signing key, you can pass its "material id" as a plain string:
+### Loading from Memory
+If you already have the session information (`SessionData` in Typescript) in memory, you can
+load that directly into a client.
 
 ```typescript
-console.log("Signing transaction using imported signer session");
-const secpKeyStr: string = secpKey.materialId;
-sig = await signerSession.signEvm(secpKeyStr, eth1Request);
-console.log(sig.data());
-assert(sig.data().rlp_signed_tx);
+// Get the session data we want to use with the client
+const sessionData: cs.SessionData = await role.createSession("readme");
+await cs.CubeSignerClient.create(new cs.MemorySessionManager(sessionData))
+// or, for short
+await cs.CubeSignerClient.create(sessionData)
 ```
 
+> [!WARNING]  
+> Clients created this way will automatically refresh the session. If you try to use this session with another client, they will both try to refresh, leading to failures.
+
+### Managers, Storage and Refreshing
+
+As we've seen in the examples above, all `CubeSignerClient`s are constructed using the `create` constructor. The `create`
+constructor accepts either raw `SessionData` or a `SessionManager`. So far we've seen two different session managers:
+ - `JsonFileSessionManager`
+ - `MemorySessionManager`
+
+These managers are responsible for keeping your session tokens refreshed
+and (optionally) persisted. Whenever your session tokens are refreshed,
+`JsonFileSessionManager` will write the new tokens to disk.
+
+More complex managers can be written by implementing the `SessionManager` interface.
+
 ### Create a session for an OIDC user
 
 CubeSigner supports the [OIDC](https://openid.net/developers/how-connect-works/)
@@ -360,7 +380,7 @@ assert(oidcToken);
 Before we can use the OIDC token for authentication, we must add an org policy
 to allow the particular issuer/audience pair from the token.
 
-```ts
+```
 const oldOrgPolicy = await org.policy();
 const oidcPayload = JSON.parse(atob(oidcToken.split(".")[1].replace(/-/g, "+").replace(/_/g, "/")));
 const oidcAuthSourcesPolicy = {
@@ -372,22 +392,16 @@ console.log("Setting org policy", oidcAuthSourcesPolicy);
 await org.setPolicy([oidcAuthSourcesPolicy]);
 ```
 
-Finally, exchange the OIDC token for either a _signer_ session (i.e., an instance
-of `SignerSession`, required by all signing endpoints, e.g., `signEvm`)
+Finally, exchange the OIDC token for a session.
 
 ```typescript
-const oidcSession = new cs.SignerSession(
-  // we'll use this session for both signing and approving MFA request, hence the following scopes
-  await cubesigner.oidcAuth(oidcToken, ["manage:mfa", "sign:*"]),
+const oidcSessionResp = await cs.CubeSignerClient.createOidcSession(
+  cubesigner.env,
+  org.id, // org id to log into
+  oidcToken,
+  ["manage:mfa", "sign:*"] // scopes for the session 
 );
-```
-
-or a _management_ session (i.e., and instance of `CubeSigner`,
-required by all management endpoints, e.g., retrieving user
-information, configuring user MFA methods, etc.).
-
-```typescript
-const oidcCubeSigner = new cs.CubeSignerClient(await cubesigner.oidcAuth(oidcToken, ["manage:*"]));
+const oidcClient = await cs.CubeSignerClient.create(oidcSessionResp.data());
 ```
 
 > **Info**
@@ -398,7 +412,7 @@ const oidcCubeSigner = new cs.CubeSignerClient(await cubesigner.oidcAuth(oidcTok
 
 ### Set up TOTP for a user
 
-To manage a user we need a management session bound to that user. It
+To manage a user we need a session bound to that user. It
 doesn't matter if that user is native to CubeSigner or a third-party
 OIDC user. For that purpose, in this section we are going to use the
 previously created `oidcCubeSigner` instance.
@@ -408,12 +422,12 @@ TOTP reset procedure.
 
 ```typescript
 console.log(`Setting up TOTP for user ${me.email}`);
-let totpResetResp = await oidcCubeSigner.resetTotpStart();
+let totpResetResp = await oidcClient.resetTotp();
 ```
 
 If the user has already configured TOTP (or any other form of MFA),
 this response will require multi factor authentication. In that case,
-for example, call `approveTotp` and provide the code for the existing
+for example, call `totpApprove` and provide the code for the existing
 TOTP to proceed:
 
 ```typescript
@@ -423,7 +437,7 @@ let totpSecret = process.env["CS_USER_TOTP_SECRET"]!;
 if (totpResetResp.requiresMfa()) {
   console.log("Resetting TOTP requires MFA");
   const code = authenticator.generate(totpSecret);
-  totpResetResp = await totpResetResp.approveTotp(oidcSession, code);
+  totpResetResp = await totpResetResp.totpApprove(oidcClient, code);
   assert(!totpResetResp.requiresMfa());
   console.log("MFA approved using existing TOTP");
 }
@@ -437,7 +451,7 @@ create an authenticator for automated testing.
 
 ```typescript
 const totpChallenge = totpResetResp.data();
-assert(totpChallenge.totpUrl);
+assert(totpChallenge.url);
 ```
 
 To complete the challenge, we must call `resetTotpComplete` and
@@ -455,14 +469,14 @@ is generating the correct code by calling `verifyTotp`
 ```typescript
 console.log(`Verifying current TOTP code`);
 let code = authenticator.generate(totpSecret);
-await oidcCubeSigner.verifyTotp(code);
+await oidcClient.verifyTotp(code);
 ```
 
 We can also check that the user's profile now indeed includes `Totp`
 as one of the configured MFA factors.
 
 ```typescript
-const mfa = (await oidcCubeSigner.aboutMe()).mfa;
+const mfa = (await oidcClient.user()).mfa;
 console.log("Configured MFA types", mfa);
 assert(mfa.map((m) => m.type).includes("totp"));
 ```
@@ -486,18 +500,19 @@ receive `202 Accepted` instead of `200 Ok`. The response body contains
 an MFA ID, which we can use to fetch and inspect the associated MFA
 request, see how many approvals it requires, what kind of MFA factors
 it allows, etc. Instead, since we know that our key requires TOTP, we
-can just call `approveTotp` on the response and pass the current TOTP
+can just call `totpApprove` on the response and pass the current TOTP
 code to it; if the code is correct, the call will succeed
 and return the signature.
 
 ```typescript
 console.log(`Signing a transaction now requires TOTP`);
-let resp = await oidcSession.signEvm(secpKeyStr, eth1Request);
+const oidcKey = new cs.Key(oidcClient, secpKey.cached);
+let resp = await oidcKey.signEvm(eth1Request);
 assert(resp.requiresMfa());
 
 console.log(`Approving with TOTP code`);
 code = authenticator.generate(totpSecret);
-resp = await resp.approveTotp(oidcSession, code);
+resp = await resp.totpApprove(oidcClient, code);
 assert(!resp.requiresMfa());
 console.log(resp.data());
 assert(resp.data().rlp_signed_tx);
@@ -510,7 +525,8 @@ we created.
 
 ```typescript
 console.log("Cleaning up");
-await session.sessionMgr.revoke();
+await signingClient.revokeSession();
+await roleClient.revokeSession();
 await role.delete();
 ```
 

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cubist-labs/cubesigner-sdk",
-    "version": "0.3.29",
+    "version": "0.4.24-0",
     "description": "CubeSigner TypeScript SDK",
     "license": "MIT OR Apache-2.0",
     "author": "Cubist, Inc.",
@@ -27,7 +27,7 @@
         "typedoc": "typedoc"
     },
     "dependencies": {
-        "openapi-fetch": "0.6.1"
+        "openapi-fetch": "0.8.2"
     },
     "optionalDependencies": {
         "@hpke/core": "^1.2.7"
@@ -37,5 +37,8 @@
     },
     "directories": {
         "test": "test"
+    },
+    "devDependencies": {
+        "openapi-typescript-helpers": "^0.0.7"
     }
 }

package/dist/cjs/src/api.d.ts

@@ -332,10 +332,9 @@ export declare class CubeSignerApi {
      * List all keys in the org.
      * @param {KeyType?} type Optional key type to filter list for.
      * @param {PageOpts?} page Pagination options. Defaults to fetching the entire result set.
-     * @param {string?} owner Optional key owner to filter list for.
      * @return {Paginator<ListKeysResponse, KeyInfoApi>} Paginator for iterating over keys.
      */
-    keysList(type?: KeyType, page?: PageOpts, owner?: string): Paginator<ListKeysResponse, KeyInfoApi>;
+    keysList(type?: KeyType, page?: PageOpts): Paginator<ListKeysResponse, KeyInfoApi>;
     /**
      * Create a new role.
      *