fraim 2.0.297 → 2.0.298

package/dist/src/core/handoff-contracts.js

@@ -152,18 +152,39 @@ function validateNextJobRecommendations(value) {
         return ['evidence.nextJobRecommendations must be an array'];
     }
     const errors = [];
+    if (value.length > 3) {
+        errors.push('evidence.nextJobRecommendations must contain at most 3 entries');
+    }
     value.forEach((entry, i) => {
         if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
             errors.push(`evidence.nextJobRecommendations[${i}] must be an object`);
             return;
         }
         const rec = entry;
+        if ('jobName' in rec && !('jobId' in rec)) {
+            errors.push(`evidence.nextJobRecommendations[${i}] uses jobName, but runnable recommendations must use jobId. Use jobId, not jobName.`);
+        }
         if (typeof rec.jobId !== 'string' || !rec.jobId.trim()) {
             errors.push(`evidence.nextJobRecommendations[${i}].jobId must be a non-empty string`);
         }
         if (typeof rec.label !== 'string' || !rec.label.trim()) {
             errors.push(`evidence.nextJobRecommendations[${i}].label must be a non-empty string`);
         }
+        if (typeof rec.label === 'string' && rec.label.length > 60) {
+            errors.push(`evidence.nextJobRecommendations[${i}].label must be 60 characters or fewer`);
+        }
+        if (rec.reason !== undefined && typeof rec.reason !== 'string') {
+            errors.push(`evidence.nextJobRecommendations[${i}].reason must be a string when present`);
+        }
+        if (typeof rec.reason === 'string' && rec.reason.length > 200) {
+            errors.push(`evidence.nextJobRecommendations[${i}].reason must be 200 characters or fewer`);
+        }
+        if (rec.contextSummary !== undefined && typeof rec.contextSummary !== 'string') {
+            errors.push(`evidence.nextJobRecommendations[${i}].contextSummary must be a string when present`);
+        }
+        if (typeof rec.contextSummary === 'string' && rec.contextSummary.length > 300) {
+            errors.push(`evidence.nextJobRecommendations[${i}].contextSummary must be 300 characters or fewer`);
+        }
     });
     return errors.length > 0 ? errors : null;
 }

package/dist/src/fraim/db-service.js

