@calimero-network/mero-js 19.2.0 → 19.4.0

package/dist/login/index.d.ts

@@ -0,0 +1,4 @@
+export { signLoginStatement } from './login.js';
+export type { Audience, LoginStatementInput } from './login.js';
+export { login, generateSessionKey } from './session.js';
+export type { LoginConfig, DelegatedSession, SessionKeyPair, } from './session.js';

package/dist/login/index.js

@@ -0,0 +1,3 @@
+// Login-statement signing — the device's half of a password-free session
+export { signLoginStatement } from './login.js';
+export { login, generateSessionKey } from './session.js';

package/dist/login/login.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Sign the statement a device key presents to obtain a session on a node.
+ *
+ * This is the half of password-free login that has to run where the device key
+ * lives, and for the case delegated execution exists for that is a browser tab.
+ * Until this module, the only thing that could produce a login statement was
+ * `merod account login-statement` — which is to say, a client had to hold a node
+ * to ask a node for a session.
+ *
+ * **What this gets you, and what it does not.** A statement proves a device key
+ * asked for this session. It says nothing about which account that device
+ * belongs to: that is the `AccountProof` travelling beside it, which the node
+ * checks separately. Signing here and presenting no proof gets a 401 that looks
+ * exactly like a bad signature.
+ *
+ * **The session key is minted by the caller, not here.** The device key signs
+ * once, over a short-lived key the caller generates and keeps; that key does the
+ * talking for the rest of the session, which is what keeps the device key off
+ * the wire. Passing a key you do not hold the private half of produces a session
+ * you cannot speak on.
+ *
+ * **`node` must come from something you pinned.** Not from the challenge
+ * response, and not from any field the node itself chose — an attacker who can
+ * answer on the node's behalf would otherwise pick what your device signs about,
+ * which is the whole reason the field exists. Read it out of band from the node
+ * operator.
+ *
+ * **The byte contract is pinned in core**, at
+ * `crates/account/src/tests/login_wire_fixture.rs`, for the same reason the
+ * warrant one is: `AUTH_LOGIN_SIGN_DOMAIN` is `pub(crate)` there and the field
+ * order is implicit in a `derive`, so nothing on that side forces anyone to
+ * notice this file depends on both. This module's test asserts the same vectors.
+ */
+/**
+ * The client surface a session is bound to.
+ *
+ * A session minted for one surface cannot be presented from another, so a single
+ * compromised surface does not yield sessions usable everywhere.
+ */
+export type Audience = {
+    /**
+     * A browser origin, spelled exactly as the browser spells it
+     * (`https://host:port`, no trailing slash).
+     *
+     * Compared byte for byte by the node. Do not normalize it here: two
+     * spellings of one origin would mean a verifier that disagrees with the
+     * browser about which one a token was for. `location.origin` is already
+     * the spelling you want.
+     */
+    kind: 'webOrigin';
+    origin: string;
+} | {
+    /** A signed native client, named by its code-signing identity. */
+    kind: 'codeSigningId';
+    id: string;
+} | {
+    /**
+     * A command-line client, which has no origin and no signing identity.
+     *
+     * Carries no payload deliberately: a string here would be an audience that
+     * binds nothing while looking like it binds something.
+     */
+    kind: 'cli';
+};
+/** What a device is asking for. */
+export interface LoginStatementInput {
+    /**
+     * The node this session is for, hex (32 bytes) — its identity public key, as
+     * you pinned it. See the module note: this must not come from the node.
+     */
+    node: string;
+    /** The client surface the session is bound to. */
+    audience: Audience;
+    /** The challenge this node issued, hex (32 bytes). Proves freshness. */
+    challenge: string;
+    /**
+     * The public half of the ephemeral key this session will speak with, hex (32
+     * bytes). Minted per session by the caller and thrown away with it.
+     */
+    sessionKey: string;
+    /** Unix seconds at signing. */
+    issuedAt: number | bigint;
+    /** Unix seconds after which the node must refuse it. */
+    expiresAt: number | bigint;
+    /**
+     * The device's ed25519 signing secret, hex (32 bytes).
+     *
+     * Never sent anywhere. It signs locally and only the signature travels, which
+     * is what lets a statement be minted by something holding no node.
+     */
+    deviceSecret: string;
+}
+/**
+ * Sign a login statement and return it hex-encoded, ready to present with an
+ * account proof.
+ *
+ * Returns the encoding rather than an object for the reason `signWarrant` does:
+ * the signature covers exactly these bytes, and a caller that rebuilt the fields
+ * from JSON would have a second spelling able to disagree with what was signed.
+ */
+export declare function signLoginStatement(input: LoginStatementInput): Promise<string>;

