@reventlessdev/reventless-local 3.0.0-alpha.216 → 3.0.0-alpha.218

package/src/ShellConfig.res.mjs

@@ -0,0 +1,114 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
+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 Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
+import * as HostShellDist$ReventlessLocal from "./HostShellDist.res.mjs";
+import * as Platform_BakedManifest$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_BakedManifest.res.mjs";
+
+let log = Logger$ReventlessCore.fromEnv();
+
+let fileName = "config.json";
+
+let baselineFileName = "config.base.json";
+
+function manifestUrlOf(config) {
+  return Platform_BakedManifest$ReventlessCore.urlForKey(config.key);
+}
+
+let journeyManifestsKey = "journeyManifestUrls";
+
+let computedKeys = [
+  "manifestUrl",
+  journeyManifestsKey
+];
+
+function overlay(bakedManifest, shellConfig) {
+  let out = {};
+  Stdlib_Option.forEach(bakedManifest, config => {
+    out["manifestUrl"] = Platform_BakedManifest$ReventlessCore.urlForKey(config.key);
+    let journeys = config.journeys;
+    if (journeys === undefined) {
+      return;
+    }
+    if (journeys.length === 0) {
+      return;
+    }
+    let map = {};
+    journeys.forEach(j => {
+      map[j.group] = Platform_BakedManifest$ReventlessCore.urlForKey(Stdlib_Option.getOr(j.key, Platform_BakedManifest$ReventlessCore.journeyKey(j.group)));
+    });
+    out[journeyManifestsKey] = map;
+  });
+  Stdlib_Option.forEach(shellConfig, extra => {
+    let collisions = Object.keys(extra).filter(k => computedKeys.includes(k));
+    if (collisions.length !== 0) {
+      Stdlib_JsError.throwWithMessage("host UI config.json: shellConfig sets key(s) the platform already computes — " + collisions.join(", ") + ". Remove them from shellConfig; a passthrough cannot redirect a computed key.");
+    }
+    Stdlib_Dict.forEachWithKey(extra, (v, k) => {
+      out[k] = v;
+    });
+  });
+  return out;
+}
+
+function readObject(path, label) {
+  let obj;
+  try {
+    obj = Stdlib_JSON.Decode.object(JSON.parse(Nodefs.readFileSync(path, "utf8")));
+  } catch (exn) {
+    return Stdlib_JsError.throwWithMessage(`host UI ` + label + `: cannot read ` + path + ` as JSON`);
+  }
+  if (obj !== undefined) {
+    return obj;
+  } else {
+    return Stdlib_JsError.throwWithMessage(`host UI ` + label + `: ` + path + ` is not a JSON object`);
+  }
+}
+
+function emit(bakedManifest, shellConfig, dir) {
+  let overlay$1 = overlay(bakedManifest, shellConfig);
+  let dir$1 = dir !== undefined ? dir : HostShellDist$ReventlessLocal.dir();
+  if (dir$1 === undefined) {
+    if (Object.keys(overlay$1).length !== 0) {
+      return Stdlib_JsError.throwWithMessage(`host UI config.json: cannot resolve ` + HostShellDist$ReventlessLocal.$$package + ` from ` + process.cwd() + ` — the local shell reads its config from that package's dist/, so declaring shell config without the package installed would write nothing and leave the shell configured as it shipped.`);
+    } else {
+      return;
+    }
+  }
+  let path = Nodepath.join(dir$1, fileName);
+  let baselinePath = Nodepath.join(dir$1, baselineFileName);
+  if (!Nodefs.existsSync(baselinePath) && Object.keys(overlay$1).length !== 0) {
+    if (!Nodefs.existsSync(path)) {
+      Stdlib_JsError.throwWithMessage(`host UI config.json: ` + HostShellDist$ReventlessLocal.$$package + ` ships no ` + fileName + ` at ` + dir$1 + ` — there is no baseline to overlay, so the shell would boot with only the keys declared here and none of the ones it expects.`);
+    }
+    Nodefs.writeFileSync(baselinePath, Nodefs.readFileSync(path, "utf8"), "utf8");
+  }
+  if (!Nodefs.existsSync(baselinePath)) {
+    return;
+  }
+  let merged = readObject(baselinePath, "config baseline");
+  Stdlib_Dict.forEachWithKey(overlay$1, (v, k) => {
+    merged[k] = v;
+  });
+  Nodefs.writeFileSync(path, JSON.stringify(merged, undefined, 2), "utf8");
+  let keys = Object.keys(overlay$1);
+  log.info("ShellConfig", undefined, keys.length === 0 ? `restored ` + fileName + ` from ` + baselineFileName + `: ` + path : `wrote ` + fileName + ` with ` + keys.join(", ") + `: ` + path);
+}
+
+export {
+  log,
+  fileName,
+  baselineFileName,
+  manifestUrlOf,
+  journeyManifestsKey,
+  computedKeys,
+  overlay,
+  readObject,
+  emit,
+}
+/* log Not a pure module */

package/src/UiHints.res

@@ -0,0 +1,107 @@
+// Serves the AutoUI hints file a deployment declared, where the local host
+// shell serves its static assets from (`HostShellDist`).
+//
+// On AWS `uiHintsFile` is read and written verbatim as a `BucketObject` beside
+// `config.json`, and the host-shell package's own `ui-hints.json` is excluded
+// from the upload as the dev-mode fallback it is. Locally that fallback is in
+// the mode it exists for, so an undeclared platform goes on serving it — but a
+// declared file has to win, or the hints a deployment authors are the only ones
+// its dev shell never applies.
+//
+// Hence the baseline, for the reason `ShellConfig` keeps one: without it a
+// withdrawn declaration leaves yesterday's hints in place with nothing in the
+// diff to explain them. Unlike `ShellConfig` there is no merge — AWS writes the
+// declared file verbatim, and layering a deployment's hints over the shell
+// package's demonstration hints would invent a third behaviour neither platform
+// has.
+
+let log = ReventlessCore.Logger.fromEnv()
+
+let fileName = "ui-hints.json"
+
+// Keeps the `.json` extension for the same reason `config.base.json` does: the
+// dist is served as a static directory, and a dev can open the baseline in a
+// browser to see what the declaration replaced.
+let baselineFileName = "ui-hints.base.json"
+
+/**
+ Write the declared hints into the served `dist/`, or restore the shipped file
+ when nothing is declared.
+
+ A no-op when there is nothing to say and nothing was said before, so a platform
+ that declares no hints is byte-identical to one built before this existed.
+ Once a file is declared the write happens or fails loudly: a path that does not
+ resolve, content that is not JSON, and a missing shell package are all the
+ deployment's own mistake, and all three produce the same symptom if swallowed —
+ hints that quietly are not applied.
+ */
+let emit = (
+  ~uiHintsFile: option<string>,
+  // Test seam, as in `ShellConfig.emit`: the baseline dance is the part with
+  // state behind it, and "boot twice and the second write still starts from the
+  // shipped file" is not a property a pure function can carry.
+  ~dir: option<string>=?,
+) => {
+  // Read before anything is touched, so a bad declaration cannot leave the
+  // served file half-replaced.
+  let declared = uiHintsFile->Option.map(path => {
+    let source = switch NodeFs.readFileSync(path) {
+    | contents => contents
+    | exception _ =>
+      JsError.throwWithMessage(
+        `host UI ${fileName}: cannot read the declared uiHintsFile at ${path} — ` ++
+        `the shell fetches this file at boot, so a declaration pointing nowhere ` ++
+        `applies no hints and says nothing about why.`,
+      )
+    }
+    switch source->JSON.parseOrThrow {
+    | _ => ()
+    | exception _ =>
+      JsError.throwWithMessage(
+        `host UI ${fileName}: the declared uiHintsFile at ${path} is not JSON — ` ++
+        `the shell warns once and applies no hints, which reads as hints that do nothing.`,
+      )
+    }
+    source
+  })
+
+  switch (
+    switch dir {
+    | Some(_) as given => given
+    | None => HostShellDist.dir()
+    }
+  ) {
+  | None =>
+    // No shell installed is the ordinary case for a platform nobody points a
+    // browser at; only a declaration makes the missing package an error.
+    if declared->Option.isSome {
+      JsError.throwWithMessage(
+        `host UI ${fileName}: cannot resolve ${HostShellDist.package} from ${NodeProcess.cwd()} — ` ++
+        `the local shell reads its hints from that package's dist/, so declaring a ` ++
+        `uiHintsFile without the package installed would write nothing and leave the ` ++
+        `shell applying whatever the package shipped.`,
+      )
+    }
+  | Some(dir) =>
+    let path = NodePath.join([dir, fileName])
+    let baselinePath = NodePath.join([dir, baselineFileName])
+
+    // Seeded only when there is something to replace it with. A platform that
+    // declares nothing must not leave a baseline behind for the next one to
+    // read as authoritative.
+    if !NodeFs.existsSync(baselinePath) && declared->Option.isSome && NodeFs.existsSync(path) {
+      NodeFs.writeFileSync(baselinePath, NodeFs.readFileSync(path))
+    }
+
+    switch declared {
+    | Some(contents) =>
+      NodeFs.writeFileSync(path, contents)
+      log.info(~comp="UiHints", `wrote ${fileName} from the declared uiHintsFile: ${path}`)
+    | None =>
+      if NodeFs.existsSync(baselinePath) {
+        NodeFs.writeFileSync(path, NodeFs.readFileSync(baselinePath))
+        log.info(~comp="UiHints", `restored ${fileName} from ${baselineFileName}: ${path}`)
+      }
+    }
+  }
+}

