@ibgib/node-gib 0.0.14 → 0.0.17

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

@@ -0,0 +1,297 @@
+import { generateKeyPairSync, createSign } from 'node:crypto';
+import {
+    respecfully,
+    ifWeMight,
+    iReckon,
+    firstOfAll,
+    lastOfAll,
+    ifWe
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { SsoCustodianService } from './sso-custodian-service.mjs';
+import { SsoServerConfig } from './sso-types.mjs';
+import { POOL_ID_CUSTODIAN_MANAGE, POOL_ID_MANAGE } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+import { createStandardPoolConfig } from '@ibgib/core-gib/dist/keystone/keystone-config-builder.mjs';
+
+const maam = `[${import.meta.url}]`, sir = maam;
+
+await respecfully(sir, 'SsoCustodianService', async () => {
+    let mockPrivateKey: any;
+    let mockPublicKeyJwk: any;
+    let originalFetch: any;
+
+    firstOfAll(sir, async () => {
+        // Generate mock RSA key pair
+        const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+            modulusLength: 2048
+        });
+        mockPrivateKey = privateKey;
+
+        // Export public key as JWK
+        mockPublicKeyJwk = publicKey.export({ format: 'jwk' });
+        mockPublicKeyJwk.kid = 'mock-kid-123';
+        mockPublicKeyJwk.alg = 'RS256';
+        mockPublicKeyJwk.use = 'sig';
+
+        // Mock global fetch to return JWKS containing the mock public key
+        originalFetch = (globalThis as any).fetch;
+        (globalThis as any).fetch = async (url: string, options?: any) => {
+            if (url === 'https://www.googleapis.com/oauth2/v3/certs') {
+                return {
+                    ok: true,
+                    status: 200,
+                    json: async () => ({
+                        keys: [mockPublicKeyJwk]
+                    })
+                } as any;
+            }
+            return {
+                ok: false,
+                status: 404,
+                text: async () => 'Not Found'
+            } as any;
+        };
+    });
+
+    lastOfAll(sir, async () => {
+        // Restore global fetch
+        if (originalFetch) {
+            (globalThis as any).fetch = originalFetch;
+        }
+    });
+
+    await ifWe(sir, 'verify dynamic RSA RS256 JWT signature successfully', async () => {
+        const config: SsoServerConfig = {
+            ssoServerKdfSecret: 'mock-kdf-secret',
+            sessionSecret: 'mock-session-secret',
+            providers: {
+                google: {
+                    providerId: 'google',
+                    clientId: 'google-client-id-123',
+                    clientSecret: 'google-client-secret-123',
+                    tokenUrl: 'https://oauth2.googleapis.com/token',
+                    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+                    jwksUrl: 'https://www.googleapis.com/oauth2/v3/certs'
+                }
+            }
+        };
+
+        const service = new SsoCustodianService(config);
+
+        // 1. Build JWT Header & Payload
+        const header = { alg: 'RS256', kid: 'mock-kid-123', typ: 'JWT' };
+        const payload = {
+            sub: 'user-sub-999',
+            email: 'user@example.com',
+            name: 'John Doe',
+            aud: 'google-client-id-123',
+            iss: 'https://accounts.google.com',
+            exp: Math.floor(Date.now() / 1000) + 3600 // expires in 1 hour
+        };
+
+        const headerB64 = Buffer.from(JSON.stringify(header)).toString('base64url');
+        const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+        const data = `${headerB64}.${payloadB64}`;
+
+        // 2. Sign JWT using private key
+        const sign = createSign('RSA-SHA256');
+        sign.update(data);
+        const signatureB64 = sign.sign(mockPrivateKey, 'base64url');
+
+        const mockJwtToken = `${data}.${signatureB64}`;
+
+        // 3. Verify signature via service
+        const decodedPayload = await service.verifyJwt(mockJwtToken, config.providers.google!);
+
+        iReckon(sir, decodedPayload.sub).isGonnaBe('user-sub-999');
+        iReckon(sir, decodedPayload.email).isGonnaBe('user@example.com');
+        iReckon(sir, decodedPayload.name).isGonnaBe('John Doe');
+    });
+
+    await ifWe(sir, 'fail validation if JWT has invalid signature', async () => {
+        const config: SsoServerConfig = {
+            ssoServerKdfSecret: 'mock-kdf-secret',
+            sessionSecret: 'mock-session-secret',
+            providers: {
+                google: {
+                    providerId: 'google',
+                    clientId: 'google-client-id-123',
+                    clientSecret: 'google-client-secret-123',
+                    tokenUrl: 'https://oauth2.googleapis.com/token',
+                    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+                    jwksUrl: 'https://www.googleapis.com/oauth2/v3/certs'
+                }
+            }
+        };
+
+        const service = new SsoCustodianService(config);
+
+        const header = { alg: 'RS256', kid: 'mock-kid-123', typ: 'JWT' };
+        const payload = {
+            sub: 'user-sub-999',
+            aud: 'google-client-id-123',
+            exp: Math.floor(Date.now() / 1000) + 3600
+        };
+
+        const headerB64 = Buffer.from(JSON.stringify(header)).toString('base64url');
+        const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+        const data = `${headerB64}.${payloadB64}`;
+
+        // Create signature using a different/unregistered RSA key
+        const { privateKey: badPrivateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+        const sign = createSign('RSA-SHA256');
+        sign.update(data);
+        const badSignatureB64 = sign.sign(badPrivateKey, 'base64url');
+
+        const badJwtToken = `${data}.${badSignatureB64}`;
+
+        let verifyError: any;
+        try {
+            await service.verifyJwt(badJwtToken, config.providers.google!);
+        } catch (error: any) {
+            verifyError = error;
+        }
+
+        iReckon(sir, verifyError).not.isGonnaBeUndefined();
+        iReckon(sir, verifyError.message).includes('Cryptographic signature verification failed');
+    });
+
+    await ifWe(sir, 'derive server-delegate secret deterministically', async () => {
+        const config: SsoServerConfig = {
+            ssoServerKdfSecret: 'high-entropy-server-kdf-secret',
+            sessionSecret: 'session-secret-123',
+            providers: {}
+        };
+        const service = new SsoCustodianService(config);
+
+        const key = 'google:123456789';
+        const nonce1 = 'nonce-abc-123';
+        const nonce2 = 'nonce-def-456';
+
+        const secret1_a = await service.deriveServerDelegateSecret(key, nonce1);
+        const secret1_b = await service.deriveServerDelegateSecret(key, nonce1);
+        const secret2 = await service.deriveServerDelegateSecret(key, nonce2);
+
+        // Identical inputs must yield identical outputs
+        iReckon(sir, secret1_a).isGonnaBe(secret1_b);
+        // Different nonces must yield different outputs
+        iReckon(sir, secret1_a).not.isGonnaBe(secret2);
+        // Derived secrets must be string type with high entropy
+        iReckon(sir, typeof secret1_a).isGonnaBe('string');
+        iReckon(sir, secret1_a.length).isGonnaBe(128); // sha512 output in hex/base64 wrap
+    });
+
+    await ifWe(sir, 'create custodian challenge pool successfully', async () => {
+        const config: SsoServerConfig = {
+            ssoServerKdfSecret: 'high-entropy-server-kdf-secret',
+            sessionSecret: 'session-secret-123',
+            providers: {}
+        };
+        const service = new SsoCustodianService(config);
+
+        const key = 'google:123456789';
+        const nonce = 'nonce-abc-123';
+
+        // 1. Create a mock target keystone containing a 'manage' pool
+        const userManageConfig = createStandardPoolConfig({
+            id: POOL_ID_MANAGE,
+            salt: 'user-manage-salt'
+        });
+        userManageConfig.behavior.size = 12; // custom size for verification
+        const mockTargetKeystone = {
+            ib: 'keystone^some-tjp-addr',
+            gib: 'some-gib-value',
+            data: {
+                challengePools: [
+                    {
+                        id: 'manage',
+                        config: userManageConfig,
+                        challenges: { 'chal1': 'val1' }
+                    }
+                ],
+                n: 0
+            }
+        };
+
+        // 2. Mock metaspace and space calls
+        const mockSpace = {};
+        const mockMetaspace = {
+            getLatestAddr: async () => 'latest-keystone-addr',
+            get: async () => ({
+                success: true,
+                ibGibs: [mockTargetKeystone]
+            })
+        };
+
+        const custodianPool = await service.createCustodianChallengePool({
+            providerId: 'google',
+            providerKey: key,
+            userNonce: nonce,
+            keystoneAddr: 'some-tjp-addr',
+            metaspace: mockMetaspace as any,
+            space: mockSpace as any
+        });
+
+        iReckon(sir, custodianPool).not.isGonnaBeUndefined();
+        iReckon(sir, custodianPool.id).willEqual('custodian-manage-google');
+        iReckon(sir, custodianPool.isForeign).isGonnaBeTrue();
+        iReckon(sir, custodianPool.metadata?.providerKey).willEqual(key);
+
+        // Replicated behavior size from parent manage pool config
+        iReckon(sir, custodianPool.config.behavior.size).willEqual(userManageConfig.behavior.size);
+
+        // Structural validation of challenges
+        const challengesCount = Object.keys(custodianPool.challenges).length;
+        iReckon(sir, challengesCount).willEqual(custodianPool.config.behavior.size);
+    });
+
+    await ifWe(sir, 'revoke tokens successfully, making the correct http fetch calls', async () => {
+        const config: SsoServerConfig = {
+            ssoServerKdfSecret: 'high-entropy-server-kdf-secret',
+            sessionSecret: 'session-secret-123',
+            providers: {
+                google: {
+                    providerId: 'google',
+                    clientId: 'google-client-id-abc',
+                    clientSecret: 'google-client-secret-abc',
+                    tokenUrl: 'https://oauth2.googleapis.com/token',
+                    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo'
+                },
+                github: {
+                    providerId: 'github',
+                    clientId: 'github-client-id-xyz',
+                    clientSecret: 'github-client-secret-xyz',
+                    tokenUrl: 'https://github.com/login/oauth/access_token',
+                    userInfoUrl: 'https://api.github.com/user'
+                }
+            }
+        };
+        const service = new SsoCustodianService(config);
+
+        const originalFetch = globalThis.fetch;
+        let fetchCalls: { url: string, options: any }[] = [];
+        globalThis.fetch = (async (url: any, options: any) => {
+            fetchCalls.push({ url, options });
+            return {
+                ok: true,
+                status: 200,
+                text: async () => 'ok'
+            } as any;
+        }) as any;
+
+        try {
+            // Revoke Google token
+            await service.revokeToken('google', 'google-test-token-123');
+            iReckon(sir, fetchCalls.length).willEqual(1);
+            iReckon(sir, fetchCalls[0].url).includes('google-test-token-123');
+
+            // Revoke GitHub token
+            await service.revokeToken('github', 'github-test-token-456');
+            iReckon(sir, fetchCalls.length).willEqual(2);
+            iReckon(sir, fetchCalls[1].url).includes('/applications/github-client-id-xyz/grant');
+            iReckon(sir, fetchCalls[1].options.method).willEqual('DELETE');
+            iReckon(sir, fetchCalls[1].options.headers['Authorization']).includes('Basic');
+        } finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+});

package/src/identity/sso/sso-types.mts

@@ -0,0 +1,80 @@
+/**
+ * @module identity/sso/sso-types
+ *
+ * Core types and interfaces for extensible SSO (OAuth2) authentication on the server.
+ */
+
+export type SsoProviderId = 'google' | 'github';
+
+export interface SsoProviderClientConfig {
+    providerId: SsoProviderId;
+    clientId: string;
+    authUrl: string;
+    redirectUri: string;
+    scope: string;
+}
+
+export interface SsoProviderServerConfig {
+    providerId: SsoProviderId;
+    clientId: string;
+    clientSecret: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    jwksUrl?: string;
+}
+
+export interface SsoServerConfig {
+    /** Server's private KDF secret used to derive server-delegate keystones. */
+    ssoServerKdfSecret: string;
+    /** Server's private session encryption secret. */
+    sessionSecret: string;
+    /** Map of active OAuth2 providers. */
+    providers: Partial<Record<SsoProviderId, SsoProviderServerConfig>>;
+}
+
+export interface OAuthUserInfo {
+    /** Unique identity key combining provider and sub ID (e.g., `google:107632...`). */
+    providerKey: string;
+    providerId: SsoProviderId;
+    /** Unique user ID within the provider. */
+    sub: string;
+    email?: string;
+    name?: string;
+    picture?: string;
+}
+
+/**
+ * Single-turn authorization requirements object issued by the custodian server
+ * after successful passwordless SSO/Email authentication.
+ *
+ * Placed in `delegateKeystone.data.frameDetails.custodianReqs` when registering
+ * a client delegate keystone via passwordless onboarding.
+ */
+export interface CustodianRequirements {
+    /**
+     * The primary identity keystone TJP address (`ib^gib`) to which the delegate keystone will be registered.
+     * Prevents Man-In-The-Middle reuse of authorization requirements across different primary identities.
+     */
+    primaryTjpAddr: string;
+
+    /**
+     * High-entropy, single-turn random nonce generated by the server.
+     * Prevents replay attacks when registering delegate keystones.
+     */
+    nonce: string;
+
+    /**
+     * Single-turn authorization code computed by the server over `Omit<CustodianRequirements, 'authCode'>`.
+     */
+    authCode: string;
+
+    /**
+     * Expiration timestamp in epoch milliseconds after which this requirements object is invalid.
+     */
+    expiresAt: number;
+
+    /**
+     * Explicit list of permitted keystone verbs allowed for the delegate keystone (e.g., `['sync', 'connect']`).
+     */
+    allowedVerbs: string[];
+}

package/src/index.mts

@@ -37,5 +37,19 @@ export {
     EmailSenderAws,
     EmailReceiverAws,
     EmailSenderMock,
+    createMagicLinkToken,
+    verifyMagicLinkToken,
+    markNonceUsed,
+    isNonceUsed,
+    clearConsumedNonces,
+    DEFAULT_MAGIC_LINK_TTL_MS,
+    getMagicLinkSecret,
 } from './email/index.mjs';
 export type * from './email/email-types.mjs';
+
+// identity & SSO custodian infrastructure
+export * from './identity/sso/sso-custodian-service.mjs';
+export * from './identity/sso/sso-config-helper.mjs';
+export * from './identity/sso/custodian-auth-helpers.mjs';
+export type * from './identity/sso/sso-types.mjs';
+

package/src/serve-gib/handlers/api/email/email-outbound.handler.mts

@@ -33,15 +33,21 @@ export class EmailOutboundHandler extends ServeGibHandlerBase {
         if (options.sender) {
             this.sender = options.sender;
         } else {
-            const mode = process.env.EMAIL_MODE || 'mock';
+            const isProd = process.env.NODE_ENV === 'production';
+            const mode = (process.env.EMAIL_MODE || (isProd ? 'aws' : 'mock')).toLowerCase();
             if (mode === 'aws') {
                 this.sender = new EmailSenderAws({
                     accessKeyId: process.env.AWS_ACCESS_KEY_ID || '',
                     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '',
                     region: process.env.AWS_REGION || 'us-east-1',
                 });
-            } else {
+            } else if (mode === 'mock') {
+                if (isProd) {
+                    throw new Error('EMAIL_MODE=mock is prohibited when NODE_ENV=production. (E: 897a6b5c4d3e2f10987654321fedcba0)');
+                }
                 this.sender = new EmailSenderMock();
+            } else {
+                throw new Error(`Unsupported EMAIL_MODE '${mode}'. Must be 'aws' or 'mock'. (E: 987a6b5c4d3e2f10987654321fedcba1)`);
             }
         }
     }

package/src/serve-gib/handlers/api/email/email-verification-code.handler.mts

@@ -0,0 +1,163 @@
+/**
+ * @module serve-gib/handlers/api/email/email-verification-code
+ *
+ * Handler for POST /api/email/verification-code
+ */
+
+import { extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { EmailSenderAws } from '../../../../email/aws/email-sender-aws.mjs';
+// import { generateVerificationCode, getPendingTjpHash, savePendingCodeRecord, getPendingStagingDir, validateEmail } from '../../../../email/index.mjs';
+import { EmailSender, OutboundEmail } from '../../../../email/email-types.mjs';
+import { EmailSenderMock } from '../../../../email/mock/email-sender-mock.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { ServeGibHandlerBase } from '../../handler-base.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { generateVerificationCode, getPendingStagingDir, getPendingTjpHash, savePendingCodeRecord, savePendingStagingKeystone } from '../../../../email/verify/email-verify-helpers.mjs';
+import { validateEmail } from '../../../../email/email-helpers.mjs';
+import { normalizeEmail } from '../../../identity-index/identity-index-helpers.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+export interface EmailMagicLinkHandlerOptions {
+    sender?: EmailSender;
+}
+
+export interface EmailMagicLinkRequestBody {
+    email: string;
+    primaryTjpAddr?: string;
+    keystone?: any;
+}
+
+/**
+ * POST /api/email/verification-code
+ * Generates a 6-digit verification code, saves it to pending staging, and dispatches email.
+ */
+export class EmailVerificationCodeHandler extends ServeGibHandlerBase {
+    protected override lc = `[${EmailVerificationCodeHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.EMAIL_VERIFICATION_CODE;
+
+    private sender: EmailSender;
+
+    constructor(options: EmailMagicLinkHandlerOptions = {}) {
+        super();
+
+        if (options.sender) {
+            this.sender = options.sender;
+        } else {
+            const isProd = process.env.NODE_ENV === 'production';
+            const mode = (process.env.EMAIL_MODE || (isProd ? 'aws' : 'mock')).toLowerCase();
+            if (mode === 'aws') {
+                this.sender = new EmailSenderAws({
+                    accessKeyId: process.env.AWS_ACCESS_KEY_ID || '',
+                    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '',
+                    region: process.env.AWS_REGION || 'us-east-1',
+                });
+            } else if (mode === 'mock') {
+                if (isProd) {
+                    throw new Error('EMAIL_MODE=mock is prohibited when NODE_ENV=production. (E: 897a6b5c4d3e2f10987654321fedcba0)');
+                }
+                this.sender = new EmailSenderMock();
+            } else {
+                throw new Error(`Unsupported EMAIL_MODE '${mode}'. Must be 'aws' or 'mock'. (E: 987a6b5c4d3e2f10987654321fedcba1)`);
+            }
+        }
+    }
+
+    protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        const timestampUUID = `${lc}[${(await getUUID()).substring(0, 8)}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: f123456789abcdef0123456789a0001)`); }
+            if (logalot) { console.time(timestampUUID); }
+
+            if (reqCtx.method !== 'POST') {
+                return this.error(405, 'Method Not Allowed');
+            }
+
+            if (!reqCtx.body) {
+                return this.error(400, 'Request body is empty (E: c1d2e3f4a5b67890123456789abcdef0)');
+            }
+
+            let body: EmailMagicLinkRequestBody;
+            try {
+                body = JSON.parse(reqCtx.body);
+            } catch {
+                return this.error(400, 'Request body must be valid JSON (E: d2e3f4a5b67890123456789abcdef01)');
+            }
+
+            if (logalot) { console.timeLog(timestampUUID, 'parse complete'); }
+
+            const { email, primaryTjpAddr } = body;
+
+            if (!email || !validateEmail(email)) {
+                return this.error(400, 'Invalid email address format (E: e3f4a5b67890123456789abcdef012)');
+            }
+
+            const normEmail = normalizeEmail(email);
+            const effectivePrimaryTjpAddr = primaryTjpAddr || `pending:${normEmail}`;
+            const tjpHash = await getPendingTjpHash(effectivePrimaryTjpAddr);
+
+            const code = generateVerificationCode();
+            if (reqCtx.dataDir && tjpHash) {
+                let info = await getPendingStagingDir({ dataDir: reqCtx.dataDir, tjpHash });
+                if (!info) {
+                    // Create pending staging directory for this email if not yet present
+                    await savePendingStagingKeystone({
+                        dataDir: reqCtx.dataDir,
+                        primaryTjpAddr: effectivePrimaryTjpAddr,
+                        emails: [normEmail],
+                    });
+                    info = await getPendingStagingDir({ dataDir: reqCtx.dataDir, tjpHash });
+                }
+
+                if (info) {
+                    await savePendingCodeRecord({ pendingDir: info.pendingDir, code });
+                    if (logalot) { console.timeLog(timestampUUID, 'code record saved to pending staging'); }
+                } else {
+                    console.warn(`${lc} Failed to create or access pending staging directory for tjpHash ${tjpHash}`);
+                }
+            }
+
+            const outboundEmail: OutboundEmail = {
+                from: process.env.AWS_SES_FROM_EMAIL || 'noreply@ibgib.com',
+                to: [email],
+                subject: 'Verify your Ibgib Identity Email',
+                textBody: `Hello,\n\nYour 6-digit verification code for your Ibgib identity is:\n\n${code}\n\nThis code will expire in 15 minutes.\n\nIf you did not request this, please ignore this email.`,
+                htmlBody: `<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; border: 1px solid #e0e0e0; border-radius: 8px;">
+<h2>Verify your Ibgib Identity Email</h2>
+<p>Your 6-digit verification code is:</p>
+<h1 style="font-family: monospace; font-size: 36px; letter-spacing: 6px; color: #4f46e5; margin: 24px 0;">${code}</h1>
+<p style="font-size: 12px; color: #999;">This code will expire in 15 minutes.</p>
+</div>`,
+            };
+
+            const sendResult = await this.sender.sendEmail(outboundEmail);
+            if (logalot) { console.timeLog(timestampUUID, 'email send complete'); }
+
+            if (sendResult.success) {
+                console.log(`${lc} Verification code dispatched for ${email} -> ${primaryTjpAddr} msgId: ${sendResult.messageId} (I: a5b67890123456789abcdef012345678)`);
+                const isProd = process.env.NODE_ENV === 'production';
+                const mode = (process.env.EMAIL_MODE || (isProd ? 'aws' : 'mock')).toLowerCase();
+                if (mode === 'mock' || !isProd) {
+                    console.log(`${lc} ✉️ [EmailSenderMock] Verification Code for ${email}: ${code} (I: c123456789abcdef0123456789abcdef)`);
+                }
+                return this.ok({ success: true, message: 'Verification code dispatched successfully.' });
+            } else {
+                console.error(`${lc} Failed to send magic link email: ${sendResult.error} (E: 5b67890123456789abcdef0123456789)`);
+                return this.error(sendResult.statusCode || 500, sendResult.error || 'Failed to send magic link email');
+            }
+
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} Magic link dispatch error: ${emsg} (E: 67890123456789abcdef0123456789a)`);
+            return this.error(500, `Magic link dispatch error: ${emsg}`);
+        } finally {
+            if (logalot) {
+                console.log(`${lc} complete.`);
+                console.timeEnd(timestampUUID);
+            }
+        }
+    }
+}