package/dist/login/login.js

@@ -0,0 +1,109 @@
+/**
+ * Sign the statement a device key presents to obtain a session on a node.
+ *
+ * This is the half of password-free login that has to run where the device key
+ * lives, and for the case delegated execution exists for that is a browser tab.
+ * Until this module, the only thing that could produce a login statement was
+ * `merod account login-statement` — which is to say, a client had to hold a node
+ * to ask a node for a session.
+ *
+ * **What this gets you, and what it does not.** A statement proves a device key
+ * asked for this session. It says nothing about which account that device
+ * belongs to: that is the `AccountProof` travelling beside it, which the node
+ * checks separately. Signing here and presenting no proof gets a 401 that looks
+ * exactly like a bad signature.
+ *
+ * **The session key is minted by the caller, not here.** The device key signs
+ * once, over a short-lived key the caller generates and keeps; that key does the
+ * talking for the rest of the session, which is what keeps the device key off
+ * the wire. Passing a key you do not hold the private half of produces a session
+ * you cannot speak on.
+ *
+ * **`node` must come from something you pinned.** Not from the challenge
+ * response, and not from any field the node itself chose — an attacker who can
+ * answer on the node's behalf would otherwise pick what your device signs about,
+ * which is the whole reason the field exists. Read it out of band from the node
+ * operator.
+ *
+ * **The byte contract is pinned in core**, at
+ * `crates/account/src/tests/login_wire_fixture.rs`, for the same reason the
+ * warrant one is: `AUTH_LOGIN_SIGN_DOMAIN` is `pub(crate)` there and the field
+ * order is implicit in a `derive`, so nothing on that side forces anyone to
+ * notice this file depends on both. This module's test asserts the same vectors.
+ */
+import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+const SIGN_DOMAIN = new TextEncoder().encode('calimero.auth.login.v1');
+/** The borsh enum tag for each variant, in core's declaration order. */
+const AUDIENCE_TAG = {
+    webOrigin: 0,
+    codeSigningId: 1,
+    cli: 2,
+};
+/** The variant's payload as UTF-8 — empty for the payload-free `cli`. */
+function audienceBody(audience) {
+    const encoder = new TextEncoder();
+    switch (audience.kind) {
+        case 'webOrigin':
+            return encoder.encode(audience.origin);
+        case 'codeSigningId':
+            return encoder.encode(audience.id);
+        case 'cli':
+            return new Uint8Array(0);
+    }
+}
+/**
+ * What the audience contributes to the **signing preimage**: tag then body, with
+ * no length between them.
+ *
+ * `domainHash` length-prefixes every part it is handed, so a length written here
+ * would be counted twice and the preimage would verify nowhere. This is the one
+ * field spelled differently in the two encodings — see {@link audienceWire}.
+ */
+function audienceSigningBytes(audience) {
+    return concat(Uint8Array.from([AUDIENCE_TAG[audience.kind]]), audienceBody(audience));
+}
+/**
+ * What the audience contributes to the **wire encoding**: the borsh enum tag,
+ * then for the two payload-carrying variants a borsh `String` — its own `u32`
+ * little-endian length, then the UTF-8.
+ *
+ * `cli` is a bare tag. Writing a `u32` zero after it instead produces four extra
+ * bytes that a node reads as the start of the challenge, so the statement fails
+ * as a bad signature rather than as a malformed one.
+ */
+function audienceWire(audience) {
+    const tag = Uint8Array.from([AUDIENCE_TAG[audience.kind]]);
+    if (audience.kind === 'cli') {
+        return tag;
+    }
+    const body = audienceBody(audience);
+    return concat(tag, u32le(body.length), body);
+}
+/**
+ * Sign a login statement and return it hex-encoded, ready to present with an
+ * account proof.
+ *
+ * Returns the encoding rather than an object for the reason `signWarrant` does:
+ * the signature covers exactly these bytes, and a caller that rebuilt the fields
+ * from JSON would have a second spelling able to disagree with what was signed.
+ */
+export async function signLoginStatement(input) {
+    const node = fromHex(input.node, 'node', 32);
+    const challenge = fromHex(input.challenge, 'challenge', 32);
+    const sessionKey = fromHex(input.sessionKey, 'sessionKey', 32);
+    const key = await importSigningKey(input.deviceSecret);
+    const deviceKey = await derivePublicKey(input.deviceSecret);
+    const issuedAt = u64le(input.issuedAt);
+    const expiresAt = u64le(input.expiresAt);
+    const preimage = await domainHash(SIGN_DOMAIN, [
+        node,
+        audienceSigningBytes(input.audience),
+        challenge,
+        sessionKey,
+        deviceKey,
+        issuedAt,
+        expiresAt,
+    ]);
+    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    return hex(concat(node, audienceWire(input.audience), challenge, sessionKey, deviceKey, issuedAt, expiresAt, signature));
+}