package/src/UiHints.res.mjs

@@ -0,0 +1,61 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
+import * as HostShellDist$ReventlessLocal from "./HostShellDist.res.mjs";
+
+let log = Logger$ReventlessCore.fromEnv();
+
+let fileName = "ui-hints.json";
+
+let baselineFileName = "ui-hints.base.json";
+
+function emit(uiHintsFile, dir) {
+  let declared = Stdlib_Option.map(uiHintsFile, path => {
+    let source;
+    try {
+      source = Nodefs.readFileSync(path, "utf8");
+    } catch (exn) {
+      source = Stdlib_JsError.throwWithMessage(`host UI ` + fileName + `: cannot read the declared uiHintsFile at ` + path + ` — the shell fetches this file at boot, so a declaration pointing nowhere applies no hints and says nothing about why.`);
+    }
+    try {
+      JSON.parse(source);
+    } catch (exn$1) {
+      Stdlib_JsError.throwWithMessage(`host UI ` + fileName + `: the declared uiHintsFile at ` + path + ` is not JSON — the shell warns once and applies no hints, which reads as hints that do nothing.`);
+    }
+    return source;
+  });
+  let dir$1 = dir !== undefined ? dir : HostShellDist$ReventlessLocal.dir();
+  if (dir$1 === undefined) {
+    if (Stdlib_Option.isSome(declared)) {
+      return Stdlib_JsError.throwWithMessage(`host UI ` + fileName + `: cannot resolve ` + HostShellDist$ReventlessLocal.$$package + ` from ` + process.cwd() + ` — the local shell reads its hints from that package's dist/, so declaring a uiHintsFile without the package installed would write nothing and leave the shell applying whatever the package shipped.`);
+    } else {
+      return;
+    }
+  }
+  let path = Nodepath.join(dir$1, fileName);
+  let baselinePath = Nodepath.join(dir$1, baselineFileName);
+  if (!Nodefs.existsSync(baselinePath) && Stdlib_Option.isSome(declared) && Nodefs.existsSync(path)) {
+    Nodefs.writeFileSync(baselinePath, Nodefs.readFileSync(path, "utf8"), "utf8");
+  }
+  if (declared !== undefined) {
+    Nodefs.writeFileSync(path, declared, "utf8");
+    return log.info("UiHints", undefined, `wrote ` + fileName + ` from the declared uiHintsFile: ` + path);
+  } else if (Nodefs.existsSync(baselinePath)) {
+    Nodefs.writeFileSync(path, Nodefs.readFileSync(baselinePath, "utf8"), "utf8");
+    return log.info("UiHints", undefined, `restored ` + fileName + ` from ` + baselineFileName + `: ` + path);
+  } else {
+    return;
+  }
+}
+
+export {
+  log,
+  fileName,
+  baselineFileName,
+  emit,
+}
+/* log Not a pure module */

package/src/adapter/Auth/Auth_GraphqlContext.res

@@ -54,12 +54,10 @@ let extractIdentity = (ctx: JSON.t): Reventless.Identity.t =>
   | _ => Reventless.Identity.anonymous
   }
 
