feat(bb-auth-cognito): close auth.admin type-safety & ergonomics gaps

Addresses reviewer-identified gaps in the admin surface:

- Gap 1 (typed reads): AdminUser is now AdminUser<O> — getUser/scan/listUsersInGroup
  return narrowed groups (GroupOf<O>) and attributes (ReadAttrOf<O>), matching the
  client-side CognitoUser. createUser attributes narrow via AttrOf<O> too, catching
  typos the way signUp does.
- Gap 3 (ungranted-action feedback): a new AdminActionGate rest-param makes calling
  an ungranted method (e.g. deleteUser under actions:['groups']) a COMPILE error —
  variance-safe because the gate is in parameter position, not the surface shape
  (verified against the call sites the earlier shape-narrowing attempt regressed).
  A runtime guard also fast-fails with a clear message instead of AWS AccessDenied.
- Gap 4 (scan filter): scan(filter?) accepts an AdminUserFilter mapped to Cognito's
  ListUsers Filter (startsWith/equals); mock filters in memory.
- Gap 5 (readability): setUserPassword(username, password, { permanent }) uses a
  named options object instead of a bare boolean.

Umbrella @aws-blocks/blocks re-exports the new public types. API reports + changeset
updated. Package suite: 228 pass, 0 fail; full type-test incl. gate + variance guard.

Author: harsh62

.changeset/auth-cognito-admin-handle.md

@@ -4,13 +4,21 @@
 
 Add an opt-in `auth.admin` handle to `AuthCognito` for server-side group-membership and user-lifecycle administration.
 
-Enable it by passing an `admin` options object; `admin.actions` scopes the granted `Admin*` / `List*` IAM. Without it, `auth.admin` is a compile error and no admin IAM is granted (unchanged default). Group names on the admin methods narrow via `GroupOf<O>`.
+Enable it by passing an `admin` options object; `admin.actions` scopes both the granted `Admin*` / `List*` IAM **and** the compile-time method surface. Without it, `auth.admin` is a compile error and no admin IAM is granted (unchanged default).
 
 ```ts
 const auth = new AuthCognito(scope, 'auth', { groups: ['admins'], admin: { actions: ['groups'] } });
 await auth.admin.addUserToGroup('alice', 'admins');
 ```
 
+The admin surface is fully typed by the pool config `O`:
+
+- **Action gating:** calling a method whose action group wasn't granted (e.g. `deleteUser` under `actions: ['groups']`) is a compile error, and fast-fails at runtime with a clear message instead of a cryptic AWS `AccessDenied`.
+- **Typed reads:** `getUser` / `scan` / `listUsersInGroup` return `AdminUser<O>` — `groups` narrows to the configured group union and `attributes` keys to the declared attributes, matching the client-side `CognitoUser`.
+- **Typed writes:** `createUser`'s `attributes` narrow to the declared keys (catches typos like `signUp` does).
+- **`scan(filter?)`** accepts a server-side `AdminUserFilter` mapped to Cognito's `ListUsers` `Filter`.
+- **`setUserPassword(username, password, { permanent })`** takes a named options object instead of a bare boolean.
+
 The `AuthCognito` class generic is now a `const` type parameter, so inline options literals narrow without `as const`.
 
 BREAKING CHANGE: `const O` narrows the params of `requireRole`, `updateUserAttribute`, and `updateMFAPreference` for inline-literal options. Callers passing widened `string` variables to these now need a cast or literal arguments.

packages/bb-auth-cognito/API.md

@@ -13,8 +13,14 @@ import { Scope } from '@aws-blocks/core';
 import type { ScopeParent } from '@aws-blocks/core';
 
 // @public
