@ibgib/core-gib 0.0.49 → 0.0.50

package/src/common/secret/secret-helper.mts

@@ -15,20 +15,22 @@
 
 import {
     extractErrorMsg, delay, getSaferSubstring,
-    getTimestampInTicks, getUUID, pretty,
+    getTimestampInTicks, getUUID, pretty, HashAlgorithm, getTimestamp,
 } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
 import { UUID_REGEXP, CLASSNAME_REGEXP, } from '@ibgib/helper-gib/dist/constants.mjs';
 import { Ib, } from '@ibgib/ts-gib/dist/types.mjs';
 import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
 
 import { GLOBAL_LOG_A_LOT } from "../../core-constants.mjs";
-import { SecretData_V1, SecretIbGib_V1, SecretInfo, SecretInfo_Password, SecretType, } from './secret-types.mjs';
+import { CheckIfPasswordProbablyCorrectInfo, SecretData_V1, SecretIbGib_V1, SecretInfo, SecretInfo_Password, SecretType, VALID_SECRET_TYPES, } from './secret-types.mjs';
 import { SECRET_ATOM, SECRET_NAME_REGEXP, SECRET_REL8N_NAME, } from './secret-constants.mjs';
 import { MetaspaceService } from "../../witness/space/metaspace/metaspace-types.mjs";
 import { IbGibSpaceAny } from "../../witness/space/space-base-v1.mjs";
 import { SpecialIbGibType } from "../other/other-types.mjs";
-import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+import { INVALID_DATE_STRING } from '../other/other-constants.mjs';
+import { hash16816 } from '../other/ibgib-helper.mjs';
 
 /**
  * for verbose logging
@@ -46,7 +48,9 @@ export function validateCommonSecretData({
         if (!data) { throw new Error(`data required (E: f7d9a12390e2d3821c07c115a289b5af)`); }
         const errors: string[] = [];
         const {
-            name, uuid, classname,
+            name, /*uuid,*/ classname,
+            expirationUTC,
+            type,
         } =
             data;
 
