saaslayer 0.3.0 → 0.4.0

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 (60) hide show
  1. package/README.md +105 -16
  2. package/bin/saaslayer.js +321 -60
  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 +33 -10
  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 +1 -1
  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 +139 -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/saaslayer-foundation-region.yml +45 -1
  60. package/templates/saaslayer-foundation.yml +747 -296
package/README.md CHANGED
@@ -20,12 +20,13 @@ Requires Node.js >= 18. The `init` command shells out to the [AWS CLI](https://a
20
20
 
21
21
  ### `saaslayer init`
22
22
 
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`.
23
+ 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
24
 
25
25
  ```bash
26
26
  saaslayer init \
27
27
  --control-plane-account <12-digit-account-id> \
28
- --external-id <secret> \
28
+ --external-id <trust-identifier> \
29
+ --control-plane-id <id> \
29
30
  [--stack-name saaslayer-foundation] \
30
31
  [--region us-east-1] \
31
32
  [--stack-name-prefix sl-] \
@@ -35,8 +36,9 @@ saaslayer init \
35
36
 
36
37
  | Flag | Env | Description |
37
38
  | --- | --- | --- |
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. |
39
+ | `--control-plane-account` | `SAASLAYER_CONTROL_PLANE_ACCOUNT` | 12-digit AWS account id of the managing control plane. Required. |
40
+ | `--external-id` | `SAASLAYER_EXTERNAL_ID` | Trust identifier (AWS ExternalId) shared during onboarding. Required. |
41
+ | `--control-plane-id` | — | The managing SaaSLayer control plane (e.g. `saaslayer-control-plane`); its identity roles are the only callers trusted. Required. |
40
42
  | `--stack-name` | — | CloudFormation stack name. Defaults to `saaslayer-foundation`. |
41
43
  | `--region` | `AWS_REGION` | Deploy region. Defaults to `us-east-1`. |
42
44
  | `--stack-name-prefix` | — | Prefix for provisioned resources. Defaults to `sl-`. |
@@ -46,7 +48,8 @@ saaslayer init \
46
48
  ### `saaslayer foundation status` / `saaslayer foundation upgrade`
47
49
 
48
50
  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>`.
51
+ both stacks: the account-global `saaslayer-foundation` (IAM), upgraded in its home region (where it was first
52
+ created, found from its roles' `aws:cloudformation:stack-id` tag), and the per-region `saaslayer-foundation-<region>`.
50
53
  Do not apply raw CloudFormation change sets to these stacks yourself; use this command.
51
54
 
52
55
  ```bash
@@ -59,8 +62,10 @@ saaslayer foundation upgrade --region us-west-2 --profile my-profile
59
62
 
60
63
  1. Reads the stack. Refuses if it is missing, not in a stable state (`*_COMPLETE`), or runs a newer version than
61
64
  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.
65
+ 2. Creates a change set from the bundled template, with the account stack's trust statements re-rendered from its
66
+ own `TrustEntries`. Every existing parameter keeps its previous value, so trust identifiers are never re-entered or
67
+ printed. A parameter new in the template takes its default. A foundation that still trusts a single `ExternalId`
68
+ is converted by `saaslayer aws connect` from its home region, which supplies the control plane's trust entry.
64
69
  3. Prints the version change (`5.8.0 -> 5.9.0`) and each resource change: action, resource, type, replacement, scope.
65
70
  4. Refuses (and deletes the change set) when a resource would be replaced, or an IAM role, the permissions boundary
66
71
  or the artifact bucket would be removed, unless you pass `--allow-replacement`.
@@ -69,7 +74,7 @@ saaslayer foundation upgrade --region us-west-2 --profile my-profile
69
74
 
70
75
  | Flag | Description |
71
76
  | --- | --- |
72
- | `--region` | Region the stacks live in. Defaults to `$AWS_REGION`, else `us-east-1`. |
77
+ | `--region` | Region of the region stack. Defaults to `$AWS_REGION`, else `us-east-1`. |
73
78
  | `--profile` | AWS CLI profile to use. Defaults to the AWS CLI's credential chain. |
74
79
  | `--stack-name` | Account stack name. Defaults to `saaslayer-foundation`. |
75
80
  | `--only account\|region` | Act on one stack. The region stack is otherwise skipped when it is not installed. |
@@ -129,7 +134,7 @@ module revision); `settings schema` shows it.
129
134
  saaslayer settings schema --module user-service # the revision your selected deployment runs
130
135
  saaslayer settings get --env dev
131
136
  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"
137
+ saaslayer settings set --env prod --file settings.prod.json --reason "raise the password minimum length"
133
138
  saaslayer settings diff --env staging --env prod --manifest release.json
