saaslayer 0.3.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 (60) hide show
  1. package/README.md +105 -16
  2. package/bin/saaslayer.js +321 -60
  3. package/package.json +3 -2
  4. package/src/aws-sigv4.js +74 -26
  5. package/src/commands/access-admins.js +2 -2
  6. package/src/commands/admin-allowlist.js +23 -3
  7. package/src/commands/api-keys.js +83 -0
  8. package/src/commands/audit.js +77 -0
  9. package/src/commands/aws.js +355 -82
  10. package/src/commands/binding-handoff.js +174 -0
  11. package/src/commands/bindings.js +111 -0
  12. package/src/commands/catalog.js +30 -3
  13. package/src/commands/deploy.js +33 -10
  14. package/src/commands/env-export.js +58 -0
  15. package/src/commands/first-admin.js +15 -4
  16. package/src/commands/foundation.js +75 -117
  17. package/src/commands/hooks.js +271 -0
  18. package/src/commands/integration-credentials.js +1 -1
  19. package/src/commands/lifecycle.js +149 -24
  20. package/src/commands/login-domain.js +259 -0
  21. package/src/commands/permission-orgs.js +80 -0
  22. package/src/commands/release-manifest.js +17 -8
  23. package/src/commands/service-principals.js +42 -5
  24. package/src/commands/settings.js +21 -5
  25. package/src/commands/sms-registration.js +182 -0
  26. package/src/commands/sms.js +178 -0
  27. package/src/commands/social.js +265 -0
  28. package/src/commands/support-staff.js +72 -0
  29. package/src/commands/users-management.js +2 -20
  30. package/src/commands/users.js +56 -11
  31. package/src/commands/versions.js +61 -0
  32. package/src/connection-proof.js +41 -0
  33. package/src/deployments.js +1 -1
  34. package/src/foundation-change-set.js +180 -0
  35. package/src/foundation-home.js +121 -0
  36. package/src/foundation-template.js +51 -10
  37. package/src/foundation-trust-write.js +379 -0
  38. package/src/iam-session.js +14 -8
  39. package/src/login-domain.js +139 -0
  40. package/src/login-methods.js +118 -0
  41. package/src/module-catalog.js +3 -2
  42. package/src/release-manifest.js +11 -4
  43. package/src/scope.js +3 -1
  44. package/src/settings.js +85 -13
  45. package/src/sms/number.js +37 -0
  46. package/src/sms/registration-fields.js +167 -0
  47. package/src/sms/registration-validate.js +151 -0
  48. package/src/sms/registration.js +216 -0
  49. package/src/sms/release.js +55 -0
  50. package/src/sms/scope.js +86 -0
  51. package/src/sms/status.js +181 -0
  52. package/src/ssm-api.js +31 -0
  53. package/src/trust-entries.js +350 -0
  54. package/src/user-service-instance.js +27 -0
  55. package/src/users-api.js +55 -8
  56. package/src/users-import/checkpoint.js +76 -0
  57. package/src/users-import/import.js +233 -24
  58. package/src/versions.js +80 -0
  59. package/templates/saaslayer-foundation-region.yml +45 -1
  60. package/templates/saaslayer-foundation.yml +747 -296
package/src/users-api.js CHANGED
@@ -1,5 +1,6 @@
1
1
  // A deployment's user-service /api/users for CLI commands: create (durable operation, Idempotency-Key), operation status,
2
- // lookup and paging, profile updates, sign-in state, passwords, adoption and delete — with the auth headers a caller gives.
2
+ // lookup, paging and batch profile reads, profile and reserved-attribute updates, sign-in state, passwords, adoption and delete
3
+ // — with the auth headers a caller gives.
3
4
  'use strict'
4
5
  const crypto = require('crypto')
5
6
 
@@ -13,16 +14,28 @@ const crypto = require('crypto')
13
14
  * @typedef {{ email: string, password?: string, name?: string, soid?: string, suid?: string, delivery?: 'none'|'invitation' }} CreateAttributes
14
15
  */
15
16
 
16
- /** A refusal from user-service, with its HTTP status and error code. */
17
+ /** A refusal from user-service, with its HTTP status, error code and the response meta (a create's operation). */
17
18
  class UsersApiError extends Error {
18
- /** @param {number} status @param {string} code @param {string} message */
19
- constructor(status, code, message) {
19
+ /** @param {number} status @param {string} code @param {string} message @param {{ operation?: Operation }} [meta] */
20
+ constructor(status, code, message, meta) {
20
21
  super(message)
21
22
  this.status = status
22
23
  this.code = code
24
+ this.meta = meta
23
25
  }
24
26
  }
25
27
 
28
+ /** One batch read of profiles holds at most this many suids (user-service's limit). */
29
+ const BATCH_SUIDS = 100
30
+
31
+ /** @param {any} body @param {number} status */
32
+ function errorOf(body, status) {
33
+ const errors = (body && body.errors) || []
34
+ const code = (errors[0] && errors[0].code) || 'ERROR'
35
+ const detail = errors.map((e) => e.title || e.message || e.detail).filter(Boolean).join('; ') || `HTTP ${status}`
36
+ return { code, detail }
37
+ }
38
+
26
39
  /** @param {string} suid @param {string} [action] */
27
40
  const userPath = (suid, action) => `/api/users/${encodeURIComponent(suid)}${action ? `/${action}` : ''}`
28
41
 
@@ -66,10 +79,8 @@ function usersApi(target, { fetch: fetchImpl = fetch } = {}) {
66
79
  })
67
80
  const body = await res.json().catch(() => ({}))
68
81
  if (!res.ok) {
69
- const errors = body.errors || []
70
- const code = (errors[0] && errors[0].code) || 'ERROR'
71
- const detail = errors.map((e) => e.message || e.detail).filter(Boolean).join('; ') || `HTTP ${res.status}`
72
- throw new UsersApiError(res.status, code, `${method} ${path.split('?')[0]} refused (${res.status} ${code}: ${detail})`)
82
+ const { code, detail } = errorOf(body, res.status)
83
+ throw new UsersApiError(res.status, code, `${method} ${path.split('?')[0]} refused (${res.status} ${code}: ${detail})`, body.meta)
73
84
  }
74
85
  return { status: res.status, body }
75
86
  }
@@ -86,6 +97,38 @@ function usersApi(target, { fetch: fetchImpl = fetch } = {}) {
86
97
  const { status, body } = await call('POST', '/api/users', { headers: { 'idempotency-key': idempotencyKey }, body: { data: { attributes: attrs } } })
87
98
  return { status, user: body.data ? toUser(body.data) : null, operation: body.meta && body.meta.operation }
88
99
  },
100
+ /**
101
+ * A create without an Idempotency-Key, to learn whether the caller may create with a supplied suid without writing:
102
+ * user-service authorizes create + update-reserved (the suid is read from data.attributes) before it refuses the
103
+ * missing key. 400 IDEMPOTENCY_KEY_REQUIRED = both held; 403 = one is missing. Refusals are returned, never thrown.
104
+ * @param {string} email @param {string} suid
105
+ * @returns {Promise<{ status: number, code: string, message: string }>}
106
+ */
107
+ async probeCreate(email, suid) {
108
+ const res = await fetchImpl(`${base}/api/users`, {
109
+ method: 'POST',
110
+ headers: { 'content-type': 'application/json', ...(await target.headers()) },
111
+ body: JSON.stringify({ data: { attributes: { email, suid } } }),
112
+ })
113
+ const body = await res.json().catch(() => ({}))
114
+ const { code, detail } = errorOf(body, res.status)
115
+ return { status: res.status, code: res.ok ? 'OK' : code, message: res.ok ? '' : detail }
116
+ },
117
+ /**
118
+ * Which of these suids have a user-service profile (users:read), read in batches of 100.
119
+ * @param {string[]} suids
120
+ * @returns {Promise<{ present: Set<string>, missing: Set<string> }>}
121
+ */
122
+ async profiles(suids) {
123
+ const present = new Set()
124
+ const missing = new Set()
125
+ for (let i = 0; i < suids.length; i += BATCH_SUIDS) {
126
+ const { body } = await call('POST', '/api/users/batch', { body: { suids: suids.slice(i, i + BATCH_SUIDS) } })
127
+ for (const d of body.data || []) present.add(d.id)
128
+ for (const suid of (body.meta && body.meta.missing) || []) missing.add(suid)
129
+ }
130
+ return { present, missing }
131
+ },
89
132
  /** @param {string} id @returns {Promise<Operation>} */
90
133
  async getOperation(id) {
91
134
  return (await call('GET', `/api/users/operations/${encodeURIComponent(id)}`)).body.data.attributes
@@ -114,6 +157,10 @@ function usersApi(target, { fetch: fetchImpl = fetch } = {}) {
114
157
  async update(suid, attributes) {
115
158
  return toUser((await call('PATCH', userPath(suid), { body: { data: { attributes } } })).body.data)
116
159
  },
160
+ /** Reserved fields (email, email_verified, soid). @param {string} suid @param {Record<string, string|boolean>} attributes @returns {Promise<User>} */
161
+ async updateReserved(suid, attributes) {
162
+ return toUser((await call('PATCH', userPath(suid, 'reserved-attributes'), { body: { data: { attributes } } })).body.data)
163
+ },
117
164
  /** @param {string} suid @returns {Promise<User>} */
118
165
  async disable(suid) {
119
166
  return toUser((await call('POST', userPath(suid, 'disable'))).body.data)
@@ -0,0 +1,76 @@
1
+ // `saaslayer users import` profiles checkpoint: per person, the exact create (Idempotency-Key + body) and its outcome,
2
+ // bound to one pool + users API and written atomically, so an interrupted run resumes unfinished creates as sent.
3
+ 'use strict'
4
+ const nodeFs = require('fs')
5
+ const path = require('path')
6
+
7
+ /**
8
+ * @typedef {'sent'|'done'|'failed'|'conflict'|'anomaly'} CheckpointState
9
+ * @typedef {{ key: string, body: unknown, state: CheckpointState, operationId?: string, updatedAt: string }} CheckpointEntry
10
+ * @typedef {{ userPoolId: string, usersApiBase: string }} CheckpointTarget
11
+ */
12
+
13
+ /** The checkpoint next to a manifest: `<manifest without .json>.profiles-checkpoint.json`. @param {string} manifestPath */
14
+ const checkpointPath = (manifestPath) => `${manifestPath.replace(/\.json$/, '')}.profiles-checkpoint.json`
15
+
16
+ /** @param {CheckpointTarget} t */
17
+ const describe = (t) => `pool ${t.userPoolId}, users API ${t.usersApiBase}`
18
+
19
+ /**
20
+ * Open (never create) the checkpoint at `file` for this target; the file is written on the first mark.
21
+ * A checkpoint of another target is refused, never ignored or applied.
22
+ * @param {string} file
23
+ * @param {CheckpointTarget} target
24
+ * @param {{ now?: () => Date, fs?: typeof nodeFs }} [deps]
25
+ */
26
+ function openCheckpoint(file, target, { now = () => new Date(), fs = nodeFs } = {}) {
27
+ /** @type {Record<string, CheckpointEntry>} */
28
+ let people = {}
29
+ if (fs.existsSync(file)) {
30
+ let saved
31
+ try {
32
+ saved = JSON.parse(fs.readFileSync(file, 'utf8'))
33
+ } catch (err) {
34
+ throw new Error(`users import: can't read the profiles checkpoint ${file} (${err.message}); move it aside only if no import is unfinished`)
35
+ }
36
+ const t = saved.target || {}
37
+ if (t.userPoolId !== target.userPoolId || t.usersApiBase !== target.usersApiBase) {
38
+ throw new Error(`users import: the profiles checkpoint ${file} belongs to ${describe(t)}, not ${describe(target)}; use that target or another manifest path`)
39
+ }
40
+ people = saved.people || {}
41
+ }
42
+ let writes = 0
43
+
44
+ /** Write to a temp file in the same directory, fsync, then rename over the checkpoint: a crash leaves the previous file. */
45
+ const save = () => {
46
+ const tmp = path.join(path.dirname(file), `${path.basename(file)}.tmp-${process.pid}-${++writes}`)
47
+ const fd = fs.openSync(tmp, 'w', 0o600)
48
+ try {
49
+ fs.writeSync(fd, JSON.stringify({ version: 1, target, people }, null, 2) + '\n')
50
+ fs.fsyncSync(fd)
51
+ } finally {
52
+ fs.closeSync(fd)
53
+ }
54
+ fs.renameSync(tmp, file)
55
+ }
56
+
57
+ return {
58
+ file,
59
+ /** @param {string} suid @returns {CheckpointEntry|undefined} */
60
+ get: (suid) => people[suid],
61
+ /** Record the create about to be sent (before the request). @param {string} suid @param {string} key @param {unknown} body */
62
+ markSent(suid, key, body) {
63
+ people[suid] = { key, body, state: 'sent', updatedAt: now().toISOString() }
64
+ save()
65
+ },
66
+ /** Record how the create ended. @param {string} suid @param {CheckpointState} state @param {{ operationId?: string }} [extra] */
67
+ markOutcome(suid, state, { operationId } = {}) {
68
+ people[suid] = { ...people[suid], state, ...(operationId ? { operationId } : {}), updatedAt: now().toISOString() }
69
+ save()
70
+ },
71
+ /** Creates to re-send with their stored key and body: sent (outcome unknown) or failed. */
72
+ pending: () => Object.entries(people).filter(([, e]) => e.state === 'sent' || e.state === 'failed').map(([suid, e]) => ({ suid, ...e })),
73
+ }
74
+ }
75
+
76
+ module.exports = { openCheckpoint, checkpointPath }
@@ -3,6 +3,8 @@
3
3
  // members and the first Owner.
4
4
  'use strict'
5
5
  const { OWNER, displayName } = require('./manifest')
6
+ const { usersApi, UsersApiError } = require('../users-api')
7
+ const { openCheckpoint } = require('./checkpoint')
6
8
 
7
9
  const TERMINAL_JOB_STATES = ['Succeeded', 'Failed', 'Stopped', 'Expired']
8
10
  const E164 = /^\+[1-9]\d{7,14}$/
@@ -46,26 +48,96 @@ function parseCsv(text) {
46
48
  /** @param {{ region: string, profile?: string, userPoolId: string }} target */
47
49
  const poolArgs = (target) => ['--user-pool-id', target.userPoolId, '--region', target.region, ...(target.profile ? ['--profile', target.profile] : [])]
48
50
 
51
+ /** @param {{ region: string, profile?: string }} target */
52
+ const awsScope = (target) => ['--region', target.region, ...(target.profile ? ['--profile', target.profile] : [])]
53
+
49
54
  /**
50
- * The import-job logs role the target pool's user-service stack publishes at /<stack>/user/pool/import-logs-role-arn,
51
- * or null when the pool isn't a stack resource or the stack predates the role.
55
+ * The CloudFormation stack the target pool belongs to (its user-service stack), or null when the pool isn't a stack resource.
52
56
  * @param {Function} exec
53
57
  * @param {{ userPoolId: string, region: string, profile?: string }} target
58
+ * @returns {string | null}
59
+ */
60
+ function poolStack(exec, target) {
61
+ try {
62
+ const resources = JSON.parse(exec('aws', ['cloudformation', 'describe-stack-resources', '--physical-resource-id', target.userPoolId, ...awsScope(target), '--output', 'json'])).StackResources || []
63
+ return resources.length ? resources[0].StackName : null
64
+ } catch {
65
+ return null
66
+ }
67
+ }
68
+
69
+ /**
70
+ * The import-job logs role the pool's user-service stack publishes at /<stack>/user/pool/import-logs-role-arn,
71
+ * or null when there is no stack or the stack predates the role.
72
+ * @param {Function} exec
73
+ * @param {{ region: string, profile?: string }} target
74
+ * @param {string | null} stack from poolStack
54
75
  * @returns {{ arn: string | null, parameter: string | null }}
55
76
  */
56
- function publishedLogsRole(exec, target) {
57
- const scope = ['--region', target.region, ...(target.profile ? ['--profile', target.profile] : [])]
58
- let parameter = null
77
+ function publishedLogsRole(exec, target, stack) {
78
+ if (!stack) return { arn: null, parameter: null }
79
+ const parameter = `/${stack}/user/pool/import-logs-role-arn`
59
80
  try {
60
- const resources = JSON.parse(exec('aws', ['cloudformation', 'describe-stack-resources', '--physical-resource-id', target.userPoolId, ...scope, '--output', 'json'])).StackResources || []
61
- if (!resources.length) return { arn: null, parameter }
62
- parameter = `/${resources[0].StackName}/user/pool/import-logs-role-arn`
63
- return { arn: JSON.parse(exec('aws', ['ssm', 'get-parameter', '--name', parameter, ...scope, '--output', 'json'])).Parameter.Value || null, parameter }
81
+ return { arn: JSON.parse(exec('aws', ['ssm', 'get-parameter', '--name', parameter, ...awsScope(target), '--output', 'json'])).Parameter.Value || null, parameter }
64
82
  } catch {
65
83
  return { arn: null, parameter }
66
84
  }
67
85
  }
68
86
 
87
+ /**
88
+ * The user-service API of the pool's stack (its ServiceEndpoint output), where the import creates profiles.
89
+ * @param {Function} exec
90
+ * @param {{ userPoolId: string, region: string, profile?: string }} target
91
+ * @param {string | null} stack from poolStack
92
+ * @returns {string} the API base
93
+ */
94
+ function publishedUsersApi(exec, target, stack) {
95
+ const missing = (why) => new Error(`users import: can't find the user-service API for pool ${target.userPoolId}: ${why}`)
96
+ if (!stack) throw missing('the pool is not a resource of a CloudFormation stack')
97
+ let outputs = []
98
+ try {
99
+ outputs = (JSON.parse(exec('aws', ['cloudformation', 'describe-stacks', '--stack-name', stack, ...awsScope(target), '--output', 'json'])).Stacks || [])[0].Outputs || []
100
+ } catch {
101
+ outputs = []
102
+ }
103
+ const endpoint = (outputs.find((o) => o.OutputKey === 'ServiceEndpoint') || {}).OutputValue
104
+ if (!endpoint) throw missing(`the pool's stack ${stack} has no ServiceEndpoint output`)
105
+ return endpoint
106
+ }
107
+
108
+ // The preflight's placeholder person: never a real account (the .invalid domain can't receive mail).
109
+ const PREFLIGHT_SUID = 'saaslayer-users-import-preflight'
110
+ const PREFLIGHT_EMAIL = 'users-import-preflight@saaslayer.invalid'
111
+
112
+ /**
113
+ * Whether the credential holds every user-service permission the profile step needs, checked without writing: a batch
114
+ * read (users:account:read) and a key-less create with a supplied suid, which user-service authorizes (account:create +
115
+ * account:update-reserved, the suid being read from data.attributes) before it refuses the missing key with exactly 400
116
+ * IDEMPOTENCY_KEY_REQUIRED. A flat body would be checked for create only, so the probe always sends the envelope.
117
+ * @param {ReturnType<typeof usersApi>} users
118
+ * @param {{ iam?: string }} target
119
+ * @returns {Promise<{ ok: true } | { ok: false, message: string }>}
120
+ */
121
+ async function preflightProfiles(users, target) {
122
+ const who = target.iam ? `the IAM principal ${target.iam}` : 'the IAM principal'
123
+ const missingScopes = (detail) => ({ ok: false, message: `users import: ${who} needs users:read and users:write-reserved (plus users:write, orgs:write, owners:bootstrap) and their grants: ${detail}` })
124
+ const unchecked = (detail) => ({ ok: false, message: `users import: couldn't check the user-service permissions the profiles need (${detail})` })
125
+ try {
126
+ await users.profiles([PREFLIGHT_SUID])
127
+ } catch (err) {
128
+ return err instanceof UsersApiError && err.status === 403 ? missingScopes(err.message) : unchecked(err.message)
129
+ }
130
+ let probe
131
+ try {
132
+ probe = await users.probeCreate(PREFLIGHT_EMAIL, PREFLIGHT_SUID)
133
+ } catch (err) {
134
+ return unchecked(`POST /api/users: ${err.message}`)
135
+ }
136
+ if (probe.status === 400 && probe.code === 'IDEMPOTENCY_KEY_REQUIRED') return { ok: true }
137
+ const answer = `POST /api/users answered ${probe.status} ${probe.code}: ${probe.message}`
138
+ return probe.status === 403 ? missingScopes(answer) : unchecked(answer)
139
+ }
140
+
69
141
  /** @param {Array<{ Name: string, Value: string }>} list @param {string} name */
70
142
  const attr = (list, name) => ((list || []).find((a) => a.Name === name) || {}).Value || null
71
143
 
@@ -174,6 +246,120 @@ async function runImportJob(rows, plan, target, { exec, fetch, sleep, now }) {
174
246
  throw new Error(`users import: job ${created.JobId} did not finish; check it with aws cognito-idp describe-user-import-job`)
175
247
  }
176
248
 
249
+ /** The Idempotency-Key of a person's profile create: the same on every run, so a retry replays or resumes it. @param {string} suid */
250
+ const profileKey = (suid) => `users-import-profile:${suid}`
251
+
252
+ /**
253
+ * Send one profile create (exactly the stored key and body) and classify user-service's answer; the checkpoint records it.
254
+ * created = the profile was projected for the account already in the pool (200, created false, every component done);
255
+ * failed = unfinished (202: re-run resumes it) or refused; conflict = another account holds the email or suid; anomaly =
256
+ * user-service created an account (201): this step only projects accounts the import already put in the pool.
257
+ * A lost response (network) leaves the checkpoint at sent, so the next run re-sends it.
258
+ * @param {ReturnType<typeof usersApi>} users
259
+ * @param {ReturnType<typeof openCheckpoint>} checkpoint
260
+ * @param {string} suid @param {string} key @param {{ data: { attributes: Record<string, string> } }} body
261
+ * @returns {Promise<{ profile: 'created'|'failed'|'conflict'|'anomaly', note?: string, operationId?: string }>}
262
+ */
263
+ async function sendProfile(users, checkpoint, suid, key, body) {
264
+ const email = body.data.attributes.email
265
+ let answer
266
+ try {
267
+ answer = await users.create(body.data.attributes, key)
268
+ } catch (err) {
269
+ if (!(err instanceof UsersApiError)) return { profile: 'failed', note: `profile create: ${err.message}; re-run to resume` }
270
+ const operation = err.meta && err.meta.operation
271
+ const identity = operation && (operation.components || []).find((c) => c.name === 'identity' && c.status === 'failed')
272
+ if (err.status === 409 && identity && identity.error && ['EMAIL_EXISTS', 'SUID_EXISTS'].includes(identity.error.code)) {
273
+ checkpoint.markOutcome(suid, 'conflict', { operationId: operation.id })
274
+ return { profile: 'conflict', operationId: operation.id, note: `${identity.error.message || identity.error.code}; check it with \`saaslayer users get --email ${email}\`` }
275
+ }
276
+ checkpoint.markOutcome(suid, 'failed')
277
+ return { profile: 'failed', note: `profile create ${err.message}` }
278
+ }
279
+ const operation = answer.operation || { id: undefined, status: 'unknown', components: [] }
280
+ const operationId = operation.id
281
+ if (answer.status === 201 || (answer.user && answer.user.attributes.created === true)) {
282
+ checkpoint.markOutcome(suid, 'anomaly', { operationId })
283
+ return { profile: 'anomaly', operationId, note: `user-service created a new account for ${email} (operation ${operationId}): the pool changed under the import` }
284
+ }
285
+ const unfinished = (operation.components || []).find((c) => c.status !== 'succeeded' && c.status !== 'skipped')
286
+ if (answer.status === 200 && !unfinished) {
287
+ checkpoint.markOutcome(suid, 'done', { operationId })
288
+ return { profile: 'created', operationId }
289
+ }
290
+ checkpoint.markOutcome(suid, 'failed', { operationId })
291
+ const why = unfinished ? `${unfinished.name} ${unfinished.status}${unfinished.error ? ` (${unfinished.error.code}: ${unfinished.error.message})` : ''}` : operation.status
292
+ return { profile: 'failed', operationId, note: `profile unfinished (operation ${operationId}): ${why}; re-run to resume` }
293
+ }
294
+
295
+ /**
296
+ * Each created or linked person's user-service profile. Cognito runs no triggers for a CSV import, so without this a
297
+ * person has no profile until they first sign in. Unfinished creates in the checkpoint are re-sent first (stored key +
298
+ * body); then a profile is looked up by suid and, when missing, created with the person's own suid, never a password
299
+ * and delivery none — user-service finds the account by email (created false) and sends nothing.
300
+ * @param {Map<string, { user: string, suid: string|null, name: string|null }>} people by email
301
+ * @returns {Promise<Map<string, { profile: string, note?: string, operationId?: string }>>} by suid
302
+ */
303
+ async function ensureProfiles(users, checkpoint, people) {
304
+ /** @type {Map<string, { profile: string, note?: string, operationId?: string }>} */
305
+ const results = new Map()
306
+ const wanted = new Map([...people].filter(([, p]) => p.suid && (p.user === 'created' || p.user === 'linked')).map(([email, p]) => [p.suid, { email, name: p.name }]))
307
+ for (const entry of checkpoint.pending()) {
308
+ if (wanted.has(entry.suid)) results.set(entry.suid, await sendProfile(users, checkpoint, entry.suid, entry.key, /** @type {any} */ (entry.body)))
309
+ }
310
+ const unchecked = [...wanted.keys()].filter((suid) => !results.has(suid))
311
+ let present
312
+ try {
313
+ present = (await users.profiles(unchecked)).present
314
+ } catch (err) {
315
+ for (const suid of unchecked) results.set(suid, { profile: 'failed', note: `profile lookup ${err.message}` })
316
+ return results
317
+ }
318
+ for (const suid of unchecked) {
319
+ if (present.has(suid)) { results.set(suid, { profile: 'exists' }); continue }
320
+ const { email, name } = wanted.get(suid)
321
+ // The name is sent so imported profiles have one. Accepted race: a linked person who never signed in and finishes their
322
+ // first sign-in between the lookup and this create gets attributes={name} (the create replaces the attributes map).
323
+ const body = { data: { attributes: { email, suid, ...(name ? { name } : {}), delivery: 'none' } } }
324
+ const key = profileKey(suid)
325
+ checkpoint.markSent(suid, key, body)
326
+ results.set(suid, await sendProfile(users, checkpoint, suid, key, body))
327
+ }
328
+ return results
329
+ }
330
+
331
+ /**
332
+ * The dry run's profile check (with --iam): the preflight, then how many people would get a profile and how many have one.
333
+ * People the run would create have no suid yet, so they count as to create; linked people are looked up by suid. Writes nothing.
334
+ * @param {any} plan from planImport
335
+ * @param {{ userPoolId: string, region: string, profile?: string, iam?: string }} target
336
+ * @param {{ exec: Function, fetch: Function, authHeaders: () => Promise<Record<string, string>> }} deps
337
+ * @returns {Promise<string[]>} lines to print
338
+ */
339
+ async function checkProfiles(plan, target, { exec, fetch, authHeaders }) {
340
+ let usersApiBase
341
+ try {
342
+ usersApiBase = publishedUsersApi(exec, target, poolStack(exec, target))
343
+ } catch (err) {
344
+ return [`warning: ${err.message}; --apply would stop before writing`]
345
+ }
346
+ /** @type {Promise<Record<string, string>> | null} */
347
+ let headers = null
348
+ const userService = usersApi({ apiBase: usersApiBase, headers: () => (headers = headers || authHeaders()) }, { fetch })
349
+ const preflight = await preflightProfiles(userService, target)
350
+ if (!preflight.ok) return [`warning: ${preflight.message}; --apply would stop before writing`]
351
+ const people = new Map()
352
+ for (const a of plan.accounts) for (const u of a.users) if (u.action === 'create' || u.action === 'link') people.set(u.email, u.existing && u.existing.suid)
353
+ const suids = [...people.values()].filter(Boolean)
354
+ let exist
355
+ try {
356
+ exist = (await userService.profiles(suids)).present.size
357
+ } catch (err) {
358
+ return [`warning: profile lookup ${err.message}`]
359
+ }
360
+ return [`user-service permissions for profiles: ok (${usersApiBase})`, `profiles: ${people.size - exist} to create, ${exist} exist`]
361
+ }
362
+
177
363
  /** POST to the permissions API; returns { status, message }. */
178
364
  async function permissionsPost(fetch, target, headers, path, body) {
179
365
  const res = await fetch(`${target.apiBase.replace(/\/$/, '')}${path}`, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify(body) })
@@ -185,8 +371,9 @@ async function permissionsPost(fetch, target, headers, path, body) {
185
371
  * Apply a plan: import new users (one CSV job), give linked users a suid and default org when missing, then create each
186
372
  * account's org, add members and bootstrap the first Owner. Idempotent: a re-run skips what exists and retries failures.
187
373
  * @param {any} plan from planImport
188
- * @param {{ userPoolId: string, region: string, profile?: string, apiBase?: string, product?: string, logsRoleArn?: string }} target
189
- * logsRoleArn defaults to the role the pool's user-service stack publishes (publishedLogsRole)
374
+ * @param {{ userPoolId: string, region: string, profile?: string, apiBase?: string, product?: string, logsRoleArn?: string, iam?: string }} target
375
+ * iam = the IAM principal (named when the preflight fails); logsRoleArn defaults to the role the pool's user-service
376
+ * stack publishes (publishedLogsRole); the user-service API is that stack's ServiceEndpoint (publishedUsersApi)
190
377
  * @param {{ exec: Function, fetch: Function, mint: () => string, sleep: (ms: number) => Promise<void>, authHeaders: () => Promise<Record<string, string>>, now: () => Date }} deps
191
378
  */
192
379
  async function applyImport(plan, target, deps) {
@@ -195,13 +382,23 @@ async function applyImport(plan, target, deps) {
195
382
  for (const a of plan.accounts) for (const u of a.users) if (u.action === 'create') newUsers.set(u.email, u)
196
383
  if (!target.apiBase) throw new Error('users import: --api-base is required with --apply')
197
384
  if (!target.product) throw new Error('users import: --product is required with --apply (its catalog names the owner role)')
385
+ if (!target.checkpointFile) throw new Error('users import: a profiles checkpoint file is required with --apply (it resumes unfinished profile creates)')
386
+ const stack = poolStack(exec, target)
387
+ const usersApiBase = publishedUsersApi(exec, target, stack)
198
388
  if (newUsers.size && !target.logsRoleArn) {
199
- const published = publishedLogsRole(exec, target)
389
+ const published = publishedLogsRole(exec, target, stack)
200
390
  if (!published.arn) {
201
391
  throw new Error(`users import: no logs role for the import job: pass --logs-role-arn (the Cognito import job writes its log there)${published.parameter ? `; ${published.parameter} not found — deploy the user-service stack with UserImportLogsRole` : ''}`)
202
392
  }
203
393
  target = { ...target, logsRoleArn: published.arn }
204
394
  }
395
+ // One credential (the IAM principal's token) for both APIs, fetched once.
396
+ /** @type {Promise<Record<string, string>> | null} */
397
+ let headers = null
398
+ const authHeaders = () => (headers = headers || deps.authHeaders())
399
+ const userService = usersApi({ apiBase: usersApiBase, headers: authHeaders }, { fetch })
400
+ const preflight = await preflightProfiles(userService, target)
401
+ if (!preflight.ok) throw new Error(`${preflight.message}; nothing was written`)
205
402
  const startedAt = now().toISOString()
206
403
 
207
404
  // 1. new users through one import job
@@ -223,8 +420,9 @@ async function applyImport(plan, target, deps) {
223
420
  if (u.action !== 'create' && u.action !== 'link') continue
224
421
  const notes = []
225
422
  const found = findUser(exec, target, u.email)
226
- if (!found) { people.set(u.email, { user: 'failed', suid: null, notes: ['not in the pool after the import job — see the job\'s CloudWatch log'] }); continue }
227
- if (u.action === 'create') { people.set(u.email, { user: 'created', suid: found.suid, notes }); continue }
423
+ const name = displayName(u.source) === u.email ? null : displayName(u.source)
424
+ if (!found) { people.set(u.email, { user: 'failed', suid: null, name, notes: ['not in the pool after the import job — see the job\'s CloudWatch log'] }); continue }
425
+ if (u.action === 'create') { people.set(u.email, { user: 'created', suid: found.suid, name, notes }); continue }
228
426
  const updates = []
229
427
  let suid = found.suid
230
428
  if (!suid) { suid = mint(); updates.push({ Name: 'custom:suid', Value: suid }) }
@@ -233,20 +431,26 @@ async function applyImport(plan, target, deps) {
233
431
  if (updates.length) {
234
432
  exec('aws', ['cognito-idp', 'admin-update-user-attributes', ...poolArgs(target), '--username', found.username, '--user-attributes', JSON.stringify(updates)])
235
433
  }
236
- people.set(u.email, { user: 'linked', suid, notes })
434
+ people.set(u.email, { user: 'linked', suid, name, notes })
237
435
  }
238
436
  }
239
437
 
240
- // 3. orgs, members, first owner — through the permissions IAM principal
241
- const headers = await deps.authHeaders()
438
+ // 3. each person's user-service profile, before any org or membership (products read member names from it)
439
+ const checkpoint = openCheckpoint(target.checkpointFile, { userPoolId: target.userPoolId, usersApiBase }, { now })
440
+ const profiles = await ensureProfiles(userService, checkpoint, people)
441
+
442
+ // 4. orgs, members, first owner — through the permissions IAM principal
443
+ const permissionsHeaders = await authHeaders()
242
444
  const summary = { created: 0, linked: 0, failed: 0, skipped: 0, orgsCreated: 0, ownersGranted: 0 }
243
445
  for (const p of people.values()) summary[p.user === 'created' ? 'created' : p.user === 'linked' ? 'linked' : 'failed']++
446
+ const profileCount = (...states) => [...profiles.values()].filter((p) => states.includes(p.profile)).length
447
+ Object.assign(summary, { profilesCreated: profileCount('created'), profilesExisting: profileCount('exists'), profilesFailed: profileCount('failed', 'conflict', 'anomaly') })
244
448
  // Each person's permissions principal, created once before any membership (imported users haven't signed in yet, and
245
449
  // sign-in is what normally creates it); 409 = it already exists.
246
450
  const principals = new Map()
247
451
  const ensurePrincipal = async (email, suid) => {
248
452
  if (!principals.has(suid)) {
249
- const res = await permissionsPost(fetch, target, headers, '/users', { id: suid, email })
453
+ const res = await permissionsPost(fetch, target, permissionsHeaders, '/users', { id: suid, email })
250
454
  principals.set(suid, res.status === 201 || res.status === 409 ? null : `permissions user create failed (${res.status}): ${res.message}`)
251
455
  }
252
456
  return principals.get(suid)
@@ -257,23 +461,28 @@ async function applyImport(plan, target, deps) {
257
461
  const active = a.users.filter((u) => u.action !== 'skip' && people.get(u.email) && people.get(u.email).suid)
258
462
  let org = 'skipped'
259
463
  if (active.length) {
260
- const res = await permissionsPost(fetch, target, headers, '/orgs', { id: a.id, name: a.name })
464
+ const res = await permissionsPost(fetch, target, permissionsHeaders, '/orgs', { id: a.id, name: a.name })
261
465
  org = res.status === 201 ? 'created' : res.status === 409 ? 'exists' : 'failed'
262
466
  if (org === 'created') summary.orgsCreated++
263
467
  if (org === 'failed') users.push({ email: null, notes: [`org create failed (${res.status}): ${res.message}`] })
264
468
  }
265
469
  for (const u of a.users) {
266
- if (u.action === 'skip') { summary.skipped++; users.push({ email: u.email, user: 'skipped', owner: 'n/a', notes: [u.reason] }); continue }
470
+ if (u.action === 'skip') { summary.skipped++; users.push({ email: u.email, user: 'skipped', profile: 'skipped', owner: 'n/a', notes: [u.reason] }); continue }
267
471
  const person = people.get(u.email)
268
- const row = { email: u.email, user: u.action === 'member' ? 'linked' : person.user, suid: person.suid, member: false, owner: 'n/a', notes: [...person.notes] }
472
+ const profile = (person.suid && profiles.get(person.suid)) || { profile: 'skipped' }
473
+ const row = {
474
+ email: u.email, user: u.action === 'member' ? 'linked' : person.user, suid: person.suid, profile: profile.profile,
475
+ ...(profile.operationId && profile.profile !== 'created' ? { profileOperationId: profile.operationId } : {}),
476
+ member: false, owner: 'n/a', notes: [...person.notes, ...(profile.note ? [profile.note] : [])],
477
+ }
269
478
  const principalError = person.suid && org !== 'failed' && org !== 'skipped' ? await ensurePrincipal(u.email, person.suid) : null
270
479
  if (principalError) row.notes.push(principalError)
271
480
  if (person.suid && org !== 'failed' && org !== 'skipped' && !principalError) {
272
- const member = await permissionsPost(fetch, target, headers, `/orgs/${encodeURIComponent(a.id)}/members`, { type: 'user', id: person.suid })
481
+ const member = await permissionsPost(fetch, target, permissionsHeaders, `/orgs/${encodeURIComponent(a.id)}/members`, { type: 'user', id: person.suid })
273
482
  row.member = member.status === 201
274
483
  if (!row.member) row.notes.push(`member add failed (${member.status}): ${member.message}`)
275
484
  if (row.member && u.grant === 'owner') {
276
- const owner = await permissionsPost(fetch, target, headers, `/catalog/${encodeURIComponent(target.product)}/bootstrap-owner`, { orgId: a.id, userId: person.suid })
485
+ const owner = await permissionsPost(fetch, target, permissionsHeaders, `/catalog/${encodeURIComponent(target.product)}/bootstrap-owner`, { orgId: a.id, userId: person.suid })
277
486
  row.owner = owner.status === 201 ? 'granted' : owner.status === 409 ? 'exists' : 'failed'
278
487
  if (row.owner === 'granted') summary.ownersGranted++
279
488
  if (row.owner === 'exists') row.notes.push('the org already has an owner; grant more owners in the product')
@@ -289,4 +498,4 @@ async function applyImport(plan, target, deps) {
289
498
  return { startedAt, finishedAt: now().toISOString(), target: plan.target, job, accounts, summary }
290
499
  }
291
500
 
292
- module.exports = { planImport, applyImport, formatPlan, toCsv, parseCsv, csvRow }
501
+ module.exports = { planImport, applyImport, formatPlan, toCsv, parseCsv, csvRow, poolStack, publishedUsersApi, preflightProfiles, checkProfiles }
@@ -0,0 +1,80 @@
1
+ // The versions a deployment may move to (GET /api/versions) and the release a deploy or update names: --version,
2
+ // --channel or --commit-sha, one at most. A version or channel is checked against the control plane before it is sent.
3
+ 'use strict'
4
+ const { apiCall } = require('./api-client')
5
+
6
+ // MAJOR.MINOR.PATCH, no leading zeros, up to 6 digits each (the deployer's release-version format).
7
+ const SEMVER = /^(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})$/
8
+ const LIST_HINT = 'saaslayer versions lists them'
9
+
10
+ /**
11
+ * @typedef {{ version: string, compat: 'breaking'|'non-breaking', cutAt: string|null, notes: string|null, channels: string[] }} Version
12
+ * @typedef {{ version: string } | { channel: string } | { commitSha: string }} ReleaseChoice
13
+ */
14
+
15
+ /**
16
+ * The deployable versions, highest first. An older control plane without the route is named instead of a 404.
17
+ * @param {object} flags
18
+ * @returns {Promise<Version[]>}
19
+ */
20
+ async function fetchVersions(flags) {
21
+ try {
22
+ const doc = await apiCall('GET', '/api/versions', undefined, flags)
23
+ return ((doc && doc.data) || []).map((d) => d.attributes)
24
+ } catch (err) {
25
+ if (err.status === 404) throw new Error('this control plane is too old for versions (it has no GET /api/versions): use --commit-sha until it is upgraded')
26
+ throw err
27
+ }
28
+ }
29
+
30
+ /**
31
+ * The release named by --version, --channel or --commit-sha (camelCase commitSha too), or null when none is given.
32
+ * @param {Record<string, any>} flags
33
+ * @returns {ReleaseChoice|null}
34
+ */
35
+ function releaseChoice(flags) {
36
+ const commitSha = flags['commit-sha'] || flags.commitSha
37
+ const given = [flags.version !== undefined && 'version', flags.channel !== undefined && 'channel', commitSha && 'commitSha'].filter(Boolean)
38
+ if (given.length > 1) throw new Error('name the release with one of --version, --channel or --commit-sha')
39
+ if (flags.version !== undefined) {
40
+ if (typeof flags.version !== 'string' || !SEMVER.test(flags.version)) throw new Error(`--version must be MAJOR.MINOR.PATCH, e.g. 1.4.0 (${LIST_HINT})`)
41
+ return { version: flags.version }
42
+ }
43
+ if (flags.channel !== undefined) {
44
+ if (typeof flags.channel !== 'string' || !flags.channel) throw new Error(`--channel needs a channel name, e.g. stable (${LIST_HINT})`)
45
+ return { channel: flags.channel }
46
+ }
47
+ return commitSha ? { commitSha: String(commitSha) } : null
48
+ }
49
+
50
+ /**
51
+ * Check a version or channel against GET /api/versions before it is sent (a commit is checked by the control plane).
52
+ * @param {ReleaseChoice|null} choice
53
+ * @param {object} flags
54
+ * @returns {Promise<Version|null>} the version moved to, when the choice names one
55
+ */
56
+ async function checkReleaseChoice(choice, flags) {
57
+ if (!choice || 'commitSha' in choice) return null
58
+ const versions = await fetchVersions(flags)
59
+ if ('version' in choice) {
60
+ const found = versions.find((v) => v.version === choice.version)
61
+ if (!found) throw new Error(`no version ${choice.version} (${LIST_HINT})`)
62
+ return found
63
+ }
64
+ const found = versions.find((v) => (v.channels || []).includes(choice.channel))
65
+ if (!found) throw new Error(`channel ${choice.channel} points at no version (${LIST_HINT})`)
66
+ return found
67
+ }
68
+
69
+ /**
70
+ * The release a choice names, for messages.
71
+ * @param {ReleaseChoice} choice
72
+ * @param {Version|null} [resolved]
73
+ */
74
+ function describeChoice(choice, resolved = null) {
75
+ if ('version' in choice) return `version ${choice.version}`
76
+ if ('channel' in choice) return `channel ${choice.channel}${resolved ? ` (${resolved.version})` : ''}`
77
+ return choice.commitSha
78
+ }
79
+
80
+ module.exports = { SEMVER, fetchVersions, releaseChoice, checkReleaseChoice, describeChoice }