saaslayer 0.3.0 → 0.4.1

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 (65) hide show
  1. package/README.md +199 -18
  2. package/bin/saaslayer.js +335 -62
  3. package/package.json +3 -2
  4. package/src/aws-sigv4.js +74 -26
  5. package/src/commands/access-admins.js +2 -2
  6. package/src/commands/admin-allowlist.js +23 -3
  7. package/src/commands/api-keys.js +83 -0
  8. package/src/commands/audit.js +77 -0
  9. package/src/commands/aws.js +355 -82
  10. package/src/commands/binding-handoff.js +174 -0
  11. package/src/commands/bindings.js +111 -0
  12. package/src/commands/catalog.js +30 -3
  13. package/src/commands/deploy.js +49 -11
  14. package/src/commands/env-export.js +58 -0
  15. package/src/commands/first-admin.js +15 -4
  16. package/src/commands/foundation.js +75 -117
  17. package/src/commands/hooks.js +271 -0
  18. package/src/commands/integration-credentials.js +1 -1
  19. package/src/commands/lifecycle.js +149 -24
  20. package/src/commands/login-domain.js +259 -0
  21. package/src/commands/permission-orgs.js +80 -0
  22. package/src/commands/release-manifest.js +17 -8
  23. package/src/commands/service-principals.js +42 -5
  24. package/src/commands/settings.js +21 -5
  25. package/src/commands/sms-registration.js +182 -0
  26. package/src/commands/sms.js +178 -0
  27. package/src/commands/social.js +265 -0
  28. package/src/commands/support-staff.js +72 -0
  29. package/src/commands/users-management.js +2 -20
  30. package/src/commands/users.js +56 -11
  31. package/src/commands/versions.js +61 -0
  32. package/src/connection-proof.js +41 -0
  33. package/src/deployments.js +14 -2
  34. package/src/foundation-change-set.js +180 -0
  35. package/src/foundation-home.js +121 -0
  36. package/src/foundation-template.js +51 -10
  37. package/src/foundation-trust-write.js +379 -0
  38. package/src/iam-session.js +14 -8
  39. package/src/login-domain.js +138 -0
  40. package/src/login-methods.js +118 -0
  41. package/src/module-catalog.js +3 -2
  42. package/src/release-manifest.js +11 -4
  43. package/src/scope.js +3 -1
  44. package/src/settings.js +85 -13
  45. package/src/sms/number.js +37 -0
  46. package/src/sms/registration-fields.js +167 -0
  47. package/src/sms/registration-validate.js +151 -0
  48. package/src/sms/registration.js +216 -0
  49. package/src/sms/release.js +55 -0
  50. package/src/sms/scope.js +86 -0
  51. package/src/sms/status.js +181 -0
  52. package/src/ssm-api.js +31 -0
  53. package/src/trust-entries.js +350 -0
  54. package/src/user-service-instance.js +27 -0
  55. package/src/users-api.js +55 -8
  56. package/src/users-import/checkpoint.js +76 -0
  57. package/src/users-import/import.js +233 -24
  58. package/src/versions.js +80 -0
  59. package/templates/bootstrap/saaslayer-bootstrap-permission-set-inline-policy.json +148 -0
  60. package/templates/bootstrap/saaslayer-bootstrap-policy-email-sender.json +22 -0
  61. package/templates/bootstrap/saaslayer-bootstrap-policy-sms-number.json +22 -0
  62. package/templates/bootstrap/saaslayer-bootstrap-policy.json +114 -0
  63. package/templates/bootstrap/saaslayer-bootstrap-trust-policy.json +18 -0
  64. package/templates/saaslayer-foundation-region.yml +45 -1
  65. package/templates/saaslayer-foundation.yml +759 -309
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # saaslayer
2
2
 
3
- SaaSLayer onboarding CLI. Bootstrap an AWS account for the SaaSLayer control plane and register a service's permissions manifest.
3
+ Manage SaaSLayer projects and deployments, connect your AWS account, and administer
4
+ your app's users and permissions. `saaslayer` is the customer CLI; the separate
5
+ `cplane` CLI is for SaaSLayer operators.
4
6
 
5
7
  ## Install
6
8
 
@@ -14,18 +16,109 @@ Or run without installing:
14
16
  npx saaslayer --help
