@ibgib/web-gib 0.0.11 → 0.0.12

package/dist/keystone/keystone-config-builder.d.mts

@@ -0,0 +1,77 @@
+import { KeystonePoolConfig, KeystonePoolConfig_HashV1, KeystonePoolBehavior, KeystoneReplenishStrategy, KeystonePoolConfigBase } from './keystone-types.mjs';
+/**
+ * Abstract Base Builder.
+ * Handles configuration common to ALL strategies (Salt, Size, Replenishment, Selection).
+ *
+ * @template TConfig The concrete config type being built.
+ */
+export declare abstract class KeystoneConfigBuilderBase<TConfig extends KeystonePoolConfigBase> {
+    protected _salt: string;
+    protected _size: number;
+    protected _replenish: KeystoneReplenishStrategy;
+    protected _seq: number;
+    protected _rand: number;
+    protected _verbs: string[];
+    protected _targetBinding: number;
+    /**
+     * Sets the unique salt/ID for this pool.
+     */
+    withSalt(salt: string): this;
+    /**
+     * Sets the total number of challenges to maintain in the pool.
+     */
+    withSize(size: number): 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;
+    /**
+     * Configures the pool to use strictly Sequential (FIFO) selection.
+     * @param count Number of challenges to consume per sign.
+     */
+    withFIFO(count: number): this;
+    /**
+     * Configures the pool to use strictly Random selection.
+     * @param count Number of challenges to consume per sign.
+     */
+    withRandom(count: number): this;
+    /**
+     * Configures the pool to use Hybrid (Both FIFO and Random) selection.
+     */
+    withHybrid(seqCount: number, randCount: number): this;
+    /**
+     * Sets the replenishment strategy.
+     */
+    withReplenishStrategy(strategy: KeystoneReplenishStrategy): this;
+    /**
+     * Constructs the behavioral config object.
+     * Helper for subclasses.
+     */
+    protected buildBehavior(): KeystonePoolBehavior;
+    /**
+     * Restricts this pool to specific verbs.
+     * @param verbs List of verb addresses (e.g. 'revoke^gib')
+     */
+    forVerbs(verbs: string[]): this;
+    protected buildBase(): KeystonePoolConfigBase;
+    abstract build(): TConfig;
+}
+/**
+ * Concrete Builder for Hash-Reveal V1 Strategy.
+ */
+export declare class KeystoneConfigBuilder_HashV1 extends KeystoneConfigBuilderBase<KeystonePoolConfig_HashV1> {
+    private _algo;
+    private _rounds;
+    /**
+     * Sets the hashing strength.
+     */
+    withHash(algo: 'SHA-256' | 'SHA-512', rounds?: number): this;
+    build(): KeystonePoolConfig_HashV1;
+}
+export declare class KeystoneConfig {
+    static hash(): KeystoneConfigBuilder_HashV1;
+}
+export declare function createStandardPoolConfig(salt?: string): KeystonePoolConfig;
+export declare function createRevocationPoolConfig(salt?: string): KeystonePoolConfig;
+//# sourceMappingURL=keystone-config-builder.d.mts.map

package/dist/keystone/keystone-config-builder.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-config-builder.d.mts","sourceRoot":"","sources":["../../src/keystone/keystone-config-builder.mts"],"names":[],"mappings":"AAAA,OAAO,EACH,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,EACpB,yBAAyB,EACzB,sBAAsB,EACzB,MAAM,sBAAsB,CAAC;AAG9B;;;;;GAKG;AACH,8BAAsB,yBAAyB,CAAC,OAAO,SAAS,sBAAsB;IAClF,SAAS,CAAC,KAAK,EAAE,MAAM,CAAa;IACpC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAO;IAC9B,SAAS,CAAC,UAAU,EAAE,yBAAyB,CAAY;IAC3D,SAAS,CAAC,IAAI,EAAE,MAAM,CAAK;IAC3B,SAAS,CAAC,KAAK,EAAE,MAAM,CAAK;IAC5B,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAM;IAChC,SAAS,CAAC,cAAc,EAAE,MAAM,CAAK;IAGrC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B;;;MAGE;IACF,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKtC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM7B;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM/B;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAMrD;;OAEG;IACH,qBAAqB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAKhE;;;OAGG;IACH,SAAS,CAAC,aAAa,IAAI,oBAAoB;IAU/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAK/B,SAAS,CAAC,SAAS,IAAI,sBAAsB;IAS7C,QAAQ,CAAC,KAAK,IAAI,OAAO;CAC5B;AAED;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,yBAAyB,CAAC,yBAAyB,CAAC;IAClG,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,OAAO,CAAa;IAE5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,EAAE,MAAM,GAAE,MAAU,GAAG,IAAI;IAM/D,KAAK,IAAI,yBAAyB;CAUrC;AAMD,qBAAa,cAAc;IACvB,MAAM,CAAC,IAAI,IAAI,4BAA4B;CAM9C;AAMD,wBAAgB,wBAAwB,CAAC,IAAI,GAAE,MAAwB,GAAG,kBAAkB,CAO3F;AAED,wBAAgB,0BAA0B,CAAC,IAAI,GAAE,MAAuB,GAAG,kBAAkB,CAS5F"}

