@rexezuge/shared 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rexezuge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/Base64.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Base64 codec for byte payloads.
+ *
+ * ## Provenance
+ *
+ * Converged from `packages/shared/src/utils/Base64.ts` (Durable-DAV), the
+ * documented best form. Four implementations once existed — Durable-DAV's own,
+ * `DavReadCache`, and `aes-gcm` running the `String.fromCodePoint(...subarray)`
+ * + `btoa` form this file was written to replace. ChordDHT-Tracker and
+ * Mail-Otter carry no byte codec of their own; their `CryptoUtil`s use the
+ * `btoa`+transform form. This file is the canonical one for **standard**
+ * base64. The **base64url** alphabet is a different job and lives in
+ * `CryptoUtil` — that duplication is deliberate (different alphabet).
+ *
+ * ## Why not `String.fromCodePoint` + `btoa`
+ *
+ * The obvious encoder builds a binary string and `btoa`s it:
+ *
+ * ```ts
+ * let binary = '';
+ * for (let i = 0; i < bytes.length; i += 8192) {
+ *   binary += String.fromCodePoint(...bytes.subarray(i, i + 8192));
+ * }
+ * return btoa(binary);
+ * ```
+ *
+ * That allocates roughly 2× the input as UTF-16 — up to 100 MB of garbage for a
+ * 50 MB payload, on top of the buffer and the result — and the variadic spread
+ * approaches the engine's argument limit. A direct 3-byte-to-4-char table is
+ * allocation-light and has no argument limit. `base64ToBytes` keeps the `atob`
+ * form: decoding allocates one binary string and one buffer, which is the
+ * output's own size rather than double it, and `atob` does the validation for
+ * free.
+ */
+/**
+ * Encode `bytes` as standard base64 (with `=` padding).
+ *
+ * Not base64url: pre-binary KV file entries stored these as opaque values and
+ * `aes-gcm` stores them where `atob` reads them back. `CryptoUtil` has the
+ * URL-safe variant for the cases that need one.
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Decode standard base64.
+ *
+ * `atob` throws on malformed input rather than producing partial bytes, which is
+ * the right behaviour for every caller here: a corrupt cache entry or a mistyped
+ * key should fail loudly, not decrypt to noise.
+ */
+declare function base64ToBytes(b64: string): Uint8Array;
+export { bytesToBase64, base64ToBytes };
+//# sourceMappingURL=Base64.d.ts.map

package/dist/Base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Base64.d.ts","sourceRoot":"","sources":["../src/Base64.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH;;;;;;GAMG;AACH,iBAAS,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAqBhD;AAED;;;;;;GAMG;AACH,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAK9C;AAED,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC"}

package/dist/Base64.js

