@reventlessdev/reventless-aws 3.0.0-alpha.319 → 3.0.0-alpha.321

package/src/adapter/Auth/Auth_ActiveRoleStore_Schema.res

@@ -0,0 +1,92 @@
+// The active-role store's identity: what it is called, and how its rows are
+// keyed. See [docs/plans/active-role-store-scoped-to-the-pool.md].
+//
+// 🚨 **One definition, four consumers, and that is the whole reason this file
+// exists.** The deploy creates or looks the table up ([Auth_ActiveRoleStore]),
+// the write door writes rows ([Auth_ActiveRoleStore_Ops]), the pre-token trigger
+// reads them ([Auth_ActiveRoleTrigger_Ops]), and the provisioning script creates
+// the table on a provider no stack owns (`scripts/provision-identity.mjs`). Any
+// two of those disagreeing produces the same failure: a row written where nothing
+// looks for it, so a role switch reports success and does nothing.
+//
+// Deliberately free of Pulumi and of the AWS SDK, so the script and both Lambda
+// bundles can import it without dragging a deploy-time dependency into a runtime
+// graph — the hazard that once broke command-handler cold starts.
+
+/**
+The store belonging to an identity provider this framework does not own.
+
+Derived rather than configured. The objection to deriving was that two stacks
+would both try to *create* the table and the second would fail or adopt a
+resource it does not own — true while stacks create it, and no stack creates this
+one. What derivation buys is worth more than the config key it removes: two
+platforms on one provider **cannot** name different stores, so the defect stops
+being something to detect and becomes something that cannot be expressed.
+
+The provider id carries its own region (`eu-west-1_CQTwafSeX`), which is the
+region the store must live in too — a pre-token-generation trigger has to sit in
+its pool's region, so every stack that can attach one derives the same name in
+the same place.
+*/
+let derivedStoreName = (~identityProviderId: string): string =>
+  `ReventlessActiveRoleStore-${identityProviderId}`
+
+/** The caller's Cognito `sub`. Stable across a rename, unlike the username. */
+let partitionKey = "id"
+
+/**
+The app client the token was minted for.
+
+A sort key rather than nothing, because one identity provider can serve several
+platforms: each platform stack declares its own app client, so keying on the pair
+gives every platform its own active role over one shared set of rows. Keyed on
+the subject alone, narrowing to a role in one platform would narrow the caller's
+session in every other platform on that provider — defensible as "one identity,
+one session", but not what an operator wants, since a role with surfaces in one
+platform and none in another leaves the second showing nothing.
+*/
+let sortKey = "clientId"
+
+/** The stored choice itself. */
+let roleAttribute = "activeRole"
+
+/** The key schema as DynamoDB describes one: `(attribute, keyType)` pairs.
+
+  Plain tuples rather than the SDK's `keySchemaElement` so this module keeps its
+  "no side effect" footer — importing the AWS SDK here would put it in both Lambda
+  bundles, which is the dependency leak that once broke command-handler cold
+  starts. Callers map their own shapes into this. */
+let expectedKeySchema: array<(string, string)> = [(partitionKey, "HASH"), (sortKey, "RANGE")]
+
+let describeKeySchema = (elements: array<(string, string)>): string =>
+  elements
+  ->Array.map(((attribute, keyType)) => `${attribute}:${keyType}`)
+  ->Array.toSorted(String.compare)
+  ->Array.join(",")
+
+/**
+Why a table that already exists cannot serve as the store, if it cannot.
+
+🚨 **A table under the right name with the wrong key is worse than no table.** The
+deploy finds it, the handlers write into it, and every read misses — a role switch
+that reports success and does nothing, which is the defect this whole store was
+repaired for. So adoption checks the schema and refuses, rather than reporting
+success.
+
+The pre-`clientId` store is exactly this case: keyed on the subject alone. An
+operator upgrading meets a sentence instead of a silent misbehaviour.
+
+Order-insensitive, because `DescribeTable` does not promise one.
+*/
+let keySchemaRefusal = (
+  ~tableName: string,
+  ~actual: array<(string, string)>,
+): option<string> => {
+  let actualKey = describeKeySchema(actual)
+  let wantedKey = describeKeySchema(expectedKeySchema)
+  actualKey == wantedKey
+    ? None
+    : Some(
+        `table "${tableName}" already exists with key schema [${actualKey}], but the active-role store needs [${wantedKey}]. A row written under one key is invisible to a read under the other, so role switching would report success and do nothing. Delete the table if its rows are disposable — they are preferences, and every caller re-chooses on their next switch.`,
+      )
+}

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

