create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-get-user-attributes-by-user-id.md

@@ -0,0 +1,53 @@
+---
+title: askUserDirectoryGetUserAttributesByUserId
+description: Read a user's profile attributes by their userId (sub).
+---
+
+# askUserDirectoryGetUserAttributesByUserId
+
+Reads a user's profile attributes from a [user directory](../../../config/core/user-directory.md) by their `userId` (the Cognito `sub`) rather than by username. Useful when you only have the stable identifier stored on your own records.
+
+- **Action type:** `UserDirectoryActionType.GetUserAttributesByUserId`
+- **On AWS:** issues Cognito `ListUsers` filtered on the `sub` attribute.
+
+```typescript
+import { askUserDirectoryGetUserAttributesByUserId } from 'quidproquo-core';
+
+export function* askLoadProfileById(userId: string) {
+  const attributes = yield* askUserDirectoryGetUserAttributesByUserId('app-users', userId);
+  return attributes;
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryGetUserAttributesByUserId(
+  userDirectoryName: string,
+  userId: string,
+): AskResponse<UserAttributes>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `userId` | `string` | The user's unique identifier (the Cognito `sub`). |
+
+## Returns
+
+`UserAttributes` — the user's profile attributes. See [UserAttributes](./ask-user-directory-get-user-attributes.md#userattributes).
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryGetUserAttributesByUserIdErrorTypeEnum.UserNotFound` | No user matches the supplied userId (`sub`). |
+
+## Related
+
+- [askUserDirectoryGetUserAttributes](./ask-user-directory-get-user-attributes.md) — read attributes by username instead.
+- [askUserDirectorySetUserAttributes](./ask-user-directory-set-user-attributes.md) — update a user's attributes.
+- [askUserDirectoryDecodeAccessToken](./ask-user-directory-decode-access-token.md) — obtain the `userId` from an access token.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-get-user-attributes.md

@@ -0,0 +1,78 @@
+---
+title: askUserDirectoryGetUserAttributes
+description: Read a user's profile attributes by username.
+---
+
+# askUserDirectoryGetUserAttributes
+
+Reads a user's profile attributes from a [user directory](../../../config/core/user-directory.md) by username (email).
+
+- **Action type:** `UserDirectoryActionType.GetUserAttributes`
+- **On AWS:** issues Cognito `AdminGetUser`.
+
+```typescript
+import { askUserDirectoryGetUserAttributes } from 'quidproquo-core';
+
+export function* askLoadProfile(username: string) {
+  const attributes = yield* askUserDirectoryGetUserAttributes('app-users', username);
+  return attributes; // { email, givenName, familyName, ... }
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryGetUserAttributes(
+  userDirectoryName: string,
+  username: string,
+): AskResponse<UserAttributes>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `username` | `string` | The user (email) to read. |
+
+## Returns
+
+`UserAttributes` — the user's profile attributes.
+
+### `UserAttributes`
+
+All properties are optional. This is the standard attribute set shared across the User Directory actions.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `email` | `string` | The user's email address. |
+| `emailVerified` | `boolean` | Whether the email address has been verified. |
+| `userId` | `string` | The user's unique identifier (the Cognito `sub`). |
+| `address` | `string` | The user's postal address. |
+| `birthDate` | `string` | Date of birth (`YYYY-MM-DD`). |
+| `familyName` | `string` | Last name / surname. |
+| `gender` | `string` | Gender (e.g. `"male"`, `"female"`, `"other"`). |
+| `givenName` | `string` | First name / given name. |
+| `locale` | `string` | Preferred locale (e.g. `"en-US"`). |
+| `middleName` | `string` | Middle name. |
+| `name` | `string` | Full name. |
+| `nickname` | `string` | Nickname or alias. |
+| `phoneNumber` | `string` | Phone number (E.164, e.g. `"+1-555-123-4567"`). |
+| `picture` | `string` | URL of the profile picture. |
+| `preferredUsername` | `string` | Preferred username, if different from the given name. |
+| `profile` | `string` | URL of the profile page. |
+| `website` | `string` | URL of the personal website or blog. |
+| `zoneInfo` | `string` | Timezone (e.g. `"America/Los_Angeles"`). |
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryGetUserAttributesErrorTypeEnum.UserNotFound` | No user matches the supplied username. |
+
+## Related
+
+- [askUserDirectoryGetUserAttributesByUserId](./ask-user-directory-get-user-attributes-by-user-id.md) — read attributes by userId (`sub`) instead of username.
+- [askUserDirectorySetUserAttributes](./ask-user-directory-set-user-attributes.md) — update these attributes.
+- [askUserDirectoryGetUsers](./ask-user-directory-get-users.md) / [askUserDirectoryGetUsersByAttribute](./ask-user-directory-get-users-by-attribute.md) — list users.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-get-users-by-attribute.md

