@reventlessdev/reventless-local 3.0.0-alpha.219 → 3.0.0-alpha.221

package/src/reset/LocalSeedReset.res.mjs

@@ -11,6 +11,7 @@ import * as Seed_Prompt$ReventlessSeed from "@reventlessdev/reventless-seed/src/
 import * as UiFragments$ReventlessCore from "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateViewSlice/UiFragments.res.mjs";
 import * as ComponentType$ReventlessCore from "@reventlessdev/reventless-core/src/ComponentType.res.mjs";
 import * as SqliteDriver$ReventlessLocal from "../adapter/SqliteDriver.res.mjs";
+import * as LocalSeedTarget$ReventlessLocal from "../LocalSeedTarget.res.mjs";
 import * as LocalObjectStore$ReventlessLocal from "../adapter/ObjectStore/LocalObjectStore.res.mjs";
 import * as PluginsReadModelSpec$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/lifecycle/PluginsReadModelSpec.res.mjs";
 import * as ObjectStoreStorage_FileSystem$ReventlessLocal from "../adapter/ObjectStore/ObjectStoreStorage_FileSystem.res.mjs";
@@ -437,33 +438,60 @@ function scopeOptions(plugins) {
 
 function run(dbPath) {
   let go = async () => {
-    let resolved;
-    if (dbPath !== undefined) {
-      resolved = dbPath;
-    } else {
+    let fromBackendEnv = () => {
       let match = Backend$ReventlessLocal.fromEnv();
       if (typeof match !== "object") {
-        console.log("Nothing to reset — REVENTLESS_LOCAL_BACKEND selects an in-memory store, which a restart already empties.");
-        resolved = undefined;
-      } else if (match.TAG === "Sqlite") {
-        let path = match.path;
-        if (path !== ":memory:") {
-          resolved = path;
-        } else {
-          console.log("Nothing to reset — REVENTLESS_LOCAL_BACKEND selects an in-memory store, which a restart already empties.");
-          resolved = undefined;
-        }
+        return {
+          TAG: "Error",
+          _0: "REVENTLESS_LOCAL_BACKEND selects an in-memory store, which a restart already empties."
+        };
+      }
+      if (match.TAG !== "Sqlite") {
+        return {
+          TAG: "Error",
+          _0: "the Postgres backend keeps its event logs off this machine. Reset it against the database."
+        };
+      }
+      let path = match.path;
+      if (path !== ":memory:") {
+        return {
+          TAG: "Ok",
+          _0: path
+        };
       } else {
-        console.log("Nothing to reset here — the Postgres backend keeps its event logs off this machine. Reset it against the database.");
-        resolved = undefined;
+        return {
+          TAG: "Error",
+          _0: "REVENTLESS_LOCAL_BACKEND selects an in-memory store, which a restart already empties."
+        };
       }
+    };
+    let match = Seed_Prompt$ReventlessSeed.envValue("REVENTLESS_LOCAL_BACKEND");
+    let resolved;
+    if (dbPath !== undefined) {
+      resolved = {
+        TAG: "Ok",
+        _0: dbPath
+      };
+    } else if (match !== undefined) {
+      resolved = fromBackendEnv();
+    } else {
+      let target = await LocalSeedTarget$ReventlessLocal.select();
+      LocalSeedTarget$ReventlessLocal.announce(target);
+      resolved = LocalSeedTarget$ReventlessLocal.storePath(target);
+    }
+    let resolved$1;
+    if (resolved.TAG === "Ok") {
+      resolved$1 = resolved._0;
+    } else {
+      console.log(`Nothing to reset — ` + resolved._0);
+      resolved$1 = undefined;
     }
-    if (resolved === undefined) {
+    if (resolved$1 === undefined) {
       return;
     }
-    if (Nodefs.existsSync(resolved)) {
-      let root = Nodepath.dirname(resolved);
-      let db = SqliteDriver$ReventlessLocal.openDb(resolved);
+    if (Nodefs.existsSync(resolved$1)) {
+      let root = Nodepath.dirname(resolved$1);
+      let db = SqliteDriver$ReventlessLocal.openDb(resolved$1);
       let plugins = readPlugins(db, root).map(p => p.plugin);
       let scope = await Seed_Prompt$ReventlessSeed.select("Reset scope:", scopeOptions(plugins), "SEED_RESET_SCOPE");
       let plan = build(db, root, scope);
@@ -500,7 +528,7 @@ function run(dbPath) {
       Seed_Prompt$ReventlessSeed.close();
       return SqliteDriver$ReventlessLocal.close(db);
     }
-    console.log(`Nothing to reset — no store at ` + resolved + `.`);
+    console.log(`Nothing to reset — no store at ` + resolved$1 + `.`);
   };
   go();
 }

package/tests/LocalPlatformRegistryTest.res

@@ -0,0 +1,143 @@
+// What the seed tools rely on when they ask "which platform do you mean".
+//
+// The failure these pin is not a crash: it is two tools reporting success about
+// different databases. `seed:reset` emptied the store its own environment named
+// while the platform served another, so the `seed` after it refused as though
+// nothing had been reset. Everything here is therefore about the registry
+// telling the truth — including when a platform died without cleaning up.
+
+@@warning("-44")
+
+open JestGlobals
+
+let tempRoot = (): string =>
+  NodeFs.mkdtempSync(NodePath.join([NodeOs.tmpdir(), "reventless-registry-"]))
+
+// Above any real pid on macOS and Linux, so `kill(pid, 0)` reports it gone
+// rather than hitting an unrelated process that happens to be running.
+let deadPid = 2147483646
+
+let sqliteStore = (path): LocalPlatformRegistry.store => {kind: "sqlite", path: Some(path)}
+let memoryStore: LocalPlatformRegistry.store = {kind: "memory", path: None}
+
+let writeAt = (~cwd, ~port, ~store, ~pid=NodeProcess.pid) =>
+  LocalPlatformRegistry.write(
+    ~port,
+    ~endpoint=`http://localhost:${port->Int.toString}/graphql`,
+    ~loginEndpoint=`http://localhost:${port->Int.toString}/__inmemory/login`,
+    ~store,
+    ~pid,
+    ~cwd,
+  )
+
+describe("LocalPlatformRegistry", () => {
+  testSync("reports a running platform with the store it opened", () => {
+    let cwd = tempRoot()
+    let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore("/abs/.reventless/runner.db"))
+
+    switch LocalPlatformRegistry.list(~cwd, ())->Array.get(0) {
+    | Some(entry) =>
+      expect(entry.port)->toEqual(4000)
+      expect(entry.endpoint)->toEqual("http://localhost:4000/graphql")
+      expect(entry.store.kind)->toEqual("sqlite")
+      expect(entry.store.path)->toEqual(Some("/abs/.reventless/runner.db"))
+    | None => fail("expected the entry just written to be listed")
+    }
+  })
+
+  // The pair that broke: same app, same directory, two platforms. A registry
+  // that could only hold one of them would answer with a coin flip.
+  testSync("lists both platforms in one directory, by port", () => {
+    let cwd = tempRoot()
+    let _ = writeAt(~cwd, ~port=4010, ~store=memoryStore)
+    let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore("/abs/.reventless/runner.db"))
+
+    let ports = LocalPlatformRegistry.list(~cwd, ())->Array.map(e => e.port)
+    expect(ports)->toEqual([4000, 4010])
+  })
+
+  testSync("drops an entry whose process is gone, and deletes it", () => {
+    let cwd = tempRoot()
+    let path = writeAt(~cwd, ~port=4000, ~store=sqliteStore("/abs/x.db"), ~pid=deadPid)
+
+    expect(LocalPlatformRegistry.list(~cwd, ()))->toEqual([])
+    // Pruned, not merely skipped: a file that survived would be re-read (and
+    // re-rejected) on every seed for the life of the working copy.
+    expect(NodeFs.existsSync(path))->toEqual(false)
+  })
+
+  testSync("drops an unreadable entry rather than failing the run", () => {
+    let cwd = tempRoot()
+    let dir = LocalPlatformRegistry.runningDir(~cwd, ())
+    NodeFs.mkdirSync(dir, {recursive: true})
+    let path = NodePath.join([dir, "4000.json"])
+    NodeFs.writeFileSync(path, "{ this is not json")
+
+    expect(LocalPlatformRegistry.list(~cwd, ()))->toEqual([])
+    expect(NodeFs.existsSync(path))->toEqual(false)
+  })
+
+  testSync("reads empty where no platform ever ran", () => {
+    expect(LocalPlatformRegistry.list(~cwd=tempRoot(), ()))->toEqual([])
+  })
+})
+
+describe("LocalSeedTarget.loginFor", () => {
+  // Setting only REVENTLESS_GRAPHQL_ENDPOINT used to leave the login round-trip
+  // on :4000 — seeding one platform through another's front door.
+  testSync("follows the endpoint's own host and port", () => {
+    expect(LocalSeedTarget.loginFor("http://localhost:4010/graphql"))->toEqual(
+      "http://localhost:4010/__inmemory/login",
+    )
+    expect(LocalSeedTarget.loginFor("http://127.0.0.1:9999/graphql"))->toEqual(
+      "http://127.0.0.1:9999/__inmemory/login",
+    )
+  })
+})
+
+describe("LocalSeedTarget.storePath", () => {
+  let target = (store: LocalPlatformRegistry.store): LocalSeedTarget.t => {
+    endpoint: "http://localhost:4000/graphql",
+    loginEndpoint: "http://localhost:4000/__inmemory/login",
+    origin: Running({
+      app: "demo",
+      port: 4000,
+      pid: NodeProcess.pid,
+      endpoint: "http://localhost:4000/graphql",
+      loginEndpoint: "http://localhost:4000/__inmemory/login",
+      store,
+      startedAt: "2026-08-14T00:00:00.000Z",
+    }),
+  }
+
+  testSync("hands back the file a SQLite platform opened", () => {
+    expect(target(sqliteStore("/abs/.reventless/runner.db"))->LocalSeedTarget.storePath)->toEqual(
+      Ok("/abs/.reventless/runner.db"),
+    )
+  })
+
+  // Three different reasons there is no file, and a tool that collapsed them
+  // would tell an in-memory platform to go and check its disk.
+  testSync("explains each kind of store it cannot open, naming the platform", () => {
+    let reason = t =>
+      switch t->LocalSeedTarget.storePath {
+      | Ok(_) => "unexpectedly resolved a path"
+      | Error(message) => message
+      }
+
+    expect(target(memoryStore)->reason->String.includes("in memory"))->toEqual(true)
+    expect(target(memoryStore)->reason->String.includes("localhost:4000"))->toEqual(true)
+    expect(
+      target({kind: "postgres", path: None})->reason->String.includes("off this machine"),
+    )->toEqual(true)
+    expect(
+      {
+        endpoint: "http://localhost:4000/graphql",
+        loginEndpoint: "http://localhost:4000/__inmemory/login",
+        origin: NoneRunning,
+      }
+      ->reason
+      ->String.includes("no local platform is running"),
+    )->toEqual(true)
+  })
+})

package/tests/LocalPlatformRegistryTest.res.mjs

@@ -0,0 +1,152 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodeos from "node:os";
+import * as Nodepath from "node:path";
+import * as JestGlobals from "@reventlessdev/rescript-jest/src/JestGlobals.res.mjs";
+import * as LocalSeedTarget$ReventlessLocal from "../src/LocalSeedTarget.res.mjs";
+import * as LocalPlatformRegistry$ReventlessLocal from "../src/LocalPlatformRegistry.res.mjs";
+
+function tempRoot() {
+  return Nodefs.mkdtempSync(Nodepath.join(Nodeos.tmpdir(), "reventless-registry-"));
+}
+
+function sqliteStore(path) {
+  return {
+    kind: "sqlite",
+    path: path
+  };
+}
+
+let memoryStore = {
+  kind: "memory",
+  path: undefined
+};
+
+function writeAt(cwd, port, store, pidOpt) {
+  let pid = pidOpt !== undefined ? pidOpt : process.pid;
+  return LocalPlatformRegistry$ReventlessLocal.write(port, `http://localhost:` + port.toString() + `/graphql`, `http://localhost:` + port.toString() + `/__inmemory/login`, store, pid, cwd);
+}
+
+globalThis.describe("LocalPlatformRegistry", () => {
+  globalThis.test("reports a running platform with the store it opened", () => {
+    let cwd = tempRoot();
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: "/abs/.reventless/runner.db"
+    }, undefined);
+    let entry = LocalPlatformRegistry$ReventlessLocal.list(cwd, undefined)[0];
+    if (entry !== undefined) {
+      globalThis.expect(entry.port).toEqual(4000);
+      globalThis.expect(entry.endpoint).toEqual("http://localhost:4000/graphql");
+      globalThis.expect(entry.store.kind).toEqual("sqlite");
+      globalThis.expect(entry.store.path).toEqual("/abs/.reventless/runner.db");
+      return;
+    } else {
+      return JestGlobals.fail("expected the entry just written to be listed");
+    }
+  });
+  globalThis.test("lists both platforms in one directory, by port", () => {
+    let cwd = tempRoot();
+    writeAt(cwd, 4010, memoryStore, undefined);
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: "/abs/.reventless/runner.db"
+    }, undefined);
+    let ports = LocalPlatformRegistry$ReventlessLocal.list(cwd, undefined).map(e => e.port);
+    globalThis.expect(ports).toEqual([
+      4000,
+      4010
+    ]);
+  });
+  globalThis.test("drops an entry whose process is gone, and deletes it", () => {
+    let cwd = tempRoot();
+    let path = writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: "/abs/x.db"
+    }, 2147483646);
+    globalThis.expect(LocalPlatformRegistry$ReventlessLocal.list(cwd, undefined)).toEqual([]);
+    globalThis.expect(Nodefs.existsSync(path)).toEqual(false);
+  });
+  globalThis.test("drops an unreadable entry rather than failing the run", () => {
+    let cwd = tempRoot();
+    let dir = LocalPlatformRegistry$ReventlessLocal.runningDir(cwd, undefined);
+    Nodefs.mkdirSync(dir, {
+      recursive: true
+    });
+    let path = Nodepath.join(dir, "4000.json");
+    Nodefs.writeFileSync(path, "{ this is not json", "utf8");
+    globalThis.expect(LocalPlatformRegistry$ReventlessLocal.list(cwd, undefined)).toEqual([]);
+    globalThis.expect(Nodefs.existsSync(path)).toEqual(false);
+  });
+  globalThis.test("reads empty where no platform ever ran", () => {
+    globalThis.expect(LocalPlatformRegistry$ReventlessLocal.list(tempRoot(), undefined)).toEqual([]);
+  });
+});
+
+globalThis.describe("LocalSeedTarget.loginFor", () => {
+  globalThis.test("follows the endpoint's own host and port", () => {
+    globalThis.expect(LocalSeedTarget$ReventlessLocal.loginFor("http://localhost:4010/graphql")).toEqual("http://localhost:4010/__inmemory/login");
+    globalThis.expect(LocalSeedTarget$ReventlessLocal.loginFor("http://127.0.0.1:9999/graphql")).toEqual("http://127.0.0.1:9999/__inmemory/login");
+  });
+});
+
+globalThis.describe("LocalSeedTarget.storePath", () => {
+  let target = store => ({
+    endpoint: "http://localhost:4000/graphql",
+    loginEndpoint: "http://localhost:4000/__inmemory/login",
+    origin: {
+      TAG: "Running",
+      _0: {
+        app: "demo",
+        port: 4000,
+        pid: process.pid,
+        endpoint: "http://localhost:4000/graphql",
+        loginEndpoint: "http://localhost:4000/__inmemory/login",
+        store: store,
+        startedAt: "2026-08-14T00:00:00.000Z"
+      }
+    }
+  });
+  globalThis.test("hands back the file a SQLite platform opened", () => {
+    globalThis.expect(LocalSeedTarget$ReventlessLocal.storePath(target({
+      kind: "sqlite",
+      path: "/abs/.reventless/runner.db"
+    }))).toEqual({
+      TAG: "Ok",
+      _0: "/abs/.reventless/runner.db"
+    });
+  });
+  globalThis.test("explains each kind of store it cannot open, naming the platform", () => {
+    let reason = t => {
+      let message = LocalSeedTarget$ReventlessLocal.storePath(t);
+      if (message.TAG === "Ok") {
+        return "unexpectedly resolved a path";
+      } else {
+        return message._0;
+      }
+    };
+    globalThis.expect(reason(target(memoryStore)).includes("in memory")).toEqual(true);
+    globalThis.expect(reason(target(memoryStore)).includes("localhost:4000")).toEqual(true);
+    globalThis.expect(reason(target({
+      kind: "postgres",
+      path: undefined
+    })).includes("off this machine")).toEqual(true);
+    globalThis.expect(reason({
+      endpoint: "http://localhost:4000/graphql",
+      loginEndpoint: "http://localhost:4000/__inmemory/login",
+      origin: "NoneRunning"
+    }).includes("no local platform is running")).toEqual(true);
+  });
+});
+
+let deadPid = 2147483646;
+
+export {
+  tempRoot,
+  deadPid,
+  sqliteStore,
+  memoryStore,
+  writeAt,
+}
+/*  Not a pure module */

package/tests/adapter/LocalAuthLoginTest.res

@@ -392,3 +392,47 @@ testPromise("switching refuses a token this server did not sign", async () => {
   | Error(msg) => expect(msg)->toEqual("Invalid token")
   }
 })
+
+// ── The shared conformance table ──────────────────────────────────────────
+//
+// The cases above were written against this path. `ReventlessCore.Auth_ActiveRole`
+// holds them in a form the Cognito path runs too — the two minting
+// implementations cannot share code across a process boundary, so a table both
+// drive is what keeps them from drifting. A case added there fails here until
+// this path satisfies it, which is the point.
+
+describe("the conformance table, minted locally", () => {
+  ReventlessCore.Auth_ActiveRole.conformanceCases->Array.forEach(({
+    label,
+    membership,
+    requested,
+    expected,
+  }) =>
+    testPromise(label, async () => {
+      resetAll()
+      LocalAuth.Login.setCredentials(
+        ~username="conformance",
+        ~password="pw",
+        ~identity={
+          userId: "u-conformance",
+          username: "conformance",
+          groups: membership,
+          provider: InMemory,
+        },
+      )
+      let minted = await LocalAuth.Login.issue(
+        ~username="conformance",
+        ~password="pw",
+        ~activeRole=?requested,
+      )
+      switch (minted, expected) {
+      | (Ok(token), Some(groups)) => expect(decodeOrThrow(token).groups)->toEqual(groups)
+      // `None` means refused — not honoured, not ignored, and not reduced to the
+      // empty set. A token minted here at all would be the vulnerability.
+      | (Ok(_), None) => JsError.throwWithMessage("expected the request to be refused")
+      | (Error(msg), Some(_)) => JsError.throwWithMessage("expected a token, got: " ++ msg)
+      | (Error(_), None) => expect(true)->toEqual(true)
+      }
+    })
+  )
+})

