@calimero-network/mero-js 19.14.1 → 19.16.0

package/dist/request/caller-proof.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Assemble the credential a node reads from `X-Calimero-Proof`.
+ *
+ * A request-carried proof is three links, and the node needs all of them in one
+ * header: the account root certified the device, the device (optionally)
+ * certified a short-lived session key, and that key signed THIS request. Each
+ * link is minted by its own function here — {@link signDeviceCert},
+ * {@link signLoginStatement}, {@link signRequest} — and each already returns
+ * the borsh encoding of the Rust type the node deserializes. Rust's
+ * `CallerProof` is a plain struct of those three fields, and borsh writes a
+ * struct as its fields back to back, so assembling the header is concatenation
+ * rather than a fourth encoder.
+ *
+ * That is worth stating because it is load-bearing and it is not obvious: if it
+ * were re-encoded here there would be a second spelling of a signed structure,
+ * able to disagree with the one that was signed. `caller-proof.test.ts` pins the
+ * concatenation against bytes produced by core itself.
+ */
+/** The three links, each already hex-encoded by the function that signed it. */
+export interface CallerProofInput {
+    /**
+     * `signDeviceCert(...)` — the account root's certificate over the device key,
+     * with the genesis that names the account.
+     */
+    credential: string;
+    /**
+     * `signLoginStatement(...)`, when signing with a session key.
+     *
+     * Omit it on the two-link chain, where the device key signs the request
+     * itself. Omitting is not the same as passing an empty string: borsh writes
+     * `Option` as a tag byte, so the two produce different bytes and only one of
+     * them parses.
+     */
+    session?: string;
+    /** `signRequest(...)` — the signature over this exact method, path and body. */
+    request: string;
+}
+/**
+ * Concatenate the three links into the header value.
+ *
+ * Returns hex, ready to present as `X-Calimero-Proof`.
+ */
+export declare function callerProof(input: CallerProofInput): string;

package/dist/request/caller-proof.js

@@ -0,0 +1,36 @@
+/**
+ * Assemble the credential a node reads from `X-Calimero-Proof`.
+ *
+ * A request-carried proof is three links, and the node needs all of them in one
+ * header: the account root certified the device, the device (optionally)
+ * certified a short-lived session key, and that key signed THIS request. Each
+ * link is minted by its own function here — {@link signDeviceCert},
+ * {@link signLoginStatement}, {@link signRequest} — and each already returns
+ * the borsh encoding of the Rust type the node deserializes. Rust's
+ * `CallerProof` is a plain struct of those three fields, and borsh writes a
+ * struct as its fields back to back, so assembling the header is concatenation
+ * rather than a fourth encoder.
+ *
+ * That is worth stating because it is load-bearing and it is not obvious: if it
+ * were re-encoded here there would be a second spelling of a signed structure,
+ * able to disagree with the one that was signed. `caller-proof.test.ts` pins the
+ * concatenation against bytes produced by core itself.
+ */
+import { fromHexUnsized, hex, concat } from "../crypto/internal.js";
+/**
+ * Concatenate the three links into the header value.
+ *
+ * Returns hex, ready to present as `X-Calimero-Proof`.
+ */
+export function callerProof(input) {
+    const credential = fromHexUnsized(input.credential, "credential");
+    const request = fromHexUnsized(input.request, "request signature");
+    // Borsh `Option<T>`: a single tag byte, then the value when present. A
+    // two-link chain is `None`, not an empty `Some` — the node reads the tag
+    // before anything else, so getting it backwards fails to parse rather than
+    // failing to verify, which at least is loud.
+    const session = input.session === undefined
+        ? new Uint8Array([0])
+        : concat(new Uint8Array([1]), fromHexUnsized(input.session, "session statement"));
+    return hex(concat(credential, session, request));
+}

package/dist/request/index.d.ts

@@ -0,0 +1,3 @@
+export { requestBodyHash, signRequest, type RequestSigInput, } from "./request-sig.js";
+export { callerProof, type CallerProofInput } from "./caller-proof.js";
+export { createProofSigner, type ProofRequest, type ProofSignerOptions, } from "./proof-signer.js";

package/dist/request/index.js

@@ -0,0 +1,3 @@
+export { requestBodyHash, signRequest, } from "./request-sig.js";
+export { callerProof } from "./caller-proof.js";
+export { createProofSigner, } from "./proof-signer.js";