@@ -0,0 +1,49 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+
+function derivedStoreName(identityProviderId) {
+  return `ReventlessActiveRoleStore-` + identityProviderId;
+}
+
+let partitionKey = "id";
+
+let sortKey = "clientId";
+
+let expectedKeySchema = [
+  [
+    partitionKey,
+    "HASH"
+  ],
+  [
+    sortKey,
+    "RANGE"
+  ]
+];
+
+function describeKeySchema(elements) {
+  return elements.map(param => param[0] + `:` + param[1]).toSorted(Primitive_string.compare).join(",");
+}
+
+function keySchemaRefusal(tableName, actual) {
+  let actualKey = describeKeySchema(actual);
+  let wantedKey = describeKeySchema(expectedKeySchema);
+  if (actualKey === wantedKey) {
+    return;
+  } else {
+    return `table "` + tableName + `" already exists with key schema [` + actualKey + `], but the active-role store needs [` + wantedKey + `]. A row written under one key is invisible to a read under the other, so role switching would report success and do nothing. Delete the table if its rows are disposable — they are preferences, and every caller re-chooses on their next switch.`;
+  }
+}
+
+let roleAttribute = "activeRole";
+
+export {
+  derivedStoreName,
+  partitionKey,
+  sortKey,
+  roleAttribute,
+  expectedKeySchema,
+  describeKeySchema,
+  keySchemaRefusal,
+}
+/* No side effect */

package/src/adapter/Auth/Auth_ActiveRoleTrigger_Ops.res

@@ -60,6 +60,11 @@ type triggerRequest = {
   groupConfiguration?: groupConfiguration,
 }
 
