saaslayer 0.4.2 → 0.4.3

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 (49) hide show
  1. package/package.json +5 -6
  2. package/src/commands/operations.js +1 -1
  3. package/src/commands/users-management.js +2 -2
  4. package/src/users-import/ids.js +1 -1
  5. package/vendor/config/login-domain.js +213 -0
  6. package/vendor/discovery/index.d.mts +109 -0
  7. package/vendor/discovery/index.mjs +409 -0
  8. package/vendor/ids/index.d.ts +21 -0
  9. package/vendor/ids/index.js +237 -0
  10. package/vendor/migrations/backups.js +118 -0
  11. package/vendor/migrations/child.js +78 -0
  12. package/vendor/migrations/credentials.js +103 -0
  13. package/vendor/migrations/errors.js +30 -0
  14. package/vendor/migrations/exec-child.js +78 -0
  15. package/vendor/migrations/gate.js +51 -0
  16. package/vendor/migrations/index.js +30 -0
  17. package/vendor/migrations/inventory.js +92 -0
  18. package/vendor/migrations/log.js +14 -0
  19. package/vendor/migrations/release.js +45 -0
  20. package/vendor/migrations/report.js +129 -0
  21. package/vendor/migrations/rules.js +104 -0
  22. package/vendor/migrations/run.js +311 -0
  23. package/vendor/migrations/session-policy.js +37 -0
  24. package/vendor/migrations/step-guard.js +82 -0
  25. package/vendor/operations/activity.d.ts +21 -0
  26. package/vendor/operations/activity.js +126 -0
  27. package/vendor/operations/index.d.ts +60 -0
  28. package/vendor/operations/index.js +471 -0
  29. package/vendor/permissions-engine-core/account-status.js +270 -0
  30. package/vendor/permissions-engine-core/delegation.js +174 -0
  31. package/vendor/permissions-engine-core/direct-mode-contract.js +237 -0
  32. package/vendor/permissions-engine-core/sso-claims.js +206 -0
  33. package/vendor/user-management/cognito/emails/token-registry.js +48 -0
  34. package/vendor/user-management/email/validate.js +207 -0
  35. package/vendor/user-management/extensibility/hook-contract.js +720 -0
  36. package/vendor/user-management/extensibility/safe-webhook.js +85 -0
  37. package/vendor/user-management/identity/admission.js +215 -0
  38. package/vendor/user-management/identity/attr.js +27 -0
  39. package/vendor/user-management/identity/attribute-registry.js +115 -0
  40. package/vendor/user-management/identity/email.js +25 -0
  41. package/vendor/user-management/identity/ensure-suid.js +74 -0
  42. package/vendor/user-management/identity/pointers.js +192 -0
  43. package/vendor/user-management/identity/stitch-provider.js +275 -0
  44. package/vendor/user-management/management/apply-request.js +227 -0
  45. package/vendor/user-management/management/core-profile.js +110 -0
  46. package/vendor/user-management/management/index.js +23 -0
  47. package/vendor/user-management/management/purposes.js +94 -0
  48. package/vendor/user-management/management/registry.js +569 -0
  49. package/vendor/user-management/store/table.js +332 -0
