@seliseblocks/cli-os 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/AI_USAGE_GUIDE.md +560 -560
  2. package/LICENSE +21 -21
  3. package/README.md +173 -173
  4. package/bin/run.js +2 -2
  5. package/dist/commands/auth/idp/create.d.ts +7 -0
  6. package/dist/commands/auth/idp/create.js +22 -3
  7. package/dist/commands/auth/idp/update.d.ts +7 -0
  8. package/dist/commands/auth/idp/update.js +22 -3
  9. package/dist/commands/new/web.js +4 -0
  10. package/dist/index.js +692 -672
  11. package/dist/lib/scaffold-web/app-core.js +6 -1
  12. package/dist/lib/scaffold-web/blocks-lib.js +36 -2
  13. package/dist/skills/blocks-data-gateway-configuration/SKILL.md +204 -204
  14. package/dist/skills/blocks-data-gateway-crud/SKILL.md +223 -223
  15. package/dist/skills/blocks-data-storage/SKILL.md +253 -253
  16. package/dist/skills/blocks-data-storage/flows/object-management.md +124 -124
  17. package/dist/skills/blocks-frontend-local-https/SKILL.md +100 -100
  18. package/dist/skills/blocks-iam-access-control/SKILL.md +49 -49
  19. package/dist/skills/blocks-iam-access-control/flows/feature-gating.md +38 -38
  20. package/dist/skills/blocks-iam-access-control/flows/manage-roles-permissions.md +110 -110
  21. package/dist/skills/blocks-iam-account/SKILL.md +169 -169
  22. package/dist/skills/blocks-iam-mfa/SKILL.md +124 -124
  23. package/dist/skills/blocks-iam-organizations/SKILL.md +43 -43
  24. package/dist/skills/blocks-iam-organizations/flows/admin-mutations.md +89 -89
  25. package/dist/skills/blocks-iam-organizations/flows/read-and-switch.md +57 -57
  26. package/dist/skills/blocks-iam-sso-oidc-configuration/SKILL.md +105 -89
  27. package/dist/skills/blocks-iam-sso-oidc-implementation/SKILL.md +80 -80
  28. package/dist/skills/blocks-iam-users/SKILL.md +131 -131
  29. package/dist/skills/blocks-localization-configuration/SKILL.md +149 -149
  30. package/dist/skills/blocks-localization-implementation/SKILL.md +63 -63
  31. package/dist/skills/blocks-mail/SKILL.md +95 -95
  32. package/dist/skills/blocks-notification/SKILL.md +69 -69
  33. package/dist/skills/blocks-notifier/SKILL.md +107 -107
  34. package/dist/skills/blocks-onboarding/SKILL.md +78 -78
  35. package/dist/skills/blocks-release-deployment/SKILL.md +81 -81
  36. package/dist/skills/blocks-secrets/SKILL.md +81 -81
  37. package/dist/skills/blocks-storage-configuration/SKILL.md +93 -93
  38. package/dist/skills/lint.mjs +168 -168
  39. package/package.json +47 -47