+/** The app client this token is being minted for — the second half of the store's
+  row key, and what makes the active role per-platform on a provider serving
+  several. Cognito supplies it on every pre-token-generation event. */
+type callerContext = {clientId?: string}
+
 type groupOverrideDetails = {
   groupsToOverride: array<string>,
   iamRolesToOverride: array<string>,
@@ -77,6 +82,7 @@ type event = {
   request?: triggerRequest,
   response?: triggerResponse,
   userName?: string,
+  callerContext?: callerContext,
 }
 
 // ── The decision ────────────────────────────────────────────────────────────
@@ -171,15 +177,18 @@ sign-in outright, and failing a login because a *preference* could not be read
 trades a working session for a cosmetic one. The caller lands on full membership —
 their existing privileges, not more — which is the safe direction to fail.
 */
-let storedRoleFor = async (~sub: string, ~table: string): option<string> =>
+let storedRoleFor = async (~sub: string, ~clientId: string, ~table: string): option<string> =>
   try {
     let out = await DynamoDb_DocumentClient.GetCommand.make({
       tableName: table,
-      key: Dict.fromArray([("id", JSON.Encode.string(sub))]),
+      key: Dict.fromArray([
+        (Auth_ActiveRoleStore_Schema.partitionKey, JSON.Encode.string(sub)),
+        (Auth_ActiveRoleStore_Schema.sortKey, JSON.Encode.string(clientId)),
+      ]),
     })->DynamoDb_DocumentClient.GetCommand.send
     out.item
     ->Option.flatMap(JSON.Decode.object)
-    ->Option.flatMap(o => o->Dict.get("activeRole"))
+    ->Option.flatMap(o => o->Dict.get(Auth_ActiveRoleStore_Schema.roleAttribute))
     ->Option.flatMap(JSON.Decode.string)
   } catch {
   | _ => None
@@ -197,12 +206,17 @@ let handler = async (event: event): event => {
   let sub =
     event.request->Option.flatMap(r => r.userAttributes)->Option.flatMap(u => u.sub)->Option.getOr("")
 
-  // No subject means no row to look up. Returning the event untouched keeps the
-  // sign-in working on exactly the membership the pool granted.
-  if sub == "" {
+  let clientId = event.callerContext->Option.flatMap(c => c.clientId)->Option.getOr("")
+
+  // Neither half of the key means no row to look up. Returning the event
+  // untouched keeps the sign-in working on exactly the membership the pool
+  // granted — the safe direction, and the same one a read failure takes. An
+  // absent client id is not worth failing a login over: the caller lands on their
+  // full membership, which is their existing privileges and not more.
+  if sub == "" || clientId == "" {
     event
   } else {
-    let storedRole = await storedRoleFor(~sub, ~table=tableName())
+    let storedRole = await storedRoleFor(~sub, ~clientId, ~table=tableName())
     respond(~event, ~decision=decide(~membership, ~storedRole))
   }
 }

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

@@ -6,6 +6,7 @@ import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as LibDynamodb from "@aws-sdk/lib-dynamodb";
 import * as Auth_ActiveRole$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/Auth/Auth_ActiveRole.res.mjs";
 import * as DynamoDb_DocumentClient$AwsSdk from "@reventlessdev/rescript-aws-sdk/src/DynamoDb_DocumentClient.res.mjs";
+import * as Auth_ActiveRoleStore_Schema$ReventlessAws from "./Auth_ActiveRoleStore_Schema.res.mjs";
 
 function getEnv(k) {
   let v = process.env[k];
@@ -90,16 +91,22 @@ function respond(event, decision) {
   ]));
 }
 
-async function storedRoleFor(sub, table) {
+async function storedRoleFor(sub, clientId, table) {
   try {
     let out = await DynamoDb_DocumentClient$AwsSdk.GetCommand.send(new LibDynamodb.GetCommand({
       TableName: table,
-      Key: Object.fromEntries([[
-          "id",
+      Key: Object.fromEntries([
+        [
+          Auth_ActiveRoleStore_Schema$ReventlessAws.partitionKey,
           sub
-        ]])
+        ],
+        [
+          Auth_ActiveRoleStore_Schema$ReventlessAws.sortKey,
+          clientId
+        ]
+      ])
     }));
-    return Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(out.Item, Stdlib_JSON.Decode.object), o => o["activeRole"]), Stdlib_JSON.Decode.string);
+    return Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(out.Item, Stdlib_JSON.Decode.object), o => o[Auth_ActiveRoleStore_Schema$ReventlessAws.roleAttribute]), Stdlib_JSON.Decode.string);
   } catch (exn) {
     return;
   }
@@ -108,10 +115,11 @@ async function storedRoleFor(sub, table) {
 async function handler(event) {
   let membership = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(event.request, r => r.groupConfiguration), g => g.groupsToOverride), []);
   let sub = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(event.request, r => r.userAttributes), u => u.sub), "");
-  if (sub === "") {
+  let clientId = Stdlib_Option.getOr(Stdlib_Option.flatMap(event.callerContext, c => c.clientId), "");
+  if (sub === "" || clientId === "") {
     return event;
   }
-  let storedRole = await storedRoleFor(sub, tableName());
+  let storedRole = await storedRoleFor(sub, clientId, tableName());
   return respond(event, decide(membership, storedRole));
 }
 

package/src/adapter/QueryDb/QueryDbResolvers_AppSync.res

@@ -283,13 +283,6 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
     // (prefix-agnostic: real plugin rows always carry `name`, internal rows never do).
     // See docs/plans/done/platform-plugins-admin-connection-null-rows.md.
     let requireAttribute = internalRowRequiredAttr(name)
