refactor: align object names with KERIpy and add function docs (#307)

* refactor: align object names with KERIpy and add function docs

* docs: add key management and siginput docs

* fix: npm audit failure fix; some tsconfig excludes

* docs: Add PubPath docs

* docs: correct Salter constructer args docs

* refactor: change key state interface names and add docs

Author: kentbull

README.md

@@ -81,7 +81,7 @@ The integration tests depends on a local instance of KERIA, vLEI-Server and Witn
 docker compose up --wait
 ```
 
-If successful, it should print someting like this:
+If successful, it should print something like this:
 
 ```bash
 $ docker compose up --wait

docker-compose.yaml

@@ -21,7 +21,7 @@ services:
             - 7723:7723
 
     keria:
-        image: ${KERIA_IMAGE:-weboftrust/keria}:${KERIA_IMAGE_TAG:-0.2.0-dev6}
+        image: ${KERIA_IMAGE:-weboftrust/keria}:${KERIA_IMAGE_TAG:-0.2.0-rc1}
         environment:
             KERI_AGENT_CORS: 1
             <<: *python-env

examples/integration-scripts/modules/bip39_shim.ts

@@ -1,7 +1,14 @@
 import { mnemonicToSeedSync, generateMnemonic } from 'bip39';
-import { Diger, Signer, MtrDex, Keeper, KeeperResult, Algos } from 'signify-ts';
+import {
+    Diger,
+    Signer,
+    MtrDex,
+    IdentifierManager,
+    IdentifierManagerResult,
+    Algos,
+} from 'signify-ts';
 
-export class BIP39Shim implements Keeper {
+export class BIP39Shim implements IdentifierManager {
     private icount: number;
     private ncount: number;
     private dcode: string | undefined;
@@ -49,7 +56,7 @@ export class BIP39Shim implements Keeper {
         return keys;
     }
 
-    async incept(transferable: boolean): Promise<KeeperResult> {
+    async incept(transferable: boolean): Promise<IdentifierManagerResult> {
         const signers = this.keys(this.icount, this.kidx, transferable);
         const verfers = signers.map((signer) => signer.verfer.qb64);
 
@@ -70,7 +77,7 @@ export class BIP39Shim implements Keeper {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         count: any, //number,
         transferable: boolean
-    ): Promise<KeeperResult> {
+    ): Promise<IdentifierManagerResult> {
         const signers = this.keys(
             this.ncount,
             this.kidx + this.icount,

examples/integration-scripts/multisig-join.test.ts

@@ -164,6 +164,7 @@ describe('multisig-join', () => {
             waitOperation(client3, opOobi5),
         ]);
 
+        // rotate single sig
         const [rotateResult1, rotateResult2] = await Promise.all([
             client1.identifiers().rotate(nameMember1),
             client2.identifiers().rotate(nameMember2),
@@ -309,7 +310,7 @@ describe('multisig-join', () => {
             .exchanges()
             .send(
                 nameMember1,
-                nameMultisig,
+                'multisig',
                 aid1,
                 '/multisig/rot',
                 { gid: serder1.pre, smids, rmids },

examples/integration-scripts/utils/multisig-utils.ts

@@ -9,7 +9,7 @@ import signify, {
     messagize,
 } from 'signify-ts';
 import { getStates, waitAndMarkNotification } from './test-util';
-import { HabState } from '../../../src/keri/core/state';
+import { HabState } from '../../../src/keri/core/keyState';
 import assert from 'assert';
 
 export interface AcceptMultisigInceptArgs {

examples/integration-scripts/utils/test-util.ts

@@ -9,7 +9,7 @@ import signify, {
     Tier,
 } from 'signify-ts';
 import { RetryOptions, retry } from './retry';
-import { HabState } from '../../../src/keri/core/state';
+import { HabState } from '../../../src/keri/core/keyState';
 import assert from 'assert';
 import { resolveEnvironment } from './resolve-env';
 

package-lock.json

@@ -39,6 +39,6 @@ export * from './keri/core/signer';
 export * from './keri/core/tholder';
 export * from './keri/core/utils';
 export * from './keri/core/verfer';
-export * from './keri/core/state';
+export * from './keri/core/keyState';
 
 export * from './keri/end/ending';

src/exports.ts

@@ -1,13 +1,13 @@
 import { Tier } from '../core/salter';
 import { Algos } from '../core/manager';
 import { incept, interact, reply, rotate } from '../core/eventing';
-import { b, Ilks, Serials, Versionage } from '../core/core';
+import { b, Ilks, Serials, Vrsn_1_0 } from '../core/core';
 import { Tholder } from '../core/tholder';
 import { MtrDex } from '../core/matter';
 import { Serder } from '../core/serder';
 import { parseRangeHeaders } from '../core/httping';
-import { KeyManager } from '../core/keeping';
-import { HabState } from '../core/state';
+import { IdentifierManagerFactory } from '../core/keeping';
+import { HabState } from '../core/keyState';
 
 /** Arguments required to create an identfier */
 export interface CreateIdentiferArgs {
@@ -63,7 +63,7 @@ export interface IdentifierDeps {
         headers?: Headers
     ): Promise<Response>;
     pidx: number;
-    manager: KeyManager | null;
+    manager: IdentifierManagerFactory | null;
 }
 
 /**
@@ -225,7 +225,7 @@ export class Identifier {
                 wits: wits,
                 cnfg: [],
                 data: data,
-                version: Versionage,
+                version: Vrsn_1_0,
                 kind: Serials.JSON,
                 code: dcode,
                 intive: false,
@@ -240,7 +240,7 @@ export class Identifier {
                 wits: wits,
                 cnfg: [],
                 data: data,
-                version: Versionage,
+                version: Vrsn_1_0,
                 kind: Serials.JSON,
                 code: dcode,
                 intive: false,

src/keri/app/aiding.ts

@@ -1,6 +1,6 @@
 import { Authenticater } from '../core/authing';
 import { HEADER_SIG_TIME } from '../core/httping';
-import { ExternalModule, KeyManager } from '../core/keeping';
+import { ExternalModule, IdentifierManagerFactory } from '../core/keeping';
 import { Tier } from '../core/salter';
 
 import { Identifier } from './aiding';
@@ -30,15 +30,18 @@ class State {
     }
 }
 
-/** SignifyClient */
+/**
+ * An in-memory key manager that can connect to a KERIA Agent and use it to
+ * receive messages and act as a proxy for multi-signature operations and delegation operations.
+ */
 export class SignifyClient {
     public controller: Controller;
     public url: string;
     public bran: string;
     public pidx: number;
     public agent: Agent | null;
     public authn: Authenticater | null;
-    public manager: KeyManager | null;
+    public manager: IdentifierManagerFactory | null;
     public tier: Tier;
     public bootUrl: string;
     public exteralModules: ExternalModule[];
@@ -147,7 +150,7 @@ export class SignifyClient {
         if (this.controller.serder.ked.s == 0) {
             await this.approveDelegation();
         }
-        this.manager = new KeyManager(
+        this.manager = new IdentifierManagerFactory(
             this.controller.salter,
             this.exteralModules
         );

src/keri/app/clienting.ts

@@ -5,7 +5,7 @@ import { Diger } from '../core/diger';
 import { incept, rotate, interact } from '../core/eventing';
 import { Serder } from '../core/serder';
 import { Tholder } from '../core/tholder';
-import { Ilks, b, Serials, Versionage } from '../core/core';
+import { Ilks, b, Serials, Vrsn_1_0 } from '../core/core';
 import { Verfer } from '../core/verfer';
 import { Encrypter } from '../core/encrypter';
 import { Decrypter } from '../core/decrypter';
@@ -89,17 +89,67 @@ export class Agent {
  * signing key represents the Account for the client on the agent
  */
 export class Controller {
+    /*
+    The bran is the combination of the first 21 characters of the passcode passed in prefixed with 'A' and '0A'.
+    Looks like: '0A' + 'A' + 'thisismysecretkeyseed'
+    Or: "0AAthisismysecretkeyseed"
+
+    This is interpreted as encoded Base64URLSafe characters when used as the salt for key generation.
+     */
     private bran: string;
+    /**
+     * The stem is the prefix for the stretched input bytes the controller's cryptographic
+     * key pairs are derived from.
+     */
     public stem: string;
+    /**
+     * The security tier for the identifiers created by this Controller.
+     */
     public tier: Tier;
+    /**
+     * The rotation index used during key generation by this Controller.
+     */
     public ridx: number;
+    /**
+     * The salter is a cryptographic salt used to derive the controller's cryptographic key pairs
+     * and is deterministically derived from the bran and the security tier.
+     */
     public salter: any;
+    /**
+     * The current signing key used to sign requests for this controller.
+     */
     public signer: any;
+    /**
+     * The next signing key of which a digest is committed to in an establishment event (inception or rotation) to become the
+     * signing key after the next rotation.
+     * @private
+     */
     private nsigner: any;
+    /**
+     * Either the current establishment event, inception or rotation, or the interaction event used for delegation approval.
+     */
     public serder: Serder;
+    /**
+     * Current public keys formatted in fully-qualified Base64.
+     * @private
+     */
     private keys: string[];
+    /**
+     * Digests of the next public keys formatted in fully-qualified Base64.
+     */
     public ndigs: string[];
 
+    /**
+     * Creates a Signify Controller starting at key index 0 that generates keys in
+     * memory based on the provided seed, or bran, the tier, and the rotation index.
+     *
+     * The rotation index is used as follows:
+     *
+     * @param bran
+     * @param tier
+     * @param ridx
+     * @param state
+     */
     constructor(
         bran: string,
         tier: Tier,
@@ -110,6 +160,13 @@ export class Controller {
         this.stem = 'signify:controller';
         this.tier = tier;
         this.ridx = ridx;
+        const codes = undefined; // Defines the types of seeds that the SaltyCreator will create. Defaults to undefined.
+        const keyCount = 1; // The number of keys to create. Defaults to 1.
+        const transferable = true; // Whether the keys are transferable. Defaults to true.
+        const code = MtrDex.Ed25519_Seed; // The type  cryptographic seed to create by default when not overiddeen by "codes".
+        const pidx = 0; // The index of this identifier prefix of all managed identifiers created for this SignifyClient Controller. Defaults to 0.
+        const kidx = 0; // The overall starting key index for the first key this rotation set of keys. This is not a local index to this set of keys but an index in the overall set of keys for all keys in this sequence.
+        // Defaults to 0. Multiply rotation index (ridx) times key count to get the overall key index.
 
         this.salter = new Salter({ qb64: this.bran, tier: this.tier });
 
@@ -119,30 +176,34 @@ export class Controller {
             this.stem
         );
 
+        // Creates the first key pair used to sign the inception event.
+        // noinspection UnnecessaryLocalVariableJS
+        const initialKeyIndex = ridx; // will be zero for inception
         this.signer = creator
             .create(
-                undefined,
-                1,
-                MtrDex.Ed25519_Seed,
-                true,
-                0,
-                this.ridx,
-                0,
-                false
+                codes,
+                keyCount,
+                code,
+                transferable,
+                pidx,
+                initialKeyIndex,
+                kidx
             )
-            .signers.pop();
+            .signers.pop(); // assumes only one key pair is created because keyCount is 1
+
+        // Creates the second key pair which a digest of the public key is committed to in the inception event.
+        const nextKeyIndex = ridx + 1;
         this.nsigner = creator
             .create(
-                undefined,
-                1,
-                MtrDex.Ed25519_Seed,
-                true,
-                0,
-                this.ridx + 1,
-                0,
-                false
+                codes,
+                keyCount,
+                code,
+                transferable,
+                pidx,
+                nextKeyIndex,
+                kidx
             )
-            .signers.pop();
+            .signers.pop(); // assumes only one key pair is created because keyCount is 1
         this.keys = [this.signer.verfer.qb64];
         this.ndigs = [
             new Diger({ code: MtrDex.Blake3_256 }, this.nsigner.verfer.qb64b)
@@ -173,7 +234,7 @@ export class Controller {
             dig: this.serder.ked['d'],
             sn: sn,
             data: [anchor],
-            version: Versionage,
+            version: Vrsn_1_0,
             kind: Serials.JSON,
         });
         return [this.signer.sign(this.serder.raw, 0).qb64];