@ibgib/core-gib 0.1.4 → 0.1.8

package/src/keystone/keystone-types.mts

@@ -0,0 +1,315 @@
+import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+
+import { KEYSTONE_ATOM } from "./keystone-constants.mjs";
+
+/**
+ * The discriminator for the mechanism.
+ * 'hash-reveal-v1': Standard Hash chain (Sigma-like).
+ */
+export type KeystoneChallengeType =
+    | 'hash-reveal-v1'
+    // | 'decrypt-v1' // Future
+    // | 'pow-v1';    // Future
+    ;
+
+// ===========================================================================
+// CONFIGURATION
+// ===========================================================================
+
+// #region KeystoneReplenishStrategy
+/**
+ * replaces each used challenge, "topping up" the pool to the pool's size
+ */
+export const KEYSTONE_REPLENISH_STRATEGY_TOP_UP = 'top-up';
+/**
+ * replaces the entire pool with the new challenges
+ */
+export const KEYSTONE_REPLENISH_STRATEGY_REPLACE_ALL = 'replace-all';
+/**
+ * do not replenish, only consume
+ *
+ * ## intent
+ * adding this for revocation
+ */
+export const KEYSTONE_REPLENISH_STRATEGY_CONSUME = 'consume';
+/**
+ * Deletes ALL challenges in the pool, regardless of how many were used.
+ * The "Nuclear Option" for revocation.
+ */
+export const KEYSTONE_REPLENISH_STRATEGY_SCORCHED_EARTH = 'scorched-earth';
+export type KeystoneReplenishStrategy =
+    | typeof KEYSTONE_REPLENISH_STRATEGY_TOP_UP
+    | typeof KEYSTONE_REPLENISH_STRATEGY_REPLACE_ALL
+    | typeof KEYSTONE_REPLENISH_STRATEGY_CONSUME
+    | typeof KEYSTONE_REPLENISH_STRATEGY_SCORCHED_EARTH
+    ;
+/**
+ * @see {@link KeystonePoolBehavior.replenish}
+ */
+export const KeystoneReplenishStrategy = {
+    /**
+     * @see {@link KEYSTONE_REPLENISH_STRATEGY_TOP_UP}
+     */
+    topUp: KEYSTONE_REPLENISH_STRATEGY_TOP_UP,
+    /**
+     * @see {@link KEYSTONE_REPLENISH_STRATEGY_REPLACE_ALL}
+     */
+    replaceAll: KEYSTONE_REPLENISH_STRATEGY_REPLACE_ALL,
+    /**
+     * @see {@link KEYSTONE_REPLENISH_STRATEGY_CONSUME}
+     */
+    consume: KEYSTONE_REPLENISH_STRATEGY_CONSUME,
+    /**
+     * @see {@link KEYSTONE_REPLENISH_STRATEGY_SCORCHED_EARTH}
+     */
+    scorchedEarth: KEYSTONE_REPLENISH_STRATEGY_SCORCHED_EARTH,
+} satisfies { [key: string]: KeystoneReplenishStrategy };
+export const KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES = Object.values(KeystoneReplenishStrategy);
+export function isKeystoneReplenishStrategy(x: any): x is KeystoneReplenishStrategy {
+    return KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES.includes(x);
+}
+// #endregion KeystoneReplenishStrategy
+
+export interface KeystonePoolBehavior {
+    /**
+     * Target number of challenges to maintain in the pool.
+     */
+    size: number;
+
+    /**
+     * How do we fill the void left by consumed challenges?
+     */
+    replenish: KeystoneReplenishStrategy;
+
+    /**
+     * Minimum number of challenges to consume from the "front" (oldest) of the pool.
+     * Mitigates sequence prediction attacks if high, allows strictly ordered audit if used alone.
+     */
+    selectSequentially: number;
+
+    /**
+     * Minimum number of challenges to consume randomly from the remainder.
+     * Mitigates pre-computation attacks on the sequence.
+     */
+    selectRandomly: number;
+
+    /**
+     * Number of hex characters from the Target's Gib to match.
+     * @default 0
+     */
+    targetBindingChars: number;
+}
+
+export interface KeystonePoolConfigBase {
+    /**
+     * The ID of the pool this config belongs to.
+     */
+    id: string;
+
+    type: KeystoneChallengeType;
+    /**
+     * Unique salt for this pool's derivation path from the Master Secret.
+     */
+    salt: string;
+    behavior: KeystonePoolBehavior;
+    /**
+     * The list of Verbs (primitive ibGib addresses) this pool is authorized to sign.
+     * e.g. ["revoke^gib", "admin^gib"]
+     *
+     * If undefined or empty, this pool is considered a "General/Default" pool
+     * and can sign any verb NOT explicitly claimed by another pool (implementation detail of selection)
+     * or simply any verb at all (permissive).
+     *
+     * For V1 Security: If this is set, Validation MUST enforce it.
+     */
+    allowedVerbs: string[];
+}
+
+export interface KeystonePoolConfig_HashV1 extends KeystonePoolConfigBase {
+    type: 'hash-reveal-v1';
+    algo: 'SHA-256' | 'SHA-512';
+    rounds: number;
+}
+
+export type KeystonePoolConfig = KeystonePoolConfig_HashV1;
+
+// ===========================================================================
+// CHALLENGES (Public Puzzles)
+// ===========================================================================
+
+export interface KeystoneChallengeBase {
+    type: KeystoneChallengeType;
+}
+
+export interface KeystoneChallenge_HashV1 extends KeystoneChallengeBase {
+    id: string;
+    type: 'hash-reveal-v1';
+    /**
+     * The hash that must be matched by the solution.
+     */
+    hash: string;
+}
+
+export type KeystoneChallenge = KeystoneChallenge_HashV1;
+
+// ===========================================================================
+// SOLUTIONS (Private Answers revealed in Proofs)
+// ===========================================================================
+
+export interface KeystoneSolutionBase {
+    type: KeystoneChallengeType;
+    /**
+     * The ID of the pool this solution comes from.
+     */
+    poolId: string;
+    /**
+     * The ID of the specific challenge being solved.
+     */
+    challengeId: string;
+}
+
+export interface KeystoneSolution_HashV1 extends KeystoneSolutionBase {
+    type: 'hash-reveal-v1';
+    /**
+     * The Pre-image value.
+     */
+    value: string;
+}
+
+export type KeystoneSolution = KeystoneSolution_HashV1;
+
+// ===========================================================================
+// HIGH-LEVEL STRUCTURES
+// ===========================================================================
+
+/**
+ * A container for a set of challenges.
+ */
+export interface KeystoneChallengePool {
+    /**
+     * Unique ID (e.g. "default", "admin").
+     */
+    id: string;
+
+    /**
+     * Parameterization of this pool.
+     *
+     * Signing and validating this pool must observe this config.
+     */
+    config: KeystonePoolConfig;
+
+    /**
+     * Default claim values for this pool.
+     * Useful for "verb-stones".
+     */
+    defaultClaim?: Partial<KeystoneClaim>;
+
+    /**
+     * The currently active challenges.
+     * Key: The unique Challenge ID (e.g. "poolSalt_0").
+     */
+    challenges: { [challengeId: string]: KeystoneChallenge };
+
+    /**
+     * Explicit Buckets for Target Binding.
+     * Key: Hex Character ('0'-'f').
+     * Value: Array of Challenge IDs that satisfy this bucket.
+     * Note: A single ID may appear in multiple buckets (Coverage Strategy).
+     */
+    bindingMap: { [hexChar: string]: string[] };
+}
+
+/**
+ * Semantic intent.
+ */
+export interface KeystoneClaim {
+    target: string; // ibGib address
+    verb: string;   // ibGib address (primitive)
+    scope?: string; // ibGib address (primitive)
+}
+
+/**
+ * Authorization Proof.
+ */
+export interface KeystoneProof {
+    id?: string;
+
+    /**
+     * The claim being made.
+     */
+    claim: Partial<KeystoneClaim>;
+
+    /**
+     * The solutions required to validate this claim.
+     */
+    solutions: KeystoneSolution[];
+
+    /**
+     * The list of specific Challenge IDs that were mandatorily requested
+     * by the verifier/context during the signing process.
+     * Essential for deterministic validation.
+     */
+    requiredChallengeIds?: string[];
+}
+
+/**
+ * Revocation Context.
+ */
+export interface KeystoneRevocationInfo {
+    reason: string;
+    proof: KeystoneProof;
+}
+
+// ===========================================================================
+// TOP LEVEL IBGIB DATA
+// ===========================================================================
+
+export interface KeystoneIbInfo_V1 {
+    atom: typeof KEYSTONE_ATOM;
+}
+
+export interface KeystoneData_V1 extends IbGibData_V1 {
+    /**
+     * The pools containing the FUTURE challenges.
+     * (Always topped up in V1 implementation).
+     */
+    challengePools: KeystoneChallengePool[];
+
+    /**
+     * The proofs authorizing THIS frame's evolution.
+     */
+    proofs: KeystoneProof[];
+
+    /**
+     * If present, this Keystone is dead.
+     */
+    revocationInfo?: KeystoneRevocationInfo;
+
+    /**
+     * Ephemeral details specific to this frame's creation context.
+     * Meant to be observed on this frame, but NOT automatically carried forward
+     * to the next frame's data during evolution.
+     */
+    frameDetails?: any;
+}
+
+export interface KeystoneRel8ns_V1 extends IbGibRel8ns_V1 {
+    // Standard ibGib relations (ancestor, past, etc.)
+    // Specific hard-links for composite keystones go here later.
+}
+
+export interface KeystoneIbGib_V1 extends IbGib_V1<KeystoneData_V1, KeystoneRel8ns_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[];
+}

