daku 0.0.1 → 0.0.3

package/README.md

@@ -1,8 +1,45 @@
-# daku
+# DAKU
 
-> Leave no trace. Just authenticate.
+> **Anonymous authentication. Zero personal data.**
 
-Cryptographic authentication library with built-in proof-of-work spam protection. No emails, no passwords, no personal data.
+**DAKU** (pronounced _DAA KU_) means "bandits" in Punjabi. Historically, bandits operated anonymously, often using masks to hide their identity. This library adopts that privacy-first ethos—anonymous cryptographic authentication without personal data.
+
+---
+
+## Why DAKU?
+
+**Stop storing passwords. Stop managing email verifications. Stop worrying about data breaches.**
+
+DAKU is a simpler approach to user authentication that keeps both you and your users anonymous. No databases of usernames, no password hashes to secure, no personal information to leak.
+
+```javascript
+// Traditional auth: Store emails, hash passwords, manage resets...
+// DAKU: Just verify cryptographic signatures ✨
+const publicKey = await verifyAuth(token);
+```
+
+### The Problem with Traditional Auth
+
+Every traditional authentication system carries risk:
+
+- **Passwords**: Users reuse them, forget them, get them stolen
+- **Email/Phone**: Requires collecting personal data (GDPR, privacy laws)
+- **Databases**: Honeypots for hackers; one breach exposes everything
+- **Identity**: Your users leave traces everywhere they sign up
+
+### The DAKU Way
+
+Users authenticate with cryptographic keypairs—like Bitcoin wallets, but for your app:
+
+- **No signup forms**: Generate a keypair, start using your app
+- **No passwords**: Users never create or remember passwords
+- **No PII collection**: No emails, phones, or personal data
+- **Built-in spam protection**: Proof-of-work prevents abuse
+- **You stay clean**: Nothing sensitive to store, nothing to breach
+
+> DAKU uses **secp256k1** signatures (same as Bitcoin/Ethereum) with **proof-of-work** spam protection. Auth tokens expire in 1 minute. Users control their private keys, you just verify signatures.
+
+---
 
 ## Installation
 
@@ -12,188 +49,226 @@ npm install daku
 
 ## Quick Start
 
-### 1. Generate a Keypair
-
 ```javascript
-import { generateKeyPair } from 'daku';
+import { generateKeyPair, createAuth, verifyAuth } from "daku";
 
-// Generate once and store securely (localStorage, secure storage, etc.)
+// 1. User generates keypair (client-side)
 const { privateKey, publicKey } = generateKeyPair();
-```
-
-### 2. Client-Side: Create Authentication Request
 
-```javascript
-import { createAuth } from 'daku';
-
-// Create authentication token (includes timestamp, nonce, signature, and POW)
+// 2. Create auth token (client-side)
 const token = await createAuth(privateKey);
 
-// Send to your server
-fetch('/api/login', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'daku': token
-  }
-});
+// 3. Verify auth (server-side)
+const publicKey = await verifyAuth(token);
+// ✅ Authenticated! publicKey is the unique user ID
 ```
 
-### 3. Server-Side: Verify Authentication
+---
 
-```javascript
-import { verifyAuth } from 'daku';
+## Core Functions
 
-const publicKey = await verifyAuth(req.headers['daku']);
+### `generateKeyPair()`
 
-if (publicKey) {
-  // ✅ Authenticated! Use publicKey as unique user ID
-  console.log(`User ${publicKey} authenticated`);
-} else {
-  // ❌ Invalid or expired authentication
-  res.status(401).json({ error: 'Unauthorized' });
-}
+**Create a new identity**
+
+```javascript
+const { privateKey, publicKey } = generateKeyPair();
 ```
 
-## ExpressJS Middleware
+Generates a secp256k1 keypair. The **privateKey** stays with the user (never share it), the **publicKey** identifies them to your service.
 
-```javascript
-import express from 'express';
-import { verifyAuth } from 'daku';
+- Returns: `{ privateKey: string, publicKey: string }`
+- Use case: First-time users, account creation
 
-const app = express();
+---
 
