@calimero-network/mero-js 19.8.1 → 19.10.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,44 @@ export interface AccountLinkProof {
     /** `signAccountLink`'s output — standard base64. */
     signature: string;
 }
+/** Where to send someone so a cloud login can consent to linking an account. */
+export interface AccountLinkHandoff {
+    /** The cloud portal URL to open — a new tab, a popup, or the system browser. */
+    url: string;
+    /** The account the consent will be for, echoed so a caller can show it. */
+    accountId: string;
+}
+/** What comes back on the callback: a grant, a refusal, or neither. */
+export interface AccountLinkCallback {
+    /** The grant to spend with {@link CloudClient.linkAccountWithGrant}. */
+    grant?: string;
+    /** The account the grant is for, as the portal echoed it. */
+    accountId?: string;
+    /** `'denied'` when the person cancelled. Absent on success. */
+    error?: 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 +320,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.
      *
@@ -483,6 +560,64 @@ export declare class CloudClient {
      * key rather than letting a user type either.
      */
     submitAccountLink(proof: AccountLinkProof): Promise<CloudAccountLink>;
+    /**
+     * Where to send someone to authorise linking this account, and what to expect
+     * back. Pairs with {@link readAccountLinkCallback} and
+     * {@link linkAccountWithGrant}.
+     *
+     * This exists because a browser app is in a bind: it holds an account root and
+     * can never hold a *first* cloud session, since only Google issues one. So the
+     * person goes to the cloud, where they are signed in, and consents there. What
+     * comes back is a grant — consent to link this one account, spendable only by
+     * whoever can sign with its root.
+     *
+     * @param callbackUrl where the portal sends the person back. Must be an origin
+     *   the cloud allows; unlisted ones are refused when the grant is minted, not
+     *   here. The grant arrives in the URL **fragment**, which browsers do not
+     *   send to servers.
+     *
+     * Static, so it needs no client and no session: there is nothing to
+     * authenticate as yet.
+     */
+    static accountLinkHandoff(options: {
+        /** The cloud portal's origin, e.g. `https://cloud.calimero.network`. */
+        portalUrl: string;
+        /** The account to be linked, 64 hex — derive it, never let a user type it. */
+        accountId: string;
+        /** Where to come back to. */
+        callbackUrl: string;
+    }): AccountLinkHandoff;
+    /**
+     * Read the portal's answer out of a callback URL's fragment.
+     *
+     * Returns `{}` when there is nothing to read, so it is safe to call on every
+     * load — which is how a redirected app finds out it has been sent back.
+     *
+     * @param href defaults to the current location, when there is one.
+     */
+    static readAccountLinkCallback(href?: string): AccountLinkCallback;
+    /**
+     * Spend a link grant: sign it with the account root and post the pair.
+     *
+     * Anonymous, and it has to be — the app doing this holds no cloud session,
+     * which is the whole reason the grant exists. The grant carries the consenting
+     * login sealed inside it, so nothing here names one; a caller-supplied email
+     * would be a field to lie in.
+     *
+     * The signature is an ordinary account-link signature with the grant as the
+     * nonce, so the same {@link signAccountLink} every other link path uses signs
+     * this one. Both halves are required: a grant without the key links nothing,
+     * which is what makes it safe to carry through a browser redirect.
+     *
+     * A `403` means the grant was bad, expired, already spent, or signed by a key
+     * that names a different account; `409` that the account belongs to another
+     * login; `402` that the plan is full.
+     */
+    linkAccountWithGrant(options: {
+        grant: string;
+        /** The root of the account the grant names, 64 hex. */
+        rootSecret: string;
+    }): Promise<CloudAccountLink>;
     /** The accounts linked to this login, and how many the plan allows. */
     getMyAccounts(): Promise<CloudLinkedAccounts>;
     private adoptSession;

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.
      *
@@ -429,6 +489,101 @@ export class CloudClient {
             alreadyLinked: body.already_linked === true,
         };
     }
+    /**
+     * Where to send someone to authorise linking this account, and what to expect
+     * back. Pairs with {@link readAccountLinkCallback} and
+     * {@link linkAccountWithGrant}.
+     *
+     * This exists because a browser app is in a bind: it holds an account root and
+     * can never hold a *first* cloud session, since only Google issues one. So the
+     * person goes to the cloud, where they are signed in, and consents there. What
+     * comes back is a grant — consent to link this one account, spendable only by
+     * whoever can sign with its root.
+     *
+     * @param callbackUrl where the portal sends the person back. Must be an origin
+     *   the cloud allows; unlisted ones are refused when the grant is minted, not
+     *   here. The grant arrives in the URL **fragment**, which browsers do not
+     *   send to servers.
+     *
+     * Static, so it needs no client and no session: there is nothing to
+     * authenticate as yet.
+     */
+    static accountLinkHandoff(options) {
+        const portal = options.portalUrl.replace(/\/+$/, '');
+        const query = new URLSearchParams({
+            'link-account': options.accountId,
+            'callback-url': options.callbackUrl,
+        });
+        return { url: `${portal}/?${query.toString()}`, accountId: options.accountId };
+    }
+    /**
+     * Read the portal's answer out of a callback URL's fragment.
+     *
+     * Returns `{}` when there is nothing to read, so it is safe to call on every
+     * load — which is how a redirected app finds out it has been sent back.
+     *
+     * @param href defaults to the current location, when there is one.
+     */
+    static readAccountLinkCallback(href) {
+        const source = href ?? (typeof window === 'undefined' ? '' : window.location.href);
+        if (!source)
+            return {};
+        let hash;
+        try {
+            hash = new URL(source).hash;
+        }
+        catch {
+            return {};
+        }
+        const params = new URLSearchParams(hash.replace(/^#/, ''));
+        const grant = params.get('grant');
+        const accountId = params.get('account');
+        const error = params.get('error');
+        const out = {};
+        if (grant)
+            out.grant = grant;
+        if (accountId)
+            out.accountId = accountId;
+        if (error)
+            out.error = error;
+        return out;
+    }
+    /**
+     * Spend a link grant: sign it with the account root and post the pair.
+     *
+     * Anonymous, and it has to be — the app doing this holds no cloud session,
+     * which is the whole reason the grant exists. The grant carries the consenting
+     * login sealed inside it, so nothing here names one; a caller-supplied email
+     * would be a field to lie in.
+     *
+     * The signature is an ordinary account-link signature with the grant as the
+     * nonce, so the same {@link signAccountLink} every other link path uses signs
+     * this one. Both halves are required: a grant without the key links nothing,
+     * which is what makes it safe to carry through a browser redirect.
+     *
+     * A `403` means the grant was bad, expired, already spent, or signed by a key
+     * that names a different account; `409` that the account belongs to another
+     * login; `402` that the plan is full.
+     */
+    async linkAccountWithGrant(options) {
+        const root = await accountRootFromSecret(options.rootSecret);
+        const body = await this.request('POST', '/api/cloud/accounts/link', {
+            body: {
+                grant: options.grant,
+                root_public_key: root.publicKey,
+                signature: await signAccountLink({
+                    rootSecret: options.rootSecret,
+                    nonce: options.grant,
+                }),
+            },
+            anonymous: true,
+        });
+        return {
+            accountId: String(body.account_id ?? root.accountId),
+            linkedAt: body.linked_at ?? null,
+            alreadyLinked: body.already_linked === true,
+        };
+    }
     /** The accounts linked to this login, and how many the plan allows. */
     async getMyAccounts() {
         const body = await this.request('GET', '/api/cloud/me/accounts');

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, AccountLinkHandoff, AccountLinkCallback, 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.