package/dist/request/proof-signer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Turn a device key into something the HTTP client can call per request.
+ *
+ * A session is a bearer token: mint once, present many times. A request-carried
+ * proof is the opposite — it commits to one method, one path and one body, so
+ * it has to be produced at the moment of the call, by something holding the
+ * signing key. This is that something, shaped like `getAuthToken` so the key
+ * stays with the caller and never reaches the transport.
+ */
+/** What the transport knows about the call it is about to make. */
+export interface ProofRequest {
+    /** `GET`, `POST`, … exactly as it will be sent. */
+    method: string;
+    /** The URL path the node will see, **without** the query string. */
+    path: string;
+    /** The exact bytes that will be sent, if any. */
+    body?: unknown;
+}
+export interface ProofSignerOptions {
+    /** `signDeviceCert(...)`, hex. */
+    credential: string;
+    /**
+     * `signLoginStatement(...)`, hex — the three-link chain.
+     *
+     * Omit for the two-link chain, where `signerSecret` is the device key itself.
+     */
+    session?: string;
+    /**
+     * The ed25519 secret that signs each request, hex: the session key when
+     * `session` is set, otherwise the device key.
+     */
+    signerSecret: string;
+    /**
+     * How long each signature stays valid. Seconds, default 120.
+     *
+     * This is what bounds replay and nothing else does, so it is deliberately
+     * short and deliberately not configurable to "never". A clock skew allowance
+     * lives on the node; this only has to outlive the flight time.
+     */
+    ttlSeconds?: number;
+    /** Unix seconds. Injectable so a test does not depend on the wall clock. */
+    now?: () => number;
+}
+/**
+ * Build the `X-Calimero-Proof` value for one request.
+ *
+ * Pass the result to the HTTP client's `getProof`.
+ */
+export declare function createProofSigner(options: ProofSignerOptions): (request: ProofRequest) => Promise<string>;

package/dist/request/proof-signer.js

@@ -0,0 +1,59 @@
+/**
+ * Turn a device key into something the HTTP client can call per request.
+ *
+ * A session is a bearer token: mint once, present many times. A request-carried
+ * proof is the opposite — it commits to one method, one path and one body, so
+ * it has to be produced at the moment of the call, by something holding the
+ * signing key. This is that something, shaped like `getAuthToken` so the key
+ * stays with the caller and never reaches the transport.
+ */
+import { callerProof } from "./caller-proof.js";
+import { signRequest } from "./request-sig.js";
+/**
+ * The bytes a body will actually be sent as.
+ *
+ * Refuses what it cannot hash without consuming or re-encoding. A stream can be
+ * read once, and reading it here would send an empty body; `FormData` and
+ * `URLSearchParams` are serialized by `fetch` in ways this cannot reproduce
+ * byte for byte. Signing a guess would produce a signature over bytes that
+ * never travelled, and the node would reject it with a signature error that
+ * says nothing about the real cause — so this throws, naming the type.
+ */
+function bodyBytes(body) {
+    if (body === undefined || body === null)
+        return new Uint8Array(0);
+    if (typeof body === "string")
+        return body;
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    if (ArrayBuffer.isView(body)) {
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    }
+    throw new Error(`a request-carried proof cannot commit to a ${body?.constructor?.name ?? typeof body} body: pass a string or bytes, or use a session for this call`);
+}
+/**
+ * Build the `X-Calimero-Proof` value for one request.
+ *
+ * Pass the result to the HTTP client's `getProof`.
+ */
+export function createProofSigner(options) {
+    const ttl = options.ttlSeconds ?? 120;
+    const clock = options.now ?? (() => Math.floor(Date.now() / 1000));
+    return async (request) => {
+        const issuedAt = clock();
+        return callerProof({
+            credential: options.credential,
+            session: options.session,
+            request: await signRequest({
+                method: request.method,
+                path: request.path,
+                body: bodyBytes(request.body),
+                issuedAt,
+                expiresAt: issuedAt + ttl,
+                signerSecret: options.signerSecret,
+            }),
+        });
+    };
+}

