@calimero-network/mero-js 19.8.0 → 19.9.0

package/dist/account/account.d.ts

@@ -74,3 +74,28 @@ export interface AccountLinkInput {
  * serve.
  */
 export declare function signAccountLink(input: AccountLinkInput): Promise<string>;
+/** What {@link signAccountLogin} needs. */
+export interface AccountLoginInput {
+    /** The account root's signing secret, 64 hex. */
+    rootSecret: string;
+    /** The challenge from `GET /api/auth/account/challenge`, verbatim UTF-8. */
+    nonce: string;
+}
+/**
+ * Sign a cloud login challenge with the account root. Returns base64.
+ *
+ * The statement this makes is *"I hold the root of account X"*, and it is the
+ * one statement a device credential can never make. A routing read proves the
+ * caller holds a device the root certified — the credential carries the root's
+ * signature over that device — but a certificate is public and travels in the
+ * clear inside every device-link op, so anyone who has seen one can say "a
+ * device of X is asking". Only the root can say the account is theirs.
+ *
+ * Which is why this is worth doing **once**: the cloud records the claim, and
+ * from then on it knows the account behind a device proof was proven by its
+ * owner. The session it also mints is the ordinary MDMA session token, accepted
+ * everywhere a Google-issued one is.
+ *
+ * Standard base64, not base64url — mdma decodes with `validate=True`.
+ */
+export declare function signAccountLogin(input: AccountLoginInput): Promise<string>;

package/dist/account/index.d.ts

@@ -1,2 +1,2 @@
-export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, } from './account.js';
-export type { AccountRoot, RecoverableAccountRoot, AccountLinkInput, } from './account.js';
+export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, signAccountLogin, } from './account.js';
+export type { AccountRoot, RecoverableAccountRoot, AccountLinkInput, AccountLoginInput, } from './account.js';

package/dist/account/index.js

@@ -1,2 +1,2 @@
 // Account roots — minting one, restoring it from a phrase, and proving you hold it.
-export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, } from './account.js';
+export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, signAccountLogin, } from './account.js';

package/dist/cloud/cloud-client.d.ts

@@ -240,6 +240,28 @@ export interface AccountLinkProof {
     /** `signAccountLink`'s output — standard base64. */
     signature: string;
 }