15
17
  ```
16
18
 
17
- Requires Node.js >= 18. The `init` command shells out to the [AWS CLI](https://aws.amazon.com/cli/), which must be installed and authenticated.
19
+ Requires Node.js >= 18. AWS connection and foundation commands also need the
20
+ [AWS CLI](https://aws.amazon.com/cli/) installed and credentials for the account
21
+ you intend to connect. Ordinary management commands use your SaaSLayer login.
22
+
23
+ ## First deployment
24
+
25
+ The documented beta path deploys into your AWS account. You need beta admission,
26
+ an accessible email address and permission to create the foundation in that
27
+ account. These commands create resources that can incur AWS charges.
28
+
29
+ ```bash
30
+ saaslayer signup
31
+ saaslayer login
32
+ saaslayer org create "Acme"
33
+ saaslayer project create "Acme app" --slug acme-app
34
+ saaslayer context
35
+ ```
36
+
37
+ Creating an organization and project selects each one locally. If they already
38
+ exist, use `saaslayer org list`, `saaslayer org use ORG_ID`, `saaslayer projects`
39
+ and `saaslayer project use PROJECT_ID` instead. Check `saaslayer context` before
40
+ connecting an AWS account or deploying.
41
+
42
+ With AWS credentials for the intended account, replace the account ID and
43
+ administrator email below. [Prepare your AWS account](https://saaslayer.com/docs/getting-started/aws-account-setup/)
44
+ covers a new AWS account, AWS CloudShell, and the least-privilege `SaaSLayerBootstrap`
45
+ policies in [`templates/bootstrap/`](templates/bootstrap/). Pass `--profile` to
46
+ pick an AWS CLI profile; without it the AWS CLI's default credentials are used.
47
+
48
+ ```bash
49
+ saaslayer aws connect --aws-account YOUR_AWS_ACCOUNT_ID --region us-east-1 --profile saaslayer-bootstrap
50
+ saaslayer stacks
51
+ saaslayer deploy --services user-service,permissions-service --hosting byoa --env dev --region us-east-1 --admin-email admin@example.com
52
+ saaslayer status --env dev --region us-east-1
53
+ ```
54
+
55
+ `--hosting byoa` explicitly selects your connected account. Without a hosting flag,
56
+ the control plane uses a connected project account when present and otherwise
57
+ selects hosted placement; use an explicit choice for this cloud-prem walkthrough.
58
+ `saaslayer stacks` reports the catalog module IDs and dependencies available to
59
+ your account. Review the CLI's creation/settings and cost confirmation prompts;
60
+ this example does not promise admission for every module or region.
61
+
62
+ Follow the deployment's first-admin sign-in instructions, then sign in to that
63
+ **deployment** when administering its users:
64
+
65
+ ```bash
66
+ saaslayer login --deployment dev
67
+ ```
68
+
69
+ The management login from `saaslayer login` and the deployment login are separate.
70
+ See [your first setup](https://saaslayer.com/docs/getting-started/first-customer-instance/)
71
+ and [Users](https://saaslayer.com/docs/users/quickstart/) for the next steps.
72
+
73
+ ## Command map
74
+
75
+ `saaslayer --help` is the complete command and flag reference. This README expands
76
+ selected workflows rather than duplicating every help entry.
77
+
78
+ | Task | Commands |
79
+ | --- | --- |
80
+ | Select the account, organization and project | `login`, `whoami`, `context`, `org`, `projects`, `project use` |
81
+ | Connect your AWS account | `aws connect`, `foundation status`, `foundation upgrade` |
82
+ | Inspect modules and releases | `stacks`, `versions` |
83
+ | Manage a deployment | `deploy`, `status`, `update`, `destroy` |
84
+ | Configure services | `settings`, `social`, `first-admin` |
85
+ | Administer app identities and access | `users`, `permissions`, `audit` |
86
+
87
+ ## Configuration and credentials
88
+
89
+ The control-plane API defaults to `https://api.saaslayer.com`. Override it with
90
+ `--config-url URL` or `SAASLAYER_CONFIG_URL` (the flag wins). A deployment's API
91
+ base is a different address: commands that call it use the deployment's published
92
+ outputs or an explicit `--api-base` as documented below.
93
+
94
+ The CLI keeps credentials in `~/.saaslayer/credentials.json` and selection context
95
+ in `~/.saaslayer/context.json`. `SAASLAYER_HOME` selects a different directory,
96
+ useful for an isolated environment. Keep that directory private: the credential
97
+ store includes session and refresh tokens. `--profile` selects AWS credentials
98
+ for commands that use AWS; it does not select a SaaSLayer login.
99
+
100
+ ## Troubleshooting
101
+
102
+ | Symptom | Check |
103
+ | --- | --- |
104
+ | Signup is refused | Confirm your email has beta admission before retrying; creating AWS resources does not grant admission. |
105
+ | `no project selected` | Run `saaslayer projects` in the intended org, then `saaslayer project use PROJECT_ID`, or pass `--project`. |
106
+ | Status is empty or shows another environment | Inspect `saaslayer context`; use the intended `--project`, `--env` and `--region`. |
107
+ | AWS connect reports credentials for another account | Select the intended AWS credentials, or use `--profile`, and rerun the connection command. |
108
+ | A users/permissions command lacks credentials or returns 403 | Use the deployment login or an explicitly authorized machine/API key. A control-plane login is not a deployment administrator credential. |
109
+ | A protected settings update asks for a reason | Supply `--reason` for staging/prod; follow the command's refusal details rather than changing managed stacks directly. |
18
110
 