package/dist/request/request-sig.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Sign one HTTP request, so a caller's identity travels with it.
+ *
+ * This is the bottom link of the chain a delegated client presents. A session
+ * has the node mint and remember something; this has the caller prove itself on
+ * every call, so the node holds no session state and the same path works
+ * whether or not the node runs a login provider at all.
+ *
+ * ```text
+ * account root ──signs──▶ DeviceCert       cold, once, offline
+ * device key   ──signs──▶ LoginStatement   once per session, hours
+ * session key  ──signs──▶ RequestSig       per call   ◀── this module
+ * ```
+ *
+ * **The middle link is optional.** A CLI or a server-side job signs with its
+ * device key directly and presents two links; a browser keeping the device key
+ * behind a hardware or extension boundary mints a session key and presents
+ * three. The node's verifier handles both, so which you produce here is a
+ * question about where your key lives, not about what the node accepts.
+ *
+ * **What it binds.** Method, path and a hash of the body. A signature for
+ * `GET /a` is not a signature for `POST /a`, for `GET /b`, or for the same call
+ * with different arguments.
+ *
+ * **The path excludes the query string**, deliberately: a proxy may legitimately
+ * rewrite it — a token parameter most of all — and signing over bytes something
+ * else is entitled to change means failing for reasons the caller cannot see.
+ * Anything that must be bound belongs in the body.
+ *
+ * **The method is not normalized.** `HEAD` and `GET` are the same *permission*
+ * and the node's permission layer folds them, but they are different requests.
+ * Sign the method you are about to send.
+ *
+ * **Replay inside the window performs the identical request** and is bounded
+ * rather than prevented — keep `expiresAt` short. A warrant, which authorizes a
+ * change with lasting effect, carries a nonce ledger for this; a request
+ * signature does not.
+ *
+ * **The byte contract is pinned in core**, at
+ * `crates/account/src/tests/request_wire_fixture.rs`, for the same reason the
+ * warrant and login ones are: the domains are `pub(crate)` there and the field
+ * order is implicit in a `derive`, so nothing on that side forces anyone to
+ * notice this file depends on both. This module's test asserts the same vectors.
+ */
+import { fromHex } from "../crypto/internal.js";
+/**
+ * Commit to a request body.
+ *
+ * Always call it, including for a body-less request: an empty body hashes to a
+ * value like any other, and there is no "absent body" encoding for a verifier
+ * to disagree with you about.
+ */
+export declare function requestBodyHash(body?: Uint8Array | string): Promise<Uint8Array>;
+/** What a caller is about to send. */
+export interface RequestSigInput {
+    /**
+     * The HTTP method, exactly as it will appear on the wire — `GET`, `POST`,
+     * `HEAD`. Not folded: see the module note.
+     */
+    method: string;
+    /**
+     * The path, **without** the query string. `/admin-api/namespaces`, not
+     * `/admin-api/namespaces?token=…`.
+     */
+    path: string;
+    /**
+     * The request body, or nothing. Pass exactly the bytes you will send: the
+     * signature commits to their hash, so a body re-serialized between signing
+     * and sending is a signature for a different request.
+     */
+    body?: Uint8Array | string;
+    /** Unix seconds at signing. */
+    issuedAt: number | bigint;
+    /**
+     * Unix seconds after which the node must refuse it.
+     *
+     * Keep it short — minutes, not hours. It is what bounds replay, and nothing
+     * else does.
+     */
+    expiresAt: number | bigint;
+    /**
+     * The ed25519 signing secret, hex (32 bytes): the session key on the
+     * three-link chain, the device key on the two-link one.
+     *
+     * Never sent anywhere. It signs locally and only the signature travels.
+     */
+    signerSecret: string;
+}
+/**
+ * Sign one request and return it hex-encoded, ready to present.
+ *
+ * Returns the encoding rather than an object for the reason `signWarrant` and
+ * `signLoginStatement` do: the signature covers exactly these bytes, and a
+ * caller that rebuilt the fields from JSON would have a second spelling able to
+ * disagree with what was signed.
+ */
+export declare function signRequest(input: RequestSigInput): Promise<string>;
+/** Re-exported so a caller can check a hex signer key before signing with it. */
+export { fromHex };

package/dist/request/request-sig.js

