@calimero-network/mero-js 22.8.0 → 22.9.0

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

@@ -1,5 +1,5 @@
 import { HttpClient, HTTPError } from '../http-client/index.js';
-import type { HealthStatus, ReadinessStatus, 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, AccountSignWithRootRequest, AccountSignWithRootResponseData, RelinkDeviceRequest, RelinkDeviceResponseData, RescopeDeviceRequest, RescopeDeviceResponseData, LabelDeviceRequest, LabelDeviceResponseData, AccountDeviceEntry, AccountApplicationEntry, RevokeAccountDeviceRequest, RevokeAccountDeviceResponseData, MemberDevicesEntry, ListMemberDevicesOptions, GroupInfoResponseData, CreateGroupRequest, CreateGroupResponseData, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetMemberAutoFollowRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetTeeAuthoringPolicyRequest, 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, QueryContextRequest, QueryContextResponseData, ListMemberDevicesResponseData, SealToAccountRequest, SealedEnvelope, AdmitJoinRequest, AdmitJoinResponseData, WarrantNonceState } from './admin-types.js';
+import type { HealthStatus, ReadinessStatus, 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, AccountSignWithRootRequest, AccountSignWithRootResponseData, RelinkDeviceRequest, RelinkDeviceResponseData, RescopeDeviceRequest, RescopeDeviceResponseData, LabelDeviceRequest, LabelDeviceResponseData, AccountDeviceEntry, AccountApplicationEntry, RevokeAccountDeviceRequest, LinkAccountDeviceRequest, LinkAccountDeviceResponseData, RevokeAccountDeviceResponseData, MemberDevicesEntry, ListMemberDevicesOptions, GroupInfoResponseData, CreateGroupRequest, CreateGroupResponseData, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetMemberAutoFollowRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetTeeAuthoringPolicyRequest, 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, QueryContextRequest, QueryContextResponseData, ListMemberDevicesResponseData, SealToAccountRequest, SealedEnvelope, AdmitJoinRequest, AdmitJoinResponseData, WarrantNonceState } from './admin-types.js';
 import { type RedeemOutcome } from './redeem-invitation.js';
 /**
  * Thrown when a node answers the warrant-nonce route with a 404.
@@ -437,6 +437,22 @@ export declare class AdminApiClient {
      * that - "this device can no longer act" is the only claim it supports.
      */
     revokeAccountDevice(namespaceId: string, request: RevokeAccountDeviceRequest): Promise<RevokeAccountDeviceResponseData>;
+    /**
+     * Carry the device link of an account **this node does not hold**, so the
+     * namespace binds that device's key to the account.
+     *
+     * The relay half of a nodeless account minting invitations. An account added
+     * to a group by account holds its grants but has no device bound, so peers
+     * refuse whatever its device signs as "bound to no account". The credential
+     * and scope are root-signed and self-certifying; this node adds its own
+     * member endorsement and publishes the `AccountDeviceLinked`. After that the
+     * device signs invitations itself — see `signGroupInvitation`.
+     *
+     * Refusals: `400` when a proof does not verify or the scope does not reach
+     * this namespace (re-sign it), `403` when the device was revoked here or the
+     * account is a member of nothing in the namespace (add it first).
+     */
+    linkAccountDevice(namespaceId: string, request: LinkAccountDeviceRequest): Promise<LinkAccountDeviceResponseData>;
     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

@@ -829,6 +829,24 @@ export class AdminApiClient {
     async revokeAccountDevice(namespaceId, request) {
         return unwrap(await this.httpClient.post(`/admin-api/namespaces/${namespaceId}/account/revoke`, request));
     }
+    /**
+     * Carry the device link of an account **this node does not hold**, so the
+     * namespace binds that device's key to the account.
+     *
+     * The relay half of a nodeless account minting invitations. An account added
+     * to a group by account holds its grants but has no device bound, so peers
+     * refuse whatever its device signs as "bound to no account". The credential
+     * and scope are root-signed and self-certifying; this node adds its own
+     * member endorsement and publishes the `AccountDeviceLinked`. After that the
+     * device signs invitations itself — see `signGroupInvitation`.
+     *
+     * Refusals: `400` when a proof does not verify or the scope does not reach
+     * this namespace (re-sign it), `403` when the device was revoked here or the
+     * account is a member of nothing in the namespace (add it first).
+     */
+    async linkAccountDevice(namespaceId, request) {
+        return unwrap(await this.httpClient.post(`/admin-api/namespaces/${namespaceId}/account/link-device`, request));
+    }
     // ---- Group Management ----
     async getGroupInfo(groupId) {
         return unwrap(await this.httpClient.get(`/admin-api/groups/${groupId}`));

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

@@ -1162,6 +1162,40 @@ export interface RevokeAccountDeviceResponseData {
      */
     revokedIn: RevocationOutcome[];
 }
+/**
+ * Bind a device of an account the node does not hold, so what that device
+ * signs in the namespace resolves to its account.
+ *
+ * For an account with **no node**: its root certifies a device offline
+ * (`signDeviceCert`) and scopes it
+ * (`signDeviceScope`), and a relay that is a member of the namespace carries
+ * the link, endorsing the account with its own member key. Both proofs are
+ * root-signed, so the relay can carry them and cannot alter them.
+ */
+export interface LinkAccountDeviceRequest {
+    /**
+     * The device's credential: hex, borsh `AccountProof<DeviceCert>` — what
+     * `signDeviceCert` returns and `merod account sign-cert` prints.
+     */
+    credential: string;
+    /**
+     * The device's scope: hex, borsh `AccountProof<DeviceScope>` — what
+     * `signDeviceScope` returns. It must reach the namespace's application, or
+     * name none.
+     */
+    scope: string;
+}
+export interface LinkAccountDeviceResponseData {
+    /** The account the device speaks for, 64 hex. */
+    accountId: string;
+    /** The device now bound, 64 hex. */
+    deviceId: string;
+    /**
+     * The namespace already bound this device key, so nothing was published.
+     * A repeat call is harmless and answers `true`.
+     */
+    alreadyBound: boolean;
+}
 /** One device of one member account, as the group's live bindings record it. */
 export interface MemberDeviceEntry {
     /** The device id, 64 hex - the form {@link RevokeAccountDeviceRequest.deviceId} takes. */

package/dist/device-cert/device-cert.d.ts

@@ -1,4 +1,15 @@
 import { type Signer } from '../signer/signer.js';
+/**
+ * Core's `ACCOUNT_GENESIS_VERSION`. It is part of the `AccountId` preimage, so
+ * this value decides which account a root key names — a mismatch does not fail
+ * as a version error at the edge, it silently derives a different account and
+ * core refuses the credential as unverifiable.
+ *
+ * `2` since the genesis dropped its per-namespace nonce. This was `1`, which
+ * produced credentials current core rejects outright; the shape was already v2,
+ * only the tag was stale.
+ */
+export declare const ACCOUNT_GENESIS_VERSION = 2;
 /** What a root certifies about one device. */
 export interface DeviceCertInput {
     /**

package/dist/device-cert/device-cert.js

@@ -20,7 +20,6 @@ import { resolveSigner } from '../signer/signer.js';
 const CERT_DOMAIN = new TextEncoder().encode('calimero.device.cert.v1');
 const ACCOUNT_ID_DOMAIN = new TextEncoder().encode('calimero.account.genesis.v1');
 const DEVICE_ID_DOMAIN = new TextEncoder().encode('calimero.device.id.v1');
-/** `AccountGenesis::version`, which the credential's borsh encoding leads with. */
 /**
  * Core's `ACCOUNT_GENESIS_VERSION`. It is part of the `AccountId` preimage, so
  * this value decides which account a root key names — a mismatch does not fail
@@ -31,7 +30,7 @@ const DEVICE_ID_DOMAIN = new TextEncoder().encode('calimero.device.id.v1');
  * produced credentials current core rejects outright; the shape was already v2,
  * only the tag was stale.
  */
-const ACCOUNT_GENESIS_VERSION = 2;
+export const ACCOUNT_GENESIS_VERSION = 2;
 /** Byte length of an `AccountProof<DeviceCert>` with an empty handoff chain. */
 const ACCOUNT_PROOF_BYTES = 237;
 /**

package/dist/device-cert/device-scope.d.ts

@@ -0,0 +1,58 @@
+import { type Signer } from '../signer/signer.js';
+/** What a root scopes one device to. */
+export interface DeviceScopeInput {
+    /**
+     * The account root's signing secret, 64 hex. Pass this or {@link signer}.
+     */
+    rootSecret?: string;
+    /**
+     * The account root as a {@link Signer} — for a root that cannot be exported.
+     * Its `publicKey` is the genesis key the proof carries, and the account is
+     * derived from it.
+     */
+    signer?: Signer;
+    /** The device being scoped, 64 hex — the one its certificate names. */
+    device: string;
+    /**
+     * Application ids the device may speak for, 64 hex each. **Empty means all of
+     * them**, which is also what the default is.
+     *
+     * A namespace binds the device only when its application is listed here (or
+     * the list is empty), so a scope naming the wrong application yields a relay
+     * refusal of `400`, not a binding.
+     */
+    applications?: readonly string[];
+    /**
+     * Orders scopes for this device: only a higher one supersedes. 0 for a
+     * device's first scope.
+     */
+    scopeEpoch?: number;
+}
+/**
+ * The 32 bytes a root signs to scope a device: `domain_hash` over account,
+ * device, `scope_epoch` (u32 LE), `key_epoch` (u32 LE), then each application id
+ * as its own length-prefixed part.
+ */
+export declare function deviceScopePayload(input: {
+    account: string;
+    device: string;
+    applications: readonly string[];
+    scopeEpoch: number;
+    keyEpoch: number;
+}): Promise<Uint8Array>;
+/**
+ * Scope a device, returning the hex `AccountProof<DeviceScope>` a relay's
+ * `linkAccountDevice` takes beside the credential.
+ *
+ * ```
+ * AccountProof { genesis: AccountGenesis, chain: Vec<RootKeyHandoff>, statement: DeviceScope }
+ *   AccountGenesis { version: u8, root_sign_pk: [u8; 32] }
+ *   chain          → u32-LE count (0 here)
+ *   DeviceScope    { account, device: [u8; 32] x2, applications: Vec<[u8; 32]>,
+ *                    scope_epoch: u32, key_epoch: u32, signature: [u8; 64] }
+ * ```
+ *
+ * `chain` is empty and `key_epoch` 0 for the reason they are in
+ * {@link signDeviceCert}: a root that was never handed off signs directly.
+ */
+export declare function signDeviceScope(input: DeviceScopeInput): Promise<string>;

package/dist/device-cert/device-scope.js

@@ -0,0 +1,76 @@
+/**
+ * Scoping a device offline: which applications a device of an account may speak
+ * for, signed by the account root.
+ *
+ * The certificate from {@link signDeviceCert} says *this key is a device of the
+ * account*. It does not say where: that is this statement, and a namespace binds
+ * a device only when both arrive together. A node that pairs a device signs the
+ * scope for you; an account with **no node** has to sign it itself, next to the
+ * certificate, and hand both to a relay's `linkAccountDevice`.
+ *
+ * Derived from core:
+ *
+ * - `DeviceScope` and `DeviceScope::signing_payload` — `crates/account/src/scope.rs`
+ * - `DEVICE_SCOPE_SIGN_DOMAIN`                       — `crates/account/src/domain.rs`
+ * - `AccountProof` / `AccountGenesis` borsh layout   — `crates/account/src/{signed,account}.rs`
+ *
+ * The unit tests pin vectors produced by core's own `DeviceScope::sign`.
+ */
+import { concat, domainHash, fromHex, hex, u32le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
+import { accountForRootPublicKey, ACCOUNT_GENESIS_VERSION } from './device-cert.js';
+const SCOPE_DOMAIN = new TextEncoder().encode('calimero.device.scope.v1');
+/**
+ * The 32 bytes a root signs to scope a device: `domain_hash` over account,
+ * device, `scope_epoch` (u32 LE), `key_epoch` (u32 LE), then each application id
+ * as its own length-prefixed part.
+ */
+export async function deviceScopePayload(input) {
+    return domainHash(SCOPE_DOMAIN, [
+        fromHex(input.account, 'account', 32),
+        fromHex(input.device, 'device', 32),
+        u32le(input.scopeEpoch),
+        u32le(input.keyEpoch),
+        ...input.applications.map((a, i) => fromHex(a, `applications[${i}]`, 32)),
+    ]);
+}
+/**
+ * Scope a device, returning the hex `AccountProof<DeviceScope>` a relay's
+ * `linkAccountDevice` takes beside the credential.
+ *
+ * ```
+ * AccountProof { genesis: AccountGenesis, chain: Vec<RootKeyHandoff>, statement: DeviceScope }
+ *   AccountGenesis { version: u8, root_sign_pk: [u8; 32] }
+ *   chain          → u32-LE count (0 here)
+ *   DeviceScope    { account, device: [u8; 32] x2, applications: Vec<[u8; 32]>,
+ *                    scope_epoch: u32, key_epoch: u32, signature: [u8; 64] }
+ * ```
+ *
+ * `chain` is empty and `key_epoch` 0 for the reason they are in
+ * {@link signDeviceCert}: a root that was never handed off signs directly.
+ */
+export async function signDeviceScope(input) {
+    const signer = await resolveSigner(input.rootSecret, input.signer, 'rootSecret');
+    const rootPublicKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
+    const account = await accountForRootPublicKey(hex(rootPublicKey));
+    const applications = input.applications ?? [];
+    const scopeEpoch = input.scopeEpoch ?? 0;
+    // `u32le` would wrap a negative or oversized value into a different epoch
+    // rather than refuse it, and the scope would then order itself wrongly.
+    if (!Number.isInteger(scopeEpoch) || scopeEpoch < 0 || scopeEpoch > 4294967295) {
+        throw new Error(`scopeEpoch must be a u32, got ${scopeEpoch}`);
+    }
+    const keyEpoch = 0;
+    const payload = await deviceScopePayload({
+        account,
+        device: input.device,
+        applications,
+        scopeEpoch,
+        keyEpoch,
+    });
+    const signature = await signer.sign(payload);
+    if (signature.length !== 64) {
+        throw new Error(`signer returned ${signature.length} bytes, expected a 64-byte Ed25519 signature`);
+    }
+    return hex(concat(new Uint8Array([ACCOUNT_GENESIS_VERSION]), rootPublicKey, u32le(0), fromHex(account, 'account', 32), fromHex(input.device, 'device', 32), u32le(applications.length), ...applications.map((a, i) => fromHex(a, `applications[${i}]`, 32)), u32le(scopeEpoch), u32le(keyEpoch), signature));
+}

package/dist/device-cert/index.d.ts

@@ -1,2 +1,4 @@
 export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, accountForRootPublicKey, accountProofBytes, parseDeviceCredential, verifyDeviceCredential, } from './device-cert.js';
 export type { DeviceCertInput, DeviceCredential } from './device-cert.js';
+export { signDeviceScope, deviceScopePayload } from './device-scope.js';
+export type { DeviceScopeInput } from './device-scope.js';

package/dist/device-cert/index.js

@@ -1,2 +1,3 @@
 // Offline device certification — the account-root half of the keyholder story.
 export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, accountForRootPublicKey, accountProofBytes, parseDeviceCredential, verifyDeviceCredential, } from './device-cert.js';
+export { signDeviceScope, deviceScopePayload } from './device-scope.js';