@ibgib/node-gib 0.0.10 → 0.0.14

package/src/serve-gib/handlers/api/keystone/sso-config.handler.mts

@@ -0,0 +1,66 @@
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { loadSsoServerConfig } from '@ibgib/web-gib/dist/identity/sso/sso-config-helper.mjs';
+import { SsoCustodianService } from '@ibgib/web-gib/dist/identity/sso/sso-custodian-service.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerBase } from '../../handler-base.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+let custodian: SsoCustodianService | undefined;
+function getCustodian(): SsoCustodianService {
+    if (!custodian) {
+        const config = loadSsoServerConfig();
+        custodian = new SsoCustodianService(config);
+    }
+    return custodian;
+}
+
+/**
+ * GET /api/identity/sso/config
+ *
+ * Retrieves safe public client configurations (client ID, scope, auth URLs) for active OAuth2 providers.
+ */
+export class SsoConfigHandler extends ServeGibHandlerBase<any, any> {
+    protected override lc: string = `[${SsoConfigHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'GET';
+    protected override regex = API_PATH_REGEXES.IDENTITY_SSO_CONFIG;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<any, any>): Promise<any> {
+        return undefined;
+    }
+
+    protected override async validateQueryParams({ queryParams }: { queryParams: any }): Promise<string[]> {
+        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).
+     */
+    protected async handleRouteImpl(reqCtx: RequestContext<any>): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            const service = getCustodian();
+            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(`${lc} Fetching SSO config failed: ${emsg}`);
+            return this.error(500, `SSO configuration retrieval failed: ${emsg}`);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/serve-gib/handlers/api/keystone/sso-link.handler.mts

@@ -0,0 +1,140 @@
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { loadSsoServerConfig } from '@ibgib/web-gib/dist/identity/sso/sso-config-helper.mjs';
+import { SsoCustodianService } from '@ibgib/web-gib/dist/identity/sso/sso-custodian-service.mjs';
+import { SsoProviderId } from '@ibgib/web-gib/dist/identity/sso/sso-types.mjs';
+import { isSsoProviderLinked } from '@ibgib/web-gib/dist/identity/sso/sso-helpers.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { ParamsWithDomain, RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+let custodian: SsoCustodianService | undefined;
+function getCustodian(): SsoCustodianService {
+    if (!custodian) {
+        const config = loadSsoServerConfig();
+        custodian = new SsoCustodianService(config);
+    }
+    return custodian;
+}
+
+interface LinkParams extends ParamsWithDomain {
+    parentTjpAddr: string;
+}
+
+interface LinkBody {
+    code: string;
+    providerId: SsoProviderId;
+    parentTjpAddr: string;
+    userNonce: string;
+    redirectUri: string;
+}
+
+/**
+ * POST /api/identity/sso/link
+ *
+ * Links an identity provider (Google, GitHub) to the user's sovereign parent identity.
+ * Generates the deterministic server-delegate keystone and registers it in the domain metaspace.
+ */
+export class SsoLinkHandler extends ServeGibHandlerWithMetaspaceBase<LinkParams, any> {
+    protected override lc: string = `[${SsoLinkHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.IDENTITY_SSO_LINK;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<LinkParams, any>): Promise<LinkParams | undefined> {
+        let parsed: any;
+        try {
+            parsed = JSON.parse(reqCtx.body);
+        } catch {
+            return undefined;
+        }
+        const parentTjpAddr = parsed?.parentTjpAddr;
+        if (!parentTjpAddr) { return undefined; }
+        return {
+            parentTjpAddr,
+            domainInfo: this.getDomainInfo({ domainAddr: parentTjpAddr })
+        };
+    }
+
+    protected override async validateQueryParams({ queryParams }: { queryParams: any }): Promise<string[]> {
+        return [];
+    }
+
+    protected async handleRouteImpl(reqCtx: RequestContext<LinkParams>): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (!reqCtx.params) {
+                return this.error(400, 'Invalid parameters: parentTjpAddr missing');
+            }
+            if (!reqCtx.metaspace) {
+                return this.error(500, 'Metaspace not initialized');
+            }
+
+            let parsed: LinkBody;
+            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');
+            }
+
+            // 0. Fetch target keystone and verify if already linked
+            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.`);
+            }
+
+            // 1. Authenticate with provider and retrieve user info
+            const service = getCustodian();
+            const userInfo = await service.getOAuthUserInfo(providerId, code, redirectUri);
+
+            // 2. Generate the custodian foreign challenge pool
+            const custodianPool = await service.createCustodianChallengePool({
+                providerId,
+                providerKey: userInfo.providerKey,
+                userNonce,
+                keystoneAddr: parentTjpAddr,
+                metaspace: reqCtx.metaspace,
+                space
+            });
+
+            console.log(`${lc} created custodian pool for: ${userInfo.providerKey}`);
+
+            return this.ok({
+                success: true,
+                custodianPool
+            }, 200);
+
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} Link failed: ${emsg}`);
+            return this.error(500, `Link failed: ${emsg}`);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/serve-gib/handlers/api/keystone/sso-login.handler.mts