package/dist/keystone/keystone-config-builder.mjs

@@ -0,0 +1,156 @@
+import { KeystoneReplenishStrategy } 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 class KeystoneConfigBuilderBase {
+    _salt = 'default';
+    _size = 100;
+    _replenish = 'top-up';
+    _seq = 0;
+    _rand = 0;
+    _verbs = [];
+    _targetBinding = 0; // Default 0
+    /**
+     * Sets the unique salt/ID for this pool.
+     */
+    withSalt(salt) {
+        this._salt = salt;
+        return this;
+    }
+    /**
+     * Sets the total number of challenges to maintain in the pool.
+     */
+    withSize(size) {
+        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) {
+        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) {
+        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) {
+        this._seq = 0;
+        this._rand = count;
+        return this;
+    }
+    /**
+     * Configures the pool to use Hybrid (Both FIFO and Random) selection.
+     */
+    withHybrid(seqCount, randCount) {
+        this._seq = seqCount;
+        this._rand = randCount;
+        return this;
+    }
+    /**
+     * Sets the replenishment strategy.
+     */
+    withReplenishStrategy(strategy) {
+        this._replenish = strategy;
+        return this;
+    }
+    /**
+     * Constructs the behavioral config object.
+     * Helper for subclasses.
+     */
+    buildBehavior() {
+        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) {
+        this._verbs = verbs;
+        return this;
+    }
+    buildBase() {
+        // Helper to keep the concrete build() clean
+        return {
+            type: 'hash-reveal-v1',
+            salt: this._salt,
+            allowedVerbs: this._verbs
+        };
+    }
+}
+/**
+ * Concrete Builder for Hash-Reveal V1 Strategy.
+ */
+export class KeystoneConfigBuilder_HashV1 extends KeystoneConfigBuilderBase {
+    _algo = 'SHA-256';
+    _rounds = 1;
+    /**
+     * Sets the hashing strength.
+     */
+    withHash(algo, rounds = 1) {
+        this._algo = algo;
+        this._rounds = rounds;
+        return this;
+    }
+    build() {
+        return {
+            type: 'hash-reveal-v1',
+            salt: this._salt,
+            allowedVerbs: this._verbs,
+            behavior: this.buildBehavior(),
+            algo: this._algo,
+            rounds: this._rounds,
+        };
+    }
+}
+// ===========================================================================
+// STATIC ENTRY POINT (Optional Convenience)
+// ===========================================================================
+export class KeystoneConfig {
+    static hash() {
+        return new KeystoneConfigBuilder_HashV1();
+    }
+}
+// ===========================================================================
+// FACTORY FUNCTIONS (Presets)
+// ===========================================================================
+export function createStandardPoolConfig(salt = POOL_ID_DEFAULT) {
+    return KeystoneConfig.hash()
+        .withSalt(salt)
+        .withSize(100)
+        .withHybrid(2, 2)
+        .withReplenishStrategy('top-up')
+        .build();
+}
+export function createRevocationPoolConfig(salt = POOL_ID_REVOKE) {
+    return KeystoneConfig.hash()
+        .withSalt(salt)
+        .withHash('SHA-256', 10)
+        .withSize(500)
+        .withHybrid(10, 10)
+        .withReplenishStrategy(KeystoneReplenishStrategy.scorchedEarth)
+        .forVerbs([VERB_REVOKE])
+        .build();
+}
+//# sourceMappingURL=keystone-config-builder.mjs.map

package/dist/keystone/keystone-config-builder.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-config-builder.mjs","sourceRoot":"","sources":["../../src/keystone/keystone-config-builder.mts"],"names":[],"mappings":"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"}

package/dist/keystone/keystone-constants.d.mts

@@ -0,0 +1,15 @@
+export declare 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 declare const VERB_REVOKE = "revoke";
+/**
+ * Standard pool IDs can be conventionally named after their primary verb.
+ */
+export declare const POOL_ID_REVOKE = "revoke";
+export declare const POOL_ID_DEFAULT = "default";
+//# sourceMappingURL=keystone-constants.d.mts.map

package/dist/keystone/keystone-constants.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-constants.d.mts","sourceRoot":"","sources":["../../src/keystone/keystone-constants.mts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,cAAc,WAAc,CAAC;AAC1C,eAAO,MAAM,eAAe,YAAY,CAAC"}

