wire-mesh-core 1.3.0 → 1.5.0

package/dist/domain/room-path.cjs

@@ -0,0 +1,58 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/domain/room-path.ts
+/**
+* Room paths — the naming and parsing convention core/room's device-keyed membership uses, mirroring spec/room.cddl's own owner-named-room-path/dm-room-path grammar exactly: an owner-named room is `<owner-hex>/<local-name>`, trust rooted at the owner named in the path; a DM is the bytewise-ascending sorted pair `<lower-hex>+<higher-hex>`, trust rooted at the verifier itself rather than either named party (see room.cddl's own comments for why that asymmetry is load-bearing, not incidental).
+*/
+const DEVICE_ID_HEX_PATTERN = /^[0-9a-f]{64}$/;
+const LOCAL_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+const SLUG_INVALID_RUN = /[^A-Za-z0-9_-]+/g;
+function assertDeviceIdHex(value, label) {
+	if (!DEVICE_ID_HEX_PATTERN.test(value)) throw new Error(`expected ${label} to be a 64-character lowercase hex device-id, got ${JSON.stringify(value)}`);
+}
+/** `<owner-hex>/<local-name>`. localName must already satisfy [A-Za-z0-9_-]+ -- run an untrusted name through slugRoomName first. */
+function ownerNamedRoomPath(owner, localName) {
+	assertDeviceIdHex(owner, "owner");
+	if (!LOCAL_NAME_PATTERN.test(localName)) throw new Error(`expected localName to match [A-Za-z0-9_-]+, got ${JSON.stringify(localName)}`);
+	return `${owner}/${localName}`;
+}
+/** `<lower-hex>+<higher-hex>`, the bytewise-ascending sorted pair. Refuses a==b outright: a path naming the same device twice is not a valid DM path at all, and a self-DM is a purely local concept a consumer models its own way, needing no path. */
+function dmRoomPath(a, b) {
+	assertDeviceIdHex(a, "a");
+	assertDeviceIdHex(b, "b");
+	if (a === b) throw new Error(`a DM room path cannot name the same device twice (${a})`);
+	return a < b ? `${a}+${b}` : `${b}+${a}`;
+}
+/** Parses a room-path back into its owner-named or DM shape. Throws on anything matching neither -- there is no third path shape. */
+function parseRoomPath(path) {
+	const slashIndex = path.indexOf("/");
+	if (slashIndex !== -1) {
+		const owner = path.slice(0, slashIndex);
+		const localName = path.slice(slashIndex + 1);
+		if (DEVICE_ID_HEX_PATTERN.test(owner) && LOCAL_NAME_PATTERN.test(localName)) return {
+			kind: "owner-named",
+			owner,
+			localName
+		};
+	}
+	const plusIndex = path.indexOf("+");
+	if (plusIndex !== -1) {
+		const first = path.slice(0, plusIndex);
+		const second = path.slice(plusIndex + 1);
+		if (DEVICE_ID_HEX_PATTERN.test(first) && DEVICE_ID_HEX_PATTERN.test(second) && first !== second) return {
+			kind: "dm",
+			participants: [first, second]
+		};
+	}
+	throw new Error(`${JSON.stringify(path)} is not a valid room-path`);
+}
+/** Sanitises an arbitrary name (e.g. a directory basename) into a valid room-path localName by replacing every run of characters outside [A-Za-z0-9_-] with a single hyphen. Throws if nothing valid remains. */
+function slugRoomName(name) {
+	const slug = name.replace(SLUG_INVALID_RUN, "-").replace(/^-+|-+$/g, "");
+	if (slug.length === 0) throw new Error(`${JSON.stringify(name)} has no valid room-name characters to slug`);
+	return slug;
+}
+//#endregion
+exports.dmRoomPath = dmRoomPath;
+exports.ownerNamedRoomPath = ownerNamedRoomPath;
+exports.parseRoomPath = parseRoomPath;
+exports.slugRoomName = slugRoomName;

package/dist/domain/room-path.d.cts