-// Throw a `GraphQLError` from the `graphql` package — yoga's `maskedErrors`
-// option preserves these (only opaque thrown values get masked as
-// "Unexpected error / INTERNAL_SERVER_ERROR"). Mirrors the directive-level
-// `@aws_auth` rejection that AppSync surfaces in production.
-@new @module("graphql")
-external makeGraphqlError: (string, {"extensions": {"code": string}}) => exn = "GraphQLError"
+// An unauthorized caller reads the reason: `GraphQL_CallerError` explains why a
+// resolver has to construct the error rather than throw a bare one. Mirrors the
+// directive-level `@aws_auth` rejection that AppSync surfaces in production.
+let makeGraphqlError = GraphQL_CallerError.make
 
 let unauthorizedError = (~group: string): exn =>
   makeGraphqlError(

package/src/adapter/Auth/Auth_GraphqlContext.res.mjs

@@ -44,6 +44,10 @@ function extractIdentity(ctx) {
   }
 }
 
+function makeGraphqlError(prim0, prim1) {
+  return new Graphql.GraphQLError(prim0, prim1);
+}
+
 function unauthorizedError(group) {
   return new Graphql.GraphQLError(`Unauthorized: requires group "` + group + `"`, {
     extensions: {
@@ -70,6 +74,7 @@ export {
   identityFromAuthResult,
   buildAuthContext,
   extractIdentity,
+  makeGraphqlError,
   unauthorizedError,
   requireGroup,
 }

package/src/adapter/Auth/LocalAuth.res

@@ -138,17 +138,107 @@ module Login = {
     }
   }
 
-  /** Verifies credentials and returns a signed token (or an error string). */
-  let issue = async (~username: string, ~password: string): result<string, string> =>
+  /**
+   Claim naming the role the caller chose to act as. Present only on a narrowed
+   token, so its presence *is* the answer to "am I acting as one of my roles?".
+
+   Kept apart from `groups` even though a narrowed token's groups are exactly
+   this one role, because the two say different things: `groups` is what every
+   enforcement point evaluates, and this is what the caller asked for. A client
+   reading the choice out of the group array would be depending on the current
+   shape of the narrowing rather than on the choice itself.
+   */
+  let activeRoleClaim = "activeRole"
+
+  /**
+   Claim naming the roles the caller gave up by narrowing — their full
+   membership, comma-joined as the `X-Groups` header already joins groups.
+
+   🚨 **Never read this for authorization.** It exists so a client can offer the
+   switch back, and it is by definition wider than what the caller is currently
+   permitted. Every enforcement point in the system reads `groups`; this claim is
+   the one piece of an identity that deliberately describes privilege the caller
+   does *not* currently have.
+
+   Present only on a narrowed token, which is also what keeps an ordinary login
+   byte-identical to what it minted before any of this existed: an unnarrowed
+   token's `groups` already *are* the full membership, so there is nothing to
+   remember.
+   */
+  let availableRolesClaim = "availableRoles"
+
+  /**
+   Narrow an identity to one of its own roles.
+
+   `Error` when the role is not one the caller holds. Refusing rather than
+   ignoring is the security-critical line of this feature: a request for a group
+   the user does not have is either confused or hostile, and a token that
+   silently does not match what was asked for serves neither. Because the check
+   is a subset test against actual membership, a tampering client can only ever
+   reduce its own privilege.
+   */
+  let narrow = (identity: Identity.t, ~activeRole: string): result<Identity.t, string> =>
+    if !(identity.groups->Array.includes(activeRole)) {
+      Error(`Cannot act as "${activeRole}": not a group this user holds`)
+    } else {
+      let claims = switch identity.claims {
+      | Some(existing) => Dict.fromArray(existing->Dict.toArray)
+      | None => Dict.make()
+      }
+      claims->Dict.set(activeRoleClaim, activeRole)
+      claims->Dict.set(availableRolesClaim, identity.groups->Array.join(","))
+      Ok({...identity, groups: [activeRole], claims})
+    }
+
+  /**
+   Verifies credentials and returns a signed token (or an error string).
+
+   `activeRole` narrows the minted token to one of the caller's own roles; unset
+   mints exactly what it has always minted.
+   */
+  let issue = async (
+    ~username: string,
+    ~password: string,
+    ~activeRole: option<string>=?,
+  ): result<string, string> =>
     switch store.contents->Dict.get(username) {
     | Some({password: stored, identity}) if stored === password =>
-      let json = identity->S.reverseConvertToJsonOrThrow(Identity.schema)->JSON.stringify
-      let payload = _b64urlEncode(json)
-      let sig = _sign(payload)
-      Ok(`${payload}.${sig}`)
+      switch switch activeRole {
+      | None => Ok(identity)
+      | Some(role) => identity->narrow(~activeRole=role)
+      } {
+      | Error(_) as e => e
+      | Ok(minted) =>
+        let json = minted->S.reverseConvertToJsonOrThrow(Identity.schema)->JSON.stringify
+        let payload = _b64urlEncode(json)
+        let sig = _sign(payload)
+        Ok(`${payload}.${sig}`)
+      }
     | _ => Error("Invalid credentials")
     }
 
+  /**
+   The identity a token carries, for a caller that has just been issued one.
+
+   Exists so the login response can echo the *minted* identity rather than the
+   stored one. They differ exactly when the token is narrowed, and a response
+   disagreeing with the token it accompanies would leave the client a step behind
+   the server from its very first request.
+   */
+  let mintedIdentity = (~username: string, ~activeRole: option<string>): option<Identity.t> =>
+    store.contents
+    ->Dict.get(username)
+    ->Option.flatMap(({identity, _}) =>
+      switch activeRole {
+      | None => Some(identity)
+      | Some(role) =>
+        switch identity->narrow(~activeRole=role) {
+        | Ok(narrowed) => Some(narrowed)
+        | Error(_) => None
+        }
+      }
+    )
+
   /**
    * Returns the embedded Identity if signature verifies and the payload
    * decodes; `None` for any tampered, malformed, or unsigned token.
@@ -167,6 +257,46 @@ module Login = {
     | _ => None
     }
   }
+
+  /**
+   Re-mint an existing session as one of the caller's roles.
+
+   A switch is not a fresh login: the client holds a token, not a password, and
+   asking for the password again to change role would make an ordinary
+   navigation a re-authentication. Possession of a token this server signed is
+   already proof of the credentials that produced it.
+
+   🚨 **Membership is re-read from the store, never from the presented token.**
+   A narrowed token carries `availableRolesClaim`, and widening back by trusting
+   it would make the record of what a caller gave up into the authority for
+   getting it back. The signature makes that claim authentic, not correct: the
+   store is where membership actually lives, and re-reading it means a role
+   revoked since the token was issued cannot be switched into.
+
+   `activeRole` unset widens back to full membership — which is not a privilege
+   escalation, because the subset being widened *to* is the one the store says
+   the caller has.
+   */
+  let reissue = (~token: string, ~activeRole: option<string>): result<string, string> =>
+    switch verifyAndDecode(token) {
+    | None => Error("Invalid token")
+    | Some(presented) =>
+      switch store.contents->Dict.get(presented.username) {
+      | None => Error("Unknown user")
+      | Some({identity, _}) =>
+        switch switch activeRole {
+        | None => Ok(identity)
+        | Some(role) => identity->narrow(~activeRole=role)
+        } {
+        | Error(_) as e => e
+        | Ok(minted) =>
+          let json = minted->S.reverseConvertToJsonOrThrow(Identity.schema)->JSON.stringify
+          let payload = _b64urlEncode(json)
+          Ok(`${payload}.${_sign(payload)}`)
+        }
+      }
+    }
+
 }
 
 // ── Provider implementation ───────────────────────────────────────────────

package/src/adapter/Auth/LocalAuth.res.mjs

@@ -118,7 +118,29 @@ function _b64urlDecode(s) {
   }
 }
 
-async function issue(username, password) {
+let activeRoleClaim = "activeRole";
+
+let availableRolesClaim = "availableRoles";
+
+function narrow(identity, activeRole) {
+  if (!identity.groups.includes(activeRole)) {
+    return {
+      TAG: "Error",
+      _0: `Cannot act as "` + activeRole + `": not a group this user holds`
+    };
+  }
+  let existing = identity.claims;
+  let claims = existing !== undefined ? Object.fromEntries(Object.entries(existing)) : ({});
+  claims[activeRoleClaim] = activeRole;
+  claims[availableRolesClaim] = identity.groups.join(",");
+  let newrecord = {...identity};
+  return {
+    TAG: "Ok",
+    _0: (newrecord.claims = claims, newrecord.groups = [activeRole], newrecord)
+  };
+}
+
+async function issue(username, password, activeRole) {
   let match = store.contents[username];
   if (match === undefined) {
     return {
@@ -132,7 +154,15 @@ async function issue(username, password) {
       _0: "Invalid credentials"
     };
   }
-  let json = JSON.stringify(S.reverseConvertToJsonOrThrow(match.identity, Identity$Reventless.schema));
+  let identity = match.identity;
+  let e = activeRole !== undefined ? narrow(identity, activeRole) : ({
+      TAG: "Ok",
+      _0: identity
+    });
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let json = JSON.stringify(S.reverseConvertToJsonOrThrow(e._0, Identity$Reventless.schema));
   let payload = _b64urlEncode(json);
   let sig = _sign(payload);
   return {
@@ -141,6 +171,19 @@ async function issue(username, password) {
   };
 }
 
+function mintedIdentity(username, activeRole) {
+  return Stdlib_Option.flatMap(store.contents[username], param => {
+    let identity = param.identity;
+    if (activeRole === undefined) {
+      return identity;
+    }
+    let narrowed = narrow(identity, activeRole);
+    if (narrowed.TAG === "Ok") {
+      return narrowed._0;
+    }
+  });
+}
+
 function verifyAndDecode(token) {
   let parts = token.split(".");
   let match = parts[0];
@@ -156,6 +199,37 @@ function verifyAndDecode(token) {
   }
 }
 
+function reissue(token, activeRole) {
+  let presented = verifyAndDecode(token);
+  if (presented === undefined) {
+    return {
+      TAG: "Error",
+      _0: "Invalid token"
+    };
+  }
+  let match = store.contents[presented.username];
+  if (match === undefined) {
+    return {
+      TAG: "Error",
+      _0: "Unknown user"
+    };
+  }
+  let identity = match.identity;
+  let e = activeRole !== undefined ? narrow(identity, activeRole) : ({
+      TAG: "Ok",
+      _0: identity
+    });
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let json = JSON.stringify(S.reverseConvertToJsonOrThrow(e._0, Identity$Reventless.schema));
+  let payload = _b64urlEncode(json);
+  return {
+    TAG: "Ok",
+    _0: payload + `.` + _sign(payload)
+  };
+}
+
 let Login = {
   store: store,
   setCredentials: setCredentials,
@@ -166,8 +240,13 @@ let Login = {
   _sign: _sign,
   _b64urlEncode: _b64urlEncode,
   _b64urlDecode: _b64urlDecode,
+  activeRoleClaim: activeRoleClaim,
+  availableRolesClaim: availableRolesClaim,
+  narrow: narrow,
   issue: issue,
-  verifyAndDecode: verifyAndDecode
+  mintedIdentity: mintedIdentity,
+  verifyAndDecode: verifyAndDecode,
+  reissue: reissue
 };
 
 function _bearerToken(header) {

package/src/adapter/CommandGenerator/CommandGeneratorResolvers_GraphQL.res

@@ -159,6 +159,27 @@ let deriveSdlField = (~fieldName, variantSchema: S.t<unknown>) =>
 
 let handlerRefs: dict<ref<option<CommandGenerator.commandGenerator>>> = Dict.make()
 
+// Run a command through its generator, letting a failure that describes the
+// caller's own request reach them.
+//
+// Without this every such failure arrives as "Unexpected error /
+// INTERNAL_SERVER_ERROR": yoga masks anything that is not a `GraphQLError`, so
+// a payload that does not decode and a database outage read identically from
+// outside. Only errors core marked as the caller's are unwrapped — everything
+// else propagates untouched and stays masked, which is what masking is for.
+let runCommand = async (
+  generateCommand: CommandGenerator.commandGenerator,
+  payload: CommandGenerator.payload,
+) =>
+  try await generateCommand(payload)->Effect.runPromise catch {
+  | e if ReventlessCore.Plugin_ResolverError.isCallerFault(e) =>
+    throw(
+      GraphQL_CallerError.badUserInput(
+        e->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("invalid command"),
+      ),
+    )
+  }
+
 // -- register (Phase 1 — synchronous, Aggregates) ----------------------------
 // Called by Plugin_Builder via aggregateMutationResolverHook before any
 // Output.apply chains fire. Registers SDL + resolver stubs in GraphQL_Server.
@@ -210,7 +231,7 @@ let register = (
               meta: {ip: [], user: identity.userId, info: `Mutation.${field}`},
               identity,
             }
-            let outcome = await generateCommand(payload)->Effect.runPromise
+            let outcome = await runCommand(generateCommand, payload)
             outcome->commandOutcomeToJson
           }
         }
@@ -273,7 +294,7 @@ let registerDcb = (
             meta: {ip: [], user: identity.userId, info: `Mutation.${fieldName}`},
             identity,
           }
-          let outcome = await generateCommand(payload)->Effect.runPromise
+          let outcome = await runCommand(generateCommand, payload)
           outcome->commandOutcomeToJson
         }
       }