signify-ts 0.2.1 → 0.3.0-rc1

package/README.md

@@ -9,7 +9,7 @@ Project Name: signify-ts
 
 ## Signify - KERI Signing at the Edge
 
-Of the five functions in a KERI agent, 
+Of the five functions in a KERI agent,
 
 1. Key generation
 2. Encrypted key storage
@@ -19,20 +19,18 @@ Of the five functions in a KERI agent,
 
 Signify-TS splits off two, key generation and event signing into a TypeScript library to provide "signing at the edge".
 It accomplishes this by using [libsodium](https://doc.libsodium.org/) to generate ed25519 key pairs for signing and x25519 key pairs for encrypting the
-private keys, next public keys and salts used to generate the private keys.  The encrypted private key and salts are then stored on a
-remote cloud agent that never has access to the decryption keys.  New key pair sets (current and next) will be generated 
+private keys, next public keys and salts used to generate the private keys. The encrypted private key and salts are then stored on a
+remote cloud agent that never has access to the decryption keys. New key pair sets (current and next) will be generated
 for inception and rotation events with only the public keys and blake3 hash of the next keys made available to the agent.
 
 The communication protocol between a Signify client and [KERI](https://github.com/WebOfTrust/keri) agent will encode all cryptographic primitives as CESR base64
-encoded strings for the initial implementation.  Support for binary CESR can be added in the future.
-
+encoded strings for the initial implementation. Support for binary CESR can be added in the future.
 
 ### Environment Setup
 
 The code is built using Typescript and running code locally requires a Mac or Linux OS.
 
--   Install [Node.js](https://nodejs.org)    
-
+-   Install [Node.js](https://nodejs.org)
 
 -   Install dependencies:
     ```bash
@@ -42,10 +40,31 @@ The code is built using Typescript and running code locally requires a Mac or Li
 Typescript source files needs to be transpiled before running scripts or integration tests
 
 -   Build:
+
     ```bash
     npm run build
     ```
 
+-   ready() must be called before library is useable. Example minimum viable client code.
+
+    ```javascript
+    import { randomPasscode, ready, SignifyClient, Tier } from 'signify-ts';
+
+    await ready();
+
+    const bran = randomPasscode();
+    const url = 'http://127.0.0.1:3901';
+    const boot_url = 'http://127.0.0.1:3903';
+    const actualSignifyClient = new SignifyClient(
+        url,
+        bran,
+        Tier.low,
+        boot_url
+    );
+
+    console.log(actualSignifyClient);
+    ```
+
 ### Unit testing
 
 To run unit tests
@@ -59,22 +78,34 @@ npm test
 The integration tests depends on a local instance of KERIA, vLEI-Server and Witness Demo. These are specified in the [Docker Compose](./docker-compose.yaml) file. To start the dependencies, use docker compose:
 
 ```bash
-docker compose up deps
+docker compose up --wait
 ```
 
 If successful, it should print someting like this:
 
 ```bash
-$ docker compose up deps
-[+] Running 5/4
+$ docker compose up --wait
+[+] Running 4/4
  ✔ Network signify-ts_default           Created                                           0.0s
- ✔ Container signify-ts-vlei-server-1   Created                                           0.1s
- ✔ Container signify-ts-keria-1         Created                                           0.1s
- ✔ Container signify-ts-witness-demo-1  Created                                           0.1s
- ✔ Container signify-ts-deps-1          Created                                           0.0s
-Attaching to signify-ts-deps-1
-signify-ts-deps-1  | Dependencies running
-signify-ts-deps-1 exited with code 0
+ ✔ Container signify-ts-vlei-server-1   Healthy                                           5.7s
+ ✔ Container signify-ts-keria-1         Healthy                                           6.2s
+ ✔ Container signify-ts-witness-demo-1  Healthy                                           6.2s
+```
+
+It is possible to change the keria image by using environment variables. For example, to use weboftrust/keria:0.1.3, do:
+
+```bash
+export KERIA_IMAGE_TAG=0.1.3
+docker compose pull
+docker compose up --wait
+```
+
+To use another repository, you can do:
+
+```bash
+export KERIA_IMAGE=gleif/keria
+docker compose pull
+docker compose up --wait
 ```
 
 **Important!** The integration tests runs on the build output in `dist/` directory. Make sure to run build before running the integration tests.
@@ -103,19 +134,10 @@ TEST_ENVIRONMENT=local npx jest examples/integration-scripts/credentials.test.ts
 
 This changes the discovery urls to use `localhost` instead of the hostnames inside the docker network.
 
-### Old integration scripts
-
-To run any of the old integration scripts that has not yet been converted to an integration test. Use `ts-node-esm`
-
-```bash
-npx ts-node-esm examples/integration-scripts/challenge.ts
-```
-
 # Diagrams
 
 Account Creation Workflow
 
 ![Account Creation](/diagrams/account-creation-workflow.png)
 
-
 ![Account Creation Webpage](/diagrams/account-creation-webpage-workflow.png)

package/dist/exports.d.ts

@@ -1,5 +1,4 @@
 export * from './ready';
-export * from './math';
 export * from './keri/app/habery';
 export * from './keri/app/controller';
 export * from './keri/app/aiding';
@@ -37,4 +36,5 @@ 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/end/ending';

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import './buffer-polyfill';
 import * as exp from './exports';
 export * from './exports';
 export default exp;

package/dist/keri/app/aiding.d.ts

@@ -2,6 +2,7 @@ import { Tier } from '../core/salter';
 import { Algos } from '../core/manager';
 import { Serder } from '../core/serder';
 import { KeyManager } from '../core/keeping';
+import { HabState } from '../core/state';
 /** Arguments required to create an identfier */
 export interface CreateIdentiferArgs {
     transferable?: boolean;
@@ -19,9 +20,9 @@ export interface CreateIdentiferArgs {
     rstates?: any[];
     prxs?: any[];
     nxts?: any[];
-    mhab?: any;
-    keys?: any[];
-    ndigs?: any[];
+    mhab?: HabState;
+    keys?: string[];
+    ndigs?: string[];
     bran?: string;
     count?: number;
     ncount?: number;
@@ -51,6 +52,12 @@ export interface IdentifierDeps {
     pidx: number;
     manager: KeyManager | null;
 }
+/**
+ * Updatable information for a managed identifier
+ */
+export interface IdentifierInfo {
+    name: string;
+}
 /** Identifier */
 export declare class Identifier {
     client: IdentifierDeps;
@@ -70,10 +77,18 @@ export declare class Identifier {
     /**
      * Get information for a managed identifier
      * @async
-     * @param {string} name Name or alias of the identifier
-     * @returns {Promise<any>} A promise to the identifier information
+     * @param {string} name Prefix or alias of the identifier
+     * @returns {Promise<HabState>} A promise to the identifier information
      */
-    get(name: string): Promise<any>;
+    get(name: string): Promise<HabState>;
+    /**
+     * Update managed identifier
+     * @async
+     * @param {string} name Prefix or alias of the identifier
+     * @param {IdentifierInfo} info Information to update for the given identifier
+     * @returns {Promise<HabState>} A promise to the identifier information after updating
+     */
+    update(name: string, info: IdentifierInfo): Promise<HabState>;
     /**
      * Create a managed identifier
      * @async
@@ -85,11 +100,16 @@ export declare class Identifier {
     /**
      * Generate an interaction event in a managed identifier
      * @async
-     * @param {string} name Name or alias of the identifier
+     * @param {string} name Prefix or alias of the identifier
      * @param {any} [data] Option data to be anchored in the interaction event
      * @returns {Promise<EventResult>} A promise to the interaction event result
      */
     interact(name: string, data?: any): Promise<EventResult>;
+    createInteract(name: string, data?: any): Promise<{
+        serder: any;
+        sigs: any;
+        jsondata: any;
+    }>;
     /**
      * Generate a rotation event in a managed identifier
      * @param {string} name Name or alias of the identifier
@@ -130,8 +150,8 @@ export declare class Identifier {
 export declare class EventResult {
     private readonly _serder;
     private readonly _sigs;
-    private readonly promise;
-    constructor(serder: Serder, sigs: string[], promise: Promise<Response> | Response);
+    private readonly response;
+    constructor(serder: Serder, sigs: string[], response: Response);
     get serder(): Serder;
     get sigs(): string[];
     op(): Promise<any>;

package/dist/keri/app/clienting.d.ts

@@ -1,15 +1,16 @@
-import { Agent, Controller } from './controller';
-import { Tier } from '../core/salter';
 import { Authenticater } from '../core/authing';
 import { ExternalModule, KeyManager } from '../core/keeping';
+import { Tier } from '../core/salter';
 import { Identifier } from './aiding';
 import { Contacts, Challenges } from './contacting';
-import { Oobis, Operations, KeyEvents, KeyStates } from './coring';
+import { Agent, Controller } from './controller';
+import { Oobis, Operations, KeyEvents, KeyStates, Config } from './coring';
 import { Credentials, Ipex, Registries, Schemas } from './credentialing';
-import { Notifications } from './notifying';
+import { Delegations } from './delegating';
 import { Escrows } from './escrowing';
-import { Groups } from './grouping';
 import { Exchanges } from './exchanging';
+import { Groups } from './grouping';
+import { Notifications } from './notifying';
 declare class State {
     agent: any | null;
     controller: any | null;
@@ -66,16 +67,20 @@ export declare class SignifyClient {
      */
     fetch(path: string, method: string, data: any, extraHeaders?: Headers): Promise<Response>;
     /**
-     * Fetch a resource from from an external URL with headers signed by an AID
+     * Create a Signed Request to fetch a resource from an external URL with headers signed by an AID
      * @async
-     * @param {string} url URL of the resource
-     * @param {string} path Path to the resource
-     * @param {string} method HTTP method
-     * @param {any} data Data to be sent in the body of the resource
      * @param {string} aidName Name or alias of the AID to be used for signing
-     * @returns {Promise<Response>} A promise to the result of the fetch
-     */
-    signedFetch(url: string, path: string, method: string, data: any, aidName: string): Promise<Response>;
+     * @param {string} url URL of the requested resource
+     * @param {RequestInit} req Request options should include:
+     *     - method: HTTP method
+     *     - data Data to be sent in the body of the resource.
+     *              If the data is a CESR JSON string then you should also set contentType to 'application/json+cesr'
+     *              If the data is a FormData object then you should not set the contentType and the browser will set it to 'multipart/form-data'
+     *              If the data is an object then you should use JSON.stringify to convert it to a string and set the contentType to 'application/json'
+     *     - contentType Content type of the request.
+     * @returns {Promise<Request>} A promise to the created Request
+     */
+    createSignedRequest(aidName: string, url: string, req: RequestInit): Promise<Request>;
     /**
      * Approve the delegation of the client AID to the KERIA agent
      * @async
@@ -178,5 +183,15 @@ export declare class SignifyClient {
      * @returns {Exchanges}
      */
     exchanges(): Exchanges;
+    /**
+     * Get delegations resource
+     * @returns {Delegations}
+     */
+    delegations(): Delegations;
+    /**
+     * Get agent config resource
+     * @returns {Config}
+     */
+    config(): Config;
 }
 export {};

package/dist/keri/app/contacting.d.ts

@@ -1,5 +1,14 @@
 import { SignifyClient } from './clienting';
 import { Operation } from './coring';
+export interface Contact {
+    alias: string;
+    oobi: string;
+    id: string;
+    [key: string]: unknown;
+}
+export interface ContactInfo {
+    [key: string]: unknown;
+}
 /**
  * Contacts
  */
@@ -18,29 +27,29 @@ export declare class Contacts {
      * @param {string} [filterValue] Optional field value to filter contacts
      * @returns {Promise<any>} A promise to the list of contacts
      */
-    list(group?: string, filterField?: string, filterValue?: string): Promise<any>;
+    list(group?: string, filterField?: string, filterValue?: string): Promise<Contact[]>;
     /**
      * Get a contact
      * @async
      * @param {string} pre Prefix of the contact
      * @returns {Promise<any>} A promise to the contact
      */
-    get(pre: string): Promise<any>;
+    get(pre: string): Promise<Contact>;
     /**
      * Add a contact
      * @async
-     * @param {string} pre Prefix of the contact
-     * @param {any} info Information about the contact
-     * @returns {Promise<any>} A promise to the result of the addition
+     * @param pre Prefix of the contact
+     * @param info Information about the contact
+     * @returns A promise to the result of the addition
      */
-    add(pre: string, info: any): Promise<any>;
+    add(pre: string, info: ContactInfo): Promise<Contact>;
     /**
      * Delete a contact
      * @async
      * @param {string} pre Prefix of the contact
-     * @returns {Promise<any>} A promise to the result of the deletion
+     * @returns {Promise<void>}
      */
-    delete(pre: string): Promise<any>;
+    delete(pre: string): Promise<void>;
     /**
      * Update a contact
      * @async
@@ -48,7 +57,10 @@ export declare class Contacts {
      * @param {any} info Updated information about the contact
      * @returns {Promise<any>} A promise to the result of the update
      */
-    update(pre: string, info: any): Promise<any>;
+    update(pre: string, info: ContactInfo): Promise<Contact>;
+}
+export interface Challenge {
+    words: string[];
 }
 /**
  * Challenges
@@ -66,27 +78,27 @@ export declare class Challenges {
      * @param {number} strength Integer representing the strength of the challenge. Typically 128 or 256
      * @returns {Promise<any>} A promise to the list of random words
      */
-    generate(strength?: number): Promise<any>;
+    generate(strength?: number): Promise<Challenge>;
     /**
      * Respond to a challenge by signing a message with the list of words
      * @async
-     * @param {string} name Name or alias of the identifier
-     * @param {string} recipient Prefix of the recipient of the response
-     * @param {Array<string>} words List of words to embed in the signed response
-     * @returns {Promise<Response>} A promise to the result of the response
+     * @param name Name or alias of the identifier
+     * @param recipient Prefix of the recipient of the response
+     * @param words List of words to embed in the signed response
+     * @returns A promise to the result of the response
      */
-    respond(name: string, recipient: string, words: string[]): Promise<Response>;
+    respond(name: string, recipient: string, words: string[]): Promise<unknown>;
     /**
      * Ask Agent to verify a given sender signed the provided words
-     * @param {string} source Prefix of the identifier that was challenged
-     * @param {Array<string>} words List of challenge words to check for
+     * @param source Prefix of the identifier that was challenged
+     * @param words List of challenge words to check for
      * @returns A promise to the long running operation
      */
     verify(source: string, words: string[]): Promise<Operation<unknown>>;
     /**
      * Mark challenge response as signed and accepted
-     * @param {string} source Prefix of the identifier that was challenged
-     * @param {string} said qb64 AID of exn message representing the signed response
+     * @param source Prefix of the identifier that was challenged
+     * @param said qb64 AID of exn message representing the signed response
      * @returns {Promise<Response>} A promise to the result
      */
     responded(source: string, said: string): Promise<Response>;

package/dist/keri/app/coring.d.ts

@@ -34,18 +34,24 @@ export interface Operation<T = unknown> {
     error?: any;
     response?: T;
 }
+export interface OperationsDeps {
+    fetch(pathname: string, method: string, body: unknown, headers?: Headers): Promise<Response>;
+}
+export interface AgentConfig {
+    iurls?: string[];
+}
 /**
  * Operations
  * @remarks
  * Operations represent the status and result of long running tasks performed by KERIA agent
  */
 export declare class Operations {
-    client: SignifyClient;
+    client: OperationsDeps;
     /**
      * Operations
      * @param {SignifyClient} client
      */
-    constructor(client: SignifyClient);
+    constructor(client: OperationsDeps);
     /**
      * Get operation status
      * @async
@@ -66,6 +72,15 @@ export declare class Operations {
      * @param {string} name Name of the operation
      */
     delete(name: string): Promise<void>;
+    /**
+     * Poll for operation to become completed.
+     */
+    wait<T>(op: Operation<T>, options?: {
+        signal?: AbortSignal;
+        minSleep?: number;
+        maxSleep?: number;
+        increaseFactor?: number;
+    }): Promise<Operation<T>>;
 }
 /**
  * KeyEvents
@@ -119,3 +134,12 @@ export declare class KeyStates {
      */
     query(pre: string, sn?: string, anchor?: any): Promise<any>;
 }
+export declare class Config {
+    client: SignifyClient;
+    /**
+     * Config
+     * @param {SignifyClient} client
+     */
+    constructor(client: SignifyClient);
+    get(): Promise<AgentConfig>;
+}