feat: add external API administrator UI

.env.example

@@ -78,6 +78,10 @@ YOUTUBE_OUTPUT_DIR=./downloads
 # Default: true (authentication enabled)
 AUTH_ENABLED=true
 
+# Versioned external API. This API always requires an external API key even
+# when AUTH_ENABLED=false. It is disabled by default; set to true to enable it.
+EXTERNAL_API_ENABLED=false
+
 # Initial Admin Credentials (for headless/automated deployments)
 # If not set, you'll create credentials through the web UI on first access
 # And they will be saved to config/config.json (password hashed)

.github/workflows/ci.yml

@@ -121,6 +121,9 @@ jobs:
       - name: Install dependencies
         run: npm ci --ignore-scripts
 
+      - name: Validate external API fixture and checksum
+        run: npm run test:external-fixture
+
       - name: Run backend tests with coverage
         run: npm run test:backend -- --coverage --coverageReporters=json-summary --coverageReporters=lcov --coverageReporters=text
         env:
@@ -161,7 +164,7 @@ jobs:
             coverage/lcov.info
 
   test-external-api-database:
-    name: External API DB migrations (${{ matrix.engine }})
+    name: External API DB runtime and migrations (${{ matrix.engine }})
     runs-on: ubuntu-latest
     timeout-minutes: 10
     strategy:
@@ -197,7 +200,7 @@ jobs:
         run: npm install -g npm@11.15.0 --ignore-scripts
       - name: Install dependencies
         run: npm ci --ignore-scripts
-      - name: Run external API migration lifecycle
+      - name: Run external API runtime and migration lifecycle
         run: |
           npm run test:external-api-database -- --json --outputFile=external-api-database-results.json
           node -e "const result = require('./external-api-database-results.json'); if (result.numPassedTests < 1 || result.numPendingTestSuites !== 0 || result.numPendingTests !== 0 || result.numTodoTests !== 0) process.exit(1);"
@@ -208,6 +211,19 @@ jobs:
           DB_PASSWORD: rootpass
           DB_ADMIN_USER: root
           DB_ADMIN_PASSWORD: rootpass
+      - name: Verify runtime query plans on synthetic data
+        run: npm run test:external-index-plans
+        env:
+          DB_HOST: 127.0.0.1
+          DB_PORT: 3321
+          DB_USER: root
+          DB_PASSWORD: rootpass
+          EXTERNAL_API_INDEX_REPORT: external-api-index-plans.json
+      - name: Upload runtime query plans
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: external-api-index-plans-${{ matrix.engine }}
+          path: external-api-index-plans.json
 
   test-frontend:
     name: Frontend Tests

CLAUDE.md

@@ -29,6 +29,9 @@ For multi-part requests (e.g., "review this PR AND explain WebSocket handling"),
 ## Architecture
 
 ### Backend (server/)