package/src/keystone/strategy/hash-reveal-v1/hash-reveal-v1.mts

@@ -0,0 +1,146 @@
+import { hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { KeystoneStrategy } from '../keystone-strategy.mjs';
+import {
+    KeystonePoolConfig_HashV1,
+    KeystoneChallenge_HashV1,
+    KeystoneSolution_HashV1
+} from '../../keystone-types.mjs';
+
+/**
+ * The concrete implementation of the "Salted Wrap" Hash Reveal strategy.
+ */
+export class KeystoneStrategy_HashRevealV1 extends KeystoneStrategy<
+    KeystonePoolConfig_HashV1,
+    KeystoneChallenge_HashV1,
+    KeystoneSolution_HashV1
+> {
+
+    /**
+     * Derives Pool Secret = Hash(PoolSalt + MasterSecret + PoolSalt) ^ Rounds
+     */
+    override async derivePoolSecret({
+        masterSecret
+    }: {
+        masterSecret: string
+    }): Promise<string> {
+        const lc = `[${KeystoneStrategy_HashRevealV1.name}.${this.derivePoolSecret.name}]`;
+        try {
+            const { salt, rounds, algo } = this.config;
+            // Map algo string to HashAlgorithm type if needed,
+            // assuming config.algo matches the helper's expected inputs.
+
+            let current = masterSecret;
+            for (let i = 0; i < rounds; i++) {
+                current = await hash({
+                    s: `${salt}${current}${salt}`,
+                    algorithm: algo
+                });
+            }
+            return current;
+        } catch (error) {
+            console.error(`${lc} Error deriving pool secret: ${error.message}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Solution Value = Hash(IndexSalt + PoolSecret + IndexSalt) ^ Rounds
+     */
+    override async generateSolution({
+        poolSecret,
+        poolId,
+        challengeId,
+    }: {
+        poolSecret: string;
+        poolId: string;
+        challengeId: string;
+    }): Promise<KeystoneSolution_HashV1> {
+        const lc = `[${KeystoneStrategy_HashRevealV1.name}.${this.generateSolution.name}]`;
+        try {
+            const { rounds, algo } = this.config;
+
+            // The Index Salt is the unique identifier for this slot
+            const indexSalt = challengeId;
+
+            let current = poolSecret;
+            for (let i = 0; i < rounds; i++) {
+                current = await hash({
+                    s: `${indexSalt}${current}${indexSalt}`,
+                    algorithm: algo
+                });
+            }
+
+            return {
+                type: 'hash-reveal-v1',
+                poolId,
+                challengeId,
+                value: current
+            };
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Challenge Hash = Hash(IndexSalt + SolutionValue + IndexSalt) ^ Rounds
+     */
+    override async generateChallenge({
+        solution,
+    }: {
+        solution: KeystoneSolution_HashV1;
+    }): Promise<KeystoneChallenge_HashV1> {
+        const lc = `[${KeystoneStrategy_HashRevealV1.name}.${this.generateChallenge.name}]`;
+        try {
+            const { rounds, algo } = this.config;
+            const { challengeId, value } = solution;
+            const indexSalt = challengeId;
+
+            let current = value;
+            for (let i = 0; i < rounds; i++) {
+                current = await hash({
+                    s: `${indexSalt}${current}${indexSalt}`,
+                    algorithm: algo
+                });
+            }
+
+            return {
+                id: challengeId,
+                type: 'hash-reveal-v1',
+                hash: current
+            };
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Re-generates the challenge from the candidate solution and compares.
+     */
+    override async validateSolution({
+        solution,
+        challenge,
+    }: {
+        solution: KeystoneSolution_HashV1;
+        challenge: KeystoneChallenge_HashV1;
+    }): Promise<boolean> {
+        const lc = `[${KeystoneStrategy_HashRevealV1.name}.${this.validateSolution.name}]`;
+        try {
+            // 1. Check Type Compatibility
+            if (solution.type !== 'hash-reveal-v1' || challenge.type !== 'hash-reveal-v1') {
+                console.warn(`${lc} Mismatched types provided.`);
+                return false;
+            }
+
+            // 2. Generate the expected challenge hash from the solution provided
+            const calculatedChallenge = await this.generateChallenge({ solution });
+
+            // 3. Compare
+            return calculatedChallenge.hash === challenge.hash;
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            return false; // Fail closed
+        }
+    }
+}

package/src/keystone/strategy/keystone-strategy-factory.mts

@@ -0,0 +1,35 @@
+import {
+    KeystonePoolConfig
+} from '../keystone-types.mjs';
+import { KeystoneStrategyAny } from './keystone-strategy.mjs';
+import { KeystoneStrategy_HashRevealV1 } from './hash-reveal-v1/hash-reveal-v1.mjs';
+
+export class KeystoneStrategyFactory {
+
+    /**
+     * Instantiates the appropriate concrete KeystoneStrategy based on the
+     * provided configuration type.
+     *
+     * @param config The configuration object for the pool (contains 'type').
+     * @returns An instance of the specific strategy class.
+     */
+    static create({
+        config,
+    }: {
+        config: KeystonePoolConfig,
+    }): KeystoneStrategyAny {
+        const lc = `[${KeystoneStrategyFactory.name}.create]`;
+        try {
+            switch (config.type) {
+                case 'hash-reveal-v1':
+                    return new KeystoneStrategy_HashRevealV1(config);
+
+                default:
+                    throw new Error(`Unknown strategy type: ${(config as any).type} (E: 4e3c2f7129a241c1b687555e678c1065)`);
+            }
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        }
+    }
+}

package/src/keystone/strategy/keystone-strategy.mts

@@ -0,0 +1,71 @@
+import {
+    KeystonePoolConfigBase,
+    KeystoneChallengeBase,
+    KeystoneSolutionBase
+} from '../keystone-types.mjs';
+
+/**
+ * Abstract base class for all Keystone Challenge Strategies.
+ *
+ * @template TConfig The specific configuration interface (e.g. HashV1).
+ * @template TChallenge The specific public challenge interface.
+ * @template TSolution The specific private solution interface.
+ */
+export abstract class KeystoneStrategy<
+    TConfig extends KeystonePoolConfigBase,
+    TChallenge extends KeystoneChallengeBase,
+    TSolution extends KeystoneSolutionBase
+> {
+    constructor(protected config: TConfig) {}
+
+    /**
+     * Derives the secret specific to this pool from the master keystone secret.
+     * This isolates the pool so the master secret is never used directly
+     * in challenge generation.
+     */
+    abstract derivePoolSecret({
+        masterSecret
+    }: {
+        masterSecret: string
+    }): Promise<string>;
+
+    /**
+     * Generates the private solution (Pre-image) for a specific challenge ID.
+     *
+     * @returns The concrete solution object (not just the value string).
+     */
+    abstract generateSolution({
+        poolSecret,
+        poolId,
+        challengeId,
+    }: {
+        poolSecret: string;
+        poolId: string;
+        challengeId: string;
+    }): Promise<TSolution>;
+
+    /**
+     * Generates the public challenge from a given solution.
+     * Used when creating the pool (Top Up) or verifying a solution.
+     */
+    abstract generateChallenge({
+        solution,
+    }: {
+        solution: TSolution;
+    }): Promise<TChallenge>;
+
+    /**
+     * Validates that a given solution mathematically solves the given challenge.
+     *
+     * @returns true if valid, false otherwise.
+     */
+    abstract validateSolution({
+        solution,
+        challenge,
+    }: {
+        solution: TSolution;
+        challenge: TChallenge;
+    }): Promise<boolean>;
+}
+
+export type KeystoneStrategyAny = KeystoneStrategy<any,any,any>;

package/src/respec-gib.node.mts

@@ -1,4 +1,5 @@
 import { readdir, open } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
 import { statSync } from 'node:fs';
 import * as pathUtils from 'path';
 
@@ -95,7 +96,8 @@ if (logalot) { console.log(`respecPaths found:\n${respecPaths}`); }
 for (let i = 0; i < respecPaths.length; i++) {
     const respecPath = respecPaths[i];
     if (logalot) { console.log(respecPath); }
-    const esm = await import(respecPath);
+    const respecPathUrl = pathToFileURL(respecPath).href;
+    const esm = await import(respecPathUrl);
     if (logalot) { console.log(pretty(Object.keys(esm))); }
 }
 

package/src/spec-helper.node.respec.mts

@@ -1,4 +1,5 @@
 import { default as pathUtils } from 'path';
+import { fileURLToPath } from 'node:url';
 
 import { delay, getUUID, } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 
@@ -11,12 +12,9 @@ import { delay, getUUID, } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs
 export async function getCurrentFilename(importMetaUrl: string): Promise<string> {
     const lc = `[${getCurrentFilename.name}]`;
     try {
-        const pieces = importMetaUrl.split(pathUtils.sep);
-        let filename = pieces.at(-1)?.replace(/\.respec\.mjs$/, '')
-        if (!filename) {
-            console.warn(`filename not able to be gotten?`);
-            filename = (new Date()).toTimeString() + (await getUUID());
-        }
+        const filePath = fileURLToPath(importMetaUrl);
+        const filenameWithExt = pathUtils.basename(filePath);
+        const filename = filenameWithExt.replace(/\.respec\.mjs$/, '');
         return `ibgib${pathUtils.sep}${filename}`;
     } catch (error) {
         console.error(`${lc} ${error.message}`);

package/src/witness/robbot/robbot-base-v1.mts

@@ -694,7 +694,7 @@ export abstract class RobbotBase_V1<
             // todo: adjust to use the cacheIbGibs (not get them if already have in cache, but still return them in this fn's result)
             for (let i = 0; i < rel8nNames.length; i++) {
                 const rel8nName = rel8nNames[i];
-                const rel8dAddrs: IbGibAddr[] = this.rel8ns ? (this.rel8ns[rel8nName] ?? []) : undefined ?? [];
+                const rel8dAddrs: IbGibAddr[] = this.rel8ns?.[rel8nName] ?? [];
 
                 if (rel8dAddrs.length > 0) {
                     const resGet = await getFromSpace({ addrs: rel8dAddrs, space });