feat(migrate-tool): add track migration tool

A small Vite + React SPA backed by Vercel functions + Supabase that lets an
artist request migration of tracks from an old Audius account they've lost
access to onto a new account they control. Every migration sits in a
pending queue until an Audius team member approves it via an admin route
gated by a bearer token — the README spells out that identity
verification of the requester has to happen out-of-band.

The frontend uses the SDK's PKCE OAuth flow with apiKey only; on approval
the backend re-uploads each track via createSdkWithServices using the
dev app's API key + bearer token, acting on behalf of the new owner.

Designed for migrate.audius.co.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dylanjeffers

package-lock.json

@@ -0,0 +1,25 @@
+# ----- Frontend (Vite — must be prefixed VITE_) -----
+
+# Audius developer app API key (safe to expose in browser).
+# Get one at audius.co/settings → Developer Apps.
+VITE_AUDIUS_API_KEY=
+
+# "production" (default) or "development" to point at a local protocol stack.
+VITE_AUDIUS_ENVIRONMENT=production
+
+# ----- Backend (Vercel functions — never expose in browser) -----
+
+# Audius bearer token. Backend only. Used with the API key above so the
+# server can act on behalf of users who have authorized the developer app.
+AUDIUS_API_KEY=
+AUDIUS_BEARER_TOKEN=
+
+# Bearer secret that admin endpoints (list/approve/reject) require in the
+# Authorization header. Pick a long random string and share it only with
+# Audius team members authorized to approve migrations.
+ADMIN_BEARER_TOKEN=
+
+# Supabase connection. The service role key bypasses RLS and must stay
+# backend-only — never expose it.
+SUPABASE_URL=
+SUPABASE_SERVICE_ROLE_KEY=

packages/migrate-tool/.env.example

@@ -0,0 +1,7 @@
+node_modules
+dist
+.vercel
+.env
+.env.local
+*.log
+.turbo

packages/migrate-tool/.gitignore

@@ -0,0 +1,120 @@
+# @audius/migrate-tool
+
+A small web tool for moving an artist's tracks from an old Audius account to a
+new one — for cases where the artist has lost access to their original account
+(forgotten password, lost email) and has created a new account.
+
+Designed to be deployed to **migrate.audius.co** on Vercel with a Supabase
+database backing the request queue.
+
+## How it works
+
+1. The artist signs in with their new Audius account (OAuth via the Audius
+   developer app).
+2. They enter the handle of their old account. The tool previews the tracks
+   that would be migrated.
+3. They submit a migration request. The request is stored in Supabase with
+   `status = 'pending'`.
+4. An Audius team member opens `/admin`, unlocks with the admin bearer token,
+   and reviews the request. Identity verification (confirming the requester
+   actually owns the old account) happens **out-of-band** via the usual
+   support channel — the tool does not enforce it.
+5. On approval the backend pulls each old track's audio + artwork via the SDK
+   and re-uploads it on the new account using the developer app's bearer
+   token. Per-track results are written back to the DB and shown on the
+   status page.
+
+## Limitations
+
+- **Original masters**: only tracks the artist marked as **downloadable** expose
+  the original audio file via the public API. Other tracks migrate with the
+  transcoded MP3 stream, which is a lossy re-encoding rather than a bit-for-bit
+  copy. The track preview shows which of these applies per track.
+- **No identity verification in-tool**: anyone signed in can request migration
+  of any handle. The approver is responsible for verifying the requester owns
+  the old account before approving. Don't approve a request without
+  confirming identity through a separate channel.
+- **Old account is not modified**: the tracks are re-created on the new
+  account. The originals on the old account are untouched (the tool has no
+  authority over the old account).
+- **No social-graph preservation**: plays, favorites, reposts, and comments
+  on the old tracks do not carry over.
+
+## Deploy
+
+### 1. Supabase
+
+Create a project, then run the SQL in `supabase/migrations/0001_init.sql`.
+
+You'll need:
+
+- `SUPABASE_URL` — project URL
+- `SUPABASE_SERVICE_ROLE_KEY` — backend-only key (do not expose to the browser)
+
+### 2. Audius developer app
+
+Create a developer app at <https://audius.co/settings> → Developer Apps. You'll
+get an **API Key** and a **Bearer Token**.
+
+- `VITE_AUDIUS_API_KEY` — the API key (safe in the browser; baked into the build)
+- `AUDIUS_API_KEY` — same API key, for the backend
+- `AUDIUS_BEARER_TOKEN` — backend-only; grants the app permission to act on
+  behalf of users who have authorized it via OAuth
+
+You'll also need to whitelist the deployment's OAuth redirect URI in the dev
+app's settings (e.g. `https://migrate.audius.co/`).
+
+### 3. Admin token
+
+- `ADMIN_BEARER_TOKEN` — pick a long random string. Share it only with team
+  members authorized to approve migrations.
+
+### 4. Vercel
+
+```sh
+cd packages/migrate-tool
+npx vercel link
+npx vercel env add VITE_AUDIUS_API_KEY
+npx vercel env add AUDIUS_API_KEY
+npx vercel env add AUDIUS_BEARER_TOKEN
+npx vercel env add ADMIN_BEARER_TOKEN
+npx vercel env add SUPABASE_URL
+npx vercel env add SUPABASE_SERVICE_ROLE_KEY
+npx vercel --prod
+```
+
+Then add `migrate.audius.co` as a domain in the Vercel project.
+
+## Local development
+
+```sh
+cp .env.example .env.local
+# Fill in the values, then:
+npm install
+npm run dev
+```
+
+The Vite dev server runs at `http://localhost:5180`. To exercise the API
+functions locally, run them with `npx vercel dev` instead.
+
+## Approving a request
+
+1. Go to `https://migrate.audius.co/admin`.
+2. Paste the `ADMIN_BEARER_TOKEN` to unlock.
+3. Review the request — especially the old handle and the track list.
+4. **Verify the requester owns the old account through your usual support
+   channel.** This is the only safeguard against migration abuse.
+5. Click **Approve & execute**. The backend runs the migration synchronously
+   (Vercel function timeout is set to 5 minutes in `vercel.json`).
+
+## Files
+
+- `src/` — Vite + React SPA (home / status / admin pages)
+- `api/` — Vercel serverless functions
+  - `api/requests/index.ts` — `POST /api/requests` (create)
+  - `api/requests/[id].ts` — `GET /api/requests/:id` (status)
+  - `api/admin/requests.ts` — `GET /api/admin/requests` (list, bearer-gated)
+  - `api/admin/approve.ts` — `POST /api/admin/approve?id=…` (bearer-gated)
+  - `api/admin/reject.ts` — `POST /api/admin/reject?id=…` (bearer-gated)
+  - `api/_lib/migrate.ts` — migration worker
+- `supabase/migrations/0001_init.sql` — DB schema

packages/migrate-tool/README.md

@@ -0,0 +1,37 @@
+import {
+  createSdkWithServices,
+  type AudiusSdkWithServices
+} from '@audius/sdk'
+
+let serverSdk: AudiusSdkWithServices | null = null
+
+/**
+ * Server-side SDK initialized with the developer app's API key + bearer
+ * token. The bearer token grants the app permission to act on behalf of
+ * any user who has authorized it via OAuth.
+ *
+ * Per the SDK README: "Bearer Token — backend only. Grants your app the
+ * ability to act on behalf of users who have authorized it. Never expose
+ * this in browser or mobile code."
+ *
+ * We use createSdkWithServices (rather than the public sdk() factory) so
+ * sdk.tracks is the wrapped TracksApi with friendly helpers like
+ * getTrackStreamUrl, getTrackDownloadUrl, and the createTrack overload
+ * that handles audio + image upload + trackCid in one call.
+ */
+export function getServerSDK(): AudiusSdkWithServices {
+  if (serverSdk) return serverSdk
+  const apiKey = process.env.AUDIUS_API_KEY
+  const bearerToken = process.env.AUDIUS_BEARER_TOKEN
+  if (!apiKey || !bearerToken) {
+    throw new Error(
+      'AUDIUS_API_KEY and AUDIUS_BEARER_TOKEN must be set on the server.'
+    )
+  }
+  serverSdk = createSdkWithServices({
+    apiKey,
+    bearerToken,
+    appName: 'AudiusTrackMigration'
+  })
+  return serverSdk
+}

packages/migrate-tool/api/_lib/audius.ts

@@ -0,0 +1,34 @@
+import type { VercelRequest, VercelResponse } from '@vercel/node'
+
+/**
+ * Constant-time check that the incoming Authorization header matches the
+ * admin bearer token. Returns true if authorized, otherwise writes a 401
+ * response and returns false — callers can early-return.
+ */
+export function requireAdmin(
+  req: VercelRequest,
+  res: VercelResponse
+): boolean {
+  const expected = process.env.ADMIN_BEARER_TOKEN
+  if (!expected) {
+    res.status(500).json({ error: 'ADMIN_BEARER_TOKEN not configured.' })
+    return false
+  }
+  const header = req.headers.authorization ?? ''
+  const match = /^Bearer\s+(.+)$/.exec(header)
+  const token = match?.[1] ?? ''
+  if (!constantTimeEquals(token, expected)) {
+    res.status(401).json({ error: 'Unauthorized.' })
+    return false
+  }
+  return true
+}
+
+function constantTimeEquals(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  let mismatch = 0
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  }
+  return mismatch === 0
+}

packages/migrate-tool/api/_lib/auth.ts

