saaslayer 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +132 -16
  2. package/bin/saaslayer.js +387 -61
  3. package/package.json +3 -2
  4. package/src/api-client.js +37 -1
  5. package/src/aws-sigv4.js +74 -26
  6. package/src/cognito-user-api.js +80 -0
  7. package/src/commands/access-admins.js +2 -2
  8. package/src/commands/account-email.js +43 -0
  9. package/src/commands/admin-allowlist.js +65 -0
  10. package/src/commands/api-keys.js +83 -0
  11. package/src/commands/audit.js +77 -0
  12. package/src/commands/aws.js +355 -82
  13. package/src/commands/binding-handoff.js +174 -0
  14. package/src/commands/bindings.js +111 -0
  15. package/src/commands/catalog.js +30 -3
  16. package/src/commands/deploy.js +33 -10
  17. package/src/commands/env-export.js +58 -0
  18. package/src/commands/first-admin.js +15 -4
  19. package/src/commands/foundation.js +75 -117
  20. package/src/commands/hooks.js +271 -0
  21. package/src/commands/integration-credentials.js +1 -1
  22. package/src/commands/lifecycle.js +149 -24
  23. package/src/commands/login-domain.js +259 -0
  24. package/src/commands/login.js +53 -16
  25. package/src/commands/org-members.js +109 -0
  26. package/src/commands/permission-orgs.js +80 -0
  27. package/src/commands/release-manifest.js +17 -8
  28. package/src/commands/service-principals.js +42 -5
  29. package/src/commands/settings.js +21 -5
  30. package/src/commands/sms-registration.js +182 -0
  31. package/src/commands/sms.js +178 -0
  32. package/src/commands/social.js +265 -0
  33. package/src/commands/support-staff.js +72 -0
  34. package/src/commands/trust-policies.js +172 -0
  35. package/src/commands/users-management.js +2 -20
  36. package/src/commands/users.js +56 -11
  37. package/src/commands/versions.js +61 -0
  38. package/src/connection-proof.js +41 -0
  39. package/src/deployment-api-auth.js +166 -8
  40. package/src/deployments.js +1 -1
  41. package/src/foundation-change-set.js +180 -0
  42. package/src/foundation-home.js +121 -0
  43. package/src/foundation-template.js +51 -10
  44. package/src/foundation-trust-write.js +379 -0
  45. package/src/iam-session.js +14 -8
  46. package/src/login-domain.js +139 -0
  47. package/src/login-methods.js +118 -0
  48. package/src/module-catalog.js +3 -2
  49. package/src/permissions-request.js +15 -9
  50. package/src/release-manifest.js +11 -4
  51. package/src/scope.js +3 -1
  52. package/src/settings.js +85 -13
  53. package/src/sms/number.js +37 -0
  54. package/src/sms/registration-fields.js +167 -0
  55. package/src/sms/registration-validate.js +151 -0
  56. package/src/sms/registration.js +216 -0
  57. package/src/sms/release.js +55 -0
  58. package/src/sms/scope.js +86 -0
  59. package/src/sms/status.js +181 -0
  60. package/src/ssm-api.js +31 -0
  61. package/src/trust-entries.js +350 -0
  62. package/src/user-service-instance.js +27 -0
  63. package/src/users-api.js +55 -8
  64. package/src/users-import/checkpoint.js +76 -0
  65. package/src/users-import/import.js +233 -24
  66. package/src/versions.js +80 -0
  67. package/templates/saaslayer-foundation-region.yml +45 -1
  68. package/templates/saaslayer-foundation.yml +747 -296
package/bin/saaslayer.js CHANGED
@@ -30,11 +30,12 @@ function parseArgs(argv) {
30
30
  const HELP = `saaslayer — SaaSLayer onboarding CLI
31
31
 
32
32
  Usage:
33
- saaslayer init --control-plane-account <12-digit> --external-id <secret> [--stack-name NAME]
33
+ saaslayer init --control-plane-account <12-digit> --external-id <id> --control-plane-id <id> [--stack-name NAME]
34
34
  [--region REGION] [--stack-name-prefix sl-] [--org-id ID] [--template PATH] [--dry-run]
35
- Deploy the SaaSLayer foundation stack (3 IAM roles + permissions boundary + artifact
36
- bucket) into the caller's AWS account, trusting the SaaSLayer control plane.
37
- Uses the bundled templates/saaslayer-foundation.yml. --dry-run validates only.
35
+ Create the SaaSLayer foundation stack (3 IAM roles + permissions boundary) in the caller's AWS account, with one
36
+ trust entry for that SaaSLayer control plane (its control-plane account, trust identifier and control-plane id) and
37
+ the caller as the account's connection authorizer. Refuses an account that already has a foundation (use
38
+ saaslayer foundation upgrade). Uses the bundled templates/saaslayer-foundation.yml. --dry-run validates only.
38
39
 
39
40
  saaslayer foundation status [--region R] [--profile P] [--stack-name saaslayer-foundation] [--only account|region]
40
41
  Show each installed foundation stack (saaslayer-foundation + saaslayer-foundation-<region>): its status,
@@ -42,20 +43,26 @@ Usage:
42
43
  saaslayer foundation upgrade [--region R] [--profile P] [--stack-name saaslayer-foundation] [--only account|region]
43
44
  [--dry-run] [--yes] [--allow-replacement]
44
45
  Upgrade the installed foundation stacks in place to this CLI's bundled templates with YOUR AWS credentials.
45
- Builds a CloudFormation change set that keeps every existing parameter value (the ExternalId is never
46
+ The account stack is upgraded in its home region (where it was first created), with its trust re-rendered from
47
+ its own TrustEntries; a foundation that still trusts a single ExternalId converts through saaslayer aws connect.
48
+ Builds a CloudFormation change set that keeps every existing parameter value (trust identifiers are never
46
49
  re-entered or printed; new parameters take their template default), prints the version change and each
47
50
  resource change, then executes after you confirm and reads the new version back. Refuses a stack that is
48
51
  not in a stable state or that runs a newer version than this CLI. A change that replaces a resource or
49
52
  removes an IAM role, the permissions boundary or the artifact bucket needs --allow-replacement.
50
- --dry-run shows the change set and deletes it; --yes skips the confirmation. --region is where the stacks
51
- live (default $AWS_REGION, else us-east-1). The region stack is skipped when it is not installed.
53
+ --dry-run shows the change set and deletes it; --yes skips the confirmation. --region is the region stack's region
54
+ (default $AWS_REGION, else us-east-1). The region stack is skipped when it is not installed.
52
55
  After the upgrade (or when nothing changed) the control plane re-reads the account's foundation through its
53
56
  own trust, as your saaslayer login (no AWS credentials are sent), so the console and deploys see the new
54
57
  version; if that fails the upgrade still stands and the console's "check again" re-reads it.
55
58
 
56
- saaslayer signup [--config-url URL] [--email E --password P]
57
- Create a SaaSLayer account (allowlist-gated) and log in.
59
+ saaslayer signup [--config-url URL] [--email E --password P] [--code C | --resend]
60
+ Create a SaaSLayer account (allowlist-gated), confirm the code emailed to you (prompted, or --code), and log in.
61
+ Without a terminal it stops once the code is sent; finish with --code. --resend emails a new code.
58
62
  --config-url (or $SAASLAYER_CONFIG_URL) is the control-plane API; default https://api.saaslayer.com.
63
+ saaslayer account verify-email [--code C]
64
+ Prove the logged-in account owns its email (a code is emailed; type it, or pass --code). Org owners can add
65
+ only accounts whose email is verified.
59
66
  saaslayer login [--email E --password P] [--config-url URL | --user-pool-id ID --client-id ID --region R]
60
67
  Log in to your SaaSLayer account (Cognito SRP) and cache tokens in ~/.saaslayer.
61
68
  Email/password fall back to $SAASLAYER_EMAIL/$SAASLAYER_PASSWORD, else prompt.
@@ -65,7 +72,8 @@ Usage:
65
72
  Log in to a deployment's user-service as an access admin. The pool, client and API bases are
66
73
  discovered from the deployment's public outputs (an env name resolves the active project's deployment).
67
74
  Kept separate from your control-plane login, which stays logged in.
68
- saaslayer whoami Show the current logged-in account, its control plane, and the active org/project.
75
+ saaslayer whoami Show the current logged-in account, its account id (share it with an org owner to be added
76
+ to their org), its control plane, and the active org/project.
69
77
  saaslayer context [--json] [--profile AWS_PROFILE] Show the control-plane account, the deployment login, the AWS
70
78
  profile, org and project (and where each came from) and every cached identity.
71
79
  Tokens are never printed.
@@ -106,8 +114,10 @@ Usage:
106
114
  saaslayer permissions owner bootstrap <product> --org ORG --user USER --api-base URL (--iam PRINCIPAL | --token KEY)
107
115
  Make a member the FIRST owner of an org (refused once the org has an owner). Needs saaslayer:catalog:owner:bootstrap
108
116
  (a machine: the owners:bootstrap scope and a grant of it).
109
- saaslayer permissions owner reconcile <product> --api-base URL (--iam PRINCIPAL | --token KEY) [--org ORG] [--apply]
110
- Compare each org's owner counter with a live recount; --apply repairs drift. Needs saaslayer:catalog:owner:reconcile
117
+ saaslayer permissions owner reconcile <product> --api-base URL (--iam PRINCIPAL | --token KEY) [--org ORG] [--complete-owners] [--apply]
118
+ Compare each org's owner counter with a live recount; --apply repairs drift. --complete-owners also grants the
119
+ product's ownerRole to every org's platform owners (saaslayer:org-owner) who lack it and prints the counts
120
+ (dry run unless --apply; resumes from its checkpoint). Needs saaslayer:catalog:owner:reconcile
111
121
  (a machine: the catalog:write scope and a grant of it).
112
122
  saaslayer permissions service-principal roles (<id> | --machine PRINCIPAL) --api-base URL (--token KEY | --iam PRINCIPAL)
113
123
  saaslayer permissions service-principal assign (<id> | --machine PRINCIPAL) --role ROLE [--scope S] --api-base URL (--token KEY | --iam PRINCIPAL)
@@ -116,6 +126,11 @@ Usage:
116
126
  mapped principal (iam.PRINCIPAL), which acts with its scopes AND these grants.
117
127
  Grants are deployment-wide unless --scope names an org scope. Needs roles:role:{assign,unassign} +
118
128
  identity:principal:read.
129
+ saaslayer permissions service-principal verifier-key create <id> [--ssm-parameter PATH [--region R] [--profile P]] --api-base URL (--token KEY | --iam PRINCIPAL)
130
+ Issue service account <id> (created, owned by you, when missing) a deployment-wide key whose only permission is
131
+ verifying API keys, for a backend that accepts its users' keys. Prints the key once; --ssm-parameter also writes it
132
+ to that SecureString (replacing the key it held) with your AWS credentials. Needs keys:api-key:issue-verifier.
133
+ Rotate: create a new key, deploy it, then revoke the old one (DELETE /api-keys/<keyId>).
119
134
  saaslayer permissions machine-trust list | get <principalId> --api-base URL [auth]
120
135
  saaslayer permissions machine-trust declare <principalId> --role-arn ARN --scope S [--scope S2] --api-base URL [auth]
121
136
  saaslayer permissions machine-trust update <principalId> [--role-arn ARN] [--scope S …] [--expected-revision N] --api-base URL [auth]
@@ -134,11 +149,53 @@ Usage:
134
149
  saaslayer permissions access-admins status | cancel <transferId> --api-base URL [auth]
135
150
  saaslayer permissions access-admins accept <transferId> | activate --api-base URL [your deployment login]
136
151
  The deployment's administrators (saaslayer:access-admin). At least one usable human administrator
137
- always remains — enabled, and activated: signed in themselves with a verified email; machines never count — so
138
- the last one can't be revoked, disabled, deleted or unverified (409 LAST_ADMIN). offer grants <suid> the role at
139
- once; it counts once they accept with their own deployment login. --mode transfer (default) then removes you,
152
+ always remains — enabled, and activated: signed in themselves with a verified email or phone
153
+ number; machines never count — so the last one can't be revoked, disabled, deleted or unverified (409
154
+ LAST_ADMIN). offer grants <suid> the role at once; it counts once they accept with their own deployment login. --mode transfer (default) then removes you,
140
155
  add keeps you. An interrupted accept leaves both admins; accept again to finish. cancel (pending offers, by you)
141
156
  revokes the grant. activate records your own activation. See services/permissions-service/user-docs/access-admins.md.
157
+ saaslayer permissions support-staff grant <suid> --mode view-only|act-as [--expires-at ISO] --api-base URL [your deployment login]
158
+ saaslayer permissions support-staff revoke <suid> --mode view-only|act-as --api-base URL [your deployment login]
159
+ saaslayer permissions support-staff list --api-base URL [auth]
160
+ The deployment's support staff: people who view as a member of any org without belonging to it
161
+ (saaslayer:support-view-only refuses every write while viewing; saaslayer:support-act-as also allows them,
162
+ reserved operations stay refused). Only an access admin signed in themselves grants or revokes them
163
+ (--id-token-file or a deployment login; never an API key or IAM machine). Find a suid with saaslayer users get --email.
164
+ saaslayer permissions orgs create <name> [--id ID] [--description TEXT] --api-base URL [auth]
165
+ saaslayer permissions orgs members add <orgId> --user <suid> [--email E] --api-base URL [auth]
166
+ A deployment's runtime orgs (not your SaaSLayer account org — that is saaslayer org). create makes an org
167
+ (--id picks its id, else one is generated); members add puts a user in it. Then permissions owner bootstrap
168
+ makes a member its first owner. Needs orgs:write (an access admin holds it).
169
+ saaslayer permissions orgs hook-joinable set <orgId> --consumer <user-service@<deploymentId>/<instance>> --role <roleId> [--role …] --api-base URL [auth]
170
+ saaslayer permissions orgs hook-joinable disable <orgId> --api-base URL [auth]
171
+ Which roles one user-service instance's lifecycle hook may grant in the org (exact role ids, at most 20; privileged
172
+ roles are refused). set publishes the list for that --consumer; disable stops the org's hooks granting any role.
173
+ Only an owner of the org, signed in as themselves (deployment login), may change it.
174
+ saaslayer permissions api-keys create --user OWNER --name N --allow service:resource:action [--allow …] [--deny …]
175
+ [--scope ORG] [--expires-at ISO] (--deployment ID | --api-base URL) [auth]
176
+ saaslayer permissions api-keys list [--user OWNER] | get <keyId> | revoke <keyId> (--deployment ID | --api-base URL) [auth]
177
+ Scoped API keys on the deployment's permissions API (for deployments without a console, e.g. permissions-only with an
178
+ outside login provider). A key holds exactly its --allow tuples minus --deny (product:service:resource:action also
179
+ accepted), never more than the caller holds. create prints the key once; revoke stops it authenticating at once.
180
+ saaslayer permissions trust-policies list | get <policyId> (--deployment ID | --api-base URL) [auth]
181
+ saaslayer permissions trust-policies add <issuerUrl> --audience A [--audience B] (--subject S … | --allow-any-subject)
182
+ [--principal-claim sub] [--jwks-uri URL] [--description D] (--deployment ID | --api-base URL) [auth]
183
+ saaslayer permissions trust-policies update <policyId> [--audience A …] [--subject S … | --allow-any-subject] [--jwks-uri URL] [--description D] …
184
+ saaslayer permissions trust-policies disable | enable <policyId> (--deployment ID | --api-base URL) [auth]
185
+ saaslayer permissions trust-policies delete <policyId> --reason TEXT [--yes] (--deployment ID | --api-base URL) [auth]
186
+ The external login providers (OIDC issuers: your Cognito pool, Auth0, Okta, …) whose ID tokens the deployment accepts.
187
+ Needs an access admin (or a trust-manager holder). <issuerUrl> is the EXACT iss of the provider's ID tokens: add
188
+ refuses unless <issuerUrl>/.well-known/openid-configuration names it. Providers added here are external (people get
189
+ ext_ principal ids) and never impersonate; the deployment's own pool is read-only (409 FIRST_PARTY_POLICY). A change
190
+ that would leave no usable access admin a way to sign in is refused (409 LAST_ADMIN_PROVIDER). delete asks you to
191
+ type the issuer (--yes confirms). See docs/permissions-only.md.
192
+ External ID token (saaslayer permissions commands):
193
+ --id-token-file FILE (or $SAASLAYER_ID_TOKEN) sends the raw OIDC ID token from your own login provider as the
194
+ credential — e.g. \`saaslayer permissions access-admins activate --id-token-file id.jwt --deployment dep_…\`. It goes
195
+ only to a pinned host: --deployment <dep_id|env> (its permissions API, read through the control plane with your
196
+ \`saaslayer login\`; commands that need --api-base must name that same API) or an https --api-base whose host you
197
+ type to confirm (--yes confirms). Expired tokens and access tokens are refused locally; never combined with --iam,
198
+ --token, $SAASLAYER_TOKEN or a deployment login; the token is never printed. Keep the file chmod 600.
142
199
 
143
200
  saaslayer users export --provider cognito --user-pool-id POOL --region R [--profile P]
144
201
  [--account-attribute ATTR] [--account-name-attribute ATTR] [--role-map map.js] --out manifest.json
@@ -147,10 +204,13 @@ Usage:
147
204
  exported; the file holds personal data.
148
205
  saaslayer users import --manifest manifest.json --user-pool-id POOL --region R [--profile P]
149
206
  [--api-base URL --product P (--iam PRINCIPAL | --token KEY) [--logs-role-arn ARN] --apply] [--report FILE]
150
- Dry run by default: prints what would be created or linked. --apply imports new users through a Cognito CSV
151
- import job (reset required on first sign-in, no emails sent), stamps their SaaSLayer id + default org, then
152
- creates each user's permissions principal and org, adds members and bootstraps the first Owner (IAM scopes users:write + orgs:write + owners:bootstrap).
153
- Idempotent: re-run to retry failures. See docs/users-import.md.
207
+ Dry run by default: prints what would be created or linked (with --iam, also checks the profile permissions and
208
+ counts profiles). --apply imports new users through a Cognito CSV import job (reset required on first sign-in, no
209
+ emails sent), stamps their SaaSLayer id + default org, creates each person's user-service profile (no email, no
210
+ password), then each permissions principal and org, adds members and bootstraps the first Owner. --apply needs --iam
211
+ (--token: dry run only; IAM scopes users:write + users:read + users:write-reserved + orgs:write + owners:bootstrap, checked for user-service
212
+ before anything is written). Idempotent: re-run to retry failures; resumes from <manifest>.profiles-checkpoint.json.
213
+ Exits 1 when any user or profile needs attention. See docs/users-import.md.
154
214
  saaslayer users <command> … [target] [auth]
155
215
  Administer a deployment's users through its user-service /api/users (see services/user-service/docs/users.md).
156
216
  [auth] = the current deployment login (\`saaslayer login --deployment\`; pick one with --deployment/--as), or
@@ -171,12 +231,19 @@ Usage:
171
231
  saaslayer users list (--email E | --default-org ORG) [--limit N] [--cursor C]
172
232
  Users holding an email, or whose default org is ORG; prints nextCursor for the next page.
173
233
  saaslayer users update <user> [--name N] [--attr name=value …]
174
- Profile attributes (name, given_name, family_name, locale, zoneinfo, picture).
234
+ Profile attributes (name, given_name, family_name, locale, zoneinfo, picture), or reserved ones (email,
235
+ email_verified=true|false, soid) through the reserved route, which needs saaslayer:users:account:update-reserved.
236
+ Profile and reserved attributes are separate updates; one command never mixes them.
175
237
  saaslayer users disable <user> | saaslayer users enable <user>
176
238
  Sign the user out everywhere and refuse sign-in / allow it again (grants and credentials are kept). The last
177
239
  usable owner of an org can't be disabled.
178
240
  saaslayer users delete <suid> --yes [--email E]
179
241
  GDPR delete everywhere (sign-in, passwordless data, profile). --email finds a user that was never projected.
242
+ First erases the person from the audit and their membership profile copies, then removes their own personal
243
+ workspace; prints auditIdentities (requested|done|not-configured), profileCopies (removed|not-configured) and
244
+ personalWorkspace (removed|none|not-configured). If that fails nothing is deleted:
245
+ run it again. After a finished delete, erase an address user-service never held with
246
+ saaslayer audit erase <suid> --email E.
180
247
  saaslayer users reset-password <user>
181
248
  Cognito mails a reset code to the verified email; the current password stops working.
182
249
  saaslayer users set-password <user> --password-stdin [--temporary]
@@ -203,75 +270,158 @@ Usage:
203
270
  Purposes: account-read, account-provisioning, account-import, account-administration, account-deletion,
204
271
  account-sensitive, account-recovery (humans only), reconciliation, config, email-authoring. A raw key is written
205
272
  only to --output (0600); revoke needs --reason; a revoked grant or root comes back only with --reason.
273
+ saaslayer audit erase <suid> [--email E …] (--iam PRINCIPAL [--region R] [--profile P] | --token KEY)
274
+ (--api-base PERMISSIONS_URL | --deployment <dep_id|env> [--config-url URL] | --discovery-url URL)
275
+ GDPR erasure of a person from the deployment's audit trail: their name and email come off every audit entry that
276
+ names them, and each --email address (repeat, at most 50) comes off the invitation entries holding it; ids and
277
+ events stay. Invitation entries are found only by the addresses you pass: give every address the person had,
278
+ including any the deployment never knew.
279
+ For operators, and to retry the erasure after \`saaslayer users delete\`. Needs the platform-only scope
280
+ audit:person:erase. Prints { personId, status, emails: <count> } (addresses are never printed);
281
+ status requested is finished by the deployment's audit worker within minutes. Safe to run again, with more addresses.
206
282
 
207
283
  Deploy & lifecycle (requires login + a connected AWS account):
208
- saaslayer aws connect --aws-account <id> [--region R] [--org ID] [--org-wide]
284
+ saaslayer aws connect --aws-account <id> [--region R] [--org ID] [--org-wide] [--sms-toll-free [--yes]]
209
285
  Connect your AWS account to an org. Binds it to your active project by
210
- default; --org-wide lets any project in the org deploy into it.
286
+ default; --org-wide lets any project in the org deploy into it. The account foundation lives in one home region
287
+ (created by the first connect); connecting another region adds only that region's stack. --sms-toll-free also installs the account's US
288
+ toll-free SMS sending number (~$2/month, asks first unless --yes) and prints its ARN.
289
+ The org connection is activated by a proof signed with your AWS credentials: you must be one of the account's
290
+ connection authorizers (the first connect makes you one); until then it stays PENDING_PROOF and rerunning resumes it.
291
+ saaslayer aws authorizers <add|remove> <arn> --aws-account <id> [--region R] [--profile P]
292
+ Change who may authorize SaaSLayer org connections to the account (ConnectionAuthorizerArns, stored as path-less
293
+ role ARNs). Run by a current authorizer; the last one cannot be removed.
294
+ saaslayer aws rotate-trust <start|verify|switch|retire|rollback|status> --aws-account <id> [--reason <text>] [--region R] [--org ID] [--profile P]
295
+ Rotate the account's trust identifier for this control plane, with overlap: start (needs --reason) adds a new
296
+ identifier beside the current one, verify checks it assumes, switch moves new operations to it, retire removes the
297
+ old one once no running operation carries it. rollback (before retire) goes back to the current identifier; after
298
+ a switch it waits for the operations already using the new one. Each step is signed with your AWS credentials (a
299
+ 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]
301
+ Install the SMS sending number for phone login on the region foundation of the env's account and region (from
302
+ the project's deployment there, else its connected account), with your own AWS credentials for that account
303
+ (cloud-prem; hosted accounts are not supported yet). Shows the cost (~$2/month) and asks unless --yes. Prints the
304
+ number's ARN and the exact settings command. It cannot send until its registration is approved (AWS review: up to
305
+ 15 business days). --simulator (dev only, refused when the account has staging or prod deployments) installs an
306
+ AWS simulator number instead: it reaches simulator destinations only, and needs no registration.
307
+ saaslayer sms register --env <env> [--region R] [--file registration.json] [--profile P]
308
+ Register the account's toll-free sending number with AWS (cloud-prem, with YOUR AWS credentials for the env's
309
+ account): asks for (or reads from --file) the company, website, public privacy-policy and terms URLs, contact,
310
+ opt-in description + PNG screenshot and message samples (naming the brand, with HELP and STOP), checks them,
311
+ then creates the registration, fills it, associates the number and submits. AWS review: up to 15 business days.
312
+ Re-running resumes the same registration; after AWS asks for updates it shows the reasons, re-asks only the
313
+ flagged fields and resubmits. A submitted, reviewing or complete registration is left as it is.
314
+ saaslayer sms status --env <env> [--region R] [--json] [--profile P]
315
+ The sending number, registration state, sandbox or production, spend limit and what is still missing (as the
316
+ deploy's sms.* readiness codes), with the console links and values for the production-access and spend-limit
317
+ requests (AWS has no API for either). An unfinished sms release is moved forward from the stack's actual state
318
+ and shown with the command that resumes it.
319
+ saaslayer sms release --env E [--region R] [--yes] [--profile P]
320
+ Retire the account-and-region SMS number: takes the control plane's SMS lock (deploys that set the number are
321
+ refused meanwhile), checks that no deployment in any project still uses it, asks, removes the number (billing
322
+ stops), then deletes its registration. Every step is recorded; re-run it from any machine to resume (sms status
323
+ also records a number removal that landed).
211
324
  saaslayer project use <id> Set the active project for deploy/status (a project id tnt_… or a customer id).
325
+ saaslayer org members list [--org ID]
326
+ saaslayer org members add --user <accountId> [--role deployer] [--org ID] [--yes]
327
+ saaslayer org members remove --user <accountId> [--org ID]
328
+ saaslayer org members set-role --user <accountId> --role deployer|member [--org ID]
329
+ Org owners only: manage the org's members by account id (the teammate prints it with \`saaslayer whoami\`). add
330
+ shows the account's email and asks for it to be typed back unless --yes; an account whose email is not verified
331
+ is refused (EMAIL_NOT_PROVEN). A deployer may update deployments and cancel its own runs; owner powers stay with
332
+ owners. remove revokes the deployer role, then the membership. --org defaults to the active org.
212
333
  saaslayer project destroy [<id>] [--yes]
213
334
  Delete a project (the active one by default) and release its public name for reuse. Refused while any of its
214
335
  deployments is live: destroy each with \`saaslayer destroy\` first. Asks for the id to be typed unless --yes.
215
336
  saaslayer stacks List the modules a project can deploy: module id, regions, required
216
337
  modules and stable outputs.
338
+ saaslayer versions [--project ID] [--json]
339
+ The versions a deployment may move to, highest first: the channels on each (stable), breaking releases, and
340
+ which of the project's deployments run each one (a deployment on an unversioned commit is listed apart).
217
341
  saaslayer deploy [--services a,b | --module M ...] [--set MODULE.Setting=VALUE ...] [--settings FILE] [--env prod]
218
- [--region R] [--target ACCT] [--commit-sha SHA] [--admin-email E] [--yes]
342
+ [--region R] [--target ACCT] [--version X.Y.Z | --channel stable] [--admin-email E | --admin-phone-number +E164] [--yes]
219
343
  Deploy the project's modules into your connected account. --services/--module and --set take catalog module
220
344
  ids (\`saaslayer stacks\`, e.g. permissions-service); an unknown id or a missing required module is refused before
221
345
  anything is sent. --settings FILE is { "<module>": { "<Setting>": value } }; --set overrides it (--param is
222
- the same as --set). The settings are checked against the schema of the release being deployed (--commit-sha,
223
- else the default release \`saaslayer stacks\` reports) before anything is sent, and the create-only ones are
224
- listed; the control plane always checks them too. A secret takes ssm:/<parameter name>.
346
+ the same as --set). --version (\`saaslayer versions\`) or --channel names the release to start on; without either
347
+ the control plane picks its default (stable). With neither, the settings are checked against the schema of the
348
+ default release \`saaslayer stacks\` reports before anything is sent and the create-only ones are listed; the
349
+ control plane always checks them too (it alone checks them for a --version). A secret takes ssm:/<parameter name>.
225
350
  Asks before creating anything, then confirms any cost estimate (--yes answers both; required non-interactively).
351
+ Sign-in: user-service.PrimaryLoginMethod (email, the default, or phone) is permanent. Only the opposite method can be
352
+ added as a second sign-in pool: EnablePhoneLogin on an email primary, EnableEmailLogin on a phone primary
353
+ (EnableEmailLogin=false means no email pool is added, not that sign-in is off); once accepted it is never turned off.
354
+ Phone sign-in needs user-service.PhoneSmsAllowedCountries (e.g. US,CA) and passes the SMS setup check first
355
+ (\`saaslayer sms status\`; a failed check saves nothing). A phone primary names its first admin by
356
+ --admin-phone-number (E.164; shown masked). The permanent primary, added pools, countries and SMS/Cognito cost
357
+ categories are printed before the confirm.
226
358
  saaslayer status [--project ID] [--env E] [--region R]
227
359
  Show the deployed instances of a project. --project takes a project id (tnt_…) or a customer id. Every scoped
228
360
  command prints \`scope: org=… project=… env=… (from: …)\` on stderr first (--json omits it); an empty result
229
361
  lists the projects you can see that do have deployments.
230
- saaslayer service add <service> [--region R]
362
+ saaslayer service add <service> [--region R] [--param MODULE.Setting=VALUE] [--settings FILE]
231
363
  saaslayer service remove <service> --data-custody delete|retain [--region R] [--reason TEXT] [--yes]
232
364
  Add or remove a single service on an existing deployment. A protected env (staging, prod) removal needs --reason
233
365
  and the service name typed to confirm (--yes confirms it).
234
- saaslayer update --commit-sha SHA [--env E] [--region R] [--reason TEXT] [--force]
235
- Roll an existing deployment's services to a new release (upgrade; deploy only creates). Protected envs
236
- (staging, prod) need --reason; --force updates past the drift gate (audited with the reason).
366
+ saaslayer update --version X.Y.Z | --channel stable [--env E] [--region R] [--reason TEXT] [--force]
367
+ Roll an existing deployment's services to a version (upgrade; deploy only creates); a lower version is a
368
+ rollback. --channel moves to what the channel points at now (once, not a subscription). \`saaslayer versions\`
369
+ lists them. Protected envs (staging, prod) need --reason; --force updates past the drift gate (audited with the
370
+ reason). --commit-sha SHA still works until the control plane refuses it.
371
+ saaslayer update --retry [--env E] [--region R] [--reason TEXT] [--no-wait]
372
+ Retry the deployment at its deployed release with its stored settings (nothing is rewritten): resumes an accepted
373
+ sign-in method that failed or is not ready yet (\`saaslayer settings get\` shows why and what to fix first). An
374
+ accepted method is never turned off. Nothing to resume answers "nothing to retry". Protected envs need --reason.
237
375
  saaslayer migrations approve --env E [--region R] --run <runId> --reason TEXT [--no-wait]
238
376
  Approve the migrations an update left awaiting approval (a protected env's destructive contract migrations, e.g. a
239
377
  rename's retire step): \`saaslayer update\` prints the run id. The control plane records you and the reason.
240
378
  saaslayer update --param MODULE.Setting=VALUE ... [--env E] [--region R] [--reason TEXT]
241
379
  Change settings, keeping the current release: --param goes through the settings route, exactly like
242
- \`saaslayer settings set --set\`. --commit-sha and --param cannot be combined: move the release, then set.
380
+ \`saaslayer settings set --set\`. A release (--version, --channel) and --param cannot be combined: move it, then set.
243
381
  saaslayer update --manifest FILE [--env E] [--region R] [--settings F] [--reason TEXT] [--force] [--dry-run]
244
382
  Promote a tested release manifest to this environment. Preflight first, nothing sent on any problem: the CLI
245
383
  version the release was tested with, every deployed module in the bundle, each module's published settings
246
384
  contract matching the manifest's sha256, schema transitions from the deployed revision (a set setting the target
247
385
  drops or refuses, a changed create-only default), the environment's settings (environments.<env>.settings in
248
386
  the manifest, or --settings) against the target contracts, direct-mode readers (permissionsDirectMode.readers) against
249
- what the release writes, and --reason for staging/prod. Then moves the release through the update route, waits,
250
- and writes the settings that differ through the settings route. --dry-run prints the preflight and plan only.
387
+ what the release writes, and --reason for staging/prod. Then moves the release through the update route (by
388
+ bundle.version when the manifest has one), waits, and writes the settings that differ through the settings route.
389
+ --dry-run prints the preflight and plan only.
251
390
  saaslayer release-manifest create --env E [--region R] [--out FILE] [--name NAME]
252
- Record a tested deployment as a release manifest: its revision, each module's settings-contract sha256, this
253
- CLI's version and what its permissions service writes. Add permissionsDirectMode.readers and environments.<env>.settings yourself.
391
+ Record a tested deployment as a release manifest: its version (bundle.version; a deployment on an unversioned
392
+ 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.
254
394
  saaslayer settings schema --module M [--revision SHA] [--env E] [--json]
255
395
  Print a module's published settings schema: type, update behavior (update-safe | create-only), kind
256
396
  (deployment | runtime), secret, billing impact, default. Without --revision, the revision the selected
257
397
  deployment runs.
258
398
  saaslayer settings get --env E [--region R] [--json]
259
399
  Print a deployment's settings: value and source (set | default | unset), the settings revision and any
260
- pending operation. A secret shows only whether it is set.
400
+ pending operation. A secret shows only whether it is set. With phone sign-in requested, also each sign-in
401
+ method's stage (accepted, provisioning, failed, created, ready — only ready signs in), why it is not ready and
402
+ the next command (sms setup, first-admin resend, update --retry).
261
403
  saaslayer settings set --env E (--set MODULE.Setting=VALUE ... | --file settings.<env>.json) [--reason TEXT] [--no-wait]
262
404
  Change settings (null in a file resets one to its default; omitted settings are untouched). Checked against
263
405
  the deployment's schema before anything is sent: create-only, runtime and unknown settings are refused, and
264
406
  a secret takes a reference (ssm:/<parameter name>, or { "ssmParameter": "/<name>" } in a file), never the
265
407
  value. Sent with the settings revision just read, so a concurrent change is refused (re-read and retry).
266
408
  A billing change and the protected envs (staging, prod) need --reason. Waits for the update operation.
409
+ The login-domain settings (user-service.CustomCognitoDomainName, CustomCognitoDomainCertificateArn,
410
+ ActiveLoginDomain) are set by saaslayer login-domain and refused here (LOGIN_DOMAIN_MANAGED_SETTING).
267
411
  saaslayer settings diff --env A --env B [--manifest release.json] [--json]
268
412
  Compare two environments: module revisions, differing settings (create-only and secret marked; secrets as
269
413
  set/unset) and each settings revision, plus the gaps between them. With --manifest, each environment is also
270
414
  checked against the release: modules outside or behind the bundle, bundle modules it lacks, the
271
415
  permission-doc format it writes, and its deployed values against environments.<env>.settings.
272
416
  Every settings command prints its scope and the deployment id on stderr (--json omits them).
273
- saaslayer destroy --data-custody delete|retain [--region R] [--yes]
274
- Tear down the project's deployment (typed-name confirmation).
417
+ saaslayer destroy --data-custody delete|retain [--region R] [--reason TEXT] [--yes]
418
+ saaslayer destroy --purge-retained --reason TEXT [--region R] [--yes]
419
+ Tear down the project's deployment (typed-name confirmation; --yes confirms it). delete removes its data
420
+ (irreversible); retain keeps its data and leaves the deployment RETIRED: retained resources remain your
421
+ organization's responsibility and cost until purged. --purge-retained deletes what a retain destroy kept
422
+ (irreversible) and takes no --data-custody. A protected env (staging, prod) and every purge need --reason.
423
+ A delete destroy or purge prints its purgeResult: complete, pending (residual items AWS finishes later, with
424
+ when) or incomplete (failed items and items outside SaaSLayer custody).
275
425
  saaslayer operations get <operationId> [--deployment ID] [--json]
276
426
  saaslayer operations watch <operationId> [--deployment ID] [--interval SECONDS]
277
427
  Show (get) or wait for (watch) an operation: a deploy, update, service add/remove or destroy and each
@@ -284,11 +434,70 @@ Deploy & lifecycle (requires login + a connected AWS account):
284
434
  Cancel an in-flight operation: stops its run and releases the deployment for the next command. The deployment's
285
435
  activity records who cancelled it and the reason. A finished operation is refused.
286
436
  saaslayer first-admin resend [--deployment ID | --env E --region R] [--reason TEXT] [--no-wait]
287
- saaslayer first-admin recover --email E --reason TEXT [--suid ID] [--deployment ID | --env E --region R] [--no-wait]
437
+ saaslayer first-admin recover (--email E | --phone-number +E164) --reason TEXT [--suid ID] [--deployment ID | --env E --region R] [--no-wait]
288
438
  The deployment's first administrator (needs saaslayer:deployer:deployment:admin-bootstrap; org owners hold it).
289
439
  resend delivers the designated admin's first sign-in again (the only rotation of its temporary password;
290
- refused once they activated). recover designates a new first admin (--email, optional --suid) and is refused
440
+ refused once they activated). recover designates a new first admin (--email; --phone-number on a phone-primary
441
+ deployment; optional --suid) and is refused
291
442
  with ADMIN_EXISTS while any usable access admin remains. Both wait for their operation.
443
+ saaslayer social status [--env E] [--region R] [--service REF] [--json]
444
+ One user-service instance's social sign-in: each provider on or off, its client id and hosted domains, the
445
+ callback/logout URLs and app origins, and the redirect URI and JavaScript origin to paste into the Google console.
446
+ --service names the instance (user-service or user-service@<instance>); a deployment with several needs it.
447
+ saaslayer social enable google [--client-id ID] [--client-secret-stdin] [--hosted-domain D ...] [--callback-url URL ...]
448
+ [--app-origin ORIGIN ...] [--env E] [--service REF] [--reason TEXT] [--no-wait]
449
+ saaslayer social rotate-secret google --client-secret-stdin [--env E] [--service REF] [--reason TEXT] [--no-wait]
450
+ saaslayer social disable google [--confirm] [--env E] [--service REF] [--reason TEXT] [--no-wait]
451
+ Change the instance's social sign-in as one request and wait for the deployment run it starts. The client secret
452
+ is read only from stdin (e.g. < secret.txt); it is never a flag and never printed. enable keeps the stored
453
+ client id and secret unless given; each --callback-url / --app-origin / --hosted-domain list replaces the
454
+ stored one. A protected env (staging, prod) needs --reason. disable is refused (SOCIAL_ONLY_USERS_AFFECTED, with
455
+ the count) while users sign in only with that provider, even with --confirm, until they have another method.
456
+ A retry after a dropped connection repeats the same request and answers the same run.
457
+ saaslayer login-domain status [--env E] [--region R] [--service REF] [--json]
458
+ One user-service instance's branded login domain: kind (managed | custom), host and state, the active and
459
+ opaque hosts, the certificate status and whether DNS points correctly, the records a custom domain needs at
460
+ your DNS provider, the redirect URIs to keep registered in each provider console, and the account+region quota.
461
+ saaslayer login-domain provision managed|HOST [--env E] [--service REF] [--reason TEXT] [--no-wait] [--json]
462
+ managed: auth.<space>.saaslayer-cloud.com. HOST: your own (e.g. auth.acme.com); the first call requests its
463
+ certificate and prints the two records to add; run it again once the certificate is ISSUED to start the
464
+ provision run. Provisioning keeps the opaque login domain advertised until activate.
465
+ saaslayer login-domain activate --confirm-domain HOST --reason TEXT [--env E] [--service REF] [--no-wait] [--json]
466
+ saaslayer login-domain deactivate --confirm-domain HOST --reason TEXT [--env E] [--service REF] [--no-wait] [--json]
467
+ 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
471
+ listed redirect and callback is updated. Register the new redirect URI before activate and keep the old one.
472
+ saaslayer login-domain remove [--env E] [--service REF] [--reason TEXT] [--no-wait] [--json]
473
+ Delete the custom login domain, its DNS alias and (for HOST) its certificate, and free its quota slot. Refused
474
+ while it is active: deactivate first. A protected env (staging, prod) needs --reason for every change.
475
+ saaslayer hooks status [--env E] [--region R] [--service REF] [--json]
476
+ One user-service instance's lifecycle hooks: each point's target (URL or Lambda), failure mode and timeout, the
477
+ {org, role} pairs a hook may grant, and the signing-secret key ids (never the secret). --service names the
478
+ instance (user-service or user-service@<instance>); a deployment with several needs it.
479
+ saaslayer hooks set <point> (--url URL | --lambda ARN) [--on-failure allow|deny] [--timeout-ms N] [--claims-ttl-seconds N]
480
+ [--env E] [--service REF]
481
+ saaslayer hooks unset <point> [--env E] [--service REF]
482
+ Set or remove the target of one point: beforeSignUp, afterUserCreated, beforeTokenIssue, afterSignIn, message.
483
+ set replaces the point's whole configuration. --on-failure and --timeout-ms apply to beforeSignUp and
484
+ beforeTokenIssue. --claims-ttl-seconds (beforeTokenIssue only) is how long the hook's app: claims are reused
485
+ before it is asked again; 0 asks on every issuance. A Lambda must first be listed in the instance's HookLambdaArns setting (saaslayer settings
486
+ set; a protected env needs --reason there). Owners of the deployment's org only.
487
+ saaslayer hooks grants set --org ID --role ROLE [--org ID --role ROLE ...] [--env E] [--service REF]
488
+ Replace the exact {org, role} pairs a hook may grant; each --org pairs with the --role after it. The org's owner
489
+ must also list the role as hook-joinable. Owners of the deployment's org only.
490
+ saaslayer hooks test <point> [--env E] [--service REF] [--json]
491
+ The instance sends the point a signed test event (test: true, sample data naming no real account) and shows
492
+ what the hook proposed, or why the call failed and what a real call would then do. Nothing is applied.
493
+ saaslayer hooks rotate-secret [--env E] [--service REF] [--json]
494
+ A new signing secret, printed once: store it in your receiver. The previous key keeps signing until the time
495
+ shown, so verify with both until then. Owners of the deployment's org only.
496
+ saaslayer hooks claims-cache invalidate [--env E] [--service REF] [--json]
497
+ Drop every cached beforeTokenIssue claim, so the next sign-in asks the hook again (after changing its logic).
498
+ saaslayer hooks logs [--point P] [--env E] [--service REF] [--json]
499
+ The newest hook calls (kept 14 days): when, point, event and attempt, target kind, outcome, HTTP status,
500
+ time, reason code and the names of the actions a reply proposed. Never a body, target, secret or personal data.
292
501
  saaslayer activity --env E [--region R | --deployment ID] [--limit N] [--json]
293
502
  A deployment's activity, newest first: every change — yours and any SaaSLayer operator's — with who made it
294
503
  (customer:<id> | operator:<id>), the action, what it touched, the reason and its operation id.
@@ -297,6 +506,32 @@ Deploy & lifecycle (requires login + a connected AWS account):
297
506
  Org owners: a user-service instance's console integration credentials (key ids, state, age; never a value), and an
298
507
  emergency revoke of one key (no delay). The revoke answers its pending operation; the key stops working once every
299
508
  verifier holds the replacement.
509
+ saaslayer bindings create --label NAME (--deployment <dep_id> | --env E [--region R]) [--user-service-instance I] [--permissions-instance I] [--json]
510
+ saaslayer bindings list [--org ID] [--json]
511
+ saaslayer bindings show <bindingId> [--json]
512
+ Org owners: consumer bindings. A consumer binding points at one deployment and its user-service and
513
+ permissions-service instances (the default ones unless named) and keeps pointing there when instances are added;
514
+ consumers read it at its discovery URL (<api>/api/discovery/bindings/<bindingId>), which create prints.
515
+ saaslayer bindings handoff start <bindingId> --to <dep_id> [--json]
516
+ saaslayer bindings handoff prepare <bindingId> [--validation-writes FILE] [--reader-role-confirmed] [--consumer NAME]... [--consumers-confirmed] [--json]
517
+ saaslayer bindings handoff freeze|cutover|complete <bindingId> [--json]
518
+ saaslayer bindings handoff sync <bindingId> --report FILE [--json]
519
+ saaslayer bindings handoff rollback <bindingId> [--mode reverse-migration|accept-loss] [--json]
520
+ saaslayer bindings handoff status <bindingId> [--json]
521
+ Org owners: move a consumer binding to a replacement deployment in a maintenance window (only when the control
522
+ plane enables it). start names the replacement; prepare records the writes made validating against it (FILE: a
523
+ JSON array of { description, disposition: reverted|overwritten }), the reader role on it, the consumers and that
524
+ static consumers were rebuilt; freeze verifies the current deployment's write freeze (WriteFreeze and
525
+ AdminMaintenance on, writers drained); sync records the final sync (FILE: the user-service
526
+ scripts/migrate-pool.js --delta --commit report, which must match); cutover switches the binding; rollback
527
+ returns it (after the replacement accepted writes, --mode is required); complete closes it. The previous
528
+ deployment is never removed by a handoff. Each step prints the next one.
529
+ saaslayer env export --binding <bindingId> [--format dotenv|json]
530
+ A consumer binding's public configuration as env, to bake in at build or deploy time (no login needed):
531
+ SAASLAYER_USER_POOL_ID, SAASLAYER_CLIENT_ID, SAASLAYER_REGION, SAASLAYER_ISSUER, SAASLAYER_JWKS_URL,
532
+ SAASLAYER_USERS_API_BASE, SAASLAYER_PERMISSIONS_API_BASE, SAASLAYER_HOSTED_LOGIN_URL. dotenv (default) prints
533
+ KEY=value lines; json prints one object. A handoff underway is a notice on stderr. Apps that discover at runtime
534
+ instead set SAASLAYER_DISCOVERY_URL to the binding's discovery URL.
300
535
 
301
536
  Data migrations you run yourself (a deployment with migrationRunner self):
302
537
  saaslayer migrate status --deployment <id> [--service <ref>]
@@ -313,6 +548,12 @@ Data migrations you run yourself (a deployment with migrationRunner self):
313
548
  Standalone (no control plane, no report): --stack <stackName> --region <r>, with --repo the service dir.
314
549
  Exit codes: 0 ok / up-to-date, 1 failed, 2 awaiting approval, 3 applied but not reported.
315
550
 
551
+ Platform operators:
552
+ saaslayer admin allowlist list | add <email> | remove <email> | open | close
553
+ The control plane's signup allowlist (the login pool's PreSignUp gate for console and CLI signup). close: only
554
+ listed emails may sign up; open: anyone may (the emails are kept for the next close). Operators only; the
555
+ control plane refuses anyone else.
556
+
316
557
  Global:
317
558
  --help Show this help.`
318
559
 
@@ -323,33 +564,43 @@ function cmdInit({ flags }) {
323
564
  // Canonical name — the account-global named IAM resources allow only one SaaSLayer
324
565
  // foundation stack per account, so init always updates the same stack.
325
566
  const stackName = flags['stack-name'] || 'saaslayer-foundation'
326
- const { writeDeployableTemplate, initDeployArgs, redactArgs } = require('../src/foundation-template')
567
+ const { writeDeployableTemplate } = require('../src/foundation-template')
327
568
  if (flags['dry-run']) {
328
569
  execFileSync('aws', ['cloudformation', 'validate-template', '--template-body', `file://${writeDeployableTemplate(template)}`, '--region', region], { stdio: 'inherit' })
329
570
  console.log(`\n[dry-run] template valid. Would deploy stack "${stackName}" to ${region}.`)
330
571
  return
331
572
  }
332
- // Required params: the SaaSLayer control-plane account that may assume the deploy role,
333
- // and the ExternalId trust secret shared during onboarding.
573
+ // Required params: the SaaSLayer control plane the foundation trusts: its control-plane account, its control-plane id and
574
+ // the trust identifier (AWS ExternalId) shared during onboarding.
334
575
  const controlPlaneAccount = flags['control-plane-account'] || process.env.SAASLAYER_CONTROL_PLANE_ACCOUNT
335
576
  const externalId = flags['external-id'] || process.env.SAASLAYER_EXTERNAL_ID
577
+ const controlPlaneId = flags['control-plane-id']
336
578
  const stackPrefix = flags['stack-name-prefix'] || 'sl-'
337
579
  const orgId = flags['org-id'] || process.env.SAASLAYER_ORG_ID || ''
338
580
  if (!controlPlaneAccount) throw new Error('init: --control-plane-account <12-digit id> (or $SAASLAYER_CONTROL_PLANE_ACCOUNT) is required')
339
581
  if (!/^[0-9]{12}$/.test(controlPlaneAccount)) throw new Error('init: --control-plane-account must be a 12-digit AWS account id')
340
- if (!externalId) throw new Error('init: --external-id <secret> (or $SAASLAYER_EXTERNAL_ID) is required — shared during onboarding')
341
- console.log(`Deploying SaaSLayer foundation stack "${stackName}" to ${region} (control plane ${controlPlaneAccount})…`)
342
- const args = initDeployArgs({ template, stackName, region, controlPlaneAccount, externalId, stackPrefix, orgId })
582
+ if (!externalId) throw new Error('init: --external-id <id> (or $SAASLAYER_EXTERNAL_ID) is required — shared during onboarding')
583
+ if (!controlPlaneId) throw new Error('init: --control-plane-id <id> is required — the SaaSLayer control plane this account trusts')
584
+ const { controlPlaneEntry, mergeTrustEntry, canonicalRoleArn } = require('../src/trust-entries')
585
+ const { resolveFoundationHome } = require('../src/foundation-home')
586
+ const { awsRunner } = require('../src/foundation-change-set')
587
+ const { createAccountFoundation } = require('../src/commands/aws')
588
+ const trustEntries = mergeTrustEntry('', controlPlaneEntry({ controlPlaneId, principalAccountId: controlPlaneAccount, trustIdentifiers: [externalId] }))
589
+ const exec = (cmd, args) => execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024 })
590
+ const awsIn = (r) => awsRunner(exec, { region: r, profile: flags.profile })
591
+ const home = resolveFoundationHome({ awsIn, requestedRegion: region, stackName })
592
+ if (home.state === 'home') throw new Error(`init: this account already has a foundation (${home.stackId}); upgrade it with saaslayer foundation upgrade`)
593
+ const authorizer = canonicalRoleArn(awsIn(region)(['sts', 'get-caller-identity']).Arn)
594
+ console.log(`Creating SaaSLayer foundation stack "${stackName}" in ${region} (control plane ${controlPlaneId}, account ${controlPlaneAccount})…`)
343
595
  try {
344
- execFileSync('aws', args, { stdio: 'inherit' })
596
+ createAccountFoundation({ aws: awsIn(region), trustEntries, connectionAuthorizerArns: authorizer, controlPlaneAccount, stackNamePrefix: stackPrefix, orgId, stackName, templatePath: template })
345
597
  } catch (err) {
346
- // execFileSync's message echoes the full argv; never let the ExternalId reach the terminal or logs.
347
- throw new Error(`init: aws ${redactArgs(args).join(' ')} failed (exit ${err.status ?? '?'})`)
598
+ throw new Error(`init: ${err.message}`)
348
599
  }