package/dist/keystone/keystone-constants.mjs

@@ -0,0 +1,15 @@
+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";
+//# sourceMappingURL=keystone-constants.mjs.map

package/dist/keystone/keystone-constants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-constants.mjs","sourceRoot":"","sources":["../../src/keystone/keystone-constants.mts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;AAC1C,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC"}

package/dist/keystone/keystone-helpers.d.mts

@@ -0,0 +1,54 @@
+import { Ib } from "@ibgib/ts-gib/dist/types.mjs";
+import { KeystoneData_V1, KeystoneIbInfo_V1, KeystoneChallengePool } from "./keystone-types.mjs";
+/**
+ * space-delimited keystone ib containing select keystone metadata.
+ *
+ * NOTE: This must match {@link parseKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export declare function getKeystoneIb({ keystoneData, }: {
+    keystoneData: KeystoneData_V1;
+}): Promise<Ib>;
+/**
+ * NOTE: This must match {@link getKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export declare function parseKeystoneIb({ ib, }: {
+    ib: Ib;
+}): Promise<KeystoneIbInfo_V1>;
+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 declare function getDeterministicRequirements({ pool, requiredChallengeIds, targetAddr }: {
+    pool: KeystoneChallengePool;
+    requiredChallengeIds?: string[];
+    targetAddr?: string;
+}): DeterministicResult;
+/**
+ * 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 declare function addToBindingMap(map: {
+    [char: string]: string[];
+}, challengeId: string): void;
+/**
+ * Helper to clean up Binding Map when removing IDs.
+ */
+export declare function removeFromBindingMap(map: {
+    [char: string]: string[];
+}, challengeId: string): void;
+//# sourceMappingURL=keystone-helpers.d.mts.map

package/dist/keystone/keystone-helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-helpers.d.mts","sourceRoot":"","sources":["../../src/keystone/keystone-helpers.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAmB,MAAM,8BAA8B,CAAC;AAMnE,OAAO,EAAE,eAAe,EAAoB,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAKnH;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,EAChC,YAAY,GACf,EAAE;IACC,YAAY,EAAE,eAAe,CAAC;CACjC,GAAG,OAAO,CAAC,EAAE,CAAC,CAkBd;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,EAClC,EAAE,GACL,EAAE;IACC,EAAE,EAAE,EAAE,CAAC;CACV,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqB7B;AAED,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAE1B;;;OAGG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,EACzC,IAAI,EACJ,oBAAoB,EACpB,UAAU,EACb,EAAE;IACC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,mBAAmB,CAuEtB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,GAAG,EAAE;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,EACjC,WAAW,EAAE,MAAM,GACpB,IAAI,CAWN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAChC,GAAG,EAAE;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,EACjC,WAAW,EAAE,MAAM,GACpB,IAAI,CAON"}

package/dist/keystone/keystone-helpers.mjs

