@calimero-network/mero-js 22.7.0 → 22.8.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,25 @@
+import { type Signer } from '../signer/signer.js';
 /** 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 +106,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,7 +15,8 @@
  * - `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');
@@ -31,6 +32,8 @@ const DEVICE_ID_DOMAIN = new TextEncoder().encode('calimero.device.id.v1');
  * only the tag was stale.
  */
 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 +107,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 +121,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 +134,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/index.d.ts

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

package/dist/device-cert/index.js

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

package/dist/events/sse.d.ts

@@ -19,9 +19,22 @@ type SseEvent = SseEventData | GroupMembershipEventData | GroupMigrationEventDat
 type SseEventHandler = (event: SseEvent) => void;
 type SseConnectHandler = (sessionId: string) => void;
 type SseErrorHandler = (error: Error) => void;
+/**
+ * How one request to the SSE endpoints is authenticated.
+ *
+ * A bearer token is one value reused across requests; a request proof commits to
+ * the method, the path and the body, so it must be produced per request. Both
+ * reduce to the same thing from this client's point of view — headers — so the
+ * stream takes the general form and {@link SseClient} adapts `getAuthToken` to it.
+ */
+export type SseAuthorizer = (request: {
+    method: string;
+    path: string;
+    body?: string;
+}) => Promise<Record<string, string>>;
 export declare class SseClient {
     private baseUrl;
-    private getAuthToken;
+    private authorize;
     private reconnectDelayMs;
     private sessionId;
     private abortController;
@@ -33,7 +46,14 @@ export declare class SseClient {
     private fetchImpl;
     constructor(opts: {
         baseUrl: string;
-        getAuthToken: () => Promise<string>;
+        /** A bearer token provider. The historical form, and still the default. */
+        getAuthToken?: () => Promise<string>;
+        /**
+         * Per-request authorization, for a credential that commits to the request —
+         * a device cert signing a request proof. Takes precedence over
+         * `getAuthToken`; one of the two is required.
+         */
+        authorize?: SseAuthorizer;
         reconnectDelayMs?: number;
         fetch?: typeof fetch;
     });

package/dist/events/sse.js

@@ -42,7 +42,16 @@ export class SseClient {
         this.closed = false;
         this.listeners = { connect: [], event: [], error: [] };
         this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
-        this.getAuthToken = opts.getAuthToken;
+        if (opts.authorize) {
+            this.authorize = opts.authorize;
+        }
+        else if (opts.getAuthToken) {
+            const getAuthToken = opts.getAuthToken;
+            this.authorize = async () => ({ Authorization: `Bearer ${await getAuthToken()}` });
+        }
+        else {
+            throw new Error('SseClient needs either `getAuthToken` or `authorize`');
+        }
         this.reconnectDelayMs = opts.reconnectDelayMs ?? 3000;
         // globalThis.fetch must be called as a method on globalThis, not through a
         // variable, or browsers throw "Illegal invocation".
@@ -123,11 +132,10 @@ export class SseClient {
         this.closed = false;
         this.abortController = new AbortController();
         try {
-            const token = await this.getAuthToken();
             const url = `${this.baseUrl}/sse`;
             const response = await this.fetchImpl(url, {
                 headers: {
-                    'Authorization': `Bearer ${token}`,
+                    ...(await this.authorize({ method: 'GET', path: new URL(url).pathname })),
                     'Accept': 'text/event-stream',
                 },
                 signal: this.abortController.signal,
@@ -297,23 +305,24 @@ export class SseClient {
     }
     async sendSubscription(method, ids) {
         try {
-            const token = await this.getAuthToken();
             const params = {};
             if (ids.contextIds && ids.contextIds.length > 0)
                 params.contextIds = ids.contextIds;
             if (ids.groupIds && ids.groupIds.length > 0)
                 params.groupIds = ids.groupIds;
-            const response = await this.fetchImpl(`${this.baseUrl}/sse/subscription`, {
+            const url = `${this.baseUrl}/sse/subscription`;
+            // Serialized once and both signed and sent, because a proof commits to the
+            // body: re-stringifying for the signature risks two byte sequences that
+            // differ in key order, which fails as a refused credential rather than as
+            // anything that names the real cause.
+            const body = JSON.stringify({ id: this.sessionId, method, params });
+            const response = await this.fetchImpl(url, {
                 method: 'POST',
                 headers: {
-                    'Authorization': `Bearer ${token}`,
+                    ...(await this.authorize({ method: 'POST', path: new URL(url).pathname, body })),
                     'Content-Type': 'application/json',
                 },
-                body: JSON.stringify({
-                    id: this.sessionId,
-                    method,
-                    params,
-                }),
+                body,
             });
             if (!response.ok) {
                 // The subscribe path used to report only the status. On the one failure

package/dist/http-client/http-types.d.ts

@@ -4,6 +4,24 @@ export interface Transport {
     baseUrl: string;
     defaultHeaders?: Record<string, string>;
     getAuthToken?: () => Promise<string | undefined>;
+    /**
+     * Per-request authorization, for a credential that commits to the request.
+     *
+     * `getAuthToken` returns one value reused across requests; a request proof
+     * signs the method, the path and the body, so it can only be produced where
+     * those are known. This is called with exactly that, and whatever it returns
+     * is merged into the headers.
+     *
+     * It runs AFTER `getAuthToken`, so a transport holding both sends both and
+     * lets the node decide — which it does by answering a request carrying a token
+     * by that token, and consulting a proof only when there is none.
+     */
+    authorizeRequest?: (request: {
+        method: string;
+        /** The path the node will see, query excluded. */
+        path: string;
+        body?: string | Uint8Array;
+    }) => Promise<Record<string, string>>;
     /**
      * Sign each request instead of, or alongside, presenting a session.
      *

package/dist/http-client/web-client.js

@@ -193,8 +193,28 @@ export class WebHttpClient {
         else {
             headersObj = headers;
         }
+        const method = init?.method || 'GET';
+        // A credential that commits to the request can only be produced here, where
+        // the method, the assembled path and the body are all known. The path comes
+        // from the URL rather than from `path`, because a base URL may carry a prefix
+        // (`…/admin-api`) that the node sees and a bare relative path would not sign.
+        if (this.transport.authorizeRequest) {
+            const body = init?.body;
+            if (body !== undefined && typeof body !== 'string' && !(body instanceof Uint8Array)) {
+                throw new Error('this transport authorizes each request against its body, so the body must be a string ' +
+                    'or Uint8Array — a stream cannot be signed, because the signature would have to read ' +
+                    'bytes the request then cannot send.');
+            }
+            Object.assign(headersObj, await this.transport.authorizeRequest({
+                method,
+                path: new URL(url).pathname,
+                // Narrowed by the guard above; `BodyInit` is wider than what can be
+                // signed.
+                body: body,
+            }));
+        }
         const requestInit = {
-            method: init?.method || 'GET',
+            method,
             headers: headersObj,
         };
         // Check if body is a stream (ReadableStream) that can't be reused