soulprint-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+export interface SoulprintKeypair {
+    did: string;
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}
+export interface SoulprintToken {
+    sip: "1";
+    did: string;
+    score: number;
+    level: TrustLevel;
+    country?: string;
+    credentials: CredentialType[];
+    nullifier: string;
+    zkp?: string;
+    issued: number;
+    expires: number;
+    network_sig?: string;
+}
+export type TrustLevel = "Unverified" | "EmailVerified" | "PhoneVerified" | "KYCLite" | "KYCFull";
+export type CredentialType = "EmailVerified" | "PhoneVerified" | "GitHubLinked" | "DocumentVerified" | "FaceMatch" | "BiometricBound";
+/**
+ * Genera un keypair Ed25519 y construye un did:key
+ * El DID es portable — mismo keypair = mismo DID en cualquier dispositivo
+ */
+export declare function generateKeypair(): SoulprintKeypair;
+/**
+ * Reconstruye el keypair desde una llave privada guardada
+ */
+export declare function keypairFromPrivateKey(privateKey: Uint8Array): SoulprintKeypair;
+/**
+ * Deriva el nullifier desde datos del documento + embedding de cara cuantizado.
+ * Determinístico: mismo documento + misma cara = mismo nullifier en cualquier dispositivo.
+ * Resistente a Sybil: misma cédula no puede generar dos nullifiers distintos
+ * si el face embedding se mantiene.
+ *
+ * @param cedulaNumber     Número de cédula colombiana
+ * @param fechaNacimiento  YYYY-MM-DD
+ * @param faceEmbedding    Float32Array (512 dims de InsightFace), cuantizado a 2 decimales
+ */
+export declare function deriveNullifier(cedulaNumber: string, fechaNacimiento: string, faceEmbedding: Float32Array): string;
+/**
+ * Cuantiza el embedding de cara para que pequeñas variaciones
+ * entre fotos del mismo rostro produzcan el mismo resultado.
+ * precision=2 → rounds to 0.01 increments
+ */
+export declare function quantizeEmbedding(embedding: Float32Array, precision: number): Float32Array;
+/**
+ * Firma un payload con la llave privada del DID
+ */
+export declare function sign(payload: object, privateKey: Uint8Array): string;
+/**
+ * Verifica una firma contra un DID did:key:...
+ */
+export declare function verify(payload: object, signature: string, did: string): boolean;
+/**
+ * Crea un Soulprint Token (SPT) firmado — el JWT de Soulprint.
+ * Lifetime por defecto: 24 horas.
+ */
+export declare function createToken(keypair: SoulprintKeypair, nullifier: string, credentials: CredentialType[], options?: {
+    lifetimeSeconds?: number;
+    country?: string;
+    zkProof?: string;
+}): string;
+/**
+ * Decodifica y verifica un SPT. Retorna null si es inválido o expirado.
+ */
+export declare function decodeToken(spt: string): (SoulprintToken & {
+    sig: string;
+}) | null;
+export declare function calculateScore(credentials: CredentialType[]): number;
+export declare function calculateLevel(credentials: CredentialType[]): TrustLevel;

package/dist/index.js