+- `routes/externalApi.js` and `middleware/externalApiAuth.js`: opt-in `/external-api/v1` routes with mandatory external-key authentication, bounded UTF-8 JSON bodies, private responses, and per-key limits. All External API business logic lives in `modules/externalApi/`; `externalApiConfig.js` (feature availability and `isExternalApiPath`), `externalApiResponse.js`, `externalPermissions.js`, and `externalEligibility.js` (media/rating policy; maps TV-Y7 to level 2 locally since `ratingMapper` has no numeric TV-Y7) centralize the shared rules, and `apiKeyChannelGrantModule.js` manages per-key channel grants.
+- `modules/externalApi/externalCatalogService.js`: cached, grant-filtered catalog and asset lookup. Reads never spawn yt-dlp or write: video detail uses `videoMetadataModule.getCachedVideoMetadata` (cached `.info.json` only). Raw SQL stays portable (snake_case aliases, `POSITION(... IN ...)`), keyset cursors (v3) tie-break on `cv.id`, and single-channel lookups go through `Channel.findOne` with the `apiKeyGrants` include. `externalCatalogRequests.js` batches current-page request status, `externalPagination.js` shares bounded page cursors, and `externalThumbnailProxy.js` enforces upstream image URL, size, and timeout limits.
+- `modules/externalApi/externalRequestService.js`: request creation (auto-approved requests are stored `approved` with `approval_source='auto'`) and owner history; reads never change request state. `externalRequestExecutor.js` is the background executor (started in `server.js` only when the External API is enabled; sweeps every minute, wakes on create/approve, and on `jobModule.onJobEnded`): it rechecks authority, claims `approved` -> `processing`, queues video downloads through `downloadModule.doSpecificDownloads` with the request id as the job id, provisions/enables/grants channels, and deletes videos through `videoDeletionModule`, holding requests with a message while downloads are paused or the video is busy, and recovering interrupted rows. `externalRequestTargets.js` validates grant/channel/video/policy targets, `externalRequestReconciliation.js` closes processing video requests whose job ended, `externalRequestReviewService.js` owns idempotent administrator approve/reject (approve only marks `approved` and wakes the executor), `externalRequestPrimitives.js` shares validation/DTOs, and `externalQuotaService.js` counts `approved` + `processing` as active jobs. Key-before-request locks serialize decisions; `externalWorkLimiter.js` bounds expensive work. `routes/externalRequests.js` exposes admin management endpoints that reject every API key; their UI is a separate follow-up.
 - `modules/externalCookies.js`: validates external cookie snapshots through the installed yt-dlp parser in `utils/validate-cookies.py`, memoizes unchanged results, and reports unusable files for omission; `modules/uploadedCookies.js` gives the uploaded `config/cookies.user.txt` a disposable private copy per run (yt-dlp rewrites its cookie file in place on exit, so concurrent runs sharing it could read a half-written jar or undo a Settings upload; nothing is written back, and Settings uploads are written to a temp file and renamed into place; if the copy fails, the run goes without cookies (error-level log; info when the upload was just deleted) and yt-dlp is never handed the uploaded file itself, whose exit-time jar save could overwrite a newer upload or recreate deleted cookies); `modules/ytdlpProcess.js` owns both kinds of copy's lifetime around yt-dlp processes. No persistent cookie fallback.
 - `modules/rescanRowUpdate.js` + `modules/videoRowGuard.js`: the filesystem rescan (`videosModule.backfillVideoMetadata`) walks the disk once and reads rows in chunks, so downloads and deletions in between make the walk stale. The walk only nominates rows (`isRescanCandidate`); `resolveRescanUpdate` recomputes each nominated row's write from a fresh per-format stat (present only for a regular file / missing on `ENOENT` or `ENOTDIR` or a non-file / unknown on any other error; both formats missing marks the row missing and keeps its stored paths; a missing format is cleared only when the other is present; any present format means `removed: false` even if the other is unknown; an unknown format is never cleared, and with nothing present an unknown writes nothing), and the write only lands if the row is unchanged since read (`videoRowGuard.unchangedSinceRead`: removed, both paths and sizes, `video_resolution`, `last_downloaded_at`; zero affected rows means a conflict only when the write includes a column that really differs, because Sequelize's MySQL dialect connects with -FOUND_ROWS and mysql2 then counts changed rows, not matched rows). Nominated rows left as recorded (files still at a stored path, e.g. outside the downloads folder, or files that could not be checked; re-checked every run) are counted as `kept` (`videosKept` in the run details, not the message). The walk's count of folders and files it could not read is `unreadableOnDisk` in the run details and log (not the message: those rows are re-checked by path). Rows another writer changed are counted as `skippedChanged` (`videosSkipped` in the run record) and failed writes as `failed` (`videosFailed`); both appear in the run message, and a finished scan with failed writes records as `error`/`partial` (a timed-out scan stays `timed-out` so Maintenance can continue it); the completion `rescanStatus` broadcast is built through the same `rescanRunSummary` record so the live Maintenance view matches the run history. Library repair (`jobModule.backfillFromCompleteList`) uses the same guard: it reads the row before searching the disk, writes file details and `removed: false` only for a file it actually found, and looks up a lost row's files by YouTube id with one `videosModule.scanForVideoFiles` walk per run (only when a lost row exists; video and audio, any folder layout), recreating it as missing when the walk finds nothing. The walk skips and counts (`unreadable`) folders and files it cannot read rather than stopping, logging unreadable files once per folder; repair still recreates unmatched rows as missing after a partial walk, because deferring would block recovery wherever a folder is never readable (lost+found, NAS recycle bins), and the next rescan restores a row whose file it finds. Such a run records as `error`/`partial`, naming the count in its message (`recreatedUnverified` and `unreadableOnDisk` in the details); a partial walk that affected no row stays `completed`.
 - `modules/cookieDetails.js`: summarizes the YouTube login cookies (names, counts, earliest expiry; never values) in the active cookie file as `details` on `GET /api/cookies/status` and the upload/delete responses, reading external files through `externalCookies.readExternalCookies`. `modules/cookieTest.js`: `POST /api/cookies/test`, one yt-dlp request to the subscriptions feed with `buildCommonArgs` (same proxy/IP family/cookies/cache as downloads) through `ytDlpRunner`, against a private temp copy of uploaded cookies (yt-dlp writes its jar back on exit, which would otherwise undo a replace/delete made mid-test; external files get spawnYtDlp's snapshot) and never logs stderr (yt-dlp echoes malformed cookie lines with their values); any exit 0 with JSON is signed in (even zero subscriptions), and the feed's "Incomplete yt initial data" warnings mean signed out (EXPIRED_COOKIES), a meaning specific to this feed, so it is not in the shared subscription-import classifier. One test at a time (409), rate-limited by `cookieTestRateLimiter`.
@@ -66,6 +69,8 @@ For multi-part requests (e.g., "review this PR AND explain WebSocket handling"),
 - `components/Configuration/sections/LoggingSection.tsx` (`/settings/logging`): log level select ('' = LOG_LEVEL), the current level's source from the saved setting plus `/getconfig`'s `logging.envLevel` (via `useConfig().loggingStatus`), log file limits or an unwritable-folder warning, and Download logs through `Configuration/hooks/useLogDownload.ts` (axios blob, since a link cannot send `x-access-token`).
 - `components/FindChannels/`: channel search page at `/subscriptions/find`; each result card has an Open in YouTube link below its clickable area; clicking an unsubscribed card opens the shared `AddChannelDialog`, whose confirm hands off to `Subscriptions` via `location.state.addChannelUrl` and auto-runs the add flow.
 - `components/FindVideos/`: video search page at `/videos/find`. The server returns YouTube's relevance order; `sortResults.ts` sorts the loaded set client-side (relevance, published, views, duration, title, channel; nulls last either way), through the desktop table's headers (natural direction, reversed, then back to relevance) or the shared `VideoList/VideoListSortButton` on phones and in grid view (its `SortOption.undirected` marks relevance, which has no arrow). `hooks/useFindVideosPreferences.ts` remembers view (table by default), sort, and minimum duration in localStorage; `hooks/useVideoSearch.ts` keeps the last search in sessionStorage and restores it when the page opens with the same `?q=`, which the page writes after every search (a `?q=` with nothing remembered runs the search). `components/resultParts.tsx` holds the pieces the table, phone list, and cards share: relative published date with the exact date as tooltip (yt-dlp dates are approximate), compact view count, a Short badge at 60 s or less, a status chip only for states other than never-downloaded, the per-row download button (`hooks/useResultDownload.ts` owns the dialog for either one row or the selection, never touching the selection for a single download), and the channel name through the shared `ChannelNameDisplay` (link when `channelSubscribed`, plus a Subscribed chip; otherwise the add-channel affordance opening `AddChannelDialog`).
+- `components/ExternalRequests/`: administrator review queue for external API requests at `/requests` (routed and linked in the nav only when `/getconfig`'s `isPlatformManaged.externalApiEnabled` is true; the `showRequestsNavLink` setting can additionally hide the link). `RequestsPage.tsx` renders filters, a table on desktop and cards on phones, and the shared `PageControls`; `hooks/useExternalRequests.ts` loads the page (stale responses discarded, page clamped when a review empties the last page, and a silent refetch every 5 s while any visible request is `approved`/`processing`, since the server's background executor advances them; paused while the tab is hidden) and `hooks/useRequestReview.ts` owns details (kept in step with those refetches) and approve/reject confirmation for pending requests (cancelling an action started from the details dialog returns to it; an inline one returns to the list); `components/` holds `RequestActions`, `RequestTarget`, `RequestDetailsDialog`, and `RequestActionDialog`.
+- `components/Configuration/sections/ApiKeysSection.tsx` (`/settings/api-keys`): bookmarklet keys always come first (`ApiKeysSection/BookmarkletKeysSection.tsx`, and `CreatedKeyDialog.tsx` shows the one-time key, the draggable Send to Youtarr bookmarklet, and phone shortcut details); the external access keys section (`ExternalKeysSection`, `ExternalKeyCard`, `CreateKeyDialog`, `EditKeyDialog` + `useExternalAccessEditor`, `PolicyEditor`, `ChannelGrantPicker`) appears only when the external API is enabled. Requests go through `ApiKeysSection/useApiKeys.ts` (axios); `WORKLOAD_LIMITS` there mirrors the server's per-key ceilings.
 - `themes/`: theme definitions (`playful`, `linear`, `flat`), shared layout policy (`layoutPolicy.ts`), and the `ALL_THEMES` registry. New themes add an entry here and implement the required token surface.
 - `hooks/`: app-wide custom hooks for data fetching and state.
 - `contexts/` and `providers/`: React Context for cross-cutting concerns (auth token, WebSocket, theme). `contexts/ThemeEngineContext.tsx` owns the active theme mode, resolves the layout policy for the current viewport, and injects theme CSS variables onto the document root.
@@ -232,6 +237,8 @@ npm run test:frontend                                        # all frontend test
 npm run test:frontend -- client/src/hooks/__tests__/foo.ts   # one frontend test
 npm run test:backend                                         # all backend tests
 npm run test:backend -- server/modules/__tests__/foo.test.js # one backend test
+npm run test:external-api-database                           # real database migration/runtime regressions
+npm run test:external-index-plans                            # local synthetic query/EXPLAIN report
 npm run lint                                                  # lint front + back
 npm run lint:ts                                               # TypeScript typecheck
 ```