@calimero-network/mero-js 22.8.0 → 22.9.0

package/dist/index.d.ts

@@ -28,6 +28,10 @@ export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, crea
 export type { AccountRoot, RecoverableAccountRoot, AccountRootSigner, NewAccountRootSigner, AccountLinkInput, AccountLoginInput, RootSource, ResolvedRoot, } from "./account/index.js";
 export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, accountForRootPublicKey, parseDeviceCredential, verifyDeviceCredential, } from "./device-cert/index.js";
 export type { DeviceCertInput, DeviceCredential } from "./device-cert/index.js";
+export { signDeviceScope, deviceScopePayload } from "./device-cert/index.js";
+export type { DeviceScopeInput } from "./device-cert/index.js";
+export { signGroupInvitation, encodeGroupInvitation, groupInvitationHash, defaultAdmitters, MAX_INVITATION_VALIDITY_SECS, INVITED_ROLE, } from "./invitation/index.js";
+export type { GroupInvitationInput } from "./invitation/index.js";
 export { signMemberJoinOp, encodeSignedInvitation, SIGNED_NAMESPACE_OP_SCHEMA_VERSION, } from "./namespace-op/index.js";
 export type { SignMemberJoinInput } from "./namespace-op/index.js";
 export type { WarrantInput, CreationWarrantInput, CreationWarrantFields, SignedCreationWarrant, GovernanceWarrantInput, GovernanceWarrantFields, GovernanceOp, GovernanceOpKind, GovernanceMemberRole, GroupCreatedInput, NamespaceCreatedInput, } from "./warrant/index.js";

package/dist/index.js

@@ -46,6 +46,11 @@ export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, crea
 // name it in a signature only by re-declaring it.
 resolveRoot, resolveRootPair, } from "./account/index.js";
 export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, accountForRootPublicKey, parseDeviceCredential, verifyDeviceCredential, } from "./device-cert/index.js";
+// A device's scope — signed by the root beside its certificate, and what a relay
+// needs with it to bind the device of an account that has no node.
+export { signDeviceScope, deviceScopePayload } from "./device-cert/index.js";
+// Invitations minted off-node, signed by a bound device key.
+export { signGroupInvitation, encodeGroupInvitation, groupInvitationHash, defaultAdmitters, MAX_INVITATION_VALIDITY_SECS, INVITED_ROLE, } from "./invitation/index.js";
 export { signMemberJoinOp, encodeSignedInvitation, SIGNED_NAMESPACE_OP_SCHEMA_VERSION, } from "./namespace-op/index.js";
 // Login-statement signing — the device's half of a password-free session
 export { requestBodyHash, signRequest, callerProof, createProofSigner, } from "./request/index.js";

package/dist/index.mjs

@@ -1810,6 +1810,29 @@ var AdminApiClient = class {
       )
     );
   }
