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,129 @@
1
+ // Builds the §2.17.6 report-up payload: an idempotent projection of the service ledger (authoritative)
2
+ // plus dry-run, gate and backup facts. Counts and ids only, never item data.
3
+ const { classifyDryRunFailure } = require('./step-guard')
4
+
5
+ const RUN_BLOCK_STATUSES = ['MIGRATION_LOCKED', 'MIGRATION_TOO_LARGE', 'BLOCKED_NO_BACKUP']
6
+
7
+ /**
8
+ * @typedef {{ status: string, durationMs?: number, progress?: Record<string, any>, sdkStats?: Record<string, any>, error?: string }} StepResult
9
+ * @typedef {{ status: string, checksum?: string, appliedAt?: string, errorMessage?: string }} LedgerRow
10
+ * @typedef {{ status: string, restorePoints: Record<string, string>, backupArns: string[] }} BackupFacts
11
+ */
12
+
13
+ /** @param {unknown} v */
14
+ function num(v) {
15
+ return typeof v === 'number' && Number.isFinite(v) ? v : 0
16
+ }
17
+
18
+ /**
19
+ * @param {string} message
20
+ * @param {boolean} dryRun
21
+ */
22
+ function errorFromMessage(message, dryRun) {
23
+ const prefixed = /^([A-Z][A-Z0-9_]+): /.exec(message)
24
+ const code = dryRun ? classifyDryRunFailure(message) : 'MIGRATION_FAILED'
25
+ return { code: code === 'MIGRATION_FAILED' && prefixed ? prefixed[1] : code, message }
26
+ }
27
+
28
+ /**
29
+ * @param {LedgerRow|undefined} row
30
+ * @param {StepResult|undefined} dry
31
+ * @param {boolean} waiting
32
+ */
33
+ function migrationStatus(row, dry, waiting) {
34
+ if (row && row.status === 'completed') return 'completed'
35
+ // This run's gate holds the migration: a failed or interrupted row from an earlier run is retried only after approval.
36
+ if (waiting) return 'awaiting-approval'
37
+ if (row) {
38
+ if (row.status === 'failed') return 'failed'
39
+ return 'interrupted'
40
+ }
41
+ if (dry && dry.status === 'failed') return 'failed'
42
+ if (dry && dry.status === 'interrupted') return 'interrupted'
43
+ if (dry && dry.status === 'dry-run') return 'dry-run-ok'
44
+ return 'pending'
45
+ }
46
+
47
+ /**
48
+ * @param {{
49
+ * serviceRef: string, deploymentId?: string|null, commitSha?: string|null, source: string, runId: string,
50
+ * phase: string, mode: string, startedAt: string, finishedAt: string,
51
+ * ledger: { tableName: string, scope: string, stage: string },
52
+ * lock?: { owner: string, takeover: boolean }|null,
53
+ * migrations: { id: string, checksum: string, meta: Record<string, any> }[],
54
+ * ledgerRows?: Record<string, LedgerRow>, dryRun?: Record<string, StepResult>, apply?: Record<string, StepResult>,
55
+ * backups?: Record<string, BackupFacts>, waiting?: string[], approval?: object|null,
56
+ * error?: { code: string, message: string }|null,
57
+ * }} p
58
+ */
59
+ function buildReport(p) {
60
+ const ledgerRows = p.ledgerRows || {}
61
+ const dryRun = p.dryRun || {}
62
+ const apply = p.apply || {}
63
+ const backups = p.backups || {}
64
+ const waiting = new Set(p.waiting || [])
65
+
66
+ const migrations = p.migrations.map((m) => {
67
+ const row = ledgerRows[m.id]
68
+ const dry = dryRun[m.id]
69
+ const applied = apply[m.id]
70
+ const status = migrationStatus(row, dry, waiting.has(m.id))
71
+ const dryProgress = (dry && dry.progress) || {}
72
+ const applyProgress = (applied && applied.progress) || {}
73
+ let error = null
74
+ if (status === 'failed' || status === 'interrupted') {
75
+ if (row && row.errorMessage) error = errorFromMessage(row.errorMessage, false)
76
+ else if (applied && applied.error) error = errorFromMessage(applied.error, false)
77
+ else if (dry && dry.error) error = errorFromMessage(dry.error, true)
78
+ }
79
+ const facts = backups[m.id]
80
+ return {
81
+ id: m.id,
82
+ checksum: m.checksum,
83
+ phase: m.meta.phase,
84
+ destructive: !!m.meta.destructive,
85
+ rollbackSafe: !!m.meta.rollbackSafe,
86
+ status,
87
+ durationMs: num((applied && applied.durationMs) ?? (dry && dry.durationMs)),
88
+ counts: {
89
+ itemsScanned: num(applyProgress.scanned ?? dryProgress.scanned),
90
+ wouldWrite: num(dryProgress.wouldWrite),
91
+ wouldDelete: num(dryProgress.wouldDelete),
92
+ written: num(applyProgress.written),
93
+ deleted: num(applyProgress.deleted),
94
+ },
95
+ sdkStats: (applied && applied.sdkStats) || (dry && dry.sdkStats) || {},
96
+ restorePoints: (facts && facts.restorePoints) || {},
97
+ backupArns: (facts && facts.backupArns) || [],
98
+ error,
99
+ }
100
+ })
101
+
102
+ let status
103
+ if (p.error) status = RUN_BLOCK_STATUSES.includes(p.error.code) ? p.error.code : 'FAILED'
104
+ else if (migrations.some((m) => m.status === 'failed' || m.status === 'interrupted')) status = 'FAILED'
105
+ else if (migrations.length === 0) status = 'up-to-date'
106
+ else if (migrations.some((m) => m.status === 'awaiting-approval')) status = 'awaiting-approval'
107
+ else if (migrations.every((m) => m.status === 'completed')) status = 'applied'
108
+ else status = 'pending'
109
+
110
+ return {
111
+ serviceRef: p.serviceRef,
112
+ deploymentId: p.deploymentId || null,
113
+ commitSha: p.commitSha || null,
114
+ source: p.source,
115
+ runId: p.runId,
116
+ phase: p.phase,
117
+ mode: p.mode,
118
+ startedAt: p.startedAt,
119
+ finishedAt: p.finishedAt,
120
+ ledger: { tableName: p.ledger.tableName, scope: p.ledger.scope, stage: p.ledger.stage },
121
+ status,
122
+ lock: p.lock ? { owner: p.lock.owner, takeover: !!p.lock.takeover } : null,
123
+ migrations,
124
+ approval: p.approval || null,
125
+ ...(p.error ? { error: { code: p.error.code, message: p.error.message } } : {}),
126
+ }
127
+ }
128
+
129
+ module.exports = { buildReport }
@@ -0,0 +1,104 @@
1
+ // Load-time migration rules (§2.4): validates each migration's declared metadata and refuses unsafe
2
+ // pre-deploy migrations before any dry-run. Also loads pending migrations with metadata via `plan`.
3
+ const { MigrationError } = require('./errors')
4
+
5
+ const PHASES = ['pre-deploy', 'post-deploy']
6
+ const BACKUP_MODES = ['pitr', 'on-demand']
7
+
8
+ /**
9
+ * @typedef {{ description?: string, phase: 'pre-deploy'|'post-deploy', destructive: boolean, backup: 'pitr'|'on-demand', rollbackSafe: boolean, tables: string[] }} MigrationMeta
10
+ * @typedef {{ id: string, checksum: string, path?: string, meta: MigrationMeta }} LoadedMigration
11
+ */
12
+
13
+ /**
14
+ * @param {string} id
15
+ * @param {string} message
16
+ */
17
+ function invalid(id, message) {
18
+ return new MigrationError('MIGRATION_INVALID', `${id}: ${message}`, { id })
19
+ }
20
+
21
+ /**
22
+ * @param {{ id: string, meta?: Record<string, unknown> }} migration
23
+ * @param {{ tables: Record<string, string> }} service logical table → physical name from the current outputs
24
+ * @returns {MigrationMeta}
25
+ */
26
+ function validateMigration({ id, meta = {} }, { tables }) {
27
+ const phase = meta.phase === undefined ? 'post-deploy' : meta.phase
28
+ const backup = meta.backup === undefined ? 'pitr' : meta.backup
29
+ const destructive = meta.destructive === undefined ? false : meta.destructive
30
+ const rollbackSafe = meta.rollbackSafe === undefined ? false : meta.rollbackSafe
31
+ const declared = meta.tables
32
+
33
+ if (!PHASES.includes(/** @type {string} */ (phase))) throw invalid(id, `phase must be one of ${PHASES.join(', ')}`)
34
+ if (!BACKUP_MODES.includes(/** @type {string} */ (backup))) throw invalid(id, `backup must be one of ${BACKUP_MODES.join(', ')}`)
35
+ if (typeof destructive !== 'boolean') throw invalid(id, 'destructive must be a boolean')
36
+ if (typeof rollbackSafe !== 'boolean') throw invalid(id, 'rollbackSafe must be a boolean')
37
+ if (!Array.isArray(declared) || declared.length === 0 || !declared.every((t) => typeof t === 'string' && t.length > 0)) {
38
+ throw invalid(id, 'tables must be a non-empty array of logical table names')
39
+ }
40
+ if (meta.description !== undefined && typeof meta.description !== 'string') throw invalid(id, 'description must be a string')
41
+
42
+ const missing = declared.filter((t) => !tables[t])
43
+ if (phase === 'pre-deploy') {
44
+ if (destructive) {
45
+ throw new MigrationError('PRE_DEPLOY_DESTRUCTIVE', `${id}: a pre-deploy migration must not be destructive (the previous release is still serving)`, { id })
46
+ }
47
+ if (rollbackSafe !== true) {
48
+ throw new MigrationError('PRE_DEPLOY_NOT_ROLLBACK_SAFE', `${id}: a pre-deploy migration must declare rollbackSafe: true`, { id })
49
+ }
50
+ if (missing.length > 0) {
51
+ throw new MigrationError('PRE_DEPLOY_TABLE_MISSING', `${id}: pre-deploy tables not in the current stack outputs: ${missing.join(', ')}`, { id, missing })
52
+ }
53
+ }
54
+ if (missing.length > 0) {
55
+ throw new MigrationError('MIGRATION_TABLE_OUTPUT_MISSING', `${id}: no stack output resolved for tables: ${missing.join(', ')}`, { id, missing })
56
+ }
57
+
58
+ return {
59
+ description: /** @type {string|undefined} */ (meta.description),
60
+ phase: /** @type {MigrationMeta['phase']} */ (phase),
61
+ destructive,
62
+ backup: /** @type {MigrationMeta['backup']} */ (backup),
63
+ rollbackSafe,
64
+ tables: declared.slice(),
65
+ }
66
+ }
67
+
68
+ /**
69
+ * @template {{ id: string, meta: { phase: string } }} M
70
+ * @param {M[]} migrations lexical id order
71
+ * @param {'pre'|'post'|'all'} phase
72
+ * @returns {M[]}
73
+ */
74
+ function selectPhase(migrations, phase) {
75
+ const pre = migrations.filter((m) => m.meta.phase === 'pre-deploy')
76
+ const post = migrations.filter((m) => m.meta.phase === 'post-deploy')
77
+ if (phase === 'pre') return pre
78
+ if (phase === 'post') return post
79
+ if (phase === 'all') return [...pre, ...post]
80
+ throw new MigrationError('MIGRATION_INVALID', `phase must be pre, post or all; got ${String(phase)}`)
81
+ }
82
+
83
+ /**
84
+ * Lists pending migrations with their metadata through the library's `plan` (reads the ledger, imports
85
+ * each pending module) and validates every one. Fails closed on the first invalid migration.
86
+ * @param {{ config: object, stage: string, clients: object, tables: Record<string, string> }} p
87
+ * @returns {Promise<{ pending: LoadedMigration[], drifted: string[] }>}
88
+ */
89
+ async function loadMigrations({ config, stage, clients, tables }) {
90
+ const { plan } = await import('ddb-migration-tools')
91
+ const result = await plan({ config, stage, clients, includeMeta: true })
92
+ if (result.drifted.length > 0) {
93
+ throw new MigrationError('MIGRATION_CHECKSUM_DRIFT', `completed migrations changed on disk: ${result.drifted.join(', ')}`, { drifted: result.drifted })
94
+ }
95
+ const pending = result.pending.map((p) => ({
96
+ id: p.id,
97
+ checksum: p.checksum,
98
+ path: p.path,
99
+ meta: validateMigration({ id: p.id, meta: p.meta }, { tables }),
100
+ }))
101
+ return { pending, drifted: result.drifted }
102
+ }
103
+
104
+ module.exports = { validateMigration, selectPhase, loadMigrations, PHASES }
@@ -0,0 +1,311 @@
1
+ // runServiceMigrations: one service's migrations for one phase against its own ledger — lease, plan,
2
+ // IAM-enforced dry-run child, gate, backup check, apply child, release, report. Shared by deployer and CLI.
3
+ const path = require('path')
4
+ const { DescribeTableCommand, DynamoDBClient } = require('@aws-sdk/client-dynamodb')
5
+ const { DynamoDBDocumentClient } = require('@aws-sdk/lib-dynamodb')
6
+ const { assumeMigrateRole, migrateSessionName, SESSION_PREFIX } = require('./credentials')
7
+ const { runStepChild } = require('./child')
8
+ const { checkBackups } = require('./backups')
9
+ const { splitByGate } = require('./gate')
10
+ const { loadMigrations, selectPhase } = require('./rules')
11
+ const { buildReport } = require('./report')
12
+ const { MigrationError, toErrorInfo } = require('./errors')
13
+ const { debugRun } = require('./log')
14
+
15
+ // Lease outlives the phase timeout by 5 minutes so a slow finish never loses it.
16
+ const LEASE_GRACE_SECONDS = 300
17
+ const MAX_HEARTBEAT_MS = 60 * 1000
18
+ // Library/child codes mapped onto the pipeline's failure taxonomy names.
19
+ const CODE_MAP = { LOCK_HELD: 'MIGRATION_LOCKED', LEDGER_MISSING: 'MIGRATION_LEDGER_MISSING' }
20
+
21
+ /**
22
+ * @typedef {{
23
+ * service: { ref: string, dir: string, migrationsDir: string, tables: Record<string, string> },
24
+ * ledger: { tableName: string, scope: string, stage: string },
25
+ * role: { roleArn?: string, sourceCredentials?: any, sessionPrefix?: string },
26
+ * region: string,
27
+ * accountId?: string,
28
+ * endpoint?: string,
29
+ * phase: 'pre'|'post'|'all',
30
+ * mode: 'plan'|'dry-run'|'apply',
31
+ * gate: { policy: 'auto'|'destructive'|'all', protected: boolean, approval?: any },
32
+ * run: { runId: string, appliedBy: string, source: 'deployer'|'self', commitSha?: string, lockOwner?: string },
33
+ * params?: Record<string, unknown>,
34
+ * faultInjection?: { failAfterCheckpoints: number },
35
+ * timeoutSeconds: number,
36
+ * estimateSeconds?: (migration: { id: string, meta: any }) => Promise<number>,
37
+ * onReport?: (report: object) => Promise<void>,
38
+ * onOutput?: (chunk: string) => void,
39
+ * onEvent?: (event: { type: string, id: string }) => void,
40
+ * signal?: AbortSignal,
41
+ * }} RunOptions
42
+ */
43
+
44
+ /**
45
+ * @param {unknown} err
46
+ * @returns {{ code: string, message: string }}
47
+ */
48
+ function errorOf(err) {
49
+ const info = toErrorInfo(err)
50
+ const code = CODE_MAP[info.code] || info.code
51
+ return { code, message: info.message.replace(/^[A-Z][A-Z0-9_]+: /, '') }
52
+ }
53
+
54
+ /**
55
+ * @param {{ results?: any[] }} upResult
56
+ * @returns {Record<string, any>}
57
+ */
58
+ function resultsById(upResult) {
59
+ return Object.fromEntries((upResult.results || []).map((r) => [r.id, r]))
60
+ }
61
+
62
+ /**
63
+ * @param {{ ledgerRaw: any, tableName: string }} p
64
+ */
65
+ async function assertLedgerExists({ ledgerRaw, tableName }) {
66
+ try {
67
+ await ledgerRaw.send(new DescribeTableCommand({ TableName: tableName }))
68
+ } catch (err) {
69
+ if (err && err.name === 'ResourceNotFoundException') {
70
+ throw new MigrationError('MIGRATION_LEDGER_MISSING', `ledger table ${tableName} does not exist`)
71
+ }
72
+ throw err
73
+ }
74
+ }
75
+
76
+ /**
77
+ * The library config object for one service's ledger stage (nothing is read from cwd).
78
+ * @param {Pick<RunOptions, 'service'|'ledger'|'region'|'accountId'|'endpoint'>} opts
79
+ */
80
+ function libraryConfig({ service, ledger, region, accountId, endpoint }) {
81
+ return {
82
+ appName: service.ref,
83
+ migrationsDir: path.resolve(service.dir, service.migrationsDir),
84
+ ledger: { tableName: ledger.tableName, scope: ledger.scope, create: false },
85
+ stages: { [ledger.stage]: { region, accountId, tables: service.tables, ...(endpoint ? { endpoint } : {}) } },
86
+ }
87
+ }
88
+
89
+ /**
90
+ * @param {RunOptions} opts
91
+ * @param {{ assumeMigrateRole?: typeof assumeMigrateRole, runStepChild?: typeof runStepChild, checkBackups?: typeof checkBackups, now?: () => number }} [deps]
92
+ * @returns {Promise<object>} the §2.17.6 report (plus reportError when onReport failed)
93
+ */
94
+ async function runServiceMigrations(opts, deps = {}) {
95
+ const assume = deps.assumeMigrateRole || assumeMigrateRole
96
+ const stepChild = deps.runStepChild || runStepChild
97
+ const backupCheck = deps.checkBackups || checkBackups
98
+ const now = deps.now || Date.now
99
+ const startedAt = new Date(now()).toISOString()
100
+ const { service, ledger, run, gate } = opts
101
+ const lockOwner = run.lockOwner || run.appliedBy
102
+
103
+ /** @type {{ id: string, checksum: string, path?: string, meta: any }[]} */
104
+ let considered = []
105
+ const dryRun = {}
106
+ const apply = {}
107
+ const backups = {}
108
+ const waiting = []
109
+ /** @type {{ code: string, message: string }|null} */
110
+ let error = null
111
+ let lockInfo = null
112
+ let ledgerRows = {}
113
+
114
+ const finish = async () => {
115
+ const report = buildReport({
116
+ serviceRef: service.ref,
117
+ deploymentId: opts.params && typeof opts.params.deploymentId === 'string' ? opts.params.deploymentId : null,
118
+ commitSha: run.commitSha,
119
+ source: run.source,
120
+ runId: run.runId,
121
+ phase: opts.phase,
122
+ mode: opts.mode,
123
+ startedAt,
124
+ finishedAt: new Date(now()).toISOString(),
125
+ ledger,
126
+ lock: lockInfo,
127
+ migrations: considered,
128
+ ledgerRows,
129
+ dryRun,
130
+ apply,
131
+ backups,
132
+ waiting,
133
+ approval: gate.approval || null,
134
+ error,
135
+ })
136
+ debugRun('report service=%s phase=%s mode=%s status=%s', service.ref, opts.phase, opts.mode, report.status)
137
+ if (!opts.onReport) return report
138
+ try {
139
+ await opts.onReport(report)
140
+ return report
141
+ } catch (err) {
142
+ // The ledger already holds the outcome; a lost report is re-sent later, never re-applied.
143
+ debugRun('report delivery failed service=%s reason=%s', service.ref, toErrorInfo(err).code)
144
+ return { ...report, reportError: toErrorInfo(err) }
145
+ }
146
+ }
147
+
148
+ // Proof knob (non-protected deployments only): the apply child fails after its Nth checkpoint write.
149
+ const fault = opts.faultInjection
150
+ if (fault && !(Number.isInteger(fault.failAfterCheckpoints) && fault.failAfterCheckpoints > 0)) {
151
+ error = { code: 'INVALID_FAULT_INJECTION', message: `faultInjection.failAfterCheckpoints must be a positive integer; got ${String(fault.failAfterCheckpoints)}` }
152
+ return finish()
153
+ }
154
+ if (!ledger || !ledger.tableName) {
155
+ error = { code: 'MIGRATION_LEDGER_MISSING', message: 'no MigrationsLedgerTableName output for this service' }
156
+ return finish()
157
+ }
158
+ if (!opts.role || !opts.role.roleArn) {
159
+ error = { code: 'MIGRATE_ROLE_MISSING', message: 'no MigrateRoleArn output for this service (no trusted principal?)' }
160
+ return finish()
161
+ }
162
+
163
+ const stage = ledger.stage
164
+ const config = libraryConfig(opts)
165
+ const sessionPrefix = opts.role.sessionPrefix || SESSION_PREFIX
166
+ const fullSession = assume({
167
+ roleArn: opts.role.roleArn,
168
+ sourceCredentials: opts.role.sourceCredentials,
169
+ readOnly: false,
170
+ region: opts.region,
171
+ sessionName: migrateSessionName({ prefix: sessionPrefix, kind: 'apply', runId: run.runId }),
172
+ })
173
+ const clientConfig = { region: opts.region, credentials: fullSession, ...(opts.endpoint ? { endpoint: opts.endpoint } : {}) }
174
+ const ledgerRaw = new DynamoDBClient(clientConfig)
175
+ const ledgerDoc = DynamoDBDocumentClient.from(ledgerRaw)
176
+ const lib = await import('ddb-migration-tools')
177
+ const lockParams = { ledgerClient: ledgerDoc, tableName: ledger.tableName, scope: ledger.scope, stage, owner: lockOwner }
178
+ const ttlSeconds = opts.timeoutSeconds + LEASE_GRACE_SECONDS
179
+
180
+ /** @type {NodeJS.Timeout|undefined} */
181
+ let heartbeat
182
+ const stepAbort = new AbortController()
183
+ const forwardAbort = () => stepAbort.abort()
184
+ if (opts.signal) opts.signal.addEventListener('abort', forwardAbort, { once: true })
185
+ let acquired = false
186
+
187
+ try {
188
+ await assertLedgerExists({ ledgerRaw, tableName: ledger.tableName })
189
+ const loaded = await loadMigrations({ config, stage, clients: { ledger: { raw: ledgerRaw } }, tables: service.tables })
190
+ considered = selectPhase(loaded.pending, opts.phase)
191
+ if (opts.mode === 'plan' || considered.length === 0) return await finish()
192
+
193
+ try {
194
+ const lease = await lib.acquireLock({ ...lockParams, ttlSeconds })
195
+ acquired = true
196
+ lockInfo = { owner: lockOwner, takeover: lease.takeover }
197
+ } catch (err) {
198
+ if (err && err.code === 'LOCK_HELD') {
199
+ throw new MigrationError('MIGRATION_LOCKED', `ledger lease held by ${err.holder} until ${new Date(err.expiresAt * 1000).toISOString()}`)
200
+ }
201
+ throw err
202
+ }
203
+ heartbeat = setInterval(() => {
204
+ lib.heartbeatLock({ ...lockParams, ttlSeconds }).catch((err) => {
205
+ debugRun('lease heartbeat failed reason=%s; stopping step', toErrorInfo(err).code)
206
+ stepAbort.abort()
207
+ })
208
+ }, Math.min(MAX_HEARTBEAT_MS, (ttlSeconds * 1000) / 3))
209
+ heartbeat.unref()
210
+
211
+ const readOnlySession = assume({
212
+ roleArn: opts.role.roleArn,
213
+ sourceCredentials: opts.role.sourceCredentials,
214
+ readOnly: true,
215
+ region: opts.region,
216
+ sessionName: migrateSessionName({ prefix: sessionPrefix, kind: 'dryrun', runId: run.runId }),
217
+ })
218
+ const tablesById = Object.fromEntries(considered.map((m) => [m.id, m.meta.tables.map((t) => service.tables[t])]))
219
+ const request = (dryRunStep, only) => ({
220
+ stage,
221
+ config,
222
+ cwd: service.dir,
223
+ dryRun: dryRunStep,
224
+ only,
225
+ appliedBy: run.appliedBy,
226
+ params: opts.params || {},
227
+ lockOwner,
228
+ tablesById,
229
+ ...(fault && !dryRunStep ? { faultInjection: fault } : {}),
230
+ })
231
+ const step = (credentials, dryRunStep, only) => stepChild({
232
+ credentials,
233
+ region: opts.region,
234
+ request: request(dryRunStep, only),
235
+ cwd: service.dir,
236
+ onOutput: opts.onOutput,
237
+ onEvent: opts.onEvent,
238
+ signal: stepAbort.signal,
239
+ })
240
+
241
+ const passes = opts.phase === 'all' ? ['pre', 'post'] : [opts.phase]
242
+ for (const pass of passes) {
243
+ const migrations = selectPhase(considered, pass)
244
+ if (migrations.length === 0) continue
245
+
246
+ const dry = await step(readOnlySession, true, migrations.map((m) => m.id))
247
+ Object.assign(dryRun, resultsById(dry))
248
+ if (dry.failed || dry.interrupted) break
249
+
250
+ if (opts.estimateSeconds) {
251
+ for (const m of migrations) {
252
+ const estimate = await opts.estimateSeconds(m)
253
+ if (estimate > opts.timeoutSeconds) {
254
+ throw new MigrationError('MIGRATION_TOO_LARGE', `${m.id} estimated ${estimate}s exceeds the ${opts.timeoutSeconds}s window`)
255
+ }
256
+ }
257
+ }
258
+ if (opts.mode === 'dry-run') continue
259
+
260
+ const split = splitByGate({ ...gate, serviceRef: service.ref, migrations })
261
+ waiting.push(...split.waiting.map((m) => m.id))
262
+ const toApply = []
263
+ for (const m of split.apply) {
264
+ if (m.meta.destructive) {
265
+ const result = await backupCheck({
266
+ dynamo: new DynamoDBClient(clientConfig),
267
+ tables: m.meta.tables.map((t) => service.tables[t]),
268
+ mode: m.meta.backup,
269
+ protected: gate.protected,
270
+ label: m.id,
271
+ })
272
+ backups[m.id] = result
273
+ if (result.status !== 'ok') {
274
+ const why = result.blockedTables ? `PITR not enabled on ${result.blockedTables.join(', ')}` : (result.error && result.error.message)
275
+ error = { code: 'BLOCKED_NO_BACKUP', message: `${m.id}: ${why}` }
276
+ break
277
+ }
278
+ }
279
+ toApply.push(m)
280
+ }
281
+ if (toApply.length > 0) {
282
+ const applied = await step(fullSession, false, toApply.map((m) => m.id))
283
+ Object.assign(apply, resultsById(applied))
284
+ if (applied.failed || applied.interrupted) break
285
+ }
286
+ if (error || waiting.length > 0) break
287
+ }
288
+ } catch (err) {
289
+ error = errorOf(err)
290
+ debugRun('run stopped service=%s reason=%s', service.ref, error.code)
291
+ } finally {
292
+ if (heartbeat) clearInterval(heartbeat)
293
+ if (opts.signal) opts.signal.removeEventListener('abort', forwardAbort)
294
+ if (acquired) {
295
+ await lib.releaseLock(lockParams).catch((err) => debugRun('lease release failed reason=%s', toErrorInfo(err).code))
296
+ }
297
+ }
298
+
299
+ if (considered.length > 0) {
300
+ try {
301
+ const statuses = await lib.status({ config, stage, clients: { ledger: { raw: ledgerRaw } } })
302
+ ledgerRows = Object.fromEntries(statuses.filter((s) => s.status !== 'pending' && s.status !== 'orphan').map((s) => [s.id, { status: s.status, appliedAt: s.appliedAt }]))
303
+ } catch (err) {
304
+ debugRun('ledger re-read failed reason=%s', toErrorInfo(err).code)
305
+ if (!error) error = errorOf(err)
306
+ }
307
+ }
308
+ return finish()
309
+ }
310
+
311
+ module.exports = { runServiceMigrations, libraryConfig, assertLedgerExists, errorOf }
@@ -0,0 +1,37 @@
1
+ // Read-only STS session policy for migration dry-runs. Passed as `Policy` when assuming the migrate
2
+ // role, so the session's effective permissions (role ∩ session) reject every DynamoDB write.
3
+
4
+ /**
5
+ * @template T
6
+ * @param {T} value
7
+ * @returns {Readonly<T>}
8
+ */
9
+ function deepFreeze(value) {
10
+ if (value && typeof value === 'object') {
11
+ for (const inner of Object.values(value)) deepFreeze(inner)
12
+ Object.freeze(value)
13
+ }
14
+ return value
15
+ }
16
+
17
+ // Resource '*' is safe: a session policy only removes permissions, and the role policy already limits
18
+ // resources to the service's own tables and ledger.
19
+ const readOnlySessionPolicy = deepFreeze({
20
+ Version: '2012-10-17',
21
+ Statement: [{
22
+ Sid: 'MigrationDryRunReadOnly',
23
+ Effect: 'Allow',
24
+ Action: [
25
+ 'dynamodb:GetItem',
26
+ 'dynamodb:BatchGetItem',
27
+ 'dynamodb:Query',
28
+ 'dynamodb:Scan',
29
+ 'dynamodb:DescribeTable',
30
+ 'dynamodb:DescribeContinuousBackups',
31
+ 'dynamodb:DescribeBackup',
32
+ ],
33
+ Resource: '*',
34
+ }],
35
+ })
36
+
37
+ module.exports = { readOnlySessionPolicy, deepFreeze }
@@ -0,0 +1,82 @@
1
+ // Client-side guard on the migration app client: refuses any table the active migration did not declare
2
+ // (UNDECLARED_TABLE) and, in a dry-run, any non-read command (DRY_RUN_WRITE_BLOCKED). IAM stays the guarantee.
3
+ const { MigrationError } = require('./errors')
4
+
5
+ // Command-name prefixes a dry-run may send. Everything else (writes, backups, table changes) is refused.
6
+ const DRY_RUN_ALLOWED = ['Get', 'BatchGet', 'TransactGet', 'Query', 'Scan', 'Describe', 'List']
7
+ // PartiQL statements carry table names inside SQL text, which this guard cannot check.
8
+ const UNGUARDABLE = ['ExecuteStatementCommand', 'BatchExecuteStatementCommand', 'ExecuteTransactionCommand']
9
+ const WRITE_ACTIONS = ['PutItem', 'UpdateItem', 'DeleteItem', 'BatchWriteItem', 'TransactWriteItems', 'CreateBackup']
10
+
11
+ /** @param {string} tableNameOrArn */
12
+ function tableOf(tableNameOrArn) {
13
+ const i = tableNameOrArn.indexOf(':table/')
14
+ if (i === -1) return tableNameOrArn
15
+ return tableNameOrArn.slice(i + ':table/'.length).split('/')[0]
16
+ }
17
+
18
+ /**
19
+ * @param {Record<string, any>} input
20
+ * @returns {string[]}
21
+ */
22
+ function tablesInInput(input) {
23
+ const out = []
24
+ if (typeof input.TableName === 'string') out.push(input.TableName)
25
+ if (input.RequestItems && typeof input.RequestItems === 'object') out.push(...Object.keys(input.RequestItems))
26
+ if (Array.isArray(input.TransactItems)) {
27
+ for (const item of input.TransactItems) {
28
+ for (const op of Object.values(item || {})) {
29
+ if (op && typeof op.TableName === 'string') out.push(op.TableName)
30
+ }
31
+ }
32
+ }
33
+ return out.map(tableOf)
34
+ }
35
+
36
+ /**
37
+ * Adds the guard to the raw client's middleware stack, which the library's document client shares.
38
+ * @param {{ middlewareStack: { add: Function } }} raw
39
+ * @param {{ dryRun: boolean, tablesFor: (migrationId: string) => string[] }} opts physical table names per migration
40
+ * @returns {{ setActiveMigration: (id: string|undefined) => void }}
41
+ */
42
+ function guardAppClient(raw, { dryRun, tablesFor }) {
43
+ /** @type {string|undefined} */
44
+ let active
45
+
46
+ const middleware = (next, context) => async (args) => {
47
+ const command = context.commandName || 'UnknownCommand'
48
+ const tables = tablesInInput(args.input || {})
49
+ if (UNGUARDABLE.includes(command)) {
50
+ throw new MigrationError('UNDECLARED_TABLE', `${command} cannot be table-guarded; use item commands`, { command })
51
+ }
52
+ if (tables.length > 0) {
53
+ const allowed = active ? tablesFor(active) : []
54
+ const undeclared = tables.filter((t) => !allowed.includes(t))
55
+ if (undeclared.length > 0) {
56
+ throw new MigrationError('UNDECLARED_TABLE', `${active || '(no active migration)'} sent ${command} to undeclared tables: ${undeclared.join(', ')}`, { migrationId: active, command })
57
+ }
58
+ }
59
+ if (dryRun && !DRY_RUN_ALLOWED.some((prefix) => command.startsWith(prefix))) {
60
+ throw new MigrationError('DRY_RUN_WRITE_BLOCKED', `${command} on ${tables.join(', ') || '(no table)'} refused during dry-run`, { migrationId: active, command })
61
+ }
62
+ return next(args)
63
+ }
64
+
65
+ raw.middlewareStack.add(middleware, { step: 'initialize', name: 'saaslayerMigrationStepGuard', priority: 'high' })
66
+ return { setActiveMigration: (id) => { active = id } }
67
+ }
68
+
69
+ /**
70
+ * Maps a dry-run failure message to its code. An IAM denial of a write action (a migration that built
71
+ * its own client) and the client guard's refusal both mean the migration tried to write.
72
+ * @param {string} message
73
+ * @returns {'DRY_RUN_WRITE_BLOCKED'|'MIGRATION_FAILED'}
74
+ */
75
+ function classifyDryRunFailure(message) {
76
+ if (/^DRY_RUN_WRITE_BLOCKED\b/.test(message)) return 'DRY_RUN_WRITE_BLOCKED'
77
+ const denied = /not authorized to perform: dynamodb:(\w+)/.exec(message)
78
+ if (denied && WRITE_ACTIONS.includes(denied[1])) return 'DRY_RUN_WRITE_BLOCKED'
79
+ return 'MIGRATION_FAILED'
80
+ }
81
+
82
+ module.exports = { guardAppClient, classifyDryRunFailure, tablesInInput }
@@ -0,0 +1,21 @@
1
+ // Types for the deployment activity feed (activity.js): entries projected from deployer runs and recorded
2
+ // non-run actions, each attributed to a customer or operator actor.
3
+ export type ActorKind = 'customer' | 'operator'
4
+ export interface Actor { kind: ActorKind; id: string }
5
+ export interface ActivityEntry {
6
+ id: string
7
+ at: string | null
8
+ actor: Actor | null
9
+ action: string
10
+ subject: string | null
11
+ reason: string | null
12
+ operationId: string | null
13
+ status?: string
14
+ }
15
+
16
+ export const ACTOR_KINDS: ActorKind[]
17
+ export function actorOf(value: unknown): Actor | null
18
+ export function activityFromRun(run: Record<string, unknown>): ActivityEntry
19
+ export function activityFromRecord(record: Record<string, unknown>): ActivityEntry
20
+ export function activityFeed(input: { runs?: Array<Record<string, unknown>>; records?: Array<Record<string, unknown>>; limit?: number }): ActivityEntry[]
21
+ export function formatActivity(entries: ActivityEntry[]): string[]