19
111
  ## Commands
20
112
 
21
113
  ### `saaslayer init`
22
114
 
23
- Deploy the SaaSLayer foundation stack (3 IAM roles + permissions boundary + artifact bucket) into the caller's AWS account, trusting the SaaSLayer control plane. Uses the bundled `templates/saaslayer-foundation.yml`.
115
+ Create the SaaSLayer foundation stack (3 IAM roles + permissions boundary) in the caller's AWS account, with one trust entry for the SaaSLayer control plane that manages it, and the caller as the account's connection authorizer. Refuses an account that already has a foundation (use `saaslayer foundation upgrade`). Uses the bundled `templates/saaslayer-foundation.yml`.
24
116
 
25
117
  ```bash
26
118
  saaslayer init \
27
119
  --control-plane-account <12-digit-account-id> \
28
- --external-id <secret> \
120
+ --external-id <trust-identifier> \
121
+ --control-plane-id <id> \
29
122
  [--stack-name saaslayer-foundation] \
30
123
  [--region us-east-1] \
31
124
  [--stack-name-prefix sl-] \
@@ -35,8 +128,9 @@ saaslayer init \
35
128
 
36
129
  | Flag | Env | Description |
37
130
  | --- | --- | --- |
38
- | `--control-plane-account` | `SAASLAYER_CONTROL_PLANE_ACCOUNT` | 12-digit AWS account id allowed to assume the deploy role. Required. |
39
- | `--external-id` | `SAASLAYER_EXTERNAL_ID` | Trust secret shared during onboarding. Required. |
131
+ | `--control-plane-account` | `SAASLAYER_CONTROL_PLANE_ACCOUNT` | 12-digit AWS account id of the managing control plane. Required. |
132
+ | `--external-id` | `SAASLAYER_EXTERNAL_ID` | Trust identifier (AWS ExternalId) shared during onboarding. Required. |
133
+ | `--control-plane-id` | — | The managing SaaSLayer control plane (e.g. `saaslayer-control-plane`); its identity roles are the only callers trusted. Required. |
40
134
  | `--stack-name` | — | CloudFormation stack name. Defaults to `saaslayer-foundation`. |
41
135
  | `--region` | `AWS_REGION` | Deploy region. Defaults to `us-east-1`. |
42
136
  | `--stack-name-prefix` | — | Prefix for provisioned resources. Defaults to `sl-`. |
@@ -46,7 +140,8 @@ saaslayer init \
46
140
  ### `saaslayer foundation status` / `saaslayer foundation upgrade`
47
141
 
48
142
  Upgrade an installed foundation to the templates bundled with this CLI version, with your own AWS credentials. Covers
49
- both stacks: the account-global `saaslayer-foundation` (IAM) and the per-region `saaslayer-foundation-<region>`.
143
+ both stacks: the account-global `saaslayer-foundation` (IAM), upgraded in its home region (where it was first
144
+ created, found from its roles' `aws:cloudformation:stack-id` tag), and the per-region `saaslayer-foundation-<region>`.
50
145
  Do not apply raw CloudFormation change sets to these stacks yourself; use this command.
51
146
 
52
147
  ```bash
@@ -59,8 +154,10 @@ saaslayer foundation upgrade --region us-west-2 --profile my-profile
59
154
 
60
155
  1. Reads the stack. Refuses if it is missing, not in a stable state (`*_COMPLETE`), or runs a newer version than
61
156
  this CLI.
62
- 2. Creates a change set from the bundled template. Every existing parameter keeps its previous value, so the
63
- ExternalId is never re-entered or printed. A parameter new in the template takes its default.
157
+ 2. Creates a change set from the bundled template, with the account stack's trust statements re-rendered from its
158
+ own `TrustEntries`. Every existing parameter keeps its previous value, so trust identifiers are never re-entered or
159
+ printed. A parameter new in the template takes its default. A foundation that still trusts a single `ExternalId`
160
+ is converted by `saaslayer aws connect` from its home region, which supplies the control plane's trust entry.
64
161
  3. Prints the version change (`5.8.0 -> 5.9.0`) and each resource change: action, resource, type, replacement, scope.
65
162
  4. Refuses (and deletes the change set) when a resource would be replaced, or an IAM role, the permissions boundary
66
163
  or the artifact bucket would be removed, unless you pass `--allow-replacement`.
@@ -69,7 +166,7 @@ saaslayer foundation upgrade --region us-west-2 --profile my-profile
69
166
 
70
167
  | Flag | Description |
71
168
  | --- | --- |
72
- | `--region` | Region the stacks live in. Defaults to `$AWS_REGION`, else `us-east-1`. |
169
+ | `--region` | Region of the region stack. Defaults to `$AWS_REGION`, else `us-east-1`. |
73
170
  | `--profile` | AWS CLI profile to use. Defaults to the AWS CLI's credential chain. |
74
171
  | `--stack-name` | Account stack name. Defaults to `saaslayer-foundation`. |
75
172
  | `--only account\|region` | Act on one stack. The region stack is otherwise skipped when it is not installed. |
@@ -129,7 +226,7 @@ module revision); `settings schema` shows it.
129
226
  saaslayer settings schema --module user-service # the revision your selected deployment runs
130
227
  saaslayer settings get --env dev
131
228
  saaslayer settings set --env dev --set user-service.AllowedAppOrigins=https://app.example.com
132
- saaslayer settings set --env prod --file settings.prod.json --reason "rotate the Google client"
229
+ saaslayer settings set --env prod --file settings.prod.json --reason "raise the password minimum length"
133
230
  saaslayer settings diff --env staging --env prod --manifest release.json