+  /**
+   * 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}`));
@@ -3495,6 +3518,54 @@ async function accountForRootPublicKey(rootPublicKey) {
   );
 }
 
+// src/device-cert/device-scope.ts
+var SCOPE_DOMAIN = new TextEncoder().encode("calimero.device.scope.v1");
+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))
+  ]);
+}
+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;
+  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
+    )
+  );
+}
+
 // src/account/wordlist.ts
 var ENGLISH_WORDLIST = [
   "abandon",
@@ -10103,6 +10174,101 @@ function splitVersion2(version) {
   return [[Number(match[1]), Number(match[2]), Number(match[3])], match[4]];
 }
 
+// src/invitation/invitation.ts
+var MAX_INVITATION_VALIDITY_SECS = 24 * 60 * 60;
+var INVITED_ROLE = { Admin: 0, Member: 1, ReadOnly: 2 };
+function encodeGroupInvitation(body) {
+  const admitters = body.admitters ?? [];
+  return concat(
+    // `SignerId` and `ContextGroupId` cross JSON as 32 numbers; `AccountId`
+    // crosses as hex. Same width, different spelling.
+    bytes32(body.inviter_identity, "inviter_identity"),
+    bytes32(body.group_id, "group_id"),
+    u64le(body.expiration_timestamp),
+    bytes32(body.secret_salt, "secret_salt"),
+    new Uint8Array([body.invited_role]),
+    u32le(admitters.length),
+    ...admitters.map((a, i) => fromHex(a, `admitters[${i}]`, 32))
+  );
+}
+async function groupInvitationHash(body) {
+  return new Uint8Array(
+    await crypto.subtle.digest("SHA-256", encodeGroupInvitation(body))
+  );
+}
+function defaultAdmitters(members) {
+  const admins = new Set(
+    members.filter((m) => m.role === "Admin").map((m) => m.identity.toLowerCase())
+  );
+  return [...admins].sort();
+}
+async function signGroupInvitation(input) {
+  const signer = await resolveSigner(input.deviceSecret, input.signer, "deviceSecret");
+  const inviterKey = fromHex(signer.publicKey, "signer.publicKey", 32);
+  const groupId = fromHex(input.groupId, "groupId", 32);
+  fromHex(input.inviterAccount, "inviterAccount", 32);
+  let admitters = [...input.admitters ?? []].map((a) => a.trim().toLowerCase());
+  if (admitters.length === 0) {
+    if (!input.members) {
+      throw new Error(
+        "name the admitters, or pass the group members to default them to its admins: an invitation with no admitters is claimable by broadcast"
+      );
+    }
+    admitters = defaultAdmitters(input.members);
+    if (admitters.length === 0) {
+      throw new Error(
+        "the member list names no admin, so there is nobody to default the admitters to"
+      );
+    }
+  }
+  admitters.forEach((a, i) => fromHex(a, `admitters[${i}]`, 32));
+  const invitedRole = input.invitedRole ?? INVITED_ROLE.Member;
+  if (![0, 1, 2].includes(invitedRole)) {
+    throw new Error(`invitedRole must be 0 (Admin), 1 (Member) or 2 (ReadOnly), got ${invitedRole}`);
+  }
+  const now = input.now ?? Math.floor(Date.now() / 1e3);
+  const validFor = Math.min(
+    input.validForSecs ?? MAX_INVITATION_VALIDITY_SECS,
+    MAX_INVITATION_VALIDITY_SECS
+  );
+  if (!Number.isInteger(validFor) || validFor <= 0) {
+    throw new Error(`validForSecs must be a positive whole number, got ${input.validForSecs}`);
+  }
+  const nonce2 = input.nonce ?? crypto.getRandomValues(new Uint8Array(32));
+  if (nonce2.length !== 32) {
+    throw new Error(`nonce must be 32 bytes, got ${nonce2.length}`);
+  }
+  const invitation = {
+    inviter_identity: Array.from(inviterKey),
+    group_id: Array.from(groupId),
+    expiration_timestamp: now + validFor,
+    secret_salt: Array.from(nonce2),
+    invited_role: invitedRole,
+    admitters
+  };
+  const signature = await signer.sign(await groupInvitationHash(invitation));
+  if (signature.length !== 64) {
+    throw new Error(`signer returned ${signature.length} bytes, expected a 64-byte Ed25519 signature`);
+  }
+  const signed = {
+    invitation,
+    inviter_signature: hex(signature),
+    inviter_account: input.inviterAccount.trim().toLowerCase()
+  };
+  if (input.admitterAddrs?.length) signed.admitter_addrs = [...input.admitterAddrs];
+  if (input.applicationId) {
+    signed.application_id = Array.from(fromHex(input.applicationId, "applicationId", 32));
+  }
+  if (input.appKey) signed.app_key = Array.from(fromHex(input.appKey, "appKey", 32));
+  return signed;
+}
+function bytes32(value, label2) {
+  if (value.length !== 32) {
+    throw new Error(`${label2} must be 32 bytes, got ${value.length}`);
+  }
+  return new Uint8Array(value);
+}
+
 // src/namespace-op/namespace-op.ts
 var SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 16;
 var NAMESPACE_SIGN_DOMAIN = new TextEncoder().encode("calimero.namespace.v1");
@@ -10120,12 +10286,6 @@ var ROOT_OP2 = {
   NamespaceCreatedV2: 9,
   MemberJoinedViaTeeAttestation: 10
 };
-function bytes32(value, label2) {
-  if (value.length !== 32) {
-    throw new Error(`${label2} must be 32 bytes, got ${value.length}`);
-  }
-  return new Uint8Array(value);
-}
 function optionalBytes32(value, label2) {
   if (value === null || value === void 0) {
     return new Uint8Array([0]);
@@ -10141,21 +10301,11 @@ function borshString2(value) {
 }
 function encodeSignedInvitation(signed) {
   const body = signed.invitation;
-  const admitters = body.admitters ?? [];
   const admitterAddrs = signed.admitter_addrs ?? [];
   return concat(
-    // GroupInvitationFromAdmin.
-    //
-    // `SignerId` and `ContextGroupId` cross JSON as 32 numbers; `AccountId`
-    // crosses as hex. Same width, different spelling, and reading either the
-    // wrong way yields 32 bytes that encode cleanly and verify as nothing.
-    bytes32(body.inviter_identity, "inviter_identity"),
-    bytes32(body.group_id, "group_id"),
-    u64le(body.expiration_timestamp),
-    bytes32(body.secret_salt, "secret_salt"),
-    new Uint8Array([body.invited_role]),
-    u32le(admitters.length),
-    ...admitters.map((a, i) => fromHex(a, `admitters[${i}]`, 32)),
+    // GroupInvitationFromAdmin, from the one encoder the SDK's own invitation
+    // signer uses: the bytes signed and the bytes carried must not drift.
+    encodeGroupInvitation(body),
     // ...then the enclosing SignedGroupOpenInvitation, in declaration order.
     // `inviter_account` sits between the signature and the addresses; putting it
     // anywhere else still encodes 32 bytes and still verifies as nothing.
@@ -10370,8 +10520,10 @@ export {
   EphemeralClient,
   HANDSHAKE_PATH,
   HTTPError,
+  INVITED_ROLE,
   IntentRefusedError,
   LocalStorageTokenStore,
+  MAX_INVITATION_VALIDITY_SECS,
   MemoryTokenStore,
   MeroClient,
   MeroJs,
@@ -10445,11 +10597,14 @@ export {
   createTimeoutSignal,
   createUniversalHttpClient,
   creationInitHash,
+  defaultAdmitters,
   defaultAudience,
   defaultCapabilitiesSetOp,
   deviceCertPayload,
   deviceEnrolmentUrl,
+  deviceScopePayload,
   discoverLocalNodes,
+  encodeGroupInvitation,
   encodeSignedInvitation,
   fetchAttestedTransportKey,
   fetchNodeRelease,
@@ -10460,6 +10615,7 @@ export {
   governanceOpHash,
   groupCreatedOp,
   groupDeletedOp,
+  groupInvitationHash,
   groupReparentedOp,
   hasCap,
   hexEncodeUtf8,
@@ -10495,7 +10651,9 @@ export {
   signAccountLogin,
   signCreationWarrant,
   signDeviceCert,
+  signDeviceScope,
   signGovernanceWarrant,
+  signGroupInvitation,
   signLoginStatement,
   signMemberJoinOp,
   signRequest,