saaslayer 0.0.7 → 0.2.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 (48) hide show
  1. package/README.md +150 -13
  2. package/bin/saaslayer.js +318 -66
  3. package/package.json +4 -3
  4. package/src/api-client.js +48 -28
  5. package/src/aws-sigv4.js +1 -1
  6. package/src/commands/access-admins.js +73 -0
  7. package/src/commands/accounts.js +32 -3
  8. package/src/commands/activity.js +33 -0
  9. package/src/commands/aws.js +55 -6
  10. package/src/commands/catalog.js +30 -29
  11. package/src/commands/context.js +64 -0
  12. package/src/commands/deploy.js +79 -10
  13. package/src/commands/first-admin.js +42 -0
  14. package/src/commands/foundation.js +456 -0
  15. package/src/commands/integration-credentials.js +66 -0
  16. package/src/commands/lifecycle.js +77 -40
  17. package/src/commands/login.js +200 -26
  18. package/src/commands/machine-trust.js +96 -0
  19. package/src/commands/operations.js +140 -0
  20. package/src/commands/orgs.js +29 -4
  21. package/src/commands/{rbac-inspect.js → permissions-inspect.js} +15 -15
  22. package/src/commands/release-manifest.js +138 -0
  23. package/src/commands/service-principals.js +81 -0
  24. package/src/commands/settings.js +140 -0
  25. package/src/commands/stacks.js +12 -7
  26. package/src/commands/users-management.js +401 -0
  27. package/src/commands/users.js +192 -4
  28. package/src/config.js +20 -7
  29. package/src/credentials.js +221 -34
  30. package/src/deployment-api-auth.js +61 -0
  31. package/src/deployment-auth.js +38 -0
  32. package/src/deployments.js +12 -13
  33. package/src/discovery.js +66 -0
  34. package/src/env-compare.js +143 -0
  35. package/src/iam-session.js +4 -30
  36. package/src/module-catalog.js +66 -0
  37. package/src/permissions-request.js +43 -0
  38. package/src/release-manifest.js +334 -0
  39. package/src/scope.js +114 -0
  40. package/src/settings.js +272 -0
  41. package/src/users-api.js +165 -0
  42. package/src/users-import/import.js +10 -10
  43. package/templates/saaslayer-foundation-region.yml +37 -1
  44. package/templates/saaslayer-foundation.yml +63 -10
  45. package/src/commands/iam-principals.js +0 -53
  46. package/src/rbac-auth.js +0 -25
  47. package/vendor/ids/index.d.ts +0 -21
  48. package/vendor/ids/index.js +0 -237
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # saaslayer
2
2
 
3
- SaaSLayer onboarding CLI. Bootstrap an AWS account for the SaaSLayer control plane and register a service's RBAC manifest.
3
+ SaaSLayer onboarding CLI. Bootstrap an AWS account for the SaaSLayer control plane and register a service's permissions manifest.
4
4
 
5
5
  ## Install
6
6
 
@@ -43,22 +43,56 @@ saaslayer init \
43
43
  | `--template` | — | Override the bundled template path. |
44
44
  | `--dry-run` | — | Validate the template only; deploy nothing. |
45
45
 
46
- ### `saaslayer rbac register <manifest.json>`
46
+ ### `saaslayer foundation status` / `saaslayer foundation upgrade`
47
47
 
48
- Upsert a service's `rbac.manifest.json` into the RBAC catalog (`POST /catalog/register`). Run by a human or wired into CI.
48
+ 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>`.
50
+ Do not apply raw CloudFormation change sets to these stacks yourself; use this command.
49
51
 
50
52
  ```bash