@@ -0,0 +1,145 @@
+import type { Genre, Mood } from '@audius/sdk'
+
+import { getServerSDK } from './audius'
+import { getSupabase, TABLE } from './supabase'
+import type { DbRow, TrackResult } from './types'
+
+/**
+ * Fetch a URL into a Blob with a reasonable timeout. Used for pulling the
+ * old track's audio and artwork before re-uploading them to the new owner.
+ */
+async function fetchBlob(url: string, timeoutMs = 90_000): Promise<Blob> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const res = await fetch(url, { signal: controller.signal })
+    if (!res.ok) throw new Error(`Fetch ${res.status} ${res.statusText} (${url})`)
+    return await res.blob()
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function filenameFromUrl(url: string, fallback: string): string {
+  try {
+    const u = new URL(url)
+    const last = u.pathname.split('/').filter(Boolean).pop()
+    return last || fallback
+  } catch {
+    return fallback
+  }
+}
+
+function blobToFile(blob: Blob, name: string): File {
+  return new File([blob], name, { type: blob.type || 'application/octet-stream' })
+}
+
+/**
+ * Run the migration for one DB row. Updates the row in-place with per-track
+ * results as it goes, and sets the final status when done.
+ *
+ * Limitation: only tracks flagged as downloadable expose the original
+ * audio file. Other tracks fall back to the transcoded mp3 stream, which
+ * is a lossy re-encoding rather than a bit-for-bit copy.
+ */
+export async function executeMigration(row: DbRow): Promise<void> {
+  const supabase = getSupabase()
+  const sdk = getServerSDK()
+
+  await supabase
+    .from(TABLE)
+    .update({ status: 'running' })
+    .eq('id', row.id)
+
+  const results: TrackResult[] = row.tracks.map((t) => ({
+    oldTrackId: t.trackId,
+    status: 'pending'
+  }))
+
+  const persistResults = async () => {
+    await supabase
+      .from(TABLE)
+      .update({ results })
+      .eq('id', row.id)
+  }
+
+  let anyFailed = false
+
+  for (let i = 0; i < row.tracks.length; i++) {
+    const preview = row.tracks[i]!
+    try {
+      const trackRes = await sdk.tracks.getTrack({ trackId: preview.trackId })
+      const track = trackRes.data
+      if (!track) throw new Error('Track not found on source account.')
+
+      const audioUrl = preview.isDownloadable
+        ? await sdk.tracks.getTrackDownloadUrl({ trackId: preview.trackId })
+        : await sdk.tracks.getTrackStreamUrl({ trackId: preview.trackId })
+
+      const audioBlob = await fetchBlob(audioUrl)
+      const audioFile = blobToFile(
+        audioBlob,
+        filenameFromUrl(audioUrl, `${preview.trackId}.mp3`)
+      )
+
+      let imageFile: File | undefined
+      const artworkUrl =
+        track.artwork?._1000x1000 ??
+        track.artwork?._480x480 ??
+        track.artwork?._150x150
+      if (artworkUrl) {
+        const imageBlob = await fetchBlob(artworkUrl)
+        imageFile = blobToFile(
+          imageBlob,
+          filenameFromUrl(artworkUrl, 'artwork.jpg')
+        )
+      }
+
+      const upload = await sdk.tracks.createTrack({
+        userId: row.new_user_id,
+        audioFile,
+        imageFile,
+        // The generated type requires trackCid here, but the wrapped
+        // createTrack populates it from the audio upload response. See
+        // TracksApi.createTrack → populateTrackMetadataWithUploadResponseV2.
+        // @ts-expect-error trackCid is set by the SDK after audio upload
+        metadata: {
+          title: track.title,
+          genre: track.genre as Genre,
+          description: track.description ?? undefined,
+          mood: (track.mood as Mood | undefined) ?? undefined,
+          tags: track.tags ?? undefined,
+          isrc: track.isrc ?? undefined,
+          iswc: track.iswc ?? undefined,
+          license: track.license ?? undefined
+        }
+      })
+
+      results[i] = {
+        oldTrackId: preview.trackId,
+        newTrackId: upload.trackId,
+        status: 'success'
+      }
+    } catch (e) {
+      anyFailed = true
+      results[i] = {
+        oldTrackId: preview.trackId,
+        status: 'failed',
+        error: e instanceof Error ? e.message : String(e)
+      }
+    }
+    await persistResults()
+  }
+
+  await supabase
+    .from(TABLE)
+    .update({
+      status: anyFailed ? 'failed' : 'completed',
+      results,
+      completed_at: new Date().toISOString(),
+      failure_reason: anyFailed
+        ? 'One or more tracks failed to migrate. See per-track results.'
+        : null
+    })
+    .eq('id', row.id)
+}

packages/migrate-tool/api/_lib/migrate.ts

@@ -0,0 +1,18 @@
+import type { DbRow } from './types'
+
+export function rowToResponse(row: DbRow) {
+  return {
+    id: row.id,
+    newUserId: row.new_user_id,
+    newUserHandle: row.new_user_handle,
+    oldHandle: row.old_handle,
+    status: row.status,
+    tracks: row.tracks,
+    results: row.results ?? [],
+    rejectionReason: row.rejection_reason,
+    failureReason: row.failure_reason,
+    createdAt: row.created_at,
+    approvedAt: row.approved_at,
+    completedAt: row.completed_at
+  }
+}