@@ -0,0 +1,155 @@
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { getIbAndGib } from "@ibgib/ts-gib/dist/helper.mjs";
+import { GLOBAL_LOG_A_LOT } from "../constants.mjs";
+import { KEYSTONE_ATOM } from "./keystone-constants.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, }) {
+    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, }) {
+    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.`);
+        }
+    }
+}
+/**
+ * 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 }) {
+    const behavior = pool.config.behavior;
+    const mandatory = new Set();
+    // 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, challengeId) {
+    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, challengeId) {
+    // 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);
+    }
+}
+//# sourceMappingURL=keystone-helpers.mjs.map

package/dist/keystone/keystone-helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-helpers.mjs","sourceRoot":"","sources":["../../src/keystone/keystone-helpers.mts"],"names":[],"mappings":"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"}

package/dist/keystone/keystone-service-v1.d.mts

@@ -0,0 +1,81 @@
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { MetaspaceService } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+import { KeystoneIbGib_V1, KeystonePoolConfig, KeystoneClaim } from './keystone-types.mjs';
+/**
+ * Facade for managing Keystone Identities.
+ *
+ * Handles Genesis, Authorized Evolution (Signing), and Validation.
+ */
+export declare class KeystoneService_V1 {
+    protected lc: string;
+    /**
+     * Creates a brand new Keystone Identity Timeline.
+     */
+    genesis({ masterSecret, configs, metaspace, space, }: {
+        masterSecret: string;
+        configs: KeystonePoolConfig[];
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1>;
+    /**
+     * Signs a claim using a hybrid selection strategy.
+     * Supports: Mandatory IDs (Alice) + Sequential (FIFO) + Random (Stochastic).
+     */
+    sign({ latestKeystone, masterSecret, claim, poolId, requiredChallengeIds, frameDetails, metaspace, space, }: {
+        latestKeystone: KeystoneIbGib_V1;
+        masterSecret: string;
+        claim: Partial<KeystoneClaim>;
+        poolId?: string;
+        requiredChallengeIds?: string[];
+        frameDetails?: any;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1>;
+    /**
+     * Validates the transition from Prev -> Curr.
+     * Enforces Cryptography AND Behavioral Policy.
+     *
+     * @returns Array of validation error strings. Empty array means Valid.
+     */
+    validate({ currentIbGib, prevIbGib, }: {
+        currentIbGib: KeystoneIbGib_V1;
+        prevIbGib: KeystoneIbGib_V1;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<string[]>;
+    /**
+     * Permanently revokes the Identity.
+     *
+     * Logic:
+     * 1. Locates the 'revoke' pool.
+     * 2. Consumes ALL available challenges in that pool (Scorched Earth).
+     * 3. Sets the revocationInfo on the new frame.
+     */
+    revoke({ latestKeystone, masterSecret, reason, frameDetails, metaspace, space, }: {
+        latestKeystone: KeystoneIbGib_V1;
+        masterSecret: string;
+        reason?: string;
+        frameDetails?: any;
+        metaspace: MetaspaceService;
+        space?: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1>;
+    /**
+     * Generates an opaque, collision-resistant ID for a challenge.
+     * Hash(Salt + Timestamp + Index)
+     */
+    private generateOpaqueChallengeId;
+    private applyReplenishmentStrategy;
+    /**
+     * Creates a new keystone ibgib that has no dna and no past.
+     */
+    private createKeystoneIbGibImpl;
+    /**
+     * for signing/revoking, the newData is entirely new per frame, i.e., we
+     * replace all relevant keystone information. IOW we are not just patching
+     * the data by adding or replacing keys, we are providing all pools, claim,
+     * solutions, required, and frameDetails. So this implementation is required
+     * to remove each of the old keys in the call to {@link mut8}.
+     */
+    private evolveKeystoneIbGibImpl;
+}
+//# sourceMappingURL=keystone-service-v1.d.mts.map

package/dist/keystone/keystone-service-v1.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-service-v1.d.mts","sourceRoot":"","sources":["../../src/keystone/keystone-service-v1.mts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,sDAAsD,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kEAAkE,CAAC;AAGpG,OAAO,EAEH,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EAOhB,MAAM,sBAAsB,CAAC;AAW9B;;;;GAIG;AACH,qBAAa,kBAAkB;IAC3B,SAAS,CAAC,EAAE,EAAE,MAAM,CAAkC;IAEtD;;OAEG;IACG,OAAO,CAAC,EACV,YAAY,EACZ,OAAO,EACP,SAAS,EACT,KAAK,GACR,EAAE;QACC,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,kBAAkB,EAAE,CAAC;QAC9B,SAAS,EAAE,gBAAgB,CAAC;QAC5B,KAAK,EAAE,aAAa,CAAC;KACxB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqD7B;;;OAGG;IACG,IAAI,CAAC,EACP,cAAc,EACd,YAAY,EACZ,KAAK,EACL,MAAM,EACN,oBAAyB,EACzB,YAAY,EACZ,SAAS,EACT,KAAK,GACR,EAAE;QACC,cAAc,EAAE,gBAAgB,CAAC;QACjC,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;QAChC,YAAY,CAAC,EAAE,GAAG,CAAC;QACnB,SAAS,EAAE,gBAAgB,CAAC;QAC5B,KAAK,EAAE,aAAa,CAAC;KACxB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmH7B;;;;;OAKG;IACG,QAAQ,CAAC,EACX,YAAY,EACZ,SAAS,GACZ,EAAE;QACC,YAAY,EAAE,gBAAgB,CAAC;QAC/B,SAAS,EAAE,gBAAgB,CAAC;QAC5B,SAAS,EAAE,gBAAgB,CAAC;QAC5B,KAAK,EAAE,aAAa,CAAC;KACxB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmGrB;;;;;;;OAOG;IACG,MAAM,CAAC,EACT,cAAc,EACd,YAAY,EACZ,MAAoC,EACpC,YAAY,EACZ,SAAS,EACT,KAAK,GACR,EAAE;QACC,cAAc,EAAE,gBAAgB,CAAC;QACjC,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,GAAG,CAAC;QACnB,SAAS,EAAE,gBAAgB,CAAC;QAC5B,KAAK,CAAC,EAAE,aAAa,CAAC;KACzB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2F7B;;;OAGG;YACW,yBAAyB;YAgBzB,0BAA0B;IA+ExC;;OAEG;YACW,uBAAuB;IA0ErC;;;;;;OAMG;YACW,uBAAuB;CAuExC"}