@reventlessdev/reventless-spec 3.0.0-alpha.156 → 3.0.0-alpha.158

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.158 (2026-10-06)
+
+**Note:** Version bump only for package @reventlessdev/reventless-spec
+
+
+
+
+
+# 3.0.0-alpha.157 (2026-10-01)
+
+### Bug Fixes
+
+* check a plugin's roles against the user pool's groups ([ddb3c42](https://github.com/ReventlessDev/reventless-core/commit/ddb3c422b7226a19800e781abd5f03af18867007))
+
+
 # 3.0.0-alpha.156 (2026-10-01)
 
 * feat!: roles a plugin declares, groups a platform provides ([43daace](https://github.com/ReventlessDev/reventless-core/commit/43daace6ca588afe22562d079af1e6f1da81942e))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.156",
+  "version": "3.0.0-alpha.158",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -26,7 +26,7 @@
     "sury": "11.0.0",
     "sury-ppx": "11.0.0",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.20"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.21"
   },
   "devDependencies": {
     "rescript": "12.3.1",

package/src/generator/Codegen.res

@@ -567,12 +567,17 @@ let renderMain = (~config: Config.config): string => {
     "module Platform = ReventlessAws.Platform.Make()",
     "module " ++ name ++ " = Plugin.Make(Platform)",
     "",
-    "let default = Platform.deployPlugin(",
-    "  ~plugin=module(" ++ name ++ "),",
-    ")",
-    "",
+    // The plugin is deployed once the user pool's groups are in, for the check
+    // that every role it needs has one, which runs while `deployPlugin` builds
+    // it. A promise rather than a top-level await: Pulumi `require`s the
+    // program, which Node refuses for a module that awaits at the top level.
+    // Pulumi resolves the promise in the stack outputs.
+    "let default = ReventlessAws.Platform.loadProvidedGroups()->Promise.thenResolve(() => {",
+    "  let deployed = Platform.deployPlugin(~plugin=module(" ++ name ++ "))",
     // PostDeploy runs after the graph is registered (exports, cross-stack output).
-    "ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "  ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "  deployed",
+    "})",
     "",
   ]->Array.join("\n")
 }

package/src/generator/Codegen.res.mjs

@@ -365,11 +365,11 @@ function renderMain(config) {
     "module Platform = ReventlessAws.Platform.Make()",
     "module " + name + " = Plugin.Make(Platform)",
     "",
-    "let default = Platform.deployPlugin(",
-    "  ~plugin=module(" + name + "),",
-    ")",
-    "",
-    "ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "let default = ReventlessAws.Platform.loadProvidedGroups()->Promise.thenResolve(() => {",
+    "  let deployed = Platform.deployPlugin(~plugin=module(" + name + "))",
+    "  ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "  deployed",
+    "})",
     ""
   ].join("\n");
 }

package/src/types/Role.res

@@ -107,9 +107,9 @@ let groupOf = (role: name): string =>
 let adminGroup = (): string => groupOf(admin)
 
 /**
-Where the groups this deployment provides come from: the administrator group and
-accounts manifest a platform finds for itself, and the groups of a user pool it
-did not create, which the platform root declares.
+Where the groups this deployment provides come from: what the identity provider
+reports where the platform can ask it, else the administrator group and accounts
+manifest a platform finds for itself and the groups a platform root declares.
 
 Sources rather than values, read when the check runs: a platform states them
 while its functor is applied, before the root has said how its roles map. Empty
@@ -118,26 +118,61 @@ has an answer to compare against.
 */
 let groupSources: ref<array<unit => array<string>>> = ref([])
 
+/** The groups a root declared with `provideGroups`, kept apart so a listing can
+    contradict them. */
+let declaredGroups: ref<array<string>> = ref([])
+
+/** The groups the identity provider itself reported, and which provider that was. */
+type listing = {source: string, groups: array<string>}
+
+let listing: ref<option<listing>> = ref(None)
+
 let provideGroupsFrom = (source: unit => array<string>) =>
   groupSources := groupSources.contents->Array.concat([source])
 
-let provideGroups = (groups: array<string>) => provideGroupsFrom(() => groups)
+let provideGroups = (groups: array<string>) => {
+  declaredGroups := declaredGroups.contents->Array.concat(groups)
+  provideGroupsFrom(() => groups)
+}
+
+/**
+Record what the identity provider says it has. A platform that can ask (the AWS
+user pool) does, before its plugins are built. The listing is then the whole
+answer: a group a manifest names, a root declares or the mapping points to is
+provided only if the provider has it, since a group it lacks refuses everybody.
+*/
+let provideListedGroups = (~source: string, groups: array<string>) =>
+  listing := Some({source, groups})
+
+let clearProvidedGroups = () => {
+  groupSources := []
+  declaredGroups := []
+  listing := None
+}
 
-let clearProvidedGroups = () => groupSources := []
+let _distinct = (groups: array<string>) => groups->Set.fromArray->Set.values->Array.fromIterator
 
-/** The groups a deployment provides: every source plus every group the mapping
-    names. `None` when nothing was provided — a process that is not a platform (a
-    unit test, a function runtime) has no answer to give. */
+/** The groups a deployment provides: the provider's listing where there is one,
+    else every source plus every group the mapping names. `None` when nothing was
+    provided — a process that is not a platform (a unit test, a function runtime)
+    has no answer to give. */
 let providedGroups = (): option<array<string>> =>
-  switch groupSources.contents {
-  | [] => None
-  | sources =>
+  switch (listing.contents, groupSources.contents) {
+  | (Some({groups}), _) => Some(_distinct(groups))
+  | (None, []) => None
+  | (None, sources) =>
     Some(
       sources
       ->Array.flatMap(source => source())
       ->Array.concat(renamed()->Array.map(((_, group)) => group))
-      ->Set.fromArray
-      ->Set.values
-      ->Array.fromIterator,
+      ->_distinct,
     )
   }
+
+/** The declared groups the provider's listing does not have. Empty without a
+    listing, when there is nothing to contradict them. */
+let declaredButMissing = (): array<string> =>
+  switch listing.contents {
+  | None => []
+  | Some({groups}) => declaredGroups.contents->Array.filter(g => !(groups->Array.includes(g)))
+  }

package/src/types/Role.res.mjs

@@ -85,23 +85,60 @@ let groupSources = {
   contents: []
 };
 
+let declaredGroups = {
+  contents: []
+};
+
+let listing = {
+  contents: undefined
+};
+
 function provideGroupsFrom(source) {
   groupSources.contents = groupSources.contents.concat([source]);
 }
 
 function provideGroups(groups) {
+  declaredGroups.contents = declaredGroups.contents.concat(groups);
   provideGroupsFrom(() => groups);
 }
 
+function provideListedGroups(source, groups) {
+  listing.contents = {
+    source: source,
+    groups: groups
+  };
+}
+
 function clearProvidedGroups() {
   groupSources.contents = [];
+  declaredGroups.contents = [];
+  listing.contents = undefined;
+}
+
+function _distinct(groups) {
+  return Array.from(new Set(groups).values());
 }
 
 function providedGroups() {
-  let sources = groupSources.contents;
-  if (sources.length !== 0) {
-    return Array.from(new Set(sources.flatMap(source => source()).concat(renamed().map(param => param[1]))).values());
+  let match = listing.contents;
+  let match$1 = groupSources.contents;
+  if (match !== undefined) {
+    return Array.from(new Set(match.groups).values());
+  }
+  if (match$1.length === 0) {
+    return;
+  }
+  let groups = match$1.flatMap(source => source()).concat(renamed().map(param => param[1]));
+  return Array.from(new Set(groups).values());
+}
+
+function declaredButMissing() {
+  let match = listing.contents;
+  if (match === undefined) {
+    return [];
   }
+  let groups = match.groups;
+  return declaredGroups.contents.filter(g => !groups.includes(g));
 }
 
 let envKey = "REVENTLESS_ROLE_GROUPS";
@@ -121,9 +158,14 @@ export {
   groupOf,
   adminGroup,
   groupSources,
+  declaredGroups,
+  listing,
   provideGroupsFrom,
   provideGroups,
+  provideListedGroups,
   clearProvidedGroups,
+  _distinct,
   providedGroups,
+  declaredButMissing,
 }
 /* nameSchema Not a pure module */

package/src/types/RoleCoverage.res

@@ -4,9 +4,9 @@ Whether a platform can provide every role a plugin needs.
 A rule naming a role no group stands for refuses everybody it was written for, and
 nothing says so until someone is refused on a deployed stack. So every role a
 component's rule names, and every elevated role, must map to a group the platform
-provides: the administrator group it declares, the groups of its accounts
-manifest, the groups the role mapping names, and any a root declares for a user
-pool it did not create.
+provides: the groups its identity provider reports where the platform can ask it,
+else the administrator group, the accounts manifest, the role mapping and any
+groups a root declares (see `Role.providedGroups`).
 */
 
 type need = {
@@ -55,12 +55,37 @@ let describe = (n: need): string => {
     : `${n.plugin}: ${n.item} needs the role ${role} (mapped to the group ${n.group})`
 }
 
-let unmetMessage = (missing: array<need>, ~provided: array<string>): string =>
+/** What to do about it depends on where the provided groups came from: a
+    provider that was asked can only be given the group, while a manifest or a
+    declaration can be corrected. */
+let remedy = (~provided: array<string>, ~listing: option<Role.listing>): string =>
+  switch listing {
+  | Some({source}) =>
+    let source = source->String.charAt(0)->String.toUpperCase ++ source->String.slice(~start=1)
+    `  ${source} has the groups: ${provided->Array.join(", ")}.\n` ++
+    `  Create the group there (provision-accounts creates the groups of the accounts ` ++ `manifest), or map the role to a group it has (Platform.roleGroups).`
+  | None =>
+    `  The platform provides the groups: ${provided->Array.join(", ")}.\n` ++
+    `  Add an account in that group to the accounts manifest (.reventless/users.yaml), ` ++
+    `map the role to a group that exists (Platform.roleGroups), or declare the groups ` ++ `of a user pool this deployment did not create (Platform.providedGroups).`
+  }
+
+let unmetMessage = (
+  missing: array<need>,
+  ~provided: array<string>,
+  ~listing: option<Role.listing>=?,
+): string =>
   `Roles this platform cannot provide — every caller would be refused:\n` ++
   missing->Array.map(n => `  ${describe(n)}`)->Array.join("\n") ++
-  `\n  The platform provides the groups: ${provided->Array.join(", ")}.\n` ++
-  `  Add an account in that group to the accounts manifest (.reventless/users.yaml), ` ++
-  `map the role to a group that exists (Platform.roleGroups), or declare the groups ` ++ `of a user pool this deployment did not create (Platform.providedGroups).`
+  "\n" ++
+  remedy(~provided, ~listing)
+
+/** A declared group the provider says it does not have: the declaration is wrong,
+    whether or not a plugin needs the group today. */
+let contradictedMessage = (groups: array<string>, ~listing: Role.listing): string =>
+  `Groups declared with Platform.providedGroups that ${listing.source} does not have: ` ++
+  `${groups->Array.join(", ")}.\n` ++
+  `  It has: ${listing.groups->Array.join(", ")}. Create them there or remove the declaration.`
 
 /**
 Refuse a plugin needing a role nobody provides, and a deployment electing a role
@@ -76,9 +101,15 @@ let check = (structure: Plugin.pluginStructure, ~plugin: string): unit =>
   switch Role.providedGroups() {
   | None => ()
   | Some(provided) =>
+    let listing = Role.listing.contents
+    switch (listing, Role.declaredButMissing()) {
+    | (Some(listing), groups) if groups != [] =>
+      JsError.throwWithMessage(contradictedMessage(groups, ~listing))
+    | _ => ()
+    }
     let elevated = OwnerScope.explicitElevatedRoles.contents->Option.getOr([])
     switch unmet(needsOf(structure, ~plugin)->Array.concat(elevatedNeeds(elevated)), ~provided) {
     | [] => ()
-    | missing => JsError.throwWithMessage(unmetMessage(missing, ~provided))
+    | missing => JsError.throwWithMessage(unmetMessage(missing, ~provided, ~listing?))
     }
   }

package/src/types/RoleCoverage.res.mjs

@@ -3,6 +3,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 Role$Reventless from "./Role.res.mjs";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as OwnerScope$Reventless from "./OwnerScope.res.mjs";
 
 function needsOf(structure, plugin) {
@@ -45,8 +46,21 @@ function describe(n) {
   }
 }
 
-function unmetMessage(missing, provided) {
-  return `Roles this platform cannot provide — every caller would be refused:\n` + missing.map(n => `  ` + describe(n)).join("\n") + (`\n  The platform provides the groups: ` + provided.join(", ") + `.\n`) + `  Add an account in that group to the accounts manifest (.reventless/users.yaml), map the role to a group that exists (Platform.roleGroups), or declare the groups of a user pool this deployment did not create (Platform.providedGroups).`;
+function remedy(provided, listing) {
+  if (listing === undefined) {
+    return `  The platform provides the groups: ` + provided.join(", ") + `.\n  Add an account in that group to the accounts manifest (.reventless/users.yaml), map the role to a group that exists (Platform.roleGroups), or declare the groups of a user pool this deployment did not create (Platform.providedGroups).`;
+  }
+  let source = listing.source;
+  let source$1 = source.charAt(0).toUpperCase() + source.slice(1);
+  return `  ` + source$1 + ` has the groups: ` + provided.join(", ") + `.\n  Create the group there (provision-accounts creates the groups of the accounts manifest), or map the role to a group it has (Platform.roleGroups).`;
+}
+
+function unmetMessage(missing, provided, listing) {
+  return `Roles this platform cannot provide — every caller would be refused:\n` + missing.map(n => `  ` + describe(n)).join("\n") + "\n" + remedy(provided, listing);
+}
+
+function contradictedMessage(groups, listing) {
+  return `Groups declared with Platform.providedGroups that ` + listing.source + ` does not have: ` + (groups.join(", ") + `.\n`) + (`  It has: ` + listing.groups.join(", ") + `. Create them there or remove the declaration.`);
 }
 
 function check(structure, plugin) {
@@ -54,10 +68,15 @@ function check(structure, plugin) {
   if (provided === undefined) {
     return;
   }
+  let listing = Role$Reventless.listing.contents;
+  let match = Role$Reventless.declaredButMissing();
+  if (listing !== undefined && Primitive_object.notequal(match, [])) {
+    Stdlib_JsError.throwWithMessage(contradictedMessage(match, listing));
+  }
   let elevated = Stdlib_Option.getOr(OwnerScope$Reventless.explicitElevatedRoles.contents, []);
   let missing = unmet(needsOf(structure, plugin).concat(elevatedNeeds(elevated)), provided);
   if (missing.length !== 0) {
-    return Stdlib_JsError.throwWithMessage(unmetMessage(missing, provided));
+    return Stdlib_JsError.throwWithMessage(unmetMessage(missing, provided, listing));
   }
 }
 
@@ -66,7 +85,9 @@ export {
   elevatedNeeds,
   unmet,
   describe,
+  remedy,
   unmetMessage,
+  contradictedMessage,
   check,
 }
 /* Role-Reventless Not a pure module */