soulprint-network 0.2.0 → 0.2.2

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.d.ts

@@ -10,6 +10,13 @@ import { type SoulprintP2PNode } from "./p2p.js";
 export declare function setP2PNode(node: SoulprintP2PNode): void;
 /**
  * Aplica una nueva attestation al DID objetivo y persiste.
+ *
+ * PROTOCOL ENFORCEMENT:
+ * - Si el bot tiene DocumentVerified, su score total nunca puede caer por
+ *   debajo de PROTOCOL.VERIFIED_SCORE_FLOOR (52) — inamovible.
+ * - Anti-replay: la misma attestation (mismo issuer + timestamp + context)
+ *   no se puede aplicar dos veces.
+ *
  * Retorna la reputación actualizada.
  */
 declare function applyAttestation(att: BotAttestation): BotReputation;

package/dist/validator.js

@@ -2,24 +2,27 @@ 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, } from "soulprint-core";
+import { generateKeypair, keypairFromPrivateKey, decodeToken, sign, verifyAttestation, computeReputation, defaultReputation, PROTOCOL, 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 ?? "4888");
+const PORT = parseInt(process.env.SOULPRINT_PORT ?? String(PROTOCOL.DEFAULT_HTTP_PORT));
 const NODE_DIR = join(homedir(), ".soulprint", "node");
 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;
-const RATE_LIMIT_MS = 60_000;
-const RATE_LIMIT_MAX = 10;
-const CLOCK_SKEW_MAX = 300; // ±5 min
-const MIN_ATTESTER_SCORE = 60; // solo servicios verificados emiten attestations
-const ATT_MAX_AGE_SECONDS = 3600; // attestation no puede tener >1h de antigüedad
-const GOSSIP_TIMEOUT_MS = 3_000; // timeout del gossip HTTP fallback
+// ── Protocol constants (inamovibles — no cambiar directamente aquí) ───────────
+const RATE_LIMIT_MS = PROTOCOL.RATE_LIMIT_WINDOW_MS;
+const RATE_LIMIT_MAX = PROTOCOL.RATE_LIMIT_MAX;
+const CLOCK_SKEW_MAX = PROTOCOL.CLOCK_SKEW_MAX_SECONDS;
+const MIN_ATTESTER_SCORE = PROTOCOL.MIN_ATTESTER_SCORE; // 65 — inamovible
+const ATT_MAX_AGE_SECONDS = PROTOCOL.ATT_MAX_AGE_SECONDS;
+const GOSSIP_TIMEOUT_MS = PROTOCOL.GOSSIP_TIMEOUT_MS;
 // ── P2P Node (Phase 5) ────────────────────────────────────────────────────────
 let p2pNode = null;
 /**
@@ -81,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).
@@ -93,6 +105,13 @@ function getReputation(did) {
 }
 /**
  * Aplica una nueva attestation al DID objetivo y persiste.
+ *
+ * PROTOCOL ENFORCEMENT:
+ * - Si el bot tiene DocumentVerified, su score total nunca puede caer por
+ *   debajo de PROTOCOL.VERIFIED_SCORE_FLOOR (52) — inamovible.
+ * - Anti-replay: la misma attestation (mismo issuer + timestamp + context)
+ *   no se puede aplicar dos veces.
+ *
  * Retorna la reputación actualizada.
  */
 function applyAttestation(att) {
@@ -107,14 +126,33 @@ function applyAttestation(att) {
     }
     const allAtts = [...prevAtts, att];
     const rep = computeReputation(allAtts, 10); // base siempre 10
+    // ── PROTOCOL FLOOR ENFORCEMENT ─────────────────────────────────────────────
+    // Si el DID tiene DocumentVerified, su score total no puede caer bajo el floor.
+    // La reputación mínima se calcula como: floor - identity_score.
+    // Ejemplo: floor=52, identity=36 → min_rep = max(0, 52-36) = 16
+    // Nunca permitimos que la reputación baje de ese mínimo.
+    const existingToken = existing ? { hasDocument: true } : null; // conservative: assume yes if known
+    const identityFromStore = existing?.identityScore ?? 0;
+    const hasDocument = existing?.hasDocumentVerified ?? false;
+    let finalRepScore = rep.score;
+    if (hasDocument) {
+        const minRepForFloor = Math.max(0, PROTOCOL.VERIFIED_SCORE_FLOOR - identityFromStore);
+        finalRepScore = Math.max(finalRepScore, minRepForFloor);
+        if (finalRepScore !== rep.score) {
+            console.log(`[floor] Reputation clamped for ${att.target_did.slice(0, 20)}...: ` +
+                `${rep.score} → ${finalRepScore} (VERIFIED_SCORE_FLOOR=${PROTOCOL.VERIFIED_SCORE_FLOOR})`);
+        }
+    }
     repStore[att.target_did] = {
-        score: rep.score,
+        score: finalRepScore,
         base: 10,
         attestations: allAtts,
         last_updated: rep.last_updated,
+        identityScore: existing?.identityScore ?? 0,
+        hasDocumentVerified: hasDocument,
     };
     saveReputation();
-    return rep;
+    return { score: finalRepScore, attestations: allAtts.length, last_updated: rep.last_updated };
 }
 // ── Peers registry (P2P gossip) ───────────────────────────────────────────────
 let peers = []; // URLs de otros nodos (ej: "http://node2.example.com:4888")
