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 CHANGED
@@ -1,6 +1,8 @@
1
1
  # saaslayer
2
2
 
3
- SaaSLayer onboarding CLI. Bootstrap an AWS account for the SaaSLayer control plane and register a service's permissions manifest.
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. The `init` command shells out to the [AWS CLI](https://aws.amazon.com/cli/), which must be installed and authenticated.
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. A raw key is written
272
- only to --output (0600); revoke needs --reason; a revoked grant or root comes back only with --reason.
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. Binds it to your active project by
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 into your connected account. --services/--module and --set take catalog module
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. Add permissionsDirectMode.readers and environments.<env>.settings yourself.
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, app callbacks and passkeys registered against the current host, so it is refused
469
- (LOGIN_DOMAIN_HANDOFF_REQUIRED, listing them) unless --confirm-domain names the current host; the issuer does
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.0",
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
@@ -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
  }
@@ -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 { chooseInstance, refOf } = require('../user-service-instance')
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
- const deployment = await resolveDeployment(flags)
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)
@@ -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 {
@@ -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, dev only, simulator)
33
- * sending number on the region foundation of the env's account and region. Returns null when the prompt is declined.
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 installed = smsNumberOf(regionStack(aws, target))
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
  }