@calimero-network/mero-js 22.8.0 → 23.0.0

package/dist/invitation/index.d.ts

@@ -0,0 +1,2 @@
+export { signGroupInvitation, encodeGroupInvitation, groupInvitationHash, defaultAdmitters, MAX_INVITATION_VALIDITY_SECS, INVITED_ROLE, } from './invitation.js';
+export type { GroupInvitationInput } from './invitation.js';

package/dist/invitation/index.js

@@ -0,0 +1,2 @@
+// Minting a group invitation off-node, with a device key.
+export { signGroupInvitation, encodeGroupInvitation, groupInvitationHash, defaultAdmitters, MAX_INVITATION_VALIDITY_SECS, INVITED_ROLE, } from './invitation.js';

package/dist/invitation/invitation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Minting a group invitation without a node.
+ *
+ * An invitation is not a governance op. Nothing is published when one is made:
+ * it is a bearer credential, `GroupInvitationFromAdmin` borsh-encoded, hashed
+ * with SHA-256 and signed by the inviter's key. A node mints one with its own
+ * namespace key; an account with **no node** signs it here with its device key.
+ *
+ * Every peer that later folds the join resolves `inviter_identity` — the
+ * signing key — to an account through the namespace's device bindings, and then
+ * checks that account holds admin or `CAN_INVITE_MEMBERS` at the join's causal
+ * cut. So the device key must be **bound** in the namespace first. It is when
+ * the account joined through an invitation; an account that was added by
+ * account (`MemberAdded`) has no binding, and a relay has to carry its device
+ * link first — see `AdminApiClient.linkAccountDevice` and `signDeviceScope`.
+ * Without that, every peer refuses the join as signed by a key "bound to no
+ * account".
+ *
+ * Derived from core:
+ *
+ * - `GroupInvitationFromAdmin` / `SignedGroupOpenInvitation` —
+ *   `crates/context/config/src/types.rs`
+ * - the signing — `crates/context/src/handlers/create_group_invitation.rs`:
+ *   `sign(sha256(borsh(invitation)))`
+ * - the admitter default — `NamespaceMembershipService::default_admitters`
+ *
+ * The unit tests pin bytes and a signature produced by core's own types.
+ */
+import type { GroupInvitationFromAdmin, GroupMember, SignedGroupOpenInvitation } from '../admin-api/admin-types.js';
+import { type Signer } from '../signer/signer.js';
+/**
+ * Core's `MAX_INVITATION_VALIDITY_SECS`: one day. Core clamps what a node mints
+ * to it, and this does the same, so a leaked invitation is redeemable no longer
+ * than one a node would have issued.
+ */
+export declare const MAX_INVITATION_VALIDITY_SECS: number;
+/** `invited_role` values, as core numbers them. */
+export declare const INVITED_ROLE: {
+    readonly Admin: 0;
+    readonly Member: 1;
+    readonly ReadOnly: 2;
+};
+/** Borsh-encode the signed body of an invitation, field for field with core. */
+export declare function encodeGroupInvitation(body: GroupInvitationFromAdmin): Uint8Array;
+/** `sha256(borsh(invitation))`: the 32 bytes the inviter's key signs. */
+export declare function groupInvitationHash(body: GroupInvitationFromAdmin): Promise<Uint8Array>;
+/**
+ * The admitters a node names when its caller names none: the group's admins,
+ * sorted by account bytes and deduplicated, as core's `BTreeSet` leaves them.
+ *
+ * Core also adds TEE-admitted accounts, which a member list cannot tell apart
+ * from members by role alone; name those in `admitters` explicitly.
+ */
+export declare function defaultAdmitters(members: readonly GroupMember[]): string[];
+/** What {@link signGroupInvitation} needs. */
+export interface GroupInvitationInput {
+    /** The group (or namespace) invited to, 64 hex. */
+    groupId: string;
+    /**
+     * The account the inviter acts as, 64 hex. An unsigned bootstrap hint the
+     * joiner seeds the group's admin view from; it confers nothing.
+     */
+    inviterAccount: string;
+    /** The device key as a {@link Signer}. Pass this or {@link deviceSecret}. */
+    signer?: Signer;
+    /** The device signing secret, 64 hex. Pass this or {@link signer}. */
+    deviceSecret?: string;
+    /**
+     * Accounts permitted to admit a claim, 64 hex each. Signed.
+     *
+     * Omitted or empty, it defaults to the group's admins, which is what a node
+     * does — pass {@link members} (from `listGroupMembers`) to derive them. An
+     * empty list would mean *claimable by broadcast*, which publishes the
+     * invitation to every subscriber of the namespace topic, so this never
+     * produces one.
+     */
+    admitters?: readonly string[];
+    /** The group's members, to default {@link admitters} from. */
+    members?: readonly GroupMember[];
+    /**
+     * The role granted, as {@link INVITED_ROLE} numbers it. Defaults to Member.
+     * Only an admin may invite an admin; peers refuse the join otherwise.
+     */
+    invitedRole?: number;
+    /**
+     * Seconds from now until it expires, clamped to
+     * {@link MAX_INVITATION_VALIDITY_SECS} (also the default).
+     */
+    validForSecs?: number;
+    /** Unix seconds to count from. Defaults to the clock; for tests. */
+    now?: number;
+    /** The 32-byte uniqueness nonce. Defaults to fresh random bytes. */
+    nonce?: Uint8Array;
+    /** Unsigned bootstrap: the group's application id, 64 hex. */
+    applicationId?: string;
+    /** Unsigned bootstrap: the group's `app_key` (core's `bytecode_id`), 64 hex. */
+    appKey?: string;
+    /** Unsigned bootstrap: multiaddrs for the admitters, `/p2p/<peer>` included. */
+    admitterAddrs?: readonly string[];
+}
+/**
+ * Sign a group invitation with a device key, returning it in the JSON shape a
+ * node's `createGroupInvitation` returns — so it goes to `joinGroup`,
+ * `signMemberJoinOp` and `admitJoin` unchanged.
+ */
+export declare function signGroupInvitation(input: GroupInvitationInput): Promise<SignedGroupOpenInvitation>;

package/dist/invitation/invitation.js

@@ -0,0 +1,104 @@
+import { concat, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
+/**
+ * Core's `MAX_INVITATION_VALIDITY_SECS`: one day. Core clamps what a node mints
+ * to it, and this does the same, so a leaked invitation is redeemable no longer
+ * than one a node would have issued.
+ */
+export const MAX_INVITATION_VALIDITY_SECS = 24 * 60 * 60;
+/** `invited_role` values, as core numbers them. */
+export const INVITED_ROLE = { Admin: 0, Member: 1, ReadOnly: 2 };
+/** Borsh-encode the signed body of an invitation, field for field with core. */
+export 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)));
+}
+/** `sha256(borsh(invitation))`: the 32 bytes the inviter's key signs. */
+export async function groupInvitationHash(body) {
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', encodeGroupInvitation(body)));
+}
+/**
+ * The admitters a node names when its caller names none: the group's admins,
+ * sorted by account bytes and deduplicated, as core's `BTreeSet` leaves them.
+ *
+ * Core also adds TEE-admitted accounts, which a member list cannot tell apart
+ * from members by role alone; name those in `admitters` explicitly.
+ */
+export function defaultAdmitters(members) {
+    const admins = new Set(members.filter((m) => m.role === 'Admin').map((m) => m.identity.toLowerCase()));
+    // Lowercase hex sorts as the bytes do.
+    return [...admins].sort();
+}
+/**
+ * Sign a group invitation with a device key, returning it in the JSON shape a
+ * node's `createGroupInvitation` returns — so it goes to `joinGroup`,
+ * `signMemberJoinOp` and `admitJoin` unchanged.
+ */
+export 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() / 1000);
+    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 nonce = input.nonce ?? crypto.getRandomValues(new Uint8Array(32));
+    if (nonce.length !== 32) {
+        throw new Error(`nonce must be 32 bytes, got ${nonce.length}`);
+    }
+    const invitation = {
+        inviter_identity: Array.from(inviterKey),
+        group_id: Array.from(groupId),
+        expiration_timestamp: now + validFor,
+        secret_salt: Array.from(nonce),
+        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));
+    // The brand marks a value as one to pass through unchanged. This one is
+    // signed, so it qualifies the same way a node's does.
+    return signed;
+}
+/** A required `[u8; 32]`, as JSON carries it: 32 byte values. */
+function bytes32(value, label) {
+    if (value.length !== 32) {
+        throw new Error(`${label} must be 32 bytes, got ${value.length}`);
+    }
+    return new Uint8Array(value);
+}

