saaslayer 0.0.2 → 0.1.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 +195 -8
- package/bin/saaslayer.js +454 -38
- package/package.json +19 -4
- package/src/api-client.js +91 -0
- package/src/aws-sigv4.js +47 -0
- package/src/commands/access-admins.js +73 -0
- package/src/commands/accounts.js +54 -0
- package/src/commands/activity.js +33 -0
- package/src/commands/aws.js +132 -0
- package/src/commands/catalog.js +246 -0
- package/src/commands/context.js +64 -0
- package/src/commands/deploy.js +118 -0
- package/src/commands/first-admin.js +42 -0
- package/src/commands/foundation.js +405 -0
- package/src/commands/lifecycle.js +124 -0
- package/src/commands/login.js +261 -0
- package/src/commands/machine-trust.js +96 -0
- package/src/commands/migrate.js +290 -0
- package/src/commands/operations.js +140 -0
- package/src/commands/orgs.js +81 -0
- package/src/commands/permissions-inspect.js +228 -0
- package/src/commands/release-manifest.js +138 -0
- package/src/commands/service-principals.js +81 -0
- package/src/commands/settings.js +140 -0
- package/src/commands/stacks.js +22 -0
- package/src/commands/users.js +269 -0
- package/src/config.js +49 -0
- package/src/context-store.js +37 -0
- package/src/credentials.js +285 -0
- package/src/deployment-api-auth.js +61 -0
- package/src/deployment-auth.js +38 -0
- package/src/deployments.js +26 -0
- package/src/discovery.js +66 -0
- package/src/env-compare.js +143 -0
- package/src/foundation-template.js +57 -0
- package/src/iam-session.js +67 -0
- package/src/migrations-lib.js +15 -0
- package/src/module-catalog.js +66 -0
- package/src/permissions-request.js +43 -0
- package/src/prompt.js +19 -0
- package/src/release-manifest.js +334 -0
- package/src/scope.js +114 -0
- package/src/settings.js +272 -0
- package/src/users-api.js +165 -0
- package/src/users-import/ids.js +24 -0
- package/src/users-import/import.js +292 -0
- package/src/users-import/manifest.js +90 -0
- package/src/users-import/providers/cognito.js +61 -0
- package/src/users-import/providers/index.js +24 -0
- package/templates/saaslayer-foundation-region.yml +109 -0
- package/templates/{host-account.yml → saaslayer-foundation.yml} +381 -87
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
|
|
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
|
|
|
@@ -20,13 +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
|
|
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`.
|
|
24
24
|
|
|
25
25
|
```bash
|
|
26
26
|
saaslayer init \
|
|
27
27
|
--control-plane-account <12-digit-account-id> \
|
|
28
28
|
--external-id <secret> \
|
|
29
|
-
[--stack-name saaslayer-
|
|
29
|
+
[--stack-name saaslayer-foundation] \
|
|
30
30
|
[--region us-east-1] \
|
|
31
31
|
[--stack-name-prefix sl-] \
|
|
32
32
|
[--template PATH] \
|
|
@@ -37,27 +37,214 @@ saaslayer init \
|
|
|
37
37
|
| --- | --- | --- |
|
|
38
38
|
| `--control-plane-account` | `SAASLAYER_CONTROL_PLANE_ACCOUNT` | 12-digit AWS account id allowed to assume the deploy role. Required. |
|
|
39
39
|
| `--external-id` | `SAASLAYER_EXTERNAL_ID` | Trust secret shared during onboarding. Required. |
|
|
40
|
-
| `--stack-name` | — | CloudFormation stack name. Defaults to `saaslayer-
|
|
40
|
+
| `--stack-name` | — | CloudFormation stack name. Defaults to `saaslayer-foundation`. |
|
|
41
41
|
| `--region` | `AWS_REGION` | Deploy region. Defaults to `us-east-1`. |
|
|
42
42
|
| `--stack-name-prefix` | — | Prefix for provisioned resources. Defaults to `sl-`. |
|
|
43
43
|
| `--template` | — | Override the bundled template path. |
|
|
44
44
|
| `--dry-run` | — | Validate the template only; deploy nothing. |
|
|
45
45
|
|
|
46
|
-
### `saaslayer
|
|
46
|
+
### `saaslayer foundation status` / `saaslayer foundation upgrade`
|
|
47
47
|
|
|
48
|
-
|
|
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
|
|
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` |
|
|
92
|
+
| `--api-base` | `SAASLAYER_API_BASE` | The deployment's permissions API base URL. Required. |
|
|
59
93
|
| `--token` | `SAASLAYER_TOKEN` | API key. Required. |
|
|
60
94
|
|
|
95
|
+
### `saaslayer permissions inspect <TYPE>:<id>`
|
|
96
|
+
|
|
97
|
+
Print a principal's permissions (needs `saaslayer:principals` authority over the principal): the assignments table (role, scope,
|
|
98
|
+
direct / inherited / derived, expiry), then `global`, then each scope's allows/denies with the granting role or policy
|
|
99
|
+
and conditions. It always prints size stats: item bytes vs the 340 KB gate, defs, ref sets and scopes. Scopes and
|
|
100
|
+
assignments page independently, and the output ends with copy-paste commands for the next pages. Works the same for
|
|
101
|
+
v1 and v2 (compact) stored docs, because the CLI reads the server's expanded view and never parses the stored format.
|
|
102
|
+
|
|
103
|
+
```bash
|
|
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
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
| Flag | Description |
|
|
112
|
+
| --- | --- |
|
|
113
|
+
| `--scope S` | Only these scopes (repeatable, at most 50); turns off scope paging. |
|
|
114
|
+
| `--scope-page C` / `--assignment-page C` | The next page (cursors printed by the previous run). A 409 means the doc was rebuilt: restart. |
|
|
115
|
+
| `--all-scopes` | Follow every scope page. Restarts once, with a message, if the doc is rebuilt mid-way. |
|
|
116
|
+
| `--stored` | The stored doc's inspection model: format label, sizes, counts, defs / ref sets or v1 buckets, validation problems. |
|
|
117
|
+
| `--json` | The route payload verbatim. With `--stored`, the raw stored items `{ main, overflow }`. |
|
|
118
|
+
| `--api-base`, `--token` / `--iam` | As for `permissions register`. |
|
|
119
|
+
|
|
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
|
|
121
|
+
ref, or a missing token.
|
|
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
|
+
|
|
61
177
|
## License
|
|
62
178
|
|
|
63
179
|
Proprietary. All rights reserved. See [LICENSE](./LICENSE).
|
|
180
|
+
|
|
181
|
+
### `saaslayer users export` / `saaslayer users import`
|
|
182
|
+
|
|
183
|
+
Move people from another identity system (today: a Cognito user pool) into a SaaSLayer deployment. It runs locally
|
|
184
|
+
with your own AWS credentials, and nothing passes through SaaSLayer.
|
|
185
|
+
|
|
186
|
+
- **Export** writes a reviewable manifest of accounts, people and roles. Everyone is their account's owner by default.
|
|
187
|
+
- **Import** is a dry run by default. With `--apply` it:
|
|
188
|
+
- imports new users through a Cognito CSV import job. They land reset-required, and no emails are sent; on first
|
|
189
|
+
sign-in `<SignIn>` sends them a reset code.
|
|
190
|
+
- creates each org, adds its members and makes the first Owner.
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
saaslayer users export --provider cognito --user-pool-id us-west-2_SOURCE --region us-west-2 \
|
|
194
|
+
--account-attribute custom:orgId --out manifest.json
|
|
195
|
+
saaslayer users import --manifest manifest.json --user-pool-id us-west-2_TARGET --region us-west-2 # dry run
|
|
196
|
+
saaslayer users import --manifest manifest.json --user-pool-id us-west-2_TARGET --region us-west-2 \
|
|
197
|
+
--api-base https://permissions.example.com --product acme --iam importer --apply # logs role: found from the pool's stack
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Prerequisites, the manifest format and how to add a provider (Auth0, Clerk, …) are in
|
|
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`.
|