@calimero-network/mero-js 22.5.0 → 22.6.0

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

@@ -24,8 +24,12 @@ import type { SignedGroupOpenInvitation } from '../admin-api/admin-types.js';
  * governance through a relay. None of these changes a layout this module
  * signs; the version moves with core's so nodes on different versions never
  * share a namespace.
+ *
+ * 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.
  */
-export declare const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 15;
+export declare const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 16;
 /**
  * Borsh-encode a `SignedGroupOpenInvitation`.
  *

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

@@ -9,8 +9,12 @@ import { concat, derivePublicKey, fromHex, hex, importSigningKey, u32le, u64le,
  * governance through a relay. None of these changes a layout this module
  * signs; the version moves with core's so nodes on different versions never
  * share a namespace.
+ *
+ * 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.
  */
-export const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 15;
+export const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 16;
 /** 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. */

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

@@ -28,6 +28,7 @@
  * unspendable: the number is gone and the write never happened.
  */
 import type { GovernanceOp } from '../warrant/governance-op.js';
+import { type Signer } from '../signer/signer.js';
 import type { NonceSource } from './nonce-source.js';
 /** Where and as whom to write, plus the key that consents. */
 export interface RelayClientConfig {
@@ -60,8 +61,18 @@ export interface RelayClientConfig {
      *
      * Never transmitted. It signs in this process and only the signature leaves,
      * which is the whole reason a keyholder can author without a node.
+     *
+     * Mutually exclusive with {@link RelayClientConfig.signer}: exactly one is
+     * required. A browser should prefer the signer: a secret held as a string is
+     * readable by anything on the origin, and a non-extractable key is not.
+     */
+    deviceSecret?: string;
+    /**
+     * The author device's signer: use instead of
+     * {@link RelayClientConfig.deviceSecret} when the key cannot be exported
+     * (a non-extractable WebCrypto key, a passkey, a hardware or remote signer).
      */
-    deviceSecret: string;
+    signer?: Signer;
     /** Where nonces come from. See {@link NonceSource} — a reset replays. */
     nonces: NonceSource;
     /**
@@ -198,6 +209,12 @@ export declare class RelayClient {
     private readonly fetchImpl;
     private readonly timeoutMs;
     constructor(config: RelayClientConfig);
+    /**
+     * The author device's signer, built from `deviceSecret` when that is what was
+     * configured. A {@link Signer} and never the secret, so no caller of a
+     * `RelayClient` gains the ability to read key material.
+     */
+    authorSigner(): Promise<Signer>;
     /**
      * Ask the relay what it can do in `contextId`.
      *

package/dist/relay/relay-client.js

@@ -32,6 +32,7 @@ import { signCreationWarrant } from '../warrant/creation-warrant.js';
 import { signGovernanceWarrant } from '../warrant/governance-warrant.js';
 import { HTTPError } from '../http-client/web-client.js';
 import { hex } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
 /** How long a freshly minted warrant stays presentable, in seconds. */
 const DEFAULT_TTL_SECONDS = 300;
 /**
@@ -71,6 +72,14 @@ export class RelayClient {
             : (input, init) => globalThis.fetch(input, init);
         this.timeoutMs = config.timeoutMs ?? 10000;
     }
+    /**
+     * The author device's signer, built from `deviceSecret` when that is what was
+     * configured. A {@link Signer} and never the secret, so no caller of a
+     * `RelayClient` gains the ability to read key material.
+     */
+    async authorSigner() {
+        return resolveSigner(this.config.deviceSecret, this.config.signer, 'deviceSecret');
+    }
     /**
      * Ask the relay what it can do in `contextId`.
      *
@@ -94,6 +103,8 @@ export class RelayClient {
      */
     async execute(contextId, method, argsJson = {}) {
         const executor = this.executorAccount ?? (await this.describe(contextId)).executorAccount;
+        // Resolved before the nonce, so a misconfigured key burns none.
+        const signer = await this.authorSigner();
         const nonce = await this.config.nonces.next();
         const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
         const warrant = await signWarrant({
@@ -104,7 +115,7 @@ export class RelayClient {
             argsJson,
             nonce,
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
-            deviceSecret: this.config.deviceSecret,
+            signer,
         });
         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 };
@@ -157,6 +168,8 @@ export class RelayClient {
         }
         const executor = this.checkedExecutor(described.executorAccount);
         const initArgs = input.initArgs ?? {};
+        // Resolved before the nonce, so a misconfigured key burns none.
+        const signer = await this.authorSigner();
         const nonce = await this.config.nonces.next();
         const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
         const { warrant } = await signCreationWarrant({
@@ -170,7 +183,7 @@ export class RelayClient {
             initArgs,
             nonce,
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
-            deviceSecret: this.config.deviceSecret,
+            signer,
         });
         const body = await this.json('POST', `/admin-api/groups/${encodeURIComponent(input.groupId)}/context-intents`, { warrant, authorProof: this.config.authorProof, initArgs });
         return {
@@ -211,6 +224,8 @@ export class RelayClient {
                 '(checked before signing, no nonce was spent)', false, 403);
         }
         const executor = this.checkedExecutor(described.executorAccount);
+        // Resolved before the nonce, so a misconfigured key burns none.
+        const signer = await this.authorSigner();
         const nonce = await this.config.nonces.next();
         const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
         const warrant = await signGovernanceWarrant({
@@ -220,7 +235,7 @@ export class RelayClient {
             executor,
             nonce,
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
-            deviceSecret: this.config.deviceSecret,
+            signer,
         });
         const body = await this.json('POST', `/admin-api/groups/${encodeURIComponent(input.groupId)}/governance-intents`, { warrant, authorProof: this.config.authorProof, op: hex(input.op.bytes) });
         return { groupId: body.data.groupId };

package/dist/signer/index.d.ts

@@ -0,0 +1,2 @@
+export { signerFromSecret, signerFromCryptoKey } from './signer.js';
+export type { Signer } from './signer.js';

package/dist/signer/index.js

@@ -0,0 +1,3 @@
+// Who signs — a key's capability, separated from its material, so a
+// non-extractable `CryptoKey` can be used wherever a hex secret could.
+export { signerFromSecret, signerFromCryptoKey } from './signer.js';

package/dist/signer/signer.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Who signs, separated from what is signed.
+ *
+ * Every signing entry point in this package used to take 32 hex bytes. That is
+ * fine for a CLI or a server holding a key file, and it is the one thing a
+ * browser must not do: a secret that exists as a string can be read by anything
+ * running on the origin, and a stolen account key is the account — permanently,
+ * because unlike a device key there is nothing above it to revoke it with.
+ *
+ * WebCrypto can hold an Ed25519 key that **signs but cannot be exported**
+ * (`generateKey(..., extractable: false, ...)`). Such a key has no hex
+ * representation to pass, so it could not be used with this package at all —
+ * which pushed consumers into reimplementing core's wire formats around their
+ * own key. That is the failure `crates/account/src/tests/sdk_credential_fixture.rs`
+ * exists to document: a second implementation of a byte contract agreed with
+ * itself for a full release while core rejected every credential it produced.
+ *
+ * So the interface is the key's *capability*, not its material:
+ *
+ * ```ts
+ * const signer = await signerFromSecret(deviceSecret);           // as before
+ * const signer = await signerFromCryptoKey(privateKey, pubKey);  // unexportable
+ * await signWarrant({ ...terms, signer });
+ * ```
+ *
+ * `deviceSecret` and `rootSecret` keep working everywhere they did. They are
+ * now one way of producing a `Signer` rather than the only way, and callers
+ * that pass a secret get a signer built for them.
+ */
+/**
+ * Something that can produce Ed25519 signatures and name the key they verify
+ * against.
+ *
+ * Deliberately the smallest surface that works: a signature and the public key
+ * it belongs to. Anything larger would start describing *how* the key is held,
+ * which is the detail this exists to hide — a hex seed, a non-extractable
+ * `CryptoKey`, a hardware token behind an async prompt, and a remote signing
+ * service all satisfy it.
+ */
+export interface Signer {
+    /**
+     * The public half, 64 hex characters.
+     *
+     * Carried rather than derived on demand because a non-extractable private key
+     * cannot produce it: the public half has to be captured when the key is
+     * generated. A signer that could not name its key would force every caller to
+     * pass the public key alongside it, and the two could then disagree.
+     */
+    readonly publicKey: string;
+    /**
+     * Sign `payload` — the exact bytes, with no hashing or framing added.
+     *
+     * Every caller in this package passes a 32-byte domain-separated digest it
+     * has already computed, and an implementation that hashed again would produce
+     * signatures that verify nowhere.
+     */
+    sign(payload: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * A signer over a raw 32-byte Ed25519 seed, hex.
+ *
+ * The public half is derived from the seed rather than accepted alongside it,
+ * for the reason core does the same: a caller able to name a key it does not
+ * hold could produce a statement it cannot sign, and the field would stop
+ * meaning "who authorised this".
+ *
+ * @param secret the seed, 64 hex characters
+ * @param label what to call it in an error — `deviceSecret`, `rootSecret`
+ */
+export declare function signerFromSecret(secret: string, label?: string): Promise<Signer>;
+/**
+ * A signer over a `CryptoKey` this process may use and cannot read.
+ *
+ * The point of the whole interface. Generate the key with
+ * `generateKey({ name: 'Ed25519' }, false, ['sign', 'verify'])`, keep the pair's
+ * private half (structured-clone it into IndexedDB if it must survive a reload),
+ * and pass it here with its public half.
+ *
+ * @param privateKey the signing key — extractable or not, it is never exported
+ * @param publicKey its public half: 64 hex, or the pair's `publicKey` (which
+ *   WebCrypto leaves exportable even when the private half is not)
+ */
+export declare function signerFromCryptoKey(privateKey: CryptoKey, publicKey: string | CryptoKey): Promise<Signer>;
+/**
+ * Resolve the signer an input describes, accepting either form.
+ *
+ * Internal. Every signing entry point takes an optional secret *and* an
+ * optional signer, and exactly one must be present — passing both is refused
+ * rather than silently preferring one, because the two could name different
+ * keys and the caller would have no way to tell which signed.
+ */
+export declare function resolveSigner(secret: string | undefined, signer: Signer | undefined, label: string): Promise<Signer>;

package/dist/signer/signer.js

@@ -0,0 +1,147 @@
+/**
+ * Who signs, separated from what is signed.
+ *
+ * Every signing entry point in this package used to take 32 hex bytes. That is
+ * fine for a CLI or a server holding a key file, and it is the one thing a
+ * browser must not do: a secret that exists as a string can be read by anything
+ * running on the origin, and a stolen account key is the account — permanently,
+ * because unlike a device key there is nothing above it to revoke it with.
+ *
+ * WebCrypto can hold an Ed25519 key that **signs but cannot be exported**
+ * (`generateKey(..., extractable: false, ...)`). Such a key has no hex
+ * representation to pass, so it could not be used with this package at all —
+ * which pushed consumers into reimplementing core's wire formats around their
+ * own key. That is the failure `crates/account/src/tests/sdk_credential_fixture.rs`
+ * exists to document: a second implementation of a byte contract agreed with
+ * itself for a full release while core rejected every credential it produced.
+ *
+ * So the interface is the key's *capability*, not its material:
+ *
+ * ```ts
+ * const signer = await signerFromSecret(deviceSecret);           // as before
+ * const signer = await signerFromCryptoKey(privateKey, pubKey);  // unexportable
+ * await signWarrant({ ...terms, signer });
+ * ```
+ *
+ * `deviceSecret` and `rootSecret` keep working everywhere they did. They are
+ * now one way of producing a `Signer` rather than the only way, and callers
+ * that pass a secret get a signer built for them.
+ */
+import { concat, fromHex, hex } from '../crypto/internal.js';
+/** Ed25519 PKCS#8 prefix, so a raw 32-byte seed can be imported by WebCrypto. */
+const PKCS8_ED25519_PREFIX = new Uint8Array([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04,
+    0x22, 0x04, 0x20,
+]);
+/** Turn WebCrypto's bare `NotSupportedError` into something actionable. */
+function unsupported(cause) {
+    // The original is folded into the message rather than passed as `cause`:
+    // this package targets ES2020, where `Error` has no `cause` option.
+    const detail = cause instanceof Error ? `: ${cause.message}` : '';
+    return new Error('this runtime has no WebCrypto Ed25519, so nothing can be signed here. ' +
+        'Node 18.4+, Safari 17+, Firefox 129+ and Chrome 137+ have it' +
+        detail);
+}
+/**
+ * A signer over a raw 32-byte Ed25519 seed, hex.
+ *
+ * The public half is derived from the seed rather than accepted alongside it,
+ * for the reason core does the same: a caller able to name a key it does not
+ * hold could produce a statement it cannot sign, and the field would stop
+ * meaning "who authorised this".
+ *
+ * @param secret the seed, 64 hex characters
+ * @param label what to call it in an error — `deviceSecret`, `rootSecret`
+ */
+export async function signerFromSecret(secret, label = 'secret') {
+    const seed = fromHex(secret, label, 32);
+    const pkcs8 = concat(PKCS8_ED25519_PREFIX, seed);
+    let privateKey;
+    let publicKey;
+    try {
+        // Imported twice on purpose: `extractable: true` is needed to read the
+        // public half out of a JWK, and the signing key is then re-imported
+        // unexportable so a `Signer` built from a secret is no more powerful than
+        // one built from a `CryptoKey`.
+        const exportable = await crypto.subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']);
+        const jwk = (await crypto.subtle.exportKey('jwk', exportable));
+        publicKey = hex(Uint8Array.from(atob(jwk.x.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0)));
+        privateKey = await crypto.subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, false, ['sign']);
+    }
+    catch (cause) {
+        throw unsupported(cause);
+    }
+    return fromKeyAndPublic(privateKey, publicKey);
+}
+/**
+ * A signer over a `CryptoKey` this process may use and cannot read.
+ *
+ * The point of the whole interface. Generate the key with
+ * `generateKey({ name: 'Ed25519' }, false, ['sign', 'verify'])`, keep the pair's
+ * private half (structured-clone it into IndexedDB if it must survive a reload),
+ * and pass it here with its public half.
+ *
+ * @param privateKey the signing key — extractable or not, it is never exported
+ * @param publicKey its public half: 64 hex, or the pair's `publicKey` (which
+ *   WebCrypto leaves exportable even when the private half is not)
+ */
+export async function signerFromCryptoKey(privateKey, publicKey) {
+    if (privateKey.type !== 'private') {
+        throw new Error(`signerFromCryptoKey needs the private half of the pair, got a ${privateKey.type} key`);
+    }
+    if (!privateKey.usages.includes('sign')) {
+        throw new Error("this CryptoKey cannot sign: generate it with usages ['sign', 'verify']");
+    }
+    let publicHex;
+    if (typeof publicKey === 'string') {
+        // Validated rather than trusted: a wrong public key produces signatures
+        // that verify nowhere, and the refusal arrives at a relay as a 403 —
+        // nowhere near this call.
+        fromHex(publicKey, 'publicKey', 32);
+        publicHex = publicKey.trim().toLowerCase();
+    }
+    else {
+        try {
+            publicHex = hex(new Uint8Array(await crypto.subtle.exportKey('raw', publicKey)));
+        }
+        catch (cause) {
+            const detail = cause instanceof Error ? `: ${cause.message}` : '';
+            throw new Error('could not read the public half of this key pair; pass the public key ' +
+                'as 64 hex instead' +
+                detail);
+        }
+    }
+    return fromKeyAndPublic(privateKey, publicHex);
+}
+/** The shared tail of both constructors. */
+function fromKeyAndPublic(privateKey, publicKey) {
+    return {
+        publicKey,
+        async sign(payload) {
+            try {
+                return new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, privateKey, payload));
+            }
+            catch (cause) {
+                throw unsupported(cause);
+            }
+        },
+    };
+}
+/**
+ * Resolve the signer an input describes, accepting either form.
+ *
+ * Internal. Every signing entry point takes an optional secret *and* an
+ * optional signer, and exactly one must be present — passing both is refused
+ * rather than silently preferring one, because the two could name different
+ * keys and the caller would have no way to tell which signed.
+ */
+export async function resolveSigner(secret, signer, label) {
+    if (signer && secret !== undefined) {
+        throw new Error(`pass either ${label} or signer, not both — they may name different keys`);
+    }
+    if (signer)
+        return signer;
+    if (secret !== undefined)
+        return signerFromSecret(secret, label);
+    throw new Error(`${label} or signer is required`);
+}

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

@@ -21,6 +21,7 @@
  * `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 { type Signer } from '../signer/signer.js';
 /** What a creation warrant authorises. */
 export interface CreationWarrantInput {
     /** The group the context is created in, hex (32 bytes). */
@@ -71,8 +72,21 @@ export interface CreationWarrantInput {
      * relay supplied is one the relay chose.
      */
     governanceFloor?: string[];
-    /** The author device's ed25519 signing secret, hex (32 bytes). Never sent. */
-    deviceSecret: string;
+    /**
+     * The author device's ed25519 signing secret, hex (32 bytes). Never sent.
+     *
+     * Mutually exclusive with {@link CreationWarrantInput.signer}: exactly one is required.
+     * Prefer `signer` in a browser, since a secret held as a string is readable
+     * by anything on the origin.
+     */
+    deviceSecret?: string;
+    /**
+     * The author device's signer, in place of {@link CreationWarrantInput.deviceSecret}: for a
+     * key that cannot be exported to hex (a non-extractable WebCrypto key, a
+     * passkey, a hardware or remote signer). Its `publicKey` becomes the
+     * warrant's `author_device_key`, and it signs the 32-byte preimage as is.
+     */
+    signer?: Signer;
 }
 /** A signed creation warrant and the seed it commits to. */
 export interface SignedCreationWarrant {
@@ -86,7 +100,7 @@ export interface CreationWarrantFields {
     group: string;
     seed: string;
     authorAccount: string;
-    /** The author device key `signCreationWarrant` derived from the secret. */
+    /** The author device key: the signer's public key. */
     deviceKey: string;
     executor: string;
     applicationId: string;

package/dist/warrant/creation-warrant.js

@@ -21,8 +21,9 @@
  * `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';
+import { concat, domainHash, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
+import { checkedSignature, 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. */
@@ -82,8 +83,8 @@ export async function signCreationWarrant(input) {
     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 signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
+    const deviceKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
     const initHash = await creationInitHash(input.initArgs);
     const preimage = await creationWarrantPreimage({
         group,
@@ -100,7 +101,7 @@ export async function signCreationWarrant(input) {
         nonce: input.nonce,
         notAfter: input.notAfter,
     });
-    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    const signature = checkedSignature(await signer.sign(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) };
 }

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

@@ -26,6 +26,7 @@
  * `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 Signer } from '../signer/signer.js';
 import type { GovernanceOp, GovernanceOpKind } from './governance-op.js';
 /** What a governance warrant authorises. */
 export interface GovernanceWarrantInput {
@@ -51,15 +52,28 @@ export interface GovernanceWarrantInput {
     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;
+    /**
+     * The author device's ed25519 signing secret, hex (32 bytes). Never sent.
+     *
+     * Mutually exclusive with {@link GovernanceWarrantInput.signer}: exactly one is required.
+     * Prefer `signer` in a browser, since a secret held as a string is readable
+     * by anything on the origin.
+     */
+    deviceSecret?: string;
+    /**
+     * The author device's signer, in place of {@link GovernanceWarrantInput.deviceSecret}: for a
+     * key that cannot be exported to hex (a non-extractable WebCrypto key, a
+     * passkey, a hardware or remote signer). Its `publicKey` becomes the
+     * warrant's `author_device_key`, and it signs the 32-byte preimage as is.
+     */
+    signer?: Signer;
 }
 /** 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. */
+    /** The author device key: the signer's public key. */
     deviceKey: string;
     executor: string;
     opHash: string;

package/dist/warrant/governance-warrant.js

@@ -26,8 +26,9 @@
  * `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';
+import { concat, domainHash, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
+import { checkedSignature, 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. */
@@ -72,8 +73,8 @@ export async function signGovernanceWarrant(input) {
     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 signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
+    const deviceKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
     const opHash = await governanceOpHash(input.op);
     const preimage = await governanceWarrantPreimage({
         scope,
@@ -87,7 +88,7 @@ export async function signGovernanceWarrant(input) {
         nonce: input.nonce,
         notAfter: input.notAfter,
     });
-    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    const signature = checkedSignature(await signer.sign(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));
 }
 /**

package/dist/warrant/warrant.d.ts

@@ -27,6 +27,7 @@
  * this producing well-formed warrants whose signatures verify nowhere, surfacing
  * at a relay as a 403: an authorization refusal, nowhere near the cause.
  */
+import { type Signer } from '../signer/signer.js';
 /** Ed25519 PKCS#8 prefix, so a raw 32-byte seed can be imported by WebCrypto. */
 /** What a warrant authorises. */
 export interface WarrantInput {
@@ -103,8 +104,18 @@ export interface WarrantInput {
      *
      * Never sent anywhere. It signs locally and only the signature travels, which
      * is the whole reason a warrant can be minted by something holding no node.
+     *
+     * Mutually exclusive with {@link WarrantInput.signer}: exactly one is
+     * required. Prefer `signer` in a browser, since a secret held as a string is
+     * readable by anything on the origin.
+     */
+    deviceSecret?: string;
+    /**
+     * The author device's signer, in place of {@link WarrantInput.deviceSecret}:
+     * for a key that cannot be exported to hex (a non-extractable WebCrypto key,
+     * a passkey, a hardware or remote signer).
      */
-    deviceSecret: string;
+    signer?: Signer;
 }
 /**
  * The commitment a warrant carries in place of the intent itself.
@@ -125,6 +136,14 @@ 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.
  */
+/**
+ * A signer's output, refused unless it is a 64-byte Ed25519 signature.
+ *
+ * The signature is spliced into the encoding at a fixed width, so a signer that
+ * returned anything else would yield a warrant that parses as garbage at a
+ * relay, far from the signer at fault. Internal.
+ */
+export declare function checkedSignature(signature: Uint8Array): Uint8Array;
 export declare function citedHeads(heads: string[] | undefined, label: string): Uint8Array[];
 /** A warrant's fields, as hex, decoded from the wire encoding. */
 export interface WarrantFields {

package/dist/warrant/warrant.js

@@ -27,7 +27,8 @@
  * this producing well-formed warrants whose signatures verify nowhere, surfacing
  * at a relay as a 403: an authorization refusal, nowhere near the cause.
  */
-import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+import { concat, domainHash, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
 const SIGN_DOMAIN = new TextEncoder().encode('calimero.warrant.v2');
 const INTENT_DOMAIN = new TextEncoder().encode('calimero.warrant.intent.v1');
 /**
@@ -61,8 +62,8 @@ export async function signWarrant(input) {
     const appVersion = fromHex(input.appVersion ?? UNPINNED_APP, 'appVersion', 32);
     const accountHeads = citedHeads(input.accountHeads, 'accountHeads');
     const governanceFloor = citedHeads(input.governanceFloor, 'governanceFloor');
-    const key = await importSigningKey(input.deviceSecret);
-    const publicKey = await derivePublicKey(input.deviceSecret);
+    const signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
+    const publicKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
     const method = new TextEncoder().encode(input.method);
     const commitment = await intentHash(input.method, input.argsJson);
     const nonce = u64le(input.nonce);
@@ -87,7 +88,7 @@ export async function signWarrant(input) {
         nonce,
         notAfter,
     ]);
-    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    const signature = checkedSignature(await signer.sign(preimage));
     // Borsh: a `String` is a u32 length then its UTF-8 bytes; a `Vec<[u8; 32]>` is
     // a u32 count then the elements. u32 HERE; u64 in the preimage above.
     return hex(concat(context, authorAccount, publicKey, executor, appVersion, u32le(method.length), method, commitment, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, nonce, notAfter, signature));
@@ -96,6 +97,20 @@ export async function signWarrant(input) {
  * 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.
  */
+/**
+ * A signer's output, refused unless it is a 64-byte Ed25519 signature.
+ *
+ * The signature is spliced into the encoding at a fixed width, so a signer that
+ * returned anything else would yield a warrant that parses as garbage at a
+ * relay, far from the signer at fault. Internal.
+ */
+export function checkedSignature(signature) {
+    if (!(signature instanceof Uint8Array) || signature.length !== 64) {
+        const got = signature instanceof Uint8Array ? `${signature.length} bytes` : typeof signature;
+        throw new Error(`signer returned ${got}, expected a 64-byte Ed25519 signature`);
+    }
+    return signature;
+}
 export function citedHeads(heads, label) {
     const list = heads ?? [];
     if (list.length > MAX_CITED_HEADS) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "22.5.0",
+  "version": "22.6.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {