@calimero-network/mero-js 19.15.0 → 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

@@ -1 +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

@@ -1 +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/package.json

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