349
- console.log('\nSaaSLayer foundation deployed.')
350
- console.log(` • Control plane ${controlPlaneAccount} may now assume the deploy role (ExternalId gated).`)
600
+ console.log('\nSaaSLayer foundation created.')
601
+ console.log(` • Control plane ${controlPlaneId} (account ${controlPlaneAccount}) may now assume the deploy role (trust identifier gated).`)
351
602
  console.log(` • It can manage only CloudFormation stacks named "${stackPrefix}*" in this account.`)
352
- console.log(' • Share the ControlPlaneAccountId + ExternalId with SaaSLayer onboarding to finish setup.')
603
+ console.log(` • Connection authorizer: ${authorizer}.`)
353
604
  }
354
605
 
355
606
  async function main() {
@@ -364,9 +615,8 @@ async function main() {
364
615
  if (cmd === 'permissions' && sub === 'model' && positional[2] === 'apply') { await require('../src/commands/catalog').catalogApply(positional.slice(3), flags); return }
365
616
  if (cmd === 'permissions' && sub === 'owner' && positional[2] === 'bootstrap') { const a = await require('../src/commands/catalog').catalogBootstrapOwner(positional.slice(3), flags); console.log(`${a.userId} is now ${a.roleId} of ${a.scope}`); return }
366
617
  if (cmd === 'permissions' && sub === 'owner' && positional[2] === 'reconcile') {
367
- const r = await require('../src/commands/catalog').catalogReconcileOwners(positional.slice(3), flags)
368
- for (const o of r.orgs) console.log(`${o.ok ? 'ok ' : 'DRIFT'} ${o.orgId} counter=${o.counter} actual=${o.actual}`)
369
- console.log(r.applied ? 'repaired mismatched counters' : 'report only (pass --apply to repair)')
618
+ const catalog = require('../src/commands/catalog')
619
+ console.log(catalog.formatReconcileResult(await catalog.catalogReconcileOwners(positional.slice(3), flags)))
370
620
  return
371
621
  }
372
622
  if (cmd === 'permissions' && sub === 'model' && positional[2] === 'export') { await require('../src/commands/catalog').catalogExport(positional.slice(3), flags); return }
@@ -376,7 +626,14 @@ async function main() {
376
626
  if (positional[2] === 'roles') { console.log(JSON.stringify(await sp.servicePrincipalRoles(positional.slice(3), flags), null, 2)); return }
377
627
  if (positional[2] === 'assign') { const a = await sp.servicePrincipalAssign(positional.slice(3), flags); console.log(`granted ${a.roleId} to ${a.principalId}${a.scope ? ` in ${a.scope}` : ' (deployment-wide)'}`); return }
378
628
  if (positional[2] === 'unassign') { await sp.servicePrincipalUnassign(positional.slice(3), flags); console.log(`revoked ${flags.role}`); return }
379
- console.error('usage: saaslayer permissions service-principal <roles|assign|unassign> (<id> | --machine PRINCIPAL) [--role ROLE] [--scope S] --api-base URL'); process.exit(1)
629
+ if (positional[2] === 'verifier-key' && positional[3] === 'create') {
630
+ const issued = await sp.verifierKeyCreate(positional.slice(4), flags)
631
+ console.log(`issued verifier key ${issued.keyId} for service account ${issued.servicePrincipalId}${issued.expiresAt ? ` (expires ${issued.expiresAt})` : ''}`)
632
+ console.log(`key (shown once): ${issued.apiKey}`)
633
+ if (flags['ssm-parameter']) { const stored = await sp.storeVerifierKey(issued.apiKey, flags); console.log(`stored in SSM SecureString ${stored.name} (version ${stored.version})`) }
634
+ return
635
+ }
636
+ console.error('usage: saaslayer permissions service-principal <roles|assign|unassign|verifier-key create> (<id> | --machine PRINCIPAL) [--role ROLE] [--scope S] [--ssm-parameter PATH] --api-base URL'); process.exit(1)
380
637
  }
381
638
  if (cmd === 'permissions' && sub === 'machine-trust') {
382
639
  const trust = require('../src/commands/machine-trust')
@@ -397,18 +654,50 @@ async function main() {
397
654
  if (run) { console.log(JSON.stringify(await run(rest, flags), null, 2)); return }
398
655
  console.error('usage: saaslayer permissions access-admins <list|offer|status|cancel|accept|activate> [suid|transferId] --api-base URL'); process.exit(1)
399
656
  }
657
+ if (cmd === 'permissions' && sub === 'support-staff') {
658
+ const staff = require('../src/commands/support-staff')
659
+ const run = { grant: staff.supportStaffGrant, revoke: staff.supportStaffRevoke, list: staff.supportStaffList }[positional[2]]
660
+ if (run) { console.log(JSON.stringify(await run(positional.slice(3), flags), null, 2)); return }
661
+ console.error('usage: saaslayer permissions support-staff <grant|revoke|list> [suid] --mode view-only|act-as --api-base URL'); process.exit(1)
662
+ }
663
+ if (cmd === 'permissions' && sub === 'orgs') {
664
+ const orgs = require('../src/commands/permission-orgs')
665
+ if (positional[2] === 'create') { console.log(JSON.stringify(await orgs.orgCreate(positional.slice(3), flags), null, 2)); return }
666
+ if (positional[2] === 'members' && positional[3] === 'add') { console.log(JSON.stringify(await orgs.orgMemberAdd(positional.slice(4), flags), null, 2)); return }
667
+ if (positional[2] === 'hook-joinable' && positional[3] === 'set') { console.log(JSON.stringify(await orgs.orgHookJoinableSet(positional.slice(4), flags), null, 2)); return }
668
+ if (positional[2] === 'hook-joinable' && positional[3] === 'disable') { console.log(JSON.stringify(await orgs.orgHookJoinableDisable(positional.slice(4), flags), null, 2)); return }
669
+ console.error('usage: saaslayer permissions orgs <create <name> | members add <orgId> --user <suid> | hook-joinable set <orgId> --consumer <ref> --role <roleId> | hook-joinable disable <orgId>> --api-base URL [auth]'); process.exit(1)
670
+ }
671
+ if (cmd === 'permissions' && sub === 'api-keys') {
672
+ const keys = require('../src/commands/api-keys')
673
+ const rest = positional.slice(3)
674
+ const run = { create: keys.apiKeysCreate, list: keys.apiKeysList, get: keys.apiKeysGet, revoke: keys.apiKeysRevoke }[positional[2]]
675
+ if (run) { console.log(JSON.stringify(await run(rest, flags), null, 2)); return }
676
+ console.error('usage: saaslayer permissions api-keys <create|list|get|revoke> [keyId] (--deployment ID | --api-base URL) [auth]'); process.exit(1)
677
+ }
678
+ if (cmd === 'permissions' && sub === 'trust-policies') {
679
+ const tp = require('../src/commands/trust-policies')
680
+ const rest = positional.slice(3)
681
+ const run = { list: tp.trustPoliciesList, get: tp.trustPoliciesGet, add: tp.trustPoliciesAdd, update: tp.trustPoliciesUpdate, disable: tp.trustPoliciesDisable, enable: tp.trustPoliciesEnable, delete: tp.trustPoliciesDelete }[positional[2]]
682
+ if (run) { console.log(JSON.stringify(await run(rest, flags), null, 2)); return }
683
+ console.error('usage: saaslayer permissions trust-policies <list|get|add|update|disable|enable|delete> [policyId|issuerUrl] (--deployment ID | --api-base URL) [auth]'); process.exit(1)
684
+ }
685
+ if (cmd === 'audit') {
686
+ if (sub === 'erase') { await require('../src/commands/audit').auditErase(positional.slice(2), flags); return }
687
+ console.error('usage: saaslayer audit erase <suid> [--email E …] (--iam PRINCIPAL | --token KEY) (--api-base URL | --deployment ID | --discovery-url URL)'); process.exit(1)
688
+ }
400
689
  if (cmd === 'users') {
401
690
  const users = require('../src/commands/users')
402
691
  if (sub === 'export') { await users.usersExport(flags); return }
403
- if (sub === 'import') { await users.usersImport(flags); return }
692
+ if (sub === 'import') { const result = await users.usersImport(flags); if (result.exitCode) process.exitCode = result.exitCode; return }
404
693
  if (sub === 'admin') { await require('../src/commands/users-management').usersManagement(positional[2], flags); return }
405
694
  if (users.ADMIN_COMMANDS.includes(sub)) { await users.usersAdmin(sub, positional.slice(2), flags); return }
406
695
  console.error(users.USAGE); process.exit(1)
407
696
  }
408
697
  if (cmd === 'signup') {
409
698
  const { signup } = require('../src/commands/login')
410
- const who = await signup(flags)
411
- console.log(`account created — logged in as ${who.email}`)
699
+ const out = await signup(flags)
700
+ console.log(out.status === 'logged-in' ? `account created — logged in as ${out.email}` : out.next)
412
701
  return
413
702
  }
414
703
  if (cmd === 'login') {
@@ -449,6 +738,7 @@ async function main() {
449
738
  const who = whoami()
450
739
  if (!who) { console.log('not logged in'); return }
451
740
  console.log(`${who.email} (control plane: ${who.env})`)
741
+ if (who.accountId) console.log(`account id: ${who.accountId} (share this id with your org owner to be added to their org)`)
452
742
  const ctx = require('../src/context-store').load()
453
743
  console.log(`org: ${ctx.org || '—'} project: ${ctx.project ? `${ctx.project} (${require('../src/scope').projectIdKind(ctx.project)})` : '—'} (see: saaslayer context)`)
454
744
  return
@@ -471,6 +761,11 @@ async function main() {
471
761
  console.log('\n* = active. Switch with: saaslayer account use <email>')
472
762
  return
473
763
  }
764
+ if (cmd === 'account' && sub === 'verify-email') {
765
+ const out = await require('../src/commands/account-email').verifyEmail(flags)
766
+ console.log(out.status === 'verified' ? `email verified: ${out.email}` : out.next)
767
+ return
768
+ }
474
769
  if (cmd === 'account' && sub === 'use') {
475
770
  const { accountUse } = require('../src/commands/accounts')
476
771
  const who = accountUse(positional[2])
@@ -482,7 +777,16 @@ async function main() {
482
777
  if (sub === 'create') { const o = await orgs.orgCreate(flags, positional[2]); console.log(`created org ${o.name || ''} (${o.id}) — now active`); return }
483
778
  if (sub === 'list') { const list = await orgs.orgList(flags); if (!list.length) console.log('no orgs'); else list.forEach((o) => console.log(`${o.id}${o.name ? ' ' + o.name : ''}`)); return }
484
779
  if (sub === 'use') { const id = orgs.orgUse(flags, positional[2]); console.log(`active org: ${id}`); return }
485
- console.error('usage: saaslayer org <create|list|use> …'); process.exit(1)
780
+ if (sub === 'members') {
781
+ const members = require('../src/commands/org-members')
782
+ const action = positional[2]
783
+ if (action === 'list') { await members.membersList(flags); return }
784
+ if (action === 'add') { await members.membersAdd(flags, {}, positional[3]); return }
785
+ if (action === 'remove') { await members.membersRemove(flags, positional[3]); return }
786
+ if (action === 'set-role') { await members.membersSetRole(flags, positional[3]); return }
787
+ console.error('usage: saaslayer org members <list|add|remove|set-role> [--user <accountId>] [--role deployer|member] [--org ID]'); process.exit(1)
788
+ }
789
+ console.error('usage: saaslayer org <create|list|use|members> …'); process.exit(1)
486
790
  }
487
791
  if (cmd === 'project') {
488
792
  const orgs = require('../src/commands/orgs')
@@ -500,15 +804,25 @@ async function main() {
500
804
  if (cmd === 'aws') {
501
805
  const aws = require('../src/commands/aws')
502
806
  if (sub === 'connect') { await aws.awsConnect(flags); return }
503
- console.error('usage: saaslayer aws connect --aws-account <id> [--region <r>] [--org-wide]'); process.exit(1)
807
+ if (sub === 'authorizers') { await aws.awsAuthorizers(positional[2], positional[3], flags); return }
808
+ if (sub === 'rotate-trust') { await aws.awsRotateTrust(positional[2], flags); return }
809
+ console.error('usage: saaslayer aws connect --aws-account <id> [--region <r>] [--org-wide] [--sms-toll-free]\n saaslayer aws authorizers <add|remove> <arn> --aws-account <id>\n saaslayer aws rotate-trust <start|verify|switch|retire|rollback|status> --aws-account <id>'); process.exit(1)
504
810
  }
811
+ if (cmd === 'sms') { const { smsCommand } = require('../src/commands/sms'); await smsCommand(sub, flags); return }
505
812
  if (cmd === 'foundation') {
506
813
  const foundation = require('../src/commands/foundation')
507
814
  if (sub === 'status') { await foundation.foundationStatus(flags); return }
508
815
  if (sub === 'upgrade') { await foundation.foundationUpgrade(flags); return }
509
816
  console.error('usage: saaslayer foundation <status|upgrade> [--region R] [--profile P] (see saaslayer --help)'); process.exit(1)
510
817
  }
818
+ if (cmd === 'admin' && sub === 'allowlist') {
819
+ const allowlist = require('../src/commands/admin-allowlist')
820
+ const run = { list: allowlist.allowlistList, add: allowlist.allowlistAdd, remove: allowlist.allowlistRemove, open: allowlist.allowlistOpen, close: allowlist.allowlistClose }[positional[2]]
821
+ if (run) { await run(flags, positional[3]); return }
822
+ console.error('usage: saaslayer admin allowlist <list|add <email>|remove <email>|open|close>'); process.exit(1)
823
+ }
511
824
  if (cmd === 'stacks') { const { stacks } = require('../src/commands/stacks'); await stacks(flags); return }
825
+ if (cmd === 'versions') { const { versions } = require('../src/commands/versions'); await versions(flags); return }
512
826
  if (cmd === 'deploy') { const { deploy } = require('../src/commands/deploy'); await deploy(flags); return }
513
827
  if (cmd === 'status') { const { status } = require('../src/commands/lifecycle'); await status(flags); return }
514
828
  if (cmd === 'update') { const { update } = require('../src/commands/lifecycle'); await update(flags); return }
@@ -525,8 +839,20 @@ async function main() {
525
839
  }
526
840
  if (cmd === 'release-manifest') { const { releaseManifestCommand } = require('../src/commands/release-manifest'); await releaseManifestCommand(sub, flags); return }
527
841
  if (cmd === 'settings') { const { settingsCommand } = require('../src/commands/settings'); await settingsCommand(sub, flags); return }
842
+ if (cmd === 'social') { const { socialCommand } = require('../src/commands/social'); await socialCommand(sub, positional[2], flags); return }
843
+ if (cmd === 'login-domain') { const { loginDomainCommand } = require('../src/commands/login-domain'); await loginDomainCommand(sub, positional[2], flags); return }
844
+ if (cmd === 'hooks') { const { hooksCommand } = require('../src/commands/hooks'); await hooksCommand(sub, positional.slice(2), flags); return }
528
845
  if (cmd === 'first-admin') { const { firstAdminCommand } = require('../src/commands/first-admin'); await firstAdminCommand(sub, flags); return }
529
846
  if (cmd === 'activity') { const { activityCommand } = require('../src/commands/activity'); await activityCommand(flags); return }
847
+ if (cmd === 'bindings') {
848
+ const bindings = require('../src/commands/bindings')
849
+ if (sub === 'create') { await bindings.bindingsCreate(flags); return }
850
+ if (sub === 'list') { await bindings.bindingsList(flags); return }
851
+ if (sub === 'show') { await bindings.bindingsShow(flags, positional[2]); return }
852
+ if (sub === 'handoff') { await require('../src/commands/binding-handoff').bindingsHandoff(flags, positional[2], positional[3]); return }
853
+ console.error('usage: saaslayer bindings <create|list|show <bindingId>|handoff <step> <bindingId>> (see saaslayer --help)'); process.exit(1)
854
+ }
855
+ if (cmd === 'env' && sub === 'export') { await require('../src/commands/env-export').envExport(flags); return }
530
856
  if (cmd === 'credentials' && sub === 'status') { await require('../src/commands/integration-credentials').credentialsStatus(flags); return }
531
857
  if (cmd === 'credentials' && sub === 'revoke') { await require('../src/commands/integration-credentials').credentialsRevoke(flags); return }
532
858
  if (cmd === 'operations' || cmd === 'operation') { const { operationsCommand } = require('../src/commands/operations'); await operationsCommand(sub, positional[2], flags); return }