134
231
  ```
135
232
 
@@ -143,18 +240,23 @@ saaslayer settings diff --env staging --env prod --manifest release.json
143
240
  whether a secret is set.
144
241
  - A billing change, and any change on `staging` or `prod`, needs `--reason`.
145
242
 
146
- `saaslayer update --param MODULE.Setting=VALUE` makes the same settings write. `saaslayer update --commit-sha SHA`
147
- moves the deployment to another release; the two cannot be combined in one command.
243
+ `saaslayer update --param MODULE.Setting=VALUE` makes the same settings write. `saaslayer update --version X.Y.Z`
244
+ moves the deployment to another release (`--channel stable` moves it to what `stable` points at now); a release move
245
+ and `--param` cannot be combined in one command. `saaslayer versions` lists the versions, highest first, with their
246
+ channels, breaking releases and which of the project's deployments run each one. `saaslayer update --retry` names no
247
+ release: it redeploys the deployment's own one.
148
248
 
149
249
  `saaslayer update --manifest release.json --env staging --reason "…"` promotes a tested release manifest: it runs a
150
250
  preflight (CLI version, contract hashes, schema transitions from the deployed revision, the environment's settings,
151
251
  direct-mode readers, `--reason`), then moves the release and writes the settings that differ. `--dry-run` runs only
152
252
  the preflight. `saaslayer release-manifest create --env dev --out release.json` records a tested deployment as a
153
- manifest. Format and checks: `docs/architecture/release-manifest.md`.
253
+ manifest; it records the deployment's version as `bundle.version` (an unversioned deployment is refused), and
254
+ `update --manifest` moves by that version. Format and checks: `docs/architecture/release-manifest.md`.
154
255
 
155
256
  `saaslayer deploy` takes create settings: `--module M` (repeatable), `--set MODULE.Setting=VALUE` and
156
- `--settings FILE`. They are checked against the schema of the release being deployed (`--commit-sha`, else the
157
- default release the catalog reports) before anything is sent, and the create-only ones are listed. When the control
257
+ `--settings FILE`, and `--version X.Y.Z` or `--channel stable` for the release to start on. Without a version they
258
+ are checked against the schema of the default release the catalog reports before anything is sent, and the create-only
259
+ ones are listed; with `--version` the control plane checks them. When the control
158
260
  plane reports no default release, the CLI says so and only the control plane checks them; it checks them either way.
159
261
 
160
262
  ### `saaslayer first-admin resend|recover`
@@ -174,6 +276,42 @@ saaslayer first-admin recover --env prod --email new-admin@example.com --reason
174
276
  `GET /access-admins` reports): hand the role over with `saaslayer permissions access-admins offer` instead.
175
277
  - Both start an operation and wait for it (`--no-wait` returns); the deployment's activity records who asked and why.
176
278
 
279
+ ### `saaslayer permissions support-staff grant|revoke|list`
280
+
281
+ Support staff view as a member of any org without belonging to it. An access admin signed in themselves grants or
282
+ revokes the reserved support role at deployment scope (never an API key or IAM machine):
283
+
284
+ ```bash
285
+ saaslayer users get --email support@acme.com --env prod # the person's suid
286
+ saaslayer permissions support-staff grant <suid> --mode act-as --expires-at 2027-01-01T00:00:00Z --id-token-file id.jwt --deployment dep_…
287
+ saaslayer permissions support-staff list --deployment dep_…
288
+ saaslayer permissions support-staff revoke <suid> --mode act-as --id-token-file id.jwt --deployment dep_…
289
+ ```
290
+
291
+ - `--mode view-only` grants `saaslayer:support-view-only` (every write refused while viewing); `--mode act-as` grants
292
+ `saaslayer:support-act-as` (view-only and act-as sessions).
293
+ - See `services/permissions-service/user-docs/support-staff.md` for sessions, modes and the impersonation settings.
294
+
295
+ ### `saaslayer social status|enable|rotate-secret|disable`
296
+
297
+ Google sign-in for one user-service instance, with your own Google OAuth app. Each change is one request and one
298
+ deployment run, the same as a save on the console's Social login page:
299
+
300
+ ```bash
301
+ saaslayer social status --env dev # on/off, client id, URL lists, the redirect URI for Google
302
+ saaslayer social enable google --env dev --client-id 1234.apps.googleusercontent.com --client-secret-stdin \
303
+ --callback-url http://localhost:5173/ --app-origin http://localhost:5173 < secret.txt
304
+ saaslayer social rotate-secret google --env dev --client-secret-stdin < new-secret.txt
305
+ saaslayer social disable google --env prod --reason "switching to Workspace SSO"
306
+ ```
307
+
308
+ - The client secret is read only from stdin. It's never a flag, never printed and never stored in the CLI.
309
+ - `--service user-service@<instance>` picks the instance on a deployment with more than one (required there).
310
+ - `--callback-url`, `--app-origin` and `--hosted-domain` each replace their whole stored list.
311
+ - A protected environment (staging, prod) needs `--reason`.
312
+ - `disable` is refused with `SOCIAL_ONLY_USERS_AFFECTED` and the count while users sign in only with Google, even with
313
+ `--confirm`. Give them another sign-in method first (a signed-in user can add a password from their profile).
314
+
177
315
  ### External ID token and `saaslayer permissions trust-policies`
178
316
 
179
317
  On a deployment that trusts your own login provider (Cognito, Auth0, Okta, …), an administrator signs in with an ID
@@ -214,7 +352,10 @@ with your own AWS credentials, and nothing passes through SaaSLayer.
214
352
  - **Import** is a dry run by default. With `--apply` it:
215
353
  - imports new users through a Cognito CSV import job. They land reset-required, and no emails are sent; on first
216
354
  sign-in `<SignIn>` sends them a reset code.
355
+ - creates each person's user-service profile (no email, no password), so products see their name before they sign in.
217
356
  - creates each org, adds its members and makes the first Owner.
357
+ - needs `--iam` (scopes `users:write`, `users:read`, `users:write-reserved`, `orgs:write`, `owners:bootstrap`); it
358
+ checks the user-service ones before writing, and exits 1 when anything needs attention.
218
359
 
219
360
  ```bash
220
361
  saaslayer users export --provider cognito --user-pool-id us-west-2_SOURCE --region us-west-2 \
@@ -248,6 +389,7 @@ saaslayer login --deployment dev
248
389
  printf '%s' "$PASSWORD" | saaslayer users create --email qa+viewer@acme.com --password-stdin --name Vera
249
390
  saaslayer users list --default-org org_123 --limit 20
250
391
  saaslayer users update --email qa+viewer@acme.com --attr locale=en