@@ -0,0 +1,190 @@
+import { createHmac } from 'node:crypto';
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { loadSsoServerConfig } from '@ibgib/web-gib/dist/identity/sso/sso-config-helper.mjs';
+import { SsoCustodianService } from '@ibgib/web-gib/dist/identity/sso/sso-custodian-service.mjs';
+import { SsoProviderId } from '@ibgib/web-gib/dist/identity/sso/sso-types.mjs';
+import { POOL_ID_CUSTODIAN_MANAGE, KEYSTONE_VERB_MANAGE } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+import { KeystoneStrategyFactory } from '@ibgib/core-gib/dist/keystone/strategy/keystone-strategy-factory.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { ParamsWithDomain, RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+let custodian: SsoCustodianService | undefined;
+function getCustodian(): SsoCustodianService {
+    if (!custodian) {
+        const config = loadSsoServerConfig();
+        custodian = new SsoCustodianService(config);
+    }
+    return custodian;
+}
+
+function signSessionToken(payload: any, secret: string): string {
+    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}`;
+}
+
+interface LoginParams extends ParamsWithDomain {
+    parentTjpAddr: string;
+}
+
+interface LoginBody {
+    code: string;
+    providerId: SsoProviderId;
+    parentTjpAddr: string;
+    userNonce: string;
+    redirectUri: string;
+}
+
+/**
+ * POST /api/identity/sso/login
+ *
+ * Exposes login endpoint for SSO authentication. Verifies provider identity, asserts
+ * that the deterministic server-delegate keystone is registered in the parent keystone,
+ * and yields a secure HttpOnly session token.
+ */
+export class SsoLoginHandler extends ServeGibHandlerWithMetaspaceBase<LoginParams, any> {
+    protected override lc: string = `[${SsoLoginHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.IDENTITY_SSO_LOGIN;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<LoginParams, any>): Promise<LoginParams | undefined> {
+        let parsed: any;
+        try {
+            parsed = JSON.parse(reqCtx.body);
+        } catch {
+            return undefined;
+        }
+        const parentTjpAddr = parsed?.parentTjpAddr;
+        if (!parentTjpAddr) { return undefined; }
+        return {
+            parentTjpAddr,
+            domainInfo: this.getDomainInfo({ domainAddr: parentTjpAddr })
+        };
+    }
+
+    protected override async validateQueryParams({ queryParams }: { queryParams: any }): Promise<string[]> {
+        return [];
+    }
+
+    protected async handleRouteImpl(reqCtx: RequestContext<LoginParams>): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (!reqCtx.params) {
+                return this.error(400, 'Invalid parameters: parentTjpAddr missing');
+            }
+            if (!reqCtx.metaspace) {
+                return this.error(500, 'Metaspace not initialized');
+            }
+
+            let parsed: LoginBody;
+            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');
+            }
+
+            // 1. Authenticate with provider and retrieve user info
+            const service = getCustodian();
+            const userInfo = await service.getOAuthUserInfo(providerId, code, redirectUri);
+
+            // 2. Derive custodian secret using providerKey and userNonce
+            const custodianSecret = await service.deriveServerDelegateSecret(userInfo.providerKey, userNonce);
+
+            // 3. Fetch latest parent keystone from metaspace
+            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}`);
+            }
+
+            // 4. Resolve the custodian pool from the parent keystone using dynamic poolId
+            const targetPoolId = `custodian-manage-${providerId}`;
+            const custodianPool = parentKeystone.data?.challengePools?.find((p: any) => p.id === targetPoolId);
+            if (!custodianPool) {
+                return this.error(401, `Unauthorized: Custodian pool '${targetPoolId}' is not registered in the parent identity keystone.`);
+            }
+
+            // 5. Assert allowed verbs contain KEYSTONE_VERB_MANAGE
+            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.`);
+            }
+
+            // 6. Cryptographically verify the custodian secret against the pool's challenges
+            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 as any).hash) {
+                    return this.error(401, 'Unauthorized: Cryptographic verification of custodian pool challenges failed.');
+                }
+            }
+
+            // 7. Issue secure HttpOnly session cookie
+            const sessionPayload = {
+                parentTjpAddr,
+                providerKey: userInfo.providerKey,
+                exp: Math.floor(Date.now() / 1000) + 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(`${lc} 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(`${lc} Login failed: ${emsg}`);
+            return this.error(500, `Login failed: ${emsg}`);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/serve-gib/handlers/error-handler.mts

@@ -0,0 +1,36 @@
+/**
+ * @module serve-gib/handlers/error-handler
+ *
+ * Default error handler for serve-gib.
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../constants.mjs';
+import { ServeGibHandlerBase } from './handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+export class ErrorHandler extends ServeGibHandlerBase {
+    protected override lc: string = `[${ErrorHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'ALL';
+    protected override regex = /.*/;
+
+    async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            const { rawUrl, pathname, method, } = reqCtx;
+
+            // This is the fallback handler
+            return this.error(404, 'Not Found', { method, rawUrl, pathname });
+        } catch (error: any) {
+            console.log(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}