134
139
  ```
135
140
 
@@ -143,18 +148,23 @@ saaslayer settings diff --env staging --env prod --manifest release.json
143
148
  whether a secret is set.
144
149
  - A billing change, and any change on `staging` or `prod`, needs `--reason`.
145
150
 
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.
151
+ `saaslayer update --param MODULE.Setting=VALUE` makes the same settings write. `saaslayer update --version X.Y.Z`
152
+ moves the deployment to another release (`--channel stable` moves it to what `stable` points at now); a release move
153
+ and `--param` cannot be combined in one command. `saaslayer versions` lists the versions, highest first, with their
154
+ channels, breaking releases and which of the project's deployments run each one. `saaslayer update --retry` names no
155
+ release: it redeploys the deployment's own one.
148
156
 
149
157
  `saaslayer update --manifest release.json --env staging --reason "…"` promotes a tested release manifest: it runs a
150
158
  preflight (CLI version, contract hashes, schema transitions from the deployed revision, the environment's settings,
151
159
  direct-mode readers, `--reason`), then moves the release and writes the settings that differ. `--dry-run` runs only
152
160
  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`.
161
+ manifest; it records the deployment's version as `bundle.version` (an unversioned deployment is refused), and
162
+ `update --manifest` moves by that version. Format and checks: `docs/architecture/release-manifest.md`.
154
163
 
155
164
  `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
165
+ `--settings FILE`, and `--version X.Y.Z` or `--channel stable` for the release to start on. Without a version they
166
+ are checked against the schema of the default release the catalog reports before anything is sent, and the create-only
167
+ ones are listed; with `--version` the control plane checks them. When the control
158
168
  plane reports no default release, the CLI says so and only the control plane checks them; it checks them either way.
159
169
 
160
170
  ### `saaslayer first-admin resend|recover`
@@ -174,6 +184,42 @@ saaslayer first-admin recover --env prod --email new-admin@example.com --reason
174
184
  `GET /access-admins` reports): hand the role over with `saaslayer permissions access-admins offer` instead.
175
185
  - Both start an operation and wait for it (`--no-wait` returns); the deployment's activity records who asked and why.
176
186
 
187
+ ### `saaslayer permissions support-staff grant|revoke|list`
188
+
189
+ Support staff view as a member of any org without belonging to it. An access admin signed in themselves grants or
190
+ revokes the reserved support role at deployment scope (never an API key or IAM machine):
191
+
192
+ ```bash
193
+ saaslayer users get --email support@acme.com --env prod # the person's suid
194
+ saaslayer permissions support-staff grant <suid> --mode act-as --expires-at 2027-01-01T00:00:00Z --id-token-file id.jwt --deployment dep_…
195
+ saaslayer permissions support-staff list --deployment dep_…
196
+ saaslayer permissions support-staff revoke <suid> --mode act-as --id-token-file id.jwt --deployment dep_…
197
+ ```
198
+
199
+ - `--mode view-only` grants `saaslayer:support-view-only` (every write refused while viewing); `--mode act-as` grants
200
+ `saaslayer:support-act-as` (view-only and act-as sessions).
201
+ - See `services/permissions-service/user-docs/support-staff.md` for sessions, modes and the impersonation settings.
202
+
203
+ ### `saaslayer social status|enable|rotate-secret|disable`
204
+
205
+ Google sign-in for one user-service instance, with your own Google OAuth app. Each change is one request and one
206
+ deployment run, the same as a save on the console's Social login page:
207
+
208
+ ```bash
209
+ saaslayer social status --env dev # on/off, client id, URL lists, the redirect URI for Google
210
+ saaslayer social enable google --env dev --client-id 1234.apps.googleusercontent.com --client-secret-stdin \
211
+ --callback-url http://localhost:5173/ --app-origin http://localhost:5173 < secret.txt
212
+ saaslayer social rotate-secret google --env dev --client-secret-stdin < new-secret.txt
213
+ saaslayer social disable google --env prod --reason "switching to Workspace SSO"
214
+ ```
215
+
216
+ - The client secret is read only from stdin. It's never a flag, never printed and never stored in the CLI.
217
+ - `--service user-service@<instance>` picks the instance on a deployment with more than one (required there).
218
+ - `--callback-url`, `--app-origin` and `--hosted-domain` each replace their whole stored list.
219
+ - A protected environment (staging, prod) needs `--reason`.
220
+ - `disable` is refused with `SOCIAL_ONLY_USERS_AFFECTED` and the count while users sign in only with Google, even with
221
+ `--confirm`. Give them another sign-in method first (a signed-in user can add a password from their profile).
222
+
177
223
  ### External ID token and `saaslayer permissions trust-policies`
178
224
 
179
225
  On a deployment that trusts your own login provider (Cognito, Auth0, Okta, …), an administrator signs in with an ID
@@ -214,7 +260,10 @@ with your own AWS credentials, and nothing passes through SaaSLayer.
214
260
  - **Import** is a dry run by default. With `--apply` it:
215
261
  - imports new users through a Cognito CSV import job. They land reset-required, and no emails are sent; on first
216
262
  sign-in `<SignIn>` sends them a reset code.
263
+ - creates each person's user-service profile (no email, no password), so products see their name before they sign in.
217
264
  - creates each org, adds its members and makes the first Owner.
265
+ - needs `--iam` (scopes `users:write`, `users:read`, `users:write-reserved`, `orgs:write`, `owners:bootstrap`); it
266
+ checks the user-service ones before writing, and exits 1 when anything needs attention.
218
267
 
219
268
  ```bash