@@ -1,169 +1,169 @@
1
- ---
2
- name: blocks-iam-account
3
- description: "Signed-in (or partially-signed-in) user's own SELISE Blocks IAM account actions via @seliseblocks/client — never raw fetch/curl. Covers activation, forgot/reset/change password, logout(-all), profile bootstrap (iam.me/updateMe), self-service MFA, signup, and login-options discovery. Use for activation/password pages, logout buttons, profile bootstrap, signup forms, or letting a user manage their own MFA. The self-service half of IAM — not admin CRUD on other users (blocks-iam-users/blocks-iam-access-control), not hosted-login redirect (blocks-iam-sso-oidc-implementation)."
4
- ---
5
-
6
- # Blocks IAM — Account Self-Service
7
-
8
- Account-lifecycle and account-security actions the signed-in (or not-yet-fully-signed-in) user takes on **their own** account, all through the single `@seliseblocks/client` instance the scaffold gives you — `blocks new web` wires up `createBlocksClient({ apiUrl, xBlocksKey, oidc, accessToken })` once; every call below hangs off that instance's `.auth`, `.iam`, or `.mfa` namespace. **Never** hand-roll `fetch`/`curl` against `api.seliseblocks.com` for these.
9
-
10
- Source of truth: `auth-client.ts`, `iam-client.ts`, and `mfa-client.ts` in `@seliseblocks/client`. Every method has a What/Why/How docstring in source — this skill surfaces them, it doesn't add new ones.
11
-
12
- ## Scope: this vs. the other IAM skills
13
-
14
- - **This skill** — the current user acting on themselves: activate their own invite, reset their own forgotten password, change their own password, log themselves out, read/edit their own profile, sign up, discover login options, enroll/manage their own MFA.
15
- - **blocks-iam-users / blocks-iam-access-control** — an admin managing *other* users (create, deactivate, grant/revoke access). Different actor, different skill. Don't duplicate that here.
16
- - **blocks-iam-sso-oidc-implementation** — the hosted-login redirect/callback flow (`auth.idp.initiate`/`redirectToProvider`/`callback`, `oidc.refreshToken`). This skill only covers direct account-lifecycle calls (activate, recover, reset, change-password, logout) that a user takes outside that redirect dance — don't reimplement hosted login here.
17
- - **blocks-iam-mfa** (not yet written) — the full self-service MFA walkthrough (enrollment UX, challenge flows, backup codes). This skill only notes that `mfa.*` exists and is in scope; go there for depth.
18
-
19
- ## The SDK never owns your session
20
-
21
- Every method here just relays IAM's request/response. The SDK **does not** read or write cookies, localStorage, or any token store — your app decides where the access token, refresh token, and "am I logged in" flag live, and passes the access token in via the `accessToken` option (string or async callback) on `createBlocksClient`. After `logout`/`logoutAll`, activation, or a password reset, **you** clear/update that app-owned state; the SDK call alone doesn't do it for you.
22
-
23
- Request/payload types for most of these methods are intentionally loose (`Record<string, unknown>` passthrough — IAM, not the SDK, defines the exact fields). `BlocksLogoutRequest` is the one exception with a typed hint (`refreshToken?: string`). Where the SDK doesn't pin the shape, confirm exact field names against your tenant's IAM contract rather than guessing — the examples below show the well-known fields, not an exhaustive schema.
24
-
25
- ## Activation — finishing account setup
26
-
27
- Three related calls, all under `blocksClient.auth`, all public (no bearer token needed for `activate`/`validateActivation` — the emailed code is the credential):
28
-
29
- - **`auth.validateActivation(request)`** — no auth required. Check the activation code/state *before* showing the final "set your password" step, so an expired/invalid link fails fast with a clear message instead of after the user fills out the form.
30
- - **`auth.activate(request)`** — no auth required. Completes setup for a user created/invited in an inactive state: pass the emailed `code` plus the new password (and whatever else your tenant's activation contract needs, e.g. `firstName`/`lastName`) after your UI confirms password === confirm-password client-side (don't send a confirm field — that's a UI-only check).
31
- - **`auth.resendActivation(request)`** — Send a new code/link when the old one expired. This call attaches the bearer token if one happens to be configured, but works either way — typical callers are not-yet-active, so don't gate this behind requiring a token.
32
-
33
- ```ts
34
- // after the user opens /activate?code=... and submits password + confirm
35
- const state = await blocksClient.auth.validateActivation({ code });
36
- if (!state.valid) {
37
- // show "this link expired" + a resend option
38
- }
39
-
40
- await blocksClient.auth.activate({
41
- code,
42
- password,
43
- firstName,
44
- lastName
45
- });
46
- // account is now active — route to login / hosted-login (blocks-iam-sso-oidc-implementation)
47
- ```
48
-
49
- ## Password — forgot, reset, and authenticated change
50
-
51
- - **`auth.recover(request)`** — no auth required. Public entry point for "forgot password" — typically just the account's email. Triggers IAM to send a reset link/code.
52
- - **`auth.resetPassword(request)`** — no auth required. Completes the recovery: pass the emailed reset token plus the new password. IAM owns token validation and password-policy enforcement — surface its response/errors directly rather than pre-validating password rules yourself.
53
- - **`auth.changePassword(request)`** — requires an access token (an authenticated account-security action, not part of the recovery flow). Use this for a signed-in "change my password" settings-page action — current password + new password.
54
-
55
- ```ts
56
- // forgot-password page
57
- await blocksClient.auth.recover({ email });
58
-
59
- // reset-password page (link from the recovery email)
60
- await blocksClient.auth.resetPassword({ code, password: newPassword });
61
-
62
- // signed-in settings page
63
- await blocksClient.auth.changePassword({ oldPassword, newPassword });
64
- ```
65
-
66
- ## Logout — end this session or all sessions
67
-
68
- - **`auth.logout(request = {})`** — Ends the current session; commonly takes `{ refreshToken }` if your app manages a refresh token directly (the typed field on `BlocksLogoutRequest`). If your app relies on the hosted IdP's session cookie instead, an empty `{}` is enough — the SDK always sends the request with `credentials: "include"`.
69
- - **`auth.logoutAll(request = {})`** — "Sign out everywhere" — invalidates every session for the account, not just the current one. Good for a security settings page next to change-password.
70
-
71
- ```ts
72
- async function signOut() {
73
- try {
74
- await blocksClient.auth.logout({ refreshToken });
75
- } finally {
76
- // clear app-owned session state even if the network call fails,
77
- // so the UI never shows a stale signed-in state
78
- clearLocalSession();
79
- navigate("/login");
80
- }
81
- }
82
- ```
83
-
84
- ## Profile bootstrap and self-edit
85
-
86
- - **`iam.me()`** — The current IAM user record: roles, permissions, active organization context, resolved from the access token. This is the right call to bootstrap an app's profile/account page or a permission-gated shell after login — don't reconstruct this from token claims yourself.
87
- - **`iam.updateMe(request)`** — Updates the CURRENT authenticated user's own profile fields (name, etc., per your tenant's IAM contract). The backend resolves the user id from the token — **never** pass another user's id here; that's `iam.users.update(id, request)` in the admin skill, a different call entirely.
88
-
89
- ```ts
90
- const me = await blocksClient.iam.me();
91
- // me.data?.roles / me.data?.permissions -> gate nav items, feature flags, etc.
92
- // (iam.me() wraps the user record in a { data } envelope, not the fields directly)
93
-
94
- await blocksClient.iam.updateMe({ firstName, lastName });
95
- ```
96
-
97
- ## Self-service MFA
98
-
99
- Enrolling, challenging, or turning off MFA for the **signed-in user's own** account, via `blocksClient.mfa.*` (see `mfa-client.ts`'s own docstrings — they call this out as self-service, distinct from `mfa.saveConfig`, which is a tenant/admin policy action, not covered here):
100
-
101
- - **`mfa.totp.setup()`** — Starts authenticator-app enrollment; render IAM's returned secret/QR in your UI.
102
- - **`mfa.totp.verifySetup({ code })`** — Confirms enrollment with the 6-digit code from the authenticator app.
103
- - **`mfa.generate({ mfaType, sendPhoneNumberAsEmailDomain? })`** — Sends an email/SMS OTP challenge; returns an `mfaId` for `resend`/`verify`.
104
- - **`mfa.resend({ mfaId, sendPhoneNumberAsEmailDomain? })`** — Re-sends a pending OTP.
105
- - **`mfa.verify({ mfaId, verificationCode, authType, isFromTokenCall? })`** — Confirms an OTP or step-up challenge; set `isFromTokenCall` when verifying as part of a login/token exchange.
106
- - **`mfa.setMethod({ mfaType })`** — Switches which enrolled method is active.
107
- - **`mfa.disable()`** — Self-service opt-out, where the tenant's policy allows it.
108
- - **`mfa.backupCodes.list()`** / **`.generate()`** / **`.use({ code, userId })`** — View remaining recovery codes, mint a fresh set (treat the response as sensitive, show once), or consume one when the primary method is unavailable.
109
-
110
- ```ts
111
- await blocksClient.mfa.totp.setup();
112
- await blocksClient.mfa.totp.verifySetup({ code });
113
- ```
114
-
115
- The same self-service surface is also reachable from a terminal via `blocks mfa totp setup/verify-setup/enable`, `blocks mfa generate/resend/verify`, `blocks mfa method set`, `blocks mfa disable`, and `blocks mfa backup-codes list/generate/use` (project-scoped, impersonated-user token). **See also:** `blocks-iam-mfa` for the full enrollment/challenge walkthrough — this section only flags that self-service MFA exists and is in this skill's scope.
116
-
117
- ## Signup and login discovery
118
-
119
- - **`auth.signup(request)`** — no auth required. Registers a new account; IAM owns account-creation rules — send its expected payload and render its response/errors directly rather than pre-validating fields yourself.
120
- - **`auth.loginOptions()`** — no auth required. Discovers which login methods the tenant supports; call before rendering the login screen so you only show controls IAM actually accepts.
121
-
122
- ```ts
123
- const options = await blocksClient.auth.loginOptions();
124
- // options -> render enabled login methods (password, social, etc.)
125
-
126
- await blocksClient.auth.signup({ email, password, firstName, lastName });
127
- ```
128
-
129
- ## Signup/invite dedup checks
130
-
131
- Useful inside a signup or invite form before submit — both still send `x-blocks-key` even though they don't require a signed-in user:
132
-
133
- - **`iam.users.emailAvailable(query)`** — no auth required. Returns an availability flag (`isAvailable`/`IsAvailable` — IAM's casing varies, check both) for a candidate email.
134
- - **`iam.users.exists(email)`** — Existence check by email.
135
-
136
- ```ts
137
- const availability = await blocksClient.iam.users.emailAvailable({ email });
138
- if (availability.isAvailable === false || availability.IsAvailable === false) {
139
- // show "email already in use" before the user finishes the form
140
- }
141
- ```
142
-
143
- ## Gotchas
144
-
145
- - **Don't invent payload fields.** Several of these methods (`activate`, `resendActivation`, `validateActivation`, `changePassword`, `recover`, `resetPassword`, `logoutAll`, `updateMe`) take an untyped `Record<string, unknown>` in the SDK — the shape is IAM's contract, not something the client library enforces. Use the well-known fields shown above; confirm anything beyond that against the tenant's actual IAM behavior instead of guessing new field names.
146
- - **`activate`/`validateActivation`/`recover`/`resetPassword` are public (no bearer token)** — the emailed code/token *is* the credential. `changePassword` and `updateMe` require an access token to be configured on the client (via `accessToken` on `createBlocksClient`). `logout`/`logoutAll`/`resendActivation` will attach a bearer token if one is configured, but don't require it.
147
- - **`iam.me()` is not `auth.userInfo()` or `auth.isAuthenticated()`.** `auth.userInfo()`/`isAuthenticated()` (OIDC-style claims, session-cookie aware) belong to the SSO/OIDC login-flow territory. `iam.me()` is the full IAM user record — roles, permissions, org context — wrapped in a `{ data }` envelope (`BlocksMeResponse = BlocksQueryResponse<BlocksUser>`), so read `me.data?.roles` etc., not `me.roles` directly.
148
- - **Always clear local app state after logout, even on failure.** The SDK doesn't clear anything for you; a network error from `logout`/`logoutAll` shouldn't leave the UI showing a signed-in user.
149
- - **`updateMe` never takes a user id.** If you find yourself passing an id, you want the admin `iam.users.update(id, request)` call instead — wrong skill for that.
150
- - **Confirm-password fields are UI-only.** IAM's `activate`/`resetPassword`/`changePassword` contracts want the new password once; matching against a second "confirm" field is validated client-side and never sent.
151
-
152
- ## Example trigger prompts
153
-
154
- - "Activate a new account with the emailed code."
155
- - "Build the /activate page that sets a password from an invite link."
156
- - "The activation link expired — let the user request a new one."
157
- - "Add a forgot-password flow to the login page."
158
- - "Build the reset-password page for the emailed reset link."
159
- - "Let a signed-in user change their password from account settings."
160
- - "Add a logout button."
161
- - "Add a 'sign out of all devices' option."
162
- - "Fetch the current user's roles and permissions after login."
163
- - "Let a user edit their own name on their profile page."
164
- - "Check if an email is already taken before letting someone submit the signup form."
165
- - "Register a new account from the signup page."
166
- - "Show which login methods are enabled before rendering the login screen."
167
- - "Let a signed-in user enroll in authenticator-app MFA."
168
- - "Add a 'turn off MFA' option to account security settings."
169
- - "Let a user view or regenerate their MFA backup codes."
1
+ ---
2
+ name: blocks-iam-account
3
+ description: "Signed-in (or partially-signed-in) user's own SELISE Blocks IAM account actions via @seliseblocks/client — never raw fetch/curl. Covers activation, forgot/reset/change password, logout(-all), profile bootstrap (iam.me/updateMe), self-service MFA, signup, and login-options discovery. Use for activation/password pages, logout buttons, profile bootstrap, signup forms, or letting a user manage their own MFA. The self-service half of IAM — not admin CRUD on other users (blocks-iam-users/blocks-iam-access-control), not hosted-login redirect (blocks-iam-sso-oidc-implementation)."
4
+ ---
5
+
6
+ # Blocks IAM — Account Self-Service
7
+
8
+ Account-lifecycle and account-security actions the signed-in (or not-yet-fully-signed-in) user takes on **their own** account, all through the single `@seliseblocks/client` instance the scaffold gives you — `blocks new web` wires up `createBlocksClient({ apiUrl, xBlocksKey, oidc, accessToken })` once; every call below hangs off that instance's `.auth`, `.iam`, or `.mfa` namespace. **Never** hand-roll `fetch`/`curl` against `api.seliseblocks.com` for these.
9
+
10
+ Source of truth: `auth-client.ts`, `iam-client.ts`, and `mfa-client.ts` in `@seliseblocks/client`. Every method has a What/Why/How docstring in source — this skill surfaces them, it doesn't add new ones.
11
+
12
+ ## Scope: this vs. the other IAM skills
13
+
14
+ - **This skill** — the current user acting on themselves: activate their own invite, reset their own forgotten password, change their own password, log themselves out, read/edit their own profile, sign up, discover login options, enroll/manage their own MFA.
15
+ - **blocks-iam-users / blocks-iam-access-control** — an admin managing *other* users (create, deactivate, grant/revoke access). Different actor, different skill. Don't duplicate that here.
16
+ - **blocks-iam-sso-oidc-implementation** — the hosted-login redirect/callback flow (`auth.idp.initiate`/`redirectToProvider`/`callback`, `oidc.refreshToken`). This skill only covers direct account-lifecycle calls (activate, recover, reset, change-password, logout) that a user takes outside that redirect dance — don't reimplement hosted login here.
17
+ - **blocks-iam-mfa** (not yet written) — the full self-service MFA walkthrough (enrollment UX, challenge flows, backup codes). This skill only notes that `mfa.*` exists and is in scope; go there for depth.
18
+
19
+ ## The SDK never owns your session
20
+
21
+ Every method here just relays IAM's request/response. The SDK **does not** read or write cookies, localStorage, or any token store — your app decides where the access token, refresh token, and "am I logged in" flag live, and passes the access token in via the `accessToken` option (string or async callback) on `createBlocksClient`. After `logout`/`logoutAll`, activation, or a password reset, **you** clear/update that app-owned state; the SDK call alone doesn't do it for you.
22
+
23
+ Request/payload types for most of these methods are intentionally loose (`Record<string, unknown>` passthrough — IAM, not the SDK, defines the exact fields). `BlocksLogoutRequest` is the one exception with a typed hint (`refreshToken?: string`). Where the SDK doesn't pin the shape, confirm exact field names against your tenant's IAM contract rather than guessing — the examples below show the well-known fields, not an exhaustive schema.
24
+
25
+ ## Activation — finishing account setup
26
+
27
+ Three related calls, all under `blocksClient.auth`, all public (no bearer token needed for `activate`/`validateActivation` — the emailed code is the credential):
28
+
29
+ - **`auth.validateActivation(request)`** — no auth required. Check the activation code/state *before* showing the final "set your password" step, so an expired/invalid link fails fast with a clear message instead of after the user fills out the form.
30
+ - **`auth.activate(request)`** — no auth required. Completes setup for a user created/invited in an inactive state: pass the emailed `code` plus the new password (and whatever else your tenant's activation contract needs, e.g. `firstName`/`lastName`) after your UI confirms password === confirm-password client-side (don't send a confirm field — that's a UI-only check).
31
+ - **`auth.resendActivation(request)`** — Send a new code/link when the old one expired. This call attaches the bearer token if one happens to be configured, but works either way — typical callers are not-yet-active, so don't gate this behind requiring a token.
32
+
33
+ ```ts
34
+ // after the user opens /activate?code=... and submits password + confirm
35
+ const state = await blocksClient.auth.validateActivation({ code });
36
+ if (!state.valid) {
37
+ // show "this link expired" + a resend option
38
+ }
39
+
40
+ await blocksClient.auth.activate({
41
+ code,
42
+ password,
43
+ firstName,
44
+ lastName
45
+ });
46
+ // account is now active — route to login / hosted-login (blocks-iam-sso-oidc-implementation)
47
+ ```
48
+
49
+ ## Password — forgot, reset, and authenticated change
50
+
51
+ - **`auth.recover(request)`** — no auth required. Public entry point for "forgot password" — typically just the account's email. Triggers IAM to send a reset link/code.
52
+ - **`auth.resetPassword(request)`** — no auth required. Completes the recovery: pass the emailed reset token plus the new password. IAM owns token validation and password-policy enforcement — surface its response/errors directly rather than pre-validating password rules yourself.
53
+ - **`auth.changePassword(request)`** — requires an access token (an authenticated account-security action, not part of the recovery flow). Use this for a signed-in "change my password" settings-page action — current password + new password.
54
+
55
+ ```ts
56
+ // forgot-password page
57
+ await blocksClient.auth.recover({ email });
58
+
59
+ // reset-password page (link from the recovery email)
60
+ await blocksClient.auth.resetPassword({ code, password: newPassword });
61
+
62
+ // signed-in settings page
63
+ await blocksClient.auth.changePassword({ oldPassword, newPassword });
64
+ ```
65
+
66
+ ## Logout — end this session or all sessions
67
+
68
+ - **`auth.logout(request = {})`** — Ends the current session; commonly takes `{ refreshToken }` if your app manages a refresh token directly (the typed field on `BlocksLogoutRequest`). If your app relies on the hosted IdP's session cookie instead, an empty `{}` is enough — the SDK always sends the request with `credentials: "include"`.
69
+ - **`auth.logoutAll(request = {})`** — "Sign out everywhere" — invalidates every session for the account, not just the current one. Good for a security settings page next to change-password.
70
+
71
+ ```ts
72
+ async function signOut() {
73
+ try {
74
+ await blocksClient.auth.logout({ refreshToken });
75
+ } finally {
76
+ // clear app-owned session state even if the network call fails,
77
+ // so the UI never shows a stale signed-in state
78
+ clearLocalSession();
79
+ navigate("/login");
80
+ }
81
+ }
82
+ ```
83
+
84
+ ## Profile bootstrap and self-edit
85
+
86
+ - **`iam.me()`** — The current IAM user record: roles, permissions, active organization context, resolved from the access token. This is the right call to bootstrap an app's profile/account page or a permission-gated shell after login — don't reconstruct this from token claims yourself.
87
+ - **`iam.updateMe(request)`** — Updates the CURRENT authenticated user's own profile fields (name, etc., per your tenant's IAM contract). The backend resolves the user id from the token — **never** pass another user's id here; that's `iam.users.update(id, request)` in the admin skill, a different call entirely.
88
+
89
+ ```ts
90
+ const me = await blocksClient.iam.me();
91
+ // me.data?.roles / me.data?.permissions -> gate nav items, feature flags, etc.
92
+ // (iam.me() wraps the user record in a { data } envelope, not the fields directly)
93
+
94
+ await blocksClient.iam.updateMe({ firstName, lastName });
95
+ ```
96
+
97
+ ## Self-service MFA
98
+
99
+ Enrolling, challenging, or turning off MFA for the **signed-in user's own** account, via `blocksClient.mfa.*` (see `mfa-client.ts`'s own docstrings — they call this out as self-service, distinct from `mfa.saveConfig`, which is a tenant/admin policy action, not covered here):
100
+
101
+ - **`mfa.totp.setup()`** — Starts authenticator-app enrollment; render IAM's returned secret/QR in your UI.
102
+ - **`mfa.totp.verifySetup({ code })`** — Confirms enrollment with the 6-digit code from the authenticator app.
103
+ - **`mfa.generate({ mfaType, sendPhoneNumberAsEmailDomain? })`** — Sends an email/SMS OTP challenge; returns an `mfaId` for `resend`/`verify`.
104
+ - **`mfa.resend({ mfaId, sendPhoneNumberAsEmailDomain? })`** — Re-sends a pending OTP.
105
+ - **`mfa.verify({ mfaId, verificationCode, authType, isFromTokenCall? })`** — Confirms an OTP or step-up challenge; set `isFromTokenCall` when verifying as part of a login/token exchange.
106
+ - **`mfa.setMethod({ mfaType })`** — Switches which enrolled method is active.
107
+ - **`mfa.disable()`** — Self-service opt-out, where the tenant's policy allows it.
108
+ - **`mfa.backupCodes.list()`** / **`.generate()`** / **`.use({ code, userId })`** — View remaining recovery codes, mint a fresh set (treat the response as sensitive, show once), or consume one when the primary method is unavailable.
109
+
110
+ ```ts
111
+ await blocksClient.mfa.totp.setup();
112
+ await blocksClient.mfa.totp.verifySetup({ code });
113
+ ```
114
+
115
+ The same self-service surface is also reachable from a terminal via `blocks mfa totp setup/verify-setup/enable`, `blocks mfa generate/resend/verify`, `blocks mfa method set`, `blocks mfa disable`, and `blocks mfa backup-codes list/generate/use` (project-scoped, impersonated-user token). **See also:** `blocks-iam-mfa` for the full enrollment/challenge walkthrough — this section only flags that self-service MFA exists and is in this skill's scope.
116
+
117
+ ## Signup and login discovery
118
+
119
+ - **`auth.signup(request)`** — no auth required. Registers a new account; IAM owns account-creation rules — send its expected payload and render its response/errors directly rather than pre-validating fields yourself.
120
+ - **`auth.loginOptions()`** — no auth required. Discovers which login methods the tenant supports; call before rendering the login screen so you only show controls IAM actually accepts.
121
+
122
+ ```ts
123
+ const options = await blocksClient.auth.loginOptions();
124
+ // options -> render enabled login methods (password, social, etc.)
125
+
126
+ await blocksClient.auth.signup({ email, password, firstName, lastName });
127
+ ```
128
+
129
+ ## Signup/invite dedup checks
130
+
131
+ Useful inside a signup or invite form before submit — both still send `x-blocks-key` even though they don't require a signed-in user:
132
+
133
+ - **`iam.users.emailAvailable(query)`** — no auth required. Returns an availability flag (`isAvailable`/`IsAvailable` — IAM's casing varies, check both) for a candidate email.
134
+ - **`iam.users.exists(email)`** — Existence check by email.
135
+
136
+ ```ts
137
+ const availability = await blocksClient.iam.users.emailAvailable({ email });
138
+ if (availability.isAvailable === false || availability.IsAvailable === false) {
139
+ // show "email already in use" before the user finishes the form
140
+ }
141
+ ```
142
+
143
+ ## Gotchas
144
+
145
+ - **Don't invent payload fields.** Several of these methods (`activate`, `resendActivation`, `validateActivation`, `changePassword`, `recover`, `resetPassword`, `logoutAll`, `updateMe`) take an untyped `Record<string, unknown>` in the SDK — the shape is IAM's contract, not something the client library enforces. Use the well-known fields shown above; confirm anything beyond that against the tenant's actual IAM behavior instead of guessing new field names.
146
+ - **`activate`/`validateActivation`/`recover`/`resetPassword` are public (no bearer token)** — the emailed code/token *is* the credential. `changePassword` and `updateMe` require an access token to be configured on the client (via `accessToken` on `createBlocksClient`). `logout`/`logoutAll`/`resendActivation` will attach a bearer token if one is configured, but don't require it.
147
+ - **`iam.me()` is not `auth.userInfo()` or `auth.isAuthenticated()`.** `auth.userInfo()`/`isAuthenticated()` (OIDC-style claims, session-cookie aware) belong to the SSO/OIDC login-flow territory. `iam.me()` is the full IAM user record — roles, permissions, org context — wrapped in a `{ data }` envelope (`BlocksMeResponse = BlocksQueryResponse<BlocksUser>`), so read `me.data?.roles` etc., not `me.roles` directly.
148
+ - **Always clear local app state after logout, even on failure.** The SDK doesn't clear anything for you; a network error from `logout`/`logoutAll` shouldn't leave the UI showing a signed-in user.
149
+ - **`updateMe` never takes a user id.** If you find yourself passing an id, you want the admin `iam.users.update(id, request)` call instead — wrong skill for that.
150
+ - **Confirm-password fields are UI-only.** IAM's `activate`/`resetPassword`/`changePassword` contracts want the new password once; matching against a second "confirm" field is validated client-side and never sent.
151
+
152
+ ## Example trigger prompts
153
+
154
+ - "Activate a new account with the emailed code."
155
+ - "Build the /activate page that sets a password from an invite link."
156
+ - "The activation link expired — let the user request a new one."
157
+ - "Add a forgot-password flow to the login page."
158
+ - "Build the reset-password page for the emailed reset link."
159
+ - "Let a signed-in user change their password from account settings."
160
+ - "Add a logout button."
161
+ - "Add a 'sign out of all devices' option."
162
+ - "Fetch the current user's roles and permissions after login."
163
+ - "Let a user edit their own name on their profile page."
164
+ - "Check if an email is already taken before letting someone submit the signup form."
165
+ - "Register a new account from the signup page."
166
+ - "Show which login methods are enabled before rendering the login screen."
167
+ - "Let a signed-in user enroll in authenticator-app MFA."
168
+ - "Add a 'turn off MFA' option to account security settings."
169
+ - "Let a user view or regenerate their MFA backup codes."