saaslayer 0.4.0 → 0.4.2
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 +94 -2
- package/bin/saaslayer.js +110 -13
- package/package.json +2 -2
- package/src/api-client.js +3 -2
- package/src/commands/deploy.js +16 -1
- package/src/commands/foundation.js +5 -3
- package/src/commands/hooks.js +4 -9
- package/src/commands/release-manifest.js +3 -1
- package/src/commands/settings.js +2 -0
- package/src/commands/sms.js +35 -4
- package/src/commands/sso.js +913 -0
- package/src/commands/users.js +7 -3
- package/src/commands/verifier-keys.js +105 -0
- package/src/deployments.js +13 -1
- package/src/login-domain.js +1 -1
- package/src/release-manifest.js +30 -7
- package/src/secret-sink.js +77 -0
- package/src/sms/registration-fields.js +1 -1
- package/src/sso-plan.js +21 -0
- package/src/user-service-instance.js +30 -1
- package/src/users-api.js +3 -2
- package/templates/bootstrap/saaslayer-bootstrap-permission-set-inline-policy.json +148 -0
- package/templates/bootstrap/saaslayer-bootstrap-policy-email-sender.json +22 -0
- package/templates/bootstrap/saaslayer-bootstrap-policy-sms-number.json +22 -0
- package/templates/bootstrap/saaslayer-bootstrap-policy.json +114 -0
- package/templates/bootstrap/saaslayer-bootstrap-trust-policy.json +18 -0
- package/templates/saaslayer-foundation-region.yml +10 -2
- package/templates/saaslayer-foundation.yml +53 -26
package/README.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# saaslayer
|
|
2
2
|
|
|
3
|
-
SaaSLayer
|
|
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,7 +16,97 @@ Or run without installing:
|
|
|
14
16
|
npx saaslayer --help
|
|
15
17
|
```
|
|
16
18
|
|
|
17
|
-
Requires Node.js >= 18.
|
|
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
|
|
package/bin/saaslayer.js
CHANGED
|
@@ -268,8 +268,9 @@ Usage:
|
|
|
268
268
|
keys --caller <id> --phase activate|retire|revoke --key-id <id> [--reason <text>] | keys --phase status
|
|
269
269
|
grants --principal <suid> [repeat] --purpose <p> --phase grant|revoke|status [--reason <text>]
|
|
270
270
|
Purposes: account-read, account-provisioning, account-import, account-administration, account-deletion,
|
|
271
|
-
account-sensitive, account-recovery (humans only), reconciliation, config, email-authoring
|
|
272
|
-
only to --output (0600); revoke needs --reason; a revoked grant or root comes back only
|
|
271
|
+
account-sensitive, account-recovery (humans only), reconciliation, config, email-authoring, sso-management (SSO
|
|
272
|
+
connections, setup links and management sessions), verifier-keys (humans only). A raw key is written only to --output (0600); revoke needs --reason; a revoked grant or root comes back only
|
|
273
|
+
with --reason.
|
|
273
274
|
saaslayer audit erase <suid> [--email E …] (--iam PRINCIPAL [--region R] [--profile P] | --token KEY)
|
|
274
275
|
(--api-base PERMISSIONS_URL | --deployment <dep_id|env> [--config-url URL] | --discovery-url URL)
|
|
275
276
|
GDPR erasure of a person from the deployment's audit trail: their name and email come off every audit entry that
|
|
@@ -280,9 +281,19 @@ Usage:
|
|
|
280
281
|
audit:person:erase. Prints { personId, status, emails: <count> } (addresses are never printed);
|
|
281
282
|
status requested is finished by the deployment's audit worker within minutes. Safe to run again, with more addresses.
|
|
282
283
|
|
|
284
|
+
Organizations and projects (requires login):
|
|
285
|
+
saaslayer org create <name> Create an org (you are its owner) and make it the active org.
|
|
286
|
+
saaslayer org list List the orgs you belong to.
|
|
287
|
+
saaslayer org use <id> Set the active org.
|
|
288
|
+
saaslayer projects [--org ID] List the active org's projects.
|
|
289
|
+
saaslayer project create <name> [--slug <slug>] [--org ID]
|
|
290
|
+
Create a project in the active org and make it the active project. --slug is its public deploy name (letter-first,
|
|
291
|
+
lowercase, at most 15 characters; derived from the name when omitted).
|
|
292
|
+
|
|
283
293
|
Deploy & lifecycle (requires login + a connected AWS account):
|
|
284
|
-
saaslayer aws connect --aws-account <id> [--region R] [--org ID] [--org-wide] [--sms-toll-free [--yes]]
|
|
285
|
-
Connect your AWS account to an org
|
|
294
|
+
saaslayer aws connect --aws-account <id> [--region R] [--profile P] [--org ID] [--org-wide] [--sms-toll-free [--yes]]
|
|
295
|
+
Connect your AWS account to an org, with YOUR AWS credentials for that account (--profile, else the AWS CLI's
|
|
296
|
+
default credentials: environment, SSO profile or AWS CloudShell). Binds it to your active project by
|
|
286
297
|
default; --org-wide lets any project in the org deploy into it. The account foundation lives in one home region
|
|
287
298
|
(created by the first connect); connecting another region adds only that region's stack. --sms-toll-free also installs the account's US
|
|
288
299
|
toll-free SMS sending number (~$2/month, asks first unless --yes) and prints its ARN.
|
|
@@ -297,13 +308,15 @@ Deploy & lifecycle (requires login + a connected AWS account):
|
|
|
297
308
|
old one once no running operation carries it. rollback (before retire) goes back to the current identifier; after
|
|
298
309
|
a switch it waits for the operations already using the new one. Each step is signed with your AWS credentials (a
|
|
299
310
|
connection authorizer of the account) and is safe to rerun. status shows the rotation; identifiers are never shown.
|
|
300
|
-
saaslayer sms setup --env E [--region R] [--simulator] [--yes] [--profile P]
|
|
311
|
+
saaslayer sms setup --env E [--region R] [--simulator] [--help-message <text>] [--yes] [--profile P]
|
|
301
312
|
Install the SMS sending number for phone login on the region foundation of the env's account and region (from
|
|
302
313
|
the project's deployment there, else its connected account), with your own AWS credentials for that account
|
|
303
314
|
(cloud-prem; hosted accounts are not supported yet). Shows the cost (~$2/month) and asks unless --yes. Prints the
|
|
304
315
|
number's ARN and the exact settings command. It cannot send until its registration is approved (AWS review: up to
|
|
305
316
|
15 business days). --simulator (dev only, refused when the account has staging or prod deployments) installs an
|
|
306
317
|
AWS simulator number instead: it reaches simulator destinations only, and needs no registration.
|
|
318
|
+
--help-message sets the number's automatic reply to HELP (one SMS, at most 160 characters, naming a contact and
|
|
319
|
+
STOP; carriers check it). Run again with a new --help-message to change only the reply.
|
|
307
320
|
saaslayer sms register --env <env> [--region R] [--file registration.json] [--profile P]
|
|
308
321
|
Register the account's toll-free sending number with AWS (cloud-prem, with YOUR AWS credentials for the env's
|
|
309
322
|
account): asks for (or reads from --file) the company, website, public privacy-policy and terms URLs, contact,
|
|
@@ -339,8 +352,10 @@ Deploy & lifecycle (requires login + a connected AWS account):
|
|
|
339
352
|
The versions a deployment may move to, highest first: the channels on each (stable), breaking releases, and
|
|
340
353
|
which of the project's deployments run each one (a deployment on an unversioned commit is listed apart).
|
|
341
354
|
saaslayer deploy [--services a,b | --module M ...] [--set MODULE.Setting=VALUE ...] [--settings FILE] [--env prod]
|
|
342
|
-
[--region R] [--target ACCT] [--version X.Y.Z | --channel stable] [--admin-email E | --admin-phone-number +E164] [--yes]
|
|
343
|
-
Deploy the project's modules
|
|
355
|
+
[--region R] [--hosting hosted|byoa] [--target ACCT] [--version X.Y.Z | --channel stable] [--admin-email E | --admin-phone-number +E164] [--yes]
|
|
356
|
+
Deploy the project's modules. --hosting hosted runs them in a SaaSLayer AWS account (no AWS account of your own);
|
|
357
|
+
--hosting byoa runs them in your connected account (\`saaslayer aws connect\`). Without it, a project with a
|
|
358
|
+
connected account deploys there and one without is hosted. --services/--module and --set take catalog module
|
|
344
359
|
ids (\`saaslayer stacks\`, e.g. permissions-service); an unknown id or a missing required module is refused before
|
|
345
360
|
anything is sent. --settings FILE is { "<module>": { "<Setting>": value } }; --set overrides it (--param is
|
|
346
361
|
the same as --set). --version (\`saaslayer versions\`) or --channel names the release to start on; without either
|
|
@@ -384,13 +399,14 @@ Deploy & lifecycle (requires login + a connected AWS account):
|
|
|
384
399
|
contract matching the manifest's sha256, schema transitions from the deployed revision (a set setting the target
|
|
385
400
|
drops or refuses, a changed create-only default), the environment's settings (environments.<env>.settings in
|
|
386
401
|
the manifest, or --settings) against the target contracts, direct-mode readers (permissionsDirectMode.readers) against
|
|
387
|
-
what the release writes, and --reason for staging/prod. Then moves the release through the update route (by
|
|
402
|
+
what the release writes (with user-service EnableSso, also the SSO current state they must enforce), and --reason for staging/prod. Then moves the release through the update route (by
|
|
388
403
|
bundle.version when the manifest has one), waits, and writes the settings that differ through the settings route.
|
|
389
404
|
--dry-run prints the preflight and plan only.
|
|
390
405
|
saaslayer release-manifest create --env E [--region R] [--out FILE] [--name NAME]
|
|
391
406
|
Record a tested deployment as a release manifest: its version (bundle.version; a deployment on an unversioned
|
|
392
407
|
commit is refused) and revision, each module's settings-contract sha256, this CLI's version and what its
|
|
393
|
-
permissions service writes
|
|
408
|
+
permissions service writes (and, with user-service EnableSso, compatibility.permissions.sso). Add
|
|
409
|
+
permissionsDirectMode.readers and environments.<env>.settings yourself.
|
|
394
410
|
saaslayer settings schema --module M [--revision SHA] [--env E] [--json]
|
|
395
411
|
Print a module's published settings schema: type, update behavior (update-safe | create-only), kind
|
|
396
412
|
(deployment | runtime), secret, billing impact, default. Without --revision, the revision the selected
|
|
@@ -465,9 +481,9 @@ Deploy & lifecycle (requires login + a connected AWS account):
|
|
|
465
481
|
saaslayer login-domain activate --confirm-domain HOST --reason TEXT [--env E] [--service REF] [--no-wait] [--json]
|
|
466
482
|
saaslayer login-domain deactivate --confirm-domain HOST --reason TEXT [--env E] [--service REF] [--no-wait] [--json]
|
|
467
483
|
Advertise the custom login domain (activate) or the opaque one again (deactivate). Switching breaks the provider
|
|
468
|
-
redirects
|
|
469
|
-
(LOGIN_DOMAIN_HANDOFF_REQUIRED, listing them) unless --confirm-domain names the current host;
|
|
470
|
-
not change. A completion checklist is printed: the switch is done when the new host serves sign-in and every
|
|
484
|
+
redirects and app callbacks registered against the current host, so it is refused
|
|
485
|
+
(LOGIN_DOMAIN_HANDOFF_REQUIRED, listing them) unless --confirm-domain names the current host; passkeys and the
|
|
486
|
+
issuer do not change. A completion checklist is printed: the switch is done when the new host serves sign-in and every
|
|
471
487
|
listed redirect and callback is updated. Register the new redirect URI before activate and keep the old one.
|
|
472
488
|
saaslayer login-domain remove [--env E] [--service REF] [--reason TEXT] [--no-wait] [--json]
|
|
473
489
|
Delete the custom login domain, its DNS alias and (for HOST) its certificate, and free its quota slot. Refused
|
|
@@ -479,7 +495,8 @@ Deploy & lifecycle (requires login + a connected AWS account):
|
|
|
479
495
|
saaslayer hooks set <point> (--url URL | --lambda ARN) [--on-failure allow|deny] [--timeout-ms N] [--claims-ttl-seconds N]
|
|
480
496
|
[--env E] [--service REF]
|
|
481
497
|
saaslayer hooks unset <point> [--env E] [--service REF]
|
|
482
|
-
Set or remove the target of one point: beforeSignUp, afterUserCreated, beforeTokenIssue, afterSignIn, message
|
|
498
|
+
Set or remove the target of one point: beforeSignUp, afterUserCreated, beforeTokenIssue, afterSignIn, message,
|
|
499
|
+
ssoLifecycle (SSO lifecycle events, ids only; EnableSso instances only).
|
|
483
500
|
set replaces the point's whole configuration. --on-failure and --timeout-ms apply to beforeSignUp and
|
|
484
501
|
beforeTokenIssue. --claims-ttl-seconds (beforeTokenIssue only) is how long the hook's app: claims are reused
|
|
485
502
|
before it is asked again; 0 asks on every issuance. A Lambda must first be listed in the instance's HookLambdaArns setting (saaslayer settings
|
|
@@ -501,6 +518,84 @@ Deploy & lifecycle (requires login + a connected AWS account):
|
|
|
501
518
|
saaslayer activity --env E [--region R | --deployment ID] [--limit N] [--json]
|
|
502
519
|
A deployment's activity, newest first: every change — yours and any SaaSLayer operator's — with who made it
|
|
503
520
|
(customer:<id> | operator:<id>), the action, what it touched, the reason and its operation id.
|
|
521
|
+
saaslayer keys create --scope trusted-clients|token-status (--to-ssm NAME [--ssm-region R] [--profile P] | --to-file PATH)
|
|
522
|
+
[--env E] [--service REF] [--json]
|
|
523
|
+
A server key for your backend or SDK that verifies this deployment's tokens (SSO on). trusted-clients reads the
|
|
524
|
+
trusted-clients registry only; token-status checks a token's live standing (POST /api/auth/status) only. The key
|
|
525
|
+
is never printed: it goes to an SSM SecureString in your AWS account (your credentials, the deployment's region by
|
|
526
|
+
default) or to a new 0600 file, and a key that cannot be stored is revoked. At most two active keys per scope.
|
|
527
|
+
saaslayer keys list [--env E] [--service REF] [--json]
|
|
528
|
+
saaslayer keys revoke <keyId> [--env E] [--service REF] [--json]
|
|
529
|
+
Key ids, scopes and states (never a key); revoke refuses the key from its next request. Deployment owners only:
|
|
530
|
+
an owner of the owning org, acting as their own deployment login of that instance (\`saaslayer login --deployment\`;
|
|
531
|
+
--as picks one of several).
|
|
532
|
+
saaslayer sso list [--tenant T] [--env E] [--service REF] [--json]
|
|
533
|
+
saaslayer sso status <connectionId> [--env E] [--service REF] [--json]
|
|
534
|
+
Enterprise SSO connections of a user-service instance (EnableSso on), through the control plane as your own
|
|
535
|
+
deployment login (\`saaslayer login --deployment\`; deployment owners). status adds the connection's health
|
|
536
|
+
(sign-in, signing certificate, SCIM, domains, open issues), what to register in the identity provider and the
|
|
537
|
+
DNS proof of each unverified domain. Secrets are never shown: a client secret reads back as set.
|
|
538
|
+
saaslayer sso add --tenant T --protocol saml|oidc [--issuer I] [--metadata-url URL | --metadata-file FILE |
|
|
539
|
+
--client-id ID --client-secret-stdin [--oidc-scope S ...]] [--domain D ...] [settings] [--json]
|
|
540
|
+
saaslayer sso update <connectionId> [settings] [--issuer I] [--metadata-url URL | --metadata-file FILE]
|
|
541
|
+
[--client-id ID] [--client-secret-stdin] [--yes] [--json]
|
|
542
|
+
add creates a draft connection for the tenant (refused when the tenant already has one for that issuer) and
|
|
543
|
+
prints what to register in the identity provider. Without the issuer and IdP flags it starts from scratch: the
|
|
544
|
+
draft lists what is missing, and saaslayer sso link issue hands the rest to the customer's IT admin (activation
|
|
545
|
+
waits until the issuer and the metadata or OIDC client id and secret are set);
|
|
546
|
+
update changes it at the version it reads (a re-run with the same values changes nothing). settings:
|
|
547
|
+
--org ID ... (orgs it may join), --provider-tenant T, --subject-source nameid|sub|oid, --jit on|off,
|
|
548
|
+
--create-personal-org on|off, --scim on|off, --deprovision disable_and_remove_from_org|remove_from_org_only|disable,
|
|
549
|
+
--mfa delegated|saaslayer, --delegated-tokens blocked|short_lived, --session-cap-hours 1-24,
|
|
550
|
+
--token-ttl-minutes 5-60, --idp-initiated on|off, --enforce on [--notice-days 0-90] (asks to confirm: it ends
|
|
551
|
+
native sign-in for the verified domains after the notice), --manager-group G|none, --break-glass SUID ...,
|
|
552
|
+
--break-glass-minutes 15-1440, --delete-policy keep_dormant_reinvite|block_while_sso_only|delete_sso_only_people,
|
|
553
|
+
--settings-file FILE (connection settings as JSON). The client secret is read from stdin only. issuer,
|
|
554
|
+
providerTenant, subjectSource and the OIDC client id lock at the first activation.
|
|
555
|
+
saaslayer sso activate <connectionId> [--json]
|
|
556
|
+
saaslayer sso disable <connectionId> [--yes] [--json]
|
|
557
|
+
saaslayer sso rotate <connectionId> (--metadata-url URL | --metadata-file FILE | --client-secret-stdin) [--json]
|
|
558
|
+
activate applies the provider and its app client in Cognito, then trusts the connection (again on an active
|
|
559
|
+
one); disable withdraws trust at once and keeps everything for re-activation (asks to confirm); rotate replaces
|
|
560
|
+
the SAML metadata (two signing certificates may overlap) or the OIDC client secret in place.
|
|
561
|
+
saaslayer sso remove <connectionId> --reason TEXT [--sso-only-people N] [--yes] [--json]
|
|
562
|
+
Shows the people affected and the delete policy, then deletes after the typed connection id (or --yes);
|
|
563
|
+
delete_sso_only_people also needs the SSO-only count. A delete that stops part way resumes when run again.
|
|
564
|
+
saaslayer sso domains add|remove|verify <connectionId> <domain> [--yes] [--json]
|
|
565
|
+
add lists a domain and prints its DNS TXT proof; verify checks the proof now; removing a verified domain asks
|
|
566
|
+
to confirm. A domain decides where its people sign in, never what they may do.
|
|
567
|
+
saaslayer sso link issue <connectionId> [--valid-hours 1-168] [--app-url URL] [--replace]
|
|
568
|
+
(--to-ssm NAME [--ssm-region R] [--profile P] | --to-file PATH) [--json]
|
|
569
|
+
saaslayer sso link status|revoke <connectionId> [--json]
|
|
570
|
+
The connection's one setup link for the customer's IT admin (7 days by default). Never printed: it goes to an
|
|
571
|
+
SSM SecureString in your AWS account or a new 0600 file (--app-url stores the whole <app>/sso-setup link), and a
|
|
572
|
+
link that cannot be stored is revoked. A new link ends the active one (--replace) and every session it opened.
|
|
573
|
+
saaslayer sso scim status <connectionId> [--json]
|
|
574
|
+
saaslayer sso scim issue <connectionId> [--expires-in-days N] (--to-ssm NAME [--ssm-region R] | --to-file PATH) [--json]
|
|
575
|
+
saaslayer sso scim rotate <connectionId> <credentialId> [--overlap-seconds N] [--expires-in-days N] (--to-ssm NAME | --to-file PATH) [--json]
|
|
576
|
+
saaslayer sso scim revoke <connectionId> <credentialId> [--json]
|
|
577
|
+
saaslayer sso scim sync-complete <connectionId> [--json]
|
|
578
|
+
SCIM bearer tokens (shown never: written like setup links; a token that cannot be stored is revoked) and the SCIM
|
|
579
|
+
URL to enter with them. rotate keeps the old token working for the overlap (default 1 day). sync-complete
|
|
580
|
+
confirms the identity provider's initial provisioning, continuing a large directory, so SCIM becomes the
|
|
581
|
+
connection's group authority. Google directory sync is not supported.
|
|
582
|
+
saaslayer sso reactivate <connectionId> --directory-id ID --reason TEXT [--json]
|
|
583
|
+
Restores one deactivated person of a connection SCIM does not manage, by their stable identity-provider id.
|
|
584
|
+
saaslayer sso audit [<connectionId> | --tenant T] [--type T] [--from ISO] [--to ISO] [--limit N] [--cursor C]
|
|
585
|
+
[--include-exports] [--json]
|
|
586
|
+
The connection's (or a tenant's, or the deployment's) redacted SSO audit trail, newest first, one page a call.
|
|
587
|
+
Each read is itself recorded as audit.exported; those are listed only with --include-exports.
|
|
588
|
+
saaslayer sso mappings show|ceiling|rules <connectionId> --tenant ORG (--deployment ID | --api-base URL) [auth]
|
|
589
|
+
[--allow-org ID ... --approve-role ORG/ROLE ...] [--file RULES.json] [--json]
|
|
590
|
+
Group-to-role mappings on the deployment's permissions API. ceiling (the deployment owner) sets the orgs the
|
|
591
|
+
connection may add people to and the privileged roles its rules may grant; rules (the tenant's admin) sets
|
|
592
|
+
{ rules: [{ group, orgId, roleIds }], defaultGrant } at the revision it reads; show prints both.
|
|
593
|
+
saaslayer sso enforcement status <connectionId> [--json]
|
|
594
|
+
saaslayer sso enforcement disable <connectionId> --reason TEXT [--yes] [--json]
|
|
595
|
+
status shows where domain enforcement stands (off, scheduled, enforced; in effect only on an active connection), the
|
|
596
|
+
sweep's notices and sign-outs, and how many people of each verified domain it affects (an upper bound: SSO-only
|
|
597
|
+
people count too). disable turns it off, or cancels a scheduled cutover, with a recorded reason after the typed
|
|
598
|
+
connection id (or --yes): native sign-in works again at once. The deployment owner or the tenant's org admin only.
|
|
504
599
|
saaslayer credentials status --deployment <id> --service <ref> [--json]
|
|
505
600
|
saaslayer credentials revoke --deployment <id> --service <ref> --kind email-authoring|config --key-id <id> --reason <text> [--json]
|
|
506
601
|
Org owners: a user-service instance's console integration credentials (key ids, state, age; never a value), and an
|
|
@@ -853,6 +948,8 @@ async function main() {
|
|
|
853
948
|
console.error('usage: saaslayer bindings <create|list|show <bindingId>|handoff <step> <bindingId>> (see saaslayer --help)'); process.exit(1)
|
|
854
949
|
}
|
|
855
950
|
if (cmd === 'env' && sub === 'export') { await require('../src/commands/env-export').envExport(flags); return }
|
|
951
|
+
if (cmd === 'keys') { await require('../src/commands/verifier-keys').keysCommand(sub, positional.slice(2), flags); return }
|
|
952
|
+
if (cmd === 'sso') { await require('../src/commands/sso').ssoCommand(sub, positional.slice(2), flags); return }
|
|
856
953
|
if (cmd === 'credentials' && sub === 'status') { await require('../src/commands/integration-credentials').credentialsStatus(flags); return }
|
|
857
954
|
if (cmd === 'credentials' && sub === 'revoke') { await require('../src/commands/integration-credentials').credentialsRevoke(flags); return }
|
|
858
955
|
if (cmd === 'operations' || cmd === 'operation') { const { operationsCommand } = require('../src/commands/operations'); await operationsCommand(sub, positional[2], flags); return }
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "saaslayer",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "SaaSLayer CLI — onboard an account (init) and register a service's permissions manifest.",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"bin": {
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
"access": "public"
|
|
42
42
|
},
|
|
43
43
|
"scripts": {
|
|
44
|
-
"test": "node scripts/sync-template.js --check && node scripts/sync-vendor.js --check && node bin/saaslayer.js --help >/dev/null && node test/credentials.test.js && node test/multi-account.test.js && node test/aws.test.js && node test/api-client-refresh.test.js && node test/update.test.js && node test/versions.test.js && node test/migrations-approve.test.js && node test/service-add.test.js && node test/service-remove.test.js && node test/destroy.test.js && node test/settings.test.js && node test/login-methods.test.js && node test/settings-login-domain.test.js && node test/login-domain.test.js && node test/env-compare.test.js && node test/release-manifest.test.js && node test/operations.test.js && node test/projects.test.js && node test/activity.test.js && node test/integration-credentials.test.js && node test/users-management.test.js && node test/deploy.test.js && node test/module-catalog.test.js && node test/stacks.test.js && node test/catalog.test.js && node test/catalog-registry.test.js && node test/permissions-inspect.test.js && node test/permissions-commands.test.js && node test/iam.test.js && node test/machine-trust.test.js && node test/access-admins.test.js && node test/support-staff.test.js && node test/permission-orgs.test.js && node test/first-admin.test.js && node test/social.test.js && node test/hooks.test.js && node test/service-principals.test.js && node test/package-files.test.js && node test/users-export.test.js && node test/users-import.test.js && node test/users-import-checkpoint.test.js && node test/users-import-profiles.test.js && node test/users.test.js && node test/users-api.test.js && node test/migrate.test.js && node test/foundation-template.test.js && node test/trust-entries.test.js && node test/foundation-home.test.js && node test/foundation.test.js && node test/foundation-change-set.test.js && node test/foundation-trust-write.test.js && node test/connection-proof.test.js && node test/aws-connect.test.js && node test/aws-rotate-trust.test.js && node test/sms-setup.test.js && node test/sms-release.test.js && node test/scope.test.js && node test/discovery.test.js && node test/credential-profiles.test.js && node test/login-challenges.test.js && node test/login-prompt.test.js && node test/control-plane-url.test.js && node test/signup.test.js && node test/org-members.test.js && node test/sms-register.test.js && node test/sms-status.test.js && echo ok && node test/id-token-auth.test.js && node test/trust-policies.test.js && node test/api-keys.test.js && node test/bindings.test.js && node test/binding-handoff.test.js && node test/env-export.test.js && node test/audit-erase.test.js",
|
|
44
|
+
"test": "node scripts/sync-template.js --check && node scripts/sync-vendor.js --check && node bin/saaslayer.js --help >/dev/null && node test/credentials.test.js && node test/multi-account.test.js && node test/aws.test.js && node test/api-client-refresh.test.js && node test/update.test.js && node test/versions.test.js && node test/migrations-approve.test.js && node test/service-add.test.js && node test/service-remove.test.js && node test/destroy.test.js && node test/settings.test.js && node test/login-methods.test.js && node test/settings-login-domain.test.js && node test/login-domain.test.js && node test/env-compare.test.js && node test/release-manifest.test.js && node test/operations.test.js && node test/projects.test.js && node test/activity.test.js && node test/integration-credentials.test.js && node test/users-management.test.js && node test/deploy.test.js && node test/module-catalog.test.js && node test/stacks.test.js && node test/catalog.test.js && node test/catalog-registry.test.js && node test/permissions-inspect.test.js && node test/permissions-commands.test.js && node test/iam.test.js && node test/machine-trust.test.js && node test/access-admins.test.js && node test/support-staff.test.js && node test/permission-orgs.test.js && node test/first-admin.test.js && node test/social.test.js && node test/hooks.test.js && node test/verifier-keys.test.js && node test/sso.test.js && node test/service-principals.test.js && node test/package-files.test.js && node test/users-export.test.js && node test/users-import.test.js && node test/users-import-checkpoint.test.js && node test/users-import-profiles.test.js && node test/users.test.js && node test/users-api.test.js && node test/migrate.test.js && node test/foundation-template.test.js && node test/trust-entries.test.js && node test/foundation-home.test.js && node test/foundation.test.js && node test/foundation-change-set.test.js && node test/foundation-trust-write.test.js && node test/connection-proof.test.js && node test/aws-connect.test.js && node test/bootstrap-policy.test.js && node test/aws-rotate-trust.test.js && node test/sms-setup.test.js && node test/sms-release.test.js && node test/scope.test.js && node test/discovery.test.js && node test/credential-profiles.test.js && node test/login-challenges.test.js && node test/login-prompt.test.js && node test/control-plane-url.test.js && node test/signup.test.js && node test/org-members.test.js && node test/sms-register.test.js && node test/sms-status.test.js && echo ok && node test/id-token-auth.test.js && node test/trust-policies.test.js && node test/api-keys.test.js && node test/bindings.test.js && node test/binding-handoff.test.js && node test/env-export.test.js && node test/audit-erase.test.js",
|
|
45
45
|
"sync-template": "node scripts/sync-template.js",
|
|
46
46
|
"sync-template:check": "node scripts/sync-template.js --check",
|
|
47
47
|
"prepublishOnly": "node scripts/sync-template.js",
|
package/src/api-client.js
CHANGED
|
@@ -113,10 +113,11 @@ async function apiCall(method, path, body, flags, opts = {}) {
|
|
|
113
113
|
* @param {string} path
|
|
114
114
|
* @param {unknown} [body]
|
|
115
115
|
* @param {object} [flags]
|
|
116
|
+
* @param {{ headers?: Record<string, string> }} [opts]
|
|
116
117
|
*/
|
|
117
|
-
async function jsonApiCall(method, path, body, flags) {
|
|
118
|
+
async function jsonApiCall(method, path, body, flags, opts = {}) {
|
|
118
119
|
try {
|
|
119
|
-
return await apiCall(method, path, body, flags)
|
|
120
|
+
return await apiCall(method, path, body, flags, opts)
|
|
120
121
|
} catch (err) {
|
|
121
122
|
const first = err && err.body && Array.isArray(err.body.errors) ? err.body.errors[0] : null
|
|
122
123
|
if (!first) throw err
|
package/src/commands/deploy.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// `saaslayer deploy` (swf2.7) — self-serve deploy of the customer's project into their connected account.
|
|
1
|
+
// `saaslayer deploy` (swf2.7) — self-serve deploy of the customer's project into a SaaSLayer pool account or their connected account.
|
|
2
2
|
// POSTs to the BFF (Bearer id token); the BFF authorizes the caller, resolves the target, and calls the
|
|
3
3
|
// deployer. Handles the two-step cost-confirm (D14): the first call returns NEEDS_CONFIRMATION with an
|
|
4
4
|
// estimate; on y (or --yes) we re-send confirmCost:true. Then waits for the deploy operation unless --no-wait.
|
|
@@ -24,6 +24,19 @@ function selectedModules(flags) {
|
|
|
24
24
|
return ids.length ? ids : undefined
|
|
25
25
|
}
|
|
26
26
|
|
|
27
|
+
/**
|
|
28
|
+
* Where the deploy runs from --hosting: hosted (a SaaSLayer pool account) or byoa (your connected AWS account); absent,
|
|
29
|
+
* the control plane uses the project's connected account when there is one, else hosts it.
|
|
30
|
+
* @param {Record<string, any>} flags
|
|
31
|
+
* @returns {'hosted'|'byoa'|undefined}
|
|
32
|
+
*/
|
|
33
|
+
function hostingChoice(flags) {
|
|
34
|
+
if (flags.hosting === undefined) return undefined
|
|
35
|
+
if (flags.hosting !== 'hosted' && flags.hosting !== 'byoa') throw new Error('--hosting must be hosted (a SaaSLayer pool account) or byoa (your connected AWS account)')
|
|
36
|
+
if (flags.hosting === 'hosted' && flags.target) throw new Error('--target names your own account: drop it, or use --hosting byoa')
|
|
37
|
+
return flags.hosting
|
|
38
|
+
}
|
|
39
|
+
|
|
27
40
|
/**
|
|
28
41
|
* Check create settings against each module's schema at the revision being deployed (--commit-sha, else the default
|
|
29
42
|
* release the catalog reports) and name the create-only ones. A --version or --channel names no commit here (versions
|
|
@@ -61,6 +74,7 @@ async function deploy(flags, io = {}) {
|
|
|
61
74
|
const interactive = io.interactive === undefined ? Boolean(process.stdin.isTTY) : io.interactive
|
|
62
75
|
const ask = io.confirm || confirm
|
|
63
76
|
const yes = flags.yes === true || flags.yes === 'true'
|
|
77
|
+
const hosting = hostingChoice(flags)
|
|
64
78
|
const scope = resolveScope(flags, { env: 'prod' })
|
|
65
79
|
printScope(scope, flags)
|
|
66
80
|
const project = scope.project.value
|
|
@@ -95,6 +109,7 @@ async function deploy(flags, io = {}) {
|
|
|
95
109
|
...(services ? { services } : {}),
|
|
96
110
|
...(flags.region ? { region: flags.region } : {}),
|
|
97
111
|
...(flags.target ? { targetAccountId: flags.target } : {}),
|
|
112
|
+
...(hosting ? { hosting } : {}),
|
|
98
113
|
...(choice || {}),
|
|
99
114
|
...(flags['admin-email'] ? { adminEmail: flags['admin-email'] } : {}),
|
|
100
115
|
...(adminPhoneNumber ? { adminPhoneNumber } : {}),
|
|
@@ -10,7 +10,7 @@ const { renderFoundationTemplate } = require('../trust-entries')
|
|
|
10
10
|
const { resolveFoundationHome } = require('../foundation-home')
|
|
11
11
|
const { STABLE_STATUSES, NO_CHANGES, awsRunner, describeStack, waitForChangeSet, formatChanges, smsNumberRefusal } = require('../foundation-change-set')
|
|
12
12
|
const { confirm: promptConfirm } = require('../prompt')
|
|
13
|
-
const { apiCall } = require('../api-client')
|
|
13
|
+
const { apiCall, apiBase } = require('../api-client')
|
|
14
14
|
|
|
15
15
|
/** @param {string} cmd @param {string[]} args */
|
|
16
16
|
const defaultExec = (cmd, args) => execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024 })
|
|
@@ -378,12 +378,14 @@ async function refreshFoundationRecord({ accountId, region }, flags) {
|
|
|
378
378
|
* @param {{ aws: import('../foundation-change-set').AwsJson, region: string, log: Function, refresh: Refresh }} ctx
|
|
379
379
|
*/
|
|
380
380
|
async function reportToControlPlane(flags, { aws, region, log, refresh }) {
|
|
381
|
+
// Named in both lines so a re-read sent to another control plane (e.g. the default one) is visible.
|
|
382
|
+
const controlPlane = apiBase(flags)
|
|
381
383
|
try {
|
|
382
384
|
const accountId = String(aws(['sts', 'get-caller-identity']).Account)
|
|
383
385
|
const recorded = await refresh({ accountId, region }, flags)
|
|
384
|
-
log(`control plane: recorded foundation ${recorded.foundationVersion || 'unknown'} for ${accountId} (${region})`)
|
|
386
|
+
log(`control plane ${controlPlane}: recorded foundation ${recorded.foundationVersion || 'unknown'} for ${accountId} (${region})`)
|
|
385
387
|
} catch (err) {
|
|
386
|
-
log(`! control plane not updated yet: ${err.message}`)
|
|
388
|
+
log(`! control plane ${controlPlane} not updated yet: ${err.message}`)
|
|
387
389
|
log(' "check again" on the console Accounts page re-reads it, or run this command again (an up-to-date foundation changes nothing).')
|
|
388
390
|
}
|
|
389
391
|
}
|
package/src/commands/hooks.js
CHANGED
|
@@ -3,15 +3,14 @@
|
|
|
3
3
|
// new signing secret is printed once.
|
|
4
4
|
'use strict'
|
|
5
5
|
const { apiCall } = require('../api-client')
|
|
6
|
-
const { resolveDeployment } = require('../deployments')
|
|
7
6
|
const { PROTECTED_ENVS } = require('../settings')
|
|
8
|
-
const {
|
|
7
|
+
const { resolveInstanceProxy } = require('../user-service-instance')
|
|
9
8
|
|
|
10
9
|
const USAGE = 'usage: saaslayer hooks <status|set|unset|grants set|rotate-secret|test|claims-cache invalidate|logs> [--env E] [--service REF] … (see saaslayer --help)'
|
|
11
10
|
const CLAIMS_CACHE_USAGE = 'usage: saaslayer hooks claims-cache invalidate [--env E] [--service REF] [--json]'
|
|
12
11
|
const GRANTS_USAGE = 'usage: saaslayer hooks grants set --org <orgId> --role <roleId> [--org <orgId> --role <roleId> …] [--env E] [--service REF]'
|
|
13
|
-
// The hook points user-service runs, in the order a sign-up meets them.
|
|
14
|
-
const HOOK_POINTS = ['beforeSignUp', 'afterUserCreated', 'beforeTokenIssue', 'afterSignIn', 'message']
|
|
12
|
+
// The hook points user-service runs, in the order a sign-up meets them, then the SSO lifecycle events (EnableSso instances).
|
|
13
|
+
const HOOK_POINTS = ['beforeSignUp', 'afterUserCreated', 'beforeTokenIssue', 'afterSignIn', 'message', 'ssoLifecycle']
|
|
15
14
|
|
|
16
15
|
/** @param {unknown} value a repeatable flag @returns {string[]} */
|
|
17
16
|
const list = (value) => (value === undefined ? [] : (Array.isArray(value) ? value : [value]).map(String))
|
|
@@ -44,11 +43,7 @@ function describeSecret(secret) {
|
|
|
44
43
|
* @param {Record<string, any>} flags
|
|
45
44
|
*/
|
|
46
45
|
async function resolveHooks(flags) {
|
|
47
|
-
|
|
48
|
-
const doc = await apiCall('GET', `/api/deployments/${encodeURIComponent(deployment.deploymentId)}`, undefined, flags)
|
|
49
|
-
const service = refOf(/** @type {any} */ (chooseInstance({ deploymentId: deployment.deploymentId, ...doc.data.attributes }, flags)))
|
|
50
|
-
const path = `/api/deployments/${encodeURIComponent(deployment.deploymentId)}/services/${encodeURIComponent(service)}/hooks`
|
|
51
|
-
return { deployment, service, path }
|
|
46
|
+
return resolveInstanceProxy(flags, 'hooks')
|
|
52
47
|
}
|
|
53
48
|
|
|
54
49
|
/**
|
|
@@ -114,12 +114,14 @@ async function createManifest(flags) {
|
|
|
114
114
|
for (const m of settings.modules) modules[m.module] = { settingsContractSha256: rm.contractHash(await fetchSchema(m.module, revision, flags)) }
|
|
115
115
|
const writer = settings.modules.find((m) => m.module === rm.PERMISSIONS_WRITER.module)
|
|
116
116
|
const docSetting = writer && writer.settings.find((s) => s.name === rm.PERMISSIONS_WRITER.permissionDocSetting)
|
|
117
|
+
const ssoModule = settings.modules.find((m) => m.module === rm.SSO_CAPABILITY.module)
|
|
118
|
+
const ssoSetting = ssoModule && ssoModule.settings.find((s) => s.name === rm.SSO_CAPABILITY.setting)
|
|
117
119
|
const manifest = {
|
|
118
120
|
schemaVersion: rm.MANIFEST_SCHEMA_VERSION,
|
|
119
121
|
...(typeof flags.name === 'string' ? { name: flags.name } : {}),
|
|
120
122
|
bundle: { revision, version: deployment.version, modules },
|
|
121
123
|
tooling: { cli: CLI_VERSION },
|
|
122
|
-
...(writer ? { compatibility: { permissions: rm.permissionsWriterRelease(docSetting ? docSetting.value : undefined) } } : {}),
|
|
124
|
+
...(writer ? { compatibility: { permissions: rm.permissionsWriterRelease(docSetting ? docSetting.value : undefined, ssoSetting ? ssoSetting.value : undefined) } } : {}),
|
|
123
125
|
environments: {},
|
|
124
126
|
}
|
|
125
127
|
const { problems } = rm.validateManifest(manifest)
|
package/src/commands/settings.js
CHANGED
|
@@ -9,6 +9,7 @@ const { readManifest, environmentSettings } = require('../release-manifest')
|
|
|
9
9
|
const { compareEnvironments, formatComparison } = require('../env-compare')
|
|
10
10
|
const { refuseManagedLoginDomainSettings, admitLoginDomainChanges, loginDomainChecklist } = require('../login-domain')
|
|
11
11
|
const { USER_SERVICE, signInChange, signInRefusalHint } = require('../login-methods')
|
|
12
|
+
const { SSO_PLAN_NOTE, turnsSsoOn } = require('../sso-plan')
|
|
12
13
|
|
|
13
14
|
const USAGE = 'usage: saaslayer settings <schema|get|set|diff> … (see saaslayer --help)'
|
|
14
15
|
|
|
@@ -90,6 +91,7 @@ async function applySettings(input, flags) {
|
|
|
90
91
|
console.log(`Changing settings of ${deployment.deploymentId} (settings revision ${settings.settingsRevision}):`)
|
|
91
92
|
for (const line of formatChanges(patch, settings)) console.log(line)
|
|
92
93
|
for (const line of signIn ? signIn.preview : []) console.log(` ${line}`)
|
|
94
|
+
if (turnsSsoOn(patch[USER_SERVICE], current[USER_SERVICE])) console.log(` ${SSO_PLAN_NOTE}`)
|
|
93
95
|
const attributes = { expectedRevision: settings.settingsRevision, settings: patch, ...(reason ? { reason } : {}), ...(domainHandoff ? { domainHandoff } : {}) }
|
|
94
96
|
let res
|
|
95
97
|
try {
|
package/src/commands/sms.js
CHANGED
|
@@ -21,6 +21,27 @@ const DEFAULT_WAIT = { sleep: (ms) => new Promise((r) => setTimeout(r, ms)), pol
|
|
|
21
21
|
* sms?: import('../sms/registration').SmsClient }} Deps
|
|
22
22
|
*/
|
|
23
23
|
|
|
24
|
+
// A contact a texter can reach: an email address, a URL or a phone number.
|
|
25
|
+
const HELP_CONTACT = /[^\s@]+@[^\s@]+\.[a-z]{2,}|https?:\/\/\S+|\+?\d[\d\s().-]{7,}\d/i
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* The --help-message text, checked before anything is called: one SMS (160 characters) that says how to opt out (STOP)
|
|
29
|
+
* and names a contact, as carriers expect of a HELP reply. undefined when the flag is not given.
|
|
30
|
+
* @param {Record<string, unknown>} flags
|
|
31
|
+
*/
|
|
32
|
+
function helpMessageOf(flags) {
|
|
33
|
+
if (!('help-message' in flags)) return undefined
|
|
34
|
+
const text = typeof flags['help-message'] === 'string' ? flags['help-message'].trim() : ''
|
|
35
|
+
if (!text) throw new Error('--help-message needs a text: the reply to HELP, with your name, a contact and "Reply STOP to opt out."')
|
|
36
|
+
if (text.length > 160) throw new Error(`--help-message must be at most 160 characters (one SMS); it is ${text.length}`)
|
|
37
|
+
if (!/\bSTOP\b/.test(text)) throw new Error('--help-message must say how to opt out (STOP), e.g. "Reply STOP to opt out."')
|
|
38
|
+
if (!HELP_CONTACT.test(text)) throw new Error('--help-message must name a contact (an email, a phone number or a URL)')
|
|
39
|
+
return text
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The region foundation stack's current value of a parameter, or undefined. @param {any} stack @param {string} key */
|
|
43
|
+
const stackParameter = (stack, key) => ((stack.Parameters || []).find((p) => p.ParameterKey === key) || {}).ParameterValue
|
|
44
|
+
|
|
24
45
|
/** The region foundation stack of the target, refused when the account was never connected in that region. */
|
|
25
46
|
function regionStack(aws, target) {
|
|
26
47
|
const stack = describeStack(aws, foundationRegionStackName(target.region))
|
|
@@ -29,11 +50,13 @@ function regionStack(aws, target) {
|
|
|
29
50
|
}
|
|
30
51
|
|
|
31
52
|
/**
|
|
32
|
-
* `saaslayer sms setup --env <env> [--region R] [--simulator] [--yes]`: install the toll-free (or,
|
|
33
|
-
* sending number on the region foundation of the env's account and region
|
|
53
|
+
* `saaslayer sms setup --env <env> [--region R] [--simulator] [--help-message <text>] [--yes]`: install the toll-free (or,
|
|
54
|
+
* dev only, simulator) sending number on the region foundation of the env's account and region, with its HELP reply; on an
|
|
55
|
+
* installed number, --help-message changes only the reply. Returns null when the prompt is declined.
|
|
34
56
|
* @param {object} flags @param {Deps} [deps]
|
|
35
57
|
*/
|
|
36
58
|
async function smsSetup(flags, { exec = defaultExec, api = jsonApiCall, confirm = promptConfirm, log = console.log, wait = DEFAULT_WAIT } = {}) {
|
|
59
|
+
const helpMessage = helpMessageOf(flags)
|
|
37
60
|
const simulator = flags.simulator === true
|
|
38
61
|
const numberType = simulator ? 'simulator' : 'toll-free'
|
|
39
62
|
const { target, aws } = await cloudPremTarget(flags, 'sms setup', { api, exec })
|
|
@@ -42,7 +65,14 @@ async function smsSetup(flags, { exec = defaultExec, api = jsonApiCall, confirm
|
|
|
42
65
|
throw new Error(`--simulator refused: ${target.accountId} has staging or prod deployments; a simulator number belongs in a dev or test account`)
|
|
43
66
|
}
|
|
44
67
|
const stackName = foundationRegionStackName(target.region)
|
|
45
|
-
const
|
|
68
|
+
const stack = regionStack(aws, target)
|
|
69
|
+
const installed = smsNumberOf(stack)
|
|
70
|
+
if (installed.numberType === numberType && installed.arn && helpMessage !== undefined && helpMessage !== stackParameter(stack, 'SmsHelpMessage')) {
|
|
71
|
+
// Only the HELP reply changes: the number, its type and its registration stay as they are.
|
|
72
|
+
await applyRegionFoundation({ aws, stackName, templateFile: FOUNDATION_REGION_TEMPLATE, overrides: { SmsHelpMessage: helpMessage }, wait, log })
|
|
73
|
+
log(`HELP reply updated on the ${numberType} SMS number: ${helpMessage}`)
|
|
74
|
+
return { arn: installed.arn, numberType, accountId: target.accountId, region: target.region, changed: true }
|
|
75
|
+
}
|
|
46
76
|
if (installed.numberType === numberType && installed.arn) {
|
|
47
77
|
log(`${target.accountId} ${target.region} already has a ${numberType} SMS number.`)
|
|
48
78
|
logSmsNextSteps(log, { arn: installed.arn, env: target.env, numberType })
|
|
@@ -64,9 +94,10 @@ async function smsSetup(flags, { exec = defaultExec, api = jsonApiCall, confirm
|
|
|
64
94
|
log('Nothing changed.')
|
|
65
95
|
return null
|
|
66
96
|
}
|
|
67
|
-
await applyRegionFoundation({ aws, stackName, templateFile: FOUNDATION_REGION_TEMPLATE, overrides: { SmsOriginationNumberType: numberType }, wait, log })
|
|
97
|
+
await applyRegionFoundation({ aws, stackName, templateFile: FOUNDATION_REGION_TEMPLATE, overrides: { SmsOriginationNumberType: numberType, ...(helpMessage !== undefined ? { SmsHelpMessage: helpMessage } : {}) }, wait, log })
|
|
68
98
|
const { arn } = smsNumberOf(regionStack(aws, target))
|
|
69
99
|
if (!arn) throw new Error(`${stackName} updated but reports no SmsOriginationIdentityArn; check the stack in the CloudFormation console`)
|
|
100
|
+
if (helpMessage !== undefined) log(`HELP reply: ${helpMessage}`)
|
|
70
101
|
logSmsNextSteps(log, { arn, env: target.env, numberType })
|
|
71
102
|
return { arn, numberType, accountId: target.accountId, region: target.region, changed: true }
|
|
72
103
|
}
|