@calimero-network/mero-js 22.5.1 → 22.7.0

package/dist/relay/index.d.ts

@@ -1,4 +1,4 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
-export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, } from './relay-client.js';
+export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, FoundNamespaceInput, FoundedNamespace, } 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

@@ -27,7 +27,8 @@
  * monotonic per-device sequence, and one minted against the wrong executor is
  * unspendable: the number is gone and the write never happened.
  */
-import type { GovernanceOp } from '../warrant/governance-op.js';
+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;
     /**
@@ -158,6 +169,61 @@ export interface GovernResult {
     /** The group the op acted on, hex: the new subgroup, for a creation. */
     groupId: string;
 }
+/** What {@link RelayClient.foundNamespace} founds with. */
+export interface FoundNamespaceInput {
+    /**
+     * The salt the namespace id is derived from, hex (32 bytes). Random when
+     * absent, which is what almost every caller wants: one account founds many
+     * namespaces by varying it.
+     */
+    salt?: string;
+    /**
+     * The relay's account, hex: the warrant's `executor`. The namespace does not
+     * exist yet, so there is nothing to ask `describeGovernance` about. Falls back
+     * to the client's configured or already-learned `executorAccount`.
+     */
+    executorAccount?: string;
+    /**
+     * The namespace root's default capability mask (`MemberCapabilities` bits),
+     * set right after founding. A namespace is founded with core's minimal
+     * default (`CAN_JOIN_OPEN_SUBGROUPS` only), so an app that wants members to
+     * create contexts or invite, for example, names its own mask here.
+     *
+     * Set through the relay with a delegated `DefaultCapabilitiesSet`, applied as
+     * the founder, who is the namespace's admin. It cannot include
+     * `CAN_AUTHOR_ON_BEHALF` (bit 9): which relays may write for members is never
+     * decided through a relay, and such a mask is refused before anything is
+     * signed.
+     */
+    defaultCapabilities?: number;
+}
+/** A namespace founded through a relay. */
+export interface FoundedNamespace {
+    /** The new namespace's id, hex: `foundedNamespaceId(author, salt)`. */
+    namespaceId: string;
+    /**
+     * The salt it was derived with, hex. Keep it if anyone will need to be shown
+     * who founded the namespace: `(founder, salt)` reproduces the id.
+     */
+    salt: string;
+    /**
+     * Whether the relay admitted itself as the namespace's first TEE, which also
+     * sets its default relay-mode admission policy. `false` from a relay that is
+     * not a TEE, or whose attestation failed (see `teeError`). The namespace is
+     * founded either way.
+     */
+    teeEnabled: boolean;
+    /** Why `teeEnabled` is `false`, when the relay tried and failed. */
+    teeError?: string;
+    /**
+     * Present only when `defaultCapabilities` was asked for: whether the mask was
+     * set. `false` leaves the namespace founded with core's default; retry with
+     * `govern({ groupId: namespaceId, op: defaultCapabilitiesSetOp(mask) })`.
+     */
+    defaultCapabilitiesSet?: boolean;
+    /** Why `defaultCapabilitiesSet` is `false`. */
+    defaultCapabilitiesError?: string;
+}
 /** Where an accepted intent landed. */
 export interface IntentResult<T = unknown> {
     /** The context's scope root after the run — did this change anything? */
@@ -198,6 +264,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`.
      *
@@ -267,6 +339,39 @@ export declare class RelayClient {
      * other warrant.
      */
     govern(input: GovernInput): Promise<GovernResult>;
+    /**
+     * Found a namespace through the relay, with the author as its founder, owner
+     * and admin. For an account with no node, this is how it gets a namespace at
+     * all.
+     *
+     * The author signs the exact genesis (`NamespaceCreatedV2`, carrying the
+     * author's own credential and the salt) under a root-plane governance
+     * warrant scoped to the new namespace's id, which is derived from the
+     * author's account and the salt, so the relay can neither choose another id
+     * nor found it for anyone else. The relay takes an identity in the new
+     * namespace, mints its key, publishes the genesis, and is seated as the
+     * founding relay (a `Member` holding `CAN_AUTHOR_ON_BEHALF`), so later
+     * `govern`, `createContext` and `execute` calls in the namespace work
+     * through it straight away. A TEE relay then admits itself as the
+     * namespace's first TEE; `teeEnabled` reports whether it did.
+     *
+     * The executor cannot be learned from the relay first: the namespace does not
+     * exist, so `describeGovernance` has nothing to answer about. It comes from
+     * `input.executorAccount`, the configured one, or one an earlier call learned
+     * (`describe`, `createContext`, `govern`), and without any of them this
+     * throws before taking a nonce.
+     * The nonce is spent in the new namespace's ledger.
+     *
+     * With `defaultCapabilities`, the founder then sets the namespace's default
+     * capability mask through the same relay (a second warrant, a second nonce)
+     * and `defaultCapabilitiesSet` reports whether it landed. A failure there
+     * does not throw, since the namespace is already founded.
+     *
+     * Refusals (`400`/`403`) come back as {@link IntentRefusedError}; a salt
+     * that names an existing namespace is a `409`, an `HTTPError`.
+     */
+    foundNamespace(input?: FoundNamespaceInput): Promise<FoundedNamespace>;
+    private postGovernance;
     /**
      * The executor a warrant must name: the one the relay answered with, which a
      * configured account must agree with. Remembered for later calls.

package/dist/relay/relay-client.js

@@ -30,8 +30,10 @@
 import { signWarrant } from '../warrant/warrant.js';
 import { signCreationWarrant } from '../warrant/creation-warrant.js';
 import { signGovernanceWarrant } from '../warrant/governance-warrant.js';
+import { defaultCapabilitiesSetOp, foundedNamespaceId, namespaceCreatedOp, } from '../warrant/governance-op.js';
 import { HTTPError } from '../http-client/web-client.js';
-import { hex } from '../crypto/internal.js';
+import { fromHex, 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 +73,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 +104,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 +116,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 +169,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 +184,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 +225,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,10 +236,109 @@ export class RelayClient {
             executor,
             nonce,
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
-            deviceSecret: this.config.deviceSecret,
+            signer,
+        });
+        const data = await this.postGovernance(input.groupId, input.op, warrant);
+        return { groupId: data.groupId };
+    }
+    /**
+     * Found a namespace through the relay, with the author as its founder, owner
+     * and admin. For an account with no node, this is how it gets a namespace at
+     * all.
+     *
+     * The author signs the exact genesis (`NamespaceCreatedV2`, carrying the
+     * author's own credential and the salt) under a root-plane governance
+     * warrant scoped to the new namespace's id, which is derived from the
+     * author's account and the salt, so the relay can neither choose another id
+     * nor found it for anyone else. The relay takes an identity in the new
+     * namespace, mints its key, publishes the genesis, and is seated as the
+     * founding relay (a `Member` holding `CAN_AUTHOR_ON_BEHALF`), so later
+     * `govern`, `createContext` and `execute` calls in the namespace work
+     * through it straight away. A TEE relay then admits itself as the
+     * namespace's first TEE; `teeEnabled` reports whether it did.
+     *
+     * The executor cannot be learned from the relay first: the namespace does not
+     * exist, so `describeGovernance` has nothing to answer about. It comes from
+     * `input.executorAccount`, the configured one, or one an earlier call learned
+     * (`describe`, `createContext`, `govern`), and without any of them this
+     * throws before taking a nonce.
+     * The nonce is spent in the new namespace's ledger.
+     *
+     * With `defaultCapabilities`, the founder then sets the namespace's default
+     * capability mask through the same relay (a second warrant, a second nonce)
+     * and `defaultCapabilitiesSet` reports whether it landed. A failure there
+     * does not throw, since the namespace is already founded.
+     *
+     * Refusals (`400`/`403`) come back as {@link IntentRefusedError}; a salt
+     * that names an existing namespace is a `409`, an `HTTPError`.
+     */
+    async foundNamespace(input = {}) {
+        const executor = input.executorAccount
+            ? this.checkedExecutor(input.executorAccount)
+            : this.executorAccount;
+        if (!executor) {
+            throw new Error("foundNamespace needs the relay's account: pass executorAccount or configure it " +
+                '(checked before signing, no nonce was spent)');
+        }
+        const salt = input.salt
+            ? hex(fromHex(input.salt, 'salt', 32))
+            : hex(crypto.getRandomValues(new Uint8Array(32)));
+        const namespaceId = await foundedNamespaceId(this.config.authorAccount, salt);
+        const op = namespaceCreatedOp({
+            founder: this.config.authorAccount,
+            credential: this.config.authorProof,
+            salt,
+        });
+        // Encoded (and so validated) before anything is signed: a mask the relay
+        // would refuse must not cost the founding a nonce.
+        const capabilitiesOp = input.defaultCapabilities === undefined
+            ? undefined
+            : defaultCapabilitiesSetOp(input.defaultCapabilities);
+        // 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({
+            scope: namespaceId,
+            op,
+            authorAccount: this.config.authorAccount,
+            executor,
+            nonce,
+            notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
+            signer,
+        });
+        const data = await this.postGovernance(namespaceId, op, warrant);
+        const founded = {
+            namespaceId: data.groupId,
+            salt,
+            teeEnabled: data.teeEnabled ?? false,
+            ...(data.teeError ? { teeError: data.teeError } : {}),
+        };
+        if (!capabilitiesOp)
+            return founded;
+        // A second op, under its own warrant, on the namespace root: the founder is
+        // its admin and the relay was seated to act for members, so it goes through
+        // the ordinary `govern` path. The namespace exists whatever happens here, so
+        // a failure is reported rather than thrown.
+        try {
+            await this.govern({ groupId: founded.namespaceId, op: capabilitiesOp });
+            return { ...founded, defaultCapabilitiesSet: true };
+        }
+        catch (err) {
+            return {
+                ...founded,
+                defaultCapabilitiesSet: false,
+                defaultCapabilitiesError: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    async postGovernance(groupId, op, warrant) {
+        const body = await this.json('POST', `/admin-api/groups/${encodeURIComponent(groupId)}/governance-intents`, {
+            warrant,
+            authorProof: this.config.authorProof,
+            op: hex(op.bytes),
         });
-        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 };
+        return body.data;
     }
     /**
      * The executor a warrant must name: the one the relay answered with, which a

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) };
 }