@calimero-network/mero-js 22.3.0 → 22.5.0

package/dist/warrant/creation-warrant.js

@@ -0,0 +1,189 @@
+/**
+ * Mint a creation warrant: the author's consent for one relay to create one
+ * context in one group, once.
+ *
+ * The intent warrant in `warrant.ts` lets an account with no node *write* to a
+ * context; this lets it *create* one. The relay executes the warrant and
+ * publishes `GroupOp::ContextRegisteredOnBehalf` carrying it, and every peer
+ * checks the **author's** `CAN_CREATE_CONTEXT` (or admin) — the relay needs no
+ * create rights of its own, only standing to act for members. The app's `init`
+ * runs as the author's account.
+ *
+ * Same primitives and the same two-widths trap as `warrant.ts`: counts **inside
+ * the encoding** are borsh `u32`, counts the **signing preimage** hashes are
+ * `u64`. The two `Option<String>` labels add a third shape: on the wire an
+ * option is a one-byte tag followed (when present) by a `u32`-prefixed string,
+ * while the preimage hashes the tag and the bytes as two separate parts, the
+ * bytes empty when absent. That is what keeps `None` and `Some("")` distinct in
+ * both.
+ *
+ * **The byte contract is pinned in core**, at
+ * `crates/account/src/tests/creation_wire_fixture.rs`, and this module's test
+ * asserts the same vectors. A drift would surface at a relay as a 403.
+ */
+import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+import { citedHeads } from './warrant.js';
+const SIGN_DOMAIN = new TextEncoder().encode('calimero.context-creation-warrant.v1');
+const INIT_DOMAIN = new TextEncoder().encode('calimero.context-creation.init.v1');
+/** core's cap on `service_name` and `name`, in UTF-8 bytes. */
+const MAX_LABEL_BYTES = 256;
+/**
+ * The commitment a creation warrant carries in place of the init arguments.
+ *
+ * Hashes `JSON.stringify(initArgs)`, the same bytes `RelayClient.createContext`
+ * sends, under its own domain.
+ */
+export async function creationInitHash(initArgs) {
+    const bytes = new TextEncoder().encode(JSON.stringify(initArgs));
+    return domainHash(INIT_DOMAIN, [bytes]);
+}
+/**
+ * The bytes the device key signs. Exported for the conformance test only — not
+ * from the package root.
+ */
+export async function creationWarrantPreimage(p) {
+    // An option is two parts here — its tag, then its bytes (empty when absent) —
+    // so `None` and `Some("")` hash differently. u64 counts HERE; u32 on the wire.
+    return domainHash(SIGN_DOMAIN, [
+        p.group,
+        p.seed,
+        p.authorAccount,
+        p.deviceKey,
+        p.executor,
+        p.applicationId,
+        new Uint8Array([p.serviceName === null ? 0 : 1]),
+        p.serviceName ?? new Uint8Array(0),
+        new Uint8Array([p.name === null ? 0 : 1]),
+        p.name ?? new Uint8Array(0),
+        p.initHash,
+        u64le(p.accountHeads.length),
+        ...p.accountHeads,
+        u64le(p.governanceFloor.length),
+        ...p.governanceFloor,
+        u64le(p.nonce),
+        u64le(p.notAfter),
+    ]);
+}
+/**
+ * Sign a creation warrant and return it hex-encoded, with its seed.
+ *
+ * Returns the encoding rather than an object for the reason `signWarrant`
+ * does: the signature covers exactly these bytes.
+ */
+export async function signCreationWarrant(input) {
+    const group = fromHex(input.group, 'group', 32);
+    const seed = input.seed === undefined
+        ? crypto.getRandomValues(new Uint8Array(32))
+        : fromHex(input.seed, 'seed', 32);
+    const authorAccount = fromHex(input.authorAccount, 'authorAccount', 32);
+    const executor = fromHex(input.executor, 'executor', 32);
+    const applicationId = fromHex(input.applicationId, 'applicationId', 32);
+    const serviceName = label(input.serviceName, 'serviceName');
+    const name = label(input.name, 'name');
+    const accountHeads = citedHeads(input.accountHeads, 'accountHeads');
+    const governanceFloor = citedHeads(input.governanceFloor, 'governanceFloor');
+    const key = await importSigningKey(input.deviceSecret);
+    const deviceKey = await derivePublicKey(input.deviceSecret);
+    const initHash = await creationInitHash(input.initArgs);
+    const preimage = await creationWarrantPreimage({
+        group,
+        seed,
+        authorAccount,
+        deviceKey,
+        executor,
+        applicationId,
+        serviceName,
+        name,
+        initHash,
+        accountHeads,
+        governanceFloor,
+        nonce: input.nonce,
+        notAfter: input.notAfter,
+    });
+    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    const warrant = hex(concat(group, seed, authorAccount, deviceKey, executor, applicationId, borshOption(serviceName), borshOption(name), initHash, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, u64le(input.nonce), u64le(input.notAfter), signature));
+    return { warrant, seed: hex(seed) };
+}
+/**
+ * Decode a hex creation warrant back into its fields.
+ *
+ * Refuses truncated or trailing bytes rather than reading a neighbouring field.
+ * Does not verify the signature.
+ */
+export function parseCreationWarrant(warrant) {
+    const clean = warrant.trim();
+    if (!/^[0-9a-fA-F]*$/.test(clean) || clean.length % 2 !== 0) {
+        throw new Error('creation warrant must be an even number of hex characters');
+    }
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i += 1) {
+        bytes[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    const view = new DataView(bytes.buffer);
+    let o = 0;
+    const take = (n, what) => {
+        if (o + n > bytes.length) {
+            throw new Error(`creation warrant ends inside ${what} (${bytes.length} bytes)`);
+        }
+        const out = bytes.subarray(o, o + n);
+        o += n;
+        return out;
+    };
+    const u32 = (what) => view.getUint32(take(4, what).byteOffset, true);
+    const u64 = (what) => view.getBigUint64(take(8, what).byteOffset, true);
+    const option = (what) => {
+        const tag = take(1, what)[0];
+        if (tag === 0)
+            return null;
+        if (tag !== 1)
+            throw new Error(`${what} has option tag ${tag}, expected 0 or 1`);
+        const len = u32(what);
+        if (len > MAX_LABEL_BYTES) {
+            throw new Error(`${what} is ${len} bytes, over the ${MAX_LABEL_BYTES} a node accepts`);
+        }
+        return new TextDecoder('utf-8', { fatal: true }).decode(take(len, what));
+    };
+    const heads = (what) => {
+        const count = u32(what);
+        if (count > 64) {
+            throw new Error(`${what} cites ${count} heads, over the 64 a node accepts`);
+        }
+        return Array.from({ length: count }, () => hex(take(32, what)));
+    };
+    const fields = {
+        group: hex(take(32, 'group')),
+        seed: hex(take(32, 'seed')),
+        authorAccount: hex(take(32, 'authorAccount')),
+        deviceKey: hex(take(32, 'deviceKey')),
+        executor: hex(take(32, 'executor')),
+        applicationId: hex(take(32, 'applicationId')),
+        serviceName: option('serviceName'),
+        name: option('name'),
+        initHash: hex(take(32, 'initHash')),
+        accountHeads: heads('accountHeads'),
+        governanceFloor: heads('governanceFloor'),
+        nonce: u64('nonce'),
+        notAfter: u64('notAfter'),
+        signature: hex(take(64, 'signature')),
+    };
+    if (o !== bytes.length) {
+        throw new Error(`creation warrant is ${bytes.length} bytes but its fields account for ${o}`);
+    }
+    return fields;
+}
+/** UTF-8 encode an optional label, refusing one longer than a node accepts. */
+function label(value, what) {
+    if (value === undefined)
+        return null;
+    const bytes = new TextEncoder().encode(value);
+    if (bytes.length > MAX_LABEL_BYTES) {
+        throw new Error(`${what} is ${bytes.length} UTF-8 bytes, over the ${MAX_LABEL_BYTES} a node accepts`);
+    }
+    return bytes;
+}
+/** Borsh `Option<String>`: `0x00`, or `0x01` then a u32 length and the bytes. */
+function borshOption(bytes) {
+    if (bytes === null)
+        return new Uint8Array([0]);
+    return concat(new Uint8Array([1]), u32le(bytes.length), bytes);
+}

package/dist/warrant/governance-op.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Encode the governance ops a member may have a relay publish for them.
+ *
+ * A governance warrant commits to an op's **borsh bytes**, not to a description
+ * of it, so the client has to produce exactly the bytes the node decodes. These
+ * encoders cover the delegable ops (core's `GroupOp::delegable_form` and
+ * `RootOp::delegable_form`) that a keyholder app is likely to need. Every
+ * discriminant is a variant's position in core's enum, which is how borsh
+ * encodes a Rust enum; they are pinned against core's own vectors in the test.
+ *
+ * **Delegable form.** A removal, a leave and a cascade delete carry fields only
+ * the publisher can compute (post-state hashes, the enumerated subtree). The
+ * member signs them cleared, and these encoders only ever produce the cleared
+ * form, which is the one a relay accepts. The relay fills them in afterwards.
+ *
+ * Sources in core, for the next person to check a discriminant:
+ * `crates/governance-types/src/lib.rs` (`GroupOp`, `RootOp`),
+ * `crates/primitives/src/context.rs` (`GroupMemberRole`), and the vectors in
+ * `crates/governance-types/src/tests.rs` (`delegated_governance_op_vectors_are_stable`).
+ */
+/**
+ * Which plane an op is published on: `group` is a `GroupOp` on the group's own
+ * log, `root` a `RootOp` on the namespace log. The kind is signed over, so
+ * consent to one can never be presented as the other.
+ */
+export type GovernanceOpKind = 'group' | 'root';
+/** An encoded governance op and the plane it belongs to. */
+export interface GovernanceOp {
+    kind: GovernanceOpKind;
+    /** The op's borsh bytes in delegable form: what the warrant commits to. */
+    bytes: Uint8Array;
+}
+/** A group member's role. Borsh discriminants follow core's `GroupMemberRole`. */
+export type GovernanceMemberRole = 'Admin' | 'Member' | 'ReadOnly';
+/**
+ * Add `member` (an account, hex) to the group with `role`.
+ *
+ * Applied as the author: adding a `Member` needs `MANAGE_MEMBERS` or admin,
+ * adding an `Admin` needs admin.
+ */
+export declare function memberAddedOp(member: string, memberRole: GovernanceMemberRole): GovernanceOp;
+/**
+ * Remove `member` (an account, hex) from the group, in delegable form: both
+ * post-state claims cleared, for the relay to compute from its own view.
+ */
+export declare function memberRemovedOp(member: string): GovernanceOp;
+/**
+ * The author leaves the group, in delegable form. The node applies it only when
+ * `member` is the author's own account.
+ */
+export declare function memberLeftOp(member: string): GovernanceOp;
+/** Set `member`'s role (an account, hex). */
+export declare function memberRoleSetOp(member: string, memberRole: GovernanceMemberRole): GovernanceOp;
+/** What a subgroup is created with. */
+export interface GroupCreatedInput {
+    /** The new subgroup's id, hex (32 bytes). Choose it fresh; a taken id is refused. */
+    groupId: string;
+    /** The group it is nested under, hex: the namespace root or an existing subgroup. */
+    parentId: string;
+    /** `true` for a Restricted subgroup (the usual default), `false` for born-Open. */
+    restricted: boolean;
+    /**
+     * The subgroup's founding admin, hex: the **author's** account. The node
+     * refuses any other, since the op is applied as the author.
+     */
+    admin: string;
+}
+/**
+ * Create a subgroup under `parentId`, a root op published on the namespace.
+ *
+ * Needs `CAN_CREATE_SUBGROUP` or admin on the parent; the author, not the
+ * relay, becomes the new subgroup's admin.
+ */
+export declare function groupCreatedOp(input: GroupCreatedInput): GovernanceOp;
+/** Move `childGroupId` under `newParentId`, a root op. */
+export declare function groupReparentedOp(childGroupId: string, newParentId: string): GovernanceOp;
+/**
+ * Delete `rootGroupId` and its subtree, in delegable form: both cascade lists
+ * empty, for the relay to enumerate.
+ */
+export declare function groupDeletedOp(rootGroupId: string): GovernanceOp;

package/dist/warrant/governance-op.js

@@ -0,0 +1,125 @@
+/**
+ * Encode the governance ops a member may have a relay publish for them.
+ *
+ * A governance warrant commits to an op's **borsh bytes**, not to a description
+ * of it, so the client has to produce exactly the bytes the node decodes. These
+ * encoders cover the delegable ops (core's `GroupOp::delegable_form` and
+ * `RootOp::delegable_form`) that a keyholder app is likely to need. Every
+ * discriminant is a variant's position in core's enum, which is how borsh
+ * encodes a Rust enum; they are pinned against core's own vectors in the test.
+ *
+ * **Delegable form.** A removal, a leave and a cascade delete carry fields only
+ * the publisher can compute (post-state hashes, the enumerated subtree). The
+ * member signs them cleared, and these encoders only ever produce the cleared
+ * form, which is the one a relay accepts. The relay fills them in afterwards.
+ *
+ * Sources in core, for the next person to check a discriminant:
+ * `crates/governance-types/src/lib.rs` (`GroupOp`, `RootOp`),
+ * `crates/primitives/src/context.rs` (`GroupMemberRole`), and the vectors in
+ * `crates/governance-types/src/tests.rs` (`delegated_governance_op_vectors_are_stable`).
+ */
+import { concat, fromHex, u32le } from '../crypto/internal.js';
+/**
+ * `GroupMemberRole` discriminants. The two TEE roles (3 and 4) are minted only
+ * by attestation admission and never by a member's op, so they are not offered.
+ */
+const ROLE = {
+    Admin: 0,
+    Member: 1,
+    ReadOnly: 2,
+};
+/** `GroupOp` discriminants, by position in core's enum. */
+const GROUP_OP = {
+    MemberAdded: 1,
+    MemberRemoved: 2,
+    MemberLeft: 3,
+    MemberRoleSet: 4,
+};
+/** `RootOp` discriminants, by position in core's enum. */
+const ROOT_OP = {
+    GroupCreated: 0,
+    GroupReparented: 1,
+    GroupDeleted: 2,
+};
+/** A post-state hash left for the relay to compute: 32 zero bytes. */
+const CLEARED_HASH = new Uint8Array(32);
+/** An empty borsh `Vec`: a zero `u32` count. */
+const EMPTY_VEC = u32le(0);
+function role(value) {
+    const byte = ROLE[value];
+    if (byte === undefined) {
+        throw new Error(`role must be Admin, Member or ReadOnly, got ${String(value)}`);
+    }
+    return new Uint8Array([byte]);
+}
+function tag(byte) {
+    return new Uint8Array([byte]);
+}
+/**
+ * Add `member` (an account, hex) to the group with `role`.
+ *
+ * Applied as the author: adding a `Member` needs `MANAGE_MEMBERS` or admin,
+ * adding an `Admin` needs admin.
+ */
+export function memberAddedOp(member, memberRole) {
+    return {
+        kind: 'group',
+        bytes: concat(tag(GROUP_OP.MemberAdded), fromHex(member, 'member', 32), role(memberRole)),
+    };
+}
+/**
+ * Remove `member` (an account, hex) from the group, in delegable form: both
+ * post-state claims cleared, for the relay to compute from its own view.
+ */
+export function memberRemovedOp(member) {
+    return {
+        kind: 'group',
+        bytes: concat(tag(GROUP_OP.MemberRemoved), fromHex(member, 'member', 32), CLEARED_HASH, EMPTY_VEC),
+    };
+}
+/**
+ * The author leaves the group, in delegable form. The node applies it only when
+ * `member` is the author's own account.
+ */
+export function memberLeftOp(member) {
+    return {
+        kind: 'group',
+        bytes: concat(tag(GROUP_OP.MemberLeft), fromHex(member, 'member', 32), CLEARED_HASH, EMPTY_VEC),
+    };
+}
+/** Set `member`'s role (an account, hex). */
+export function memberRoleSetOp(member, memberRole) {
+    return {
+        kind: 'group',
+        bytes: concat(tag(GROUP_OP.MemberRoleSet), fromHex(member, 'member', 32), role(memberRole)),
+    };
+}
+/**
+ * Create a subgroup under `parentId`, a root op published on the namespace.
+ *
+ * Needs `CAN_CREATE_SUBGROUP` or admin on the parent; the author, not the
+ * relay, becomes the new subgroup's admin.
+ */
+export function groupCreatedOp(input) {
+    return {
+        kind: 'root',
+        bytes: concat(tag(ROOT_OP.GroupCreated), fromHex(input.groupId, 'groupId', 32), fromHex(input.parentId, 'parentId', 32), tag(input.restricted ? 1 : 0), fromHex(input.admin, 'admin', 32)),
+    };
+}
+/** Move `childGroupId` under `newParentId`, a root op. */
+export function groupReparentedOp(childGroupId, newParentId) {
+    return {
+        kind: 'root',
+        bytes: concat(tag(ROOT_OP.GroupReparented), fromHex(childGroupId, 'childGroupId', 32), fromHex(newParentId, 'newParentId', 32)),
+    };
+}
+/**
+ * Delete `rootGroupId` and its subtree, in delegable form: both cascade lists
+ * empty, for the relay to enumerate.
+ */
+export function groupDeletedOp(rootGroupId) {
+    return {
+        kind: 'root',
+        bytes: concat(tag(ROOT_OP.GroupDeleted), fromHex(rootGroupId, 'rootGroupId', 32), EMPTY_VEC, EMPTY_VEC),
+    };
+}

package/dist/warrant/governance-warrant.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Mint a governance warrant: the author's consent for one relay to publish one
+ * governance op in the author's name, once.
+ *
+ * The intent warrant lets an account with no node write to a context and the
+ * creation warrant lets it create one. This covers the governance around them:
+ * adding the other person to a DM, creating a channel's subgroup, changing a
+ * role. The relay wraps the op in `OnBehalf` and publishes it; every peer applies
+ * the inner op **as the author**, so the author's own authority decides
+ * (`MANAGE_MEMBERS` to add a member, `CAN_CREATE_SUBGROUP` to create a subgroup,
+ * and so on) and the relay needs only standing to act for members.
+ *
+ * **It commits to the op's bytes.** The warrant carries
+ * `H(kind || op bytes)` over the op's delegable form (see `governance-op.ts`), so
+ * what the op does, to whom and where is signed byte for byte and the relay
+ * chooses nothing about it. `kind` is inside the commitment, so a group op can
+ * never be presented as a root op whose bytes happen to coincide.
+ *
+ * **`scope` is where the op is published**: the group itself for a group op,
+ * the namespace for a root op.
+ *
+ * Same primitives and the same two-widths trap as `warrant.ts`: counts inside
+ * the encoding are borsh `u32`, counts in the signing preimage are `u64`.
+ *
+ * **The byte contract is pinned in core**, at
+ * `crates/account/src/tests/governance_wire_fixture.rs`, and this module's test
+ * asserts the same vectors. A drift would surface at a relay as a 400.
+ */
+import type { GovernanceOp, GovernanceOpKind } from './governance-op.js';
+/** What a governance warrant authorises. */
+export interface GovernanceWarrantInput {
+    /**
+     * Where the op is published, hex (32 bytes): the group for a group op, the
+     * namespace for a root op. The relay refuses a warrant presented anywhere else.
+     */
+    scope: string;
+    /** The op, from one of the encoders in `governance-op.ts`. Its kind is signed over. */
+    op: GovernanceOp;
+    /** The author's account, hex: whose authority the op is applied under. */
+    authorAccount: string;
+    /** The relay authorised to publish it, hex. An account, not a key. */
+    executor: string;
+    /**
+     * Monotonic per author **device**, spent in a per-group ledger. The same
+     * nonce source `RelayClient` uses for every other warrant is correct.
+     */
+    nonce: number | bigint;
+    /** Unix seconds after which the relay must refuse it. */
+    notAfter: number | bigint;
+    /** Account-log heads the author saw, each hex (32 bytes). At most 64. */
+    accountHeads?: string[];
+    /** Governance heads the author's view descended from, each hex (32 bytes). At most 64. */
+    governanceFloor?: string[];
+    /** The author device's ed25519 signing secret, hex (32 bytes). Never sent. */
+    deviceSecret: string;
+}
+/** A governance warrant's fields, decoded from the wire encoding. */
+export interface GovernanceWarrantFields {
+    scope: string;
+    kind: GovernanceOpKind;
+    authorAccount: string;
+    /** The author device key `signGovernanceWarrant` derived from the secret. */
+    deviceKey: string;
+    executor: string;
+    opHash: string;
+    accountHeads: string[];
+    governanceFloor: string[];
+    nonce: bigint;
+    notAfter: bigint;
+    signature: string;
+}
+/**
+ * The commitment a governance warrant carries in place of the op:
+ * `H(kind || op bytes)` under its own domain.
+ */
+export declare function governanceOpHash(op: GovernanceOp): Promise<Uint8Array>;
+/** The already-decoded fields the signature covers. Internal. */
+export interface GovernancePreimageParts {
+    scope: Uint8Array;
+    kind: GovernanceOpKind;
+    authorAccount: Uint8Array;
+    deviceKey: Uint8Array;
+    executor: Uint8Array;
+    opHash: Uint8Array;
+    accountHeads: Uint8Array[];
+    governanceFloor: Uint8Array[];
+    nonce: number | bigint;
+    notAfter: number | bigint;
+}
+/**
+ * The bytes the device key signs. Exported for the conformance test only, not
+ * from the package root.
+ */
+export declare function governanceWarrantPreimage(p: GovernancePreimageParts): Promise<Uint8Array>;
+/**
+ * Sign a governance warrant and return it hex-encoded (borsh
+ * `GovernanceWarrant`), ready for the relay alongside the op's own bytes.
+ */
+export declare function signGovernanceWarrant(input: GovernanceWarrantInput): Promise<string>;
+/**
+ * Decode a hex governance warrant back into its fields.
+ *
+ * Refuses truncated or trailing bytes and an unknown kind. Does not verify the
+ * signature.
+ */
+export declare function parseGovernanceWarrant(warrant: string): GovernanceWarrantFields;

package/dist/warrant/governance-warrant.js

@@ -0,0 +1,159 @@
+/**
+ * Mint a governance warrant: the author's consent for one relay to publish one
+ * governance op in the author's name, once.
+ *
+ * The intent warrant lets an account with no node write to a context and the
+ * creation warrant lets it create one. This covers the governance around them:
+ * adding the other person to a DM, creating a channel's subgroup, changing a
+ * role. The relay wraps the op in `OnBehalf` and publishes it; every peer applies
+ * the inner op **as the author**, so the author's own authority decides
+ * (`MANAGE_MEMBERS` to add a member, `CAN_CREATE_SUBGROUP` to create a subgroup,
+ * and so on) and the relay needs only standing to act for members.
+ *
+ * **It commits to the op's bytes.** The warrant carries
+ * `H(kind || op bytes)` over the op's delegable form (see `governance-op.ts`), so
+ * what the op does, to whom and where is signed byte for byte and the relay
+ * chooses nothing about it. `kind` is inside the commitment, so a group op can
+ * never be presented as a root op whose bytes happen to coincide.
+ *
+ * **`scope` is where the op is published**: the group itself for a group op,
+ * the namespace for a root op.
+ *
+ * Same primitives and the same two-widths trap as `warrant.ts`: counts inside
+ * the encoding are borsh `u32`, counts in the signing preimage are `u64`.
+ *
+ * **The byte contract is pinned in core**, at
+ * `crates/account/src/tests/governance_wire_fixture.rs`, and this module's test
+ * asserts the same vectors. A drift would surface at a relay as a 400.
+ */
+import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+import { citedHeads } from './warrant.js';
+const SIGN_DOMAIN = new TextEncoder().encode('calimero.governance-warrant.v1');
+const OP_DOMAIN = new TextEncoder().encode('calimero.governance-warrant.op.v1');
+/** core's `GovernanceOpKind` discriminants. */
+const KIND_BYTE = { group: 0, root: 1 };
+/**
+ * The commitment a governance warrant carries in place of the op:
+ * `H(kind || op bytes)` under its own domain.
+ */
+export async function governanceOpHash(op) {
+    return domainHash(OP_DOMAIN, [new Uint8Array([kindByte(op.kind)]), op.bytes]);
+}
+/**
+ * The bytes the device key signs. Exported for the conformance test only, not
+ * from the package root.
+ */
+export async function governanceWarrantPreimage(p) {
+    // u64 counts HERE; u32 on the wire. The counts keep the two adjacent head
+    // lists from being relabelled into each other.
+    return domainHash(SIGN_DOMAIN, [
+        p.scope,
+        new Uint8Array([kindByte(p.kind)]),
+        p.authorAccount,
+        p.deviceKey,
+        p.executor,
+        p.opHash,
+        u64le(p.accountHeads.length),
+        ...p.accountHeads,
+        u64le(p.governanceFloor.length),
+        ...p.governanceFloor,
+        u64le(p.nonce),
+        u64le(p.notAfter),
+    ]);
+}
+/**
+ * Sign a governance warrant and return it hex-encoded (borsh
+ * `GovernanceWarrant`), ready for the relay alongside the op's own bytes.
+ */
+export async function signGovernanceWarrant(input) {
+    const scope = fromHex(input.scope, 'scope', 32);
+    const authorAccount = fromHex(input.authorAccount, 'authorAccount', 32);
+    const executor = fromHex(input.executor, 'executor', 32);
+    const accountHeads = citedHeads(input.accountHeads, 'accountHeads');
+    const governanceFloor = citedHeads(input.governanceFloor, 'governanceFloor');
+    const kind = kindByte(input.op.kind);
+    const key = await importSigningKey(input.deviceSecret);
+    const deviceKey = await derivePublicKey(input.deviceSecret);
+    const opHash = await governanceOpHash(input.op);
+    const preimage = await governanceWarrantPreimage({
+        scope,
+        kind: input.op.kind,
+        authorAccount,
+        deviceKey,
+        executor,
+        opHash,
+        accountHeads,
+        governanceFloor,
+        nonce: input.nonce,
+        notAfter: input.notAfter,
+    });
+    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    return hex(concat(scope, new Uint8Array([kind]), authorAccount, deviceKey, executor, opHash, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, u64le(input.nonce), u64le(input.notAfter), signature));
+}
+/**
+ * Decode a hex governance warrant back into its fields.
+ *
+ * Refuses truncated or trailing bytes and an unknown kind. Does not verify the
+ * signature.
+ */
+export function parseGovernanceWarrant(warrant) {
+    const clean = warrant.trim();
+    if (!/^[0-9a-fA-F]*$/.test(clean) || clean.length % 2 !== 0) {
+        throw new Error('governance warrant must be an even number of hex characters');
+    }
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i += 1) {
+        bytes[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    const view = new DataView(bytes.buffer);
+    let o = 0;
+    const take = (n, what) => {
+        if (o + n > bytes.length) {
+            throw new Error(`governance warrant ends inside ${what} (${bytes.length} bytes)`);
+        }
+        const out = bytes.subarray(o, o + n);
+        o += n;
+        return out;
+    };
+    const u32 = (what) => view.getUint32(take(4, what).byteOffset, true);
+    const u64 = (what) => view.getBigUint64(take(8, what).byteOffset, true);
+    const heads = (what) => {
+        const count = u32(what);
+        if (count > 64) {
+            throw new Error(`${what} cites ${count} heads, over the 64 a node accepts`);
+        }
+        return Array.from({ length: count }, () => hex(take(32, what)));
+    };
+    const kind = () => {
+        const byte = take(1, 'kind')[0];
+        if (byte === 0)
+            return 'group';
+        if (byte === 1)
+            return 'root';
+        throw new Error(`governance warrant has kind ${byte}, expected 0 (group) or 1 (root)`);
+    };
+    const fields = {
+        scope: hex(take(32, 'scope')),
+        kind: kind(),
+        authorAccount: hex(take(32, 'authorAccount')),
+        deviceKey: hex(take(32, 'deviceKey')),
+        executor: hex(take(32, 'executor')),
+        opHash: hex(take(32, 'opHash')),
+        accountHeads: heads('accountHeads'),
+        governanceFloor: heads('governanceFloor'),
+        nonce: u64('nonce'),
+        notAfter: u64('notAfter'),
+        signature: hex(take(64, 'signature')),
+    };
+    if (o !== bytes.length) {
+        throw new Error(`governance warrant is ${bytes.length} bytes but its fields account for ${o}`);
+    }
+    return fields;
+}
+function kindByte(kind) {
+    const byte = KIND_BYTE[kind];
+    if (byte === undefined) {
+        throw new Error(`op kind must be 'group' or 'root', got ${String(kind)}`);
+    }
+    return byte;
+}

package/dist/warrant/index.d.ts

@@ -1,2 +1,8 @@
 export { signWarrant, intentHash } from './warrant.js';
 export type { WarrantInput } from './warrant.js';
+export { signCreationWarrant, parseCreationWarrant, creationInitHash, } from './creation-warrant.js';
+export type { CreationWarrantInput, CreationWarrantFields, SignedCreationWarrant, } from './creation-warrant.js';
+export { signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, } from './governance-warrant.js';
+export type { GovernanceWarrantInput, GovernanceWarrantFields, } from './governance-warrant.js';
+export { memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, } from './governance-op.js';
+export type { GovernanceOp, GovernanceOpKind, GovernanceMemberRole, GroupCreatedInput, } from './governance-op.js';

package/dist/warrant/index.js

@@ -1,2 +1,5 @@
 // Warrant signing — the author's half of delegated authorship
 export { signWarrant, intentHash } from './warrant.js';
+export { signCreationWarrant, parseCreationWarrant, creationInitHash, } from './creation-warrant.js';
+export { signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, } from './governance-warrant.js';
+export { memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, } from './governance-op.js';