51
- saaslayer rbac register ./rbac.manifest.json \
53
+ saaslayer foundation status --region us-west-2 --profile my-profile # installed vs bundled version
54
+ saaslayer foundation upgrade --region us-west-2 --profile my-profile --dry-run # review the change set, apply nothing
55
+ saaslayer foundation upgrade --region us-west-2 --profile my-profile # review, confirm, apply
56
+ ```
57
+
58
+ `upgrade` does this for each stack (account stack first):
59
+
60
+ 1. Reads the stack. Refuses if it is missing, not in a stable state (`*_COMPLETE`), or runs a newer version than
61
+ 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.
64
+ 3. Prints the version change (`5.8.0 -> 5.9.0`) and each resource change: action, resource, type, replacement, scope.
65
+ 4. Refuses (and deletes the change set) when a resource would be replaced, or an IAM role, the permissions boundary
66
+ or the artifact bucket would be removed, unless you pass `--allow-replacement`.
67
+ 5. Asks to confirm, executes, waits for `UPDATE_COMPLETE` and reads the new version back. On a rollback it prints the
68
+ failing resources.
69
+
70
+ | Flag | Description |
71
+ | --- | --- |
72
+ | `--region` | Region the stacks live in. Defaults to `$AWS_REGION`, else `us-east-1`. |
73
+ | `--profile` | AWS CLI profile to use. Defaults to the AWS CLI's credential chain. |
74
+ | `--stack-name` | Account stack name. Defaults to `saaslayer-foundation`. |
75
+ | `--only account\|region` | Act on one stack. The region stack is otherwise skipped when it is not installed. |
76
+ | `--dry-run` | Create and print the change set, then delete it. |
77
+ | `--yes` | Skip the confirmation prompt. |
78
+ | `--allow-replacement` | Allow a change that replaces a resource or removes an IAM role, the boundary or the bucket. |
79
+
80
+ ### `saaslayer permissions register <manifest.json>`
81
+
82
+ Upsert a service's permissions manifest into the permissions catalog (`POST /catalog/register`). Run by a human or wired into CI.
83
+
84
+ ```bash
85
+ saaslayer permissions register ./manifest.json --product acme \
52
86
  --api-base https://api.example.com \
53
87
  [--token $SAASLAYER_TOKEN]
54
88
  ```
55
89
 
56
90
  | Flag | Env | Description |
57
91
  | --- | --- | --- |
58
- | `--api-base` | `SAASLAYER_API_BASE` | RBAC catalog API base URL. Required. |
92
+ | `--api-base` | `SAASLAYER_API_BASE` | The deployment's permissions API base URL. Required. |
59
93
  | `--token` | `SAASLAYER_TOKEN` | API key. Required. |
60
94
 
61
- ### `saaslayer rbac inspect <TYPE>:<id>`
95
+ ### `saaslayer permissions inspect <TYPE>:<id>`
62
96
 
63
97
  Print a principal's permissions (needs `saaslayer:principals` authority over the principal): the assignments table (role, scope,
64
98
  direct / inherited / derived, expiry), then `global`, then each scope's allows/denies with the granting role or policy
@@ -67,11 +101,11 @@ assignments page independently, and the output ends with copy-paste commands for
67
101
  v1 and v2 (compact) stored docs, because the CLI reads the server's expanded view and never parses the stored format.
68
102
 
69
103
  ```bash
70
- saaslayer rbac inspect USER:alice --api-base https://api.example.com --token $SAASLAYER_TOKEN
71
- saaslayer rbac inspect USER:alice --scope org_1 --scope site:org_1:s1 # only these scopes
72
- saaslayer rbac inspect USER:alice --all-scopes --json > alice.json # every scope page (scripting)
73
- saaslayer rbac inspect USER:alice --stored # "Stored v1" / "Stored v2 (compact)", problems
74
- saaslayer rbac inspect session:sess_01abc # a session's stored permission set
104
+ saaslayer permissions inspect USER:alice --api-base https://api.example.com --token $SAASLAYER_TOKEN
105
+ saaslayer permissions inspect USER:alice --scope org_1 --scope site:org_1:s1 # only these scopes
106
+ saaslayer permissions inspect USER:alice --all-scopes --json > alice.json # every scope page (scripting)
107
+ saaslayer permissions inspect USER:alice --stored # "Stored v1" / "Stored v2 (compact)", problems
108
+ saaslayer permissions inspect session:sess_01abc # a session's stored permission set
75
109
  ```
76
110
 
77
111
  | Flag | Description |
@@ -81,11 +115,65 @@ saaslayer rbac inspect session:sess_01abc # a se
81
115
  | `--all-scopes` | Follow every scope page. Restarts once, with a message, if the doc is rebuilt mid-way. |
82
116
  | `--stored` | The stored doc's inspection model: format label, sizes, counts, defs / ref sets or v1 buckets, validation problems. |
83
117
  | `--json` | The route payload verbatim. With `--stored`, the raw stored items `{ main, overflow }`. |
84
- | `--api-base`, `--token` / `--iam` | As for `rbac register`. |
118
+ | `--api-base`, `--token` / `--iam` | As for `permissions register`. |
85
119
 
86
120
  The `--token` API key must carry `saaslayer:principals` permissions explicitly; a key without explicit permissions confers none, even when its owner is an admin. Exits 1 with a clear message on 401 / 403 / 404 (no authority, or the principal isn't where you have authority), a bad
87
121
  ref, or a missing token.
88
122
 
123
+ ### `saaslayer settings schema|get|set|diff`
124
+
125
+ Read and change a deployment's module settings. Each module's settings come from its published schema (one per
126
+ module revision); `settings schema` shows it.
127
+
128
+ ```bash
129
+ saaslayer settings schema --module user-service # the revision your selected deployment runs
130
+ saaslayer settings get --env dev
131
+ 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"
133
+ saaslayer settings diff --env staging --env prod --manifest release.json
134
+ ```
135
+
136
+ - `set` reads the current settings, checks the change against the schema and sends it with the settings revision it
137
+ read. A concurrent change is refused: read again and retry. It waits for the update operation (`--no-wait` returns).
138
+ - `--file` is `{ "<module>": { "<Setting>": value } }`; `null` resets a setting to its default, and `--set` overrides
139
+ the file. It is input to one command, not a second copy of your settings.
140
+ - Create-only, runtime and unknown settings are refused before anything is sent.
141
+ - A secret setting takes a reference to an SSM SecureString in your account: `ssm:/<name>` on the command line or
142
+ `{ "ssmParameter": "/<name>" }` in a file. A raw value is refused and never printed; `get` and `diff` show only
143
+ whether a secret is set.
144
+ - A billing change, and any change on `staging` or `prod`, needs `--reason`.
145
+
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.
148
+
149
+ `saaslayer update --manifest release.json --env staging --reason "…"` promotes a tested release manifest: it runs a
150
+ preflight (CLI version, contract hashes, schema transitions from the deployed revision, the environment's settings,
151
+ direct-mode readers, `--reason`), then moves the release and writes the settings that differ. `--dry-run` runs only
152
+ 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`.
154
+
155
+ `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
158
+ plane reports no default release, the CLI says so and only the control plane checks them; it checks them either way.
159
+
160
+ ### `saaslayer first-admin resend|recover`
161
+
162
+ The deployment's first administrator is named at deploy (`--admin-email`). If their first sign-in never arrived, or
163
+ nobody can administer the deployment any more, an org owner (`saaslayer:deployer:deployment:admin-bootstrap`) can act
164
+ from the control plane:
165
+
166
+ ```bash
167
+ saaslayer first-admin resend --env prod # deliver the first sign-in again
168
+ saaslayer first-admin recover --env prod --email new-admin@example.com --reason "first admin left"
169
+ ```
170
+
171
+ - `resend` is the only thing that rotates the designated admin's temporary password. It's refused once they activated.
172
+ - `recover` designates a new first admin (`--suid` to choose their principal id) and retires the bindings nobody can
173
+ use. It's refused with `ADMIN_EXISTS` while any usable access admin remains (the count
174
+ `GET /access-admins` reports): hand the role over with `saaslayer permissions access-admins offer` instead.
175
+ - Both start an operation and wait for it (`--no-wait` returns); the deployment's activity records who asked and why.
176
+
89
177
  ## License
90
178
 
91
179
  Proprietary. All rights reserved. See [LICENSE](./LICENSE).
@@ -106,8 +194,57 @@ saaslayer users export --provider cognito --user-pool-id us-west-2_SOURCE --regi
106
194
  --account-attribute custom:orgId --out manifest.json
107
195
  saaslayer users import --manifest manifest.json --user-pool-id us-west-2_TARGET --region us-west-2 # dry run
108
196
  saaslayer users import --manifest manifest.json --user-pool-id us-west-2_TARGET --region us-west-2 \
109
- --api-base https://rbac.example.com --product acme --iam importer --apply # logs role: found from the pool's stack
197
+ --api-base https://permissions.example.com --product acme --iam importer --apply # logs role: found from the pool's stack
110
198
  ```