-    // A DynamoDB FilterExpression is applied AFTER the page is read, so a scoped
-    // list over a table with no index on the owner field returns short pages —
-    // correct, but pathological once a caller owns a small fraction of the rows.
-    // Warned rather than refused: the resolver does serve the query, and a
-    // deployment may legitimately accept the cost on a small table. Mirrors the
-    // `@scanSort` alignment warning above, which exists for the same class of
-    // "works, but scans" mistake.
     ReventlessCore.OwnerScopeDiagnostics.warnIfNoElevatedGroups(
       ~comp="QueryDbResolvers_AppSync",
       ~view=name,
@@ -298,17 +291,33 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
     let isIndexed = f =>
       indexes->Array.some(ic => ic.idField->Option.getOr(ic.index) == f) ||
         subIdField->Option.getOr("") == f
-    switch ownerField {
+    // The index `@owner` derives, and the sort key that orders one caller's rows
+    // inside it. Its absence means the author declined it — the list then falls
+    // back to the Scan-and-filter this used to prescribe an `@index` for.
+    let ownerIndexConfig = switch ownerField {
     | Some(f) =>
-      if !isIndexed(f) {
-        log.warn(
-          ~comp="QueryDbResolvers_AppSync",
-          `${name}: @owner field "${f}" is not the key of any index on this table. ` ++
-          "Owner-scoped reads will Scan and filter, so pages shrink as the caller's " ++
-          "share of the rows falls. Add an @index on that field before this read model grows.",
-        )
-      }
-    | None => ()
+      indexes->Array.find(ic =>
+        Reventless.ReadModel.isDerivedIndex(ic) && ic.idField->Option.getOr(ic.index) == f
+      )
+    | None => None
+    }
+    let ownerIndex = ownerIndexConfig->Option.map(ic => ic.index)
+    let ownerIndexSortField = ownerIndexConfig->Option.flatMap(ic => ic.subIdField)
+    // Only reachable through `@owner({index: false})` now that the index is
+    // derived by default, so this states the cost of that choice rather than
+    // prescribing an `@index` — which would provision a second index on the same
+    // key and still not be the one the list reads.
+    switch (ownerField, ownerIndex) {
+    | (Some(f), None) if !isIndexed(f) =>
+      log.warn(
+        ~comp="QueryDbResolvers_AppSync",
+        `${name}: @owner field "${f}" keys no index on this table, so owner-scoped ` ++
+        "reads Scan the table and filter after the page is read — cost grows with the " ++
+        "table while the answer shrinks with the caller's share of it. Drop " ++
+        "`@owner({index: false})` to let the framework derive the index, or accept " ++
+        "the cost on a view that stays small.",
+      )
+    | _ => ()
     }
     // The same class of "works, but scans" mistake as the owner warning above,
     // and the retirement case degrades the same way: the FilterExpression is
@@ -346,12 +355,19 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
           ~elevatedGroups,
           ~retiredField?,
           ~retiredValues?,
+          ~ownerIndex?,
+          ~ownerIndexSortField?,
         )
       } else {
         Resolver.Functions.listAllItems
       },
     )
