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

package/tests/Auth_ActiveRolePoolAttachmentTest.res.mjs

@@ -362,6 +362,142 @@ globalThis.describe("Auth_ActiveRolePoolAttachment.probeEvent", () => {
   globalThis.test("presents no groups to narrow", () => {
     globalThis.expect(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(event, o => o["request"]), Stdlib_JSON.Decode.object), r => r["groupConfiguration"]), Stdlib_JSON.Decode.object), g => g["groupsToOverride"]), Stdlib_JSON.Decode.array)).toEqual([]);
   });
+  globalThis.test("carries the caller context the handler keys its read on", () => {
+    globalThis.expect(Stdlib_Option.isSome(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(event, o => o["callerContext"]), Stdlib_JSON.Decode.object), c => c["clientId"]), Stdlib_JSON.Decode.string))).toBe(true);
+  });
+  globalThis.test("the probe's subject and client cannot collide with a real row", () => {
+    globalThis.expect(Auth_ActiveRolePoolAttachment$ReventlessAws.probeSubject === Auth_ActiveRolePoolAttachment$ReventlessAws.probeClientId).toBe(false);
+  });
+});
+
+globalThis.describe("Auth_ActiveRolePoolAttachment.attachedTriggerArn", () => {
+  let theirArn = "arn:aws:lambda:eu-west-1:1:function:TheirOwnPreToken";
+  let withConfig = version => Object.fromEntries([[
+      "LambdaConfig",
+      Object.fromEntries([[
+          "PreTokenGenerationConfig",
+          Object.fromEntries([
+            [
+              "LambdaArn",
+              theirArn
+            ],
+            [
+              "LambdaVersion",
+              version
+            ]
+          ])
+        ]])
+    ]]);
+  globalThis.test("an empty pool holds nothing", () => {
+    globalThis.expect(Auth_ActiveRolePoolAttachment$ReventlessAws.attachedTriggerArn(Object.fromEntries([[
+        "Name",
+        "Bare"
+      ]]))).toEqual(undefined);
+  });
+  globalThis.test("reports the trigger a pool carries", () => {
+    globalThis.expect(Auth_ActiveRolePoolAttachment$ReventlessAws.attachedTriggerArn(withConfig("V1_0"))).toEqual(theirArn);
+  });
+  globalThis.test("a foreign trigger at another version is still occupying the slot", () => {
+    globalThis.expect([
+      Auth_ActiveRolePoolAttachment$ReventlessAws.attachedTriggerArn(withConfig("V2_0")),
+      Auth_ActiveRolePoolAttachment$ReventlessAws.attachedTrigger(withConfig("V2_0"))
+    ]).toEqual([
+      theirArn,
+      undefined
+    ]);
+  });
+  globalThis.test("falls back to the legacy field on a pool carrying only that", () => {
+    globalThis.expect(Auth_ActiveRolePoolAttachment$ReventlessAws.attachedTriggerArn(Object.fromEntries([[
+        "LambdaConfig",
+        Object.fromEntries([[
+            "PreTokenGeneration",
+            theirArn
+          ]])
+      ]]))).toEqual(theirArn);
+  });
+});
+
+globalThis.describe("Auth_ActiveRolePoolAttachment.classifySlot", () => {
+  let ours = "arn:aws:lambda:eu-west-1:1:function:OurTrigger";
+  let theirs = "arn:aws:lambda:eu-west-1:1:function:OtherStackTrigger";
+  let store = "ReventlessActiveRoleStore-eu-west-1_x";
+  let classify = (attachedArn, attachedStore) => Auth_ActiveRolePoolAttachment$ReventlessAws.classifySlot(attachedArn, ours, store, attachedStore);
+  globalThis.test("an empty slot is free to take", () => {
+    globalThis.expect(classify(undefined, undefined)).toEqual("Vacant");
+  });
+  globalThis.test("an empty ARN is an empty slot, not a foreign trigger", () => {
+    globalThis.expect(classify("", undefined)).toEqual("Vacant");
+  });
+  globalThis.test("our own trigger is ours to re-attach", () => {
+    globalThis.expect(classify(ours, undefined)).toEqual("Ours");
+  });
+  globalThis.test("another deployment's trigger on the same store serves both", () => {
+    globalThis.expect(classify(theirs, store)).toEqual({
+      TAG: "SharedWith",
+      _0: theirs
+    });
+  });
+  globalThis.test("another deployment's trigger on a different store is the defect", () => {
+    globalThis.expect(classify(theirs, "ActiveRoleStore-829c96f")).toEqual({
+      TAG: "DifferentStore",
+      arn: theirs,
+      theirStore: "ActiveRoleStore-829c96f"
+    });
+  });
+  globalThis.test("a trigger with no store of ours is foreign", () => {
+    globalThis.expect(classify(theirs, undefined)).toEqual({
+      TAG: "Foreign",
+      _0: theirs
+    });
+  });
+});
+
+globalThis.describe("Auth_ActiveRolePoolAttachment.refusalFor", () => {
+  let store = "ReventlessActiveRoleStore-eu-west-1_x";
+  globalThis.test("the three attachable slots produce no refusal", () => {
+    globalThis.expect([
+      Auth_ActiveRolePoolAttachment$ReventlessAws.refusalFor("Vacant", "eu-west-1_x", store),
+      Auth_ActiveRolePoolAttachment$ReventlessAws.refusalFor("Ours", "eu-west-1_x", store),
+      Auth_ActiveRolePoolAttachment$ReventlessAws.refusalFor({
+        TAG: "SharedWith",
+        _0: "arn:aws:lambda:eu-west-1:1:function:Other"
+      }, "eu-west-1_x", store)
+    ]).toEqual([
+      undefined,
+      undefined,
+      undefined
+    ]);
+  });
+  globalThis.test("a disagreeing store is refused, naming both stores", () => {
+    let message = Stdlib_Option.getOr(Auth_ActiveRolePoolAttachment$ReventlessAws.refusalFor({
+      TAG: "DifferentStore",
+      arn: "arn:aws:lambda:eu-west-1:1:function:Other",
+      theirStore: "ActiveRoleStore-829c96f"
+    }, "eu-west-1_x", store), "");
+    globalThis.expect([
+      message.includes(store),
+      message.includes("ActiveRoleStore-829c96f"),
+      message.includes("eu-west-1_x")
+    ]).toEqual([
+      true,
+      true,
+      true
+    ]);
+  });
+  globalThis.test("a foreign trigger is refused, naming what is attached", () => {
+    let arn = "arn:aws:lambda:eu-west-1:1:function:TheirClaimsEnrichment";
+    let message = Stdlib_Option.getOr(Auth_ActiveRolePoolAttachment$ReventlessAws.refusalFor({
+      TAG: "Foreign",
+      _0: arn
+    }, "eu-west-1_x", store), "");
+    globalThis.expect([
+      message.includes(arn),
+      message.includes("lambda:GetFunctionConfiguration")
+    ]).toEqual([
+      true,
+      true
+    ]);
+  });
 });
 
 let Attachment;