111
199
 
112
200
  Prerequisites, the manifest format and how to add a provider (Auth0, Clerk, …) are in
113
201
  [docs/users-import.md](../../docs/users-import.md). The manifest holds personal data, so keep it private.
202
+
203
+ ### `saaslayer users create|get|list|update|disable|enable|delete|reset-password|set-password|adopt|reset-mfa`
204
+
205
+ Administer a deployment's users through its user-service `/api/users`; you never call Cognito yourself. Each command
206
+ acts as one of:
207
+
208
+ - **the deployment login** (default): `saaslayer login --deployment <dep_id|env>` first; `--deployment`/`--as` pick
209
+ among several. The users API is the one that deployment publishes. Needs the `saaslayer:users:account:<action>` grant.
210
+ - **an IAM principal** (`--iam <principalId> [--region R] [--profile P]`): your AWS identity is exchanged for an `iam_`
211
+ token at the deployment's permissions API. Needs the IAM scope (`users:read`, `users:write`, `users:write-reserved`,
212
+ `users:set-password`, `users:adopt`) and the grant on `iam.<principalId>`.
213
+ - **an API key** (`--token KEY`).
214
+
215
+ With `--iam`/`--token`, name the APIs with `--api-base USERS_URL` (+ `--permissions-api-base PERMISSIONS_URL` for `--iam`) or let the
216
+ CLI discover them from the deployment's public outputs: `--deployment <dep_id|env>` (with `--config-url`) or
217
+ `--discovery-url URL`. A user is `<suid>`, `--suid ID` or `--email E` (looked up). Every command prints JSON.
218
+
219
+ ```bash
220
+ saaslayer login --deployment dev
221
+ printf '%s' "$PASSWORD" | saaslayer users create --email qa+viewer@acme.com --password-stdin --name Vera
222
+ saaslayer users list --default-org org_123 --limit 20
223
+ saaslayer users update --email qa+viewer@acme.com --attr locale=en
224
+ saaslayer users disable <suid>
225
+ saaslayer users delete <suid> --yes
226
+
227
+ # as an IAM principal, APIs discovered from the deployment
228
+ saaslayer users get <suid> --iam seeder --deployment dep_abc123 --config-url https://api.saaslayer.example
229
+ ```
230
+
231
+ - **Passwords** (`create`, `set-password`, `adopt`): read only from stdin (`--password-stdin`), never from a flag.
232
+ Setting one is password initialization: it needs `users:set-password` and its grant, and the deployment needs
233
+ `user-service.EnablePasswordInitialization=true`. It is always refused on prod. `set-password --temporary` makes the
234
+ user replace it at next sign-in. Without a password, `create --delivery invitation` has Cognito mail a temporary one.
235
+ - **Re-running create:** the command sends the same Idempotency-Key for the same email, so running it again replays
236
+ the same operation. A running operation is waited for (`--interval SECONDS`); a failed step is reported, and running
237
+ the command again resumes it.
238
+ - **Existing account:** an email that belongs to another account is refused (`409`), and that account is left as it is.
239
+ - **adopt** takes over an account made outside SaaSLayer's routes (sign-up, console): it records the account as
240
+ adopted, verifies its email and, with a password, sets it. It needs its own scope `users:adopt` and grant
241
+ (`users:write` never implies it). Invitation-registered and SaaSLayer-created accounts are never adopted.
242
+ - **delete** is a GDPR delete everywhere and needs `--yes`.
243
+ - **reset-mfa** `--reason "…"` is for a user who lost every MFA factor: it removes their passkeys and
244
+ authenticator-app MFA, clears step-up evidence and signs them out everywhere, so they can enroll a new factor. It
245
+ needs `saaslayer:users:account:reset-mfa` (access admins); no IAM scope opens it and an
246
+ impersonated session is refused. The reason is recorded in the audit line. Resetting your own MFA needs a fresh MFA
247
+ sign-in.
248
+
249
+ The rules are in [services/user-service/docs/users.md](../../services/user-service/docs/users.md). The same API is in
250
+ `@saaslayer/js` as `createUsersAdminClient`.