@macula-io/ts 0.20.0 → 0.21.0

package/README.md

@@ -162,6 +162,7 @@ a Promise; events, served calls and served streams reach JavaScript through a
 | Streams (`openStream`, `serveStream`) | ✅ | ✅ | Server, client and bidi; a QUIC stream per session, released on every path |
 | Publish/subscribe | ✅ | ✅ | Signed publications, delivered once across links |
 | DHT (`findRecord`, `findRecords`, `findRecordsByType`, `putRecord`) | ✅ | — | Records verified before they are handed on |
+| Realm proof v2 (`NodeKey.deviceRequestProof`) | ✅ | — | macula-realm#29: a join session over HTTP (`"http"`, the realm's JSON rule) or a membership UCAN over the mesh (`"mesh"`), with its device_info and ttl_seconds, the realm and the procedure signed, and a nonce; the realm's own vector reproduced through macula-go's encoder |
 | Node-served content (`shareContent`, `unshareContent`, `getContent`) | ✅ | ✅ | macula 12.6.0 (D27): shared on the node's own `~<node_id>/content_v1` and announced; a fetch checks the block, the manifest and every chunk against the content id, bounded, with no realm key; `NotSharedError` / `ContentUnavailableError` |
 
 ## Not yet implemented

package/dist/binding.d.ts

@@ -17,6 +17,8 @@ export declare const native: {
     keyPublicKey(key: Handle): Uint8Array;
     keyProfile(key: Handle): string;
     keySign(key: Handle, data: Uint8Array): Promise<Uint8Array>;
+    keyDeviceRequestProof(key: Handle, realm: Uint8Array, procedure: string, requestJson: string, rule: number): Promise<string>;
+    deviceRequestMessage(publicKey: Uint8Array, realm: Uint8Array, procedure: string, timestampMs: number, nonce: Uint8Array, requestJson: string, rule: number): Uint8Array;
     keyFree(key: Handle): void;
     verify(data: Uint8Array, signature: Uint8Array, publicKey: Uint8Array, profile: string): boolean;
     poolConnect(key: Handle, seedsJson: string, optionsJson: string): Promise<Handle>;

package/dist/binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,oEAAoE;AACpE,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,yBAAyB;AACzB,EAAE;AACF,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAgBrE,8DAA8D;AAC9D,MAAM,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAgDvD,CAAC"}
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,oEAAoE;AACpE,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,yBAAyB;AACzB,EAAE;AACF,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAgBrE,8DAA8D;AAC9D,MAAM,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAmDvD,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { NodeKey, type Profile } from "./key.js";
+export { NodeKey, JOIN_SESSION_PROCEDURE, MEMBERSHIP_UCAN_PROCEDURE, type Profile, type DeviceRequestRule, type DeviceRequestProof, } from "./key.js";
 export { Pool, Subscription, Served, RecordType, type Seed, type PoolOptions, type LinkStatus, type Provider, type Event, type Request, type DhtRecord, } from "./pool.js";
 export { NotSharedError, ContentUnavailableError, DEFAULT_CONTENT_TIMEOUT_MS, type ContentOptions, type Mcid, } from "./content.js";
 export { Stream, StreamMode, type StreamEvent, type StreamRequest } from "./stream.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 // @macula-io/ts: the macula 12 mesh from TypeScript, over macula-go.
-export { NodeKey } from "./key.js";
+export { NodeKey, JOIN_SESSION_PROCEDURE, MEMBERSHIP_UCAN_PROCEDURE, } from "./key.js";
 export { Pool, Subscription, Served, RecordType, } from "./pool.js";
 export { NotSharedError, ContentUnavailableError, DEFAULT_CONTENT_TIMEOUT_MS, } from "./content.js";
 export { Stream, StreamMode } from "./stream.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,EAAE,OAAO,EAAgB,MAAM,UAAU,CAAC;AACjD,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,UAAU,GAQX,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,0BAA0B,GAG3B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAwC,MAAM,aAAa,CAAC;AACvF,OAAO,EACL,aAAa,EACb,UAAU,EACV,WAAW,EACX,uBAAuB,GAIxB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,EACL,OAAO,EACP,sBAAsB,EACtB,yBAAyB,GAI1B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,UAAU,GAQX,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,0BAA0B,GAG3B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAwC,MAAM,aAAa,CAAC;AACvF,OAAO,EACL,aAAa,EACb,UAAU,EACV,WAAW,EACX,uBAAuB,GAIxB,MAAM,WAAW,CAAC"}

package/dist/key.d.ts

@@ -1,6 +1,25 @@
 import { type Handle } from "./binding.js";
