signify-ts 0.3.0 → 0.4.1

package/dist/keri/core/authing.d.ts

@@ -1,10 +1,29 @@
 import { Signer } from './signer.ts';
 import { Verfer } from './verfer.ts';
-export declare class Authenticater {
+export declare abstract class Authenticator {
+    protected verfer: Verfer;
+    protected readonly csig: Signer;
+    constructor(csig: Signer, verfer: Verfer);
+    abstract prepare(request: Request, local: string, remote: string): Promise<Request>;
+    abstract verify(request: Request, response: Response, local: string, remote: string): Promise<Response>;
+}
+export declare class SignedHeaderAuthenticator extends Authenticator {
     static DefaultFields: string[];
-    private _verfer;
-    private readonly _csig;
+    prepare(request: Request, _local: string, _remote: string): Promise<Request>;
+    verify(request: Request, response: Response, _local: string, remote: string): Promise<Response>;
+    private verifyHeaders;
+    private sign;
+}
+export declare class EssrAuthenticator extends Authenticator {
+    private readonly cx25519Pub;
+    private readonly cx25519Priv;
+    private readonly vx25519Pub;
     constructor(csig: Signer, verfer: Verfer);
-    verify(headers: Headers, method: string, path: string): boolean;
-    sign(headers: Headers, method: string, path: string, fields?: Array<string>): Headers;
+    prepare(request: Request, local: string, remote: string): Promise<Request>;
+    verify(request: Request, response: Response, local: string, remote: string): Promise<Response>;
+    static serializeRequest(request: Request): Promise<string>;
+    static streamToBytes(stream: ReadableStream): Promise<Uint8Array>;
+    private unwrap;
+    private decrypt;
+    static deserializeResponse(httpString: string): Response;
 }

package/dist/keri/core/authing.js

@@ -1,16 +1,42 @@
-import { desiginput, HEADER_SIG_INPUT, HEADER_SIG_TIME, normalize, siginput, } from "./httping.js";
+import libsodium from 'libsodium-wrappers-sumo';
+import { desiginput, HEADER_SIG, HEADER_SIG_DESTINATION, HEADER_SIG_INPUT, HEADER_SIG_SENDER, HEADER_SIG_TIME, normalize, siginput, } from "./httping.js";
 import { Signage, signature, designature } from "../end/ending.js";
-export class Authenticater {
+import { Diger } from "./diger.js";
+import { MtrDex } from "./matter.js";
+import { b, d } from "./core.js";
+export class Authenticator {
     constructor(csig, verfer) {
-        this._csig = csig;
-        this._verfer = verfer;
+        this.csig = csig;
+        this.verfer = verfer;
     }
-    verify(headers, method, path) {
+}
+export class SignedHeaderAuthenticator extends Authenticator {
+    async prepare(request, _local, _remote) {
+        const headers = request.headers;
+        const signedHeaders = this.sign(request.headers, request.method, new URL(request.url).pathname);
+        signedHeaders.forEach((value, key) => {
+            headers.set(key, value);
+        });
+        return request;
+    }
+    async verify(request, response, _local, remote) {
+        if (response.status === 401) {
+            throw new Error(`HTTP ${request.method} ${new URL(request.url).pathname} - ${response.status} ${response.statusText}`);
+        }
+        if (remote !== response.headers.get(HEADER_SIG_SENDER)) {
+            throw new Error('message from a different remote agent');
+        }
+        if (!this.verifyHeaders(response.headers, request.method, new URL(request.url).pathname)) {
+            throw new Error('response verification failed');
+        }
+        return response;
+    }
+    verifyHeaders(headers, method, path) {
         const siginput = headers.get(HEADER_SIG_INPUT);
         if (siginput == null) {
             return false;
         }
-        const signature = headers.get('Signature');
+        const signature = headers.get(HEADER_SIG);
         if (signature == null) {
             return false;
         }
@@ -61,24 +87,21 @@ export class Authenticater {
             const signage = designature(signature);
             const markers = signage[0].markers;
             const cig = markers.get(input.name);
-            if (!cig || !this._verfer.verify(cig.raw, ser)) {
+            if (!cig || !this.verfer.verify(cig.raw, ser)) {
                 throw new Error(`Signature for ${input.keyid} invalid.`);
             }
         });
         return true;
     }
-    sign(headers, method, path, fields) {
-        if (fields == undefined) {
-            fields = Authenticater.DefaultFields;
-        }
-        const [header, sig] = siginput(this._csig, {
+    sign(headers, method, path) {
+        const [header, sig] = siginput(this.csig, {
             name: 'signify',
             method,
             path,
             headers,
-            fields,
+            fields: SignedHeaderAuthenticator.DefaultFields,
             alg: 'ed25519',
-            keyid: this._csig.verfer.qb64,
+            keyid: this.csig.verfer.qb64,
         });
         header.forEach((value, key) => {
             headers.append(key, value);
@@ -93,9 +116,159 @@ export class Authenticater {
         return headers;
     }
 }
-Authenticater.DefaultFields = [
+SignedHeaderAuthenticator.DefaultFields = [
     '@method',
     '@path',
     'signify-resource',
     HEADER_SIG_TIME.toLowerCase(),
 ];
+export class EssrAuthenticator extends Authenticator {
+    constructor(csig, verfer) {
+        super(csig, verfer);
+        const sigkey = new Uint8Array(this.csig.raw.length + this.csig.verfer.raw.length);
+        sigkey.set(this.csig.raw);
+        sigkey.set(this.csig.verfer.raw, this.csig.raw.length);
+        this.cx25519Priv =
+            libsodium.crypto_sign_ed25519_sk_to_curve25519(sigkey);
+        this.cx25519Pub = libsodium.crypto_scalarmult_base(this.cx25519Priv);
+        this.vx25519Pub = libsodium.crypto_sign_ed25519_pk_to_curve25519(this.verfer.raw);
+    }
+    async prepare(request, local, remote) {
+        const dt = new Date().toISOString().replace('Z', '000+00:00');
+        const headers = new Headers();
+        headers.set(HEADER_SIG_SENDER, local);
+        headers.set(HEADER_SIG_DESTINATION, remote);
+        headers.set(HEADER_SIG_TIME, dt);
+        headers.set('Content-Type', 'application/octet-stream');
+        const requestStr = await EssrAuthenticator.serializeRequest(request);
+        const raw = libsodium.crypto_box_seal(requestStr, this.vx25519Pub);
+        const diger = new Diger({ code: MtrDex.Blake3_256 }, raw);
+        const payload = {
+            src: local,
+            dest: remote,
+            d: diger.qb64,
+            dt,
+        };
+        const sig = this.csig.sign(b(JSON.stringify(payload)));
+        const markers = new Map();
+        markers.set('signify', sig);
+        const signage = new Signage(markers, false);
+        const signed = signature([signage]);
+        signed.forEach((value, key) => {
+            headers.append(key, value);
+        });
+        return new Request(new URL(request.url).origin + '/', {
+            method: 'POST',
+            body: raw,
+            headers,
+        });
+    }
+    async verify(request, response, local, remote) {
+        if (response.status === 401) {
+            throw new Error(`HTTP ${request.method} ${new URL(request.url).pathname} - ${response.status} ${response.statusText}`);
+        }
+        return await this.unwrap(response, remote, local);
+    }
+    static async serializeRequest(request) {
+        let headers = '';
+        request.headers.forEach((value, name) => {
+            headers += `${name}: ${value}\r\n`;
+        });
+        let body = '';
+        if (request.method !== 'GET' && request.body) {
+            const bytes = await this.streamToBytes(request.body);
+            try {
+                body = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch (e) {
+                throw new Error('Failed to serialize ESSR request - body is not valid UTF-8', { cause: e });
+            }
+        }
+        return `${request.method} ${request.url} HTTP/1.1\r\n${headers}\r\n${body}`;
+    }
+    static async streamToBytes(stream) {
+        const reader = stream.getReader();
+        const chunks = [];
+        let done, value;
+        while ((({ done, value } = await reader.read()), !done)) {
+            if (value)
+                chunks.push(value);
+        }
+        reader.releaseLock();
+        const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+        const result = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return result;
+    }
+    async unwrap(wrapper, sender, receiver) {
+        const signature = wrapper.headers.get(HEADER_SIG);
+        if (!signature) {
+            throw new Error('Signature is missing from ESSR payload');
+        }
+        if (wrapper.headers.get(HEADER_SIG_SENDER) !== sender) {
+            throw new Error('Message from a different remote agent');
+        }
+        if (wrapper.headers.get(HEADER_SIG_DESTINATION) !== receiver) {
+            throw new Error('Invalid ESSR payload, missing or incorrect destination prefix');
+        }
+        const dt = wrapper.headers.get(HEADER_SIG_TIME);
+        if (!dt) {
+            throw new Error('Timestamp is missing from ESSR payload');
+        }
+        const ciphertext = new Uint8Array(await wrapper.arrayBuffer());
+        const diger = new Diger({ code: MtrDex.Blake3_256 }, ciphertext);
+        const payload = {
+            src: sender,
+            dest: receiver,
+            d: diger.qb64,
+            dt,
+        };
+        const signages = designature(signature);
+        const markers = signages[0].markers;
+        const cig = markers.get('signify');
+        if (!cig) {
+            throw new Error('Invalid signature format - missing "signify" marker');
+        }
+        const verified = this.verfer.verify(cig.raw, b(JSON.stringify(payload)));
+        if (!verified) {
+            throw new Error('Invalid signature');
+        }
+        const response = EssrAuthenticator.deserializeResponse(d(this.decrypt(ciphertext)));
+        if (response.headers.get(HEADER_SIG_SENDER) !== sender) {
+            throw new Error('Invalid ESSR payload, missing or incorrect encrypted sender');
+        }
+        return response;
+    }
+    // KERIA seals the response to the client key it has in the controller's KEL
+    decrypt(ciphertext) {
+        try {
+            return libsodium.crypto_box_seal_open(ciphertext, this.cx25519Pub, this.cx25519Priv);
+        }
+        catch (e) {
+            throw new Error('Failed to decrypt ESSR response - sealed to a different client key', { cause: e });
+        }
+    }
+    static deserializeResponse(httpString) {
+        const sep = httpString.indexOf('\r\n\r\n');
+        const head = sep === -1 ? httpString.trimEnd() : httpString.slice(0, sep);
+        const [statusLine, ...headerLines] = head.split('\r\n');
+        const [, statusCode, ...statusTextArr] = statusLine.split(' ');
+        const body = sep === -1 ? '' : httpString.slice(sep + 4);
+        const headers = new Headers();
+        for (const line of headerLines) {
+            const i = line.indexOf(':');
+            if (i !== -1) {
+                headers.append(line.slice(0, i).trim(), line.slice(i + 1).trim());
+            }
+        }
+        return new Response(body.length ? body : null, {
+            status: Number(statusCode),
+            statusText: statusTextArr.join(' '),
+            headers,
+        });
+    }
+}

package/dist/keri/core/eventing.js

@@ -286,7 +286,7 @@ export function messagize(serder, sigers, seal, wigers, cigars, pipelined = fals
                 atc = concat(atc, new Counter({ code: CtrDex.TransIdxSigGroups, count: 1 })
                     .qb64b);
                 atc = concat(atc, new TextEncoder().encode(seal[1].i));
-                atc = concat(atc, new Seqner({ sn: parseInt(seal[1].s) }).qb64b);
+                atc = concat(atc, new Seqner({ snh: seal[1].s }).qb64b);
                 atc = concat(atc, new TextEncoder().encode(seal[1].d));
             }
             else if (seal[0] == 'SealLast') {

package/dist/keri/core/httping.d.ts

@@ -1,8 +1,11 @@
 import { Signer } from './signer.ts';
 import { Cigar } from './cigar.ts';
 import { Siger } from './siger.ts';
+export declare const HEADER_SIG: string;
 export declare const HEADER_SIG_INPUT: string;
 export declare const HEADER_SIG_TIME: string;
+export declare const HEADER_SIG_SENDER: string;
+export declare const HEADER_SIG_DESTINATION: string;
 export declare function normalize(header: string): string;
 export interface SiginputArgs {
     name: string;

package/dist/keri/core/httping.js

@@ -2,8 +2,11 @@ import { serializeDictionary, parseDictionary, } from 'structured-headers';
 import { b } from "./core.js";
 import { nowUTC } from "./utils.js";
 import { encodeBase64Url } from "./base64.js";
+export const HEADER_SIG = normalize('Signature');
 export const HEADER_SIG_INPUT = normalize('Signature-Input');
 export const HEADER_SIG_TIME = normalize('Signify-Timestamp');
+export const HEADER_SIG_SENDER = normalize('Signify-Resource');
+export const HEADER_SIG_DESTINATION = normalize('Signify-Receiver');
 export function normalize(header) {
     return header.trim();
 }

package/dist/keri/core/keeping.d.ts

@@ -46,7 +46,18 @@ export interface IdentifierManager<T extends IdentifierManagerParams = Identifie
     params(): T;
     incept(transferable: boolean): Promise<IdentifierManagerResult>;
     rotate(ncodes: string[], transferable: boolean, states?: KeyState[], rstates?: KeyState[]): Promise<IdentifierManagerResult>;
-    sign(ser: Uint8Array, indexed?: boolean, indices?: number[], ondices?: number[]): Promise<SignResult>;
+    /**
+     * Sign serialized bytes.
+     *
+     * `rotated` is meaningful for group identifiers only. Callers building a
+     * group rotation must pass `rotated=true` so the group signature exposes
+     * prior-next `ondex`; non-rotation calls leave it false/current-only.
+     *
+     * `ondices === undefined` uses the default dual-index behavior where each
+     * `ondex` matches its `index`. `ondices[j] === undefined` is the explicit
+     * current-only case for that signature, so no `ondex` is emitted.
+     */
+    sign(ser: Uint8Array, indexed?: boolean, indices?: number[], ondices?: Ondex[], rotated?: boolean): Promise<SignResult>;
 }
 /**
  * Creates IdentifierManager instances based on the algorithm and key indexes.
@@ -102,7 +113,7 @@ export declare class SaltyIdentifierManager implements IdentifierManager {
     params(): SaltyManagerParams;
     incept(transferable: boolean): Promise<IdentifierManagerResult>;
     rotate(ncodes: string[], transferable: boolean): Promise<[string[], string[]]>;
-    sign(ser: Uint8Array, indexed?: boolean, indices?: number[] | undefined, ondices?: number[] | undefined): Promise<SignResult>;
+    sign(ser: Uint8Array, indexed?: boolean, indices?: number[] | undefined, ondices?: Ondex[] | undefined, _rotated?: boolean): Promise<SignResult>;
 }
 export declare class RandyIdentifierManager implements IdentifierManager {
     private salter;
@@ -126,45 +137,109 @@ export declare class RandyIdentifierManager implements IdentifierManager {
     params(): RandyManagerParams;
     incept(transferable: boolean): Promise<IdentifierManagerResult>;
     rotate(ncodes: string[], transferable: boolean): Promise<IdentifierManagerResult>;
-    sign(ser: Uint8Array, indexed?: boolean, indices?: number[] | undefined, ondices?: number[] | undefined): Promise<SignResult>;
+    sign(ser: Uint8Array, indexed?: boolean, indices?: number[] | undefined, ondices?: Ondex[] | undefined, _rotated?: boolean): Promise<SignResult>;
 }
+type Ondex = number | undefined;
+/**
+ * Identifier manager for group identifiers.
+ *
+ * A group identifier does not have its own private signing keys. Instead, this
+ * manager maps group event signing indexes onto the local member AID (`mhab`)
+ * and delegates actual signing to that member's key manager.
+ *
+ * The central invariant is that indexed rotation signatures carry two
+ * positions:
+ *
+ * - `index` points to the signer's current key in the event's current key list
+ *   (`k`), which SignifyTS derives from `states`.
+ * - `ondex` points to the prior establishment event's next digest list (`n`),
+ *   proving that the current key was a precommitted key.
+ *
+ * `rstates` are the proposed next digest source for the new event. They are not
+ * the signer authorization set for the event being signed.
+ */
 export declare class GroupIdentifierManager implements IdentifierManager {
+    /** Factory used to recover the local member keeper that performs signing. */
     private manager;
+    /** Local member AID whose private key signs on behalf of the group. */
     private mhab;
+    /**
+     * Current group signing public keys for the event being built. During
+     * rotation these come from `states[*].k[0]` and define signature `index`.
+     */
     private gkeys;
+    /**
+     * Proposed next digest list for the event being built. During rotation
+     * these come from `rstates[*].n[0]`, are returned from `rotate()`, and are
+     * serialized as `group.ndigs`.
+     */
     private gdigs;
+    /**
+     * Prior next digest list from the current group establishment event. For
+     * rotations, this is the authorization commitment set used to derive
+     * `ondex`; it must remain separate from proposed next digests in `gdigs`.
+     */
+    private gpndigs;
     algo: Algos;
+    /**
+     * Retained for the `IdentifierManager` interface. Group signing delegates
+     * to the local member AID keeper instead of storing signers here.
+     */
     signers: Signer[];
+    /**
+     * Creates a manager for either a new group event or an existing group AID.
+     *
+     * `states` and `rstates` are app-level key state records used when creating
+     * a new group event. `keys` and `ndigs` are persisted group manager params
+     * used when loading an existing group. For an existing group, `ndigs` is
+     * expected to be the current establishment event's next digest list.
+     *
+     * During group inception there is no separate prior establishment event, so
+     * `gpndigs` starts as the same digest list as `gdigs`. During rotation,
+     * `gdigs` changes to the proposed next digests, while `gpndigs` stays
+     * fixed for `ondex` derivation.
+     */
     constructor(manager: IdentifierManagerFactory, mhab: HabState, states?: KeyState[] | undefined, rstates?: KeyState[] | undefined, keys?: string[], ndigs?: string[]);
+    /**
+     * Returns the inception key material for the group event.
+     *
+     * Inception has no prior group establishment event. The current keys and
+     * proposed next digests are therefore returned directly from the manager's
+     * configured `states` and `rstates`.
+     */
     incept(): Promise<IdentifierManagerResult>;
     /**
-     * Performs a multisig rotation
+     * Performs a multisig rotation.
+     *
+     * `states` supplies the current group signing keys for the event being
+     * signed. `rstates` supplies the proposed next key digests to put in the
+     * new event. The prior next digests used for rotation `ondex` lookup stay
+     * unchanged until KERIA accepts the new establishment event and returns an
+     * updated group state.
+     *
      * @param _ncodes
      * @param _transferable
      * @param states
-     * @param rstates key state records for the prior establishment event indicating next key digests.
-     *                You should pass in the current key
+     * @param rstates
      */
     rotate(_ncodes: string[], _transferable: boolean, states: KeyState[], rstates: KeyState[]): Promise<IdentifierManagerResult>;
-    sign(ser: Uint8Array, indexed?: boolean): Promise<SignResult>;
+    /**
+     * Signs for the group by delegating to the local member keeper.
+     */
+    sign(ser: Uint8Array, indexed?: boolean, _indices?: number[] | undefined, _ondices?: Ondex[] | undefined, rotated?: boolean): Promise<SignResult>;
+    /**
+     * Finds the prior next digest position that precommitted the current key.
+     *
+     * This mirrors KERIpy's exposed-prior-next behavior: for each prior next
+     * digest, hash the current verifier key using that digest's code and compare
+     * the result to the digest at that position. A match means the signer has
+     * exposed that precommitted key, and the matching position is the `ondex`.
+     */
+    private priorNextIndexForKey;
     params(): {
-        mhab: {
-            name: string;
-            prefix: string;
-            icp_dt: string;
-            state: import("../../types/keria-api-schema.ts").components["schemas"]["KeyStateRecord"];
-            transferable: boolean;
-            windexes: string[];
-        } & ({
-            salty: import("../../types/keria-api-schema.ts").components["schemas"]["SaltyState"];
-        } | {
-            randy: import("../../types/keria-api-schema.ts").components["schemas"]["RandyKeyState"];
-        } | {
-            group: import("../../types/keria-api-schema.ts").components["schemas"]["GroupKeyState"];
-        } | {
-            extern: import("../../types/keria-api-schema.ts").components["schemas"]["ExternState"];
-        });
+        mhab: HabState;
         keys: string[];
         ndigs: string[];
     };
 }
+export {};