@ibgib/space-gib 0.0.6 → 0.0.8

package/dist/server/server.mjs

@@ -228,10 +228,10 @@ function isExpired({ expirationTimestampUTC }) {
 function unique(arr) {
   return Array.from(new Set(arr));
 }
-function patchObject({ obj, value, path, pathDelimiter, logalot: logalot60 }) {
+function patchObject({ obj, value, path, pathDelimiter, logalot: logalot63 }) {
   const lc2 = `[${patchObject.name}]`;
   try {
-    if (logalot60) {
+    if (logalot63) {
       console.log(`${lc2} starting...`);
     }
     if (!obj) {
@@ -263,7 +263,7 @@ function patchObject({ obj, value, path, pathDelimiter, logalot: logalot60 }) {
     console.error(`${lc2} ${error.message}`);
     throw error;
   } finally {
-    if (logalot60) {
+    if (logalot63) {
       console.log(`${lc2} complete.`);
     }
   }
@@ -477,6 +477,121 @@ var ServeGib_V1 = class _ServeGib_V1 {
   }
 };
 
+// ../../libs/ts-gib/dist/V1/sha256v1.mjs
+var crypto3 = globalThis.crypto;
+var { subtle: subtle2 } = crypto3;
+var BYTE_TO_HEX = new Array(256);
+for (let n = 0; n < 256; ++n) {
+  BYTE_TO_HEX[n] = n.toString(16).padStart(2, "0");
+}
+function bufToHex(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += BYTE_TO_HEX[bytes[i]];
+  }
+  return hex;
+}
+function toNormalizedForHashing(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((element) => toNormalizedForHashing(element));
+  }
+  const normalizedObject = {};
+  const sortedKeys = Object.keys(value).sort();
+  for (const key of sortedKeys) {
+    const propertyValue = value[key];
+    if (propertyValue !== void 0) {
+      normalizedObject[key] = toNormalizedForHashing(propertyValue);
+    }
+  }
+  return normalizedObject;
+}
+async function hashToHex(message) {
+  if (!message) {
+    return "";
+  }
+  const msgUint8 = new TextEncoder().encode(message);
+  const buffer = await subtle2.digest("SHA-256", msgUint8);
+  return bufToHex(buffer);
+}
+async function hashToHex_Uint8Array(salt, msgUint8) {
+  let tohashUint8Array;
+  if (salt) {
+    const msgUint8_salt = new TextEncoder().encode(salt);
+    tohashUint8Array = new Uint8Array(msgUint8_salt.length + msgUint8.length);
+    tohashUint8Array.set(msgUint8_salt);
+    tohashUint8Array.set(msgUint8, msgUint8_salt.length);
+  } else {
+    tohashUint8Array = msgUint8;
+  }
+  const hashAsBuffer = await subtle2.digest("SHA-256", tohashUint8Array);
+  return bufToHex(hashAsBuffer);
+}
+var PROFILE_SHA256 = false;
+var sha256v1CallCount = 0;
+var sha256v1TotalDuration = 0;
+async function sha256v1_Internal(ibGib, salt = "") {
+  const s = salt || "";
+  const ib = ibGib.ib;
+  const data = ibGib.data;
+  const rel8ns = ibGib.rel8ns;
+  const hasRel8ns = Object.keys(rel8ns || {}).length > 0 && Object.keys(rel8ns || {}).some((k) => rel8ns[k] && rel8ns[k].length > 0);
+  let hasData = !!data;
+  if (hasData) {
+    if (typeof data === "string") {
+      hasData = data.length > 0;
+    } else if (data instanceof Uint8Array) {
+      hasData = true;
+    } else if (typeof data === "object") {
+      hasData = Object.keys(data || {}).length > 0;
+    } else {
+      hasData = true;
+    }
+  }
+  const ibHash = (await hashToHex(s ? s + ib : ib)).toUpperCase();
+  let rel8nsHash = "";
+  if (hasRel8ns) {
+    const normalizedRel8ns = toNormalizedForHashing(rel8ns);
+    const rel8nsStr = JSON.stringify(normalizedRel8ns);
+    rel8nsHash = (await hashToHex(s ? s + rel8nsStr : rel8nsStr)).toUpperCase();
+  }
+  let dataHash = "";
+  if (hasData) {
+    if (data instanceof Uint8Array) {
+      dataHash = (await hashToHex_Uint8Array(s, data)).toUpperCase();
+    } else {
+      const normalizedData = toNormalizedForHashing(data);
+      const dataStr = JSON.stringify(normalizedData);
+      dataHash = (await hashToHex(s ? s + dataStr : dataStr)).toUpperCase();
+    }
+  }
+  let allHash;
+  if (hasRel8ns || hasData) {
+    const combinedMsg = ibHash + rel8nsHash + dataHash;
+    allHash = (await hashToHex(s ? s + combinedMsg : combinedMsg)).toUpperCase();
+  } else {
+    allHash = (await hashToHex(s ? s + ibHash : ibHash)).toUpperCase();
+  }
+  return allHash;
+}
+async function sha256v1(ibGib, salt = "") {
+  if (PROFILE_SHA256) {
+    const start = globalThis.performance ? globalThis.performance.now() : Date.now();
+    const res = await sha256v1_Internal(ibGib, salt);
+    const duration = (globalThis.performance ? globalThis.performance.now() : Date.now()) - start;
+    sha256v1CallCount++;
+    sha256v1TotalDuration += duration;
+    if (sha256v1CallCount % 1e3 === 0) {
+      console.log(`[sha256v1 Profile] Total Runs: ${sha256v1CallCount} | Average Duration: ${(sha256v1TotalDuration / sha256v1CallCount).toFixed(4)} ms`);
+    }
+    return res;
+  }
+  return sha256v1_Internal(ibGib, salt);
+}
+
 // ../../libs/ts-gib/dist/helper.mjs
 function getIbGibAddr({ ib, gib, ibGib, delimiter = "^" }) {
   ib = ib || ibGib?.ib || "";
@@ -516,114 +631,6 @@ function getIbAndGib({ ibGib, ibGibAddr, delimiter = "^" }) {
   }
 }
 
-// ../../libs/ts-gib/dist/V1/sha256v1.mjs
-var crypto3 = globalThis.crypto;
-var { subtle: subtle2 } = crypto3;
-function sha256v1(ibGib, salt = "") {
-  if (!salt) {
-    salt = "";
-  }
-  let hashToHex = async (message) => {
-    if (!message) {
-      return "";
-    }
-    const msgUint8 = new TextEncoder().encode(message);
-    const buffer = await subtle2.digest("SHA-256", msgUint8);
-    const asArray = Array.from(new Uint8Array(buffer));
-    return asArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-  };
-  let hashToHex_Uint8Array = async (salt2, msgUint8) => {
-    let tohashUint8Array;
-    if (salt2) {
-      const msgUint8_salt = new TextEncoder().encode(salt2);
-      tohashUint8Array = new Uint8Array(msgUint8_salt.length + msgUint8.length);
-      tohashUint8Array.set(msgUint8_salt);
-      tohashUint8Array.set(msgUint8, msgUint8_salt.length);
-    } else {
-      tohashUint8Array = msgUint8;
-    }
-    const hashAsBuffer = await subtle2.digest("SHA-256", tohashUint8Array);
-    const hashAsArray = Array.from(new Uint8Array(hashAsBuffer));
-    return hashAsArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-  };
-  const toNormalizedForHashing = (value) => {
-    if (value === null || typeof value !== "object") {
-      return value;
-    }
-    if (Array.isArray(value)) {
-      return value.map((element) => toNormalizedForHashing(element));
-    }
-    const normalizedObject = {};
-    const sortedKeys = Object.keys(value).sort();
-    for (const key of sortedKeys) {
-      const propertyValue = value[key];
-      if (propertyValue !== void 0) {
-        normalizedObject[key] = toNormalizedForHashing(propertyValue);
-      }
-    }
-    return normalizedObject;
-  };
-  let hashFields;
-  if (salt) {
-    hashFields = async (ib, data, rel8ns) => {
-      const hasRel8ns = Object.keys(rel8ns || {}).length > 0 && Object.keys(rel8ns || {}).some((k) => rel8ns[k] && rel8ns[k].length > 0);
-      let hasData = !!data;
-      if (hasData) {
-        if (typeof data === "string") {
-          hasData = data.length > 0;
-        } else if (data instanceof Uint8Array) {
-          hasData = true;
-        } else if (typeof data === "object") {
-          hasData = Object.keys(data || {}).length > 0;
-        } else {
-          hasData = true;
-        }
-      }
-      const ibHash = (await hashToHex(salt + ib)).toUpperCase();
-      const rel8nsHash = hasRel8ns ? (await hashToHex(salt + JSON.stringify(toNormalizedForHashing(rel8ns)))).toUpperCase() : "";
-      let dataHash = "";
-      if (hasData) {
-        if (data instanceof Uint8Array) {
-          dataHash = (await hashToHex_Uint8Array(salt, data)).toUpperCase();
-        } else {
-          dataHash = (await hashToHex(salt + JSON.stringify(toNormalizedForHashing(data)))).toUpperCase();
-        }
-      }
-      const allHash = hasRel8ns || hasData ? (await hashToHex(salt + ibHash + rel8nsHash + dataHash)).toUpperCase() : (await hashToHex(salt + ibHash)).toUpperCase();
-      return allHash;
-    };
-  } else {
-    hashFields = async (ib, data, rel8ns) => {
-      const hasRel8ns = Object.keys(rel8ns || {}).length > 0 && Object.keys(rel8ns || {}).some((k) => rel8ns[k] && rel8ns[k].length > 0);
-      let hasData = !!data;
-      if (hasData) {
-        if (typeof data === "string") {
-          hasData = data.length > 0;
-        } else if (data instanceof Uint8Array) {
-          hasData = true;
-        } else if (typeof data === "object") {
-          hasData = Object.keys(data || {}).length > 0;
-        } else {
-          hasData = true;
-        }
-      }
-      const ibHash = (await hashToHex(ib)).toUpperCase();
-      const rel8nsHash = hasRel8ns ? (await hashToHex(JSON.stringify(toNormalizedForHashing(rel8ns)))).toUpperCase() : "";
-      let dataHash = "";
-      if (hasData) {
-        if (data instanceof Uint8Array) {
-          dataHash = (await hashToHex_Uint8Array("", data)).toUpperCase();
-        } else {
-          dataHash = (await hashToHex(JSON.stringify(toNormalizedForHashing(data)))).toUpperCase();
-        }
-      }
-      const allHash = hasRel8ns || hasData ? (await hashToHex(ibHash + rel8nsHash + dataHash)).toUpperCase() : (await hashToHex(ibHash)).toUpperCase();
-      return allHash;
-    };
-  }
-  return hashFields(ibGib.ib, ibGib?.data, ibGib?.rel8ns);
-}
-
 // ../../libs/ts-gib/dist/V1/constants.mjs
 var IB = "ib";
 var GIB = "gib";
@@ -17319,7 +17326,19 @@ var API_PATH_REGEXES = {
   /**
    * /api/sync/ws/:domainAddr
    */
-  SYNC_WS: /^\/api\/sync\/ws\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/
+  SYNC_WS: /^\/api\/sync\/ws\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+  /**
+   * /api/identity/sso/link
+   */
+  IDENTITY_SSO_LINK: /^\/api\/identity\/sso\/link\/?$/,
+  /**
+   * /api/identity/sso/login
+   */
+  IDENTITY_SSO_LOGIN: /^\/api\/identity\/sso\/login\/?$/,
+  /**
+   * /api/identity/sso/config
+   */
+  IDENTITY_SSO_CONFIG: /^\/api\/identity\/sso\/config\/?$/
 };
 var VALID_STATIC_PATH_REGEX = /^\/[a-zA-Z0-9\-_\.\/]*$/;
 
@@ -17645,6 +17664,17 @@ var KeystoneReplenishStrategy = {
   deleteAll: KEYSTONE_REPLENISH_STRATEGY_DELETE_ALL
 };
 var KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES = Object.values(KeystoneReplenishStrategy);
+var KEYSTONE_CLAIM_TYPE_ADD_POOL = "add-pool";
+var KEYSTONE_CLAIM_TYPE_REMOVE_POOL = "remove-pool";
+var KEYSTONE_CLAIM_TYPE_REPLACE_POOL = "replace-pool";
+var KEYSTONE_CLAIM_TYPE_CHANGE_PASSWORD = "change-password";
+var KeystoneClaimType = {
+  add_pool: KEYSTONE_CLAIM_TYPE_ADD_POOL,
+  remove_pool: KEYSTONE_CLAIM_TYPE_REMOVE_POOL,
+  replace_pool: KEYSTONE_CLAIM_TYPE_REPLACE_POOL,
+  change_password: KEYSTONE_CLAIM_TYPE_CHANGE_PASSWORD
+};
+var KEYSTONE_CLAIM_TYPE_VALID_VALUES = Object.values(KeystoneClaimType);
 
 // ../../libs/core-gib/dist/keystone/keystone-constants.mjs
 var KEYSTONE_ATOM = "keystone";
@@ -17692,7 +17722,6 @@ var KeystoneVerb = {
   CONNECT: KEYSTONE_VERB_CONNECT
 };
 var KEYSTONE_VERB_VALID_VALUES = Object.values(KeystoneVerb);
-var POOL_ID_REVOKE = KEYSTONE_VERB_REVOKE;
 var POOL_ID_MANAGE = KEYSTONE_VERB_MANAGE;
 var POOL_ID_CONNECT = KEYSTONE_VERB_CONNECT;
 var POOL_ID_SYNC = KEYSTONE_VERB_SYNC;
@@ -18057,7 +18086,7 @@ async function generateOpaqueChallengeId({ salt, timestamp, index }) {
   const raw = await hash({ s: `${salt}${timestamp}${index}` });
   return raw.substring(0, 16);
 }
-async function applyReplenishmentStrategy({ prevPools, targetPoolId, consumedIds, masterSecret, strategy, config }) {
+async function applyReplenishmentStrategy({ prevPools, targetPoolId, consumedIds, masterSecret, strategy, config, verb }) {
   const lc2 = `[applyReplenishmentStrategy]`;
   try {
     const newPools = JSON.parse(JSON.stringify(prevPools));
@@ -18068,7 +18097,10 @@ async function applyReplenishmentStrategy({ prevPools, targetPoolId, consumedIds
     const pool = newPools[targetIdx];
     const poolSecret = await strategy.derivePoolSecret({ masterSecret });
     const timestamp = Date.now().toString();
-    const strategyType = config.behavior.replenish;
+    let strategyType = config.behavior.replenish;
+    if (verb === KEYSTONE_VERB_REVOKE) {
+      strategyType = KeystoneReplenishStrategy.deleteAll;
+    }
     if (strategyType === KeystoneReplenishStrategy.topUp) {
       consumedIds.forEach((id) => delete pool.challenges[id]);
       for (let i = 0; i < consumedIds.length; i++) {
@@ -18085,20 +18117,10 @@ async function applyReplenishmentStrategy({ prevPools, targetPoolId, consumedIds
         pool.challenges[newId] = await strategy.generateChallenge({ solution });
       }
     } else if (strategyType === KeystoneReplenishStrategy.replaceAll) {
-      pool.challenges = {};
-      for (let i = 0; i < config.behavior.size; i++) {
-        const newId = await generateOpaqueChallengeId({
-          salt: config.salt,
-          timestamp,
-          index: i
-        });
-        const solution = await strategy.generateSolution({
-          poolSecret,
-          poolId: pool.id,
-          challengeId: newId
-        });
-        pool.challenges[newId] = await strategy.generateChallenge({ solution });
-      }
+      pool.challenges = await generatePoolChallenges({
+        config,
+        masterSecret
+      });
     } else if (strategyType === KeystoneReplenishStrategy.consume) {
       consumedIds.forEach((id) => delete pool.challenges[id]);
     } else if (strategyType === KeystoneReplenishStrategy.deleteAll) {
@@ -18124,6 +18146,10 @@ async function solveAndReplenish({ targetPoolId, prevPools, masterSecret, challe
     }
     const strategy = KeystoneStrategyFactory.create({ config: pool.config });
     const poolSecret = await strategy.derivePoolSecret({ masterSecret });
+    const isSecretCorrect = await verifyPoolSecret({ pool, signingSecret: masterSecret });
+    if (!isSecretCorrect) {
+      throw new Error(`Crypto Violation: Invalid signing secret for pool: ${pool.id} (E: 8a4c2b1d3e5f6a7b8c9d0e1f2a3b4c5f)`);
+    }
     const solutions = [];
     for (const id of challengeIds) {
       const solution = await strategy.generateSolution({
@@ -18144,7 +18170,8 @@ async function solveAndReplenish({ targetPoolId, prevPools, masterSecret, challe
       consumedIds: challengeIds,
       masterSecret,
       strategy,
-      config: pool.config
+      config: pool.config,
+      verb: claim.verb
     });
     return { proof, nextPools };
   } catch (error) {
@@ -18417,6 +18444,152 @@ async function validateKeystoneTransition({ currentIbGib, prevIbGib }) {
         errors.push(`Revocation target mismatch. Expected ${expectedTarget}, got ${target}`);
       }
     }
+    const signingPoolIds = new Set(currData.proofs.map((p) => p.solutions?.[0]?.poolId).filter(Boolean));
+    for (const proof of currData.proofs) {
+      const claim = proof.claim;
+      if (claim?.details) {
+        const details = claim.details;
+        const type = details.type;
+        const info = details.info;
+        if (type === "add-pool") {
+          const addInfo = info;
+          if (!addInfo || !Array.isArray(addInfo.add) || addInfo.add.length === 0) {
+            errors.push(`details type is '${type}' but payload is invalid. (E: 1fa2a8cb28c9b60e68994511a5825)`);
+            continue;
+          }
+          const prevIds = new Set(prevData.challengePools.map((p) => p.id));
+          const currIds = new Set(currData.challengePools.map((p) => p.id));
+          for (const id of addInfo.add) {
+            if (!currIds.has(id)) {
+              errors.push(`ClaimDetails_AddPool lists pool ${id} but it is missing in the evolved keystone. (E: 2fa2a8cb28c9b60e68994511a5825)`);
+            }
+            if (prevIds.has(id)) {
+              errors.push(`ClaimDetails_AddPool attempts to add existing pool ${id}. (E: 3fa2a8cb28c9b60e68994511a5825)`);
+            }
+          }
+          if (currData.challengePools.length !== prevData.challengePools.length + addInfo.add.length) {
+            errors.push(`Structural mismatch: expected ${prevData.challengePools.length + addInfo.add.length} pools, found ${currData.challengePools.length}. (E: 4fa2a8cb28c9b60e68994511a5825)`);
+          }
+          for (const prevPool of prevData.challengePools) {
+            const currPool = currData.challengePools.find((p) => p.id === prevPool.id);
+            if (!currPool) {
+              errors.push(`Existing pool ${prevPool.id} was removed during add-pool transition. (E: 5fa2a8cb28c9b60e68994511a5825)`);
+              continue;
+            }
+            if (JSON.stringify(prevPool.config) !== JSON.stringify(currPool.config)) {
+              errors.push(`Existing pool config ${prevPool.id} was mutated during add-pool transition. (E: 6fa2a8cb28c9b60e68994511a5825)`);
+            }
+            if (!signingPoolIds.has(prevPool.id) && JSON.stringify(prevPool.challenges) !== JSON.stringify(currPool.challenges)) {
+              errors.push(`Existing pool challenges ${prevPool.id} were mutated during add-pool transition. (E: 7fa2a8cb28c9b60e68994511a5825)`);
+            }
+          }
+        } else if (type === "replace-pool") {
+          const replaceInfo = info;
+          if (!replaceInfo || typeof replaceInfo.replace !== "string" || !replaceInfo.replace) {
+            errors.push(`details type is '${type}' but payload is invalid. (E: 8fa2a8cb28c9b60e68994511a5825)`);
+            continue;
+          }
+          const targetId = replaceInfo.replace;
+          const prevIds = prevData.challengePools.map((p) => p.id).sort();
+          const currIds = currData.challengePools.map((p) => p.id).sort();
+          if (JSON.stringify(prevIds) !== JSON.stringify(currIds)) {
+            errors.push(`replace-pool transition mutated the pool IDs set. (E: 9fa2a8cb28c9b60e68994511a5825)`);
+          }
+          const prevTarget = prevData.challengePools.find((p) => p.id === targetId);
+          const currTarget = currData.challengePools.find((p) => p.id === targetId);
+          if (!prevTarget || !currTarget) {
+            errors.push(`Replaced pool ${targetId} not found in keystone challenge pools. (E: afa2a8cb28c9b60e68994511a5825)`);
+          }
+          for (const prevPool of prevData.challengePools) {
+            if (prevPool.id === targetId)
+              continue;
+            const currPool = currData.challengePools.find((p) => p.id === prevPool.id);
+            if (!currPool)
+              continue;
+            if (JSON.stringify(prevPool.config) !== JSON.stringify(currPool.config)) {
+              errors.push(`Unrelated pool config ${prevPool.id} was mutated during replace-pool. (E: bfa2a8cb28c9b60e68994511a5825)`);
+            }
+            if (!signingPoolIds.has(prevPool.id) && JSON.stringify(prevPool.challenges) !== JSON.stringify(currPool.challenges)) {
+              errors.push(`Unrelated pool challenges ${prevPool.id} were mutated during replace-pool. (E: cfa2a8cb28c9b60e68994511a5825)`);
+            }
+          }
+        } else if (type === "remove-pool") {
+          const removeInfo = info;
+          if (!removeInfo || !Array.isArray(removeInfo.remove) || removeInfo.remove.length === 0) {
+            errors.push(`details type is '${type}' but payload is invalid. (E: b7a2a8cb28c9b60e68994511a5825)`);
+            continue;
+          }
+          const removeSet = new Set(removeInfo.remove);
+          const prevIds = new Set(prevData.challengePools.map((p) => p.id));
+          const currIds = new Set(currData.challengePools.map((p) => p.id));
+          for (const id of removeInfo.remove) {
+            if (!prevIds.has(id)) {
+              errors.push(`ClaimDetails_RemovePool lists pool ${id} but it is missing in the previous keystone. (E: c7a2a8cb28c9b60e68994511a5825)`);
+            }
+            if (currIds.has(id)) {
+              errors.push(`ClaimDetails_RemovePool lists pool ${id} but it is still present in the evolved keystone. (E: d7a2a8cb28c9b60e68994511a5825)`);
+            }
+          }
+          if (currData.challengePools.length !== prevData.challengePools.length - removeInfo.remove.length) {
+            errors.push(`Structural mismatch: expected ${prevData.challengePools.length - removeInfo.remove.length} pools, found ${currData.challengePools.length}. (E: e7a2a8cb28c9b60e68994511a5825)`);
+          }
+          for (const prevPool of prevData.challengePools) {
+            if (removeSet.has(prevPool.id))
+              continue;
+            const currPool = currData.challengePools.find((p) => p.id === prevPool.id);
+            if (!currPool) {
+              errors.push(`Pool ${prevPool.id} was unexpectedly removed. (E: f7a2a8cb28c9b60e68994511a5825)`);
+              continue;
+            }
+            if (JSON.stringify(prevPool.config) !== JSON.stringify(currPool.config)) {
+              errors.push(`Remaining pool config ${prevPool.id} was mutated during remove-pool. (E: 07a2a8cb28c9b60e68994511a5825)`);
+            }
+            if (!signingPoolIds.has(prevPool.id) && JSON.stringify(prevPool.challenges) !== JSON.stringify(currPool.challenges)) {
+              errors.push(`Remaining pool challenges ${prevPool.id} were mutated during remove-pool. (E: 17a2a8cb28c9b60e68994511a5825)`);
+            }
+          }
+        } else if (type === "change-password") {
+          const changeInfo = info;
+          if (!changeInfo || !Array.isArray(changeInfo.change) || changeInfo.change.length === 0) {
+            errors.push(`details type is '${type}' but payload is invalid. (E: dfa2a8cb28c9b60e68994511a5825)`);
+            continue;
+          }
+          const prevIds = prevData.challengePools.map((p) => p.id).sort();
+          const currIds = currData.challengePools.map((p) => p.id).sort();
+          if (JSON.stringify(prevIds) !== JSON.stringify(currIds)) {
+            errors.push(`change-password transition mutated the pool IDs set. (E: efa2a8cb28c9b60e68994511a5825)`);
+          }
+          const rotatedIds = new Set(changeInfo.change);
+          for (const prevPool of prevData.challengePools) {
+            const currPool = currData.challengePools.find((p) => p.id === prevPool.id);
+            if (!currPool)
+              continue;
+            if (rotatedIds.has(prevPool.id)) {
+              if (prevPool.isForeign) {
+                errors.push(`Security Violation: Password rotation attempted on foreign pool ${prevPool.id}. (E: ffa2a8cb28c9b60e68994511a5825)`);
+              }
+              const prevConfCopy = { ...prevPool.config, salt: "" };
+              const currConfCopy = { ...currPool.config, salt: "" };
+              if (JSON.stringify(prevConfCopy) !== JSON.stringify(currConfCopy)) {
+                errors.push(`Pool config metadata for rotated pool ${prevPool.id} was mutated. (E: 00b2a8cb28c9b60e68994511a5825)`);
+              }
+              if (prevPool.config.salt === currPool.config.salt) {
+                errors.push(`Pool salt for rotated pool ${prevPool.id} was not rotated. (E: 01b2a8cb28c9b60e68994511a5825)`);
+              }
+            } else {
+              if (JSON.stringify(prevPool.config) !== JSON.stringify(currPool.config)) {
+                errors.push(`Unrelated pool config ${prevPool.id} was mutated during change-password. (E: 02b2a8cb28c9b60e68994511a5825)`);
+              }
+              if (!signingPoolIds.has(prevPool.id) && JSON.stringify(prevPool.challenges) !== JSON.stringify(currPool.challenges)) {
+                errors.push(`Unrelated pool challenges ${prevPool.id} were mutated during change-password. (E: 03b2a8cb28c9b60e68994511a5825)`);
+              }
+            }
+          }
+        } else {
+          errors.push(`Unknown claim details type: ${type}`);
+        }
+      }
+    }
     return errors;
   } catch (error) {
     console.error(`${lc2} ${extractErrorMsg(error)}`);
@@ -18704,6 +18877,65 @@ async function validateKeystoneGraph({ keystoneIbGib, dependencyGraph, getLatest
     }
   }
 }
+async function generatePoolChallenges({ config, masterSecret }) {
+  const strategy = KeystoneStrategyFactory.create({ config });
+  const poolSecret = await strategy.derivePoolSecret({ masterSecret });
+  const challenges = {};
+  const targetSize = config.behavior.size;
+  const timestamp = Date.now().toString();
+  for (let i = 0; i < targetSize; i++) {
+    const challengeId = await generateOpaqueChallengeId({
+      salt: config.salt,
+      timestamp,
+      index: i
+    });
+    const solution = await strategy.generateSolution({
+      poolSecret,
+      poolId: config.id,
+      challengeId
+    });
+    challenges[challengeId] = await strategy.generateChallenge({ solution });
+  }
+  return challenges;
+}
+async function rotatePoolChallenges({ prevPool, newMasterSecret }) {
+  const prevConfig = prevPool.config;
+  const newSalt = (await getUUID()).substring(0, 16);
+  const newConfig = {
+    ...prevConfig,
+    salt: newSalt
+  };
+  const newChallenges = await generatePoolChallenges({
+    config: newConfig,
+    masterSecret: newMasterSecret
+  });
+  return {
+    id: prevPool.id,
+    config: newConfig,
+    challenges: newChallenges,
+    ...prevPool.isForeign !== void 0 ? { isForeign: prevPool.isForeign } : {},
+    ...prevPool.metadata ? { metadata: prevPool.metadata } : {}
+  };
+}
+async function verifyPoolSecret({ pool, signingSecret }) {
+  const challengeIds = Object.keys(pool.challenges);
+  if (challengeIds.length === 0)
+    return false;
+  try {
+    const firstId = challengeIds[0];
+    const challenge = pool.challenges[firstId];
+    const strategy = KeystoneStrategyFactory.create({ config: pool.config });
+    const poolSecret = await strategy.derivePoolSecret({ masterSecret: signingSecret });
+    const solution = await strategy.generateSolution({
+      poolSecret,
+      poolId: pool.id,
+      challengeId: firstId
+    });
+    return await strategy.validateSolution({ solution, challenge });
+  } catch {
+    return false;
+  }
+}
 
 // ../../libs/core-gib/dist/keystone/keystone-service-v1.mjs
 var logalot41 = GLOBAL_LOG_A_LOT2;
@@ -18712,7 +18944,7 @@ var KeystoneService_V1 = class _KeystoneService_V1 {
   /**
    * Creates a brand new Keystone Identity Timeline.
    */
-  async genesis({ masterSecret, frameDetails, configs, metaspace, space }) {
+  async genesis({ masterSecret, frameDetails, configs, metaspace, space, isPrimary }) {
     const lc2 = `${this.lc}[${this.genesis.name}]`;
     try {
       if (logalot41) {
@@ -18720,25 +18952,10 @@ var KeystoneService_V1 = class _KeystoneService_V1 {
       }
       const challengePools = [];
       for (const config of configs) {
-        const strategy = KeystoneStrategyFactory.create({ config });
-        const poolSecret = await strategy.derivePoolSecret({ masterSecret });
-        const challenges = {};
-        const targetSize = config.behavior.size;
-        const timestamp = Date.now().toString();
-        for (let i = 0; i < targetSize; i++) {
-          const challengeId = await generateOpaqueChallengeId({
-            salt: config.salt,
-            timestamp,
-            index: i
-          });
-          const solution = await strategy.generateSolution({
-            poolSecret,
-            poolId: config.id,
-            challengeId
-          });
-          const challenge = await strategy.generateChallenge({ solution });
-          challenges[challengeId] = challenge;
-        }
+        const challenges = await generatePoolChallenges({
+          config,
+          masterSecret
+        });
         challengePools.push({
           id: config.id,
           config,
@@ -18749,8 +18966,11 @@ var KeystoneService_V1 = class _KeystoneService_V1 {
         throw new Error(`No challenge pools created. (E: 38e538530996940e1f16a8b199995825)`);
       }
       const data = { challengePools, proofs: [] };
-      if (frameDetails) {
-        data.frameDetails = frameDetails;
+      if (frameDetails || isPrimary !== void 0) {
+        data.frameDetails = { ...frameDetails || {} };
+        if (isPrimary !== void 0) {
+          data.frameDetails.isPrimary = isPrimary;
+        }
       }
       const keystoneIbGib = await createKeystoneIbGibImpl({ data, metaspace, space });
       return keystoneIbGib;
@@ -19095,8 +19315,7 @@ var KeystoneService_V1 = class _KeystoneService_V1 {
       const prevData = latestKeystone.data;
       const pool = resolveTargetPool({
         pools: prevData.challengePools,
-        poolId: POOL_ID_REVOKE
-        // Explicitly require the special revoke pool
+        verb: KEYSTONE_VERB_REVOKE
       });
       const claim = {
         verb: KEYSTONE_VERB_REVOKE,
@@ -19196,8 +19415,10 @@ var KeystoneService_V1 = class _KeystoneService_V1 {
         verb: KEYSTONE_VERB_MANAGE,
         target,
         // I am managing myself
-        // Scope creates a cryptographic commitment to WHICH pools are being added
-        scope: JSON.stringify({ add: newPools.map((p) => p.id) })
+        details: {
+          type: KeystoneClaimType.add_pool,
+          info: { add: newPools.map((p) => p.id) }
+        }
       };
       const idsToSolve = await selectChallengeIds({
         pool: adminPool,
@@ -19253,6 +19474,98 @@ var KeystoneService_V1 = class _KeystoneService_V1 {
       }
     }
   }
+  /**
+   * Structural evolution: Removes challenge pools from the keystone.
+   *
+   * Use Case: Unlinking a custodian or delegate SSO pool.
+   *
+   * Requires the Master Secret to authorize the change via a pool containing
+   * the 'manage' verb (the administrative manage pool).
+   */
+  async removePools({ latestKeystone, masterSecret, poolIds, metaspace, space }) {
+    const lc2 = `${this.lc}[${this.removePools.name}]`;
+    try {
+      if (logalot41) {
+        console.log(`${lc2} starting...`);
+      }
+      if (!latestKeystone.data) {
+        throw new Error(`(UNEXPECTED) latestKeystone.data falsy? (E: 8334c8faed128166a999d428c7805b25)`);
+      }
+      const prevData = latestKeystone.data;
+      if (prevData.revocationInfo) {
+        throw new Error(`Keystone has been revoked. Cannot remove pools. (E: 9599f8f51c78d722252ddb2894fdbe25)`);
+      }
+      if (poolIds.length === 0) {
+        throw new Error(`No pool IDs provided to remove. (E: 7599f8f51c78d722252ddb2894fdbe25)`);
+      }
+      const adminPool = resolveTargetPool({
+        pools: prevData.challengePools,
+        verb: KEYSTONE_VERB_MANAGE
+      });
+      if (logalot41) {
+        console.log(`${lc2} Authorized via pool: ${adminPool.id}`);
+      }
+      const target = getIbGibAddr({ ibGib: latestKeystone });
+      const claim = {
+        verb: KEYSTONE_VERB_MANAGE,
+        target,
+        details: {
+          type: KeystoneClaimType.remove_pool,
+          info: { remove: poolIds }
+        }
+      };
+      const idsToSolve = await selectChallengeIds({
+        pool: adminPool,
+        targetAddr: target
+      });
+      const { proof, nextPools: replenishedExistingPools } = await solveAndReplenish({
+        targetPoolId: adminPool.id,
+        prevPools: prevData.challengePools,
+        masterSecret,
+        challengeIds: idsToSolve,
+        claim
+      });
+      const removeSet = new Set(poolIds);
+      const finalPools = replenishedExistingPools.filter((p) => !removeSet.has(p.id));
+      if (finalPools.length !== replenishedExistingPools.length - poolIds.length) {
+        const missingIds = poolIds.filter((id) => !replenishedExistingPools.some((p) => p.id === id));
+        throw new Error(`Cannot remove pool. Pool IDs not found in keystone: ${missingIds.join(", ")} (E: 8a4c2b1d3e5f6a7b8c9d0e1f2a3b4c5e)`);
+      }
+      const n = (prevData.n ?? 0) + 1;
+      let checkpointDetails;
+      if (n % KEYSTONE_CHECKPOINT_FREQUENCY === 0) {
+        const currentFrameView = {
+          ...latestKeystone,
+          data: { ...prevData, challengePools: finalPools }
+        };
+        checkpointDetails = await this.getAggregateDetails({
+          latestKeystone: currentFrameView,
+          metaspace,
+          space
+        });
+      }
+      const newData = {
+        challengePools: finalPools,
+        proofs: [proof],
+        checkpointDetails,
+        ...prevData.delegates ? { delegates: prevData.delegates } : {}
+      };
+      const newKeystone = await evolvePersistAndRegisterKeystone({
+        prevIbGib: latestKeystone,
+        newData,
+        metaspace,
+        space
+      });
+      return newKeystone;
+    } catch (error) {
+      console.error(`${lc2} ${extractErrorMsg(error)}`);
+      throw error;
+    } finally {
+      if (logalot41) {
+        console.log(`${lc2} complete.`);
+      }
+    }
+  }
   /**
    * Consolidates the state of a Keystone identity across its history.
    * Walks back until it hits a checkpoint or genesis.
@@ -19297,29 +19610,328 @@ var KeystoneService_V1 = class _KeystoneService_V1 {
       throw error;
     }
   }
-};
-
-// ../../libs/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs
-var logalot42 = GLOBAL_LOG_A_LOT2;
-var SESSION_KEYSTONE_POLICY = {
-  COMMON: {
-    ALGO: HashAlgorithm.sha_256,
-    TYPE: KeystoneChallengeType.hash_reveal_v1,
-    ROUNDS: 2,
-    REPLENISH: KeystoneReplenishStrategy.topUp
-  },
-  CONNECT_POOL: {
-    ID: POOL_ID_CONNECT,
-    VERB: KEYSTONE_VERB_CONNECT,
-    SIZE: 10,
-    SELECT_SEQUENTIALLY: 2,
-    SELECT_RANDOMLY: 2,
-    TARGET_BINDING_COUNT: 0,
-    SERVER_DEMAND_COUNT: 3
-  }
-};
-function getConnectChallenge(keystone) {
-  const lc2 = `[${getConnectChallenge.name}]`;
+  /**
+   * Retrieves common aggregated info for a keystone timeline.
+   */
+  async getKeystoneCommonInfo({ addr, ibGib, metaspace, space }) {
+    const lc2 = `${this.lc}[getKeystoneCommonInfo]`;
+    try {
+      let targetAddr = addr;
+      let targetIbGib = ibGib;
+      if (!targetAddr) {
+        if (!targetIbGib) {
+          return null;
+        }
+        targetAddr = getIbGibAddr({ ibGib: targetIbGib });
+      }
+      if (!targetIbGib) {
+        const { ib, gib } = getIbAndGib({ ibGibAddr: targetAddr });
+        targetIbGib = { ib, gib };
+      }
+      const resGetLatest = await getLatestAddrs({
+        ibGibs: [targetIbGib],
+        space
+      });
+      if (!resGetLatest.data?.latestAddrsMap) {
+        return null;
+      }
+      const latestAddr = resGetLatest.data.latestAddrsMap[targetAddr] || Object.values(resGetLatest.data.latestAddrsMap)[0];
+      if (!latestAddr) {
+        return null;
+      }
+      const resGet = await metaspace.get({ addr: latestAddr, space });
+      const latestKeystone = resGet.ibGibs?.at(0);
+      if (!latestKeystone || !latestKeystone.data) {
+        return null;
+      }
+      const aggregateDetails = await this.getAggregateDetails({
+        latestKeystone,
+        metaspace,
+        space
+      });
+      const name = aggregateDetails?.username || aggregateDetails?.profile?.name || aggregateDetails?.name || "";
+      const description = aggregateDetails?.description || aggregateDetails?.profile?.description || "";
+      const isPrimary = !!aggregateDetails?.isPrimary || !!aggregateDetails?.profile?.isPrimary;
+      const latestFrameDetails = latestKeystone.data.frameDetails || {};
+      const n = latestKeystone.data.n ?? 0;
+      const timestamp = latestFrameDetails?.timestamp || aggregateDetails?.timestamp || "";
+      const timestampMs = latestFrameDetails?.timestampMs || aggregateDetails?.timestampMs || void 0;
+      return {
+        name,
+        description,
+        isPrimary,
+        aggregateDetails,
+        latestFrameDetails,
+        n,
+        timestamp,
+        timestampMs
+      };
+    } catch (error) {
+      console.error(`${lc2} ${extractErrorMsg(error)}`);
+      return null;
+    }
+  }
+  /**
+   * Replaces a challenge pool (such as manage or custodian-manage) with a new pool,
+   * authorizing the transition via the specified signing pool.
+   *
+   * @param latestKeystone The current tip frame of the keystone timeline.
+   *   - Visibility: Public (Public Merkle frame, safe for logs/ledger).
+   *   - Generator: Client/Server (Constructed locally and synced).
+   *
+   * @param newPool The fully constructed new pool to place in the next frame.
+   *   - Visibility: Public (Public configuration and public challenges, safe for ledger).
+   *   - Generator: Client/Server (Generated dynamically by the party proposing the update).
+   *
+   * @param signingSecret The master secret or derived KDF secret of the pool authorizing the change.
+   *   - Visibility: Private (Confidential secret credential. Must never go over the wire).
+   *   - Generator: Client/Server (Known only to the signing party).
+   *
+   * @param signingPoolId The ID of the pool used to authorize the transition (defaults to 'manage').
+   *   - Visibility: Public (Non-sensitive configuration string).
+   *   - Generator: Client/Server (From pool configuration).
+   */
+  async replacePool({ latestKeystone, newPool, signingSecret, signingPoolId = POOL_ID_MANAGE, frameDetails, metaspace, space }) {
+    const lc2 = `${this.lc}[${this.replacePool.name}]`;
+    try {
+      if (logalot41) {
+        console.log(`${lc2} starting... replacing pool: ${newPool.id}`);
+      }
+      if (!latestKeystone.data) {
+        throw new Error(`(UNEXPECTED) latestKeystone.data falsy? (E: 1334c8faed128166a999d428c7805b25)`);
+      }
+      const prevData = latestKeystone.data;
+      if (prevData.revocationInfo) {
+        throw new Error(`Keystone has been revoked. Cannot replace pool. (E: 2599f8f51c78d722252ddb2894fdbe25)`);
+      }
+      const prevPools = prevData.challengePools;
+      const signingPool = prevPools.find((p) => p.id === signingPoolId);
+      if (!signingPool) {
+        throw new Error(`Signing pool not found: ${signingPoolId} (E: 3599f8f51c78d722252ddb2894fdbe25)`);
+      }
+      const target = getIbGibAddr({ ibGib: latestKeystone });
+      const claim = {
+        verb: KEYSTONE_VERB_MANAGE,
+        target,
+        details: {
+          type: KeystoneClaimType.replace_pool,
+          info: { replace: newPool.id }
+        }
+      };
+      const idsToSolve = await selectChallengeIds({
+        pool: signingPool,
+        targetAddr: target
+      });
+      const { proof, nextPools } = await solveAndReplenish({
+        targetPoolId: signingPoolId,
+        prevPools,
+        masterSecret: signingSecret,
+        challengeIds: idsToSolve,
+        claim
+      });
+      const targetIdx = nextPools.findIndex((p) => p.id === newPool.id);
+      if (targetIdx === -1) {
+        throw new Error(`Target pool to replace '${newPool.id}' not found in keystone challenge pools.`);
+      }
+      nextPools[targetIdx] = newPool;
+      const n = (prevData.n ?? 0) + 1;
+      let checkpointDetails;
+      if (n % KEYSTONE_CHECKPOINT_FREQUENCY === 0) {
+        const currentFrameView = {
+          ...latestKeystone,
+          data: { ...prevData, frameDetails }
+        };
+        checkpointDetails = await this.getAggregateDetails({
+          latestKeystone: currentFrameView,
+          metaspace,
+          space
+        });
+      }
+      const newData = {
+        challengePools: nextPools,
+        proofs: [proof],
+        frameDetails,
+        checkpointDetails,
+        ...prevData.delegates ? { delegates: prevData.delegates } : {}
+      };
+      const newKeystone = await evolvePersistAndRegisterKeystone({
+        prevIbGib: latestKeystone,
+        newData,
+        metaspace,
+        space
+      });
+      return newKeystone;
+    } catch (error) {
+      console.error(`${lc2} ${extractErrorMsg(error)}`);
+      throw error;
+    } finally {
+      if (logalot41) {
+        console.log(`${lc2} complete.`);
+      }
+    }
+  }
+  /**
+   * Evolve the keystone by rotating the primary user manage pool (`manage`) to a new master secret (passphrase).
+   * This creates a new frame signed by the specified `signingPoolId` using `signingSecret`.
+   *
+   * Supports recovery (signing via `custodian-manage` using the custodian secret) and normal rotation
+   * (signing via `manage` using the old password).
+   *
+   * @param latestKeystone The current tip frame of the keystone.
+   *   - Visibility: Public (Public Merkle frame, safe for ledger).
+   *   - Generator: Client/Server (Constructed locally and synced).
+   *
+   * @param newMasterSecret The new passphrase/master secret to set for the user's primary pools.
+   *   - Visibility: Private (Confidential secret credential. Must never go over the wire).
+   *   - Generator: Client (From user input in settings).
+   *
+   * @param signingSecret The secret of the pool authorizing this change (either old passphrase or derived custodian secret).
+   *   - Visibility: Private (Confidential secret. Must never go over the wire).
+   *   - Generator: Client/Server (Known only to the signing party).
+   *
+   * @param signingPoolId The ID of the pool used to authorize the rotation (defaults to 'manage').
+   *   - Visibility: Public (Non-sensitive ID string).
+   *   - Generator: Client/Server (From pool configuration).
+   */
+  async changePassword({ latestKeystone, newMasterSecret, signingSecret, signingPoolId = POOL_ID_MANAGE, poolIds, frameDetails, metaspace, space }) {
+    const lc2 = `${this.lc}[${this.changePassword.name}]`;
+    try {
+      if (logalot41) {
+        console.log(`${lc2} starting...`);
+      }
+      if (!latestKeystone.data) {
+        throw new Error(`latestKeystone.data falsy`);
+      }
+      if (latestKeystone.data.revocationInfo) {
+        throw new Error(`Keystone has been revoked. Cannot change password. (E: 8599f8f51c78d722252ddb2894fdbe25)`);
+      }
+      const prevPools = latestKeystone.data.challengePools;
+      const signingPool = prevPools.find((p) => p.id === signingPoolId);
+      if (!signingPool) {
+        throw new Error(`Signing pool not found: ${signingPoolId} (E: 3599f8f51c78d722252ddb2894fdbe25)`);
+      }
+      let targets = [];
+      if (poolIds && poolIds.length > 0) {
+        for (const id of poolIds) {
+          const found = prevPools.find((p) => p.id === id);
+          if (!found) {
+            throw new Error(`Target pool to rotate not found: ${id} (E: 4599f8f51c78d722252ddb2894fdbe25)`);
+          }
+          targets.push(found);
+        }
+      } else {
+        targets = prevPools.filter((p) => !p.isForeign);
+        if (targets.length === 0) {
+          throw new Error(`No non-foreign pools found to rotate. (E: 5599f8f51c78d722252ddb2894fdbe25)`);
+        }
+      }
+      const rotatedPools = [];
+      for (const targetPool of targets) {
+        const rotated = await rotatePoolChallenges({
+          prevPool: targetPool,
+          newMasterSecret
+        });
+        rotatedPools.push(rotated);
+      }
+      const target = getIbGibAddr({ ibGib: latestKeystone });
+      const claim = {
+        verb: KEYSTONE_VERB_MANAGE,
+        target,
+        details: {
+          type: KeystoneClaimType.change_password,
+          info: { change: rotatedPools.map((p) => p.id) }
+        }
+      };
+      const idsToSolve = await selectChallengeIds({
+        pool: signingPool,
+        targetAddr: target
+      });
+      const { proof, nextPools } = await solveAndReplenish({
+        targetPoolId: signingPoolId,
+        prevPools,
+        masterSecret: signingSecret,
+        challengeIds: idsToSolve,
+        claim
+      });
+      for (const rotated of rotatedPools) {
+        const idx = nextPools.findIndex((p) => p.id === rotated.id);
+        if (idx === -1) {
+          throw new Error(`Rotated pool ${rotated.id} not found in next pools list. (E: 6599f8f51c78d722252ddb2894fdbe25)`);
+        }
+        nextPools[idx] = rotated;
+      }
+      const n = (latestKeystone.data.n ?? 0) + 1;
+      let checkpointDetails;
+      if (n % KEYSTONE_CHECKPOINT_FREQUENCY === 0) {
+        const currentFrameView = {
+          ...latestKeystone,
+          data: { ...latestKeystone.data, challengePools: nextPools }
+        };
+        checkpointDetails = await this.getAggregateDetails({
+          latestKeystone: currentFrameView,
+          metaspace,
+          space
+        });
+      }
+      const newData = {
+        challengePools: nextPools,
+        proofs: [proof],
+        frameDetails,
+        checkpointDetails,
+        ...latestKeystone.data.delegates ? { delegates: latestKeystone.data.delegates } : {}
+      };
+      return await evolvePersistAndRegisterKeystone({
+        prevIbGib: latestKeystone,
+        newData,
+        metaspace,
+        space
+      });
+    } catch (error) {
+      console.error(`${lc2} ${extractErrorMsg(error)}`);
+      throw error;
+    }
+  }
+  /**
+   * Verifies if a candidate signing secret (passphrase) is correct for a specific challenge pool.
+   * Does not mutate any state.
+   */
+  async verifySigningSecret({ keystoneIbGib, signingSecret, poolId }) {
+    const lc2 = `${this.lc}[${this.verifySigningSecret.name}]`;
+    try {
+      if (!keystoneIbGib.data)
+        return false;
+      const pool = keystoneIbGib.data.challengePools.find((p) => p.id === poolId);
+      if (!pool)
+        return false;
+      return await verifyPoolSecret({ pool, signingSecret });
+    } catch (error) {
+      console.warn(`${lc2} Exception during verification: ${extractErrorMsg(error)}`);
+      return false;
+    }
+  }
+};
+
+// ../../libs/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs
+var logalot42 = GLOBAL_LOG_A_LOT2;
+var SESSION_KEYSTONE_POLICY = {
+  COMMON: {
+    ALGO: HashAlgorithm.sha_256,
+    TYPE: KeystoneChallengeType.hash_reveal_v1,
+    ROUNDS: 2,
+    REPLENISH: KeystoneReplenishStrategy.topUp
+  },
+  CONNECT_POOL: {
+    ID: POOL_ID_CONNECT,
+    VERB: KEYSTONE_VERB_CONNECT,
+    SIZE: 10,
+    SELECT_SEQUENTIALLY: 2,
+    SELECT_RANDOMLY: 2,
+    TARGET_BINDING_COUNT: 0,
+    SERVER_DEMAND_COUNT: 3
+  }
+};
+function getConnectChallenge(keystone) {
+  const lc2 = `[${getConnectChallenge.name}]`;
   try {
     if (logalot42) {
       console.log(`${lc2} starting... (I: 3c791af2f978a00a087dfdde90884826)`);
@@ -19890,6 +20502,457 @@ var KeystoneGenesisHandler = class _KeystoneGenesisHandler extends ServeGibHandl
   }
 };
 
+// ../../libs/web-gib/dist/identity/sso/sso-config-helper.mjs
+function loadSsoServerConfig() {
+  const ssoServerKdfSecret = process.env.SSO_SERVER_KDF_SECRET;
+  const sessionSecret = process.env.SESSION_SECRET;
+  if (!ssoServerKdfSecret) {
+    throw new Error(`SSO_SERVER_KDF_SECRET is missing from environment. (E: 840899ab4fdfd23e89cfae1889cfae12)`);
+  }
+  if (!sessionSecret) {
+    throw new Error(`SESSION_SECRET is missing from environment. (E: bfa899ab4fdfd23e89cfae23)`);
+  }
+  const providers = {};
+  if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+    providers.google = {
+      providerId: "google",
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      tokenUrl: "https://oauth2.googleapis.com/token",
+      userInfoUrl: "https://openidconnect.googleapis.com/v1/userinfo",
+      jwksUrl: "https://www.googleapis.com/oauth2/v3/certs"
+    };
+  }
+  if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
+    providers.github = {
+      providerId: "github",
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+      tokenUrl: "https://github.com/login/oauth/access_token",
+      userInfoUrl: "https://api.github.com/user"
+    };
+  }
+  return {
+    ssoServerKdfSecret,
+    sessionSecret,
+    providers
+  };
+}
+
+// ../../libs/web-gib/dist/identity/sso/sso-custodian-service.mjs
+import { createPublicKey, verify } from "node:crypto";
+var SsoCustodianService = class _SsoCustodianService {
+  config;
+  lc = `[${_SsoCustodianService.name}]`;
+  // In-memory cache for JSON Web Key Sets (JWKS) per provider
+  jwksCache = /* @__PURE__ */ new Map();
+  jwksTtlMs = 24 * 60 * 60 * 1e3;
+  // Cache certs for 24 hours
+  /**
+   * @param config The server's global SSO configuration.
+   *   - Visibility: Private (Contains high-entropy secrets like `ssoServerKdfSecret` and `sessionSecret`).
+   *   - Generator: Server (Bootstrapped from node environment variables on server initialization).
+   */
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Exchanges an authorization code for an OAuth2 token and retrieves normalized user info.
+   *
+   * @param providerId The string identifier of the OAuth provider (e.g. 'google' or 'github').
+   *   - Visibility: Public (Non-sensitive metadata string).
+   *   - Generator: Client (Sent from browser UI selection).
+   *
+   * @param code The temporary authorization code returned by the OAuth provider.
+   *   - Visibility: Private (Confidential short-lived bearer credential. Must be kept private).
+   *   - Generator: Provider (Created by provider's OAuth page and sent to client redirect URI).
+   *
+   * @param redirectUri The redirect URI registered in the provider portal.
+   *   - Visibility: Public (Configuration URL).
+   *   - Generator: Client/Server (Derived from environmental configuration and sent by client).
+   */
+  async getOAuthUserInfo(providerId, code, redirectUri) {
+    const lc2 = `${this.lc}[${this.getOAuthUserInfo.name}]`;
+    const providerConfig = this.config.providers[providerId];
+    if (!providerConfig) {
+      throw new Error(`Provider '${providerId}' is not configured on this server. (E: c28900abfefd23e89cf23f12)`);
+    }
+    console.log(`${lc2} Exchanging code for provider: ${providerId}`);
+    const tokens = await this.exchangeCodeForTokens(providerConfig, code, redirectUri);
+    if (providerId === "google") {
+      if (!tokens.id_token) {
+        throw new Error(`Google token exchange did not return id_token. (E: e28900abfefd23e89cf45f23)`);
+      }
+      return this.verifyAndNormalizeGoogleToken(tokens.id_token);
+    } else if (providerId === "github") {
+      if (!tokens.access_token) {
+        throw new Error(`GitHub token exchange did not return access_token. (E: a28900abfefd23e89cf56f34)`);
+      }
+      return this.fetchAndNormalizeGithubUser(providerConfig, tokens.access_token);
+    }
+    throw new Error(`Unsupported provider: ${providerId}. (E: d28900abfefd23e89cf67f45)`);
+  }
+  /**
+   * Directly validates a Google ID Token (JWT) locally and returns normalized user info.
+   * Useful for client-side authentication handshakes.
+   *
+   * @param idToken The raw base64-encoded signed JSON Web Token (JWT) ID token returned by Google.
+   *   - Visibility: Private (Sensitive bearer credential containing signature and claims. Must be kept private).
+   *   - Generator: Provider (Generated and signed cryptographically by Google authentication servers).
+   */
+  async verifyAndNormalizeGoogleToken(idToken) {
+    const lc2 = `${this.lc}[${this.verifyAndNormalizeGoogleToken.name}]`;
+    const providerConfig = this.config.providers.google;
+    if (!providerConfig) {
+      throw new Error(`Google provider config is missing. (E: g28900abfefd23e89cf78f56)`);
+    }
+    const payload = await this.verifyJwt(idToken, providerConfig);
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    if (payload.exp && payload.exp < nowSeconds) {
+      throw new Error(`Token has expired. (E: t28900abfefd23e89cf89f67)`);
+    }
+    if (payload.aud !== providerConfig.clientId) {
+      throw new Error(`Token audience mismatch. Expected ${providerConfig.clientId}, got ${payload.aud}. (E: m28900abfefd23e89cf90f78)`);
+    }
+    if (!payload.sub) {
+      throw new Error(`Google JWT is missing subject claim ('sub'). (E: s28900abfefd23e89cfa1f89)`);
+    }
+    return {
+      providerKey: `google:${payload.sub}`,
+      providerId: "google",
+      sub: payload.sub,
+      email: payload.email,
+      name: payload.name,
+      picture: payload.picture
+    };
+  }
+  /**
+   * Internal: Exchange authorization code for access token / ID token.
+   *
+   * @param providerConfig Server configuration settings for the specific provider.
+   *   - Visibility: Private (Contains provider client secrets. Must stay server-side).
+   *   - Generator: Server (Configured from node environment variables).
+   *
+   * @param code The temporary authorization code to exchange.
+   *   - Visibility: Private (Short-lived credential. Must be kept private).
+   *   - Generator: Provider (Via OAuth flow).
+   *
+   * @param redirectUri The redirect URI registered for the exchange.
+   *   - Visibility: Public (Configuration URL).
+   *   - Generator: Client/Server (From app configuration).
+   */
+  async exchangeCodeForTokens(providerConfig, code, redirectUri) {
+    const body = new URLSearchParams({
+      client_id: providerConfig.clientId,
+      client_secret: providerConfig.clientSecret,
+      code,
+      redirect_uri: redirectUri,
+      grant_type: "authorization_code"
+    });
+    const headers = {
+      "Content-Type": "application/x-www-form-urlencoded"
+    };
+    if (providerConfig.providerId === "github") {
+      headers["Accept"] = "application/json";
+    }
+    const res = await fetch(providerConfig.tokenUrl, {
+      method: "POST",
+      headers,
+      body: body.toString()
+    });
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`Token exchange failed (HTTP ${res.status}): ${errText}`);
+    }
+    return res.json();
+  }
+  /**
+   * Internal: Fetch GitHub user profile and normalize.
+   *
+   * @param providerConfig Server configuration settings for GitHub.
+   *   - Visibility: Private (Contains GitHub client secret).
+   *   - Generator: Server (From environment config).
+   *
+   * @param accessToken The active OAuth2 access token to authorize the API call.
+   *   - Visibility: Private (Bearer token. Must be kept private).
+   *   - Generator: Provider (GitHub token endpoint).
+   */
+  async fetchAndNormalizeGithubUser(providerConfig, accessToken) {
+    const res = await fetch(providerConfig.userInfoUrl, {
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "User-Agent": "space-gib-auth-agent"
+        // GitHub API requires User-Agent
+      }
+    });
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`Failed to fetch GitHub user info (HTTP ${res.status}): ${errText}`);
+    }
+    const rawUser = await res.json();
+    if (!rawUser.id) {
+      throw new Error(`GitHub user info response missing 'id' field.`);
+    }
+    const sub = String(rawUser.id);
+    return {
+      providerKey: `github:${sub}`,
+      providerId: "github",
+      sub,
+      email: rawUser.email || void 0,
+      name: rawUser.name || rawUser.login || void 0,
+      picture: rawUser.avatar_url || void 0
+    };
+  }
+  /**
+   * Internal: Decodes and cryptographically verifies a JWT signature using JWKS public keys.
+   *
+   * @param token The raw base64-encoded JWT token to verify.
+   *   - Visibility: Private (Sensitive token. Must be kept private).
+   *   - Generator: Provider (Google / OIDC server).
+   *
+   * @param providerConfig The target provider server settings containing `jwksUrl`.
+   *   - Visibility: Private (Contains secrets).
+   *   - Generator: Server (From environment config).
+   */
+  async verifyJwt(token, providerConfig) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new Error("JWT must have 3 parts separated by dots.");
+    }
+    const [headerB64, payloadB64, signatureB64] = parts;
+    let header;
+    try {
+      header = JSON.parse(Buffer.from(headerB64, "base64url").toString("utf-8"));
+    } catch {
+      throw new Error("Failed to parse JWT header.");
+    }
+    if (header.alg !== "RS256") {
+      throw new Error(`Only RS256 algorithm is supported, got: ${header.alg}`);
+    }
+    const kid = header.kid;
+    if (!kid) {
+      throw new Error("JWT header missing key ID (kid).");
+    }
+    const keys = await this.getJwksKeys(providerConfig);
+    const jwk = keys.find((key) => key.kid === kid);
+    if (!jwk) {
+      throw new Error(`JWK public key matching kid '${kid}' not found.`);
+    }
+    const publicKey = createPublicKey({
+      key: jwk,
+      format: "jwk"
+    });
+    const signature = Buffer.from(signatureB64, "base64url");
+    const data = Buffer.from(`${headerB64}.${payloadB64}`);
+    const isValid = verify("sha256", data, publicKey, signature);
+    if (!isValid) {
+      throw new Error("Cryptographic signature verification failed.");
+    }
+    try {
+      return JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf-8"));
+    } catch {
+      throw new Error("Failed to parse JWT payload.");
+    }
+  }
+  /**
+   * Internal: Retrieves JWKS keys from cache or fetches them from the provider's jwksUrl.
+   *
+   * @param providerConfig The provider config containing the target `jwksUrl`.
+   *   - Visibility: Private (Contains client secrets).
+   *   - Generator: Server (From environment config).
+   */
+  async getJwksKeys(providerConfig) {
+    const providerId = providerConfig.providerId;
+    const cached = this.jwksCache.get(providerId);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.keys;
+    }
+    if (!providerConfig.jwksUrl) {
+      throw new Error(`Provider '${providerId}' does not define a jwksUrl for JWT signature validation.`);
+    }
+    const res = await fetch(providerConfig.jwksUrl);
+    if (!res.ok) {
+      throw new Error(`Failed to fetch JWKS from ${providerConfig.jwksUrl} (HTTP ${res.status})`);
+    }
+    const body = await res.json();
+    if (!body.keys || !Array.isArray(body.keys)) {
+      throw new Error(`Invalid JWKS response structure from ${providerConfig.jwksUrl}`);
+    }
+    this.jwksCache.set(providerId, {
+      keys: body.keys,
+      expiresAt: Date.now() + this.jwksTtlMs
+    });
+    return body.keys;
+  }
+  /**
+   * Derives a server-delegate master secret deterministically using the server's private KDF secret,
+   * the providerKey, and the user's public nonce.
+   *
+   * @param providerKey The unique key identifying the provider and user sub ID (e.g. `google:123...`).
+   *   - Visibility: Public (Identifier saved on parent's delegate claim, safe for log/ledger storage).
+   *   - Generator: Provider/Server (Derived by mapping provider user sub ID after authentication).
+   *
+   * @param userNonce The public, high-entropy nonce generated by the client to salt the KDF derivation.
+   *   - Visibility: Public (Salt value stored on parent's delegate claim, safe for ledger storage).
+   *   - Generator: Client (Generated offline on user's device).
+   */
+  async deriveServerDelegateSecret(providerKey, userNonce) {
+    const salt = await hash({
+      s: `${providerKey}:${userNonce}`,
+      algorithm: HashAlgorithm.sha_512
+    });
+    return await kdf_recursiveSaltWrap({
+      masterSecret: this.config.ssoServerKdfSecret,
+      salt,
+      rounds: 1e3,
+      algorithm: HashAlgorithm.sha_512
+    });
+  }
+  /**
+   * Creates a public custodian challenge pool (custodian-manage) derived deterministically
+   * from the server's private KDF secret, providerKey, and userNonce.
+   *
+   * @param providerKey The unique key identifying the provider and user sub ID (e.g. `google:123...`).
+   *   - Visibility: Public (Mapped identifier, safe for ledger).
+   *   - Generator: Provider/Server (Derived after successful token exchange).
+   *
+   * @param userNonce The public, high-entropy nonce.
+   *   - Visibility: Public (Derivation salt, safe for ledger).
+   *   - Generator: Client (Generated on user's device).
+   */
+  async createCustodianChallengePool({ providerId, providerKey, userNonce, keystoneAddr, metaspace, space }) {
+    const keystoneService = new KeystoneService_V1();
+    const targetKeystone = await keystoneService.getLatestKeystone({
+      addr: keystoneAddr,
+      metaspace,
+      space
+    });
+    if (!targetKeystone) {
+      throw new Error(`Keystone not found for address: ${keystoneAddr} (E: 8a9c2b1d3e5f6a7b8c9d0e1f2a3b4c5d)`);
+    }
+    const userManagePool = targetKeystone.data?.challengePools.find((p) => p.id === POOL_ID_MANAGE);
+    if (!userManagePool) {
+      throw new Error(`Keystone manage pool not found. Custodian manage pool must match the user manage pool's security config. (E: 7c4e5f6a7b8c9d0e1f2a3b4c5e6f7a8b)`);
+    }
+    if (!providerId || !KEYSTONE_POOL_ID_REGEXP.test(providerId)) {
+      throw new Error(`Invalid providerId: "${providerId}". Must match ${KEYSTONE_POOL_ID_REGEXP} (E: 3a2c4e5f6a7b8c9d0e1f2a3b4c5e6f)`);
+    }
+    const poolId = `custodian-manage-${providerId}`;
+    const custodianSecret = await this.deriveServerDelegateSecret(providerKey, userNonce);
+    const poolSalt = await hash({
+      s: `${providerKey}:${userNonce}:salt`,
+      algorithm: HashAlgorithm.sha_256
+    });
+    const poolSaltShort = poolSalt.substring(0, 16);
+    const config = {
+      ...userManagePool.config,
+      id: poolId,
+      salt: poolSaltShort,
+      allowedVerbs: [KEYSTONE_VERB_MANAGE, KEYSTONE_VERB_REVOKE]
+    };
+    const strategy = KeystoneStrategyFactory.create({ config });
+    const poolSecret = await strategy.derivePoolSecret({ masterSecret: custodianSecret });
+    const challenges = {};
+    const timestamp = Date.now().toString();
+    for (let i = 0; i < config.behavior.size; i++) {
+      const challengeId = await generateOpaqueChallengeId({
+        salt: config.salt,
+        timestamp,
+        index: i
+      });
+      const solution = await strategy.generateSolution({
+        poolSecret,
+        poolId: config.id,
+        challengeId
+      });
+      challenges[challengeId] = await strategy.generateChallenge({ solution });
+    }
+    return {
+      id: poolId,
+      config,
+      challenges,
+      isForeign: true,
+      metadata: {
+        owner: "custodian",
+        providerKey
+      }
+    };
+  }
+  /**
+   * Maps private server configuration to safe public client configurations.
+   *
+   * @param hostUrl The root URL host address of the server (e.g. `https://space-gib.localhost` or `https://ibgib.space`).
+   *   - Visibility: Public (Non-sensitive hostname configuration).
+   *   - Generator: Server (Extracted from the HTTP request context headers/protocol).
+   */
+  getSsoClientConfigs(hostUrl) {
+    const configs = [];
+    if (this.config.providers.google) {
+      configs.push({
+        providerId: "google",
+        clientId: this.config.providers.google.clientId,
+        authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+        redirectUri: `${hostUrl}/`,
+        scope: "openid email profile"
+      });
+    }
+    if (this.config.providers.github) {
+      configs.push({
+        providerId: "github",
+        clientId: this.config.providers.github.clientId,
+        authUrl: "https://github.com/login/oauth/authorize",
+        redirectUri: `${hostUrl}/`,
+        scope: "read:user user:email"
+      });
+    }
+    return configs;
+  }
+  /**
+   * Revokes an active OAuth access or refresh token with the provider.
+   * Keeps token revocation logic DRY and centralized.
+   */
+  async revokeToken(providerId, token) {
+    const lc2 = `${this.lc}[${this.revokeToken.name}]`;
+    const providerConfig = this.config.providers[providerId];
+    if (!providerConfig) {
+      throw new Error(`SSO provider "${providerId}" config is missing. (E: r28900abfefd23e89cf78f57)`);
+    }
+    try {
+      if (providerId === "google") {
+        const res = await fetch(`https://oauth2.googleapis.com/revoke?token=${encodeURIComponent(token)}`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/x-www-form-urlencoded"
+          }
+        });
+        if (!res.ok) {
+          const text = await res.text();
+          console.warn(`${lc2} Google token revocation returned status ${res.status}: ${text}`);
+        }
+      } else if (providerId === "github") {
+        const auth = Buffer.from(`${providerConfig.clientId}:${providerConfig.clientSecret}`).toString("base64");
+        const res = await fetch(`https://api.github.com/applications/${providerConfig.clientId}/grant`, {
+          method: "DELETE",
+          headers: {
+            "Authorization": `Basic ${auth}`,
+            "Accept": "application/vnd.github.v3+json",
+            "User-Agent": "space-gib-server"
+          },
+          body: JSON.stringify({ access_token: token })
+        });
+        if (!res.ok && res.status !== 404) {
+          const text = await res.text();
+          console.warn(`${lc2} GitHub token revocation returned status ${res.status}: ${text}`);
+        }
+      } else {
+        throw new Error(`Unsupported provider: ${providerId} (E: e28900abfefd23e89cf78f58)`);
+      }
+    } catch (error) {
+      console.error(`${lc2} Token revocation failed for provider ${providerId}: ${extractErrorMsg(error)}`);
+    }
+  }
+};
+
 // src/server/serve-gib/handlers/api/keystone/keystone-evolve.handler.mts
 var logalot46 = GLOBAL_LOG_A_LOT || true;
 var KeystoneEvolveHandler = class _KeystoneEvolveHandler extends ServeGibHandlerWithMetaspaceBase {
@@ -19951,6 +21014,30 @@ var KeystoneEvolveHandler = class _KeystoneEvolveHandler extends ServeGibHandler
         metaspace: reqCtx.metaspace,
         space
       });
+      const claim = keystoneIbGib.data?.proofs?.[0]?.claim;
+      if (claim?.details?.type === "remove-pool") {
+        const removeInfo = claim.details.info;
+        if (removeInfo && Array.isArray(removeInfo.remove)) {
+          const config = loadSsoServerConfig();
+          const custodian4 = new SsoCustodianService(config);
+          for (const poolId of removeInfo.remove) {
+            if (poolId.startsWith("custodian-manage-")) {
+              const providerId = poolId.replace("custodian-manage-", "");
+              console.log(`${lc2} Evolved keystone removed custodian pool: ${poolId}. Performing unlink cleanup for provider: ${providerId}`);
+              const token = parsed.revokeTokens?.[providerId];
+              if (token) {
+                try {
+                  await custodian4.revokeToken(providerId, token);
+                } catch (e) {
+                  console.warn(`${lc2} Failed to revoke token for provider ${providerId}: ${extractErrorMsg(e)}`);
+                }
+              } else {
+                console.log(`${lc2} No OAuth token supplied by client for revocation of provider: ${providerId}`);
+              }
+            }
+          }
+        }
+      }
       return this.ok({
         message: `Successfully evolved domain keystone with session keystone`
       });
@@ -25225,6 +26312,298 @@ var SyncChannelHandler = class _SyncChannelHandler extends SyncUpgradeHandlerBas
 };
 var SyncUpgradeHandler = SyncChannelHandler;
 
+// ../../libs/web-gib/dist/identity/sso/sso-helpers.mjs
+function isSsoProviderLinked({ keystone, providerId }) {
+  if (!keystone?.data?.challengePools)
+    return false;
+  const targetPoolId = `custodian-manage-${providerId}`;
+  return keystone.data.challengePools.some((p) => p.id === targetPoolId);
+}
+
+// src/server/serve-gib/handlers/api/keystone/sso-link.handler.mts
+var logalot60 = GLOBAL_LOG_A_LOT || true;
+var custodian;
+function getCustodian() {
+  if (!custodian) {
+    const config = loadSsoServerConfig();
+    custodian = new SsoCustodianService(config);
+  }
+  return custodian;
+}
+var SsoLinkHandler = class _SsoLinkHandler extends ServeGibHandlerWithMetaspaceBase {
+  lc = `[${_SsoLinkHandler.name}]`;
+  method = "POST";
+  regex = API_PATH_REGEXES.IDENTITY_SSO_LINK;
+  async parseParamsImpl(reqCtx) {
+    let parsed;
+    try {
+      parsed = JSON.parse(reqCtx.body);
+    } catch {
+      return void 0;
+    }
+    const parentTjpAddr = parsed?.parentTjpAddr;
+    if (!parentTjpAddr) {
+      return void 0;
+    }
+    return {
+      parentTjpAddr,
+      domainInfo: this.getDomainInfo({ domainAddr: parentTjpAddr })
+    };
+  }
+  async validateQueryParams({ queryParams }) {
+    return [];
+  }
+  async handleRouteImpl(reqCtx) {
+    const lc2 = `${this.lc}[${this.handleRouteImpl.name}]`;
+    try {
+      if (logalot60) {
+        console.log(`${lc2} starting...`);
+      }
+      if (!reqCtx.params) {
+        return this.error(400, "Invalid parameters: parentTjpAddr missing");
+      }
+      if (!reqCtx.metaspace) {
+        return this.error(500, "Metaspace not initialized");
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(reqCtx.body);
+      } catch {
+        return this.error(400, "Request body must be valid JSON");
+      }
+      const { code, providerId, parentTjpAddr, userNonce, redirectUri } = parsed;
+      if (!code || !providerId || !parentTjpAddr || !userNonce || !redirectUri) {
+        return this.error(400, "Body missing required parameters (code, providerId, parentTjpAddr, userNonce, redirectUri)");
+      }
+      const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
+      if (!space) {
+        return this.error(500, "No local user space found in domain metaspace");
+      }
+      const keystoneService = new KeystoneService_V1();
+      const targetKeystone = await keystoneService.getLatestKeystone({
+        addr: parentTjpAddr,
+        metaspace: reqCtx.metaspace,
+        space
+      });
+      if (!targetKeystone) {
+        return this.error(400, `Keystone not found for address: ${parentTjpAddr}`);
+      }
+      if (isSsoProviderLinked({ keystone: targetKeystone, providerId })) {
+        return this.error(400, `SSO provider "${providerId}" is already linked to this keystone.`);
+      }
+      const service = getCustodian();
+      const userInfo = await service.getOAuthUserInfo(providerId, code, redirectUri);
+      const custodianPool = await service.createCustodianChallengePool({
+        providerId,
+        providerKey: userInfo.providerKey,
+        userNonce,
+        keystoneAddr: parentTjpAddr,
+        metaspace: reqCtx.metaspace,
+        space
+      });
+      console.log(`${lc2} created custodian pool for: ${userInfo.providerKey}`);
+      return this.ok({
+        success: true,
+        custodianPool
+      }, 200);
+    } catch (error) {
+      const emsg = extractErrorMsg(error);
+      console.error(`${lc2} Link failed: ${emsg}`);
+      return this.error(500, `Link failed: ${emsg}`);
+    } finally {
+      if (logalot60) {
+        console.log(`${lc2} complete.`);
+      }
+    }
+  }
+};
+
+// src/server/serve-gib/handlers/api/keystone/sso-login.handler.mts
+import { createHmac } from "node:crypto";
+var logalot61 = GLOBAL_LOG_A_LOT || true;
+var custodian2;
+function getCustodian2() {
+  if (!custodian2) {
+    const config = loadSsoServerConfig();
+    custodian2 = new SsoCustodianService(config);
+  }
+  return custodian2;
+}
+function signSessionToken(payload, secret) {
+  const header = { alg: "HS256", typ: "JWT" };
+  const headerB64 = Buffer.from(JSON.stringify(header)).toString("base64url");
+  const payloadB64 = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const data = `${headerB64}.${payloadB64}`;
+  const signature = createHmac("sha256", secret).update(data).digest("base64url");
+  return `${data}.${signature}`;
+}
+var SsoLoginHandler = class _SsoLoginHandler extends ServeGibHandlerWithMetaspaceBase {
+  lc = `[${_SsoLoginHandler.name}]`;
+  method = "POST";
+  regex = API_PATH_REGEXES.IDENTITY_SSO_LOGIN;
+  async parseParamsImpl(reqCtx) {
+    let parsed;
+    try {
+      parsed = JSON.parse(reqCtx.body);
+    } catch {
+      return void 0;
+    }
+    const parentTjpAddr = parsed?.parentTjpAddr;
+    if (!parentTjpAddr) {
+      return void 0;
+    }
+    return {
+      parentTjpAddr,
+      domainInfo: this.getDomainInfo({ domainAddr: parentTjpAddr })
+    };
+  }
+  async validateQueryParams({ queryParams }) {
+    return [];
+  }
+  async handleRouteImpl(reqCtx) {
+    const lc2 = `${this.lc}[${this.handleRouteImpl.name}]`;
+    try {
+      if (logalot61) {
+        console.log(`${lc2} starting...`);
+      }
+      if (!reqCtx.params) {
+        return this.error(400, "Invalid parameters: parentTjpAddr missing");
+      }
+      if (!reqCtx.metaspace) {
+        return this.error(500, "Metaspace not initialized");
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(reqCtx.body);
+      } catch {
+        return this.error(400, "Request body must be valid JSON");
+      }
+      const { code, providerId, parentTjpAddr, userNonce, redirectUri } = parsed;
+      if (!code || !providerId || !parentTjpAddr || !userNonce || !redirectUri) {
+        return this.error(400, "Body missing required parameters (code, providerId, parentTjpAddr, userNonce, redirectUri)");
+      }
+      const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
+      if (!space) {
+        return this.error(500, "No local user space found in domain metaspace");
+      }
+      const service = getCustodian2();
+      const userInfo = await service.getOAuthUserInfo(providerId, code, redirectUri);
+      const custodianSecret = await service.deriveServerDelegateSecret(userInfo.providerKey, userNonce);
+      const latestParentAddr = await reqCtx.metaspace.getLatestAddr({ addr: parentTjpAddr, space });
+      if (!latestParentAddr) {
+        return this.error(404, `Parent identity keystone not found for address: ${parentTjpAddr}`);
+      }
+      const resGet = await reqCtx.metaspace.get({ addr: latestParentAddr, space });
+      const parentKeystone = resGet.ibGibs?.[0];
+      if (!parentKeystone) {
+        return this.error(404, `Parent identity keystone not found in space for address: ${latestParentAddr}`);
+      }
+      const targetPoolId = `custodian-manage-${providerId}`;
+      const custodianPool = parentKeystone.data?.challengePools?.find((p) => p.id === targetPoolId);
+      if (!custodianPool) {
+        return this.error(401, `Unauthorized: Custodian pool '${targetPoolId}' is not registered in the parent identity keystone.`);
+      }
+      const allowedVerbs = custodianPool.config.allowedVerbs || [];
+      if (!allowedVerbs.includes(KEYSTONE_VERB_MANAGE)) {
+        return this.error(401, `Unauthorized: Custodian pool does not have the required manage permission.`);
+      }
+      const strategy = KeystoneStrategyFactory.create({ config: custodianPool.config });
+      const poolSecret = await strategy.derivePoolSecret({ masterSecret: custodianSecret });
+      for (const [id, challenge] of Object.entries(custodianPool.challenges)) {
+        const solution = await strategy.generateSolution({
+          poolSecret,
+          poolId: custodianPool.id,
+          challengeId: id
+        });
+        const hashValue = await strategy.generateChallenge({ solution });
+        if (hashValue.hash !== challenge.hash) {
+          return this.error(401, "Unauthorized: Cryptographic verification of custodian pool challenges failed.");
+        }
+      }
+      const sessionPayload = {
+        parentTjpAddr,
+        providerKey: userInfo.providerKey,
+        exp: Math.floor(Date.now() / 1e3) + 24 * 3600
+        // 24-hour expiration
+      };
+      const config = loadSsoServerConfig();
+      const sessionToken = signSessionToken(sessionPayload, config.sessionSecret);
+      const headers = {
+        "Set-Cookie": `space_gib_session=${sessionToken}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`
+      };
+      console.log(`${lc2} login successful for parent: ${parentTjpAddr}, custodian providerKey: ${userInfo.providerKey}`);
+      return {
+        status: 200,
+        headers,
+        body: {
+          success: true,
+          parentTjpAddr,
+          custodianPoolId: custodianPool.id
+        },
+        isJson: true
+      };
+    } catch (error) {
+      const emsg = extractErrorMsg(error);
+      console.error(`${lc2} Login failed: ${emsg}`);
+      return this.error(500, `Login failed: ${emsg}`);
+    } finally {
+      if (logalot61) {
+        console.log(`${lc2} complete.`);
+      }
+    }
+  }
+};
+
+// src/server/serve-gib/handlers/api/keystone/sso-config.handler.mts
+var logalot62 = GLOBAL_LOG_A_LOT || true;
+var custodian3;
+function getCustodian3() {
+  if (!custodian3) {
+    const config = loadSsoServerConfig();
+    custodian3 = new SsoCustodianService(config);
+  }
+  return custodian3;
+}
+var SsoConfigHandler = class _SsoConfigHandler extends ServeGibHandlerBase {
+  lc = `[${_SsoConfigHandler.name}]`;
+  method = "GET";
+  regex = API_PATH_REGEXES.IDENTITY_SSO_CONFIG;
+  async parseParamsImpl(reqCtx) {
+    return void 0;
+  }
+  async validateQueryParams({ queryParams }) {
+    return [];
+  }
+  /**
+   * @param reqCtx Context details of the incoming request.
+   *   - Visibility: Public/Private (Contextual request information containing headers).
+   *   - Generator: Server (Constructed dynamically by serve-gib-v1 pipeline).
+   */
+  async handleRouteImpl(reqCtx) {
+    const lc2 = `${this.lc}[${this.handleRouteImpl.name}]`;
+    try {
+      if (logalot62) {
+        console.log(`${lc2} starting...`);
+      }
+      const service = getCustodian3();
+      const hostUrl = `${reqCtx.protocol}://${reqCtx.headers.host}`;
+      const providers = service.getSsoClientConfigs(hostUrl);
+      return this.ok({
+        success: true,
+        providers
+      }, 200);
+    } catch (error) {
+      const emsg = extractErrorMsg(error);
+      console.error(`${lc2} Fetching SSO config failed: ${emsg}`);
+      return this.error(500, `SSO configuration retrieval failed: ${emsg}`);
+    } finally {
+      if (logalot62) {
+        console.log(`${lc2} complete.`);
+      }
+    }
+  }
+};
+
 // src/server/server.mts
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var PORT = parseInt(process.env.PORT ?? "3000", 10);
@@ -25246,6 +26625,9 @@ async function main() {
         new KeystoneEvolveHandler(),
         new KeystonePostHandler(),
         new KeystoneGetHandler(),
+        new SsoLinkHandler(),
+        new SsoLoginHandler(),
+        new SsoConfigHandler(),
         new StaticFileHandler(CLIENT_DIR)
       ],
       errorHandler: new ErrorHandler()