@ibgib/web-gib 0.0.49 → 0.0.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/web-gib",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "description": "Framework for creating agentic ibGib web apps. Contains plumbing for ibgib components, agentic framework (currently only Gemini implemented), web-based IndexedDB storage substrate, and more.",
   "funding": {
     "type": "individual",
@@ -14,6 +14,7 @@
     "//_orchestration": "~~ ORCHESTRATION (handled by @ibgib/build-gib) ~~",
     "//_publish": "~~ PUBLISH ~~",
     "pack": "npm pack --pack-destination=\"./published\"",
+    "test:node:nobuild": "node dist/respec-gib.node.mjs --inspect",
     "prepare:publish": "npm version patch && node ../../build/dist/concrete-build/build-web-gib.mjs --prod && npm run pack",
     "man:prepare:publish": "use this to patch > build > pack for publishing to npm repo"
   },
@@ -28,10 +29,10 @@
   "license": "ISC",
   "dependencies": {
     "@google/genai": "^1.33.0",
-    "@ibgib/core-gib": "^0.1.63",
+    "@ibgib/core-gib": "^0.1.64",
     "@ibgib/encrypt-gib": "^0.2.37",
     "@ibgib/helper-gib": "^0.0.36",
-    "@ibgib/ts-gib": "^0.5.32"
+    "@ibgib/ts-gib": "^0.5.33"
   },
   "engines": {
     "node": ">=19.0.0"

package/src/AUTO-GENERATED-version.mts

@@ -11,4 +11,4 @@
 /**
  * this is the version of this package, auto-updated in the build process
  */
-export const AUTO_GENERATED_VERSION = '0.0.49';
+export const AUTO_GENERATED_VERSION = '0.0.50';

package/src/common/settings/settings-constants.mts

@@ -14,6 +14,7 @@ export const SETTINGS_TYPE_PROJECTSDROPDOWN = 'projects-dropdown';
 export const SETTINGS_TYPE_PROJECT = 'project';
 export const SETTINGS_TYPE_MINIGAME = 'minigame';
 export const SETTINGS_TYPE_CHRONOLOGYS = 'chronologys';
+export const SETTINGS_TYPE_IDENTITY_MANAGER = 'identity-manager';
 /**
  * Discriminator for Settings info
  */
@@ -26,6 +27,7 @@ export type SettingsType =
     | typeof SETTINGS_TYPE_PROJECT
     | typeof SETTINGS_TYPE_MINIGAME
     | typeof SETTINGS_TYPE_CHRONOLOGYS
+    | typeof SETTINGS_TYPE_IDENTITY_MANAGER
     ;
 export const SettingsType = {
     general: SETTINGS_TYPE_GENERAL satisfies SettingsType,
@@ -36,6 +38,7 @@ export const SettingsType = {
     project: SETTINGS_TYPE_PROJECT satisfies SettingsType,
     minigame: SETTINGS_TYPE_MINIGAME satisfies SettingsType,
     chronologys: SETTINGS_TYPE_CHRONOLOGYS satisfies SettingsType,
+    identityManager: SETTINGS_TYPE_IDENTITY_MANAGER satisfies SettingsType,
 } satisfies { readonly [key: string]: SettingsType; };
 export const SETTINGS_TYPE_VALID_VALUES: SettingsType[] = Object.values(SettingsType);
 export function isSettingsType(value: any): value is SettingsType {
@@ -69,6 +72,12 @@ export const DEFAULT_SETTINGS_CHRONOLOGYS: Settings_Chronologys = {
     activeChildTjpAddr: undefined,
 }
 
+export const DEFAULT_SETTINGS_IDENTITY_MANAGER = {
+    type: SettingsType.identityManager,
+    openChildTjpAddrs: [],
+    activeChildTjpAddr: undefined,
+}
+
 export const DEFAULT_SETTINGS_DATA_V1: SettingsData_V1 = {
     sections: {},
     children: {},

package/src/common/settings/settings-helpers.mts

@@ -14,7 +14,8 @@ import {
     SETTINGS_ATOM,
     DEFAULT_SETTINGS_PROJECT,
     DEFAULT_SETTINGS_MINIGAME,
-    DEFAULT_SETTINGS_CHRONOLOGYS
+    DEFAULT_SETTINGS_CHRONOLOGYS,
+    DEFAULT_SETTINGS_IDENTITY_MANAGER
 } from "./settings-constants.mjs";
 import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
 import { getIbAndGib } from "@ibgib/ts-gib/dist/helper.mjs";
@@ -110,6 +111,8 @@ export async function getDefaultSettings<TSettings extends IbGibSettings>({
                 return clone(DEFAULT_SETTINGS_MINIGAME) as TSettings;
             case SettingsType.chronologys:
                 return clone(DEFAULT_SETTINGS_CHRONOLOGYS) as TSettings;
+            case SettingsType.identityManager:
+                return clone(DEFAULT_SETTINGS_IDENTITY_MANAGER) as any as TSettings;
             default:
                 throw new Error(`(UNEXPECTED) unknown settingsType (${settingsType})? right now, we're whitelisting only. SettingsTypes: ${SETTINGS_TYPE_VALID_VALUES} (E: 801a7ade4c0849b308d5c8f8f0318d25)`);
         }

package/src/common/settings/settings-types.mts

@@ -15,7 +15,7 @@ import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
 
 import {
     SETTINGS_ATOM, SETTINGS_TYPE_CHRONOLOGYS, SETTINGS_TYPE_MINIGAME, SETTINGS_TYPE_PROJECT,
-    SETTINGS_TYPE_TEXTEDITOR, SettingsType,
+    SETTINGS_TYPE_TEXTEDITOR, SETTINGS_TYPE_IDENTITY_MANAGER, SettingsType,
 } from "./settings-constants.mjs";
 import { LensMode } from "../project/project-types.mjs";
 
@@ -80,6 +80,10 @@ export interface Settings_Chronologys extends SettingsBase, SettingsWithTabs {
     // activeChildTjpAddr: IbGibAddr | undefined;
 }
 
+export interface Settings_IdentityManager extends SettingsBase, SettingsWithTabs {
+    type: typeof SETTINGS_TYPE_IDENTITY_MANAGER;
+}
+
 /**
  * union type of known Settings interfaces for various use cases.
  *
@@ -95,7 +99,8 @@ export type IbGibSettings =
     | Settings_TextEditor
     | Settings_Project
     | Settings_Minigame
-    | Settings_Chronologys;
+    | Settings_Chronologys
+    | Settings_IdentityManager;
 
 export interface SettingsData_V1 extends IbGibData_V1 {
     /**

package/src/identity/sso/sso-config-helper.mts

@@ -0,0 +1,52 @@
+import { SsoServerConfig, SsoProviderServerConfig, SsoProviderId } from './sso-types.mjs';
+
+/**
+ * Loads the SSO configuration from environment variables.
+ * Parses active OAuth2 providers dynamically based on their environment keys.
+ */
+export function loadSsoServerConfig(): SsoServerConfig {
+    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: Partial<Record<SsoProviderId, SsoProviderServerConfig>> = {};
+
+    // Load Google Provider if configured
+    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'
+        };
+    }
+
+    // Load GitHub Provider if configured
+    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
+    };
+}

package/src/identity/sso/sso-custodian-service.mts

@@ -0,0 +1,453 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { hash, HashAlgorithm } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { kdf_recursiveSaltWrap } from '@ibgib/core-gib/dist/keystone/kdf/kdf-helpers.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { KeystoneProfileBuilder } from '@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs';
+import { KeystoneIbGib_V1, KeystoneChallengePool } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { POOL_ID_CUSTODIAN_MANAGE, KEYSTONE_VERB_MANAGE, KEYSTONE_VERB_REVOKE } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+import { createStandardPoolConfig } from '@ibgib/core-gib/dist/keystone/keystone-config-builder.mjs';
+import { generateOpaqueChallengeId } from '@ibgib/core-gib/dist/keystone/keystone-helpers.mjs';
+import { KeystoneStrategyFactory } from '@ibgib/core-gib/dist/keystone/strategy/keystone-strategy-factory.mjs';
+import { 
+    SsoServerConfig, 
+    SsoProviderId, 
+    OAuthUserInfo, 
+    SsoProviderServerConfig,
+    SsoProviderClientConfig
+} from './sso-types.mjs';
+
+interface JwkKey {
+    kty: string;
+    alg?: string;
+    use?: string;
+    kid: string;
+    n: string;
+    e: string;
+    [key: string]: any;
+}
+
+interface JwksResponse {
+    keys: JwkKey[];
+}
+
+/**
+ * Server-side service for token exchange, JWT validation, and user profile normalization.
+ */
+export class SsoCustodianService {
+    private lc = `[${SsoCustodianService.name}]`;
+    
+    // In-memory cache for JSON Web Key Sets (JWKS) per provider
+    private jwksCache: Map<SsoProviderId, { keys: JwkKey[]; expiresAt: number }> = new Map();
+    private jwksTtlMs = 24 * 60 * 60 * 1000; // 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(private config: SsoServerConfig) {}
+
+    /**
+     * 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: SsoProviderId, code: string, redirectUri: string): Promise<OAuthUserInfo> {
+        const lc = `${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(`${lc} Exchanging code for provider: ${providerId}`);
+
+        // 1. Exchange authorization code for tokens
+        const tokens = await this.exchangeCodeForTokens(providerConfig, code, redirectUri);
+
+        // 2. Retrieve and normalize user info
+        if (providerId === 'google') {
+            // Google returns an id_token (JWT) directly containing user info
+            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') {
+            // GitHub requires calling the /user API using the access_token
+            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: string): Promise<OAuthUserInfo> {
+        const lc = `${this.lc}[${this.verifyAndNormalizeGoogleToken.name}]`;
+        const providerConfig = this.config.providers.google;
+        if (!providerConfig) {
+            throw new Error(`Google provider config is missing. (E: g28900abfefd23e89cf78f56)`);
+        }
+
+        // Verify signature and decode JWT payload
+        const payload = await this.verifyJwt(idToken, providerConfig);
+
+        // Assert claims
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        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).
+     */
+    private async exchangeCodeForTokens(
+        providerConfig: SsoProviderServerConfig, 
+        code: string, 
+        redirectUri: string
+    ): Promise<any> {
+        const body = new URLSearchParams({
+            client_id: providerConfig.clientId,
+            client_secret: providerConfig.clientSecret,
+            code,
+            redirect_uri: redirectUri,
+            grant_type: 'authorization_code'
+        });
+
+        const headers: Record<string, string> = {
+            'Content-Type': 'application/x-www-form-urlencoded'
+        };
+
+        // GitHub requires an Accept header to return JSON instead of URL-encoded string
+        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).
+     */
+    private async fetchAndNormalizeGithubUser(
+        providerConfig: SsoProviderServerConfig, 
+        accessToken: string
+    ): Promise<OAuthUserInfo> {
+        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 || undefined,
+            name: rawUser.name || rawUser.login || undefined,
+            picture: rawUser.avatar_url || undefined
+        };
+    }
+
+    /**
+     * 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).
+     */
+    public async verifyJwt(token: string, providerConfig: SsoProviderServerConfig): Promise<any> {
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            throw new Error('JWT must have 3 parts separated by dots.');
+        }
+
+        const [headerB64, payloadB64, signatureB64] = parts;
+
+        // 1. Decode header and select algorithm/key ID
+        let header: any;
+        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).');
+        }
+
+        // 2. Fetch public keys (JWKS)
+        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.`);
+        }
+
+        // 3. Create Public Key object using Node native crypto
+        const publicKey = createPublicKey({
+            key: jwk as any,
+            format: 'jwk'
+        });
+
+        // 4. Verify signature against header + payload data
+        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.');
+        }
+
+        // 5. Decode and return payload
+        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).
+     */
+    private async getJwksKeys(providerConfig: SsoProviderServerConfig): Promise<JwkKey[]> {
+        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()) as JwksResponse;
+        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: string, userNonce: string): Promise<string> {
+        const salt = await hash({
+            s: `${providerKey}:${userNonce}`,
+            algorithm: HashAlgorithm.sha_512
+        });
+        return await kdf_recursiveSaltWrap({
+            masterSecret: this.config.ssoServerKdfSecret,
+            salt,
+            rounds: 1000,
+            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(
+        providerKey: string,
+        userNonce: string,
+    ): Promise<KeystoneChallengePool> {
+        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 = createStandardPoolConfig({
+            id: POOL_ID_CUSTODIAN_MANAGE,
+            salt: poolSaltShort
+        });
+        config.allowedVerbs = [KEYSTONE_VERB_MANAGE, KEYSTONE_VERB_REVOKE];
+
+        const strategy = KeystoneStrategyFactory.create({ config });
+        const poolSecret = await strategy.derivePoolSecret({ masterSecret: custodianSecret });
+        const challenges: { [id: string]: any } = {};
+        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: POOL_ID_CUSTODIAN_MANAGE,
+            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: string): SsoProviderClientConfig[] {
+        const configs: SsoProviderClientConfig[] = [];
+        
+        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;
+    }
+}