@calimero-network/mero-js 22.2.0 → 22.4.0

package/dist/relay/index.d.ts

@@ -1,4 +1,4 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
-export type { RelayClientConfig, RelayDescription, IntentResult } from './relay-client.js';
+export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, } from './relay-client.js';
 export { createMemoryNonceSource, createLocalStorageNonceSource } from './nonce-source.js';
 export type { NonceSource } from './nonce-source.js';

package/dist/relay/relay-client.d.ts

@@ -84,6 +84,51 @@ export interface RelayDescription {
     /** The group whose admin grants that capability, hex. */
     groupId: string;
 }
+/** What a relay says about its ability to create contexts in one group. */
+export interface CreationDescription {
+    /** The account a creation warrant must name as `executor`, hex. */
+    executorAccount: string;
+    /** The group, hex. */
+    groupId: string;
+    /**
+     * Whether the relay has standing to act for members of this group (a
+     * `RelayTee` role or `CAN_AUTHOR_ON_BEHALF`). It needs no create rights of
+     * its own — those are checked on the author.
+     */
+    canCreateOnBehalf: boolean;
+    /**
+     * Whether the author holds `CAN_CREATE_CONTEXT` (or admin) here. Present only
+     * when `describeCreation` was given an `author`.
+     */
+    authorMayCreate?: boolean;
+}
+/** What {@link RelayClient.createContext} creates. */
+export interface CreateContextInput {
+    /** The group to create the context in, hex. */
+    groupId: string;
+    /** The application to create it with, hex (32 bytes). */
+    applicationId: string;
+    /** The JSON the app's `init()` receives — run as the author's account. */
+    initArgs?: unknown;
+    /** Which service of a multi-service bundle; absent for the default. */
+    serviceName?: string;
+    /** A display name for the context. */
+    name?: string;
+    /**
+     * The seed the context id is derived from, hex (32 bytes). Random when
+     * absent, which is what almost every caller wants.
+     */
+    seed?: string;
+}
+/** Where a delegated creation landed. */
+export interface CreatedContext {
+    /** The new context's id, hex. */
+    contextId: string;
+    /** The group it was created in, hex. */
+    groupId: string;
+    /** The relay's identity in the new context, hex. */
+    memberPublicKey: string;
+}
 /** Where an accepted intent landed. */
 export interface IntentResult<T = unknown> {
     /** The context's scope root after the run — did this change anything? */
@@ -140,5 +185,36 @@ export declare class RelayClient {
      * apply. Nothing accumulates and nothing is reusable.
      */
     execute<T = unknown>(contextId: string, method: string, argsJson?: unknown): Promise<IntentResult<T>>;
+    /**
+     * Ask the relay what it can do about creating contexts in `groupId`.
+     *
+     * Pass `author` (an account, hex) to also learn whether that account may
+     * create here — `authorMayCreate` is present only then.
+     */
+    describeCreation(groupId: string, opts?: {
+        author?: string;
+    }): Promise<CreationDescription>;
+    /**
+     * Create a context in a group through the relay, as the author.
+     *
+     * Always asks {@link describeCreation} first — with the author, so both
+     * standing checks happen before anything is signed. A relay without standing
+     * in the group, or an author without `CAN_CREATE_CONTEXT`, is refused here as
+     * an {@link IntentRefusedError} *before* a nonce is taken: the nonce source
+     * is monotonic, and a warrant nobody will spend burns one for nothing.
+     *
+     * The creation warrant's nonce is spent in the new context's per-device
+     * ledger — the same one later `execute` calls in that context draw from — so
+     * it comes from the configured {@link NonceSource} like any other warrant.
+     *
+     * Sealing: nothing here is plaintext-specific. The request goes through the
+     * injected `fetch`, so a `createAttestedSealedFetch` seals it exactly as it
+     * seals `execute`. Whether the relay *accepts* it sealed is the node's call:
+     * a proxy-auth relay only admits sealed requests for routes `merod` serves
+     * without a credential, so `/admin-api/groups/:id/context-intents` must be on
+     * that list on the core side or the request comes back
+     * `403 sealed_route_unguarded`.
+     */
+    createContext(input: CreateContextInput): Promise<CreatedContext>;
     private json;
 }

package/dist/relay/relay-client.js

@@ -28,6 +28,7 @@
  * unspendable: the number is gone and the write never happened.
  */
 import { signWarrant } from '../warrant/warrant.js';
+import { signCreationWarrant } from '../warrant/creation-warrant.js';
 import { HTTPError } from '../http-client/web-client.js';
 /** How long a freshly minted warrant stays presentable, in seconds. */
 const DEFAULT_TTL_SECONDS = 300;
@@ -106,6 +107,82 @@ export class RelayClient {
         const body = await this.json('POST', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`, { method, argsJson, warrant, authorProof: this.config.authorProof });
         return { rootHash: body.data.rootHash, returns: body.data.returns ?? null };
     }
+    /**
+     * Ask the relay what it can do about creating contexts in `groupId`.
+     *
+     * Pass `author` (an account, hex) to also learn whether that account may
+     * create here — `authorMayCreate` is present only then.
+     */
+    async describeCreation(groupId, opts = {}) {
+        const query = opts.author ? `?author=${encodeURIComponent(opts.author)}` : '';
+        const body = await this.json('GET', `/admin-api/groups/${encodeURIComponent(groupId)}/context-intents${query}`);
+        return body.data;
+    }
+    /**
+     * Create a context in a group through the relay, as the author.
+     *
+     * Always asks {@link describeCreation} first — with the author, so both
+     * standing checks happen before anything is signed. A relay without standing
+     * in the group, or an author without `CAN_CREATE_CONTEXT`, is refused here as
+     * an {@link IntentRefusedError} *before* a nonce is taken: the nonce source
+     * is monotonic, and a warrant nobody will spend burns one for nothing.
+     *
+     * The creation warrant's nonce is spent in the new context's per-device
+     * ledger — the same one later `execute` calls in that context draw from — so
+     * it comes from the configured {@link NonceSource} like any other warrant.
+     *
+     * Sealing: nothing here is plaintext-specific. The request goes through the
+     * injected `fetch`, so a `createAttestedSealedFetch` seals it exactly as it
+     * seals `execute`. Whether the relay *accepts* it sealed is the node's call:
+     * a proxy-auth relay only admits sealed requests for routes `merod` serves
+     * without a credential, so `/admin-api/groups/:id/context-intents` must be on
+     * that list on the core side or the request comes back
+     * `403 sealed_route_unguarded`.
+     */
+    async createContext(input) {
+        const described = await this.describeCreation(input.groupId, {
+            author: this.config.authorAccount,
+        });
+        if (!described.canCreateOnBehalf) {
+            throw new IntentRefusedError(`the relay (${described.executorAccount}) has no standing to act for members of group ` +
+                `${described.groupId}; an admin must admit it as a relay or grant it CAN_AUTHOR_ON_BEHALF ` +
+                '(checked before signing — no nonce was spent)', false, 403);
+        }
+        if (described.authorMayCreate === false) {
+            throw new IntentRefusedError(`the author (${this.config.authorAccount}) may not create contexts in group ` +
+                `${described.groupId}; it needs CAN_CREATE_CONTEXT or admin ` +
+                '(checked before signing — no nonce was spent)', false, 403);
+        }
+        const configured = this.config.executorAccount;
+        if (configured && configured.toLowerCase() !== described.executorAccount.toLowerCase()) {
+            throw new Error(`configured executorAccount ${configured} is not the relay's account ` +
+                `${described.executorAccount}; a warrant naming it would be unspendable`);
+        }
+        const executor = described.executorAccount;
+        this.executorAccount = executor;
+        const initArgs = input.initArgs ?? {};
+        const nonce = await this.config.nonces.next();
+        const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        const { warrant } = await signCreationWarrant({
+            group: input.groupId,
+            seed: input.seed,
+            authorAccount: this.config.authorAccount,
+            executor,
+            applicationId: input.applicationId,
+            serviceName: input.serviceName,
+            name: input.name,
+            initArgs,
+            nonce,
+            notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
+            deviceSecret: this.config.deviceSecret,
+        });
+        const body = await this.json('POST', `/admin-api/groups/${encodeURIComponent(input.groupId)}/context-intents`, { warrant, authorProof: this.config.authorProof, initArgs });
+        return {
+            contextId: body.data.contextId,
+            groupId: body.data.groupId,
+            memberPublicKey: body.data.memberPublicKey,
+        };
+    }
     async json(method, path, body) {
         const headers = { Accept: 'application/json' };
         if (body !== undefined)

package/dist/sealed/release.d.ts

@@ -97,6 +97,10 @@ export declare function nodeReleaseVersionFromImage(osImage: string): string;
  * `GET /admin-api/tee/info` reports. The node's own claim, and not trusted:
  * it only picks which signed release to fetch, and the quote must then match
  * that release's measurements.
+ *
+ * `/tee/info` is read in the clear, before any session exists. A node that
+ * requires sealing serves it unsealed from core#4196 on; an older one refuses
+ * it with `403 sealed_required`, and then this throws saying so.
  */
 export declare function fetchNodeReleaseVersion(baseUrl: string, options?: {
     fetch?: typeof fetch;
@@ -172,15 +176,22 @@ export interface SignedReleaseSealedFetchOptions extends Omit<SignedReleaseVerif
      * URL of a mirror serving {@link cloudNodeReleaseUrl}'s path, defaulting to
      * {@link DEFAULT_RELEASE_MIRROR}; a function gets the version and returns
      * the release, e.g. from a file bundled with the app. Whichever it is, it is
-     * not trusted: the release is verified. `/tee/info` is read in the clear,
-     * which a node with `[server.sealed] required` refuses: for one, pass a
-     * function that ignores `version` and returns the release you expect.
+     * not trusted: the release is verified. `/tee/info` is read in the clear;
+     * for a node that refuses that, see `releaseVersion`.
      */
     releaseSource?: string | ((context: {
         baseUrl: string;
         version: string;
         fetch: typeof fetch;
     }) => Promise<SignedNodeRelease>);
+    /**
+     * The release to fetch when the node will not name one: a node that
+     * requires sealing (`[server.sealed] required`) and predates core#4196
+     * refuses `/tee/info` unsealed. Used only then; a node that answers is
+     * taken at its word. Either way untrusted: the quote must match the signed
+     * release, so a wrong version only fails the attestation.
+     */
+    releaseVersion?: string;
     /** Also require the node to run this application with this bytecode hash. */
     applicationId?: string;
     applicationHash?: string;
@@ -190,7 +201,8 @@ export interface SignedReleaseSealedFetchOptions extends Omit<SignedReleaseVerif
 /**
  * {@link createAttestedSealedFetch} for a TEE node known only by URL, trusting
  * whatever signed release at or above `minReleaseVersion` it runs: it reads
- * the release the node names from its `/tee/info`, gets that release from
+ * the release the node names from its `/tee/info` (or takes `releaseVersion`
+ * when a node too old to serve that unsealed requires sealing), gets that release from
  * `releaseSource` (the public mirror unless you say otherwise), verifies its
  * signature, builds the quote verifier from its measurements, attests the node
  * and seals everything to it.

package/dist/sealed/release.js

@@ -127,10 +127,35 @@ export function nodeReleaseVersionFromImage(osImage) {
  * `GET /admin-api/tee/info` reports. The node's own claim, and not trusted:
  * it only picks which signed release to fetch, and the quote must then match
  * that release's measurements.
+ *
+ * `/tee/info` is read in the clear, before any session exists. A node that
+ * requires sealing serves it unsealed from core#4196 on; an older one refuses
+ * it with `403 sealed_required`, and then this throws saying so.
  */
 export async function fetchNodeReleaseVersion(baseUrl, options = {}) {
-    const url = `${baseUrl.replace(/\/+$/, '')}/admin-api/tee/info`;
-    const response = await (options.fetch ?? fetch)(url, { headers: { accept: 'application/json' } });
+    const version = await readNodeReleaseVersion(baseUrl, options.fetch ?? fetch);
+    if (version === undefined) {
+        throw new Error(`${infoUrl(baseUrl)} was refused unsealed: the node requires sealing and is too old to name its ` +
+            "release before a session exists. Name the release it runs yourself (createSignedReleaseSealedFetch's " +
+            '`releaseVersion`), or upgrade the node');
+    }
+    return version;
+}
+function infoUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, '')}/admin-api/tee/info`;
+}
+/** As {@link fetchNodeReleaseVersion}, but `undefined` when the node refuses `/tee/info` as `sealed_required`. */
+async function readNodeReleaseVersion(baseUrl, givenFetch) {
+    const url = infoUrl(baseUrl);
+    const response = await givenFetch(url, { headers: { accept: 'application/json' } });
+    if (response.status === 403) {
+        const code = await response
+            .json()
+            .then((body) => body?.error?.code)
+            .catch(() => undefined);
+        if (code === 'sealed_required')
+            return undefined;
+    }
     if (!response.ok)
         throw new Error(`Fetching ${url} failed: HTTP ${response.status}`);
     let osImage;
@@ -211,7 +236,8 @@ export function createSignedReleaseVerifier(options) {
 /**
  * {@link createAttestedSealedFetch} for a TEE node known only by URL, trusting
  * whatever signed release at or above `minReleaseVersion` it runs: it reads
- * the release the node names from its `/tee/info`, gets that release from
+ * the release the node names from its `/tee/info` (or takes `releaseVersion`
+ * when a node too old to serve that unsealed requires sealing), gets that release from
  * `releaseSource` (the public mirror unless you say otherwise), verifies its
  * signature, builds the quote verifier from its measurements, attests the node
  * and seals everything to it.
@@ -232,10 +258,14 @@ export function createSignedReleaseVerifier(options) {
  * ```
  */
 export function createSignedReleaseSealedFetch(options) {
-    const { baseUrl, releaseSource, applicationId, applicationHash, fetch: givenFetch, ...verifierOptions } = options;
+    const { baseUrl, releaseSource, releaseVersion: fallbackVersion, applicationId, applicationHash, fetch: givenFetch, ...verifierOptions } = options;
+    if (fallbackVersion !== undefined)
+        releaseVersion(fallbackVersion, 'releaseVersion');
     const baseFetch = givenFetch ?? ((input, init) => fetch(input, init));
     const release = async () => {
-        const version = await fetchNodeReleaseVersion(baseUrl, { fetch: baseFetch });
+        const version = fallbackVersion === undefined
+            ? await fetchNodeReleaseVersion(baseUrl, { fetch: baseFetch })
+            : ((await readNodeReleaseVersion(baseUrl, baseFetch)) ?? fallbackVersion);
         return typeof releaseSource === 'function'
             ? releaseSource({ baseUrl, version, fetch: baseFetch })
             : fetchNodeRelease(cloudNodeReleaseUrl(releaseSource ?? DEFAULT_RELEASE_MIRROR, version), { fetch: baseFetch });

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

@@ -0,0 +1,145 @@
+/**
+ * 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.
+ */
+/** What a creation warrant authorises. */
+export interface CreationWarrantInput {
+    /** The group the context is created in, hex (32 bytes). */
+    group: string;
+    /**
+     * The seed the node derives the new context's id from, hex (32 bytes).
+     *
+     * Optional: when absent, 32 random bytes are drawn and returned alongside the
+     * warrant. Pass one only to make the id predictable — reusing a seed asks for
+     * a context that already exists.
+     */
+    seed?: string;
+    /** The author's account, hex — whose consent this is, and who runs `init`. */
+    authorAccount: string;
+    /** The relay authorised to act, hex. An account, not a key. */
+    executor: string;
+    /** The application the context is created with, hex (32 bytes). */
+    applicationId: string;
+    /**
+     * Which service of a multi-service bundle, or absent for the default.
+     *
+     * Absent and `""` are different values and sign differently. At most 256
+     * UTF-8 bytes.
+     */
+    serviceName?: string;
+    /** A display name for the context, or absent. At most 256 UTF-8 bytes. */
+    name?: string;
+    /**
+     * The JSON the app's `init()` will receive.
+     *
+     * Committed to rather than carried: the relay is sent the same value
+     * separately and the node checks it hashes to what was signed, so pass the
+     * exact value you will send. See {@link creationInitHash}.
+     */
+    initArgs: unknown;
+    /**
+     * Monotonic per author **device**. Spent in the *new* context's warrant
+     * ledger, so the same per-device nonce source `RelayClient` uses 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. The same caveat as the intent warrant's floor applies: one the
+     * relay supplied is one the relay chose.
+     */
+    governanceFloor?: string[];
+    /** The author device's ed25519 signing secret, hex (32 bytes). Never sent. */
+    deviceSecret: string;
+}
+/** A signed creation warrant and the seed it commits to. */
+export interface SignedCreationWarrant {
+    /** Hex borsh `ContextCreationWarrant`, ready for the relay. */
+    warrant: string;
+    /** The seed, hex — the one passed in, or the one drawn when none was. */
+    seed: string;
+}
+/** A creation warrant's fields, decoded from the wire encoding. */
+export interface CreationWarrantFields {
+    group: string;
+    seed: string;
+    authorAccount: string;
+    /** The author device key `signCreationWarrant` derived from the secret. */
+    deviceKey: string;
+    executor: string;
+    applicationId: string;
+    /** `null` when absent — distinct from `""`. */
+    serviceName: string | null;
+    /** `null` when absent — distinct from `""`. */
+    name: string | null;
+    initHash: string;
+    accountHeads: string[];
+    governanceFloor: string[];
+    nonce: bigint;
+    notAfter: bigint;
+    signature: string;
+}
+/**
+ * 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 declare function creationInitHash(initArgs: unknown): Promise<Uint8Array>;
+/** The already-decoded fields the signature covers. Internal. */
+export interface CreationPreimageParts {
+    group: Uint8Array;
+    seed: Uint8Array;
+    authorAccount: Uint8Array;
+    deviceKey: Uint8Array;
+    executor: Uint8Array;
+    applicationId: Uint8Array;
+    serviceName: Uint8Array | null;
+    name: Uint8Array | null;
+    initHash: 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 creationWarrantPreimage(p: CreationPreimageParts): Promise<Uint8Array>;
+/**
+ * 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 declare function signCreationWarrant(input: CreationWarrantInput): Promise<SignedCreationWarrant>;
+/**
+ * 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 declare function parseCreationWarrant(warrant: string): CreationWarrantFields;

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/index.d.ts

@@ -1,2 +1,4 @@
 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';

package/dist/warrant/index.js

@@ -1,2 +1,3 @@
 // Warrant signing — the author's half of delegated authorship
 export { signWarrant, intentHash } from './warrant.js';
+export { signCreationWarrant, parseCreationWarrant, creationInitHash, } from './creation-warrant.js';

package/dist/warrant/warrant.d.ts

@@ -121,6 +121,11 @@ export declare function intentHash(method: string, argsJson: unknown): Promise<U
  * second spelling able to disagree with what was signed.
  */
 export declare function signWarrant(input: WarrantInput): Promise<string>;
+/**
+ * Decode a cited-head list, refusing one longer than a node will accept.
+ * Shared with `creation-warrant.ts`; internal, not exported from the package root.
+ */
+export declare function citedHeads(heads: string[] | undefined, label: string): Uint8Array[];
 /** A warrant's fields, as hex, decoded from the wire encoding. */
 export interface WarrantFields {
     context: string;