package/tests/Auth_ActiveRoleStoreTest.res

@@ -72,3 +72,68 @@ describe("Auth_ActiveRoleStore_Ops.cognitoLookupName", () => {
     expect(Ops.cognitoLookupName(~identity={}))->toEqual(None)
   )
 })
+
+// Which store this deployment reads and writes. Two cases and no third: a stack
+// that creates its own provider owns everything attached to it, and a stack given
+// a provider owns none of it. See
+// [docs/plans/active-role-store-scoped-to-the-pool.md].
+describe("Auth_ActiveRoleStore.chooseStore", () => {
+  testSync("a stack that creates its own provider keeps its own table", () =>
+    expect(Auth_ActiveRoleStore.chooseStore(~identityProviderId=None))->toEqual(
+      Auth_ActiveRoleStore.StackScoped,
+    )
+  )
+
+  testSync("a stack given a provider reads that provider's derived store", () =>
+    expect(Auth_ActiveRoleStore.chooseStore(~identityProviderId=Some("eu-west-1_CQTwafSeX")))
+    ->toEqual(
+      Auth_ActiveRoleStore.ProviderScoped("ReventlessActiveRoleStore-eu-west-1_CQTwafSeX"),
+    )
+  )
+
+  // 🚨 The defect, expressed as the property that now prevents it. Two platform
+  // stacks on one provider previously deployed a table each, so the pool's single
+  // trigger read rows the other's resolver wrote — every switch succeeding and
+  // doing nothing. There is no configuration either could carry that would make
+  // them disagree.
+  testSync("two deployments on one provider cannot choose different stores", () =>
+    expect(Auth_ActiveRoleStore.chooseStore(~identityProviderId=Some("eu-west-1_Shared")))
+    ->toEqual(Auth_ActiveRoleStore.chooseStore(~identityProviderId=Some("eu-west-1_Shared")))
+  )
+})
+
+// The second half of the row key. Every other absent field in this handler has a
+// defensible default; this one does not, and the test that matters is the one
+// asserting it refuses rather than substituting something.
+describe("Auth_ActiveRoleStore_Ops.appClientId", () => {
+  testSync("the app client the authorizer resolved is the one used", () =>
+    expect(Ops.appClientId(~identity={sub: "sub-1", clientId: Value("7cl13nt")}))->toEqual(
+      Some("7cl13nt"),
+    )
+  )
+
+  // 🚨 The trigger keys its read on the client id Cognito hands it, so a write
+  // under any substitute — a constant, the subject, the empty string — is a row
+  // the trigger never finds. Refusing is the only answer that does not recreate
+  // the defect one level down.
+  testSync("an absent client id yields nothing to key a row on", () =>
+    expect(Ops.appClientId(~identity={sub: "sub-1"}))->toEqual(None)
+  )
+
+  // The resolver sends `appClientId(id)`, which returns null when the claims are
+  // not there to read — so null is the shape that actually arrives, not a missing
+  // field.
+  testSync("an explicitly null client id is not a client id", () =>
+    expect(Ops.appClientId(~identity={sub: "sub-1", clientId: Null}))->toEqual(None)
+  )
+
+  testSync("a blank client id is not a client id either", () =>
+    expect(Ops.appClientId(~identity={sub: "sub-1", clientId: Value("   ")}))->toEqual(None)
+  )
+
+  // The subject is deliberately not a fallback: it would key every platform's row
+  // identically and undo the per-platform narrowing the pair key exists for.
+  testSync("the subject is never substituted for the app client", () =>
+    expect(Ops.appClientId(~identity={sub: "sub-1", clientId: Null}))->toEqual(None)
+  )
+})