@@ -0,0 +1,21 @@
+//#region src/domain/room-path.d.ts
+/**
+ * Room paths — the naming and parsing convention core/room's device-keyed membership uses, mirroring spec/room.cddl's own owner-named-room-path/dm-room-path grammar exactly: an owner-named room is `<owner-hex>/<local-name>`, trust rooted at the owner named in the path; a DM is the bytewise-ascending sorted pair `<lower-hex>+<higher-hex>`, trust rooted at the verifier itself rather than either named party (see room.cddl's own comments for why that asymmetry is load-bearing, not incidental).
+ */
+/** `<owner-hex>/<local-name>`. localName must already satisfy [A-Za-z0-9_-]+ -- run an untrusted name through slugRoomName first. */
+export declare function ownerNamedRoomPath(owner: string, localName: string): string;
+/** `<lower-hex>+<higher-hex>`, the bytewise-ascending sorted pair. Refuses a==b outright: a path naming the same device twice is not a valid DM path at all, and a self-DM is a purely local concept a consumer models its own way, needing no path. */
+export declare function dmRoomPath(a: string, b: string): string;
+export type ParsedRoomPath = {
+  kind: "owner-named";
+  owner: string;
+  localName: string;
+} | {
+  kind: "dm";
+  participants: [string, string];
+};
+/** Parses a room-path back into its owner-named or DM shape. Throws on anything matching neither -- there is no third path shape. */
+export declare function parseRoomPath(path: string): ParsedRoomPath;
+/** Sanitises an arbitrary name (e.g. a directory basename) into a valid room-path localName by replacing every run of characters outside [A-Za-z0-9_-] with a single hyphen. Throws if nothing valid remains. */
+export declare function slugRoomName(name: string): string;
+//#endregion

package/dist/domain/room-path.d.mts

@@ -0,0 +1,21 @@
+//#region src/domain/room-path.d.ts
+/**
+ * Room paths — the naming and parsing convention core/room's device-keyed membership uses, mirroring spec/room.cddl's own owner-named-room-path/dm-room-path grammar exactly: an owner-named room is `<owner-hex>/<local-name>`, trust rooted at the owner named in the path; a DM is the bytewise-ascending sorted pair `<lower-hex>+<higher-hex>`, trust rooted at the verifier itself rather than either named party (see room.cddl's own comments for why that asymmetry is load-bearing, not incidental).
+ */
+/** `<owner-hex>/<local-name>`. localName must already satisfy [A-Za-z0-9_-]+ -- run an untrusted name through slugRoomName first. */
+export declare function ownerNamedRoomPath(owner: string, localName: string): string;
+/** `<lower-hex>+<higher-hex>`, the bytewise-ascending sorted pair. Refuses a==b outright: a path naming the same device twice is not a valid DM path at all, and a self-DM is a purely local concept a consumer models its own way, needing no path. */
+export declare function dmRoomPath(a: string, b: string): string;
+export type ParsedRoomPath = {
+  kind: "owner-named";
+  owner: string;
+  localName: string;
+} | {
+  kind: "dm";
+  participants: [string, string];
+};
+/** Parses a room-path back into its owner-named or DM shape. Throws on anything matching neither -- there is no third path shape. */
+export declare function parseRoomPath(path: string): ParsedRoomPath;
+/** Sanitises an arbitrary name (e.g. a directory basename) into a valid room-path localName by replacing every run of characters outside [A-Za-z0-9_-] with a single hyphen. Throws if nothing valid remains. */
+export declare function slugRoomName(name: string): string;
+//#endregion

package/dist/domain/room-path.mjs

