@ibgib/core-gib 0.1.61 → 0.1.62

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/core-gib",
-  "version": "0.1.61",
+  "version": "0.1.62",
   "description": "ibgib core functionality, including base architecture for witnesses, spaces, apps, robbots, etc., as well as shared utility functions. Node v19+ needed for heavily-used isomorphic webcrypto hashing consumed in both node and browsers.",
   "funding": {
     "type": "individual",

package/src/keystone/README.md

@@ -24,8 +24,8 @@ Keystones organize challenges into **pools** with specific purposes:
 
 *   **Default Pool**: General-purpose signing operations
 *   **Revoke Pool**: Permanent identity termination (one-time use, `verb: revoke`)
-*   **Manage Pool**: Structural changes like adding pools (`verb: manage`)
-*   **Foreign Pools**: Delegation to external identities (SSO-like workflows)
+*   **Manage Pool**: Structural changes like adding pools (`verb: manage`) or managing delegates
+*   **Foreign Pools**: Inward delegation to external identities (SSO co-signing workflows)
 
 Each pool configuration specifies:
 *   **`id`**: Unique identifier within the keystone
@@ -33,6 +33,19 @@ Each pool configuration specifies:
 *   **`algo` / `rounds`**: Hashing algorithm and KDF iteration count
 *   **`behavior`**: Rules for capacity (`size`), replenishment (`replenish`), sequential/random consumption (`selectSequentially`/`selectRandomly`), and target binding (`targetBindingCount`).
 
+## Delegation (Inward vs. Outward)
+
+Keystones support both **Inward Delegation** (bringing external keys inside this identity) and **Outward Delegation** (externalizing keystone responsibilities to other keystones).
+
+### 1. Inward Delegation (Foreign Pools)
+Alice can delegate co-signing rights to Bob (e.g., for Single Sign-On) by embedding Bob's challenge pool in her Keystone. Bob can then sign claims on Alice's behalf without ever exposing Alice's master secret, sharing Bob's master secret, or requiring co-located servers.
+
+### 2. Outward Delegation (Delegate Keystones)
+Alice can authorize entire external keystones to act on her behalf (e.g., authorizing a specific client keystone to sync data or sign messages) by adding them to her keystone's `delegates` map:
+*   **Manage Verb Authorized**: Adding or removing a delegate modifies the keystone's metadata. This transition is strictly rejected during validation unless authorized by a signature proof using the parent's `manage` pool (`KEYSTONE_VERB_MANAGE`).
+*   **Ancestry Linkage**: The delegate registration records the exact frame (`thisAddr`) in the parent timeline where the delegation is active. The validator enforces that `thisAddr` is a valid historical or current frame in the parent's timeline ancestry, preventing delegate replay or hijack attacks.
+*   **Soft-Linking**: Keeps delegate keystones "pure" and independent (with their own pools/lifecycle) while maintaining secure, verifiable delegation on the parent.
+
 ## Basic Usage
 
 ### Genesis (Create Identity)

package/src/keystone/docs/architecture.md

@@ -14,10 +14,10 @@
 *   **Challenge Pool**: A collection of puzzles stored in each Keystone Frame.
 *   **Constraint/Policy Engine**: Logic that determines *which* challenges must be solved to authorize a specific action (Binding, FIFO, Stochastic).
 
-### Foreign Pools (Delegation)
+### Inward Delegation (Foreign Pools)
 
 > [!IMPORTANT]
-> **🔀 Keystones support delegation** by embedding challenges from external identities.
+> **🔀 Keystones support inward delegation** by embedding challenges from external identities.
 
 **Mechanism**:
 *   **Use Case**: Alice adds Bob's challenge pool to her keystone
@@ -41,6 +41,25 @@
 
 See [KeystoneService_V1.addPools()](file:../keystone-service-v1.mts) for implementation.
 
+### Outward Delegation (Delegate Keystones)
+
+> [!IMPORTANT]
+> **🔀 Keystones support outward delegation** by authorizing entire external keystones (e.g. client keys) to act on their behalf.
+
+**Mechanism**:
+*   **Use Case**: Alice registers a dedicated delegate keystone in her parent keystone to synchronize data.
+*   **Structure**: Alice's parent keystone stores a `delegates` mapping in its data. Each delegate info stores:
+    *   `delegateTjpAddr`: The temporal junction point address (stable identity) of the delegate.
+    *   `delegateAddr`: The current/latest frame address of the delegate.
+    *   `thisAddr`: The exact frame address of the parent keystone where this delegation was registered.
+*   **Validation & Transition Security**:
+    - **Authorization**: Modifying the delegates map (registering/unregistering) requires a signature proof matching the `manage` verb (`KEYSTONE_VERB_MANAGE`).
+    - **Ancestry Verification**: The validator checks that `thisAddr` is a valid current or historical address in the parent keystone timeline (`prevIbGib.rel8ns.past` or current address), securing the timeline against replay or hijack attempts.
+    - **Well-Formedness**: The validator enforces that the keys in the `delegates` map match `delegateTjpAddr`, and all addresses are valid keystone addresses.
+*   **Soft-Linking Pattern**: Keeps delegate keystones pure/clean while establishing a secure, verifiable association on the parent.
+
+See `KeystoneService_V1.registerDelegate()`, `unregisterDelegate()` (in [keystone-service-v1.mts](file:../keystone-service-v1.mts)), and `validateDelegates()` (in [keystone-helpers.mts](file:../keystone-helpers.mts)) for details.
+
 ## 3. Policy Engine (Selection & Mitigation)
 
 To prevent replay attacks by Man-in-the-Middle (MITM) actors, the challenges required to sign a frame are selected via a multi-layered pipeline:

package/src/keystone/docs/delegation.md

@@ -0,0 +1,57 @@
+# Keystone Delegation Models
+
+Keystones support both **Inward Delegation** (integrating external keys/challenges) and **Outward Delegation** (externalizing keystone responsibilities to other keystones).
+
+---
+
+## 1. Inward Delegation (Foreign Pools)
+
+*   **Mechanism**: A keystone embeds challenges from an external identity (e.g., Alice's keystone containing Bob's co-signing/SSO pool).
+*   **Purpose**: Allows external custodians or identities to co-sign or sign specific claims on behalf of this identity without sharing master secrets.
+*   **Lifecycle**: Added/removed via standard pool evolution paths (`addPools` / `removePools`).
+
+---
+
+## 2. Outward Delegation (Delegate Keystones)
+
+*   **Mechanism**: A parent keystone stores a `delegates` map in its `data` object mapping `delegateTjpAddr` to `DelegateKeystoneInfo`.
+*   **Purpose**: Authorizes entire independent external keystones (such as a device key or client) to act on behalf of the parent identity.
+*   **Lifecycle**: Registered and unregistered via `registerDelegate()` and `unregisterDelegate()`.
+*   **Security Policies**:
+    *   **Manage Verb Proof**: Mutating the delegates map is rejected during validation unless authorized by a signature proof using the parent's `manage` pool (`KEYSTONE_VERB_MANAGE`).
+    *   **Ancestry Verification**: The delegate's `thisAddr` records the exact frame in the parent's timeline where the delegation took place. The validator enforces that `thisAddr` is a valid historical or current frame in the parent's timeline history.
+    *   **Soft-Linking**: All relations use soft-links (embedded in `data`) to avoid merging cryptographic dependency graphs of different keystones.
+
+---
+
+## 3. The Multi-Tiered Identity Hierarchy
+
+To balance high cryptographic security with practical daily usability (avoiding the performance and size overhead of constantly evolving a root identity), `ibgib` utilizes a multi-tiered delegation model:
+
+```
+           [ Tier 1: Root/Parent Keystone ] (High Security, Cold/Warm)
+                         │
+                         ▼ (Persistent Delegation via `delegates` map)
+             [ Tier 2: Sync/Device Keystone ] (Medium/Low Security, e.g. Laptop/Phone)
+                         │
+                         ▼ (Ephemeral Delegation via signed Claims / sync verb)
+               [ Tier 3: Session Keystone ] (Temporary, Tab-Specific)
+```
+
+### Tier 1: Root/Parent Keystone (Primary Identity)
+*   **Role**: The primary, slow-evolving root of the user's decentralized identity.
+*   **Secrets**: Typically derived from a strong, user-memorized passphrase.
+*   **Activity**: Rarely evolved. Only updated to register or unregister client devices.
+*   **Delegates**: Formally registers a device's keystone in its `delegates` map.
+
+### Tier 2: Sync/Device Keystone
+*   **Role**: A persistent client identity dedicated to a specific user device (e.g. laptop, phone).
+*   **Secrets**: Stored locally on the device (e.g. keychains, secure storage).
+*   **Activity**: Initiates business-level operations (like synchronization sagas) as the `senderIdentity`.
+*   **Authorization**: Verifiers trace this device keystone back to the Root/Parent's registered `delegates` map.
+
+### Tier 3: Session Keystone
+*   **Role**: An ephemeral, memory-only keystone created for a single sync session or browser tab.
+*   **Secrets**: Transient, thrown away on tab close or session timeout.
+*   **Authorization**: Authorized by the Tier 2 Sync/Device Keystone using an ad-hoc signed co-signing/delegation claim. No root evolution required.
+*   **Benefit**: Absolute isolation. If a device is compromised, the Root Keystone unregisters the Tier 2 Device delegate, instantly invalidating the device and all associated Tier 3 sessions.

package/src/keystone/keystone-constants.mts

@@ -95,7 +95,6 @@ export function isKeystoneVerb(value: string): value is KeystoneVerb {
 export const POOL_ID_REVOKE = KEYSTONE_VERB_REVOKE;
 export const POOL_ID_MANAGE = KEYSTONE_VERB_MANAGE;
 export const POOL_ID_DEFAULT = "default";
-export const POOL_ID_DELEGATE = "delegate";
 /**
  * Pool ID for the session keystone's transport connect pool.
  * Paired with {@link KEYSTONE_VERB_CONNECT}. Consumed once per sync session

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, KEYSTONE_USERNAME_REGEXP, KEYSTONE_DESCRIPTION_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, KEYSTONE_VERB_MANAGE } from "./keystone-constants.mjs";
 import {
     KeystoneData_V1, KeystoneIbGib_V1, KeystoneIb_V1, KeystoneChallengePool,
     DeterministicResult, KeystoneProof, KeystonePoolConfig,
@@ -17,6 +17,7 @@ import {
     KeystoneChallengeType,
     KEYSTONE_CHALLENGE_TYPE_VALID_VALUES,
     KeystonePoolConfig_HashV1,
+    DelegateKeystoneInfo,
 } from "./keystone-types.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
 import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
@@ -90,6 +91,22 @@ export async function parseKeystoneIb({
     }
 }
 
+/**
+ * Helper to validate if an ib string is a well-formed keystone ib.
+ */
+export async function validateKeystoneIb({
+    ib,
+}: {
+    ib: Ib,
+}): Promise<boolean> {
+    try {
+        await parseKeystoneIb({ ib });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 /**
  * The Policy Engine.
  * Calculates exactly which challenges MUST be consumed based on config and demands.
@@ -634,6 +651,11 @@ export async function validateGenesisKeystone({
 
         const { data, rel8ns } = keystoneIbGib;
 
+        const isValidIb = await validateKeystoneIb({ ib: keystoneIbGib.ib });
+        if (!isValidIb) {
+            errors.push(`${lc} invalid keystone ib (${keystoneIbGib.ib}). (E: ad7a88bc38c290a184dfbd42be48f526)`);
+        }
+
         // Validate username/description metadata if present
         const metadataErrors = validateKeystoneMetadata({ data });
         metadataErrors.forEach(x => errors.push(x));
@@ -670,6 +692,89 @@ export async function validateGenesisKeystone({
     }
 }
 
+/**
+ * Helper to determine if two delegates maps differ.
+ */
+export function isDelegatesChanged({
+    currDelegates,
+    prevDelegates,
+}: {
+    currDelegates?: Record<string, DelegateKeystoneInfo>,
+    prevDelegates?: Record<string, DelegateKeystoneInfo>,
+}): boolean {
+    const curr = currDelegates || {};
+    const prev = prevDelegates || {};
+    const currKeys = Object.keys(curr);
+    const prevKeys = Object.keys(prev);
+
+    if (currKeys.length !== prevKeys.length) { return true; }
+
+    for (const key of currKeys) {
+        const currVal = curr[key];
+        const prevVal = prev[key];
+        if (!prevVal) { return true; }
+        if (currVal.delegateTjpAddr !== prevVal.delegateTjpAddr ||
+            currVal.delegateAddr !== prevVal.delegateAddr ||
+            currVal.thisAddr !== prevVal.thisAddr) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Validates the structure and constraints of the delegates map.
+ */
+export async function validateDelegates({
+    currDelegates,
+    prevIbGib,
+    lc,
+    errors,
+}: {
+    currDelegates: Record<string, DelegateKeystoneInfo>,
+    prevIbGib: KeystoneIbGib_V1,
+    lc: string,
+    errors: string[],
+}): Promise<void> {
+    const currKeys = Object.keys(currDelegates);
+    const prevAddr = getIbGibAddr({ ibGib: prevIbGib });
+
+    for (const key of currKeys) {
+        const info = currDelegates[key];
+        if (key !== info.delegateTjpAddr) {
+            errors.push(`${lc} Invalid delegate mapping: Key '${key}' does not match delegateTjpAddr '${info.delegateTjpAddr}'. (E: 9c8da8bc38c290a184dfbd42be48f526)`);
+        }
+
+        // Verify addresses are valid keystone addresses
+        const [
+            parsedDelegateTjp,
+            parsedDelegate,
+            parsedThis,
+        ] = await Promise.all([
+            validateKeystoneIb({ ib: info.delegateTjpAddr.split('^')[0] }),
+            validateKeystoneIb({ ib: info.delegateAddr.split('^')[0] }),
+            validateKeystoneIb({ ib: info.thisAddr.split('^')[0] }),
+        ]);
+
+        if (!parsedDelegateTjp) {
+            errors.push(`${lc} Delegate delegateTjpAddr '${info.delegateTjpAddr}' is not a valid keystone address. (E: 10d8a8bc38c290a184dfbd42be48f526)`);
+        }
+        if (!parsedDelegate) {
+            errors.push(`${lc} Delegate delegateAddr '${info.delegateAddr}' is not a valid keystone address. (E: 20d8a8bc38c290a184dfbd42be48f526)`);
+        }
+        if (!parsedThis) {
+            errors.push(`${lc} Delegate thisAddr '${info.thisAddr}' is not a valid keystone address. (E: 30d8a8bc38c290a184dfbd42be48f526)`);
+        }
+
+        // Verify thisAddr is in the parent's past (or is the current parent address)
+        const isHistoricalParent = info.thisAddr === prevAddr || (prevIbGib.rel8ns?.past || []).includes(info.thisAddr);
+        if (!isHistoricalParent) {
+            errors.push(`${lc} Delegate thisAddr '${info.thisAddr}' is not a valid historical address in the parent keystone timeline. (E: 40d8a8bc38c290a184dfbd42be48f526)`);
+        }
+    }
+}
+
 /**
  * Validates the transition from Prev -> Curr.
  * Enforces Cryptography AND Behavioral Policy.
@@ -700,28 +805,48 @@ export async function validateKeystoneTransition({
         const currData = currentIbGib.data!;
         const prevData = prevIbGib.data!;
 
+        const isValidIb = await validateKeystoneIb({ ib: currentIbGib.ib });
+        if (!isValidIb) {
+            errors.push(`${lc} invalid keystone ib (${currentIbGib.ib}). (E: a98dc8bc38c290a184dfbd42be48f526)`);
+        }
+
         // Validate username/description metadata if present
         const metadataErrors = validateKeystoneMetadata({ data: currData });
         metadataErrors.forEach(x => errors.push(x));
 
+        // Validate delegates map mutations if present
+        const currDelegates = currData.delegates || {};
+        const prevDelegates = prevData.delegates || {};
+        const delegatesChanged = isDelegatesChanged({ currDelegates, prevDelegates });
+
+        if (delegatesChanged) {
+            const hasManageProof = currData.proofs?.some(proof => proof.claim?.verb === KEYSTONE_VERB_MANAGE);
+            if (!hasManageProof) {
+                errors.push(`${lc} Policy Violation: Delegates map was mutated but no proof for manage verb ('${KEYSTONE_VERB_MANAGE}') is present. (E: 819fa8cb28c9b60e68994511a5825)`);
+            }
+        }
+
+        // Validate each delegate's structure and constraints
+        await validateDelegates({ currDelegates, prevIbGib, lc, errors });
+
         // 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
         const currDataN = currData.n ?? -2;
         const prevDataN = prevData.n ?? -2;
         if (currDataN < 0) {
-            errors.push('invalid keystone.currData.n is undefined or null.');
+            errors.push('invalid keystone.currData.n is undefined or null. (E: 9fbe38704b68829d18ea1d0940d0aa26)');
         }
         if (prevDataN < 0) {
-            errors.push('invalid keystone.prevData.n is undefined or null.');
+            errors.push('invalid keystone.prevData.n is undefined or null. (E: 6dc5aa9c87017db6080ed4268b07af26)');
         };
         if (currDataN !== (prevDataN + 1)) {
-            errors.push(`keystone data.n values are not sequential. prevData.n: ${prevDataN}, currData.n: ${currDataN}. `);
+            errors.push(`keystone data.n values are not sequential. prevData.n: ${prevDataN}, currData.n: ${currDataN}. (E: 5ae12809f2c67216d38d8ba8d6c42826)`);
         }
 
         for (const proof of currData.proofs) {
             if (proof.solutions.length === 0) {
-                errors.push(`Proof ${proof.id || 'unknown'} has no solutions.`);
+                errors.push(`Proof ${proof.id || 'unknown'} has no solutions. (E: e2b4683ce0ce30f798ec77841e88c826)`);
                 continue;
             }
 
@@ -860,6 +985,7 @@ export async function evolvePersistAndRegisterKeystone({
         if (prevData.challengePools) { dataToRemove.challengePools = []; }
         if (prevData.frameDetails) { dataToRemove.frameDetails = {}; }
         if (prevData.checkpointDetails) { dataToRemove.checkpointDetails = {}; }
+        if (prevData.delegates) { (dataToRemove as any).delegates = 'remove'; }
         if (Object.keys(dataToRemove).length === 0) { dataToRemove = undefined; }
 
         const resMut8 = await mut8({

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

@@ -1,22 +1,30 @@
 import { extractErrorMsg, mergeMapsOrArrays_Naive } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { getIbGibAddr, getIbAndGib } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
 import {
     KeystoneData_V1, KeystoneIbGib_V1, KeystonePoolConfig, KeystoneClaim,
     KeystoneChallengePool, KeystoneReplenishStrategy, KeystoneRevocationInfo,
+    DelegateKeystoneStatus,
 } from './keystone-types.mjs';
 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 {
+    POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_VERB_MANAGE,
+    KEYSTONE_CHECKPOINT_FREQUENCY, POOL_ID_MANAGE
+} from './keystone-constants.mjs';
 import {
     createKeystoneIbGibImpl, evolvePersistAndRegisterKeystone,
     generateOpaqueChallengeId, resolveTargetPool, selectChallengeIds,
     solveAndReplenish, validateKeystoneTransition,
     validateGenesisKeystone, validateKeystoneGraph
 } from './keystone-helpers.mjs';
+import { getLatestAddrs } from '../witness/space/space-helper.mjs';
 import { IbGibSpaceAny } from '../witness/space/space-base-v1.mjs';
 import { MetaspaceService } from '../witness/space/metaspace/metaspace-types.mjs';
 import { FlatIbGibGraph } from '../common/other/graph-types.mjs';
+import { getTjpAddr } from '../common/other/ibgib-helper.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -110,6 +118,7 @@ export class KeystoneService_V1 {
         frameDetails,
         metaspace,
         space,
+        dataToPatch,
     }: {
         latestKeystone: KeystoneIbGib_V1;
         /**
@@ -133,6 +142,7 @@ export class KeystoneService_V1 {
         frameDetails?: any;
         metaspace: MetaspaceService;
         space: IbGibSpaceAny;
+        dataToPatch?: Partial<KeystoneData_V1>;
     }): Promise<KeystoneIbGib_V1> {
         const lc = `${this.lc}[${this.sign.name}]`;
         try {
@@ -193,6 +203,8 @@ export class KeystoneService_V1 {
                 proofs: [proof],
                 frameDetails,
                 checkpointDetails,
+                ...(prevData.delegates ? { delegates: prevData.delegates } : {}),
+                ...dataToPatch,
             };
 
             // 5. Commit (Evolve, Persist, Register)
@@ -236,6 +248,209 @@ export class KeystoneService_V1 {
         return errors;
     }
 
+    /**
+     * Registers a delegate keystone on the parent keystone by appending its information
+     * to the parent's `delegates` map. This operation is signed using the parent's `manage` pool.
+     * Validates the delegate keystone's entire graph/timeline before registering.
+     */
+    async registerDelegate({
+        parentKeystone,
+        delegateKeystone,
+        masterSecret,
+        frameDetails,
+        metaspace,
+        space,
+    }: {
+        parentKeystone: KeystoneIbGib_V1;
+        delegateKeystone: KeystoneIbGib_V1;
+        masterSecret: string;
+        frameDetails?: any;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.registerDelegate.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            // 1. Validate the delegate keystone's entire graph/timeline
+            const validationErrors = await validateKeystoneGraph({
+                keystoneIbGib: delegateKeystone,
+                getLatest: true,
+                invalidIfMoreRecentKeystoneFoundInSpace: false,
+                space,
+            });
+            if (validationErrors.length > 0) {
+                throw new Error(`Delegate keystone validation failed: ${validationErrors.join(', ')} (E: 88fa8ab28c9b60e68994511a5825)`);
+            }
+
+            // 2. Verify that parent contains POOL_ID_MANAGE pool configuration
+            const prevData = parentKeystone.data!;
+            const hasManagePool = prevData.challengePools.some(p => p.id === POOL_ID_MANAGE);
+            if (!hasManagePool) {
+                throw new Error(`Parent keystone does not support delegation. Manage pool is required. (E: 818fa8ab28c9b60e68994511a5825)`);
+            }
+
+            const delegateTjpAddr = getTjpAddr({ ibGib: delegateKeystone });
+            if (!delegateTjpAddr) { throw new Error(`(UNEXPECTED) delegateTjpAddr falsy? (E: d4d6e8ad03c8925d4838b9a87b8f2826)`); }
+
+            // 3. Prepare the claim
+            const claim: Partial<KeystoneClaim> = {
+                target: delegateTjpAddr,
+                verb: KEYSTONE_VERB_MANAGE,
+            };
+
+            // 4. Update the delegates map
+            const currentDelegates = prevData.delegates ? { ...prevData.delegates } : {};
+            currentDelegates[delegateTjpAddr] = {
+                delegateTjpAddr,
+                delegateAddr: getIbGibAddr({ ibGib: delegateKeystone }),
+                thisAddr: getIbGibAddr({ ibGib: parentKeystone }),
+            };
+
+            // 5. Sign & evolve parent keystone using the 'manage' pool
+            const evolved = await this.sign({
+                latestKeystone: parentKeystone,
+                masterSecret,
+                claim,
+                poolId: POOL_ID_MANAGE,
+                frameDetails,
+                metaspace,
+                space,
+                dataToPatch: {
+                    delegates: currentDelegates
+                }
+            });
+
+            return evolved;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Unregisters a delegate keystone from the parent keystone by removing its entry
+     * from the parent's `delegates` map. This operation is signed using the parent's `manage` pool.
+     */
+    async unregisterDelegate({
+        parentKeystone,
+        delegateTjpAddr,
+        masterSecret,
+        frameDetails,
+        metaspace,
+        space,
+    }: {
+        parentKeystone: KeystoneIbGib_V1;
+        delegateTjpAddr: IbGibAddr;
+        masterSecret: string;
+        frameDetails?: any;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.unregisterDelegate.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            // 1. Verify that parent contains POOL_ID_MANAGE pool configuration
+            const prevData = parentKeystone.data!;
+            const hasManagePool = prevData.challengePools.some(p => p.id === POOL_ID_MANAGE);
+            if (!hasManagePool) {
+                throw new Error(`Parent keystone does not support delegation. Manage pool is required. (E: 3889f8ab28c9b60e68994511a5825)`);
+            }
+
+            // 2. Prepare the claim
+            const claim: Partial<KeystoneClaim> = {
+                target: delegateTjpAddr,
+                verb: KEYSTONE_VERB_MANAGE,
+            };
+
+            // 3. Update the delegates map
+            const currentDelegates = prevData.delegates ? { ...prevData.delegates } : {};
+            if (!currentDelegates[delegateTjpAddr]) {
+                throw new Error(`Delegate ${delegateTjpAddr} is not registered on this parent. (E: 81d9f8ab28c9b60e68994511a5825)`);
+            }
+            delete currentDelegates[delegateTjpAddr];
+
+            // 4. Sign & evolve parent keystone using the 'manage' pool
+            const evolved = await this.sign({
+                latestKeystone: parentKeystone,
+                masterSecret,
+                claim,
+                poolId: POOL_ID_MANAGE,
+                frameDetails,
+                metaspace,
+                space,
+                dataToPatch: {
+                    delegates: currentDelegates
+                }
+            });
+
+            return evolved;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Gets the registration status of a delegate keystone from the parent's latest tip frame.
+     */
+    async getDelegateStatus({
+        parentTjpAddr,
+        delegateTjpAddr,
+        metaspace,
+        space,
+    }: {
+        parentTjpAddr: IbGibAddr;
+        delegateTjpAddr: IbGibAddr;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<DelegateKeystoneStatus> {
+        const lc = `${this.lc}[${this.getDelegateStatus.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            const { ib, gib } = getIbAndGib({ ibGibAddr: parentTjpAddr });
+            const parentIbGib: IbGib_V1 = { ib, gib };
+            const resGetLatest = await getLatestAddrs({
+                ibGibs: [parentIbGib],
+                space,
+            });
+
+            if (!resGetLatest.data?.latestAddrsMap) {
+                return { registered: false };
+            }
+
+            const latestAddr = resGetLatest.data.latestAddrsMap[parentTjpAddr];
+            if (!latestAddr) {
+                return { registered: false };
+            }
+
+            const resGet = await metaspace.get({ addr: latestAddr, space });
+            const latestParent = resGet.ibGibs?.at(0) as KeystoneIbGib_V1;
+            if (!latestParent || !latestParent.data) {
+                return { registered: false };
+            }
+
+            const delegates = latestParent.data.delegates || {};
+            const delegateInfo = delegates[delegateTjpAddr];
+
+            return {
+                registered: !!delegateInfo,
+                delegateInfo,
+            };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
     /**
      * Validates a genesis keystone.
      *
@@ -429,6 +644,7 @@ export class KeystoneService_V1 {
                 revocationInfo,
                 frameDetails,
                 checkpointDetails,
+                ...(prevData.delegates ? { delegates: prevData.delegates } : {}),
             };
 
             // 7. Commit
@@ -555,6 +771,7 @@ export class KeystoneService_V1 {
                 challengePools: finalPools,
                 proofs: [proof], // The proof authorizes the structure change
                 checkpointDetails,
+                ...(prevData.delegates ? { delegates: prevData.delegates } : {}),
             };
 
             // 7. Commit