@ibgib/core-gib 0.1.60 → 0.1.62

package/src/keystone/keystone-types.mts

@@ -111,10 +111,12 @@ export interface KeystonePoolBehavior {
     selectRandomly: number;
 
     /**
-     * Number of hex characters from the Target's Gib to match.
+     * Number of challenges to draw deterministically from the pool using
+     * next-gen hash-based index selection (drawing without replacement)
+     * bound to the full target address (`ib` + `gib`).
      * @default 0
      */
-    targetBindingChars: number;
+    targetBindingCount: number;
 }
 
 export interface KeystonePoolConfigBase {
@@ -227,13 +229,7 @@ export interface KeystoneChallengePool {
      */
     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[] };
+
 
     /**
      * If true, this pool's secrets are NOT derived from the Keystone's
@@ -318,6 +314,50 @@ export interface KeystoneRevocationInfo {
     proof: KeystoneProof;
 }
 
+/**
+ * Shape of info we collect about delegated keystones. We can check 
+ * against this info later when validating any identity delegation requests.
+ */
+export interface DelegateKeystoneInfo {
+    /**
+     * The Timeline Junction Point (TJP) address of the delegate keystone.
+     * Serves as its immutable, unique identifier.
+     */
+    delegateTjpAddr: IbGibAddr;
+    /**
+     * concrete addr of **DELEGATE** keystone **at the time when the 
+     * delegate was added.**
+     *
+     * So if we have a delegate keystone at D3, then this value would be the
+     * addr of that D3 keystone. This will have both a `punctiliarHash` and a
+     * `tjpGib` in its `GibInfo`.
+     */
+    delegateAddr: IbGibAddr;
+    /**
+     * concrete keystone addr of **THIS** parent keystone **at the time 
+     * when the delegate was added.**
+     *
+     * So if we have a delegate keystone at D3, then this value would be the
+     * addr of that D3 keystone. This will have both a `punctiliarHash` and a
+     * `tjpGib` in its `GibInfo`.
+     */
+    thisAddr: IbGibAddr;
+}
+
+/**
+ * Status response when checking if a delegate keystone is registered.
+ */
+export interface DelegateKeystoneStatus {
+    /**
+     * True if the delegate is currently registered on the parent.
+     */
+    registered: boolean;
+    /**
+     * Truthy only if registered is true.
+     */
+    delegateInfo?: DelegateKeystoneInfo;
+}
+
 // ===========================================================================
 // TOP LEVEL IBGIB DATA
 // ===========================================================================
@@ -355,6 +395,12 @@ export interface KeystoneData_V1 extends IbGibData_V1 {
      * Acts as a snapshot to avoid walking the entire timeline.
      */
     checkpointDetails?: any;
+
+    /**
+     * Map of delegated keystones soft-linked to this parent keystone.
+     * Keyed by the delegate keystone's tjp address.
+     */
+    delegates?: { [delegateTjpAddr: IbGibAddr]: DelegateKeystoneInfo };
 }
 
 export interface KeystoneRel8ns_V1 extends IbGibRel8ns_V1 {

package/src/keystone/policy/IMPLEMENTATION.md

@@ -0,0 +1,60 @@
+# Implementation Plan: Modular Policy Schemas & Keystone Profile Builder
+
+This document outlines the step-by-step development tasks to transition the Keystone policy engine to a modular JSON-schema composed architecture with a fluent builder.
+
+Parent Architecture Doc: [ARCHITECTURE.md](../../../../../docs/identity/ARCHITECTURE.md)
+
+---
+
+## 📋 Task Checklist
+
+- [x] **1. Modular JSON Schema & Profiles Definitions**
+  - [x] Create schemas: `sync-pool.schema.json`, `manage-pool.schema.json`, `revoke-pool.schema.json`, `connect-pool.schema.json`, `sign-pool.schema.json` under `libs/core-gib/src/keystone/policy/schemas/`.
+  - [x] Define composite schemas `keystone.high.schema.json`, `keystone.medium.schema.json`, `keystone.low.schema.json`.
+  - [x] Migrate JSON profile files to use new schema locations.
+
+- [x] **2. Type System Refactoring**
+  - [x] Update [keystone-policy-types.mts](../keystone-policy-types.mts) to support composite profiles and new metadata schemas.
+
+- [x] **3. Implement `KeystoneProfileBuilder`**
+  - [x] Create `keystone-profile-builder.mts` inside `libs/core-gib/src/keystone/policy/`.
+  - [x] Implement `buildKeystone`, `withUsername`, `withEmail`, `withDescription`, `withDetails`.
+  - [x] Implement `customizePool` and `compileConfigs` with unique salt derivation and `frameDetails` unification.
+
+- [x] **4. Build Pipeline Integration**
+  - [x] Update `build-core-gib.mts` to copy new schema/profile directories to `dist`.
+
+- [x] **5. Downstream Consumption Refactoring**
+  - [x] Refactor space-gib's `keystone-creator.mts` to use the new builder.
+
+- [x] **6. Automated Verification**
+  - [x] Add integration tests in `keystone-service-v1.respec.mts` ensuring the builder and modular schemas are correctly parsed, validated, and applied.
+
+- [x] **7. Documentation & Architecture Sync**
+  - [x] Update [ARCHITECTURE.md](../../../../../docs/identity/ARCHITECTURE.md) with corrected code snippets (including fluent builder code samples) and clickable links to the actual code files (like schemas and builder implementation) for reference.
+
+---
+
+## 🛠️ Build & Verification Guide
+
+Use the following commands from the monorepo root to build and verify your changes:
+
+### 1. Build core-gib
+Check if core-gib compiles clean:
+```powershell
+npm run build:core-gib
+```
+
+### 2. Monorepo Chain Build
+Build all libraries and compile the downstream `space-gib` application to test integration:
+```powershell
+npm run chain:build:core-gib
+```
+
+### 3. Run Space-Gib Client
+To manually test the Keystone creation process via the space-gib UI, run:
+```powershell
+npm run dev:space-gib
+```
+
+

package/src/keystone/policy/README.md

@@ -0,0 +1,94 @@
+# Keystone Identity Policies & Fluent Builder
+
+This module manages Keystone Identity Policies, including security preset profiles (`high`, `medium`, `low`), modular schema composition, and the fluent configuration builder.
+
+---
+
+## 📖 Documentation Index
+
+*   **[Policy Architecture](../../../../../docs/identity/ARCHITECTURE.md)**: Conceptual design of separate pool behaviors, verbs, and composed schemas.
+*   **[Implementation Roadmap](./IMPLEMENTATION.md)**: Current development checklist and tasks.
+
+---
+
+## 🛠️ Usage: Fluent Builder API
+
+The `KeystoneProfileBuilder` provides a fluid interface to construct, enrich, and customize Keystone configurations before genesis.
+
+### Basic Identity Creation
+
+```typescript
+import { KeystoneProfileBuilder } from "@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs";
+
+// Build a medium-security identity config salted for a specific user
+const configs = KeystoneProfileBuilder
+    .buildKeystone('medium')
+    .withUsername('alice')
+    .withEmail('alice@example.com')
+    .withDescription('Main user identity for Space-Gib')
+    .compileConfigs();
+
+// Pass these configurations directly to genesis
+const identity = await keystoneService.genesis({
+    masterSecret,
+    configs,
+    metaspace,
+    space
+});
+```
+
+### Unifying Identity Details
+
+The metadata provided to `withUsername`, `withEmail`, `withDescription`, and `withDetails` are automatically consolidated into the unified `frameDetails` field of the genesis frame:
+
+```typescript
+const configs = KeystoneProfileBuilder
+    .buildKeystone('low')
+    .withUsername('bob')
+    .withDetails({
+        device: 'Pixel 8 Pro',
+        os: 'Android 14'
+    })
+    .compileConfigs();
+```
+
+### Runtime Customizations
+
+If an application needs to customize a specific pool's parameters dynamically (for example, raising KDF hash rounds on the sync pool for higher-security environments), use `customizePool`:
+
+```typescript
+const configs = KeystoneProfileBuilder
+    .buildKeystone('medium')
+    .withUsername('charlie')
+    .customizePool('sync', {
+        rounds: 5, // Override base medium profile rounds
+    })
+    .compileConfigs();
+```
+
+---
+
+## ⚠️ TypeScript & JSON Config Integration
+
+If downstream projects import or load their own JSON configurations (e.g., custom `.json` files representing schemas or behavior configurations) rather than relying solely on the built-in profiles, TypeScript requires explicit path tracking in projects using `"composite": true`.
+
+To prevent compiler errors like `TS6307: File '...' is not listed within the file list...`, ensure your project's `tsconfig.json` contains:
+
+1. `"resolveJsonModule": true` under `compilerOptions` to allow static importing of JSON files as ES modules.
+2. The folder/wildcard path of the JSON files added to the `"include"` array. For example:
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "resolveJsonModule": true,
+    "module": "ESNext"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.mts",
+    "src/custom-policies/*.json"
+  ]
+}
+```
+

package/src/keystone/policy/keystone-profile-builder.mts

@@ -0,0 +1,131 @@
+import { hash } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { KeystonePoolConfig } from "../keystone-types.mjs";
+import { KeystonePoolTemplate, KeystonePolicyConfigTemplate, KeystoneBehaviorProfileTemplate } from "../keystone-policy-types.mjs";
+import { createPoolConfigFromJson } from "../keystone-config-builder.mjs";
+
+import profileHigh from "./profiles/profile-high.json" assert { type: "json" };
+import profileMedium from "./profiles/profile-medium.json" assert { type: "json" };
+import profileLow from "./profiles/profile-low.json" assert { type: "json" };
+import profileSession from "./profiles/profile-session.json" assert { type: "json" };
+import profileTest from "./profiles/profile-test.json" assert { type: "json" };
+
+export class KeystoneProfileBuilder {
+    private _template: KeystonePolicyConfigTemplate;
+    private _username?: string;
+    private _email?: string;
+    private _description?: string;
+    private _details?: any;
+    private _customizations: { [poolId: string]: { template?: Partial<KeystonePoolTemplate>, behavior?: Partial<KeystoneBehaviorProfileTemplate> } } = {};
+
+    private constructor(template: KeystonePolicyConfigTemplate) {
+        // Deep copy the template to avoid modifying shared imports
+        this._template = JSON.parse(JSON.stringify(template));
+    }
+
+    static buildKeystone(profileName: 'high' | 'medium' | 'low' | 'session' | 'test'): KeystoneProfileBuilder {
+        let selected: KeystonePolicyConfigTemplate;
+        switch (profileName) {
+            case 'high':
+                selected = profileHigh as any;
+                break;
+            case 'medium':
+                selected = profileMedium as any;
+                break;
+            case 'low':
+                selected = profileLow as any;
+                break;
+            case 'session':
+                selected = profileSession as any;
+                break;
+            case 'test':
+                selected = profileTest as any;
+                break;
+            default:
+                throw new Error(`Unknown profile name: ${profileName} (E: fc10a8ad482ef2bda871ac567d268d26)`);
+        }
+        return new KeystoneProfileBuilder(selected);
+    }
+
+    withUsername(username: string): this {
+        this._username = username;
+        return this;
+    }
+
+    withEmail(email: string): this {
+        this._email = email;
+        return this;
+    }
+
+    withDescription(description: string): this {
+        this._description = description;
+        return this;
+    }
+
+    withDetails(details: any): this {
+        this._details = details;
+        return this;
+    }
+
+    customizePool(
+        poolId: string,
+        overrides: Omit<Partial<KeystonePoolTemplate>, 'behavior'> & { behavior?: Partial<KeystoneBehaviorProfileTemplate> }
+    ): this {
+        const { behavior, ...templateOverrides } = overrides;
+        this._customizations[poolId] = {
+            template: templateOverrides as any,
+            behavior
+        };
+        return this;
+    }
+
+    /**
+     * Unifies username, email, description, and details into a frameDetails object for genesis.
+     */
+    getFrameDetails(): any {
+        const details: any = { ...this._details };
+        if (this._username) { details.username = this._username; }
+        if (this._email) { details.email = this._email; }
+        if (this._description) { details.description = this._description; }
+        return details;
+    }
+
+    async compileConfigs(): Promise<KeystonePoolConfig[]> {
+        const poolConfigs: KeystonePoolConfig[] = [];
+        
+        // Derive a unique user-specific base salt if username/email is provided
+        let userSalt = "";
+        if (this._username || this._email) {
+            const seed = `${this._username || ""}:${this._email || ""}`;
+            userSalt = await hash({ s: seed });
+        } else {
+            // Fallback salt to guarantee unique challenge IDs even without user details
+            userSalt = await hash({ s: "default-keystone-salt" });
+        }
+
+        for (const [poolKey, poolTemplate] of Object.entries(this._template.pools)) {
+            // Apply customization overrides
+            const custom = this._customizations[poolTemplate.id];
+            if (custom) {
+                if (custom.template) {
+                    Object.assign(poolTemplate, custom.template);
+                }
+                if (custom.behavior && poolTemplate.behavior) {
+                    Object.assign(poolTemplate.behavior, custom.behavior);
+                }
+            }
+
+            // Derive a unique salt for this specific pool by hashing userSalt + poolId
+            const saltSeed = `${userSalt}-${poolTemplate.id}`;
+            const derivedSalt = await hash({ s: saltSeed });
+
+            const poolConfig = createPoolConfigFromJson({
+                template: poolTemplate,
+                salt: derivedSalt
+            });
+
+            poolConfigs.push(poolConfig);
+        }
+
+        return poolConfigs;
+    }
+}

package/src/keystone/policy/profiles/profile-high.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "../schemas/keystone.high.schema.json",
+  "metadata": {
+    "name": "High Security Profile",
+    "securityLevel": "high"
+  },
+  "pools": {
+    "sync": {
+      "id": "sync",
+      "allowedVerbs": [
+        "sync"
+      ],
+      "algo": "SHA-512",
+      "rounds": 4,
+      "behavior": {
+        "size": 2000,
+        "replenish": "top-up",
+        "selectSequentially": 10,
+        "selectRandomly": 10,
+        "targetBindingCount": 16
+      }
+    },
+    "manage": {
+      "id": "manage",
+      "allowedVerbs": [
+        "manage"
+      ],
+      "algo": "SHA-512",
+      "rounds": 4,
+      "behavior": {
+        "size": 2000,
+        "replenish": "replace-all",
+        "selectSequentially": 10,
+        "selectRandomly": 10,
+        "targetBindingCount": 16
+      }
+    },
+    "revoke": {
+      "id": "revoke",
+      "allowedVerbs": [
+        "revoke"
+      ],
+      "algo": "SHA-512",
+      "rounds": 20,
+      "behavior": {
+        "size": 2000,
+        "replenish": "delete-all",
+        "selectSequentially": 50,
+        "selectRandomly": 50,
+        "targetBindingCount": 0
+      }
+    },
+    "connect": {
+      "id": "connect",
+      "allowedVerbs": [
+        "connect"
+      ],
+      "algo": "SHA-512",
+      "rounds": 4,
+      "behavior": {
+        "size": 2000,
+        "replenish": "top-up",
+        "selectSequentially": 10,
+        "selectRandomly": 10,
+        "targetBindingCount": 16
+      }
+    },
+    "sign": {
+      "id": "default",
+      "allowedVerbs": [
+        "sign"
+      ],
+      "algo": "SHA-512",
+      "rounds": 4,
+      "behavior": {
+        "size": 2000,
+        "replenish": "top-up",
+        "selectSequentially": 10,
+        "selectRandomly": 10,
+        "targetBindingCount": 16
+      }
+    }
+  }
+}

package/src/keystone/policy/profiles/profile-low.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "../schemas/keystone.low.schema.json",
+  "metadata": {
+    "name": "Low Security Profile",
+    "securityLevel": "low"
+  },
+  "pools": {
+    "sync": {
+      "id": "sync",
+      "allowedVerbs": [
+        "sync"
+      ],
+      "algo": "SHA-256",
+      "rounds": 1,
+      "behavior": {
+        "size": 100,
+        "replenish": "top-up",
+        "selectSequentially": 3,
+        "selectRandomly": 3,
+        "targetBindingCount": 8
+      }
+    },
+    "manage": {
+      "id": "manage",
+      "allowedVerbs": [
+        "manage"
+      ],
+      "algo": "SHA-256",
+      "rounds": 2,
+      "behavior": {
+        "size": 100,
+        "replenish": "replace-all",
+        "selectSequentially": 3,
+        "selectRandomly": 3,
+        "targetBindingCount": 8
+      }
+    },
+    "revoke": {
+      "id": "revoke",
+      "allowedVerbs": [
+        "revoke"
+      ],
+      "algo": "SHA-256",
+      "rounds": 5,
+      "behavior": {
+        "size": 100,
+        "replenish": "delete-all",
+        "selectSequentially": 3,
+        "selectRandomly": 3,
+        "targetBindingCount": 0
+      }
+    },
+    "connect": {
+      "id": "connect",
+      "allowedVerbs": [
+        "connect"
+      ],
+      "algo": "SHA-256",
+      "rounds": 1,
+      "behavior": {
+        "size": 100,
+        "replenish": "top-up",
+        "selectSequentially": 3,
+        "selectRandomly": 3,
+        "targetBindingCount": 8
+      }
+    },
+    "sign": {
+      "id": "default",
+      "allowedVerbs": [
+        "sign"
+      ],
+      "algo": "SHA-256",
+      "rounds": 2,
+      "behavior": {
+        "size": 100,
+        "replenish": "top-up",
+        "selectSequentially": 3,
+        "selectRandomly": 3,
+        "targetBindingCount": 8
+      }
+    }
+  }
+}

package/src/keystone/policy/profiles/profile-medium.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "../schemas/keystone.medium.schema.json",
+  "metadata": {
+    "name": "Medium Security Profile",
+    "securityLevel": "medium"
+  },
+  "pools": {
+    "sync": {
+      "id": "sync",
+      "allowedVerbs": [
+        "sync"
+      ],
+      "algo": "SHA-256",
+      "rounds": 2,
+      "behavior": {
+        "size": 500,
+        "replenish": "top-up",
+        "selectSequentially": 5,
+        "selectRandomly": 5,
+        "targetBindingCount": 10
+      }
+    },
+    "manage": {
+      "id": "manage",
+      "allowedVerbs": [
+        "manage"
+      ],
+      "algo": "SHA-256",
+      "rounds": 2,
+      "behavior": {
+        "size": 500,
+        "replenish": "replace-all",
+        "selectSequentially": 5,
+        "selectRandomly": 5,
+        "targetBindingCount": 10
+      }
+    },
+    "revoke": {
+      "id": "revoke",
+      "allowedVerbs": [
+        "revoke"
+      ],
+      "algo": "SHA-256",
+      "rounds": 10,
+      "behavior": {
+        "size": 500,
+        "replenish": "delete-all",
+        "selectSequentially": 20,
+        "selectRandomly": 20,
+        "targetBindingCount": 0
+      }
+    },
+    "connect": {
+      "id": "connect",
+      "allowedVerbs": [
+        "connect"
+      ],
+      "algo": "SHA-256",
+      "rounds": 2,
+      "behavior": {
+        "size": 500,
+        "replenish": "top-up",
+        "selectSequentially": 5,
+        "selectRandomly": 5,
+        "targetBindingCount": 10
+      }
+    },
+    "sign": {
+      "id": "default",
+      "allowedVerbs": [
+        "sign"
+      ],
+      "algo": "SHA-256",
+      "rounds": 2,
+      "behavior": {
+        "size": 500,
+        "replenish": "top-up",
+        "selectSequentially": 5,
+        "selectRandomly": 5,
+        "targetBindingCount": 10
+      }
+    }
+  }
+}