+import { type Id, type JsonValue } from "./wire.js";
 /** A crypto profile: "pq_hybrid" (the fleet's) or "pq_pure". */
 export type Profile = "pq_hybrid" | "pq_pure";
+/**
+ * How a device request is signed (realm proof v2, macula-realm#29): "http" is a
+ * join-session body under the realm's JSON rule (an integral number is an
+ * integer, a boolean or an integer beyond 2^53 - 1 is refused); "mesh" is a
+ * call's payload as this library puts it on the wire.
+ */
+export type DeviceRequestRule = "http" | "mesh";
+/** The procedure a join session over HTTP is signed for. */
+export declare const JOIN_SESSION_PROCEDURE = "macula_realm.join_session";
+/** The procedure a membership UCAN asked for over the mesh is signed for. */
+export declare const MEMBERSHIP_UCAN_PROCEDURE = "macula_realm.membership_ucan";
+/** A realm proof v2, as it goes on the wire beside the request's public_key. */
+export interface DeviceRequestProof {
+    v: 2;
+    timestamp: number;
+    nonce: string;
+    signature: string;
+}
 export declare class NodeKey {
     private handle;
     private constructor();
@@ -24,6 +43,20 @@ export declare class NodeKey {
     profile(): Profile;
     /** Signs data as given. */
     sign(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * A realm proof v2 (macula-realm#29) that this key made request (every field
+     * of it except "proof") for procedure in realm, now and with a fresh nonce.
+     * The request's device_info and ttl_seconds, the realm and the procedure are
+     * all signed, so the realm refuses a request changed on the way.
+     */
+    deviceRequestProof(realm: Id, procedure: string, request: {
+        [field: string]: JsonValue;
+    }, rule: DeviceRequestRule): Promise<DeviceRequestProof>;
+    /** The exact bytes a realm proof v2 signs, for a given timestamp and 16-byte
+     * nonce: what the realm's vector is checked against. */
+    static deviceRequestMessage(publicKey: Uint8Array, realm: Id, procedure: string, timestampMs: number, nonce: Uint8Array, request: {
+        [field: string]: JsonValue;
+    }, rule: DeviceRequestRule): Uint8Array;
     /** Whether signature is valid over data for a public key as carried on the
      * wire (publicKey()), under profile: ML-DSA-87 in pq_pure, and in pq_hybrid
      * the LAMPS composite id-MLDSA87-RSA4096-PSS-SHA512 with the empty context,

package/dist/key.js

@@ -4,7 +4,12 @@
 // owner only.
 import { access } from "node:fs/promises";
 import { native } from "./binding.js";
-import { hex } from "./wire.js";
+import { hex, id32 } from "./wire.js";
+/** The procedure a join session over HTTP is signed for. */
+export const JOIN_SESSION_PROCEDURE = "macula_realm.join_session";
+/** The procedure a membership UCAN asked for over the mesh is signed for. */
+export const MEMBERSHIP_UCAN_PROCEDURE = "macula_realm.membership_ucan";
+const ruleNumber = (rule) => (rule === "http" ? 0 : 1);
 export class NodeKey {
     handle;
     constructor(handle) {
@@ -56,6 +61,21 @@ export class NodeKey {
     async sign(data) {
         return native.keySign(this.live(), data);
     }
+    /**
+     * A realm proof v2 (macula-realm#29) that this key made request (every field
+     * of it except "proof") for procedure in realm, now and with a fresh nonce.
+     * The request's device_info and ttl_seconds, the realm and the procedure are
+     * all signed, so the realm refuses a request changed on the way.
+     */
+    async deviceRequestProof(realm, procedure, request, rule) {
+        const proof = await native.keyDeviceRequestProof(this.live(), id32(realm, "realm"), procedure, JSON.stringify(request), ruleNumber(rule));
+        return JSON.parse(proof);
+    }
+    /** The exact bytes a realm proof v2 signs, for a given timestamp and 16-byte
+     * nonce: what the realm's vector is checked against. */
+    static deviceRequestMessage(publicKey, realm, procedure, timestampMs, nonce, request, rule) {
+        return native.deviceRequestMessage(publicKey, id32(realm, "realm"), procedure, timestampMs, nonce, JSON.stringify(request), ruleNumber(rule));
+    }
     /** Whether signature is valid over data for a public key as carried on the
      * wire (publicKey()), under profile: ML-DSA-87 in pq_pure, and in pq_hybrid
      * the LAMPS composite id-MLDSA87-RSA4096-PSS-SHA512 with the empty context,

package/dist/key.js.map

@@ -1 +1 @@
-{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macula-io/ts",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "TypeScript SDK for the Macula mesh (FFI over macula-go)",
   "license": "Apache-2.0",
   "keywords": [