@reventlessdev/reventless-core 3.0.0-alpha.231 → 3.0.0-alpha.232

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.232 (2026-08-13)
+
+### Features
+
+* **aws:** narrow the token to the role a caller chose to act as ([194332f](https://github.com/ReventlessDev/reventless-core/commit/194332fa0af8e13417f72d57904e2ed469747dde))
+
+
 # 3.0.0-alpha.231 (2026-08-13)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.231",
+  "version": "3.0.0-alpha.232",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -28,17 +28,17 @@
   "dependencies": {
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.5",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-node": "2.0.0-alpha.5",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.5",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
     "@reventlessdev/reventless-infra": "3.0.0-alpha.139",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.31",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.112"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.112",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.31"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/adapter/Auth/Auth_ActiveRole.res

@@ -0,0 +1,118 @@
+// The cross-provider contract for "a caller holding several roles acting as one
+// of them" — see [docs/plans/active-role-narrows-the-token.md].
+//
+// The narrowing itself is minted in two places that cannot share code: the local
+// platform signs its own tokens (`LocalAuth.Login`), and on AWS the minting point
+// is Cognito's pre-token-generation trigger, running in Cognito's runtime against
+// Cognito's event shape. What the two must agree on is exactly what lives here:
+// the claim names a client reads, and the table of cases the subset rule has to
+// satisfy on both paths.
+
+/**
+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 the group claim even though a narrowed token's groups are exactly
+this one role, because the two say different things: groups are what every
+enforcement point evaluates, and this is what the caller asked for.
+*/
+let activeRoleClaim = "activeRole"
+
+/**
+Claim naming the roles the caller gave up by narrowing — their full membership,
+comma-joined.
+
+🚨 **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 reads the group claim; this is the one piece
+of an identity that deliberately describes privilege the caller does *not*
+currently have.
+*/
+let availableRolesClaim = "availableRoles"
+
+/**
+Claim naming a stored role that was *not* applied because the caller no longer
+holds it.
+
+Only the Cognito path can produce this. A stored preference outlives the
+membership that justified it, and the trigger meets that on an ordinary refresh
+with no client asking for anything — so it cannot refuse the way the local path
+refuses a request. It mints the full set instead, and says so here: without this
+claim a caller would be silently un-narrowed with nothing to explain why the role
+they picked stopped taking effect.
+*/
+let staleRoleClaim = "activeRoleStale"
+
+/**
+The conformance table §6 of the plan requires: the same (membership, requested,
+expected) cases run against both minting paths, so the two implementations cannot
+drift on the question that carries the security.
+
+It lives in product code rather than in either package's tests because ReScript
+test directories are `type: dev` and therefore invisible across a package
+boundary — and a table copied into two test suites is exactly the drift it exists
+to prevent.
+
+`expected` is the group set the minted token must carry. `None` means the request
+must be **refused** rather than honoured, ignored, or reduced to the empty set —
+the distinction §3 turns on. A path with no client to refuse (the trigger, reading
+stored state) resolves `None` by minting `membership` and marking
+[staleRoleClaim]; a path answering a live request refuses it.
+*/
+type conformanceCase = {
+  label: string,
+  membership: array<string>,
+  requested: option<string>,
+  expected: option<array<string>>,
+}
+
+let conformanceCases: array<conformanceCase> = [
+  {
+    label: "no role requested mints exactly what it always minted",
+    membership: ["Fulfilment", "Shopper"],
+    requested: None,
+    expected: Some(["Fulfilment", "Shopper"]),
+  },
+  {
+    label: "a held role narrows to that role alone",
+    membership: ["Fulfilment", "Shopper"],
+    requested: Some("Shopper"),
+    expected: Some(["Shopper"]),
+  },
+  {
+    label: "the other held role narrows just as well",
+    membership: ["Fulfilment", "Shopper"],
+    requested: Some("Fulfilment"),
+    expected: Some(["Fulfilment"]),
+  },
+  {
+    label: "a role the caller does not hold is refused, never widened into",
+    membership: ["Fulfilment", "Shopper"],
+    requested: Some("Admin"),
+    expected: None,
+  },
+  {
+    label: "a sole role narrows to itself rather than being a special case",
+    membership: ["Shopper"],
+    requested: Some("Shopper"),
+    expected: Some(["Shopper"]),
+  },
+  {
+    label: "a caller holding nothing can request nothing",
+    membership: [],
+    requested: Some("Shopper"),
+    expected: None,
+  },
+  {
+    label: "the empty string is a request, and one no caller can hold",
+    membership: ["Shopper"],
+    requested: Some(""),
+    expected: None,
+  },
+  {
+    label: "group names are matched exactly, not case-insensitively",
+    membership: ["Shopper"],
+    requested: Some("shopper"),
+    expected: None,
+  },
+]

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

@@ -0,0 +1,82 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let conformanceCases = [
+  {
+    label: "no role requested mints exactly what it always minted",
+    membership: [
+      "Fulfilment",
+      "Shopper"
+    ],
+    requested: undefined,
+    expected: [
+      "Fulfilment",
+      "Shopper"
+    ]
+  },
+  {
+    label: "a held role narrows to that role alone",
+    membership: [
+      "Fulfilment",
+      "Shopper"
+    ],
+    requested: "Shopper",
+    expected: ["Shopper"]
+  },
+  {
+    label: "the other held role narrows just as well",
+    membership: [
+      "Fulfilment",
+      "Shopper"
+    ],
+    requested: "Fulfilment",
+    expected: ["Fulfilment"]
+  },
+  {
+    label: "a role the caller does not hold is refused, never widened into",
+    membership: [
+      "Fulfilment",
+      "Shopper"
+    ],
+    requested: "Admin",
+    expected: undefined
+  },
+  {
+    label: "a sole role narrows to itself rather than being a special case",
+    membership: ["Shopper"],
+    requested: "Shopper",
+    expected: ["Shopper"]
+  },
+  {
+    label: "a caller holding nothing can request nothing",
+    membership: [],
+    requested: "Shopper",
+    expected: undefined
+  },
+  {
+    label: "the empty string is a request, and one no caller can hold",
+    membership: ["Shopper"],
+    requested: "",
+    expected: undefined
+  },
+  {
+    label: "group names are matched exactly, not case-insensitively",
+    membership: ["Shopper"],
+    requested: "shopper",
+    expected: undefined
+  }
+];
+
+let activeRoleClaim = "activeRole";
+
+let availableRolesClaim = "availableRoles";
+
+let staleRoleClaim = "activeRoleStale";
+
+export {
+  activeRoleClaim,
+  availableRolesClaim,
+  staleRoleClaim,
+  conformanceCases,
+}
+/* No side effect */

package/src/admin/Platform_AdminApi.res

@@ -119,6 +119,33 @@ let geocodeTypes = [
 
 let geocodeQueryFields = [`  geocode(text: String!): [GeocodeCandidate!]`]
 
+// Acting as one of the roles you hold (docs/plans/active-role-narrows-the-token.md).
+//
+// The write door for the caller's chosen role. Like uploads and geocoding this is
+// an ordinary authenticated-user operation, so it belongs on the **domain** base
+// (default `AllowAuthenticated`), never the Admin-gated admin base — the whole
+// point is that a non-admin can drop into a narrower role.
+//
+// There is deliberately no `sub` argument: the subject is the authorizer-verified
+// `ctx.identity.sub`, so the mutation can only ever address the caller's own row.
+// `activeRole: null` clears the choice and widens back to full membership.
+//
+// 🚨 **Mounted by the AWS platform only.** This is the Cognito path's door —
+// Cognito mints the token, so the choice has to be stored for the pre-token-
+// generation trigger to read on the next refresh. The local platform mints its own
+// tokens and therefore re-mints immediately over `POST /__inmemory/switch-role`
+// (`LocalAuth.Login.reissue`); a mutation there would be a second way to do
+// something already done, with a token the caller would still have to go and
+// fetch. The constants live here with the other platform SDL rather than in the
+// AWS package so every platform-owned field stays in one file.
+let activeRoleTypes = [
+  `type Platform_ActiveRole {\n  activeRole: String\n  availableRoles: [String!]!\n}`,
+]
+
+let activeRoleMutationFields = [
+  `  Platform_SetActiveRole(activeRole: String): Platform_ActiveRole`,
+]
+
 let baseFragment = (~cloner: bool) => {
   let base = GraphQL_FragmentGenerator.generate(
     ~mutationEntries=mutationEntries(~cloner),

package/src/admin/Platform_AdminApi.res.mjs

@@ -86,6 +86,10 @@ let geocodeTypes = [`type GeocodeCandidate {\n  label: String!\n  lat: Float!\n
 
 let geocodeQueryFields = [`  geocode(text: String!): [GeocodeCandidate!]`];
 
+let activeRoleTypes = [`type Platform_ActiveRole {\n  activeRole: String\n  availableRoles: [String!]!\n}`];
+
+let activeRoleMutationFields = [`  Platform_SetActiveRole(activeRole: String): Platform_ActiveRole`];
+
 function baseFragment(cloner) {
   let base = GraphQL_FragmentGenerator$ReventlessCore.generate(mutationEntries(cloner), PluginBaseFragment$ReventlessCore.queryEntries);
   let parts = GraphQL_Stitcher$ReventlessCore.decode(base);
@@ -128,6 +132,8 @@ export {
   uploadMutationFields,
   geocodeTypes,
   geocodeQueryFields,
+  activeRoleTypes,
+  activeRoleMutationFields,
   baseFragment,
 }
 /* cloneArgsSchema Not a pure module */