@@ -0,0 +1,118 @@
1
+ // Backup check run before a destructive migration: verifies PITR and records the restore point, and for
2
+ // backup: 'on-demand' also takes a CreateBackup snapshot. Blocks only on protected envs.
3
+ const {
4
+ CreateBackupCommand,
5
+ DescribeBackupCommand,
6
+ DescribeContinuousBackupsCommand,
7
+ } = require('@aws-sdk/client-dynamodb')
8
+ const { debugBackups } = require('./log')
9
+
10
+ const DEFAULT_MAX_WAIT_SECONDS = 600
11
+ const POLL_INTERVAL_MS = 5000
12
+
13
+ /**
14
+ * @typedef {{ send: (command: any) => Promise<any> }} DynamoSender
15
+ * @typedef {{ status: 'ok'|'BLOCKED_NO_BACKUP', restorePoints: Record<string, string>, backupArns: string[], blockedTables?: string[], error?: { code: string, message: string } }} BackupCheckResult
16
+ */
17
+
18
+ /** @param {unknown} err */
19
+ function errorInfo(err) {
20
+ const e = /** @type {{ name?: string, code?: string, message?: string }} */ (err || {})
21
+ return { code: e.code || e.name || 'BACKUP_CHECK_FAILED', message: e.message || String(err) }
22
+ }
23
+
24
+ /**
25
+ * @param {string} label
26
+ * @param {string} table
27
+ * @param {number} nowMs
28
+ */
29
+ function backupName(label, table, nowMs) {
30
+ const stamp = new Date(nowMs).toISOString().replace(/[^0-9]/g, '').slice(0, 14)
31
+ return `${label}-${table}-${stamp}`.replace(/[^A-Za-z0-9_.-]/g, '-').slice(-255)
32
+ }
33
+
34
+ /**
35
+ * @param {DynamoSender} dynamo
36
+ * @param {string} table
37
+ * @returns {Promise<string|undefined>} ISO restore point when PITR is ENABLED
38
+ */
39
+ async function pitrRestorePoint(dynamo, table) {
40
+ const out = await dynamo.send(new DescribeContinuousBackupsCommand({ TableName: table }))
41
+ const pitr = out && out.ContinuousBackupsDescription && out.ContinuousBackupsDescription.PointInTimeRecoveryDescription
42
+ if (!pitr || pitr.PointInTimeRecoveryStatus !== 'ENABLED' || !pitr.LatestRestorableDateTime) return undefined
43
+ return new Date(pitr.LatestRestorableDateTime).toISOString()
44
+ }
45
+
46
+ /**
47
+ * @param {{ dynamo: DynamoSender, table: string, name: string, maxWaitSeconds: number, now: () => number, sleep: (ms: number) => Promise<void> }} p
48
+ * @returns {Promise<string>} BackupArn once AVAILABLE
49
+ */
50
+ async function createBackupAndWait({ dynamo, table, name, maxWaitSeconds, now, sleep }) {
51
+ const created = await dynamo.send(new CreateBackupCommand({ TableName: table, BackupName: name }))
52
+ const arn = created.BackupDetails.BackupArn
53
+ const deadline = now() + maxWaitSeconds * 1000
54
+ for (;;) {
55
+ const out = await dynamo.send(new DescribeBackupCommand({ BackupArn: arn }))
56
+ const status = out.BackupDescription.BackupDetails.BackupStatus
57
+ if (status === 'AVAILABLE') return arn
58
+ if (status === 'DELETED') throw Object.assign(new Error(`backup ${arn} was deleted before it became AVAILABLE`), { code: 'BACKUP_DELETED' })
59
+ if (now() >= deadline) {
60
+ throw Object.assign(new Error(`backup ${arn} not AVAILABLE after ${maxWaitSeconds}s`), { code: 'BACKUP_TIMEOUT' })
61
+ }
62
+ await sleep(POLL_INTERVAL_MS)
63
+ }
64
+ }
65
+
66
+ /**
67
+ * Protected envs fail closed (PITR off, a denied describe, or a backup that never becomes AVAILABLE →
68
+ * BLOCKED_NO_BACKUP). Non-protected envs only record a restore point when PITR happens to be on.
69
+ * @param {{ dynamo: DynamoSender, tables: string[], mode?: 'pitr'|'on-demand', protected: boolean, label: string, maxWaitSeconds?: number, now?: () => number, sleep?: (ms: number) => Promise<void> }} p
70
+ * @returns {Promise<BackupCheckResult>}
71
+ */
72
+ async function checkBackups({ dynamo, tables, mode = 'pitr', protected: isProtected, label, maxWaitSeconds = DEFAULT_MAX_WAIT_SECONDS, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
73
+ /** @type {Record<string, string>} */
74
+ const restorePoints = {}
75
+ /** @type {string[]} */
76
+ const backupArns = []
77
+
78
+ if (!isProtected) {
79
+ for (const table of tables) {
80
+ try {
81
+ const point = await pitrRestorePoint(dynamo, table)
82
+ if (point) restorePoints[table] = point
83
+ } catch (err) {
84
+ debugBackups('restore point skipped reason=%s table=%s', errorInfo(err).code, table)
85
+ }
86
+ }
87
+ return { status: 'ok', restorePoints, backupArns }
88
+ }
89
+
90
+ const blockedTables = []
91
+ try {
92
+ for (const table of tables) {
93
+ const point = await pitrRestorePoint(dynamo, table)
94
+ if (point) restorePoints[table] = point
95
+ else blockedTables.push(table)
96
+ }
97
+ } catch (err) {
98
+ debugBackups('blocked reason=%s', errorInfo(err).code)
99
+ return { status: 'BLOCKED_NO_BACKUP', restorePoints, backupArns, error: errorInfo(err) }
100
+ }
101
+ if (blockedTables.length > 0) {
102
+ debugBackups('blocked reason=PITR_DISABLED tables=%o', blockedTables)
103
+ return { status: 'BLOCKED_NO_BACKUP', restorePoints, backupArns, blockedTables }
104
+ }
105
+ if (mode !== 'on-demand') return { status: 'ok', restorePoints, backupArns }
106
+
107
+ try {
108
+ for (const table of tables) {
109
+ backupArns.push(await createBackupAndWait({ dynamo, table, name: backupName(label, table, now()), maxWaitSeconds, now, sleep }))
110
+ }
111
+ } catch (err) {
112
+ debugBackups('blocked reason=%s', errorInfo(err).code)
113
+ return { status: 'BLOCKED_NO_BACKUP', restorePoints, backupArns, error: errorInfo(err) }
114
+ }
115
+ return { status: 'ok', restorePoints, backupArns }
116
+ }
117
+
118
+ module.exports = { checkBackups }
@@ -0,0 +1,78 @@
1
+ // Parent side of a migration step child: forks exec-child.js with a credential-only env, serves refreshed
2
+ // credentials for that one session over IPC, relays events, and returns the library's `up` result.
3
+ const path = require('path')
4
+ const { fork } = require('child_process')
5
+ const { buildChildEnv } = require('./credentials')
6
+ const { MigrationError } = require('./errors')
7
+ const { debugChild } = require('./log')
8
+
9
+ const EXEC_CHILD = path.join(__dirname, 'exec-child.js')
10
+
11
+ /**
12
+ * @param {{
13
+ * credentials: import('./credentials').CredentialProvider,
14
+ * region: string,
15
+ * request: Record<string, unknown>,
16
+ * cwd: string,
17
+ * parentEnv?: NodeJS.ProcessEnv,
18
+ * onEvent?: (event: any) => void,
19
+ * onOutput?: (chunk: string) => void,
20
+ * signal?: AbortSignal,
21
+ * }} p
22
+ * @returns {Promise<any>} the library UpResult
23
+ */
24
+ async function runStepChild({ credentials, region, request, cwd, parentEnv = process.env, onEvent, onOutput, signal }) {
25
+ const first = await credentials()
26
+ const env = buildChildEnv({ credentials: first, region, parentEnv })
27
+ const child = fork(EXEC_CHILD, [], { cwd, env, stdio: onOutput ? ['ignore', 'pipe', 'pipe', 'ipc'] : ['ignore', 'inherit', 'inherit', 'ipc'] })
28
+ if (onOutput) {
29
+ child.stdout.setEncoding('utf8').on('data', onOutput)
30
+ child.stderr.setEncoding('utf8').on('data', onOutput)
31
+ }
32
+ const stop = () => child.kill('SIGTERM')
33
+ if (signal) {
34
+ if (signal.aborted) stop()
35
+ else signal.addEventListener('abort', stop, { once: true })
36
+ }
37
+
38
+ try {
39
+ return await new Promise((resolve, reject) => {
40
+ let settled = false
41
+ child.on('message', (message) => {
42
+ if (!message || typeof message !== 'object') return
43
+ if (message.type === 'credentials-request') {
44
+ credentials().then(
45
+ (c) => child.connected && child.send({ type: 'credentials', id: message.id, credentials: { ...c, expiration: c.expiration && c.expiration.toISOString() } }),
46
+ (err) => { debugChild('credential refresh failed reason=%s', err && err.name); stop() },
47
+ )
48
+ return
49
+ }
50
+ if (message.type === 'event') {
51
+ if (onEvent) onEvent(message.event)
52
+ return
53
+ }
54
+ if (message.type === 'result') {
55
+ settled = true
56
+ resolve(message.result)
57
+ return
58
+ }
59
+ if (message.type === 'error') {
60
+ settled = true
61
+ reject(new MigrationError(message.error.code, message.error.message.replace(/^[A-Z][A-Z0-9_]+: /, '')))
62
+ }
63
+ })
64
+ child.on('error', (err) => { if (!settled) { settled = true; reject(err) } })
65
+ child.on('exit', (code, sig) => {
66
+ if (!settled) {
67
+ settled = true
68
+ reject(new MigrationError('MIGRATE_CHILD_EXITED', `migrate step child exited (code=${code}, signal=${sig}) without a result`))
69
+ }
70
+ })
71
+ child.send({ type: 'run', request })
72
+ })
73
+ } finally {
74
+ if (signal) signal.removeEventListener('abort', stop)
75
+ }
76
+ }
77
+
78
+ module.exports = { runStepChild }
@@ -0,0 +1,103 @@
1
+ // Migrate-role credentials: a refreshing AssumeRole provider (read-only session policy for dry-runs)
2
+ // and the child-process env that carries only one step's credentials and no ambient AWS identity.
3
+ const os = require('os')
4
+ const { AssumeRoleCommand, STSClient } = require('@aws-sdk/client-sts')
5
+ const { readOnlySessionPolicy } = require('./session-policy')
6
+ const { MigrationError } = require('./errors')
7
+ const { debugCredentials } = require('./log')
8
+
9
+ const SESSION_PREFIX = 'saaslayer-migrate'
10
+ // Role chaining caps every hop at 1 hour, whatever the role's MaxSessionDuration.
11
+ const SESSION_SECONDS = 3600
12
+ const REFRESH_BEFORE_MS = 5 * 60 * 1000
13
+ const MAX_SESSION_NAME = 64
14
+ // Non-credential variables a child may inherit. Everything else is dropped, so no ambient identity
15
+ // (AWS_PROFILE, container/web-identity credentials, the deploy-role session) can reach migration code.
16
+ const INHERITED_ENV = ['PATH', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL', 'TZ', 'DEBUG']
17
+
18
+ /**
19
+ * @typedef {{ accessKeyId: string, secretAccessKey: string, sessionToken?: string, expiration?: Date }} Credentials
20
+ * @typedef {() => Promise<Credentials>} CredentialProvider
21
+ */
22
+
23
+ /** @param {string} name */
24
+ function assertSessionName(name) {
25
+ if (typeof name !== 'string' || !name.startsWith(`${SESSION_PREFIX}-`) || name.length > MAX_SESSION_NAME || !/^[\w+=,.@-]+$/.test(name)) {
26
+ throw new MigrationError('MIGRATE_SESSION_NAME_INVALID', `session name must match ${SESSION_PREFIX}-* (≤${MAX_SESSION_NAME} chars, [\\w+=,.@-]); got ${String(name)}`)
27
+ }
28
+ }
29
+
30
+ /**
31
+ * The migrate role's trust requires a saaslayer-migrate-* session name (CloudTrail attribution).
32
+ * @param {{ prefix?: string, kind: string, runId: string }} p
33
+ * @returns {string}
34
+ */
35
+ function migrateSessionName({ prefix = SESSION_PREFIX, kind, runId }) {
36
+ const head = `${prefix}-${kind}-`
37
+ const safeRun = String(runId).replace(/[^\w+=,.@-]/g, '-')
38
+ const name = `${head}${safeRun}`.slice(0, MAX_SESSION_NAME)
39
+ assertSessionName(name)
40
+ return name
41
+ }
42
+
43
+ /**
44
+ * Returns a credential provider that assumes the migrate role and re-assumes 5 minutes before the
45
+ * session expires, so a migration can outlive one chained session.
46
+ * @param {{ roleArn: string, sourceCredentials?: CredentialProvider|Credentials, readOnly: boolean, sessionName: string, region?: string, sts?: { send: (c: any) => Promise<any> }, now?: () => number }} p
47
+ * @returns {CredentialProvider}
48
+ */
49
+ function assumeMigrateRole({ roleArn, sourceCredentials, readOnly, sessionName, region, sts, now = Date.now }) {
50
+ assertSessionName(sessionName)
51
+ const client = sts || new STSClient({ region, credentials: sourceCredentials })
52
+ /** @type {Credentials|undefined} */
53
+ let current
54
+ /** @type {Promise<Credentials>|undefined} */
55
+ let inflight
56
+
57
+ async function assume() {
58
+ const out = await client.send(new AssumeRoleCommand({
59
+ RoleArn: roleArn,
60
+ RoleSessionName: sessionName,
61
+ DurationSeconds: SESSION_SECONDS,
62
+ ...(readOnly ? { Policy: JSON.stringify(readOnlySessionPolicy) } : {}),
63
+ }))
64
+ const c = out.Credentials
65
+ debugCredentials('assumed session=%s readOnly=%s', sessionName, readOnly)
66
+ return { accessKeyId: c.AccessKeyId, secretAccessKey: c.SecretAccessKey, sessionToken: c.SessionToken, expiration: new Date(c.Expiration) }
67
+ }
68
+
69
+ return async function migrateRoleCredentials() {
70
+ const fresh = current && current.expiration && current.expiration.getTime() - now() > REFRESH_BEFORE_MS
71
+ if (fresh) return /** @type {Credentials} */ (current)
72
+ if (!inflight) {
73
+ inflight = assume().then((c) => { current = c; return c }).finally(() => { inflight = undefined })
74
+ }
75
+ return inflight
76
+ }
77
+ }
78
+
79
+ /**
80
+ * @param {{ credentials: Credentials, region: string, parentEnv?: NodeJS.ProcessEnv }} p
81
+ * @returns {Record<string, string>}
82
+ */
83
+ function buildChildEnv({ credentials, region, parentEnv = process.env }) {
84
+ /** @type {Record<string, string>} */
85
+ const env = {}
86
+ for (const key of INHERITED_ENV) {
87
+ if (typeof parentEnv[key] === 'string') env[key] = /** @type {string} */ (parentEnv[key])
88
+ }
89
+ env.AWS_REGION = region
90
+ env.AWS_DEFAULT_REGION = region
91
+ env.AWS_ACCESS_KEY_ID = credentials.accessKeyId
92
+ env.AWS_SECRET_ACCESS_KEY = credentials.secretAccessKey
93
+ if (credentials.sessionToken) env.AWS_SESSION_TOKEN = credentials.sessionToken
94
+ if (credentials.expiration) env.AWS_CREDENTIAL_EXPIRATION = credentials.expiration.toISOString()
95
+ // With env credentials present the default chain never reaches these, but if they were missing it
96
+ // must find nothing rather than a shared profile or instance metadata.
97
+ env.AWS_SHARED_CREDENTIALS_FILE = os.devNull
98
+ env.AWS_CONFIG_FILE = os.devNull
99
+ env.AWS_EC2_METADATA_DISABLED = 'true'
100
+ return env
101
+ }
102
+
103
+ module.exports = { assumeMigrateRole, buildChildEnv, migrateSessionName, SESSION_PREFIX }
@@ -0,0 +1,30 @@
1
+ // Typed migration-pipeline error with a stable `code` (MIGRATION_LOCKED, UNDECLARED_TABLE, ...) that the
2
+ // runner copies into reports and the deployer maps onto its failure taxonomy.
3
+
4
+ class MigrationError extends Error {
5
+ /**
6
+ * @param {string} code
7
+ * @param {string} message
8
+ * @param {Record<string, unknown>} [details]
9
+ */
10
+ constructor(code, message, details) {
11
+ super(`${code}: ${message}`)
12
+ this.name = 'MigrationError'
13
+ this.code = code
14
+ if (details) this.details = details
15
+ }
16
+ }
17
+
18
+ /**
19
+ * @param {unknown} err
20
+ * @returns {{ code: string, message: string }}
21
+ */
22
+ function toErrorInfo(err) {
23
+ const e = /** @type {{ code?: unknown, message?: unknown }} */ (err || {})
24
+ return {
25
+ code: typeof e.code === 'string' ? e.code : 'MIGRATION_FAILED',
26
+ message: typeof e.message === 'string' ? e.message : String(err),
27
+ }
28
+ }
29
+
30
+ module.exports = { MigrationError, toErrorInfo }
@@ -0,0 +1,78 @@
1
+ // Child-process entry for one migration step (dry-run or apply): one library `up` call using only the
2
+ // credentials the parent gave this step (env, refreshed over IPC). Never sees the deploy-role session.
3
+ const { DynamoDBClient } = require('@aws-sdk/client-dynamodb')
4
+ const { guardAppClient } = require('./step-guard')
5
+ const { MigrationError } = require('./errors')
6
+
7
+ /** @type {Map<number, (creds: any) => void>} */
8
+ const pendingCredentials = new Map()
9
+ let nextRequest = 0
10
+
11
+ /** Asks the parent for the step's current (refreshed) credentials. */
12
+ function credentialsFromParent() {
13
+ return new Promise((resolve) => {
14
+ const id = ++nextRequest
15
+ pendingCredentials.set(id, resolve)
16
+ process.send({ type: 'credentials-request', id })
17
+ }).then((c) => ({ ...c, expiration: c.expiration ? new Date(c.expiration) : undefined }))
18
+ }
19
+
20
+ /** @param {unknown} err */
21
+ function serializeError(err) {
22
+ const e = /** @type {{ code?: string, name?: string, message?: string }} */ (err || {})
23
+ return { code: e.code || e.name || 'MIGRATION_FAILED', name: e.name, message: e.message || String(err) }
24
+ }
25
+
26
+ /**
27
+ * @param {{ stage: string, config: any, cwd: string, dryRun: boolean, only: string[], appliedBy: string, params: Record<string, unknown>, lockOwner: string, tablesById: Record<string, string[]>, faultInjection?: { failAfterCheckpoints: number } }} request
28
+ */
29
+ async function runStep(request) {
30
+ const { up } = await import('ddb-migration-tools')
31
+ const stage = request.config.stages[request.stage]
32
+ const clientConfig = { region: stage.region, endpoint: stage.endpoint, credentials: credentialsFromParent }
33
+ const appRaw = new DynamoDBClient(clientConfig)
34
+ const ledgerRaw = new DynamoDBClient(clientConfig)
35
+ const guard = guardAppClient(appRaw, { dryRun: request.dryRun, tablesFor: (id) => request.tablesById[id] || [] })
36
+ const abort = new AbortController()
37
+ process.once('SIGTERM', () => abort.abort(new Error('SIGTERM: migrate step stopped by the runner')))
38
+ const failAfter = request.faultInjection ? request.faultInjection.failAfterCheckpoints : 0
39
+ let checkpoints = 0
40
+
41
+ const result = await up({
42
+ stage: request.stage,
43
+ config: request.config,
44
+ cwd: request.cwd,
45
+ dryRun: request.dryRun,
46
+ only: request.only,
47
+ appliedBy: request.appliedBy,
48
+ params: request.params,
49
+ lock: { owner: request.lockOwner, held: true },
50
+ clients: { app: { raw: appRaw }, ledger: { raw: ledgerRaw } },
51
+ signal: abort.signal,
52
+ onEvent: (event) => {
53
+ if (event.type === 'start') guard.setActiveMigration(event.id)
54
+ if (event.type === 'complete' || event.type === 'fail' || event.type === 'interrupt') guard.setActiveMigration(undefined)
55
+ process.send({ type: 'event', event })
56
+ // Thrown from the library's after-checkpoint hook: the checkpoint is already written, so ctx.checkpoint
57
+ // rejects in the migration and the library marks the row failed with that checkpoint kept.
58
+ if (failAfter && event.type === 'checkpoint' && ++checkpoints === failAfter) {
59
+ throw new MigrationError('MIGRATION_FAULT_INJECTED', `fault injection: failing after checkpoint ${checkpoints} (migrationFaultInjection)`)
60
+ }
61
+ },
62
+ })
63
+ return result
64
+ }
65
+
66
+ process.on('message', (message) => {
67
+ if (message && message.type === 'credentials') {
68
+ const resolve = pendingCredentials.get(message.id)
69
+ pendingCredentials.delete(message.id)
70
+ if (resolve) resolve(message.credentials)
71
+ return
72
+ }
73
+ if (message && message.type === 'run') {
74
+ runStep(message.request)
75
+ .then((result) => ({ type: 'result', result }), (err) => ({ type: 'error', error: serializeError(err) }))
76
+ .then((reply) => process.send(reply, () => process.exit(0)))
77
+ }
78
+ })
@@ -0,0 +1,51 @@
1
+ // Approval gate for a deployment's migrationApproval policy (auto | destructive | all): decides per
2
+ // migration whether it applies now or waits, and keeps id order by holding everything after a wait.
3
+ const { MigrationError } = require('./errors')
4
+
5
+ const POLICIES = ['auto', 'destructive', 'all']
6
+
7
+ /**
8
+ * @typedef {'auto'|'destructive'|'all'} ApprovalPolicy
9
+ * @typedef {{ serviceRef: string, id: string, checksum: string }} ApprovalItem
10
+ * @typedef {{ runId: string, approver: string, reason: string, items: ApprovalItem[] }} Approval
11
+ * @typedef {{ id: string, checksum: string, meta: { destructive?: boolean } }} GatedMigration
12
+ */
13
+
14
+ /**
15
+ * @param {{ serviceRef: string, migration: GatedMigration, approval?: Approval|null }} p
16
+ * @returns {boolean}
17
+ */
18
+ function isApproved({ serviceRef, migration, approval }) {
19
+ if (!approval || !Array.isArray(approval.items)) return false
20
+ return approval.items.some((item) => item.serviceRef === serviceRef &&
21
+ item.id === migration.id &&
22
+ item.checksum === migration.checksum)
23
+ }
24
+
25
+ /**
26
+ * Backups on protected envs are a separate check (checkBackups); this only decides apply vs wait.
27
+ * @param {{ policy: ApprovalPolicy, protected: boolean, serviceRef: string, migration: GatedMigration, approval?: Approval|null }} p
28
+ * @returns {'apply'|'awaiting-approval'}
29
+ */
30
+ function evaluateGate({ policy, serviceRef, migration, approval }) {
31
+ if (!POLICIES.includes(policy)) {
32
+ throw new MigrationError('INVALID_APPROVAL_POLICY', `migrationApproval must be one of ${POLICIES.join(', ')}; got ${String(policy)}`)
33
+ }
34
+ if (policy === 'auto') return 'apply'
35
+ const needsApproval = policy === 'all' || !!migration.meta.destructive
36
+ if (!needsApproval) return 'apply'
37
+ return isApproved({ serviceRef, migration, approval }) ? 'apply' : 'awaiting-approval'
38
+ }
39
+
40
+ /**
41
+ * @template {GatedMigration} M
42
+ * @param {{ policy: ApprovalPolicy, protected: boolean, serviceRef: string, migrations: M[], approval?: Approval|null }} p
43
+ * @returns {{ apply: M[], waiting: M[] }}
44
+ */
45
+ function splitByGate({ migrations, ...gate }) {
46
+ const firstWait = migrations.findIndex((migration) => evaluateGate({ ...gate, migration }) === 'awaiting-approval')
47
+ if (firstWait === -1) return { apply: migrations.slice(), waiting: [] }
48
+ return { apply: migrations.slice(0, firstWait), waiting: migrations.slice(firstWait) }
49
+ }
50
+
51
+ module.exports = { evaluateGate, splitByGate, APPROVAL_POLICIES: POLICIES }
@@ -0,0 +1,30 @@
1
+ // Public entry for @saaslayer/migrations: the per-service migration runner and its building blocks
2
+ // (session policy, gate, backup check, phase rules, credentials, report builder).
3
+ const { readOnlySessionPolicy } = require('./session-policy')
4
+ const { evaluateGate, splitByGate } = require('./gate')
5
+ const { MigrationError } = require('./errors')
6
+ const { checkBackups } = require('./backups')
7
+ const { validateMigration, selectPhase, loadMigrations } = require('./rules')
8
+ const { assumeMigrateRole, buildChildEnv, migrateSessionName } = require('./credentials')
9
+ const { buildReport } = require('./report')
10
+ const { runServiceMigrations } = require('./run')
11
+ const { readLedgerReport } = require('./inventory')
12
+ const { readReleaseMigrations } = require('./release')
13
+
14
+ module.exports = {
15
+ runServiceMigrations,
16
+ readLedgerReport,
17
+ readReleaseMigrations,
18
+ buildReport,
19
+ assumeMigrateRole,
20
+ buildChildEnv,
21
+ migrateSessionName,
22
+ readOnlySessionPolicy,
23
+ evaluateGate,
24
+ splitByGate,
25
+ checkBackups,
26
+ validateMigration,
27
+ selectPhase,
28
+ loadMigrations,
29
+ MigrationError,
30
+ }
@@ -0,0 +1,92 @@
1
+ // readLedgerReport: re-projects one service's ledger into the §2.17.6 report plus its completed set, with a
2
+ // read-only migrate-role session (no lease, no writes). Used to re-send a lost report-up (`saaslayer migrate report`).
3
+ const { DynamoDBClient } = require('@aws-sdk/client-dynamodb')
4
+ const { assumeMigrateRole, migrateSessionName, SESSION_PREFIX } = require('./credentials')
5
+ const { loadMigrations, selectPhase } = require('./rules')
6
+ const { buildReport } = require('./report')
7
+ const { libraryConfig, assertLedgerExists, errorOf } = require('./run')
8
+ const { debugInventory } = require('./log')
9
+
10
+ /**
11
+ * @typedef {{ id: string, checksum: string|null, completedAt: string|null }} AppliedMigration
12
+ */
13
+
14
+ /**
15
+ * @param {{
16
+ * service: { ref: string, dir: string, migrationsDir: string, tables: Record<string, string> },
17
+ * ledger: { tableName: string, scope: string, stage: string },
18
+ * role: { roleArn?: string, sourceCredentials?: any, sessionPrefix?: string },
19
+ * region: string, accountId?: string, endpoint?: string,
20
+ * run: { runId: string, source: 'deployer'|'self', commitSha?: string },
21
+ * params?: Record<string, unknown>,
22
+ * phase?: 'pre'|'post'|'all',
23
+ * }} opts phase (default 'all') selects which pending migrations the report lists
24
+ * @param {{ assumeMigrateRole?: typeof assumeMigrateRole, now?: () => number }} [deps]
25
+ * @returns {Promise<object & { appliedMigrations: AppliedMigration[] }>} the report (mode plan) + appliedMigrations
26
+ */
27
+ async function readLedgerReport(opts, deps = {}) {
28
+ const assume = deps.assumeMigrateRole || assumeMigrateRole
29
+ const now = deps.now || Date.now
30
+ const startedAt = new Date(now()).toISOString()
31
+ const { service, ledger, run } = opts
32
+ const phase = opts.phase || 'all'
33
+ /** @type {{ id: string, checksum: string, meta: any }[]} */
34
+ let pending = []
35
+ /** @type {Record<string, { status: string, appliedAt?: string }>} */
36
+ let ledgerRows = {}
37
+ /** @type {AppliedMigration[]} */
38
+ let appliedMigrations = []
39
+ /** @type {{ code: string, message: string }|null} */
40
+ let error = null
41
+
42
+ if (!ledger || !ledger.tableName) {
43
+ error = { code: 'MIGRATION_LEDGER_MISSING', message: 'no MigrationsLedgerTableName output for this service' }
44
+ } else if (!opts.role || !opts.role.roleArn) {
45
+ error = { code: 'MIGRATE_ROLE_MISSING', message: 'no MigrateRoleArn output for this service (no trusted principal?)' }
46
+ } else {
47
+ try {
48
+ const readOnly = assume({
49
+ roleArn: opts.role.roleArn,
50
+ sourceCredentials: opts.role.sourceCredentials,
51
+ readOnly: true,
52
+ region: opts.region,
53
+ sessionName: migrateSessionName({ prefix: opts.role.sessionPrefix || SESSION_PREFIX, kind: 'report', runId: run.runId }),
54
+ })
55
+ const ledgerRaw = new DynamoDBClient({ region: opts.region, credentials: readOnly, ...(opts.endpoint ? { endpoint: opts.endpoint } : {}) })
56
+ await assertLedgerExists({ ledgerRaw, tableName: ledger.tableName })
57
+ const config = libraryConfig(opts)
58
+ const clients = { ledger: { raw: ledgerRaw } }
59
+ const loaded = await loadMigrations({ config, stage: ledger.stage, clients, tables: service.tables })
60
+ pending = selectPhase(loaded.pending, phase)
61
+ const lib = await import('ddb-migration-tools')
62
+ const statuses = await lib.status({ config, stage: ledger.stage, clients })
63
+ const pendingIds = new Set(pending.map((m) => m.id))
64
+ ledgerRows = Object.fromEntries(statuses.filter((s) => pendingIds.has(s.id) && s.status !== 'pending').map((s) => [s.id, { status: s.status, appliedAt: s.appliedAt || undefined }]))
65
+ appliedMigrations = statuses.filter((s) => s.status === 'completed').map((s) => ({ id: s.id, checksum: null, completedAt: s.appliedAt || null }))
66
+ } catch (err) {
67
+ error = errorOf(err)
68
+ debugInventory('ledger read stopped service=%s reason=%s', service.ref, error.code)
69
+ }
70
+ }
71
+
72
+ const report = buildReport({
73
+ serviceRef: service.ref,
74
+ deploymentId: opts.params && typeof opts.params.deploymentId === 'string' ? opts.params.deploymentId : null,
75
+ commitSha: run.commitSha,
76
+ source: run.source,
77
+ runId: run.runId,
78
+ phase,
79
+ mode: 'plan',
80
+ startedAt,
81
+ finishedAt: new Date(now()).toISOString(),
82
+ ledger: ledger || { tableName: '', scope: service.ref, stage: '' },
83
+ lock: null,
84
+ migrations: pending,
85
+ ledgerRows,
86
+ error,
87
+ })
88
+ debugInventory('report service=%s status=%s applied=%d', service.ref, report.status, appliedMigrations.length)
89
+ return { ...report, appliedMigrations }
90
+ }
91
+
92
+ module.exports = { readLedgerReport }
@@ -0,0 +1,14 @@
1
+ // Debug namespaces for @saaslayer/migrations (enable with DEBUG=migrations:*). Messages carry reason
2
+ // codes and ids only, never item data or credentials.
3
+ const debugLib = require('@davidwells/smart-log/debug')
4
+
5
+ const debugMigrations = debugLib('migrations')
6
+
7
+ module.exports = {
8
+ debugRun: debugMigrations.extend('run'),
9
+ debugBackups: debugMigrations.extend('backups'),
10
+ debugCredentials: debugMigrations.extend('credentials'),
11
+ debugChild: debugMigrations.extend('child'),
12
+ debugTestkit: debugMigrations.extend('testkit'),
13
+ debugInventory: debugMigrations.extend('inventory'),
14
+ }
@@ -0,0 +1,45 @@
1
+ // readReleaseMigrations: the migrations a checkout ships and each one's declared phase, with no ledger and no AWS.
2
+ // Lists entries with the library's rule (a directory's index.* or a flat code file) and reads only the phase export.
3
+ const fs = require('fs')
4
+ const path = require('path')
5
+ const { pathToFileURL } = require('url')
6
+ const { MigrationError } = require('./errors')
7
+ const { PHASES } = require('./rules')
8
+
9
+ const CODE_EXT = /\.(ts|mts|mjs|js|cjs)$/
10
+ const ENTRYPOINTS = ['index.ts', 'index.mts', 'index.mjs', 'index.js', 'index.cjs']
11
+
12
+ /**
13
+ * @param {string} dir absolute path of the service's migrations dir
14
+ * @returns {Promise<Array<{ id: string, phase: 'pre-deploy'|'post-deploy' }>>} lexical id order (the library's run order)
15
+ */
16
+ async function readReleaseMigrations(dir) {
17
+ if (!fs.existsSync(dir)) return []
18
+ const entries = fs.readdirSync(dir, { withFileTypes: true })
19
+ .filter((e) => !e.name.startsWith('.'))
20
+ .sort((a, b) => a.name.localeCompare(b.name))
21
+ const out = []
22
+ for (const entry of entries) {
23
+ let id
24
+ let file
25
+ if (entry.isDirectory()) {
26
+ id = entry.name
27
+ const name = ENTRYPOINTS.find((n) => fs.existsSync(path.join(dir, entry.name, n)))
28
+ if (!name) throw new MigrationError('MIGRATION_INVALID', `${id}: migration directory has no ${ENTRYPOINTS.join('/')}`, { id })
29
+ file = path.join(dir, entry.name, name)
30
+ } else if (entry.isFile() && CODE_EXT.test(entry.name) && !entry.name.endsWith('.d.ts')) {
31
+ id = entry.name.replace(CODE_EXT, '')
32
+ file = path.join(dir, entry.name)
33
+ } else {
34
+ continue
35
+ }
36
+ // Authoring rule 13: a migration's top level is side-effect free, so importing it only reads its metadata.
37
+ const mod = await import(pathToFileURL(file).href)
38
+ const phase = mod.phase === undefined ? 'post-deploy' : mod.phase
39
+ if (!PHASES.includes(phase)) throw new MigrationError('MIGRATION_INVALID', `${id}: phase must be one of ${PHASES.join(', ')}`, { id })
40
+ out.push({ id, phase })
41
+ }
42
+ return out
43
+ }
44
+
45
+ module.exports = { readReleaseMigrations }