template/.planning/codebase/INTEGRATIONS.md

# External Integrations

**Analysis Date:** 2026-09-07

## APIs & External Services

**h5mota.com (H5魔塔 tower publishing platform) — the only external HTTP service:**

The project integrates with the H5魔塔 community platform (`h5mota.com`) in three distinct places:

1. **Tower metadata scraper** — `script/special.ts`
   - `GET https://h5mota.com/backend/towers/query.php` (`mode=list`) — list all published towers
   - `GET https://h5mota.com/backend/admin/tower/info.php` (`name=<tower>`) — fetch tower metadata
   - `GET https://h5mota.com/games/{name}/project/{functions|enemys|floors.min|maps}.js` — download raw game source files for offline analysis
   - Auth: hardcoded `Cookie: id=2691; password=...` header (a session credential embedded in source — treat as sensitive; see Security Considerations below)

2. **Danmaku (barrage) proxy** — `script/dev.ts`
   - Vite dev proxy route `/danmaku` → `https://h5mota.com/backend/tower/barrage.php`

3. **Cloud save sync** — `packages-user/client-modules/src/render/utils/saves.ts`
   - `POST /games/sync.php` (relative path, resolved against the deployed `h5mota.com` origin)
   - Request body: `FormData` with `type=load`, `name`, `id`, `password`
   - Response: `SyncSaveFromServerResponse` — JSON with `code`/`msg`; `msg` is `lz-string` base64-compressed save data
   - Auth: identifier string (`存档编号` + `密码`) split into `id`/`password` by `parseIdPassword()`

## Data Storage

**Databases:**
- IndexedDB via **Dexie** (`dexie ^4.4.2`)
  - Implementation: `packages-user/data-common/src/save/system.ts` (`SaveSystem`)
  - Schema (v1): `saves` table (`id` key) and `global` table (`key` key)
  - Used for local save/autosave slots, undo/redo stack persistence, and global key-value state
- `localStorage` (legacy) — `packages/legacy-system/src/storage.ts`
- **localforage** (legacy fallback) — vendored at `public/libs/thirdparty/localforage.min.js`, typed in `src/types/declaration/util.d.ts`

**File Storage:**
- Local filesystem only. The dev/editor server exposes a file CRUD API over Express (`script/dev.ts`): `POST /listFile`, `/makeDir`, `/readFile`, `/writeFile`, `/deleteFile`, `/moveFile`, `/writeMultiFiles`; `GET /all/__all_floors__.js`, `/all/__all_animates__`, `/esm`, `/getPort`. All paths are confined to the `public/` base directory (`resolvePath()` safety check).

**Caching:**
- None (no external cache service). In-browser `localStorage`/IndexedDB are used for persistence only.

## Authentication & Identity

**Auth Provider:**
- Custom / none. There is no OAuth or third-party identity provider.
- Cloud save uses a bare `id` + `password` pair (split from a user-entered save code). See `parseIdPassword()` in `packages-user/client-modules/src/render/utils/saves.ts`.
- The scraper in `script/special.ts` authenticates to the admin API using a hardcoded session cookie.

**Native bridge (mobile packaging):**
- `window.jsinterface` global is called for orientation control (`requestPortrait()` / `requestLandscape()`) in `packages/legacy-ui/src/utils.ts` (`triggerFullscreen()`). This is the interface exposed by the native app shell (Android/iOS) that wraps the HTML5 game.

## Monitoring & Observability

**Error Tracking:**
- None (no Sentry/Bugsnag/etc.)

**Logs:**
- Custom in-repo logger: `packages/common/src/logger.ts` (with error/warn code tables surfaced in `docs/logger/`). Uses `console` output; `no-console` is `warn` in `eslint.config.js`.

## CI/CD & Deployment

**Hosting:**
- GitHub Pages (static) — `.github/workflows/page.yml` builds on push to `master` and deploys the `dist/` folder to the `gh-pages` branch using `JamesIves/github-pages-deploy-action`.
- The built game is also distributed as a self-contained static bundle (`dist/`) and `dist.zip`.

**CI Pipeline:**
- GitHub Actions only:
  - `page.yml` — install deps (`pnpm@7.27.0`), `pnpm i`, `pnpm build`, deploy to Pages (uses secret `ACCESS_TOKEN`)
  - `codeql.yml` — CodeQL static analysis (JavaScript), runs on push/PR to `master` + weekly cron

## Environment Configuration

**Required env vars:**
- None at runtime. The project uses no `.env` files.

**Secrets location:**
- GitHub Actions secret: `ACCESS_TOKEN` (referenced in `.github/workflows/page.yml`)
- Editor server config: `public/_server/config.json` (gitignored; auto-created as `{}` by `script/dev.ts`)
- Hardcoded admin cookie in `script/special.ts` (should be externalized, see Security Considerations)

## Webhooks & Callbacks

**Incoming:**
- Dev-time Express server routes (`script/dev.ts`): file CRUD endpoints listed above, plus `GET /getPort` (returns the hot-reload WebSocket port to the client, `packages-user/legacy-plugin-client/src/dev/hotReload.ts`).
- WebSocket server (`ws`) on the editor HTTP server for hot reload; client connects to `ws://127.0.0.1:{port}` and receives `reload`, `floorHotReload`, `dataHotReload`, `cssHotReload` messages.

**Outgoing:**
- h5mota.com tower query/info/game-file endpoints (`script/special.ts`)
- h5mota.com barrage endpoint via dev proxy (`script/dev.ts`)
- h5mota.com cloud save sync `/games/sync.php` (`packages-user/client-modules/src/render/utils/saves.ts`)
- Local asset streaming via `window.fetch` (`packages/loader/src/task.ts`, `packages/loader/src/stream.ts`)

---

## Security Considerations

**Hardcoded session credential in `script/special.ts`**
- The admin API calls embed `Cookie: id=2691; password=26e631510147c1d0b71a368a3729df5a` directly in source. This is a live-looking session credential checked into the repository.
- Impact: if the credential is valid, it grants the scraper access to h5mota.com's admin/tower endpoints and leaks on any code share.
- Recommendation: move the cookie value to a local, gitignored config or environment variable; rotate the credential.

**No auth on editor file API (`script/dev.ts`)**
- The Express routes (`/readFile`, `/writeFile`, `/deleteFile`, etc.) require no authentication and are bound to the local server; the only protection is a path-traversal check (`resolvePath()`).
- Recommendation: keep the editor server loopback-only in production; do not expose port 3000 publicly.

---

*Integration audit: 2026-09-07*