@ibgib/node-gib 0.0.9 → 0.0.13

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

@@ -0,0 +1,23 @@
+import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
+import { ParamsWithDomain, RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+interface LinkParams extends ParamsWithDomain {
+    parentTjpAddr: 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 declare class SsoLinkHandler extends ServeGibHandlerWithMetaspaceBase<LinkParams, any> {
+    protected lc: string;
+    protected method: ServeGibHttpMethod;
+    protected regex: RegExp;
+    protected parseParamsImpl(reqCtx: RequestContext<LinkParams, any>): Promise<LinkParams | undefined>;
+    protected validateQueryParams({ queryParams }: {
+        queryParams: any;
+    }): Promise<string[]>;
+    protected handleRouteImpl(reqCtx: RequestContext<LinkParams>): Promise<ResponseResult | undefined>;
+}
+export {};
+//# sourceMappingURL=sso-link.handler.d.mts.map

package/dist/serve-gib/handlers/api/keystone/sso-link.handler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-link.handler.d.mts","sourceRoot":"","sources":["../../../../../src/serve-gib/handlers/api/keystone/sso-link.handler.mts"],"names":[],"mappings":"AASA,OAAO,EAAE,gCAAgC,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAa1G,UAAU,UAAW,SAAQ,gBAAgB;IACzC,aAAa,EAAE,MAAM,CAAC;CACzB;AAUD;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,gCAAgC,CAAC,UAAU,EAAE,GAAG,CAAC;IACjF,UAAmB,EAAE,EAAE,MAAM,CAA8B;IAC3D,UAAmB,MAAM,EAAE,kBAAkB,CAAU;IACvD,UAAmB,KAAK,SAAsC;IAE9D,UAAyB,eAAe,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAajH;IAED,UAAyB,mBAAmB,CAAC,EAAE,WAAW,EAAE,EAAE;QAAE,WAAW,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAErG;IAED,UAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAwEvG;CACJ"}

package/dist/serve-gib/handlers/api/keystone/sso-link.handler.mjs

@@ -0,0 +1,118 @@
+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 { 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';
+const logalot = GLOBAL_LOG_A_LOT || true;
+let custodian;
+function getCustodian() {
+    if (!custodian) {
+        const config = loadSsoServerConfig();
+        custodian = new SsoCustodianService(config);
+    }
+    return custodian;
+}
+/**
+ * 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 {
+    lc = `[${SsoLinkHandler.name}]`;
+    method = 'POST';
+    regex = API_PATH_REGEXES.IDENTITY_SSO_LINK;
+    async parseParamsImpl(reqCtx) {
+        let parsed;
+        try {
+            parsed = JSON.parse(reqCtx.body);
+        }
+        catch {
+            return undefined;
+        }
+        const parentTjpAddr = parsed?.parentTjpAddr;
+        if (!parentTjpAddr) {
+            return undefined;
+        }
+        return {
+            parentTjpAddr,
+            domainInfo: this.getDomainInfo({ domainAddr: parentTjpAddr })
+        };
+    }
+    async validateQueryParams({ queryParams }) {
+        return [];
+    }
+    async handleRouteImpl(reqCtx) {
+        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;
+            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.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=sso-link.handler.mjs.map

package/dist/serve-gib/handlers/api/keystone/sso-link.handler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-link.handler.mjs","sourceRoot":"","sources":["../../../../../src/serve-gib/handlers/api/keystone/sso-link.handler.mts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,24 @@
+import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
+import { ParamsWithDomain, RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+interface LoginParams extends ParamsWithDomain {
+    parentTjpAddr: 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 declare class SsoLoginHandler extends ServeGibHandlerWithMetaspaceBase<LoginParams, any> {
+    protected lc: string;
+    protected method: ServeGibHttpMethod;
+    protected regex: RegExp;
+    protected parseParamsImpl(reqCtx: RequestContext<LoginParams, any>): Promise<LoginParams | undefined>;
+    protected validateQueryParams({ queryParams }: {
+        queryParams: any;
+    }): Promise<string[]>;
+    protected handleRouteImpl(reqCtx: RequestContext<LoginParams>): Promise<ResponseResult | undefined>;
+}
+export {};
+//# sourceMappingURL=sso-login.handler.d.mts.map

package/dist/serve-gib/handlers/api/keystone/sso-login.handler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-login.handler.d.mts","sourceRoot":"","sources":["../../../../../src/serve-gib/handlers/api/keystone/sso-login.handler.mts"],"names":[],"mappings":"AAUA,OAAO,EAAE,gCAAgC,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAsB1G,UAAU,WAAY,SAAQ,gBAAgB;IAC1C,aAAa,EAAE,MAAM,CAAC;CACzB;AAUD;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,gCAAgC,CAAC,WAAW,EAAE,GAAG,CAAC;IACnF,UAAmB,EAAE,EAAE,MAAM,CAA+B;IAC5D,UAAmB,MAAM,EAAE,kBAAkB,CAAU;IACvD,UAAmB,KAAK,SAAuC;IAE/D,UAAyB,eAAe,CAAC,MAAM,EAAE,cAAc,CAAC,WAAW,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAanH;IAED,UAAyB,mBAAmB,CAAC,EAAE,WAAW,EAAE,EAAE;QAAE,WAAW,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAErG;IAED,UAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CA+GxG;CACJ"}

package/dist/serve-gib/handlers/api/keystone/sso-login.handler.mjs

@@ -0,0 +1,160 @@
+import { createHmac } from 'node:crypto';
+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 { 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';
+const logalot = GLOBAL_LOG_A_LOT || true;
+let custodian;
+function getCustodian() {
+    if (!custodian) {
+        const config = loadSsoServerConfig();
+        custodian = new SsoCustodianService(config);
+    }
+    return custodian;
+}
+function signSessionToken(payload, secret) {
+    const header = { alg: 'HS256', typ: 'JWT' };
+    const headerB64 = Buffer.from(JSON.stringify(header)).toString('base64url');
+    const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const data = `${headerB64}.${payloadB64}`;
+    const signature = createHmac('sha256', secret).update(data).digest('base64url');
+    return `${data}.${signature}`;
+}
+/**
+ * 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 {
+    lc = `[${SsoLoginHandler.name}]`;
+    method = 'POST';
+    regex = API_PATH_REGEXES.IDENTITY_SSO_LOGIN;
+    async parseParamsImpl(reqCtx) {
+        let parsed;
+        try {
+            parsed = JSON.parse(reqCtx.body);
+        }
+        catch {
+            return undefined;
+        }
+        const parentTjpAddr = parsed?.parentTjpAddr;
+        if (!parentTjpAddr) {
+            return undefined;
+        }
+        return {
+            parentTjpAddr,
+            domainInfo: this.getDomainInfo({ domainAddr: parentTjpAddr })
+        };
+    }
+    async validateQueryParams({ queryParams }) {
+        return [];
+    }
+    async handleRouteImpl(reqCtx) {
+        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;
+            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) => 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.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.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=sso-login.handler.mjs.map

package/dist/serve-gib/handlers/api/keystone/sso-login.handler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-login.handler.mjs","sourceRoot":"","sources":["../../../../../src/serve-gib/handlers/api/keystone/sso-login.handler.mts"],"names":[],"mappings":"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"}

package/dist/serve-gib/handlers/error-handler.d.mts

@@ -0,0 +1,14 @@
+/**
+ * @module serve-gib/handlers/error-handler
+ *
+ * Default error handler for serve-gib.
+ */
+import { ServeGibHandlerBase } from './handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../types.mjs';
+export declare class ErrorHandler extends ServeGibHandlerBase {
+    protected lc: string;
+    protected method: ServeGibHttpMethod;
+    protected regex: RegExp;
+    handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined>;
+}
+//# sourceMappingURL=error-handler.d.mts.map

package/dist/serve-gib/handlers/error-handler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.mts","sourceRoot":"","sources":["../../../src/serve-gib/handlers/error-handler.mts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlF,qBAAa,YAAa,SAAQ,mBAAmB;IACjD,UAAmB,EAAE,EAAE,MAAM,CAA4B;IACzD,UAAmB,MAAM,EAAE,kBAAkB,CAAS;IACtD,UAAmB,KAAK,SAAQ;IAE1B,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAejF;CACJ"}

package/dist/serve-gib/handlers/error-handler.mjs

@@ -0,0 +1,35 @@
+/**
+ * @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';
+const logalot = GLOBAL_LOG_A_LOT;
+export class ErrorHandler extends ServeGibHandlerBase {
+    lc = `[${ErrorHandler.name}]`;
+    method = 'ALL';
+    regex = /.*/;
+    async handleRouteImpl(reqCtx) {
+        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) {
+            console.log(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+        finally {
+            if (logalot) {
+                console.log(`${lc} complete.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=error-handler.mjs.map

package/dist/serve-gib/handlers/error-handler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.mjs","sourceRoot":"","sources":["../../../src/serve-gib/handlers/error-handler.mts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAElF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD,MAAM,OAAO,GAAG,gBAAgB,CAAC;AAEjC,MAAM,OAAO,YAAa,SAAQ,mBAAmB;IAC9B,EAAE,GAAW,IAAI,YAAY,CAAC,IAAI,GAAG,CAAC;IACtC,MAAM,GAAuB,KAAK,CAAC;IACnC,KAAK,GAAG,IAAI,CAAC;IAEhC,KAAK,CAAC,eAAe,CAAC,MAAsB;QACxC,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC;QACtD,IAAI,CAAC;YACD,IAAI,OAAO,EAAE,CAAC;gBAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAAC,CAAC;YAElD,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,MAAM,CAAC;YAE7C,+BAA+B;YAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC/C,MAAM,KAAK,CAAC;QAChB,CAAC;gBAAS,CAAC;YACP,IAAI,OAAO,EAAE,CAAC;gBAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;YAAC,CAAC;QACpD,CAAC;IACL,CAAC;CACJ"}

package/dist/serve-gib/handlers/handler-base.d.mts

@@ -0,0 +1,129 @@
+/**
+ * @module serve-gib/handler
+ *
+ * Base class and utilities for serve-gib handlers.
+ */
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { DomainInfo, ParamsWithDomain, RequestContext, ResponseResult, ServeGibHandler } from '../types.mjs';
+import { ServeGibHttpMethod } from '../types.mjs';
+/**
+ * Abstract base class for serve-gib handlers.
+ * Provides a "pit of success" plumbing for routing, error handling, and parameter parsing.
+ *
+ * @template TParams Type for the parsed query parameters.
+ * @template TQueryParams Type for the parsed query parameters.
+ */
+export declare abstract class ServeGibHandlerBase<TParams = any, TQueryParams = any> implements ServeGibHandler<TParams, TQueryParams> {
+    protected lc: string;
+    /** The HTTP method this handler supports, or 'ALL' for catch-all. */
+    protected abstract method: ServeGibHttpMethod;
+    /** Regex for quick route matching via the default `canHandleRoute`. */
+    protected abstract regex: RegExp;
+    /**
+     * The main entry point processing incoming requests.
+     * Implements standard plumbing for matching, error handling, and param parsing.
+     */
+    handleRoute(reqCtx: RequestContext<TParams, TQueryParams>): Promise<ResponseResult | undefined>;
+    /**
+     * Concrete implementation of the handler logic.
+     *
+     * This is where the "meat" of the code goes, as there is some
+     * pre-processing in the parent wrapper.
+     */
+    protected abstract handleRouteImpl(reqCtx: RequestContext<TParams, TQueryParams>): Promise<ResponseResult | undefined>;
+    /**
+     * Extracts per-handler/route params from a request context.
+     *
+     * @see {@link RequestContext.params}
+     */
+    parseParams(reqCtx: RequestContext<TParams, TQueryParams>): Promise<TParams | undefined>;
+    /**
+     * Concrete implementation for extracting params from a path.
+     *
+     * @see {@link RequestContext.params}
+     */
+    protected parseParamsImpl(reqCtx: RequestContext<TParams, TQueryParams>): Promise<TParams | undefined>;
+    /**
+     * Hook to initialize concrete context, e.g., initializing a metaspace for the
+     * specific domain. The base implementation is a no-op.
+     */
+    protected initConcreteContext(reqCtx: RequestContext<TParams, TQueryParams>): Promise<void>;
+    /**
+     * Determines if this handler should attempt to handle the given request.
+     *
+     * Default implementation checks {@link method} and {@link regex} matching
+     * against the pathname. Override for more advanced logic for edge cases.
+     */
+    protected canHandleRoute(reqCtx: RequestContext<TParams, TQueryParams>): boolean;
+    /**
+     * Parses query parameters from the URL.
+     * Defaults to a basic key-value mapping of the URL search params.
+     */
+    protected parseQueryParams(reqCtx: RequestContext<TParams, TQueryParams>): Promise<TQueryParams | undefined>;
+    /**
+     * base class implementation is a no-op. override this in descendant class
+     * who expect the possibility of query params
+     * @returns array of validation errors, empty if valid
+     */
+    protected validateQueryParams({ queryParams }: {
+        queryParams: any;
+    }): Promise<string[]>;
+    /**
+     * Standard JSON success response.
+     */
+    protected ok(body: any, status?: number): ResponseResult;
+    /**
+     * Standard JSON error response.
+     */
+    protected error(status: number, message: string, details?: any): ResponseResult;
+    /**
+     * 404 Not Found response.
+     */
+    protected notFound(message?: string): ResponseResult;
+}
+/**
+ * Base class for handlers that have to first initialize a metaspace in order to
+ * process the incoming request.
+ *
+ * ## notes
+ *
+ * Some handlers, like those who do error handling or serving static files, do
+ * not need to initialize a metaspace or do any get/put of any ibgibs. So those
+ * don't need to descend from this class.
+ *
+ * But if the handler is one that has to put/get an ibgib, then a metaspace will
+ * need to be init. Those handlers should descend from this class.
+ */
+export declare abstract class ServeGibHandlerWithMetaspaceBase<TParams extends ParamsWithDomain = ParamsWithDomain, TQueryParams = any> extends ServeGibHandlerBase<TParams, TQueryParams> {
+    protected lc: string;
+    protected initConcreteContext(reqCtx: RequestContext<TParams, TQueryParams>): Promise<void>;
+    protected parseParamsImpl(reqCtx: RequestContext<TParams, TQueryParams>): Promise<TParams | undefined>;
+    protected validateQueryParams({ queryParams }: {
+        queryParams: any;
+    }): Promise<string[]>;
+    /**
+     * helper that should extract the "domain" (driven by the correctly scoped
+     * keystone) and set related props on the context.
+     */
+    protected initAndPopulateDomainContext(reqCtx: RequestContext<TParams, TQueryParams>): Promise<void>;
+    /**
+     * Helper to build the domain info from a {@link domainAddr}.
+     *
+     * ## usage
+     *
+     * Use this helper function once your concrete handler has parsed the
+     * domainAddr from the request url.
+     *
+     * For example, say the incoming path is /api/ibgib/:domainAddr/:ibgibAddr (GET)
+     * Then the concrete handler for this path would pull out domainAddr, call
+     * this function to build the domain info, and then put that domain info on
+     * the `reqCtx`.
+     */
+    protected getDomainInfo({ domainAddr, }: {
+        /**
+         * addr extracted from incoming url by concrete handler
+         */
+        domainAddr: IbGibAddr;
+    }): DomainInfo;
+}
+//# sourceMappingURL=handler-base.d.mts.map

package/dist/serve-gib/handlers/handler-base.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-base.d.mts","sourceRoot":"","sources":["../../../src/serve-gib/handlers/handler-base.mts"],"names":[],"mappings":"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"}