@ibgib/core-gib 0.1.59 → 0.1.61

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 } from "./keystone-constants.mjs";
 import {
     KeystoneData_V1, KeystoneIbGib_V1, KeystoneIb_V1, KeystoneChallengePool,
     DeterministicResult, KeystoneProof, KeystonePoolConfig,
@@ -95,7 +95,7 @@ export async function parseKeystoneIb({
  * 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 +103,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 +131,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();
+
+        // Start hashing path from targetAddr
+        let currentHash = await hash({ s: targetAddr });
 
-                // Strict: Consume it.
-                mandatory.add(match);
-                available = available.filter(id => id !== match);
+        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 +182,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 +265,7 @@ export function resolveTargetPool({
  *
  * @returns Array of unique challenge IDs.
  */
-export function selectChallengeIds({
+export async function selectChallengeIds({
     pool,
     targetAddr,
     requiredChallengeIds,
@@ -311,11 +279,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 +366,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 +380,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 +392,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 +555,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 +592,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 +634,10 @@ export async function validateGenesisKeystone({
 
         const { data, rel8ns } = keystoneIbGib;
 
+        // 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)`);
@@ -707,6 +700,10 @@ export async function validateKeystoneTransition({
         const currData = currentIbGib.data!;
         const prevData = prevIbGib.data!;
 
+        // Validate username/description metadata if present
+        const metadataErrors = validateKeystoneMetadata({ data: currData });
+        metadataErrors.forEach(x => errors.push(x));
+
         // 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
@@ -784,7 +781,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

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>;
 }

package/src/keystone/keystone-service-v1.mts

@@ -9,7 +9,7 @@ import {
 import { KeystoneStrategyFactory } from './strategy/keystone-strategy-factory.mjs';
 import { POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_VERB_MANAGE, KEYSTONE_CHECKPOINT_FREQUENCY } from './keystone-constants.mjs';
 import {
-    addToBindingMap, createKeystoneIbGibImpl, evolvePersistAndRegisterKeystone,
+    createKeystoneIbGibImpl, evolvePersistAndRegisterKeystone,
     generateOpaqueChallengeId, resolveTargetPool, selectChallengeIds,
     solveAndReplenish, validateKeystoneTransition,
     validateGenesisKeystone, validateKeystoneGraph
@@ -54,7 +54,6 @@ export class KeystoneService_V1 {
                 const strategy = KeystoneStrategyFactory.create({ config });
                 const poolSecret = await strategy.derivePoolSecret({ masterSecret });
                 const challenges: { [id: string]: any } = {};
-                const bindingMap: { [char: string]: string[] } = {};
 
                 const targetSize = config.behavior.size;
                 const timestamp = Date.now().toString();
@@ -69,16 +68,12 @@ export class KeystoneService_V1 {
                     });
                     const challenge = await strategy.generateChallenge({ solution });
                     challenges[challengeId] = challenge;
-
-                    // Populate Binding Map
-                    addToBindingMap(bindingMap, challengeId);
                 }
 
                 challengePools.push({
                     id: config.id,
                     config,
                     challenges,
-                    bindingMap
                 });
             }
 
@@ -158,7 +153,7 @@ export class KeystoneService_V1 {
             if (logalot) { console.log(`${lc} Selected pool: ${pool.id} (size: ${Object.keys(pool.challenges).length}) (I: 6b26d6f4aad18380f2b3a0989b592826)`); }
 
             // 2. Calculate Costs (Select IDs)
-            const idsToSolve = selectChallengeIds({
+            const idsToSolve = await selectChallengeIds({
                 pool,
                 targetAddr: claim.target,
                 requiredChallengeIds
@@ -384,7 +379,7 @@ export class KeystoneService_V1 {
             };
 
             // 3. Calculate Costs
-            const idsToSolve = selectChallengeIds({
+            const idsToSolve = await selectChallengeIds({
                 pool,
                 targetAddr: claim.target,
                 requiredChallengeIds: []
@@ -515,7 +510,7 @@ export class KeystoneService_V1 {
             };
 
             // 3. Calculate Costs
-            const idsToSolve = selectChallengeIds({
+            const idsToSolve = await selectChallengeIds({
                 pool: adminPool,
                 targetAddr: target
             });