@calimero-network/mero-js 19.9.0 → 19.11.0

package/dist/admin-api/admin-client.d.ts

@@ -1,5 +1,5 @@
 import { HttpClient } from '../http-client/index.js';
-import type { HealthStatus, AdminAuthStatus, InstallApplicationRequest, InstallApplicationResponseData, InstallDevApplicationRequest, UninstallApplicationResponseData, ListApplicationsResponseData, GetApplicationResponseData, ApplicationVersionEntry, GetApplicationAbiResponseData, GetLatestVersionResponseData, ListPackagesResponseData, ListVersionsResponseData, CreateContextRequest, CreateContextResponseData, DeleteContextResponseData, GetContextsResponseData, Context, GenerateContextIdentityResponseData, GetContextIdentitiesResponseData, JoinContextResponseData, JoinSubgroupInheritanceResponseData, ContextGroupResponseData, ContextStorageResponseData, InviteSpecializedNodeRequest, InviteSpecializedNodeResponseData, UpdateContextApplicationRequest, ResyncContextRequest, ResyncContextResponseData, ContextsWithExecutorsResponseData, UploadBlobRequest, UploadBlobResponseData, DeleteBlobResponseData, ListBlobsResponseData, GetBlobInfoResponseData, BlobReadOptions, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateDeviceAliasRequest, CreateAliasResponseData, LookupAliasResponseData, DeleteAliasResponseData, ListAliasesResponseData, ListNamespacesResponseData, CreateNamespaceRequest, CreateNamespaceResponseData, DeleteNamespaceResponseData, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, JoinNamespaceRequest, JoinNamespaceResponseData, CreateGroupInNamespaceRequest, CreateGroupInNamespaceResponseData, SubgroupEntry, Namespace, NamespaceIdentity, NodeIdentity, AccountPairInitRequest, AccountPairInitResponseData, AccountPairCompleteRequest, AccountPairCompleteResponseData, RelinkDeviceRequest, RelinkDeviceResponseData, AccountDeviceEntry, AccountApplicationEntry, RevokeAccountDeviceRequest, RevokeAccountDeviceResponseData, GroupInfoResponseData, CreateGroupRequest, CreateGroupResponseData, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetMemberAutoFollowRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetGroupMetadataRequest, SetMemberMetadataRequest, SetContextMetadataRequest, MetadataRecord, SyncGroupResponseData, UpgradeGroupRequest, UpgradeGroupResponseData, GroupUpgradeStatusResponseData, MigrationStatus, CascadeStatusEntry, RetryGroupUpgradeResponseData, ReparentGroupRequest, ReparentGroupResponseData, IssueOwnershipProofRequest, IssueNamespaceOwnershipProofRequest, IssueOwnershipProofResponseData, CreateGroupInvitationRequest, CreateGroupInvitationResponseData, CreateRecursiveGroupInvitationResponseData, JoinGroupRequest, JoinGroupResponseData, TeeInfoResponseData, TeeAttestRequest, TeeAttestResponseData, TeeVerifyQuoteRequest, TeeVerifyQuoteResponseData, PerformIntentRequest, PerformIntentResponseData, IntentRelayInfo, AdmitJoinRequest, AdmitJoinResponseData } from './admin-types.js';
+import type { HealthStatus, AdminAuthStatus, InstallApplicationRequest, InstallApplicationResponseData, InstallDevApplicationRequest, UninstallApplicationResponseData, ListApplicationsResponseData, GetApplicationResponseData, ApplicationVersionEntry, GetApplicationAbiResponseData, GetLatestVersionResponseData, ListPackagesResponseData, ListVersionsResponseData, CreateContextRequest, CreateContextResponseData, DeleteContextResponseData, GetContextsResponseData, Context, GenerateContextIdentityResponseData, GetContextIdentitiesResponseData, JoinContextResponseData, JoinSubgroupInheritanceResponseData, ContextGroupResponseData, ContextStorageResponseData, InviteSpecializedNodeRequest, InviteSpecializedNodeResponseData, UpdateContextApplicationRequest, ResyncContextRequest, ResyncContextResponseData, ContextsWithExecutorsResponseData, UploadBlobRequest, UploadBlobResponseData, DeleteBlobResponseData, ListBlobsResponseData, GetBlobInfoResponseData, BlobReadOptions, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateDeviceAliasRequest, CreateAliasResponseData, LookupAliasResponseData, DeleteAliasResponseData, ListAliasesResponseData, ListNamespacesResponseData, CreateNamespaceRequest, CreateNamespaceResponseData, DeleteNamespaceResponseData, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, JoinNamespaceRequest, JoinNamespaceResponseData, CreateGroupInNamespaceRequest, CreateGroupInNamespaceResponseData, SubgroupEntry, Namespace, NamespaceIdentity, NodeIdentity, AccountPairInitRequest, AccountPairInitResponseData, AccountPairCompleteRequest, AccountPairCompleteResponseData, RelinkDeviceRequest, RelinkDeviceResponseData, RescopeDeviceRequest, RescopeDeviceResponseData, AccountDeviceEntry, AccountApplicationEntry, RevokeAccountDeviceRequest, RevokeAccountDeviceResponseData, GroupInfoResponseData, CreateGroupRequest, CreateGroupResponseData, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetMemberAutoFollowRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetGroupMetadataRequest, SetMemberMetadataRequest, SetContextMetadataRequest, MetadataRecord, SyncGroupResponseData, UpgradeGroupRequest, UpgradeGroupResponseData, GroupUpgradeStatusResponseData, MigrationStatus, CascadeStatusEntry, RetryGroupUpgradeResponseData, ReparentGroupRequest, ReparentGroupResponseData, IssueOwnershipProofRequest, IssueNamespaceOwnershipProofRequest, IssueOwnershipProofResponseData, CreateGroupInvitationRequest, CreateGroupInvitationResponseData, CreateRecursiveGroupInvitationResponseData, JoinGroupRequest, JoinGroupResponseData, TeeInfoResponseData, TeeAttestRequest, TeeAttestResponseData, TeeVerifyQuoteRequest, TeeVerifyQuoteResponseData, PerformIntentRequest, PerformIntentResponseData, IntentRelayInfo, AdmitJoinRequest, AdmitJoinResponseData } from './admin-types.js';
 /**
  * Compare two version strings by SemVer 2.0 precedence, ascending: negative if
  * `a < b`, positive if `a > b`, `0` if equal. Build metadata (`+...`) is stripped
@@ -272,6 +272,14 @@ export declare class AdminApiClient {
      * would make the accidental request the widest one.
      */
     relinkAccountDevice(deviceId: string, request?: RelinkDeviceRequest): Promise<RelinkDeviceResponseData>;
