@bandeira-tech/b3nd-web 0.2.7 → 0.3.1

package/dist/{client-B0Ekm99R.d.ts → client-C4oQxiDu.d.ts}

@@ -3,6 +3,59 @@
  *
  * Type definitions for the B3nd Wallet Client that interacts with wallet servers.
  */
+/**
+ * Common interface for wallet clients (WalletClient and MemoryWalletClient)
+ *
+ * Implement this interface to create custom wallet clients or use
+ * for dependency injection in tests.
+ *
+ * @example
+ * ```typescript
+ * function setupApp(wallet: WalletClientInterface) {
+ *   // Works with both WalletClient and MemoryWalletClient
+ *   await wallet.proxyWrite({ uri: "...", data: {...} });
+ * }
+ *
+ * // Production
+ * setupApp(new WalletClient({ walletServerUrl: "...", apiBasePath: "/api/v1" }));
+ *
+ * // Tests
+ * setupApp(await MemoryWalletClient.create());
+ * ```
+ */
+interface WalletClientInterface {
+    getSession(): AuthSession | null;
+    setSession(session: AuthSession | null): void;
+    isAuthenticated(): boolean;
+    getUsername(): string | null;
+    getToken(): string | null;
+    logout(): void;
+    health(): Promise<HealthResponse>;
+    getServerKeys(): Promise<{
+        identityPublicKeyHex: string;
+        encryptionPublicKeyHex: string;
+    }>;
+    /**
+     * Signup with session keypair.
+     * Session must be approved by app at mutable://accounts/{appKey}/sessions/{sessionPubkey} = 1
+     */
+    signupWithToken(appKey: string, session: SessionKeypair, credentials: UserCredentials): Promise<AuthSession>;
+    /**
+     * Login with session keypair.
+     * Session must be approved by app at mutable://accounts/{appKey}/sessions/{sessionPubkey} = 1
+     */
+    loginWithTokenSession(appKey: string, session: SessionKeypair, credentials: UserCredentials): Promise<AuthSession>;
+    changePassword(appKey: string, oldPassword: string, newPassword: string): Promise<void>;
+    requestPasswordResetWithToken(appKey: string, tokenOrUsername: string, maybeUsername?: string): Promise<PasswordResetToken>;
+    resetPasswordWithToken(appKey: string, tokenOrUsername: string, usernameOrReset: string, resetToken?: string, newPassword?: string): Promise<AuthSession>;
+    getPublicKeys(appKey: string): Promise<UserPublicKeys>;
+    getMyPublicKeys(appKey: string): Promise<UserPublicKeys>;
+    proxyWrite(request: ProxyWriteRequest): Promise<ProxyWriteResponse>;
+    proxyRead(request: ProxyReadRequest): Promise<ProxyReadResponse>;
+    proxyReadMulti(request: ProxyReadMultiRequest): Promise<ProxyReadMultiResponse>;
+    signupWithGoogle(appKey: string, token: string, googleIdToken: string): Promise<GoogleAuthSession>;
+    loginWithGoogle(appKey: string, token: string, session: SessionKeypair, googleIdToken: string): Promise<GoogleAuthSession>;
+}
 /**
  * Configuration for wallet client
  */
@@ -27,6 +80,17 @@ interface UserCredentials {
     username: string;
     password: string;
 }
+/**
+ * Session keypair for authentication
+ * Sessions are Ed25519 keypairs. The client creates the session, requests
+ * approval from the app, then uses the private key to sign login requests.
+ */
+interface SessionKeypair {
+    /** Session public key (hex encoded) - used as session identifier */
+    publicKeyHex: string;
+    /** Session private key (hex encoded) - used to sign login requests */
+    privateKeyHex: string;
+}
 /**
  * Authenticated session with JWT token
  */
@@ -89,6 +153,38 @@ interface ProxyReadResponse {
     decrypted?: unknown;
     error?: string;
 }
+/**
+ * Read-multi proxy request
+ */
+interface ProxyReadMultiRequest {
+    uris: string[];
+}
+/**
+ * Read-multi proxy result item
+ */
+interface ProxyReadMultiResultItem {
+    uri: string;
+    success: boolean;
+    record?: {
+        data: unknown;
+        ts: number;
+    };
+    decrypted?: unknown;
+    error?: string;
+}
+/**
+ * Read-multi proxy response
+ */
+interface ProxyReadMultiResponse {
+    success: boolean;
+    results: ProxyReadMultiResultItem[];
+    summary: {
+        total: number;
+        succeeded: number;
+        failed: number;
+    };
+    error?: string;
+}
 /**
  * API response wrapper
  */
