@reventlessdev/reventless-spec 3.0.0-alpha.134 → 3.0.0-alpha.136

package/src/types/AccountsManifest.res.mjs

@@ -0,0 +1,312 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
+import * as Yaml from "yaml";
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.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 Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Util_Password$Reventless from "../util/Util_Password.res.mjs";
+
+let entrySchema = Sury.$schema(s => ({
+  username: s.m(Sury.string),
+  password: s.m(Sury.string),
+  groups: s.m(Sury.array(Sury.string)),
+  userId: s.m(Sury.$option(Sury.string)),
+  demoOwner: s.m(Sury.$option(Sury.string))
+}));
+
+let entriesSchema = Sury.array(entrySchema);
+
+function parseString(yamlText) {
+  try {
+    return {
+      TAG: "Ok",
+      _0: S.parseOrThrow(Yaml.parse(yamlText), entriesSchema)
+    };
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    if (err.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), "YAML parse error")
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: "YAML parse error"
+      };
+    }
+  }
+}
+
+function parseFile(path) {
+  try {
+    return parseString(Nodefs.readFileSync(path, "utf8"));
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    if (err.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), `Cannot read ` + path)
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: `Cannot read ` + path
+      };
+    }
+  }
+}
+
+function defaultPath() {
+  return Nodepath.join(process.cwd(), ".reventless", "users.yaml");
+}
+
+function path(index, field) {
+  return [
+    index,
+    field
+  ];
+}
+
+function currentString(doc, index, field) {
+  let s = doc.getIn(path(index, field));
+  if (typeof s === "string") {
+    return s;
+  }
+}
+
+function applyFills(yamlText, fills) {
+  try {
+    let doc = Yaml.parseDocument(yamlText);
+    let report = fills.map(param => {
+      let userId = param.userId;
+      let password = param.password;
+      let index = param.index;
+      let passwordWritten = password !== undefined && Stdlib_Option.getOr(currentString(doc, index, "password"), "").trim() === "" ? (doc.setIn(path(index, "password"), password), true) : false;
+      let userIdWritten = userId !== undefined && Primitive_object.notequal(currentString(doc, index, "userId"), userId) ? (doc.setIn(path(index, "userId"), userId), true) : false;
+      return {
+        index: index,
+        passwordWritten: passwordWritten,
+        userIdWritten: userIdWritten
+      };
+    });
+    return {
+      TAG: "Ok",
+      _0: [
+        doc.toString(),
+        report
+      ]
+    };
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    if (err.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), "Cannot rewrite the manifest")
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: "Cannot rewrite the manifest"
+      };
+    }
+  }
+}
+
+function fillFile(file, fills) {
+  let e;
+  try {
+    e = {
+      TAG: "Ok",
+      _0: Nodefs.readFileSync(file, "utf8")
+    };
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    e = err.RE_EXN_ID === "JsExn" ? ({
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), `Cannot read ` + file)
+      }) : ({
+        TAG: "Error",
+        _0: `Cannot read ` + file
+      });
+  }
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let e$1 = applyFills(e._0, fills);
+  if (e$1.TAG !== "Ok") {
+    return e$1;
+  }
+  let match = e$1._0;
+  let report = match[1];
+  if (!report.some(r => {
+      if (r.passwordWritten) {
+        return true;
+      } else {
+        return r.userIdWritten;
+      }
+    })) {
+    return {
+      TAG: "Ok",
+      _0: report
+    };
+  }
+  try {
+    Nodefs.writeFileSync(file, match[0], "utf8");
+    return {
+      TAG: "Ok",
+      _0: report
+    };
+  } catch (raw_err$1) {
+    let err$1 = Primitive_exceptions.internalToException(raw_err$1);
+    if (err$1.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err$1._1), `Cannot write ` + file)
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: `Cannot write ` + file
+      };
+    }
+  }
+}
+
+let templateName = "users.example.yaml";
+
+function pathOf(located) {
+  return located._0;
+}
+
+function locate(given, param) {
+  if (given !== undefined) {
+    if (Nodefs.existsSync(given)) {
+      return {
+        TAG: "Ok",
+        _0: {
+          TAG: "Declared",
+          _0: given
+        }
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: given + ` does not exist — a named manifest is read, never created`
+      };
+    }
+  }
+  let file = defaultPath();
+  if (Nodefs.existsSync(file)) {
+    return {
+      TAG: "Ok",
+      _0: {
+        TAG: "Declared",
+        _0: file
+      }
+    };
+  }
+  let template = Nodepath.join(process.cwd(), templateName);
+  if (!Nodefs.existsSync(template)) {
+    return {
+      TAG: "Error",
+      _0: `no ` + file + ` and no ` + templateName + ` here to start one from. Declare the accounts in .reventless/users.yaml — each entry a username, a password (empty to have one generated) and the groups it belongs to`
+    };
+  }
+  try {
+    Nodefs.mkdirSync(Nodepath.dirname(file), {
+      recursive: true
+    });
+    Nodefs.cpSync(template, file, {});
+    return {
+      TAG: "Ok",
+      _0: {
+        TAG: "SeededFrom",
+        _0: file,
+        _1: template
+      }
+    };
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    if (err.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "Error",
+        _0: `could not copy ` + templateName + ` into place: ` + Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), "unknown error")
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: `could not copy ` + templateName + ` into place`
+      };
+    }
+  }
+}
+
+function prepare(file) {
+  let e = parseFile(file);
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let entries = e._0;
+  let minted = entries.map(entry => {
+    if (entry.password.trim() === "") {
+      return Util_Password$Reventless.generate();
+    }
+  });
+  let fills = minted.map((password, index) => ({
+    index: index,
+    password: password,
+    userId: undefined
+  }));
+  let e$1 = fillFile(file, fills);
+  if (e$1.TAG !== "Ok") {
+    return e$1;
+  }
+  let report = e$1._0;
+  return {
+    TAG: "Ok",
+    _0: entries.map((entry, index) => {
+      let written = Stdlib_Option.mapOr(report[index], false, r => r.passwordWritten);
+      let match = minted[index];
+      if (!written) {
+        return {
+          entry: entry,
+          passwordGenerated: false
+        };
+      }
+      if (match === undefined) {
+        return {
+          entry: entry,
+          passwordGenerated: false
+        };
+      }
+      let newrecord = {...entry};
+      return {
+        entry: (newrecord.password = match, newrecord),
+        passwordGenerated: true
+      };
+    })
+  };
+}
+
+export {
+  entrySchema,
+  entriesSchema,
+  parseString,
+  parseFile,
+  defaultPath,
+  path,
+  currentString,
+  applyFills,
+  fillFile,
+  templateName,
+  pathOf,
+  locate,
+  prepare,
+}
+/* entrySchema Not a pure module */