+    /**
+     * Replace a device's scope outright, in one root-signed op.
+     *
+     * {@link relinkAccountDevice} only ever adds applications; this is how a
+     * scope is narrowed - or an `all` device is given a fixed list instead. The
+     * device need not be online.
+     */
+    rescopeAccountDevice(deviceId: string, request: RescopeDeviceRequest): Promise<RescopeDeviceResponseData>;
     /**
      * Every device of this account, as this node sees them - its own included.
      *

package/dist/admin-api/admin-client.js

@@ -587,6 +587,16 @@ export class AdminApiClient {
     async relinkAccountDevice(deviceId, request) {
         return unwrap(await this.httpClient.post(`/admin-api/account/devices/${deviceId}/relink`, request ?? {}));
     }
+    /**
+     * Replace a device's scope outright, in one root-signed op.
+     *
+     * {@link relinkAccountDevice} only ever adds applications; this is how a
+     * scope is narrowed - or an `all` device is given a fixed list instead. The
+     * device need not be online.
+     */
+    async rescopeAccountDevice(deviceId, request) {
+        return unwrap(await this.httpClient.put(`/admin-api/account/devices/${encodeURIComponent(deviceId)}/scope`, request));
+    }
     /**
      * Every device of this account, as this node sees them - its own included.
      *

package/dist/admin-api/admin-types.d.ts

@@ -811,6 +811,25 @@ export interface RelinkDeviceRequest {
      */
     applications?: string[];
 }
+/**
+ * The scope to hold: every application, or only the ones named.
+ *
+ * A tagged shape rather than a list whose emptiness means everything - `all`
+ * and `only: []` differ by a whole order of magnitude in what they grant, and
+ * an empty `only` is refused rather than treated as `all`.
+ */
+export type DeviceScope = 'all' | {
+    only: string[];
+};
+/**
+ * Replace a device's scope outright, in one root-signed op.
+ *
+ * {@link relinkAccountDevice} only ever adds applications; this is how a
+ * scope is narrowed, or an `all` device is given a fixed list instead.
+ */
+export interface RescopeDeviceRequest {
+    scope: DeviceScope;
+}
 /** One namespace the relink published the device's link into. */
 export interface RelinkOutcomeEntry {
     /** The namespace id, 64 hex characters. */
@@ -834,6 +853,31 @@ export interface RelinkSkipEntry {
      */
     reason: string;
 }
+/** One namespace a scope replacement no longer reaches. */
+export interface RescopeDescopeEntry {
+    /** The namespace id, 64 hex characters. */
+    namespaceId: string;
+    /**
+     * Whether the scope key was rotated. `false` means the device stopped writing
+     * there but still holds the key it had, until an admin rotates.
+     */
+    keyRotated: boolean;
+}
+/** The scope a device now holds, and what each namespace did about it. */
+export interface RescopeDeviceResponseData {
+    /** The account the device speaks for, 64 hex characters. */
+    accountId: string;
+    /** The device that was rescoped, 64 hex characters. */
+    deviceId: string;
+    /** The scope after the request, 64 hex each. Empty means every application. */
+    applications: string[];
+    /** Namespaces the new scope no longer reaches. */
+    descoped: RescopeDescopeEntry[];
+    /** Namespaces the device was linked into by this call. */
+    linkedIn: RelinkOutcomeEntry[];
+    /** Namespaces nothing was published into, and why. */
+    skipped: RelinkSkipEntry[];
+}
 /** What the relink repaired, and what it left alone. */
 export interface RelinkDeviceResponseData {
     /** The account the device speaks for, 64 hex characters. */

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';