@ibgib/node-gib 0.0.13 → 0.0.15

package/dist/identity/sso/sso-config-helper.mjs

@@ -0,0 +1,42 @@
+/**
+ * Loads the SSO configuration from environment variables.
+ * Parses active OAuth2 providers dynamically based on their environment keys.
+ */
+export 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 = {};
+    // 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
+    };
+}
+//# sourceMappingURL=sso-config-helper.mjs.map

package/dist/identity/sso/sso-config-helper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-config-helper.mjs","sourceRoot":"","sources":["../../../src/identity/sso/sso-config-helper.mts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IAC/B,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IAC7D,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAEjD,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACX,0FAA0F,CAC7F,CAAC;IACN,CAAC;IACD,IAAI,CAAC,aAAa,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACX,2EAA2E,CAC9E,CAAC;IACN,CAAC;IAED,MAAM,SAAS,GAA4D,EAAE,CAAC;IAE9E,qCAAqC;IACrC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QACnE,SAAS,CAAC,MAAM,GAAG;YACf,UAAU,EAAE,QAAQ;YACpB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;YACtC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;YAC9C,QAAQ,EAAE,qCAAqC;YAC/C,WAAW,EAAE,kDAAkD;YAC/D,OAAO,EAAE,4CAA4C;SACxD,CAAC;IACN,CAAC;IAED,qCAAqC;IACrC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QACnE,SAAS,CAAC,MAAM,GAAG;YACf,UAAU,EAAE,QAAQ;YACpB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;YACtC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;YAC9C,QAAQ,EAAE,6CAA6C;YACvD,WAAW,EAAE,6BAA6B;SAC7C,CAAC;IACN,CAAC;IAED,OAAO;QACH,kBAAkB;QAClB,aAAa;QACb,SAAS;KACZ,CAAC;AACN,CAAC"}

package/dist/identity/sso/sso-custodian-service.d.mts

