saaslayer 0.4.1 → 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.
- package/bin/saaslayer.js +91 -6
- package/package.json +5 -6
- package/src/api-client.js +3 -2
- package/src/commands/foundation.js +5 -3
- package/src/commands/hooks.js +4 -9
- package/src/commands/operations.js +1 -1
- package/src/commands/release-manifest.js +3 -1
- package/src/commands/settings.js +2 -0
- package/src/commands/sms.js +35 -4
- package/src/commands/sso.js +913 -0
- package/src/commands/users-management.js +2 -2
- package/src/commands/users.js +7 -3
- package/src/commands/verifier-keys.js +105 -0
- package/src/login-domain.js +1 -0
- package/src/release-manifest.js +30 -7
- package/src/secret-sink.js +77 -0
- package/src/sms/registration-fields.js +1 -1
- package/src/sso-plan.js +21 -0
- package/src/user-service-instance.js +30 -1
- package/src/users-api.js +3 -2
- package/src/users-import/ids.js +1 -1
- package/templates/saaslayer-foundation-region.yml +10 -2
- package/templates/saaslayer-foundation.yml +33 -5
- package/vendor/config/login-domain.js +213 -0
- package/vendor/discovery/index.d.mts +109 -0
- package/vendor/discovery/index.mjs +409 -0
- package/vendor/ids/index.d.ts +21 -0
- package/vendor/ids/index.js +237 -0
- package/vendor/migrations/backups.js +118 -0
- package/vendor/migrations/child.js +78 -0
- package/vendor/migrations/credentials.js +103 -0
- package/vendor/migrations/errors.js +30 -0
- package/vendor/migrations/exec-child.js +78 -0
- package/vendor/migrations/gate.js +51 -0
- package/vendor/migrations/index.js +30 -0
- package/vendor/migrations/inventory.js +92 -0
- package/vendor/migrations/log.js +14 -0
- package/vendor/migrations/release.js +45 -0
- package/vendor/migrations/report.js +129 -0
- package/vendor/migrations/rules.js +104 -0
- package/vendor/migrations/run.js +311 -0
- package/vendor/migrations/session-policy.js +37 -0
- package/vendor/migrations/step-guard.js +82 -0
- package/vendor/operations/activity.d.ts +21 -0
- package/vendor/operations/activity.js +126 -0
- package/vendor/operations/index.d.ts +60 -0
- package/vendor/operations/index.js +471 -0
- package/vendor/permissions-engine-core/account-status.js +270 -0
- package/vendor/permissions-engine-core/delegation.js +174 -0
- package/vendor/permissions-engine-core/direct-mode-contract.js +237 -0
- package/vendor/permissions-engine-core/sso-claims.js +206 -0
- package/vendor/user-management/cognito/emails/token-registry.js +48 -0
- package/vendor/user-management/email/validate.js +207 -0
- package/vendor/user-management/extensibility/hook-contract.js +720 -0
- package/vendor/user-management/extensibility/safe-webhook.js +85 -0
- package/vendor/user-management/identity/admission.js +215 -0
- package/vendor/user-management/identity/attr.js +27 -0
- package/vendor/user-management/identity/attribute-registry.js +115 -0
- package/vendor/user-management/identity/email.js +25 -0
- package/vendor/user-management/identity/ensure-suid.js +74 -0
- package/vendor/user-management/identity/pointers.js +192 -0
- package/vendor/user-management/identity/stitch-provider.js +275 -0
- package/vendor/user-management/management/apply-request.js +227 -0
- package/vendor/user-management/management/core-profile.js +110 -0
- package/vendor/user-management/management/index.js +23 -0
- package/vendor/user-management/management/purposes.js +94 -0
- package/vendor/user-management/management/registry.js +569 -0
- 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 }
|