@@ -0,0 +1,81 @@
+/**
+ * Base64 codec for byte payloads.
+ *
+ * ## Provenance
+ *
+ * Converged from `packages/shared/src/utils/Base64.ts` (Durable-DAV), the
+ * documented best form. Four implementations once existed — Durable-DAV's own,
+ * `DavReadCache`, and `aes-gcm` running the `String.fromCodePoint(...subarray)`
+ * + `btoa` form this file was written to replace. ChordDHT-Tracker and
+ * Mail-Otter carry no byte codec of their own; their `CryptoUtil`s use the
+ * `btoa`+transform form. This file is the canonical one for **standard**
+ * base64. The **base64url** alphabet is a different job and lives in
+ * `CryptoUtil` — that duplication is deliberate (different alphabet).
+ *
+ * ## Why not `String.fromCodePoint` + `btoa`
+ *
+ * The obvious encoder builds a binary string and `btoa`s it:
+ *
+ * ```ts
+ * let binary = '';
+ * for (let i = 0; i < bytes.length; i += 8192) {
+ *   binary += String.fromCodePoint(...bytes.subarray(i, i + 8192));
+ * }
+ * return btoa(binary);
+ * ```
+ *
+ * That allocates roughly 2× the input as UTF-16 — up to 100 MB of garbage for a
+ * 50 MB payload, on top of the buffer and the result — and the variadic spread
+ * approaches the engine's argument limit. A direct 3-byte-to-4-char table is
+ * allocation-light and has no argument limit. `base64ToBytes` keeps the `atob`
+ * form: decoding allocates one binary string and one buffer, which is the
+ * output's own size rather than double it, and `atob` does the validation for
+ * free.
+ */
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * Encode `bytes` as standard base64 (with `=` padding).
+ *
+ * Not base64url: pre-binary KV file entries stored these as opaque values and
+ * `aes-gcm` stores them where `atob` reads them back. `CryptoUtil` has the
+ * URL-safe variant for the cases that need one.
+ */
+function bytesToBase64(bytes) {
+    let out = '';
+    const len = bytes.length;
+    const remainder = len % 3;
+    const limit = len - remainder;
+    for (let i = 0; i < limit; i += 3) {
+        const triple = bytes[i] * 65_536 + bytes[i + 1] * 256 + bytes[i + 2];
+        out +=
+            BASE64_ALPHABET[(triple >> 18) & 63] +
+                BASE64_ALPHABET[(triple >> 12) & 63] +
+                BASE64_ALPHABET[(triple >> 6) & 63] +
+                BASE64_ALPHABET[triple & 63];
+    }
+    if (remainder === 1) {
+        const value = bytes[limit];
+        out += `${BASE64_ALPHABET[value >> 2]}${BASE64_ALPHABET[(value << 4) & 63]}==`;
+    }
+    else if (remainder === 2) {
+        const pair = (bytes[limit] << 8) | bytes[limit + 1];
+        out += `${BASE64_ALPHABET[pair >> 10]}${BASE64_ALPHABET[(pair >> 4) & 63]}${BASE64_ALPHABET[(pair << 2) & 63]}=`;
+    }
+    return out;
+}
+/**
+ * Decode standard base64.
+ *
+ * `atob` throws on malformed input rather than producing partial bytes, which is
+ * the right behaviour for every caller here: a corrupt cache entry or a mistyped
+ * key should fail loudly, not decrypt to noise.
+ */
+function base64ToBytes(b64) {
+    const binary = atob(b64);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        out[i] = (binary.codePointAt(i) ?? 0) & 0xff;
+    return out;
+}
+export { bytesToBase64, base64ToBytes };
+//# sourceMappingURL=Base64.js.map

package/dist/Base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Base64.js","sourceRoot":"","sources":["../src/Base64.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,eAAe,GAAG,kEAAkE,CAAC;AAE3F;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,KAAiB;IACtC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;IACzB,MAAM,SAAS,GAAG,GAAG,GAAG,CAAC,CAAC;IAC1B,MAAM,KAAK,GAAG,GAAG,GAAG,SAAS,CAAC;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACrE,GAAG;YACD,eAAe,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC;gBACpC,eAAe,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC;gBACpC,eAAe,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;gBACnC,eAAe,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC3B,GAAG,IAAI,GAAG,eAAe,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;IACjF,CAAC;SAAM,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACpD,GAAG,IAAI,GAAG,eAAe,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC;IACnH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,GAAW;IAChC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IACxF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC"}

