diff --git a/package.json b/package.json
index 52905a2af..0d9de0230 100644
--- a/package.json
+++ b/package.json
@@ -71,9 +71,14 @@
     "test-coverage-ci": "cross-env NODE_ENV=test vitest --run --dir ./test --coverage.enabled=true --coverage.reporter=lcovonly --coverage.reporter=text",
     "test:integration": "cross-env NODE_ENV=test vitest --run --config vitest.config.integration.ts",
     "test:watch": "cross-env NODE_ENV=test vitest --dir ./test --watch",
+    "test:migrate": "cross-env NODE_ENV=test vitest --run --dir ./scripts/migrate/test",
     "prepare": "node ./scripts/prepare.js",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
+    "migrate:urls": "node scripts/migrate/migrate-urls.js",
+    "migrate:users": "node scripts/migrate/migrate-users.js",
+    "backup:urls": "node scripts/migrate/backup-urls.js",
+    "backup:users": "node scripts/migrate/backup-users.js",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,yml,yaml,css,scss}\" --ignore-path .gitignore --config ./.prettierrc",
     "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,md,yml,yaml,css,scss}\" --ignore-path .gitignore --config ./.prettierrc",
     "gen-schema-doc": "node ./scripts/doc-schema.js",
diff --git a/scripts/migrate/Migration-guide-v1-to-v2.md b/scripts/migrate/Migration-guide-v1-to-v2.md
new file mode 100644
index 000000000..f9006a19a
--- /dev/null
+++ b/scripts/migrate/Migration-guide-v1-to-v2.md
@@ -0,0 +1,233 @@
+# Git-Proxy v1.19.2 → v2.0.0 migration (MongoDB or file DB)
+
+Operator prep for upgrade, aligned with [finos/git-proxy#1535](https://github.com/finos/git-proxy/issues/1535#issuecomment-4478956510) (these scripts do **not** replace your own DB backup/snapshot).
+**Behavior:** dry-run by default for both phases; normalization is idempotent; email apply skips unchanged rows and checks uniqueness before writes; backups are explicit helper scripts plus your own infra.
+
+| Phase | Scripts                               | Goal                                                                                                                                                                               |
+| ----- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1** | `migrate-urls.js`, `backup-urls.js`   | **Repo URL normalization** — append `.git` to `repos.url` where missing (idempotent)                                                                                               |
+| **2** | `migrate-users.js`, `backup-users.js` | **Email audit** (blocking issues) + optional **CSV apply**; **ACL audit** — list `canPush` / `canAuthorise` entries that do not resolve to any `User.username` (no silent rewrite) |
+
+Configuration: `scripts/migrate/lib/config.js` and `scripts/migrate/lib/datastore.js`. Report file names and contents: [Report artifacts](#report-artifacts) below.
+
+## npm scripts
+
+```bash
+npm run backup:urls
+npm run migrate:urls                        # repo URL normalization — dry-run
+npm run migrate:urls -- --apply              # apply normalization
+
+npm run backup:users
+npm run migrate:users                        # email + ACL audit (dry-run)
+npm run migrate:users -- --apply --csv ./map.csv
+```
+
+Equivalent: `node scripts/migrate/<script>.js` from the repository root (same env vars).
+
+Optional local env file (example): `scripts/migrate/envs/local.env`
+
+```bash
+set -a && source scripts/migrate/envs/local.env && set +a
+npm run migrate:users
+```
+
+---
+
+## Database backend (`--dbType`)
+
+All scripts connect through `scripts/migrate/lib/datastore.js`.
+
+| Backend     | `--dbType` | When used                                         |
+| ----------- | ---------- | ------------------------------------------------- |
+| MongoDB     | `mongo`    | **Default** if `--dbType` and `DB_TYPE` are unset |
+| File (neDB) | `fs`       | Explicit: `--dbType fs` or `DB_TYPE=fs`           |
+
+Priority: CLI `--dbType` → env `DB_TYPE` → `mongo` (no auto-detection).
+
+Collections / files: `users`, `repos`.
+
+---
+
+## Environment variables
+
+| Variable        | Required | Default                          | Purpose                                            |
+| --------------- | -------- | -------------------------------- | -------------------------------------------------- |
+| `MONGO_URI`     | no       | `mongodb://localhost:27017`      | MongoDB connection string (`dbType=mongo`)         |
+| `DB_NAME`       | no       | `git-proxy`                      | MongoDB database name                              |
+| `DB_TYPE`       | no       | `mongo`                          | Backend: `mongo` or `fs`                           |
+| `USERS_DB_PATH` | no       | `./.data/db/users.db`            | neDB users file (`dbType=fs`), relative to **cwd** |
+| `REPOS_DB_PATH` | no       | `./.data/db/repos.db`            | neDB repos file (`dbType=fs`), relative to **cwd** |
+| `REPORTS_DIR`   | no       | `reports/<YYYY-MM-DD>-migration` | Directory where report files are written           |
+
+CLI overrides (same priority as above for connection): `--mongoUri`, `--dbName`, `--usersDbPath`, `--reposDbPath`.
+
+When `REPORTS_DIR` is set, it is used **as the full output directory** (the dated `reports/<date>-migration` subpath is **not** appended). When unset, reports go under `reports/<today>-migration/` relative to the process working directory.
+
+```bash
+# MongoDB (default)
+export MONGO_URI="mongodb://host:27017"
+export DB_NAME="git-proxy"
+export REPORTS_DIR="/var/git-proxy/migration-run-1"   # optional
+
+# File DB
+export DB_TYPE=fs
+export USERS_DB_PATH="./.data/db/users.db"
+export REPOS_DB_PATH="./.data/db/repos.db"
+```
+
+---
+
+## Report artifacts
+
+Reports are **action-oriented**: YAML/CSV list repos or users that need migration, manual URL fixes, email fixes, or ACL fixes. Repos/users already OK appear only as **counts** in YAML (for example `reposAlreadyFixed`), not as full row lists. This is not a full-database export (use `mongodump` or `backup-users` for users).
+
+### Always written (when the script reaches report generation)
+
+| File                      | Written by                                     |
+| ------------------------- | ---------------------------------------------- |
+| `report-{timestamp}.yaml` | `migrate-urls`, `backup-urls`, `migrate-users` |
+
+### Conditional CSV / JSON (created only if the relevant list is non-empty)
+
+| File                            | Written by                    | Condition                          |
+| ------------------------------- | ----------------------------- | ---------------------------------- |
+| `report-{timestamp}.csv`        | `migrate-urls`, `backup-urls` | `changes.length > 0` (URL pending) |
+| `url-issues-{timestamp}.csv`    | `migrate-urls`, `backup-urls` | `issues.length > 0` (manual URL)   |
+| `users-audit-{timestamp}.csv`   | `migrate-users`               | blocking email `users.issues`      |
+| `acl-orphans-{timestamp}.csv`   | `migrate-users`               | `acl.orphans.length > 0`           |
+| `email-changes-{timestamp}.csv` | `migrate-users` (--apply)     | `apply.changes.length > 0`         |
+| `backup-urls-{timestamp}.json`  | `backup-urls` only            | see backup-urls below              |
+
+### Backup-only extras
+
+| File                            | Written by     | Contents                                                 |
+| ------------------------------- | -------------- | -------------------------------------------------------- |
+| `backup-users-{timestamp}.json` | `backup-users` | **All** users (password field excluded)                  |
+| `users-email-{timestamp}.csv`   | `backup-users` | **All** users as `username,email` template for CSV apply |
+
+`backup-urls` does **not** dump every repo: the JSON array contains only documents that appear in `changes` (missing `.git`) or `issues` (blank / unsupported URL), each with `backupReason` metadata. If nothing needs migration and there are no URL issues, **no** `backup-urls-*.json` is created and the script exits 0.
+
+CSV validation errors from `--apply --csv` are recorded in YAML (`report.csv.errors`); there is no separate `csv-errors-*.csv`.
+
+### YAML contents (summary)
+
+**Phase 1** (`migrate-urls`, `backup-urls`): `totalRepos`, `reposNeedingUpdate`, `reposAlreadyFixed`, `changes[]` (repos to append `.git`), `issues[]` (manual fix), `issueCount`. After `--apply`: may include `reposUpdated`, `errors`, and `changes[].status` (`updated` / `error` / …). `backup-urls` sets `mode: backup-only`.
+
+**Phase 2** (`migrate-users`): nested structure:
+
+- `mode`: `dry-run` or `apply`
+- `users`: audit (`totalUsers`, `counts`, `issues`, `duplicateGroups`, `blockingIssueCount`, …)
+- `acl`: `orphanCount`, `orphans[]` (entries in `repos.users.canPush` / `canAuthorise` with no matching `users.username`)
+- `apply`: present on `--apply` (`ok`, `reason`, `changes`, `conflicts`, …)
+- `csv`: present on `--apply` (`path`, `rowCount`, `errors`)
+
+### Exit codes
+
+| Script          | Exit 0 when                                                                                      | Exit 1 when                    |
+| --------------- | ------------------------------------------------------------------------------------------------ | ------------------------------ |
+| `migrate-urls`  | no apply errors and no URL issues                                                                | URL issues and/or apply errors |
+| `migrate-users` | no blocking email issues, no ACL orphans, apply OK, no post-apply email conflicts, no CSV errors | any of the above fail          |
+| `backup-urls`   | always (including “nothing to backup”)                                                           | fatal error only               |
+| `backup-users`  | success                                                                                          | fatal error only               |
+
+After a successful URL apply, a follow-up dry-run should show `reposNeedingUpdate: 0`, but exit code is still **1** if URL **issues** remain (blank or non-http(s) URLs).
+
+### Read-only issue reports (manual fix in the database)
+
+Some CSV files are **audit output only** — no migration script reads them back as input:
+
+| File                | Meaning                                                                                                          |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `url-issues-*.csv`  | Repos whose `url` is blank or not `http`/`https` — fix in the DB, then re-run `migrate:urls`                     |
+| `acl-orphans-*.csv` | Repo ACL entries whose username does not match any `users.username` — fix in the DB, then re-run `migrate:users` |
+
+Only `migrate-users --apply --csv` consumes a CSV (`username,email` for `users.email`). `email-changes-*.csv` is an apply **log**, not a re-import format.
+
+---
+
+## Phase 1 — Repo URL normalization (append `.git` where missing)
+
+**Goal:** every `repos.url` that v2 will match must include the `.git` suffix where it is missing.
+
+**Why:** v2 resolves repos by **exact** `url` via `getRepoByUrl`; v1 often relied on `name`. Incoming git HTTP traffic is normalized to a URL that includes `.git` (see `parseAction`), while legacy `repos` rows may have been stored without it. Those rows no longer match, so processors such as `checkRepoInAuthorisedList` treat the repo as unauthorized. (The admin UI already requires `.git` when creating new repositories.)
+
+|              | v1.19.2      | v2.0.0                                     |
+| ------------ | ------------ | ------------------------------------------ |
+| Lookup       | `name`       | `url` (exact `$eq`)                        |
+| `.git` in DB | not required | required for parity with incoming requests |
+
+**Scripts:** `migrate-urls.js`, `backup-urls.js`; helpers under `lib/` (`analyze-urls.js`, `reporting.js`, `common.js`, `config.js`).
+
+```bash
+npm run migrate:urls
+npm run backup:urls
+npm run migrate:urls -- --apply
+```
+
+Notes: trailing `/` is normalized (`.../repo/` → `.../repo.git`). Blank/non-http(s) URLs are reported as issues and require **manual** correction in the database; `url-issues-*.csv` is a checklist only (see [Read-only issue reports](#read-only-issue-reports-manual-fix-in-the-database)).
+
+Phase 1 report files: see [Report artifacts](#report-artifacts) (`report-*.yaml`, `report-*.csv`, `url-issues-*.csv`, `backup-urls-*.json`).
+
+---
+
+## Phase 2 — User emails & ACL audit
+
+**Goal:** unblock v2 pushes: valid **unique** `users.email` (audit + CSV apply fallback); surface **ACL orphan** entries that must be corrected **manually** in the database (scripts never rewrite repo ACL).
+
+**migrate-urls vs migrate-users**
+
+|             | `migrate-urls.js`      | `migrate-users.js`              |
+| ----------- | ---------------------- | ------------------------------- |
+| Apply flags | `--apply`              | `--apply` **and** `--csv`       |
+| Writes      | `repos.url` only       | `users.email` from CSV only     |
+| Always      | normalization analysis | email audit + ACL orphan report |
+
+`backup-users.js` is separate (not invoked by `migrate-users`) and writes a **full** users JSON snapshot plus `users-email-*.csv` for all users (see [Report artifacts](#report-artifacts)).
+
+### Recommended order (emails → ACL → verify)
+
+1. **Emails** — run `npm run migrate:users` (dry-run). Resolve every blocking row in `users-audit-*.csv` / YAML `users.issues` (missing/invalid/duplicate email). Where CSV apply is appropriate, run `npm run migrate:users -- --apply --csv ./mappings.csv` and confirm `apply.ok` in the report.
+2. **ACL orphans** — while `acl.orphanCount` (console: `ACL orphans`) is greater than zero, fix each orphan listed in `acl-orphans-*.csv` or YAML `acl.orphans` in the database. Migration tools **do not** update `repos.users.canPush` or `repos.users.canAuthorise`.
+3. **Verify** — run `npm run migrate:users` (dry-run) again after each batch of fixes. Phase 2 is complete only when `blockingIssueCount` is **0**, `orphanCount` is **0**, and the process exits **0** (see [Exit codes](#exit-codes)).
+
+```bash
+npm run migrate:users
+npm run backup:users
+npm run migrate:users -- --apply --csv ./mappings.csv
+# … manual ACL fixes in the database …
+npm run migrate:users   # repeat until ACL orphans: 0 and exit 0
+```
+
+### ACL orphans (manual fix required)
+
+An **orphan** is a username string stored under a repo’s `users.canPush` or `users.canAuthorise` that does not match any document in `users` (match is trimmed, case-insensitive on `username`). These stale or mistyped ACL entries keep `migrate-users` in a failing state until they are removed or aligned with a real user record.
+
+`acl-orphans-{timestamp}.csv` columns: `RepoID`, `RepoName`, `RepoURL`, `Field` (`canPush` / `canAuthorise`), `OrphanUsername`, `NormalizedOrphan`, `Index`. Like `url-issues-*.csv`, this file is **read-only** — it cannot be “loaded back” or applied by any script; use it as a work list, fix data in your environment, then re-run the dry-run (see [Read-only issue reports](#read-only-issue-reports-manual-fix-in-the-database)).
+
+For **apply** (`migrate-users --apply --csv ...`): CSV header must be `username,email` (`lib/csv.js`). The command exits `1` on blocking email issues, ACL orphans, CSV/apply failures, or duplicate-email simulation (see [Exit codes](#exit-codes)).
+
+CSV input: UTF‑8, one row per line, only those two columns; parser is minimal (quoted commas OK, **`""`** escapes inside fields not supported). Prefer export without BOM.
+
+Phase 2 report files (when applicable): `users-audit-*.csv`, `acl-orphans-*.csv`, `email-changes-*.csv`, plus `report-*.yaml` (full nested report).
+
+---
+
+## Pre-upgrade checklist
+
+```bash
+export MONGO_URI="mongodb://host:27017"
+export DB_NAME="git-proxy"
+
+# Phase 1 — repo URL normalization
+npm run migrate:urls
+npm run backup:urls
+npm run migrate:urls -- --apply
+npm run migrate:urls   # expect reposNeedingUpdate: 0; exit 1 if URL issues remain
+
+# Phase 2 — email + ACL (timing vs app upgrade — your runbook)
+npm run migrate:users
+npm run backup:users
+npm run migrate:users -- --apply --csv ./mappings.csv
+# fix ACL orphans manually (acl-orphans-*.csv is not re-importable)
+npm run migrate:users   # repeat until orphanCount: 0 and exit 0
+```
diff --git a/scripts/migrate/backup-urls.js b/scripts/migrate/backup-urls.js
new file mode 100644
index 000000000..84fcf8a01
--- /dev/null
+++ b/scripts/migrate/backup-urls.js
@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Backup: Create backup of repos without .git suffix before migration
+ *
+ * BACKUP ONLY
+ *
+ * Usage:
+ *   npm run backup:urls
+ *   # optional: --dbType mongo|fs (default mongo)
+ */
+
+const config = require('./lib/config');
+const { createDatastoreFromArgv } = require('./lib/datastore');
+const { analyzeReposWithDatastore } = require('./lib/analyze-urls');
+const { generateReports } = require('./lib/reporting');
+const { createBackup } = require('./lib/common');
+
+config.ensureReportsDir();
+
+async function main() {
+  const argv = process.argv.slice(2);
+  let ds;
+
+  try {
+    ds = await createDatastoreFromArgv(argv);
+    const { allRepos, report } = await analyzeReposWithDatastore(ds);
+    const issues = Array.isArray(report.issues) ? report.issues : [];
+
+    if (report.reposNeedingUpdate === 0 && issues.length === 0) {
+      console.log('\n=== BACKUP PHASE ===');
+      console.log('No repos need migration - backup not necessary');
+      process.exit(0);
+    }
+
+    console.log('\n=== BACKUP PHASE ===');
+    const repoById = new Map(allRepos.map((r) => [r._id?.toString?.() ?? String(r._id ?? ''), r]));
+    const backupData = [];
+
+    for (const change of report.changes) {
+      const repo = repoById.get(change.repoId);
+      if (!repo) continue;
+      backupData.push({
+        ...repo,
+        backupReason: 'missing-dot-git',
+        normalizedUrl: change.oldUrl,
+        newUrl: change.newUrl,
+      });
+    }
+
+    for (const issue of issues) {
+      const repo = repoById.get(issue.repoId);
+      if (!repo) continue;
+      backupData.push({
+        ...repo,
+        backupReason: 'url-issue',
+        rawUrl: issue.rawUrl,
+        normalizedUrl: issue.normalizedUrl,
+        issueReason: issue.reason,
+        issueScheme: issue.scheme,
+      });
+    }
+
+    const backupPath = createBackup(config.reportsDir, 'backup-urls', backupData);
+    console.log(`SUCCESS Backup created: ${backupPath}`);
+    console.log(`  (${report.reposNeedingUpdate} repos missing .git, ${issues.length} URL issues)`);
+    console.log('\nBackup completed. Ready to apply migration:');
+    console.log('  node scripts/migrate/migrate-urls.js --apply');
+
+    const timestamp = Date.now();
+    report.mode = 'backup-only';
+    generateReports(config.reportsDir, report, timestamp);
+
+    process.exit(0);
+  } catch (error) {
+    console.error('FATAL ERROR:', error.message);
+    process.exit(1);
+  } finally {
+    if (ds) {
+      await ds.close().catch(() => {});
+    }
+  }
+}
+
+main();
diff --git a/scripts/migrate/backup-users.js b/scripts/migrate/backup-users.js
new file mode 100644
index 000000000..9a6057610
--- /dev/null
+++ b/scripts/migrate/backup-users.js
@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Backup: Create backup of users before email migration
+ *
+ * BACKUP ONLY
+ *
+ * Outputs:
+ * - backup-users-*.json (full users snapshot; passwords excluded)
+ * - users-email-*.csv (username,email template for admin edits + later --apply --csv)
+ *
+ * Usage:
+ *   npm run backup:users
+ *   # or: node scripts/migrate/backup-users.js
+ *   # optional: --dbType mongo|fs (default mongo)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const config = require('./lib/config');
+const { createDatastoreFromArgv } = require('./lib/datastore');
+const { generateReports } = require('./lib/reporting');
+const { createBackup } = require('./lib/common');
+
+config.ensureReportsDir();
+
+function toCsvValue(v) {
+  if (v === null || v === undefined) return '""';
+  const s = String(v).replace(/"/g, '""');
+  return `"${s}"`;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  let ds;
+
+  try {
+    ds = await createDatastoreFromArgv(argv);
+    console.log('\n=== BACKUP USERS PHASE ===');
+    const users = await ds.listUsers();
+    console.log(`Total users in database: ${users.length}`);
+
+    const backupPath = createBackup(config.reportsDir, 'backup-users', users);
+    console.log(`SUCCESS Backup created: ${backupPath}`);
+
+    const timestamp = Date.now();
+
+    const emailCsvPath = path.join(config.reportsDir, `users-email-${timestamp}.csv`);
+    const header = ['username', 'email'].join(',') + '\n';
+    const rows = users
+      .map((u) => [toCsvValue(u.username ?? ''), toCsvValue(u.email ?? '')].join(','))
+      .join('\n');
+    fs.writeFileSync(emailCsvPath, header + rows);
+    console.log(`SUCCESS CSV template: ${emailCsvPath}`);
+
+    const report = { mode: 'backup-users', totalUsers: users.length };
+    generateReports(config.reportsDir, report, timestamp);
+
+    process.exit(0);
+  } catch (error) {
+    console.error('FATAL ERROR:', error.message);
+    process.exit(1);
+  } finally {
+    if (ds) {
+      await ds.close().catch(() => {});
+    }
+  }
+}
+
+main();
diff --git a/scripts/migrate/lib/analyze-acl.js b/scripts/migrate/lib/analyze-acl.js
new file mode 100644
index 000000000..0360d8417
--- /dev/null
+++ b/scripts/migrate/lib/analyze-acl.js
@@ -0,0 +1,81 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+function normalizeUsername(v) {
+  return (v || '').toString().trim().toLowerCase();
+}
+
+function collectAclOrphans(repos, usernameSet) {
+  const orphans = [];
+
+  for (const repo of repos) {
+    const repoId = repo._id?.toString?.() ?? String(repo._id ?? '');
+    const repoName = repo.name ?? '';
+    const repoUrl = repo.url ?? '';
+    const usersObj = repo.users ?? {};
+
+    for (const field of ['canPush', 'canAuthorise']) {
+      const list = Array.isArray(usersObj[field]) ? usersObj[field] : [];
+      for (let i = 0; i < list.length; i++) {
+        const raw = list[i];
+        if (typeof raw !== 'string') continue;
+        const entry = normalizeUsername(raw);
+        if (!entry) continue;
+
+        if (!usernameSet.has(entry)) {
+          orphans.push({
+            repoId,
+            repoName,
+            repoUrl,
+            field,
+            orphanUsername: raw,
+            normalizedOrphan: entry,
+            index: i,
+          });
+        }
+      }
+    }
+  }
+
+  return orphans;
+}
+
+async function analyzeAclWithDatastore(datastore) {
+  console.log('\n=== ACL AUDIT PHASE ===');
+
+  const users = await datastore.listUsers();
+  const usernameSet = new Set(users.map((u) => normalizeUsername(u.username)).filter(Boolean));
+
+  const repos = await datastore.listRepos();
+  const orphans = collectAclOrphans(repos, usernameSet);
+
+  const report = {
+    totalRepos: repos.length,
+    totalUsers: users.length,
+    orphanCount: orphans.length,
+    orphans,
+  };
+
+  console.log(`ACL orphan entries: ${report.orphanCount}`);
+
+  return { report };
+}
+
+module.exports = {
+  analyzeAclWithDatastore,
+  collectAclOrphans,
+  normalizeUsername,
+};
diff --git a/scripts/migrate/lib/analyze-urls.js b/scripts/migrate/lib/analyze-urls.js
new file mode 100644
index 000000000..81293c17f
--- /dev/null
+++ b/scripts/migrate/lib/analyze-urls.js
@@ -0,0 +1,127 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+function detectScheme(url) {
+  const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\//.exec(url);
+  return m ? m[1].toLowerCase() : 'unknown';
+}
+
+function normalizeRepoUrl(raw) {
+  const rawUrl = (raw ?? '').toString().trim();
+  if (!rawUrl) {
+    return { ok: false, rawUrl, normalizedUrl: '', reason: 'blank', scheme: 'unknown' };
+  }
+
+  const normalizedUrl = rawUrl.replace(/\/+$/, '');
+  const scheme = detectScheme(normalizedUrl);
+  const isHttp = normalizedUrl.startsWith('http://') || normalizedUrl.startsWith('https://');
+  if (!isHttp) {
+    return { ok: false, rawUrl, normalizedUrl, reason: 'unsupported-scheme', scheme };
+  }
+
+  return { ok: true, rawUrl, normalizedUrl, scheme: scheme === 'unknown' ? 'http' : scheme };
+}
+
+function buildUrlNormalizationReport(repos) {
+  const report = {
+    totalRepos: repos.length,
+    reposNeedingUpdate: 0,
+    reposAlreadyFixed: 0,
+    changes: [],
+    issues: [],
+    issueCount: 0,
+  };
+
+  for (const repo of repos) {
+    const repoId = repo._id?.toString?.() ?? String(repo._id ?? '');
+    const repoName = repo.name ?? '';
+
+    const norm = normalizeRepoUrl(repo.url);
+    if (!norm.ok) {
+      report.issues.push({
+        repoId,
+        repoName,
+        rawUrl: norm.rawUrl,
+        normalizedUrl: norm.normalizedUrl,
+        reason: norm.reason,
+        scheme: norm.scheme,
+      });
+      report.issueCount++;
+      continue;
+    }
+
+    const currentUrl = norm.normalizedUrl;
+    const needsUpdate = !currentUrl.endsWith('.git');
+
+    if (needsUpdate) {
+      report.reposNeedingUpdate++;
+      const newUrl = `${currentUrl}.git`;
+      report.changes.push({
+        repoId,
+        repoName,
+        oldUrl: currentUrl,
+        newUrl: newUrl,
+        status: 'pending',
+      });
+    } else {
+      report.reposAlreadyFixed++;
+    }
+  }
+
+  return report;
+}
+
+function logUrlAnalysis(allRepos, report) {
+  for (const repo of allRepos) {
+    const repoName = repo.name ?? '';
+    const norm = normalizeRepoUrl(repo.url);
+    if (!norm.ok) {
+      console.log(
+        `  WARNING ${repoName}: invalid url "${norm.rawUrl}" (reason: ${norm.reason}, scheme: ${norm.scheme})`,
+      );
+      continue;
+    }
+
+    const currentUrl = norm.normalizedUrl;
+    if (!currentUrl.endsWith('.git')) {
+      const newUrl = `${currentUrl}.git`;
+      console.log(`  INFO ${repoName}: ${currentUrl} -> ${newUrl}`);
+    } else {
+      console.log(`  OK ${repoName}: already has .git`);
+    }
+  }
+
+  console.log(`\nRepos needing update: ${report.reposNeedingUpdate}`);
+  console.log(`Repos already fixed: ${report.reposAlreadyFixed}`);
+  console.log(`URL issues (manual fix): ${report.issueCount}`);
+}
+
+async function analyzeReposWithDatastore(datastore) {
+  console.log('\n=== ANALYSIS PHASE ===');
+  const allRepos = await datastore.listRepos();
+
+  console.log(`Total repos in database: ${allRepos.length}`);
+  const report = buildUrlNormalizationReport(allRepos);
+  logUrlAnalysis(allRepos, report);
+
+  return { allRepos, report };
+}
+
+module.exports = {
+  analyzeReposWithDatastore,
+  buildUrlNormalizationReport,
+  normalizeRepoUrl,
+};
diff --git a/scripts/migrate/lib/analyze-users.js b/scripts/migrate/lib/analyze-users.js
new file mode 100644
index 000000000..5bc8c670d
--- /dev/null
+++ b/scripts/migrate/lib/analyze-users.js
@@ -0,0 +1,116 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const { normalizeEmail, isEmailFormatValid } = require('./email');
+
+function buildUsersEmailReport(users) {
+  const byEmail = new Map(); // normalizedEmail -> [{...userInfo}]
+  const issues = [];
+
+  for (const user of users) {
+    const hasEmailField = Object.prototype.hasOwnProperty.call(user, 'email');
+    const rawEmail = hasEmailField ? user.email : undefined;
+    const email = normalizeEmail(rawEmail);
+
+    let status = 'ok';
+    if (!hasEmailField) status = 'missing';
+    else if (!email) status = 'blank';
+    else if (!isEmailFormatValid(email)) status = 'invalid-format';
+
+    const info = {
+      userId: user._id?.toString?.() ?? String(user._id ?? ''),
+      username: user.username,
+      gitAccount: user.gitAccount,
+      oidcId: user.oidcId ?? null,
+      email: rawEmail,
+      normalizedEmail: email,
+      status,
+    };
+
+    if (email) {
+      const list = byEmail.get(email) ?? [];
+      list.push(info);
+      byEmail.set(email, list);
+    }
+
+    if (status !== 'ok') {
+      issues.push(info);
+    }
+  }
+
+  const duplicateGroups = [];
+  for (const [email, list] of byEmail.entries()) {
+    if (list.length > 1) {
+      duplicateGroups.push({ normalizedEmail: email, users: list });
+    }
+  }
+
+  // mark all users that are part of duplicates
+  if (duplicateGroups.length > 0) {
+    const duplicatedUserIds = new Set();
+    for (const group of duplicateGroups) {
+      for (const u of group.users) duplicatedUserIds.add(u.userId);
+    }
+    for (const item of issues) {
+      if (duplicatedUserIds.has(item.userId)) item.status = 'duplicate';
+    }
+    // also add duplicate-only users that were previously ok
+    for (const group of duplicateGroups) {
+      for (const u of group.users) {
+        if (u.status === 'ok') {
+          issues.push({ ...u, status: 'duplicate' });
+        }
+      }
+    }
+  }
+
+  const counts = {
+    total: users.length,
+    missing: issues.filter((x) => x.status === 'missing').length,
+    blank: issues.filter((x) => x.status === 'blank').length,
+    duplicate: issues.filter((x) => x.status === 'duplicate').length,
+    invalidFormat: issues.filter((x) => x.status === 'invalid-format').length,
+  };
+
+  const report = {
+    totalUsers: users.length,
+    counts,
+    duplicateGroups,
+    issues,
+    blockingIssueCount: counts.missing + counts.blank + counts.duplicate + counts.invalidFormat,
+  };
+
+  return { report };
+}
+
+async function analyzeUsersWithDatastore(datastore) {
+  console.log('\n=== USERS EMAIL AUDIT PHASE ===');
+  const users = await datastore.listUsers();
+  console.log(`Total users in database: ${users.length}`);
+
+  const { report } = buildUsersEmailReport(users);
+
+  console.log(`Users with blocking issues: ${report.blockingIssueCount}`);
+
+  return { users, report };
+}
+
+module.exports = {
+  analyzeUsersWithDatastore,
+  buildUsersEmailReport,
+  normalizeEmail,
+  isEmailFormatValid,
+};
diff --git a/scripts/migrate/lib/apply-user-emails.js b/scripts/migrate/lib/apply-user-emails.js
new file mode 100644
index 000000000..1ca541219
--- /dev/null
+++ b/scripts/migrate/lib/apply-user-emails.js
@@ -0,0 +1,149 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const { normalizeEmail } = require('./email');
+const { normalizeUsername } = require('./csv');
+
+function simulatePostApplyUniqueness(users, usernameToEmail) {
+  const projected = new Map(); // userId -> normalizedEmail
+
+  for (const u of users) {
+    const id = u._id?.toString?.() ?? String(u._id ?? '');
+    const username = normalizeUsername(u.username);
+    const currentEmail = normalizeEmail(u.email);
+    const nextEmail = normalizeEmail(usernameToEmail.get(username) ?? currentEmail);
+    projected.set(id, nextEmail);
+  }
+
+  const byEmail = new Map(); // email -> [userId]
+  for (const [userId, email] of projected.entries()) {
+    if (!email) continue;
+    const list = byEmail.get(email) ?? [];
+    list.push(userId);
+    byEmail.set(email, list);
+  }
+
+  const conflicts = [];
+  for (const [email, ids] of byEmail.entries()) {
+    if (ids.length > 1) conflicts.push({ normalizedEmail: email, userIds: ids });
+  }
+
+  return { conflicts, projected };
+}
+
+async function applyUserEmailsWithDatastore(datastore, usernameToEmail, options = {}) {
+  const { dryRun = false } = options;
+
+  const users = await datastore.listUsers();
+
+  const { conflicts } = simulatePostApplyUniqueness(users, usernameToEmail);
+  if (conflicts.length > 0) {
+    return {
+      ok: false,
+      reason: 'post-apply-duplicate',
+      conflicts,
+      changes: [],
+    };
+  }
+
+  const changes = [];
+  let updated = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  const userByUsername = new Map();
+  for (const u of users) {
+    userByUsername.set(normalizeUsername(u.username), u);
+  }
+
+  for (const [username, newEmail] of usernameToEmail.entries()) {
+    const user = userByUsername.get(username);
+    if (!user) {
+      changes.push({ username, status: 'skipped', reason: 'user-not-found' });
+      skipped++;
+      continue;
+    }
+
+    const oldEmail = normalizeEmail(user.email);
+    const nextEmail = normalizeEmail(newEmail);
+    if (oldEmail === nextEmail) {
+      changes.push({
+        username,
+        oldEmail,
+        newEmail: nextEmail,
+        status: 'skipped',
+        reason: 'already-correct',
+      });
+      skipped++;
+      continue;
+    }
+
+    if (dryRun) {
+      changes.push({ username, oldEmail, newEmail: nextEmail, status: 'planned' });
+      continue;
+    }
+
+    try {
+      const res = await datastore.updateUserEmailByUsername(username, nextEmail);
+      if (res.ok && res.modified) {
+        changes.push({ username, oldEmail, newEmail: nextEmail, status: 'updated' });
+        updated++;
+      } else if (res.ok && !res.modified) {
+        changes.push({
+          username,
+          oldEmail,
+          newEmail: nextEmail,
+          status: 'skipped',
+          reason: 'no-change',
+        });
+        skipped++;
+      } else {
+        changes.push({
+          username,
+          oldEmail,
+          newEmail: nextEmail,
+          status: 'skipped',
+          reason: res.reason ?? 'user-not-found',
+        });
+        skipped++;
+      }
+    } catch (e) {
+      changes.push({
+        username,
+        oldEmail,
+        newEmail: nextEmail,
+        status: 'error',
+        error: e?.message ?? String(e),
+      });
+      errors++;
+    }
+  }
+
+  return {
+    ok: errors === 0,
+    reason: errors === 0 ? 'applied' : 'errors',
+    updated,
+    skipped,
+    errors,
+    changes,
+    conflicts: [],
+  };
+}
+
+module.exports = {
+  applyUserEmailsWithDatastore,
+  simulatePostApplyUniqueness,
+};
diff --git a/scripts/migrate/lib/args.js b/scripts/migrate/lib/args.js
new file mode 100644
index 000000000..5499ae1c4
--- /dev/null
+++ b/scripts/migrate/lib/args.js
@@ -0,0 +1,76 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const VALID_DB_TYPES = new Set(['mongo', 'fs']);
+
+function getArgValue(flag, argv) {
+  const idx = argv.indexOf(flag);
+  if (idx === -1) return null;
+  return argv[idx + 1] ?? null;
+}
+
+function normalizeDbType(value, sourceLabel) {
+  const v = (value || '').toString().trim().toLowerCase();
+  if (!VALID_DB_TYPES.has(v)) {
+    throw new Error(`Invalid ${sourceLabel}: "${value}". Use mongo or fs.`);
+  }
+  return v;
+}
+
+/**
+ * Resolve database backend. Priority: --dbType → DB_TYPE env → mongo (default).
+ * @param {string[]} [argv]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {'mongo'|'fs'}
+ */
+function getDbType(argv = [], env = {}) {
+  const fromCli = getArgValue('--dbType', argv);
+  if (fromCli) {
+    return normalizeDbType(fromCli, '--dbType');
+  }
+
+  const fromEnv = (env.DB_TYPE || '').trim();
+  if (fromEnv) {
+    return normalizeDbType(fromEnv, 'DB_TYPE');
+  }
+
+  return 'mongo';
+}
+
+/**
+ * @param {string[]} [argv]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {{ mongoUri?: string, dbName?: string, usersDbPath?: string, reposDbPath?: string }} [defaults]
+ */
+function parseMigrationArgs(argv = [], env = {}, defaults = {}) {
+  const dbType = getDbType(argv, env);
+
+  return {
+    dbType,
+    mongoUri: getArgValue('--mongoUri', argv) ?? env.MONGO_URI ?? defaults.mongoUri ?? null,
+    dbName: getArgValue('--dbName', argv) ?? env.DB_NAME ?? defaults.dbName ?? null,
+    usersDbPath:
+      getArgValue('--usersDbPath', argv) ?? env.USERS_DB_PATH ?? defaults.usersDbPath ?? null,
+    reposDbPath:
+      getArgValue('--reposDbPath', argv) ?? env.REPOS_DB_PATH ?? defaults.reposDbPath ?? null,
+  };
+}
+
+module.exports = {
+  getArgValue,
+  getDbType,
+  parseMigrationArgs,
+};
diff --git a/scripts/migrate/lib/common.js b/scripts/migrate/lib/common.js
new file mode 100644
index 000000000..661b82714
--- /dev/null
+++ b/scripts/migrate/lib/common.js
@@ -0,0 +1,29 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+function createBackup(reportsDir, backupFilePrefix, data) {
+  const fs = require('fs');
+  const path = require('path');
+
+  const backupPath = path.join(reportsDir, `${backupFilePrefix}-${Date.now()}.json`);
+  fs.writeFileSync(backupPath, JSON.stringify(data, null, 2));
+
+  return backupPath;
+}
+
+module.exports = {
+  createBackup,
+};
diff --git a/scripts/migrate/lib/config.js b/scripts/migrate/lib/config.js
new file mode 100644
index 000000000..f472a6359
--- /dev/null
+++ b/scripts/migrate/lib/config.js
@@ -0,0 +1,31 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const path = require('path');
+
+const today = new Date().toISOString().split('T')[0];
+
+module.exports = {
+  mongoUri: process.env.MONGO_URI || 'mongodb://localhost:27017',
+  dbName: process.env.DB_NAME || 'git-proxy',
+  reportsDir: process.env.REPORTS_DIR || path.join(process.cwd(), 'reports', `${today}-migration`),
+  ensureReportsDir: function () {
+    const fs = require('fs');
+    if (!fs.existsSync(this.reportsDir)) {
+      fs.mkdirSync(this.reportsDir, { recursive: true });
+    }
+  },
+};
diff --git a/scripts/migrate/lib/csv.js b/scripts/migrate/lib/csv.js
new file mode 100644
index 000000000..23b000cd6
--- /dev/null
+++ b/scripts/migrate/lib/csv.js
@@ -0,0 +1,126 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const fs = require('fs');
+const { normalizeEmail, isEmailFormatValid } = require('./email');
+
+function parseCsvLine(line) {
+  // Minimal CSV parsing: supports quoted fields with commas, no escaped quotes.
+  // Good enough for username,email mapping.
+  const out = [];
+  let cur = '';
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (ch === ',' && !inQuotes) {
+      out.push(cur);
+      cur = '';
+      continue;
+    }
+    cur += ch;
+  }
+  out.push(cur);
+  return out.map((x) => x.trim());
+}
+
+function normalizeUsername(username) {
+  return (username || '').trim().toLowerCase();
+}
+
+function readUsernameEmailCsv(csvPath) {
+  const raw = fs.readFileSync(csvPath, 'utf8');
+  const lines = raw
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+
+  if (lines.length === 0) {
+    throw new Error('CSV is empty');
+  }
+
+  const header = parseCsvLine(lines[0]).map((h) => h.toLowerCase());
+  const uIdx = header.indexOf('username');
+  const eIdx = header.indexOf('email');
+  if (uIdx === -1 || eIdx === -1) {
+    throw new Error('CSV header must include: username,email');
+  }
+
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const cols = parseCsvLine(lines[i]);
+    const username = cols[uIdx] ?? '';
+    const email = cols[eIdx] ?? '';
+    rows.push({
+      line: i + 1,
+      usernameRaw: username,
+      emailRaw: email,
+      username: normalizeUsername(username),
+      email: normalizeEmail(email),
+    });
+  }
+
+  const errors = [];
+  const mapping = new Map(); // username -> email
+  for (const row of rows) {
+    if (!row.username) {
+      errors.push({ line: row.line, code: 'missing-username', message: 'Username is blank' });
+      continue;
+    }
+    if (!row.email) {
+      errors.push({
+        line: row.line,
+        code: 'missing-email',
+        message: 'Email is blank',
+        username: row.username,
+      });
+      continue;
+    }
+    if (!isEmailFormatValid(row.email)) {
+      errors.push({
+        line: row.line,
+        code: 'invalid-email-format',
+        message: 'Email does not match basic format',
+        username: row.username,
+        email: row.email,
+      });
+      continue;
+    }
+    if (mapping.has(row.username) && mapping.get(row.username) !== row.email) {
+      errors.push({
+        line: row.line,
+        code: 'duplicate-username',
+        message: 'Username appears multiple times with different emails',
+        username: row.username,
+        email: row.email,
+      });
+      continue;
+    }
+    mapping.set(row.username, row.email);
+  }
+
+  return { rows, mapping, errors };
+}
+
+module.exports = {
+  readUsernameEmailCsv,
+  normalizeUsername,
+  normalizeEmail,
+  isEmailFormatValid,
+};
diff --git a/scripts/migrate/lib/datastore.js b/scripts/migrate/lib/datastore.js
new file mode 100644
index 000000000..73d83cd71
--- /dev/null
+++ b/scripts/migrate/lib/datastore.js
@@ -0,0 +1,243 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { MongoClient, ObjectId } = require('mongodb');
+const Datastore = require('@seald-io/nedb');
+
+const { parseMigrationArgs } = require('./args');
+const { normalizeEmail } = require('./email');
+const { normalizeUsername } = require('./csv');
+const baseConfig = require('./config');
+
+const DEFAULT_USERS_DB_PATH = './.data/db/users.db';
+const DEFAULT_REPOS_DB_PATH = './.data/db/repos.db';
+
+function omitPassword(user) {
+  const { password, ...rest } = user;
+  return rest;
+}
+
+function nedbFind(db, query = {}) {
+  return new Promise((resolve, reject) => {
+    db.find(query, (err, docs) => {
+      if (err) reject(err);
+      else resolve(docs);
+    });
+  });
+}
+
+function nedbFindOne(db, query) {
+  return new Promise((resolve, reject) => {
+    db.findOne(query, (err, doc) => {
+      if (err) reject(err);
+      else resolve(doc ?? null);
+    });
+  });
+}
+
+function nedbUpdate(db, query, update, options = { multi: false, upsert: false }) {
+  return new Promise((resolve, reject) => {
+    db.update(query, update, options, (err, numReplaced) => {
+      if (err) reject(err);
+      else resolve(numReplaced);
+    });
+  });
+}
+
+function ensureParentDir(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+async function createMongoDatastore({ mongoUri, dbName }) {
+  if (!mongoUri) {
+    throw new Error('mongoUri is required for mongo datastore');
+  }
+  if (!dbName) {
+    throw new Error('dbName is required for mongo datastore');
+  }
+
+  const client = new MongoClient(mongoUri);
+  await client.connect();
+  const db = client.db(dbName);
+  const usersCollection = db.collection('users');
+  const reposCollection = db.collection('repos');
+
+  return {
+    dbType: 'mongo',
+    async listUsers() {
+      return usersCollection.find({}).project({ password: 0 }).toArray();
+    },
+    async listRepos() {
+      return reposCollection.find({}).toArray();
+    },
+    async updateUserEmailByUsername(username, email) {
+      const key = normalizeUsername(username);
+      const nextEmail = normalizeEmail(email);
+      const user = await usersCollection.findOne({ username: key });
+      if (!user) {
+        return { ok: false, reason: 'user-not-found' };
+      }
+      const id = user._id?.toString?.() ?? String(user._id ?? '');
+      const res = await usersCollection.updateOne(
+        { _id: new ObjectId(id) },
+        { $set: { email: nextEmail } },
+      );
+      return { ok: true, modified: res.modifiedCount === 1 };
+    },
+    async updateRepoUrlById(repoId, newUrl) {
+      const res = await reposCollection.updateOne(
+        { _id: new ObjectId(repoId) },
+        { $set: { url: newUrl } },
+      );
+      return res.modifiedCount === 1;
+    },
+    async countReposWithoutGitSuffix() {
+      return reposCollection.countDocuments({
+        url: { $not: /\.git$/ },
+      });
+    },
+    async close() {
+      await client.close().catch(() => {});
+    },
+  };
+}
+
+async function createFsDatastore({ usersDbPath, reposDbPath }) {
+  const usersPath = path.resolve(process.cwd(), usersDbPath || DEFAULT_USERS_DB_PATH);
+  const reposPath = path.resolve(process.cwd(), reposDbPath || DEFAULT_REPOS_DB_PATH);
+
+  ensureParentDir(usersPath);
+  ensureParentDir(reposPath);
+
+  const usersDb = new Datastore({ filename: usersPath, autoload: true });
+  const reposDb = new Datastore({ filename: reposPath, autoload: true });
+
+  await Promise.all([
+    new Promise((resolve, reject) => {
+      usersDb.ensureIndex({ fieldName: 'username', unique: true }, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    }),
+    new Promise((resolve, reject) => {
+      reposDb.ensureIndex({ fieldName: 'url', unique: true }, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    }),
+  ]);
+
+  return {
+    dbType: 'fs',
+    async listUsers() {
+      const docs = await nedbFind(usersDb, {});
+      return docs.map(omitPassword);
+    },
+    async listRepos() {
+      return nedbFind(reposDb, {});
+    },
+    async updateUserEmailByUsername(username, email) {
+      const key = normalizeUsername(username);
+      const nextEmail = normalizeEmail(email);
+      const existing = await nedbFindOne(usersDb, { username: key });
+      if (!existing) {
+        return { ok: false, reason: 'user-not-found' };
+      }
+      const merged = { ...existing, email: nextEmail };
+      const numReplaced = await nedbUpdate(usersDb, { username: key }, merged, {
+        multi: false,
+        upsert: false,
+      });
+      return { ok: true, modified: numReplaced >= 1 };
+    },
+    async updateRepoUrlById(repoId, newUrl) {
+      const existing = await nedbFindOne(reposDb, { _id: repoId });
+      if (!existing) {
+        return false;
+      }
+      const merged = { ...existing, url: newUrl };
+      const numReplaced = await nedbUpdate(reposDb, { _id: repoId }, merged, {
+        multi: false,
+        upsert: false,
+      });
+      return numReplaced >= 1;
+    },
+    async countReposWithoutGitSuffix() {
+      const repos = await nedbFind(reposDb, {});
+      return repos.filter((r) => {
+        const url = (r.url ?? '').toString().replace(/\/+$/, '');
+        return url && !url.endsWith('.git');
+      }).length;
+    },
+    async close() {
+      // neDB file handles are managed per process; no explicit close required
+    },
+  };
+}
+
+/**
+ * Create a migration datastore for the given options.
+ * Caller must call `close()` when finished (use try/finally in scripts).
+ *
+ * @param {{ dbType: string, mongoUri?: string|null, dbName?: string|null, usersDbPath?: string|null, reposDbPath?: string|null }} options
+ */
+async function createDatastore(options) {
+  if (options.dbType === 'fs') {
+    return createFsDatastore({
+      usersDbPath: options.usersDbPath,
+      reposDbPath: options.reposDbPath,
+    });
+  }
+
+  if (options.dbType === 'mongo') {
+    return createMongoDatastore({
+      mongoUri: options.mongoUri,
+      dbName: options.dbName,
+    });
+  }
+
+  throw new Error(`Unsupported dbType: ${options.dbType}`);
+}
+
+/**
+ * Parse CLI/env and create a datastore (convenience for entrypoint scripts).
+ *
+ * @param {string[]} [argv]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {object} [defaults]
+ */
+async function createDatastoreFromArgv(
+  argv = process.argv.slice(2),
+  env = process.env,
+  defaults = {},
+) {
+  const parsed = parseMigrationArgs(argv, env, {
+    mongoUri: baseConfig.mongoUri,
+    dbName: baseConfig.dbName,
+    ...defaults,
+  });
+  return createDatastore(parsed);
+}
+
+module.exports = {
+  createDatastore,
+  createDatastoreFromArgv,
+};
diff --git a/scripts/migrate/lib/email.js b/scripts/migrate/lib/email.js
new file mode 100644
index 000000000..3a3c0ed1e
--- /dev/null
+++ b/scripts/migrate/lib/email.js
@@ -0,0 +1,30 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+function normalizeEmail(email) {
+  return (email || '').trim().toLowerCase();
+}
+
+function isEmailFormatValid(email) {
+  const v = normalizeEmail(email);
+  // Basic sanity check only (not RFC exhaustive)
+  return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v);
+}
+
+module.exports = {
+  normalizeEmail,
+  isEmailFormatValid,
+};
diff --git a/scripts/migrate/lib/reporting.js b/scripts/migrate/lib/reporting.js
new file mode 100644
index 000000000..e3832d4f5
--- /dev/null
+++ b/scripts/migrate/lib/reporting.js
@@ -0,0 +1,126 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+function toCsvValue(v) {
+  if (v === null || v === undefined) return '""';
+  const s = String(v).replace(/"/g, '""');
+  return `"${s}"`;
+}
+
+function writeCsv(filePath, headerCols, rows) {
+  const header = headerCols.join(',') + '\n';
+  const body = rows.map((r) => r.map(toCsvValue).join(',')).join('\n');
+  fs.writeFileSync(filePath, header + body);
+}
+
+function generateReports(reportsDir, report, timestamp) {
+  console.log('\n=== REPORT GENERATION ===');
+
+  const yamlPath = path.join(reportsDir, `report-${timestamp}.yaml`);
+  fs.writeFileSync(yamlPath, yaml.dump(report, { indent: 2 }));
+  console.log(`SUCCESS YAML report: ${yamlPath}`);
+
+  // URL migration CSV (backward compatible)
+  if (report.changes && report.changes.length > 0) {
+    const csvPath = path.join(reportsDir, `report-${timestamp}.csv`);
+    writeCsv(
+      csvPath,
+      ['RepoID', 'RepoName', 'OldURL', 'NewURL', 'Status'],
+      report.changes.map((c) => [c.repoId, c.repoName, c.oldUrl, c.newUrl, c.status]),
+    );
+    console.log(`SUCCESS CSV report: ${csvPath}`);
+  }
+
+  // URL issues CSV (manual fix required)
+  if (report.issues && Array.isArray(report.issues) && report.issues.length > 0) {
+    const csvPath = path.join(reportsDir, `url-issues-${timestamp}.csv`);
+    writeCsv(
+      csvPath,
+      ['RepoID', 'RepoName', 'RawURL', 'NormalizedURL', 'Reason', 'Scheme'],
+      report.issues.map((i) => [
+        i.repoId,
+        i.repoName,
+        i.rawUrl ?? '',
+        i.normalizedUrl ?? '',
+        i.reason ?? '',
+        i.scheme ?? '',
+      ]),
+    );
+    console.log(`SUCCESS CSV report: ${csvPath}`);
+  }
+
+  // Users email audit CSV
+  if (report.users && Array.isArray(report.users.issues) && report.users.issues.length > 0) {
+    const csvPath = path.join(reportsDir, `users-audit-${timestamp}.csv`);
+    writeCsv(
+      csvPath,
+      ['UserID', 'Username', 'Status', 'Email', 'GitAccount', 'OIDCId', 'NormalizedEmail'],
+      report.users.issues.map((u) => [
+        u.userId,
+        u.username,
+        u.status,
+        u.email,
+        u.gitAccount,
+        u.oidcId,
+        u.normalizedEmail,
+      ]),
+    );
+    console.log(`SUCCESS CSV report: ${csvPath}`);
+  }
+
+  // ACL orphans CSV
+  if (report.acl && Array.isArray(report.acl.orphans) && report.acl.orphans.length > 0) {
+    const csvPath = path.join(reportsDir, `acl-orphans-${timestamp}.csv`);
+    writeCsv(
+      csvPath,
+      ['RepoID', 'RepoName', 'RepoURL', 'Field', 'OrphanUsername', 'NormalizedOrphan', 'Index'],
+      report.acl.orphans.map((o) => [
+        o.repoId,
+        o.repoName,
+        o.repoUrl,
+        o.field,
+        o.orphanUsername,
+        o.normalizedOrphan,
+        o.index,
+      ]),
+    );
+    console.log(`SUCCESS CSV report: ${csvPath}`);
+  }
+
+  // Email changes CSV (apply)
+  if (report.apply && Array.isArray(report.apply.changes) && report.apply.changes.length > 0) {
+    const csvPath = path.join(reportsDir, `email-changes-${timestamp}.csv`);
+    writeCsv(
+      csvPath,
+      ['Username', 'OldEmail', 'NewEmail', 'Status', 'Reason', 'Error'],
+      report.apply.changes.map((c) => [
+        c.username,
+        c.oldEmail ?? '',
+        c.newEmail ?? '',
+        c.status,
+        c.reason ?? '',
+        c.error ?? '',
+      ]),
+    );
+    console.log(`SUCCESS CSV report: ${csvPath}`);
+  }
+}
+
+module.exports = { generateReports };
diff --git a/scripts/migrate/migrate-urls.js b/scripts/migrate/migrate-urls.js
new file mode 100644
index 000000000..23dc7c221
--- /dev/null
+++ b/scripts/migrate/migrate-urls.js
@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Migration: Repo URL normalization — append .git to repos.url where missing
+ *
+ * DRY RUN (default):
+ *   npm run migrate:urls
+ *
+ * APPLY:
+ *   npm run migrate:urls -- --apply
+ *
+ * Optional: --dbType mongo|fs (default mongo), DB_TYPE env
+ */
+
+const config = require('./lib/config');
+const { createDatastoreFromArgv } = require('./lib/datastore');
+const { analyzeReposWithDatastore } = require('./lib/analyze-urls');
+const { generateReports } = require('./lib/reporting');
+
+const argv = process.argv.slice(2);
+
+const args = {
+  apply: argv.includes('--apply'),
+};
+
+config.ensureReportsDir();
+
+async function main() {
+  let ds;
+
+  try {
+    ds = await createDatastoreFromArgv(argv);
+    const { report } = await analyzeReposWithDatastore(ds);
+    const urlIssues =
+      report.issueCount ?? (Array.isArray(report.issues) ? report.issues.length : 0);
+
+    if (!args.apply) {
+      console.log('\n=== DRY RUN MODE (default) ===');
+      console.log('No changes applied.');
+      if (report.reposNeedingUpdate > 0) {
+        console.log(`\nNext steps:`);
+        console.log(`  1. Create backup (recommended):`);
+        console.log(`     node scripts/migrate/backup-urls.js`);
+        console.log(`  2. Apply changes:`);
+        console.log(`     node scripts/migrate/migrate-urls.js --apply`);
+      }
+      if (urlIssues > 0) {
+        console.log(`\nWARNING URL issues detected (manual fix required): ${urlIssues}`);
+      }
+    } else {
+      console.log('\n=== APPLY PHASE ===');
+      let reposUpdated = 0;
+      let errors = 0;
+
+      for (const change of report.changes) {
+        try {
+          const success = await ds.updateRepoUrlById(change.repoId, change.newUrl);
+
+          if (success) {
+            change.status = 'updated';
+            reposUpdated++;
+            console.log(`  SUCCESS Updated ${change.repoName}`);
+          } else {
+            change.status = 'no-change';
+            console.log(`  WARNING No change for ${change.repoName}`);
+          }
+        } catch (error) {
+          change.status = 'error';
+          change.error = error.message;
+          errors++;
+          console.error(`  ERROR updating ${change.repoName}: ${error.message}`);
+        }
+      }
+
+      console.log(`\nRepos updated: ${reposUpdated}`);
+      console.log(`Errors: ${errors}`);
+
+      console.log('\n=== VERIFICATION PHASE ===');
+      const remaining = await ds.countReposWithoutGitSuffix();
+      console.log(`Repos still without .git: ${remaining}`);
+
+      if (remaining === 0) {
+        console.log('SUCCESS Migration verified: all repos now have .git');
+      } else {
+        console.warn(
+          `WARNING ${remaining} repo(s) still have url not ending with .git (includes blank/invalid URLs in issues — see URL issues above)`,
+        );
+      }
+
+      report.reposUpdated = reposUpdated;
+      report.errors = errors;
+    }
+
+    const timestamp = Date.now();
+    generateReports(config.reportsDir, report, timestamp);
+
+    console.log('\n=== SUMMARY ===');
+    console.log(`Mode: ${args.apply ? 'APPLY' : 'DRY RUN'}`);
+    console.log(`Total repos: ${report.totalRepos}`);
+    console.log(`Needing update: ${report.reposNeedingUpdate}`);
+    console.log(`URL issues: ${urlIssues}`);
+    console.log(`Updated: ${report.reposUpdated || 0}`);
+    console.log(`Errors: ${report.errors || 0}`);
+
+    const shouldFail = (report.errors || 0) > 0 || urlIssues > 0;
+    process.exit(shouldFail ? 1 : 0);
+  } catch (error) {
+    console.error('FATAL ERROR:', error.message);
+    process.exit(1);
+  } finally {
+    if (ds) {
+      await ds.close().catch(() => {});
+    }
+  }
+}
+
+main();
diff --git a/scripts/migrate/migrate-users.js b/scripts/migrate/migrate-users.js
new file mode 100644
index 000000000..97501484c
--- /dev/null
+++ b/scripts/migrate/migrate-users.js
@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Migration: Audit and (optionally) fix users.email for v2.0.0 compatibility
+ *
+ * DRY RUN (default):
+ *   npm run migrate:users
+ *   # or: node scripts/migrate/migrate-users.js
+ *
+ * APPLY (requires CSV mapping username,email):
+ *   npm run migrate:users -- --apply --csv ./mappings.csv
+ *
+ * Optional: --dbType mongo|fs (default mongo), DB_TYPE env
+ */
+
+const path = require('path');
+
+const config = require('./lib/config');
+const { generateReports } = require('./lib/reporting');
+const { getArgValue } = require('./lib/args');
+const { createDatastoreFromArgv } = require('./lib/datastore');
+const { analyzeUsersWithDatastore } = require('./lib/analyze-users');
+const { analyzeAclWithDatastore } = require('./lib/analyze-acl');
+const { readUsernameEmailCsv } = require('./lib/csv');
+const { applyUserEmailsWithDatastore } = require('./lib/apply-user-emails');
+
+const argv = process.argv.slice(2);
+
+const args = {
+  apply: argv.includes('--apply'),
+  csvPath: getArgValue('--csv', argv),
+};
+
+config.ensureReportsDir();
+
+function printDryRunNextSteps() {
+  console.log('\n=== DRY RUN MODE (default) ===');
+  console.log('No changes applied.');
+  console.log('\nNext steps:');
+  console.log('  1. Create users backup (recommended):');
+  console.log('     node scripts/migrate/backup-users.js');
+  console.log('  2. Prepare CSV mapping: username,email');
+  console.log('  3. Apply changes:');
+  console.log('     node scripts/migrate/migrate-users.js --apply --csv mappings.csv');
+}
+
+function buildUsersMigrationReport({ mode, usersReport, aclReport, csv, apply }) {
+  return {
+    mode,
+    users: usersReport,
+    acl: aclReport,
+    apply: apply ?? null,
+    csv: csv ?? null,
+  };
+}
+
+async function runEmailApplyFromCsv(datastore, csvPath) {
+  const absCsvPath = path.isAbsolute(csvPath) ? csvPath : path.join(process.cwd(), csvPath);
+  const { mapping, errors, rows } = readUsernameEmailCsv(absCsvPath);
+  const csv = { path: absCsvPath, rowCount: rows.length, errors };
+
+  if (errors.length > 0) {
+    console.error(`CSV validation errors: ${errors.length}`);
+    return {
+      csv,
+      apply: { ok: false, reason: 'csv-errors', changes: [] },
+    };
+  }
+
+  const apply = await applyUserEmailsWithDatastore(datastore, mapping, {
+    dryRun: false,
+  });
+  return { csv, apply };
+}
+
+function computeExitCode(report) {
+  const blockingUsers = report.users?.blockingIssueCount ?? 0;
+  const aclOrphans = report.acl?.orphanCount ?? 0;
+  const applyOk = report.apply ? report.apply.ok : true;
+  const applyConflicts =
+    report.apply && Array.isArray(report.apply.conflicts) ? report.apply.conflicts.length : 0;
+  const csvErrors = report.csv && Array.isArray(report.csv.errors) ? report.csv.errors.length : 0;
+
+  const shouldFail =
+    blockingUsers > 0 || aclOrphans > 0 || !applyOk || applyConflicts > 0 || csvErrors > 0;
+
+  return shouldFail ? 1 : 0;
+}
+
+function printMigrationSummary(report, applyMode) {
+  const blockingUsers = report.users?.blockingIssueCount ?? 0;
+  const aclOrphans = report.acl?.orphanCount ?? 0;
+  const applyOk = report.apply ? report.apply.ok : true;
+  const applyConflicts =
+    report.apply && Array.isArray(report.apply.conflicts) ? report.apply.conflicts.length : 0;
+  const csvErrors = report.csv && Array.isArray(report.csv.errors) ? report.csv.errors.length : 0;
+
+  console.log('\n=== SUMMARY ===');
+  console.log(`Mode: ${report.mode}`);
+  console.log(`Users (blocking): ${blockingUsers}`);
+  console.log(`ACL orphans: ${aclOrphans}`);
+  if (applyMode) {
+    console.log(`CSV errors: ${csvErrors}`);
+    console.log(`Apply ok: ${applyOk}`);
+    console.log(`Apply conflicts: ${applyConflicts}`);
+  }
+}
+
+function persistReportAndPrintSummary(reportsDir, report, applyMode) {
+  const timestamp = Date.now();
+  generateReports(reportsDir, report, timestamp);
+  printMigrationSummary(report, applyMode);
+  return computeExitCode(report);
+}
+
+async function main() {
+  let ds;
+  try {
+    ds = await createDatastoreFromArgv(argv);
+    const { report: usersReport } = await analyzeUsersWithDatastore(ds);
+    const { report: aclReport } = await analyzeAclWithDatastore(ds);
+
+    let csv = null;
+    let apply = null;
+
+    if (!args.apply) {
+      printDryRunNextSteps();
+    } else {
+      console.log('\n=== APPLY MODE ===');
+      if (!args.csvPath) {
+        throw new Error('--apply requires --csv <path>');
+      }
+      ({ csv, apply } = await runEmailApplyFromCsv(ds, args.csvPath));
+    }
+
+    const report = buildUsersMigrationReport({
+      mode: args.apply ? 'apply' : 'dry-run',
+      usersReport,
+      aclReport,
+      csv,
+      apply,
+    });
+
+    const exitCode = persistReportAndPrintSummary(config.reportsDir, report, args.apply);
+    process.exit(exitCode);
+  } catch (error) {
+    console.error('FATAL ERROR:', error.message);
+    process.exit(1);
+  } finally {
+    if (ds) {
+      await ds.close().catch(() => {});
+    }
+  }
+}
+
+main();
diff --git a/scripts/migrate/test/analyze-acl.test.ts b/scripts/migrate/test/analyze-acl.test.ts
new file mode 100644
index 000000000..9af31e973
--- /dev/null
+++ b/scripts/migrate/test/analyze-acl.test.ts
@@ -0,0 +1,51 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, test } from 'vitest';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { collectAclOrphans } = require('../lib/analyze-acl.js');
+
+describe('scripts/migrate/lib/analyze-acl.js collectAclOrphans', () => {
+  test('finds orphans case-insensitively and ignores blanks/non-strings', () => {
+    const usernameSet = new Set(['alice', 'bob']);
+    const repos = [
+      {
+        _id: 'r1',
+        name: 'repo1',
+        url: 'https://example/repo1.git',
+        users: {
+          canPush: ['Alice', '  ', null, 'Mallory'],
+          canAuthorise: ['bob', 'Eve'],
+        },
+      },
+    ];
+
+    const orphans = collectAclOrphans(repos, usernameSet);
+    expect(orphans).toHaveLength(2);
+    expect(orphans.map((o: any) => o.orphanUsername)).toEqual(['Mallory', 'Eve']);
+
+    expect(orphans[0]).toMatchObject({
+      repoId: 'r1',
+      repoName: 'repo1',
+      repoUrl: 'https://example/repo1.git',
+      field: 'canPush',
+      normalizedOrphan: 'mallory',
+      index: 3,
+    });
+  });
+});
diff --git a/scripts/migrate/test/analyze-urls.test.ts b/scripts/migrate/test/analyze-urls.test.ts
new file mode 100644
index 000000000..5e03e75a6
--- /dev/null
+++ b/scripts/migrate/test/analyze-urls.test.ts
@@ -0,0 +1,79 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, test } from 'vitest';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { buildUrlNormalizationReport } = require('../lib/analyze-urls.js');
+
+describe('scripts/migrate/lib/analyze-urls.js buildUrlNormalizationReport', () => {
+  test('plans .git append where missing and trims whitespace', () => {
+    const repos = [
+      { _id: 'r1', name: 'a', url: 'https://x/a' },
+      { _id: 'r2', name: 'b', url: ' https://x/b.git ' },
+    ];
+    const report = buildUrlNormalizationReport(repos);
+    expect(report.totalRepos).toBe(2);
+    expect(report.reposNeedingUpdate).toBe(1);
+    expect(report.reposAlreadyFixed).toBe(1);
+    expect(report.changes).toHaveLength(1);
+    expect(report.issues).toHaveLength(0);
+    expect(report.changes[0]).toMatchObject({
+      repoId: 'r1',
+      repoName: 'a',
+      oldUrl: 'https://x/a',
+      newUrl: 'https://x/a.git',
+      status: 'pending',
+    });
+  });
+
+  test('reports blank url as issue (no change)', () => {
+    const repos = [{ _id: 'r1', name: 'a', url: '   ' }];
+    const report = buildUrlNormalizationReport(repos);
+    expect(report.reposNeedingUpdate).toBe(0);
+    expect(report.changes).toHaveLength(0);
+    expect(report.issues).toHaveLength(1);
+    expect(report.issues[0]).toMatchObject({
+      repoId: 'r1',
+      repoName: 'a',
+      rawUrl: '',
+      normalizedUrl: '',
+      reason: 'blank',
+    });
+  });
+
+  test('strips trailing slashes before appending .git', () => {
+    const repos = [{ _id: 'r1', name: 'a', url: 'https://github.com/org/repo/' }];
+    const report = buildUrlNormalizationReport(repos);
+    expect(report.changes).toHaveLength(1);
+    expect(report.changes[0]).toMatchObject({
+      oldUrl: 'https://github.com/org/repo',
+      newUrl: 'https://github.com/org/repo.git',
+    });
+  });
+
+  test('reports unsupported scheme as issue', () => {
+    const repos = [{ _id: 'r1', name: 'a', url: 'ssh://git@github.com/org/repo' }];
+    const report = buildUrlNormalizationReport(repos);
+    expect(report.changes).toHaveLength(0);
+    expect(report.issues).toHaveLength(1);
+    expect(report.issues[0]).toMatchObject({
+      reason: 'unsupported-scheme',
+      scheme: 'ssh',
+    });
+  });
+});
diff --git a/scripts/migrate/test/analyze-users.test.ts b/scripts/migrate/test/analyze-users.test.ts
new file mode 100644
index 000000000..a37b9190c
--- /dev/null
+++ b/scripts/migrate/test/analyze-users.test.ts
@@ -0,0 +1,51 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, test } from 'vitest';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { buildUsersEmailReport } = require('../lib/analyze-users.js');
+
+describe('scripts/migrate/lib/analyze-users.js buildUsersEmailReport', () => {
+  test('classifies missing vs blank vs invalid-format', () => {
+    const users = [
+      { _id: 'u1', username: 'noEmail' }, // missing field
+      { _id: 'u2', username: 'blankEmail', email: '   ' },
+      { _id: 'u3', username: 'badEmail', email: 'not-an-email' },
+    ];
+    const { report } = buildUsersEmailReport(users);
+    const byId = new Map(report.issues.map((i: any) => [i.userId, i]));
+    expect(byId.get('u1').status).toBe('missing');
+    expect(byId.get('u2').status).toBe('blank');
+    expect(byId.get('u3').status).toBe('invalid-format');
+    expect(report.blockingIssueCount).toBe(3); // missing + blank + invalid-format
+  });
+
+  test('marks duplicate emails as duplicate and counts blocking issues', () => {
+    const users = [
+      { _id: 'u1', username: 'alice', email: 'dup@x.com' },
+      { _id: 'u2', username: 'bob', email: 'DUP@X.COM' },
+    ];
+    const { report } = buildUsersEmailReport(users);
+    expect(report.counts.duplicate).toBe(2);
+    expect(report.blockingIssueCount).toBe(2);
+    const statuses = report.issues.map((i: any) => i.status);
+    expect(statuses.every((s: string) => s === 'duplicate')).toBe(true);
+    expect(report.duplicateGroups).toHaveLength(1);
+    expect(report.duplicateGroups[0].normalizedEmail).toBe('dup@x.com');
+  });
+});
diff --git a/scripts/migrate/test/apply-user-emails.test.ts b/scripts/migrate/test/apply-user-emails.test.ts
new file mode 100644
index 000000000..71fc7c816
--- /dev/null
+++ b/scripts/migrate/test/apply-user-emails.test.ts
@@ -0,0 +1,54 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, test } from 'vitest';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { simulatePostApplyUniqueness } = require('../lib/apply-user-emails.js');
+
+describe('scripts/migrate/lib/apply-user-emails.js simulatePostApplyUniqueness', () => {
+  test('detects duplicates already present in DB state', () => {
+    const users = [
+      { _id: 'u1', username: 'alice', email: 'dup@x.com' },
+      { _id: 'u2', username: 'bob', email: 'dup@x.com' },
+    ];
+    const mapping = new Map();
+    const { conflicts } = simulatePostApplyUniqueness(users, mapping);
+    expect(conflicts).toEqual([{ normalizedEmail: 'dup@x.com', userIds: ['u1', 'u2'] }]);
+  });
+
+  test('detects conflicts introduced by mapping', () => {
+    const users = [
+      { _id: 'u1', username: 'alice', email: 'a@x.com' },
+      { _id: 'u2', username: 'bob', email: 'b@x.com' },
+    ];
+    const mapping = new Map([
+      ['alice', 'same@x.com'],
+      ['bob', 'same@x.com'],
+    ]);
+    const { conflicts } = simulatePostApplyUniqueness(users, mapping);
+    expect(conflicts).toEqual([{ normalizedEmail: 'same@x.com', userIds: ['u1', 'u2'] }]);
+  });
+
+  test('mapping key is matched against normalized username', () => {
+    const users = [{ _id: 'u1', username: 'Alice', email: 'old@x.com' }];
+    const mapping = new Map([['alice', 'NEW@X.COM ']]);
+    const { conflicts, projected } = simulatePostApplyUniqueness(users, mapping);
+    expect(conflicts).toEqual([]);
+    expect(projected.get('u1')).toBe('new@x.com');
+  });
+});
diff --git a/scripts/migrate/test/csv.test.ts b/scripts/migrate/test/csv.test.ts
new file mode 100644
index 000000000..b4fd7dd1e
--- /dev/null
+++ b/scripts/migrate/test/csv.test.ts
@@ -0,0 +1,89 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, test } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { readUsernameEmailCsv } = require('../lib/csv.js');
+
+function writeTempCsv(contents: string) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'git-proxy-migrate-'));
+  const filePath = path.join(dir, 'mappings.csv');
+  fs.writeFileSync(filePath, contents, 'utf8');
+  return filePath;
+}
+
+describe('scripts/migrate/lib/csv.js', () => {
+  test('throws on empty CSV', () => {
+    const p = writeTempCsv('\n\n');
+    expect(() => readUsernameEmailCsv(p)).toThrow(/CSV is empty/);
+  });
+
+  test('throws on missing username,email header', () => {
+    const p = writeTempCsv('user,email\nalice,a@b.com\n');
+    expect(() => readUsernameEmailCsv(p)).toThrow(/CSV header must include: username,email/);
+  });
+
+  test('normalizes username/email and returns mapping', () => {
+    const p = writeTempCsv('username,email\n Alice , ALICE@EXAMPLE.COM \n');
+    const { errors, mapping, rows } = readUsernameEmailCsv(p);
+    expect(errors).toEqual([]);
+    expect(mapping.get('alice')).toBe('alice@example.com');
+    expect(rows[0].usernameRaw).toBe('Alice');
+    expect(rows[0].emailRaw).toBe('ALICE@EXAMPLE.COM');
+    expect(rows[0].username).toBe('alice');
+    expect(rows[0].email).toBe('alice@example.com');
+  });
+
+  test('reports missing username', () => {
+    const p = writeTempCsv('username,email\n, a@b.com\n');
+    const { errors, mapping } = readUsernameEmailCsv(p);
+    expect(mapping.size).toBe(0);
+    expect(errors[0]).toMatchObject({ code: 'missing-username', line: 2 });
+  });
+
+  test('reports missing email', () => {
+    const p = writeTempCsv('username,email\nbob,\n');
+    const { errors, mapping } = readUsernameEmailCsv(p);
+    expect(mapping.size).toBe(0);
+    expect(errors[0]).toMatchObject({ code: 'missing-email', line: 2, username: 'bob' });
+  });
+
+  test('reports invalid email format', () => {
+    const p = writeTempCsv('username,email\nbob,not-an-email\n');
+    const { errors, mapping } = readUsernameEmailCsv(p);
+    expect(mapping.size).toBe(0);
+    expect(errors[0]).toMatchObject({ code: 'invalid-email-format', line: 2, username: 'bob' });
+  });
+
+  test('duplicate username with different emails produces error and keeps first', () => {
+    const p = writeTempCsv('username,email\nbob,b1@ex.com\nbob,b2@ex.com\n');
+    const { errors, mapping } = readUsernameEmailCsv(p);
+    expect(mapping.get('bob')).toBe('b1@ex.com');
+    expect(errors.some((e: any) => e.code === 'duplicate-username')).toBe(true);
+  });
+
+  test('duplicate username with same email is allowed', () => {
+    const p = writeTempCsv('username,email\nbob,b@ex.com\nbob,b@ex.com\n');
+    const { errors, mapping } = readUsernameEmailCsv(p);
+    expect(errors).toEqual([]);
+    expect(mapping.get('bob')).toBe('b@ex.com');
+  });
+});
diff --git a/scripts/migrate/test/email.test.ts b/scripts/migrate/test/email.test.ts
new file mode 100644
index 000000000..2c441f53e
--- /dev/null
+++ b/scripts/migrate/test/email.test.ts
@@ -0,0 +1,54 @@
+/**
+ * Copyright 2026 GitProxy Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, test } from 'vitest';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { normalizeEmail, isEmailFormatValid } = require('../lib/email.js');
+
+describe('scripts/migrate/lib/email.js', () => {
+  describe('normalizeEmail trims, lowercases, and coerces falsy to empty string', () => {
+    test.each([
+      [null, ''],
+      [undefined, ''],
+      ['', ''],
+      ['   ', ''],
+    ])('returns %j when input is %j', (input, expected) => {
+      expect(normalizeEmail(input)).toBe(expected);
+    });
+  });
+
+  describe('isEmailFormatValid applies a basic format check after normalization', () => {
+    describe('accepts addresses that match the migration regex', () => {
+      test.each(['a@b.c', 'user+tag@example.com', 'alice@mail.example.com'])(
+        'treats %s as valid',
+        (email) => {
+          expect(isEmailFormatValid(email)).toBe(true);
+        },
+      );
+    });
+
+    describe('rejects addresses that fail the migration regex', () => {
+      test.each(['', 'a@b', '@x.com', 'a@', 'a @b.com', 'a@@b.com'])(
+        'treats %s as invalid',
+        (email) => {
+          expect(isEmailFormatValid(email)).toBe(false);
+        },
+      );
+    });
+  });
+});