@calimero-network/mero-js 19.9.0 → 19.10.0

package/dist/index.mjs

@@ -5277,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");