@@ -0,0 +1,54 @@
+//#region src/domain/room-path.ts
+/**
+* Room paths — the naming and parsing convention core/room's device-keyed membership uses, mirroring spec/room.cddl's own owner-named-room-path/dm-room-path grammar exactly: an owner-named room is `<owner-hex>/<local-name>`, trust rooted at the owner named in the path; a DM is the bytewise-ascending sorted pair `<lower-hex>+<higher-hex>`, trust rooted at the verifier itself rather than either named party (see room.cddl's own comments for why that asymmetry is load-bearing, not incidental).
+*/
+const DEVICE_ID_HEX_PATTERN = /^[0-9a-f]{64}$/;
+const LOCAL_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+const SLUG_INVALID_RUN = /[^A-Za-z0-9_-]+/g;
+function assertDeviceIdHex(value, label) {
+	if (!DEVICE_ID_HEX_PATTERN.test(value)) throw new Error(`expected ${label} to be a 64-character lowercase hex device-id, got ${JSON.stringify(value)}`);
+}
+/** `<owner-hex>/<local-name>`. localName must already satisfy [A-Za-z0-9_-]+ -- run an untrusted name through slugRoomName first. */
+function ownerNamedRoomPath(owner, localName) {
+	assertDeviceIdHex(owner, "owner");
+	if (!LOCAL_NAME_PATTERN.test(localName)) throw new Error(`expected localName to match [A-Za-z0-9_-]+, got ${JSON.stringify(localName)}`);
+	return `${owner}/${localName}`;
+}
+/** `<lower-hex>+<higher-hex>`, the bytewise-ascending sorted pair. Refuses a==b outright: a path naming the same device twice is not a valid DM path at all, and a self-DM is a purely local concept a consumer models its own way, needing no path. */
+function dmRoomPath(a, b) {
+	assertDeviceIdHex(a, "a");
+	assertDeviceIdHex(b, "b");
+	if (a === b) throw new Error(`a DM room path cannot name the same device twice (${a})`);
+	return a < b ? `${a}+${b}` : `${b}+${a}`;
+}
+/** Parses a room-path back into its owner-named or DM shape. Throws on anything matching neither -- there is no third path shape. */
+function parseRoomPath(path) {
+	const slashIndex = path.indexOf("/");
+	if (slashIndex !== -1) {
+		const owner = path.slice(0, slashIndex);
+		const localName = path.slice(slashIndex + 1);
+		if (DEVICE_ID_HEX_PATTERN.test(owner) && LOCAL_NAME_PATTERN.test(localName)) return {
+			kind: "owner-named",
+			owner,
+			localName
+		};
+	}
+	const plusIndex = path.indexOf("+");
+	if (plusIndex !== -1) {
+		const first = path.slice(0, plusIndex);
+		const second = path.slice(plusIndex + 1);
+		if (DEVICE_ID_HEX_PATTERN.test(first) && DEVICE_ID_HEX_PATTERN.test(second) && first !== second) return {
+			kind: "dm",
+			participants: [first, second]
+		};
+	}
+	throw new Error(`${JSON.stringify(path)} is not a valid room-path`);
+}
+/** Sanitises an arbitrary name (e.g. a directory basename) into a valid room-path localName by replacing every run of characters outside [A-Za-z0-9_-] with a single hyphen. Throws if nothing valid remains. */
+function slugRoomName(name) {
+	const slug = name.replace(SLUG_INVALID_RUN, "-").replace(/^-+|-+$/g, "");
+	if (slug.length === 0) throw new Error(`${JSON.stringify(name)} has no valid room-name characters to slug`);
+	return slug;
+}
+//#endregion
+export { dmRoomPath, ownerNamedRoomPath, parseRoomPath, slugRoomName };

package/dist/domain/room-token-verification.cjs

@@ -0,0 +1,43 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_domain_device_id = require("./device-id.cjs");
+const require_domain_room_path = require("./room-path.cjs");
+const require_domain_tokens = require("./tokens.cjs");
+//#region src/domain/room-token-verification.ts
+/**
+* core/room's six verifier obligations (spec/room.cddl), layered on top of verifyCapabilityToken (obligations 2, 4, and 5 -- bearer match, ordinary token-claims checks, and delegations-remaining narrowing -- already live there). This module adds the two obligations specific to room-shaped scopes: the chain must terminate at the correct root for the path's own shape (1), and the token's own scope must actually name the room the request claims to act on (3). Obligation 6 (refuse an unrecognised content-type/kind) is a message-handling concern, not a token-verification one, and belongs to each consumer's own room verb router instead.
+*/
+/** The one capability every core/room verb (room.send/read/leave/members) is gated by, per spec/room.cddl -- room.join/room.invite are deliberately ungated instead and need no token check at all. */
+const ROOM_MEMBER_CAPABILITY = "room:member";
+/**
+* Verifies a `room:member` capability token against all six of core/room's verifier obligations. Delegates obligations 2/4/5 to verifyCapabilityToken directly; adds obligation 3 (scope.kind/scope.path must match the room being acted on) and obligation 1 (the chain's root must be the room's own owner for a named room, or the verifying identity itself for a DM -- never either named participant directly, since a DM token minted by anyone other than the verifier would let a sender self-issue authority to message a stranger unsolicited).
+*/
+async function verifyRoomToken(token, options) {
+	const verdict = await require_domain_tokens.verifyCapabilityToken(token, {
+		identity: options.identity,
+		clock: options.clock,
+		revocation: options.revocation,
+		expectedBearer: options.expectedBearer
+	});
+	if (!verdict.ok) return verdict;
+	if (verdict.claims.scope.kind !== "room") return {
+		ok: false,
+		reason: "wrong_scope_kind"
+	};
+	if (verdict.claims.scope.path !== options.roomPath) return {
+		ok: false,
+		reason: "wrong_scope_path"
+	};
+	const parsed = require_domain_room_path.parseRoomPath(options.roomPath);
+	const expectedRootHex = parsed.kind === "owner-named" ? parsed.owner : require_domain_device_id.deviceIdToHex(options.identity.deviceId);
+	if (require_domain_device_id.deviceIdToHex(verdict.rootIssuer) !== expectedRootHex) return {
+		ok: false,
+		reason: "wrong_chain_root"
+	};
+	return {
+		ok: true,
+		claims: verdict.claims
+	};
+}
+//#endregion
+exports.ROOM_MEMBER_CAPABILITY = ROOM_MEMBER_CAPABILITY;
+exports.verifyRoomToken = verifyRoomToken;

