@reventlessdev/reventless-seed 1.0.0-alpha.2 → 1.0.0-alpha.21

package/lib/ocaml/Seed_ClientTest.res

@@ -0,0 +1,287 @@
+open JestGlobals
+
+// A seed issues hundreds of commands against runtimes a preceding reset left
+// cold, so the endpoint faulting on one of them is a normal event rather than an
+// exceptional one. Before the retry, a single `InternalFailure` in that batch
+// aborted the run and left a half-seeded store that could only be recovered by a
+// full wipe and a re-run — for a request that would have succeeded on being
+// asked again.
+//
+// What makes the retry safe is the classifier, so that is what these pin. A
+// fault on the endpoint's side carries no information about the document and is
+// worth resending; anything that is an *answer* — a validation error, an unknown
+// field, a refused token — comes back identical however many times it is asked,
+// and resending it only delays the failure the operator needs to see.
+
+let errors = entries => JSON.Encode.array(entries->Array.map(JSON.Encode.object))
+
+let errorOfType = errorType => Dict.fromArray([("errorType", JSON.Encode.string(errorType))])
+
+describe("Seed_Client.isTransient:", () => {
+  testSync("resends a fault on the endpoint's own side", () =>
+    [
+      "InternalFailure",
+      "ServiceUnavailable",
+      "Throttling",
+      "TooManyRequestsException",
+    ]->Array.forEach(t => expect(Seed_Client.isTransient(errors([errorOfType(t)])))->toBe(true))
+  )
+
+  // The exact payload the seed aborted on.
+  testSync("resends the shape AppSync actually returned", () => {
+    let payload = JSON.parseOrThrow(`[{"errorType":"InternalFailure","message":"An internal failure occurred."}]`)
+    expect(Seed_Client.isTransient(payload))->toBe(true)
+  })
+
+  testSync("fails fast on an error that is an answer", () =>
+    ["ValidationException", "Unauthorized", "FieldUndefined"]->Array.forEach(
+      t => expect(Seed_Client.isTransient(errors([errorOfType(t)])))->toBe(false),
+    )
+  )
+
+  // A real error sitting alongside a transient one still means the request was
+  // wrong, and resending it cannot make it right.
+  testSync("refuses to resend a batch that mixes a real error in", () =>
+    expect(
+      Seed_Client.isTransient(
+        errors([errorOfType("InternalFailure"), errorOfType("ValidationException")]),
+      ),
+    )->toBe(false)
+  )
+
+  // `Array.every` is vacuously true on an empty array, which would turn "the
+  // endpoint said errors but named none" into an endless resend.
+  testSync("treats an empty or untyped error list as final", () => {
+    expect(Seed_Client.isTransient(errors([])))->toBe(false)
+    expect(
+      Seed_Client.isTransient(errors([Dict.fromArray([("message", JSON.Encode.string("boom"))])])),
+    )->toBe(false)
+    expect(Seed_Client.isTransient(JSON.Encode.null))->toBe(false)
+  })
+})
+
+// An account's listed groups are not what authorizes it — the token's are. Both
+// platforms narrow a token to the single role the caller last chose, so a seed
+// can log in as an account the user list shows as `[Admin, Shopper]` and present
+// a token carrying `Shopper` alone. The refusal that follows names the field and
+// not the caller, and the account list cannot explain it either. These pin the
+// reading-back that turns that into a sentence.
+
+let b64url = payload =>
+  payload
+  ->NodeBuffer.fromStringUtf8
+  ->NodeBuffer.toStringBase64Url
+
+// A REAL JOSE header, not the literal string "header". The difference is the
+// whole bug: `{"kid":…,"alg":"RS256"}` is base64url JSON and decodes exactly as
+// the payload does, so `claims` took it as the claims set and found no groups
+// and no id in any Cognito token ever issued. A fake header that happened not to
+// decode is what let every assertion below pass against broken code.
+let joseHeader = b64url(`{"kid":"abc123","alg":"RS256"}`)
+
+let jwt = claims =>
+  `${joseHeader}.${b64url(JSON.stringify(JSON.Encode.object(Dict.fromArray(claims))))}.signature`
+
+let localToken = claims =>
+  `${b64url(JSON.stringify(JSON.Encode.object(Dict.fromArray(claims))))}.signature`
+
+let strings = values => JSON.Encode.array(values->Array.map(JSON.Encode.string))
+
+let clientWith = token => {
+  let c = Seed_Client.make(~config={endpoint: "http://example.invalid/graphql"})
+  c->Seed_Client.useToken(token)
+  c
+}
+
+describe("Seed_Client.claims:", () => {
+  // The regression this file could not previously express. A JWT header is a
+  // decodable JSON object sitting in front of the payload, so "the first segment
+  // that parses" is the header on every real token — and the seed then reported
+  // no groups, printed no `Acting as:` line, and attached no identity to a
+  // refusal, which is exactly the diagnosis it exists to give.
+  testSync("skips the JOSE header and reads the payload behind it", () =>
+    expect(
+      clientWith(jwt([("sub", JSON.Encode.string("real-sub"))]))
+      ->Seed_Client.claims
+      ->Option.flatMap(c => c->Dict.get("sub"))
+      ->Option.flatMap(JSON.Decode.string),
+    )->toEqual(Some("real-sub"))
+  )
+
+  // The header is identified by `alg`, not by position — a two-segment local dev
+  // token has no header at all, and its payload must not be mistaken for one.
+  testSync("takes the first segment when there is no header", () =>
+    expect(
+      clientWith(localToken([("userId", JSON.Encode.string("local-shopper"))]))
+      ->Seed_Client.claims
+      ->Option.flatMap(c => c->Dict.get("userId"))
+      ->Option.flatMap(JSON.Decode.string),
+    )->toEqual(Some("local-shopper"))
+  )
+})
+
+describe("Seed_Client.effectiveGroups:", () => {
+  // A Cognito id token carries its payload in the second segment, a local dev
+  // token in the first. Neither platform should have to announce which it is.
+  testSync("reads the payload wherever the provider put it", () => {
+    expect(
+      clientWith(
+        jwt([("cognito:groups", strings(["Admin", "Shopper"]))]),
+      )->Seed_Client.effectiveGroups,
+    )->toEqual(Some(["Admin", "Shopper"]))
+    expect(
+      clientWith(localToken([("groups", strings(["Merchandiser"]))]))->Seed_Client.effectiveGroups,
+    )->toEqual(Some(["Merchandiser"]))
+  })
+
+  // An opaque bearer is not an error — it just means this can add nothing, and
+  // the failure reports what it always did.
+  testSync("says nothing about a token it cannot read", () => {
+    expect(clientWith("not-a-token")->Seed_Client.effectiveGroups)->toEqual(None)
+    expect(
+      Seed_Client.make(
+        ~config={endpoint: "http://example.invalid/graphql"},
+      )->Seed_Client.effectiveGroups,
+    )->toEqual(None)
+  })
+})
+
+// The id an `@owner` field is stamped with. A seed that cannot read it can only
+// key owner-scoped rows to a literal, and a literal matches one platform's
+// accounts at most — which is how a demo shopper came to be registered on a
+// deployment where nobody can ever be that shopper.
+
+describe("Seed_Client.callerId:", () => {
+  // A Cognito id token says `sub`; the local dev token is a base64url
+  // `Identity.t`, whose field is `userId`. Neither platform announces which.
+  testSync("reads the id under whichever name the provider gave it", () => {
+    expect(
+      clientWith(jwt([("sub", JSON.Encode.string("4275e4a4-00c1-70e1"))]))->Seed_Client.callerId,
+    )->toEqual(Some("4275e4a4-00c1-70e1"))
+    expect(
+      clientWith(
+        localToken([("userId", JSON.Encode.string("local-shopper"))]),
+      )->Seed_Client.callerId,
+    )->toEqual(Some("local-shopper"))
+  })
+
+  // `sub` first, so a token carrying both is read the way the pool that minted
+  // it means it.
+  testSync("prefers sub when a token carries both names", () =>
+    expect(
+      clientWith(
+        jwt([
+          ("sub", JSON.Encode.string("f215e4b4-30f1-700c")),
+          ("userId", JSON.Encode.string("local-shopper")),
+        ]),
+      )->Seed_Client.callerId,
+    )->toEqual(Some("f215e4b4-30f1-700c"))
+  )
+
+  // `None` is not an error — it means this cannot add anything, and the caller
+  // falls back to whatever the accounts file declared.
+  testSync("says nothing about a token it cannot read, or one naming no id", () => {
+    expect(clientWith("not-a-token")->Seed_Client.callerId)->toEqual(None)
+    expect(
+      clientWith(jwt([("cognito:groups", strings(["Admin"]))]))->Seed_Client.callerId,
+    )->toEqual(None)
+    expect(
+      Seed_Client.make(~config={endpoint: "http://example.invalid/graphql"})->Seed_Client.callerId,
+    )->toEqual(None)
+  })
+
+  // A claim of the wrong shape is not an id. Taking the array's first element
+  // would be a guess, and a guessed owner id seeds rows nobody can read.
+  testSync("refuses a claim that is not a single string", () =>
+    expect(clientWith(jwt([("sub", strings(["a", "b"]))]))->Seed_Client.callerId)->toEqual(None)
+  )
+})
+
+describe("Seed_Client.identitySummary:", () => {
+  // The case that cost the debugging: eligible in the user list, refused by the
+  // token. Naming what it was narrowed FROM is what points at the role switch.
+  testSync("names the membership a narrowed token gave up", () =>
+    expect(
+      clientWith(
+        jwt([
+          ("cognito:groups", strings(["Shopper"])),
+          ("availableRoles", JSON.Encode.string("Admin,Shopper")),
+        ]),
+      )->Seed_Client.identitySummary,
+    )->toEqual(Some("Shopper — narrowed to this role from Admin, Shopper"))
+  )
+
+  // An ordinary login is not narrowed and has nothing to explain.
+  testSync("stays quiet about an unnarrowed token", () =>
+    expect(
+      clientWith(
+        jwt([("cognito:groups", strings(["Admin", "Shopper"]))]),
+      )->Seed_Client.identitySummary,
+    )->toEqual(Some("Admin, Shopper"))
+  )
+
+  // A token granting nothing reads as a sentence rather than an empty string.
+  testSync("says so when the token carries no groups at all", () =>
+    expect(
+      clientWith(jwt([("cognito:groups", strings([]))]))->Seed_Client.identitySummary,
+    )->toEqual(Some("no groups"))
+  )
+})
+
+// Whether a token is narrowed cannot be read off the group claim: a bearer
+// carrying one group looks identical whether the account holds one role or five.
+// `availableRoles` is written only when a role was chosen, so its presence IS
+// the narrowing — and that is what decides whether the seed has anything to ask.
+
+describe("Seed_Client.narrowedFrom:", () => {
+  testSync("names the membership a narrowed token was reduced from", () =>
+    expect(
+      clientWith(
+        jwt([
+          ("cognito:groups", strings(["Shopper"])),
+          ("availableRoles", JSON.Encode.string("Admin,Shopper")),
+        ]),
+      )->Seed_Client.narrowedFrom,
+    )->toEqual(Some(["Admin", "Shopper"]))
+  )
+
+  // The case that must NOT prompt: a single-role account is not narrowed, it is
+  // simply small. Asking it to choose would put a question in every run.
+  testSync("says nothing about an unnarrowed token", () => {
+    expect(
+      clientWith(jwt([("cognito:groups", strings(["Shopper"]))]))->Seed_Client.narrowedFrom,
+    )->toEqual(None)
+    expect(
+      clientWith(
+        jwt([("cognito:groups", strings(["Admin", "Shopper"]))]),
+      )->Seed_Client.narrowedFrom,
+    )->toEqual(None)
+  })
+
+  // An empty claim is not a narrowing to nothing — it is a claim carrying no
+  // information, and offering a menu of no roles would be a dead end.
+  testSync("treats an empty availableRoles as not narrowed", () =>
+    expect(
+      clientWith(jwt([("availableRoles", JSON.Encode.string(""))]))->Seed_Client.narrowedFrom,
+    )->toEqual(None)
+  )
+})
+
+describe("Seed_Client.isDenied:", () => {
+  // AppSync types it; the local server carries it in the message.
+  testSync("recognises a refusal in either platform's vocabulary", () => {
+    expect(Seed_Client.isDenied(errors([errorOfType("Unauthorized")])))->toBe(true)
+    expect(
+      Seed_Client.isDenied(
+        errors([Dict.fromArray([("message", JSON.Encode.string("Not Authorized to access X"))])]),
+      ),
+    )->toBe(true)
+  })
+
+  // Attaching an identity to an unrelated failure would point the reader at the
+  // wrong thing.
+  testSync("leaves every other failure alone", () => {
+    expect(Seed_Client.isDenied(errors([errorOfType("ValidationException")])))->toBe(false)
+    expect(Seed_Client.isDenied(errors([])))->toBe(false)
+  })
+})