package/dist/Clock.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Inject-able time source.
+ *
+ * ## Provenance
+ *
+ * Converged from AWS-AccessBridge's `Clock.ts`, Mail-Otter's `Clock.ts` and
+ * ChordDHT-Tracker's `Clock.ts`. The three differ in surface, not concept: AWS
+ * names the seam `Clock` with `now(): number` and a shared `SYSTEM_CLOCK`;
+ * Mail-Otter/ChordDHT name it `IClock` with `nowMs()` and a mutable
+ * `FixedClock` carrying `setNowMs`/`advanceByMs`.
+ *
+ * ## Design decision
+ *
+ * The kit drops the `I` prefix on the interface (no `any`, no Hungarian drift;
+ * the consumer repos' own "no `I` on interfaces" cleanups point the same way),
+ * keeps AWS's single-method `now()` as the primary read, and keeps Mail-Otter's
+ * mutable `FixedClock` helpers — they cost nothing and are exactly what a test
+ * wants. `TimestampUtil`'s current-time reads go through `SYSTEM_CLOCK` by
+ * default; pass a `FixedClock` to pin them.
+ */
+interface Clock {
+    /**
+     * Milliseconds since the Unix epoch.
+     */
+    now(): number;
+}
+/**
+ * The production clock. A single shared instance — it holds no state, so there
+ * is nothing to gain from more than one, and a default parameter needs a value.
+ */
+declare class SystemClock implements Clock {
+    now(): number;
+}
+/**
+ * A clock seeded at `initialNowMs` and moved forward with `setNowMs`/`advanceByMs`.
+ *
+ * Two shapes were merged: AWS's `FixedClock` was immutable (constructed with the
+ * instant under test), Mail-Otter's was mutable. The mutable form is a superset
+ * and is what the time-dependent tests in every repo actually reach for, so a
+ * test either pins the instant up front or advances it as work happens.
+ */
+declare class FixedClock implements Clock {
+    private currentMs;
+    constructor(initialNowMs?: number);
+    now(): number;
+    setNowMs(valueMs: number): void;
+    advanceByMs(deltaMs: number): void;
+}
+/**
+ * The shared production instance, for the common case where a caller wants "now"
+ * without choosing a clock. Stateless, so one instance is enough.
+ */
+declare const SYSTEM_CLOCK: Clock;
+export type { Clock };
+export { SystemClock, FixedClock, SYSTEM_CLOCK };
+//# sourceMappingURL=Clock.d.ts.map

package/dist/Clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../src/Clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,UAAU,KAAK;IACb;;OAEG;IACH,GAAG,IAAI,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,cAAM,WAAY,YAAW,KAAK;IAChC,GAAG,IAAI,MAAM;CAGd;AAED;;;;;;;GAOG;AACH,cAAM,UAAW,YAAW,KAAK;IAC/B,OAAO,CAAC,SAAS,CAAS;gBAEd,YAAY,SAAI;IAI5B,GAAG,IAAI,MAAM;IAIb,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI/B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAGnC;AAED;;;GAGG;AACH,QAAA,MAAM,YAAY,EAAE,KAAyB,CAAC;AAE9C,YAAY,EAAE,KAAK,EAAE,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC"}

package/dist/Clock.js

@@ -0,0 +1,59 @@
+/**
+ * Inject-able time source.
+ *
+ * ## Provenance
+ *
+ * Converged from AWS-AccessBridge's `Clock.ts`, Mail-Otter's `Clock.ts` and
+ * ChordDHT-Tracker's `Clock.ts`. The three differ in surface, not concept: AWS
+ * names the seam `Clock` with `now(): number` and a shared `SYSTEM_CLOCK`;
+ * Mail-Otter/ChordDHT name it `IClock` with `nowMs()` and a mutable
+ * `FixedClock` carrying `setNowMs`/`advanceByMs`.
+ *
+ * ## Design decision
+ *
+ * The kit drops the `I` prefix on the interface (no `any`, no Hungarian drift;
+ * the consumer repos' own "no `I` on interfaces" cleanups point the same way),
+ * keeps AWS's single-method `now()` as the primary read, and keeps Mail-Otter's
+ * mutable `FixedClock` helpers — they cost nothing and are exactly what a test
+ * wants. `TimestampUtil`'s current-time reads go through `SYSTEM_CLOCK` by
+ * default; pass a `FixedClock` to pin them.
+ */
+/**
+ * The production clock. A single shared instance — it holds no state, so there
+ * is nothing to gain from more than one, and a default parameter needs a value.
+ */
+class SystemClock {
+    now() {
+        return Date.now();
+    }
+}
+/**
+ * A clock seeded at `initialNowMs` and moved forward with `setNowMs`/`advanceByMs`.
+ *
+ * Two shapes were merged: AWS's `FixedClock` was immutable (constructed with the
+ * instant under test), Mail-Otter's was mutable. The mutable form is a superset
+ * and is what the time-dependent tests in every repo actually reach for, so a
+ * test either pins the instant up front or advances it as work happens.
+ */
+class FixedClock {
+    currentMs;
+    constructor(initialNowMs = 0) {
+        this.currentMs = initialNowMs;
+    }
+    now() {
+        return this.currentMs;
+    }
+    setNowMs(valueMs) {
+        this.currentMs = valueMs;
+    }
+    advanceByMs(deltaMs) {
+        this.currentMs += deltaMs;
+    }
+}
+/**
+ * The shared production instance, for the common case where a caller wants "now"
+ * without choosing a clock. Stateless, so one instance is enough.
+ */
+const SYSTEM_CLOCK = new SystemClock();
+export { SystemClock, FixedClock, SYSTEM_CLOCK };
+//# sourceMappingURL=Clock.js.map

package/dist/Clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Clock.js","sourceRoot":"","sources":["../src/Clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH;;;GAGG;AACH,MAAM,WAAW;IACf,GAAG;QACD,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU;IACN,SAAS,CAAS;IAE1B,YAAY,YAAY,GAAG,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,YAAY,CAAC;IAChC,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,QAAQ,CAAC,OAAe;QACtB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED,WAAW,CAAC,OAAe;QACzB,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC;IAC5B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,YAAY,GAAU,IAAI,WAAW,EAAE,CAAC;AAG9C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC"}

package/dist/CryptoUtil.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Hashing and key generation.
+ *
+ * ## Provenance
+ *
+ * Converged from `CryptoUtil.ts` in Durable-DAV, Edge-Git, Mail-Meow,
+ * Mail-Otter, ChordDHT-Tracker and CalDAV-Bridge. Every copy carries
+ * `sha256Hex` and `randomBase64Url`; Edge-Git/Mail-Meow/Mail-Otter/ChordDHT add
+ * `hmacSha256Hex`; Mail-Meow adds the string overload `base64UrlEncode`;
+ * Durable-DAV uniquely factors the digest over raw bytes (`sha256HexOfBytes`) and
+ * rewrites base64url on the shared codec.
+ *
+ * ## Design decisions
+ *
+ * - The base64url alphabet is a **different alphabet for a different job** from
+ *   `Base64.ts`, so the URL-safe transform stays here — but it delegates to the
+ *   documented best encoder rather than re-spreading bytes (`String.fromCodePoint`
+ *   + `btoa`), which was four copies of the ~2×-UTF-16 form `Base64.ts` replaced.
+ * - `sha256Hex` is defined over `sha256HexOfBytes` (Durable-DAV's shape): the
+ *   digest then covers exactly the bytes presented, which matters when two sides
+ *   compare a digest — an intermediate encoding is a place for them to disagree.
+ * - `hmacSha256Hex` is kept from the four repos that carry it.
+ *
+ * ## Left local
+ *
+ * ChordDHT-Tracker's `sha1Hex` is deliberately **not** here. SHA-1 is the Chord
+ * ring identifier hash (protocol compatibility), not a general security digest;
+ * surfacing it in the shared surface would invite exactly the misuse the
+ * `sonarjs/hashing` lint it carries a disable for is there to catch. A repo that
+ * needs a protocol-mandated SHA-1 computes it on a `BufferSource` itself.
+ */
+declare class CryptoUtil {
+    /**
+     * SHA-256 of a string, hex-encoded.
+     *
+     * Encoded as UTF-8 first. For bytes you already hold, prefer `sha256HexOfBytes`
+     * — this overload is the reason a byte payload used to be laundered through
+     * `String.fromCodePoint` into a binary string and back, allocating roughly 2×
+     * the input as UTF-16 on the way.
+     */
+    static sha256Hex(value: string): Promise<string>;
+    /**
+     * SHA-256 of raw bytes, hex-encoded.
+     *
+     * The hash covers exactly these bytes. This matters where the digest is
+     * compared between two sides: any intermediate encoding is a place for the two
+     * to disagree for a reason that has nothing to do with the content.
+     */
+    static sha256HexOfBytes(bytes: Uint8Array): Promise<string>;
+    /**
+     * HMAC-SHA256 of `value` under `secret`, hex-encoded.
+     *
+     * A keyed MAC for a message a caller will recompute on the other side. The key
+     * is imported as non-extractable; a comparison against a re-derived MAC must be
+     * timing-safe on the caller's side — this helper returns the hex string, it does
+     * not compare.
+     */
+    static hmacSha256Hex(value: string, secret: string): Promise<string>;
+    private static toHex;
+    /**
+     * URL-safe base64 of `bytes` (no `+`, `/` or `=`).
+     *
+     * Delegates to the shared codec rather than rebuilding the binary string here:
+     * the URL-safe transform is applied to the standard alphabet because
+     * `Uint8Array#toBase64` is not guaranteed across Workers runtimes.
+     */
+    static toBase64Url(bytes: Uint8Array): string;
+    /**
+     * URL-safe base64 of a UTF-8 string.
+     *
+     * The same transform as {@link toBase64Url}, for callers holding text rather
+     * than bytes. This and `toBase64Url` used to be separate implementations in
+     * different packages; they are the same encoding and must not drift.
+     */
+    static base64UrlEncode(value: string): string;
+    static randomBase64Url(byteLength: number): string;
+}
+export { CryptoUtil };
+//# sourceMappingURL=CryptoUtil.d.ts.map

package/dist/CryptoUtil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CryptoUtil.d.ts","sourceRoot":"","sources":["../src/CryptoUtil.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,cAAM,UAAU;IACd;;;;;;;OAOG;WACiB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7D;;;;;;OAMG;WACiB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAKxE;;;;;;;OAOG;WACiB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYjF,OAAO,CAAC,MAAM,CAAC,KAAK;IAIpB;;;;;;OAMG;WACW,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IAIpD;;;;;;OAMG;WACW,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;WAItC,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;CAG1D;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/CryptoUtil.js

@@ -0,0 +1,97 @@
+import { bytesToBase64 } from './Base64';
+/**
+ * Hashing and key generation.
+ *
+ * ## Provenance
+ *
+ * Converged from `CryptoUtil.ts` in Durable-DAV, Edge-Git, Mail-Meow,
+ * Mail-Otter, ChordDHT-Tracker and CalDAV-Bridge. Every copy carries
+ * `sha256Hex` and `randomBase64Url`; Edge-Git/Mail-Meow/Mail-Otter/ChordDHT add
+ * `hmacSha256Hex`; Mail-Meow adds the string overload `base64UrlEncode`;
+ * Durable-DAV uniquely factors the digest over raw bytes (`sha256HexOfBytes`) and
+ * rewrites base64url on the shared codec.
+ *
+ * ## Design decisions
+ *
+ * - The base64url alphabet is a **different alphabet for a different job** from
+ *   `Base64.ts`, so the URL-safe transform stays here — but it delegates to the
+ *   documented best encoder rather than re-spreading bytes (`String.fromCodePoint`
+ *   + `btoa`), which was four copies of the ~2×-UTF-16 form `Base64.ts` replaced.
+ * - `sha256Hex` is defined over `sha256HexOfBytes` (Durable-DAV's shape): the
+ *   digest then covers exactly the bytes presented, which matters when two sides
+ *   compare a digest — an intermediate encoding is a place for them to disagree.
+ * - `hmacSha256Hex` is kept from the four repos that carry it.
+ *
+ * ## Left local
+ *
+ * ChordDHT-Tracker's `sha1Hex` is deliberately **not** here. SHA-1 is the Chord
+ * ring identifier hash (protocol compatibility), not a general security digest;
+ * surfacing it in the shared surface would invite exactly the misuse the
+ * `sonarjs/hashing` lint it carries a disable for is there to catch. A repo that
+ * needs a protocol-mandated SHA-1 computes it on a `BufferSource` itself.
+ */
+class CryptoUtil {
+    /**
+     * SHA-256 of a string, hex-encoded.
+     *
+     * Encoded as UTF-8 first. For bytes you already hold, prefer `sha256HexOfBytes`
+     * — this overload is the reason a byte payload used to be laundered through
+     * `String.fromCodePoint` into a binary string and back, allocating roughly 2×
+     * the input as UTF-16 on the way.
+     */
+    static async sha256Hex(value) {
+        return this.sha256HexOfBytes(new TextEncoder().encode(value));
+    }
+    /**
+     * SHA-256 of raw bytes, hex-encoded.
+     *
+     * The hash covers exactly these bytes. This matters where the digest is
+     * compared between two sides: any intermediate encoding is a place for the two
+     * to disagree for a reason that has nothing to do with the content.
+     */
+    static async sha256HexOfBytes(bytes) {
+        const digest = await crypto.subtle.digest('SHA-256', bytes);
+        return this.toHex(new Uint8Array(digest));
+    }
+    /**
+     * HMAC-SHA256 of `value` under `secret`, hex-encoded.
+     *
+     * A keyed MAC for a message a caller will recompute on the other side. The key
+     * is imported as non-extractable; a comparison against a re-derived MAC must be
+     * timing-safe on the caller's side — this helper returns the hex string, it does
+     * not compare.
+     */
+    static async hmacSha256Hex(value, secret) {
+        const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(value));
+        return this.toHex(new Uint8Array(signature));
+    }
+    static toHex(bytes) {
+        return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    }
+    /**
+     * URL-safe base64 of `bytes` (no `+`, `/` or `=`).
+     *
+     * Delegates to the shared codec rather than rebuilding the binary string here:
+     * the URL-safe transform is applied to the standard alphabet because
+     * `Uint8Array#toBase64` is not guaranteed across Workers runtimes.
+     */
+    static toBase64Url(bytes) {
+        return bytesToBase64(bytes).replaceAll('+', '-').replaceAll('/', '_').replace(/={0,2}$/, '');
+    }
+    /**
+     * URL-safe base64 of a UTF-8 string.
+     *
+     * The same transform as {@link toBase64Url}, for callers holding text rather
+     * than bytes. This and `toBase64Url` used to be separate implementations in
+     * different packages; they are the same encoding and must not drift.
+     */
+    static base64UrlEncode(value) {
+        return this.toBase64Url(new TextEncoder().encode(value));
+    }
+    static randomBase64Url(byteLength) {
+        return this.toBase64Url(crypto.getRandomValues(new Uint8Array(byteLength)));
+    }
+}
+export { CryptoUtil };
+//# sourceMappingURL=CryptoUtil.js.map

package/dist/CryptoUtil.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CryptoUtil.js","sourceRoot":"","sources":["../src/CryptoUtil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU;IACd;;;;;;;OAOG;IACI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,KAAa;QACzC,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,KAAiB;QACpD,MAAM,MAAM,GAAgB,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAqB,CAAC,CAAC;QACzF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,MAAc;QAC7D,MAAM,GAAG,GAAc,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAClD,KAAK,EACL,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAChC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAC;QACF,MAAM,SAAS,GAAgB,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACtG,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/C,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,KAAiB;QACpC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,WAAW,CAAC,KAAiB;QACzC,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,eAAe,CAAC,KAAa;QACzC,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3D,CAAC;IAEM,MAAM,CAAC,eAAe,CAAC,UAAkB;QAC9C,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC9E,CAAC;CACF;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/CursorCodec.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical opaque-cursor codec, plus the `Page<T>` shape it produces.
+ *
+ * ## Provenance
+ *
+ * Converged from ChordDHT-Tracker's `utils/Cursor.ts` (a `Cursor` class + a
+ * `Page<T>` type), Edge-Git's `backend-data/.../CursorUtil.ts` (a `CursorUtil`
+ * class that adds `decodeOrThrow` + `isValidCursor`) and Mail-Otter's
+ * `CursorUtil.ts` (the minimal `encode`/`decode` pair). All three hand-rolled
+ * DAO pagination cursors and all three converged on `btoa(JSON.stringify(...))`
+ * / `JSON.parse(atob(...))`. Canonical name is **`CursorCodec`**; the cursor is an
+ * opaque token, so callers pass it through and never inspect it.
+ *
+ * ## Design decisions
+ *
+ * - The cursor is `btoa`/`atob`, which works in workerd *and* Node 24 (both
+ *   expose browser globals now). No `Buffer` is used, so the same bundle runs in
+ *   both.
+ * - `decode` never throws: a malformed or tampered cursor is `undefined`, which a
+ *   DAO reads as "no cursor, start from the beginning" rather than an error an
+ *   attacker can provoke. `decodeOrThrow` and `isValidCursor` are kept from
+ *   Edge-Git for the call sites that *want* the strict behaviour.
+ * - **Layer 0 stays dependency-free.** Edge-Git's `decodeOrThrow` threw its
+ *   `@edge-git/backend-errors` `BadRequestError`; the shared package imports
+ *   nothing, so it throws a plain `Error` and leaves the HTTP mapping to the
+ *   layer that owns the error taxonomy (the same "throw plain `Error`, map above"
+ *   rule `Identity`/`EmailUtil` follow).
+ */
+interface Page<T> {
+    readonly items: readonly T[];
+    readonly nextCursor?: string;
+}
+declare class CursorCodec {
+    static encode(value: unknown): string;
+    /**
+     * Decode a cursor, or `undefined` for a missing/malformed one.
+     *
+     * `atob`/`JSON.parse` throw on bad input; the `try` turns that into `undefined`
+     * so a corrupt cursor degrades to a first page instead of an uncaught throw.
+     */
+    static decode<T>(cursor: string | undefined | null): T | undefined;
+    /**
+     * Decode a cursor, throwing a plain `Error` on malformed input.
+     *
+     * For a call site that treats a bad cursor as a client error; the HTTP mapping
+     * to `BadRequest` is the caller's layer's job (see the file header).
+     */
+    static decodeOrThrow<T>(cursor: string | undefined | null): T | undefined;
+    /**
+     * Whether a cursor is well-formed. A missing cursor is valid (first page).
+     */
+    static isValidCursor(cursor: string | undefined | null): boolean;
+    /**
+     * Build a `Page`, omitting `nextCursor` entirely on the last page rather than
+     * carrying an explicit `undefined`.
+     */
+    static page<T>(items: readonly T[], nextCursor?: string): Page<T>;
+}
+export { CursorCodec };
+export type { Page };
+//# sourceMappingURL=CursorCodec.d.ts.map

