signify-ts 0.1.0 → 0.2.0

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,11 +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
-private keys, next public keys any 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.
+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 
+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)
+
+
+![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 +1,4 @@
-export declare const sum: (a: number, b: number) => number;
+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;
+}