@@ -0,0 +1,139 @@
+import { KeystoneChallengePool } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { MetaspaceService } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { SsoServerConfig, SsoProviderId, OAuthUserInfo, SsoProviderServerConfig, SsoProviderClientConfig } from './sso-types.mjs';
+/**
+ * Server-side service for token exchange, JWT validation, and user profile normalization.
+ */
+export declare class SsoCustodianService {
+    private config;
+    private lc;
+    private jwksCache;
+    private jwksTtlMs;
+    /**
+     * @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: 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).
+     */
+    getOAuthUserInfo(providerId: SsoProviderId, code: string, redirectUri: string): Promise<OAuthUserInfo>;
+    /**
+     * 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).
+     */
+    verifyAndNormalizeGoogleToken(idToken: string): Promise<OAuthUserInfo>;
+    /**
+     * 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 exchangeCodeForTokens;
+    /**
+     * 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 fetchAndNormalizeGithubUser;
+    /**
+     * 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).
+     */
+    verifyJwt(token: string, providerConfig: SsoProviderServerConfig): Promise<any>;
+    /**
+     * 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 getJwksKeys;
+    /**
+     * 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).
+     */
+    deriveServerDelegateSecret(providerKey: string, userNonce: string): Promise<string>;
+    /**
+     * 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).
+     */
+    createCustodianChallengePool({ providerId, providerKey, userNonce, keystoneAddr, metaspace, space, }: {
+        providerId: string;
+        providerKey: string;
+        userNonce: string;
+        keystoneAddr: string;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneChallengePool>;
+    /**
+     * 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[];
+    /**
+     * Revokes an active OAuth access or refresh token with the provider.
+     * Keeps token revocation logic DRY and centralized.
+     */
+    revokeToken(providerId: SsoProviderId, token: string): Promise<void>;
+}
+//# sourceMappingURL=sso-custodian-service.d.mts.map

package/dist/identity/sso/sso-custodian-service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-custodian-service.d.mts","sourceRoot":"","sources":["../../../src/identity/sso/sso-custodian-service.mts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,EAAsB,MAAM,kDAAkD,CAAC;AAI7G,OAAO,EAAE,gBAAgB,EAAE,MAAM,kEAAkE,CAAC;AACpG,OAAO,EAAE,aAAa,EAAE,MAAM,sDAAsD,CAAC;AAErF,OAAO,EACH,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,uBAAuB,EACtE,uBAAuB,EAC1B,MAAM,iBAAiB,CAAC;AAgBzB;;GAEG;AACH,qBAAa,mBAAmB;IAYhB,OAAO,CAAC,MAAM;IAX1B,OAAO,CAAC,EAAE,CAAmC;IAG7C,OAAO,CAAC,SAAS,CAAwE;IACzF,OAAO,CAAC,SAAS,CAAuB;IAExC;;;;OAIG;IACH,YAAoB,MAAM,EAAE,eAAe,EAAK;IAEhD;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA4B3G;IAED;;;;;;;OAOG;IACG,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAmC3E;IAED;;;;;;;;;;;;;;OAcG;YACW,qBAAqB;IAoCnC;;;;;;;;;;OAUG;YACW,2BAA2B;IA4DzC;;;;;;;;;;OAUG;IACU,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,uBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC,CAqD3F;IAED;;;;;;OAMG;YACW,WAAW;IA8BzB;;;;;;;;;;;OAWG;IACG,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWxF;IAED;;;;;;;;;;;OAWG;IACG,4BAA4B,CAAC,EAC/B,UAAU,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,SAAS,EACT,KAAK,GACR,EAAE;QACC,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,gBAAgB,CAAC;QAC5B,KAAK,EAAE,aAAa,CAAC;KACxB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAuEjC;IAED;;;;;;OAMG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,EAAE,CAwB9D;IAED;;;OAGG;IACG,WAAW,CAAC,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCzE;CACJ"}

package/dist/identity/sso/sso-custodian-service.mjs

@@ -0,0 +1,471 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { hash, HashAlgorithm, extractErrorMsg } 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 { KEYSTONE_VERB_MANAGE, KEYSTONE_VERB_REVOKE, POOL_ID_MANAGE, KEYSTONE_POOL_ID_REGEXP } from '@ibgib/core-gib/dist/keystone/keystone-constants.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';
+/**
+ * Server-side service for token exchange, JWT validation, and user profile normalization.
+ */
+export class SsoCustodianService {
+    config;
+    lc = `[${SsoCustodianService.name}]`;
+    // In-memory cache for JSON Web Key Sets (JWKS) per provider
+    jwksCache = new Map();
+    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(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 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) {
+        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)`);
+        }
+        if (payload.email && payload.email_verified !== true && payload.email_verified !== 'true') {
+            throw new Error(`Google email is not verified: ${payload.email}. (E: v28900abfefd23e89cfb2f90)`);
+        }
+        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'
+        };
+        // 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).
+     */
+    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);
+        let email = rawUser.email || undefined;
+        // If email is missing or private, fetch /user/emails to extract primary verified email
+        if (!email) {
+            try {
+                const emailsRes = await fetch('https://api.github.com/user/emails', {
+                    headers: {
+                        'Authorization': `Bearer ${accessToken}`,
+                        'User-Agent': 'space-gib-auth-agent'
+                    }
+                });
+                if (emailsRes.ok) {
+                    const emailsList = await emailsRes.json();
+                    const primaryVerified = emailsList.find((e) => e.verified && e.primary) || emailsList.find((e) => e.verified);
+                    if (primaryVerified?.email) {
+                        email = primaryVerified.email;
+                    }
+                }
+            }
+            catch (err) {
+                console.warn(`[${this.fetchAndNormalizeGithubUser.name}] Could not fetch GitHub /user/emails fallback: ${extractErrorMsg(err)}`);
+            }
+        }
+        if (!email) {
+            throw new Error(`Your GitHub account does not have a verified primary email address. Please verify your primary email on GitHub and try again. (E: e28900abfefd23e89cfc3f01)`);
+        }
+        return {
+            providerKey: `github:${sub}`,
+            providerId: 'github',
+            sub,
+            email,
+            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).
+     */
+    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;
+        // 1. Decode header and select algorithm/key ID
+        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).');
+        }
+        // 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,
+            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).
+     */
+    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: 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({ providerId, providerKey, userNonce, keystoneAddr, metaspace, space, }) {
+        // 1. Fetch target keystone
+        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)`);
+        }
+        // 2. Locate native manage pool
+        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)`);
+        }
+        // 3. Dynamic poolId based on providerId with regex validation
+        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}`;
+        // 4. Derive delegate secrets
+        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);
+        // 5. Clone user's manage pool config, updating only ID, salt, and allowedVerbs
+        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 lc = `${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(`${lc} 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(`${lc} GitHub token revocation returned status ${res.status}: ${text}`);
+                }
+            }
+            else {
+                throw new Error(`Unsupported provider: ${providerId} (E: e28900abfefd23e89cf78f58)`);
+            }
+        }
+        catch (error) {
+            console.error(`${lc} Token revocation failed for provider ${providerId}: ${extractErrorMsg(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=sso-custodian-service.mjs.map