package/src/types/AdminGroup.res

@@ -0,0 +1,27 @@
+/**
+The group whose members administer a deployment.
+
+One definition, because the name is decided **twice and independently**: an
+authorization rule names it to allow a read, and [OwnerScope.elevatedGroups]
+names it to exempt a caller from `@owner` narrowing. Nothing checks that the two
+agree, and a deployment where they disagree is refused nowhere — the
+administrator passes every authorization check and then reads *empty views*,
+because every owner-scoped view filters them out. Empty-because-scoped and
+empty-because-there-is-nothing look identical from outside.
+
+In `spec` rather than in a provider package because **both platforms hard-code
+it**: the AWS platform decorates its admin API with it, while the local platform
+both wraps its `Platform_*` fields in it and hands it to the built-in developer
+account. A constant only one of them could reach would leave the other exactly as
+divergent as it is today.
+
+🚨 **This buys agreement, not the freedom to rename.** `"Admin"` is written into
+every example's `@@reventless.authorize` annotations, and a PPX annotation takes a
+literal — so the consumers that matter most *cannot* read this constant. Changing
+the value here would leave those annotations behind and silently split the two
+mechanisms this exists to hold together, which is the failure above rather than a
+compile error. Renaming the administrator group is a different and much larger
+act. `AdminGroupTest` asserts that the constant and the platform's own annotation
+still say the same thing, because that boundary can carry no other check.
+*/
+let name = "Admin"

package/src/types/AdminGroup.res.mjs

@@ -0,0 +1,9 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let name = "Admin";
+
+export {
+  name,
+}
+/* No side effect */

package/src/types/OwnerScope.res

@@ -94,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(",")

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 */