-// Reusable authentication middleware
-const daku = (powDifficulty = 2) => {
-  return async (req, res, next) => {
-    const token = req.headers['daku'];
-    
-    if (!token) {
-      return res.status(401).json({ error: 'Unauthorized' });
-    }
+### `getPublicKey(privateKey)`
 
-    const publicKey = await verifyAuth(token, powDifficulty);
+**Derive the public identity**
 
-    if (!publicKey) {
-      return res.status(401).json({ error: 'Unauthorized' });
-    }
+```javascript
+const publicKey = getPublicKey(privateKey);
+```
 
-    // Attach user's public key to request
-    req.userId = publicKey;
-    next();
-  };
-};
+Extract the public key from a private key. Useful when users return with their saved privateKey.
 
-// Use on protected routes
-app.post('/api/protected', daku(), (req, res) => {
-  res.json({ 
-    message: 'Access granted',
-    userId: req.userId 
-  });
-});
+- Returns: `publicKey` string
+- Deterministic: Same privateKey always produces same publicKey
 
-// Use with custom POW difficulty
-app.post('/api/high-security', daku(4), (req, res) => {
-  res.json({ message: 'High security endpoint' });
-});
+---
 
-app.listen(3000);
-```
+### `getUsername(publicKey)`
 
-## Key Features
+**Make public keys human-readable**
+
+```javascript
+const username = await getUsername(publicKey);
+// → "happy-ocean-flows-1234"
+```
 
-- **🕵️ Anonymous**: No email, phone, or personal data required
-- **🛡️ Spam Protection**: Built-in proof-of-work (default: 2 leading zeros)
-- **🔐 Secure**: secp256k1 cryptographic signatures (same as Bitcoin/Ethereum)
-- **⚡ Lightweight**: Minimal dependencies (@noble/secp256k1, @noble/hashes)
-- **🌐 Cross-Platform**: Works in Node.js and browsers
-- **⏱️ Time-Limited**: Auth requests expire after 1 minute
+Public keys are long hex strings. `getUsername()` converts them into memorable usernames for your UI.
 
-## API Reference
+- Returns: Human-readable username string
+- Deterministic: Same publicKey always → same username
+- Format: `adjective-noun-verb-number`
 
-### Authentication Functions
+> [!IMPORTANT]  
+> **Never ask users to create usernames.** DAKU keeps users anonymous. Display the generated username in your UI, but always identify users by their **publicKey** in your database.
 
-#### `createAuth(privateKey, pow = 2)`
+---
 
-Creates a complete authentication token with timestamp, nonce, signature, and proof-of-work.
+### `createAuth(privateKey, pow?)`
 
-**Returns:** String (base64-encoded token)
+**Generate authentication token**
 
-**Example:**
 ```javascript
-const token = await createAuth(privateKey);
-// "eyJwdWJsaWNrZXkiOiIwMmE..."
+const token = await createAuth(privateKey, 2); // pow = difficulty
 ```
 
-#### `verifyAuth(token, pow = 2)`
+Creates a signed auth token with timestamp, nonce, signature, and proof-of-work. Send this to your server for verification.
+
+- Returns: Base64-encoded auth token
+- Default POW: 2 (adjust for spam protection)
+- Includes: timestamp, nonce, signature, proof-of-work
 
-Verifies authentication token. Checks signature validity, proof-of-work, and timestamp (must be within 1 minute).
+---
+
+### `verifyAuth(token, pow?)`
 
-**Returns:** `publicKey` string on success, `null` on failure
+**Verify authentication token**
 
-**Example:**
 ```javascript
-const publicKey = await verifyAuth(token);
+const publicKey = await verifyAuth(token, 2);
+if (publicKey) {
+  // ✅ Valid! User authenticated
+  console.log(`User ${publicKey} logged in`);
+} else {
+  // ❌ Invalid or expired
+}
 ```
 
+Verifies the signature, proof-of-work, and timestamp (must be < 1 minute old). Returns the user's publicKey on success.
+
+- Returns: `publicKey` string or `null`
+- Checks: Signature validity, POW correctness, timestamp freshness
+- Token lifetime: 1 minute
+
 ---
 
-### General Signing Functions
+### `sign(message, privateKey, pow?)`
+
+**Sign any message**
 
-Use these for signing arbitrary messages (not authentication).
+```javascript
+const { signature, pow } = await sign("hello world", privateKey, 2);
+```
+
+Create a cryptographic signature for any message with proof-of-work. Lower-level function used by `createAuth()`.
 
-#### `sign(message, privateKey, pow = 2)`
+- Returns: `{ signature: string, pow: number }`
+- Use case: Custom message signing beyond authentication
 
-Signs any message with proof-of-work.
+---
+
+### `verify(message, signatureData, publicKey, pow?)`
 
-**Returns:** Object with `{ signature, pow }`
+**Verify any signature**
 
-**Example:**
 ```javascript