package/dist/namespace-op/namespace-op.d.ts

@@ -29,8 +29,26 @@ import { type Signer } from '../signer/signer.js';
  * 16: a namespace can be founded through a relay (a delegated
  * `NamespaceCreatedV2`), and `GroupOp::FoundingRelayAttested` lets that relay
  * admit itself as the namespace's first TEE. Again no layout this module signs.
+ *
+ * 17: `RootOp::GroupCreated` carries a `salt`, and its `group_id` must be the
+ * one `createdSubgroupId(admin, parentId, restricted, salt)` derives
+ * (calimero-network/core#4244), so two concurrent creates for one id can never
+ * name different creators. The layout of that variant changed.
+ *
+ * 18: owner-level ops need the account ROOT, not only a device of it
+ * (calimero-network/core, root-guarded owner ops). `GroupOp::RootGuarded` and
+ * `RootOp::RootGuarded` are appended and carry a root-signed proof, and the bare
+ * `TransferOwnership`, `AdminChanged`, `GroupDelete` and TEE policy ops are
+ * refused. No layout this module signs changes; see `../owner-op` for the proof.
+ *
+ * 19 is reserved for calimero-network/core#4269.
+ *
+ * 20: no layout change. A delegated `GroupCreated` whose executor is a TEE at
+ * the namespace root now seats that TEE in the new subgroup
+ * (calimero-network/core#4276), an apply-time rule older peers disagree on.
+ * Core signs and checks at 20, so every op this module signs must too.
  */
-export declare const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 16;
+export declare const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 20;
 /**
  * Borsh-encode a `SignedGroupOpenInvitation`.
  *

package/dist/namespace-op/namespace-op.js

@@ -1,3 +1,4 @@
+import { encodeGroupInvitation } from '../invitation/invitation.js';
 import { concat, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
 import { resolveSigner } from '../signer/signer.js';
 /**
@@ -14,8 +15,26 @@ import { resolveSigner } from '../signer/signer.js';
  * 16: a namespace can be founded through a relay (a delegated
  * `NamespaceCreatedV2`), and `GroupOp::FoundingRelayAttested` lets that relay
  * admit itself as the namespace's first TEE. Again no layout this module signs.
+ *
+ * 17: `RootOp::GroupCreated` carries a `salt`, and its `group_id` must be the
+ * one `createdSubgroupId(admin, parentId, restricted, salt)` derives
+ * (calimero-network/core#4244), so two concurrent creates for one id can never
+ * name different creators. The layout of that variant changed.
+ *
+ * 18: owner-level ops need the account ROOT, not only a device of it
+ * (calimero-network/core, root-guarded owner ops). `GroupOp::RootGuarded` and
+ * `RootOp::RootGuarded` are appended and carry a root-signed proof, and the bare
+ * `TransferOwnership`, `AdminChanged`, `GroupDelete` and TEE policy ops are
+ * refused. No layout this module signs changes; see `../owner-op` for the proof.
+ *
+ * 19 is reserved for calimero-network/core#4269.
+ *
+ * 20: no layout change. A delegated `GroupCreated` whose executor is a TEE at
+ * the namespace root now seats that TEE in the new subgroup
+ * (calimero-network/core#4276), an apply-time rule older peers disagree on.
+ * Core signs and checks at 20, so every op this module signs must too.
  */
-export const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 16;
+export const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 20;
 /** Domain prefixed to the signable bytes; core's `NAMESPACE_GOVERNANCE_SIGN_DOMAIN`. */
 const NAMESPACE_SIGN_DOMAIN = new TextEncoder().encode('calimero.namespace.v1');
 /** `NamespaceOp::Root` is the first variant. */
@@ -38,13 +57,6 @@ const ROOT_OP = {
     NamespaceCreatedV2: 9,
     MemberJoinedViaTeeAttestation: 10,
 };
-/** A required `[u8; 32]`, as JSON carries it: 32 byte values. */
-function bytes32(value, label) {
-    if (value.length !== 32) {
-        throw new Error(`${label} must be 32 bytes, got ${value.length}`);
-    }
-    return new Uint8Array(value);
-}
 /**
  * Borsh `Option<[u8; 32]>` from the byte array JSON carries it as.
  *
@@ -78,15 +90,11 @@ function borshString(value) {
  */
 export 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.

package/dist/owner-op/index.d.ts

@@ -0,0 +1,2 @@
+export { OWNER_OP_KIND, transferOwnershipOp, groupDeleteOp, adminChangedOp, teeAuthoringPolicyOp, teeAdmissionPolicyOp, teeReleaseAdmissionPolicyOp, ownerOpDigest, ownerOpSigningPayload, signOwnerOpProof, rootGuardedOpBytes, } from './owner-op.js';
+export type { OwnerOp, OwnerOpKind, OwnerOpPlane, OwnerOpProofInput, TeeAdmissionPolicyOpInput, TeeReleaseAdmissionPolicyOpInput, } from './owner-op.js';

package/dist/owner-op/index.js

@@ -0,0 +1,3 @@
+// Root proofs for owner-level governance ops: what a nodeless or cold-root
+// account signs offline so a stolen device alone cannot take a group.
+export { OWNER_OP_KIND, transferOwnershipOp, groupDeleteOp, adminChangedOp, teeAuthoringPolicyOp, teeAdmissionPolicyOp, teeReleaseAdmissionPolicyOp, ownerOpDigest, ownerOpSigningPayload, signOwnerOpProof, rootGuardedOpBytes, } from './owner-op.js';

package/dist/owner-op/owner-op.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Which owner-level op a proof authorises. The value is the byte core signs,
+ * its `OwnerOpKind` discriminant.
+ */
+export declare const OWNER_OP_KIND: {
+    readonly transferOwnership: 0;
+    readonly adminChanged: 1;
+    readonly groupDelete: 2;
+    readonly teeAdmissionPolicy: 3;
+    readonly teeAuthoringPolicy: 4;
+    readonly teeReleaseAdmissionPolicy: 5;
+};
+export type OwnerOpKind = keyof typeof OWNER_OP_KIND;
+/** Which plane the op is on: a `GroupOp` on a group, or a `RootOp` on the namespace. */
+export type OwnerOpPlane = 'group' | 'root';
+/** An encoded owner-level op: its borsh bytes, its kind and its plane. */
+export interface OwnerOp {
+    kind: OwnerOpKind;
+    plane: OwnerOpPlane;
+    /** The op's borsh bytes: exactly what the node builds, and what the digest covers. */
+    bytes: Uint8Array;
+}
+/** Hand the group to `newOwner` (an account, hex), who must already be an admin. */
+export declare function transferOwnershipOp(newOwner: string): OwnerOp;
+/** The owner-only deletion of a group that holds no contexts. */
+export declare function groupDeleteOp(): OwnerOp;
+/** Repoint the namespace's admin pin at `newAdmin` (an account, hex). A root op. */
+export declare function adminChangedOp(newAdmin: string): OwnerOp;
+/** The TEE authoring policy `PUT`/`DELETE …/settings/tee-authoring-policy` publishes. */
+export declare function teeAuthoringPolicyOp(allowedMrtd: string[]): OwnerOp;
+/** A measurement-list admission policy, as the node publishes it (the V2 form). */
+export interface TeeAdmissionPolicyOpInput {
+    allowedMrtd: string[];
+    allowedRtmr0: string[];
+    allowedRtmr1: string[];
+    allowedRtmr2: string[];
+    allowedRtmr3: string[];
+    allowedTcbStatuses: string[];
+    acceptMock: boolean;
+    mode?: 'replica' | 'relay';
+}
+/**
+ * The measurement-list admission policy `PUT …/settings/tee-admission-policy`
+ * publishes. Pass the fields exactly as you send them: the node signs over the
+ * op it builds from them, and any difference is a different op.
+ */
+export declare function teeAdmissionPolicyOp(input: TeeAdmissionPolicyOpInput): OwnerOp;
+/** A signed-release admission policy, as the node publishes it (the V2 form). */
+export interface TeeReleaseAdmissionPolicyOpInput {
+    allowedProfiles: string[];
+    /**
+     * The oldest release admitted. Give it in the node's normalised form
+     * (`X.Y.Z`, no tag prefix): the node normalises what it is sent before it
+     * builds the op, and the proof must be for the op it builds.
+     */
+    minReleaseVersion?: string;
+    allowedTcbStatuses: string[];
+    acceptMock: boolean;
+    mode?: 'replica' | 'relay';
+}
+/** The signed-release admission policy `PUT …/settings/tee-admission-policy` publishes. */
+export declare function teeReleaseAdmissionPolicyOp(input: TeeReleaseAdmissionPolicyOpInput): OwnerOp;
+/** core's `OwnerOpAuthorization::op_digest`: the op's bytes, hashed under the body domain. */
+export declare function ownerOpDigest(opBytes: Uint8Array): Promise<Uint8Array>;
+/** What an owner-op proof binds, apart from the op and the key that signs it. */
+export interface OwnerOpProofInput {
+    /** The account root's signing secret, 64 hex. Never sent anywhere. */
+    rootSecret: string;
+    /** The namespace the op is published in (`getGroupInfo(...).namespaceId`), hex. */
+    namespaceId: string;
+    /**
+     * The group the op acts on, hex. For `adminChanged` and the TEE policies,
+     * the namespace root.
+     */
+    groupId: string;
+    /** The op, from one of the encoders here. */
+    op: OwnerOp;
+    /** The group's current guarded-op counter (`getGroupInfo(groupId).ownerOpCounter`). */
+    counter: number | bigint;
+    /**
+     * The root epoch that signs, 0 for a root that has never been handed off.
+     * A later epoch needs `chain`.
+     */
+    keyEpoch?: number;
+    /**
+     * The account's root-key handoffs, epoch 0 upward, each the hex borsh of a
+     * `RootKeyHandoff` (account 32, from_epoch u32, new root key 32, signature
+     * 64). It must reach at least `keyEpoch`, and at least the epoch the group
+     * has recorded for the account, or the node refuses the proof.
+     */
+    chain?: string[];
+}
+/** core's `OwnerOpTerms::signing_payload`. */
+export declare function ownerOpSigningPayload(input: {
+    account: string;
+    namespaceId: string;
+    groupId: string;
+    kind: OwnerOpKind;
+    opDigest: Uint8Array;
+    counter: number | bigint;
+    keyEpoch: number;
+}): Promise<Uint8Array>;
+/**
+ * Sign a root proof for `op` and return it as core's `rootProof`: the hex
+ * borsh of an `AccountProof<OwnerOpAuthorization>`.
+ *
+ * Layout: `AccountGenesis` (version u8 + root pk 32), the handoff chain (u32
+ * count + 132 bytes each), then `OwnerOpAuthorization` (account 32, namespace
+ * 32, group 32, kind u8, op digest 32, counter u64, key epoch u32, signature
+ * 64).
+ */
+export declare function signOwnerOpProof(input: OwnerOpProofInput): Promise<string>;
+/**
+ * The `RootGuarded` wrapper core publishes: the op and its proof, as one
+ * `GroupOp` or `RootOp`. A client never sends this to a node (the endpoints
+ * take the proof and build the wrapper); it is here so the whole encoding is
+ * checkable against core's vector.
+ */
+export declare function rootGuardedOpBytes(op: OwnerOp, rootProof: string): Uint8Array;

package/dist/owner-op/owner-op.js

@@ -0,0 +1,214 @@
+/**
+ * Root proofs for owner-level governance ops (core schema 18).
+ *
+ * A device key speaks for its account everywhere in governance, so a stolen
+ * device used to be enough to take a group from its owner: promote an
+ * accomplice, transfer ownership, remove the owner. Core now refuses the ops
+ * that can do that unless they carry an authorisation signed by the account's
+ * **root** key, which a device does not hold:
+ *
+ * - `GroupOp::TransferOwnership`, `GroupOp::GroupDelete` and
+ *   `RootOp::AdminChanged`, which are owner-only;
+ * - the TEE admission, release-admission and authoring policies, which stay
+ *   admin-level but need the signing admin's own root.
+ *
+ * A node that holds the account root (as `merod init` provisions) signs the
+ * proof itself, so a caller on such a node passes nothing. This module is for
+ * the other case: a nodeless account, or a root kept cold, signing offline and
+ * passing the hex proof as `rootProof`.
+ *
+ * What the root signs binds the account, the namespace, the group, the kind of
+ * op, a digest of the op's own borsh bytes, the root epoch, and the group's
+ * guarded-op counter. Read that counter (`ownerOpCounter`, with `namespaceId`)
+ * from `getGroupInfo` first: the node applies a proof only while the group is
+ * still at that count, and advances it once the op applies, so each proof is
+ * single-use. For `AdminChanged` and the TEE policies the group is the
+ * namespace root.
+ *
+ * Byte layouts follow core's `calimero_account::OwnerOpAuthorization` and
+ * `calimero_governance_types::{GroupOp, RootOp}`. They are pinned against core's
+ * own vectors (`crates/account/src/tests/owner_op.rs`,
+ * `root_guarded_vectors_are_stable` in `crates/governance-types/src/tests.rs`)
+ * in `owner-op.test.ts`.
+ */
+import { concat, derivePublicKey, domainHash, fromHex, fromHexUnsized, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+/** core's `OWNER_OP_SIGN_DOMAIN`: what the root signs under. */
+const OWNER_OP_SIGN_DOMAIN = new TextEncoder().encode('calimero.account.owner-op.v1');
+/** core's `OWNER_OP_BODY_DOMAIN`: what the op's bytes are hashed under. */
+const OWNER_OP_BODY_DOMAIN = new TextEncoder().encode('calimero.account.owner-op.body.v1');
+/** core's `ACCOUNT_ID_DOMAIN`. */
+const ACCOUNT_ID_DOMAIN = new TextEncoder().encode('calimero.account.genesis.v1');
+/** core's `ACCOUNT_GENESIS_VERSION`. */
+const ACCOUNT_GENESIS_VERSION = 2;
+/**
+ * Which owner-level op a proof authorises. The value is the byte core signs,
+ * its `OwnerOpKind` discriminant.
+ */
+export const OWNER_OP_KIND = {
+    transferOwnership: 0,
+    adminChanged: 1,
+    groupDelete: 2,
+    teeAdmissionPolicy: 3,
+    teeAuthoringPolicy: 4,
+    teeReleaseAdmissionPolicy: 5,
+};
+/** `GroupOp` discriminants, by position in core's enum. */
+const GROUP_OP = {
+    GroupDelete: 14,
+    TransferOwnership: 21,
+    TeeAuthoringPolicySet: 33,
+    TeeAdmissionPolicySetV2: 37,
+    TeeReleaseAdmissionPolicySetV2: 38,
+    RootGuarded: 42,
+};
+/** `RootOp` discriminants, by position in core's enum. */
+const ROOT_OP = {
+    AdminChanged: 3,
+    RootGuarded: 12,
+};
+/** core's `TeeAdmissionMode` discriminants. */
+const TEE_MODE = { replica: 0, relay: 1 };
+const te = new TextEncoder();
+function tag(byte) {
+    return new Uint8Array([byte]);
+}
+function borshString(value) {
+    const bytes = te.encode(value);
+    return concat(u32le(bytes.length), bytes);
+}
+function borshStrings(values) {
+    return concat(u32le(values.length), ...values.map(borshString));
+}
+function borshBool(value) {
+    return tag(value ? 1 : 0);
+}
+function teeMode(mode) {
+    const byte = TEE_MODE[mode ?? 'replica'];
+    if (byte === undefined) {
+        throw new Error(`mode must be replica or relay, got ${String(mode)}`);
+    }
+    return tag(byte);
+}
+/** Hand the group to `newOwner` (an account, hex), who must already be an admin. */
+export function transferOwnershipOp(newOwner) {
+    return {
+        kind: 'transferOwnership',
+        plane: 'group',
+        bytes: concat(tag(GROUP_OP.TransferOwnership), fromHex(newOwner, 'newOwner', 32)),
+    };
+}
+/** The owner-only deletion of a group that holds no contexts. */
+export function groupDeleteOp() {
+    return { kind: 'groupDelete', plane: 'group', bytes: tag(GROUP_OP.GroupDelete) };
+}
+/** Repoint the namespace's admin pin at `newAdmin` (an account, hex). A root op. */
+export function adminChangedOp(newAdmin) {
+    return {
+        kind: 'adminChanged',
+        plane: 'root',
+        bytes: concat(tag(ROOT_OP.AdminChanged), fromHex(newAdmin, 'newAdmin', 32)),
+    };
+}
+/** The TEE authoring policy `PUT`/`DELETE …/settings/tee-authoring-policy` publishes. */
+export function teeAuthoringPolicyOp(allowedMrtd) {
+    return {
+        kind: 'teeAuthoringPolicy',
+        plane: 'group',
+        bytes: concat(tag(GROUP_OP.TeeAuthoringPolicySet), borshStrings(allowedMrtd)),
+    };
+}
+/**
+ * The measurement-list admission policy `PUT …/settings/tee-admission-policy`
+ * publishes. Pass the fields exactly as you send them: the node signs over the
+ * op it builds from them, and any difference is a different op.
+ */
+export function teeAdmissionPolicyOp(input) {
+    return {
+        kind: 'teeAdmissionPolicy',
+        plane: 'group',
+        bytes: concat(tag(GROUP_OP.TeeAdmissionPolicySetV2), borshStrings(input.allowedMrtd), borshStrings(input.allowedRtmr0), borshStrings(input.allowedRtmr1), borshStrings(input.allowedRtmr2), borshStrings(input.allowedRtmr3), borshStrings(input.allowedTcbStatuses), borshBool(input.acceptMock), teeMode(input.mode)),
+    };
+}
+/** The signed-release admission policy `PUT …/settings/tee-admission-policy` publishes. */
+export function teeReleaseAdmissionPolicyOp(input) {
+    const minRelease = input.minReleaseVersion === undefined
+        ? tag(0)
+        : concat(tag(1), borshString(input.minReleaseVersion));
+    return {
+        kind: 'teeReleaseAdmissionPolicy',
+        plane: 'group',
+        bytes: concat(tag(GROUP_OP.TeeReleaseAdmissionPolicySetV2), borshStrings(input.allowedProfiles), minRelease, borshStrings(input.allowedTcbStatuses), borshBool(input.acceptMock), teeMode(input.mode)),
+    };
+}
+/** core's `OwnerOpAuthorization::op_digest`: the op's bytes, hashed under the body domain. */
+export async function ownerOpDigest(opBytes) {
+    return domainHash(OWNER_OP_BODY_DOMAIN, [opBytes]);
+}
+/** core's `OwnerOpTerms::signing_payload`. */
+export async function ownerOpSigningPayload(input) {
+    return domainHash(OWNER_OP_SIGN_DOMAIN, [
+        fromHex(input.account, 'account', 32),
+        fromHex(input.namespaceId, 'namespaceId', 32),
+        fromHex(input.groupId, 'groupId', 32),
+        tag(kindByte(input.kind)),
+        input.opDigest,
+        u64le(input.counter),
+        u32le(input.keyEpoch),
+    ]);
+}
+function kindByte(kind) {
+    const byte = OWNER_OP_KIND[kind];
+    if (byte === undefined) {
+        throw new Error(`unknown owner-op kind ${String(kind)}`);
+    }
+    return byte;
+}
+const HANDOFF_BYTES = 32 + 4 + 32 + 64;
+/**
+ * Sign a root proof for `op` and return it as core's `rootProof`: the hex
+ * borsh of an `AccountProof<OwnerOpAuthorization>`.
+ *
+ * Layout: `AccountGenesis` (version u8 + root pk 32), the handoff chain (u32
+ * count + 132 bytes each), then `OwnerOpAuthorization` (account 32, namespace
+ * 32, group 32, kind u8, op digest 32, counter u64, key epoch u32, signature
+ * 64).
+ */
+export async function signOwnerOpProof(input) {
+    const rootPublicKey = await derivePublicKey(input.rootSecret);
+    const genesis = concat(tag(ACCOUNT_GENESIS_VERSION), rootPublicKey);
+    const account = hex(await domainHash(ACCOUNT_ID_DOMAIN, [genesis]));
+    const keyEpoch = input.keyEpoch ?? 0;
+    const chain = (input.chain ?? []).map((handoff, index) => {
+        const bytes = fromHexUnsized(handoff, `chain[${index}]`);
+        if (bytes.length !== HANDOFF_BYTES) {
+            throw new Error(`chain[${index}] must be a ${HANDOFF_BYTES}-byte RootKeyHandoff, got ${bytes.length}`);
+        }
+        return bytes;
+    });
+    if (keyEpoch > chain.length) {
+        throw new Error(`keyEpoch ${keyEpoch} needs ${keyEpoch} handoffs in chain, got ${chain.length}`);
+    }
+    const opDigest = await ownerOpDigest(input.op.bytes);
+    const payload = await ownerOpSigningPayload({
+        account,
+        namespaceId: input.namespaceId,
+        groupId: input.groupId,
+        kind: input.op.kind,
+        opDigest,
+        counter: input.counter,
+        keyEpoch,
+    });
+    const key = await importSigningKey(input.rootSecret);
+    const signature = new Uint8Array(await crypto.subtle.sign('Ed25519', key, payload));
+    return hex(concat(genesis, u32le(chain.length), ...chain, fromHex(account, 'account', 32), fromHex(input.namespaceId, 'namespaceId', 32), fromHex(input.groupId, 'groupId', 32), tag(kindByte(input.op.kind)), opDigest, u64le(input.counter), u32le(keyEpoch), signature));
+}
+/**
+ * The `RootGuarded` wrapper core publishes: the op and its proof, as one
+ * `GroupOp` or `RootOp`. A client never sends this to a node (the endpoints
+ * take the proof and build the wrapper); it is here so the whole encoding is
+ * checkable against core's vector.
+ */
+export function rootGuardedOpBytes(op, rootProof) {
+    const wrapper = op.plane === 'group' ? GROUP_OP.RootGuarded : ROOT_OP.RootGuarded;
+    return concat(tag(wrapper), op.bytes, fromHexUnsized(rootProof, 'rootProof'));
+}