220
269
  saaslayer users export --provider cognito --user-pool-id us-west-2_SOURCE --region us-west-2 \
@@ -248,6 +297,7 @@ saaslayer login --deployment dev
248
297
  printf '%s' "$PASSWORD" | saaslayer users create --email qa+viewer@acme.com --password-stdin --name Vera
249
298
  saaslayer users list --default-org org_123 --limit 20
250
299
  saaslayer users update --email qa+viewer@acme.com --attr locale=en
300
+ saaslayer users update <suid> --attr email_verified=false # reserved: needs saaslayer:users:account:update-reserved
251
301
  saaslayer users disable <suid>
252
302
  saaslayer users delete <suid> --yes
253
303
 
@@ -266,7 +316,13 @@ saaslayer users get <suid> --iam seeder --deployment dep_abc123 --config-url htt
266
316
  - **adopt** takes over an account made outside SaaSLayer's routes (sign-up, console): it records the account as
267
317
  adopted, verifies its email and, with a password, sets it. It needs its own scope `users:adopt` and grant
268
318
  (`users:write` never implies it). Invitation-registered and SaaSLayer-created accounts are never adopted.
269
- - **delete** is a GDPR delete everywhere and needs `--yes`.
319
+ - **delete** is a GDPR delete everywhere and needs `--yes`. Before anything is purged it erases the person from the
320
+ audit (with every address user-service holds for them), removes their profile copies from their memberships and
321
+ removes their own personal workspace (never a shared org), and prints `auditIdentities` (`requested`, `done`, or
322
+ `not-configured` without an audit table), `profileCopies` (`removed`) and `personalWorkspace` (`removed`, or `none`
323
+ when they have none). If any of these fails, nothing is deleted: run it again. After a finished delete, the user no longer resolves,
324
+ so erase again (or erase an address user-service never held, such as an invitation's) with
325
+ `saaslayer audit erase <suid> --email …`.
270
326
  - **reset-mfa** `--reason "…"` is for a user who lost every MFA factor: it removes their passkeys and
271
327
  authenticator-app MFA, clears step-up evidence and signs them out everywhere, so they can enroll a new factor. It
272
328
  needs `saaslayer:users:account:reset-mfa` (access admins); no IAM scope opens it and an
@@ -274,4 +330,37 @@ saaslayer users get <suid> --iam seeder --deployment dep_abc123 --config-url htt
274
330
  sign-in.
275
331
 
276
332
  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`.
333
+ `@saaslayer/js` as `createUsersAdminClient`. Its `discovery` option is looked up once at first use; add
334
+ `refreshSeconds` to refresh it at most once per interval, keeping the last-known-good users API through a discovery
335
+ outage (runtime discovery makes startup depend on the control plane):
336
+
337
+ ```js
338
+ const users = createUsersAdminClient({
339
+ discovery: { url: process.env.SAASLAYER_DISCOVERY_URL, refreshSeconds: 900 },
340
+ getToken: () => idToken,
341
+ })
342
+ ```
343
+
344
+ ### `saaslayer audit erase <suid>`
345
+
346
+ GDPR erasure of a person from a deployment's audit trail, through its permissions API
347
+ (`POST /audit/identities/:personId/erase`). Their name and email come off every audit entry that names them, and each
348
+ `--email` address comes off the invitation entries that hold it; ids and events stay, and the erasure itself is recorded
349
+ as `audit.identity_erased` (ids only). It is for operators, and to retry the erasure after `saaslayer users delete`.
350
+
351
+ ```bash
352
+ saaslayer audit erase <suid> --email old@acme.com --email new@acme.com --iam eraser --deployment dep_abc123
353
+ saaslayer audit erase <suid> --token "$KEY" --api-base https://permissions.example.com
354
+ ```
355
+
356
+ - **Auth:** `--iam <principalId> [--region R] [--profile P]` or `--token KEY`, holding the platform-only scope
357
+ `audit:person:erase` (org admins never have it). A `403` says so.
358
+ - **API:** `--api-base PERMISSIONS_URL`, or discovered from the deployment's public outputs (`--deployment <dep_id|env>`
359
+ with `--config-url`, or `--discovery-url URL`).
360
+ - **Addresses:** invitation entries are found only by the addresses you pass, so give every address the person had
361
+ (repeat `--email`, at most 50), including any the deployment never knew. They are never printed.
362
+ - **Output:** `{ personId, status, emails }`, where `emails` is the count sent. `status` is `done`, or `requested` when
363
+ the sweep did not finish in the request; the deployment's audit worker then finishes it within minutes. There is no
364
+ status read, so the command does not wait. Running it again is safe and may add addresses, but each run records
365
+ another `audit.identity_erased` entry.
366
+ - A `503` means the deployment has no audit table.