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.
- package/README.md +105 -16
- package/bin/saaslayer.js +321 -60
- package/package.json +3 -2
- package/src/aws-sigv4.js +74 -26
- package/src/commands/access-admins.js +2 -2
- package/src/commands/admin-allowlist.js +23 -3
- package/src/commands/api-keys.js +83 -0
- package/src/commands/audit.js +77 -0
- package/src/commands/aws.js +355 -82
- package/src/commands/binding-handoff.js +174 -0
- package/src/commands/bindings.js +111 -0
- package/src/commands/catalog.js +30 -3
- package/src/commands/deploy.js +33 -10
- package/src/commands/env-export.js +58 -0
- package/src/commands/first-admin.js +15 -4
- package/src/commands/foundation.js +75 -117
- package/src/commands/hooks.js +271 -0
- package/src/commands/integration-credentials.js +1 -1
- package/src/commands/lifecycle.js +149 -24
- package/src/commands/login-domain.js +259 -0
- package/src/commands/permission-orgs.js +80 -0
- package/src/commands/release-manifest.js +17 -8
- package/src/commands/service-principals.js +42 -5
- package/src/commands/settings.js +21 -5
- package/src/commands/sms-registration.js +182 -0
- package/src/commands/sms.js +178 -0
- package/src/commands/social.js +265 -0
- package/src/commands/support-staff.js +72 -0
- package/src/commands/users-management.js +2 -20
- package/src/commands/users.js +56 -11
- package/src/commands/versions.js +61 -0
- package/src/connection-proof.js +41 -0
- package/src/deployments.js +1 -1
- package/src/foundation-change-set.js +180 -0
- package/src/foundation-home.js +121 -0
- package/src/foundation-template.js +51 -10
- package/src/foundation-trust-write.js +379 -0
- package/src/iam-session.js +14 -8
- package/src/login-domain.js +139 -0
- package/src/login-methods.js +118 -0
- package/src/module-catalog.js +3 -2
- package/src/release-manifest.js +11 -4
- package/src/scope.js +3 -1
- package/src/settings.js +85 -13
- package/src/sms/number.js +37 -0
- package/src/sms/registration-fields.js +167 -0
- package/src/sms/registration-validate.js +151 -0
- package/src/sms/registration.js +216 -0
- package/src/sms/release.js +55 -0
- package/src/sms/scope.js +86 -0
- package/src/sms/status.js +181 -0
- package/src/ssm-api.js +31 -0
- package/src/trust-entries.js +350 -0
- package/src/user-service-instance.js +27 -0
- package/src/users-api.js +55 -8
- package/src/users-import/checkpoint.js +76 -0
- package/src/users-import/import.js +233 -24
- package/src/versions.js +80 -0
- package/templates/saaslayer-foundation-region.yml +45 -1
- 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
|
-
|
|
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 <
|
|
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
|
|
39
|
-
| `--external-id` | `SAASLAYER_EXTERNAL_ID` | Trust
|
|
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)
|
|
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
|
|
63
|
-
|
|
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
|
|
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 "
|
|
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 --
|
|
147
|
-
moves the deployment to another release
|
|
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
|
|
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
|
|
157
|
-
default release the catalog reports
|
|
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.
|