package/lib/ocaml/Seed_Connect.res

@@ -1,40 +1,223 @@
 // Turns endpoints plus a login function into a ready `connection`.
 //
 // A connection is what a data set seeds against: an authenticated GraphQL
-// client, the upload endpoint (empty when the deployment serves no uploads), and
-// a human label for the target. `make` is provider-agnostic — it prompts for
+// client, the deployment's upload endpoints (empty when it serves no uploads),
+// and a human label for the target. `make` is provider-agnostic — it prompts for
 // credentials, calls the supplied `login` to obtain a bearer, and wires it onto
 // the client via `useToken`. Where the bearer comes from (a local `/login`
 // round-trip, a Cognito id token) is the caller's concern.
 
 open Seed_Types
 
-type connection = {client: Seed_Client.t, uploadEndpoint: string, label: string}
+// ── Active role ───────────────────────────────────────────────────────────────
+//
+// Both platforms narrow a token to the single role the caller last chose, and on
+// Cognito that choice is STORED — so an operator who acted as one role in the
+// host shell gets a narrowed token from the next seed login, days later, with
+// nothing in the seed's own environment to explain it. That is a refusal on the
+// first gated call and no way out of the terminal.
+
+/**
+ * Applies an active-role choice, if the platform offers one. `None` clears the
+ * choice and widens back to the caller's full membership.
+ *
+ * Returns the fresh bearer when the platform mints one itself, and `None` when
+ * the choice is merely stored and a re-authentication is what picks it up. The
+ * two platforms genuinely differ here: the local server re-issues on the spot,
+ * while Cognito's pre-token-generation trigger reads the stored row on the next
+ * login, so nothing changes until the seed authenticates again.
+ *
+ * Supplied by the platform adapter for the reason `~login` is: this package must
+ * not learn which provider signed the token, and the routes are not alike — a
+ * GraphQL mutation on one, an HTTP endpoint on the other.
+ */
+type roleSwitch = (~client: Seed_Client.t, ~role: option<string>) => promise<option<string>>
+
+/** What a run should act as. `Full` is the default because seeding wants every
+    right the account has; `Narrowed` exists so a run can deliberately act as one
+    role — the only way to exercise what a restricted caller is refused. */
+type roleChoice = Full | Narrowed(string)
+
+// `SEED_ROLE`: a role name, or `full`/`all` to clear. Honoured whether or not the
+// token arrived narrowed, so a deliberate narrowed run needs no TTY.
+let roleFromEnv = (): option<roleChoice> =>
+  Seed_Prompt.envValue("SEED_ROLE")->Option.map(v =>
+    switch v->String.toLowerCase {
+    | "full" | "all" | "none" | "clear" => Full
+    | _ => Narrowed(v)
+    }
+  )
+
+// Under route B the client mints uploads through the domain API's `Upload_Presign`
+// mutation (authenticated by the same bearer as commands), so a connection needs no
+// upload endpoint — just the authenticated client and whether uploads are skipped this
+// run (`SEED_SKIP_UPLOADS`). Which store an asset uploads into is the caller's `~store`.
+type connection = {
+  client: Seed_Client.t,
+  uploadsSkipped: bool,
+  label: string,
+  // Every account the platform's accounts file declares — `[]` when there was no
+  // file, since the `REVENTLESS_DEMO_USER`/`REVENTLESS_DEMO_PASSWORD` path
+  // bypasses it entirely. A data set resolves a demo owner through this, so the
+  // id it seeds is the id the platform stamps rather than a literal that only
+  // happens to match one platform's accounts.
+  accounts: array<Seed_Users.user>,
+  // The account this run authenticated as, and the id its bearer actually
+  // carries — which is the only id available when there is no accounts file.
+  caller: Seed_Users.user,
+  callerId: option<string>,
+  // The login this run authenticated with, kept so a data set can mint a second
+  // client for another account. An owner-scoped read is only ever verified by
+  // the account the rows belong to: the seeding client is elevated, and an
+  // elevated token answers for every owner at once.
+  login: (~username: string, ~password: string) => promise<string>,
+  // How this platform stores an active-role choice, when it offers one at all.
+  // `None` means the deployment has no such door (a unified-mode AWS API does
+  // not carry `Platform_SetActiveRole`), and a narrowing can then only be
+  // reported, not fixed from here.
+  roleSwitch: option<roleSwitch>,
+}
+
+let announceIdentity = (client: Seed_Client.t, ~prefix: string="Acting as"): unit =>
+  switch Seed_Client.identitySummary(client) {
+  | Some(summary) => Console.log(`${prefix}: ${summary}`)
+  | None => ()
+  }
+
+/**
+ * Applies a role choice and leaves `client` holding a bearer that reflects it.
+ *
+ * The re-authentication is not optional bookkeeping: on Cognito the stored row
+ * is read at token generation, so a run that set a role and kept its old bearer
+ * would carry on with exactly the token it just tried to change.
+ */
+let applyRole = async (
+  ~client: Seed_Client.t,
+  ~roleSwitch: roleSwitch,
+  ~login: (~username: string, ~password: string) => promise<string>,
+  ~caller: Seed_Users.user,
+  ~role: option<string>,
+): unit => {
+  let minted = await roleSwitch(~client, ~role)
+  let token = switch minted {
+  | Some(fresh) => fresh
+  | None => await login(~username=caller.username, ~password=caller.password)
+  }
+  client->Seed_Client.useToken(token)
+  // A second line rather than a replacement, and worded so the pair reads as a
+  // change: the first says what the login gave, this says what the run proceeds
+  // under, and a reader needs both to see that the switch actually took.
+  client->announceIdentity(~prefix="Now acting as")
+}
+
+/**
+ * Chooses what the run acts as, when the platform lets it choose.
+ *
+ * Deliberately quiet on a healthy run: an unnarrowed token has nothing to ask
+ * about, so the common case gains no prompt. The menu appears only when the
+ * bearer arrived narrowed — the case where the account list says one thing and
+ * the token another, which is unreadable from the terminal without it.
+ *
+ * `SEED_ROLE` answers non-interactively and is honoured even when the token is
+ * NOT narrowed, which is what makes a deliberate restricted run possible: acting
+ * as one role is the only way to exercise what a restricted caller is refused.
+ *
+ * Without a TTY and without `SEED_ROLE` it proceeds untouched rather than
+ * throwing. A narrowing is not always fatal — narrowed to Admin is fine — so
+ * refusing to start would break runs that would have worked.
+ */
+let resolveRole = async (
+  ~client: Seed_Client.t,
+  ~roleSwitch: option<roleSwitch>,
+  ~login: (~username: string, ~password: string) => promise<string>,
+  ~caller: Seed_Users.user,
+): unit =>
+  switch roleSwitch {
+  | None => ()
+  | Some(roleSwitch) =>
+    let narrowedFrom = Seed_Client.narrowedFrom(client)
+    let chosen = switch roleFromEnv() {
+    | Some(choice) => Some(choice)
+    | None =>
+      switch narrowedFrom {
+      | Some(available) if available->Array.length > 1 && Seed_Prompt.hasTty() =>
+        Console.log("")
+        Console.log(
+          "This token is narrowed to one role. Seeding needs every right the account has;",
+        )
+        Console.log("clearing also widens your host-shell session, which shares the stored choice.")
+        let options = Array.concat(
+          [(`full membership (${available->Array.join(", ")})`, Full)],
+          available->Array.map(r => (r, Narrowed(r))),
+        )
+        Some(await Seed_Prompt.select(~title="Act as:", ~options, ~defaultIndex=0))
+      | _ => None
+      }
+    }
+    switch chosen {
+    | None => ()
+    | Some(Full) => await applyRole(~client, ~roleSwitch, ~login, ~caller, ~role=None)
+    | Some(Narrowed(role)) =>
+      await applyRole(~client, ~roleSwitch, ~login, ~caller, ~role=Some(role))
+    }
+  }
 
 /**
  * Prompts for credentials, calls `login` to mint a bearer, and returns a
  * connection with that bearer already applied. `login` returns the bearer so a
  * single `useToken` path serves every provider.
+ *
+ * `roleSwitch` is the platform's active-role door, when it has one; supplying it
+ * is what lets a narrowed token be widened here instead of in a browser.
  */
 let make = async (
   ~label: string,
   ~endpoint: string,
-  ~uploadEndpoint: string,
   ~login: (~username: string, ~password: string) => promise<string>,
+  ~roleSwitch: option<roleSwitch>=?,
   ~localDefaults: bool=false,
 ): connection => {
-  // `SEED_SKIP_UPLOADS` forces the connection to carry no upload endpoint, so a
-  // data set's upload phase no-ops the same way it does when a deployment serves
-  // none. Use it to seed domain data fast, or to skip a broken/absent upload path
-  // without editing the data set. It is the single knob: an empty
-  // `REVENTLESS_UPLOAD_ENDPOINT` env reads as "unset" (falls back to discovery),
-  // so this is the reliable way to disable uploads.
-  let uploadEndpoint = Seed_Prompt.envValue("SEED_SKIP_UPLOADS")->Option.isSome ? "" : uploadEndpoint
-  let (username, password) = await Seed_Prompt.credentials(~localDefaults)
-  let token = await login(~username, ~password)
+  // `SEED_SKIP_UPLOADS` forces the upload phase to no-op — seed domain data fast, or
+  // skip a broken/absent upload path without editing the data set. The data set reads
+  // `connection.uploadsSkipped` and reports the skip.
+  let uploadsSkipped = Seed_Upload.uploadsSkipped()
+  let {caller, accounts} = await Seed_Prompt.credentials(~localDefaults)
+  let token = await login(~username=caller.username, ~password=caller.password)
   let client = Seed_Client.make(~config={endpoint: endpoint})
   client->Seed_Client.useToken(token)
-  {client, uploadEndpoint, label}
+  // What the bearer grants, which is not always what the account list showed: a
+  // token narrowed to one role presents that role alone. Said at login so the
+  // run starts from the identity it will actually be refused or served under.
+  announceIdentity(client)
+  // Offered before anything is probed or written, so a narrowing is settled
+  // while the run can still be redirected rather than after a refusal.
+  await resolveRole(~client, ~roleSwitch, ~login, ~caller)
+  {
+    client,
+    uploadsSkipped,
+    label,
+    accounts,
+    caller,
+    callerId: Seed_Client.callerId(client),
+    login,
+    roleSwitch,
+  }
+}
+
+/**
+ * A second authenticated client, for one of the accounts the platform's accounts
+ * file declares. Same endpoint, same login route, a different bearer.
+ *
+ * It exists so a data set can read back what it seeded as the account the rows
+ * belong to. The seeding client cannot answer that question: it is elevated, so
+ * an owner-scoped view counts every owner's rows for it and reads non-empty
+ * whether or not a single row is reachable by the person it was seeded for.
+ */
+let clientFor = async (c: connection, ~account: Seed_Users.user): Seed_Client.t => {
+  let token = await c.login(~username=account.username, ~password=account.password)
+  let client = Seed_Client.make(~config={endpoint: Seed_Client.endpoint(c.client)})
+  client->Seed_Client.useToken(token)
+  client
 }
 
 /**
@@ -42,19 +225,77 @@ let make = async (
  * `/__inmemory/login` shape: POST `{username, password}` → `{token}`). Reuses
  * `Seed_Client.login` but hands the token back for `useToken`.
  */
