@calimero-network/mero-js 22.7.0 → 22.9.0

package/dist/cloud/link-redirect.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Linking an account to a cloud login **from a browser**.
+ *
+ * The cloud's own accounts screen says it plainly: *"The cloud cannot link an
+ * account on your behalf: proving you own it is a signature by the account root
+ * key, which the cloud never holds."* So the link needs two things that live in
+ * different places — a cloud session, which only Google can mint, and a root
+ * signature, which only the holder can make. Neither side can do it alone.
+ *
+ * The cloud already implements its half: send a person to
+ * `?link-account=<id>&callback-url=<url>`, it shows a consent screen and
+ * redirects back with a **grant** — that login's sealed consent to link one
+ * named account. This module is the missing other half, and it is deliberately
+ * small: send them there, then spend what comes back.
+ *
+ * ## Why a grant rather than a session
+ *
+ * A grant is spendable by anyone holding the account's root, and by nobody
+ * else. That is what lets the page complete the link while holding **no cloud
+ * session at all** — and it is why a wallet should never be handed one. A
+ * session token is a credential for everything that login can do; a grant is a
+ * credential for exactly one link, to exactly one account, sealed at the moment
+ * the person read the id on screen and agreed to it.
+ *
+ * ## The account id is chosen by us and read by them
+ *
+ * The cloud seals the account into the grant at consent time, and its own note
+ * says why: the server can check that the key which later signs derives that
+ * same account, but *"it cannot know whether the person meant this account"*.
+ * The consent screen is that check. So show the same id the person will see,
+ * before sending them — a wallet that hides it has removed the only safeguard.
+ */
+import type { CloudAccountLink } from './cloud-client.js';
+import { type RootSource } from '../account/account.js';
+export interface BeginCloudLinkOptions {
+    /** The account to link — 64 hex. Show this to the person before redirecting. */
+    accountId: string;
+    /**
+     * Where the cloud sends them back. Must be `https:`, or `http:` on localhost.
+     *
+     * The grant returns in the URL **fragment**, which is never sent to a server,
+     * so it does not land in anyone's access log on the way.
+     */
+    returnTo: string;
+    /** The cloud's web origin. Defaults to the hosted one. */
+    cloudWebUrl?: string;
+}
+/** The consent URL to send a person to. */
+export declare function cloudLinkUrl(options: BeginCloudLinkOptions): string;
+/** Send the person to the cloud to consent. Does not return. */
+export declare function beginCloudLink(options: BeginCloudLinkOptions): never;
+/** What came back in the fragment, if anything. */
+export interface CloudLinkCallback {
+    grant: string;
+    /** The account the cloud sealed into the grant. */
+    account: string;
+}
+/**
+ * Read a grant out of the current URL fragment, and strip it.
+ *
+ * Returns `null` when this is an ordinary page load, so a caller can run it
+ * unconditionally at startup. Throws when the person declined, because that is
+ * an outcome the app has to show rather than a state to wait in.
+ */
+export declare function readCloudLinkCallback(location?: {
+    hash: string;
+}): CloudLinkCallback | null;
+export interface CompleteCloudLinkOptions extends CloudLinkCallback {
+    /** The account root — a 64-hex secret, or a Signer over a key you cannot read. */
+    root: RootSource;
+    /** The **manager** API base, e.g. `https://manager.cloud.calimero.network`. */
+    cloudBaseUrl?: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Spend the grant: sign it with the root and hand it back to the cloud.
+ *
+ * Anonymous by construction — the client is built with no session, because the
+ * whole point is that the page never needed one.
+ *
+ * @throws if the grant names a different account than the root derives, before
+ * anything is sent. The cloud checks this too, but failing here says which two
+ * accounts disagreed rather than returning a bare 403.
+ */
+export declare function completeCloudLink(options: CompleteCloudLinkOptions): Promise<CloudAccountLink>;

package/dist/cloud/link-redirect.js

@@ -0,0 +1,105 @@
+/**
+ * Linking an account to a cloud login **from a browser**.
+ *
+ * The cloud's own accounts screen says it plainly: *"The cloud cannot link an
+ * account on your behalf: proving you own it is a signature by the account root
+ * key, which the cloud never holds."* So the link needs two things that live in
+ * different places — a cloud session, which only Google can mint, and a root
+ * signature, which only the holder can make. Neither side can do it alone.
+ *
+ * The cloud already implements its half: send a person to
+ * `?link-account=<id>&callback-url=<url>`, it shows a consent screen and
+ * redirects back with a **grant** — that login's sealed consent to link one
+ * named account. This module is the missing other half, and it is deliberately
+ * small: send them there, then spend what comes back.
+ *
+ * ## Why a grant rather than a session
+ *
+ * A grant is spendable by anyone holding the account's root, and by nobody
+ * else. That is what lets the page complete the link while holding **no cloud
+ * session at all** — and it is why a wallet should never be handed one. A
+ * session token is a credential for everything that login can do; a grant is a
+ * credential for exactly one link, to exactly one account, sealed at the moment
+ * the person read the id on screen and agreed to it.
+ *
+ * ## The account id is chosen by us and read by them
+ *
+ * The cloud seals the account into the grant at consent time, and its own note
+ * says why: the server can check that the key which later signs derives that
+ * same account, but *"it cannot know whether the person meant this account"*.
+ * The consent screen is that check. So show the same id the person will see,
+ * before sending them — a wallet that hides it has removed the only safeguard.
+ */
+import { CloudClient } from './cloud-client.js';
+import { resolveRoot } from '../account/account.js';
+/** Where the consent screen lives. The web app, not the manager API. */
+const DEFAULT_CLOUD_WEB_URL = 'https://cloud.calimero.network';
+/** The consent URL to send a person to. */
+export function cloudLinkUrl(options) {
+    if (!/^[0-9a-f]{64}$/.test(options.accountId)) {
+        throw new Error('accountId must be 64 lowercase hex characters');
+    }
+    const url = new URL(options.cloudWebUrl ?? DEFAULT_CLOUD_WEB_URL);
+    url.searchParams.set('link-account', options.accountId);
+    url.searchParams.set('callback-url', options.returnTo);
+    return url.toString();
+}
+/** Send the person to the cloud to consent. Does not return. */
+export function beginCloudLink(options) {
+    window.location.assign(cloudLinkUrl(options));
+    // `assign` does not stop execution, and a caller that kept going would act on
+    // a page already being replaced.
+    throw new Error('redirecting to the cloud to authorise this link');
+}
+/**
+ * Read a grant out of the current URL fragment, and strip it.
+ *
+ * Returns `null` when this is an ordinary page load, so a caller can run it
+ * unconditionally at startup. Throws when the person declined, because that is
+ * an outcome the app has to show rather than a state to wait in.
+ */
+export function readCloudLinkCallback(location = window.location) {
+    const params = new URLSearchParams(location.hash.replace(/^#/, ''));
+    const error = params.get('error');
+    if (error) {
+        stripFragment();
+        throw new Error(error === 'denied'
+            ? 'the account link was declined at the cloud'
+            : `the cloud refused this link: ${error}`);
+    }
+    const grant = params.get('grant');
+    const account = params.get('account');
+    if (!grant || !account)
+        return null;
+    // Consumed once. Leaving it in the bar means a reload replays a spent grant
+    // and reports a confusing failure instead of the link that already worked.
+    stripFragment();
+    return { grant, account };
+}
+function stripFragment() {
+    if (typeof history === 'undefined' || !history.replaceState)
+        return;
+    history.replaceState(null, '', location.pathname + location.search);
+}
+/**
+ * Spend the grant: sign it with the root and hand it back to the cloud.
+ *
+ * Anonymous by construction — the client is built with no session, because the
+ * whole point is that the page never needed one.
+ *
+ * @throws if the grant names a different account than the root derives, before
+ * anything is sent. The cloud checks this too, but failing here says which two
+ * accounts disagreed rather than returning a bare 403.
+ */
+export async function completeCloudLink(options) {
+    const root = await resolveRoot(options.root);
+    if (root.accountId !== options.account) {
+        throw new Error(`this grant is for account ${options.account}, but the root here derives ` +
+            `${root.accountId} — it was minted for a different account`);
+    }
+    const cloud = new CloudClient({
+        cloudBaseUrl: options.cloudBaseUrl,
+        fetch: options.fetch,
+    });
+    return cloud.linkAccountWithGrant({ grant: options.grant, signer: root.signer });
+}

package/dist/crypto/internal.d.ts

@@ -31,6 +31,21 @@ export declare function concat(...parts: Uint8Array[]): Uint8Array;
  */
 export declare function domainHash(domain: Uint8Array, parts: Uint8Array[]): Promise<Uint8Array>;
 export declare function importSigningKey(secretHex: string): Promise<CryptoKey>;
+/**
+ * Check an ed25519 signature against a public key, both raw.
+ *
+ * The one primitive here that consumes rather than produces a signature: a page
+ * handed a credential by another origin has to check it before it acts on it,
+ * and "the node will reject it later" is not the same safeguard — by then the
+ * page has already stored an account it does not control.
+ *
+ * `raw` import is the public-key counterpart of the PKCS#8 import above and is
+ * available on exactly the runtimes that can sign, so a runtime that got this
+ * far will not fail here for lack of support.
+ *
+ * @param publicKey 64 hex, the key the signature must verify against
+ */
+export declare function verifySignature(publicKey: string, signature: Uint8Array, payload: Uint8Array): Promise<boolean>;
 /**
  * The public half of an ed25519 seed.
  *

package/dist/crypto/internal.js

@@ -97,6 +97,24 @@ export async function importSigningKey(secretHex) {
             detail);
     }
 }
+/**
+ * Check an ed25519 signature against a public key, both raw.
+ *
+ * The one primitive here that consumes rather than produces a signature: a page
+ * handed a credential by another origin has to check it before it acts on it,
+ * and "the node will reject it later" is not the same safeguard — by then the
+ * page has already stored an account it does not control.
+ *
+ * `raw` import is the public-key counterpart of the PKCS#8 import above and is
+ * available on exactly the runtimes that can sign, so a runtime that got this
+ * far will not fail here for lack of support.
+ *
+ * @param publicKey 64 hex, the key the signature must verify against
+ */
+export async function verifySignature(publicKey, signature, payload) {
+    const key = await crypto.subtle.importKey('raw', fromHex(publicKey, 'publicKey', 32), { name: 'Ed25519' }, false, ['verify']);
+    return crypto.subtle.verify({ name: 'Ed25519' }, key, signature, payload);
+}
 /**
  * The public half of an ed25519 seed.
  *

package/dist/device-cert/device-cert.d.ts

@@ -1,7 +1,36 @@
+import { type Signer } from '../signer/signer.js';
+/**
+ * Core's `ACCOUNT_GENESIS_VERSION`. It is part of the `AccountId` preimage, so
+ * this value decides which account a root key names — a mismatch does not fail
+ * as a version error at the edge, it silently derives a different account and
+ * core refuses the credential as unverifiable.
+ *
+ * `2` since the genesis dropped its per-namespace nonce. This was `1`, which
+ * produced credentials current core rejects outright; the shape was already v2,
+ * only the tag was stale.
+ */
+export declare const ACCOUNT_GENESIS_VERSION = 2;
 /** What a root certifies about one device. */
 export interface DeviceCertInput {
-    /** The account root's signing secret, 64 hex. Signs the certificate. */
-    rootSecret: string;
+    /**
+     * The account root's signing secret, 64 hex. Signs the certificate.
+     *
+     * Mutually exclusive with {@link DeviceCertInput.signer}, and the weaker of
+     * the two in a browser: this is the one key in the system with nothing above
+     * it to revoke it, so a page that can read it can take the account for good.
+     * Prefer `signer` anywhere the root is held rather than loaded.
+     */
+    rootSecret?: string;
+    /**
+     * The account root's signer — use instead of {@link DeviceCertInput.rootSecret}
+     * when the root is a key this page may use and cannot read.
+     *
+     * This is what lets the certifying page keep its root as a non-extractable
+     * `CryptoKey`: {@link accountRootSignerFromPhrase} hands one back, and script
+     * injected into the page can then mint certificates only while the page is
+     * open, rather than walking off with the account.
+     */
+    signer?: Signer;
     /** The device being certified, 64 hex — see {@link mintDeviceId}. */
     device: string;
     /** The key that device signs with, 64 hex. */
@@ -88,5 +117,70 @@ export declare function accountProofBytes(input: {
  * than accepting a value it would then have to ignore.
  */
 export declare function signDeviceCert(input: DeviceCertInput): Promise<string>;
+/** A credential read back apart, field for field. */
+export interface DeviceCredential {
+    /** The account root that signed, 64 hex — `AccountGenesis::root_sign_pk`. */
+    rootPublicKey: string;
+    /** The account the certificate names, 64 hex. */
+    account: string;
+    /** The device it certifies, 64 hex. */
+    device: string;
+    /** That device's ed25519 signing key, 64 hex. */
+    signPublicKey: string;
+    /** That device's X25519 key-delivery key, 64 hex. */
+    kemPublicKey: string;
+    keyEpoch: number;
+    deviceEpoch: number;
+    /** The root's signature over {@link deviceCertPayload}, 128 hex. */
+    signature: string;
+}
+/**
+ * Read an `AccountProof<DeviceCert>` back apart — the inverse of
+ * {@link accountProofBytes}, and deliberately in the same file as it.
+ *
+ * A decoder that lives away from its encoder drifts: the layout is only checked
+ * by a peer rejecting a signature, which points at the signature rather than at
+ * whichever copy went stale.
+ *
+ * This checks the *shape* and nothing else — it says what the bytes claim, not
+ * whether the claim is true. {@link verifyDeviceCredential} is the one that
+ * answers that, and it is the one a caller acting on a credential from another
+ * origin wants.
+ *
+ * @throws on a wrong genesis version, a non-empty handoff chain, or trailing
+ * bytes. A non-empty chain is refused rather than skipped: verifying a handed-off
+ * root means walking the chain, and a decoder that returned the statement while
+ * ignoring who was entitled to sign it would hand a verifier the wrong root.
+ */
+export declare function parseDeviceCredential(credential: string): DeviceCredential;
+/**
+ * Check that a credential says what it claims: the root signed it, and the
+ * account it names is the one that root derives.
+ *
+ * Both halves matter and neither implies the other. The signature says the
+ * genesis root consented to these exact keys; the account derivation says the
+ * certificate cannot have been re-pointed at a different account while keeping a
+ * signature that verifies. A caller that checked only the first would accept a
+ * certificate naming an account whose root never signed anything.
+ *
+ * What it does **not** establish is that the account is one the caller wanted.
+ * Anyone can mint a root offline and certify any public key with it, so a
+ * credential arriving from elsewhere proves a *consistent* account, not *your*
+ * account — see `cloud/enrol-redirect.ts` for the binding that closes that.
+ *
+ * @throws with which check failed, rather than returning false — every failure
+ * here is a credential that must not be stored, and a boolean gets ignored.
+ */
+export declare function verifyDeviceCredential(credential: string): Promise<DeviceCredential>;
 /** The account this root owns — the content address of its genesis. */
 export declare function accountForRoot(rootSecret: string): Promise<string>;
+/**
+ * The same account id, from the root's **public** half.
+ *
+ * The form a root that cannot be exported needs. It is also the honest shape of
+ * the derivation: an account id is a function of the public key, and asking for
+ * the secret only ever meant "let me derive the public key first".
+ *
+ * @param rootPublicKey the root's ed25519 public key, 64 hex
+ */
+export declare function accountForRootPublicKey(rootPublicKey: string): Promise<string>;

package/dist/device-cert/device-cert.js

@@ -15,11 +15,11 @@
  * - `DeviceId::mint`              — `crates/primitives/src/identity.rs`
  * - `AccountProof` / `AccountGenesis` borsh layout — `crates/account/src/{signed,account}.rs`
  */
-import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, } from '../crypto/internal.js';
+import { concat, derivePublicKey, domainHash, fromHex, hex, u32le, verifySignature, } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
 const CERT_DOMAIN = new TextEncoder().encode('calimero.device.cert.v1');
 const ACCOUNT_ID_DOMAIN = new TextEncoder().encode('calimero.account.genesis.v1');
 const DEVICE_ID_DOMAIN = new TextEncoder().encode('calimero.device.id.v1');
-/** `AccountGenesis::version`, which the credential's borsh encoding leads with. */
 /**
  * Core's `ACCOUNT_GENESIS_VERSION`. It is part of the `AccountId` preimage, so
  * this value decides which account a root key names — a mismatch does not fail
@@ -30,7 +30,9 @@ const DEVICE_ID_DOMAIN = new TextEncoder().encode('calimero.device.id.v1');
  * produced credentials current core rejects outright; the shape was already v2,
  * only the tag was stale.
  */
-const ACCOUNT_GENESIS_VERSION = 2;
+export const ACCOUNT_GENESIS_VERSION = 2;
+/** Byte length of an `AccountProof<DeviceCert>` with an empty handoff chain. */
+const ACCOUNT_PROOF_BYTES = 237;
 /**
  * Mint a device id: `H(DEVICE_ID_DOMAIN, account ‖ nonce)`.
  *
@@ -104,10 +106,11 @@ export function accountProofBytes(input) {
  * than accepting a value it would then have to ignore.
  */
 export async function signDeviceCert(input) {
-    const rootPublicKey = await derivePublicKey(input.rootSecret);
-    const account = hex(await domainHash(ACCOUNT_ID_DOMAIN, [
-        concat(new Uint8Array([ACCOUNT_GENESIS_VERSION]), rootPublicKey),
-    ]));
+    const signer = await resolveSigner(input.rootSecret, input.signer, 'rootSecret');
+    // The signer names its own key, so the account is read off it rather than
+    // derived from material this function may not have.
+    const rootPublicKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
+    const account = await accountForRootPublicKey(signer.publicKey);
     const keyEpoch = 0;
     const payload = await deviceCertPayload({
         account,
@@ -117,8 +120,7 @@ export async function signDeviceCert(input) {
         keyEpoch,
         deviceEpoch: input.deviceEpoch,
     });
-    const key = await importSigningKey(input.rootSecret);
-    const signature = new Uint8Array(await crypto.subtle.sign('Ed25519', key, payload));
+    const signature = await signer.sign(payload);
     const credential = accountProofBytes({
         rootPublicKey,
         account,
@@ -131,10 +133,98 @@ export async function signDeviceCert(input) {
     });
     return hex(credential);
 }
+/**
+ * Read an `AccountProof<DeviceCert>` back apart — the inverse of
+ * {@link accountProofBytes}, and deliberately in the same file as it.
+ *
+ * A decoder that lives away from its encoder drifts: the layout is only checked
+ * by a peer rejecting a signature, which points at the signature rather than at
+ * whichever copy went stale.
+ *
+ * This checks the *shape* and nothing else — it says what the bytes claim, not
+ * whether the claim is true. {@link verifyDeviceCredential} is the one that
+ * answers that, and it is the one a caller acting on a credential from another
+ * origin wants.
+ *
+ * @throws on a wrong genesis version, a non-empty handoff chain, or trailing
+ * bytes. A non-empty chain is refused rather than skipped: verifying a handed-off
+ * root means walking the chain, and a decoder that returned the statement while
+ * ignoring who was entitled to sign it would hand a verifier the wrong root.
+ */
+export function parseDeviceCredential(credential) {
+    const bytes = fromHex(credential, 'credential', 
+    // Fixed-width with an empty chain: 1 + 32 + 4 + 32*4 + 4 + 4 + 64.
+    ACCOUNT_PROOF_BYTES);
+    if (bytes[0] !== ACCOUNT_GENESIS_VERSION) {
+        throw new Error(`this credential has account genesis version ${bytes[0]}, not ` +
+            `${ACCOUNT_GENESIS_VERSION} — it names a different account than its root ` +
+            'key derives here, and core would refuse it');
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const chainLength = view.getUint32(33, true);
+    if (chainLength !== 0) {
+        throw new Error(`this credential carries a ${chainLength}-handoff root chain, which this ` +
+            'SDK cannot verify yet — the signing root is not the genesis root, so ' +
+            'checking it means walking the chain');
+    }
+    const at = (offset, length) => hex(bytes.subarray(offset, offset + length));
+    return {
+        rootPublicKey: at(1, 32),
+        account: at(37, 32),
+        device: at(69, 32),
+        signPublicKey: at(101, 32),
+        kemPublicKey: at(133, 32),
+        keyEpoch: view.getUint32(165, true),
+        deviceEpoch: view.getUint32(169, true),
+        signature: at(173, 64),
+    };
+}
+/**
+ * Check that a credential says what it claims: the root signed it, and the
+ * account it names is the one that root derives.
+ *
+ * Both halves matter and neither implies the other. The signature says the
+ * genesis root consented to these exact keys; the account derivation says the
+ * certificate cannot have been re-pointed at a different account while keeping a
+ * signature that verifies. A caller that checked only the first would accept a
+ * certificate naming an account whose root never signed anything.
+ *
+ * What it does **not** establish is that the account is one the caller wanted.
+ * Anyone can mint a root offline and certify any public key with it, so a
+ * credential arriving from elsewhere proves a *consistent* account, not *your*
+ * account — see `cloud/enrol-redirect.ts` for the binding that closes that.
+ *
+ * @throws with which check failed, rather than returning false — every failure
+ * here is a credential that must not be stored, and a boolean gets ignored.
+ */
+export async function verifyDeviceCredential(credential) {
+    const parsed = parseDeviceCredential(credential);
+    const derived = await accountForRootPublicKey(parsed.rootPublicKey);
+    if (derived !== parsed.account) {
+        throw new Error(`this credential names account ${parsed.account}, but its root key ` +
+            `derives ${derived} — the certificate was re-pointed at another account`);
+    }
+    const signed = await verifySignature(parsed.rootPublicKey, fromHex(parsed.signature, 'signature', 64), await deviceCertPayload(parsed));
+    if (!signed) {
+        throw new Error(`the root key of account ${parsed.account} did not sign this certificate`);
+    }
+    return parsed;
+}
 /** The account this root owns — the content address of its genesis. */
 export async function accountForRoot(rootSecret) {
-    const rootPublicKey = await derivePublicKey(rootSecret);
+    return accountForRootPublicKey(hex(await derivePublicKey(rootSecret)));
+}
+/**
+ * The same account id, from the root's **public** half.
+ *
+ * The form a root that cannot be exported needs. It is also the honest shape of
+ * the derivation: an account id is a function of the public key, and asking for
+ * the secret only ever meant "let me derive the public key first".
+ *
+ * @param rootPublicKey the root's ed25519 public key, 64 hex
+ */
+export async function accountForRootPublicKey(rootPublicKey) {
     return hex(await domainHash(ACCOUNT_ID_DOMAIN, [
-        concat(new Uint8Array([ACCOUNT_GENESIS_VERSION]), rootPublicKey),
+        concat(new Uint8Array([ACCOUNT_GENESIS_VERSION]), fromHex(rootPublicKey, 'rootPublicKey', 32)),
     ]));
 }

package/dist/device-cert/device-scope.d.ts

@@ -0,0 +1,58 @@
+import { type Signer } from '../signer/signer.js';
+/** What a root scopes one device to. */
+export interface DeviceScopeInput {
+    /**
+     * The account root's signing secret, 64 hex. Pass this or {@link signer}.
+     */
+    rootSecret?: string;
+    /**
+     * The account root as a {@link Signer} — for a root that cannot be exported.
+     * Its `publicKey` is the genesis key the proof carries, and the account is
+     * derived from it.
+     */
+    signer?: Signer;
+    /** The device being scoped, 64 hex — the one its certificate names. */
+    device: string;
+    /**
+     * Application ids the device may speak for, 64 hex each. **Empty means all of
+     * them**, which is also what the default is.
+     *
+     * A namespace binds the device only when its application is listed here (or
+     * the list is empty), so a scope naming the wrong application yields a relay
+     * refusal of `400`, not a binding.
+     */
+    applications?: readonly string[];
+    /**
+     * Orders scopes for this device: only a higher one supersedes. 0 for a
+     * device's first scope.
+     */
+    scopeEpoch?: number;
+}
+/**
+ * The 32 bytes a root signs to scope a device: `domain_hash` over account,
+ * device, `scope_epoch` (u32 LE), `key_epoch` (u32 LE), then each application id
+ * as its own length-prefixed part.
+ */
+export declare function deviceScopePayload(input: {
+    account: string;
+    device: string;
+    applications: readonly string[];
+    scopeEpoch: number;
+    keyEpoch: number;
+}): Promise<Uint8Array>;
+/**
+ * Scope a device, returning the hex `AccountProof<DeviceScope>` a relay's
+ * `linkAccountDevice` takes beside the credential.
+ *
+ * ```
+ * AccountProof { genesis: AccountGenesis, chain: Vec<RootKeyHandoff>, statement: DeviceScope }
+ *   AccountGenesis { version: u8, root_sign_pk: [u8; 32] }
+ *   chain          → u32-LE count (0 here)
+ *   DeviceScope    { account, device: [u8; 32] x2, applications: Vec<[u8; 32]>,
+ *                    scope_epoch: u32, key_epoch: u32, signature: [u8; 64] }
+ * ```
+ *
+ * `chain` is empty and `key_epoch` 0 for the reason they are in
+ * {@link signDeviceCert}: a root that was never handed off signs directly.
+ */
+export declare function signDeviceScope(input: DeviceScopeInput): Promise<string>;

package/dist/device-cert/device-scope.js

@@ -0,0 +1,76 @@
+/**
+ * Scoping a device offline: which applications a device of an account may speak
+ * for, signed by the account root.
+ *
+ * The certificate from {@link signDeviceCert} says *this key is a device of the
+ * account*. It does not say where: that is this statement, and a namespace binds
+ * a device only when both arrive together. A node that pairs a device signs the
+ * scope for you; an account with **no node** has to sign it itself, next to the
+ * certificate, and hand both to a relay's `linkAccountDevice`.
+ *
+ * Derived from core:
+ *
+ * - `DeviceScope` and `DeviceScope::signing_payload` — `crates/account/src/scope.rs`
+ * - `DEVICE_SCOPE_SIGN_DOMAIN`                       — `crates/account/src/domain.rs`
+ * - `AccountProof` / `AccountGenesis` borsh layout   — `crates/account/src/{signed,account}.rs`
+ *
+ * The unit tests pin vectors produced by core's own `DeviceScope::sign`.
+ */
+import { concat, domainHash, fromHex, hex, u32le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
+import { accountForRootPublicKey, ACCOUNT_GENESIS_VERSION } from './device-cert.js';
+const SCOPE_DOMAIN = new TextEncoder().encode('calimero.device.scope.v1');
+/**
+ * The 32 bytes a root signs to scope a device: `domain_hash` over account,
+ * device, `scope_epoch` (u32 LE), `key_epoch` (u32 LE), then each application id
+ * as its own length-prefixed part.
+ */
+export async function deviceScopePayload(input) {
+    return domainHash(SCOPE_DOMAIN, [
+        fromHex(input.account, 'account', 32),
+        fromHex(input.device, 'device', 32),
+        u32le(input.scopeEpoch),
+        u32le(input.keyEpoch),
+        ...input.applications.map((a, i) => fromHex(a, `applications[${i}]`, 32)),
+    ]);
+}
+/**
+ * Scope a device, returning the hex `AccountProof<DeviceScope>` a relay's
+ * `linkAccountDevice` takes beside the credential.
+ *
+ * ```
+ * AccountProof { genesis: AccountGenesis, chain: Vec<RootKeyHandoff>, statement: DeviceScope }
+ *   AccountGenesis { version: u8, root_sign_pk: [u8; 32] }
+ *   chain          → u32-LE count (0 here)
+ *   DeviceScope    { account, device: [u8; 32] x2, applications: Vec<[u8; 32]>,
+ *                    scope_epoch: u32, key_epoch: u32, signature: [u8; 64] }
+ * ```
+ *
+ * `chain` is empty and `key_epoch` 0 for the reason they are in
+ * {@link signDeviceCert}: a root that was never handed off signs directly.
+ */
+export async function signDeviceScope(input) {
+    const signer = await resolveSigner(input.rootSecret, input.signer, 'rootSecret');
+    const rootPublicKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
+    const account = await accountForRootPublicKey(hex(rootPublicKey));
+    const applications = input.applications ?? [];
+    const scopeEpoch = input.scopeEpoch ?? 0;
+    // `u32le` would wrap a negative or oversized value into a different epoch
+    // rather than refuse it, and the scope would then order itself wrongly.
+    if (!Number.isInteger(scopeEpoch) || scopeEpoch < 0 || scopeEpoch > 4294967295) {
+        throw new Error(`scopeEpoch must be a u32, got ${scopeEpoch}`);
+    }
+    const keyEpoch = 0;
+    const payload = await deviceScopePayload({
+        account,
+        device: input.device,
+        applications,
+        scopeEpoch,
+        keyEpoch,
+    });
+    const signature = await signer.sign(payload);
+    if (signature.length !== 64) {
+        throw new Error(`signer returned ${signature.length} bytes, expected a 64-byte Ed25519 signature`);
+    }
+    return hex(concat(new Uint8Array([ACCOUNT_GENESIS_VERSION]), rootPublicKey, u32le(0), fromHex(account, 'account', 32), fromHex(input.device, 'device', 32), u32le(applications.length), ...applications.map((a, i) => fromHex(a, `applications[${i}]`, 32)), u32le(scopeEpoch), u32le(keyEpoch), signature));
+}

package/dist/device-cert/index.d.ts

@@ -1,2 +1,4 @@
-export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, accountProofBytes, } from './device-cert.js';
-export type { DeviceCertInput } from './device-cert.js';
+export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, accountForRootPublicKey, accountProofBytes, parseDeviceCredential, verifyDeviceCredential, } from './device-cert.js';
+export type { DeviceCertInput, DeviceCredential } from './device-cert.js';
+export { signDeviceScope, deviceScopePayload } from './device-scope.js';
+export type { DeviceScopeInput } from './device-scope.js';

package/dist/device-cert/index.js

@@ -1,2 +1,3 @@
 // Offline device certification — the account-root half of the keyholder story.
-export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, accountProofBytes, } from './device-cert.js';
+export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, accountForRootPublicKey, accountProofBytes, parseDeviceCredential, verifyDeviceCredential, } from './device-cert.js';
+export { signDeviceScope, deviceScopePayload } from './device-scope.js';