@calimero-network/mero-js 22.8.0 → 23.0.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, TransferOwnershipRequest, ChangeNamespaceAdminRequest, OwnerDeleteGroupRequest, RootGuardedOpRequest, 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>;
@@ -660,8 +676,28 @@ export declare class AdminApiClient {
      * and admitted TEEs stay members. The node applies the same op as
      * `setTeeAuthoringPolicy(groupId, { allowedMrtd: [] })`. `groupId` must be a
      * namespace root.
+     *
+     * `rootProof` is the signing admin's own root proof for that empty policy
+     * (`teeAuthoringPolicyOp([])`); omit it on a node that holds that root.
+     */
+    disableTeeAuthoringPolicy(groupId: string, options?: RootGuardedOpRequest): Promise<void>;
+    /**
+     * Hand the group to `newOwner`, who must already be one of its admins.
+     * Owner-only, and it needs the owner account's root proof; see
+     * {@link RootGuardedOpRequest}.
+     */
+    transferOwnership(groupId: string, request: TransferOwnershipRequest): Promise<void>;
+    /**
+     * Repoint the namespace's admin pin at `newAdmin`, a member of its root.
+     * Owner-only, with the owner account's root proof; see {@link RootGuardedOpRequest}.
+     */
+    changeNamespaceAdmin(namespaceId: string, request: ChangeNamespaceAdminRequest): Promise<void>;
+    /**
+     * Delete a group through the owner-only path: it must hold no contexts, and
+     * the op needs the owner account's root proof. {@link deleteGroup} is the
+     * admin-level cascading delete.
      */
-    disableTeeAuthoringPolicy(groupId: string): Promise<void>;
+    ownerDeleteGroup(groupId: string, request?: OwnerDeleteGroupRequest): Promise<void>;
     setGroupMetadata(groupId: string, request: SetGroupMetadataRequest): Promise<void>;
     getGroupMetadata(groupId: string): Promise<MetadataRecord | null>;
     setMemberMetadata(groupId: string, identity: string, request: SetMemberMetadataRequest): Promise<void>;

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}`));
@@ -1174,9 +1192,45 @@ export class AdminApiClient {
      * and admitted TEEs stay members. The node applies the same op as
      * `setTeeAuthoringPolicy(groupId, { allowedMrtd: [] })`. `groupId` must be a
      * namespace root.
+     *
+     * `rootProof` is the signing admin's own root proof for that empty policy
+     * (`teeAuthoringPolicyOp([])`); omit it on a node that holds that root.
+     */
+    async disableTeeAuthoringPolicy(groupId, options = {}) {
+        const path = `/admin-api/groups/${groupId}/settings/tee-authoring-policy`;
+        if (options.rootProof === undefined) {
+            await this.httpClient.delete(path);
+            return;
+        }
+        await this.httpClient.request(path, {
+            method: 'DELETE',
+            body: JSON.stringify({ rootProof: options.rootProof }),
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    // ---- Root-guarded owner ops (core schema 18) ----
+    /**
+     * Hand the group to `newOwner`, who must already be one of its admins.
+     * Owner-only, and it needs the owner account's root proof; see
+     * {@link RootGuardedOpRequest}.
+     */
+    async transferOwnership(groupId, request) {
+        await this.httpClient.post(`/admin-api/groups/${groupId}/transfer-ownership`, request);
+    }
+    /**
+     * Repoint the namespace's admin pin at `newAdmin`, a member of its root.
+     * Owner-only, with the owner account's root proof; see {@link RootGuardedOpRequest}.
+     */
+    async changeNamespaceAdmin(namespaceId, request) {
+        await this.httpClient.post(`/admin-api/namespaces/${namespaceId}/admin`, request);
+    }
+    /**
+     * Delete a group through the owner-only path: it must hold no contexts, and
+     * the op needs the owner account's root proof. {@link deleteGroup} is the
+     * admin-level cascading delete.
      */
-    async disableTeeAuthoringPolicy(groupId) {
-        await this.httpClient.delete(`/admin-api/groups/${groupId}/settings/tee-authoring-policy`);
+    async ownerDeleteGroup(groupId, request = {}) {
+        await this.httpClient.post(`/admin-api/groups/${groupId}/owner-delete`, request);
     }
     // ---- Group / member / context metadata ----
     async setGroupMetadata(groupId, request) {

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. */
@@ -1303,6 +1337,19 @@ export interface GroupInfo {
      * `null` if no metadata has ever been set for this group.
      */
     metadata?: MetadataRecord | null;
+    /** Hex hash of the group's authorization-relevant state, for convergence polling. */
+    groupStateHash?: string;
+    /**
+     * The namespace this group belongs to (itself, for a namespace root). An
+     * owner-op root proof binds it. Absent from nodes before core schema 18.
+     */
+    namespaceId?: string;
+    /**
+     * How many root-guarded owner ops this group has applied: the `counter` a
+     * root proof for its next one must name. Absent from nodes before core
+     * schema 18.
+     */
+    ownerOpCounter?: number;
 }
 export type GroupInfoResponseData = GroupInfo;
 /**
@@ -1479,6 +1526,12 @@ export interface MeasurementTeeAdmissionPolicyRequest {
     acceptMock: boolean;
     /** Absent means `replica`. */
     mode?: TeeAdmissionMode;
+    /**
+     * Hex borsh of the signing admin's own root proof for this policy op
+     * ({@link signOwnerOpProof} with the matching policy encoder). Omit it on a
+     * node that holds that admin's account root, which signs one itself.
+     */
+    rootProof?: string;
 }
 /** A policy that admits by signed release. The node refuses measurement lists beside it. */
 export interface SignedReleaseTeeAdmissionPolicyRequest {
@@ -1487,6 +1540,12 @@ export interface SignedReleaseTeeAdmissionPolicyRequest {
     acceptMock: boolean;
     /** Absent means `replica`. */
     mode?: TeeAdmissionMode;
+    /**
+     * Hex borsh of the signing admin's own root proof for this policy op
+     * ({@link signOwnerOpProof} with the matching policy encoder). Omit it on a
+     * node that holds that admin's account root, which signs one itself.
+     */
+    rootProof?: string;
 }
 export type SetTeeAdmissionPolicyRequest = MeasurementTeeAdmissionPolicyRequest | SignedReleaseTeeAdmissionPolicyRequest;
 export type SetTeeAdmissionPolicyResponseData = Record<string, never>;
@@ -1517,7 +1576,42 @@ export interface GetTeeAdmissionPolicyResponseData {
  */
 export interface SetTeeAuthoringPolicyRequest {
     allowedMrtd: string[];
+    /**
+     * Hex borsh of the signing admin's own root proof for this policy op
+     * ({@link signOwnerOpProof} with the matching policy encoder). Omit it on a
+     * node that holds that admin's account root, which signs one itself.
+     */
+    rootProof?: string;
 }
+/**
+ * The root proof an owner-level op carries (core schema 18).
+ *
+ * A device key alone cannot transfer a group, repoint a namespace's admin,
+ * delete a group through the owner-only path, or set a TEE policy: each needs a
+ * proof signed by the account's ROOT key. On a node that holds that root (as
+ * `merod init` provisions) omit `rootProof` and the node signs it. Otherwise sign
+ * one offline with {@link signOwnerOpProof}, over the group's current
+ * `ownerOpCounter` and `namespaceId` from {@link GroupInfo}. Each proof applies
+ * once. Without either, the node answers `403`.
+ */
+export interface RootGuardedOpRequest {
+    /** Hex borsh of an `AccountProof<OwnerOpAuthorization>`. */
+    rootProof?: string;
+}
+/** Hand a group to `newOwner`, an account (64 hex) that is already one of its admins. */
+export interface TransferOwnershipRequest extends RootGuardedOpRequest {
+    newOwner: string;
+}
+/** Repoint a namespace's admin pin at `newAdmin`, an account that is a member of its root. */
+export interface ChangeNamespaceAdminRequest extends RootGuardedOpRequest {
+    newAdmin: string;
+}
+/**
+ * The owner-only deletion of a group that holds no contexts. The admin-level
+ * cascading delete is {@link AdminApiClient.deleteGroup}.
+ */
+export type OwnerDeleteGroupRequest = RootGuardedOpRequest;
+export type RootGuardedOpResponseData = Record<string, never>;
 export type SetTeeAuthoringPolicyResponseData = Record<string, never>;
 /**
  * Generic metadata record attached to a group, group member, or

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