feat(bb-auth-cognito): opt-in auth.admin handle (group + user-lifecycle admin) (#38)

Co-authored-by: Harshdeep Singh <harsh62@users.noreply.github.com>

Author: harsh62

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

@@ -0,0 +1,24 @@
+---
+"@aws-blocks/bb-auth-cognito": patch
+---
+
+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 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`.
+
+Note: `const O` narrows the params of `requireRole`, `updateUserAttribute`, and `updateMFAPreference` for inline-literal options. Callers passing widened `string` variables to these may need a cast or literal arguments.

.changeset/bb-agent-api-report-sync.md

@@ -0,0 +1,5 @@
+---
+"@aws-blocks/bb-agent": patch
+---
+
+Regenerate the API report to match the current `BedrockModels` source (the committed `API.md` had drifted from the model-id constants). No source or runtime change.

.changeset/blocks-admin-types-reexport.md

@@ -0,0 +1,5 @@
+---
+"@aws-blocks/blocks": patch
+---
+
+Re-export the `auth.admin` types (`AdminOptions`, `AdminUser`, `AdminCreateInit`, `GroupAdmin`, `LifecycleAdmin`, `AdminSurface`, `AdminGetterOf`, `AdminDisabled`) from the umbrella package so consumers using `@aws-blocks/blocks` can name the values `auth.admin` returns and annotate `admin` options.

docs/tech-design/BB-auth-cognito-admin-implementation-plan.md

@@ -0,0 +1,11 @@
+# BB: AuthCognitoAdmin — SUPERSEDED
+
+> **⚠️ SUPERSEDED.** The original design proposed a separate `@aws-blocks/bb-auth-cognito-admin` package. We instead ship the admin surface as an **opt-in `auth.admin` handle** on the existing `AuthCognito` class.
+>
+> The authoritative design and implementation plan is **[BB-auth-cognito-admin-implementation-plan.md](./BB-auth-cognito-admin-implementation-plan.md)**. For the shipped API and usage, see the [`bb-auth-cognito` README](../../packages/bb-auth-cognito/README.md) (*Admin surface*) and [DESIGN.md](../../packages/bb-auth-cognito/DESIGN.md).
+
+## Why the direction changed
+
+The separate-package design carried a second construct, a `/internal` subpath for sharing mock state across instances, and cross-construct wiring — all to preserve an admin/client separation that, on the shared backend-Lambda model, is enforced by API surface + lint rather than IAM anyway. The in-package handle preserves that same separation (plus a compile-time opt-in gate) at a fraction of the cost. The full trade study, type-safety analysis (including the `AuthCognito<O>` variance constraint that makes `admin.actions` scope the IAM grant rather than the typed method set), task list, and verification plan live in the implementation-plan doc.
+
+The original 755-line design doc (API surface, error model, mock-parity research) was retired here to avoid drift: its code snippets predated the rebrand and its package/wiring model no longer matches shipped code. Its still-relevant content was folded into the implementation plan and the package README/DESIGN.

docs/tech-design/BB-auth-cognito-admin.md

@@ -12,6 +12,65 @@ import type { ChildLogger } from '@aws-blocks/bb-logger';
 import { Scope } from '@aws-blocks/core';
 import type { ScopeParent } from '@aws-blocks/core';
 
+// @public
+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;
+}
+
+// @public
+export type AdminDisabled = {
+    readonly __adminNotEnabled: 'construct AuthCognito with { admin: {} }';
+};
+
+// @public
+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 AdminAction[];
+}
+
+// @public
+export type AdminSurface<O extends AuthCognitoOptions = AuthCognitoOptions> = GroupAdmin<O> & LifecycleAdmin<O>;
+
+// @public
+export interface AdminUser<O extends AuthCognitoOptions = AuthCognitoOptions> {
+    // (undocumented)
+    attributes: Partial<Record<ReadAttrOf<O>, string>>;
+    // (undocumented)
+    enabled: boolean;
+    // (undocumented)
+    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
@@ -20,8 +79,9 @@ export type AttrOf<O extends AuthCognitoOptions> = O extends {
 } ? StandardUserAttributeKey | CustomAttrNames<O> | `custom:${CustomAttrNames<O>}` : string;
 
 // @public
-export class AuthCognito<O extends AuthCognitoMockOptions = AuthCognitoMockOptions> extends Scope implements BlocksAuth {
+export class AuthCognito<const O extends AuthCognitoMockOptions = AuthCognitoMockOptions> extends Scope implements BlocksAuth {
     constructor(scope: ScopeParent, id: string, options?: O);
+    get admin(): AdminGetterOf<O>;
     autoSignIn(context: BlocksContext): Promise<SignInResult<O>>;
     checkAuth(context: BlocksContext): Promise<boolean>;
     completePasskeyRegistration(context: BlocksContext, credential: string): Promise<CompletePasskeyRegistrationResult>;
@@ -114,6 +174,7 @@ export interface AuthCognitoMockOptions extends AuthCognitoOptions {
 
 // @public
 export interface AuthCognitoOptions {
+    admin?: AdminOptions;
     authFlowType?: AuthFlowType;
     crossDomain?: boolean;
     deviceTracking?: {
@@ -270,6 +331,18 @@ export interface FetchAuthSessionOptions {
     forceRefresh?: boolean;
 }
 
+// @public
+export interface GroupAdmin<O extends AuthCognitoOptions = AuthCognitoOptions> {
+    // (undocumented)
+    addUserToGroup(username: string, group: GroupOf<O>, ...gate: AdminActionGate<O, 'groups'>): Promise<void>;
+    // (undocumented)
+    listGroupsForUser(username: string, ...gate: AdminActionGate<O, 'groups'>): Promise<GroupOf<O>[]>;
+    // (undocumented)
+    listUsersInGroup(group: GroupOf<O>, ...gate: AdminActionGate<O, 'groups'>): Promise<AdminUser<O>[]>;
+    // (undocumented)
+    removeUserFromGroup(username: string, group: GroupOf<O>, ...gate: AdminActionGate<O, 'groups'>): Promise<void>;
+}
+
 // @public
 export type GroupOf<O extends AuthCognitoOptions> = O extends {
     groups: readonly [unknown, ...unknown[]];
@@ -292,6 +365,28 @@ export interface JWT {
     toString(): string;
 }
 
+// @public
+export interface LifecycleAdmin<O extends AuthCognitoOptions = AuthCognitoOptions> {
+    // (undocumented)
+    createUser(username: string, init?: AdminCreateInit<O>, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<AdminUser<O>>;
+    // (undocumented)
+    deleteUser(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
+    // (undocumented)
+    disableUser(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
+    // (undocumented)
+    enableUser(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
+    // (undocumented)
+    getUser(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<AdminUser<O> | null>;
+    // (undocumented)
+    resetUserPassword(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
+    // (undocumented)
+    revokeUserSessions(username: string, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
+    // (undocumented)
+    scan(filter?: AdminUserFilter, ...gate: AdminActionGate<O, 'lifecycle'>): AsyncIterable<AdminUser<O>>;
+    // (undocumented)
+    setUserPassword(username: string, password: string, options?: SetPasswordOptions, ...gate: AdminActionGate<O, 'lifecycle'>): Promise<void>;
+}
+
 // @public
 export function makeExternalUserPoolRef(userPoolId: string, clientId?: string): ExternalUserPoolRef;
 
@@ -376,12 +471,18 @@ export interface SessionRecord {
 export class SessionStore {
     constructor(scope: ScopeParent, id?: string);
     createSession(record: SessionRecord): Promise<string>;
+    deleteByUsername(username: string): Promise<number>;
     deleteSession(sessionId: string): Promise<void>;
     lookupSession(sessionId: string): Promise<SessionRecord | null>;
     // (undocumented)
     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/API.md

@@ -18,10 +18,10 @@ Design document. For usage, see [README.md](./README.md).
 - Device tracking (list, forget).
 - Password reset via verification code.
 - Provider-agnostic state machine driving the same `<Authenticator>` UI as every other Blocks auth BB.
+- **Admin user-lifecycle + group-membership APIs** (`createUser`, `deleteUser`, `addUserToGroup`, `listUsersInGroup`, etc.) — exposed as an **opt-in `auth.admin` handle** on this class, gated by the `admin` options object. Off by default (no handle, no `Admin*` IAM). See *Admin surface* below and [BB-auth-cognito-admin-implementation-plan.md](../../docs/tech-design/BB-auth-cognito-admin-implementation-plan.md) for the rationale.
 
 **Out (for this BB):**
 
-- **Admin user-lifecycle APIs** (`createUser`, `deleteUser`, `addUserToGroup`, `listUsers`, etc.) — deliberately excluded. Those operate on *any* user and can't self-gate from a `context`, so they don't belong on the same class that exposes `signIn`/`signUp`. They are provided by a separate admin Building Block.
 - **HostedUI + federated sign-in** (Google / Facebook / LoginWithAmazon / Apple / OIDC / SAML) — not supported.
 - **Cognito Lambda triggers** (`preSignUp`, `postConfirmation`, `preAuthentication`, …) — customers who need them can attach against the underlying `userPool` construct directly.
 - **Auth flows other than `USER_PASSWORD_AUTH`** — widened typing only.
@@ -47,7 +47,7 @@ Creates under the construct's scope:
 - **Nested `AppSetting(this, 'session-secret', { secret: true })`** — SSM SecureString HMAC for signing session-ID cookies. `AppSetting` handles the custom-resource wiring (CF can't create SecureString natively) and grants `ssm:GetParameter` + `kms:Decrypt` to `this.handler` automatically. Both the CDK layer and AWS runtime instantiate an `AppSetting` at the same scope path, so each side derives the same SSM parameter name without a dedicated env var.
 - **Nested `KVStore(this, 'sessions', { removalPolicy })`** — DynamoDB table holding server-side session records.
 
-The Lambda handler receives env vars `BLOCKS_AUTH_COGNITO_<UPPER_FULLID>_{USER_POOL_ID, CLIENT_ID, REGION}` so the AWS runtime can discover the pool/client IDs without CfnOutput round-trips. IAM grants are a **single** policy statement scoped to the pool ARN — the 17 client-facing Cognito actions (sign-up, sign-in, MFA, devices, self-service password/attribute mutations, `GlobalSignOut`). No `cognito-idp:Admin*` or `cognito-idp:List*` actions are granted; those belong to a separate admin Building Block.
+The Lambda handler receives env vars `BLOCKS_AUTH_COGNITO_<UPPER_FULLID>_{USER_POOL_ID, CLIENT_ID, REGION}` so the AWS runtime can discover the pool/client IDs without CfnOutput round-trips. IAM grants are scoped to the pool ARN: a base policy statement covering the 17 client-facing Cognito actions (sign-up, sign-in, MFA, devices, self-service password/attribute mutations, `GlobalSignOut`) is always attached. `cognito-idp:Admin*` / `cognito-idp:List*` actions are granted **only** when the `admin` option is set — a second statement whose action set is scoped by `admin.actions` (`'groups'` and/or `'lifecycle'`). Omit `admin` and the synthesized role is byte-identical to the client-only grant (least privilege by default). See *Admin surface*.
 
 `userPoolName` is `this.fullId`; the construct throws at synth time if the ID exceeds Cognito's 128-char limit.
 
@@ -81,6 +81,15 @@ Everything else (`username`, `userSub`, `groups`, `attributes`) is derived on re
 
 **Challenge envelopes.** The challenge token returned by `signIn` on MFA / `NEW_PASSWORD_REQUIRED` is a small HMAC-signed envelope the client echoes back in `confirmSignIn`. Cognito's raw session token never reaches the browser; the envelope carries enough state to reconstruct `ChallengeResponses` on the server.
 
+## Admin surface (`auth.admin`)
+
+Server-side group-membership and user-lifecycle administration is exposed as an **opt-in handle on this class**, not a separate Building Block. Enable it by passing an `admin` options object; the handle grants the matching `Admin*` / `List*` IAM (scoped by `admin.actions`). This keeps the admin/client API distinction structural while avoiding a second package, its `/internal` mock-state-sharing port, and cross-construct wiring — the handle mutates the same live `state`/pool the client methods use. See [BB-auth-cognito-admin-implementation-plan.md](../../docs/tech-design/BB-auth-cognito-admin-implementation-plan.md) for the full rationale and the package-vs-handle trade study.
+
+- **Compile-time gate.** The getter's type is `AdminGetterOf<O> = O extends { admin: object } ? AdminSurface<O> : AdminDisabled`. Without an `admin` object, `auth.admin` is `AdminDisabled` and any access is a compile error whose message names the fix; the getter also throws at runtime for untyped JS callers. Group names on the methods narrow via `GroupOf<O>`.
+- **`actions` scopes both the IAM grant and the compile-time method surface.** Each method on `GroupAdmin<O>` / `LifecycleAdmin<O>` carries a trailing `...gate: AdminActionGate<O, A>` parameter: when `actions` grants action group `A` the gate is an empty tuple (callable normally), otherwise it demands an extra `never` argument, so an ungranted call is a **compile error**. Crucially the gate lives in a *parameter* position, not a conditional over the surface *shape* — so it does **not** make `AuthCognito<O>` invariant (a shape-narrowing conditional over `O` did, breaking assignability across the codebase — verified). `actions` therefore scopes both the CDK grant and the typed surface. Untyped JS callers that reach past the gate additionally fast-fail at runtime with a clear error.
+- **Not an access boundary.** Like every block on the shared backend Lambda, client and admin run under one role; separation is by API surface + lint, not IAM. Gate every admin route behind `requireRole`.
+- **Session freshness.** `revokeUserSessions` revokes Cognito refresh tokens (AWS: `AdminUserGlobalSignOut`; mock: deletes session records). On AWS an already-issued access token stays valid until it expires, so `checkAuth` does not flip immediately — a known mock-vs-AWS parity difference. Group changes likewise apply on the next sign-in / `fetchAuthSession({ forceRefresh: true })`, not to a live session.
+
 ## Options Split: `AuthCognitoOptions` vs `AuthCognitoMockOptions`
 
 `AuthCognitoOptions` is the cross-runtime option type — CDK, AWS, and mock all accept it. The mock entry accepts a widened type:
@@ -134,3 +143,4 @@ Resolved by the MFA_SETUP + USER_AUTH work:
 4. **Mock + AWS runtimes share the session/cookie code path.** `SessionStore`, cookie helpers, JWT decode — all shared. The only divergence is that mock issues placeholder-signature JWTs and never talks to Cognito.
 5. **Error constants mirror Cognito's wire-format exception names.** Every value equals the name Cognito puts on the wire, so `isBlocksError(e, AuthCognitoErrors.X)` works identically for errors thrown by the mock (matched name directly) and errors propagated from the AWS SDK (name preserved when re-thrown as `ApiError`).
 6. **`GroupNotFound` maps to `ResourceNotFoundException`.** Real Cognito returns `ResourceNotFoundException` (not the intuitive `GroupNotFoundException`) for a missing group. The constant name preserves the semantic label while the value matches what Cognito actually returns.
+7. **Admin surface as an opt-in `auth.admin` handle, not a separate Building Block.** The admin/client distinction is preserved by the handle (and the `admin` opt-in gate) rather than by a second package. This removes a whole package, an `/internal` subpath for sharing mock state, and cross-construct wiring, at the cost of independent versioning (not needed). `admin.actions` scopes both the IAM grant and the compile-time method surface via a parameter-position `AdminActionGate` (ungranted calls are compile errors); the gate is a method *parameter* rather than a conditional over the surface shape, so `AuthCognito<O>` stays covariant in `O`. Full trade study in [BB-auth-cognito-admin-implementation-plan.md](../../docs/tech-design/BB-auth-cognito-admin-implementation-plan.md).