package/tests/adapter/LocalAuthLoginTest.res.mjs

@@ -4,6 +4,7 @@ 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 Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
 import * as LocalAuth$ReventlessLocal from "../../src/adapter/Auth/LocalAuth.res.mjs";
+import * as Auth_ActiveRole$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/Auth/Auth_ActiveRole.res.mjs";
 
 let alice_groups = ["Editor"];
 
@@ -378,6 +379,37 @@ globalThis.test("switching refuses a token this server did not sign", async () =
   globalThis.expect(msg._0).toEqual("Invalid token");
 });
 
+globalThis.describe("the conformance table, minted locally", () => {
+  Auth_ActiveRole$ReventlessCore.conformanceCases.forEach(param => {
+    let expected = param.expected;
+    let requested = param.requested;
+    let membership = param.membership;
+    globalThis.test(param.label, async () => {
+      resetAll();
+      LocalAuth$ReventlessLocal.Login.setCredentials("conformance", "pw", {
+        userId: "u-conformance",
+        username: "conformance",
+        groups: membership,
+        provider: "InMemory"
+      });
+      let minted = await LocalAuth$ReventlessLocal.Login.issue("conformance", "pw", requested);
+      if (minted.TAG === "Ok") {
+        if (expected !== undefined) {
+          globalThis.expect(decodeOrThrow(minted._0).groups).toEqual(expected);
+          return;
+        } else {
+          return Stdlib_JsError.throwWithMessage("expected the request to be refused");
+        }
+      } else if (expected !== undefined) {
+        return Stdlib_JsError.throwWithMessage("expected a token, got: " + minted._0);
+      } else {
+        globalThis.expect(true).toEqual(true);
+        return;
+      }
+    });
+  });
+});
+
 export {
   alice,
   bob,

package/tests/adapter/RequireGroupRefusalTest.res

@@ -0,0 +1,107 @@
+// Which refusal an admin-gated field gives, and why the two are not one.
+//
+// A group check has two ways to say no, and for a long time it said them with
+// one code. A caller the server identified who does not hold the group, a
+// caller whose token did not verify, and a caller who presented nothing at all
+// all read `UNAUTHORIZED` — so the answer a client can draw from a refusal is
+// the same in a case where presenting credentials again fixes it and a case
+// where it never will.
+//
+// Clients resolve that by guessing, and the guess that fits an expired token is
+// to discard the session. Applied to a caller who simply lacks the group, it
+// ends a session that is working perfectly — and on a platform whose discovery
+// surfaces are all admin-gated, every non-admin caller meets this refusal as a
+// matter of course.
+//
+// `FORBIDDEN` is the fact that removes the guess: the caller is known, and the
+// answer will not change if they authenticate again.
+
+open JestGlobals
+
+let identity = (~groups): Reventless.Identity.t => {
+  userId: "u-1",
+  username: "u",
+  groups,
+  provider: InMemory,
+}
+
+// The context shape `buildAuthContext` writes. Built here rather than driven
+// through a server so the two axes — holds the group, and was authenticated —
+// can be set independently, including the combination a real request cannot
+// produce but a malformed context can.
+let context = (~groups, ~authenticated): JSON.t =>
+  Obj.magic({"identity": identity(~groups), "authenticated": authenticated})
+
+let ok: GraphqlYoga.resolverFn = async (_root, _args, _ctx) => JSON.Encode.string("ran")
+
+// The thrown value is a `GraphQLError`, but a ReScript `catch` hands back its
+// own exception wrapper — so it is unwrapped before the message and extensions
+// are read off the raw object. No decoder: that shape is the contract this file
+// is about, and describing it through one would test the decoder instead.
+let describeRefusal = (e: exn): (string, string) =>
+  switch e->JsExn.fromException {
+  | None => ("not a JavaScript error", "")
+  | Some(js) => (js->JsExn.message->Option.getOr(""), (js->Obj.magic)["extensions"]["code"])
+  }
+
+let refusalOf = async (~groups, ~authenticated): result<JSON.t, (string, string)> => {
+  let guarded = Auth_GraphqlContext.requireGroup(~group="Admin", ok)
+  try {
+    Ok(await guarded(JSON.Encode.null, JSON.Encode.null, context(~groups, ~authenticated)))
+  } catch {
+  | e => Error(describeRefusal(e))
+  }
+}
+
+describe("requireGroup", () => {
+  testPromise("runs the resolver for a caller holding the group", async () => {
+    let outcome = await refusalOf(~groups=["Admin"], ~authenticated=true)
+    expect(outcome)->toEqual(Ok(JSON.Encode.string("ran")))
+  })
+
+  // The case that ended working sessions: a real caller, a real token, and a
+  // group they do not hold. Nothing about signing in again changes it.
+  testPromise("refuses an identified caller without the group as FORBIDDEN", async () => {
+    let outcome = await refusalOf(~groups=["Shopper"], ~authenticated=true)
+    expect(outcome)->toEqual(Error(("Forbidden: requires group \"Admin\"", "FORBIDDEN")))
+  })
+
+  // Unchanged, deliberately. A client reading only `UNAUTHORIZED` already treats
+  // it as "your credentials are not being honoured", and confining the code to
+  // the case where that holds makes such a client right rather than broken.
+  testPromise("refuses a caller it could not identify as UNAUTHORIZED", async () => {
+    let outcome = await refusalOf(~groups=[], ~authenticated=false)
+    expect(outcome)->toEqual(Error(("Unauthorized: requires group \"Admin\"", "UNAUTHORIZED")))
+  })
+
+  // A context without the key proves nothing about the caller, so it takes the
+  // reading that asks for credentials rather than the one that says theirs were
+  // read and found wanting.
+  testPromise("reads a context missing the outcome as unidentified", async () => {
+    let guarded = Auth_GraphqlContext.requireGroup(~group="Admin", ok)
+    let legacyContext: JSON.t = Obj.magic({"identity": identity(~groups=["Shopper"])})
+    let code = try {
+      let _ = await guarded(JSON.Encode.null, JSON.Encode.null, legacyContext)
+      "no refusal"
+    } catch {
+    | e => describeRefusal(e)->Pair.second
+    }
+    expect(code)->toBe("UNAUTHORIZED")
+  })
+})
+
+describe("isAuthenticated", () => {
+  testSync("a verified caller is authenticated", () =>
+    expect(Auth_GraphqlContext.isAuthenticated(Authenticated(identity(~groups=[]))))->toBe(true)
+  )
+
+  // The distinction `identityFromAuthResult` loses: both of these become the
+  // anonymous identity, and only one of them means credentials were rejected.
+  testSync("a rejected token is not", () =>
+    expect(Auth_GraphqlContext.isAuthenticated(AuthError("Invalid bearer token")))->toBe(false)
+  )
+
+  testSync("nor is an anonymous caller", () =>
+    expect(Auth_GraphqlContext.isAuthenticated(Anonymous))->toBe(false)
+  )
+})