@@ -209,13 +247,13 @@ function handleInfo(res, nodeKeypair) {
     json(res, 200, {
         node_did: nodeKeypair.did,
         version: VERSION,
-        protocol: "sip/0.1",
+        protocol: PROTOCOL.VERSION,
         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"],
-        rate_limit: `${RATE_LIMIT_MAX} req/min per IP`,
+        rate_limit: `${PROTOCOL.RATE_LIMIT_MAX} req/min per IP`,
         // P2P stats (Phase 5)
         p2p: p2pStats ? {
             enabled: true,
@@ -226,6 +264,31 @@ function handleInfo(res, nodeKeypair) {
         } : { enabled: false },
     });
 }
+// ── GET /protocol ──────────────────────────────────────────────────────────────
+/**
+ * Expone las constantes de protocolo inamovibles.
+ * Los clientes y otros nodos usan este endpoint para:
+ *  1. Verificar compatibilidad de versión antes de conectarse
+ *  2. Obtener los valores actuales de SCORE_FLOOR y MIN_ATTESTER_SCORE
+ *  3. Validar que el nodo no ha sido modificado para bajar los thresholds
+ */
+function handleProtocol(res) {
+    json(res, 200, {
+        protocol_version: PROTOCOL.VERSION,
+        score_floor: PROTOCOL.SCORE_FLOOR,
+        verified_score_floor: PROTOCOL.VERIFIED_SCORE_FLOOR,
+        min_attester_score: PROTOCOL.MIN_ATTESTER_SCORE,
+        identity_max: PROTOCOL.IDENTITY_MAX,
+        reputation_max: PROTOCOL.REPUTATION_MAX,
+        max_score: PROTOCOL.MAX_SCORE,
+        default_reputation: PROTOCOL.DEFAULT_REPUTATION,
+        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
+    });
+}
 // ── GET /reputation/:did ──────────────────────────────────────────────────────
 function handleGetReputation(res, did) {
     if (!did.startsWith("did:"))
@@ -308,16 +371,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 ──────────────────────────────────────────────────────
@@ -394,6 +487,23 @@ async function handleVerify(req, res, nodeKeypair, ip) {
     const coSig = sign({ nullifier: zkResult.nullifier, did: token.did, timestamp: now }, nodeKeypair.privateKey);
     // Incluir reputación actual del bot en la respuesta
     const reputation = getReputation(token.did);
+    // Guardar identityScore y hasDocumentVerified para enforcement del floor
+    if (!repStore[token.did]) {
+        repStore[token.did] = {
+            score: reputation.score,
+            base: 10,
+            attestations: [],
+            last_updated: now,
+            identityScore: token.identity_score ?? 0,
+            hasDocumentVerified: (token.credentials ?? []).includes("DocumentVerified"),
+        };
+    }
+    else {
+        // Actualizar identity info si el token es más reciente
+        repStore[token.did].identityScore = token.identity_score ?? 0;
+        repStore[token.did].hasDocumentVerified = (token.credentials ?? []).includes("DocumentVerified");
+    }
+    saveReputation();
     json(res, 200, {
         valid: true,
         anti_sybil: antiSybil,
@@ -418,10 +528,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");
@@ -430,20 +551,28 @@ 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 === "/verify" && req.method === "POST")
+        if (cleanUrl === "/protocol" && req.method === "GET")
+            return handleProtocol(res);
+        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, () => {
@@ -453,14 +582,21 @@ export function startValidatorNode(port = PORT) {
         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.0",
+  "version": "0.2.2",
   "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",
@@ -11,10 +11,6 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/server.js"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -44,12 +40,16 @@
     "@libp2p/ping": "2.0.37",
     "@libp2p/tcp": "10.1.19",
     "libp2p": "2.10.0",
-    "soulprint-core": "workspace:*",
-    "soulprint-zkp": "workspace:*",
-    "uint8arrays": "5.1.0"
+    "nodemailer": "^8.0.1",
+    "otpauth": "^9.5.0",
+    "otplib": "^13.3.0",
+    "uint8arrays": "5.1.0",
+    "soulprint-core": "0.1.5",
+    "soulprint-zkp": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/nodemailer": "^7.0.11",
     "typescript": "^5.4.0"
   },
   "engines": {
@@ -61,5 +61,9 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     }
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/server.js"
   }
-}
+}