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

package/dist/cjs/BranchShare.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Share capabilities: the authorization boundary of a shared branch.
+ *
+ * A share link carries a capability, not a session. The capability names
+ * exactly one branch, one access level, and one expiry, and it is signed, so
+ * the holder cannot widen it. Every branch operation authorizes through
+ * `verify`, which is therefore the single place cross-branch access and
+ * expired links are refused.
+ *
+ * The signature is HMAC-SHA-256 over a length-prefixed encoding of the claims,
+ * led by a scheme label. Length prefixes matter: without them a branch id
+ * ending in the separator could be re-cut into a different, still-validly-
+ * signed claim set. The label matters for the same reason across schemes: a
+ * branch capability can never verify as a workspace capability even if one
+ * secret is misconfigured into both authorities. Web Crypto is used directly
+ * so the same module runs in the browser and on node.
+ *
+ * A `kid` inside the claims names the key that signed them, so a branch secret
+ * rotates the way the workspace secret already did: the new key signs, the
+ * retired key stays in the verification keyring, and the share links already
+ * out keep working until they expire.
+ *
+ * @since 0.1.0
+ */
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { Access, BranchId, ShareCapability, ShareClaims } from "./BranchProtocol.ts";
+import * as shareSigner from "./internal/ShareSigner.ts";
+import type { SyncError } from "./SyncError.ts";
+/**
+ * The branch and access one authorization request needs.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface AuthorizeRequest {
+    readonly branchId: BranchId;
+    readonly access: Access;
+}
+/**
+ * What a freshly minted capability grants.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const MintRequest: Schema.Struct<{
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly capabilityId: Schema.NonEmptyString;
+    readonly access: Schema.Literals<readonly ["read", "write"]>;
+    readonly ttlMs: Schema.Int;
+    /** Absolute expiry ceiling for a capability delegated from a parent. */
+    readonly maxExpiresAtMs: Schema.optionalKey<Schema.Int>;
+}>;
+/**
+ * What a freshly minted capability grants.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type MintRequest = typeof MintRequest.Type;
+/**
+ * Share capability operations.
+ *
+ * `mint` fails with a `SyncError` when the Web Crypto signing operation
+ * rejects or the absolute expiry ceiling has elapsed; `verify` fails with a
+ * `SyncError` when signing rejects or the capability is refused.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly mint: (request: MintRequest) => Effect.Effect<ShareCapability, SyncError>;
+    readonly verify: (capability: ShareCapability, request: AuthorizeRequest) => Effect.Effect<ShareClaims, SyncError>;
+}
+declare const BranchShare_base: Context.ServiceClass<BranchShare, "@smthrs/sync/BranchShare", Service>;
+/**
+ * The branch share-capability authority.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class BranchShare extends BranchShare_base {
+}
+/**
+ * Constructs a share authority that mints nothing and trusts nothing.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides a share authority that refuses every capability.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<BranchShare>;
+/**
+ * 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 type Key = shareSigner.Key;
+/**
+ * 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 links expire, so rotating the
+ * branch secret no longer breaks every share link that is already out.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Keyring = shareSigner.Keyring;
+/**
+ * Constructs the HMAC-SHA-256 share authority over a keyring.
+ *
+ * Every key is imported up front, so a misconfigured keyring — an unknown
+ * active kid, a duplicate kid, or a key Web Crypto refuses — fails at
+ * construction rather than at the first request. Secrets enter as `Redacted`
+ * values: an authority never holds a plain string that a log, a span, or an
+ * inspection of the keyring could render.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeHmac: (keyring: Keyring) => Effect.Effect<Service, SyncError>;
+/**
+ * Provides the HMAC-SHA-256 share authority over a keyring.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerHmac: (keyring: Keyring) => Layer.Layer<BranchShare, SyncError>;
+/**
+ * Provides the branch share authority from configuration: the secret from
+ * `SMITHERS_SYNC_BRANCH_SECRET` (read as `Redacted`, never logged) and the key
+ * name from `SMITHERS_SYNC_BRANCH_KEY_ID`, defaulting to `primary`. Rotation
+ * beyond one configured key uses {@link layerHmac} with an explicit keyring.
+ *
+ * The names are the branch authority's own, not the workspace's: the scheme
+ * label makes one secret in both authorities survivable, not advisable, and a
+ * deployment that rotates one credential should not silently invalidate the
+ * other's outstanding capabilities.
+ *
+ * There is deliberately no default secret: a deployment that configures
+ * neither name fails to construct the authority, and every branch operation
+ * stays closed.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerConfig: Layer.Layer<BranchShare, SyncError | Config.ConfigError>;
+export {};
+//# sourceMappingURL=BranchShare.d.ts.map

package/dist/cjs/BranchShare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchShare.d.ts","sourceRoot":"","sources":["../../src/BranchShare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEpF,OAAO,KAAK,WAAW,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;IAKtB,wEAAwE;;EAExE,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAA;IAClF,QAAQ,CAAC,MAAM,EAAE,CACf,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,gBAAgB,KACtB,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;CAC3C;;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,gBAAmE;CAAG;AAIvG;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,YAAW,OAAO,CAAC,OAAO,CAAM,KAAG,OAQxD,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,CAA0C,CAAA;AA0CzF;;;;;;GAMG;AACH,MAAM,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAA;AAEjC;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAA;AAEzC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAkEzE,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,OAAO,KAAG,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,SAAS,CACjC,CAAA;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,SAAS,GAAG,MAAM,CAAC,WAAW,CAOhF,CAAA"}

package/dist/cjs/BranchShare.js

@@ -0,0 +1,147 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var BranchShare_exports = {};
+__export(BranchShare_exports, {
+  BranchShare: () => BranchShare,
+  MintRequest: () => MintRequest,
+  layerConfig: () => layerConfig,
+  layerHmac: () => layerHmac,
+  layerNoop: () => layerNoop,
+  makeHmac: () => makeHmac,
+  makeNoop: () => makeNoop
+});
+module.exports = __toCommonJS(BranchShare_exports);
+var Clock = __toESM(require("effect/Clock"), 1);
+var Config = __toESM(require("effect/Config"), 1);
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_BranchProtocol = require("./BranchProtocol.js");
+var Admission = __toESM(require("./internal/Admission.js"), 1);
+var shareSigner = __toESM(require("./internal/ShareSigner.js"), 1);
+const MintRequest = Schema.Struct({
+  branchId: import_BranchProtocol.BranchId,
+  capabilityId: Schema.NonEmptyString,
+  access: import_BranchProtocol.Access,
+  ttlMs: Schema.Int.check(Schema.isGreaterThan(0)),
+  /** Absolute expiry ceiling for a capability delegated from a parent. */
+  maxExpiresAtMs: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+});
+class BranchShare extends Context.Service()("@smthrs/sync/BranchShare") {
+}
+const denied = shareSigner.unauthorized;
+const makeNoop = (overrides = {}) => BranchShare.of({
+  // Both operations FAIL. `mint` used to die, which contradicted its own
+  // declared `Effect<ShareCapability, SyncError>` and left a consumer
+  // wired to this authority unable to tell "sharing is off" from a bug.
+  mint: () => Effect.fail(denied("Branch sharing is unavailable")),
+  verify: () => Effect.fail(denied("Branch sharing is unavailable")),
+  ...overrides
+});
+const layerNoop = Layer.succeed(BranchShare, makeNoop());
+const schemeLabel = "@smthrs/sync/BranchShare/v2";
+const canonical = (claims) => shareSigner.lengthPrefixed([
+  schemeLabel,
+  claims.kid,
+  claims.branchId,
+  claims.capabilityId,
+  claims.access,
+  String(claims.issuedAtMs),
+  String(claims.expiresAtMs)
+]);
+const snapshot = (claims) => new import_BranchProtocol.ShareClaims({
+  kid: claims.kid,
+  branchId: claims.branchId,
+  capabilityId: claims.capabilityId,
+  access: claims.access,
+  issuedAtMs: claims.issuedAtMs,
+  expiresAtMs: claims.expiresAtMs
+});
+const makeHmac = (keyring) => Effect.map(
+  shareSigner.importKeyring(keyring, "branch"),
+  (ring) => {
+    const mint = Effect.fn("BranchShare.mint")(function* (request) {
+      const admitted = yield* Admission.decode(MintRequest, request, "invalid_request");
+      yield* Effect.annotateCurrentSpan({ branchId: admitted.branchId, access: admitted.access });
+      const issuedAtMs = yield* Clock.currentTimeMillis;
+      const maxExpiresAtMs = admitted.maxExpiresAtMs ?? Infinity;
+      if (issuedAtMs >= maxExpiresAtMs) {
+        return yield* Effect.fail(denied("The share capability has expired"));
+      }
+      const claims = new import_BranchProtocol.ShareClaims({
+        kid: ring.activeKid,
+        branchId: admitted.branchId,
+        capabilityId: admitted.capabilityId,
+        access: admitted.access,
+        issuedAtMs,
+        expiresAtMs: Math.min(issuedAtMs + admitted.ttlMs, maxExpiresAtMs)
+      });
+      return new import_BranchProtocol.ShareCapability({
+        claims,
+        signature: yield* shareSigner.signHmac(ring.active, canonical(claims))
+      });
+    });
+    const verify = Effect.fn("BranchShare.verify")(function* (capability, request) {
+      yield* Effect.annotateCurrentSpan({ branchId: request.branchId, access: request.access });
+      const claims = snapshot(capability.claims);
+      const signature = capability.signature;
+      const branchId = request.branchId;
+      const key = ring.verification.get(claims.kid);
+      if (key === void 0) {
+        return yield* Effect.fail(denied("The share capability names an unknown signing key"));
+      }
+      yield* shareSigner.verifyClaims({
+        key,
+        canonical: canonical(claims),
+        signature,
+        expiresAtMs: claims.expiresAtMs,
+        granted: claims.access,
+        requested: request.access,
+        subject: "The share capability",
+        // The one check this authority adds, run after the signature so a
+        // forged claim set is refused as a bad signature and never reported
+        // back as the branch it names.
+        scope: claims.branchId === branchId ? Effect.void : Effect.fail(denied(`The share capability is scoped to branch ${claims.branchId}`))
+      });
+      return claims;
+    });
+    return BranchShare.of({ mint, verify });
+  }
+);
+const layerHmac = (keyring) => Layer.effect(BranchShare, makeHmac(keyring));
+const layerConfig = Layer.effect(
+  BranchShare,
+  Effect.gen(function* () {
+    const secret = yield* Config.Redacted("SMITHERS_SYNC_BRANCH_SECRET");
+    const kid = yield* Config.String("SMITHERS_SYNC_BRANCH_KEY_ID").pipe(Config.withDefault("primary"));
+    return yield* makeHmac({ activeKid: kid, keys: [{ kid, secret }] });
+  })
+);
+//# sourceMappingURL=BranchShare.js.map