package/dist/domain/room-token-verification.d.cts

@@ -0,0 +1,24 @@
+import { Ot as TokenClaims, b as DeviceId, o as CapabilityToken } from "../protocol-CrX3Du0D.cjs";
+import { TokenVerdictReason, VerifyCapabilityTokenOptions } from "./tokens.cjs";
+//#region src/domain/room-token-verification.d.ts
+/** The one capability every core/room verb (room.send/read/leave/members) is gated by, per spec/room.cddl -- room.join/room.invite are deliberately ungated instead and need no token check at all. */
+export declare const ROOM_MEMBER_CAPABILITY = "room:member";
+export type RoomTokenVerdictReason = TokenVerdictReason | "wrong_scope_kind" | "wrong_scope_path" | "wrong_chain_root";
+export type RoomTokenVerdict = {
+  ok: true;
+  claims: TokenClaims;
+} | {
+  ok: false;
+  reason: RoomTokenVerdictReason;
+};
+export interface VerifyRoomTokenOptions extends Omit<VerifyCapabilityTokenOptions, "expectedBearer"> {
+  /** The peer identity actually authenticated on the arriving connection (obligation 2) -- never a relay-asserted or gossip-derived value. Mandatory here: every room verb requires a bearer, unlike verifyCapabilityToken's own optional field for callers presenting a token to authorise themselves rather than a specific counterparty. */
+  expectedBearer: DeviceId;
+  /** The room path this request claims to act on (obligation 3) -- must equal the token's own scope.path, and its own shape determines the chain root obligation 1 requires. */
+  roomPath: string;
+}
+/**
+ * Verifies a `room:member` capability token against all six of core/room's verifier obligations. Delegates obligations 2/4/5 to verifyCapabilityToken directly; adds obligation 3 (scope.kind/scope.path must match the room being acted on) and obligation 1 (the chain's root must be the room's own owner for a named room, or the verifying identity itself for a DM -- never either named participant directly, since a DM token minted by anyone other than the verifier would let a sender self-issue authority to message a stranger unsolicited).
+ */
+export declare function verifyRoomToken(token: CapabilityToken, options: Readonly<VerifyRoomTokenOptions>): Promise<RoomTokenVerdict>;
+//#endregion

package/dist/domain/room-token-verification.d.mts

@@ -0,0 +1,24 @@
+import { Ot as TokenClaims, b as DeviceId, o as CapabilityToken } from "../protocol-CrX3Du0D.mjs";
+import { TokenVerdictReason, VerifyCapabilityTokenOptions } from "./tokens.mjs";
+//#region src/domain/room-token-verification.d.ts
+/** The one capability every core/room verb (room.send/read/leave/members) is gated by, per spec/room.cddl -- room.join/room.invite are deliberately ungated instead and need no token check at all. */
+export declare const ROOM_MEMBER_CAPABILITY = "room:member";
+export type RoomTokenVerdictReason = TokenVerdictReason | "wrong_scope_kind" | "wrong_scope_path" | "wrong_chain_root";
+export type RoomTokenVerdict = {
+  ok: true;
+  claims: TokenClaims;
+} | {
+  ok: false;
+  reason: RoomTokenVerdictReason;
+};
+export interface VerifyRoomTokenOptions extends Omit<VerifyCapabilityTokenOptions, "expectedBearer"> {
+  /** The peer identity actually authenticated on the arriving connection (obligation 2) -- never a relay-asserted or gossip-derived value. Mandatory here: every room verb requires a bearer, unlike verifyCapabilityToken's own optional field for callers presenting a token to authorise themselves rather than a specific counterparty. */
+  expectedBearer: DeviceId;
+  /** The room path this request claims to act on (obligation 3) -- must equal the token's own scope.path, and its own shape determines the chain root obligation 1 requires. */
+  roomPath: string;
+}
+/**
+ * Verifies a `room:member` capability token against all six of core/room's verifier obligations. Delegates obligations 2/4/5 to verifyCapabilityToken directly; adds obligation 3 (scope.kind/scope.path must match the room being acted on) and obligation 1 (the chain's root must be the room's own owner for a named room, or the verifying identity itself for a DM -- never either named participant directly, since a DM token minted by anyone other than the verifier would let a sender self-issue authority to message a stranger unsolicited).
+ */
+export declare function verifyRoomToken(token: CapabilityToken, options: Readonly<VerifyRoomTokenOptions>): Promise<RoomTokenVerdict>;
+//#endregion