package/tests/Auth_ActiveRoleStoreTest.res.mjs

@@ -2,6 +2,7 @@
 
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Auth_ActiveRole$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/Auth/Auth_ActiveRole.res.mjs";
+import * as Auth_ActiveRoleStore$ReventlessAws from "../src/adapter/Auth/Auth_ActiveRoleStore.res.mjs";
 import * as Auth_ActiveRoleStore_Ops$ReventlessAws from "../src/adapter/Auth/Auth_ActiveRoleStore_Ops.res.mjs";
 
 globalThis.describe("Auth_ActiveRoleStore_Ops.mayActAs — the conformance table", () => {
@@ -59,6 +60,53 @@ globalThis.describe("Auth_ActiveRoleStore_Ops.cognitoLookupName", () => {
   });
 });
 
+globalThis.describe("Auth_ActiveRoleStore.chooseStore", () => {
+  globalThis.test("a stack that creates its own provider keeps its own table", () => {
+    globalThis.expect(Auth_ActiveRoleStore$ReventlessAws.chooseStore(undefined)).toEqual("StackScoped");
+  });
+  globalThis.test("a stack given a provider reads that provider's derived store", () => {
+    globalThis.expect(Auth_ActiveRoleStore$ReventlessAws.chooseStore("eu-west-1_CQTwafSeX")).toEqual({
+      TAG: "ProviderScoped",
+      _0: "ReventlessActiveRoleStore-eu-west-1_CQTwafSeX"
+    });
+  });
+  globalThis.test("two deployments on one provider cannot choose different stores", () => {
+    globalThis.expect(Auth_ActiveRoleStore$ReventlessAws.chooseStore("eu-west-1_Shared")).toEqual(Auth_ActiveRoleStore$ReventlessAws.chooseStore("eu-west-1_Shared"));
+  });
+});
+
+globalThis.describe("Auth_ActiveRoleStore_Ops.appClientId", () => {
+  globalThis.test("the app client the authorizer resolved is the one used", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Ops$ReventlessAws.appClientId({
+      sub: "sub-1",
+      clientId: "7cl13nt"
+    })).toEqual("7cl13nt");
+  });
+  globalThis.test("an absent client id yields nothing to key a row on", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Ops$ReventlessAws.appClientId({
+      sub: "sub-1"
+    })).toEqual(undefined);
+  });
+  globalThis.test("an explicitly null client id is not a client id", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Ops$ReventlessAws.appClientId({
+      sub: "sub-1",
+      clientId: null
+    })).toEqual(undefined);
+  });
+  globalThis.test("a blank client id is not a client id either", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Ops$ReventlessAws.appClientId({
+      sub: "sub-1",
+      clientId: "   "
+    })).toEqual(undefined);
+  });
+  globalThis.test("the subject is never substituted for the app client", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Ops$ReventlessAws.appClientId({
+      sub: "sub-1",
+      clientId: null
+    })).toEqual(undefined);
+  });
+});
+
 let Ops;
 
 let Contract;