package/dist/CursorCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CursorCodec.d.ts","sourceRoot":"","sources":["../src/CursorCodec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,UAAU,IAAI,CAAC,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,cAAM,WAAW;WACD,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAI5C;;;;;OAKG;WACW,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,SAAS;IASzE;;;;;OAKG;WACW,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,SAAS;IAShF;;OAEG;WACW,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO;IAUvE;;;OAGG;WACW,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;CAGzE;AAED,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,YAAY,EAAE,IAAI,EAAE,CAAC"}

package/dist/CursorCodec.js

@@ -0,0 +1,60 @@
+class CursorCodec {
+    static encode(value) {
+        return btoa(JSON.stringify(value));
+    }
+    /**
+     * Decode a cursor, or `undefined` for a missing/malformed one.
+     *
+     * `atob`/`JSON.parse` throw on bad input; the `try` turns that into `undefined`
+     * so a corrupt cursor degrades to a first page instead of an uncaught throw.
+     */
+    static decode(cursor) {
+        if (!cursor)
+            return undefined;
+        try {
+            return JSON.parse(atob(cursor));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Decode a cursor, throwing a plain `Error` on malformed input.
+     *
+     * For a call site that treats a bad cursor as a client error; the HTTP mapping
+     * to `BadRequest` is the caller's layer's job (see the file header).
+     */
+    static decodeOrThrow(cursor) {
+        if (!cursor)
+            return undefined;
+        try {
+            return JSON.parse(atob(cursor));
+        }
+        catch {
+            throw new Error('Invalid cursor');
+        }
+    }
+    /**
+     * Whether a cursor is well-formed. A missing cursor is valid (first page).
+     */
+    static isValidCursor(cursor) {
+        if (!cursor)
+            return true;
+        try {
+            JSON.parse(atob(cursor));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Build a `Page`, omitting `nextCursor` entirely on the last page rather than
+     * carrying an explicit `undefined`.
+     */
+    static page(items, nextCursor) {
+        return nextCursor ? { items, nextCursor } : { items };
+    }
+}
+export { CursorCodec };
+//# sourceMappingURL=CursorCodec.js.map

package/dist/CursorCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CursorCodec.js","sourceRoot":"","sources":["../src/CursorCodec.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW;IACR,MAAM,CAAC,MAAM,CAAC,KAAc;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,MAAM,CAAI,MAAiC;QACvD,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAM,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,aAAa,CAAI,MAAiC;QAC9D,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAM,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,aAAa,CAAC,MAAiC;QAC3D,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,IAAI,CAAI,KAAmB,EAAE,UAAmB;QAC5D,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;CACF;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/EmailUtil.d.ts

@@ -0,0 +1,29 @@
+import { isValidEmailFormat, MAX_EMAIL_LENGTH } from './Identity';
+/**
+ * Email address value helpers.
+ *
+ * ## Provenance
+ *
+ * Converged from Durable-DAV's `EmailUtil.ts` (a shape check) and Mail-Meow's
+ * `EmailUtil.ts` (address normalization). Durable-DAV's predicate `isValidEmailFormat`
+ * canonically lives in `Identity.ts` — the wider group's home, and the stricter
+ * of the two regexes found (see the merge note there) — and is re-exported here
+ * so `EmailUtil` is the one-stop surface for validation + normalization.
+ *
+ * `normalizeEmail` comes from Mail-Meow, whose header records why a single
+ * normalization rule is a correctness concern, not a cosmetic one: "This function
+ * used to exist four times, and the copies disagreed." One copy trimmed and
+ * lowercased, the others lowercased only, so `"  Alice@Example.com "` and
+ * `"alice@example.com"` were the same account to one layer and different accounts
+ * to another — a different account key on each side of a boundary, and a stored
+ * registry row that its own service could not resolve.
+ *
+ * ## Design decision
+ *
+ * The kit keeps `normalizeEmail` and re-exports the validator; it does not
+ * re-introduce Edge-Git's `EmailAddress` value class, which is sugar over the
+ * same trim+lowercase and would be a second spelling of the same rule.
+ */
+declare function normalizeEmail(email: string): string;
+export { normalizeEmail, isValidEmailFormat, MAX_EMAIL_LENGTH };
+//# sourceMappingURL=EmailUtil.d.ts.map

package/dist/EmailUtil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmailUtil.d.ts","sourceRoot":"","sources":["../src/EmailUtil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iBAAS,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,CAAC"}