@@ -0,0 +1,59 @@
+---
+title: askUserDirectoryGetUsersByAttribute
+description: Find users in a directory by matching a profile attribute value.
+---
+
+# askUserDirectoryGetUsersByAttribute
+
+Finds users in a [user directory](../../../config/core/user-directory.md) whose given attribute matches a value, returning a page of results.
+
+- **Action type:** `UserDirectoryActionType.GetUsersByAttribute`
+- **On AWS:** issues Cognito `ListUsers` with a filter on the requested attribute.
+
+```typescript
+import { askUserDirectoryGetUsersByAttribute } from 'quidproquo-core';
+
+export function* askFindByEmail(email: string) {
+  const page = yield* askUserDirectoryGetUsersByAttribute('app-users', 'email', email);
+  return page.items;
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryGetUsersByAttribute(
+  userDirectoryName: string,
+  attribueName: keyof UserAttributes,
+  attribueValue: string,
+  limit?: number,
+  nextPageKey?: string,
+): AskResponse<QpqPagedData<UserAttributes>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `attribueName` | `keyof UserAttributes` | The attribute to filter on (e.g. `'email'`). Must be a searchable [UserAttributes](./ask-user-directory-get-user-attributes.md#userattributes) key. |
+| `attribueValue` | `string` | The value to match. |
+| `limit` | `number` | Optional. Maximum number of users to return in this page. |
+| `nextPageKey` | `string` | Optional. The `nextPageKey` from a previous page; omit to fetch the first page. |
+
+## Returns
+
+`QpqPagedData<UserAttributes>` — a page of matching [user attributes](./ask-user-directory-get-user-attributes.md#userattributes) plus an optional `nextPageKey`. See [QpqPagedData](./ask-user-directory-get-users.md#returns).
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryGetUsersByAttributeErrorTypeEnum.InvalidSearchParameters` | The attribute name/value, limit, or page key is invalid, or the attribute is not searchable. |
+| `UserDirectoryGetUsersByAttributeErrorTypeEnum.LimitExceeded` | The directory is throttling requests; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryGetUsers](./ask-user-directory-get-users.md) — list all users without a filter.
+- [askUserDirectoryGetUserAttributes](./ask-user-directory-get-user-attributes.md) — read a single user's attributes.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-get-users.md

@@ -0,0 +1,71 @@
+---
+title: askUserDirectoryGetUsers
+description: List users in a directory, one page at a time.
+---
+
+# askUserDirectoryGetUsers
+
+Lists the users in a [user directory](../../../config/core/user-directory.md), returning a page of attributes plus a key for fetching the next page.
+
+- **Action type:** `UserDirectoryActionType.GetUsers`
+- **On AWS:** issues Cognito `ListUsers`, paging through the pool.
+
+```typescript
+import { askUserDirectoryGetUsers } from 'quidproquo-core';
+
+export function* askListAllUsers() {
+  const users = [];
+  let nextPageKey: string | undefined = undefined;
+
+  do {
+    const page = yield* askUserDirectoryGetUsers('app-users', nextPageKey);
+    users.push(...page.items);
+    nextPageKey = page.nextPageKey;
+  } while (nextPageKey);
+
+  return users;
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryGetUsers(
+  userDirectoryName: string,
+  nextPageKey?: string,
+): AskResponse<QpqPagedData<UserAttributes>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `nextPageKey` | `string` | Optional. The `nextPageKey` from a previous page; omit to fetch the first page. |
+
+## Returns
+
+`QpqPagedData<UserAttributes>`:
+
+```typescript
+interface QpqPagedData<T> {
+  nextPageKey?: string;
+  items: T[];
+}
+```
+
+- `items` — the [user attributes](./ask-user-directory-get-user-attributes.md#userattributes) for this page.
+- `nextPageKey` — pass into the next call to continue paging; absent on the last page.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryGetUsersErrorTypeEnum.InvalidPageKey` | The supplied `nextPageKey` is malformed or no longer valid. |
+| `UserDirectoryGetUsersErrorTypeEnum.LimitExceeded` | The directory is throttling requests; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryGetUsersByAttribute](./ask-user-directory-get-users-by-attribute.md) — filter users by an attribute value.
+- [askUserDirectoryGetUserAttributes](./ask-user-directory-get-user-attributes.md) — read a single user's attributes.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-read-access-token.md

