105 lines
2.9 KiB
Markdown
105 lines
2.9 KiB
Markdown
# @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
|
|
|
|
```bash
|
|
npm install @nkode/client-wasm
|
|
```
|
|
|
|
## Usage
|
|
|
|
```typescript
|
|
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`
|
|
|
|
```typescript
|
|
interface NKodeSession {
|
|
sessionId: string; // UUID
|
|
userId: string; // UUID
|
|
createdAt: string; // ISO 8601 timestamp
|
|
expiresAt: string; // ISO 8601 timestamp
|
|
}
|
|
```
|
|
|
|
## Building from Source
|
|
|
|
```bash
|
|
# 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
|