@@ -172,6 +172,8 @@ class FraimDbService {
         this.orgAuditCollection = this.db.collection('fraim_org_audit');
         // Issue #1345 — job execution modes (Coached/Trusted).
         this.jobExecutionModesCollection = this.db.collection('fraim_job_execution_modes');
+        // Issue #1431 — per-user referral codes.
+        this.referralCodesCollection = this.db.collection('fraim_referral_codes');
     }
     async initializeIndexes() {
         if (!this.db)
@@ -252,6 +254,9 @@ class FraimDbService {
         await this.auditLogCollection.createIndex({ sequence: 1 }).catch(() => { });
         await this.auditLogCollection.createIndex({ userId: 1, ts: -1 }).catch(() => { });
         await this.auditLogCollection.createIndex({ ts: -1 }).catch(() => { });
+        // Issue #1431 — referral codes: one code per user, globally unique codes.
+        await this.referralCodesCollection.createIndex({ userId: 1 }, { unique: true }).catch(() => { });
+        await this.referralCodesCollection.createIndex({ code: 1 }, { unique: true }).catch(() => { });
     }
     async createSession(session) {
         if (!this.sessionsCollection)
@@ -613,6 +618,65 @@ class FraimDbService {
             throw new Error('DB not connected');
         return await this.signupsCollection.findOne({ email });
     }
+    async setSignupAttribution(email, data) {
+        if (!this.signupsCollection)
+            throw new Error('DB not connected');
+        const now = new Date();
+        await this.signupsCollection.updateOne({ email }, {
+            $setOnInsert: {
+                email,
+                name: '',
+                company: '',
+                source: data.source,
+                timestamp: now,
+                ipAddress: data.ipAddress,
+                userAgent: data.userAgent,
+                ...(data.referrerName ? { referrerName: data.referrerName } : {}),
+                ...(data.referralCodeUsed ? { referralCodeUsed: data.referralCodeUsed } : {}),
+            },
+        }, { upsert: true });
+    }
+    generateReferralCodeString() {
+        const crypto = require('crypto');
+        const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+        const bytes = crypto.randomBytes(12);
+        return Array.from(bytes).map((b) => ALPHABET[b % ALPHABET.length]).join('');
+    }
+    async getReferralCode(userId) {
+        if (!this.referralCodesCollection)
+            throw new Error('DB not connected');
+        return await this.referralCodesCollection.findOne({ userId });
+    }
+    async getOrCreateReferralCode(userId) {
+        if (!this.referralCodesCollection)
+            throw new Error('DB not connected');
+        const existing = await this.referralCodesCollection.findOne({ userId });
+        if (existing)
+            return existing.code;
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const code = this.generateReferralCodeString();
+            try {
+                await this.referralCodesCollection.insertOne({ userId, code, createdAt: new Date() });
+                return code;
+            }
+            catch (err) {
+                if (err?.code === 11000) {
+                    const row = await this.referralCodesCollection.findOne({ userId });
+                    if (row)
+                        return row.code;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw new Error('Failed to generate unique referral code after retries');
+    }
+    async validateReferralCode(code) {
+        if (!this.referralCodesCollection)
+            throw new Error('DB not connected');
+        const exists = await this.referralCodesCollection.findOne({ code });
+        return exists !== null;
+    }
     /** Get existing API key by userId (email for self-serve) */
     async getApiKeyByUserId(userId, activeOnly = true) {
         if (!this.db)

package/dist/src/local-mcp-server/stdio-server.js

@@ -53,6 +53,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FraimLocalMCPServer = exports.FraimTemplateEngine = void 0;
 exports.parseExecutionModeFromResponse = parseExecutionModeFromResponse;
+exports.buildExecutionModeForwardUrl = buildExecutionModeForwardUrl;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
@@ -450,6 +451,19 @@ function parseExecutionModeFromResponse(text) {
         return null;
     }
 }
+// Issue #1443: the Hub's run registry is keyed by the host CLI's own session id
+// (run.sessionId, discovered from host stdout well after spawn — see
+// applyRunHostSessionSignal in ai-hub/server.ts), which has no relationship to the
+// FRAIM/MCP session id this proxy carries on every tool call. A lookup by the latter
+// never matches. FRAIM_HUB_RUN_ID is stamped into this process's env at spawn time
+// (AiHubServer.withHubRunIdEnv) specifically so this forward can target the run
+// directly; fall back to the (unreliable) session-based route only when the Hub that
+// spawned this process predates that fix.
+function buildExecutionModeForwardUrl(hubBase, hubRunId, requestSessionId) {
+    return hubRunId
+        ? `${hubBase}/api/ai-hub/runs/${encodeURIComponent(hubRunId)}/execution-mode`
+        : `${hubBase}/api/ai-hub/runs/by-session/${encodeURIComponent(requestSessionId)}/execution-mode`;
+}
 class FraimLocalMCPServer {
     constructor(writer) {
         this.config = null;
@@ -1427,7 +1441,8 @@ class FraimLocalMCPServer {
                 const hubBase = process.env.FRAIM_HUB_BASE_URL;
                 const em = parseExecutionModeFromResponse(responseText);
                 if (hubBase && em) {
-                    axios_1.default.post(`${hubBase}/api/ai-hub/runs/by-session/${encodeURIComponent(requestSessionId)}/execution-mode`, em, { headers: { 'Content-Type': 'application/json' } }).catch((err) => {
+                    const forwardUrl = buildExecutionModeForwardUrl(hubBase, process.env.FRAIM_HUB_RUN_ID, requestSessionId);
+                    axios_1.default.post(forwardUrl, em, { headers: { 'Content-Type': 'application/json' } }).catch((err) => {
                         this.log(`[req:${requestId}] execution-mode forward failed: ${err instanceof Error ? err.message : String(err)}`);
                     });
                 }
@@ -1500,6 +1515,25 @@ class FraimLocalMCPServer {
             return null;
         }
     }
+    async validateNextJobRecommendationJobIds(value, mentor) {
+        if (!Array.isArray(value))
+            return [];
+        const errors = [];
+        for (let i = 0; i < value.length; i++) {
+            const entry = value[i];
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                continue;
+            const jobId = entry.jobId;
+            if (typeof jobId !== 'string' || !jobId.trim())
+                continue;
+            const normalizedJobId = jobId.trim();
+            const job = await mentor.getJobOverview(normalizedJobId);
+            if (!job) {
+                errors.push(`evidence.nextJobRecommendations[${i}].jobId must reference a known FRAIM job (got "${normalizedJobId}")`);
+            }
+        }
+        return errors;
+    }
     async finalizeLocalToolTextResponse(request, requestSessionId, requestId, text) {
         const response = {
             jsonrpc: '2.0',
@@ -2255,6 +2289,7 @@ class FraimLocalMCPServer {
                         findings: args.findings,
                         phases: handoffPhaseMap,
                     });
+                    handoffErrors.push(...await this.validateNextJobRecommendationJobIds(args.evidence?.nextJobRecommendations, mentor));
                     if (handoffErrors.length > 0) {
                         const missingField = handoffErrors[0].includes('reviewHandoff') ? 'reviewHandoff'
                             : handoffErrors[0].includes('nextJobRecommendations') ? 'nextJobRecommendations'

package/dist/src/middleware/auth.js

@@ -38,7 +38,7 @@ class AuthMiddleware {
                 res.setHeader('WWW-Authenticate', `Bearer resource_metadata="${mcpResourceMetadataUrl}"`);
             }
         };
-        const publicPrefixes = ['/admin', '/dashboard', '/health', '/pricing', '/fraim-brain', '/installers', '/api/signup', '/api/sales', '/api/request-access', '/api/installer-key', '/api/installer-download', '/api/installer-availability', '/api/payment/bypass', '/api/pricing', '/api/personas/catalog', '/api/ai-hub/ui/releases', '/ai-hub-remote', '/auth', '/portfolio'];
+        const publicPrefixes = ['/admin', '/dashboard', '/health', '/pricing', '/fraim-brain', '/installers', '/api/signup', '/api/sales', '/api/request-access', '/api/installer-key', '/api/installer-download', '/api/installer-availability', '/api/payment/bypass', '/api/pricing', '/api/personas/catalog', '/api/ai-hub/ui/releases', '/ai-hub-remote', '/auth', '/portfolio', '/api/referral'];
         // Analytics dashboard is public, but API routes are protected
         const isAnalyticsPublic = p === '/analytics' || p === '/analytics/' || p.startsWith('/analytics/') && p.endsWith('.html');
         const isOAuthMetadataPublic = p === '/.well-known/oauth-authorization-server'

package/dist/src/routes/auth-routes.js

@@ -417,6 +417,45 @@ function registerProtectedAuthRoutes(app, deps) {
             return res.status(500).json({ ok: false });
         }
     });
+    app.get('/api/account/referral-code', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const record = await dbService.getReferralCode(apiKeyData.userId);
+            return res.status(200).json({ code: record?.code ?? null });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/referral-code GET error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.post('/api/account/referral-code', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const code = await dbService.getOrCreateReferralCode(apiKeyData.userId);
+            return res.status(200).json({ code });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/referral-code POST error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.get('/api/referral/validate', async (req, res) => {
+        try {
+            const code = String(req.query.code || '').trim().toUpperCase();
+            if (!code)
+                return res.status(200).json({ valid: false });
+            const valid = await dbService.validateReferralCode(code);
+            return res.status(200).json({ valid });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/referral/validate error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ valid: false });
+        }
+    });
     app.get('/api/account/activity', async (req, res) => {
         try {
             const apiKeyData = req.apiKeyData;

package/dist/src/routes/oauth-routes.js

@@ -118,7 +118,7 @@ function registerOAuthRoutes(app, deps) {
     });
     // Helper used by both providers to finalise authentication once we have a verified email.
     async function completeSignIn(req, res, params) {
-        const { verifiedEmail, provider, surface, redirectTo, intent, hubReturn } = params;
+        const { verifiedEmail, provider, surface, redirectTo, intent, hubReturn, referrerName, referralCode } = params;
         const lower = verifiedEmail.toLowerCase();
         const apiKeyData = await dbService.getApiKeyByUserId(lower, false);
         let apiKeyForHubReturn = apiKeyData?.key ?? '';
@@ -141,6 +141,17 @@ function registerOAuthRoutes(app, deps) {
         }
         if (!apiKeyData && intent === 'signup') {
             apiKeyForHubReturn = await (0, account_provisioning_1.ensureTrialApiKey)(dbService, lower);
+            // Issue #1431: write attribution once for new OAuth accounts. Uses upsert
+            // with $setOnInsert so repeat signups never overwrite original attribution.
+            if (referrerName || referralCode) {
+                await dbService.setSignupAttribution(lower, {
+                    source: `oauth:${provider}`,
+                    ...(referrerName ? { referrerName } : {}),
+                    ...(referralCode ? { referralCodeUsed: referralCode.toUpperCase() } : {}),
+                    userAgent: typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'] : undefined,
+                    ipAddress: (0, oauth_helpers_1.clientIpFromReq)(req),
+                }).catch(() => { });
+            }
         }
         const sessionId = (0, oauth_helpers_1.generateSessionId)();
         await dbService.createAuthSession({
@@ -174,6 +185,8 @@ function registerOAuthRoutes(app, deps) {
         const intent = pickIntent(req.query.intent);
         const redirectTo = (0, oauth_helpers_1.safeRedirectPath)(req.query.redirect_to, (0, oauth_helpers_1.defaultRedirectForSurface)(surface));
         const hubReturn = safeLoopbackHubReturn(req.query.hub_return);
+        const referrerName = typeof req.query.referrer_name === 'string' ? req.query.referrer_name.trim().slice(0, 200) : undefined;
+        const referralCode = typeof req.query.referral_code === 'string' ? req.query.referral_code.trim().toUpperCase().slice(0, 20) : undefined;
         try {
             const codeVerifier = (0, oauth_helpers_1.generatePkceVerifier)();
             const stateNonce = (0, oauth_helpers_1.generateStateNonce)();
@@ -187,6 +200,8 @@ function registerOAuthRoutes(app, deps) {
                 stateNonce,
                 redirectTo,
                 hubReturn,
+                ...(referrerName ? { referrerName } : {}),
+                ...(referralCode ? { referralCode } : {}),
             });
             (0, cookie_service_1.setOAuthPendingCookie)(res, pendingId);
             await (0, audit_log_1.auditLog)('OAUTH_START', { provider, surface, ip: (0, oauth_helpers_1.clientIpFromReq)(req), outcome: 'success' });
@@ -297,6 +312,8 @@ function registerOAuthRoutes(app, deps) {
                 redirectTo: pending.redirectTo,
                 intent: pickIntent(pending.intent),
                 hubReturn: pending.hubReturn,
+                referrerName: pending.referrerName,
+                referralCode: pending.referralCode,
             });
         }
         catch (err) {
@@ -391,6 +408,8 @@ function registerOAuthRoutes(app, deps) {
                 redirectTo: pending.redirectTo,
                 intent: pickIntent(pending.intent),
                 hubReturn: pending.hubReturn,
+                referrerName: pending.referrerName,
+                referralCode: pending.referralCode,
             });
         }
         catch (err) {

package/dist/src/services/admin-service.js

@@ -130,7 +130,7 @@ class AdminService {
      * Security: prevents unauthorized access by requiring email ownership verification.
      */
     async requestAccess(body, req) {
-        const { email, name, company, useCase } = body;
+        const { email, name, company, useCase, referrerName, referralCode } = body;
         // Issue #691: signup is now email + verification code only. Name/company
         // are optional lead-capture fields (createWebsiteSignup below already
         // tolerates missing values); the trial key itself never required them.
@@ -150,11 +150,14 @@ class AdminService {
                 source: 'request-access',
                 timestamp: new Date(),
                 ipAddress,
-                userAgent
+                userAgent,
+                ...(referrerName ? { referrerName: referrerName.trim() } : {}),
+                ...(referralCode ? { referralCodeUsed: referralCode.trim().toUpperCase() } : {}),
             });
         }
         catch {
             // Ignore duplicate or other signup errors; email verification still proceeds.
+            // Attribution write-once: duplicate emails silently fail, preserving first attribution.
         }
         const verificationToken = (0, crypto_1.randomBytes)(32).toString('hex');
         const verificationCode = (0, email_code_1.generateEmailCode)();
@@ -166,7 +169,9 @@ class AdminService {
             verified: false,
             expiresAt,
             createdAt: new Date(),
-            usedAt: null
+            usedAt: null,
+            ...(referrerName ? { referrerName: referrerName.trim() } : {}),
+            ...(referralCode ? { referralCode: referralCode.trim().toUpperCase() } : {}),
         });
         const emailService = new email_service_1.EmailService();
         const baseUrl = process.env.BASE_URL || 'https://fraimworks.ai';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.297",
+  "version": "2.0.298",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {