saaslayer 0.0.7 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +150 -13
  2. package/bin/saaslayer.js +297 -66
  3. package/package.json +4 -3
  4. package/src/api-client.js +48 -28
  5. package/src/aws-sigv4.js +1 -1
  6. package/src/commands/access-admins.js +73 -0
  7. package/src/commands/accounts.js +32 -3
  8. package/src/commands/activity.js +33 -0
  9. package/src/commands/catalog.js +30 -29
  10. package/src/commands/context.js +64 -0
  11. package/src/commands/deploy.js +79 -10
  12. package/src/commands/first-admin.js +42 -0
  13. package/src/commands/foundation.js +405 -0
  14. package/src/commands/lifecycle.js +72 -39
  15. package/src/commands/login.js +200 -26
  16. package/src/commands/machine-trust.js +96 -0
  17. package/src/commands/operations.js +140 -0
  18. package/src/commands/orgs.js +29 -4
  19. package/src/commands/{rbac-inspect.js → permissions-inspect.js} +15 -15
  20. package/src/commands/release-manifest.js +138 -0
  21. package/src/commands/service-principals.js +81 -0
  22. package/src/commands/settings.js +140 -0
  23. package/src/commands/stacks.js +12 -7
  24. package/src/commands/users.js +192 -4
  25. package/src/config.js +20 -7
  26. package/src/credentials.js +221 -34
  27. package/src/deployment-api-auth.js +61 -0
  28. package/src/deployment-auth.js +38 -0
  29. package/src/deployments.js +12 -13
  30. package/src/discovery.js +66 -0
  31. package/src/env-compare.js +143 -0
  32. package/src/iam-session.js +4 -30
  33. package/src/module-catalog.js +66 -0
  34. package/src/permissions-request.js +43 -0
  35. package/src/release-manifest.js +334 -0
  36. package/src/scope.js +114 -0
  37. package/src/settings.js +272 -0
  38. package/src/users-api.js +165 -0
  39. package/src/users-import/import.js +10 -10
  40. package/templates/saaslayer-foundation.yml +23 -6
  41. package/src/commands/iam-principals.js +0 -53
  42. package/src/rbac-auth.js +0 -25
  43. package/vendor/ids/index.d.ts +0 -21
  44. package/vendor/ids/index.js +0 -237
package/bin/saaslayer.js CHANGED
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
- // SaaSLayer CLI (M0.10, D18) — onboard an AWS account and register RBAC manifests.
2
+ // SaaSLayer CLI (M0.10, D18) — onboard an AWS account and register permissions manifests.
3
3
  // `saaslayer init` deploys the bundled saaslayer-foundation.yml (the control plane's deploy role +
4
- // boundary + artifact bucket). `saaslayer rbac register` upserts a service's rbac.manifest.json
5
- // into the RBAC catalog (POST /catalog/register) — run by a human or wired into CI.
4
+ // boundary + artifact bucket). `saaslayer permissions register` upserts a service's permissions manifest
5
+ // into the permissions catalog (POST /catalog/register) — run by a human or wired into CI.
6
6
 
7
7
  'use strict'
8
8
  const fs = require('fs')
@@ -36,49 +36,109 @@ Usage:
36
36
  bucket) into the caller's AWS account, trusting the SaaSLayer control plane.
37
37
  Uses the bundled templates/saaslayer-foundation.yml. --dry-run validates only.
38
38
 
39
- saaslayer signup --config-url URL [--email E --password P]
39
+ saaslayer foundation status [--region R] [--profile P] [--stack-name saaslayer-foundation] [--only account|region]
40
+ Show each installed foundation stack (saaslayer-foundation + saaslayer-foundation-<region>): its status,
41
+ installed version and the version bundled with this CLI.
42
+ saaslayer foundation upgrade [--region R] [--profile P] [--stack-name saaslayer-foundation] [--only account|region]
43
+ [--dry-run] [--yes] [--allow-replacement]
44
+ 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
+ re-entered or printed; new parameters take their template default), prints the version change and each
47
+ resource change, then executes after you confirm and reads the new version back. Refuses a stack that is
48
+ not in a stable state or that runs a newer version than this CLI. A change that replaces a resource or
49
+ 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.
52
+ After the upgrade (or when nothing changed) the control plane re-reads the account's foundation through its
53
+ own trust, as your saaslayer login (no AWS credentials are sent), so the console and deploys see the new
54
+ version; if that fails the upgrade still stands and the console's "check again" re-reads it.
55
+
56
+ saaslayer signup [--config-url URL] [--email E --password P]
40
57
  Create a SaaSLayer account (allowlist-gated) and log in.
58
+ --config-url (or $SAASLAYER_CONFIG_URL) is the control-plane API; default https://api.saaslayer.com.
41
59
  saaslayer login [--email E --password P] [--config-url URL | --user-pool-id ID --client-id ID --region R]
42
60
  Log in to your SaaSLayer account (Cognito SRP) and cache tokens in ~/.saaslayer.
43
61
  Email/password fall back to $SAASLAYER_EMAIL/$SAASLAYER_PASSWORD, else prompt.
44
- saaslayer whoami Show the current logged-in account.
45
- saaslayer accounts List all cached accounts (most-recently-used first; * = active).
46
- saaslayer account use <email> Switch the active account to another cached login (no re-auth).
47
- saaslayer logout [--user <email|userId>] Clear the current cached account (or the named one).
62
+ Challenges (both login forms): first-login password change via --new-password-stdin (or a hidden
63
+ prompt in a terminal); MFA via --mfa-code 123456 (or a hidden prompt). Secrets are never echoed.
64
+ saaslayer login --deployment <dep_id|env> [--user-service-instance NAME] [--project P] [--region R] [--config-url URL]
65
+ Log in to a deployment's user-service as an access admin. The pool, client and API bases are
66
+ discovered from the deployment's public outputs (an env name resolves the active project's deployment).
67
+ 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.
69
+ saaslayer context [--json] [--profile AWS_PROFILE] Show the control-plane account, the deployment login, the AWS
70
+ profile, org and project (and where each came from) and every cached identity.
71
+ Tokens are never printed.
72
+ saaslayer accounts List all cached control-plane accounts (most-recently-used first; * = active).
73
+ saaslayer account use <email> Switch the active control-plane account to another cached login (no re-auth).
74
+ saaslayer deployment logins List cached deployment logins (* = current).
75
+ saaslayer deployment use <dep_id|env> [--as <email>] [--user-service-instance NAME]
76
+ Select the deployment login that deployment commands act as. --deployment/--as on a command pick one for
77
+ that command; when several match, the command fails and names the flag to add.
78
+ saaslayer logout [--user <email|userId>] Clear the current control-plane account (or the named one).
79
+ saaslayer logout --deployment <dep_id|env> [--as <email>] Clear a deployment login (control-plane login kept).
48
80
 
49
- saaslayer rbac register <manifest.json> --product PRODUCT --api-base URL (--iam PRINCIPAL | --token KEY)
50
- Upsert a service's rbac.manifest.json into the RBAC catalog under the product that owns it (a service
81
+ saaslayer permissions register <manifest.json> --product PRODUCT --api-base URL [auth]
82
+ Upsert a service's permissions manifest into the permissions catalog under the product that owns it (a service
51
83
  belongs to exactly one product; --product defaults to the manifest's "product"). Publishes a new registry
52
- snapshot version, live in every container within 60 s. --token defaults to $SAASLAYER_TOKEN.
53
- saaslayer rbac inspect <TYPE>:<id> --api-base URL (--iam PRINCIPAL | --token KEY) [--scope S]... [--scope-page C]
84
+ snapshot version, live in every container within 60 s. Needs saaslayer:catalog:service:register: a deployment
85
+ administrator holds it; a machine (--iam) needs the catalog:register scope and a grant of it. [auth] = a
86
+ access-admin login, --token KEY (defaults to $SAASLAYER_TOKEN) or --iam PRINCIPAL.
87
+ saaslayer permissions inspect <TYPE>:<id> --api-base URL (--iam PRINCIPAL | --token KEY) [--scope S]... [--scope-page C]
54
88
  [--assignment-page C] [--all-scopes] [--stored] [--json]
55
- Print a principal's permissions (needs saaslayer:principals read): assignments, global and per-scope allows/denies with the
89
+ Print a principal's permissions (needs saaslayer:identity read): assignments, global and per-scope allows/denies with the
56
90
  granting role/policy and conditions, size stats (item bytes vs the 340 KB gate, defs, ref sets, scopes) and
57
91
  copy-paste next-page commands. --all-scopes follows every scope page (restarts once if the doc is rebuilt
58
92
  mid-way). --stored prints the stored doc's inspection model ("Stored v1" / "Stored v2 (compact)", problems);
59
93
  --stored --json the raw stored items. session:<id> inspects a session's stored permission set.
60
- saaslayer catalog apply <catalog.json> --api-base URL (--iam PRINCIPAL [--region R] [--profile P] | --token KEY)
94
+ saaslayer permissions model apply <authorization-model.json> --api-base URL (--iam PRINCIPAL [--region R] [--profile P] | --token KEY)
61
95
  [--dry-run] [--allow-orphan] [--adopt]
62
- Apply a product's versioned role catalog (managed system roles) to its RBAC API.
96
+ Apply a product's versioned authorization model (role catalog: managed system roles) to its permissions API.
63
97
  --iam authenticates as one of your IAM principals using your AWS credentials.
64
98
  --dry-run prints the plan and role diff without writing; --allow-orphan permits
65
99
  removing roles that still have assignments; --adopt converts org-owned roles with catalog
66
100
  ids into shared catalog roles (assignments kept). Fails if the manifest's selfCheck fails.
67
- saaslayer catalog export --snapshot --out FILE --api-base URL (--iam PRINCIPAL | --token KEY)
101
+ saaslayer permissions model export --snapshot --out FILE --api-base URL (--iam PRINCIPAL | --token KEY)
68
102
  Write the currently published registry snapshot ({ meta, snapshot }) to FILE — the pinned registry
69
- rbac-node direct mode loads at deploy.
70
- saaslayer catalog get <product> --api-base URL (--iam PRINCIPAL [--region R] [--profile P] | --token KEY)
71
- Print the catalog currently applied for a product (version, content hash, roles, manifest).
72
- saaslayer catalog bootstrap-owner <product> --org ORG --user USER --api-base URL (--iam PRINCIPAL | --token KEY)
73
- Make a member the FIRST owner of an org (refused once the org has an owner). Needs owners:bootstrap.
74
- saaslayer catalog reconcile-owners <product> --api-base URL (--iam PRINCIPAL | --token KEY) [--org ORG] [--apply]
75
- Compare each org's owner counter with a live recount; --apply repairs drift.
76
- saaslayer rbac iam-principals set <principals.json> --deployment DEP --region R [--profile P] [--service-instance I]
77
- saaslayer rbac iam-principals get --deployment DEP --region R [--profile P] [--service-instance I]
78
- Declare which of your AWS IAM roles are trusted RBAC principals and their credential
79
- scopes (catalog:read, catalog:write, owners:bootstrap, orgs:read, orgs:write, users:write, broker:<product>). Written to SSM in YOUR
80
- account with your AWS creds:
81
- { "principals": [{ "principalId": "ci", "roleArn": "arn:aws:iam::…:role/…", "scopes": ["catalog:write"] }] }
103
+ @saaslayer/permissions direct mode loads at deploy.
104
+ saaslayer permissions model get <product> --api-base URL (--iam PRINCIPAL [--region R] [--profile P] | --token KEY)
105
+ Print the authorization model currently applied for a product (version, content hash, roles, manifest).
106
+ saaslayer permissions owner bootstrap <product> --org ORG --user USER --api-base URL (--iam PRINCIPAL | --token KEY)
107
+ Make a member the FIRST owner of an org (refused once the org has an owner). Needs saaslayer:catalog:owner:bootstrap
108
+ (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
111
+ (a machine: the catalog:write scope and a grant of it).
112
+ saaslayer permissions service-principal roles (<id> | --machine PRINCIPAL) --api-base URL (--token KEY | --iam PRINCIPAL)
113
+ saaslayer permissions service-principal assign (<id> | --machine PRINCIPAL) --role ROLE [--scope S] --api-base URL (--token KEY | --iam PRINCIPAL)
114
+ saaslayer permissions service-principal unassign (<id> | --machine PRINCIPAL) --role ROLE [--scope S] --api-base URL (--token KEY | --iam PRINCIPAL)
115
+ List, grant or revoke roles of a service principal. --machine PRINCIPAL targets a declared IAM principal's
116
+ mapped principal (iam.PRINCIPAL), which acts with its scopes AND these grants.
117
+ Grants are deployment-wide unless --scope names an org scope. Needs roles:role:{assign,unassign} +
118
+ identity:principal:read.
119
+ saaslayer permissions machine-trust list | get <principalId> --api-base URL [auth]
120
+ saaslayer permissions machine-trust declare <principalId> --role-arn ARN --scope S [--scope S2] --api-base URL [auth]
121
+ saaslayer permissions machine-trust update <principalId> [--role-arn ARN] [--scope S …] [--expected-revision N] --api-base URL [auth]
122
+ saaslayer permissions machine-trust remove <principalId> --api-base URL [auth]
123
+ saaslayer permissions machine-trust reconcile --api-base URL [auth]
124
+ The deployment's trusted AWS IAM roles (machine trust), managed through the permissions API, which writes the
125
+ backing SSM parameter. [auth] = an access-admin login (\`saaslayer login --deployment\`), --token KEY or --iam PRINCIPAL.
126
+ A declaration grants nothing: grant roles with \`permissions service-principal assign --machine\`. remove unassigns
127
+ every role of the mapped principal. Changes reach already-issued iam_ tokens within 60 s. Every machine call
128
+ needs scope AND grant (broker:<p> and attest routes are scope-only). Scopes: catalog:read,
129
+ catalog:write, catalog:register, owners:bootstrap, orgs:read, orgs:write, users:read, users:write, users:write-reserved,
130
+ users:set-password, users:adopt, machine-trust:read, machine-trust:write, broker:<p>, attributes:attest:<p>,
131
+ context:attest:<p>.
132
+ saaslayer permissions access-admins list --api-base URL [auth]
133
+ saaslayer permissions access-admins offer <suid> [--mode transfer|add] [--expires-in-hours N] --api-base URL [auth]
134
+ saaslayer permissions access-admins status | cancel <transferId> --api-base URL [auth]
135
+ saaslayer permissions access-admins accept <transferId> | activate --api-base URL [your deployment login]
136
+ 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,
140
+ add keeps you. An interrupted accept leaves both admins; accept again to finish. cancel (pending offers, by you)
141
+ revokes the grant. activate records your own activation. See services/permissions-service/user-docs/access-admins.md.
82
142
 
83
143
  saaslayer users export --provider cognito --user-pool-id POOL --region R [--profile P]
84
144
  [--account-attribute ATTR] [--account-name-attribute ATTR] [--role-map map.js] --out manifest.json
@@ -89,31 +149,136 @@ Usage:
89
149
  [--api-base URL --product P (--iam PRINCIPAL | --token KEY) [--logs-role-arn ARN] --apply] [--report FILE]
90
150
  Dry run by default: prints what would be created or linked. --apply imports new users through a Cognito CSV
91
151
  import job (reset required on first sign-in, no emails sent), stamps their SaaSLayer id + default org, then
92
- creates each user's rbac principal and org, adds members and bootstraps the first Owner (IAM scopes users:write + orgs:write + owners:bootstrap).
152
+ creates each user's permissions principal and org, adds members and bootstraps the first Owner (IAM scopes users:write + orgs:write + owners:bootstrap).
93
153
  Idempotent: re-run to retry failures. See docs/users-import.md.
154
+ saaslayer users <command> … [target] [auth]
155
+ Administer a deployment's users through its user-service /api/users (see services/user-service/docs/users.md).
156
+ [auth] = the current deployment login (\`saaslayer login --deployment\`; pick one with --deployment/--as), or
157
+ --iam PRINCIPAL [--region R] [--profile P] (IAM scopes users:read|write|write-reserved|set-password|adopt + the
158
+ matching saaslayer:users:account:* grant on iam.PRINCIPAL), or --token KEY. [target] = the login's own APIs, or
159
+ --api-base USERS_URL [--permissions-api-base PERMISSIONS_URL], or the deployment's public discovery (--deployment <dep_id|env>
160
+ [--config-url URL] or --discovery-url URL). <user> = <suid>, --suid ID or --email E (looked up). Prints JSON.
161
+ saaslayer users create --email E [--password-stdin | --delivery invitation] [--name N] [--soid ORG] [--suid ID]
162
+ [--idempotency-key K] [--interval SECONDS]
163
+ A durable operation (identity, profile, permissions principal, password | invitation). Re-running the same command
164
+ replays it (the default Idempotency-Key is derived from the email); a running operation is waited for; a failed
165
+ step is an error — run the same command again to resume. An email of another account is refused (see adopt).
166
+ --password-stdin sets a permanent password: the deployment needs
167
+ user-service.EnablePasswordInitialization=true and is never prod.
168
+ e.g. printf '%s' "$PW" | saaslayer users create --email qa@acme.com --password-stdin
169
+ saaslayer users get <user> [--org ORG]
170
+ One user (status, enabled, email verification); --org ORG = the member view of that org.
171
+ saaslayer users list (--email E | --default-org ORG) [--limit N] [--cursor C]
172
+ Users holding an email, or whose default org is ORG; prints nextCursor for the next page.
173
+ saaslayer users update <user> [--name N] [--attr name=value …]
174
+ Profile attributes (name, given_name, family_name, locale, zoneinfo, picture).
175
+ saaslayer users disable <user> | saaslayer users enable <user>
176
+ Sign the user out everywhere and refuse sign-in / allow it again (grants and credentials are kept). The last
177
+ usable owner of an org can't be disabled.
178
+ saaslayer users delete <suid> --yes [--email E]
179
+ GDPR delete everywhere (sign-in, passwordless data, profile). --email finds a user that was never projected.
180
+ saaslayer users reset-password <user>
181
+ Cognito mails a reset code to the verified email; the current password stops working.
182
+ saaslayer users set-password <user> --password-stdin [--temporary]
183
+ Permanent unless --temporary (replaced at next sign-in). Needs EnablePasswordInitialization (never prod);
184
+ access admins are refused.
185
+ saaslayer users adopt <user> [--password-stdin]
186
+ Adopt an account made outside SaaSLayer's routes (self sign-up, the Cognito console); --password-stdin then
187
+ sets its password. Needs EnablePasswordInitialization (never prod).
188
+ Passwords are read from stdin only; a --password flag is refused.
189
+ saaslayer users reset-mfa <user> --reason "…"
190
+ For a user who lost every MFA factor: removes their passkeys and authenticator-app MFA and signs them out
191
+ everywhere, so they can enroll a new factor. Access admins only (never --iam); the reason
192
+ goes to the audit line. Resetting your own MFA needs a fresh MFA sign-in.
94
193
 
95
194
  Deploy & lifecycle (requires login + a connected AWS account):
96
195
  saaslayer aws connect --aws-account <id> [--region R] [--org ID] [--org-wide]
97
196
  Connect your AWS account to an org. Binds it to your active project by
98
197
  default; --org-wide lets any project in the org deploy into it.
99
- saaslayer project use <id> Set the active project for deploy/status.
100
- saaslayer stacks List the vendable stacks a project can deploy.
101
- saaslayer deploy [--services a,b] [--env prod] [--region R] [--target ACCT]
102
- [--commit-sha SHA] [--admin-email E] [--yes]
103
- Deploy the project's services into your connected account. Shows a cost
104
- estimate and asks to confirm (skip with --yes).
105
- saaslayer status [--project ID] [--region R]
106
- Show the deployed instances of a project.
198
+ saaslayer project use <id> Set the active project for deploy/status (a project id tnt_… or a customer id).
199
+ saaslayer project destroy [<id>] [--yes]
200
+ Delete a project (the active one by default) and release its public name for reuse. Refused while any of its
201
+ deployments is live: destroy each with \`saaslayer destroy\` first. Asks for the id to be typed unless --yes.
202
+ saaslayer stacks List the modules a project can deploy: module id, regions, required
203
+ modules and stable outputs.
204
+ saaslayer deploy [--services a,b | --module M ...] [--set MODULE.Setting=VALUE ...] [--settings FILE] [--env prod]
205
+ [--region R] [--target ACCT] [--commit-sha SHA] [--admin-email E] [--yes]
206
+ Deploy the project's modules into your connected account. --services/--module and --set take catalog module
207
+ ids (\`saaslayer stacks\`, e.g. permissions-service); an unknown id or a missing required module is refused before
208
+ anything is sent. --settings FILE is { "<module>": { "<Setting>": value } }; --set overrides it (--param is
209
+ the same as --set). The settings are checked against the schema of the release being deployed (--commit-sha,
210
+ else the default release \`saaslayer stacks\` reports) before anything is sent, and the create-only ones are
211
+ listed; the control plane always checks them too. A secret takes ssm:/<parameter name>.
212
+ Asks before creating anything, then confirms any cost estimate (--yes answers both; required non-interactively).
213
+ saaslayer status [--project ID] [--env E] [--region R]
214
+ Show the deployed instances of a project. --project takes a project id (tnt_…) or a customer id. Every scoped
215
+ command prints \`scope: org=… project=… env=… (from: …)\` on stderr first (--json omits it); an empty result
216
+ lists the projects you can see that do have deployments.
107
217
  saaslayer service add <service> [--region R]
108
- saaslayer service remove <service> --data-custody delete|retain [--region R]
109
- Add or remove a single service on an existing deployment.
110
- saaslayer update --commit-sha SHA [--param SVC.Param=VALUE ...] [--env E] [--region R] [--reason TEXT] [--force]
111
- Roll an existing deployment's services to a new commit (upgrade; deploy only creates), and/or change
112
- update-safe settings with --param (repeatable; without --commit-sha the current commit is kept), e.g.
113
- --param user-service.AllowedAppOrigins=https://app.example.com. Protected envs (staging, prod) need
114
- --reason; --force updates past the drift gate (audited with the reason).
218
+ saaslayer service remove <service> --data-custody delete|retain [--region R] [--reason TEXT] [--yes]
219
+ Add or remove a single service on an existing deployment. A protected env (staging, prod) removal needs --reason
220
+ and the service name typed to confirm (--yes confirms it).
221
+ saaslayer update --commit-sha SHA [--env E] [--region R] [--reason TEXT] [--force]
222
+ Roll an existing deployment's services to a new release (upgrade; deploy only creates). Protected envs
223
+ (staging, prod) need --reason; --force updates past the drift gate (audited with the reason).
224
+ saaslayer migrations approve --env E [--region R] --run <runId> --reason TEXT [--no-wait]
225
+ Approve the migrations an update left awaiting approval (a protected env's destructive contract migrations, e.g. a
226
+ rename's retire step): \`saaslayer update\` prints the run id. The control plane records you and the reason.
227
+ saaslayer update --param MODULE.Setting=VALUE ... [--env E] [--region R] [--reason TEXT]
228
+ Change settings, keeping the current release: --param goes through the settings route, exactly like
229
+ \`saaslayer settings set --set\`. --commit-sha and --param cannot be combined: move the release, then set.
230
+ saaslayer update --manifest FILE [--env E] [--region R] [--settings F] [--reason TEXT] [--force] [--dry-run]
231
+ Promote a tested release manifest to this environment. Preflight first, nothing sent on any problem: the CLI
232
+ version the release was tested with, every deployed module in the bundle, each module's published settings
233
+ contract matching the manifest's sha256, schema transitions from the deployed revision (a set setting the target
234
+ drops or refuses, a changed create-only default), the environment's settings (environments.<env>.settings in
235
+ the manifest, or --settings) against the target contracts, direct-mode readers (permissionsDirectMode.readers) against
236
+ what the release writes, and --reason for staging/prod. Then moves the release through the update route, waits,
237
+ and writes the settings that differ through the settings route. --dry-run prints the preflight and plan only.
238
+ saaslayer release-manifest create --env E [--region R] [--out FILE] [--name NAME]
239
+ Record a tested deployment as a release manifest: its revision, each module's settings-contract sha256, this
240
+ CLI's version and what its permissions service writes. Add permissionsDirectMode.readers and environments.<env>.settings yourself.
241
+ saaslayer settings schema --module M [--revision SHA] [--env E] [--json]
242
+ Print a module's published settings schema: type, update behavior (update-safe | create-only), kind
243
+ (deployment | runtime), secret, billing impact, default. Without --revision, the revision the selected
244
+ deployment runs.
245
+ saaslayer settings get --env E [--region R] [--json]
246
+ Print a deployment's settings: value and source (set | default | unset), the settings revision and any
247
+ pending operation. A secret shows only whether it is set.
248
+ saaslayer settings set --env E (--set MODULE.Setting=VALUE ... | --file settings.<env>.json) [--reason TEXT] [--no-wait]
249
+ Change settings (null in a file resets one to its default; omitted settings are untouched). Checked against
250
+ the deployment's schema before anything is sent: create-only, runtime and unknown settings are refused, and
251
+ a secret takes a reference (ssm:/<parameter name>, or { "ssmParameter": "/<name>" } in a file), never the
252
+ value. Sent with the settings revision just read, so a concurrent change is refused (re-read and retry).
253
+ A billing change and the protected envs (staging, prod) need --reason. Waits for the update operation.
254
+ saaslayer settings diff --env A --env B [--manifest release.json] [--json]
255
+ Compare two environments: module revisions, differing settings (create-only and secret marked; secrets as
256
+ set/unset) and each settings revision, plus the gaps between them. With --manifest, each environment is also
257
+ checked against the release: modules outside or behind the bundle, bundle modules it lacks, the
258
+ permission-doc format it writes, and its deployed values against environments.<env>.settings.
259
+ Every settings command prints its scope and the deployment id on stderr (--json omits them).
115
260
  saaslayer destroy --data-custody delete|retain [--region R] [--yes]
116
261
  Tear down the project's deployment (typed-name confirmation).
262
+ saaslayer operations get <operationId> [--deployment ID] [--json]
263
+ saaslayer operations watch <operationId> [--deployment ID] [--interval SECONDS]
264
+ Show (get) or wait for (watch) an operation: a deploy, update, service add/remove or destroy and each
265
+ component's outcome. deploy, update, destroy and service add|remove wait for their operation by default
266
+ (--no-wait returns once it starts); after a dropped connection resume with \`operations watch\`. Without
267
+ --deployment the deployment is resolved from --project/--env/--region. A failed or partial operation exits
268
+ non-zero and names the next supported command. A retried command replays its operation; request keys are kept
269
+ 7 days.
270
+ saaslayer operations cancel <operationId> [--deployment ID] [--reason TEXT] [--json]
271
+ Cancel an in-flight operation: stops its run and releases the deployment for the next command. The deployment's
272
+ activity records who cancelled it and the reason. A finished operation is refused.
273
+ saaslayer first-admin resend [--deployment ID | --env E --region R] [--reason TEXT] [--no-wait]
274
+ saaslayer first-admin recover --email E --reason TEXT [--suid ID] [--deployment ID | --env E --region R] [--no-wait]
275
+ The deployment's first administrator (needs saaslayer:deployer:deployment:admin-bootstrap; org owners hold it).
276
+ resend delivers the designated admin's first sign-in again (the only rotation of its temporary password;
277
+ refused once they activated). recover designates a new first admin (--email, optional --suid) and is refused
278
+ with ADMIN_EXISTS while any usable access admin remains. Both wait for their operation.
279
+ saaslayer activity --env E [--region R | --deployment ID] [--limit N] [--json]
280
+ A deployment's activity, newest first: every change — yours and any SaaSLayer operator's — with who made it
281
+ (customer:<id> | operator:<id>), the action, what it touched, the reason and its operation id.
117
282
 
118
283
  Data migrations you run yourself (a deployment with migrationRunner self):
119
284
  saaslayer migrate status --deployment <id> [--service <ref>]
@@ -176,29 +341,50 @@ async function main() {
176
341
  const [cmd, sub] = positional
177
342
  try {
178
343
  if (cmd === 'init') return cmdInit({ flags })
179
- if (cmd === 'rbac' && sub === 'inspect') { await require('../src/commands/rbac-inspect').rbacInspect(positional.slice(2), flags); return }
180
- if (cmd === 'rbac' && sub === 'register') { await require('../src/commands/catalog').rbacRegister(positional.slice(2), flags); return }
181
- if (cmd === 'catalog' && sub === 'apply') { await require('../src/commands/catalog').catalogApply(positional.slice(2), flags); return }
182
- if (cmd === 'catalog' && sub === 'bootstrap-owner') { const a = await require('../src/commands/catalog').catalogBootstrapOwner(positional.slice(2), flags); console.log(`${a.userId} is now ${a.roleId} of ${a.scope}`); return }
183
- if (cmd === 'catalog' && sub === 'reconcile-owners') {
184
- const r = await require('../src/commands/catalog').catalogReconcileOwners(positional.slice(2), flags)
344
+ if (cmd === 'permissions' && sub === 'inspect') { await require('../src/commands/permissions-inspect').permissionsInspect(positional.slice(2), flags); return }
345
+ if (cmd === 'permissions' && sub === 'register') { await require('../src/commands/catalog').permissionsRegister(positional.slice(2), flags); return }
346
+ if (cmd === 'permissions' && sub === 'model' && positional[2] === 'apply') { await require('../src/commands/catalog').catalogApply(positional.slice(3), flags); return }
347
+ 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 }
348
+ if (cmd === 'permissions' && sub === 'owner' && positional[2] === 'reconcile') {
349
+ const r = await require('../src/commands/catalog').catalogReconcileOwners(positional.slice(3), flags)
185
350
  for (const o of r.orgs) console.log(`${o.ok ? 'ok ' : 'DRIFT'} ${o.orgId} counter=${o.counter} actual=${o.actual}`)
186
351
  console.log(r.applied ? 'repaired mismatched counters' : 'report only (pass --apply to repair)')
187
352
  return
188
353
  }
189
- if (cmd === 'catalog' && sub === 'export') { await require('../src/commands/catalog').catalogExport(positional.slice(2), flags); return }
190
- if (cmd === 'catalog' && sub === 'get') { console.log(JSON.stringify(await require('../src/commands/catalog').catalogGet(positional.slice(2), flags), null, 2)); return }
191
- if (cmd === 'rbac' && sub === 'iam-principals') {
192
- const iamp = require('../src/commands/iam-principals')
193
- if (positional[2] === 'set') { const name = iamp.iamPrincipalsSet(positional.slice(3), flags); console.log(`wrote ${name} (takes effect within ~60s)`); return }
194
- if (positional[2] === 'get') { console.log(JSON.stringify(iamp.iamPrincipalsGet(positional.slice(3), flags), null, 2)); return }
195
- console.error('usage: saaslayer rbac iam-principals <set <file>|get> --deployment DEP --region R'); process.exit(1)
354
+ if (cmd === 'permissions' && sub === 'model' && positional[2] === 'export') { await require('../src/commands/catalog').catalogExport(positional.slice(3), flags); return }
355
+ if (cmd === 'permissions' && sub === 'model' && positional[2] === 'get') { console.log(JSON.stringify(await require('../src/commands/catalog').catalogGet(positional.slice(3), flags), null, 2)); return }
356
+ if (cmd === 'permissions' && sub === 'service-principal') {
357
+ const sp = require('../src/commands/service-principals')
358
+ if (positional[2] === 'roles') { console.log(JSON.stringify(await sp.servicePrincipalRoles(positional.slice(3), flags), null, 2)); return }
359
+ 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 }
360
+ if (positional[2] === 'unassign') { await sp.servicePrincipalUnassign(positional.slice(3), flags); console.log(`revoked ${flags.role}`); return }
361
+ console.error('usage: saaslayer permissions service-principal <roles|assign|unassign> (<id> | --machine PRINCIPAL) [--role ROLE] [--scope S] --api-base URL'); process.exit(1)
362
+ }
363
+ if (cmd === 'permissions' && sub === 'machine-trust') {
364
+ const trust = require('../src/commands/machine-trust')
365
+ const rest = positional.slice(3)
366
+ const print = (/** @type {unknown} */ v) => console.log(JSON.stringify(v, null, 2))
367
+ if (positional[2] === 'list') { print(await trust.machineTrustList(rest, flags)); return }
368
+ if (positional[2] === 'get') { print(await trust.machineTrustGet(rest, flags)); return }
369
+ if (positional[2] === 'declare') { print(await trust.machineTrustDeclare(rest, flags)); return }
370
+ if (positional[2] === 'update') { print(await trust.machineTrustUpdate(rest, flags)); return }
371
+ if (positional[2] === 'remove') { print(await trust.machineTrustRemove(rest, flags)); return }
372
+ if (positional[2] === 'reconcile') { print(await trust.machineTrustReconcile(rest, flags)); return }
373
+ console.error('usage: saaslayer permissions machine-trust <list|get|declare|update|remove|reconcile> [principalId] --api-base URL'); process.exit(1)
374
+ }
375
+ if (cmd === 'permissions' && sub === 'access-admins') {
376
+ const admins = require('../src/commands/access-admins')
377
+ const rest = positional.slice(3)
378
+ const run = { list: admins.adminsList, offer: admins.adminsOffer, status: admins.adminsStatus, cancel: admins.adminsCancel, accept: admins.adminsAccept, activate: admins.adminsActivate }[positional[2]]
379
+ if (run) { console.log(JSON.stringify(await run(rest, flags), null, 2)); return }
380
+ console.error('usage: saaslayer permissions access-admins <list|offer|status|cancel|accept|activate> [suid|transferId] --api-base URL'); process.exit(1)
196
381
  }
197
382
  if (cmd === 'users') {
198
383
  const users = require('../src/commands/users')
199
384
  if (sub === 'export') { await users.usersExport(flags); return }
200
385
  if (sub === 'import') { await users.usersImport(flags); return }
201
- console.error('usage: saaslayer users <export|import> … (see saaslayer --help)'); process.exit(1)
386
+ if (users.ADMIN_COMMANDS.includes(sub)) { await users.usersAdmin(sub, positional.slice(2), flags); return }
387
+ console.error(users.USAGE); process.exit(1)
202
388
  }
203
389
  if (cmd === 'signup') {
204
390
  const { signup } = require('../src/commands/login')
@@ -207,22 +393,51 @@ async function main() {
207
393
  return
208
394
  }
209
395
  if (cmd === 'login') {
210
- const { login } = require('../src/commands/login')
396
+ const { login, loginDeployment } = require('../src/commands/login')
397
+ if (flags.deployment) {
398
+ const who = await loginDeployment(flags)
399
+ console.log(`logged in to deployment ${who.deploymentId}${who.environment ? ` [${who.environment}]` : ''} (user-service ${who.serviceInstance}) as ${who.email} — control-plane login unchanged`)
400
+ return
401
+ }
211
402
  const who = await login(flags)
212
403
  console.log(`logged in as ${who.email}`)
213
404
  return
214
405
  }
215
406
  if (cmd === 'logout') {
216
407
  const { logout } = require('../src/commands/login')
217
- logout(flags)
218
- console.log('logged out')
408
+ const out = logout(flags)
409
+ console.log(out.authority === 'deployment' ? `logged out of deployment ${out.deploymentId} (${out.email}) — control-plane login unchanged` : 'logged out')
410
+ return
411
+ }
412
+ if (cmd === 'deployment' && (sub === 'logins' || sub === 'use')) {
413
+ const { deploymentLogins, deploymentUse } = require('../src/commands/accounts')
414
+ if (sub === 'use') {
415
+ const d = deploymentUse({ ...flags, deployment: positional[2] || flags.deployment })
416
+ console.log(`current deployment login: ${d.deploymentId}${d.environment ? ` [${d.environment}]` : ''} (user-service ${d.serviceInstance}) as ${d.email}`)
417
+ return
418
+ }
419
+ const rows = deploymentLogins()
420
+ if (!rows.length) { console.log('no deployment logins — run `saaslayer login --deployment <dep_id|env>`'); return }
421
+ for (const r of rows) {
422
+ const expired = r.expired === true ? ` (token expired — run \`saaslayer login --deployment ${r.deploymentId}\`)` : ''
423
+ console.log(`${r.current ? '*' : ' '} ${r.deploymentId}${r.environment ? ` [${r.environment}]` : ''} user-service ${r.serviceInstance} ${r.email || r.userId}${expired}`)
424
+ }
425
+ console.log('\n* = current. Switch with: saaslayer deployment use <dep_id|env> [--as <email>]')
219
426
  return
220
427
  }
221
428
  if (cmd === 'whoami') {
222
429
  const { whoami } = require('../src/commands/login')
223
430
  const who = whoami()
224
431
  if (!who) { console.log('not logged in'); return }
225
- console.log(`${who.email} (${who.env})`)
432
+ console.log(`${who.email} (control plane: ${who.env})`)
433
+ const ctx = require('../src/context-store').load()
434
+ console.log(`org: ${ctx.org || '—'} project: ${ctx.project ? `${ctx.project} (${require('../src/scope').projectIdKind(ctx.project)})` : '—'} (see: saaslayer context)`)
435
+ return
436
+ }
437
+ if (cmd === 'context') {
438
+ const { contextShow, formatContext } = require('../src/commands/context')
439
+ const ctx = contextShow(flags)
440
+ console.log(flags.json ? JSON.stringify(ctx, null, 2) : formatContext(ctx).join('\n'))
226
441
  return
227
442
  }
228
443
  if (cmd === 'accounts' || (cmd === 'account' && (sub === 'list' || sub === undefined))) {
@@ -253,8 +468,9 @@ async function main() {
253
468
  if (cmd === 'project') {
254
469
  const orgs = require('../src/commands/orgs')
255
470
  if (sub === 'create') { const p = await orgs.projectCreate(flags, positional[2]); console.log(`created project ${p.name || ''} (${p.id}) in org ${p.orgId}`); return }
256
- if (sub === 'use') { const id = positional[2]; if (!id) throw new Error('project use requires a project id'); require('../src/context-store').set('project', id); console.log(`active project: ${id}`); return }
257
- console.error('usage: saaslayer project <create <name>|use <id>>'); process.exit(1)
471
+ if (sub === 'use') { const id = positional[2]; if (!id) throw new Error('project use requires a project id'); require('../src/context-store').set('project', id); console.log(`active project: ${id} (${require('../src/scope').projectIdKind(id)})`); return }
472
+ if (sub === 'destroy') { await orgs.projectDestroy(flags, positional[2]); return }
473
+ console.error('usage: saaslayer project <create <name>|use <id>|destroy [<id>]>'); process.exit(1)
258
474
  }
259
475
  if (cmd === 'projects') {
260
476
  const orgs = require('../src/commands/orgs')
@@ -267,22 +483,37 @@ async function main() {
267
483
  if (sub === 'connect') { await aws.awsConnect(flags); return }
268
484
  console.error('usage: saaslayer aws connect --aws-account <id> [--region <r>] [--org-wide]'); process.exit(1)
269
485
  }
486
+ if (cmd === 'foundation') {
487
+ const foundation = require('../src/commands/foundation')
488
+ if (sub === 'status') { await foundation.foundationStatus(flags); return }
489
+ if (sub === 'upgrade') { await foundation.foundationUpgrade(flags); return }
490
+ console.error('usage: saaslayer foundation <status|upgrade> [--region R] [--profile P] (see saaslayer --help)'); process.exit(1)
491
+ }
270
492
  if (cmd === 'stacks') { const { stacks } = require('../src/commands/stacks'); await stacks(flags); return }
271
493
  if (cmd === 'deploy') { const { deploy } = require('../src/commands/deploy'); await deploy(flags); return }
272
494
  if (cmd === 'status') { const { status } = require('../src/commands/lifecycle'); await status(flags); return }
273
495
  if (cmd === 'update') { const { update } = require('../src/commands/lifecycle'); await update(flags); return }
274
496
  if (cmd === 'destroy') { const { destroy } = require('../src/commands/lifecycle'); await destroy(flags); return }
497
+ if (cmd === 'migrations') {
498
+ if (sub === 'approve') { const { approveMigrations } = require('../src/commands/lifecycle'); await approveMigrations(flags); return }
499
+ console.error('usage: saaslayer migrations approve --env E [--region R] --run <runId> --reason <text>'); process.exit(1)
500
+ }
275
501
  if (cmd === 'migrate') {
276
502
  const { migrate } = require('../src/commands/migrate')
277
503
  const result = await migrate(sub, flags)
278
504
  process.exitCode = result.exitCode
279
505
  return
280
506
  }
507
+ if (cmd === 'release-manifest') { const { releaseManifestCommand } = require('../src/commands/release-manifest'); await releaseManifestCommand(sub, flags); return }
508
+ if (cmd === 'settings') { const { settingsCommand } = require('../src/commands/settings'); await settingsCommand(sub, flags); return }
509
+ if (cmd === 'first-admin') { const { firstAdminCommand } = require('../src/commands/first-admin'); await firstAdminCommand(sub, flags); return }
510
+ if (cmd === 'activity') { const { activityCommand } = require('../src/commands/activity'); await activityCommand(flags); return }
511
+ if (cmd === 'operations' || cmd === 'operation') { const { operationsCommand } = require('../src/commands/operations'); await operationsCommand(sub, positional[2], flags); return }
281
512
  if (cmd === 'service') {
282
513
  const lc = require('../src/commands/lifecycle')
283
514
  if (sub === 'add') { await lc.serviceAdd(positional[2], flags); return }
284
515
  if (sub === 'remove') { await lc.serviceRemove(positional[2], flags); return }
285
- console.error('usage: saaslayer service <add|remove> <service> [--data-custody delete|retain]'); process.exit(1)
516
+ console.error('usage: saaslayer service <add|remove> <service> [--data-custody delete|retain] [--reason TEXT] [--yes]'); process.exit(1)
286
517
  }
287
518
  console.error(`Unknown command: ${positional.join(' ')}\n`); console.log(HELP); process.exit(1)
288
519
  } catch (err) {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "saaslayer",
3
- "version": "0.0.7",
4
- "description": "SaaSLayer CLI \u2014 onboard an account (init) and register a service's RBAC manifest.",
3
+ "version": "0.1.0",
4
+ "description": "SaaSLayer CLI — onboard an account (init) and register a service's permissions manifest.",
5
5
  "type": "commonjs",
6
6
  "bin": {
7
7
  "saaslayer": "bin/saaslayer.js"
@@ -31,6 +31,7 @@
31
31
  "keywords": [
32
32
  "saaslayer",
33
33
  "cli",
34
+ "permissions",
34
35
  "rbac",
35
36
  "aws",
36
37
  "cloudformation",
@@ -40,7 +41,7 @@
40
41
  "access": "public"
41
42
  },
42
43
  "scripts": {
43
- "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/catalog.test.js && node test/catalog-registry.test.js && node test/rbac-inspect.test.js && node test/iam.test.js && node test/iam-principals.test.js && node test/package-files.test.js && node test/users-export.test.js && node test/users-import.test.js && node test/migrate.test.js && node test/foundation-template.test.js && echo ok",
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/migrations-approve.test.js && node test/service-remove.test.js && node test/settings.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/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/first-admin.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.test.js && node test/migrate.test.js && node test/foundation-template.test.js && node test/foundation.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 && echo ok",
44
45
  "sync-template": "node scripts/sync-template.js",
45
46
  "sync-template:check": "node scripts/sync-template.js --check",
46
47
  "prepublishOnly": "node scripts/sync-template.js",