-let viaLoginEndpoint = (~loginEndpoint: string) => async (
-  ~username: string,
-  ~password: string,
-): string => {
-  let client = Seed_Client.make(
-    ~config={endpoint: loginEndpoint, loginEndpoint, username, password},
-  )
-  await Seed_Client.login(client)
-  switch Seed_Client.currentToken(client) {
-  | Some(token) => token
-  | None => throw(Failed(`login at ${loginEndpoint} returned no token`))
+let viaLoginEndpoint = (~loginEndpoint: string) =>
+  async (~username: string, ~password: string): string => {
+    let client = Seed_Client.make(
+      ~config={endpoint: loginEndpoint, loginEndpoint, username, password},
+    )
+    await Seed_Client.login(client)
+    switch Seed_Client.currentToken(client) {
+    | Some(token) => token
+    | None => throw(Failed(`login at ${loginEndpoint} returned no token`))
+    }
+  }
+
+/**
+ * The local dev platform's active-role door: POST `/__inmemory/switch-role` with
+ * `{activeRole}` (null to clear) and the current bearer, which answers with a
+ * freshly minted one.
+ *
+ * The local server re-issues on the spot rather than storing a choice, so this
+ * returns the new token and no re-authentication follows. Its narrowing is also
+ * per-session, which is why a local seed never arrives narrowed on its own —
+ * this exists for a *deliberate* `SEED_ROLE` run, which is where a restricted
+ * caller's refusals can be exercised without a deployed stack.
+ */
+let viaSwitchRoleEndpoint = (~switchRoleEndpoint: string): roleSwitch =>
+  async (~client: Seed_Client.t, ~role: option<string>) => {
+    let token = switch Seed_Client.currentToken(client) {
+    | Some(t) => t
+    | None => throw(Failed("switch-role: no bearer to present — log in first"))
+    }
+    // Clearing OMITS the key rather than sending `null`. The local handler reads
+    // its body through `Obj.magic` into an `option<string>`, and ReScript spells
+    // absence `undefined` — so a JSON `null` arrives as a present value and the
+    // server tries to act as a role literally named "null", refusing with
+    // `Cannot act as "null": not a group this user holds`. An absent key is the
+    // only thing it reads as "no role", which is what widens back to full.
+    let body = JSON.stringify(
+      JSON.Encode.object(
+        switch role {
+        | Some(r) => Dict.fromArray([("activeRole", JSON.Encode.string(r))])
+        | None => Dict.make()
+        },
+      ),
+    )
+    let res = try await Seed_Client.fetch(
+      switchRoleEndpoint,
+      {
+        method: "POST",
+        headers: Dict.fromArray([
+          ("content-type", "application/json"),
+          ("authorization", `Bearer ${token}`),
+        ]),
+        body,
+      },
+    ) catch {
+    | _ => throw(Failed(`switch-role: cannot reach ${switchRoleEndpoint}`))
+    }
+    let json = await res->Seed_Client.responseJson
+    if !(res->Seed_Client.responseOk) {
+      throw(
+        Failed(
+          `switch-role at ${switchRoleEndpoint} failed with HTTP ${res
+            ->Seed_Client.responseStatus
+            ->Int.toString}: ${JSON.stringify(json)}`,
+        ),
+      )
+    }
+    switch json->Seed_Client.field("token")->Option.flatMap(Seed_Client.asString) {
+    | Some(fresh) => Some(fresh)
+    | None => throw(Failed(`switch-role at ${switchRoleEndpoint} returned no token`))
+    }
   }
-}
 
 let envOr = (key: string, fallback: string): string =>
   Seed_Prompt.envValue(key)->Option.getOr(fallback)
@@ -63,22 +304,29 @@ let envOr = (key: string, fallback: string): string =>
  * A ready `connect` thunk for the local dev platform, with the localhost
  * defaults baked in and overridable per endpoint (arg, then env var, then
  * default). Empty input at the credential prompt falls back to `admin`/`admin`.
+ *
+ * No upload endpoint: uploads mint through the domain API's `Upload_Presign` mutation
+ * on the same `graphql` endpoint, with the store passed per asset.
  */
-let local = (~graphql=?, ~upload=?, ~login=?, ()): (unit => promise<connection>) => {
+let local = (~graphql=?, ~login=?, ()): (unit => promise<connection>) => {
   let endpoint =
     graphql->Option.getOr(envOr("REVENTLESS_GRAPHQL_ENDPOINT", "http://localhost:4000/graphql"))
-  let uploadEndpoint =
-    upload->Option.getOr(
-      envOr("REVENTLESS_UPLOAD_ENDPOINT", "http://localhost:4000/__inmemory/upload"),
-    )
   let loginEndpoint =
-    login->Option.getOr(envOr("REVENTLESS_LOGIN_ENDPOINT", "http://localhost:4000/__inmemory/login"))
+    login->Option.getOr(
+      envOr("REVENTLESS_LOGIN_ENDPOINT", "http://localhost:4000/__inmemory/login"),
+    )
+  // The switch-role route sits beside the login one on the same server, so it is
+  // derived rather than configured — a second env var could name a different
+  // host from the login it is supposed to re-issue, which is the mismatch
+  // `LocalSeedTarget.loginFor` exists to prevent one level up.
+  let switchRoleEndpoint =
+    loginEndpoint->String.replace("/__inmemory/login", "/__inmemory/switch-role")
   () =>
     make(
       ~label="local",
       ~endpoint,
-      ~uploadEndpoint,
       ~login=viaLoginEndpoint(~loginEndpoint),
+      ~roleSwitch=viaSwitchRoleEndpoint(~switchRoleEndpoint),
       ~localDefaults=true,
     )
 }