-const result = await sign('Hello World', privateKey);
-// { signature: 'a1b2c3...', pow: 42 }
+const isValid = await verify("hello world", { signature, pow }, publicKey, 2);
 ```
 
-#### `verify(message, signatureData, publicKey, pow = 2)`
+Verify a message signature and proof-of-work. Lower-level function used by `verifyAuth()`.
 
-Verifies a signed message.
+- Returns: `boolean`
+- Checks: Signature + POW validity
 
-**Returns:** `true` if valid, `false` otherwise
+---
+
+## Express.js Middleware
 
-**Example:**
 ```javascript
-const isValid = await verify('Hello World', { signature: 'a1b2...', pow: 42 }, publicKey);
+import express from "express";
+import { verifyAuth, getUsername } from "daku";
+
+const app = express();
+
+// Middleware: Verify DAKU auth
+const daku =
+  (powDifficulty = 2) =>
+  async (req, res, next) => {
+    const token = req.headers["daku"];
+    const publicKey = await verifyAuth(token, powDifficulty);
+
+    if (!publicKey) {
+      return res.status(401).json({ error: "Unauthorized" });
+    }
+
+    req.userId = publicKey; // Attach user ID
+    next();
+  };
+
+// Protected route
+app.post("/api/profile", daku(), async (req, res) => {
+  const username = await getUsername(req.userId);
+  res.json({
+    message: `Welcome, ${username}!`,
+    userId: req.userId,
+  });
+});
+
+app.listen(3000);
 ```
 
 ---
 
-### Utility Functions
+## Key Benefits
 
-#### `generateKeyPair()`
+| Traditional Auth                    | DAKU                                   |
+| ----------------------------------- | -------------------------------------- |
+| Manage passwords, hashes, resets    | No passwords—just verify signatures    |
+| Store emails/phones (PII)           | Zero personal data collected           |
+| User databases = security liability | Only store public keys (not sensitive) |
+| Slow authentication flows           | Instant cryptographic verification     |
+| GDPR compliance overhead            | No PII = simpler compliance            |
+| Spam = manual moderation/CAPTCHAs   | Built-in proof-of-work protection      |
 
-Generates a new secp256k1 keypair.
+---
 
-**Returns:** `{ privateKey: string, publicKey: string }`
+## Features
 
-#### `getPublicKey(privateKey)`
+- **🕵️ Anonymous**: No email, no phone, no personal data
+- **🔐 Secure**: secp256k1 signatures (Bitcoin/Ethereum-grade)
+- **🛡️ Spam-proof**: Configurable proof-of-work difficulty
+- **⚡ Lightweight**: Minimal dependencies, works everywhere
+- **🌐 Universal**: Node.js + Browser compatible
+- **⏱️ Short-lived tokens**: 1-minute expiration (anti-replay)
+- **🌍 Cross-project identity**: Reuse one keypair across apps
 
-Derives the public key from a private key.
+---
 
-**Returns:** `string` (compressed public key in hex)
+## Global Identity
 
-#### `sha256(message)`
+Users can reuse **one private key** across multiple services. Same privateKey → same publicKey → same identity everywhere.
 
-SHA-256 hash helper.
+```javascript
+// User's keypair works on yourapp.com AND anotherapp.com
+const publicKey = getPublicKey(samePrivateKey);
+// → Same publicKey = consistent cross-platform identity
+```
 
-**Returns:** `Uint8Array`
+> [!WARNING]  
+> Reusing keypairs links user identity across services. This enables seamless cross-app experiences but reduces anonymity between services. For per-app isolation, derive or generate separate keys.
 
-## Use Cases
+---
 
-- **Authentication**: Use `createAuth()` + `verifyAuth()` for login flows
-- **Message Signing**: Use `sign()` + `verify()` for arbitrary data signatures
-- **Spam Prevention**: POW difficulty prevents automated abuse
-- **Privacy-First Apps**: No PII required, just cryptographic proofs
+## Security Notes
 
-## License
+- **Private keys**: Users must store them securely (localStorage, hardware wallets). Lost keys = lost access.
+- **Token lifetime**: Hardcoded to 1 minute; prevent replay attacks.
+- **POW difficulty**: Default = 2 leading zeros. Increase for high-traffic endpoints (trade-off: slower auth).
+- **No server secrets**: DAKU has no shared secrets—everything is public-key cryptography.
+
+---
 
-ISC
+**DAKU: The authentication system that doesn't know anything about your users. By design.**

package/index.js

@@ -2,9 +2,11 @@
 import * as secp from "@noble/secp256k1";
 import { hmac } from "@noble/hashes/hmac";
 import { sha256 as nobleSha256 } from "@noble/hashes/sha2";
+import { generateAccountIdentifier } from "./username.js";
 
 // Set up HMAC for secp256k1
-secp.etc.hmacSha256Sync = (key, ...msgs) => hmac(nobleSha256, key, secp.etc.concatBytes(...msgs));
+secp.etc.hmacSha256Sync = (key, ...msgs) =>
+  hmac(nobleSha256, key, secp.etc.concatBytes(...msgs));
 
 // Browser compatibility helper for TextEncoder
 async function getTextEncoder() {
@@ -19,12 +21,14 @@ async function getTextEncoder() {
 
 // Helper function to convert bytes to hex
 function bytesToHex(bytes) {
-  return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
+    ""
+  );
 }
 
 // Helper function to convert hex to bytes
 function hexToBytes(hex) {
-  return new Uint8Array(hex.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
+  return new Uint8Array(hex.match(/.{1,2}/g).map((byte) => parseInt(byte, 16)));
 }
 
 // Helper function to generate random bytes
@@ -47,7 +51,7 @@ function base64Encode(obj) {
   if (typeof window !== "undefined") {
     return btoa(json);
   } else {
-    return Buffer.from(json).toString('base64');
+    return Buffer.from(json).toString("base64");
   }
 }
 
@@ -56,14 +60,15 @@ function base64Decode(str) {
   if (typeof window !== "undefined") {
     return JSON.parse(atob(str));
   } else {
-    return JSON.parse(Buffer.from(str, 'base64').toString());
+    return JSON.parse(Buffer.from(str, "base64").toString());
   }
 }
 
 // --- Key Generation ---
 export function generateKeyPair() {
   const privateKey = secp.utils.randomPrivateKey();
-  const publicKey = secp.getPublicKey(privateKey, true); // compressed
+  const publicKey = secp.getPublicKey(privateKey, true);
+
   return {
     privateKey: bytesToHex(privateKey),
     publicKey: bytesToHex(publicKey),
@@ -77,11 +82,16 @@ export function getPublicKey(privateKeyHex) {
   return bytesToHex(publicKeyBytes);
 }
 
+// --- Account Username from Public Key ---
+export async function getUsername(publicKey) {
+  return await generateAccountIdentifier(publicKey);
+}
+
 // --- Hashing (SHA-256) ---
 export async function sha256(msg) {
   const encoder = await getTextEncoder();
   const encoded = encoder.encode(msg);
-  
+
   if (typeof window === "undefined") {
     // Node.js - dynamic import
     const crypto = await import("node:crypto");
@@ -94,88 +104,88 @@ export async function sha256(msg) {
 }
 
 // --- Proof of Work Helper ---
-async function solveProofOfWork(message, difficulty = 2) {
+async function solveProofOfWork(message, difficulty = 1) {
   if (difficulty < 1) {
     difficulty = 1; // Minimum POW is 1
   }
-  
-  const target = '0'.repeat(difficulty);
+
+  const target = "0".repeat(difficulty);
   let nonce = 0;
-  
+
   while (true) {
     const combined = message + nonce;
     const hash = await sha256(combined);
     const hexHash = bytesToHex(hash);
-    
+
     if (hexHash.startsWith(target)) {
       return nonce;
     }
     nonce++;
-    
+
     // Yield to event loop every 1000 attempts to avoid blocking
     if (nonce % 1000 === 0) {
-      await new Promise(resolve => setTimeout(resolve, 0));
+      await new Promise((resolve) => setTimeout(resolve, 0));
     }
   }
 }
 
 // --- Verify Proof of Work ---
-async function verifyProofOfWork(message, powNonce, difficulty = 2) {
+async function verifyProofOfWork(message, powNonce, difficulty = 1) {
   if (difficulty < 1) {
     difficulty = 1; // Minimum POW is 1
   }
-  
+
   if (powNonce === null || powNonce === undefined) {
     return false;
   }
-  
-  const target = '0'.repeat(difficulty);
+
+  const target = "0".repeat(difficulty);
   const combined = message + powNonce;
   const hash = await sha256(combined);
   const hexHash = bytesToHex(hash);
-  
+
   return hexHash.startsWith(target);
 }
 
 // --- Sign Message ---
-export async function sign(message, privateKeyHex, pow = 2) {
+export async function sign(message, privateKeyHex, pow = 1) {
   // Enforce minimum POW of 1
   if (pow < 1) {
     pow = 1;
   }
-  
+
   const hash = await sha256(message);
   const privateKeyBytes = hexToBytes(privateKeyHex);
   const sig = secp.sign(hash, privateKeyBytes);
   const signature = bytesToHex(sig.toCompactRawBytes());
-  
+
   // Always generate POW and return object format
   const powNonce = await solveProofOfWork(message, pow);
   return { signature, pow: powNonce };
 }
 
 // --- Verify Signature ---
-export async function verify(message, signatureData, publicKeyHex, pow = 2) {
+export async function verify(message, signatureData, publicKeyHex, pow = 1) {
   try {
     // Enforce minimum POW of 1
     if (pow < 1) {
       pow = 1;
     }
-    
+
     // Always expect object format { signature, pow }
     const signatureHex = signatureData.signature;
     const powNonce = signatureData.pow;
-    
+
     if (!signatureHex || powNonce === undefined || powNonce === null) {
       return false;
     }
-    
+
     // Verify POW
     const powValid = await verifyProofOfWork(message, powNonce, pow);
     if (!powValid) {
       return false;
     }
-    
+
     // Verify signature
     const hash = await sha256(message);
     const signatureBytes = hexToBytes(signatureHex);
@@ -192,25 +202,25 @@ export async function createAuth(privateKeyHex, pow = 2) {
   if (pow < 1) {
     pow = 1;
   }
-  
+
   const publicKeyHex = getPublicKey(privateKeyHex);
 
   const timestamp = Date.now();
   const nonceBytes = await randomBytes(16);
   const nonce = bytesToHex(nonceBytes);
   const message = `${timestamp}:${nonce}`;
-  
+
   const signatureData = await sign(message, privateKeyHex, pow);
-  
+
   const authPayload = {
     publickey: publicKeyHex,
     signature: signatureData.signature,
     pow: signatureData.pow,
     message,
     timestamp,
-    nonce
+    nonce,
   };
-  
+
   return base64Encode(authPayload);
 }
 
@@ -221,35 +231,40 @@ export async function verifyAuth(token, pow = 2) {
     if (pow < 1) {
       pow = 1;
     }
-    
+
     // Decode token
     const authData = base64Decode(token);
     const publicKeyHex = authData.publickey;
     const { signature, message, pow: powNonce } = authData;
-    
-    if (!publicKeyHex || !signature || !message || powNonce === undefined || powNonce === null) {
+
+    if (
+      !publicKeyHex ||
+      !signature ||
+      !message ||
+      powNonce === undefined ||
+      powNonce === null
+    ) {
       return null;
     }
-    
+
     // Extract timestamp from message
-    const timestamp = Number(message.split(':')[0]);
-    
+    const timestamp = Number(message.split(":")[0]);
+
     // Check timestamp is within 1 minute
     const maxAgeMs = 1 * 60 * 1000; // Hardcoded to 1 minute
     const now = Date.now();
     if (isNaN(timestamp) || Math.abs(now - timestamp) > maxAgeMs) {
       return null;
     }
-    
+
     // Verify signature and POW
     const signatureData = { signature, pow: powNonce };
     const isValid = await verify(message, signatureData, publicKeyHex, pow);
     if (!isValid) {
       return null;
     }
-    
+
     return publicKeyHex;
-    
   } catch {
     return null;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "daku",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Leave no trace. Just authenticate.",
   "homepage": "https://github.com/besoeasy/daku#readme",
   "keywords": [