@calimero-network/mero-js 17.0.0 → 18.1.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, DeleteContextRequest, DeleteContextResponseData, GetContextsResponseData, Context, GenerateContextIdentityResponseData, GetContextIdentitiesResponseData, JoinContextResponseData, JoinSubgroupInheritanceResponseData, ContextGroupResponseData, ContextStorageResponseData, InviteSpecializedNodeRequest, InviteSpecializedNodeResponseData, UpdateContextApplicationRequest, ResyncContextRequest, ResyncContextResponseData, ContextsWithExecutorsResponseData, UploadBlobRequest, UploadBlobResponseData, DeleteBlobResponseData, ListBlobsResponseData, GetBlobInfoResponseData, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateAliasResponseData, LookupAliasResponseData, DeleteAliasResponseData, ListAliasesResponseData, ListNamespacesResponseData, CreateNamespaceRequest, CreateNamespaceResponseData, DeleteNamespaceRequest, DeleteNamespaceResponseData, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, JoinNamespaceRequest, JoinNamespaceResponseData, CreateGroupInNamespaceRequest, CreateGroupInNamespaceResponseData, SubgroupEntry, Namespace, NamespaceIdentity, NodeIdentity, GroupInfoResponseData, DeleteGroupRequest, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetGroupMetadataRequest, SetMemberMetadataRequest, SetContextMetadataRequest, MetadataRecord, SyncGroupRequest, SyncGroupResponseData, UpgradeGroupRequest, UpgradeGroupResponseData, GroupUpgradeStatusResponseData, MigrationStatus, CascadeStatusEntry, RetryGroupUpgradeRequest, RetryGroupUpgradeResponseData, ReparentGroupRequest, ReparentGroupResponseData, DetachContextFromGroupRequest, CreateGroupInvitationRequest, CreateGroupInvitationResponseData, CreateRecursiveGroupInvitationResponseData, JoinGroupRequest, JoinGroupResponseData, TeeInfoResponseData, TeeAttestRequest, TeeAttestResponseData, TeeVerifyQuoteRequest, TeeVerifyQuoteResponseData, PerformIntentRequest, PerformIntentResponseData, AdmitJoinRequest, AdmitJoinResponseData } from './admin-types.js';
+import type { HealthStatus, AdminAuthStatus, InstallApplicationRequest, InstallApplicationResponseData, InstallDevApplicationRequest, UninstallApplicationResponseData, ListApplicationsResponseData, GetApplicationResponseData, ApplicationVersionEntry, GetApplicationAbiResponseData, GetLatestVersionResponseData, ListPackagesResponseData, ListVersionsResponseData, CreateContextRequest, CreateContextResponseData, DeleteContextRequest, DeleteContextResponseData, GetContextsResponseData, Context, GenerateContextIdentityResponseData, GetContextIdentitiesResponseData, JoinContextResponseData, JoinSubgroupInheritanceResponseData, ContextGroupResponseData, ContextStorageResponseData, InviteSpecializedNodeRequest, InviteSpecializedNodeResponseData, UpdateContextApplicationRequest, ResyncContextRequest, ResyncContextResponseData, ContextsWithExecutorsResponseData, UploadBlobRequest, UploadBlobResponseData, DeleteBlobResponseData, ListBlobsResponseData, GetBlobInfoResponseData, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateAliasResponseData, LookupAliasResponseData, DeleteAliasResponseData, ListAliasesResponseData, ListNamespacesResponseData, CreateNamespaceRequest, CreateNamespaceResponseData, DeleteNamespaceRequest, DeleteNamespaceResponseData, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, JoinNamespaceRequest, JoinNamespaceResponseData, CreateGroupInNamespaceRequest, CreateGroupInNamespaceResponseData, SubgroupEntry, Namespace, NamespaceIdentity, NodeIdentity, AccountPairInitRequest, AccountPairInitResponseData, AccountPairCompleteRequest, AccountPairCompleteResponseData, RelinkDeviceRequest, RelinkDeviceResponseData, AccountDeviceEntry, AccountApplicationEntry, RevokeAccountDeviceRequest, RevokeAccountDeviceResponseData, GroupInfoResponseData, DeleteGroupRequest, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetGroupMetadataRequest, SetMemberMetadataRequest, SetContextMetadataRequest, MetadataRecord, SyncGroupRequest, SyncGroupResponseData, UpgradeGroupRequest, UpgradeGroupResponseData, GroupUpgradeStatusResponseData, MigrationStatus, CascadeStatusEntry, RetryGroupUpgradeRequest, RetryGroupUpgradeResponseData, ReparentGroupRequest, ReparentGroupResponseData, DetachContextFromGroupRequest, CreateGroupInvitationRequest, CreateGroupInvitationResponseData, CreateRecursiveGroupInvitationResponseData, JoinGroupRequest, JoinGroupResponseData, TeeInfoResponseData, TeeAttestRequest, TeeAttestResponseData, TeeVerifyQuoteRequest, TeeVerifyQuoteResponseData, PerformIntentRequest, PerformIntentResponseData, 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
@@ -16,16 +16,14 @@ export declare class AdminApiClient {
     constructor(httpClient: HttpClient);
     healthCheck(): Promise<HealthStatus>;
     isAuthed(): Promise<AdminAuthStatus>;
-    installApplication(request: InstallApplicationRequest): Promise<InstallApplicationResponseData>;
     /**
-     * Resolve a `package@version` to its registry artifact URL and install it.
-     * Node install is URL-based (no node-side package+version resolution), so this
-     * fetches the bundle manifest from the registry, derives the `.mpk` artifact
-     * URL, then calls {@link installApplication}. `registryUrl` is the registry
-     * origin. This is the discrete "download" step an Updates flow pairs with a
-     * subsequent `upgradeGroup`.
+     * Install a published application by its `package@version` coordinates. The
+     * node resolves and fetches them from its own configured `[registry]`, so no
+     * URL is passed and none is accepted. A 502 means the node's source has
+     * nothing published at those coordinates. This is the discrete "download"
+     * step an Updates flow pairs with a subsequent `upgradeGroup`.
      */
-    installFromRegistry(registryUrl: string, packageName: string, version: string): Promise<InstallApplicationResponseData>;
+    installApplication(request: InstallApplicationRequest): Promise<InstallApplicationResponseData>;
     /**
      * List a package's published versions from the registry, newest-first by
      * semver. Reads the registry's V2 bundle listing
@@ -180,6 +178,97 @@ export declare class AdminApiClient {
     joinNamespace(namespaceId: string, request: JoinNamespaceRequest): Promise<JoinNamespaceResponseData>;
     createGroupInNamespace(namespaceId: string, request?: CreateGroupInNamespaceRequest): Promise<CreateGroupInNamespaceResponseData>;
     listNamespaceGroups(namespaceId: string): Promise<SubgroupEntry[]>;
+    /**
+     * Mint this node a device for an account that already lives somewhere else -
+     * the first half of pairing, run on the joining node.
+     *
+     * Publishes nothing and needs no key: it produces the device id, the two
+     * public keys and the signature that the account holder's
+     * {@link completeAccountPairing} certifies, plus a code to read out to them
+     * over a channel the payload does not travel on. Until that second half runs,
+     * the device this mints is inert.
+     *
+     * Takes a set of namespaces rather than one, and takes it from the caller
+     * because this node cannot discover it: a node that is a member of nothing can
+     * neither read the account's namespace set off a DAG nor derive it. One device
+     * covers however many are named - the certificate is over the account, not a
+     * scope - so there is one id and one code to hand over regardless.
+     */
+    initAccountPairing(request: AccountPairInitRequest): Promise<AccountPairInitResponseData>;
+    /**
+     * Certify a device another node minted, link it, and deliver its scope keys -
+     * the second half of pairing, run on the node that holds the account root.
+     *
+     * Every field but `applications` is copied verbatim out of that node's
+     * {@link initAccountPairing} answer. Only this side can complete it: the
+     * certificate is signed by the account root, which never leaves the node that
+     * holds it.
+     *
+     * The scope is named in applications, not namespaces, because that is the
+     * question a person can answer - a namespace is an implementation unit they
+     * never chose. Leave it out to grant every application.
+     */
+    completeAccountPairing(request: AccountPairCompleteRequest): Promise<AccountPairCompleteResponseData>;
+    /**
+     * Re-run the pairing fan-out for a device this account already certified,
+     * against the namespaces this node takes part in now.
+     *
+     * Pairing is a snapshot, and this is how it is repeated. A namespace created
+     * or joined afterwards holds no binding for a device paired before it, and the
+     * symptom is silence - the device simply never sees that namespace. Nothing
+     * but the id is needed to repair it: the certificate is already held here,
+     * root-signed and naming no namespace, so a fresh endorsement and a key wrap
+     * are all a later namespace is missing. The device does not have to be online.
+     *
+     * Passing `applications` widens the device's stored scope as well as
+     * repairing. Passing none - or an empty list - repairs against the scope
+     * already stored, which is deliberately NOT the "every application" that an
+     * empty list means on {@link completeAccountPairing}: overloading it here
+     * would make the accidental request the widest one.
+     */
+    relinkAccountDevice(deviceId: string, request?: RelinkDeviceRequest): Promise<RelinkDeviceResponseData>;
+    /**
+     * Every device of this account, as this node sees them - its own included.
+     *
+     * Joined from the node-local certificate cache and the live bindings of every
+     * namespace this node takes part in, so it is this node's view rather than a
+     * global one: a device certified by another holder appears with an empty
+     * `applications`, because the certificate that would name its scope is not
+     * cached here.
+     *
+     * The wire wraps this in `devices` rather than the usual `data`; the array is
+     * what a caller wants, so that wrapper is not passed on.
+     */
+    listAccountDevices(): Promise<AccountDeviceEntry[]>;
+    /**
+     * Every application this account speaks in, with the namespaces targeting each.
+     *
+     * What a device-scoping UI lists: {@link completeAccountPairing} and
+     * {@link relinkAccountDevice} both take applications, and this is where the
+     * ids they take come from. Derived from the namespaces this node takes part
+     * in, so an application installed with no namespace yet is absent - it has
+     * nothing to scope a device to until one exists.
+     *
+     * Wrapped in `applications` on the wire rather than `data`, unwrapped here for
+     * the same reason {@link listAccountDevices} unwraps `devices`.
+     */
+    listAccountApplications(): Promise<AccountApplicationEntry[]>;
+    /**
+     * Withdraw a device from this account, terminally.
+     *
+     * Two authorities reach the same endpoint. An admin may revoke any device and
+     * rotates the scope key as it goes. The account holder may revoke its own with
+     * a root-signed `proof`, which does not rotate - so read
+     * {@link RevokeAccountDeviceResponseData.revokedIn} rather than assuming the
+     * device lost its access: a namespace reporting `keyRotated: false` has
+     * stopped the device writing but leaves it able to read until an admin
+     * rotates.
+     *
+     * `namespaceId` names where to publish from, not the extent of the revocation:
+     * a device belongs to the account, so every namespace holding a binding for it
+     * is withdrawn from and reported back.
+     */
+    revokeAccountDevice(namespaceId: string, request: RevokeAccountDeviceRequest): Promise<RevokeAccountDeviceResponseData>;
     getGroupInfo(groupId: string): Promise<GroupInfoResponseData>;
     /** Thin wrapper over {@link getGroupInfo}: returns the group's `defaultCapabilities` bitmask. */
     getDefaultCapabilities(groupId: string): Promise<number>;

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

@@ -107,34 +107,15 @@ export class AdminApiClient {
         return this.httpClient.get('/admin-api/is-authed');
     }
     // ---- Application Management ----
-    async installApplication(request) {
-        return unwrap(await this.httpClient.post('/admin-api/install-application', request));
-    }
     /**
-     * Resolve a `package@version` to its registry artifact URL and install it.
-     * Node install is URL-based (no node-side package+version resolution), so this
-     * fetches the bundle manifest from the registry, derives the `.mpk` artifact
-     * URL, then calls {@link installApplication}. `registryUrl` is the registry
-     * origin. This is the discrete "download" step an Updates flow pairs with a
-     * subsequent `upgradeGroup`.
+     * Install a published application by its `package@version` coordinates. The
+     * node resolves and fetches them from its own configured `[registry]`, so no
+     * URL is passed and none is accepted. A 502 means the node's source has
+     * nothing published at those coordinates. This is the discrete "download"
+     * step an Updates flow pairs with a subsequent `upgradeGroup`.
      */
-    async installFromRegistry(registryUrl, packageName, version) {
-        const base = new URL(registryUrl).origin;
-        const manifestUrl = new URL(`/api/v2/bundles/${encodeURIComponent(packageName)}/${encodeURIComponent(version)}`, base).toString();
-        const resp = await fetchRegistry(manifestUrl, 'manifest', `${packageName}@${version}`);
-        const bundle = (await resp.json());
-        // Encode the path segments — the package/version come from a (best-effort
-        // trusted) registry response, so guard against odd characters breaking or
-        // traversing the artifact path. For normal ids/semvers this is a no-op.
-        const pkg = encodeURIComponent(bundle.package);
-        const ver = encodeURIComponent(bundle.appVersion);
-        const artifactUrl = `${base}/artifacts/${pkg}/${ver}/${pkg}-${ver}.mpk`;
-        return this.installApplication({
-            url: artifactUrl,
-            package: bundle.package,
-            version: bundle.appVersion,
-            metadata: [],
-        });
+    async installApplication(request) {
+        return unwrap(await this.httpClient.post('/admin-api/install-application', request));
     }
     /**
      * List a package's published versions from the registry, newest-first by
@@ -505,6 +486,112 @@ export class AdminApiClient {
     async listNamespaceGroups(namespaceId) {
         return unwrap(await this.httpClient.get(`/admin-api/namespaces/${namespaceId}/groups`));
     }
+    // ---- Account Devices & Pairing ----
+    /**
+     * Mint this node a device for an account that already lives somewhere else -
+     * the first half of pairing, run on the joining node.
+     *
+     * Publishes nothing and needs no key: it produces the device id, the two
+     * public keys and the signature that the account holder's
+     * {@link completeAccountPairing} certifies, plus a code to read out to them
+     * over a channel the payload does not travel on. Until that second half runs,
+     * the device this mints is inert.
+     *
+     * Takes a set of namespaces rather than one, and takes it from the caller
+     * because this node cannot discover it: a node that is a member of nothing can
+     * neither read the account's namespace set off a DAG nor derive it. One device
+     * covers however many are named - the certificate is over the account, not a
+     * scope - so there is one id and one code to hand over regardless.
+     */
+    async initAccountPairing(request) {
+        return unwrap(await this.httpClient.post('/admin-api/account/pair-init', request));
+    }
+    /**
+     * Certify a device another node minted, link it, and deliver its scope keys -
+     * the second half of pairing, run on the node that holds the account root.
+     *
+     * Every field but `applications` is copied verbatim out of that node's
+     * {@link initAccountPairing} answer. Only this side can complete it: the
+     * certificate is signed by the account root, which never leaves the node that
+     * holds it.
+     *
+     * The scope is named in applications, not namespaces, because that is the
+     * question a person can answer - a namespace is an implementation unit they
+     * never chose. Leave it out to grant every application.
+     */
+    async completeAccountPairing(request) {
+        return unwrap(await this.httpClient.post('/admin-api/account/pair-complete', request));
+    }
+    /**
+     * Re-run the pairing fan-out for a device this account already certified,
+     * against the namespaces this node takes part in now.
+     *
+     * Pairing is a snapshot, and this is how it is repeated. A namespace created
+     * or joined afterwards holds no binding for a device paired before it, and the
+     * symptom is silence - the device simply never sees that namespace. Nothing
+     * but the id is needed to repair it: the certificate is already held here,
+     * root-signed and naming no namespace, so a fresh endorsement and a key wrap
+     * are all a later namespace is missing. The device does not have to be online.
+     *
+     * Passing `applications` widens the device's stored scope as well as
+     * repairing. Passing none - or an empty list - repairs against the scope
+     * already stored, which is deliberately NOT the "every application" that an
+     * empty list means on {@link completeAccountPairing}: overloading it here
+     * would make the accidental request the widest one.
+     */
+    async relinkAccountDevice(deviceId, request) {
+        return unwrap(await this.httpClient.post(`/admin-api/account/devices/${deviceId}/relink`, request ?? {}));
+    }
+    /**
+     * Every device of this account, as this node sees them - its own included.
+     *
+     * Joined from the node-local certificate cache and the live bindings of every
+     * namespace this node takes part in, so it is this node's view rather than a
+     * global one: a device certified by another holder appears with an empty
+     * `applications`, because the certificate that would name its scope is not
+     * cached here.
+     *
+     * The wire wraps this in `devices` rather than the usual `data`; the array is
+     * what a caller wants, so that wrapper is not passed on.
+     */
+    async listAccountDevices() {
+        const response = await this.httpClient.get('/admin-api/account/devices');
+        return response.devices;
+    }
+    /**
+     * Every application this account speaks in, with the namespaces targeting each.
+     *
+     * What a device-scoping UI lists: {@link completeAccountPairing} and
+     * {@link relinkAccountDevice} both take applications, and this is where the
+     * ids they take come from. Derived from the namespaces this node takes part
+     * in, so an application installed with no namespace yet is absent - it has
+     * nothing to scope a device to until one exists.
+     *
+     * Wrapped in `applications` on the wire rather than `data`, unwrapped here for
+     * the same reason {@link listAccountDevices} unwraps `devices`.
+     */
+    async listAccountApplications() {
+        const response = await this.httpClient.get('/admin-api/account/applications');
+        return response.applications;
+    }
+    /**
+     * Withdraw a device from this account, terminally.
+     *
+     * Two authorities reach the same endpoint. An admin may revoke any device and
+     * rotates the scope key as it goes. The account holder may revoke its own with
+     * a root-signed `proof`, which does not rotate - so read
+     * {@link RevokeAccountDeviceResponseData.revokedIn} rather than assuming the
+     * device lost its access: a namespace reporting `keyRotated: false` has
+     * stopped the device writing but leaves it able to read until an admin
+     * rotates.
+     *
+     * `namespaceId` names where to publish from, not the extent of the revocation:
+     * a device belongs to the account, so every namespace holding a binding for it
+     * is withdrawn from and reported back.
+     */
+    async revokeAccountDevice(namespaceId, request) {
+        return unwrap(await this.httpClient.post(`/admin-api/namespaces/${namespaceId}/account/revoke`, request));
+    }
     // ---- Group Management ----
     async getGroupInfo(groupId) {
         return unwrap(await this.httpClient.get(`/admin-api/groups/${groupId}`));