package/dist/domain/room-token-verification.mjs

@@ -0,0 +1,41 @@
+import { deviceIdToHex } from "./device-id.mjs";
+import { parseRoomPath } from "./room-path.mjs";
+import { verifyCapabilityToken } from "./tokens.mjs";
+//#region src/domain/room-token-verification.ts
+/**
+* core/room's six verifier obligations (spec/room.cddl), layered on top of verifyCapabilityToken (obligations 2, 4, and 5 -- bearer match, ordinary token-claims checks, and delegations-remaining narrowing -- already live there). This module adds the two obligations specific to room-shaped scopes: the chain must terminate at the correct root for the path's own shape (1), and the token's own scope must actually name the room the request claims to act on (3). Obligation 6 (refuse an unrecognised content-type/kind) is a message-handling concern, not a token-verification one, and belongs to each consumer's own room verb router instead.
+*/
+/** The one capability every core/room verb (room.send/read/leave/members) is gated by, per spec/room.cddl -- room.join/room.invite are deliberately ungated instead and need no token check at all. */
+const ROOM_MEMBER_CAPABILITY = "room:member";
+/**
+* Verifies a `room:member` capability token against all six of core/room's verifier obligations. Delegates obligations 2/4/5 to verifyCapabilityToken directly; adds obligation 3 (scope.kind/scope.path must match the room being acted on) and obligation 1 (the chain's root must be the room's own owner for a named room, or the verifying identity itself for a DM -- never either named participant directly, since a DM token minted by anyone other than the verifier would let a sender self-issue authority to message a stranger unsolicited).
+*/
+async function verifyRoomToken(token, options) {
+	const verdict = await verifyCapabilityToken(token, {
+		identity: options.identity,
+		clock: options.clock,
+		revocation: options.revocation,
+		expectedBearer: options.expectedBearer
+	});
+	if (!verdict.ok) return verdict;
+	if (verdict.claims.scope.kind !== "room") return {
+		ok: false,
+		reason: "wrong_scope_kind"
+	};
+	if (verdict.claims.scope.path !== options.roomPath) return {
+		ok: false,
+		reason: "wrong_scope_path"
+	};
+	const parsed = parseRoomPath(options.roomPath);
+	const expectedRootHex = parsed.kind === "owner-named" ? parsed.owner : deviceIdToHex(options.identity.deviceId);
+	if (deviceIdToHex(verdict.rootIssuer) !== expectedRootHex) return {
+		ok: false,
+		reason: "wrong_chain_root"
+	};
+	return {
+		ok: true,
+		claims: verdict.claims
+	};
+}
+//#endregion
+export { ROOM_MEMBER_CAPABILITY, verifyRoomToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
   "repository": {
@@ -100,6 +100,14 @@
       "import": "./dist/domain/revocation-view.mjs",
       "require": "./dist/domain/revocation-view.cjs"
     },
+    "./domain/room-path": {
+      "import": "./dist/domain/room-path.mjs",
+      "require": "./dist/domain/room-path.cjs"
+    },
+    "./domain/room-token-verification": {
+      "import": "./dist/domain/room-token-verification.mjs",
+      "require": "./dist/domain/room-token-verification.cjs"
+    },
     "./domain/tokens": {
       "import": "./dist/domain/tokens.mjs",
       "require": "./dist/domain/tokens.cjs"