@calimero-network/mero-js 19.9.0 → 19.10.0

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

@@ -240,6 +240,22 @@ 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. */
@@ -544,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

@@ -489,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, AccountLoginChallenge, AccountLoginProof, 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';