@ibgib/web-gib 0.0.11 → 0.0.12

package/src/keystone/keystone-config-builder.mts

@@ -0,0 +1,186 @@
+import {
+    KeystonePoolConfig,
+    KeystonePoolConfig_HashV1,
+    KeystonePoolBehavior,
+    KeystoneReplenishStrategy,
+    KeystonePoolConfigBase
+} from './keystone-types.mjs';
+import { POOL_ID_DEFAULT, POOL_ID_REVOKE, VERB_REVOKE } from './keystone-constants.mjs';
+
+/**
+ * Abstract Base Builder.
+ * Handles configuration common to ALL strategies (Salt, Size, Replenishment, Selection).
+ *
+ * @template TConfig The concrete config type being built.
+ */
+export abstract class KeystoneConfigBuilderBase<TConfig extends KeystonePoolConfigBase> {
+    protected _salt: string = 'default';
+    protected _size: number = 100;
+    protected _replenish: KeystoneReplenishStrategy = 'top-up';
+    protected _seq: number = 0;
+    protected _rand: number = 0;
+    protected _verbs: string[] = [];
+    protected _targetBinding: number = 0; // Default 0
+
+
+    /**
+     * Sets the unique salt/ID for this pool.
+     */
+    withSalt(salt: string): this {
+        this._salt = salt;
+        return this;
+    }
+
+    /**
+     * Sets the total number of challenges to maintain in the pool.
+     */
+    withSize(size: number): this {
+        this._size = size;
+        return this;
+    }
+
+    /**
+    * Binds challenge selection to the content address of the target.
+    * @param chars Number of hex characters to match (e.g. 4).
+    */
+    withTargetBinding(chars: number): this {
+        this._targetBinding = chars;
+        return this;
+    }
+
+    /**
+     * Configures the pool to use strictly Sequential (FIFO) selection.
+     * @param count Number of challenges to consume per sign.
+     */
+    withFIFO(count: number): this {
+        this._seq = count;
+        this._rand = 0;
+        return this;
+    }
+
+    /**
+     * Configures the pool to use strictly Random selection.
+     * @param count Number of challenges to consume per sign.
+     */
+    withRandom(count: number): this {
+        this._seq = 0;
+        this._rand = count;
+        return this;
+    }
+
+    /**
+     * Configures the pool to use Hybrid (Both FIFO and Random) selection.
+     */
+    withHybrid(seqCount: number, randCount: number): this {
+        this._seq = seqCount;
+        this._rand = randCount;
+        return this;
+    }
+
+    /**
+     * Sets the replenishment strategy.
+     */
+    withReplenishStrategy(strategy: KeystoneReplenishStrategy): this {
+        this._replenish = strategy;
+        return this;
+    }
+
+    /**
+     * Constructs the behavioral config object.
+     * Helper for subclasses.
+     */
+    protected buildBehavior(): KeystonePoolBehavior {
+        return {
+            size: this._size,
+            replenish: this._replenish,
+            selectSequentially: this._seq,
+            selectRandomly: this._rand,
+            targetBindingChars: this._targetBinding,
+        };
+    }
+
+    /**
+     * Restricts this pool to specific verbs.
+     * @param verbs List of verb addresses (e.g. 'revoke^gib')
+     */
+    forVerbs(verbs: string[]): this {
+        this._verbs = verbs;
+        return this;
+    }
+
+    protected buildBase(): KeystonePoolConfigBase {
+        // Helper to keep the concrete build() clean
+        return {
+            type: 'hash-reveal-v1', // This is overridden by concrete/interface usually, but needed for base shape
+            salt: this._salt,
+            allowedVerbs: this._verbs
+        } as any;
+    }
+
+    abstract build(): TConfig;
+}
+
+/**
+ * Concrete Builder for Hash-Reveal V1 Strategy.
+ */
+export class KeystoneConfigBuilder_HashV1 extends KeystoneConfigBuilderBase<KeystonePoolConfig_HashV1> {
+    private _algo: 'SHA-256' | 'SHA-512' = 'SHA-256';
+    private _rounds: number = 1;
+
+    /**
+     * Sets the hashing strength.
+     */
+    withHash(algo: 'SHA-256' | 'SHA-512', rounds: number = 1): this {
+        this._algo = algo;
+        this._rounds = rounds;
+        return this;
+    }
+
+    build(): KeystonePoolConfig_HashV1 {
+        return {
+            type: 'hash-reveal-v1',
+            salt: this._salt,
+            allowedVerbs: this._verbs, // <--- Mapped here
+            behavior: this.buildBehavior(),
+            algo: this._algo,
+            rounds: this._rounds,
+        };
+    }
+}
+
+// ===========================================================================
+// STATIC ENTRY POINT (Optional Convenience)
+// ===========================================================================
+
+export class KeystoneConfig {
+    static hash(): KeystoneConfigBuilder_HashV1 {
+        return new KeystoneConfigBuilder_HashV1();
+    }
+
+    // Future:
+    // static pow(): KeystoneConfigBuilder_PoW { ... }
+}
+
+// ===========================================================================
+// FACTORY FUNCTIONS (Presets)
+// ===========================================================================
+
+export function createStandardPoolConfig(salt: string = POOL_ID_DEFAULT): KeystonePoolConfig {
+    return KeystoneConfig.hash()
+        .withSalt(salt)
+        .withSize(100)
+        .withHybrid(2, 2)
+        .withReplenishStrategy('top-up')
+        .build();
+}
+
+export function createRevocationPoolConfig(salt: string = POOL_ID_REVOKE): KeystonePoolConfig {
+    return KeystoneConfig.hash()
+        .withSalt(salt)
+        .withHash('SHA-256', 10)
+        .withSize(500)
+        .withHybrid(10, 10)
+        .withReplenishStrategy(KeystoneReplenishStrategy.scorchedEarth)
+        .forVerbs([VERB_REVOKE])
+        .build();
+}

package/src/keystone/keystone-constants.mts

@@ -0,0 +1,16 @@
+export const KEYSTONE_ATOM = "keystone";
+
+/**
+ * The specific ibGib address for the 'revoke' verb.
+ * Used in Claims to indicate the Keystone should be considered dead.
+ *
+ * NOTE: This is a primitive ibGib address (ib='revoke', gib='gib'),
+ * _but with the `gib` being implied_.
+ */
+export const VERB_REVOKE = "revoke";
+
+/**
+ * Standard pool IDs can be conventionally named after their primary verb.
+ */
+export const POOL_ID_REVOKE = VERB_REVOKE;
+export const POOL_ID_DEFAULT = "default";

package/src/keystone/keystone-helpers.mts

@@ -0,0 +1,207 @@
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { Ib, TransformResult } from "@ibgib/ts-gib/dist/types.mjs";
+import { getIbAndGib } from "@ibgib/ts-gib/dist/helper.mjs";
+import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../constants.mjs";
+import { KEYSTONE_ATOM } from "./keystone-constants.mjs";
+import { KeystoneData_V1, KeystoneIbGib_V1, KeystoneIbInfo_V1, KeystoneChallengePool } from "./keystone-types.mjs";
+import { getGib } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * space-delimited keystone ib containing select keystone metadata.
+ *
+ * NOTE: This must match {@link parseKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export async function getKeystoneIb({
+    keystoneData,
+}: {
+    keystoneData: KeystoneData_V1,
+}): Promise<Ib> {
+    const lc = `[${getKeystoneIb.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: c3022a146faac9730154f34d1439a225)`); }
+
+        const atom = KEYSTONE_ATOM;
+
+        const ib = [
+            atom,
+        ].join(' ');
+
+        return ib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * NOTE: This must match {@link getKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export async function parseKeystoneIb({
+    ib,
+}: {
+    ib: Ib,
+}): Promise<KeystoneIbInfo_V1> {
+    const lc = `[${parseKeystoneIb.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 73cb6832984255ed48b2f44db6a21e25)`); }
+        const [
+            atom
+        ] = ib.split(' ');
+
+        if (atom !== KEYSTONE_ATOM) {
+            throw new Error(`invalid keystone ib. atom found in ib (${atom}) does not match keystone atom (${KEYSTONE_ATOM}) (E: 79b3d587824c4271b6e60acc76e0c825)`);
+        }
+
+        return {
+            atom,
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+export interface DeterministicResult {
+    /**
+     * The Set of IDs that MUST be present in the solution.
+     * Includes Alice's Demands + Target Binding Matches + FIFO.
+     */
+    mandatoryIds: Set<string>;
+
+    /**
+     * The IDs remaining in the pool that are valid candidates for
+     * the Random/Stochastic step.
+     */
+    availableIds: string[];
+}
+
+/**
+ * The Policy Engine.
+ * Calculates exactly which challenges MUST be consumed based on config and demands.
+ * Enforces STRICT DISTINCTNESS (No double-dipping).
+ */
+export function getDeterministicRequirements({
+    pool,
+    requiredChallengeIds,
+    targetAddr
+}: {
+    pool: KeystoneChallengePool;
+    requiredChallengeIds?: string[];
+    targetAddr?: string;
+}): DeterministicResult {
+    const behavior = pool.config.behavior;
+    const mandatory = new Set<string>();
+
+    // Start with all available IDs.
+    // We assume Object.keys respects insertion order (ES2015+), crucial for FIFO.
+    let available = Object.keys(pool.challenges);
+
+    // ---------------------------------------------------------
+    // 1. Alice's Demands (Explicit Requirements)
+    // ---------------------------------------------------------
+    if (requiredChallengeIds && requiredChallengeIds.length > 0) {
+        for (const id of requiredChallengeIds) {
+            if (!pool.challenges[id]) {
+                throw new Error(`(UNEXPECTED) Required challenge ID not found in pool: ${id} (E: 2c9f8...)`);
+            }
+            // Strict: Consume it.
+            if (!available.includes(id)) {
+                // Should be caught by check above, but handles duplicates in 'demands'
+                continue;
+            }
+            mandatory.add(id);
+        }
+        // Remove from available pool
+        available = available.filter(id => !mandatory.has(id));
+    }
+
+    // ---------------------------------------------------------
+    // 2. Target Binding (Explicit Buckets)
+    // ---------------------------------------------------------
+    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.substring(0, behavior.targetBindingChars).toLowerCase();
+
+            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: 8d3a1...)`);
+                }
+
+                // Strict: Consume it.
+                mandatory.add(match);
+                available = available.filter(id => id !== match);
+            }
+        }
+    }
+
+    // ---------------------------------------------------------
+    // 3. FIFO (Sequential)
+    // ---------------------------------------------------------
+    if (behavior.selectSequentially > 0) {
+        // Take the first N from the remaining available list
+        if (available.length < behavior.selectSequentially) {
+            throw new Error(`Entropy Exhaustion. Insufficient challenges for FIFO requirement. (E: 9c2b4...)`);
+        }
+
+        const fifoIds = available.slice(0, behavior.selectSequentially);
+        fifoIds.forEach(id => mandatory.add(id));
+
+        // Remove from available
+        available = available.slice(behavior.selectSequentially);
+    }
+
+    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).
+    }
+}
+
+/**
+ * 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);
+    }
+}