package/dist/cjs/BranchShare.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/BranchShare.ts"],
+  "sourcesContent": ["/**\n * Share capabilities: the authorization boundary of a shared branch.\n *\n * A share link carries a capability, not a session. The capability names\n * exactly one branch, one access level, and one expiry, and it is signed, so\n * the holder cannot widen it. Every branch operation authorizes through\n * `verify`, which is therefore the single place cross-branch access and\n * expired links are refused.\n *\n * The signature is HMAC-SHA-256 over a length-prefixed encoding of the claims,\n * led by a scheme label. Length prefixes matter: without them a branch id\n * ending in the separator could be re-cut into a different, still-validly-\n * signed claim set. The label matters for the same reason across schemes: a\n * branch capability can never verify as a workspace capability even if one\n * secret is misconfigured into both authorities. Web Crypto is used directly\n * so the same module runs in the browser and on node.\n *\n * A `kid` inside the claims names the key that signed them, so a branch secret\n * rotates the way the workspace secret already did: the new key signs, the\n * retired key stays in the verification keyring, and the share links already\n * out keep working until they expire.\n *\n * @since 0.1.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport * as Config from \"effect/Config\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport { Access, BranchId, ShareCapability, ShareClaims } from \"./BranchProtocol.ts\"\nimport * as Admission from \"./internal/Admission.ts\"\nimport * as shareSigner from \"./internal/ShareSigner.ts\"\nimport type { SyncError } from \"./SyncError.ts\"\n\n/**\n * The branch and access one authorization request needs.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface AuthorizeRequest {\n  readonly branchId: BranchId\n  readonly access: Access\n}\n\n/**\n * What a freshly minted capability grants.\n *\n * @category models\n * @since 0.1.0\n */\nexport const MintRequest = Schema.Struct({\n  branchId: BranchId,\n  capabilityId: Schema.NonEmptyString,\n  access: Access,\n  ttlMs: Schema.Int.check(Schema.isGreaterThan(0)),\n  /** Absolute expiry ceiling for a capability delegated from a parent. */\n  maxExpiresAtMs: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))\n})\n\n/**\n * What a freshly minted capability grants.\n *\n * @category models\n * @since 0.1.0\n */\nexport type MintRequest = typeof MintRequest.Type\n\n/**\n * Share capability operations.\n *\n * `mint` fails with a `SyncError` when the Web Crypto signing operation\n * rejects or the absolute expiry ceiling has elapsed; `verify` fails with a\n * `SyncError` when signing rejects or the capability is refused.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  readonly mint: (request: MintRequest) => Effect.Effect<ShareCapability, SyncError>\n  readonly verify: (\n    capability: ShareCapability,\n    request: AuthorizeRequest\n  ) => Effect.Effect<ShareClaims, SyncError>\n}\n\n/**\n * The branch share-capability authority.\n *\n * @category services\n * @since 0.1.0\n */\nexport class BranchShare extends Context.Service<BranchShare, Service>()(\"@smthrs/sync/BranchShare\") {}\n\nconst denied = shareSigner.unauthorized\n\n/**\n * Constructs a share authority that mints nothing and trusts nothing.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeNoop = (overrides: Partial<Service> = {}): Service =>\n  BranchShare.of({\n    // Both operations FAIL. `mint` used to die, which contradicted its own\n    // declared `Effect<ShareCapability, SyncError>` and left a consumer\n    // wired to this authority unable to tell \"sharing is off\" from a bug.\n    mint: () => Effect.fail(denied(\"Branch sharing is unavailable\")),\n    verify: () => Effect.fail(denied(\"Branch sharing is unavailable\")),\n    ...overrides\n  })\n\n/**\n * Provides a share authority that refuses every capability.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop: Layer.Layer<BranchShare> = Layer.succeed(BranchShare, makeNoop())\n\n/**\n * Domain separation: the label leads the signed encoding, so a branch\n * signature can never be replayed as a workspace signature (or any later\n * scheme's) under a shared secret. `WorkspaceShare` has always led with its\n * own label; a one-sided label protects one direction, and the branch side is\n * the one anonymous share-link holders reach.\n */\nconst schemeLabel = \"@smthrs/sync/BranchShare/v2\"\n\n/** Length-prefixed so no two distinct claim sets share an encoding. */\nconst canonical = (claims: ShareClaims): string =>\n  shareSigner.lengthPrefixed([\n    schemeLabel,\n    claims.kid,\n    claims.branchId,\n    claims.capabilityId,\n    claims.access,\n    String(claims.issuedAtMs),\n    String(claims.expiresAtMs)\n  ])\n\n/**\n * The claim fields, copied out of the capability the caller owns.\n *\n * `Schema.Class` instances are not frozen, and `verify` awaits Web Crypto\n * between signing the claims and authorizing them. Reading the caller's object\n * again after the await let an in-process holder of the same instance widen\n * `access` \u2014 or move `expiresAtMs` \u2014 between the signature that was checked\n * and the checks that follow it.\n */\nconst snapshot = (claims: ShareClaims): ShareClaims =>\n  new ShareClaims({\n    kid: claims.kid,\n    branchId: claims.branchId,\n    capabilityId: claims.capabilityId,\n    access: claims.access,\n    issuedAtMs: claims.issuedAtMs,\n    expiresAtMs: claims.expiresAtMs\n  })\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 type Key = shareSigner.Key\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 links expire, so rotating the\n * branch secret no longer breaks every share link that is already out.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Keyring = shareSigner.Keyring\n\n/**\n * Constructs the HMAC-SHA-256 share authority over a keyring.\n *\n * Every key is imported up front, so a misconfigured keyring \u2014 an unknown\n * active kid, a duplicate kid, or a key Web Crypto refuses \u2014 fails at\n * construction rather than at the first request. Secrets enter as `Redacted`\n * values: an authority never holds a plain string that a log, a span, or an\n * inspection of the keyring could render.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeHmac = (keyring: Keyring): Effect.Effect<Service, SyncError> =>\n  Effect.map(\n    shareSigner.importKeyring(keyring, \"branch\"),\n    (ring) => {\n      const mint = Effect.fn(\"BranchShare.mint\")(function*(request: MintRequest) {\n        // Decoded, not read: the declared parameter type admits an empty\n        // branch id, an empty capability id and a non-positive ttl that the\n        // schema forbids, and reading them straight into `new ShareClaims`\n        // turned a caller's bad argument into a defect out of an operation\n        // whose type promises a `SyncError`. A `ttlMs` of 0 minted an\n        // already-expired capability instead of being refused.\n        const admitted = yield* Admission.decode(MintRequest, request, \"invalid_request\")\n        yield* Effect.annotateCurrentSpan({ branchId: admitted.branchId, access: admitted.access })\n        const issuedAtMs = yield* Clock.currentTimeMillis\n        const maxExpiresAtMs = admitted.maxExpiresAtMs ?? Infinity\n        if (issuedAtMs >= maxExpiresAtMs) {\n          return yield* Effect.fail(denied(\"The share capability has expired\"))\n        }\n        const claims = new ShareClaims({\n          kid: ring.activeKid,\n          branchId: admitted.branchId,\n          capabilityId: admitted.capabilityId,\n          access: admitted.access,\n          issuedAtMs,\n          expiresAtMs: Math.min(issuedAtMs + admitted.ttlMs, maxExpiresAtMs)\n        })\n        return new ShareCapability({\n          claims,\n          signature: yield* shareSigner.signHmac(ring.active, canonical(claims))\n        })\n      })\n\n      const verify = Effect.fn(\"BranchShare.verify\")(function*(\n        capability: ShareCapability,\n        request: AuthorizeRequest\n      ) {\n        yield* Effect.annotateCurrentSpan({ branchId: request.branchId, access: request.access })\n        // Everything authorized below is read from these locals, never from\n        // the caller's objects, which may change while Web Crypto is awaited.\n        const claims = snapshot(capability.claims)\n        const signature = capability.signature\n        const branchId = request.branchId\n        const key = ring.verification.get(claims.kid)\n        if (key === undefined) {\n          return yield* Effect.fail(denied(\"The share capability names an unknown signing key\"))\n        }\n        yield* shareSigner.verifyClaims({\n          key,\n          canonical: canonical(claims),\n          signature,\n          expiresAtMs: claims.expiresAtMs,\n          granted: claims.access,\n          requested: request.access,\n          subject: \"The share capability\",\n          // The one check this authority adds, run after the signature so a\n          // forged claim set is refused as a bad signature and never reported\n          // back as the branch it names.\n          scope: claims.branchId === branchId\n            ? Effect.void\n            : Effect.fail(denied(`The share capability is scoped to branch ${claims.branchId}`))\n        })\n        return claims\n      })\n\n      return BranchShare.of({ mint, verify })\n    }\n  )\n\n/**\n * Provides the HMAC-SHA-256 share authority over a keyring.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerHmac = (keyring: Keyring): Layer.Layer<BranchShare, SyncError> =>\n  Layer.effect(BranchShare, makeHmac(keyring))\n\n/**\n * Provides the branch share authority from configuration: the secret from\n * `SMITHERS_SYNC_BRANCH_SECRET` (read as `Redacted`, never logged) and the key\n * name from `SMITHERS_SYNC_BRANCH_KEY_ID`, defaulting to `primary`. Rotation\n * beyond one configured key uses {@link layerHmac} with an explicit keyring.\n *\n * The names are the branch authority's own, not the workspace's: the scheme\n * label makes one secret in both authorities survivable, not advisable, and a\n * deployment that rotates one credential should not silently invalidate the\n * other's outstanding capabilities.\n *\n * There is deliberately no default secret: a deployment that configures\n * neither name fails to construct the authority, and every branch operation\n * stays closed.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerConfig: Layer.Layer<BranchShare, SyncError | Config.ConfigError> = Layer.effect(\n  BranchShare,\n  Effect.gen(function*() {\n    const secret = yield* Config.Redacted(\"SMITHERS_SYNC_BRANCH_SECRET\")\n    const kid = yield* Config.String(\"SMITHERS_SYNC_BRANCH_KEY_ID\").pipe(Config.withDefault(\"primary\"))\n    return yield* makeHmac({ activeKid: kid, keys: [{ kid, secret }] })\n  })\n)\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/RunCatalog.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Workspace run enumeration for synchronization.
+ *
+ * @since 0.1.0
+ */
+import type { JournalEvent } from "@smthrs/journal";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import type { SyncError } from "./SyncError.ts";
+/**
+ * Workspace run enumeration operations.
+ *
+ * `list` is the AUTHORITATIVE run set and `changes` is only a low-latency
+ * wake: a subscriber that misses an announcement re-lists rather than losing
+ * state, and a subscriber whose covered set must stay accurate re-lists on a
+ * cadence of its own. Every implementation returns a fresh array from `list`,
+ * so a caller may retain and sort what it receives without disturbing another
+ * reader.
+ *
+ * `list` names each run AT MOST ONCE. Every implementation here deduplicates,
+ * and `SyncServer` deduplicates again at the seam rather than trusting a
+ * host's catalog, because both fan-out paths key a run's served position by
+ * run id: a run named twice is read twice from the same position and its
+ * entries are served twice.
+ *
+ * The catalog is supplied by the host rather than derived from the journal:
+ * `@smthrs/journal` has no workspace-wide list or watch contract, and
+ * `@smthrs/engine-store` owns the durable run set that {@link makePolling}
+ * reads.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly list: Effect.Effect<ReadonlyArray<JournalEvent.RunId>>;
+    readonly changes: Stream.Stream<JournalEvent.RunId>;
+}
+declare const RunCatalog_base: Context.ServiceClass<RunCatalog, "@smthrs/sync/RunCatalog", Service>;
+/**
+ * Host-provided workspace run catalog.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class RunCatalog extends RunCatalog_base {
+}
+/**
+ * Provides an immutable run catalog.
+ *
+ * `list` answers with a fresh array each time, matching {@link makeMemory} and
+ * {@link makePolling}. Handing every caller the same instance let one reader
+ * sort or splice the catalog in place for every other reader, which is a
+ * defect a `ReadonlyArray` type hides from TypeScript and not from JavaScript.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerStatic: (ids: ReadonlyArray<JournalEvent.RunId>) => Layer.Layer<RunCatalog>;
+/**
+ * Announcements a stalled {@link Service.changes} subscriber may fall behind
+ * by before the oldest are dropped.
+ *
+ * `changes` is a notification feed, not a log: a follower reads it to learn
+ * that the workspace gained a run and then reads the run itself. Retaining an
+ * unbounded backlog for a subscriber that has stopped pulling — a disconnected
+ * tab whose socket has not timed out yet, a follower blocked behind a slow
+ * consumer — is therefore pure cost, and the workspace's whole run history is
+ * the upper bound on it. A subscriber that falls further behind than this
+ * bound loses the oldest announcements; `list` still names every run, so a
+ * follower that reconnects or re-lists converges.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultChangesCapacity = 1024;
+/**
+ * Options for the in-memory run catalog.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface MemoryOptions {
+    /**
+     * Announcements a stalled subscriber may fall behind by. Defaults to
+     * {@link defaultChangesCapacity}.
+     */
+    readonly changesCapacity?: number | undefined;
+}
+/**
+ * Constructs a mutable in-memory run catalog.
+ *
+ * A run is published exactly once, when it is first registered. The
+ * announcement feed slides: registering never waits on a stalled subscriber,
+ * and never grows the process on its behalf.
+ *
+ * Fails with `invalid_request` when `changesCapacity` is not a positive safe
+ * integer, rather than handing it to `PubSub.sliding` as a capacity.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeMemory: (options?: MemoryOptions) => Effect.Effect<{
+    readonly catalog: Service;
+    readonly register: (runId: JournalEvent.RunId) => Effect.Effect<void>;
+}, SyncError>;
+/**
+ * How often {@link makePolling} re-reads its source when the caller names no
+ * interval, in milliseconds.
+ *
+ * A workspace follower learns of a new run within one interval of it being
+ * created, and the read costs one bounded query per interval per composition,
+ * not per subscriber. A second is short enough that a run appears in a UI
+ * while the operator is still looking at the command that started it, and
+ * long enough that an idle workspace is close to free.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultPollIntervalMs = 1000;
+/**
+ * Options for the polling run catalog.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface PollingOptions<E, R> {
+    /**
+     * Reads the workspace's current run set. `@smthrs/engine-store` supplies
+     * the durable one over `flows_runs`; anything that answers the same
+     * question works, and the catalog holds no assumption about which.
+     */
+    readonly read: Effect.Effect<ReadonlyArray<JournalEvent.RunId>, E, R>;
+    /** Milliseconds between reads. Defaults to {@link defaultPollIntervalMs}. */
+    readonly intervalMs?: number | undefined;
+    /**
+     * Announcements a stalled subscriber may fall behind by. Defaults to
+     * {@link defaultChangesCapacity}.
+     */
+    readonly changesCapacity?: number | undefined;
+}
+/**
+ * Constructs a run catalog that polls a durable source.
+ *
+ * Polling, not waking. rc.0 has no cross-process event delivery, so a
+ * follower learns of a run another engine created by asking the workspace
+ * again, and the interval is the whole of the policy.
+ *
+ * The catalog primes itself before it returns, so the first read a follower
+ * makes is already current and a workspace that cannot be read at all fails
+ * the composition instead of serving an empty run set. After that a failed
+ * read is a warning and nothing else: the previous view stands, the interval
+ * holds, and no subscription attached to the catalog is torn down for it.
+ * The warning is written once per outage, with the first failure's cause, and
+ * one info line marks the read that ends it; the polls in between are silent.
+ *
+ * A run is announced once, when it first appears. A run the read stops
+ * naming, which is what retention collecting it looks like, leaves the view;
+ * `list` is the workspace's run set, not a log of every run it ever had.
+ *
+ * `list` answers with a fresh array each time, matching {@link layerStatic} and
+ * {@link makeMemory}. Handing back the stored snapshot let a caller sort or
+ * splice the authoritative run set in place under the poll fiber that owns it,
+ * which is a defect a `ReadonlyArray` type hides from TypeScript and not from
+ * JavaScript.
+ *
+ * The poll fiber belongs to the caller's scope. Closing the scope stops it.
+ *
+ * Both numeric options are validated here, before the first read: an
+ * `intervalMs` of `NaN` or zero reached `Effect.delay` as the whole of the
+ * poll cadence, which is a loop with no interval rather than a refusal.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makePolling: <E, R>(options: PollingOptions<E, R>) => Effect.Effect<Service, E | SyncError, R | Scope.Scope>;
+/**
+ * Provides a run catalog that polls a durable source. The poll fiber lives as
+ * long as the layer's scope.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerPolling: <E, R>(options: PollingOptions<E, R>) => Layer.Layer<RunCatalog, E | SyncError, R>;
+/**
+ * Provides the mutable in-memory run catalog, matching how every other
+ * implementation here is provided. Fails with `invalid_request` when
+ * `changesCapacity` is not a positive safe integer.
+ *
+ * The layer provides the catalog alone. A composition that also registers runs
+ * builds {@link makeMemory} itself and keeps its `register`.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerMemory: (options?: MemoryOptions) => Layer.Layer<RunCatalog, SyncError>;
+/**
+ * Provides an empty run catalog.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<RunCatalog>;
+export {};
+//# sourceMappingURL=RunCatalog.d.ts.map

package/dist/cjs/RunCatalog.d.ts.map

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