@@ -0,0 +1,176 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateKeypair = generateKeypair;
+exports.keypairFromPrivateKey = keypairFromPrivateKey;
+exports.deriveNullifier = deriveNullifier;
+exports.quantizeEmbedding = quantizeEmbedding;
+exports.sign = sign;
+exports.verify = verify;
+exports.createToken = createToken;
+exports.decodeToken = decodeToken;
+exports.calculateScore = calculateScore;
+exports.calculateLevel = calculateLevel;
+const ed25519_1 = require("@noble/curves/ed25519");
+const sha256_1 = require("@noble/hashes/sha256");
+const utils_1 = require("@noble/curves/abstract/utils");
+const bs58_1 = __importDefault(require("bs58"));
+// ── DID generation ────────────────────────────────────────────────────────────
+/**
+ * Genera un keypair Ed25519 y construye un did:key
+ * El DID es portable — mismo keypair = mismo DID en cualquier dispositivo
+ */
+function generateKeypair() {
+    const privateKey = ed25519_1.ed25519.utils.randomPrivateKey();
+    const publicKey = ed25519_1.ed25519.getPublicKey(privateKey);
+    const did = publicKeyToDID(publicKey);
+    return { did, publicKey, privateKey };
+}
+/**
+ * Reconstruye el keypair desde una llave privada guardada
+ */
+function keypairFromPrivateKey(privateKey) {
+    const publicKey = ed25519_1.ed25519.getPublicKey(privateKey);
+    const did = publicKeyToDID(publicKey);
+    return { did, publicKey, privateKey };
+}
+/**
+ * did:key format: did:key:z6Mk<base58btc(0xed01 + publicKey)>
+ * 0xed01 = multicodec prefix para Ed25519
+ */
+function publicKeyToDID(publicKey) {
+    const multicodec = new Uint8Array([0xed, 0x01, ...publicKey]);
+    const encoded = bs58_1.default.encode(multicodec);
+    return `did:key:z${encoded}`;
+}
+// ── Nullifier ─────────────────────────────────────────────────────────────────
+/**
+ * Deriva el nullifier desde datos del documento + embedding de cara cuantizado.
+ * Determinístico: mismo documento + misma cara = mismo nullifier en cualquier dispositivo.
+ * Resistente a Sybil: misma cédula no puede generar dos nullifiers distintos
+ * si el face embedding se mantiene.
+ *
+ * @param cedulaNumber     Número de cédula colombiana
+ * @param fechaNacimiento  YYYY-MM-DD
+ * @param faceEmbedding    Float32Array (512 dims de InsightFace), cuantizado a 2 decimales
+ */
+function deriveNullifier(cedulaNumber, fechaNacimiento, faceEmbedding) {
+    // Cuantizar embedding para absorber ruido entre fotos del mismo rostro
+    const quantized = quantizeEmbedding(faceEmbedding, 2);
+    // Combinar datos estables del documento con la llave biométrica
+    const input = `${cedulaNumber}:${fechaNacimiento}:${float32ToHex(quantized)}`;
+    // Hash final — 32 bytes = 256 bits de seguridad
+    const hash = (0, sha256_1.sha256)(new TextEncoder().encode(input));
+    return "0x" + (0, utils_1.bytesToHex)(hash);
+}
+/**
+ * Cuantiza el embedding de cara para que pequeñas variaciones
+ * entre fotos del mismo rostro produzcan el mismo resultado.
+ * precision=2 → rounds to 0.01 increments
+ */
+function quantizeEmbedding(embedding, precision) {
+    const factor = Math.pow(10, precision);
+    return new Float32Array(embedding.map(v => Math.round(v * factor) / factor));
+}
+function float32ToHex(arr) {
+    return Array.from(arr).map(v => {
+        // Representación fija de 4 decimales para consistencia cross-platform
+        return v.toFixed(2).replace("-", "n").replace(".", "p");
+    }).join(",");
+}
+// ── Firmas ────────────────────────────────────────────────────────────────────
+/**
+ * Firma un payload con la llave privada del DID
+ */
+function sign(payload, privateKey) {
+    const msg = (0, sha256_1.sha256)(new TextEncoder().encode(JSON.stringify(payload)));
+    const sig = ed25519_1.ed25519.sign(msg, privateKey);
+    return (0, utils_1.bytesToHex)(sig);
+}
+/**
+ * Verifica una firma contra un DID did:key:...
+ */
+function verify(payload, signature, did) {
+    try {
+        const publicKey = didToPublicKey(did);
+        const msg = (0, sha256_1.sha256)(new TextEncoder().encode(JSON.stringify(payload)));
+        return ed25519_1.ed25519.verify((0, utils_1.hexToBytes)(signature), msg, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+function didToPublicKey(did) {
+    if (!did.startsWith("did:key:z"))
+        throw new Error("Solo did:key:z... soportado");
+    const encoded = did.replace("did:key:z", "");
+    const multicodec = bs58_1.default.decode(encoded);
+    return multicodec.slice(2); // saltar 0xed 0x01
+}
+// ── SPT Token ─────────────────────────────────────────────────────────────────
+/**
+ * Crea un Soulprint Token (SPT) firmado — el JWT de Soulprint.
+ * Lifetime por defecto: 24 horas.
+ */
+function createToken(keypair, nullifier, credentials, options = {}) {
+    const now = Math.floor(Date.now() / 1000);
+    const payload = {
+        sip: "1",
+        did: keypair.did,
+        score: calculateScore(credentials),
+        level: calculateLevel(credentials),
+        country: options.country,
+        credentials,
+        nullifier,
+        ...(options.zkProof ? { zkp: options.zkProof } : {}),
+        issued: now,
+        expires: now + (options.lifetimeSeconds ?? 86400),
+    };
+    const signature = sign(payload, keypair.privateKey);
+    const tokenData = { ...payload, sig: signature };
+    return Buffer.from(JSON.stringify(tokenData)).toString("base64url");
+}
+/**
+ * Decodifica y verifica un SPT. Retorna null si es inválido o expirado.
+ */
+function decodeToken(spt) {
+    try {
+        const raw = JSON.parse(Buffer.from(spt, "base64url").toString());
+        const { sig, ...payload } = raw;
+        if (!verify(payload, sig, payload.did))
+            return null;
+        if (payload.expires < Math.floor(Date.now() / 1000))
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Trust Score ───────────────────────────────────────────────────────────────
+const CREDENTIAL_SCORES = {
+    EmailVerified: 10,
+    PhoneVerified: 15,
+    GitHubLinked: 20,
+    DocumentVerified: 25,
+    FaceMatch: 20,
+    BiometricBound: 10,
+};
+function calculateScore(credentials) {
+    return credentials.reduce((sum, c) => sum + (CREDENTIAL_SCORES[c] ?? 0), 0);
+}
+function calculateLevel(credentials) {
+    const score = calculateScore(credentials);
+    const has = (c) => credentials.includes(c);
+    if (has("DocumentVerified") && has("FaceMatch"))
+        return "KYCFull";
+    if (has("DocumentVerified") || has("FaceMatch"))
+        return "KYCLite";
+    if (has("PhoneVerified"))
+        return "PhoneVerified";
+    if (has("EmailVerified"))
+        return "EmailVerified";
+    return "Unverified";
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "soulprint-core",
+  "version": "0.1.0",
+  "description": "Soulprint core — DID keypairs, SPT tokens, Ed25519 signatures, trust scoring",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manuelariasfz/soulprint",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/manuelariasfz/soulprint#readme",
+  "keywords": [
+    "soulprint",
+    "kyc",
+    "did",
+    "decentralized-identity",
+    "zero-knowledge",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@noble/curves": "^1.4.0",
+    "@noble/hashes": "^1.4.0",
+    "bs58": "^6.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}