@reventlessdev/reventless-spec 3.0.0-alpha.133 → 3.0.0-alpha.135

package/src/types/Message.res

@@ -1,4 +1,3 @@
-
 /** Identifies the service that produced or is addressed by a message. */
 @schema
 type service = string
@@ -179,7 +178,11 @@ type commandJson = {
 //
 // `scalarFills` is an out-parameter: the walker pushes `path := value` for each scalar it
 // invented.
-let fillMissingDefaults: (S.t<'a>, JSON.t, array<string>) => JSON.t = %raw(`function(schema, json, scalarFills){
+let fillMissingDefaults: (
+  S.t<'a>,
+  JSON.t,
+  array<string>,
+) => JSON.t = %raw(`function(schema, json, scalarFills){
   function isSchema(x){ return x && typeof x === "object" && typeof x.type === "string"; }
   function firstConst(anyOf){ var m=(anyOf||[]).find(function(s){return s.const!==undefined;}); return m ? m.const : undefined; }
   // Which object-typed member of an anyOf a plain (untagged) object value belongs to.
@@ -274,8 +277,7 @@ let parseJsonTolerant = (json, schema) =>
             ->Array.length
             ->Int.toString} missing scalar field(s): ${scalarFills->Array.join(
               ", ",
-            )}. A required scalar was added to a persisted type after this message was ` ++
-          `written; the value above is fabricated, not recovered. Prefer an optional field.`,
+            )}. A required scalar was added to a persisted type after this message was ` ++ `written; the value above is fabricated, not recovered. Prefer an optional field.`,
         )
       }
       value

package/src/types/OwnerScope.res

@@ -20,7 +20,6 @@ fields this module reads are typed non-optional and are, at runtime, sometimes
 absent. Every read here goes through a nullable cast for that reason; deleting
 one restores a silent failure rather than a type error.
 */
-
 /** Whether a JS value is a primitive string — `Cognito` and `InMemory` compile to
     bare strings while `Custom(_)` compiles to an object, so this is how a modelled
     provider is told from an unmodelled one that arrived as raw JSON. */
@@ -95,6 +94,33 @@ let setElevatedGroups = (groups: array<string>) => explicitElevatedGroups := Som
 /** Forget an explicit setting and fall back to the environment again. */
 let clearElevatedGroups = () => explicitElevatedGroups := None
 
+/**
+Name the elevated groups only where the deployment has not already answered.
+
+For a platform that wants a working default without overriding an operator who
+stated one — a stack that declares an administrator group has every reason to
+exempt it, and no business overruling a deployment that named different operators.
+
+"Already answered" includes the **environment**, not only an explicit call. A
+deployment that set `REVENTLESS_ELEVATED_GROUPS` in CI has named its operators,
+and a default that beat it would leave the runtime acting on a value no source in
+that deployment states. This is the same contract, one level up, that
+`Util_OwnerScopeEnv.applyElevatedGroupsDefault` keeps with a Lambda's own
+environment: the more specific statement wins, and the default only fills silence.
+
+🚨 **An explicit empty list is an answer, and this must not fill it in.** A
+deployment that deliberately elevates nobody has decided that; a default landing
+on top would silently re-grant the cross-owner read it withheld. That is why this
+reads [explicitElevatedGroups] rather than [elevatedGroups] — the latter answers
+`[]` for "nobody" and for "nothing said" alike, and those must not be treated the
+same here.
+*/
+let defaultElevatedGroups = (groups: array<string>) =>
+  switch (explicitElevatedGroups.contents, _elevatedGroupsEnv) {
+  | (None, None) => explicitElevatedGroups := Some(groups)
+  | _ => ()
+  }
+
 let parseElevatedGroups = (raw: string): array<string> =>
   raw
   ->String.split(",")
@@ -135,8 +161,7 @@ let classify = (identity: Identity.t, ~elevated: array<string>): t => {
     switch identity.userId->asNullableString->Nullable.toOption {
     | None => Unidentified("identity carries no userId")
     | Some("") => Unidentified("identity carries an empty userId")
-    | Some(userId) if userId == Identity.anonymous.userId =>
-      Unidentified("caller is anonymous")
+    | Some(userId) if userId == Identity.anonymous.userId => Unidentified("caller is anonymous")
     | Some(userId) =>
       let groups = identity.groups->asNullableArray->Nullable.toOption->Option.getOr([])
       groups->Array.some(g => elevated->Array.includes(g))

package/src/types/OwnerScope.res.mjs

@@ -21,6 +21,17 @@ function clearElevatedGroups() {
   explicitElevatedGroups.contents = undefined;
 }
 
+function defaultElevatedGroups(groups) {
+  let match = explicitElevatedGroups.contents;
+  let match$1 = process.env.REVENTLESS_ELEVATED_GROUPS;
+  if (match !== undefined || match$1 !== undefined) {
+    return;
+  } else {
+    explicitElevatedGroups.contents = groups;
+    return;
+  }
+}
+
 function parseElevatedGroups(raw) {
   return raw.split(",").map(prim => prim.trim()).filter(part => part.length > 0);
 }
@@ -226,6 +237,7 @@ export {
   explicitElevatedGroups,
   setElevatedGroups,
   clearElevatedGroups,
+  defaultElevatedGroups,
   parseElevatedGroups,
   elevatedGroups,
   classify,

package/src/types/PrepareAccounts.res

@@ -0,0 +1,119 @@
+/***
+Make a platform's accounts manifest ready to use.
+
+```
+pnpm exec prepare-accounts
+```
+
+Finds `.reventless/users.yaml` — copying the package's committed
+`users.example.yaml` into place when there is none — validates it, and generates a
+password into every field left empty.
+
+🚨 **On the local platform this is the whole of provisioning.** The manifest *is*
+the user store there: the in-memory auth adapter hydrates from it at startup, so
+once every account has a password there is nothing left to create. On AWS the
+accounts still have to be made in a pool, which is `provision-accounts` in
+`reventless-aws`.
+
+Here, rather than as a flag on that command, because it belongs to neither
+platform. A local developer reaching it through an AWS package's binary would be
+the only thing about this half that mentioned AWS at all — and the local platform
+does not depend on `reventless-aws`, so for a project that never deploys it would
+not resolve.
+
+It creates nothing, contacts nothing, and needs no credentials. Re-running is safe:
+a password already in the file is never replaced.
+*/
+
+type args = {
+  file: option<string>,
+  help: bool,
+}
+
+let parseArgs = (argv: array<string>): result<args, string> => {
+  let acc = ref(Ok({file: None, help: false}))
+  let i = ref(0)
+  let count = argv->Array.length
+  while i.contents < count {
+    let flag = argv->Array.getUnsafe(i.contents)
+    let value = argv->Array.get(i.contents + 1)
+    switch (acc.contents, flag, value) {
+    | (Error(_), _, _) => i := count
+    | (Ok(a), "--file", Some(v)) =>
+      acc := Ok({...a, file: Some(v)})
+      i := i.contents + 2
+    | (Ok(a), "--help", _) | (Ok(a), "-h", _) =>
+      acc := Ok({...a, help: true})
+      i := i.contents + 1
+    | (Ok(_), "--file", None) => acc := Error(`${flag} needs a value`)
+    | (Ok(_), unknown, _) => acc := Error(`unknown argument "${unknown}"`)
+    }
+  }
+  acc.contents
+}
+
+let usage = `
+Make a platform's accounts manifest ready to use.
+
+  --file <path>   The manifest. Defaults to .reventless/users.yaml relative to the
+                  working directory, which is where every platform keeps it. A
+                  named path is read, never created.
+
+Copies ${AccountsManifest.templateName} into place when there is no manifest yet,
+then generates a password into every empty field. Creates no accounts and needs no
+credentials — on the local platform that is all provisioning is. A password already
+in the file is never replaced.
+`
+
+/** The cast, as the file now declares it. Printed on a fresh copy because that is
+  the moment somebody should read it: on AWS the next command turns each of these
+  into a real account in a real pool. */
+let castNote = (entries: array<AccountsManifest.entry>): string =>
+  entries
+  ->Array.map(entry =>
+    `  ${entry.username}${entry.groups->Array.length == 0
+        ? ""
+        : `  [${entry.groups->Array.join(", ")}]`}`
+  )
+  ->Array.join("\n")
+
+let run = (): result<unit, string> =>
+  // argv[0] is node, argv[1] this script.
+  switch parseArgs(NodeProcess.argv->Array.slice(~start=2, ~end=NodeProcess.argv->Array.length)) {
+  | Error(_) as e => e
+  | Ok(args) if args.help =>
+    Console.log(usage)
+    Ok()
+  | Ok(args) =>
+    switch AccountsManifest.locate(~given=?args.file, ()) {
+    | Error(_) as e => e
+    | Ok(located) =>
+      let file = located->AccountsManifest.pathOf
+      switch located {
+      | SeededFrom(_, template) => Console.log(`manifest ${file} (new, copied from ${template})`)
+      | Declared(_) => Console.log(`manifest ${file}`)
+      }
+      switch AccountsManifest.prepare(~path=file) {
+      | Error(message) => Error(`${file}: ${message}`)
+      | Ok([]) => Error(`${file} declares no accounts`)
+      | Ok(prepared) =>
+        let generated = prepared->Array.filter(p => p.passwordGenerated)->Array.length
+        Console.log(
+          `accounts ${prepared
+            ->Array.length
+            ->Int.toString} declared, ${generated->Int.toString} password(s) generated\n\n${castNote(
+              prepared->Array.map(p => p.entry),
+            )}`,
+        )
+        Ok()
+      }
+    }
+  }
+
+let main = async () =>
+  switch run() {
+  | Ok() => ()
+  | Error(message) =>
+    Console.error(`prepare-accounts: ${message}`)
+    NodeProcess.exit(1)
+  }

package/src/types/PrepareAccounts.res.mjs

@@ -0,0 +1,148 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as AccountsManifest$Reventless from "./AccountsManifest.res.mjs";
+
+function parseArgs(argv) {
+  let acc = {
+    TAG: "Ok",
+    _0: {
+      file: undefined,
+      help: false
+    }
+  };
+  let i = 0;
+  let count = argv.length;
+  while (i < count) {
+    let flag = argv[i];
+    let value = argv[i + 1 | 0];
+    let match = acc;
+    if (match.TAG === "Ok") {
+      let a = match._0;
+      let exit = 0;
+      switch (flag) {
+        case "--file" :
+          if (value !== undefined) {
+            acc = {
+              TAG: "Ok",
+              _0: {
+                file: value,
+                help: a.help
+              }
+            };
+            i = i + 2 | 0;
+          } else {
+            acc = {
+              TAG: "Error",
+              _0: flag + ` needs a value`
+            };
+          }
+          break;
+        case "--help" :
+        case "-h" :
+          exit = 1;
+          break;
+        default:
+          acc = {
+            TAG: "Error",
+            _0: `unknown argument "` + flag + `"`
+          };
+      }
+      if (exit === 1) {
+        acc = {
+          TAG: "Ok",
+          _0: {
+            file: a.file,
+            help: true
+          }
+        };
+        i = i + 1 | 0;
+      }
+    } else {
+      i = count;
+    }
+  };
+  return acc;
+}
+
+let usage = `
+Make a platform's accounts manifest ready to use.
+
+  --file <path>   The manifest. Defaults to .reventless/users.yaml relative to the
+                  working directory, which is where every platform keeps it. A
+                  named path is read, never created.
+
+Copies ` + AccountsManifest$Reventless.templateName + ` into place when there is no manifest yet,
+then generates a password into every empty field. Creates no accounts and needs no
+credentials — on the local platform that is all provisioning is. A password already
+in the file is never replaced.
+`;
+
+function castNote(entries) {
+  return entries.map(entry => `  ` + entry.username + (
+    entry.groups.length === 0 ? "" : `  [` + entry.groups.join(", ") + `]`
+  )).join("\n");
+}
+
+function run() {
+  let e = parseArgs(process.argv.slice(2, process.argv.length));
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let args = e._0;
+  if (args.help) {
+    console.log(usage);
+    return {
+      TAG: "Ok",
+      _0: undefined
+    };
+  }
+  let e$1 = AccountsManifest$Reventless.locate(args.file, undefined);
+  if (e$1.TAG !== "Ok") {
+    return e$1;
+  }
+  let located = e$1._0;
+  let file = AccountsManifest$Reventless.pathOf(located);
+  if (located.TAG === "Declared") {
+    console.log(`manifest ` + file);
+  } else {
+    console.log(`manifest ` + file + ` (new, copied from ` + located._1 + `)`);
+  }
+  let message = AccountsManifest$Reventless.prepare(file);
+  if (message.TAG !== "Ok") {
+    return {
+      TAG: "Error",
+      _0: file + `: ` + message._0
+    };
+  }
+  let prepared = message._0;
+  if (prepared.length === 0) {
+    return {
+      TAG: "Error",
+      _0: file + ` declares no accounts`
+    };
+  }
+  let generated = prepared.filter(p => p.passwordGenerated).length;
+  console.log(`accounts ` + prepared.length.toString() + ` declared, ` + generated.toString() + ` password(s) generated\n\n` + castNote(prepared.map(p => p.entry)));
+  return {
+    TAG: "Ok",
+    _0: undefined
+  };
+}
+
+async function main() {
+  let message = run();
+  if (message.TAG === "Ok") {
+    return;
+  }
+  console.error(`prepare-accounts: ` + message._0);
+  process.exit(1);
+}
+
+export {
+  parseArgs,
+  usage,
+  castNote,
+  run,
+  main,
+}
+/* AccountsManifest-Reventless Not a pure module */

package/src/types/Projection.res

@@ -145,8 +145,15 @@ module Mapping = {
   module Make = (
     Source: Source,
     Target: Target,
-    MappingImpl: MappingImpl with type sourceEvent := Source.event and type targetState := Target.state,
-  ): (Mapping with type targetState = Target.state and type sourceEvent = Source.event and module SourceId = Source.Id) => {
+    MappingImpl: MappingImpl
+      with type sourceEvent := Source.event
+      and type targetState := Target.state,
+  ): (
+    Mapping
+      with type targetState = Target.state
+      and type sourceEvent = Source.event
+      and module SourceId = Source.Id
+  ) => {
     module SourceId = Source.Id
     @schema
     type sourceEvent = Source.event

package/src/types/StoredEvent.res

@@ -38,9 +38,7 @@ let toStoredEventSchema = (idSchema: S.t<'id>): S.t<storedEvent<'id>> =>
   })
 
 /** Decode a `storedEvent<'id>` from JSON. */
-let decode = (json, idSchema) =>
-  json->Util_Sury.fromJson(toStoredEventSchema(idSchema))
+let decode = (json, idSchema) => json->Util_Sury.fromJson(toStoredEventSchema(idSchema))
 
 /** Encode a `storedEvent<'id>` to JSON. */
-let encode = (stored, idSchema) =>
-  stored->Util_Sury.toJson(toStoredEventSchema(idSchema))
+let encode = (stored, idSchema) => stored->Util_Sury.toJson(toStoredEventSchema(idSchema))

package/src/types/Transition.res

@@ -69,9 +69,11 @@ let allowedStates = (transition: t<'state>): option<array<'state>> =>
   switch transition {
   | Undeclared
   | Unrestricted
-  | Creates(_) => None
+  | Creates(_) =>
+    None
   | Guards(states)
-  | Moves(states, _) => Some(states)
+  | Moves(states, _) =>
+    Some(states)
   }
 
 /** The state the command's handler writes, or `None` for one that moves nothing. */
@@ -79,9 +81,11 @@ let targetState = (transition: t<'state>): option<'state> =>
   switch transition {
   | Undeclared
   | Unrestricted
-  | Guards(_) => None
+  | Guards(_) =>
+    None
   | Creates(state)
-  | Moves(_, state) => Some(state)
+  | Moves(_, state) =>
+    Some(state)
   }
 
 /** Whether the command is claimed legal in every state, as opposed to nothing

package/src/util/Util_Password.res

@@ -0,0 +1,60 @@
+/***
+A password a Reventless pool will accept, minted rather than chosen.
+
+Here rather than beside the AWS provisioning script because two callers need it
+and only one of them is AWS: `provision-admin` mints the first administrator's
+credential, and [AccountsManifest.prepare] fills a manifest's empty password
+fields on any platform, with no cloud account involved. A generator living in
+`reventless/aws` would make the platform-neutral half reach into the AWS package
+for arithmetic that has nothing to do with AWS.
+*/
+
+/** Excludes the glyphs a person confuses when retyping a printed credential —
+  `l`/`I`/`1` and `O`/`0`. These passwords are read off a terminal or out of a
+  file once, and a bootstrap that fails on a misread character sends the operator
+  back to the console this exists to avoid. */
+let lower = "abcdefghijkmnopqrstuvwxyz"
+let upper = "ABCDEFGHJKLMNPQRSTUVWXYZ"
+let digits = "23456789"
+let alphabet = lower ++ upper ++ digits
+
+/** Comfortably over the 12 every Reventless pool is created with, since nobody
+  has to remember it. */
+let length = 24
+
+/** `count` uniform bytes as ints.
+
+  Via the hex encoding because that is what [NodeCrypto] exposes of a Buffer, and
+  a binding returning raw byte values would be a new one added for this alone.
+  Two hex digits always parse, so the fallback below is unreachable — it is there
+  because the parse is *typed* as partial, not because it can fail. */
+let randomInts = (count: int): array<int> => {
+  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)
+  )
+}
+
+let charAt = (source: string, n: int): string =>
+  source->String.charAt(mod(n, source->String.length))
+
+/**
+A password that satisfies the pool policy every Reventless pool is created with
+(12+ characters, with a lowercase, an uppercase and a digit).
+
+Satisfies it *by construction*: the three required classes are written into three
+non-overlapping thirds of the string, so one of each is always present. The
+obvious alternative — generate, test, regenerate — would leave a branch that
+almost never runs and, when it did, would hand Cognito a password it refuses.
+Almost-never is exactly the branch nobody has tested.
+*/
+let generate = (): string => {
+  let ints = randomInts(length + 6)
+  let chars = ints->Array.slice(~start=0, ~end=length)->Array.map(n => alphabet->charAt(n))
+  let third = length / 3
+  [lower, upper, digits]->Array.forEachWithIndex((classAlphabet, block) => {
+    let position = block * third + mod(ints->Array.getUnsafe(length + block), third)
+    chars->Array.set(position, classAlphabet->charAt(ints->Array.getUnsafe(length + 3 + block)))
+  })
+  chars->Array.join("")
+}

package/src/util/Util_Password.res.mjs

@@ -0,0 +1,53 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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";
+
+let lower = "abcdefghijkmnopqrstuvwxyz";
+
+let upper = "ABCDEFGHJKLMNPQRSTUVWXYZ";
+
+let digits = "23456789";
+
+let alphabet = lower + upper + digits;
+
+function randomInts(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 charAt(source, n) {
+  return source.charAt(Primitive_int.mod_(n, source.length));
+}
+
+function generate() {
+  let ints = randomInts(30);
+  let chars = ints.slice(0, 24).map(n => charAt(alphabet, n));
+  let third = 8;
+  [
+    lower,
+    upper,
+    digits
+  ].forEach((classAlphabet, block) => {
+    let position = (block * third | 0) + Primitive_int.mod_(ints[24 + block | 0], third) | 0;
+    chars[position] = charAt(classAlphabet, ints[27 + block | 0]);
+  });
+  return chars.join("");
+}
+
+let length = 24;
+
+export {
+  lower,
+  upper,
+  digits,
+  alphabet,
+  length,
+  randomInts,
+  charAt,
+  generate,
+}
+/* node:crypto Not a pure module */

package/src/util/Util_Sury.res

@@ -11,10 +11,7 @@ let toJson: ('a, S.t<'a>) => JSON.t = (value, schema) =>
 
 // `~space` defaults to compact, matching the removed `reverseConvertToJsonStringOrThrow`.
 let toJsonString = (value: 'a, schema: S.t<'a>, ~space: int=0): string =>
-  value->S.decodeOrThrow(
-    ~from=schema,
-    ~to=space == 0 ? S.jsonString : S.jsonStringWithSpace(space),
-  )
+  value->S.decodeOrThrow(~from=schema, ~to=space == 0 ? S.jsonString : S.jsonStringWithSpace(space))
 
 let fromJson: (JSON.t, S.t<'a>) => 'a = (json, schema) => json->S.parseOrThrow(~to=schema)