signify-ts 0.3.0 → 0.4.1

package/dist/keri/core/keeping.js

@@ -7,6 +7,7 @@ import { b } from "./core.js";
 import { Cipher } from "./cipher.js";
 import { Diger } from "./diger.js";
 import { Prefixer } from "./prefixer.js";
+import { Verfer } from "./verfer.js";
 /**
  * Creates IdentifierManager instances based on the algorithm and key indexes.
  */
@@ -155,15 +156,17 @@ export class SaltyIdentifierManager {
         const digers = nsigners.signers.map((nsigner) => new Diger({ code: this.dcode }, nsigner.verfer.qb64b).qb64);
         return [verfers, digers];
     }
-    async sign(ser, indexed = true, indices = undefined, ondices = undefined) {
+    async sign(ser, indexed = true, indices = undefined, ondices = undefined, _rotated) {
         const signers = this.creator.create(this.icodes, this.ncount, this.ncode, this.transferable, this.pidx, 0, this.kidx, false);
         if (indexed) {
             const sigers = [];
             let i = 0;
             for (const [j, signer] of signers.signers.entries()) {
-                if (indices != undefined) {
-                    i = indices[j];
-                    if (typeof i != 'number' || i < 0) {
+                if (indices &&
+                    indices.length > 0 &&
+                    indices.length === signers.signers.length) {
+                    i = indices[j]; // default indexing behavior of pulling index order from signer order
+                    if (!Number.isInteger(i) || i < 0) {
                         throw new Error(`Invalid signing index = ${i}, not whole number.`);
                     }
                 }
@@ -171,19 +174,19 @@ export class SaltyIdentifierManager {
                     i = j;
                 }
                 let o = 0;
-                if (ondices != undefined) {
+                // if ondices are specified then the count and order should match the indices list
+                // even if a given ondex is "undefined" which means to ignore the ondex (dual indexed sig)
+                // for that given index.
+                if (ondices && ondices.length > 0) {
                     o = ondices[j];
-                    if ((o == undefined ||
-                        (typeof o == 'number' &&
-                            typeof o != 'number' &&
-                            o >= 0))) {
+                    if (o !== undefined && (!Number.isInteger(o) || o < 0)) {
                         throw new Error(`Invalid ondex = ${o}, not whole number.`);
                     }
                 }
                 else {
                     o = i;
                 }
-                sigers.push(signer.sign(ser, i, o == undefined ? true : false, o));
+                sigers.push(signer.sign(ser, i, o === undefined ? true : false, o));
             }
             return sigers.map((siger) => siger.qb64);
         }
@@ -251,7 +254,7 @@ export class RandyIdentifierManager {
         const digers = nsigners.signers.map((nsigner) => new Diger({ code: this.dcode }, nsigner.verfer.qb64b).qb64);
         return [verfers, digers];
     }
-    async sign(ser, indexed = true, indices = undefined, ondices = undefined) {
+    async sign(ser, indexed = true, indices = undefined, ondices = undefined, _rotated) {
         const signers = this.prxs.map((prx) => this.decrypter.decrypt(new Cipher({ qb64: prx }).qb64b, undefined, this.transferable));
         if (indexed) {
             const sigers = [];
@@ -269,17 +272,14 @@ export class RandyIdentifierManager {
                 let o = 0;
                 if (ondices != undefined) {
                     o = ondices[j];
-                    if ((o == undefined ||
-                        (typeof o == 'number' &&
-                            typeof o != 'number' &&
-                            o >= 0))) {
+                    if (o !== undefined && (!Number.isInteger(o) || o < 0)) {
                         throw new Error(`Invalid ondex = ${o}, not whole number.`);
                     }
                 }
                 else {
                     o = i;
                 }
-                sigers.push(signer.sign(ser, i, o == undefined ? true : false, o));
+                sigers.push(signer.sign(ser, i, o === undefined ? true : false, o));
             }
             return sigers.map((siger) => siger.qb64);
         }
@@ -292,11 +292,57 @@ export class RandyIdentifierManager {
         }
     }
 }
+/**
+ * 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 class GroupIdentifierManager {
+    /**
+     * 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, mhab, states = undefined, rstates = undefined, keys = [], ndigs = []) {
         var _a, _b;
+        /**
+         * Current group signing public keys for the event being built. During
+         * rotation these come from `states[*].k[0]` and define signature `index`.
+         */
         this.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`.
+         */
         this.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`.
+         */
+        this.gpndigs = [];
         this.algo = Algos.group;
         this.manager = manager;
         if (states != undefined) {
@@ -307,36 +353,92 @@ export class GroupIdentifierManager {
         }
         this.gkeys = (_a = states === null || states === void 0 ? void 0 : states.map((state) => state['k'][0])) !== null && _a !== void 0 ? _a : keys;
         this.gdigs = (_b = rstates === null || rstates === void 0 ? void 0 : rstates.map((state) => state['n'][0])) !== null && _b !== void 0 ? _b : ndigs;
+        this.gpndigs = this.gdigs;
         this.mhab = mhab;
         this.signers = [];
     }
+    /**
+     * 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`.
+     */
     async incept() {
         return [this.gkeys, this.gdigs];
     }
     /**
-     * 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
      */
     async rotate(_ncodes, _transferable, states, rstates) {
         this.gkeys = states.map((state) => state['k'][0]);
         this.gdigs = rstates.map((state) => state['n'][0]);
         return [this.gkeys, this.gdigs];
     }
-    async sign(ser, indexed = true) {
+    /**
+     * Signs for the group by delegating to the local member keeper.
+     */
+    async sign(ser, indexed = true, _indices = undefined, _ondices = undefined, rotated = false) {
         if (!this.mhab.state) {
             throw new Error(`No state in mhab`);
         }
         const key = this.mhab['state']['k'][0];
-        const ndig = this.mhab['state']['n'][0];
+        // The event's current key list authorizes the signature's `index`.
         const csi = this.gkeys.indexOf(key); // csi = current signing index (from current rotation event)
-        const pni = this.gdigs.indexOf(ndig); // pni = prior next index (from last establishment event)
+        if (csi < 0) {
+            throw new Error(`Group signing key ${key} is not present in current group signing keys.`);
+        }
+        let pni; // prior next index exposed as signature `ondex`
+        if (rotated) {
+            // Rotation call sites must explicitly request prior-next exposure,
+            // dual indexed signatures with both an index (csi) and an ondex (pni)
+            pni = this.priorNextIndexForKey(key);
+        }
+        else {
+            // Inception and non-rotation signatures satisfy only the current
+            // signing threshold. The event's `n` field is a precommitment for a
+            // future rotation, not an `ondex` source.
+            pni = undefined;
+        }
+        if (pni !== undefined && pni < 0) {
+            throw new Error(`Group signing key ${key} cannot derive ondex from prior next digest list.`);
+        }
+        // Delegate the actual signature to the local member AID keeper while
+        // supplying group-level index and ondex positions.
         const mkeeper = this.manager.get(this.mhab);
         return await mkeeper.sign(ser, indexed, [csi], [pni]);
     }
+    /**
+     * 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`.
+     */
+    priorNextIndexForKey(key) {
+        const verfer = new Verfer({ qb64: key });
+        for (const [index, ndig] of this.gpndigs.entries()) {
+            const priorDiger = new Diger({ qb64: ndig });
+            const keyDigest = new Diger({ code: priorDiger.code }, verfer.qb64b)
+                .qb64;
+            if (keyDigest === priorDiger.qb64) {
+                return index;
+            }
+        }
+        return -1;
+    }
     params() {
         return {
             mhab: this.mhab,

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

@@ -17,15 +17,39 @@ export type RandyKeyState = components['schemas']['RandyKeyState'];
 /**
  * Defining properties a multi-signature group identifier manager.
  */
-export type GroupKeyState = components['schemas']['GroupKeyState'];
+export type GroupKeyState = Omit<components['schemas']['GroupKeyState'], 'mhab'> & {
+    mhab: HabState;
+};
 /**
  * Defining properties for an external module identifier manager that uses externally managed keys such as in an HSM or a KMS system.
  */
 export type ExternState = components['schemas']['ExternState'];
+type SchemaHabState = components['schemas']['HabState'];
 /**
- * Defining properties of an identifier habitat, know as a Hab in KERIpy.
+ * Defining properties of an identifier habitat, known as a Hab in KERIpy.
+ *
+ * Omitting `state` alone would erase the algo variants — `keyof` a union of disjoint objects is
+ * `never` — so they are re-spelled, which also points `group` at the local GroupKeyState above.
  */
-export type HabState = components['schemas']['HabState'];
+type BaseHabState = Omit<SchemaHabState, 'state' | 'salty' | 'randy' | 'group' | 'extern'> & ({
+    salty: SaltyKeyState;
+} | {
+    randy: RandyKeyState;
+} | {
+    group: GroupKeyState;
+} | {
+    extern: ExternState;
+});
+/** Multisig group whose inception is still collecting member signatures; no key state yet. */
+export type PendingHabState = BaseHabState & {
+    state?: undefined;
+};
+/** Fully inceptioned identifier; key state present. */
+export type HabState = BaseHabState & {
+    state: KeyState;
+};
+export declare function isAccepted(hab: HabState | PendingHabState): hab is HabState;
+export declare function requireKeyState(hab: HabState | PendingHabState): KeyState;
 export type Icp = components['schemas']['ICP_V_1'] | components['schemas']['ICP_V_2'];
 export type Ixn = components['schemas']['IXN_V_1'] | components['schemas']['IXN_V_2'];
 export type ExnV1 = components['schemas']['EXN_V_1'];
@@ -50,6 +74,7 @@ export type DoneOperation = components['schemas']['DoneOperation'];
 export type CredentialOperation = components['schemas']['CredentialOperation'];
 export type GroupOperation = components['schemas']['GroupOperation'];
 export type DelegatorOperation = components['schemas']['DelegatorOperation'];
+export type KelOperation = components['schemas']['KelOperation'];
 export type PendingOOBIOperation = components['schemas']['PendingOOBIOperation'];
 export type PendingQueryOperation = components['schemas']['PendingQueryOperation'];
 export type PendingEndRoleOperation = components['schemas']['PendingEndRoleOperation'];
@@ -96,3 +121,5 @@ export type FailedGroupOperation = components['schemas']['FailedGroupOperation']
 export type FailedDelegatorOperation = components['schemas']['FailedDelegatorOperation'];
 export type FailedOperation = FailedOOBIOperation | FailedQueryOperation | FailedEndRoleOperation | FailedWitnessOperation | FailedDelegationOperation | FailedRegistryOperation | FailedLocSchemeOperation | FailedChallengeOperation | FailedExchangeOperation | FailedSubmitOperation | FailedDoneOperation | FailedCredentialOperation | FailedGroupOperation | FailedDelegatorOperation;
 export type GenericOperation = OOBIOperation | QueryOperation | EndRoleOperation | WitnessOperation | DelegationOperation | RegistryOperation | LocSchemeOperation | ChallengeOperation | ExchangeOperation | SubmitOperation | DoneOperation | CredentialOperation | GroupOperation | DelegatorOperation;
+export type EndRole = components['schemas']['EndRole'];
+export {};

package/dist/keri/core/keyState.js

@@ -1 +1,9 @@
-export {};
+export function isAccepted(hab) {
+    return hab.state !== undefined;
+}
+export function requireKeyState(hab) {
+    if (!isAccepted(hab)) {
+        throw new Error(`No key state for identifier ${hab.name}`);
+    }
+    return hab.state;
+}

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

@@ -242,7 +242,7 @@ interface SignArgs {
     verfers?: Array<Verfer> | undefined;
     indexed?: boolean;
     indices?: Array<number> | undefined;
-    ondices?: Array<number> | undefined;
+    ondices?: Array<number | undefined> | undefined;
 }
 /**
  * Manages key pair creation, retrieval, and message signing.

package/dist/keri/core/manager.js

@@ -722,14 +722,14 @@ export class Manager {
                 let o;
                 if (ondices != undefined) {
                     o = ondices[idx];
-                    if (o <= 0) {
-                        throw new Error(`Invalid other signing index = {o}, not None or not whole number.`);
+                    if (o !== undefined && (!Number.isInteger(o) || o < 0)) {
+                        throw new Error(`Invalid other signing index = ${o}, not None or not whole number.`);
                     }
                 }
                 else {
                     o = i;
                 }
-                const only = o == undefined;
+                const only = o === undefined;
                 sigers.push(signer.sign(ser, i, only, o));
             });
             return sigers;

package/dist/keri/end/ending.js

@@ -1,5 +1,6 @@
 import { Siger } from "../core/siger.js";
 import { Cigar } from "../core/cigar.js";
+import { HEADER_SIG } from "../core/httping.js";
 export const FALSY = [false, 0, '?0', 'no', 'false', 'False', 'off'];
 export const TRUTHY = [true, 1, '?1', 'yes', 'true', 'True', 'on'];
 export class Signage {
@@ -77,7 +78,7 @@ export function signature(signages) {
         }));
         values.push(items.join(';'));
     }
-    return new Headers([['Signature', values.join(',')]]);
+    return new Headers([[HEADER_SIG, values.join(',')]]);
 }
 export function designature(value) {
     const values = value.replace(' ', '').split(',');