-export interface AdminCreateInit {
-    attributes?: Record<string, string>;
+export type AdminAction = 'groups' | 'lifecycle';
+
+// @public
+export type AdminActionGate<O extends AuthCognitoOptions, A extends AdminAction> = AdminGrants<O, A> extends true ? [] : [ERROR_admin_action_not_granted: never];
+
+// @public
+export interface AdminCreateInit<O extends AuthCognitoOptions = AuthCognitoOptions> {
+    attributes?: Partial<Record<AttrOf<O>, string>>;
     suppressInvite?: boolean;
     temporaryPassword?: string;
 }
@@ -29,28 +35,42 @@ export type AdminGetterOf<O extends AuthCognitoOptions> = O extends {
     admin: object;
 } ? AdminSurface<O> : AdminDisabled;
 
+// @public
+export type AdminGrants<O extends AuthCognitoOptions, A extends AdminAction> = O extends {
+    admin: {
+        actions: infer L extends readonly string[];
+    };
+} ? (A extends L[number] ? true : false) : true;
+
 // @public
 export interface AdminOptions {
-    actions?: readonly ('groups' | 'lifecycle')[];
+    actions?: readonly AdminAction[];
 }
 
 // @public
 export type AdminSurface<O extends AuthCognitoOptions = AuthCognitoOptions> = GroupAdmin<O> & LifecycleAdmin<O>;
 
 // @public
-export interface AdminUser {
+export interface AdminUser<O extends AuthCognitoOptions = AuthCognitoOptions> {
     // (undocumented)
-    attributes: Record<string, string>;
+    attributes: Partial<Record<ReadAttrOf<O>, string>>;
     // (undocumented)
     enabled: boolean;
     // (undocumented)
-    groups?: string[];
+    groups?: GroupOf<O>[];
     // (undocumented)
     username: string;
     // (undocumented)
     userSub: string;
 }
 
+// @public
+export interface AdminUserFilter {
+    attribute: string;
+    match: 'startsWith' | 'equals';
+    value: string;
+}
+
 // Warning: (ae-incompatible-release-tags) The symbol "AttrOf" is marked as @public, but its signature references "CustomAttrNames" which is marked as @internal
 //
 // @public
@@ -314,13 +334,13 @@ export interface FetchAuthSessionOptions {
 // @public
 export interface GroupAdmin<O extends AuthCognitoOptions = AuthCognitoOptions> {
     // (undocumented)
-    addUserToGroup(username: string, group: GroupOf<O>): Promise<void>;
+    addUserToGroup(username: string, group: GroupOf<O>, ...gate: AdminActionGate<O, 'groups'>): Promise<void>;
     // (undocumented)
-    listGroupsForUser(username: string): Promise<GroupOf<O>[]>;
+    listGroupsForUser(username: string, ...gate: AdminActionGate<O, 'groups'>): Promise<GroupOf<O>[]>;
     // (undocumented)
-    listUsersInGroup(group: GroupOf<O>): Promise<AdminUser[]>;
+    listUsersInGroup(group: GroupOf<O>, ...gate: AdminActionGate<O, 'groups'>): Promise<AdminUser<O>[]>;
     // (undocumented)
-    removeUserFromGroup(username: string, group: GroupOf<O>): Promise<void>;
+    removeUserFromGroup(username: string, group: GroupOf<O>, ...gate: AdminActionGate<O, 'groups'>): Promise<void>;
 }
 
 // @public
@@ -348,23 +368,23 @@ export interface JWT {
 // @public
 export interface LifecycleAdmin<O extends AuthCognitoOptions = AuthCognitoOptions> {
     // (undocumented)
-    createUser(username: string, init?: AdminCreateInit): Promise<AdminUser>;
+    createUser(username: string, init?: AdminCreateInit<O>, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<AdminUser<O>>;
     // (undocumented)
-    deleteUser(username: string): Promise<void>;
+    deleteUser(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
     // (undocumented)
-    disableUser(username: string): Promise<void>;
+    disableUser(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
     // (undocumented)
-    enableUser(username: string): Promise<void>;
+    enableUser(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
     // (undocumented)
-    getUser(username: string): Promise<AdminUser | null>;
+    getUser(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<AdminUser<O> | null>;
     // (undocumented)
-    resetUserPassword(username: string): Promise<void>;
+    resetUserPassword(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
     // (undocumented)
-    revokeUserSessions(username: string): Promise<void>;
+    revokeUserSessions(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
     // (undocumented)
-    scan(): AsyncIterable<AdminUser>;
+    scan(filter?: AdminUserFilter, ...gate: AdminActionGate<O, 'lifecycle'>): AsyncIterable<AdminUser<O>>;
     // (undocumented)
-    setUserPassword(username: string, password: string, permanent: boolean): Promise<void>;
+    setUserPassword(username: string, password: string, options?: SetPasswordOptions, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
 }
 
 // @public
@@ -458,6 +478,11 @@ export class SessionStore {
     updateSession(sessionId: string, update: Partial<SessionRecord>): Promise<void>;
 }
 
+// @public
+export interface SetPasswordOptions {
+    permanent?: boolean;
+}
+
 // @public
 export type SignInNextStep = {
     name: 'CONFIRM_SIGN_IN_WITH_SMS_CODE';

packages/bb-auth-cognito/src/admin.test.ts

@@ -172,7 +172,7 @@ describe('auth.admin user lifecycle', () => {
 	test('setUserPassword(permanent) lets the user sign in with the new password', async () => {
 		const auth = new AuthCognito(ROOT, unique(), { admin: {} });
 		await signUpAndConfirm(auth, 'hank');
-		await auth.admin.setUserPassword('hank', 'NewPass!2', true);
+		await auth.admin.setUserPassword('hank', 'NewPass!2', { permanent: true });
 		const r = await auth.signIn('hank', 'NewPass!2', freshContext());
 		assert.strictEqual(r.status, 'signedIn');
 	});
@@ -186,6 +186,18 @@ describe('auth.admin user lifecycle', () => {
 		assert.deepStrictEqual(seen.sort(), ['ida', 'jack']);
 	});
 
+	test('scan with a startsWith filter narrows results (Gap 4)', async () => {
+		const auth = new AuthCognito(ROOT, unique(), { admin: {} });
+		await auth.admin.createUser('alice');
+		await auth.admin.createUser('albert');
+		await auth.admin.createUser('bob');
+		const seen: string[] = [];
+		for await (const u of auth.admin.scan({ attribute: 'username', match: 'startsWith', value: 'al' })) {
+			seen.push(u.username);
+		}
+		assert.deepStrictEqual(seen.sort(), ['albert', 'alice']);
+	});
+
 	test('revokeUserSessions deletes the user session (forces re-auth)', async () => {
 		const auth = new AuthCognito(ROOT, unique(), { admin: {} });
 		await signUpAndConfirm(auth, 'kara');
@@ -197,3 +209,34 @@ describe('auth.admin user lifecycle', () => {
 		assert.strictEqual(await auth.checkAuth(ctx), false);
 	});
 });
+
+describe('auth.admin action-scope runtime gate (Gap 3)', () => {
+	test('groups-only pool fast-fails a lifecycle call with a clear error', async () => {
+		const auth = new AuthCognito(ROOT, unique(), { groups: ['admins'], admin: { actions: ['groups'] } });
+		// Cast past the compile-time gate to reach the runtime guard (an untyped
+		// JS caller would hit this path). Error must be clear, not AWS AccessDenied.
+		const admin = auth.admin as unknown as { createUser(u: string): Promise<unknown> };
+		await assert.rejects(
+			() => admin.createUser('x'),
+			(e: unknown) => isBlocksError(e, AuthCognitoErrors.NotAuthorized) && /lifecycle actions not granted/.test((e as Error).message),
+		);
+	});
+
+	test('lifecycle-only pool fast-fails a groups call', async () => {
+		const auth = new AuthCognito(ROOT, unique(), { groups: ['admins'], admin: { actions: ['lifecycle'] } });
+		const admin = auth.admin as unknown as { addUserToGroup(u: string, g: string): Promise<unknown> };
+		await assert.rejects(
+			() => admin.addUserToGroup('x', 'admins'),
+			(e: unknown) => isBlocksError(e, AuthCognitoErrors.NotAuthorized) && /groups actions not granted/.test((e as Error).message),
+		);
+	});
+
+	test('granted action + admin:{} (all) do not fast-fail', async () => {
+		const groupsOnly = new AuthCognito(ROOT, unique(), { groups: ['admins'], admin: { actions: ['groups'] } });
+		await signUpAndConfirm(groupsOnly, 'gwen');
+		await groupsOnly.admin.addUserToGroup('gwen', 'admins'); // granted → no throw
+
+		const all = new AuthCognito(ROOT, unique(), { admin: {} });
+		await all.admin.createUser('hugo'); // no actions restriction → no throw
+	});
+});

packages/bb-auth-cognito/src/admin.types-test.ts

@@ -40,20 +40,26 @@ async function fullSurface() {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// (3) `actions` scopes the IAM grant, NOT the typed method set — the full
-//     surface is present at the type level regardless of `actions`. (Narrowing
-//     the type by `actions` would force `AuthCognito<O>` invariant; see
-//     `AdminSurface` doc.) A method whose action wasn't granted fails at
-//     runtime with IAM AccessDenied, not at compile time.
+// (3) `actions` gates the methods at COMPILE TIME (via AdminActionGate rest
+//     params) as well as scoping the IAM grant — calling an ungranted method is
+//     a type error. This is variance-safe (the gate lives in a parameter
+//     position, not the surface shape); the variance guard is case (8).
 // ─────────────────────────────────────────────────────────────────────────────
-async function actionsScopeGrantNotTypes() {
+async function actionsGateMethodsAtCompileTime() {
 	const groupsScoped = new AuthCognito(scope, 'a3', { groups: ['admins'], admin: { actions: ['groups'] } });
-	await groupsScoped.admin.addUserToGroup('u', 'admins');
-	await groupsScoped.admin.createUser('u'); // present at type level (grant-scoped at runtime)
+	await groupsScoped.admin.addUserToGroup('u', 'admins'); // granted → ok
+	// @ts-expect-error — lifecycle not granted by actions: ['groups'].
+	await groupsScoped.admin.createUser('u');
 
 	const lifecycleScoped = new AuthCognito(scope, 'a4', { groups: ['admins'], admin: { actions: ['lifecycle'] } });
-	await lifecycleScoped.admin.createUser('u');
-	await lifecycleScoped.admin.addUserToGroup('u', 'admins'); // present at type level
+	await lifecycleScoped.admin.createUser('u'); // granted → ok
+	// @ts-expect-error — groups not granted by actions: ['lifecycle'].
+	await lifecycleScoped.admin.addUserToGroup('u', 'admins');
+
+	// admin: {} (no actions) grants everything — both call groups compile.
+	const all = new AuthCognito(scope, 'a3b', { groups: ['admins'], admin: {} });
+	await all.admin.addUserToGroup('u', 'admins');
+	await all.admin.createUser('u');
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -85,3 +91,60 @@ async function defaultO() {
 	// @ts-expect-error — admin disabled on the default (wide) O.
 	await auth.admin.createUser('u');
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// (8) Variance guard — an instance narrowed on groups/attributes/mfa is still
+//     assignable to the wide AuthCognito. This is the exact property the earlier
+//     shape-narrowing attempt broke (it regressed 14 call sites); the
+//     parameter-position action gate must NOT reintroduce it.
+//
+//     Note: an admin-*enabled* instance is intentionally NOT assignable to a
+//     wide instance whose O leaves admin disabled (AdminSurface vs AdminDisabled)
+//     — that is a property of the opt-in gate itself, unrelated to the action
+//     gate, and does not affect real call sites (nothing assigns an
+//     admin-enabled instance to a plain `AuthCognito`).
+// ─────────────────────────────────────────────────────────────────────────────
+function takesWide(_auth: AuthCognito) { /* no-op */ }
+function varianceGuard() {
+	takesWide(new AuthCognito(scope, 'a8a', { groups: ['admins', 'readers'] }));
+	takesWide(new AuthCognito(scope, 'a8b', { userAttributes: [{ name: 'department' }] }));
+	takesWide(new AuthCognito(scope, 'a8c', { mfa: 'optional', mfaTypes: ['TOTP'] }));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// (9) Gap 1 — admin reads are typed by O: `attributes` keys and `groups` narrow
+//     just like the client-side CognitoUser, catching typos with no autocomplete
+//     loss. (Previously AdminUser was un-parameterized: string[] / untyped bag.)
+// ─────────────────────────────────────────────────────────────────────────────
+async function typedAdminReads() {
+	const auth = new AuthCognito(scope, 'a9', {
+		groups: ['admins', 'readers'],
+		userAttributes: [{ name: 'department' }],
+		admin: {},
+	});
+	const user = await auth.admin.getUser('alice');
+	if (user) {
+		const dept: string | undefined = user.attributes['custom:department']; // declared attr → ok
+		const email: string | undefined = user.attributes['email'];            // standard attr → ok
+		void dept; void email;
+		// @ts-expect-error — 'custom:deparment' (typo) is not a known attribute key.
+		void user.attributes['custom:deparment'];
+		if (user.groups) {
+			const g: 'admins' | 'readers' = user.groups[0]; // groups narrowed to the union
+			void g;
+		}
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// (10) Gap 4 — scan accepts an optional server-side filter.
+// ─────────────────────────────────────────────────────────────────────────────
+async function scanFilter() {
+	const auth = new AuthCognito(scope, 'a10', { admin: {} });
+	for await (const u of auth.admin.scan({ attribute: 'email', match: 'startsWith', value: 'a' })) {
+		void u.username;
+	}
+	for await (const u of auth.admin.scan()) void u.username; // filter is optional
+	// @ts-expect-error — 'contains' is not a supported match mode.
+	auth.admin.scan({ attribute: 'email', match: 'contains', value: 'a' });
+}