@@ -283,13 +379,31 @@ declare class WalletClient {
      */
     resetPassword(_username: string, _resetToken: string, _newPassword: string): Promise<AuthSession>;
     /**
-     * Sign up with app token (scoped to an app)
+     * Sign up with session keypair (scoped to an app)
+     *
+     * The session must be approved by the app beforehand:
+     * 1. Client writes request to: immutable://inbox/{appKey}/sessions/{sessionPubkey} = 1
+     * 2. App approves by writing: mutable://accounts/{appKey}/sessions/{sessionPubkey} = 1
+     * 3. Client calls this method with the session keypair
+     *
+     * @param appKey - The app's public key
+     * @param session - Session keypair (generated via generateSessionKeypair)
+     * @param credentials - User credentials (username/password)
      */
-    signupWithToken(appKey: string, tokenOrCredentials: string | UserCredentials, maybeCredentials?: UserCredentials): Promise<AuthSession>;
+    signupWithToken(appKey: string, session: SessionKeypair, credentials: UserCredentials): Promise<AuthSession>;
     /**
-     * Login with app token and session (scoped to an app)
+     * Login with session keypair (scoped to an app)
+     *
+     * The session must be approved by the app beforehand:
+     * 1. Client writes request to: immutable://inbox/{appKey}/sessions/{sessionPubkey} = 1
+     * 2. App approves by writing: mutable://accounts/{appKey}/sessions/{sessionPubkey} = 1
+     * 3. Client calls this method with the session keypair
+     *
+     * @param appKey - The app's public key
+     * @param session - Session keypair (generated via generateSessionKeypair)
+     * @param credentials - User credentials (username/password)
      */
-    loginWithTokenSession(appKey: string, tokenOrSession: string, sessionOrCredentials: string | UserCredentials, maybeCredentials?: UserCredentials): Promise<AuthSession>;
+    loginWithTokenSession(appKey: string, session: SessionKeypair, credentials: UserCredentials): Promise<AuthSession>;
     /**
      * Request password reset scoped to app token
      */
@@ -307,14 +421,27 @@ declare class WalletClient {
      * Proxy a write request through the wallet server
      * The server signs the write with its identity key
      * Requires active authentication session
+     *
+     * @returns ProxyWriteResponse - check `success` field for result
      */
     proxyWrite(request: ProxyWriteRequest): Promise<ProxyWriteResponse>;
     /**
      * Proxy a read request through the wallet server
      * The server decrypts encrypted data using user's encryption key
      * Requires active authentication session
+     *
+     * @returns ProxyReadResponse - check `success` field for result, `decrypted` for decrypted data
      */
     proxyRead(request: ProxyReadRequest): Promise<ProxyReadResponse>;
+    /**
+     * Proxy multiple read requests through the wallet server
+     * Reads multiple URIs in a single request (max 50 URIs)
+     * The server decrypts encrypted data using user's encryption key
+     * Requires active authentication session
+     *
+     * @returns ProxyReadMultiResponse - check `success` for overall result, `results` for per-URI results
+     */
+    proxyReadMulti(request: ProxyReadMultiRequest): Promise<ProxyReadMultiResponse>;
     /**
      * Convenience method: Get current user's public keys
      * Requires active authentication session
@@ -340,15 +467,27 @@ declare class WalletClient {
      */
     signupWithGoogle(appKey: string, token: string, googleIdToken: string): Promise<GoogleAuthSession>;
     /**
-     * Login with Google OAuth (scoped to app token and session)
+     * Login with Google OAuth (scoped to app token and session keypair)
      * Returns session data with Google profile info - call setSession() to activate it
      *
+     * The session must be approved by the app beforehand.
+     *
+     * @param appKey - The app's public key
      * @param token - App token from app server
-     * @param session - Session key from app server
+     * @param session - Session keypair (generated via generateSessionKeypair)
      * @param googleIdToken - Google ID token from Google Sign-In
      * @returns GoogleAuthSession with username, JWT token, and Google profile info
      */
-    loginWithGoogle(appKey: string, token: string, session: string, googleIdToken: string): Promise<GoogleAuthSession>;
+    loginWithGoogle(appKey: string, token: string, session: SessionKeypair, googleIdToken: string): Promise<GoogleAuthSession>;
 }
+/**
+ * Generate a new session keypair for authentication
+ * The public key should be registered with the app before login.
+ *
+ * Uses SDK crypto for consistent key generation across the codebase.
+ *
+ * @returns SessionKeypair with publicKeyHex and privateKeyHex
+ */
+declare function generateSessionKeypair(): Promise<SessionKeypair>;
 
-export { type AuthSession as A, type ChangePasswordResponse as C, type GoogleAuthSession as G, type HealthResponse as H, type LoginResponse as L, type PasswordResetToken as P, type RequestPasswordResetResponse as R, type SignupResponse as S, type UserCredentials as U, WalletClient as W, type UserPublicKeys as a, type ProxyWriteRequest as b, type ProxyWriteResponse as c, type ProxyReadRequest as d, type ProxyReadResponse as e, type WalletClientConfig as f, type ApiResponse as g, type PublicKeysResponse as h, type ResetPasswordResponse as i, type GoogleSignupResponse as j, type GoogleLoginResponse as k };
+export { type AuthSession as A, type ChangePasswordResponse as C, type GoogleAuthSession as G, type HealthResponse as H, type LoginResponse as L, type PasswordResetToken as P, type RequestPasswordResetResponse as R, type SessionKeypair as S, type UserCredentials as U, WalletClient as W, type UserPublicKeys as a, type ProxyWriteRequest as b, type ProxyWriteResponse as c, type ProxyReadRequest as d, type ProxyReadResponse as e, type ProxyReadMultiRequest as f, type ProxyReadMultiResponse as g, generateSessionKeypair as h, type WalletClientInterface as i, type WalletClientConfig as j, type ProxyReadMultiResultItem as k, type ApiResponse as l, type SignupResponse as m, type PublicKeysResponse as n, type ResetPasswordResponse as o, type GoogleSignupResponse as p, type GoogleLoginResponse as q };

package/dist/clients/http/mod.d.ts

@@ -1,4 +1,4 @@
-import { N as NodeProtocolInterface, a as HttpClientConfig, g as WriteResult, R as ReadResult, b as ListOptions, c as ListResult, D as DeleteResult, H as HealthStatus } from '../../types-oQCx3U-_.js';
+import { N as NodeProtocolInterface, a as HttpClientConfig, g as WriteResult, R as ReadResult, h as ReadMultiResult, b as ListOptions, c as ListResult, D as DeleteResult, H as HealthStatus } from '../../types-uuvn4oKw.js';
 
 /**
  * HttpClient - HTTP implementation of NodeProtocolInterface
@@ -23,6 +23,8 @@ declare class HttpClient implements NodeProtocolInterface {
     private parseUri;
     write<T = unknown>(uri: string, value: T): Promise<WriteResult<T>>;
     read<T = unknown>(uri: string): Promise<ReadResult<T>>;
+    readMulti<T = unknown>(uris: string[]): Promise<ReadMultiResult<T>>;
+    private readMultiFallback;
     list(uri: string, options?: ListOptions): Promise<ListResult>;
     delete(uri: string): Promise<DeleteResult>;
     health(): Promise<HealthStatus>;

package/dist/clients/http/mod.js

@@ -1,6 +1,6 @@
 import {
   HttpClient
-} from "../../chunk-LFUC4ETD.js";
+} from "../../chunk-OY4CDOHY.js";
 import "../../chunk-MLKGABMK.js";
 export {
   HttpClient

package/dist/clients/local-storage/mod.d.ts

@@ -1,4 +1,4 @@
-import { N as NodeProtocolInterface, d as LocalStorageClientConfig, g as WriteResult, R as ReadResult, b as ListOptions, c as ListResult, D as DeleteResult, H as HealthStatus } from '../../types-oQCx3U-_.js';
+import { N as NodeProtocolInterface, d as LocalStorageClientConfig, g as WriteResult, R as ReadResult, h as ReadMultiResult, b as ListOptions, c as ListResult, D as DeleteResult, H as HealthStatus } from '../../types-uuvn4oKw.js';
 
 /**
  * LocalStorageClient - Browser localStorage implementation of NodeProtocolInterface
@@ -34,6 +34,7 @@ declare class LocalStorageClient implements NodeProtocolInterface {
     private deserialize;
     write<T = unknown>(uri: string, value: T): Promise<WriteResult<T>>;
     read<T = unknown>(uri: string): Promise<ReadResult<T>>;
+    readMulti<T = unknown>(uris: string[]): Promise<ReadMultiResult<T>>;
     list(uri: string, options?: ListOptions): Promise<ListResult>;
     /**
      * Check if a URI has children (is a directory)

package/dist/clients/local-storage/mod.js

@@ -1,6 +1,6 @@
 import {
   LocalStorageClient
-} from "../../chunk-7U5JDFQW.js";
+} from "../../chunk-PZFEKQ7F.js";
 import "../../chunk-MLKGABMK.js";
 export {
   LocalStorageClient

package/dist/clients/memory/mod.d.ts

@@ -1,4 +1,4 @@
-import { S as Schema, N as NodeProtocolInterface, g as WriteResult, R as ReadResult, b as ListOptions, c as ListResult, H as HealthStatus, D as DeleteResult } from '../../types-oQCx3U-_.js';
+import { N as NodeProtocolInterface, S as Schema, g as WriteResult, R as ReadResult, h as ReadMultiResult, b as ListOptions, c as ListResult, H as HealthStatus, D as DeleteResult } from '../../types-uuvn4oKw.js';
 
 type MemoryClientStorageNode<T> = {
     value?: T;
@@ -6,20 +6,54 @@ type MemoryClientStorageNode<T> = {
 };
 type MemoryClientStorage = Map<string, MemoryClientStorageNode<unknown>>;
 interface MemoryClientConfig {
+    /**
+     * Schema mapping protocol://hostname to validators.
+     *
+     * Keys MUST be in format: "protocol://hostname"
+     * Examples: "mutable://accounts", "immutable://data", "mutable://open"
+     *
+     * @example
+     * ```typescript
+     * const schema = {
+     *   "mutable://accounts": async () => ({ valid: true }),
+     *   "immutable://accounts": async () => ({ valid: true }),
+     * };
+     * const client = new MemoryClient({ schema });
+     * ```
+     */
     schema: Schema;
     storage?: MemoryClientStorage;
 }
 declare class MemoryClient implements NodeProtocolInterface {
     protected storage: MemoryClientStorage;
     protected schema: Schema;
+    /**
+     * Create a new MemoryClient
+     *
+     * @param config - Configuration with schema mapping
+     * @throws Error if schema keys are not in "protocol://hostname" format
+     */
     constructor(config: MemoryClientConfig);
     write<T = unknown>(uri: string, payload: T): Promise<WriteResult<T>>;
     read<T>(uri: string): Promise<ReadResult<T>>;
+    readMulti<T = unknown>(uris: string[]): Promise<ReadMultiResult<T>>;
     list(uri: string, options?: ListOptions): Promise<ListResult>;
     health(): Promise<HealthStatus>;
     getSchema(): Promise<string[]>;
     cleanup(): Promise<void>;
     delete(uri: string): Promise<DeleteResult>;
 }