-    let resolversByIndex = indexes->Array.map(({index} as indexConfig) => {
+    // Derived indexes are absent from the SDL (`GraphQL_FragmentGenerator` skips
+    // them), so a resolver here would attach to a field that does not exist and
+    // fail the deploy. The list resolver above is the only thing that reads one.
+    let resolversByIndex = indexes
+    ->Array.filter(ic => !Reventless.ReadModel.isDerivedIndex(ic))
+    ->Array.map(({index} as indexConfig) => {
       // Name and key field both come from `GraphQL_FragmentGenerator`, which is
       // where the SDL field this attaches to is derived. Deriving them here as
       // well is how the two came to disagree: the emitted field declared `id`

package/src/adapter/QueryDb/QueryDbResolvers_AppSync.res.mjs

@@ -4,6 +4,7 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
 import * as Owner$Reventless from "@reventlessdev/reventless-spec/src/components/Owner.res.mjs";
+import * as ReadModel$Reventless from "@reventlessdev/reventless-spec/src/components/ReadModel.res.mjs";
 import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
 import * as OwnerScope$Reventless from "@reventlessdev/reventless-spec/src/types/OwnerScope.res.mjs";
 import * as Adapter$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/Adapter.res.mjs";
@@ -123,14 +124,23 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
         return Stdlib_Option.getOr(subIdField, "") === f;
       }
     };
-    if (ownerField !== undefined && !isIndexed(ownerField)) {
-      log.warn("QueryDbResolvers_AppSync", undefined, name$1 + `: @owner field "` + ownerField + `" is not the key of any index on this table. ` + "Owner-scoped reads will Scan and filter, so pages shrink as the caller's share of the rows falls. Add an @index on that field before this read model grows.");
+    let ownerIndexConfig = ownerField !== undefined ? indexes.find(ic => {
+        if (ReadModel$Reventless.isDerivedIndex(ic)) {
+          return Stdlib_Option.getOr(ic.idField, ic.index) === ownerField;
+        } else {
+          return false;
+        }
+      }) : undefined;
+    let ownerIndex = Stdlib_Option.map(ownerIndexConfig, ic => ic.index);
+    let ownerIndexSortField = Stdlib_Option.flatMap(ownerIndexConfig, ic => ic.subIdField);
+    if (ownerField !== undefined && !(ownerIndex !== undefined || isIndexed(ownerField))) {
+      log.warn("QueryDbResolvers_AppSync", undefined, name$1 + `: @owner field "` + ownerField + `" keys no index on this table, so owner-scoped ` + "reads Scan the table and filter after the page is read — cost grows with the table while the answer shrinks with the caller's share of it. Drop `@owner({index: false})` to let the framework derive the index, or accept the cost on a view that stays small.");
     }
     if (retiredField !== undefined && !isIndexed(retiredField)) {
       log.warn("QueryDbResolvers_AppSync", undefined, name$1 + `: @retired field "` + retiredField + `" is not the key of any index on this table. ` + "Reads that exclude retired rows will Scan and filter, so pages shrink as the archive's share of the rows grows. Add an @index on that field before this read model grows.");
     }
-    let resolverAll = makeQueryResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, connectionSpec ? AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection(labelField, filterFieldNames, rangeFieldNames, sortFieldNames, requireAttribute, ownerField, elevatedGroups, retiredField, retiredValues) : AppSync_Resolver_Functions$PulumiAws.listAllItems);
-    let resolversByIndex = indexes.map(indexConfig => {
+    let resolverAll = makeQueryResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, connectionSpec ? AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection(labelField, filterFieldNames, rangeFieldNames, sortFieldNames, requireAttribute, ownerField, elevatedGroups, retiredField, retiredValues, ownerIndex, ownerIndexSortField) : AppSync_Resolver_Functions$PulumiAws.listAllItems);
+    let resolversByIndex = indexes.filter(ic => !ReadModel$Reventless.isDerivedIndex(ic)).map(indexConfig => {
       let index = indexConfig.index;
       let fieldName = GraphQL_FragmentGenerator$ReventlessCore.indexQueryFieldName(fieldNameForSingle, index);
       let resolverName = Stdlib_String.capitalize(fieldName);

package/src/adapter/QueryDb/QueryDbStorage_DynamoDb.res

@@ -29,20 +29,35 @@ let globalSecondaryIndexes = (indexes: array<Reventless.ReadModel.indexConfig>)
   })
   ->Pulumi.Input.make
 
-let attributes = (sortField, indexes: array<Reventless.ReadModel.indexConfig>) =>
-  [
-    [{name: "id", type_: "S"}],
-    sortField->Option.mapOr([], sortField => [{name: sortField, type_: "S"}]),
-    indexes
-    ->Array.map((indexConfig: Reventless.ReadModel.indexConfig) => {
-      let {index, type_} = indexConfig
-      [
-        [{name: indexConfig.idField->Option.getOr(index), type_}],
-        indexConfig.subIdField->Option.mapOr([], sortField => [{name: sortField, type_: "S"}]),
-      ]->Array.flat
-    })
-    ->Array.flat,
-  ]->Array.flat
+// Pulumi rejects a table that defines the same attribute twice, and an index may
+// legitimately key on one the table already declares — the derived `@owner` index
+// sorts on `id`, and any index may sort on the table's own sort key. First
+// declaration wins; they agree on the type because both name the same column.
+let attributes = (sortField, indexes: array<Reventless.ReadModel.indexConfig>) => {
+  let all =
+    [
+      [{name: "id", type_: "S"}],
+      sortField->Option.mapOr([], sortField => [{name: sortField, type_: "S"}]),
+      indexes
+      ->Array.map((indexConfig: Reventless.ReadModel.indexConfig) => {
+        let {index, type_} = indexConfig
+        [
+          [{name: indexConfig.idField->Option.getOr(index), type_}],
+          indexConfig.subIdField->Option.mapOr([], sortField => [{name: sortField, type_: "S"}]),
+        ]->Array.flat
+      })
+      ->Array.flat,
+    ]->Array.flat
+  let seen = Set.make()
+  all->Array.filter(({name}) =>
+    if seen->Set.has(name) {
+      false
+    } else {
+      seen->Set.add(name)
+      true
+    }
+  )
+}
 
 let dataSource = (name, table, api, apiRole, opts) => {
   let _dataSourceRolePolicy = {

package/src/adapter/QueryDb/QueryDbStorage_DynamoDb.res.mjs

@@ -38,7 +38,7 @@ function globalSecondaryIndexes(indexes) {
 }
 
 function attributes(sortField, indexes) {
-  return [
+  let all = [
     [{
         name: "id",
         type: "S"
@@ -58,6 +58,16 @@ function attributes(sortField, indexes) {
         }])
     ].flat()).flat()
   ].flat();
+  let seen = new Set();
+  return all.filter(param => {
+    let name = param.name;
+    if (seen.has(name)) {
+      return false;
+    } else {
+      seen.add(name);
+      return true;
+    }
+  });
 }
 
 function dataSource(name, table, api, apiRole, opts) {

package/src/util/Util_AwsError.res

@@ -0,0 +1,56 @@
+// Classifying an AWS SDK failure, for callers that must tell one apart from the
+// rest rather than treat every throw alike.
+//
+// 🚨 **The error's `name` carries the code; its `message` does not have to.** A
+// v3 SDK `DescribeTable` on a missing table throws `name:
+// "ResourceNotFoundException"` with the message "Requested resource not found:
+// Table: X not found" — which does not contain the code anywhere. A guard written
+// against the message alone therefore never matches, and the ordinary case it was
+// meant to absorb escapes as an unhandled rejection instead.
+//
+// That is not hypothetical: it is why this module exists rather than the check
+// living inline. A predicate inside a script that runs on import cannot be tested,
+// so the version that could never match shipped.
+//
+// `Auth_ActiveRolePoolAttachment` keeps its own inline copy on purpose — Pulumi
+// serialises a dynamic provider's whole closure into stack state, and a helper
+// reached through a module import is a dependency that serialisation cannot carry.
+
+@get @return(nullable) external name: JsExn.t => option<string> = "name"
+
+/** Whether a failure carries this AWS error code, by `name` first and message as
+  a fallback for wrapped or re-thrown shapes. */
+let hasCode = (exn: exn, ~code: string): bool =>
+  switch exn->JsExn.fromException {
+  | Some(jsErr) =>
+    switch (jsErr->name, JsExn.message(jsErr)) {
+    | (Some(actual), _) if actual == code => true
+    | (_, Some(message)) => message->String.includes(code)
+    | _ => false
+    }
+  | None => false
+  }
+
+/** The resource named by the call does not exist — the shape both DynamoDB and
+  Cognito use, and normally an absence to handle rather than a failure to report. */
+let isNotFound = (exn: exn): bool => exn->hasCode(~code="ResourceNotFoundException")
+
+/**
+An escaped exception as one line an operator can act on.
+
+For the top of a CLI: without it Node reports `UnhandledPromiseRejection ...
+"#<Object>"`, which names neither the call that failed nor why. Every branch
+returns something, because a describer that itself throws replaces one unreadable
+failure with another.
+*/
+let describe = (exn: exn): string =>
+  switch exn->JsExn.fromException {
+  | Some(jsErr) =>
+    switch (jsErr->name, JsExn.message(jsErr)) {
+    | (Some(n), Some(m)) => `${n}: ${m}`
+    | (Some(n), None) => n
+    | (None, Some(m)) => m
+    | (None, None) => "an AWS call failed with no message"
+    }
+  | None => "an unexpected error escaped"
+  }

package/src/util/Util_AwsError.res.mjs

@@ -0,0 +1,59 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+
+function hasCode(exn, code) {
+  let jsErr = Stdlib_JsExn.fromException(exn);
+  if (jsErr === undefined) {
+    return false;
+  }
+  let jsErr$1 = Primitive_option.valFromOption(jsErr);
+  let match = jsErr$1.name;
+  let match$1 = Stdlib_JsExn.message(jsErr$1);
+  if (match == null) {
+    if (match$1 !== undefined) {
+      return match$1.includes(code);
+    } else {
+      return false;
+    }
+  } else if (match === code) {
+    return true;
+  } else if (match$1 !== undefined) {
+    return match$1.includes(code);
+  } else {
+    return false;
+  }
+}
+
+function isNotFound(exn) {
+  return hasCode(exn, "ResourceNotFoundException");
+}
+
+function describe(exn) {
+  let jsErr = Stdlib_JsExn.fromException(exn);
+  if (jsErr === undefined) {
+    return "an unexpected error escaped";
+  }
+  let jsErr$1 = Primitive_option.valFromOption(jsErr);
+  let match = jsErr$1.name;
+  let match$1 = Stdlib_JsExn.message(jsErr$1);
+  if (match == null) {
+    if (match$1 !== undefined) {
+      return match$1;
+    } else {
+      return "an AWS call failed with no message";
+    }
+  } else if (match$1 !== undefined) {
+    return match + `: ` + match$1;
+  } else {
+    return match;
+  }
+}
+
+export {
+  hasCode,
+  isNotFound,
+  describe,
+}
+/* Stdlib_JsExn Not a pure module */

package/src/util/Util_ShellConfig.res

@@ -31,6 +31,34 @@ let modeOptions = (mode: Platform.viewMode): array<(string, JSON.t)> =>
     }
   }
 
+/**
+The identity fields a shell reads, under **both** spellings.
+
+🚨 **Both, and not as a sequenced rename.** `identityProvider*` is what these
+become — the concept is not AWS-specific, so a second cloud's adapter should meet
+the same names. `cognito*` is what every shipped shell reads today.
+
+A shell reads `config.json` at runtime and CloudFront serves the previous bundle
+until someone invalidates it, so switching the keys in one deploy leaves a window
+where the served bundle and the served config disagree. `cognitoClientId` is read
+into an `option`: a bundle that cannot find its key does not error, it gets
+`None`, and login, silent refresh and token refresh all quietly fall through —
+the window is a total auth outage that reports nothing.
+
+Writing both removes the ordering dependency rather than managing it: any bundle,
+old or new or stale in a CDN, finds one it understands. The `cognito*` pair goes
+once the shell that prefers the other is the pinned one.
+
+Here rather than inline at the call site so the pairing is one fact in one place,
+and so the property can be asserted without a deploy.
+*/
+let identityFields = (~providerId: string, ~clientId: string): array<(string, JSON.t)> => [
+  ("identityProviderId", JSON.Encode.string(providerId)),
+  ("identityProviderClientId", JSON.Encode.string(clientId)),
+  ("cognitoUserPoolId", JSON.Encode.string(providerId)),
+  ("cognitoClientId", JSON.Encode.string(clientId)),
+]
+
 /**
 The config.json field set.
 

package/src/util/Util_ShellConfig.res.mjs

@@ -31,6 +31,27 @@ function modeOptions(mode) {
   }
 }
 
+function identityFields(providerId, clientId) {
+  return [
+    [
+      "identityProviderId",
+      providerId
+    ],
+    [
+      "identityProviderClientId",
+      clientId
+    ],
+    [
+      "cognitoUserPoolId",
+      providerId
+    ],
+    [
+      "cognitoClientId",
+      clientId
+    ]
+  ];
+}
+
 function fields(computed, viewModes, bakedManifest, shellConfig) {
   let out = Object.fromEntries(computed);
   Stdlib_Option.forEach(bakedManifest, bake => {
@@ -70,6 +91,7 @@ export {
   Platform,
   journeyManifestsKey,
   modeOptions,
+  identityFields,
   fields,
 }
 /* No side effect */