@@ -0,0 +1,96 @@
+/**
+ * Sign one HTTP request, so a caller's identity travels with it.
+ *
+ * This is the bottom link of the chain a delegated client presents. A session
+ * has the node mint and remember something; this has the caller prove itself on
+ * every call, so the node holds no session state and the same path works
+ * whether or not the node runs a login provider at all.
+ *
+ * ```text
+ * account root ──signs──▶ DeviceCert       cold, once, offline
+ * device key   ──signs──▶ LoginStatement   once per session, hours
+ * session key  ──signs──▶ RequestSig       per call   ◀── this module
+ * ```
+ *
+ * **The middle link is optional.** A CLI or a server-side job signs with its
+ * device key directly and presents two links; a browser keeping the device key
+ * behind a hardware or extension boundary mints a session key and presents
+ * three. The node's verifier handles both, so which you produce here is a
+ * question about where your key lives, not about what the node accepts.
+ *
+ * **What it binds.** Method, path and a hash of the body. A signature for
+ * `GET /a` is not a signature for `POST /a`, for `GET /b`, or for the same call
+ * with different arguments.
+ *
+ * **The path excludes the query string**, deliberately: a proxy may legitimately
+ * rewrite it — a token parameter most of all — and signing over bytes something
+ * else is entitled to change means failing for reasons the caller cannot see.
+ * Anything that must be bound belongs in the body.
+ *
+ * **The method is not normalized.** `HEAD` and `GET` are the same *permission*
+ * and the node's permission layer folds them, but they are different requests.
+ * Sign the method you are about to send.
+ *
+ * **Replay inside the window performs the identical request** and is bounded
+ * rather than prevented — keep `expiresAt` short. A warrant, which authorizes a
+ * change with lasting effect, carries a nonce ledger for this; a request
+ * signature does not.
+ *
+ * **The byte contract is pinned in core**, at
+ * `crates/account/src/tests/request_wire_fixture.rs`, for the same reason the
+ * warrant and login ones are: the domains are `pub(crate)` there and the field
+ * order is implicit in a `derive`, so nothing on that side forces anyone to
+ * notice this file depends on both. This module's test asserts the same vectors.
+ */
+import { concat, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from "../crypto/internal.js";
+const SIGN_DOMAIN = new TextEncoder().encode("calimero.auth.request.v1");
+/**
+ * Its own domain, distinct from the signing one.
+ *
+ * The two are different jobs on the same bytes: this produces the commitment,
+ * the other signs over it. Sharing a domain would make the commitment a
+ * truncated disclosure of bytes something signs.
+ */
+const BODY_DOMAIN = new TextEncoder().encode("calimero.auth.request.body.v1");
+/** A borsh `String`: its own `u32` little-endian length, then the UTF-8. */
+function borshString(value) {
+    const bytes = new TextEncoder().encode(value);
+    return concat(u32le(bytes.length), bytes);
+}
+/**
+ * Commit to a request body.
+ *
+ * Always call it, including for a body-less request: an empty body hashes to a
+ * value like any other, and there is no "absent body" encoding for a verifier
+ * to disagree with you about.
+ */
+export async function requestBodyHash(body = new Uint8Array(0)) {
+    const bytes = typeof body === "string" ? new TextEncoder().encode(body) : body;
+    return domainHash(BODY_DOMAIN, [bytes]);
+}
+/**
+ * Sign one request and return it hex-encoded, ready to present.
+ *
+ * Returns the encoding rather than an object for the reason `signWarrant` and
+ * `signLoginStatement` do: the signature covers exactly these bytes, and a
+ * caller that rebuilt the fields from JSON would have a second spelling able to
+ * disagree with what was signed.
+ */
+export async function signRequest(input) {
+    const key = await importSigningKey(input.signerSecret);
+    const bodyHash = await requestBodyHash(input.body);
+    const issuedAt = u64le(input.issuedAt);
+    const expiresAt = u64le(input.expiresAt);
+    const encoder = new TextEncoder();
+    const preimage = await domainHash(SIGN_DOMAIN, [
+        encoder.encode(input.method),
+        encoder.encode(input.path),
+        bodyHash,
+        issuedAt,
+        expiresAt,
+    ]);
+    const signature = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, key, preimage));
+    return hex(concat(borshString(input.method), borshString(input.path), bodyHash, issuedAt, expiresAt, signature));
+}
+/** Re-exported so a caller can check a hex signer key before signing with it. */
+export { fromHex };

package/package.json

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