@@ -58,20 +62,39 @@ export function validateCommonSecretData({
             errors.push(`name required. (E: fe088277e7677ad295b5e914ed644ab4)`);
         }
 
-        if (uuid) {
-            if (!uuid.match(UUID_REGEXP)) {
-                errors.push(`uuid must match regexp: ${UUID_REGEXP} (E: 1b035a31d191435217010ac272681c82)`);
+        if (type) {
+            if (!VALID_SECRET_TYPES.includes(type)) {
+                errors.push(`type (${type}) is invalid. must be one of ${VALID_SECRET_TYPES.join(', ')} (E: 413a1c899dcc4623a38be35bdf144217)`);
             }
         } else {
-            errors.push(`uuid required. (E: 55fee43e758fcf542866bdabe7321633)`);
+            errors.push(`type required. (E: 6126767cc5fd4c898d432b139652e5d1)`);
         }
 
+        // if (uuid) {
+        //     if (!uuid.match(UUID_REGEXP)) {
+        //         errors.push(`uuid must match regexp: ${UUID_REGEXP} (E: 1b035a31d191435217010ac272681c82)`);
+        //     }
+        // } else {
+        //     errors.push(`uuid required. (E: 55fee43e758fcf542866bdabe7321633)`);
+        // }
+
         if (classname) {
             if (!classname.match(CLASSNAME_REGEXP)) {
                 errors.push(`classname must match regexp: ${CLASSNAME_REGEXP} (E: 301c325035ad3297c2744fd25ec618dd)`);
             }
         }
 
+        if (expirationUTC) {
+            let date = new Date(expirationUTC);
+            if (date.toString() === INVALID_DATE_STRING) {
+                errors.push(`invalid expirationUTC (${expirationUTC}) (E: 969a126f12b742adbf9d671d3fdd782f)`)
+            }
+        } else {
+            errors.push(`expirationUTC required (E: f1ff3bcec74946908f0f37f9282e917d)`)
+        }
+
+
+
         return errors;
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -82,24 +105,27 @@ export function validateCommonSecretData({
 }
 
 export async function validateCommonSecretIbGib({
-    SecretIbGib,
+    ibGib,
 }: {
-    SecretIbGib: SecretIbGib_V1,
+    ibGib: SecretIbGib_V1,
 }): Promise<string[] | undefined> {
     const lc = `[${validateCommonSecretIbGib.name}]`;
     try {
         if (logalot) { console.log(`${lc} starting... (I: 596f5952f6a18ebb23ff270520818eaa)`); }
-        const intrinsicErrors: string[] = await validateIbGibIntrinsically({ ibGib: SecretIbGib }) ?? [];
+        const intrinsicErrors: string[] = await validateIbGibIntrinsically({ ibGib: ibGib }) ?? [];
 
-        if (!SecretIbGib.data) { throw new Error(`SecretIbGib.data required (E: df00780071919f55c762ee0756cf46bc)`); }
+        if (!ibGib.data) { throw new Error(`SecretIbGib.data required (E: df00780071919f55c762ee0756cf46bc)`); }
         const ibErrors: string[] = [];
-        let { SecretClassname, SecretName, SecretId } =
-            parseSecretIb({ ib: SecretIbGib.ib });
-        if (!SecretClassname) { ibErrors.push(`SecretClassname required (E: 273042f54b363c094b466f85baef3c10)`); }
-        if (!SecretName) { ibErrors.push(`SecretName required (E: 670718e47214d0cdfa844d8f7d756477)`); }
-        if (!SecretId) { ibErrors.push(`SecretId required (E: 56c5874056ff8d07e1875cc38eccf0c3)`); }
 
-        const dataErrors = validateCommonSecretData({ data: SecretIbGib.data });
+        // ib
+        let { atom, type, name, } =
+            parseSecretIb({ ib: ibGib.ib });
+        if (atom !== SECRET_ATOM) { ibErrors.push(`invalid secret atom. must be ${SECRET_ATOM} (E: 56c5874056ff8d07e1875cc38eccf0c3)`); }
+        if (!type) { ibErrors.push(`secret type required (E: 273042f54b363c094b466f85baef3c10)`); }
+        if (!name) { ibErrors.push(`secret name required (E: 670718e47214d0cdfa844d8f7d756477)`); }
+
+        // data
+        const dataErrors = validateCommonSecretData({ data: ibGib.data });
 
         let result = [...(intrinsicErrors ?? []), ...(ibErrors ?? []), ...(dataErrors ?? [])];
         if (result.length > 0) {
@@ -117,26 +143,17 @@ export async function validateCommonSecretIbGib({
 
 export function getSecretIb({
     data,
-    classname,
 }: {
     data: SecretData_V1,
-    classname?: string,
 }): Ib {
     const lc = `[${getSecretIb.name}]`;
     try {
         const validationErrors = validateCommonSecretData({ data });
         if (validationErrors.length > 0) { throw new Error(`invalid Secret data: ${validationErrors} (E: 07a71e9ba5d574274e2c6a289a3fbabe)`); }
-        if (classname) {
-            if (data.classname && data.classname !== classname) { throw new Error(`classname does not match data.classname (E: 4955d77f6b12b65958dd54f17a8ecbd8)`); }
-        } else {
-            classname = data.classname;
-            if (!classname) { throw new Error(`classname required (E: 0530c26eb1f2225e5ea4a48ba63eed6e)`); }
-        }
 
-        // ad hoc validation here.
+        const { name, type } = data;
 
-        const { name, uuid } = data;
-        return `${SECRET_ATOM} ${classname} ${name} ${uuid}`;
+        return `${SECRET_ATOM} ${type} ${name}`;
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;
@@ -144,7 +161,7 @@ export function getSecretIb({
 }
 
 /**
- * Current schema is '[SECRET_ATOM] [classname] [SecretName] [SecretId]'
+ * Current schema is '[SECRET_ATOM] [type] [name]'
  *
  * NOTE this is space-delimited
  */
@@ -153,21 +170,23 @@ export function parseSecretIb({
 }: {
     ib: Ib,
 }): {
-    SecretClassname: string,
-    SecretName: string,
-    SecretId: string,
+    atom: string,
+    type: string,
+    name: string,
 } {
     const lc = `[${parseSecretIb.name}]`;
     try {
         if (!ib) { throw new Error(`Secret ib required (E: 115e8097c30538526536b240ce4b8e87)`); }
 
-        const pieces = ib.split(' ');
+        const [atom, type, name] = ib.split(' ');
 
-        return {
-            SecretClassname: pieces[2],
-            SecretName: pieces[3],
-            SecretId: pieces[4],
-        };
+        if (atom !== SECRET_ATOM) { throw new Error(`atom !== ${SECRET_ATOM} (E: 942f3ab95687772a5483ec926ad98124)`); }
+
+        if (type !== SecretType.password) { console.warn(`${lc} type !== SecretType.password. atow (02/2024) password is the only thing we got. (W: 66511ca217b045629a7816adc4e41fad)`) }
+
+        if (!name.match(SECRET_NAME_REGEXP)) { throw new Error(`!name.match(SECRET_NAME_REGEXP) (E: 6c95dbb65d3d6d9e0400412bf7ba6824)`); }
+
+        return { atom, type, name, };
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;
@@ -180,20 +199,28 @@ export async function createAndRegisterNewSecret({
     secretInfo,
     metaspace,
     space,
-    fnPromptSecret,
 }: {
     secretType: SecretType,
     secretInfo: SecretInfo,
     metaspace: MetaspaceService,
     space: IbGibSpaceAny,
-    fnPromptSecret: (space: IbGibSpaceAny) => Promise<SecretIbGib_V1 | undefined>,
-}): Promise<void> {
+}): Promise<SecretIbGib_V1> {
     const lc = `[${createAndRegisterNewSecret.name}]`;
     try {
         if (logalot) { console.log(`${lc} starting... (I: 08a3b2c784ff4689a8abf3ba8f1d7af4)`); }
 
+        let resSecretIbGib: SecretIbGib_V1;
+
         if (secretType !== SecretType.password) { throw new Error(`unknown secretType (${secretType}). only "password" secret type currently implemented. (E: ce3dd7aef4f48f9799f2d37217eed224)`); }
 
+        resSecretIbGib = await createAndRegisterNewSecret_password({
+            secretType: secretType as 'password',
+            secretInfo: secretInfo as SecretInfo_Password,
+            metaspace,
+            space,
+        });
+
+        return resSecretIbGib;
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;
@@ -207,32 +234,22 @@ async function createAndRegisterNewSecret_password({
     secretInfo,
     metaspace,
     space,
-    fnPromptSecret,
 }: {
     secretType: "password",
     secretInfo: SecretInfo_Password,
     metaspace: MetaspaceService,
     space: IbGibSpaceAny,
-    fnPromptSecret: (space: IbGibSpaceAny) => Promise<SecretIbGib_V1 | undefined>,
-}): Promise<void> {
+}): Promise<SecretIbGib_V1> {
     const lc = `[${createAndRegisterNewSecret_password.name}]`;
     try {
         if (logalot) { console.log(`${lc} starting... (I: ab330733d4b6bb733f5b5655bcd70a24)`); }
 
         if (secretType !== 'password') { throw new Error(`(UNEXPECTED) secretType !== 'password'? (E: b086c3494808a38ad967e55a82364824)`); }
 
-        const localIndex_secretIbGibs: IbGib_V1[] = await metaspace.getSpecialRel8dIbGibs({
-            type: SpecialIbGibType.secrets,
-            rel8nName: SECRET_REL8N_NAME,
-            space,
-        });
-
         // create the secret ibgib
-
         const data: SecretData_V1 = {
             ...secretInfo,
         };
-        const dataValidationErrors = validateCommonSecretData({ data });
         const resFirstGen = await Factory_V1.firstGen({
             ib: getSecretIb({ data }),
             parentIbGib: Factory_V1.primitive({ ib: SECRET_ATOM }),
@@ -241,10 +258,19 @@ async function createAndRegisterNewSecret_password({
             nCounter: true,
             tjp: { timestamp: true, },
         });
-
         const secretIbGib = resFirstGen.newIbGib as SecretIbGib_V1;
+
+        // validate right away before anything else
+        const validationErrors = await validateCommonSecretIbGib({ ibGib: secretIbGib }) ?? [];
+        if (validationErrors.length > 0) { throw new Error(`(UNEXPECTED) newly created secretIbGib has validationErrors? validationErrors: ${validationErrors} (E: 458708237973aea6c72121016d98af24)`); }
+
+        // save first in the space...
         await metaspace.persistTransformResult({ resTransform: resFirstGen, space });
+
+        // register the new secret with the ibgib space in general...
         await metaspace.registerNewIbGib({ ibGib: secretIbGib, space });
+
+        // register the new secret with the secrets index
         await metaspace.rel8ToSpecialIbGib({
             type: "secrets",
             rel8nName: SECRET_REL8N_NAME,
@@ -256,6 +282,137 @@ async function createAndRegisterNewSecret_password({
         //     rel8nName: SECRET_REL8N_NAME,
         //     space,
         // });
+
+        return secretIbGib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * executes the hash16816 fn on the incoming {@link password} using parameters
+ * {@link recursionCount}, {@link saltPrependedPerHash} and {@link algorithm}.
+ * Then selects a random contiguous substring of {@link substringLength} of the
+ * resultant hash.
+ *
+ * @returns {@link substringLength} of deterministic hash
+ *
+ * This is a novel idea only useful in a byzantine fault tolerant distributed
+ * computation context, so to understand how this is used, PLEASE...
+ * @see {@link CheckIfPasswordProbablyCorrectInfo}
+ */
+export async function getCheckIfPasswordProbablyCorrectInfo({
+    password,
+    substringLength,
+    recursionCount,
+    saltPrependedPerHash,
+    algorithm,
+}: {
+    /**
+     * string that we're going to hash and return the substring of.
+     */
+    password: string,
+    /**
+     * length of the substring of the hash
+     */
+    substringLength: number,
+    /**
+     * salt when recursively hashing
+     */
+    saltPrependedPerHash: string,
+    /**
+     * algorithm to use. defaults to 'SHA-256'
+     */
+    algorithm: HashAlgorithm,
+    /**
+     * number of recursions to do. Defaults to 16816.
+     */
+    recursionCount: number,
+}): Promise<CheckIfPasswordProbablyCorrectInfo> {
+    const lc = `[${getCheckIfPasswordProbablyCorrectInfo.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 9dc41fcf83a6d0e6054d3a9e79803224)`); }
+        if (!substringLength) { throw new Error(`substringLength (${substringLength}) required (E: d1d4fbfaa1562abac7ec42cdd0264224)`); }
+
+        recursionCount ??= 16816;
+        algorithm ??= 'SHA-256';
+
+        const fullHash = await hash16816({
+            s: password,
+            algorithm: 'SHA-256',
+            recursionCount,
+            saltPrependedPerHash,
+        });
+
+        // we want to pick a random starting point for the substring. on the
+        // consuming end, we don't need to know this random index, we will just
+        // confirm that the fullHash generated when the user enters their
+        // password conatins this substring at all (not where it starts from).
+
+        // 64 = length of sha256 hash
+        // 64-1 = 0-indexed adjustment
+        const r = Math.random();
+        const substringStartIndex = Math.floor(r * (63 - substringLength));
+
+        const resSubstring = fullHash.substring(substringStartIndex, substringStartIndex + substringLength);
+
+        // defensive checks here (atow 02/2024), remove at some point once we
+        // see that this isn't throwing and it's tested well enough
+        if (resSubstring.length !== substringLength) { throw new Error(`(UNEXPECTED) resSubstring.length (${resSubstring.length}) !== substringLength (${substringLength})?\nfullHash: ${fullHash}\nr: ${r}\nsubstringStartIndex: ${substringStartIndex}\nresSubstring: ${resSubstring}(E: c45acd126b4c70041e92f6ad5329c424)`); }
+        const confirmResult = await passwordProbablyCorrect({
+            password, checkInfo: {
+                substring: resSubstring,
+                algorithm,
+                recursionCount,
+                saltPrependedPerHash,
+            }
+        });
+        if (!confirmResult) { throw new Error(`(UNEXPECTED) !confirmResult? uhh... (E: cc757a8ef07b6468793b1bddbafca924)`); }
+
+        return {
+            substring: resSubstring,
+            saltPrependedPerHash: saltPrependedPerHash ?? '',
+            recursionCount,
+            algorithm,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * confirmation side of verifying if a consumer's password is **probably**
+ * correct. Basically computes the silly hash of the password and checks to see
+ * if it contains the given substring.
+ *
+ * @see {@link CheckIfPasswordProbablyCorrectInfo}
+ * @see {@link getCheckIfPasswordProbablyCorrectInfo}
+ */
+export async function passwordProbablyCorrect({
+    password,
+    checkInfo,
+}: {
+    password: string,
+    checkInfo: CheckIfPasswordProbablyCorrectInfo,
+}): Promise<boolean> {
+    const lc = `[${passwordProbablyCorrect.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: ce745a0d8b5de7a24ddc83fe432e4224)`); }
+        const { substring, recursionCount, saltPrependedPerHash, algorithm } = checkInfo;
+        const fullHash = await hash16816({
+            s: password,
+            recursionCount,
+            saltPrependedPerHash,
+            algorithm,
+        });
+        const resProbablyCorrect = fullHash.includes(substring);
+        return resProbablyCorrect;
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;

package/src/common/secret/secret-types.mts

@@ -2,6 +2,7 @@
  * @module secret types (and enums)
  */
 
+import { HashAlgorithm } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 
 export type SecretType = "password";
@@ -19,16 +20,12 @@ export interface SecretInfo {
 
 export interface SecretInfo_Password extends SecretInfo {
     type: 'password';
+
     /**
-     * We won't save the entire hash, just the hash.slice(16),
-     * because we are not checking to give authority, we are
-     * just checking to see if the user entered the same
-     * password for their own check.
-     *
-     * ## warnings
-     * NOTHING giving actual authorization should look at this.
+     * @see {@link CheckIfPasswordProbablyCorrectInfo}
      */
-    hash16816_SHA256: string;
+    passwordProbablyCorrectInfo: CheckIfPasswordProbablyCorrectInfo;
+
     /**
      * Public hint to help you remember your secret (or help the bad person
      * attack your secret).
@@ -36,6 +33,139 @@ export interface SecretInfo_Password extends SecretInfo {
     hint?: string;
 }
 
+/**
+ * This contains information for doing a **convenience check** of whether or
+ * not the user/consumer has entered a password that is "probably" correct.
+ *
+ * ## READ THIS
+ *
+ * Distributed sovereignty has different requirements than a trusted server
+ * approach when it comes to handling secrets.
+ *
+ * ### trusted servers store entire hashes for authentication
+ *
+ * In a trusted server approach, we will check the password against some hashing
+ * mechanism with varying implementation details. But we will almost certainly
+ * check against the entire hash, because we will decide authentication based on
+ * this proof.
+ *
+ * ### distributed data works differently
+ *
+ * In the distributed model, however, the only utility of a password is in
+ * encryption and signatures. So when a user/consumer enters a password, it
+ * actually **does** something, i.e., creates derivative data. Either it creates
+ * an encrypted file or performs a signature (I hesitate to discuss asymmetric
+ * encryption because I still don't believe in it, and when keystones are
+ * implemented in ibgib, passwords will evolve the stone (it works _somewhat_
+ * similarly to a double-ratchet algorithm but is more hardened and expressive
+ * because it works on top of ibgib's already-established "chaining"
+ * infrastructure)).
+ *
+ * But the question is:
+ *   **How does the user/consumer know that they entered the right password?**
+ *
+ * ### we can't store entire hashes
+ *
+ * In the distributed model, we assume a brute-forcer will have access to the
+ * encrypted data and any metadata we might store. This includes those would-be
+ * hashes and that would be bad - even if they are randomly salted.
+ *
+ * This is because this approach would preclude the ability for the user to
+ * encrypt some large data with mitigations against short-circuit decryption
+ * until the entire data block was decrypted (I refer you to encrypt-gib
+ * documentation here). IOW, the brute-forcer would only have to use the
+ * password and check against the hash, which can be an extremely quick
+ * operation - even if we set iterations insanely high on some KDF, this still
+ * would provide a relatively quick avenue for brute force attacks.
+ *
+ * ### we can store partial hashes
+ *
+ * We won't save the entire hash, just some substring of the hash. (We could
+ * conceivably store other metadata that checks against the hash, e.g., parity
+ * checks like the number of 1s, 2s, etc.).
+ *
+ * ### partial hash dynamics
+ *
+ * * The larger the partial hash, the less likely false collisions are produced.
+ *   * when a user typos a password, we do NOT want a false collision.
+ *   * when a brute-forcer makes a password attempt, we DO want a false
+ *     collision.
+ * * a user's **unique** typos compose the set that we want to avoid false
+ *   collisions.
+ *   * the same typo only counts once.
+ *
+ * So we want to...
+ * * maximize the time wasted in brute forcing
+ *   * or IOW, minimize the information gained by the brute forcer
+ *   * this will statistically slow down brute force attacks that work against
+ *     this information alone.
+ * * minimize the inconvenience by a password failure due to a false collision
+ *   by the legitimate user/consumer.
+ *   * there should be in place a well-hardened fail path for when the false
+ *     password is given but the false collision allows it to pass the initial
+ *     quick check phase.
+ *
+ * ### my implementation notes
+ *
+ * I am not doing this mathematically/rigorously, because that would take way
+ * too long, rather I am working from...
+ * * my personal experience with searching for hashes in the ibgib code bases.
+ *   * Most ibgib codebase error messages are accompanied by a hash to uniquely
+ *     identify the error.
+ *   * I often search the codebase based on a substring of this when I am
+ *     troubleshooting.
+ *   * atow (02/2024) there are 1171 of these hashes in just core-gib.
+ *   * To get a unique hash, the absolute MOST I have to actually enter is 4 or
+ *     5 letters
+ *     * 5 is extremely rare.
+ * * unit testing observations
+ *   * I've found that 4 letters gives false collisions on average every 900-ish
+ *     hashes.
+ *
+ * As such, I am setting the length to 4. But note that in consuming code, we
+ * always just check for the substring, so changing this value in the future
+ * should not affect code a la an exception thrown, but rather, it will just
+ * change this dynamic of good faith typos vs. brute force cracking.
+ *
+ * ## warnings
+ *
+ * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+ * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+ * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+ * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+ */
+export interface CheckIfPasswordProbablyCorrectInfo {
+    /**
+     * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+     * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+     * NOTHING GIVING ACTUAL AUTHORIZATION SHOULD CHECK AGAINST THIS INFO.
+     * @see {CheckIfPasswordProbablyCorrectInfo}
+     *
+     * substring contained in the resultant recursive hash built on the password
+     * and other parameters of this info.
+     *
+     * other parameters:
+     * * {@link recursions}
+     * * {@link saltPrependedPerHash}
+     * * {@link algorithm}
+     */
+    substring: string;
+    /**
+     * the number of times to recursively call the hash function, analogous to a
+     * naive key stretching algorithm.
+     */
+    recursionCount: number;
+    /**
+     * salt that will be prepended to the password/intermediate hash each hash
+     * round.
+     */
+    saltPrependedPerHash: string;
+    /**
+     * hash algorithm to use per hash round.
+     */
+    algorithm: HashAlgorithm;
+}
+
 // export type SecretData_V1 extends = SecretInfo; // extend this with logical OR later
 /**
  * ibgib's intrinsic data.