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

package/src/semantic/IdentityProvider.res

@@ -0,0 +1,127 @@
+/**
+Making, grouping and unmaking principals, so the provider behind them is a
+supplier rather than a call site.
+
+The *administrative* half of identity only. Authentication — token issuance, JWT
+verification, session handling — is `Auth_Adapter.Provider`'s, and stays there:
+the two are read at different times over one provider, exactly as this and
+`CapabilityNeed.t` are.
+
+🚨 **Nothing here is a domain event's business.** `principal` is the provider's
+own handle and must never reach an event log: a log full of one provider's ids
+cannot be migrated to another, which would make the replaceability this
+capability exists for a fiction. What the log holds is the domain's own opaque
+user id; the mapping between the two lives in this capability's store.
+*/
+/** The provider's own handle for a principal. Opaque on purpose — a caller that
+    can read structure out of it is a caller coupled to the provider. */
+type principal = {providerId: string}
+
+/** How a new principal proves it is them. A variant rather than a bare password
+    so a provider offering only federated or passwordless enrolment can refuse
+    the arm it does not implement instead of being handed a secret it will
+    discard. */
+type credential =
+  | Password(string)
+  /** Enrol with no secret held here: the principal sets one through the
+        provider's own flow, or signs in federated. */
+  | NoCredential
+
+/**
+Why an operation did not happen.
+
+Three arms rather than two, and the split is the one geocoding taught: **a
+provider outage is not a verdict.** `Unavailable` must be retried, because a
+caller reaching `createPrincipal` has already recorded that the address was
+proven and the person is entitled to an account. `Refused` is permanent and must
+surface. Collapsing them either loses accounts to a transient blip or retries
+forever against a password policy.
+*/
+type failure =
+  /** The contact is already a principal. A modelled answer, not an exception —
+        which is what a silent idempotent sign-up throws away. */
+  | Conflict
+  /** The provider is down or unreachable. The domain fact stands; retry. */
+  | Unavailable(string)
+  /** Permanently rejected — policy, password rules, a refused attribute. */
+  | Refused(string)
+
+/**
+One thing a provider can be asked to do.
+
+Published rather than fixed, because providers genuinely differ: one bound
+read-only to a corporate directory can create nothing, and one with no group
+model cannot be asked about groups. A caller reads this and degrades, instead of
+discovering the gap as a `Refused` on a live registration.
+
+**`setActiveRole` is deliberately absent.** Narrowing a caller's claims to the
+role they chose happens when a token is *minted* — on Cognito, in a
+pre-token-generation trigger. That is token issuance, which this capability's
+non-goal hands to the auth seam. Admitting it here would grow the surface along
+an axis that has nothing to do with whether the principal store is replaceable,
+which is the one thing this type exists to protect.
+*/
+type operation =
+  | CreatePrincipal
+  | AddToGroup
+  | RemoveFromGroup
+  | DeletePrincipal
+
+let operationToString = (operation: operation): string =>
+  switch operation {
+  | CreatePrincipal => "CreatePrincipal"
+  | AddToGroup => "AddToGroup"
+  | RemoveFromGroup => "RemoveFromGroup"
+  | DeletePrincipal => "DeletePrincipal"
+  }
+
+/**
+The port a caller reaches an identity provider through.
+
+`operations` is the provisioned set this deployment's provider actually
+supports, published rather than inferred. Build one through `make`, so a
+provider cannot claim an operation and omit the function that performs it.
+*/
+type t = {
+  createPrincipal: (
+    ~contact: Messaging.recipient,
+    ~credential: credential,
+    ~groups: array<string>,
+  ) => promise<result<principal, failure>>,
+  addToGroup: (~principal: principal, ~group: string) => promise<result<unit, failure>>,
+  removeFromGroup: (~principal: principal, ~group: string) => promise<result<unit, failure>>,
+  deletePrincipal: (~principal: principal) => promise<result<unit, failure>>,
+  operations: array<operation>,
+}
+
+let make = (~createPrincipal, ~addToGroup, ~removeFromGroup, ~deletePrincipal, ~operations): t => {
+  createPrincipal,
+  addToGroup,
+  removeFromGroup,
+  deletePrincipal,
+  operations,
+}
+
+let supports = (provider: t, ~operation: operation): bool =>
+  provider.operations->Array.includes(operation)
+
+/**
+A provider that performs nothing, answering `Unavailable` on every operation
+with an empty `operations`.
+
+The two say different true things and both are needed. The empty list is what a
+caller reads before offering a flow that cannot complete. The refusal stays
+`Unavailable` rather than `Refused` because a caller that got this far is looking
+at a deployment gap, not at a verdict on the person — and `Refused` would strand
+someone who has already proven their address.
+*/
+let unavailable = (~reason: string): t =>
+  make(
+    ~createPrincipal=async (~contact as _, ~credential as _, ~groups as _) => Error(
+      Unavailable(reason),
+    ),
+    ~addToGroup=async (~principal as _, ~group as _) => Error(Unavailable(reason)),
+    ~removeFromGroup=async (~principal as _, ~group as _) => Error(Unavailable(reason)),
+    ~deletePrincipal=async (~principal as _) => Error(Unavailable(reason)),
+    ~operations=[],
+  )

package/src/semantic/IdentityProvider.res.mjs

@@ -0,0 +1,65 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function operationToString(operation) {
+  switch (operation) {
+    case "CreatePrincipal" :
+      return "CreatePrincipal";
+    case "AddToGroup" :
+      return "AddToGroup";
+    case "RemoveFromGroup" :
+      return "RemoveFromGroup";
+    case "DeletePrincipal" :
+      return "DeletePrincipal";
+  }
+}
+
+function make(createPrincipal, addToGroup, removeFromGroup, deletePrincipal, operations) {
+  return {
+    createPrincipal: createPrincipal,
+    addToGroup: addToGroup,
+    removeFromGroup: removeFromGroup,
+    deletePrincipal: deletePrincipal,
+    operations: operations
+  };
+}
+
+function supports(provider, operation) {
+  return provider.operations.includes(operation);
+}
+
+function unavailable(reason) {
+  return make(async (param, param$1, param$2) => ({
+    TAG: "Error",
+    _0: {
+      TAG: "Unavailable",
+      _0: reason
+    }
+  }), async (param, param$1) => ({
+    TAG: "Error",
+    _0: {
+      TAG: "Unavailable",
+      _0: reason
+    }
+  }), async (param, param$1) => ({
+    TAG: "Error",
+    _0: {
+      TAG: "Unavailable",
+      _0: reason
+    }
+  }), async param => ({
+    TAG: "Error",
+    _0: {
+      TAG: "Unavailable",
+      _0: reason
+    }
+  }), []);
+}
+
+export {
+  operationToString,
+  make,
+  supports,
+  unavailable,
+}
+/* No side effect */

package/src/semantic/Secrets.res

@@ -0,0 +1,76 @@
+/**
+Unguessable material, and a one-way function over it.
+
+Injected rather than imported, and that is the whole point. A runtime global
+would work in production and leave every consumer's *issuance* untestable: a
+suite cannot assert what a flow does with a secret it cannot predict. Handing
+the generator in is what lets a test pin it, exactly as an injected geocoder
+lets a test pin a coordinate.
+
+Not a portability seam like the others — every target runtime has a
+cryptographic source, so this is not a provisioning choice anyone makes. It is
+here because the domain must not reach for one directly, and because a test must
+be able to replace it.
+*/
+/** What a secret is drawn from. Named rather than a charset string so a caller
+    cannot ask for an alphabet nothing checks — and so the two real cases stay
+    distinguishable: one is followed as a link, the other is retyped by a human
+    off a screen. */
+type alphabet =
+  /** `0`–`9`. For a code someone reads and types back. */
+  | Digits
+  /** `A`–`Z`, `a`–`z`, `0`–`9`, `-`, `_`. Survives a URL untouched. */
+  | UrlSafe
+
+/** The one way this fails: nothing here is a verdict about the caller. */
+type failure = Unavailable(string)
+
+/**
+The port a caller reaches a cryptographic source through.
+
+Both members answer `result` rather than a bare string, so a platform that
+provisioned nothing refuses instead of returning something weak. A token is the
+one value where a silent fallback is worse than an error: it would be accepted
+everywhere and guessable by anyone.
+*/
+type t = {
+  /** `length` characters drawn uniformly from `alphabet`. */
+  randomToken: (~length: int, ~alphabet: alphabet) => result<string, failure>,
+  /** One-way, so a challenge can be stored without storing what would answer
+        it. Deterministic: the same input always gives the same digest, which is
+        what lets a presented secret be compared against a held one. */
+  hash: string => result<string, failure>,
+}
+
+/** The characters each alphabet draws from. Exposed so an implementation and a
+    test agree on the set rather than each spelling it. */
+let characters = (alphabet: alphabet): string =>
+  switch alphabet {
+  | Digits => "0123456789"
+  | UrlSafe => "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+  }
+
+/**
+A source that produces nothing, refusing both operations.
+
+Named so a platform passing it is making a statement rather than filling in a
+blank — and refusing rather than degrading, because there is no weaker token
+that would be safe to hand back.
+*/
+let unavailable = (~reason: string): t => {
+  randomToken: (~length as _, ~alphabet as _) => Error(Unavailable(reason)),
+  hash: _ => Error(Unavailable(reason)),
+}
+
+/**
+A source that returns what it was given, for a test that needs to know the
+secret it is about to present.
+
+Here rather than in each suite because a consumer testing issuance needs exactly
+this and should not be inventing it — and because a fixed generator written per
+suite is one that eventually differs from the real one's alphabet.
+*/
+let fixed = (~token: string, ~hash as hashOf: string => string): t => {
+  randomToken: (~length as _, ~alphabet as _) => Ok(token),
+  hash: input => Ok(hashOf(input)),
+}

package/src/semantic/Secrets.res.mjs

@@ -0,0 +1,49 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function characters(alphabet) {
+  if (alphabet === "Digits") {
+    return "0123456789";
+  } else {
+    return "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+  }
+}
+
+function unavailable(reason) {
+  return {
+    randomToken: (param, param$1) => ({
+      TAG: "Error",
+      _0: {
+        TAG: "Unavailable",
+        _0: reason
+      }
+    }),
+    hash: param => ({
+      TAG: "Error",
+      _0: {
+        TAG: "Unavailable",
+        _0: reason
+      }
+    })
+  };
+}
+
+function fixed(token, hashOf) {
+  return {
+    randomToken: (param, param$1) => ({
+      TAG: "Ok",
+      _0: token
+    }),
+    hash: input => ({
+      TAG: "Ok",
+      _0: hashOf(input)
+    })
+  };
+}
+
+export {
+  characters,
+  unavailable,
+  fixed,
+}
+/* No side effect */

package/src/types/AccountsManifest.res

@@ -0,0 +1,287 @@
+/***
+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.
+
+`demoOwner` names the person this account plays in a demo's data, for a seed to
+find it by. It exists because the name a pool accepts is not always the demo's:
+a pool that signs in on an email address takes `shopper@example.com`, not
+`shopper`.
+*/
+@schema
+type entry = {
+  username: string,
+  password: string,
+  groups: array<string>,
+  userId?: string,
+  demoOwner?: 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}
+          }
+        }),
+      )
+    }
+  }