package/tests/Auth_ActiveRoleStore_SchemaTest.res

@@ -0,0 +1,98 @@
+open JestGlobals
+
+// The store's identity — its name and its key — is shared by four things that
+// cannot see each other: the deploy, the write door, the pre-token trigger, and
+// the provisioning script an operator runs by hand. Any two of them disagreeing
+// produces one symptom, and it is the symptom this whole area exists to end: a
+// row written where nothing looks for it, so a role switch reports success and
+// changes nothing.
+//
+// These assert the contract itself rather than any one consumer's use of it.
+
+module Schema = Auth_ActiveRoleStore_Schema
+
+describe("Auth_ActiveRoleStore_Schema.derivedStoreName", () => {
+  testSync("names the store after the provider whose trigger reads it", () =>
+    expect(Schema.derivedStoreName(~identityProviderId="eu-west-1_CQTwafSeX"))->toBe(
+      "ReventlessActiveRoleStore-eu-west-1_CQTwafSeX",
+    )
+  )
+
+  // The property the whole design turns on: two platforms on one provider cannot
+  // name different stores, so the defect stops being something to detect and
+  // becomes something that cannot be expressed.
+  testSync("two deployments on one provider derive the same store", () =>
+    expect(Schema.derivedStoreName(~identityProviderId="eu-west-1_Shared"))->toBe(
+      Schema.derivedStoreName(~identityProviderId="eu-west-1_Shared"),
+    )
+  )
+
+  testSync("different providers do not collide", () =>
+    expect(
+      Schema.derivedStoreName(~identityProviderId="eu-west-1_A") ==
+        Schema.derivedStoreName(~identityProviderId="eu-west-1_B"),
+    )->toBe(false)
+  )
+
+  // A pool id carries an underscore and a hyphen; DynamoDB accepts both, and a
+  // name that needed escaping would make the script and the deploy disagree about
+  // what "the same name" is.
+  testSync("the derived name is a legal DynamoDB table name", () => {
+    let name = Schema.derivedStoreName(~identityProviderId="eu-west-1_CQTwafSeX")
+    expect((
+      RegExp.test(RegExp.fromString("^[A-Za-z0-9_.-]+$"), name),
+      name->String.length >= 3 && name->String.length <= 255,
+    ))->toEqual((true, true))
+  })
+})
+
+describe("Auth_ActiveRoleStore_Schema.keySchemaRefusal", () => {
+  let store = "ReventlessActiveRoleStore-eu-west-1_x"
+
+  testSync("the expected pair is adopted without complaint", () =>
+    expect(
+      Schema.keySchemaRefusal(~tableName=store, ~actual=[("id", "HASH"), ("clientId", "RANGE")]),
+    )->toEqual(None)
+  )
+
+  // DescribeTable promises no ordering, and a refusal that depended on one would
+  // reject a table that is perfectly correct.
+  testSync("order is not part of the comparison", () =>
+    expect(
+      Schema.keySchemaRefusal(~tableName=store, ~actual=[("clientId", "RANGE"), ("id", "HASH")]),
+    )->toEqual(None)
+  )
+
+  // 🚨 The upgrade case. A store keyed on the subject alone is what every
+  // deployment had before the active role became per-platform, and adopting it
+  // silently would write rows under a two-part key that nothing reads.
+  testSync("the pre-clientId store is refused rather than adopted", () =>
+    expect(
+      Schema.keySchemaRefusal(~tableName=store, ~actual=[("id", "HASH")])->Option.isSome,
+    )->toBe(true)
+  )
+
+  testSync("the refusal names the table, what it found, and what is needed", () => {
+    let message = Schema.keySchemaRefusal(~tableName=store, ~actual=[("id", "HASH")])->Option.getOr("")
+    expect((
+      message->String.includes(store),
+      message->String.includes("id:HASH"),
+      message->String.includes("clientId:RANGE"),
+    ))->toEqual((true, true, true))
+  })
+
+  testSync("a table keyed on something else entirely is refused", () =>
+    expect(
+      Schema.keySchemaRefusal(
+        ~tableName=store,
+        ~actual=[("pk", "HASH"), ("sk", "RANGE")],
+      )->Option.isSome,
+    )->toBe(true)
+  )
+
+  // Not a table anyone would build on purpose — but `DescribeTable`'s KeySchema is
+  // optional in the SDK's types, and the caller resolves an absent one to this.
+  testSync("an empty key schema is refused, not treated as a match", () =>
+    expect(Schema.keySchemaRefusal(~tableName=store, ~actual=[])->Option.isSome)->toBe(true)
+  )
+})

