@ibgib/core-gib 0.1.60 → 0.1.62

package/src/keystone/keystone-helpers.mts

@@ -8,7 +8,7 @@ import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
 import { getGib } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
 
 import { GLOBAL_LOG_A_LOT } from "../core-constants.mjs";
-import { KEYSTONE_ATOM, KEYSTONE_HASH_MAX_ROUNDS, KEYSTONE_POOL_ID_REGEXP, KEYSTONE_SALT_REGEXP } from "./keystone-constants.mjs";
+import { KEYSTONE_ATOM, KEYSTONE_HASH_MAX_ROUNDS, KEYSTONE_POOL_ID_REGEXP, KEYSTONE_SALT_REGEXP, KEYSTONE_USERNAME_REGEXP, KEYSTONE_DESCRIPTION_REGEXP, KEYSTONE_VERB_MANAGE } from "./keystone-constants.mjs";
 import {
     KeystoneData_V1, KeystoneIbGib_V1, KeystoneIb_V1, KeystoneChallengePool,
     DeterministicResult, KeystoneProof, KeystonePoolConfig,
@@ -17,6 +17,7 @@ import {
     KeystoneChallengeType,
     KEYSTONE_CHALLENGE_TYPE_VALID_VALUES,
     KeystonePoolConfig_HashV1,
+    DelegateKeystoneInfo,
 } from "./keystone-types.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
 import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
@@ -90,12 +91,28 @@ export async function parseKeystoneIb({
     }
 }
 
+/**
+ * Helper to validate if an ib string is a well-formed keystone ib.
+ */
+export async function validateKeystoneIb({
+    ib,
+}: {
+    ib: Ib,
+}): Promise<boolean> {
+    try {
+        await parseKeystoneIb({ ib });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 /**
  * The Policy Engine.
  * Calculates exactly which challenges MUST be consumed based on config and demands.
  * Enforces STRICT DISTINCTNESS (No double-dipping).
  */
-export function getDeterministicRequirements({
+export async function getDeterministicRequirements({
     pool,
     requiredChallengeIds,
     targetAddr
@@ -103,7 +120,7 @@ export function getDeterministicRequirements({
     pool: KeystoneChallengePool;
     requiredChallengeIds?: string[];
     targetAddr?: string;
-}): DeterministicResult {
+}): Promise<DeterministicResult> {
     const behavior = pool.config.behavior;
     const mandatory = new Set<string>();
 
@@ -131,31 +148,34 @@ export function getDeterministicRequirements({
     }
 
     // ---------------------------------------------------------
-    // 2. Target Binding (Explicit Buckets)
+    // 2. Target Binding (Drawing Without Replacement)
     // ---------------------------------------------------------
-    if (behavior.targetBindingChars > 0 && targetAddr) {
-        const { gib } = getIbAndGib({ ibGibAddr: targetAddr });
-        if (gib) {
-            // Get required hex prefixes (e.g. 'a', 'b', 'c', '1')
-            const prefixes = gib !== GIB ?
-                gib.substring(0, behavior.targetBindingChars).toLowerCase() :
-                'abc'; // arbitrary for primitive binding target ibgib
-
-            for (const char of prefixes) {
-                // Look in the Explicit Bucket
-                const bucket = pool.bindingMap[char] || [];
-
-                // Find the first ID in this bucket that is still in 'available'
-                const match = bucket.find(id => available.includes(id));
-
-                if (!match) {
-                    throw new Error(`Entropy Exhaustion. Cannot satisfy binding for char '${char}'. (E: 341b95dc3a58be3e083d1d9c4a0c4925)`);
-                }
+    if (behavior.targetBindingCount > 0 && targetAddr) {
+        // Sort remaining available IDs alphabetically to ensure stable ordering across platforms
+        let sortedAvailable = [...available].sort();
 
-                // Strict: Consume it.
-                mandatory.add(match);
-                available = available.filter(id => id !== match);
+        // Start hashing path from targetAddr
+        let currentHash = await hash({ s: targetAddr });
+
+        for (let i = 0; i < behavior.targetBindingCount; i++) {
+            if (sortedAvailable.length === 0) {
+                throw new Error(`Entropy Exhaustion. Cannot satisfy target binding. Sorted available pool is empty. (E: 341b95dc3a58be3e083d1d9c4a0c4925)`);
             }
+
+            // Parse the entire hash via BigInt to eliminate modulo bias
+            const hashBigInt = BigInt("0x" + currentHash);
+            const index = Number(hashBigInt % BigInt(sortedAvailable.length));
+            const selectedId = sortedAvailable[index];
+
+            // Consume selected challenge ID
+            mandatory.add(selectedId);
+            sortedAvailable.splice(index, 1);
+
+            // Filter out of insertion-ordered available list (for FIFO)
+            available = available.filter(id => id !== selectedId);
+
+            // Hash recursively for the next draw
+            currentHash = await hash({ s: currentHash });
         }
     }
 
@@ -179,42 +199,7 @@ export function getDeterministicRequirements({
     return { mandatoryIds: mandatory, availableIds: available };
 }
 
-/**
- * Helper to update the Binding Map when adding new Challenge IDs.
- * Uses "Implicit Bucketing" (ID start char) but can be extended for full coverage.
- */
-export function addToBindingMap(
-    map: { [char: string]: string[] },
-    challengeId: string
-): void {
-    const firstChar = challengeId.charAt(0).toLowerCase();
-    // Validate it is hex
-    if (/[0-9a-f]/.test(firstChar)) {
-        if (!map[firstChar]) { map[firstChar] = []; }
-        map[firstChar].push(challengeId);
-
-        // OPTIONAL: Implement Full Coverage Strategy here?
-        // e.g. map[challengeId[1]].push(challengeId) ...
-        // For V1, we stick to Native/Implicit bucket (Index 0).
-    } else {
-        throw new Error(`invalid challengeId (${challengeId}). Must start with a hex character. (E: c96ed8460de89e28c801370a0f07f826)`);
-    }
-}
 
-/**
- * Helper to clean up Binding Map when removing IDs.
- */
-export function removeFromBindingMap(
-    map: { [char: string]: string[] },
-    challengeId: string
-): void {
-    // Since we don't know exactly which buckets an ID is in (if we did multi-bucket),
-    // we strictly should scan all. For V1 Native, we check first char.
-    // SAFE IMPLEMENTATION: Scan all buckets.
-    for (const key of Object.keys(map)) {
-        map[key] = map[key].filter(id => id !== challengeId);
-    }
-}
 
 /**
  * Selects the specific pool to use for an operation based on ID, filter criteria, or verb authorization.
@@ -297,7 +282,7 @@ export function resolveTargetPool({
  *
  * @returns Array of unique challenge IDs.
  */
-export function selectChallengeIds({
+export async function selectChallengeIds({
     pool,
     targetAddr,
     requiredChallengeIds,
@@ -311,11 +296,11 @@ export function selectChallengeIds({
      * Explicit demands from a verifier.
      */
     requiredChallengeIds?: string[];
-}): string[] {
+}): Promise<string[]> {
     const lc = `[selectChallengeIds]`;
     try {
         // 1. Get Deterministic Requirements
-        const { mandatoryIds, availableIds } = getDeterministicRequirements({
+        const { mandatoryIds, availableIds } = await getDeterministicRequirements({
             pool,
             requiredChallengeIds,
             targetAddr
@@ -398,11 +383,6 @@ export async function applyReplenishmentStrategy({
 
         const strategyType = config.behavior.replenish;
 
-        // Clean up Binding Map for consumed IDs
-        consumedIds.forEach(id => {
-            if (pool.bindingMap) { removeFromBindingMap(pool.bindingMap, id); }
-        });
-
         if (strategyType === KeystoneReplenishStrategy.topUp) {
             // Remove consumed
             consumedIds.forEach(id => delete pool.challenges[id]);
@@ -417,14 +397,9 @@ export async function applyReplenishmentStrategy({
                     poolSecret, poolId: pool.id, challengeId: newId
                 });
                 pool.challenges[newId] = await strategy.generateChallenge({ solution });
-
-                // Update Binding Map
-                if (!pool.bindingMap) { pool.bindingMap = {}; }
-                addToBindingMap(pool.bindingMap, newId);
             }
         } else if (strategyType === KeystoneReplenishStrategy.replaceAll) {
             pool.challenges = {};
-            pool.bindingMap = {};
 
             for (let i = 0; i < config.behavior.size; i++) {
                 const newId = await generateOpaqueChallengeId({
@@ -434,13 +409,11 @@ export async function applyReplenishmentStrategy({
                     poolSecret, poolId: pool.id, challengeId: newId
                 });
                 pool.challenges[newId] = await strategy.generateChallenge({ solution });
-                addToBindingMap(pool.bindingMap, newId);
             }
         } else if (strategyType === KeystoneReplenishStrategy.consume) {
             consumedIds.forEach(id => delete pool.challenges[id]);
         } else if (strategyType === KeystoneReplenishStrategy.deleteAll) {
             pool.challenges = {};
-            pool.bindingMap = {};
         } else {
             throw new Error(`Unknown replenish strategy: ${strategyType}. Valid list: ${pretty(KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES)} (E: 0acf56f1e1486240080e11e8046d0825)`);
         }
@@ -599,10 +572,14 @@ export async function validateChallengePool({ pool }: {
             }
 
             if (pool.config.behavior) {
-                const { size } = pool.config.behavior;
+                const { size, selectSequentially, selectRandomly, targetBindingCount } = pool.config.behavior;
                 if (!size || size === 0) {
                     errors.push(`${lc} invalid pool.config.behavior.size (${size}). Must be positive integer. (E: b221e36ec102bdc944552248ce8fe626)`)
                 }
+                const totalRequested = (selectSequentially || 0) + (selectRandomly || 0) + (targetBindingCount || 0);
+                if (totalRequested >= size) {
+                    errors.push(`${lc} Total requested challenges (${totalRequested}) cannot equal or exceed pool size (${size}) to prevent full pool exposure and selection exhaustion. (E: 81cb834f826315264bca81c15fca58f1)`);
+                }
                 // todo: more behavior checks
             } else {
                 errors.push(`${lc} pool.config.behavior falsy (E: bede081c066c39732eefe2f92e296326)`)
@@ -632,6 +609,35 @@ export async function validateChallengePool({ pool }: {
 }
 
 
+export function validateKeystoneMetadata({
+    data
+}: {
+    data: KeystoneData_V1;
+}): string[] {
+    const lc = `[validateKeystoneMetadata]`;
+    const errors: string[] = [];
+
+    const checkDetails = (details: any, source: string) => {
+        if (!details) return;
+        if (details.username !== undefined) {
+            if (typeof details.username !== 'string' || !KEYSTONE_USERNAME_REGEXP.test(details.username)) {
+                errors.push(`${lc} invalid username in ${source} (${details.username}). Must match ${KEYSTONE_USERNAME_REGEXP}`);
+            }
+        }
+        if (details.description !== undefined) {
+            if (typeof details.description !== 'string' || !KEYSTONE_DESCRIPTION_REGEXP.test(details.description)) {
+                errors.push(`${lc} invalid description in ${source} (${details.description}). Must match ${KEYSTONE_DESCRIPTION_REGEXP}`);
+            }
+        }
+    };
+
+    checkDetails(data.frameDetails, 'frameDetails');
+    checkDetails(data.checkpointDetails, 'checkpointDetails');
+
+    return errors;
+}
+
+
 export async function validateGenesisKeystone({
     keystoneIbGib
 }: {
@@ -645,6 +651,15 @@ export async function validateGenesisKeystone({
 
         const { data, rel8ns } = keystoneIbGib;
 
+        const isValidIb = await validateKeystoneIb({ ib: keystoneIbGib.ib });
+        if (!isValidIb) {
+            errors.push(`${lc} invalid keystone ib (${keystoneIbGib.ib}). (E: ad7a88bc38c290a184dfbd42be48f526)`);
+        }
+
+        // Validate username/description metadata if present
+        const metadataErrors = validateKeystoneMetadata({ data });
+        metadataErrors.forEach(x => errors.push(x));
+
         // no proofs/solutions yet
         if (data.proofs && data.proofs.length > 0) {
             errors.push(`${lc} proofs already exist on genesis keystone. (E: 7a5e15f20918f1bbd8ffb62857dcd526)`);
@@ -677,6 +692,89 @@ export async function validateGenesisKeystone({
     }
 }
 
+/**
+ * Helper to determine if two delegates maps differ.
+ */
+export function isDelegatesChanged({
+    currDelegates,
+    prevDelegates,
+}: {
+    currDelegates?: Record<string, DelegateKeystoneInfo>,
+    prevDelegates?: Record<string, DelegateKeystoneInfo>,
+}): boolean {
+    const curr = currDelegates || {};
+    const prev = prevDelegates || {};
+    const currKeys = Object.keys(curr);
+    const prevKeys = Object.keys(prev);
+
+    if (currKeys.length !== prevKeys.length) { return true; }
+
+    for (const key of currKeys) {
+        const currVal = curr[key];
+        const prevVal = prev[key];
+        if (!prevVal) { return true; }
+        if (currVal.delegateTjpAddr !== prevVal.delegateTjpAddr ||
+            currVal.delegateAddr !== prevVal.delegateAddr ||
+            currVal.thisAddr !== prevVal.thisAddr) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Validates the structure and constraints of the delegates map.
+ */
+export async function validateDelegates({
+    currDelegates,
+    prevIbGib,
+    lc,
+    errors,
+}: {
+    currDelegates: Record<string, DelegateKeystoneInfo>,
+    prevIbGib: KeystoneIbGib_V1,
+    lc: string,
+    errors: string[],
+}): Promise<void> {
+    const currKeys = Object.keys(currDelegates);
+    const prevAddr = getIbGibAddr({ ibGib: prevIbGib });
+
+    for (const key of currKeys) {
+        const info = currDelegates[key];
+        if (key !== info.delegateTjpAddr) {
+            errors.push(`${lc} Invalid delegate mapping: Key '${key}' does not match delegateTjpAddr '${info.delegateTjpAddr}'. (E: 9c8da8bc38c290a184dfbd42be48f526)`);
+        }
+
+        // Verify addresses are valid keystone addresses
+        const [
+            parsedDelegateTjp,
+            parsedDelegate,
+            parsedThis,
+        ] = await Promise.all([
+            validateKeystoneIb({ ib: info.delegateTjpAddr.split('^')[0] }),
+            validateKeystoneIb({ ib: info.delegateAddr.split('^')[0] }),
+            validateKeystoneIb({ ib: info.thisAddr.split('^')[0] }),
+        ]);
+
+        if (!parsedDelegateTjp) {
+            errors.push(`${lc} Delegate delegateTjpAddr '${info.delegateTjpAddr}' is not a valid keystone address. (E: 10d8a8bc38c290a184dfbd42be48f526)`);
+        }
+        if (!parsedDelegate) {
+            errors.push(`${lc} Delegate delegateAddr '${info.delegateAddr}' is not a valid keystone address. (E: 20d8a8bc38c290a184dfbd42be48f526)`);
+        }
+        if (!parsedThis) {
+            errors.push(`${lc} Delegate thisAddr '${info.thisAddr}' is not a valid keystone address. (E: 30d8a8bc38c290a184dfbd42be48f526)`);
+        }
+
+        // Verify thisAddr is in the parent's past (or is the current parent address)
+        const isHistoricalParent = info.thisAddr === prevAddr || (prevIbGib.rel8ns?.past || []).includes(info.thisAddr);
+        if (!isHistoricalParent) {
+            errors.push(`${lc} Delegate thisAddr '${info.thisAddr}' is not a valid historical address in the parent keystone timeline. (E: 40d8a8bc38c290a184dfbd42be48f526)`);
+        }
+    }
+}
+
 /**
  * Validates the transition from Prev -> Curr.
  * Enforces Cryptography AND Behavioral Policy.
@@ -707,24 +805,48 @@ export async function validateKeystoneTransition({
         const currData = currentIbGib.data!;
         const prevData = prevIbGib.data!;
 
+        const isValidIb = await validateKeystoneIb({ ib: currentIbGib.ib });
+        if (!isValidIb) {
+            errors.push(`${lc} invalid keystone ib (${currentIbGib.ib}). (E: a98dc8bc38c290a184dfbd42be48f526)`);
+        }
+
+        // Validate username/description metadata if present
+        const metadataErrors = validateKeystoneMetadata({ data: currData });
+        metadataErrors.forEach(x => errors.push(x));
+
+        // Validate delegates map mutations if present
+        const currDelegates = currData.delegates || {};
+        const prevDelegates = prevData.delegates || {};
+        const delegatesChanged = isDelegatesChanged({ currDelegates, prevDelegates });
+
+        if (delegatesChanged) {
+            const hasManageProof = currData.proofs?.some(proof => proof.claim?.verb === KEYSTONE_VERB_MANAGE);
+            if (!hasManageProof) {
+                errors.push(`${lc} Policy Violation: Delegates map was mutated but no proof for manage verb ('${KEYSTONE_VERB_MANAGE}') is present. (E: 819fa8cb28c9b60e68994511a5825)`);
+            }
+        }
+
+        // Validate each delegate's structure and constraints
+        await validateDelegates({ currDelegates, prevIbGib, lc, errors });
+
         // must be sequential data.n values
         // note: "-2" because we don't want a "valid" sequential data.n if we
         // have an invalid prev and a valid currDataN of 0
         const currDataN = currData.n ?? -2;
         const prevDataN = prevData.n ?? -2;
         if (currDataN < 0) {
-            errors.push('invalid keystone.currData.n is undefined or null.');
+            errors.push('invalid keystone.currData.n is undefined or null. (E: 9fbe38704b68829d18ea1d0940d0aa26)');
         }
         if (prevDataN < 0) {
-            errors.push('invalid keystone.prevData.n is undefined or null.');
+            errors.push('invalid keystone.prevData.n is undefined or null. (E: 6dc5aa9c87017db6080ed4268b07af26)');
         };
         if (currDataN !== (prevDataN + 1)) {
-            errors.push(`keystone data.n values are not sequential. prevData.n: ${prevDataN}, currData.n: ${currDataN}. `);
+            errors.push(`keystone data.n values are not sequential. prevData.n: ${prevDataN}, currData.n: ${currDataN}. (E: 5ae12809f2c67216d38d8ba8d6c42826)`);
         }
 
         for (const proof of currData.proofs) {
             if (proof.solutions.length === 0) {
-                errors.push(`Proof ${proof.id || 'unknown'} has no solutions.`);
+                errors.push(`Proof ${proof.id || 'unknown'} has no solutions. (E: e2b4683ce0ce30f798ec77841e88c826)`);
                 continue;
             }
 
@@ -784,7 +906,7 @@ export async function verifyProofAgainstPool({
         }
 
         // 1. Reconstruct Deterministic Requirements
-        const { mandatoryIds, availableIds } = getDeterministicRequirements({
+        const { mandatoryIds, availableIds } = await getDeterministicRequirements({
             pool,
             requiredChallengeIds: proof.requiredChallengeIds,
             targetAddr: proof.claim.target // Not used extensively in V1 logic yet, mainly for logging/context
@@ -863,6 +985,7 @@ export async function evolvePersistAndRegisterKeystone({
         if (prevData.challengePools) { dataToRemove.challengePools = []; }
         if (prevData.frameDetails) { dataToRemove.frameDetails = {}; }
         if (prevData.checkpointDetails) { dataToRemove.checkpointDetails = {}; }
+        if (prevData.delegates) { (dataToRemove as any).delegates = 'remove'; }
         if (Object.keys(dataToRemove).length === 0) { dataToRemove = undefined; }
 
         const resMut8 = await mut8({

package/src/keystone/keystone-policy-types.mts

@@ -6,20 +6,22 @@ export interface KeystoneBehaviorProfileTemplate {
     replenish: KeystoneReplenishStrategy;
     selectSequentially: number;
     selectRandomly: number;
-    targetBindingChars: number;
+    targetBindingCount: number;
 }
 
 export interface KeystonePoolTemplate {
     id: string;
     allowedVerbs: string[];
-    behaviorProfile?: string; // Reference to a behavior profile key
-    behaviorInline?: KeystoneBehaviorProfileTemplate; // Or specify behavior inline
+    behavior: KeystoneBehaviorProfileTemplate;
     algo: HashAlgorithm;
     rounds: number;
     type?: KeystoneChallengeType;
 }
 
 export interface KeystonePolicyConfigTemplate {
-    behaviorProfiles?: Record<string, KeystoneBehaviorProfileTemplate>;
+    metadata?: {
+        name?: string;
+        securityLevel?: string;
+    };
     pools: Record<string, KeystonePoolTemplate>;
 }