@calimero-network/mero-js 26.11.0 → 27.0.0

package/dist/login/session.js

@@ -1,141 +0,0 @@
-/**
- * Obtain a session on a node using only a device key — the handshake around
- * {@link signLoginStatement}.
- *
- * Signing a statement was never the whole job. A client also has to fetch a
- * challenge, mint a session keypair, assemble a request body whose shape it
- * cannot see from here, and read a token out of the reply. Until now every
- * consumer wrote those two HTTP calls by hand, which is how the same three
- * mistakes kept being available to make:
- *
- * 1. **Asking for permissions.** `POST /auth/token` takes an optional
- *    `permissions` list. Left unset, the node grants the account-proof
- *    provider's own scopes — `context:intent`, `context:query`,
- *    `context:subscribe` — which are the whole delegated surface and
- *    deliberately nothing above it. This module never sends the field.
- *    `authenticate()` in this same package hardcodes `['admin']` (#84); a
- *    device-key session would be refused for that and should never ask.
- * 2. **Learning the node's key from the node.** {@link LoginConfig.node} is
- *    required and has no default, because a value read from the challenge
- *    response would let whoever answered choose what the device signs about.
- *    That is the whole attack the field exists to stop, so the awkwardness of
- *    having to supply it is the point rather than something to smooth away.
- * 3. **Losing the refresh token.** A browser tab outlives a short-lived
- *    session, so both tokens are returned. Nothing here refreshes on a timer
- *    (#87, #88 track that); this only makes it possible without a second
- *    breaking change.
- *
- * **The session key never leaves.** It is minted here, the device key signs
- * over it once, and the secret half is handed back to the caller. That is what
- * keeps a device key off the wire for the life of a session: a leaked token
- * cannot be escalated into use of the key that authorised it.
- */
-import { HTTPError } from '../http-client/web-client.js';
-import { derivePublicKey, hex } from '../crypto/internal.js';
-import { signLoginStatement } from './login.js';
-import { resolveSigner } from '../signer/signer.js';
-/** Seconds a statement stays valid unless told otherwise. */
-const DEFAULT_TTL_SECONDS = 300;
-/**
- * Mint the ephemeral keypair a session speaks with.
- *
- * An ed25519 secret *is* 32 random bytes, so this needs no key generation
- * ceremony — `getRandomValues` and the same derivation every other signer here
- * uses. Exported because a caller that wants to persist a session across a page
- * reload needs to mint the pair itself and keep the secret.
- */
-export async function generateSessionKey() {
-    const secret = hex(crypto.getRandomValues(new Uint8Array(32)));
-    return { publicKey: hex(await derivePublicKey(secret)), secret };
-}
-/**
- * Log in with a device key and return the session.
- *
- * The challenge is fetched immediately before signing on purpose: it is
- * single-use and short-lived, so a statement minted against a stale one is
- * refused before any signature work is done.
- *
- * @throws {HTTPError} if the node refuses the challenge or the token request.
- */
-export async function login(config) {
-    const baseUrl = config.nodeUrl.replace(/\/+$/, '');
-    const timeoutMs = config.timeoutMs ?? 10000;
-    const request = async (path, init) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
-        let response;
-        try {
-            // Called as `globalThis.fetch(...)`, never through a detached reference:
-            // a browser's fetch throws "Illegal invocation" when its receiver is lost.
-            const requestInit = { ...init, signal: controller.signal };
-            response = config.fetch
-                ? await config.fetch(`${baseUrl}${path}`, requestInit)
-                : await globalThis.fetch(`${baseUrl}${path}`, requestInit);
-        }
-        catch (err) {
-            throw new HTTPError(0, err instanceof Error ? err.name : 'NetworkError', `${baseUrl}${path}`, new Headers(), err instanceof Error ? err.message : String(err));
-        }
-        finally {
-            clearTimeout(timer);
-        }
-        const text = await response.text().catch(() => '');
-        if (!response.ok) {
-            throw new HTTPError(response.status, response.statusText, `${baseUrl}${path}`, response.headers, text);
-        }
-        return text ? JSON.parse(text) : {};
-    };
-    const challengeBody = (await request('/auth/challenge', {
-        method: 'GET',
-        headers: { Accept: 'application/json' },
-    }));
-    // The node has spelled this both bare and wrapped in `data`; accept either
-    // rather than couple a login to one envelope revision.
-    const challenge = challengeBody.challenge ?? challengeBody.data?.challenge;
-    if (!challenge) {
-        throw new Error('the node issued no challenge');
-    }
-    const session = await generateSessionKey();
-    const issuedAt = Math.floor(Date.now() / 1000);
-    const statement = await signLoginStatement({
-        node: config.node,
-        audience: config.audience,
-        challenge,
-        sessionKey: session.publicKey,
-        issuedAt,
-        expiresAt: issuedAt + (config.ttlSeconds ?? DEFAULT_TTL_SECONDS),
-        // Resolved once and handed on, so a config carrying a secret and a config
-        // carrying a `CryptoKey` take exactly the same path from here down.
-        signer: await resolveSigner(config.deviceSecret, config.signer, 'deviceSecret'),
-    });
-    // `timestamp` is required and the request refuses unknown fields, so a body
-    // missing it is rejected during deserialization — before the provider runs,
-    // and with an error that names the request shape rather than the login.
-    //
-    // `permissions` is omitted, not empty: see the module note.
-    const tokenBody = (await request('/auth/token', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-        body: JSON.stringify({
-            auth_method: 'account_proof',
-            public_key: session.publicKey,
-            client_name: config.clientName ?? baseUrl,
-            timestamp: issuedAt,
-            provider_data: {
-                challenge,
-                login_statement: statement,
-                account_proof: config.accountProof,
-            },
-        }),
-    }));
-    const accessToken = tokenBody.access_token ?? tokenBody.data?.access_token;
-    const refreshToken = tokenBody.refresh_token ?? tokenBody.data?.refresh_token;
-    if (!accessToken) {
-        throw new Error('the node minted no session');
-    }
-    return {
-        accessToken,
-        refreshToken: refreshToken ?? '',
-        sessionKey: session.publicKey,
-        sessionSecret: session.secret,
-    };
-}

