nkode-web/pkg/README.md

@nkode/client-wasm

nKode client compiled to WebAssembly with TypeScript bindings.

Provides OPAQUE (aPAKE) authentication flows that run entirely in the browser — no server-side secret key handling needed.

Installation

npm install @nkode/client-wasm

Usage

import init, { NKodeClient } from '@nkode/client-wasm';

// Initialize the WASM module
await init();

const client = new NKodeClient('https://api.nkode.example.com');

// Generate a new secret key (16 random bytes, hex-encoded)
const secretKey = NKodeClient.generateSecretKey();
// Store this securely — it's the user's authentication key!

// Register a new user
await client.registerKey('user@example.com', secretKey);

// Login
const session = await client.loginKey('user@example.com', secretKey);
console.log(session.sessionId); // UUID
console.log(session.userId);    // UUID
console.log(session.createdAt); // ISO 8601
console.log(session.expiresAt); // ISO 8601

// Code-based flows (for icon passcode)
await client.registerCode('user@example.com', passcodeBytes);
const codeSession = await client.loginCode('user@example.com', passcodeBytes);

API

NKodeClient

new NKodeClient(baseUrl: string)

Create a client connected to the nKode server.

static generateSecretKey(): string

Generate a random 16-byte secret key as a hex string (32 chars).

registerKey(email: string, secretKeyHex: string): Promise<void>

Register a new user with OPAQUE key-based registration.

loginKey(email: string, secretKeyHex: string): Promise<NKodeSession>

Login with OPAQUE key-based authentication.

registerCode(email: string, passcodeBytes: Uint8Array): Promise<void>

Register with OPAQUE code-based flow.

loginCode(email: string, passcodeBytes: Uint8Array): Promise<NKodeSession>

Login with OPAQUE code-based flow.

NKodeSession

interface NKodeSession {
  sessionId: string;  // UUID
  userId: string;     // UUID
  createdAt: string;  // ISO 8601 timestamp
  expiresAt: string;  // ISO 8601 timestamp
}

Building from Source

# Prerequisites
rustup target add wasm32-unknown-unknown
cargo install wasm-pack

# Build
./build.sh          # For bundlers (webpack/vite)
./build.sh web      # For ES modules
./build.sh nodejs   # For Node.js

Architecture

This crate is a standalone WASM bridge that:

• Uses opaque-ke for client-side OPAQUE protocol
• Uses the browser's Fetch API for HTTP transport
• Shares common types with the Rust server
• Runs entirely in the browser — no server round-trips for crypto

The OPAQUE flows (registration + login) are reimplemented for the WASM single-threaded environment (no Send/Sync bounds, no tokio).

Security

• Secret keys never leave the browser
• OPAQUE ensures the server never sees the user's password
• Session keys are derived from the OPAQUE protocol
• All HTTP communication should use HTTPS