feat(bb-auth-cognito)!: make AuthCognito generic a const type parameter

Change AuthCognito<O> to AuthCognito<const O> across all four entries so inline
options literals narrow without `as const`. This narrows five projections by
default — GroupOf (requireRole), AttrOf (updateUserAttribute family), ReadAttrOf
(fetchUserAttributes), MfaTypeOf (confirmSignIn/updateMFAPreference), and
CustomAttrNames.

Fixes the call sites that pass wire strings to now-narrowed params by casting at
the boundary (runtime validates regardless): comprehensive authCRequireRole +
authCMfaUpdateMFAPreference, native-bindings cognitoRequireRole. Tightens
admin.types-test case 5 to assert group narrowing without `as const`.

BREAKING CHANGE: callers passing widened variables to requireRole /
updateUserAttribute / updateMFAPreference now need a cast or literal args.
Acceptable pre-release.

Author: harsh62

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

@@ -57,13 +57,11 @@ async function actionsScopeGrantNotTypes() {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// (5) Group narrowing on admin methods. With `as const` (today) the group union
-//     narrows and a typo is rejected. (Task T5 — `const O` — will make this hold
-//     WITHOUT `as const`; the @ts-expect-error below is tightened to the
-//     non-const form then.)
+// (5) `const O` narrows group names on admin methods WITHOUT `as const` → typo
+//     is a compile error. (Enabled by the `const O` class generic, T5.)
 // ─────────────────────────────────────────────────────────────────────────────
 async function groupNarrowing() {
-	const auth = new AuthCognito(scope, 'a5', { groups: ['admins', 'readers'] as const, admin: { actions: ['groups'] } });
+	const auth = new AuthCognito(scope, 'a5', { groups: ['admins', 'readers'], admin: { actions: ['groups'] } });
 	await auth.admin.addUserToGroup('u', 'admins');
 	await auth.admin.addUserToGroup('u', 'readers');
 	// @ts-expect-error — 'editor' is not in 'admins' | 'readers'.

packages/bb-auth-cognito/src/index.aws.ts

@@ -601,7 +601,7 @@ function statusForCognitoError(name: string): number {
  * See the mock entry (`./index.ts`) for full class-level JSDoc; both runtimes
  * share the same public API.
  */
-export class AuthCognito<O extends AuthCognitoOptions = AuthCognitoOptions>
+export class AuthCognito<const O extends AuthCognitoOptions = AuthCognitoOptions>
 	extends Scope
 	implements BlocksAuth
 {

packages/bb-auth-cognito/src/index.browser.ts

@@ -28,7 +28,7 @@ export * from './types.js';
 // that references `AuthCognito<typeof options>` typechecks identically under
 // `--conditions=browser`. The browser stub never executes any method —
 // bundlers scan imports, they don't call anything.
-export class AuthCognito<O extends AuthCognitoOptions = AuthCognitoOptions> {
+export class AuthCognito<const O extends AuthCognitoOptions = AuthCognitoOptions> {
 	constructor(..._args: unknown[]) { /* no-op */ }
 	/**
 	 * Server-only admin surface. Present so `auth.admin` typechecks under

packages/bb-auth-cognito/src/index.cdk.ts

@@ -64,7 +64,7 @@ export * from './types.js';
  * Grants the Lambda `cognito-idp:*` scoped to this pool's ARN; the SSM
  * secret's IAM is granted by AppSetting itself.
  */
-export class AuthCognito<O extends AuthCognitoOptions = AuthCognitoOptions> extends Scope {
+export class AuthCognito<const O extends AuthCognitoOptions = AuthCognitoOptions> extends Scope {
 	public readonly userPool: cognito.IUserPool;
 	public readonly userPoolClient: cognito.IUserPoolClient;
 	private readonly sessions: KVStore;

packages/bb-auth-cognito/src/index.ts

@@ -203,7 +203,7 @@ interface PersistedState {
  * in a nested DynamoDB table provisioned by this BB via KVStore — single-
  * digit ms reads, pay-per-request billing.
  */
-export class AuthCognito<O extends AuthCognitoMockOptions = AuthCognitoMockOptions>
+export class AuthCognito<const O extends AuthCognitoMockOptions = AuthCognitoMockOptions>
 	extends Scope
 	implements BlocksAuth
 {

test-apps/comprehensive/aws-blocks/index.ts

@@ -952,7 +952,10 @@ export const api = new ApiNamespace(scope, 'api', (context) => ({
   },
 
   async authCRequireRole(role: string) {
-    const user = await authC.requireRole(context, role);
+    // Role arrives over the wire as a string; narrow to the pool's group union
+    // at the boundary (runtime validates membership regardless). `const O` made
+    // requireRole's param the literal union 'admins' | 'readers'.
+    const user = await authC.requireRole(context, role as Parameters<typeof authC.requireRole>[1]);
     return user;
   },
 
@@ -1082,7 +1085,9 @@ export const api = new ApiNamespace(scope, 'api', (context) => ({
     totp?: 'ENABLED' | 'DISABLED' | 'PREFERRED' | 'NOT_PREFERRED';
     email?: 'ENABLED' | 'DISABLED' | 'PREFERRED' | 'NOT_PREFERRED';
   }) {
-    await authCMfa.updateMFAPreference(context, input);
+    // `const O` narrowed updateMFAPreference's input to the pool's mfaTypes
+    // (here ['TOTP']); the wire shape is wider, so narrow at the boundary.
+    await authCMfa.updateMFAPreference(context, input as Parameters<typeof authCMfa.updateMFAPreference>[1]);
     return { success: true };
   },
 

test-apps/native-bindings/aws-blocks/index.ts

@@ -238,7 +238,9 @@ export const api = new ApiNamespace(scope, 'api', (context) => ({
   },
 
   async cognitoRequireRole(role: string) {
-    return await authCognito.requireRole(context, role);
+    // `const O` narrowed requireRole's param to the pool's group union; narrow
+    // the wire string at the boundary (runtime validates membership).
+    return await authCognito.requireRole(context, role as Parameters<typeof authCognito.requireRole>[1]);
   },
 
   async cognitoFetchUserAttributes() {