soulprint-network 0.2.1 → 0.2.3

package/dist/credentials/email.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Email OTP Credential Validator
+ *
+ * Flujo:
+ *  1. POST /credentials/email/start  { did, email }
+ *     → genera OTP de 6 dígitos, válido 10 min
+ *     → envía email via SMTP (nodemailer)
+ *     → retorna { sessionId }
+ *
+ *  2. POST /credentials/email/verify { sessionId, otp }
+ *     → si el OTP coincide → emite attestation "EmailVerified" sobre el DID
+ *     → retorna { credential: "EmailVerified", did }
+ *
+ * Configuración (env vars):
+ *  SMTP_HOST     — servidor SMTP (ej: smtp.gmail.com)
+ *  SMTP_PORT     — puerto (default 587)
+ *  SMTP_USER     — usuario SMTP
+ *  SMTP_PASS     — contraseña SMTP
+ *  SMTP_FROM     — remitente (default "noreply@soulprint.digital")
+ *
+ * En desarrollo sin SMTP configurado: usa Ethereal (catch-all fake SMTP)
+ * para testing — los emails no se envían pero son capturables.
+ */
+export declare function startEmailVerification(did: string, email: string): Promise<{
+    sessionId: string;
+    preview?: string;
+}>;
+export declare function verifyEmailOTP(sessionId: string, otp: string): {
+    ok: boolean;
+    did?: string;
+    email?: string;
+    reason?: string;
+};

package/dist/credentials/email.js

@@ -0,0 +1,110 @@
+/**
+ * Email OTP Credential Validator
+ *
+ * Flujo:
+ *  1. POST /credentials/email/start  { did, email }
+ *     → genera OTP de 6 dígitos, válido 10 min
+ *     → envía email via SMTP (nodemailer)
+ *     → retorna { sessionId }
+ *
+ *  2. POST /credentials/email/verify { sessionId, otp }
+ *     → si el OTP coincide → emite attestation "EmailVerified" sobre el DID
+ *     → retorna { credential: "EmailVerified", did }
+ *
+ * Configuración (env vars):
+ *  SMTP_HOST     — servidor SMTP (ej: smtp.gmail.com)
+ *  SMTP_PORT     — puerto (default 587)
+ *  SMTP_USER     — usuario SMTP
+ *  SMTP_PASS     — contraseña SMTP
+ *  SMTP_FROM     — remitente (default "noreply@soulprint.digital")
+ *
+ * En desarrollo sin SMTP configurado: usa Ethereal (catch-all fake SMTP)
+ * para testing — los emails no se envían pero son capturables.
+ */
+import nodemailer from "nodemailer";
+import { randomBytes, randomInt } from "node:crypto";
+// TTL de la sesión OTP (10 minutos)
+const OTP_TTL_MS = 10 * 60 * 1000;
+// Sessions en memoria (el nodo limpia las expiradas cada 5 min)
+const emailSessions = new Map();
+setInterval(() => {
+    const now = Date.now();
+    for (const [id, s] of emailSessions) {
+        if (s.expiresAt < now)
+            emailSessions.delete(id);
+    }
+}, 5 * 60_000).unref();
+// Transportador SMTP (lazy init)
+let transport = null;
+async function getTransport() {
+    if (transport)
+        return transport;
+    if (process.env.SMTP_HOST) {
+        transport = nodemailer.createTransport({
+            host: process.env.SMTP_HOST,
+            port: parseInt(process.env.SMTP_PORT ?? "587"),
+            secure: process.env.SMTP_PORT === "465",
+            auth: {
+                user: process.env.SMTP_USER,
+                pass: process.env.SMTP_PASS,
+            },
+        });
+    }
+    else {
+        // Dev: usa Ethereal (emails no se envían, se loguean)
+        const testAccount = await nodemailer.createTestAccount();
+        transport = nodemailer.createTransport({
+            host: "smtp.ethereal.email",
+            port: 587,
+            secure: false,
+            auth: { user: testAccount.user, pass: testAccount.pass },
+        });
+        console.log("[email-cred] Dev mode — usando Ethereal SMTP");
+    }
+    return transport;
+}
+export async function startEmailVerification(did, email) {
+    // Validar email básico
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        throw new Error("Invalid email address");
+    }
+    // Generar OTP de 6 dígitos con crypto.randomInt (CSPRNG)
+    const otp = randomInt(100000, 999999).toString();
+    const sessionId = randomBytes(16).toString("hex");
+    emailSessions.set(sessionId, {
+        did, email, otp,
+        expiresAt: Date.now() + OTP_TTL_MS,
+        attempts: 0,
+    });
+    const transporter = await getTransport();
+    const info = await transporter.sendMail({
+        from: process.env.SMTP_FROM ?? "noreply@soulprint.digital",
+        to: email,
+        subject: "Soulprint — Your verification code",
+        text: `Your Soulprint verification code is: ${otp}\n\nExpires in 10 minutes. Do not share this code.`,
+        html: `<p>Your Soulprint verification code is: <strong style="font-size:1.5em">${otp}</strong></p><p>Expires in 10 minutes. Do not share this code.</p>`,
+    });
+    const preview = nodemailer.getTestMessageUrl(info) || undefined;
+    if (preview)
+        console.log(`[email-cred] Preview: ${preview}`);
+    return { sessionId, preview };
+}
+export function verifyEmailOTP(sessionId, otp) {
+    const session = emailSessions.get(sessionId);
+    if (!session)
+        return { ok: false, reason: "Session not found or expired" };
+    if (Date.now() > session.expiresAt) {
+        emailSessions.delete(sessionId);
+        return { ok: false, reason: "OTP expired" };
+    }
+    session.attempts++;
+    if (session.attempts > 5) {
+        emailSessions.delete(sessionId);
+        return { ok: false, reason: "Too many attempts" };
+    }
+    if (otp.trim() !== session.otp)
+        return { ok: false, reason: "Invalid OTP" };
+    // OTP correcto — limpiar sesión y retornar
+    emailSessions.delete(sessionId);
+    return { ok: true, did: session.did, email: session.email };
+}

