@reventlessdev/reventless-core 3.0.0-alpha.261 → 3.0.0-alpha.262

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.262 (2026-09-11)
+
+* feat(spec)!: a secret is a capability, so a test can know it in advance ([71507c6](https://github.com/ReventlessDev/reventless-core/commit/71507c6459b49178746f00c5040cb479d7fdade8))
+### Features
+
+* **aws:** the first administrator is one command, not the console ([5f1a846](https://github.com/ReventlessDev/reventless-core/commit/5f1a84603b21a9feb691a08a148751c6c6e8eca8))
+
+### BREAKING CHANGES
+
+* Capabilities.t gains a secrets member. A platform that builds
+the record literally no longer compiles until it supplies one;
+Capabilities.none.secrets is the refusing value. Code that spreads
+Capabilities.none is unaffected.
+
+
+
 # 3.0.0-alpha.261 (2026-09-09)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.261",
+  "version": "3.0.0-alpha.262",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -28,17 +28,17 @@
   "dependencies": {
     "sury": "11.0.0-rc.2",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.33",
     "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.11",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.11",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.33",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.11",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.20",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.11",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.162",
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.36",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.134"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.163",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.135"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/adapter/Secrets/Secrets_Node_Backend.res

@@ -0,0 +1,60 @@
+// The secret source both platforms use: `node:crypto`, which AWS Lambda and the
+// local runtime both have. One implementation rather than two, for the same
+// reason the log messaging transport is shared — a second copy is one edit away
+// from differing on the part that matters.
+
+let _bytes = (count: int): array<int> => {
+  // Read back as hex and re-split, because the binding treats a Buffer as opaque
+  // — it is only ever stringified or fed to an HMAC. Two hex characters is one
+  // byte, so this is a decode rather than a reinterpretation.
+  let hex = NodeCrypto.randomBytes(count)->NodeCrypto.bufferToString("hex")
+  Array.fromInitializer(~length=count, i =>
+    hex->String.substring(~start=i * 2, ~end=i * 2 + 2)->Int.fromString(~radix=16)->Option.getOr(0)
+  )
+}
+
+/**
+Whether a random byte may be folded into an alphabet of `size`, or must be drawn
+again.
+
+🚨 **`byte % size` is not uniform, and this predicate is the whole defence.** 256
+is not a multiple of 10, so bytes 250–255 fold onto digits 0–5 and make those six
+about four percent likelier each than the other four. An attacker guessing a
+numeric code guesses the likelier half first. Discarding everything at or above
+the largest whole multiple of `size` costs a few extra draws and makes every
+character equally likely.
+
+Separate and named because the skew it prevents is far too small to catch by
+sampling the output — it is checked directly, over every byte value.
+*/
+let accepts = (~byte: int, ~size: int): bool => byte < 256 - mod(256, size)
+
+let _draw = (~length: int, ~from: string): string => {
+  let size = from->String.length
+  let out = []
+  while out->Array.length < length {
+    // Over-draw: most bytes are kept, so one round is nearly always enough, and
+    // a short round simply goes again.
+    _bytes((length - out->Array.length) * 2 + 8)->Array.forEach(byte =>
+      if accepts(~byte, ~size) && out->Array.length < length {
+        out->Array.push(from->String.charAt(mod(byte, size)))
+      }
+    )
+  }
+  out->Array.join("")
+}
+
+/**
+The provider both platforms pass.
+
+`length` is refused rather than clamped when it is not positive: a caller asking
+for a zero-length token has a bug, and answering `""` would hand back something
+that compares equal to nothing and settles every challenge.
+*/
+let provider: Reventless.Secrets.t = {
+  randomToken: (~length, ~alphabet) =>
+    length <= 0
+      ? Error(Unavailable(`a token needs a positive length, not ${length->Int.toString}`))
+      : Ok(_draw(~length, ~from=Reventless.Secrets.characters(alphabet))),
+  hash: input => Ok(NodeCrypto.sha256Hex(input)),
+}

package/src/adapter/Secrets/Secrets_Node_Backend.res.mjs

@@ -0,0 +1,69 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as NodeCrypto from "@reventlessdev/rescript-node/src/NodeCrypto.res.mjs";
+import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
+import * as Nodecrypto from "node:crypto";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Secrets$Reventless from "@reventlessdev/reventless-spec/src/semantic/Secrets.res.mjs";
+
+function _bytes(count) {
+  let hex = Nodecrypto.randomBytes(count).toString("hex");
+  return Stdlib_Array.fromInitializer(count, i => Stdlib_Option.getOr(Stdlib_Int.fromString(hex.substring((i << 1), (i << 1) + 2 | 0), 16), 0));
+}
+
+function accepts(byte, size) {
+  return byte < (256 - Primitive_int.mod_(256, size) | 0);
+}
+
+function _draw(length, from) {
+  let size = from.length;
+  let out = [];
+  while (out.length < length) {
+    _bytes(((length - out.length | 0) << 1) + 8 | 0).forEach(byte => {
+      if (accepts(byte, size) && out.length < length) {
+        out.push(from.charAt(Primitive_int.mod_(byte, size)));
+        return;
+      }
+    });
+  };
+  return out.join("");
+}
+
+function provider_randomToken(length, alphabet) {
+  if (length <= 0) {
+    return {
+      TAG: "Error",
+      _0: {
+        TAG: "Unavailable",
+        _0: `a token needs a positive length, not ` + length.toString()
+      }
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: _draw(length, Secrets$Reventless.characters(alphabet))
+    };
+  }
+}
+
+function provider_hash(input) {
+  return {
+    TAG: "Ok",
+    _0: NodeCrypto.sha256Hex(input)
+  };
+}
+
+let provider = {
+  randomToken: provider_randomToken,
+  hash: provider_hash
+};
+
+export {
+  _bytes,
+  accepts,
+  _draw,
+  provider,
+}
+/* NodeCrypto Not a pure module */

package/tests/Secrets_Node_BackendTest.res

@@ -0,0 +1,141 @@
+open JestGlobals
+
+// The secret source. What matters here is not that it produces characters, but
+// that it produces them uniformly — a token drawn from a skewed distribution is
+// guessable in a way that no other test would notice.
+
+module Secrets = Reventless.Secrets
+module Backend = Secrets_Node_Backend
+
+let token = (~length, ~alphabet) =>
+  Backend.provider.randomToken(~length, ~alphabet)->Result.getOr("")
+
+describe("randomToken", () => {
+  testSync("draws the requested length", () =>
+    expect(
+      [1, 6, 32, 64]->Array.map(length => token(~length, ~alphabet=Digits)->String.length),
+    )->toEqual([1, 6, 32, 64])
+  )
+
+  testSync("draws only from the alphabet it was given", () => {
+    let allowed = Secrets.characters(UrlSafe)
+    expect(
+      token(~length=512, ~alphabet=UrlSafe)
+      ->String.split("")
+      ->Array.every(c => allowed->String.includes(c)),
+    )->toBe(true)
+  })
+
+  testSync("digits are digits", () =>
+    expect(
+      token(~length=512, ~alphabet=Digits)
+      ->String.split("")
+      ->Array.every(c => "0123456789"->String.includes(c)),
+    )->toBe(true)
+  )
+
+  // Not proof of randomness — it is proof the source is not a constant, which is
+  // the failure a fixed or broken binding would produce.
+  testSync("two draws differ", () =>
+    expect(token(~length=32, ~alphabet=UrlSafe) == token(~length=32, ~alphabet=UrlSafe))->toBe(
+      false,
+    )
+  )
+
+  // A zero-length token would compare equal to nothing and settle every
+  // challenge presented against it, so it is refused rather than clamped.
+  testSync("a non-positive length is refused, not clamped", () =>
+    expect(
+      [0, -1]->Array.map(
+        length => Backend.provider.randomToken(~length, ~alphabet=Digits)->Result.isError,
+      ),
+    )->toEqual([true, true])
+  )
+})
+
+// 🚨 Checked over every byte value rather than by sampling the output, and the
+// first attempt here got that wrong. `byte % 10` skews the low six digits by
+// about four percent each — roughly 0.609 of draws landing in the low half
+// against 0.600 for a fair source. At any sample size a test can afford that
+// gap is a couple of standard errors, so a sampled assertion either flakes or,
+// as the first version did, passes happily with the defence deleted.
+describe("accepts — the rejection rule", () => {
+  let rejected = size =>
+    Array.fromInitializer(~length=256, i => i)->Array.filter(byte => !Backend.accepts(~byte, ~size))
+
+  testSync("rejects exactly the bytes that would skew a 10-character alphabet", () =>
+    expect(rejected(10))->toEqual([250, 251, 252, 253, 254, 255])
+  )
+
+  // 64 divides 256 exactly, so nothing needs discarding and a url-safe token
+  // costs no extra draws.
+  testSync("rejects nothing when the alphabet divides evenly", () =>
+    expect(rejected(64))->toEqual([])
+  )
+
+  // What survives always folds onto a whole number of cycles, which is the
+  // property that makes every character equally likely.
+  testSync("what it accepts is a whole multiple of the alphabet", () =>
+    expect(
+      [2, 3, 7, 10, 16, 26, 62, 64]->Array.map(
+        size => mod(256 - rejected(size)->Array.length, size),
+      ),
+    )->toEqual([0, 0, 0, 0, 0, 0, 0, 0])
+  )
+
+  testSync("never discards more than one cycle's worth", () =>
+    expect([3, 7, 10, 26, 62]->Array.map(size => rejected(size)->Array.length < size))->toEqual([
+      true,
+      true,
+      true,
+      true,
+      true,
+    ])
+  )
+})
+
+describe("hash", () => {
+  testSync("is deterministic, which is what lets a proof be compared", () =>
+    expect(Backend.provider.hash("a-secret") == Backend.provider.hash("a-secret"))->toBe(true)
+  )
+
+  testSync("separates different inputs", () =>
+    expect(Backend.provider.hash("a-secret") == Backend.provider.hash("a-secret "))->toBe(false)
+  )
+
+  // One-way: the digest must not carry the secret it was made from.
+  testSync("does not contain its input", () =>
+    expect(
+      Backend.provider.hash("a-secret")
+      ->Result.getOr("")
+      ->String.includes("a-secret"),
+    )->toBe(false)
+  )
+})
+
+describe("Capabilities.none.secrets", () => {
+  // Refusing rather than degrading: there is no weaker token that would be safe
+  // to hand back, so an unwired platform must fail rather than produce one.
+  testSync("refuses both operations", () =>
+    expect((
+      Reventless.Capabilities.none.secrets.randomToken(
+        ~length=32,
+        ~alphabet=UrlSafe,
+      )->Result.isError,
+      Reventless.Capabilities.none.secrets.hash("x")->Result.isError,
+    ))->toEqual((true, true))
+  )
+})
+
+describe("Secrets.fixed", () => {
+  // What a consumer's suite uses to know the secret before presenting it.
+  let provider = Secrets.fixed(~token="known", ~hash=input => `hashed:${input}`)
+
+  testSync("hands back the token it was built with", () =>
+    expect(provider.randomToken(~length=32, ~alphabet=UrlSafe))->toEqual(Ok("known"))
+  )
+
+  testSync("hashes through the function it was given", () =>
+    expect(provider.hash("known"))->toEqual(Ok("hashed:known"))
+  )
+})

package/tests/Secrets_Node_BackendTest.res.mjs

@@ -0,0 +1,152 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
+import * as Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Secrets$Reventless from "@reventlessdev/reventless-spec/src/semantic/Secrets.res.mjs";
+import * as Capabilities$Reventless from "@reventlessdev/reventless-spec/src/semantic/Capabilities.res.mjs";
+import * as Secrets_Node_Backend$ReventlessCore from "../src/adapter/Secrets/Secrets_Node_Backend.res.mjs";
+
+function token(length, alphabet) {
+  return Stdlib_Result.getOr(Secrets_Node_Backend$ReventlessCore.provider.randomToken(length, alphabet), "");
+}
+
+globalThis.describe("randomToken", () => {
+  globalThis.test("draws the requested length", () => {
+    globalThis.expect([
+      1,
+      6,
+      32,
+      64
+    ].map(length => token(length, "Digits").length)).toEqual([
+      1,
+      6,
+      32,
+      64
+    ]);
+  });
+  globalThis.test("draws only from the alphabet it was given", () => {
+    let allowed = Secrets$Reventless.characters("UrlSafe");
+    globalThis.expect(token(512, "UrlSafe").split("").every(c => allowed.includes(c))).toBe(true);
+  });
+  globalThis.test("digits are digits", () => {
+    globalThis.expect(token(512, "Digits").split("").every(c => "0123456789".includes(c))).toBe(true);
+  });
+  globalThis.test("two draws differ", () => {
+    globalThis.expect(token(32, "UrlSafe") === token(32, "UrlSafe")).toBe(false);
+  });
+  globalThis.test("a non-positive length is refused, not clamped", () => {
+    globalThis.expect([
+      0,
+      -1
+    ].map(length => Stdlib_Result.isError(Secrets_Node_Backend$ReventlessCore.provider.randomToken(length, "Digits")))).toEqual([
+      true,
+      true
+    ]);
+  });
+});
+
+globalThis.describe("accepts — the rejection rule", () => {
+  let rejected = size => Stdlib_Array.fromInitializer(256, i => i).filter(byte => !Secrets_Node_Backend$ReventlessCore.accepts(byte, size));
+  globalThis.test("rejects exactly the bytes that would skew a 10-character alphabet", () => {
+    globalThis.expect(rejected(10)).toEqual([
+      250,
+      251,
+      252,
+      253,
+      254,
+      255
+    ]);
+  });
+  globalThis.test("rejects nothing when the alphabet divides evenly", () => {
+    globalThis.expect(rejected(64)).toEqual([]);
+  });
+  globalThis.test("what it accepts is a whole multiple of the alphabet", () => {
+    globalThis.expect([
+      2,
+      3,
+      7,
+      10,
+      16,
+      26,
+      62,
+      64
+    ].map(size => Primitive_int.mod_(256 - rejected(size).length | 0, size))).toEqual([
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0
+    ]);
+  });
+  globalThis.test("never discards more than one cycle's worth", () => {
+    globalThis.expect([
+      3,
+      7,
+      10,
+      26,
+      62
+    ].map(size => rejected(size).length < size)).toEqual([
+      true,
+      true,
+      true,
+      true,
+      true
+    ]);
+  });
+});
+
+globalThis.describe("hash", () => {
+  globalThis.test("is deterministic, which is what lets a proof be compared", () => {
+    globalThis.expect(Primitive_object.equal(Secrets_Node_Backend$ReventlessCore.provider.hash("a-secret"), Secrets_Node_Backend$ReventlessCore.provider.hash("a-secret"))).toBe(true);
+  });
+  globalThis.test("separates different inputs", () => {
+    globalThis.expect(Primitive_object.equal(Secrets_Node_Backend$ReventlessCore.provider.hash("a-secret"), Secrets_Node_Backend$ReventlessCore.provider.hash("a-secret "))).toBe(false);
+  });
+  globalThis.test("does not contain its input", () => {
+    globalThis.expect(Stdlib_Result.getOr(Secrets_Node_Backend$ReventlessCore.provider.hash("a-secret"), "").includes("a-secret")).toBe(false);
+  });
+});
+
+globalThis.describe("Capabilities.none.secrets", () => {
+  globalThis.test("refuses both operations", () => {
+    globalThis.expect([
+      Stdlib_Result.isError(Capabilities$Reventless.none.secrets.randomToken(32, "UrlSafe")),
+      Stdlib_Result.isError(Capabilities$Reventless.none.secrets.hash("x"))
+    ]).toEqual([
+      true,
+      true
+    ]);
+  });
+});
+
+globalThis.describe("Secrets.fixed", () => {
+  let provider = Secrets$Reventless.fixed("known", input => `hashed:` + input);
+  globalThis.test("hands back the token it was built with", () => {
+    globalThis.expect(provider.randomToken(32, "UrlSafe")).toEqual({
+      TAG: "Ok",
+      _0: "known"
+    });
+  });
+  globalThis.test("hashes through the function it was given", () => {
+    globalThis.expect(provider.hash("known")).toEqual({
+      TAG: "Ok",
+      _0: "hashed:known"
+    });
+  });
+});
+
+let Secrets;
+
+let Backend;
+
+export {
+  Secrets,
+  Backend,
+  token,
+}
+/*  Not a pure module */

package/tests/admin/Platform_Admin_StructureTest.res

@@ -206,14 +206,23 @@ describe("the internal commands declare the edges they move rows along", () => {
 // was open to everyone and the server refused anyone outside `Admin`. The
 // mismatch is invisible until a non-admin clicks the page.
 describe("the Plugins view publishes the rule the server enforces", () => {
-  testSync("the spec declares the group", () =>
+  // 🚨 **This is also the only check `Reventless.AdminGroup.name` can carry.** A
+  // PPX annotation takes a literal, so `@@reventless.authorize(AllowGroups(
+  // ["Admin"]))` above cannot reference the constant — the constant's job is to
+  // make everything *else* agree with the annotation, and nothing in the compiler
+  // spans that gap. The actual side here comes from the expanded annotation and
+  // the expected side from the constant, so the two are compared rather than
+  // restated. Writing the literal on both sides would pass while they diverged.
+  testSync("the spec declares the group, and it is the one the constant names", () =>
     expect(PluginsReadModelSpec.authorization)->toEqual(
-      Reventless.Authorization.AllowGroups(["Admin"]),
+      Reventless.Authorization.AllowGroups([Reventless.AdminGroup.name]),
     )
   )
 
   testSync("and the published access keys are derived from it", () =>
-    expect(Platform_Admin_Structure.pluginReadModel.requiredAccess)->toEqual(Some(["Admin"]))
+    expect(Platform_Admin_Structure.pluginReadModel.requiredAccess)->toEqual(
+      Some([Reventless.AdminGroup.name]),
+    )
   )
 
   // The API entry reads the same binding rather than restating it, so the two

package/tests/admin/Platform_Admin_StructureTest.res.mjs

@@ -3,6 +3,7 @@
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as AdminGroup$Reventless from "@reventlessdev/reventless-spec/src/types/AdminGroup.res.mjs";
 import * as Plugin_Structure$ReventlessCore from "../../src/plugin/component/Plugin_Structure.res.mjs";
 import * as PluginBaseFragment$ReventlessCore from "../../src/plugin/api/PluginBaseFragment.res.mjs";
 import * as PluginsReadModelSpec$ReventlessCore from "../../src/plugin/lifecycle/PluginsReadModelSpec.res.mjs";
@@ -154,14 +155,14 @@ globalThis.describe("the internal commands declare the edges they move rows alon
 });
 
 globalThis.describe("the Plugins view publishes the rule the server enforces", () => {
-  globalThis.test("the spec declares the group", () => {
+  globalThis.test("the spec declares the group, and it is the one the constant names", () => {
     globalThis.expect(PluginsReadModelSpec$ReventlessCore.authorization).toEqual({
       TAG: "AllowGroups",
-      _0: ["Admin"]
+      _0: [AdminGroup$Reventless.name]
     });
   });
   globalThis.test("and the published access keys are derived from it", () => {
-    globalThis.expect(Platform_Admin_Structure$ReventlessCore.pluginReadModel.requiredAccess).toEqual(["Admin"]);
+    globalThis.expect(Platform_Admin_Structure$ReventlessCore.pluginReadModel.requiredAccess).toEqual([AdminGroup$Reventless.name]);
   });
   globalThis.test("the query entry carries the spec's rule and no hand-written pair", () => {
     let entry = PluginBaseFragment$ReventlessCore.queryEntries[0];