@mulmoclaude/common 1.1.2 → 1.3.0

package/README.md

@@ -37,6 +37,7 @@ helpers below.
 |---|---|---|
 | `errorMessage(v, fallback?)` | `string` | unknown caught value → human-readable string; **isomorphic**, so Vue/browser surfaces use it too |
 | `toUtcIsoDate(timestamp)` | `string` | `Date` → `YYYY-MM-DD` in UTC — for dates that must not shift with the host's local timezone |
+| `splitJwtSegments(token)` | `JwtSegments \| null` | JWS compact serialization → its three segments; `null` for anything that isn't **exactly** three. Pure string work, so the Node bridges and the Workers relay share the guard while decoding differently |
 
 `errorMessage` surfaces a non-empty string `details` (gRPC convention) or
 `message` field of a non-Error object (`details` wins) instead of

package/dist/envCoerce.d.ts

@@ -0,0 +1,21 @@
+export interface IntRange {
+    min?: number;
+    max?: number;
+}
+/**
+ * `Number()`-based integer coercion with an optional range, falling back when the
+ * value is absent, empty, non-integer, or out of range.
+ *
+ * `Number()` — not `parseInt` — on purpose: it is what the server has always used,
+ * so `0x1f`, `1e3`, `+3100` and `3100.0` coerce exactly as they did, and a
+ * whitespace-only value coerces to 0. Anything stricter here would silently
+ * disagree with the backend.
+ */
+export declare function asInt(value: string | undefined, fallback: number, opts?: IntRange): number;
+/** The port range the backend accepts, so both sides bound the value identically.
+ *  `min: 0` is deliberate — 0 asks the OS for an ephemeral port.
+ *
+ *  `Required<IntRange>`, not `IntRange`: both bounds are always present here, and
+ *  saying so lets a caller compare against them (`port <= PORT_RANGE.max`) without
+ *  a non-null assertion. Still assignable wherever an `IntRange` is expected. */
+export declare const PORT_RANGE: Required<IntRange>;

package/dist/envCoerce.js

@@ -0,0 +1,36 @@
+// Env-var type coercion for ports and other integer settings.
+//
+// It started inside `server/system/env.ts` (#504-era), moved to
+// `server/utils/envCoerce.ts` when #2650 needed the SAME rule for `yarn dev`'s
+// Vite proxy — the proxy has to resolve `PORT` exactly as the backend does, or
+// the two point at different servers — and moved here when #3084 needed it for
+// the messaging bridges too. A second opinion about "is this a port" is that
+// bug one level down, so there is exactly one copy and every tier imports it.
+/**
+ * `Number()`-based integer coercion with an optional range, falling back when the
+ * value is absent, empty, non-integer, or out of range.
+ *
+ * `Number()` — not `parseInt` — on purpose: it is what the server has always used,
+ * so `0x1f`, `1e3`, `+3100` and `3100.0` coerce exactly as they did, and a
+ * whitespace-only value coerces to 0. Anything stricter here would silently
+ * disagree with the backend.
+ */
+export function asInt(value, fallback, opts = {}) {
+    if (value === undefined || value === "")
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        return fallback;
+    if (opts.min !== undefined && parsed < opts.min)
+        return fallback;
+    if (opts.max !== undefined && parsed > opts.max)
+        return fallback;
+    return parsed;
+}
+/** The port range the backend accepts, so both sides bound the value identically.
+ *  `min: 0` is deliberate — 0 asks the OS for an ephemeral port.
+ *
+ *  `Required<IntRange>`, not `IntRange`: both bounds are always present here, and
+ *  saying so lets a caller compare against them (`port <= PORT_RANGE.max`) without
+ *  a non-null assertion. Still assignable wherever an `IntRange` is expected. */
+export const PORT_RANGE = Object.freeze({ min: 0, max: 65_535 });

package/dist/index.d.ts

@@ -62,5 +62,21 @@ export declare function toUtcIsoDate(timestamp: Date): string;
  *  introduces contain none of the other four characters, so nothing is
  *  double-escaped. Not a sanitiser: it neither strips tags nor validates URLs. */
 export declare function escapeHtml(value: string): string;
+export interface JwtSegments {
+    headerSegment: string;
+    payloadSegment: string;
+    signatureSegment: string;
+}
+/** Split a JWS compact serialization into its three segments, or `null` when the
+ *  token isn't well-formed. Pure string work, so the Node bridges and the
+ *  Cloudflare Workers relay — which decode the segments differently (`Buffer` vs
+ *  `atob`) — can still share this one guard.
+ *
+ *  A JWS compact serialization is EXACTLY three segments. Both a short token and
+ *  a longer one (a five-segment JWE, or an attacker appending `.junk`) are
+ *  rejected outright — never parsed from their first three segments, which would
+ *  let the signed input disagree with the token. */
+export declare function splitJwtSegments(token: string): JwtSegments | null;
 export { scanEnvOptions, snakeToLowerCamel, type ScanEnvOptionsConfig } from "./envScan.js";
 export type { MinimalLogger, StructuredLogger } from "./logger.js";
+export { asInt, PORT_RANGE, type IntRange } from "./envCoerce.js";

package/dist/index.js

@@ -116,4 +116,22 @@ const HTML_ESCAPES = new Map([
 export function escapeHtml(value) {
     return value.replace(/[&<>"']/g, (char) => HTML_ESCAPES.get(char) ?? char);
 }
+/** Split a JWS compact serialization into its three segments, or `null` when the
+ *  token isn't well-formed. Pure string work, so the Node bridges and the
+ *  Cloudflare Workers relay — which decode the segments differently (`Buffer` vs
+ *  `atob`) — can still share this one guard.
+ *
+ *  A JWS compact serialization is EXACTLY three segments. Both a short token and
+ *  a longer one (a five-segment JWE, or an attacker appending `.junk`) are
+ *  rejected outright — never parsed from their first three segments, which would
+ *  let the signed input disagree with the token. */
+export function splitJwtSegments(token) {
+    const [headerSegment, payloadSegment, signatureSegment, ...extraSegments] = token.split(".");
+    if (headerSegment === undefined || payloadSegment === undefined || signatureSegment === undefined)
+        return null;
+    if (extraSegments.length > 0)
+        return null;
+    return { headerSegment, payloadSegment, signatureSegment };
+}
 export { scanEnvOptions, snakeToLowerCamel } from "./envScan.js";
+export { asInt, PORT_RANGE } from "./envCoerce.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/common",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "General-purpose pure utilities (type guards, etc.) shared across the MulmoClaude host, bridges, and plugins",
   "type": "module",
   "main": "./dist/index.js",