# Development Guide

> [简体中文](../zh/DEVELOPMENT.md) | English

## Architecture

```
host (zero build, node:crypto / node:http)
├── index.js          # Cordis plugin entry: gateway lifecycle, tapIndex injection (randomUUID + authenticated LAN trust), security-event & login-audit wiring, first-run initial password
├── lib/gateway.js    # Auth gateway: HTTP/WS interception & forwarding, auth state machine, three-layer brute-force protection, replay protection, basePath routing/redirect/forward stripping, login-audit events, static-asset pass-through
├── lib/gateway-otp.js # OTP route handlers (/otp/setup|enable|verify-setup|verify|verify-backup|disable, split out of gateway.js)
├── lib/forward.js    # HTTP/WS forwarding plumbing (loopback Host/Origin rewrite, upgrade piping, lanAddresses)
├── lib/upstream-auth.js # dsh ≥ 0.1.2 upstream browser-auth bridge (secret via the credentials service, minted loopback-hop cookie; record-late fast retry / background probing and rotation re-mint)
├── lib/auth.js       # Session table & cookies: in-memory 256-bit tokens, onboarding/OTP state flags, revocation on password change
├── lib/audit-log.js  # Audit-log file sink (JSONL, $DSH_HOME/auth-gateway/log/audit.log, daily rotation, 90-day retention)
├── lib/page-shell.js # Shared page scaffolding (base CSS, HTML skeleton, script head: ERRORS + post)
├── lib/errors.js     # Master page-error dictionary (zh/en; errorsFor selects per page with overrides)
├── lib/locale.js     # Page language resolution (dsh preference > Accept-Language > zh)
├── lib/store.js      # Password storage (async scrypt hash, $DSH_HOME/auth-gateway/password.json)
├── lib/otp-store.js  # OTP storage (secret + hashed backup codes + lastCounter watermark)
├── lib/otp-crypto.js # OTP secret encryption/decryption (AES-256-GCM; master key from env var or key file)
├── lib/totp.js       # TOTP (RFC 6238/4226): base32, generate/verify, replay protection, otpauth URI, backup codes
├── lib/qr-svg.js     # Zero-dependency QR SVG generation (Reed-Solomon, mask evaluation)
├── lib/otp-page.js   # OTP setup/verify pages (self-contained HTML)
├── lib/login-page.js # Login/settings/change-password page
├── lib/onboarding-page.js # Onboarding page (set a personal password + optional OTP binding)
├── lib/policy.js     # Password-strength policy
├── lib/version.js    # Own version/repository (package.json) + SemVer-subset comparison
├── lib/update-check.js # New-version check (the only outbound request; TTL-cached, never throws)
└── lib/config.js     # Standard Schema config validation (incl. the basePath sub-path prefix)

client (optional, source-built)
├── client/src/index.jsx        # Panel container: all state/handlers, the api factory, slot registration (settings.section)
├── client/src/locales.js       # zh/en dictionaries (own namespace)
├── client/src/styles.js        # dsh design tokens + shared style objects
├── client/src/ui.jsx           # Button / Pill / StatusBanner primitives
├── client/src/*-card.jsx       # Presentational cards (OTP/password/session/cookie-Secure/about): props in, no state or requests
├── client/src/otp-setup-dialog.jsx # OTP setup dialog (scan / verify / one-time backup codes)
├── client/src/cookie-secure.js # Cookie-Secure state derivation (pure, unit-tested)
├── client/src/update-notice.js # Update-notice derivation (pure, unit-tested)
└── client/build.mjs            # esbuild build → client/index.js (served by dsh via exports["./client"])

scripts / tests
├── scripts/deploy.sh         # Deploy pipeline: syntax check → full tests → sync to the DSH install dir → post-install verification (--restart optionally restarts)
├── scripts/e2e.mjs           # Playwright end-to-end (real dsh web: login/2FA/password-change flows)
├── scripts/screenshots.mjs   # README UI screenshots (docs/assets/*.png)
├── scripts/verify.sh         # curl gate verification (401/302/WS rejection/lockout)
├── scripts/reset.mjs         # dsh-auth-gateway-reset: deletes only password.json (bilingual output)
├── scripts/uninstall.mjs     # dsh-auth-gateway-uninstall: deletes the whole auth-gateway/ (bilingual output)
└── tests/                    # gateway / config / policy / otp / locale / basepath / patch-ports / plugin-contract / client-contract / audit-log
```

Design points:

