@abraca/dabra 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraClient.ts

@@ -0,0 +1,381 @@
+import type {
+	UserProfile,
+	DocumentMeta,
+	UploadMeta,
+	UploadInfo,
+	PublicKeyInfo,
+	HealthStatus,
+} from "./types.ts";
+
+export interface AbracadabraClientConfig {
+	/** Server base URL (http or https). WebSocket URL is derived automatically. */
+	url: string;
+	/** Initial JWT token. If omitted and persistAuth is true, loads from storage. */
+	token?: string;
+	/** Persist JWT to localStorage for stay-logged-in. Default: true in browser. */
+	persistAuth?: boolean;
+	/** localStorage key for token persistence. Default: "abracadabra:auth". */
+	storageKey?: string;
+	/** Custom fetch implementation (useful for Node.js or testing). */
+	fetch?: typeof globalThis.fetch;
+}
+
+export class AbracadabraClient {
+	private _token: string | null;
+	private readonly baseUrl: string;
+	private readonly persistAuth: boolean;
+	private readonly storageKey: string;
+	private readonly _fetch: typeof globalThis.fetch;
+
+	constructor(config: AbracadabraClientConfig) {
+		this.baseUrl = config.url.replace(/\/+$/, "");
+		this.persistAuth = config.persistAuth ?? typeof localStorage !== "undefined";
+		this.storageKey = config.storageKey ?? "abracadabra:auth";
+		this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+
+		// Load token: explicit > persisted > null
+		this._token = config.token ?? this.loadPersistedToken() ?? null;
+	}
+
+	// ── Token management ─────────────────────────────────────────────────────
+
+	get token(): string | null {
+		return this._token;
+	}
+
+	set token(value: string | null) {
+		this._token = value;
+		if (this.persistAuth) {
+			if (value) {
+				this.persistToken(value);
+			} else {
+				this.clearPersistedToken();
+			}
+		}
+	}
+
+	get isAuthenticated(): boolean {
+		return this._token !== null;
+	}
+
+	/** Derives ws:// or wss:// URL from the http(s) base URL. */
+	get wsUrl(): string {
+		return this.baseUrl
+			.replace(/^https:\/\//, "wss://")
+			.replace(/^http:\/\//, "ws://") + "/ws";
+	}
+
+	// ── Auth ─────────────────────────────────────────────────────────────────
+
+	/** Register a new user with password. */
+	async register(opts: {
+		username: string;
+		password: string;
+		email?: string;
+		displayName?: string;
+	}): Promise<UserProfile> {
+		return this.request<UserProfile>("POST", "/auth/register", {
+			body: opts,
+			auth: false,
+		});
+	}
+
+	/**
+	 * Register a new user with an Ed25519 public key (crypto auth).
+	 * Username is optional — if omitted, a short identifier is derived from the key.
+	 */
+	async registerWithKey(opts: {
+		publicKey: string;
+		username?: string;
+		deviceName?: string;
+		displayName?: string;
+		email?: string;
+	}): Promise<UserProfile> {
+		const username = opts.username ?? `user-${opts.publicKey.slice(0, 8)}`;
+		return this.request<UserProfile>("POST", "/auth/register", {
+			body: {
+				username,
+				identityPublicKey: opts.publicKey,
+				deviceName: opts.deviceName,
+				displayName: opts.displayName,
+				email: opts.email,
+			},
+			auth: false,
+		});
+	}
+
+	/** Login with username + password. Auto-persists returned token. */
+	async login(opts: { username: string; password: string }): Promise<string> {
+		const res = await this.request<{ token: string }>("POST", "/auth/login", {
+			body: opts,
+			auth: false,
+		});
+		this.token = res.token;
+		return res.token;
+	}
+
+	/** Request an Ed25519 crypto auth challenge for the given public key. */
+	async challenge(publicKey: string): Promise<{ challenge: string; expiresAt: number }> {
+		return this.request("POST", "/auth/challenge", {
+			body: { publicKey },
+			auth: false,
+		});
+	}
+
+	/** Verify an Ed25519 signature to complete crypto auth. Auto-persists token. */
+	async verify(opts: {
+		publicKey: string;
+		signature: string;
+		challenge: string;
+	}): Promise<string> {
+		const res = await this.request<{ token: string }>("POST", "/auth/verify", {
+			body: opts,
+			auth: false,
+		});
+		this.token = res.token;
+		return res.token;
+	}
+
+	/**
+	 * Full crypto auth flow: challenge → sign → verify.
+	 * Convenience method combining challenge() + external signing + verify().
+	 */
+	async loginWithKey(
+		publicKey: string,
+		signChallenge: (challenge: string) => Promise<string>,
+	): Promise<string> {
+		const { challenge } = await this.challenge(publicKey);
+		const signature = await signChallenge(challenge);
+		return this.verify({ publicKey, signature, challenge });
+	}
+
+	/** Add a new Ed25519 public key to the current user (multi-device). */
+	async addKey(opts: { publicKey: string; deviceName?: string }): Promise<void> {
+		await this.request("POST", "/auth/keys", { body: opts });
+	}
+
+	/** List all registered public keys for the current user. */
+	async listKeys(): Promise<PublicKeyInfo[]> {
+		const res = await this.request<{ keys: PublicKeyInfo[] }>("GET", "/auth/keys");
+		return res.keys;
+	}
+
+	/** Revoke a public key by its ID. */
+	async revokeKey(keyId: string): Promise<void> {
+		await this.request("DELETE", `/auth/keys/${encodeURIComponent(keyId)}`);
+	}
+
+	/** Clear token from memory and storage. */
+	logout(): void {
+		this.token = null;
+	}
+
+	// ── User ─────────────────────────────────────────────────────────────────
+
+	/** Get the current user's profile. */
+	async getMe(): Promise<UserProfile> {
+		return this.request<UserProfile>("GET", "/users/me");
+	}
+
+	/** Update the current user's display name. */
+	async updateMe(opts: { displayName?: string }): Promise<void> {
+		await this.request("PATCH", "/users/me", { body: opts });
+	}
+
+	// ── Documents ────────────────────────────────────────────────────────────
+
+	/** Create a new root document. Returns its metadata. */
+	async createDoc(opts?: { id?: string }): Promise<DocumentMeta> {
+		return this.request<DocumentMeta>("POST", "/docs", { body: opts ?? {} });
+	}
+
+	/** Get document metadata. */
+	async getDoc(docId: string): Promise<DocumentMeta> {
+		return this.request<DocumentMeta>("GET", `/docs/${encodeURIComponent(docId)}`);
+	}
+
+	/** Delete a document (requires Owner role). Cascades to children and uploads. */
+	async deleteDoc(docId: string): Promise<void> {
+		await this.request("DELETE", `/docs/${encodeURIComponent(docId)}`);
+	}
+
+	/** List immediate child documents. */
+	async listChildren(docId: string): Promise<string[]> {
+		const res = await this.request<{ children: string[] }>(
+			"GET",
+			`/docs/${encodeURIComponent(docId)}/children`,
+		);
+		return res.children;
+	}
+
+	/** Create a child document under a parent (requires write permission). */
+	async createChild(docId: string, opts?: { child_id?: string }): Promise<DocumentMeta> {
+		return this.request<DocumentMeta>(
+			"POST",
+			`/docs/${encodeURIComponent(docId)}/children`,
+			{ body: opts ?? {} },
+		);
+	}
+
+	// ── Permissions ──────────────────────────────────────────────────────────
+
+	/** Grant or change a user's role on a document (requires Owner). */
+	async setPermission(
+		docId: string,
+		opts: { user_id: string; role: "owner" | "editor" | "viewer" | "observer" },
+	): Promise<void> {
+		await this.request(
+			"POST",
+			`/docs/${encodeURIComponent(docId)}/permissions`,
+			{ body: opts },
+		);
+	}
+
+	/** Revoke a user's permission on a document (requires Owner). */
+	async removePermission(docId: string, opts: { user_id: string }): Promise<void> {
+		await this.request(
+			"DELETE",
+			`/docs/${encodeURIComponent(docId)}/permissions`,
+			{ body: opts },
+		);
+	}
+
+	// ── Uploads ──────────────────────────────────────────────────────────────
+
+	/** Upload a file to a document (requires write permission). */
+	async upload(
+		docId: string,
+		file: File | Blob,
+		filename?: string,
+	): Promise<UploadMeta> {
+		const formData = new FormData();
+		formData.append("file", file, filename);
+
+		const headers: Record<string, string> = {};
+		if (this._token) {
+			headers["Authorization"] = `Bearer ${this._token}`;
+		}
+
+		const res = await this._fetch(
+			`${this.baseUrl}/docs/${encodeURIComponent(docId)}/uploads`,
+			{ method: "POST", headers, body: formData },
+		);
+		if (!res.ok) {
+			throw await this.toError(res);
+		}
+		return res.json() as Promise<UploadMeta>;
+	}
+
+	/** List all uploads for a document. */
+	async listUploads(docId: string): Promise<UploadInfo[]> {
+		const res = await this.request<{ uploads: UploadInfo[] }>(
+			"GET",
+			`/docs/${encodeURIComponent(docId)}/uploads`,
+		);
+		return res.uploads;
+	}
+
+	/** Download an upload as a Blob. */
+	async getUpload(docId: string, uploadId: string): Promise<Blob> {
+		const headers: Record<string, string> = {};
+		if (this._token) {
+			headers["Authorization"] = `Bearer ${this._token}`;
+		}
+
+		const res = await this._fetch(
+			`${this.baseUrl}/docs/${encodeURIComponent(docId)}/uploads/${encodeURIComponent(uploadId)}`,
+			{ method: "GET", headers },
+		);
+		if (!res.ok) {
+			throw await this.toError(res);
+		}
+		return res.blob();
+	}
+
+	/** Delete an upload (requires uploader or document Owner). */
+	async deleteUpload(docId: string, uploadId: string): Promise<void> {
+		await this.request(
+			"DELETE",
+			`/docs/${encodeURIComponent(docId)}/uploads/${encodeURIComponent(uploadId)}`,
+		);
+	}
+
+	// ── System ───────────────────────────────────────────────────────────────
+
+	/** Health check — no auth required. */
+	async health(): Promise<HealthStatus> {
+		return this.request<HealthStatus>("GET", "/health", { auth: false });
+	}
+
+	// ── Internals ────────────────────────────────────────────────────────────
+
+	private async request<T = void>(
+		method: string,
+		path: string,
+		opts?: { body?: unknown; auth?: boolean },
+	): Promise<T> {
+		const auth = opts?.auth ?? true;
+		const headers: Record<string, string> = {};
+
+		if (auth && this._token) {
+			headers["Authorization"] = `Bearer ${this._token}`;
+		}
+
+		const init: RequestInit = { method, headers };
+
+		if (opts?.body !== undefined) {
+			headers["Content-Type"] = "application/json";
+			init.body = JSON.stringify(opts.body);
+		}
+
+		const res = await this._fetch(`${this.baseUrl}${path}`, init);
+
+		if (!res.ok) {
+			throw await this.toError(res);
+		}
+
+		// 204 No Content
+		if (res.status === 204) {
+			return undefined as T;
+		}
+
+		return res.json() as Promise<T>;
+	}
+
+	private async toError(res: Response): Promise<Error> {
+		let message: string;
+		try {
+			const body = await res.json() as { error?: string };
+			message = body.error ?? res.statusText;
+		} catch {
+			message = res.statusText;
+		}
+		const err = new Error(message);
+		(err as any).status = res.status;
+		return err;
+	}
+
+	private loadPersistedToken(): string | null {
+		try {
+			return localStorage.getItem(this.storageKey);
+		} catch {
+			return null;
+		}
+	}
+
+	private persistToken(token: string): void {
+		try {
+			localStorage.setItem(this.storageKey, token);
+		} catch {
+			// localStorage unavailable (SSR / Node.js)
+		}
+	}
+
+	private clearPersistedToken(): void {
+		try {
+			localStorage.removeItem(this.storageKey);
+		} catch {
+			// localStorage unavailable
+		}
+	}
+}

package/src/AbracadabraProvider.ts

@@ -12,9 +12,10 @@ import type {
 	onSubdocLoadedParameters,
 } from "./types.ts";
 import { AuthenticationMessage } from "./OutgoingMessages/AuthenticationMessage.ts";
+import type { AbracadabraClient } from "./AbracadabraClient.ts";
 
 export interface AbracadabraProviderConfiguration
-	extends HocuspocusProviderConfiguration {
+	extends Omit<HocuspocusProviderConfiguration, "url" | "websocketProvider"> {
 	/**
 	 * Subdocument loading strategy.
 	 * - "lazy"  (default) – child providers are created only when explicitly requested.
@@ -45,6 +46,19 @@ export interface AbracadabraProviderConfiguration
 	 * Required when cryptoIdentity is set.
 	 */
 	signChallenge?: (challenge: string) => Promise<string>;
+
+	/**
+	 * AbracadabraClient instance for REST API access.
+	 * When provided, the provider automatically derives the WebSocket URL
+	 * and token from the client (unless explicitly overridden).
+	 */
+	client?: AbracadabraClient;
+
+	/** WebSocket URL. Derived from client.wsUrl if client is provided. */
+	url?: string;
+
+	/** Shared WebSocket connection (use when multiplexing multiple root documents). */
+	websocketProvider?: HocuspocusProviderWebsocket;
 }
 
 /**
@@ -65,6 +79,7 @@ export interface AbracadabraProviderConfiguration
 export class AbracadabraProvider extends HocuspocusProvider {
 	public effectiveRole: EffectiveRole = null;
 
+	private _client: AbracadabraClient | null;
 	private offlineStore: OfflineStore | null;
 	private childProviders = new Map<string, AbracadabraProvider>();
 	private subdocLoading: "lazy" | "eager";
@@ -74,7 +89,21 @@ export class AbracadabraProvider extends HocuspocusProvider {
 	private readonly boundHandleYSubdocsChange = this.handleYSubdocsChange.bind(this);
 
 	constructor(configuration: AbracadabraProviderConfiguration) {
-		super(configuration);
+		// Derive URL and token from client when not explicitly set.
+		const resolved = { ...configuration } as HocuspocusProviderConfiguration;
+		const client = configuration.client ?? null;
+
+		if (client) {
+			if (!resolved.url && !resolved.websocketProvider) {
+				(resolved as any).url = client.wsUrl;
+			}
+			if (resolved.token === undefined && !configuration.cryptoIdentity) {
+				resolved.token = () => client.token ?? "";
+			}
+		}
+
+		super(resolved);
+		this._client = client;
 		this.abracadabraConfig = configuration;
 		this.subdocLoading = configuration.subdocLoading ?? "lazy";
 
@@ -110,8 +139,12 @@ export class AbracadabraProvider extends HocuspocusProvider {
 	}
 
 	/**
-	 * Override sendToken to send an identity declaration instead of a JWT
-	 * when cryptoIdentity is configured.
+	 * Override sendToken to send a pubkey-only identity declaration instead of a
+	 * JWT when cryptoIdentity is configured.
+	 *
+	 * The public key is the sole identifier in the crypto auth handshake.
+	 * Username is decoupled from auth; it lives on the server as an immutable
+	 * internal field and is never sent in the challenge-response frames.
 	 */
 	override async sendToken() {
 		const { cryptoIdentity } = this.abracadabraConfig;
@@ -122,7 +155,6 @@ export class AbracadabraProvider extends HocuspocusProvider {
 					: cryptoIdentity;
 			const json = JSON.stringify({
 				type: "identity",
-				username: id.username,
 				publicKey: id.publicKey,
 			});
 			this.send(AuthenticationMessage, {
@@ -153,9 +185,9 @@ export class AbracadabraProvider extends HocuspocusProvider {
 				? await cryptoIdentity()
 				: cryptoIdentity;
 		const signature = await signChallenge(challenge);
+		// Proof frame sends only publicKey — username is fully decoupled from auth.
 		const proof = JSON.stringify({
 			type: "proof",
-			username: id.username,
 			publicKey: id.publicKey,
 			signature,
 			challenge,
@@ -178,6 +210,11 @@ export class AbracadabraProvider extends HocuspocusProvider {
 		return this.effectiveRole === "owner" || this.effectiveRole === "editor";
 	}
 
+	/** The AbracadabraClient instance for REST API access, if configured. */
+	get client(): AbracadabraClient | null {
+		return this._client;
+	}
+
 	// ── Stateless message interception ────────────────────────────────────────
 
 	/**
@@ -293,6 +330,9 @@ export class AbracadabraProvider extends HocuspocusProvider {
 			token: this.configuration.token,
 			subdocLoading: this.subdocLoading,
 			disableOfflineStore: this.abracadabraConfig.disableOfflineStore,
+			client: this._client ?? undefined,
+			cryptoIdentity: this.abracadabraConfig.cryptoIdentity,
+			signChallenge: this.abracadabraConfig.signChallenge,
 		});
 		this.childProviders.set(childId, childProvider);
 

package/src/CryptoIdentityKeystore.ts

@@ -18,8 +18,14 @@ import { sha256 } from "@noble/hashes/sha256";
 // ── Types ────────────────────────────────────────────────────────────────────
 
 interface StoredIdentity {
+	/**
+	 * Internal label stored locally. NOT sent to the server during the
+	 * challenge-response handshake — the public key is the sole auth identifier.
+	 * This may be used as a hint when calling POST /auth/register (first device)
+	 * or displayed to the user before they set a real display name.
+	 */
 	username: string;
-	/** base64url-encoded Ed25519 public key (32 bytes) */
+	/** base64url-encoded Ed25519 public key (32 bytes). Primary auth identifier. */
 	publicKey: string;
 	/** AES-GCM ciphertext of the 32-byte private key */
 	encryptedPrivateKey: ArrayBuffer;
@@ -269,7 +275,13 @@ export class CryptoIdentityKeystore {
 		return stored?.publicKey ?? null;
 	}
 
-	/** Returns the stored username, or null if no identity exists. */
+	/**
+	 * Returns the locally-stored internal username label, or null if no identity exists.
+	 *
+	 * This is NOT the auth identifier (the public key is). It can be used as a
+	 * hint when calling POST /auth/register, or displayed before the user sets
+	 * a real display name via PATCH /users/me.
+	 */
 	async getUsername(): Promise<string | null> {
 		const db = await openDb();
 		const stored = await dbGet(db);

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./HocuspocusProvider.ts";
 export * from "./HocuspocusProviderWebsocket.ts";
 export * from "./types.ts";
 export * from "./AbracadabraProvider.ts";
+export * from "./AbracadabraClient.ts";
 export * from "./OfflineStore.ts";
 export { SubdocMessage } from "./OutgoingMessages/SubdocMessage.ts";
 export { CryptoIdentityKeystore } from "./CryptoIdentityKeystore.ts";

package/src/types.ts

@@ -119,10 +119,15 @@ export type StatesArray = { clientId: number; [key: string | number]: any }[];
 
 export type EffectiveRole = "owner" | "editor" | "viewer" | null;
 
-/** Ed25519 identity for passwordless crypto auth (Model B multi-key). */
+/**
+ * Ed25519 identity for passwordless crypto auth.
+ *
+ * The public key is the sole identifier sent to the server during the
+ * challenge-response handshake. Username is decoupled from auth and is
+ * managed separately as a mutable display name (see PATCH /users/me).
+ */
 export interface CryptoIdentity {
-  username: string;
-  /** base64url-encoded Ed25519 public key (32 bytes) */
+  /** base64url-encoded Ed25519 public key (32 bytes). Primary auth identifier. */
   publicKey: string;
 }
 
@@ -141,3 +146,43 @@ export type onSubdocLoadedParameters = {
 export interface AbracadabraOutgoingMessageArguments extends OutgoingMessageArguments {
   childDocumentName: string;
 }
+
+// ── REST API response types ──────────────────────────────────────────────────
+
+export interface UserProfile {
+  id: string;
+  username: string;
+  email: string | null;
+  displayName: string | null;
+}
+
+export interface DocumentMeta {
+  id: string;
+  parent_id: string | null;
+}
+
+export interface UploadMeta {
+  id: string;
+  doc_id: string;
+  filename: string;
+}
+
+export interface UploadInfo {
+  id: string;
+  filename: string;
+  mime_type: string;
+  size: number;
+}
+
+export interface PublicKeyInfo {
+  id: string;
+  publicKey: string;
+  deviceName: string | null;
+  revoked: boolean;
+}
+
+export interface HealthStatus {
+  status: string;
+  version: string;
+  active_documents: number;
+}