+/** A single-use challenge for an account root to sign itself in with. */
+export interface AccountLoginChallenge {
+    /** Sign this verbatim. Opaque and sealed by the cloud; nonces live ~2 minutes. */
+    nonce: string;
+    /** When it stops being accepted, epoch milliseconds. */
+    expiresAtMs: number;
+}
+/** A proof assembled by whoever holds the root, for {@link CloudClient.submitAccountLogin}. */
+export interface AccountLoginProof {
+    /**
+     * The root that names the account, 64 hex.
+     *
+     * No `accountId` field, unlike {@link AccountLinkProof}: the cloud derives
+     * the account from this key rather than accepting one alongside it, so there
+     * is nothing a caller could state that the signature would then contradict.
+     */
+    rootPublicKey: string;
+    /** The challenge that was signed. */
+    nonce: string;
+    /** `signAccountLogin`'s output — standard base64. */
+    signature: string;
+}
 /** The outcome of {@link CloudClient.linkAccount}. */
 export interface CloudAccountLink {
     accountId: string;
@@ -282,6 +304,45 @@ export declare class CloudClient {
      * be kept or re-minted per call.
      */
     signInWithGoogle(idToken: string): Promise<CloudSession>;
+    /**
+     * Sign in as a Calimero account, proving it with its root key.
+     *
+     * The password-free counterpart to {@link signInWithGoogle}: no Google, no
+     * password, no server-held secret — the cloud mints a challenge, the account
+     * root signs it, and the session that comes back is the same MDMA session
+     * token every other cloud route already accepts.
+     *
+     * Doing this **once** is what makes an account's later device proofs mean
+     * something. A routing read shows that the caller holds a device the root
+     * certified, but certificates are public, so it can never show that anyone
+     * held the root; the cloud records this claim and from then on knows the
+     * account behind those reads was claimed by its owner. The claim is recorded
+     * even when the session is refused.
+     *
+     * @param rootSecret the account root's signing secret, 64 hex. It never
+     *   leaves this process — only a signature over the cloud's nonce travels.
+     *
+     * A `403` means either the signature did not verify, or the account is not
+     * linked to a cloud login: ownership alone says who you are, and the link
+     * says what you are entitled to. Anyone can mint a root offline, so a session
+     * on the proof alone would authenticate perfectly and authorize nothing. The
+     * ownership claim is recorded either way, so linking later needs no re-proof.
+     */
+    signInWithAccount(rootSecret: string): Promise<CloudSession>;
+    /**
+     * Mint a challenge for an account root to sign.
+     *
+     * Public, and deliberately so: the caller has no session — obtaining one is
+     * what this exchange does. The nonce is not a capability, it is the thing a
+     * capability gets demonstrated against, and demonstrating it needs the root.
+     *
+     * Split out of {@link signInWithAccount} for the case that call cannot serve:
+     * a root held by a hardware key, a desktop app or an air-gapped machine,
+     * which signs without the secret ever reaching this process.
+     */
+    getAccountLoginChallenge(): Promise<AccountLoginChallenge>;
+    /** Post a proof assembled elsewhere. The other half of {@link getAccountLoginChallenge}. */
+    submitAccountLogin(proof: AccountLoginProof): Promise<CloudSession>;
     /**
      * Refresh the session token explicitly.
      *

package/dist/cloud/cloud-client.js

@@ -24,7 +24,7 @@
  * ever sent, and would be a throughput bottleneck on a path that has no reason
  * to involve it.
  */
-import { accountRootFromSecret, signAccountLink, } from '../account/index.js';
+import { accountRootFromSecret, signAccountLink, signAccountLogin, } from '../account/index.js';
 import { HTTPError } from '../http-client/web-client.js';
 import { routingProofHeaders, } from './routing-proof.js';
 /** Where the hosted cloud lives when a caller names no other. */
@@ -77,6 +77,66 @@ export class CloudClient {
         const body = await this.request('POST', '/api/auth/google', { body: { id_token: idToken }, anonymous: true });
         return this.adoptSession(body);
     }
+    /**
+     * Sign in as a Calimero account, proving it with its root key.
+     *
+     * The password-free counterpart to {@link signInWithGoogle}: no Google, no
+     * password, no server-held secret — the cloud mints a challenge, the account
+     * root signs it, and the session that comes back is the same MDMA session
+     * token every other cloud route already accepts.
+     *
+     * Doing this **once** is what makes an account's later device proofs mean
+     * something. A routing read shows that the caller holds a device the root
+     * certified, but certificates are public, so it can never show that anyone
+     * held the root; the cloud records this claim and from then on knows the
+     * account behind those reads was claimed by its owner. The claim is recorded
+     * even when the session is refused.
+     *
+     * @param rootSecret the account root's signing secret, 64 hex. It never
+     *   leaves this process — only a signature over the cloud's nonce travels.
+     *
+     * A `403` means either the signature did not verify, or the account is not
+     * linked to a cloud login: ownership alone says who you are, and the link
+     * says what you are entitled to. Anyone can mint a root offline, so a session
+     * on the proof alone would authenticate perfectly and authorize nothing. The
+     * ownership claim is recorded either way, so linking later needs no re-proof.
+     */
+    async signInWithAccount(rootSecret) {
+        const root = await accountRootFromSecret(rootSecret);
+        const { nonce } = await this.getAccountLoginChallenge();
+        return this.submitAccountLogin({
+            rootPublicKey: root.publicKey,
+            nonce,
+            signature: await signAccountLogin({ rootSecret, nonce }),
+        });
+    }
+    /**
+     * Mint a challenge for an account root to sign.
+     *
+     * Public, and deliberately so: the caller has no session — obtaining one is
+     * what this exchange does. The nonce is not a capability, it is the thing a
+     * capability gets demonstrated against, and demonstrating it needs the root.
+     *
+     * Split out of {@link signInWithAccount} for the case that call cannot serve:
+     * a root held by a hardware key, a desktop app or an air-gapped machine,
+     * which signs without the secret ever reaching this process.
+     */
+    async getAccountLoginChallenge() {
+        const body = await this.request('GET', '/api/auth/account/challenge', { anonymous: true });
+        return { nonce: body.nonce, expiresAtMs: body.expires_at_ms };
+    }
+    /** Post a proof assembled elsewhere. The other half of {@link getAccountLoginChallenge}. */
+    async submitAccountLogin(proof) {
+        const body = await this.request('POST', '/api/auth/account', {
+            body: {
+                root_public_key: proof.rootPublicKey,
+                nonce: proof.nonce,
+                signature: proof.signature,
+            },
+            anonymous: true,
+        });
+        return this.adoptSession(body);
+    }
     /**
      * Refresh the session token explicitly.
      *

package/dist/cloud/index.d.ts

@@ -1,5 +1,5 @@
 export { CloudClient } from './cloud-client.js';
-export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, EnableHAOptions, DisableHAOptions, } from './cloud-client.js';
+export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, AccountLoginChallenge, AccountLoginProof, EnableHAOptions, DisableHAOptions, } from './cloud-client.js';
 export { connectCloud } from './connect.js';
 export type { ConnectCloudOptions, CloudConnection } from './connect.js';
 export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';

package/dist/http-client/web-client.js

@@ -18,12 +18,20 @@ function extractErrorMessage(bodyText) {
     if (!bodyText)
         return undefined;
     try {
-        const error = JSON.parse(bodyText)?.error;
+        const body = JSON.parse(bodyText);
+        const error = body?.error;
         if (typeof error === 'string' && error.trim() !== '')
             return error;
         const nested = error?.message;
         if (typeof nested === 'string' && nested.trim() !== '')
             return nested;
+        // FastAPI's spelling, which is what every Calimero Cloud route answers
+        // with. Without it a manager's carefully worded refusal — "ownership is
+        // recorded, but the account is not linked" — reached callers as a bare
+        // "HTTP 403", and the one thing they could do about it was invisible.
+        const detail = body?.detail;
+        if (typeof detail === 'string' && detail.trim() !== '')
+            return detail;
     }
     catch {
         // Not JSON — the status line is all we can honestly report.