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

package/src/types/AccountsManifest.res

@@ -0,0 +1,281 @@
+/***
+The accounts a deployment is operated as, as a file: `.reventless/users.yaml`.
+
+Two platforms read it and they must not disagree about its shape. Locally it *is*
+the identity store — the in-memory auth adapter loads it at startup. On AWS it is
+the record of what was created in a Cognito pool, and `provision-accounts` both
+reads it and writes back into it.
+
+Here rather than in either platform package because a manifest that works on one
+platform and silently fails on the other is the whole cost being avoided. It sits
+beside [Identity] and [AdminGroup] for the same reason those do: the vocabulary
+the two platforms share about who is signed in.
+
+🚨 **The password field is a bootstrap credential, not a stored secret.** The file
+is gitignored on every platform, and on AWS the passwords in it are generated per
+deployment rather than committed — see `users.example.yaml` beside each platform.
+*/
+
+/**
+One account. `groups` is required (`[]` for an unprivileged account).
+
+`password` is required but may be empty: an AWS manifest is written before the
+accounts exist, and `provision-accounts` fills the empty ones in. An empty
+password authenticates nowhere, which is the correct reading of "not yet
+provisioned" on both platforms.
+
+`userId` is what the platform stamps on rows this account writes. Locally it
+defaults to the username; on AWS it is the `sub` the pool minted, so it can only
+be filled in after the account exists.
+*/
+@schema
+type entry = {
+  username: string,
+  password: string,
+  groups: array<string>,
+  userId?: string,
+}
+
+let entriesSchema = S.array(entrySchema)
+
+@module("yaml") external parseYaml: string => JSON.t = "parse"
+
+/** Parses a manifest document. Strict: a malformed entry refuses the whole file
+  rather than being skipped, because on both platforms a silently dropped account
+  reads as a login that stopped working for no stated reason. */
+let parseString = (yamlText: string): result<array<entry>, string> =>
+  try {
+    Ok(S.parseOrThrow(parseYaml(yamlText), ~to=entriesSchema))
+  } catch {
+  | JsExn(err) => Error(JsExn.message(err)->Option.getOr("YAML parse error"))
+  | _ => Error("YAML parse error")
+  }
+
+let parseFile = (path: string): result<array<entry>, string> =>
+  try {
+    parseString(NodeFs.readFileSync(path))
+  } catch {
+  | JsExn(err) => Error(JsExn.message(err)->Option.getOr(`Cannot read ${path}`))
+  | _ => Error(`Cannot read ${path}`)
+  }
+
+/** Where both platforms keep it: beside the package the process runs from. */
+let defaultPath = (): string => NodePath.join([NodeProcess.cwd(), ".reventless", "users.yaml"])
+
+// ── Writing back ─────────────────────────────────────────────────────────────
+
+/**
+A value provisioning learned and the file does not know yet, addressed by the
+entry's position in the document.
+
+`password` is written **only into an empty field** — see [applyFills]. `userId` is
+written whenever it differs, because on AWS the pool mints it and the file is only
+ever a copy: a stale one is not a documentation slip but rows keyed to an id
+nobody holds.
+*/
+type fill = {
+  index: int,
+  password: option<string>,
+  userId: option<string>,
+}
+
+/** What a fill actually did, so the caller can report it rather than guess. */
+type filled = {
+  index: int,
+  passwordWritten: bool,
+  userIdWritten: bool,
+}
+
+type document
+
+@module("yaml") external parseDocument: string => document = "parseDocument"
+@send external getIn: (document, array<JSON.t>) => JSON.t = "getIn"
+@send external setIn: (document, array<JSON.t>, JSON.t) => unit = "setIn"
+@send external documentToString: document => string = "toString"
+
+let path = (index: int, field: string): array<JSON.t> => [
+  JSON.Number(index->Int.toFloat),
+  JSON.String(field),
+]
+
+let currentString = (doc: document, index: int, field: string): option<string> =>
+  switch doc->getIn(path(index, field)) {
+  | JSON.String(s) => Some(s)
+  | _ => None
+  }
+
+/**
+Applies fills to a manifest document, returning the document's new text.
+
+🚨 **Round-trips through `parseDocument` rather than re-serializing the parsed
+entries**, so every comment survives. Both manifests carry more explanation than
+data — which account is elevated and why, which pool these subs came from — and a
+tool that silently deleted it would cost more than it saved.
+
+🚨 **A password already in the file is never replaced.** A second run is the
+normal case (an operator adding one account to four), and the failure mode of the
+obvious implementation is overwriting a credential somebody is signed in with.
+Empty means empty or whitespace; anything else is somebody's choice.
+*/
+let applyFills = (yamlText: string, fills: array<fill>): result<(string, array<filled>), string> =>
+  try {
+    let doc = parseDocument(yamlText)
+    let report = fills->Array.map(({index, password, userId}) => {
+      let passwordWritten = switch password {
+      | Some(generated)
+        if doc->currentString(index, "password")->Option.getOr("")->String.trim == "" =>
+        doc->setIn(path(index, "password"), JSON.String(generated))
+        true
+      | _ => false
+      }
+      let userIdWritten = switch userId {
+      | Some(minted) if doc->currentString(index, "userId") != Some(minted) =>
+        doc->setIn(path(index, "userId"), JSON.String(minted))
+        true
+      | _ => false
+      }
+      {index, passwordWritten, userIdWritten}
+    })
+    Ok((doc->documentToString, report))
+  } catch {
+  | JsExn(err) => Error(JsExn.message(err)->Option.getOr("Cannot rewrite the manifest"))
+  | _ => Error("Cannot rewrite the manifest")
+  }
+
+/** [applyFills] against a file on disk. Reads, rewrites, writes — and writes
+  nothing at all when no fill applied, so a fully-provisioned manifest keeps its
+  mtime and a second run is visibly a no-op. */
+let fillFile = (~path as file: string, ~fills: array<fill>): result<array<filled>, string> =>
+  switch try Ok(NodeFs.readFileSync(file)) catch {
+  | JsExn(err) => Error(JsExn.message(err)->Option.getOr(`Cannot read ${file}`))
+  | _ => Error(`Cannot read ${file}`)
+  } {
+  | Error(_) as e => e
+  | Ok(text) =>
+    switch applyFills(text, fills) {
+    | Error(_) as e => e
+    | Ok((_, report)) if !(report->Array.some(r => r.passwordWritten || r.userIdWritten)) =>
+      Ok(report)
+    | Ok((rewritten, report)) =>
+      try {
+        NodeFs.writeFileSync(file, rewritten)
+        Ok(report)
+      } catch {
+      | JsExn(err) => Error(JsExn.message(err)->Option.getOr(`Cannot write ${file}`))
+      | _ => Error(`Cannot write ${file}`)
+      }
+    }
+  }
+
+// ── Finding it ───────────────────────────────────────────────────────────────
+
+/** The template each platform package keeps beside itself, committed, as the
+  declaration of its cast. Both examples spell it this way and so does the local
+  setup script, so it is a convention rather than a setting. */
+let templateName = "users.example.yaml"
+
+type located =
+  | Declared(string)
+  | SeededFrom(string, string)
+
+let pathOf = (located: located): string =>
+  switch located {
+  | Declared(file) | SeededFrom(file, _) => file
+  }
+
+/**
+The manifest to work from, copying the template into place when there is none.
+
+`.reventless/` is gitignored on every platform, so a fresh clone has no manifest
+and the first thing anyone met was `cp users.example.yaml .reventless/users.yaml`
+— ceremony of the same kind as passing a pool id the deployment already knows.
+`scripts/setup.mjs` has done this for the local platform all along; this generalises
+it to any platform package, which is why it lives beside the format rather than
+inside either platform's tooling.
+
+🚨 **A named path is never seeded.** Passing one is a claim that it exists, and
+copying a template over that claim would answer a typo by provisioning the wrong
+cast. Only the default path is filled in.
+*/
+let locate = (~given: option<string>=?, ()): result<located, string> =>
+  switch given {
+  | Some(file) =>
+    NodeFs.existsSync(file)
+      ? Ok(Declared(file))
+      : Error(`${file} does not exist — a named manifest is read, never created`)
+  | None =>
+    let file = defaultPath()
+    if NodeFs.existsSync(file) {
+      Ok(Declared(file))
+    } else {
+      let template = NodePath.join([NodeProcess.cwd(), templateName])
+      if !NodeFs.existsSync(template) {
+        Error(
+          `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`,
+        )
+      } else {
+        try {
+          NodeFs.mkdirSync(NodePath.dirname(file), {recursive: true})
+          NodeFs.cpSync(template, file, {})
+          Ok(SeededFrom(file, template))
+        } catch {
+        | JsExn(err) =>
+          Error(
+            `could not copy ${templateName} into place: ${JsExn.message(err)->Option.getOr(
+                "unknown error",
+              )}`,
+          )
+        | _ => Error(`could not copy ${templateName} into place`)
+        }
+      }
+    }
+  }
+
+// ── Preparing ────────────────────────────────────────────────────────────────
+
+/** One account after preparation: what the file now declares, and whether this
+  run is what put the password there. */
+type prepared = {
+  entry: entry,
+  passwordGenerated: bool,
+}
+
+/**
+Validates a manifest and fills in what it leaves blank.
+
+🚨 **This is the whole of provisioning on the local platform, and the first half
+of it on AWS.** Locally the manifest *is* the user store — the 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, and
+that half is Cognito's, in `reventless/aws`.
+
+Which is why it lives here and takes no client, no region and no credentials: a
+developer with an empty password field can run it on a laptop that has never held
+an AWS key.
+
+The passwords it mints are written straight back, because a generated credential
+that is only printed is one the seed client cannot read.
+*/
+let prepare = (~path as file: string): result<array<prepared>, string> =>
+  switch parseFile(file) {
+  | Error(_) as e => e
+  | Ok(entries) =>
+    let minted =
+      entries->Array.map(entry =>
+        entry.password->String.trim == "" ? Some(Util_Password.generate()) : None
+      )
+    let fills = minted->Array.mapWithIndex((password, index) => {index, password, userId: None})
+    switch fillFile(~path=file, ~fills) {
+    | Error(_) as e => e
+    | Ok(report) =>
+      Ok(
+        entries->Array.mapWithIndex((entry, index) => {
+          let written = report->Array.get(index)->Option.mapOr(false, r => r.passwordWritten)
+          switch (written, minted->Array.getUnsafe(index)) {
+          | (true, Some(password)) => {entry: {...entry, password}, passwordGenerated: true}
+          | _ => {entry, passwordGenerated: false}
+          }
+        }),
+      )
+    }
+  }

package/src/types/AccountsManifest.res.mjs

@@ -0,0 +1,311 @@
+// 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))
+}));
+
+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,