392
+ saaslayer users update <suid> --attr email_verified=false # reserved: needs saaslayer:users:account:update-reserved
251
393
  saaslayer users disable <suid>
252
394
  saaslayer users delete <suid> --yes
253
395
 
@@ -266,7 +408,13 @@ saaslayer users get <suid> --iam seeder --deployment dep_abc123 --config-url htt
266
408
  - **adopt** takes over an account made outside SaaSLayer's routes (sign-up, console): it records the account as
267
409
  adopted, verifies its email and, with a password, sets it. It needs its own scope `users:adopt` and grant
268
410
  (`users:write` never implies it). Invitation-registered and SaaSLayer-created accounts are never adopted.
269
- - **delete** is a GDPR delete everywhere and needs `--yes`.
411
+ - **delete** is a GDPR delete everywhere and needs `--yes`. Before anything is purged it erases the person from the
412
+ audit (with every address user-service holds for them), removes their profile copies from their memberships and
413
+ removes their own personal workspace (never a shared org), and prints `auditIdentities` (`requested`, `done`, or
414
+ `not-configured` without an audit table), `profileCopies` (`removed`) and `personalWorkspace` (`removed`, or `none`
415
+ when they have none). If any of these fails, nothing is deleted: run it again. After a finished delete, the user no longer resolves,
416
+ so erase again (or erase an address user-service never held, such as an invitation's) with
417
+ `saaslayer audit erase <suid> --email …`.
270
418
  - **reset-mfa** `--reason "…"` is for a user who lost every MFA factor: it removes their passkeys and
271
419
  authenticator-app MFA, clears step-up evidence and signs them out everywhere, so they can enroll a new factor. It
272
420
  needs `saaslayer:users:account:reset-mfa` (access admins); no IAM scope opens it and an
@@ -274,4 +422,37 @@ saaslayer users get <suid> --iam seeder --deployment dep_abc123 --config-url htt
274
422
  sign-in.
275
423
 
276
424
  The rules are in [services/user-service/docs/users.md](../../services/user-service/docs/users.md). The same API is in
277
- `@saaslayer/js` as `createUsersAdminClient`.
425
+ `@saaslayer/js` as `createUsersAdminClient`. Its `discovery` option is looked up once at first use; add
426
+ `refreshSeconds` to refresh it at most once per interval, keeping the last-known-good users API through a discovery
427
+ outage (runtime discovery makes startup depend on the control plane):
428
+
429
+ ```js
430
+ const users = createUsersAdminClient({
431
+ discovery: { url: process.env.SAASLAYER_DISCOVERY_URL, refreshSeconds: 900 },
432
+ getToken: () => idToken,
433
+ })
434
+ ```
435
+
436
+ ### `saaslayer audit erase <suid>`
437
+
438
+ GDPR erasure of a person from a deployment's audit trail, through its permissions API
439
+ (`POST /audit/identities/:personId/erase`). Their name and email come off every audit entry that names them, and each
440
+ `--email` address comes off the invitation entries that hold it; ids and events stay, and the erasure itself is recorded
441
+ as `audit.identity_erased` (ids only). It is for operators, and to retry the erasure after `saaslayer users delete`.
442
+
443
+ ```bash
444
+ saaslayer audit erase <suid> --email old@acme.com --email new@acme.com --iam eraser --deployment dep_abc123
445
+ saaslayer audit erase <suid> --token "$KEY" --api-base https://permissions.example.com
446
+ ```
447
+
448
+ - **Auth:** `--iam <principalId> [--region R] [--profile P]` or `--token KEY`, holding the platform-only scope
449
+ `audit:person:erase` (org admins never have it). A `403` says so.
450
+ - **API:** `--api-base PERMISSIONS_URL`, or discovered from the deployment's public outputs (`--deployment <dep_id|env>`
451
+ with `--config-url`, or `--discovery-url URL`).
452
+ - **Addresses:** invitation entries are found only by the addresses you pass, so give every address the person had
453
+ (repeat `--email`, at most 50), including any the deployment never knew. They are never printed.
454
+ - **Output:** `{ personId, status, emails }`, where `emails` is the count sent. `status` is `done`, or `requested` when
455
+ the sweep did not finish in the request; the deployment's audit worker then finishes it within minutes. There is no
456
+ status read, so the command does not wait. Running it again is safe and may add addresses, but each run records
457
+ another `audit.identity_erased` entry.
458
+ - A `503` means the deployment has no audit table.