package/dist/mero-js.d.ts

@@ -1,231 +0,0 @@
-import type { AuthApiClient } from './auth-api/index.js';
-import type { AdminApiClient } from './admin-api/index.js';
-import type { TokenStore } from './token-store/index.js';
-import type { ProofRequest, ProofSignerOptions } from './request/index.js';
-import type { AuthCallbackResult, AuthLoginOptions, ParseAuthCallbackOptions } from './auth/index.js';
-import { RpcClient } from './rpc/index.js';
-import { SseClient } from './events/sse.js';
-import { WsClient } from './events/ws.js';
-import { EphemeralClient } from './ephemeral/index.js';
-import { CloudClient } from './cloud/cloud-client.js';
-import type { CloudClientConfig } from './cloud/cloud-client.js';
-export interface MeroJsConfig {
-    /** Base URL for the Calimero node */
-    baseUrl: string;
-    /** Initial credentials for authentication */
-    credentials?: {
-        username: string;
-        password: string;
-    };
-    /** Custom HTTP client timeout in milliseconds */
-    timeoutMs?: number;
-    /** Request credentials mode for fetch (omit, same-origin, include) */
-    requestCredentials?: RequestCredentials;
-    /** Custom fetch for every HTTP request (`auth`, `admin`, `rpc`, `events`). Defaults to global `fetch`. */
-    fetch?: typeof fetch;
-    /** Optional token store for persistence */
-    tokenStore?: TokenStore;
-    /**
-     * Called when the node reports that the credential family is gone
-     * (`x-auth-error: token_reuse` / `token_revoked`). Terminal: the tokens have
-     * already been cleared by the time this runs and nothing is retried, so use it
-     * to send the user back through login. Errors thrown here are swallowed —
-     * never let a UI failure mask the auth error.
-     */
-    onAuthRevoked?: () => Promise<void> | void;
-    /**
-     * Calimero Cloud, reachable as `sdk.cloud`.
-     *
-     * A node connection and a cloud account are separate things a client can have
-     * either of, both of, or neither — a desktop app with a local node and a
-     * cloud subscription has both, and needs them from one object. So this is
-     * configuration on the existing SDK rather than a second SDK: pass the
-     * session token (or none, and sign in through `sdk.cloud`) and the node half
-     * is unaffected.
-     *
-     * For a caller with *no* node at all, `connectCloud` is the entry point
-     * instead — it returns a connection that can write without one.
-     */
-    cloud?: CloudClientConfig;
-    /**
-     * Sign every request with a device key, instead of or alongside a session.
-     *
-     * A session is a bearer token: obtained once, presented many times. A
-     * request-carried proof commits to one method, one path and one body, so it
-     * is minted per call and cannot be lifted onto another request. It is what
-     * lets a client talk to a relay it has no account on — nothing was ever
-     * issued to it.
-     *
-     * Pass the keys and let the SDK mint each proof:
-     *
-     * ```ts
-     * new MeroJs({
-     *   baseUrl,
-     *   requestProof: { credential, session, signerSecret },
-     * });
-     * ```
-     *
-     * …or pass your own signer, when the key must not reach the SDK at all — a
-     * hardware token, or a worker that holds it:
-     *
-     * ```ts
-     * new MeroJs({ baseUrl, requestProof: (req) => myWorker.sign(req) });
-     * ```
-     *
-     * The node only honours this when it runs with `--delegated-access`; a node
-     * that does not answers `403`, which is distinct from the `401` a bad proof
-     * gets.
-     *
-     * Applies to the request/response API. `events` (SSE) and `ws` are long-lived
-     * connections rather than requests, so a per-request signature does not
-     * describe them — they still use the session.
-     */
-    requestProof?: ProofSignerOptions | ((request: ProofRequest) => Promise<string | undefined>);
-}
-export interface TokenData {
-    access_token: string;
-    refresh_token: string;
-    expires_at: number;
-    /** Origin and path prefix of the issuing node; a store entry for another node is ignored. */
-    node_origin?: string;
-}
-/**
- * Main MeroJs SDK class that manages all API clients and authentication
- */
-export declare class MeroJs {
-    private config;
-    private httpClient;
-    private authClient;
-    private adminClient;
-    private tokenData;
-    private refreshPromise;
-    private tokenStore;
-    private storeHoldsTokens;
-    private tokenGeneration;
-    private readonly onStorage;
-    private readonly nodeKey;
-    private rpcClient;
-    private sseClient;
-    private wsClient;
-    private wsWarned;
-    private ephemeralClient?;
-    private cloudClient?;
-    constructor(config: MeroJsConfig);
-    /**
-     * Get the Auth API client
-     */
-    get auth(): AuthApiClient;
-    /**
-     * Get the Admin API client
-     */
-    get admin(): AdminApiClient;
-    /**
-     * Get the RPC client (lazy initialized)
-     */
-    get rpc(): RpcClient;
-    /**
-     * Get the SSE event client (lazy initialized)
-     */
-    get events(): SseClient;
-    /**
-     * Get the ephemeral-presence client (lazy initialized).
-     *
-     * Shares this instance's SSE client, so `subscribe` reuses the one event
-     * stream rather than opening a second connection.
-     */
-    get ephemeral(): EphemeralClient;
-    /**
-     * Calimero Cloud (lazy initialized).
-     *
-     * Available whether or not `cloud` was configured — an app that signs in
-     * later gets an unauthenticated client it can call `signInWithGoogle` on,
-     * which is one fewer construction path than making the getter conditional.
-     * It is entirely independent of this instance's node credential: the cloud
-     * knows nothing about the node's tokens and the node knows nothing about the
-     * cloud session.
-     */
-    get cloud(): CloudClient;
-    /**
-     * Get the WebSocket event client (lazy initialized).
-     * @experimental Use `events` (SSE) for production. WsClient is experimental.
-     */
-    get ws(): WsClient;
-    /**
-     * Authenticate with the provided credentials
-     * This will create the root key on first use
-     */
-    authenticate(credentials?: {
-        username: string;
-        password: string;
-    }): Promise<TokenData>;
-    private persistTokens;
-    /** The stored bundle, only if this node issued it; a legacy or foreign entry reads as empty. */
-    private readStoredTokens;
-    private signedOutElsewhere;
-    private dropLocalTokens;
-    /**
-     * Get a valid token. Returns the current token as-is.
-     * The server rejects refresh attempts while the access token is still valid,
-     * so we never proactively refresh. Instead, the WebHttpClient handles 401
-     * responses reactively via the refreshToken transport hook.
-     */
-    private getValidToken;
-    /**
-     * Refresh the access token. Single-flight: every caller (including the HTTP
-     * transport's 401 hook) goes through here.
-     *
-     * Refresh tokens are single-use (calimero-network/core#3083): each refresh
-     * consumes the presented token and returns a new one, and replaying a consumed
-     * token makes the server revoke the whole family. A refresh must therefore
-     * happen exactly once per rotation, which needs three layers:
-     *  - an in-process promise, so concurrent 401s in this instance share one call;
-     *  - a Web Lock (when available), so other tabs/webviews don't refresh at the
-     *    same time on the same stored token;
-     *  - a re-read of the token store inside the lock, so a bundle that another
-     *    instance already rotated is adopted instead of replaying a stale token.
-     */
-    private performTokenRefresh;
-    /**
-     * Run `fn` under the refresh lock: the token store's own (shared across
-     * processes), else the cross-tab Web Lock, else directly.
-     */
-    private withRefreshLock;
-    /**
-     * Perform the actual token refresh. Runs with the refresh lock held.
-     */
-    private performTokenRefreshLocked;
-    /**
-     * Clear the current token
-     */
-    clearToken(): void;
-    /**
-     * Check if the SDK is authenticated
-     */
-    isAuthenticated(): boolean;
-    /**
-     * Set token data directly (e.g., from auth callback).
-     * If `expires_at` is missing or 0, attempts to parse the JWT exp claim,
-     * falling back to 1 hour from now.
-     */
-    setTokenData(data: TokenData): void;
-    /**
-     * Get the current token data (for debugging)
-     */
-    getTokenData(): TokenData | null;
-    /**
-     * Close all event connections and clean up resources
-     */
-    close(): void;
-    /**
-     * Parse an auth callback URL hash fragment (static utility)
-     */
-    static parseAuthCallback(url: string, options?: ParseAuthCallbackOptions): AuthCallbackResult | null;
-    /**
-     * Build an auth login URL (static utility)
-     */
-    static buildAuthLoginUrl(nodeUrl: string, opts: AuthLoginOptions): string;
-}
-/**
- * Create a new MeroJs SDK instance
- */
-export declare function createMeroJs(config: MeroJsConfig): MeroJs;