@smthrs/sync 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/internal/PolicyOptions.js

@@ -0,0 +1,70 @@
+/**
+ * Execution-time validation of the numeric policies this package's
+ * constructors accept.
+ *
+ * Every `Options` field is typed `number`, and TypeScript admits `NaN`,
+ * `Infinity`, zero, and a negative under that type. Each of them disables the
+ * thing it configures rather than tightening it: `maxFrameBytes: NaN` makes
+ * every `bytes > maxFrameBytes` comparison false, so the ceiling silently
+ * stops existing; `concurrency: 0` reaches a bounded `Stream.flatMap`
+ * unchecked. A policy is checked once, where it enters, and a bad one is a
+ * typed refusal rather than a bound that quietly does nothing.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import { SyncError } from "../SyncError.js";
+/**
+ * The caller's value when it is a positive safe integer, the fallback when the
+ * caller supplied none, and a typed `invalid_request` refusal otherwise. The
+ * message names the option so the offending field is identifiable without the
+ * error carrying anything but the scalar it was given.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const positiveInt = (name, value, fallback) => {
+    if (value === undefined)
+        return Effect.succeed(fallback);
+    return Number.isSafeInteger(value) && value > 0 ? Effect.succeed(value) : Effect.fail(new SyncError({
+        code: "invalid_request",
+        message: `${name} must be a positive safe integer, not ${value}`
+    }));
+};
+/**
+ * A count carried by a REQUEST rather than by a policy: floored at one,
+ * ceilinged at what the wire schema allows, and refused otherwise.
+ *
+ * `SyncProtocol` already bounds `limit` and `credit` on both sides, so a
+ * decoded request cannot carry a bad one. An in-process caller that builds the
+ * request value directly never meets that schema, and the TypeScript type it
+ * does meet is `number`: `NaN`, zero, and a negative all satisfy it. Each of
+ * them disables the bound instead of tightening it — `Math.min(NaN, ceiling)`
+ * is `NaN`, every `length >= NaN` comparison answers false, and the value
+ * reaches the journal as a page size — so the floor is checked here, where
+ * both callers share one refusal and one sentence.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const requestCount = (name, value, ceiling) => Number.isSafeInteger(value) && value > 0 ? Effect.succeed(Math.min(value, ceiling)) : Effect.fail(new SyncError({
+    code: "invalid_request",
+    message: `${name} must be a positive safe integer, not ${value}`
+}));
+/**
+ * {@link positiveInt} plus a ceiling, for a policy the WIRE also bounds.
+ *
+ * A value the local schema would accept and the wire schema would refuse is
+ * not a transport failure, but that is what it looked like: the RPC client's
+ * own decode failure arrived through the same channel a dropped connection
+ * does, and the follow retried it under backoff forever. The refusal belongs
+ * here, before a request is built.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const boundedInt = (name, value, fallback, maximum) => Effect.flatMap(positiveInt(name, value, fallback), (accepted) => accepted <= maximum ? Effect.succeed(accepted) : Effect.fail(new SyncError({
+    code: "invalid_request",
+    message: `${name} must be at most ${maximum}, not ${accepted}`
+})));
+//# sourceMappingURL=PolicyOptions.js.map

package/dist/esm/internal/PolicyOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyOptions.js","sourceRoot":"","sources":["../../../src/internal/PolicyOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,IAAY,EACZ,KAAyB,EACzB,QAAgB,EACkB,EAAE;IACpC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACxD,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CACnF,IAAI,SAAS,CAAC;QACZ,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,GAAG,IAAI,yCAAyC,KAAK,EAAE;KACjE,CAAC,CACH,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,IAAY,EACZ,KAAa,EACb,OAAe,EACmB,EAAE,CACpC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAC/F,IAAI,SAAS,CAAC;IACZ,IAAI,EAAE,iBAAiB;IACvB,OAAO,EAAE,GAAG,IAAI,yCAAyC,KAAK,EAAE;CACjE,CAAC,CACH,CAAA;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,IAAY,EACZ,KAAyB,EACzB,QAAgB,EAChB,OAAe,EACmB,EAAE,CACpC,MAAM,CAAC,OAAO,CACZ,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,EAClC,CAAC,QAAQ,EAAE,EAAE,CACX,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAC1D,IAAI,SAAS,CAAC;IACZ,IAAI,EAAE,iBAAiB;IACvB,OAAO,EAAE,GAAG,IAAI,oBAAoB,OAAO,SAAS,QAAQ,EAAE;CAC/D,CAAC,CACH,CACJ,CAAA","sourcesContent":["/**\n * Execution-time validation of the numeric policies this package's\n * constructors accept.\n *\n * Every `Options` field is typed `number`, and TypeScript admits `NaN`,\n * `Infinity`, zero, and a negative under that type. Each of them disables the\n * thing it configures rather than tightening it: `maxFrameBytes: NaN` makes\n * every `bytes > maxFrameBytes` comparison false, so the ceiling silently\n * stops existing; `concurrency: 0` reaches a bounded `Stream.flatMap`\n * unchecked. A policy is checked once, where it enters, and a bad one is a\n * typed refusal rather than a bound that quietly does nothing.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport { SyncError } from \"../SyncError.ts\"\n\n/**\n * The caller's value when it is a positive safe integer, the fallback when the\n * caller supplied none, and a typed `invalid_request` refusal otherwise. The\n * message names the option so the offending field is identifiable without the\n * error carrying anything but the scalar it was given.\n *\n * @category validation\n * @since 1.0.0-rc.0\n */\nexport const positiveInt = (\n  name: string,\n  value: number | undefined,\n  fallback: number\n): Effect.Effect<number, SyncError> => {\n  if (value === undefined) return Effect.succeed(fallback)\n  return Number.isSafeInteger(value) && value > 0 ? Effect.succeed(value) : Effect.fail(\n    new SyncError({\n      code: \"invalid_request\",\n      message: `${name} must be a positive safe integer, not ${value}`\n    })\n  )\n}\n\n/**\n * A count carried by a REQUEST rather than by a policy: floored at one,\n * ceilinged at what the wire schema allows, and refused otherwise.\n *\n * `SyncProtocol` already bounds `limit` and `credit` on both sides, so a\n * decoded request cannot carry a bad one. An in-process caller that builds the\n * request value directly never meets that schema, and the TypeScript type it\n * does meet is `number`: `NaN`, zero, and a negative all satisfy it. Each of\n * them disables the bound instead of tightening it — `Math.min(NaN, ceiling)`\n * is `NaN`, every `length >= NaN` comparison answers false, and the value\n * reaches the journal as a page size — so the floor is checked here, where\n * both callers share one refusal and one sentence.\n *\n * @category validation\n * @since 1.0.0-rc.0\n */\nexport const requestCount = (\n  name: string,\n  value: number,\n  ceiling: number\n): Effect.Effect<number, SyncError> =>\n  Number.isSafeInteger(value) && value > 0 ? Effect.succeed(Math.min(value, ceiling)) : Effect.fail(\n    new SyncError({\n      code: \"invalid_request\",\n      message: `${name} must be a positive safe integer, not ${value}`\n    })\n  )\n\n/**\n * {@link positiveInt} plus a ceiling, for a policy the WIRE also bounds.\n *\n * A value the local schema would accept and the wire schema would refuse is\n * not a transport failure, but that is what it looked like: the RPC client's\n * own decode failure arrived through the same channel a dropped connection\n * does, and the follow retried it under backoff forever. The refusal belongs\n * here, before a request is built.\n *\n * @category validation\n * @since 1.0.0-rc.0\n */\nexport const boundedInt = (\n  name: string,\n  value: number | undefined,\n  fallback: number,\n  maximum: number\n): Effect.Effect<number, SyncError> =>\n  Effect.flatMap(\n    positiveInt(name, value, fallback),\n    (accepted) =>\n      accepted <= maximum ? Effect.succeed(accepted) : Effect.fail(\n        new SyncError({\n          code: \"invalid_request\",\n          message: `${name} must be at most ${maximum}, not ${accepted}`\n        })\n      )\n  )\n"]}

package/dist/esm/internal/ProtocolVersion.d.ts

@@ -0,0 +1,17 @@
+/** The one protocol-version comparison every sync boundary answers with.
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import { SyncError } from "../SyncError.ts";
+/** Refuse a version this revision does not speak, on every path, with one code.
+ *
+ * Read, subscribe and snapshot all decode a mismatched version so the refusal
+ * is this typed `protocol_violation` rather than three different decode
+ * failures, and the accepted number is only ever
+ * {@link SyncProtocol.protocolVersion}.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export declare const requireVersion: (version: number | undefined) => Effect.Effect<void, SyncError>;
+//# sourceMappingURL=ProtocolVersion.d.ts.map

package/dist/esm/internal/ProtocolVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProtocolVersion.d.ts","sourceRoot":"","sources":["../../../src/internal/ProtocolVersion.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG3C;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,GAAG,SAAS,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CASrF,CAAA"}

package/dist/esm/internal/ProtocolVersion.js

@@ -0,0 +1,24 @@
+/** The one protocol-version comparison every sync boundary answers with.
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import { SyncError } from "../SyncError.js";
+import { protocolVersion } from "../SyncProtocol.js";
+/** Refuse a version this revision does not speak, on every path, with one code.
+ *
+ * Read, subscribe and snapshot all decode a mismatched version so the refusal
+ * is this typed `protocol_violation` rather than three different decode
+ * failures, and the accepted number is only ever
+ * {@link SyncProtocol.protocolVersion}.
+ *
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const requireVersion = (version) => version === protocolVersion
+    ? Effect.void
+    : Effect.fail(new SyncError({
+        code: "protocol_violation",
+        message: `Expected sync protocol version ${protocolVersion}; received ${version}`,
+        cause: "protocol_version_mismatch"
+    }));
+//# sourceMappingURL=ProtocolVersion.js.map

package/dist/esm/internal/ProtocolVersion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProtocolVersion.js","sourceRoot":"","sources":["../../../src/internal/ProtocolVersion.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEpD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAA2B,EAAkC,EAAE,CAC5F,OAAO,KAAK,eAAe;IACzB,CAAC,CAAC,MAAM,CAAC,IAAI;IACb,CAAC,CAAC,MAAM,CAAC,IAAI,CACX,IAAI,SAAS,CAAC;QACZ,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,kCAAkC,eAAe,cAAc,OAAO,EAAE;QACjF,KAAK,EAAE,2BAA2B;KACnC,CAAC,CACH,CAAA","sourcesContent":["/** The one protocol-version comparison every sync boundary answers with.\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport { SyncError } from \"../SyncError.ts\"\nimport { protocolVersion } from \"../SyncProtocol.ts\"\n\n/** Refuse a version this revision does not speak, on every path, with one code.\n *\n * Read, subscribe and snapshot all decode a mismatched version so the refusal\n * is this typed `protocol_violation` rather than three different decode\n * failures, and the accepted number is only ever\n * {@link SyncProtocol.protocolVersion}.\n *\n * @category validation\n * @since 1.0.0-rc.0\n */\nexport const requireVersion = (version: number | undefined): Effect.Effect<void, SyncError> =>\n  version === protocolVersion\n    ? Effect.void\n    : Effect.fail(\n      new SyncError({\n        code: \"protocol_violation\",\n        message: `Expected sync protocol version ${protocolVersion}; received ${version}`,\n        cause: \"protocol_version_mismatch\"\n      })\n    )\n"]}

package/dist/esm/internal/ShareSigner.d.ts

@@ -0,0 +1,173 @@
+/**
+ * HMAC-SHA-256 signing primitives shared by the branch and workspace share
+ * authorities.
+ *
+ * Both authorities sign a length-prefixed encoding of their claims: without
+ * length prefixes a field ending in the separator could be re-cut into a
+ * different, still-validly-signed claim set. Web Crypto is used directly so
+ * the same module runs in the browser and on node, and signature comparison
+ * is length-independent so a check leaks no prefix length.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type { Access } from "../BranchProtocol.ts";
+import { SyncError } from "../SyncError.ts";
+/**
+ * Length-prefixes each field so no two distinct field sequences share an
+ * encoding.
+ *
+ * The prefix counts UTF-8 BYTES, not UTF-16 code units, because the bytes are
+ * what {@link signHmac} covers. Counting code units let a two-byte field claim
+ * length one, so the prefix no longer separated the fields the signature was
+ * taken over.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export declare const lengthPrefixed: (fields: ReadonlyArray<string>) => string;
+/**
+ * Whether a string is exactly what its own UTF-8 bytes decode back to.
+ *
+ * `TextEncoder` replaces every unpaired surrogate with U+FFFD, so two claim
+ * sets differing only in a lone surrogate sign to identical bytes: a
+ * capability minted for a lone-surrogate branch id verifies after its
+ * `branchId` is rewritten to U+FFFD, which names a different branch. A length
+ * prefix cannot separate them either, because both encode to the same three
+ * bytes. The only correct answer is to refuse such a claim set before it is
+ * signed, and the round trip is the exact question — does this string survive
+ * the encoding the signature is taken over — rather than a proxy for it.
+ *
+ * @category encoding
+ * @since 1.0.0-rc.0
+ */
+export declare const utf8RoundTrips: (value: string, bytes: Uint8Array) => boolean;
+/**
+ * Renders signature bytes as lowercase hex.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export declare const hex: (bytes: Uint8Array) => string;
+/**
+ * Length-independent comparison, so a signature check leaks no prefix length.
+ *
+ * @category comparison
+ * @since 0.1.0
+ */
+export declare const constantTimeEquals: (left: string, right: string) => boolean;
+/**
+ * The fewest UTF-8 bytes a signing secret may carry: the HMAC-SHA-256 output
+ * length, the minimum RFC 2104 section 3 recommends.
+ *
+ * Every capability carries its claims and their signature in the clear, so one
+ * observed capability is an offline oracle for the secret. A short secret such
+ * as `a` falls to exhaustive search in seconds, and the attacker then mints
+ * branch and workspace capabilities of their own.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export declare const minSecretBytes = 32;
+/**
+ * Imports a raw secret as a non-extractable Web Crypto HMAC-SHA-256 signing
+ * key. Fails with `invalid_request` when the secret does not survive UTF-8
+ * (an unpaired surrogate) or is shorter than {@link minSecretBytes}, and with
+ * a `SyncError` carrying the rejection as `cause` when Web Crypto refuses the
+ * import.
+ *
+ * @category crypto
+ * @since 0.1.0
+ */
+export declare const importHmacKey: (secret: string) => Effect.Effect<CryptoKey, SyncError>;
+/**
+ * Signs a canonical claim encoding, returning the signature as lowercase hex.
+ *
+ * @category crypto
+ * @since 0.1.0
+ */
+export declare const signHmac: (key: CryptoKey, canonical: string) => Effect.Effect<string, SyncError>;
+/**
+ * The refusal both authorities issue. Declared once so a message added to one
+ * authority's verification cannot land under a different error code in the
+ * other.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export declare const unauthorized: (message: string) => SyncError;
+/**
+ * One named signing key. The secret is `Redacted` so a keyring never renders
+ * it into logs or inspection output.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Key {
+    readonly kid: string;
+    readonly secret: Redacted.Redacted<string>;
+}
+/**
+ * A keyring: the key that signs new capabilities plus every key still
+ * accepted for verification. Rotation adds a new active key and keeps the
+ * retired one in `keys` until its outstanding capabilities expire.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Keyring {
+    readonly activeKid: string;
+    readonly keys: ReadonlyArray<Key>;
+}
+/**
+ * A keyring whose every secret is already an imported Web Crypto key: the
+ * signer for new capabilities, and the map a verifier selects a retired key
+ * from by `kid`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface ImportedKeyring {
+    readonly activeKid: string;
+    readonly active: CryptoKey;
+    readonly verification: ReadonlyMap<string, CryptoKey>;
+}
+/**
+ * Imports every key in a keyring, so a misconfigured ring — an unknown active
+ * kid, a duplicate kid, or a key Web Crypto refuses — fails at construction
+ * rather than at the first request. `subject` names the authority in the
+ * refusal ("branch", "workspace").
+ *
+ * @category crypto
+ * @since 1.0.0-rc.0
+ */
+export declare const importKeyring: (keyring: Keyring, subject: string) => Effect.Effect<ImportedKeyring, SyncError>;
+/**
+ * The authorization both capability authorities run once their signing key is
+ * selected: the signature, then the expiry, then the requested access.
+ *
+ * The order is the contract. A capability is authenticated before anything it
+ * claims is reported back, so a forged claim set is refused as a bad signature
+ * and never as a scope or an expiry. `scope` is the one check an authority
+ * adds for itself — the branch authority's cross-branch refusal — and it runs
+ * after the signature for exactly that reason.
+ *
+ * Both authorities called this sequence out by hand, which left a fix to the
+ * expiry boundary or the read-only refusal landing in one and not the other.
+ *
+ * @category crypto
+ * @since 1.0.0-rc.0
+ */
+export declare const verifyClaims: (options: {
+    readonly key: CryptoKey;
+    readonly canonical: string;
+    readonly signature: string;
+    readonly expiresAtMs: number;
+    readonly granted: Access;
+    readonly requested: Access;
+    /** The refused thing, named as it appears in the message: "The share capability". */
+    readonly subject: string;
+    readonly scope?: Effect.Effect<void, SyncError>;
+}) => Effect.Effect<void, SyncError>;
+//# sourceMappingURL=ShareSigner.d.ts.map

package/dist/esm/internal/ShareSigner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShareSigner.d.ts","sourceRoot":"","sources":["../../../src/internal/ShareSigner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAK3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,aAAa,CAAC,MAAM,CAAC,KAAG,MACa,CAAA;AAI5E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,OAAO,UAAU,KAAG,OAA0C,CAAA;AAE5G;;;;;GAKG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,UAAU,KAAG,MACkC,CAAA;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,KAAG,OAQhE,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,KAAK,CAAA;AAEhC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAiChF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,SAAS,EAAE,WAAW,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAsB3F,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,SAA6D,CAAA;AAE5G;;;;;;GAMG;AACH,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;CAC3C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,CAAA;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAC1B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;CACtD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,EAAE,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,SAAS,CA6BtG,CAAA;AAEJ;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS;IACpC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;CAChD,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAc7B,CAAA"}

package/dist/esm/internal/ShareSigner.js

@@ -0,0 +1,219 @@
+/**
+ * HMAC-SHA-256 signing primitives shared by the branch and workspace share
+ * authorities.
+ *
+ * Both authorities sign a length-prefixed encoding of their claims: without
+ * length prefixes a field ending in the separator could be re-cut into a
+ * different, still-validly-signed claim set. Web Crypto is used directly so
+ * the same module runs in the browser and on node, and signature comparison
+ * is length-independent so a check leaks no prefix length.
+ *
+ * @since 0.1.0
+ */
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { SyncError } from "../SyncError.js";
+import { causeText } from "./CauseText.js";
+const encoder = new TextEncoder();
+/**
+ * Length-prefixes each field so no two distinct field sequences share an
+ * encoding.
+ *
+ * The prefix counts UTF-8 BYTES, not UTF-16 code units, because the bytes are
+ * what {@link signHmac} covers. Counting code units let a two-byte field claim
+ * length one, so the prefix no longer separated the fields the signature was
+ * taken over.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export const lengthPrefixed = (fields) => fields.map((field) => `${encoder.encode(field).length}:${field}`).join("");
+const decoder = new TextDecoder();
+/**
+ * Whether a string is exactly what its own UTF-8 bytes decode back to.
+ *
+ * `TextEncoder` replaces every unpaired surrogate with U+FFFD, so two claim
+ * sets differing only in a lone surrogate sign to identical bytes: a
+ * capability minted for a lone-surrogate branch id verifies after its
+ * `branchId` is rewritten to U+FFFD, which names a different branch. A length
+ * prefix cannot separate them either, because both encode to the same three
+ * bytes. The only correct answer is to refuse such a claim set before it is
+ * signed, and the round trip is the exact question — does this string survive
+ * the encoding the signature is taken over — rather than a proxy for it.
+ *
+ * @category encoding
+ * @since 1.0.0-rc.0
+ */
+export const utf8RoundTrips = (value, bytes) => decoder.decode(bytes) === value;
+/**
+ * Renders signature bytes as lowercase hex.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+/**
+ * Length-independent comparison, so a signature check leaks no prefix length.
+ *
+ * @category comparison
+ * @since 0.1.0
+ */
+export const constantTimeEquals = (left, right) => {
+    let difference = left.length ^ right.length;
+    // `charCodeAt` past the end is NaN, and `NaN | 0` is 0, so the loop reads
+    // both strings to the longer length without an early return.
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        difference |= (left.charCodeAt(index) | 0) ^ (right.charCodeAt(index) | 0);
+    }
+    return difference === 0;
+};
+/**
+ * The fewest UTF-8 bytes a signing secret may carry: the HMAC-SHA-256 output
+ * length, the minimum RFC 2104 section 3 recommends.
+ *
+ * Every capability carries its claims and their signature in the clear, so one
+ * observed capability is an offline oracle for the secret. A short secret such
+ * as `a` falls to exhaustive search in seconds, and the attacker then mints
+ * branch and workspace capabilities of their own.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export const minSecretBytes = 32;
+/**
+ * Imports a raw secret as a non-extractable Web Crypto HMAC-SHA-256 signing
+ * key. Fails with `invalid_request` when the secret does not survive UTF-8
+ * (an unpaired surrogate) or is shorter than {@link minSecretBytes}, and with
+ * a `SyncError` carrying the rejection as `cause` when Web Crypto refuses the
+ * import.
+ *
+ * @category crypto
+ * @since 0.1.0
+ */
+export const importHmacKey = (secret) => {
+    // An unpaired surrogate encodes to U+FFFD's bytes, so two distinct
+    // secrets would import the same key and rotating between them revokes
+    // nothing. Refused here, as `signHmac` refuses such claims.
+    const bytes = encoder.encode(secret);
+    if (!utf8RoundTrips(secret, bytes)) {
+        return Effect.fail(new SyncError({
+            code: "invalid_request",
+            message: "The HMAC signing secret carries an unpaired surrogate"
+        }));
+    }
+    if (bytes.length < minSecretBytes) {
+        return Effect.fail(new SyncError({
+            code: "invalid_request",
+            message: `The HMAC signing secret must be at least ${minSecretBytes} bytes of UTF-8`
+        }));
+    }
+    return Effect.tryPromise({
+        try: () => crypto.subtle.importKey("raw", bytes, { name: "HMAC", hash: "SHA-256" }, false, [
+            "sign"
+        ]),
+        catch: (cause) => new SyncError({
+            code: "unknown",
+            message: "Web Crypto could not import the HMAC signing key",
+            cause: causeText(cause)
+        })
+    });
+};
+/**
+ * Signs a canonical claim encoding, returning the signature as lowercase hex.
+ *
+ * @category crypto
+ * @since 0.1.0
+ */
+export const signHmac = (key, canonical) => {
+    const bytes = encoder.encode(canonical);
+    if (!utf8RoundTrips(canonical, bytes)) {
+        return Effect.fail(new SyncError({
+            code: "invalid_request",
+            message: "Share claims carry an unpaired surrogate and cannot be signed"
+        }));
+    }
+    return Effect.map(Effect.tryPromise({
+        try: () => crypto.subtle.sign("HMAC", key, bytes),
+        catch: (cause) => new SyncError({
+            code: "unknown",
+            message: "Web Crypto could not sign the share claims",
+            cause: causeText(cause)
+        })
+    }), (signature) => hex(new Uint8Array(signature)));
+};
+/**
+ * The refusal both authorities issue. Declared once so a message added to one
+ * authority's verification cannot land under a different error code in the
+ * other.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export const unauthorized = (message) => new SyncError({ code: "unauthorized", message });
+/**
+ * Imports every key in a keyring, so a misconfigured ring — an unknown active
+ * kid, a duplicate kid, or a key Web Crypto refuses — fails at construction
+ * rather than at the first request. `subject` names the authority in the
+ * refusal ("branch", "workspace").
+ *
+ * @category crypto
+ * @since 1.0.0-rc.0
+ */
+export const importKeyring = (keyring, subject) => Effect.gen(function* () {
+    // Copied BEFORE the first import, for the reason snapshots exist on the
+    // verify path: the keyring belongs to the caller and every import below is
+    // an await, so a `for..of` over the caller's own array re-reads it between
+    // them. A splice landing in that window changed which keys the authority
+    // ended up holding, and reading `activeKid` only after the loop let it name
+    // a key the ring was validated with rather than the one the caller passed.
+    const activeKid = keyring.activeKid;
+    const keys = keyring.keys.map((key) => ({ kid: key.kid, secret: key.secret }));
+    const verification = new Map();
+    for (const key of keys) {
+        if (verification.has(key.kid)) {
+            return yield* Effect.fail(new SyncError({ code: "invalid_request", message: `The ${subject} keyring names kid ${key.kid} twice` }));
+        }
+        verification.set(key.kid, yield* importHmacKey(Redacted.value(key.secret)));
+    }
+    const active = verification.get(activeKid);
+    if (active === undefined) {
+        return yield* Effect.fail(new SyncError({
+            code: "invalid_request",
+            message: `The ${subject} keyring's active kid names no key in the ring`
+        }));
+    }
+    return { activeKid, active, verification };
+});
+/**
+ * The authorization both capability authorities run once their signing key is
+ * selected: the signature, then the expiry, then the requested access.
+ *
+ * The order is the contract. A capability is authenticated before anything it
+ * claims is reported back, so a forged claim set is refused as a bad signature
+ * and never as a scope or an expiry. `scope` is the one check an authority
+ * adds for itself — the branch authority's cross-branch refusal — and it runs
+ * after the signature for exactly that reason.
+ *
+ * Both authorities called this sequence out by hand, which left a fix to the
+ * expiry boundary or the read-only refusal landing in one and not the other.
+ *
+ * @category crypto
+ * @since 1.0.0-rc.0
+ */
+export const verifyClaims = (options) => Effect.gen(function* () {
+    const expected = yield* signHmac(options.key, options.canonical);
+    if (!constantTimeEquals(expected, options.signature)) {
+        return yield* Effect.fail(unauthorized(`${options.subject} signature is invalid`));
+    }
+    if (options.scope !== undefined)
+        yield* options.scope;
+    const nowMs = yield* Clock.currentTimeMillis;
+    if (nowMs >= options.expiresAtMs) {
+        return yield* Effect.fail(unauthorized(`${options.subject} has expired`));
+    }
+    if (options.requested === "write" && options.granted !== "write") {
+        return yield* Effect.fail(unauthorized(`${options.subject} is read-only`));
+    }
+});
+//# sourceMappingURL=ShareSigner.js.map

package/dist/esm/internal/ShareSigner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShareSigner.js","sourceRoot":"","sources":["../../../src/internal/ShareSigner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HMAC-SHA-256 signing primitives shared by the branch and workspace share\n * authorities.\n *\n * Both authorities sign a length-prefixed encoding of their claims: without\n * length prefixes a field ending in the separator could be re-cut into a\n * different, still-validly-signed claim set. Web Crypto is used directly so\n * the same module runs in the browser and on node, and signature comparison\n * is length-independent so a check leaks no prefix length.\n *\n * @since 0.1.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport * as Effect from \"effect/Effect\"\nimport * as Redacted from \"effect/Redacted\"\nimport type { Access } from \"../BranchProtocol.ts\"\nimport { SyncError } from \"../SyncError.ts\"\nimport { causeText } from \"./CauseText.ts\"\n\nconst encoder = new TextEncoder()\n\n/**\n * Length-prefixes each field so no two distinct field sequences share an\n * encoding.\n *\n * The prefix counts UTF-8 BYTES, not UTF-16 code units, because the bytes are\n * what {@link signHmac} covers. Counting code units let a two-byte field claim\n * length one, so the prefix no longer separated the fields the signature was\n * taken over.\n *\n * @category encoding\n * @since 0.1.0\n */\nexport const lengthPrefixed = (fields: ReadonlyArray<string>): string =>\n  fields.map((field) => `${encoder.encode(field).length}:${field}`).join(\"\")\n\nconst decoder = new TextDecoder()\n\n/**\n * Whether a string is exactly what its own UTF-8 bytes decode back to.\n *\n * `TextEncoder` replaces every unpaired surrogate with U+FFFD, so two claim\n * sets differing only in a lone surrogate sign to identical bytes: a\n * capability minted for a lone-surrogate branch id verifies after its\n * `branchId` is rewritten to U+FFFD, which names a different branch. A length\n * prefix cannot separate them either, because both encode to the same three\n * bytes. The only correct answer is to refuse such a claim set before it is\n * signed, and the round trip is the exact question — does this string survive\n * the encoding the signature is taken over — rather than a proxy for it.\n *\n * @category encoding\n * @since 1.0.0-rc.0\n */\nexport const utf8RoundTrips = (value: string, bytes: Uint8Array): boolean => decoder.decode(bytes) === value\n\n/**\n * Renders signature bytes as lowercase hex.\n *\n * @category encoding\n * @since 0.1.0\n */\nexport const hex = (bytes: Uint8Array): string =>\n  Array.from(bytes, (byte) => byte.toString(16).padStart(2, \"0\")).join(\"\")\n\n/**\n * Length-independent comparison, so a signature check leaks no prefix length.\n *\n * @category comparison\n * @since 0.1.0\n */\nexport const constantTimeEquals = (left: string, right: string): boolean => {\n  let difference = left.length ^ right.length\n  // `charCodeAt` past the end is NaN, and `NaN | 0` is 0, so the loop reads\n  // both strings to the longer length without an early return.\n  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {\n    difference |= (left.charCodeAt(index) | 0) ^ (right.charCodeAt(index) | 0)\n  }\n  return difference === 0\n}\n\n/**\n * The fewest UTF-8 bytes a signing secret may carry: the HMAC-SHA-256 output\n * length, the minimum RFC 2104 section 3 recommends.\n *\n * Every capability carries its claims and their signature in the clear, so one\n * observed capability is an offline oracle for the secret. A short secret such\n * as `a` falls to exhaustive search in seconds, and the attacker then mints\n * branch and workspace capabilities of their own.\n *\n * @category constants\n * @since 1.0.0-rc.1\n */\nexport const minSecretBytes = 32\n\n/**\n * Imports a raw secret as a non-extractable Web Crypto HMAC-SHA-256 signing\n * key. Fails with `invalid_request` when the secret does not survive UTF-8\n * (an unpaired surrogate) or is shorter than {@link minSecretBytes}, and with\n * a `SyncError` carrying the rejection as `cause` when Web Crypto refuses the\n * import.\n *\n * @category crypto\n * @since 0.1.0\n */\nexport const importHmacKey = (secret: string): Effect.Effect<CryptoKey, SyncError> => {\n  // An unpaired surrogate encodes to U+FFFD's bytes, so two distinct\n  // secrets would import the same key and rotating between them revokes\n  // nothing. Refused here, as `signHmac` refuses such claims.\n  const bytes = encoder.encode(secret)\n  if (!utf8RoundTrips(secret, bytes)) {\n    return Effect.fail(\n      new SyncError({\n        code: \"invalid_request\",\n        message: \"The HMAC signing secret carries an unpaired surrogate\"\n      })\n    )\n  }\n  if (bytes.length < minSecretBytes) {\n    return Effect.fail(\n      new SyncError({\n        code: \"invalid_request\",\n        message: `The HMAC signing secret must be at least ${minSecretBytes} bytes of UTF-8`\n      })\n    )\n  }\n  return Effect.tryPromise({\n    try: () =>\n      crypto.subtle.importKey(\"raw\", bytes, { name: \"HMAC\", hash: \"SHA-256\" }, false, [\n        \"sign\"\n      ]),\n    catch: (cause) =>\n      new SyncError({\n        code: \"unknown\",\n        message: \"Web Crypto could not import the HMAC signing key\",\n        cause: causeText(cause)\n      })\n  })\n}\n\n/**\n * Signs a canonical claim encoding, returning the signature as lowercase hex.\n *\n * @category crypto\n * @since 0.1.0\n */\nexport const signHmac = (key: CryptoKey, canonical: string): Effect.Effect<string, SyncError> => {\n  const bytes = encoder.encode(canonical)\n  if (!utf8RoundTrips(canonical, bytes)) {\n    return Effect.fail(\n      new SyncError({\n        code: \"invalid_request\",\n        message: \"Share claims carry an unpaired surrogate and cannot be signed\"\n      })\n    )\n  }\n  return Effect.map(\n    Effect.tryPromise({\n      try: () => crypto.subtle.sign(\"HMAC\", key, bytes),\n      catch: (cause) =>\n        new SyncError({\n          code: \"unknown\",\n          message: \"Web Crypto could not sign the share claims\",\n          cause: causeText(cause)\n        })\n    }),\n    (signature) => hex(new Uint8Array(signature))\n  )\n}\n\n/**\n * The refusal both authorities issue. Declared once so a message added to one\n * authority's verification cannot land under a different error code in the\n * other.\n *\n * @category errors\n * @since 1.0.0-rc.0\n */\nexport const unauthorized = (message: string): SyncError => new SyncError({ code: \"unauthorized\", message })\n\n/**\n * One named signing key. The secret is `Redacted` so a keyring never renders\n * it into logs or inspection output.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Key {\n  readonly kid: string\n  readonly secret: Redacted.Redacted<string>\n}\n\n/**\n * A keyring: the key that signs new capabilities plus every key still\n * accepted for verification. Rotation adds a new active key and keeps the\n * retired one in `keys` until its outstanding capabilities expire.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Keyring {\n  readonly activeKid: string\n  readonly keys: ReadonlyArray<Key>\n}\n\n/**\n * A keyring whose every secret is already an imported Web Crypto key: the\n * signer for new capabilities, and the map a verifier selects a retired key\n * from by `kid`.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface ImportedKeyring {\n  readonly activeKid: string\n  readonly active: CryptoKey\n  readonly verification: ReadonlyMap<string, CryptoKey>\n}\n\n/**\n * Imports every key in a keyring, so a misconfigured ring — an unknown active\n * kid, a duplicate kid, or a key Web Crypto refuses — fails at construction\n * rather than at the first request. `subject` names the authority in the\n * refusal (\"branch\", \"workspace\").\n *\n * @category crypto\n * @since 1.0.0-rc.0\n */\nexport const importKeyring = (keyring: Keyring, subject: string): Effect.Effect<ImportedKeyring, SyncError> =>\n  Effect.gen(function*() {\n    // Copied BEFORE the first import, for the reason snapshots exist on the\n    // verify path: the keyring belongs to the caller and every import below is\n    // an await, so a `for..of` over the caller's own array re-reads it between\n    // them. A splice landing in that window changed which keys the authority\n    // ended up holding, and reading `activeKid` only after the loop let it name\n    // a key the ring was validated with rather than the one the caller passed.\n    const activeKid = keyring.activeKid\n    const keys = keyring.keys.map((key): Key => ({ kid: key.kid, secret: key.secret }))\n    const verification = new Map<string, CryptoKey>()\n    for (const key of keys) {\n      if (verification.has(key.kid)) {\n        return yield* Effect.fail(\n          new SyncError({ code: \"invalid_request\", message: `The ${subject} keyring names kid ${key.kid} twice` })\n        )\n      }\n      verification.set(key.kid, yield* importHmacKey(Redacted.value(key.secret)))\n    }\n    const active = verification.get(activeKid)\n    if (active === undefined) {\n      return yield* Effect.fail(\n        new SyncError({\n          code: \"invalid_request\",\n          message: `The ${subject} keyring's active kid names no key in the ring`\n        })\n      )\n    }\n    return { activeKid, active, verification }\n  })\n\n/**\n * The authorization both capability authorities run once their signing key is\n * selected: the signature, then the expiry, then the requested access.\n *\n * The order is the contract. A capability is authenticated before anything it\n * claims is reported back, so a forged claim set is refused as a bad signature\n * and never as a scope or an expiry. `scope` is the one check an authority\n * adds for itself — the branch authority's cross-branch refusal — and it runs\n * after the signature for exactly that reason.\n *\n * Both authorities called this sequence out by hand, which left a fix to the\n * expiry boundary or the read-only refusal landing in one and not the other.\n *\n * @category crypto\n * @since 1.0.0-rc.0\n */\nexport const verifyClaims = (options: {\n  readonly key: CryptoKey\n  readonly canonical: string\n  readonly signature: string\n  readonly expiresAtMs: number\n  readonly granted: Access\n  readonly requested: Access\n  /** The refused thing, named as it appears in the message: \"The share capability\". */\n  readonly subject: string\n  readonly scope?: Effect.Effect<void, SyncError>\n}): Effect.Effect<void, SyncError> =>\n  Effect.gen(function*() {\n    const expected = yield* signHmac(options.key, options.canonical)\n    if (!constantTimeEquals(expected, options.signature)) {\n      return yield* Effect.fail(unauthorized(`${options.subject} signature is invalid`))\n    }\n    if (options.scope !== undefined) yield* options.scope\n    const nowMs = yield* Clock.currentTimeMillis\n    if (nowMs >= options.expiresAtMs) {\n      return yield* Effect.fail(unauthorized(`${options.subject} has expired`))\n    }\n    if (options.requested === \"write\" && options.granted !== \"write\") {\n      return yield* Effect.fail(unauthorized(`${options.subject} is read-only`))\n    }\n  })\n"]}

package/dist/esm/internal/SnapshotBoundary.d.ts

@@ -0,0 +1,17 @@
+/** Snapshot validation shared by the hosted and browser-side boundaries.
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import { SyncError } from "../SyncError.ts";
+import * as Protocol from "../SyncProtocol.ts";
+/** Decode a detached request before callbacks can mutate its expected identity.
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export declare const request: (value: unknown) => Effect.Effect<Protocol.SnapshotRequest, SyncError>;
+/** Copy JSON bytes once, bound them, then check the exact requested projection.
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export declare const response: (expected: Protocol.SnapshotRequest, value: unknown, maxBytes: number) => Effect.Effect<Protocol.Snapshot, SyncError>;
+//# sourceMappingURL=SnapshotBoundary.d.ts.map

package/dist/esm/internal/SnapshotBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotBoundary.d.ts","sourceRoot":"","sources":["../../../src/internal/SnapshotBoundary.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,QAAQ,MAAM,oBAAoB,CAAA;AAI9C;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAUvF,CAAA;AAEH;;;GAGG;AACH,eAAO,MAAM,QAAQ,GACnB,UAAU,QAAQ,CAAC,eAAe,EAClC,OAAO,OAAO,EACd,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAuDzC,CAAA"}