[diegosouzapw]

⚠️ base-red inherited: #15306

Problem

omniroute sync import --dry-run POSTed the backup to POST /api/db-backups/import?dryRun=true, but the route never read dryRun. A "dry run" therefore replaced the live database, which is data loss. The command also sent only the Bearer key. The route only accepted a dashboard session or a manage-scoped API key, so on the server host, with just the local CLI credential, the import came back 401.

Fix

Route (src/app/api/db-backups/import/route.ts): a real server-side dry run.

• dryRun=true (query string, or a multipart dryRun field) runs the same validation as a real import: .sqlite type, size limits, SQLite integrity_check and the required tables. It then returns { dryRun: true, valid: true, imported: false, connectionCount, nodeCount, comboCount, apiKeyCount, schemaVersion, sizeBytes, filename }. It skips the pre-import backup and leaves the live DB alone (the test checks the file hash).
• The handler is split into readUpload / validateUploadShape / inspectCandidate / replaceLiveDatabase. The complexity ratchet improved (complexity −2, cognitive −1). The SQL that summarizes the candidate lives in src/lib/db/backup.ts (summarizeImportCandidate), so the route has no raw SQL. The temp candidate handle is now closed on every validation exit; before, an integrity or tables 400 leaked it.
• Auth: the dashboard session and manage-scoped API keys still work as before. The route now also accepts the machine-bound local CLI credential, through the new isLocalCliCredential() helper, which resolveOperatorCredential() now shares. The always-protected classification in routeGuard.ts is unchanged.

CLI (runSyncImport in bin/cli/commands/sync.mjs; local checks in bin/cli/commands/sync-import.mjs)

• --dry-run never contacts the server. An older server still ignores dryRun and would replace the DB, so the CLI validates the file locally (header, integrity, required tables, counts, schema version) and prints the summary.
• A real import goes through fix(cli): map sync push/bundle/initialize onto the real routes; drop sync diff/resolve #16721's shared sendSyncRequest / reportFailure / routeUnavailableHint helpers, so apiFetch sends the local CLI credential to a loopback server. It runs with no retry (a replace should not be replayed blindly after a 502) and a 5-minute timeout. Files that are not SQLite (for example the JSON from sync bundle) are refused before upload, with a hint. 400/401/403/404 end in Error: sync import failed (HTTP n): <server message> plus a hint and the usual exit code (2/4/…), never a stack trace.
• Merged with release/v3.8.52 after fix(cli): map sync push/bundle/initialize onto the real routes; drop sync diff/resolve #16721. The authHeaders helper and the getBaseUrl import were unused after the merge and are removed.

Why a real dry run and not a 400: the validation already existed, and the dry run is just an early return before the destructive branch. That is cheap, and it also protects curl, dashboard and future clients that pass the flag.

Tests (TDD)

• tests/unit/db-import-dry-run.test.ts drives the real route against an isolated DATA_DIR: query and multipart dry runs leave the live sentinel row and the file hash unchanged, an invalid upload in dry-run mode gets a 400 with no side effect, a request with no credential gets 401, the pipeline-stamped local CLI subject is accepted, and a real import still replaces the DB (regression). RED on base: 5/6 failed. The first dry run returned imported: true and wiped the sentinel, and the CLI subject got a 401. GREEN: 6/6.
• tests/unit/cli-sync-import-dry-run.test.ts drives the real commander wiring with fetch stubbed: --dry-run makes zero network calls, a backup missing tables gets exit 2, a JSON bundle is refused locally, an unreadable path gives a clean error, a real import sends POST + octet-stream + x-omniroute-cli-token + ?filename=, a 403 gives exit 4 with a hint, and a 400 surfaces the server message. RED on base: 7/7 failed. GREEN: 7/7.

Validation

• Related suites on the merged tree (import, backup, auth, route-guard, cli-sync including fix(cli): map sync push/bundle/initialize onto the real routes; drop sync diff/resolve #16721's cli-sync-subcommands-routes, credential-export, cli-tokens, cli-i18n): 209/209 pass
• check:complexity-ratchets --base-ref <merge-base>: OK (complexity −2, cognitive −1)
• check:file-size: OK
• Touched TS files typecheck clean; ESLint clean (bin/ is eslint-ignored); Prettier clean
• check:docs-all, check:openapi-{breaking,coverage,routes,security-tiers}, check:cli-i18n, check:route-guard-membership, check:route-validation:t06: all pass
• docs/openapi.yaml and API_REFERENCE.md document dryRun / filename and the 400/401 responses

Notes / out of scope

• sync bundle writes JSON (/api/sync/bundle), but sync import restores a .sqlite backup, so the two do not round-trip. import now says this clearly instead of uploading the JSON. bundle itself was reworked in fix(cli): map sync push/bundle/initialize onto the real routes; drop sync diff/resolve #16721.
• Import is still reachable with a manage-scoped API key, as before. Export was tightened to operator-only credentials in fix(security): require an operator credential to export stored credentials #16680, while an irreversible full-DB replace still accepts machine credentials. Whether import should get the same restriction is an owner decision; it is not changed here.

[github-actions]

CI Coverage Report

• Coverage job: skipped
• PR test policy: success

Coverage artifact was not available for this run.