package/dist/credentials/github.d.ts

@@ -0,0 +1,44 @@
+/**
+ * GitHub OAuth Credential Validator — native fetch only, no extra deps
+ *
+ * Usa el flujo estándar OAuth 2.0 de GitHub (open source, bien documentado).
+ * No requiere librerías extra — solo fetch nativo (disponible en Node 18+).
+ *
+ * Flujo:
+ *  1. GET /credentials/github/start?did=<did>
+ *     → retorna { authUrl } — el cliente redirige al usuario a authUrl
+ *       authUrl = "https://github.com/login/oauth/authorize?..."
+ *
+ *  2. GitHub redirige a /credentials/github/callback?code=<code>&state=<state>
+ *     → intercambia code por access_token
+ *     → obtiene perfil del usuario (id, login, email)
+ *     → emite GitHubLinked credential
+ *     → retorna { credential: "GitHubLinked", did, githubLogin }
+ *
+ * Configuración (env vars):
+ *  GITHUB_CLIENT_ID      — GitHub OAuth App Client ID
+ *  GITHUB_CLIENT_SECRET  — GitHub OAuth App Client Secret
+ *  SOULPRINT_BASE_URL    — URL pública del nodo (para callback)
+ *                          ej: "https://my-validator.example.com"
+ *
+ * Crear OAuth App: https://github.com/settings/applications/new
+ *  - Homepage URL: tu dominio del nodo
+ *  - Callback URL: https://tu-nodo/credentials/github/callback
+ *
+ * Para desarrollo sin GitHub App configurada:
+ *  → el endpoint retorna instrucciones para crearla
+ */
+export declare function startGitHubOAuth(did: string): {
+    authUrl?: string;
+    state?: string;
+    error?: string;
+    setup?: string;
+};
+export declare function handleGitHubCallback(code: string, state: string): Promise<{
+    ok: boolean;
+    did?: string;
+    githubId?: number;
+    githubLogin?: string;
+    email?: string;
+    reason?: string;
+}>;

package/dist/credentials/github.js