@@ -0,0 +1,52 @@
+---
+title: askUserDirectoryReadAccessToken
+description: Read and decode the access token on the current story session.
+---
+
+# askUserDirectoryReadAccessToken
+
+Reads the access token attached to the **current story session** and returns its decoded claims. On an authenticated API request the runtime puts the caller's token on the session, so this is the usual way a story learns who is making the request — no token argument needed.
+
+- **Action type:** `UserDirectoryActionType.ReadAccessToken`
+- **On AWS:** returns the session's already-decoded token when present; otherwise verifies the session's token against the pool's public JWKs over HTTPS (no Cognito API call).
+
+```typescript
+import { askUserDirectoryReadAccessToken } from 'quidproquo-core';
+
+export function* askCurrentUserId() {
+  const token = yield* askUserDirectoryReadAccessToken('app-users', false);
+  return token.userId;
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryReadAccessToken(
+  userDirectoryName: string,
+  ignoreExpiration: boolean,
+): AskResponse<DecodedAccessToken>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory the session's token belongs to — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `ignoreExpiration` | `boolean` | When `true`, an expired token is still returned rather than rejected. |
+
+## Returns
+
+`DecodedAccessToken` — the decoded claims of the session's access token. See [DecodedAccessToken](./ask-user-directory-decode-access-token.md#returns).
+
+## Notes
+
+- This reads the token from the ambient session; there is no `accessToken` parameter. To decode a token you hold yourself, use [askUserDirectoryDecodeAccessToken](./ask-user-directory-decode-access-token.md).
+- If the session carries no token, or the token is invalid/expired (and `ignoreExpiration` is `false`), the action fails — catch it with `askCatch` from quidproquo-core.
+
+## Related
+
+- [askUserDirectorySetAccessToken](./ask-user-directory-set-access-token.md) — put a token onto the session for this action to read.
+- [askUserDirectoryDecodeAccessToken](./ask-user-directory-decode-access-token.md) — decode an arbitrary token passed as an argument.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.
+- [askEventDocResolveActor](../../features/event-doc/ask-event-doc-resolve-actor.md) — resolves the event-doc acting user from the token this reads.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-refresh-token.md

@@ -0,0 +1,53 @@
+---
+title: askUserDirectoryRefreshToken
+description: Exchange a refresh token for a fresh set of access and id tokens.
+---
+
+# askUserDirectoryRefreshToken
+
+Exchanges a previously issued refresh token for a fresh set of tokens against a [user directory](../../../config/core/user-directory.md), without the user re-entering credentials.
+
+- **Action type:** `UserDirectoryActionType.RefreshToken`
+- **On AWS:** issues Cognito `AdminInitiateAuth` with the `REFRESH_TOKEN_AUTH` flow.
+
+```typescript
+import { askUserDirectoryRefreshToken } from 'quidproquo-core';
+
+export function* askRenewSession(refreshToken: string) {
+  const result = yield* askUserDirectoryRefreshToken('app-users', refreshToken);
+  return result.authenticationInfo; // fresh access / id tokens
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryRefreshToken(
+  userDirectoryName: string,
+  refreshToken: string,
+): AskResponse<AuthenticateUserResponse>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `refreshToken` | `string` | The refresh token issued by a prior authentication (from `AuthenticationInfo.refreshToken`). |
+
+## Returns
+
+`AuthenticateUserResponse` — the same shape returned by [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md#returns). `authenticationInfo` holds the refreshed access and id tokens.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryRefreshTokenErrorTypeEnum.Unauthorized` | The access token is missing/invalid, or the refresh token was rejected (expired/revoked) — the caller must re-authenticate. |
+| `UserDirectoryRefreshTokenErrorTypeEnum.LimitExceeded` | Too many refresh attempts; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md) — the initial sign-in that issues the refresh token.
+- [askUserDirectoryRespondToAuthChallenge](./ask-user-directory-respond-to-auth-challenge.md) — completes challenges before tokens are issued.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-request-email-verification.md

@@ -0,0 +1,53 @@
+---
+title: askUserDirectoryRequestEmailVerification
+description: Send a signed-in user a code to verify their email address.
+---
+
+# askUserDirectoryRequestEmailVerification
+
+Sends a signed-in user a verification code for their email address in a [user directory](../../../config/core/user-directory.md), and reports where it was delivered. Complete the verification with [askUserDirectoryConfirmEmailVerification](./ask-user-directory-confirm-email-verification.md).
+
+- **Action type:** `UserDirectoryActionType.RequestEmailVerification`
+- **On AWS:** issues Cognito `GetUserAttributeVerificationCode` for the `email` attribute using the supplied access token. The message can be customised via the [emailTemplates.verifyEmail](../../../config/core/user-directory.md#email-templates) handler.
+
+```typescript
+import { askUserDirectoryRequestEmailVerification } from 'quidproquo-core';
+
+export function* askStartEmailVerification(accessToken: string) {
+  const delivery = yield* askUserDirectoryRequestEmailVerification('app-users', accessToken);
+  return delivery; // where the code was sent
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryRequestEmailVerification(
+  userDirectoryName: string,
+  accessToken: string,
+): AskResponse<AuthenticationDeliveryDetails>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `accessToken` | `string` | The signed-in user's access token, identifying whose email to verify. |
+
+## Returns
+
+`AuthenticationDeliveryDetails` — where the verification code was delivered (`attributeName`, `deliveryMedium`, `destination`). See [AuthenticationDeliveryDetails](./ask-user-directory-forgot-password.md#returns).
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryRequestEmailVerificationErrorTypeEnum.Unauthorized` | The access token is missing/invalid — the caller must re-authenticate. |
+| `UserDirectoryRequestEmailVerificationErrorTypeEnum.LimitExceeded` | Too many verification-code requests; back off and retry later. |
+| `UserDirectoryRequestEmailVerificationErrorTypeEnum.CodeDeliveryFailed` | The verification code could not be delivered to the user. |
+
+## Related
+
+- [askUserDirectoryConfirmEmailVerification](./ask-user-directory-confirm-email-verification.md) — finish verification with the code.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory and the verification email template.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-respond-to-auth-challenge.md

@@ -0,0 +1,124 @@
+---
+title: askUserDirectoryRespondToAuthChallenge
+description: Complete an auth challenge (new password, MFA, or custom) returned by authentication and receive tokens.
+---
+
+# askUserDirectoryRespondToAuthChallenge
+
+Completes an authentication **challenge** raised by [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md) against a [user directory](../../../config/core/user-directory.md). You build a challenge object describing the answer (a new password, an MFA code, or a custom answer) and, on success, receive the issued tokens.
+
+- **Action type:** `UserDirectoryActionType.RespondToAuthChallenge`
+- **On AWS:** issues Cognito `RespondToAuthChallenge`. For the `MFA_SETUP` challenge the processor first calls `VerifySoftwareToken` with the TOTP code, then completes the challenge with the refreshed session.
+
+```typescript
+import { askUserDirectoryRespondToAuthChallenge, AuthenticateUserChallenge } from 'quidproquo-core';
+
+export function* askCompleteMfa(username: string, session: string, mfaCode: string) {
+  const result = yield* askUserDirectoryRespondToAuthChallenge('app-users', {
+    challenge: AuthenticateUserChallenge.SOFTWARE_TOKEN_MFA,
+    username,
+    session,
+    mfaCode,
+  });
+
+  return result.authenticationInfo; // tokens, when the challenge succeeds
+}
+```
+
+## Challenge variants
+
+The second argument is an `AnyAuthChallenge` — a discriminated union keyed on the `challenge` field. Every variant extends `AuthChallengeBase`:
+
+```typescript
+interface AuthChallengeBase {
+  challenge: AuthenticateUserChallenge;
+  username: string;
+  session: string;
+}
+```
+
+- `username` — the user being authenticated.
+- `session` — the opaque session returned by [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md) (or by an intermediate step such as [askUserDirectoryAssociateSoftwareToken](./ask-user-directory-associate-software-token.md)).
+
+The variant you build must match the `challenge` value that authentication returned:
+
+### `NEW_PASSWORD_REQUIRED`
+
+```typescript
+interface AuthenticateUserNewPasswordRequiredChallenge extends AuthChallengeBase {
+  challenge: AuthenticateUserChallenge.NEW_PASSWORD_REQUIRED;
+  newPassword: string;
+}
+```
+
+Sets the account's first real password (e.g. replacing an admin-issued temporary one). `newPassword` must satisfy the pool's password policy.
+
+### `SOFTWARE_TOKEN_MFA`
+
+```typescript
+interface AuthenticateUserSoftwareTokenMfaChallenge extends AuthChallengeBase {
+  challenge: AuthenticateUserChallenge.SOFTWARE_TOKEN_MFA;
+  mfaCode: string;
+}
+```
+
+Supplies the current TOTP code from the user's already-enrolled authenticator app to complete sign-in.
+
+### `MFA_SETUP`
+
+```typescript
+interface AuthenticateUserMfaSetupChallenge extends AuthChallengeBase {
+  challenge: AuthenticateUserChallenge.MFA_SETUP;
+  mfaCode: string;
+}
+```
+
+Completes first-time MFA enrolment. The pool requires MFA but the user has no authenticator yet: first call [askUserDirectoryAssociateSoftwareToken](./ask-user-directory-associate-software-token.md) to get the shared secret and a refreshed `session`, have the user enter the resulting code, then respond with this challenge. `mfaCode` is the first TOTP code from the freshly-associated authenticator — the processor verifies it (Cognito `VerifySoftwareToken`) before completing the challenge.
+
+### `CUSTOM_CHALLENGE`
+
+```typescript
+interface AuthenticateUserCustomChallengeChallenge<T> extends AuthChallengeBase {
+  challenge: AuthenticateUserChallenge.CUSTOM_CHALLENGE;
+  challengeAnswer: T;
+}
+```
+
+Answers a challenge produced by a [customAuthRuntime](../../../config/core/user-directory.md#custom-auth-runtime). `challengeAnswer` is your own payload type — it is serialised and handed to the pool's verify-auth-challenge trigger.
+
+## Signature
+
+```typescript
+function* askUserDirectoryRespondToAuthChallenge(
+  userDirectoryName: string,
+  authChallenge: AnyAuthChallenge,
+): AskResponse<AuthenticateUserResponse>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `authChallenge` | `AnyAuthChallenge` | The challenge answer — one of the [variants](#challenge-variants) above, matching the challenge authentication returned. |
+
+## Returns
+
+`AuthenticateUserResponse` — the same shape returned by [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md#returns). On a successful answer `challenge` is `NONE` and `authenticationInfo` holds the issued tokens; a further challenge may be returned if the flow requires more steps.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryRespondToAuthChallengeErrorTypeEnum.InvalidCode` | The supplied MFA / challenge / TOTP code is incorrect. |
+| `UserDirectoryRespondToAuthChallengeErrorTypeEnum.ExpiredCode` | The supplied code has expired; restart the challenge. |
+| `UserDirectoryRespondToAuthChallengeErrorTypeEnum.InvalidNewPassword` | (`NEW_PASSWORD_REQUIRED`) the proposed password does not meet the pool's password policy. |
+| `UserDirectoryRespondToAuthChallengeErrorTypeEnum.Unauthorized` | The challenge session is invalid or has expired — restart authentication. |
+| `UserDirectoryRespondToAuthChallengeErrorTypeEnum.LimitExceeded` | Too many attempts; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md) — raises the challenge this action answers.
+- [askUserDirectoryAssociateSoftwareToken](./ask-user-directory-associate-software-token.md) — required before answering the `MFA_SETUP` challenge.
+- [askUserDirectoryRefreshToken](./ask-user-directory-refresh-token.md) — refresh tokens once authentication is complete.
+- [defineUserDirectory](../../../config/core/user-directory.md) — the `mfa` and `customAuthRuntime` options that produce these challenges.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-set-access-token.md

@@ -0,0 +1,52 @@
+---
+title: askUserDirectorySetAccessToken
+description: Load an access token onto the current story session and decode it.
+---
+
+# askUserDirectorySetAccessToken
+
+Decodes an access token issued by a [user directory](../../../config/core/user-directory.md) and stores it (and its decoded claims) on the **current story session**. Subsequent [askUserDirectoryReadAccessToken](./ask-user-directory-read-access-token.md) calls then see this identity — useful for impersonation, background work on a user's behalf, or acting as a user in a story that did not originate from an authenticated request.
+
+- **Action type:** `UserDirectoryActionType.SetAccessToken`
+- **On AWS:** verifies/decodes the token against the pool's public JWKs over HTTPS, then updates the session.
+
+```typescript
+import { askUserDirectorySetAccessToken } from 'quidproquo-core';
+
+export function* askActAs(accessToken: string) {
+  const decoded = yield* askUserDirectorySetAccessToken('app-users', accessToken);
+  // From here, askUserDirectoryReadAccessToken sees this user
+  return decoded.userId;
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectorySetAccessToken(
+  userDirectoryName: string,
+  accessToken: string,
+): AskResponse<DecodedAccessToken>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory that issued the token — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `accessToken` | `string` | The access token to load onto the session. |
+
+## Returns
+
+`DecodedAccessToken` — the decoded claims of the token just set. See [DecodedAccessToken](./ask-user-directory-decode-access-token.md#returns).
+
+## Notes
+
+- The token is stored on the session only; sessions are not transferred across service boundaries (queues, event buses, service functions), so the identity does not leak beyond the current in-process runtime.
+
+## Related
+
+- [askUserDirectoryReadAccessToken](./ask-user-directory-read-access-token.md) — read the token this action sets.
+- [askUserDirectoryDecodeAccessToken](./ask-user-directory-decode-access-token.md) — decode a token without touching the session.
+- [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md) — obtain a token to load.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-set-password.md

@@ -0,0 +1,55 @@
+---
+title: askUserDirectorySetPassword
+description: Administratively set a user's password without a confirmation code.
+---
+
+# askUserDirectorySetPassword
+
+Administratively sets a user's password in a [user directory](../../../config/core/user-directory.md), no current password or confirmation code required. Use it for support-driven resets or programmatic provisioning; it is a privileged operation and should never be exposed directly to end users.
+
+- **Action type:** `UserDirectoryActionType.SetPassword`
+- **On AWS:** issues Cognito `AdminSetUserPassword` (setting the password as permanent).
+
+```typescript
+import { askUserDirectorySetPassword } from 'quidproquo-core';
+
+export function* askResetUserPassword(username: string, newPassword: string) {
+  yield* askUserDirectorySetPassword('app-users', username, newPassword);
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectorySetPassword(
+  userDirectoryName: string,
+  username: string,
+  newPassword: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `username` | `string` | The user (email) whose password to set. |
+| `newPassword` | `string` | The new password; must satisfy the pool's password policy. |
+
+## Returns
+
+`void` — the story resumes once the password has been set.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectorySetPasswordErrorTypeEnum.UserNotFound` | No user matches the supplied username. |
+| `UserDirectorySetPasswordErrorTypeEnum.InvalidNewPassword` | The supplied password does not meet the pool's password policy. |
+| `UserDirectorySetPasswordErrorTypeEnum.LimitExceeded` | Too many attempts; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryChangePassword](./ask-user-directory-change-password.md) — self-service change using the current password.
+- [askUserDirectoryForgotPassword](./ask-user-directory-forgot-password.md) / [askUserDirectoryConfirmForgotPassword](./ask-user-directory-confirm-forgot-password.md) — user-driven reset with a code.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory and its password policy.