- **Zero runtime dependencies**: the host uses only Node built-ins; the client build artifact only externally references modules provided by the dsh runtime. Both `@deepseek-ai/dsh-client-ui-slots` and `@deepseek-ai/dsh-client-ui-primitives` (the official UI primitives — the panel's dropdown uses its `Menu` rather than a native `<select>`) belong to the shell's **frozen module table** (`PLATFORM_MODULES`), so they are required as baseline externals — do **not** list them under `dsh.client.external` (that field is only for non-baseline requests answered by a dynamic package row), and never inline host UI, which would fork both its styling and its upgrade behavior;
- **Official extension points**: `ctx.effect` (lifecycle), `webServer.tapIndex` (randomUUID and authenticated LAN trust injection), `ctx.slots` (client UI), `ctx.emit` (security events), `dsh.bundle` (composition patch);
- **basePath sub-path deployment**: the gateway strips the `basePath` prefix before routing (with a boundary check, so `/dsh2/foo` is not mistaken for the `/dsh` prefix), prepends it to 302 redirects, and strips it again when forwarding upstream; PWA metadata (`manifest.webmanifest` / `favicon.svg`) and static assets (`/assets/*`) pass through without authentication (browser sub-resource requests, no sensitive data);
- **Client trust timing**: an index script flips `isLoopback` while connection registers, before Settings makes its persistence decision; this is the project's documented security exception;
- **Settings nav order**: a `settings.section` registration's `order` must be strictly greater than every official section; `tests/client-contract.test.mjs` asserts this invariant;
- **The one outbound request, off by default**: `lib/update-check.js` queries the public npm registry for the `latest` tag behind the panel's "check for updates" action (the version number and repository link come from the local `package.json` and need no network). Automatic checks are **off** by default (`updateCheck: false`), so a fresh install never calls out; exactly two things trigger a request — a user pressing the button (`GET /login-api/version?refresh=1`), or the operator enabling `updateCheck` so opening the panel checks once. The constraints are hard: **never on the auth or panel critical path**, results AND failures are cached in memory (6h success / 15min failure, plus a 5s floor on repeated manual clicks), it never throws (a failure degrades to "cannot check", never to "up to date"), and an expired result is not presented as a verdict (`lastKnown()` reports only a cache entry within its TTL). See SECURITY.md;
- **Bilingual pages**: `lib/locale.js` reads `locale.preference` from the official `settings` service, then falls back to the request's `Accept-Language` and zh; error messages are maintained in one place, `lib/errors.js` (login failures return the single `invalid-credentials` code to prevent credential enumeration);
- **Login audit**: login success/failure/logout/password change and OTP enable/disable go through the `gateway.onAuthEvent` callback to the audit log (`ctx.logger.info`, only event kind + IP + reason — never credentials) and, together with brute-force alerts (`onSecurityEvent`), are appended by lib/audit-log.js to `$DSH_HOME/auth-gateway/log/audit.log` (JSONL, daily rotation, 90-day retention; write failures only warn and never touch the auth flow) — the current dsh runtime keeps `ctx.logger` records in an in-memory buffer only, so this file is the single persistent audit record;
- **Storage**: atomic writes (temp + rename), 0600/0700, same pattern as the password; the OTP secret is stored AES-256-GCM encrypted (master key from `DSH_AUTH_GATEWAY_MASTER_KEY` or `auth-gateway/otp-master.key`, see SECURITY.md).

## Build

```bash
npm run build:client   # build the client bundle (esbuild)
npm run build:check    # rebuild and assert the artifact matches the source
npm run typecheck      # JSDoc type check (tsc --noEmit --checkJs; host service declarations in types/dsh-host.d.ts)
npm run check          # syntax check (lib/*.js) + type check + full test suite
npm test               # full test suite
npm run deploy         # deploy pipeline (syntax → types → tests → sync → post-install verification)
```

The client build artifacts (`client/index.js` + `.map`) are committed, but `build:check` keeps them consistent — after changing the JSX source you must rebuild.

## Development statistics

This project was developed and tested by **DeepSeek Harness (dsh)**. The early development session (password-gate phase, model `deepseek-v4-flash`):

| Metric | Value |
|---|---|
| Development time | ~93 minutes |
| Turns | 20 |
| Steps | 381 |
| Tool calls | 393 |
| Input tokens (new) | 206,172 |
| Cached tokens (KV cache) | 95,108,864 |
| Cache hit rate | 99.8% |
| Output tokens | 243,803 (of which reasoning 121,760) |
| Total tokens (input + output) | ≈ 95.56 million |

> Note: cache-hit data comes from the prefix-cache (KV cache) metric returned by the model provider; the high hit rate stems from stable reuse of the input prefix across steps in a long session. The OTP phase (incl. security review and cross-repo PR collaboration) is counted separately and not included in the table above.

## Version history

- `0.5.0`: bilingual reset/uninstall commands; bilingual deployment docs (DEPLOYMENT / NGINX-DEPLOYMENT); docs maintenance;
- `0.4.2`: basePath sub-path deployment (route/redirect/forward stripping + PWA/static-asset pass-through), login audit logs, unified login-failure error + centralized page error dictionary (lib/errors.js), bilingual deployment docs;
- `0.4.1`: authenticated LAN browser settings support (loopback-trusted, PR #7);
- `0.4.0`: OTP secret encrypted at rest with AES-256-GCM (master key from `DSH_AUTH_GATEWAY_MASTER_KEY` or an auto-generated `otp-master.key`);
- `0.3.1`: enable OTP from the settings panel without a deployment switch; revoke all sessions on activation;
- `0.3.0`: gateway pages follow the dsh language (preference > Accept-Language > zh), settings-panel i18n, bilingual first-run console notice;
- `0.2.0`: OTP two-factor authentication (TOTP + backup codes + QR), layered brute-force protection, client settings panel, security-review fixes (re-verification, replay protection, rate limiting);
- `0.1.0`: password gate (set/login/change password, password policy, failure lockout, global rate limit, security events).