signify-ts 0.1.1 → 0.2.1

package/README.md

@@ -3,6 +3,9 @@
 Project Name: signify-ts
 
 [![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.png?v=101)](https://github.com/ellerbrock/typescript-badges/)
+[![Tests](https://github.com/WebOfTrust/signify-ts/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/WebOfTrust/signify-ts/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/WebOfTrust/signify-ts/branch/main/graph/badge.svg?token=K3GK7MCYVW)](https://codecov.io/gh/WebOfTrust/signify-ts)
+[![Documentation](https://img.shields.io/badge/documentation-grey?)](https://weboftrust.github.io/signify-ts/)
 
 ## Signify - KERI Signing at the Edge
 
@@ -15,58 +18,104 @@ Of the five functions in a KERI agent,
 5. Event Validation
 
 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 to generate ed25510 key pairs for signing and x25519 key pairs for encrypting the
+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 the 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 next keys made available to the agent.
+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 agent will encode all cryptographic primitives as CESR base64
+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.
 
 
+### 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 dependencies:
+    ```bash
+    npm install
+    ```
+
+Typescript source files needs to be transpiled before running scripts or integration tests
+
+-   Build:
+    ```bash
+    npm run build
+    ```
+
+### Unit testing
+
+To run unit tests
+
+```bash
+npm test
+```
+
+### Integration testing
+
+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
+```
+
+If successful, it should print someting like this:
+
+```bash
+$ docker compose up deps
+[+] Running 5/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
+```
+
+**Important!** The integration tests runs on the build output in `dist/` directory. Make sure to run build before running the integration tests.
+
+```bash
+npm run build
+```
+
+Use the npm script "test:integration" to run all integration tests in sequence:
+
+```bash
+npm run test:integration
+```
+
+Or, use execute `jest` directly to run a specific integration test, for example:
+
+```bash
+npx jest examples/integration-scripts/credentials.test.ts
+```
+
+It is also possible to run the tests using local instances of vLEI, Keria, and witness network. Set the environment variable `TEST_ENVIRONMENT` to `local`, e.g:
+
+```
+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)
+
 
-sequenceDiagram
-    actor u as User
-    participant s as Signify
-    participant c as Cloud Agent
-    u ->> s: Create Account
-    s ->> s: Generate Pub/Pri Keys
-    s ->>+ c: Request ICP Event Creation with Keys
-    note over s,c: This call can not be secured
-    note right of c: Creates ICP Event
-    c ->>- s: Return ICP event
-    s ->>+ c: Create Account with Signed ICP Event
-    note over s,c: Call Signed by new Keys
-    note right of c: Parses and Saves ICP
-    note right of c: Create Account with new AID
-    c ->>- s: Return New Account KeyState
-    s ->>+ c: Save Key Information
-    c ->>- s: Key Information Saved
-    s ->> u: Return New Account Information
-
-
-sequenceDiagram
-    actor u as User
-    participant a as Web Page App
-    participant s as Signify
-    participant c as Cloud Agent
-    u ->> a: Create Account
-    a ->>+ s: Generate Pub/Pri Keys
-    s ->>- a: Return new Pub/Pri Keypair
-    a ->>+ c: Request ICP Event Creation with Keys
-    note over s,c: This call can not be secured
-    note right of c: Creates ICP Event
-    c ->>- a: Return ICP event
-    a ->>+ s: Sign ICP Event
-    s ->>- a: Return Signed Event
-    a ->>+ c: Create Account with Signed ICP Event
-    note over s,c: Call Signed by new Keys
-    note right of c: Parses and Saves ICP
-    note right of c: Create Account with new AID
-    c ->>- a: Return New Account KeyState
-    a ->>+ s: Save Key Information
-    s ->>+ c: Save Key Information
-    c ->>- s: Key Information Saved
-    a ->> u: Return New Account Information
+![Account Creation Webpage](/diagrams/account-creation-webpage-workflow.png)

package/dist/buffer-polyfill.d.ts

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

package/dist/exports.d.ts

@@ -0,0 +1,40 @@
+export * from './ready';
+export * from './math';
+export * from './keri/app/habery';
+export * from './keri/app/controller';
+export * from './keri/app/aiding';
+export * from './keri/app/clienting';
+export * from './keri/app/contacting';
+export * from './keri/app/coring';
+export * from './keri/app/credentialing';
+export * from './keri/app/escrowing';
+export * from './keri/app/exchanging';
+export * from './keri/app/grouping';
+export * from './keri/app/notifying';
+export * from './keri/core/authing';
+export * from './keri/core/cigar';
+export * from './keri/core/cipher';
+export * from './keri/core/core';
+export * from './keri/core/counter';
+export * from './keri/core/decrypter';
+export * from './keri/core/diger';
+export * from './keri/core/encrypter';
+export * from './keri/core/eventing';
+export * from './keri/core/httping';
+export * from './keri/core/indexer';
+export * from './keri/core/keeping';
+export * from './keri/core/kering';
+export * from './keri/core/manager';
+export * from './keri/core/matter';
+export * from './keri/core/number';
+export * from './keri/core/prefixer';
+export * from './keri/core/saider';
+export * from './keri/core/salter';
+export * from './keri/core/seqner';
+export * from './keri/core/serder';
+export * from './keri/core/siger';
+export * from './keri/core/signer';
+export * from './keri/core/tholder';
+export * from './keri/core/utils';
+export * from './keri/core/verfer';
+export * from './keri/end/ending';

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export * from './keri/core/salter';
-export * from './keri/core/matter';
-export * from './keri/app/habery';
+import './buffer-polyfill';
+import * as exp from './exports';
+export * from './exports';
+export default exp;

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

@@ -0,0 +1,138 @@
+import { Tier } from '../core/salter';
+import { Algos } from '../core/manager';
+import { Serder } from '../core/serder';
+import { KeyManager } from '../core/keeping';
+/** Arguments required to create an identfier */
+export interface CreateIdentiferArgs {
+    transferable?: boolean;
+    isith?: string | number | string[];
+    nsith?: string | number | string[];
+    wits?: string[];
+    toad?: number;
+    proxy?: string;
+    delpre?: string;
+    dcode?: string;
+    data?: any;
+    algo?: Algos;
+    pre?: string;
+    states?: any[];
+    rstates?: any[];
+    prxs?: any[];
+    nxts?: any[];
+    mhab?: any;
+    keys?: any[];
+    ndigs?: any[];
+    bran?: string;
+    count?: number;
+    ncount?: number;
+    tier?: Tier;
+    extern_type?: string;
+    extern?: any;
+}
+/** Arguments required to rotate an identfier */
+export interface RotateIdentifierArgs {
+    transferable?: boolean;
+    nsith?: string | number | string[];
+    toad?: number;
+    cuts?: string[];
+    adds?: string[];
+    data?: Array<object>;
+    ncode?: string;
+    ncount?: number;
+    ncodes?: string[];
+    states?: any[];
+    rstates?: any[];
+}
+/**
+ * Reducing the SignifyClient dependencies used by Identifier class
+ */
+export interface IdentifierDeps {
+    fetch(pathname: string, method: string, body: unknown, headers?: Headers): Promise<Response>;
+    pidx: number;
+    manager: KeyManager | null;
+}
+/** Identifier */
+export declare class Identifier {
+    client: IdentifierDeps;
+    /**
+     * Identifier
+     * @param {IdentifierDeps} client
+     */
+    constructor(client: IdentifierDeps);
+    /**
+     * List managed identifiers
+     * @async
+     * @param {number} [start=0] Start index of list of notifications, defaults to 0
+     * @param {number} [end=24] End index of list of notifications, defaults to 24
+     * @returns {Promise<any>} A promise to the list of managed identifiers
+     */
+    list(start?: number, end?: number): Promise<any>;
+    /**
+     * 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
+     */
+    get(name: string): Promise<any>;
+    /**
+     * Create a managed identifier
+     * @async
+     * @param {string} name Name or alias of the identifier
+     * @param {CreateIdentiferArgs} [kargs] Optional parameters to create the identifier
+     * @returns {EventResult} The inception result
+     */
+    create(name: string, kargs?: CreateIdentiferArgs): Promise<EventResult>;
+    /**
+     * Generate an interaction event in a managed identifier
+     * @async
+     * @param {string} name Name 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>;
+    /**
+     * Generate a rotation event in a managed identifier
+     * @param {string} name Name or alias of the identifier
+     * @param {RotateIdentifierArgs} [kargs] Optional parameters requiered to generate the rotation event
+     * @returns {Promise<EventResult>} A promise to the rotation event result
+     */
+    rotate(name: string, kargs?: RotateIdentifierArgs): Promise<EventResult>;
+    /**
+     * Authorize an endpoint provider in a given role for a managed identifier
+     * @remarks
+     * Typically used to authorize the agent to be the endpoint provider for the identifier in the role of `agent`
+     * @async
+     * @param {string} name Name or alias of the identifier
+     * @param {string} role Authorized role for eid
+     * @param {string} [eid] Optional qb64 of endpoint provider to be authorized
+     * @param {string} [stamp=now] Optional date-time-stamp RFC-3339 profile of iso8601 datetime. Now is the default if not provided
+     * @returns {Promise<EventResult>} A promise to the result of the authorization
+     */
+    addEndRole(name: string, role: string, eid?: string, stamp?: string): Promise<EventResult>;
+    /**
+     * Generate an /end/role/add reply message
+     * @param {string} pre Prefix of the identifier
+     * @param {string} role Authorized role for eid
+     * @param {string} [eid] Optional qb64 of endpoint provider to be authorized
+     * @param {string} [stamp=now] Optional date-time-stamp RFC-3339 profile of iso8601 datetime. Now is the default if not provided
+     * @returns {Serder} The reply message
+     */
+    private makeEndRole;
+    /**
+     * Get the members of a group identifier
+     * @async
+     * @param {string} name - Name or alias of the identifier
+     * @returns {Promise<any>} - A promise to the list of members
+     */
+    members(name: string): Promise<any>;
+}
+/** Event Result */
+export declare class EventResult {
+    private readonly _serder;
+    private readonly _sigs;
+    private readonly promise;
+    constructor(serder: Serder, sigs: string[], promise: Promise<Response> | Response);
+    get serder(): Serder;
+    get sigs(): string[];
+    op(): Promise<any>;
+}

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

@@ -0,0 +1,182 @@
+import { Agent, Controller } from './controller';
+import { Tier } from '../core/salter';
+import { Authenticater } from '../core/authing';
+import { ExternalModule, KeyManager } from '../core/keeping';
+import { Identifier } from './aiding';
+import { Contacts, Challenges } from './contacting';
+import { Oobis, Operations, KeyEvents, KeyStates } from './coring';
+import { Credentials, Ipex, Registries, Schemas } from './credentialing';
+import { Notifications } from './notifying';
+import { Escrows } from './escrowing';
+import { Groups } from './grouping';
+import { Exchanges } from './exchanging';
+declare class State {
+    agent: any | null;
+    controller: any | null;
+    ridx: number;
+    pidx: number;
+    constructor();
+}
+/** SignifyClient */
+export declare class SignifyClient {
+    controller: Controller;
+    url: string;
+    bran: string;
+    pidx: number;
+    agent: Agent | null;
+    authn: Authenticater | null;
+    manager: KeyManager | null;
+    tier: Tier;
+    bootUrl: string;
+    exteralModules: ExternalModule[];
+    /**
+     * SignifyClient constructor
+     * @param {string} url KERIA admin interface URL
+     * @param {string} bran Base64 21 char string that is used as base material for seed of the client AID
+     * @param {Tier} tier Security tier for generating keys of the client AID (high | mewdium | low)
+     * @param {string} bootUrl KERIA boot interface URL
+     * @param {ExternalModule[]} externalModules list of external modules to load
+     */
+    constructor(url: string, bran: string, tier?: Tier, bootUrl?: string, externalModules?: ExternalModule[]);
+    get data(): (string | number | Authenticater | null)[];
+    /**
+     * Boot a KERIA agent
+     * @async
+     * @returns {Promise<Response>} A promise to the result of the boot
+     */
+    boot(): Promise<Response>;
+    /**
+     * Get state of the agent and the client
+     * @async
+     * @returns {Promise<Response>} A promise to the state
+     */
+    state(): Promise<State>;
+    /**  Connect to a KERIA agent
+     * @async
+     */
+    connect(): Promise<void>;
+    /**
+     * Fetch a resource from the KERIA agent
+     * @async
+     * @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 {Headers} [extraHeaders] Optional extra headers to be sent with the request
+     * @returns {Promise<Response>} A promise to the result of the fetch
+     */
+    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
+     * @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>;
+    /**
+     * Approve the delegation of the client AID to the KERIA agent
+     * @async
+     * @returns {Promise<Response>} A promise to the result of the approval
+     */
+    approveDelegation(): Promise<Response>;
+    /**
+     * Save old client passcode in KERIA agent
+     * @async
+     * @param {string} passcode Passcode to be saved
+     * @returns {Promise<Response>} A promise to the result of the save
+     */
+    saveOldPasscode(passcode: string): Promise<Response>;
+    /**
+     * Delete a saved passcode from KERIA agent
+     * @async
+     * @returns {Promise<Response>} A promise to the result of the deletion
+     */
+    deletePasscode(): Promise<Response>;
+    /**
+     * Rotate the client AID
+     * @async
+     * @param {string} nbran Base64 21 char string that is used as base material for the new seed
+     * @param {Array<string>} aids List of managed AIDs to be rotated
+     * @returns {Promise<Response>} A promise to the result of the rotation
+     */
+    rotate(nbran: string, aids: string[]): Promise<Response>;
+    /**
+     * Get identifiers resource
+     * @returns {Identifier}
+     */
+    identifiers(): Identifier;
+    /**
+     * Get OOBIs resource
+     * @returns {Oobis}
+     */
+    oobis(): Oobis;
+    /**
+     * Get operations resource
+     * @returns {Operations}
+     */
+    operations(): Operations;
+    /**
+     * Get keyEvents resource
+     * @returns {KeyEvents}
+     */
+    keyEvents(): KeyEvents;
+    /**
+     * Get keyStates resource
+     * @returns {KeyStates}
+     */
+    keyStates(): KeyStates;
+    /**
+     * Get credentials resource
+     * @returns {Credentials}
+     */
+    credentials(): Credentials;
+    /**
+     * Get IPEX resource
+     * @returns {Ipex}
+     */
+    ipex(): Ipex;
+    /**
+     * Get registries resource
+     * @returns {Registries}
+     */
+    registries(): Registries;
+    /**
+     * Get schemas resource
+     * @returns {Schemas}
+     */
+    schemas(): Schemas;
+    /**
+     * Get challenges resource
+     * @returns {Challenges}
+     */
+    challenges(): Challenges;
+    /**
+     * Get contacts resource
+     * @returns {Contacts}
+     */
+    contacts(): Contacts;
+    /**
+     * Get notifications resource
+     * @returns {Notifications}
+     */
+    notifications(): Notifications;
+    /**
+     * Get escrows resource
+     * @returns {Escrows}
+     */
+    escrows(): Escrows;
+    /**
+     * Get groups resource
+     * @returns {Groups}
+     */
+    groups(): Groups;
+    /**
+     * Get exchange resource
+     * @returns {Exchanges}
+     */
+    exchanges(): Exchanges;
+}
+export {};

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

@@ -0,0 +1,93 @@
+import { SignifyClient } from './clienting';
+import { Operation } from './coring';
+/**
+ * Contacts
+ */
+export declare class Contacts {
+    client: SignifyClient;
+    /**
+     * Contacts
+     * @param {SignifyClient} client
+     */
+    constructor(client: SignifyClient);
+    /**
+     * List contacts
+     * @async
+     * @param {string} [group] Optional group name to filter contacts
+     * @param {string} [filterField] Optional field name to filter 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>;
+    /**
+     * Get a contact
+     * @async
+     * @param {string} pre Prefix of the contact
+     * @returns {Promise<any>} A promise to the contact
+     */
+    get(pre: string): Promise<any>;
+    /**
+     * 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
+     */
+    add(pre: string, info: any): Promise<any>;
+    /**
+     * Delete a contact
+     * @async
+     * @param {string} pre Prefix of the contact
+     * @returns {Promise<any>} A promise to the result of the deletion
+     */
+    delete(pre: string): Promise<any>;
+    /**
+     * Update a contact
+     * @async
+     * @param {string} pre Prefix of the contact
+     * @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>;
+}
+/**
+ * Challenges
+ */
+export declare class Challenges {
+    client: SignifyClient;
+    /**
+     * Challenges
+     * @param {SignifyClient} client
+     */
+    constructor(client: SignifyClient);
+    /**
+     * Generate a random challenge word list based on BIP39
+     * @async
+     * @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>;
+    /**
+     * 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
+     */
+    respond(name: string, recipient: string, words: string[]): Promise<Response>;
+    /**
+     * 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
+     * @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
+     * @returns {Promise<Response>} A promise to the result
+     */
+    responded(source: string, said: string): Promise<Response>;
+}

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

@@ -0,0 +1,49 @@
+import { Tier } from '../core/salter';
+import { Serder } from '../core/serder';
+import { Verfer } from '../core/verfer';
+import { Encrypter } from '../core/encrypter';
+import { Decrypter } from '../core/decrypter';
+/**
+ * Agent is a custodial entity that can be used in conjuntion with a local Client to establish the
+ * KERI "signing at the edge" semantic
+ */
+export declare class Agent {
+    pre: string;
+    anchor: string;
+    verfer: Verfer | null;
+    state: any | null;
+    sn: number | undefined;
+    said: string | undefined;
+    constructor(agent: any);
+    private parse;
+    private event;
+}
+/**
+ * Controller is responsible for managing signing keys for the client and agent.  The client
+ * signing key represents the Account for the client on the agent
+ */
+export declare class Controller {
+    private bran;
+    stem: string;
+    tier: Tier;
+    ridx: number;
+    salter: any;
+    signer: any;
+    private nsigner;
+    serder: Serder;
+    private keys;
+    ndigs: string[];
+    constructor(bran: string, tier: Tier, ridx?: number, state?: any | null);
+    approveDelegation(_agent: Agent): any[];
+    get pre(): string;
+    get event(): any[];
+    get verfers(): [];
+    derive(state: any): Serder;
+    rotate(bran: string, aids: Array<any>): {
+        rot: import("../core/core").Dict<any>;
+        sigs: any[];
+        sxlt: any;
+        keys: Record<any, any>;
+    };
+    recrypt(enc: string, decrypter: Decrypter, encrypter: Encrypter): any;
+}