@calimero-network/mero-js 19.8.1 → 19.10.0

package/dist/index.d.ts

@@ -17,8 +17,8 @@ export type { Codec, EphemeralEntry } from './ephemeral/index.js';
 export * from './cloud/index.js';
 export * from './relay/index.js';
 export { signWarrant, intentHash } from './warrant/index.js';
-export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, } from './account/index.js';
-export type { AccountRoot, RecoverableAccountRoot, AccountLinkInput, } from './account/index.js';
+export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, signAccountLogin, } from './account/index.js';
+export type { AccountRoot, RecoverableAccountRoot, AccountLinkInput, AccountLoginInput, } from './account/index.js';
 export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, } from './device-cert/index.js';
 export type { DeviceCertInput } from './device-cert/index.js';
 export { signMemberJoinOp, encodeSignedInvitation, SIGNED_NAMESPACE_OP_SCHEMA_VERSION, } from './namespace-op/index.js';

package/dist/index.js

@@ -25,7 +25,7 @@ export * from './relay/index.js';
 // Warrant signing — mint the author's consent for a relay to run one intent
 export { signWarrant, intentHash } from './warrant/index.js';
 // Account roots — mint one with a recovery phrase, or prove you hold one
-export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, } from './account/index.js';
+export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, signAccountLogin, } from './account/index.js';
 export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, } from './device-cert/index.js';
 export { signMemberJoinOp, encodeSignedInvitation, SIGNED_NAMESPACE_OP_SCHEMA_VERSION, } from './namespace-op/index.js';
 // Login-statement signing — the device's half of a password-free session

package/dist/index.mjs

@@ -36,10 +36,13 @@ var TERMINAL_AUTH_ERRORS = /* @__PURE__ */ new Set(["token_reuse", "token_revoke
 function extractErrorMessage(bodyText) {
   if (!bodyText) return void 0;
   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;
+    const detail = body?.detail;
+    if (typeof detail === "string" && detail.trim() !== "") return detail;
   } catch {
   }
   return void 0;
@@ -4661,6 +4664,9 @@ var ENGLISH_WORDLIST = [
 var ACCOUNT_LINK_DOMAIN = new TextEncoder().encode(
   "calimero.mdma.account-link.v1\0"
 );
+var ACCOUNT_LOGIN_DOMAIN = new TextEncoder().encode(
+  "calimero.mdma.account-login.v1\0"
+);
 var ENTROPY_BITS = 256;
 var CHECKSUM_BITS = ENTROPY_BITS / 32;
 var PHRASE_WORDS = (ENTROPY_BITS + CHECKSUM_BITS) / 11;
@@ -4692,6 +4698,18 @@ async function signAccountLink(input) {
   );
   return base64(signature);
 }
+async function signAccountLogin(input) {
+  if (!input.nonce) throw new Error("nonce is required to sign an account login");
+  const key = await importSigningKey(input.rootSecret);
+  const signature = new Uint8Array(
+    await crypto.subtle.sign(
+      "Ed25519",
+      key,
+      concat(ACCOUNT_LOGIN_DOMAIN, new TextEncoder().encode(input.nonce))
+    )
+  );
+  return base64(signature);
+}
 async function withPhrase(secret, phrase) {
   return { ...await accountRootFromSecret(secret), phrase };
 }
@@ -4822,6 +4840,70 @@ var CloudClient = class {
     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.
    *
@@ -5195,6 +5277,100 @@ var CloudClient = class {
       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");
@@ -6388,6 +6564,7 @@ export {
   probeNodeHealth,
   routingProofHeaders,
   signAccountLink,
+  signAccountLogin,
   signDeviceCert,
   signLoginStatement,
   signMemberJoinOp,