package/tests/Auth_ActiveRoleStore_SchemaTest.res.mjs

@@ -0,0 +1,97 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Auth_ActiveRoleStore_Schema$ReventlessAws from "../src/adapter/Auth/Auth_ActiveRoleStore_Schema.res.mjs";
+
+globalThis.describe("Auth_ActiveRoleStore_Schema.derivedStoreName", () => {
+  globalThis.test("names the store after the provider whose trigger reads it", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Schema$ReventlessAws.derivedStoreName("eu-west-1_CQTwafSeX")).toBe("ReventlessActiveRoleStore-eu-west-1_CQTwafSeX");
+  });
+  globalThis.test("two deployments on one provider derive the same store", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Schema$ReventlessAws.derivedStoreName("eu-west-1_Shared")).toBe(Auth_ActiveRoleStore_Schema$ReventlessAws.derivedStoreName("eu-west-1_Shared"));
+  });
+  globalThis.test("different providers do not collide", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Schema$ReventlessAws.derivedStoreName("eu-west-1_A") === Auth_ActiveRoleStore_Schema$ReventlessAws.derivedStoreName("eu-west-1_B")).toBe(false);
+  });
+  globalThis.test("the derived name is a legal DynamoDB table name", () => {
+    let name = Auth_ActiveRoleStore_Schema$ReventlessAws.derivedStoreName("eu-west-1_CQTwafSeX");
+    globalThis.expect([
+      new RegExp("^[A-Za-z0-9_.-]+$").test(name),
+      name.length >= 3 && name.length <= 255
+    ]).toEqual([
+      true,
+      true
+    ]);
+  });
+});
+
+globalThis.describe("Auth_ActiveRoleStore_Schema.keySchemaRefusal", () => {
+  let store = "ReventlessActiveRoleStore-eu-west-1_x";
+  globalThis.test("the expected pair is adopted without complaint", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Schema$ReventlessAws.keySchemaRefusal(store, [
+      [
+        "id",
+        "HASH"
+      ],
+      [
+        "clientId",
+        "RANGE"
+      ]
+    ])).toEqual(undefined);
+  });
+  globalThis.test("order is not part of the comparison", () => {
+    globalThis.expect(Auth_ActiveRoleStore_Schema$ReventlessAws.keySchemaRefusal(store, [
+      [
+        "clientId",
+        "RANGE"
+      ],
+      [
+        "id",
+        "HASH"
+      ]
+    ])).toEqual(undefined);
+  });
+  globalThis.test("the pre-clientId store is refused rather than adopted", () => {
+    globalThis.expect(Stdlib_Option.isSome(Auth_ActiveRoleStore_Schema$ReventlessAws.keySchemaRefusal(store, [[
+        "id",
+        "HASH"
+      ]]))).toBe(true);
+  });
+  globalThis.test("the refusal names the table, what it found, and what is needed", () => {
+    let message = Stdlib_Option.getOr(Auth_ActiveRoleStore_Schema$ReventlessAws.keySchemaRefusal(store, [[
+        "id",
+        "HASH"
+      ]]), "");
+    globalThis.expect([
+      message.includes(store),
+      message.includes("id:HASH"),
+      message.includes("clientId:RANGE")
+    ]).toEqual([
+      true,
+      true,
+      true
+    ]);
+  });
+  globalThis.test("a table keyed on something else entirely is refused", () => {
+    globalThis.expect(Stdlib_Option.isSome(Auth_ActiveRoleStore_Schema$ReventlessAws.keySchemaRefusal(store, [
+      [
+        "pk",
+        "HASH"
+      ],
+      [
+        "sk",
+        "RANGE"
+      ]
+    ]))).toBe(true);
+  });
+  globalThis.test("an empty key schema is refused, not treated as a match", () => {
+    globalThis.expect(Stdlib_Option.isSome(Auth_ActiveRoleStore_Schema$ReventlessAws.keySchemaRefusal(store, []))).toBe(true);
+  });
+});
+
+let Schema;
+
+export {
+  Schema,
+}
+/*  Not a pure module */

package/tests/AwsErrorFixtures.mjs

@@ -0,0 +1,16 @@
+// Throws the shape an AWS SDK v3 client actually throws, so a test catches it
+// through the same path the real code does.
+//
+// It has to *throw* rather than return: ReScript's `exn` for a JS error is the
+// wrapper its own catch builds, not the bare `Error` object. A fixture that
+// returned one would be a different value than any real call produces, and a test
+// built on it would prove nothing about the code that catches them.
+//
+// Here rather than in a `%raw` inside the test, per the repo convention that
+// untyped reflection lives in a companion `.mjs` bound through `@module`.
+
+export const throwAwsError = (name, message) => {
+  const error = new Error(message)
+  error.name = name
+  throw error
+}

package/tests/ProvisionIdentityTest.res

@@ -0,0 +1,109 @@
+open JestGlobals
+
+// Argument handling for the operator script. Testable at all only because the
+// module no longer calls `main` at the top level — `run-provision-identity.mjs`
+// does. While it ran itself on import, nothing in here could be reached, and
+// that is how a guard that could never match shipped in the same file.
+//
+// What these cover is the one thing this script does that is hard to undo:
+// deciding whether to *adopt* a user pool or *create* one.
+
+module Provision = ProvisionIdentity
+
+describe("ProvisionIdentity.parseArgs", () => {
+  testSync("no arguments means adopt-or-create the default name", () =>
+    expect(Provision.parseArgs([]))->toEqual(
+      Ok({
+        Provision.poolName: Provision.defaultPoolName,
+        providerId: None,
+        help: false,
+      }),
+    )
+  )
+
+  testSync("--provider-id names an existing pool", () =>
+    expect(Provision.parseArgs(["--provider-id", "eu-west-1_AbCdEfGhI"]))->toEqual(
+      Ok({
+        Provision.poolName: Provision.defaultPoolName,
+        providerId: Some("eu-west-1_AbCdEfGhI"),
+        help: false,
+      }),
+    )
+  )
+
+  testSync("--name selects which pool to adopt by name", () =>
+    expect(Provision.parseArgs(["--name", "examples-dev"]))->toEqual(
+      Ok({Provision.poolName: "examples-dev", providerId: None, help: false}),
+    )
+  )
+
+  testSync("both together are accepted, and the id wins at resolve time", () =>
+    expect(Provision.parseArgs(["--name", "ignored", "--provider-id", "eu-west-1_x"]))->toEqual(
+      Ok({Provision.poolName: "ignored", providerId: Some("eu-west-1_x"), help: false}),
+    )
+  )
+
+  // 🚨 The reason unknown flags are refused rather than skipped. A misspelled
+  // `--provider-id` that parsed as "absent" would silently take the *create* path
+  // and stand up a second user pool beside the one the operator meant to extend.
+  testSync("a misspelled flag is refused, not ignored", () =>
+    expect(Provision.parseArgs(["--provider_id", "eu-west-1_x"]))->toEqual(
+      Error(`unknown argument "--provider_id"`),
+    )
+  )
+
+  // Same hazard from the other direction: a flag whose value was left off must
+  // not read as "no id given".
+  testSync("a flag with no value is refused", () =>
+    expect(Provision.parseArgs(["--provider-id"]))->toEqual(
+      Error("--provider-id needs a value"),
+    )
+  )
+
+  testSync("--name with no value is refused too", () =>
+    expect(Provision.parseArgs(["--name"]))->toEqual(Error("--name needs a value"))
+  )
+
+  testSync("--help and -h both ask for the usage text", () =>
+    expect((
+      Provision.parseArgs(["--help"])->Result.map(a => a.help),
+      Provision.parseArgs(["-h"])->Result.map(a => a.help),
+    ))->toEqual((Ok(true), Ok(true)))
+  )
+
+  // The first error stops the scan rather than the last one winning: an operator
+  // fixing what they are told about should not then meet a second surprise.
+  testSync("the first refusal is the one reported", () =>
+    expect(Provision.parseArgs(["--nope", "--also-nope"]))->toEqual(
+      Error(`unknown argument "--nope"`),
+    )
+  )
+})
+
+// The pool this script creates when it creates one. Asserted because a pool is
+// the one thing here that outlives every stack — nothing in a `pulumi destroy`
+// touches it — so its settings are not a detail an operator can revise cheaply
+// once accounts exist in it.
+describe("ProvisionIdentity.poolSettings", () => {
+  let settings = Provision.poolSettings(~poolName="MyIdentity")
+
+  testSync("carries the name it was asked for", () =>
+    expect(settings.poolName)->toBe("MyIdentity")
+  )
+
+  testSync("matches what auto mode declares: email sign-in, no MFA, admin-only", () =>
+    expect((
+      settings.usernameAttributes,
+      settings.mfaConfiguration,
+      settings.adminCreateUserConfig->Option.flatMap(c => c.allowAdminCreateUserOnly),
+    ))->toEqual((Some(["email"]), Some("OFF"), Some(true)))
+  )
+
+  testSync("keeps the 12-character password policy", () =>
+    expect(
+      settings.policies
+      ->Option.flatMap(p => p.passwordPolicy)
+      ->Option.flatMap(p => p.minimumLength),
+    )->toEqual(Some(12))
+  )
+})