@@ -0,0 +1,148 @@
+/**
+ * GitHub OAuth Credential Validator — native fetch only, no extra deps
+ *
+ * Usa el flujo estándar OAuth 2.0 de GitHub (open source, bien documentado).
+ * No requiere librerías extra — solo fetch nativo (disponible en Node 18+).
+ *
+ * Flujo:
+ *  1. GET /credentials/github/start?did=<did>
+ *     → retorna { authUrl } — el cliente redirige al usuario a authUrl
+ *       authUrl = "https://github.com/login/oauth/authorize?..."
+ *
+ *  2. GitHub redirige a /credentials/github/callback?code=<code>&state=<state>
+ *     → intercambia code por access_token
+ *     → obtiene perfil del usuario (id, login, email)
+ *     → emite GitHubLinked credential
+ *     → retorna { credential: "GitHubLinked", did, githubLogin }
+ *
+ * Configuración (env vars):
+ *  GITHUB_CLIENT_ID      — GitHub OAuth App Client ID
+ *  GITHUB_CLIENT_SECRET  — GitHub OAuth App Client Secret
+ *  SOULPRINT_BASE_URL    — URL pública del nodo (para callback)
+ *                          ej: "https://my-validator.example.com"
+ *
+ * Crear OAuth App: https://github.com/settings/applications/new
+ *  - Homepage URL: tu dominio del nodo
+ *  - Callback URL: https://tu-nodo/credentials/github/callback
+ *
+ * Para desarrollo sin GitHub App configurada:
+ *  → el endpoint retorna instrucciones para crearla
+ */
+import { randomBytes } from "node:crypto";
+const STATE_TTL_MS = 10 * 60 * 1000; // 10 minutos para completar OAuth
+const stateStore = new Map();
+setInterval(() => {
+    const now = Date.now();
+    for (const [s, v] of stateStore) {
+        if (v.expiresAt < now)
+            stateStore.delete(s);
+    }
+}, 5 * 60_000).unref();
+function getConfig() {
+    const clientId = process.env.GITHUB_CLIENT_ID;
+    const clientSecret = process.env.GITHUB_CLIENT_SECRET;
+    const baseUrl = process.env.SOULPRINT_BASE_URL ?? "http://localhost:4888";
+    return { clientId, clientSecret, baseUrl, configured: !!(clientId && clientSecret) };
+}
+export function startGitHubOAuth(did) {
+    const cfg = getConfig();
+    if (!cfg.configured) {
+        return {
+            error: "GitHub OAuth not configured on this validator node.",
+            setup: [
+                "To enable GitHubLinked verification:",
+                "1. Create a GitHub OAuth App at https://github.com/settings/applications/new",
+                "   - Homepage URL: your validator's public URL",
+                "   - Callback URL: <SOULPRINT_BASE_URL>/credentials/github/callback",
+                "2. Set env vars: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, SOULPRINT_BASE_URL",
+                "3. Restart the validator node",
+            ].join("\n"),
+        };
+    }
+    const state = randomBytes(16).toString("hex");
+    stateStore.set(state, { did, expiresAt: Date.now() + STATE_TTL_MS, used: false });
+    const params = new URLSearchParams({
+        client_id: cfg.clientId,
+        redirect_uri: `${cfg.baseUrl}/credentials/github/callback`,
+        scope: "read:user user:email",
+        state,
+    });
+    return {
+        authUrl: `https://github.com/login/oauth/authorize?${params}`,
+        state,
+    };
+}
+export async function handleGitHubCallback(code, state) {
+    const cfg = getConfig();
+    if (!cfg.configured)
+        return { ok: false, reason: "GitHub OAuth not configured" };
+    // Verificar state
+    const stored = stateStore.get(state);
+    if (!stored)
+        return { ok: false, reason: "Invalid or expired state" };
+    if (stored.used)
+        return { ok: false, reason: "State already used" };
+    if (Date.now() > stored.expiresAt) {
+        stateStore.delete(state);
+        return { ok: false, reason: "State expired" };
+    }
+    stored.used = true;
+    // Intercambiar code por access_token
+    const tokenRes = await fetch("https://github.com/login/oauth/access_token", {
+        method: "POST",
+        headers: {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            client_id: cfg.clientId,
+            client_secret: cfg.clientSecret,
+            code,
+            redirect_uri: `${cfg.baseUrl}/credentials/github/callback`,
+        }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!tokenRes.ok)
+        return { ok: false, reason: `GitHub token exchange failed: HTTP ${tokenRes.status}` };
+    const tokenData = await tokenRes.json();
+    if (tokenData.error)
+        return { ok: false, reason: `GitHub OAuth error: ${tokenData.error_description ?? tokenData.error}` };
+    const accessToken = tokenData.access_token;
+    // Obtener perfil del usuario
+    const userRes = await fetch("https://api.github.com/user", {
+        headers: {
+            "Authorization": `Bearer ${accessToken}`,
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "Soulprint-Validator/0.2.1",
+        },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!userRes.ok)
+        return { ok: false, reason: `GitHub user fetch failed: HTTP ${userRes.status}` };
+    const user = await userRes.json();
+    // Opcionalmente obtener email privado
+    let email;
+    try {
+        const emailRes = await fetch("https://api.github.com/user/emails", {
+            headers: {
+                "Authorization": `Bearer ${accessToken}`,
+                "Accept": "application/vnd.github+json",
+                "User-Agent": "Soulprint-Validator/0.2.1",
+            },
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (emailRes.ok) {
+            const emails = await emailRes.json();
+            email = emails.find(e => e.primary && e.verified)?.email;
+        }
+    }
+    catch { /* email opcional */ }
+    stateStore.delete(state);
+    return {
+        ok: true,
+        did: stored.did,
+        githubId: user.id,
+        githubLogin: user.login,
+        email,
+    };
+}

package/dist/credentials/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Credential Router — integra todos los validators de credenciales
+ * con el servidor HTTP del nodo validador.
+ *
+ * Endpoints añadidos:
+ *
+ * Email:
+ *   POST /credentials/email/start    { did, email }
+ *   POST /credentials/email/verify   { sessionId, otp }
+ *
+ * Phone (TOTP — sin SMS, sin API key):
+ *   POST /credentials/phone/start    { did, phone }
+ *   POST /credentials/phone/verify   { sessionId, code }
+ *
+ * GitHub OAuth:
+ *   GET  /credentials/github/start   ?did=<did>
+ *   GET  /credentials/github/callback?code=<code>&state=<state>
+ *
+ * Biometric (ya existe via /verify — solo se documenta aquí):
+ *   POST /verify    { spt, zkp }  → emite BiometricBound credential implícita
+ *
+ * Una vez verificado, el validator emite una BotAttestation con:
+ *   context: "credential:EmailVerified" | "credential:PhoneVerified" |
+ *            "credential:GitHubLinked"
+ * Esta attestation se gossipea al resto de la red P2P automáticamente.
+ */
+import { IncomingMessage, ServerResponse } from "node:http";
+import type { BotAttestation, SoulprintKeypair } from "soulprint-core";
+export type CredentialContext = {
+    nodeKeypair: SoulprintKeypair;
+    signAttestation: (att: Omit<BotAttestation, "sig">) => BotAttestation;
+    gossip: (att: BotAttestation) => void;
+};
+export declare function handleCredentialRoute(req: IncomingMessage, res: ServerResponse, url: string, ctx: CredentialContext): Promise<boolean>;

package/dist/credentials/index.js

@@ -0,0 +1,173 @@
+/**
+ * Credential Router — integra todos los validators de credenciales
+ * con el servidor HTTP del nodo validador.
+ *
+ * Endpoints añadidos:
+ *
+ * Email:
+ *   POST /credentials/email/start    { did, email }
+ *   POST /credentials/email/verify   { sessionId, otp }
+ *
+ * Phone (TOTP — sin SMS, sin API key):
+ *   POST /credentials/phone/start    { did, phone }
+ *   POST /credentials/phone/verify   { sessionId, code }
+ *
+ * GitHub OAuth:
+ *   GET  /credentials/github/start   ?did=<did>
+ *   GET  /credentials/github/callback?code=<code>&state=<state>
+ *
+ * Biometric (ya existe via /verify — solo se documenta aquí):
+ *   POST /verify    { spt, zkp }  → emite BiometricBound credential implícita
+ *
+ * Una vez verificado, el validator emite una BotAttestation con:
+ *   context: "credential:EmailVerified" | "credential:PhoneVerified" |
+ *            "credential:GitHubLinked"
+ * Esta attestation se gossipea al resto de la red P2P automáticamente.
+ */
+import { startEmailVerification, verifyEmailOTP, } from "./email.js";
+import { startPhoneVerification, verifyPhoneTOTP, } from "./phone.js";
+import { startGitHubOAuth, handleGitHubCallback, } from "./github.js";
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+function jsonResp(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.on("data", c => { data += c; if (data.length > 32_768) {
+            req.destroy();
+            reject(new Error("Body too large"));
+        } });
+        req.on("end", () => { try {
+            resolve(JSON.parse(data));
+        }
+        catch {
+            reject(new Error("Invalid JSON"));
+        } });
+    });
+}
+// ── Router ────────────────────────────────────────────────────────────────────
+export async function handleCredentialRoute(req, res, url, ctx) {
+    const method = req.method ?? "GET";
+    const qs = new URL(url, "http://localhost").searchParams;
+    // ── Email ──────────────────────────────────────────────────────────────────
+    if (url.startsWith("/credentials/email/start") && method === "POST") {
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch (e) {
+            return jsonResp(res, 400, { error: e.message }), true;
+        }
+        try {
+            const result = await startEmailVerification(body.did, body.email);
+            jsonResp(res, 200, { ok: true, ...result, message: "OTP sent to your email. Check your inbox." });
+        }
+        catch (e) {
+            jsonResp(res, 400, { ok: false, error: e.message });
+        }
+        return true;
+    }
+    if (url.startsWith("/credentials/email/verify") && method === "POST") {
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch (e) {
+            return jsonResp(res, 400, { error: e.message }), true;
+        }
+        const result = verifyEmailOTP(body.sessionId, body.otp);
+        if (!result.ok)
+            return jsonResp(res, 403, { ok: false, reason: result.reason }), true;
+        const att = ctx.signAttestation({
+            issuer_did: ctx.nodeKeypair.did,
+            target_did: result.did,
+            value: 1,
+            context: "credential:EmailVerified",
+            timestamp: Math.floor(Date.now() / 1000),
+        });
+        ctx.gossip(att);
+        jsonResp(res, 200, { ok: true, credential: "EmailVerified", did: result.did, email: result.email, attestation: att });
+        return true;
+    }
+    // ── Phone ──────────────────────────────────────────────────────────────────
+    if (url.startsWith("/credentials/phone/start") && method === "POST") {
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch (e) {
+            return jsonResp(res, 400, { error: e.message }), true;
+        }
+        try {
+            const result = startPhoneVerification(body.did, body.phone);
+            jsonResp(res, 200, { ok: true, ...result });
+        }
+        catch (e) {
+            jsonResp(res, 400, { ok: false, error: e.message });
+        }
+        return true;
+    }
+    if (url.startsWith("/credentials/phone/verify") && method === "POST") {
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch (e) {
+            return jsonResp(res, 400, { error: e.message }), true;
+        }
+        const result = verifyPhoneTOTP(body.sessionId, body.code);
+        if (!result.ok)
+            return jsonResp(res, 403, { ok: false, reason: result.reason }), true;
+        const att = ctx.signAttestation({
+            issuer_did: ctx.nodeKeypair.did,
+            target_did: result.did,
+            value: 1,
+            context: "credential:PhoneVerified",
+            timestamp: Math.floor(Date.now() / 1000),
+        });
+        ctx.gossip(att);
+        jsonResp(res, 200, { ok: true, credential: "PhoneVerified", did: result.did, phone: result.phone, attestation: att });
+        return true;
+    }
+    // ── GitHub OAuth ───────────────────────────────────────────────────────────
+    if (url.startsWith("/credentials/github/start") && method === "GET") {
+        const did = qs.get("did");
+        if (!did)
+            return jsonResp(res, 400, { error: "Missing query param: did" }), true;
+        const result = startGitHubOAuth(did);
+        if (result.error)
+            return jsonResp(res, 503, { ok: false, ...result }), true;
+        // Redirect al usuario a GitHub
+        res.writeHead(302, { Location: result.authUrl });
+        res.end();
+        return true;
+    }
+    if (url.startsWith("/credentials/github/callback") && method === "GET") {
+        const code = qs.get("code");
+        const state = qs.get("state");
+        if (!code || !state)
+            return jsonResp(res, 400, { error: "Missing code or state" }), true;
+        const result = await handleGitHubCallback(code, state);
+        if (!result.ok)
+            return jsonResp(res, 403, { ok: false, reason: result.reason }), true;
+        const att = ctx.signAttestation({
+            issuer_did: ctx.nodeKeypair.did,
+            target_did: result.did,
+            value: 1,
+            context: "credential:GitHubLinked",
+            timestamp: Math.floor(Date.now() / 1000),
+        });
+        ctx.gossip(att);
+        jsonResp(res, 200, {
+            ok: true,
+            credential: "GitHubLinked",
+            did: result.did,
+            github: { id: result.githubId, login: result.githubLogin },
+            attestation: att,
+        });
+        return true;
+    }
+    return false; // no es una ruta de credenciales
+}

package/dist/credentials/phone.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Phone TOTP Credential Validator — sin servicio externo
+ *
+ * Usa TOTP (RFC 6238) — el mismo estándar de Google Authenticator / Authy.
+ * No requiere SMS, no requiere API key, funciona completamente offline.
+ *
+ * Flujo:
+ *  1. POST /credentials/phone/start  { did, phone }
+ *     → genera un TOTP secret único para este DID
+ *     → retorna { sessionId, totpUri, qrData }
+ *       totpUri = "otpauth://totp/Soulprint:+57..."
+ *       qrData  = string para generar QR (usar qrencode o cualquier lib)
+ *
+ *  2. El usuario escanea el QR con Google Authenticator / Authy
+ *     y envía el código de 6 dígitos
+ *
+ *  3. POST /credentials/phone/verify { sessionId, code }
+ *     → si el TOTP es válido → emite PhoneVerified
+ *     → retorna { credential: "PhoneVerified", did }
+ *
+ * ¿Por qué TOTP en lugar de SMS?
+ *  - 100% open source (RFC 6238, sin dependencias externas)
+ *  - 0 costo — no necesita Twilio, Vonage, etc.
+ *  - Compatible con cualquier TOTP app (Google Auth, Authy, Aegis, etc.)
+ *  - El usuario confirma que controla su dispositivo (equivalente a "phone verified")
+ *  - Funciona offline en el validador
+ *  - P2P friendly: cualquier nodo puede verificar sin shared state
+ *
+ * Configuración: ninguna — funciona out of the box.
+ */
+export declare function startPhoneVerification(did: string, phone: string): {
+    sessionId: string;
+    totpUri: string;
+    qrData: string;
+    instructions: string;
+};
+export declare function verifyPhoneTOTP(sessionId: string, code: string): {
+    ok: boolean;
+    did?: string;
+    phone?: string;
+    reason?: string;
+};

package/dist/credentials/phone.js

@@ -0,0 +1,99 @@
+/**
+ * Phone TOTP Credential Validator — sin servicio externo
+ *
+ * Usa TOTP (RFC 6238) — el mismo estándar de Google Authenticator / Authy.
+ * No requiere SMS, no requiere API key, funciona completamente offline.
+ *
+ * Flujo:
+ *  1. POST /credentials/phone/start  { did, phone }
+ *     → genera un TOTP secret único para este DID
+ *     → retorna { sessionId, totpUri, qrData }
+ *       totpUri = "otpauth://totp/Soulprint:+57..."
+ *       qrData  = string para generar QR (usar qrencode o cualquier lib)
+ *
+ *  2. El usuario escanea el QR con Google Authenticator / Authy
+ *     y envía el código de 6 dígitos
+ *
+ *  3. POST /credentials/phone/verify { sessionId, code }
+ *     → si el TOTP es válido → emite PhoneVerified
+ *     → retorna { credential: "PhoneVerified", did }
+ *
+ * ¿Por qué TOTP en lugar de SMS?
+ *  - 100% open source (RFC 6238, sin dependencias externas)
+ *  - 0 costo — no necesita Twilio, Vonage, etc.
+ *  - Compatible con cualquier TOTP app (Google Auth, Authy, Aegis, etc.)
+ *  - El usuario confirma que controla su dispositivo (equivalente a "phone verified")
+ *  - Funciona offline en el validador
+ *  - P2P friendly: cualquier nodo puede verificar sin shared state
+ *
+ * Configuración: ninguna — funciona out of the box.
+ */
+import { TOTP } from "otpauth";
+import { randomBytes } from "node:crypto";
+const SESSION_TTL_MS = 15 * 60 * 1000; // 15 minutos para completar la verificación
+const phoneSessions = new Map();
+setInterval(() => {
+    const now = Date.now();
+    for (const [id, s] of phoneSessions) {
+        if (s.expiresAt < now)
+            phoneSessions.delete(id);
+    }
+}, 5 * 60_000).unref();
+export function startPhoneVerification(did, phone) {
+    // Validar formato básico de teléfono (E.164)
+    const cleanPhone = phone.replace(/\s/g, "");
+    if (!/^\+?[1-9]\d{7,14}$/.test(cleanPhone)) {
+        throw new Error("Invalid phone number. Use E.164 format: +573001234567");
+    }
+    const sessionId = randomBytes(16).toString("hex");
+    // Generar TOTP secret único para este DID + sesión
+    const secret = randomBytes(20).toString("base64").replace(/[^A-Z2-7]/gi, "A").slice(0, 32).toUpperCase();
+    const totp = new TOTP({
+        issuer: "Soulprint",
+        label: cleanPhone,
+        algorithm: "SHA1",
+        digits: 6,
+        period: 30,
+        secret,
+    });
+    const totpUri = totp.toString();
+    phoneSessions.set(sessionId, {
+        did, phone: cleanPhone, totp, totpUri, secret,
+        expiresAt: Date.now() + SESSION_TTL_MS,
+        verified: false, attempts: 0,
+    });
+    return {
+        sessionId,
+        totpUri,
+        qrData: totpUri, // el cliente puede generar el QR con cualquier lib
+        instructions: [
+            "1. Open Google Authenticator, Authy, or any TOTP app",
+            "2. Tap '+' → 'Scan QR code' and scan the QR code",
+            "   Or tap 'Enter setup key' and paste: " + totpUri,
+            "3. Enter the 6-digit code that appears in the app",
+            "4. POST /credentials/phone/verify with your sessionId and code",
+            "",
+            "This proves you control a real device (equivalent to phone verification).",
+        ].join("\n"),
+    };
+}
+export function verifyPhoneTOTP(sessionId, code) {
+    const session = phoneSessions.get(sessionId);
+    if (!session)
+        return { ok: false, reason: "Session not found or expired" };
+    if (Date.now() > session.expiresAt) {
+        phoneSessions.delete(sessionId);
+        return { ok: false, reason: "Session expired" };
+    }
+    session.attempts++;
+    if (session.attempts > 10) {
+        phoneSessions.delete(sessionId);
+        return { ok: false, reason: "Too many attempts" };
+    }
+    // TOTP valida con ventana de ±1 período (30s) para tolerancia de clock drift
+    const isValid = session.totp.validate({ token: code.trim(), window: 1 }) !== null;
+    if (!isValid)
+        return { ok: false, reason: "Invalid or expired TOTP code. Try the current code in your authenticator app." };
+    phoneSessions.delete(sessionId);
+    return { ok: true, did: session.did, phone: session.phone };
+}

package/dist/validator.js

@@ -2,8 +2,9 @@ import { createServer } from "node:http";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { generateKeypair, keypairFromPrivateKey, decodeToken, sign, verifyAttestation, computeReputation, defaultReputation, PROTOCOL, } from "soulprint-core";
+import { generateKeypair, keypairFromPrivateKey, decodeToken, sign, verifyAttestation, computeReputation, defaultReputation, PROTOCOL, PROTOCOL_HASH, isProtocolHashCompatible, checkFarming, recordApprovedGain, recordFarmingStrike, loadAuditStore, exportAuditStore, } from "soulprint-core";
 import { verifyProof, deserializeProof } from "soulprint-zkp";
+import { handleCredentialRoute } from "./credentials/index.js";
 import { publishAttestationP2P, onAttestationReceived, getP2PStats, } from "./p2p.js";
 // ── Config ────────────────────────────────────────────────────────────────────
 const PORT = parseInt(process.env.SOULPRINT_PORT ?? String(PROTOCOL.DEFAULT_HTTP_PORT));
@@ -12,6 +13,7 @@ const KEYPAIR_FILE = join(NODE_DIR, "node-identity.json");
 const NULLIFIER_DB = join(NODE_DIR, "nullifiers.json");
 const REPUTE_DB = join(NODE_DIR, "reputation.json");
 const PEERS_DB = join(NODE_DIR, "peers.json");
+const AUDIT_DB = join(NODE_DIR, "audit.json");
 const VERSION = "0.2.0";
 const MAX_BODY_BYTES = 64 * 1024;
 // ── Protocol constants (inamovibles — no cambiar directamente aquí) ───────────
@@ -82,6 +84,15 @@ function loadReputation() {
         }
 }
 function saveReputation() { writeFileSync(REPUTE_DB, JSON.stringify(repStore, null, 2)); }
+// ── Audit store (anti-farming) ────────────────────────────────────────────────
+function loadAudit() {
+    if (existsSync(AUDIT_DB))
+        try {
+            loadAuditStore(JSON.parse(readFileSync(AUDIT_DB, "utf8")));
+        }
+        catch { /* empty */ }
+}
+function saveAudit() { writeFileSync(AUDIT_DB, JSON.stringify(exportAuditStore(), null, 2)); }
 /**
  * Obtiene la reputación de un DID.
  * Si no existe, retorna la reputación neutral (score=10).
@@ -173,12 +184,17 @@ async function gossipAttestation(att, excludeUrl) {
         }
     }
     // ── Canal 2: HTTP gossip (fallback para nodos legacy) ─────────────────────
+    // Incluye X-Protocol-Hash para que el peer receptor valide compatibilidad.
     const targets = peers.filter(p => p !== excludeUrl);
     for (const peerUrl of targets) {
         fetch(`${peerUrl}/reputation/attest`, {
             method: "POST",
-            headers: { "Content-Type": "application/json", "X-Gossip": "1" },
-            body: JSON.stringify({ attestation: att }),
+            headers: {
+                "Content-Type": "application/json",
+                "X-Gossip": "1",
+                "X-Protocol-Hash": PROTOCOL_HASH, // ← el receptor valida esto
+            },
+            body: JSON.stringify({ attestation: att, from_peer: true }),
             signal: AbortSignal.timeout(GOSSIP_TIMEOUT_MS),
         }).catch(() => { });
     }
@@ -237,11 +253,12 @@ function handleInfo(res, nodeKeypair) {
         node_did: nodeKeypair.did,
         version: VERSION,
         protocol: PROTOCOL.VERSION,
+        protocol_hash: PROTOCOL_HASH, // ← cualquier modificación cambia este hash
         total_verified: Object.keys(nullifiers).length,
         total_reputation: Object.keys(repStore).length,
         known_peers: peers.length,
         supported_countries: ["CO"],
-        capabilities: ["zk-verify", "anti-sybil", "co-sign", "bot-reputation", "p2p-gossipsub"],
+        capabilities: ["zk-verify", "anti-sybil", "co-sign", "bot-reputation", "p2p-gossipsub", "credential-validators", "anti-farming"],
         rate_limit: `${PROTOCOL.RATE_LIMIT_MAX} req/min per IP`,
         // P2P stats (Phase 5)
         p2p: p2pStats ? {
@@ -264,6 +281,11 @@ function handleInfo(res, nodeKeypair) {
 function handleProtocol(res) {
     json(res, 200, {
         protocol_version: PROTOCOL.VERSION,
+        // ── Protocol Hash — IDENTIDAD DE LA RED ────────────────────────────────
+        // Cualquier nodo con un hash diferente es rechazado automáticamente.
+        // Si PROTOCOL fue modificado (aunque sea un valor), este hash cambia.
+        protocol_hash: PROTOCOL_HASH,
+        // ── Score limits ────────────────────────────────────────────────────────
         score_floor: PROTOCOL.SCORE_FLOOR,
         verified_score_floor: PROTOCOL.VERIFIED_SCORE_FLOOR,
         min_attester_score: PROTOCOL.MIN_ATTESTER_SCORE,
@@ -271,11 +293,20 @@ function handleProtocol(res) {
         reputation_max: PROTOCOL.REPUTATION_MAX,
         max_score: PROTOCOL.MAX_SCORE,
         default_reputation: PROTOCOL.DEFAULT_REPUTATION,
+        // ── Biometric thresholds ────────────────────────────────────────────────
+        face_sim_doc_selfie: PROTOCOL.FACE_SIM_DOC_SELFIE,
+        face_sim_selfie_selfie: PROTOCOL.FACE_SIM_SELFIE_SELFIE,
+        face_key_dims: PROTOCOL.FACE_KEY_DIMS,
+        face_key_precision: PROTOCOL.FACE_KEY_PRECISION,
+        // ── Retry / timing ──────────────────────────────────────────────────────
         verify_retry_max: PROTOCOL.VERIFY_RETRY_MAX,
         verify_retry_base_ms: PROTOCOL.VERIFY_RETRY_BASE_MS,
         verify_retry_max_ms: PROTOCOL.VERIFY_RETRY_MAX_MS,
         att_max_age_seconds: PROTOCOL.ATT_MAX_AGE_SECONDS,
-        immutable: true, // todas estas constantes son inamovibles por diseño
+        // ── Enforcement notice ──────────────────────────────────────────────────
+        immutable: true,
+        enforcement: "p2p-hash", // ← la red rechaza nodos con hash diferente
+        note: "Nodes with a different protocol_hash are rejected by the network. Modifying any constant changes the hash and isolates the node.",
     });
 }
 // ── GET /reputation/:did ──────────────────────────────────────────────────────
@@ -316,6 +347,21 @@ async function handleAttest(req, res, ip) {
     const { attestation, service_spt, from_peer } = body ?? {};
     if (!attestation)
         return json(res, 400, { error: "Missing field: attestation" });
+    // ── Protocol Hash Enforcement (gossip desde peers) ────────────────────────
+    // Si la attestation viene de un peer (X-Gossip: 1), validamos que el peer
+    // opera con las mismas constantes de protocolo.
+    // Un nodo con constantes modificadas no puede inyectar attestations en la red.
+    if (from_peer) {
+        const peerHash = req.headers["x-protocol-hash"];
+        if (peerHash && !isProtocolHashCompatible(peerHash)) {
+            console.warn(`[protocol] Gossip rechazado de ${ip} — hash incompatible: ${peerHash?.slice(0, 16)}...`);
+            return json(res, 409, {
+                error: "Protocol mismatch — gossip rejected",
+                our_hash: PROTOCOL_HASH,
+                their_hash: peerHash,
+            });
+        }
+    }
     const att = attestation;
     // ── Validaciones básicas de la attestation ────────────────────────────────
     if (typeof att.issuer_did !== "string")
@@ -360,16 +406,46 @@ async function handleAttest(req, res, ip) {
         return json(res, 403, { error: "Invalid attestation signature" });
     }
     // ── Aplicar y persistir ───────────────────────────────────────────────────
-    const updatedRep = applyAttestation(att);
+    // ── ANTI-FARMING CHECK (solo para attestations positivas) ─────────────────
+    // Si detectamos farming, convertimos el +1 en -1 automáticamente.
+    // Las attestations negativas no se chequean (una penalización real no hace farming).
+    let finalAtt = att;
+    if (att.value === 1 && !from_peer) {
+        const existing = repStore[att.target_did];
+        const prevAtts = existing?.attestations ?? [];
+        // Reconstruir sesión desde el contexto de la attestation
+        const session = {
+            did: att.target_did,
+            startTime: (att.timestamp - 60) * 1000, // estimar inicio de sesión 60s antes
+            events: [], // no tenemos eventos individuales aquí — se evalúa en withTracking()
+            issuerDid: att.issuer_did,
+        };
+        const farmResult = checkFarming(session, prevAtts);
+        if (farmResult.isFarming) {
+            console.warn(`[anti-farming] 🚫 Farming detectado para ${att.target_did.slice(0, 20)}...`, `\n  Razón: ${farmResult.reason}`, `\n  Convirtiendo +1 → -1 automáticamente`);
+            // Penalizar en lugar de recompensar
+            finalAtt = { ...att, value: -1, context: `farming-penalty:${att.context}` };
+            recordFarmingStrike(att.target_did);
+            saveAudit();
+        }
+        else {
+            // Registrar ganancia aprobada para el tracking de velocidad
+            recordApprovedGain(att.target_did);
+            saveAudit();
+        }
+    }
+    const updatedRep = applyAttestation(finalAtt);
     // ── Gossip a los peers (async, fire-and-forget) ───────────────────────────
     if (!from_peer) {
-        gossipAttestation(att, undefined);
+        gossipAttestation(finalAtt, undefined);
     }
     json(res, 200, {
         ok: true,
-        target_did: att.target_did,
+        target_did: finalAtt.target_did,
         reputation: updatedRep,
         gossiped_to: from_peer ? 0 : peers.length,
+        farming_detected: finalAtt.value !== att.value,
+        ...(finalAtt.value !== att.value ? { farming_reason: finalAtt.context } : {}),
     });
 }
 // ── POST /peers/register ──────────────────────────────────────────────────────
@@ -381,16 +457,30 @@ async function handlePeerRegister(req, res) {
     catch (e) {
         return json(res, 400, { error: e.message });
     }
-    const { url } = body ?? {};
+    const { url, protocol_hash } = body ?? {};
     if (!url || typeof url !== "string")
         return json(res, 400, { error: "Missing field: url" });
     if (!/^https?:\/\//.test(url))
         return json(res, 400, { error: "url must start with http:// or https://" });
+    // ── Protocol Hash Enforcement — INAMOVIBLE POR LA RED ────────────────────
+    // Si el peer envía un hash, DEBE coincidir con el nuestro.
+    // Si no envía hash → se acepta (nodos legacy / primeras versiones).
+    // En versiones futuras, el hash será OBLIGATORIO.
+    if (protocol_hash && !isProtocolHashCompatible(protocol_hash)) {
+        return json(res, 409, {
+            error: "Protocol mismatch — node rejected",
+            reason: "The peer is running with different protocol constants. This breaks network consensus.",
+            our_hash: PROTOCOL_HASH,
+            their_hash: protocol_hash,
+            our_version: PROTOCOL.VERSION,
+            resolution: "Update soulprint-network to the latest version, or join a compatible network.",
+        });
+    }
     if (peers.includes(url))
         return json(res, 200, { ok: true, peers: peers.length, msg: "Already registered" });
     peers.push(url);
     savePeers();
-    json(res, 200, { ok: true, peers: peers.length });
+    json(res, 200, { ok: true, peers: peers.length, protocol_hash: PROTOCOL_HASH });
 }
 // ── GET /peers ─────────────────────────────────────────────────────────────────
 function handleGetPeers(res) {
@@ -487,10 +577,21 @@ export function startValidatorNode(port = PORT) {
     loadNullifiers();
     loadReputation();
     loadPeers();
+    loadAudit();
     const nodeKeypair = loadOrCreateNodeKeypair();
+    // ── Credential context (para el router de credenciales) ───────────────────
+    const credentialCtx = {
+        nodeKeypair,
+        signAttestation: (att) => {
+            const sig = sign(att, nodeKeypair.privateKey);
+            return { ...att, sig };
+        },
+        gossip: (att) => gossipAttestation(att, undefined),
+    };
     const server = createServer(async (req, res) => {
         const ip = getIP(req);
-        const url = req.url?.split("?")[0] ?? "/";
+        const url = req.url ?? "/";
+        const cleanUrl = url.split("?")[0];
         res.setHeader("Access-Control-Allow-Origin", "*");
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
         res.setHeader("Access-Control-Allow-Headers", "Content-Type");
@@ -499,39 +600,54 @@ export function startValidatorNode(port = PORT) {
             res.end();
             return;
         }
-        if (url === "/info" && req.method === "GET")
+        // ── Credential routes (email, phone, github) ───────────────────────────
+        if (cleanUrl.startsWith("/credentials/")) {
+            const handled = await handleCredentialRoute(req, res, url, credentialCtx);
+            if (handled)
+                return;
+        }
+        if (cleanUrl === "/info" && req.method === "GET")
             return handleInfo(res, nodeKeypair);
-        if (url === "/protocol" && req.method === "GET")
+        if (cleanUrl === "/protocol" && req.method === "GET")
             return handleProtocol(res);
-        if (url === "/verify" && req.method === "POST")
+        if (cleanUrl === "/verify" && req.method === "POST")
             return handleVerify(req, res, nodeKeypair, ip);
-        if (url === "/reputation/attest" && req.method === "POST")
+        if (cleanUrl === "/reputation/attest" && req.method === "POST")
             return handleAttest(req, res, ip);
-        if (url === "/peers/register" && req.method === "POST")
+        if (cleanUrl === "/peers/register" && req.method === "POST")
             return handlePeerRegister(req, res);
-        if (url === "/peers" && req.method === "GET")
+        if (cleanUrl === "/peers" && req.method === "GET")
             return handleGetPeers(res);
-        if (url.startsWith("/reputation/") && req.method === "GET")
-            return handleGetReputation(res, decodeURIComponent(url.replace("/reputation/", "")));
-        if (url.startsWith("/nullifier/") && req.method === "GET")
-            return handleNullifierCheck(res, decodeURIComponent(url.replace("/nullifier/", "")));
+        if (cleanUrl.startsWith("/reputation/") && req.method === "GET")
+            return handleGetReputation(res, decodeURIComponent(cleanUrl.replace("/reputation/", "")));
+        if (cleanUrl.startsWith("/nullifier/") && req.method === "GET")
+            return handleNullifierCheck(res, decodeURIComponent(cleanUrl.replace("/nullifier/", "")));
         json(res, 404, { error: "Not found" });
     });
     server.listen(port, () => {
         console.log(`\n🌐 Soulprint Validator Node v${VERSION}`);
         console.log(`   Node DID:     ${nodeKeypair.did}`);
         console.log(`   Listening:    http://0.0.0.0:${port}`);
+        console.log(`   Protocol:     ${PROTOCOL.VERSION} | hash: ${PROTOCOL_HASH.slice(0, 16)}...`);
+        console.log(`   ⚠️  Hash mismatch with peers → connection rejected (P2P enforcement)`);
         console.log(`   Nullifiers:   ${Object.keys(nullifiers).length}`);
         console.log(`   Reputations:  ${Object.keys(repStore).length}`);
         console.log(`   Known peers:  ${peers.length}`);
-        console.log(`\n   POST /verify              verify ZK proof + co-sign`);
+        console.log(`\n   Core endpoints:`);
+        console.log(`   POST /verify              verify ZK proof + co-sign`);
         console.log(`   GET  /info                node info`);
+        console.log(`   GET  /protocol            protocol constants (immutable)`);
         console.log(`   GET  /nullifier/:n        anti-sybil check`);
-        console.log(`   POST /reputation/attest   issue +1/-1 attestation`);
+        console.log(`   POST /reputation/attest   issue attestation (anti-farming ON)`);
         console.log(`   GET  /reputation/:did     get bot reputation`);
-        console.log(`   POST /peers/register      join P2P network`);
-        console.log(`   GET  /peers               list known peers`);
-        console.log(`\n   Anyone can run a Soulprint node. More nodes = more security.\n`);
+        console.log(`\n   Credential validators (open source, no API keys needed):`);
+        console.log(`   POST /credentials/email/start    → email OTP (nodemailer)`);
+        console.log(`   POST /credentials/email/verify`);
+        console.log(`   POST /credentials/phone/start    → TOTP device proof (otpauth)`);
+        console.log(`   POST /credentials/phone/verify`);
+        console.log(`   GET  /credentials/github/start   → GitHub OAuth (native fetch)`);
+        console.log(`   GET  /credentials/github/callback`);
+        console.log(`\n   Anti-farming: ON — max +1/day, pattern detection, cooldowns\n`);
     });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soulprint-network",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Soulprint validator node — HTTP server that verifies ZK proofs, co-signs SPTs, anti-Sybil registry",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,12 +40,16 @@
     "@libp2p/ping": "2.0.37",
     "@libp2p/tcp": "10.1.19",
     "libp2p": "2.10.0",
+    "nodemailer": "^8.0.1",
+    "otpauth": "^9.5.0",
+    "otplib": "^13.3.0",
     "uint8arrays": "5.1.0",
-    "soulprint-core": "0.1.4",
-    "soulprint-zkp": "0.1.3"
+    "soulprint-core": "0.1.7",
+    "soulprint-zkp": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/nodemailer": "^7.0.11",
     "typescript": "^5.4.0"
   },
   "engines": {