+/**
+ * Default schema for testing that accepts all writes.
+ * Includes common b3nd protocol prefixes.
+ *
+ * @example
+ * ```typescript
+ * import { MemoryClient, createTestSchema } from "@bandeira-tech/b3nd-web/clients/memory";
+ *
+ * const backend = new MemoryClient({ schema: createTestSchema() });
+ * ```
+ */
+declare function createTestSchema(): Schema;
 
-export { MemoryClient, type MemoryClientConfig };
+export { MemoryClient, type MemoryClientConfig, createTestSchema };

package/dist/clients/memory/mod.js

@@ -1,7 +1,9 @@
 import {
-  MemoryClient
-} from "../../chunk-GIMIWVPX.js";
+  MemoryClient,
+  createTestSchema
+} from "../../chunk-O53KW746.js";
 import "../../chunk-MLKGABMK.js";
 export {
-  MemoryClient
+  MemoryClient,
+  createTestSchema
 };

package/dist/clients/websocket/mod.d.ts

@@ -1,4 +1,4 @@
-import { N as NodeProtocolInterface, W as WebSocketClientConfig, g as WriteResult, R as ReadResult, b as ListOptions, c as ListResult, D as DeleteResult, H as HealthStatus } from '../../types-oQCx3U-_.js';
+import { N as NodeProtocolInterface, W as WebSocketClientConfig, g as WriteResult, R as ReadResult, h as ReadMultiResult, b as ListOptions, c as ListResult, D as DeleteResult, H as HealthStatus } from '../../types-uuvn4oKw.js';
 
 /**
  * WebSocketClient - WebSocket implementation of NodeProtocolInterface
@@ -52,6 +52,7 @@ declare class WebSocketClient implements NodeProtocolInterface {
     private sendRequest;
     write<T = unknown>(uri: string, value: T): Promise<WriteResult<T>>;
     read<T = unknown>(uri: string): Promise<ReadResult<T>>;
+    readMulti<T = unknown>(uris: string[]): Promise<ReadMultiResult<T>>;
     list(uri: string, options?: ListOptions): Promise<ListResult>;
     delete(uri: string): Promise<DeleteResult>;
     health(): Promise<HealthStatus>;

package/dist/clients/websocket/mod.js

@@ -1,6 +1,6 @@
 import {
   WebSocketClient
-} from "../../chunk-T43IWAQK.js";
+} from "../../chunk-UUHVOWVI.js";
 import "../../chunk-MLKGABMK.js";
 export {
   WebSocketClient

package/dist/{core-CgxQpSVM.d.ts → core-ClnuubZw.d.ts}

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { N as NodeProtocolInterface } from './types-oQCx3U-_.js';
+import { N as NodeProtocolInterface } from './types-uuvn4oKw.js';
 
 /**
  * Wallet Server Dependency Injection Interfaces
@@ -169,6 +169,7 @@ interface ProxyWriteResponse {
  */
 interface ProxyReadResponse {
     success: boolean;
+    uri?: string;
     error?: string;
     record?: {
         data: unknown;
@@ -268,7 +269,22 @@ declare class WalletServerCore {
     private normalizeApiBasePath;
     private readBootstrapState;
     private writeBootstrapState;
+    /**
+     * Validate that a session is approved by the app.
+     * Sessions are keypairs - the sessionPubkey is used directly as the identifier.
+     * App approves sessions by writing 1 to mutable://accounts/{appKey}/sessions/{sessionPubkey}
+     *
+     * @param appKey - The app's public key
+     * @param sessionPubkey - The session's public key (hex encoded)
+     * @returns { valid: true } if approved, { valid: false, reason } if not
+     */
     private sessionExists;
+    /**
+     * Verify that a login request signature is valid for the given session pubkey.
+     * The signature should be over the stringified login payload (without the signature field).
+     * Uses SDK crypto for consistent verification across the codebase.
+     */
+    private verifySessionSignature;
     private createApp;
 }
 

package/dist/src/mod.web.d.ts

@@ -1,7 +1,7 @@
-export { C as ClientError, D as DeleteResult, H as HealthStatus, a as HttpClientConfig, L as ListItem, b as ListOptions, c as ListResult, d as LocalStorageClientConfig, N as NodeProtocolInterface, P as PersistenceRecord, R as ReadResult, S as Schema, V as ValidationFn, W as WebSocketClientConfig, e as WebSocketRequest, f as WebSocketResponse, g as WriteResult } from '../types-oQCx3U-_.js';
+export { C as ClientError, D as DeleteResult, H as HealthStatus, a as HttpClientConfig, L as ListItem, b as ListOptions, c as ListResult, d as LocalStorageClientConfig, N as NodeProtocolInterface, P as PersistenceRecord, R as ReadResult, S as Schema, V as ValidationFn, W as WebSocketClientConfig, e as WebSocketRequest, f as WebSocketResponse, g as WriteResult } from '../types-uuvn4oKw.js';
 export { HttpClient } from '../clients/http/mod.js';
 export { WebSocketClient } from '../clients/websocket/mod.js';
 export { LocalStorageClient } from '../clients/local-storage/mod.js';
-export { W as WalletClient } from '../client-B0Ekm99R.js';
+export { W as WalletClient } from '../client-C4oQxiDu.js';
 export { AppsClient } from '../apps/mod.js';
 export { m as encrypt } from '../mod-CII9wqu2.js';

package/dist/src/mod.web.js

@@ -1,23 +1,23 @@
+import {
+  WebSocketClient
+} from "../chunk-UUHVOWVI.js";
 import {
   AppsClient
 } from "../chunk-VAZUCGED.js";
 import {
   WalletClient
-} from "../chunk-7O4D7SF6.js";
-import {
-  LocalStorageClient
-} from "../chunk-7U5JDFQW.js";
-import "../chunk-GIMIWVPX.js";
-import {
-  WebSocketClient
-} from "../chunk-T43IWAQK.js";
-import "../chunk-F3W5GZU6.js";
+} from "../chunk-GWPCZVXV.js";
+import "../chunk-B4VAPGAO.js";
 import {
   mod_exports
 } from "../chunk-JN75UL5C.js";
 import {
   HttpClient
-} from "../chunk-LFUC4ETD.js";
+} from "../chunk-OY4CDOHY.js";
+import {
+  LocalStorageClient
+} from "../chunk-PZFEKQ7F.js";
+import "../chunk-O53KW746.js";
 import "../chunk-MLKGABMK.js";
 export {
   AppsClient,

package/dist/{types-oQCx3U-_.d.ts → types-uuvn4oKw.d.ts}

@@ -25,6 +25,33 @@ interface ReadResult<T> {
     record?: PersistenceRecord<T>;
     error?: string;
 }
+/**
+ * Result for a single URI in a multi-read operation
+ */
+type ReadMultiResultItem<T = unknown> = {
+    uri: string;
+    success: true;
+    record: PersistenceRecord<T>;
+} | {
+    uri: string;
+    success: false;
+    error: string;
+};
+/**
+ * Result of reading multiple URIs in a single operation
+ */
+interface ReadMultiResult<T = unknown> {
+    /** true if at least one read succeeded */
+    success: boolean;
+    /** Per-URI results */
+    results: ReadMultiResultItem<T>[];
+    /** Summary statistics */
+    summary: {
+        total: number;
+        succeeded: number;
+        failed: number;
+    };
+}
 /**
  * Result of a delete operation
  */
@@ -109,6 +136,13 @@ interface NodeProtocolWriteInterface {
 interface NodeProtocolReadInterface {
     /** Read data from a URI */
     read<T = unknown>(uri: string): Promise<ReadResult<T>>;
+    /**
+     * Read multiple URIs in a single operation.
+     * Implementations may optimize for batch reads (e.g., SQL IN clause).
+     * @param uris - Array of URIs to read (max 50)
+     * @returns ReadMultiResult with per-URI results and summary
+     */
+    readMulti<T = unknown>(uris: string[]): Promise<ReadMultiResult<T>>;
     /** List items at a URI path */
     list(uri: string, options?: ListOptions): Promise<ListResult>;
     /** Health status */
@@ -206,7 +240,7 @@ declare class ClientError extends Error {
  */
 interface WebSocketRequest {
     id: string;
-    type: "write" | "read" | "list" | "delete" | "health" | "getSchema";
+    type: "write" | "read" | "readMulti" | "list" | "delete" | "health" | "getSchema";
     payload: unknown;
 }
 interface WebSocketResponse {
@@ -216,4 +250,4 @@ interface WebSocketResponse {
     error?: string;
 }
 
-export { ClientError as C, type DeleteResult as D, type HealthStatus as H, type ListItem as L, type NodeProtocolInterface as N, type PersistenceRecord as P, type ReadResult as R, type Schema as S, type ValidationFn as V, type WebSocketClientConfig as W, type HttpClientConfig as a, type ListOptions as b, type ListResult as c, type LocalStorageClientConfig as d, type WebSocketRequest as e, type WebSocketResponse as f, type WriteResult as g };
+export { ClientError as C, type DeleteResult as D, type HealthStatus as H, type ListItem as L, type NodeProtocolInterface as N, type PersistenceRecord as P, type ReadResult as R, type Schema as S, type ValidationFn as V, type WebSocketClientConfig as W, type HttpClientConfig as a, type ListOptions as b, type ListResult as c, type LocalStorageClientConfig as d, type WebSocketRequest as e, type WebSocketResponse as f, type WriteResult as g, type ReadMultiResult as h };