@ibgib/node-gib 0.0.13 → 0.0.15

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

@@ -0,0 +1,566 @@
+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 { KeystoneChallengePool, KeystonePoolConfig } from '@ibgib/core-gib/dist/keystone/keystone-types.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';
+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';
+
+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)`);
+        }
+
+        if (payload.email && payload.email_verified !== true && (payload.email_verified as any) !== '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).
+     */
+    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);
+        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: any[] = await emailsRes.json();
+                    const primaryVerified = emailsList.find((e: any) => e.verified && e.primary) || emailsList.find((e: any) => 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).
+     */
+    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({
+        providerId,
+        providerKey,
+        userNonce,
+        keystoneAddr,
+        metaspace,
+        space,
+    }: {
+        providerId: string;
+        providerKey: string;
+        userNonce: string;
+        keystoneAddr: string;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneChallengePool> {
+        // 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: KeystonePoolConfig = {
+            ...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: { [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: 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: 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;
+    }
+
+    /**
+     * Revokes an active OAuth access or refresh token with the provider.
+     * Keeps token revocation logic DRY and centralized.
+     */
+    async revokeToken(providerId: SsoProviderId, token: string): Promise<void> {
+        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)}`);
+        }
+    }
+}