package/dist/login/session.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 { type Audience } from './login.js';
+/** A freshly minted ephemeral keypair, hex-encoded. */
+export interface SessionKeyPair {
+    /** The public half — what the statement is signed over. */
+    publicKey: string;
+    /** The private half. Held by the caller; never sent anywhere. */
+    secret: string;
+}
+/**
+ * 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 declare function generateSessionKey(): Promise<SessionKeyPair>;
+/** What a device needs in order to ask for a session. */
+export interface LoginConfig {
+    /** The node's base URL, e.g. `https://node.example`. */
+    nodeUrl: string;
+    /**
+     * The node's device signing key, hex (32 bytes), **as this client pinned it**.
+     *
+     * Learn it out of band — from the node's operator, or a certificate you
+     * already trust. Never from the node you are about to log in to: see the
+     * module note.
+     */
+    node: string;
+    /** The device's ed25519 signing secret, hex (32 bytes). Never sent. */
+    deviceSecret: string;
+    /**
+     * The device's account proof, hex — the credential certifying that this
+     * device belongs to its account.
+     *
+     * Travels beside the statement and is what settles *which account* is asking.
+     * The statement alone proves only that a device key asked, so logging in
+     * without this yields a 401 that looks exactly like a bad signature.
+     */
+    accountProof: string;
+    /** The client surface this session is bound to. */
+    audience: Audience;
+    /**
+     * How this client names itself to the node. Defaults to the audience's own
+     * spelling, which is the honest answer: a session bound to an origin should
+     * say that origin.
+     */
+    clientName?: string;
+    /** Seconds the statement stays valid. Defaults to {@link DEFAULT_TTL_SECONDS}. */
+    ttlSeconds?: number;
+    /** Injectable for tests and non-browser runtimes. */
+    fetch?: typeof fetch;
+    /** Per-request timeout. Defaults to 10s. */
+    timeoutMs?: number;
+}
+/** A session minted without a password. */
+export interface DelegatedSession {
+    /** Bearer token for the delegated surface. */
+    accessToken: string;
+    /** Presented to renew the access token. See #87/#88 — nothing here schedules it. */
+    refreshToken: string;
+    /** The session's public half, as the node knows it. */
+    sessionKey: string;
+    /** The session's private half. The caller keeps this; it was never sent. */
+    sessionSecret: string;
+}
+/**
+ * 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 declare function login(config: LoginConfig): Promise<DelegatedSession>;

package/dist/login/session.js

@@ -0,0 +1,148 @@
+/**
+ * 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';
+/** 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 };
+}
+/** The audience's own spelling, used as the default client name. */
+function audienceLabel(audience) {
+    switch (audience.kind) {
+        case 'webOrigin':
+            return audience.origin;
+        case 'codeSigningId':
+            return audience.id;
+        case 'cli':
+            return 'cli';
+    }
+}
+/**
+ * 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 doFetch = config.fetch ?? globalThis.fetch;
+    const timeoutMs = config.timeoutMs ?? 10000;
+    const request = async (path, init) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await doFetch(`${baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+            });
+        }
+        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),
+        deviceSecret: config.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 ?? audienceLabel(config.audience),
+            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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "19.2.0",
+  "version": "19.4.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {