docs: add TODO with apidoc->OpenAPI/Redoc and openpgp v6 projects
This commit is contained in:
phil
@@ -0,0 +1,141 @@
|
||||
# apxtri TODO — Version Upgrade Projects
|
||||
|
||||
> Status: **planned, not started**.
|
||||
> Two independent projects to be managed separately (do not mix them).
|
||||
>
|
||||
> Context: raised during the dev1 fresh-install session (2026-08). "Point 4"
|
||||
> (npm audit fixes) is **done**: nodemailer@9, sharp@0.35, markdown-it@14.3 and a
|
||||
> patched `tar@7` override are committed in `package.json`. The two projects below
|
||||
> remain open.
|
||||
|
||||
---
|
||||
|
||||
## Project 1 — API documentation migration: `apidoc` → **OpenAPI 3 + Redoc**
|
||||
|
||||
> Decision: **OpenAPI 3.x** (spec) + **swagger-jsdoc** (in-code parser) + **Redoc**
|
||||
> (opensource viewer, Apache-2.0).
|
||||
|
||||
### Why
|
||||
- `apidoc@1.2.0` is the **latest release** but its dependency tree is outdated and
|
||||
is the source of the **6 remaining npm vulnerabilities** (build-time only):
|
||||
- `bootstrap@3.4.1` (self-XSS in the docs UI)
|
||||
- `esbuild` / `esbuild-loader` (dev-server SSRF)
|
||||
- `markdown-it@12` + `linkify-it@3` (DoS)
|
||||
- OpenAPI 3 is the industry **standard**: validation, client/SDK generation, active
|
||||
ecosystem.
|
||||
- **Same philosophy as apidoc**: documentation lives in JSDoc comments inside the
|
||||
route files → no architectural rewrite, **incremental migration**.
|
||||
|
||||
### Target
|
||||
- `swagger-jsdoc` parses `@openapi` (YAML) blocks in `routes/*.js` +
|
||||
`middlewares/*.js` → generates an `openapi.json` spec.
|
||||
- A **Redoc** webapp (standalone bundle `redoc.standalone.js`, single-file) loads the
|
||||
spec → replaces the current `wwws/apidoc` webapp.
|
||||
- `apxtri.js` `_ensureApidocOrder()` (which prefixes `@apiGroup` according to
|
||||
`apidocorderturnaround`) → replaced by tag ordering in the Redoc spec
|
||||
(`x-tagGroups` / `x-displayName`).
|
||||
|
||||
### Annotation mapping (mechanical migration)
|
||||
|
||||
| apidoc (current) | OpenAPI (`@openapi` YAML) |
|
||||
|---|---|
|
||||
| `@api {get} /path` | `paths:` → `get:` + `path:` |
|
||||
| `@apiName` | `operationId` |
|
||||
| `@apiGroup` | `tags` |
|
||||
| `@apiVersion` | `info.version` (top-level) |
|
||||
| `@apiDescription` | `description` |
|
||||
| `@apiHeader` | `parameters: [ { in: header } ]` |
|
||||
| `@apiParam` (path/body) | `parameters` / `requestBody` |
|
||||
| `@apiSuccess` | `responses: '200'` |
|
||||
| `@apiSuccessExample` | `responses...examples` |
|
||||
| `@apiError` / `@apiErrorExample` | `responses: '4xx'/'5xx'` |
|
||||
|
||||
### Steps
|
||||
1. **Dependencies**: add `swagger-jsdoc` (+ serve the `redoc` standalone bundle);
|
||||
remove `apidoc` at the end of the migration.
|
||||
2. **Base spec**: `info`, `servers`, and `securitySchemes` for
|
||||
`checkHeaders`/`isAuthenticated` headers (`xalias`, `xdays`, `xhash`, `xtribe`,
|
||||
`xlang`).
|
||||
3. **Migrate route group by route group**: `towns`, `pagans`, `nations`,
|
||||
`blockchain`, `corelock`, `odmdb`, `wwws`, `alerts`, `tribes`, …
|
||||
4. **Conversion script** `@api` → `@openapi` (from the mapping table) to speed up;
|
||||
allow `apidoc` + `openapi` to coexist during the transition.
|
||||
5. **Generation**: produce the spec at server startup (like `_ensureApidocOrder`)
|
||||
or at build time; write to `{DATAPATH}/{tribe}/wwws/apidoc/openapi.json`.
|
||||
6. **Redoc webapp**: replaces `wwws/apidoc` (keep `appconf.json` `dns`/path),
|
||||
loads `openapi.json`.
|
||||
7. **Validation**: Redoc rendering + spec validation (e.g. `redocly lint`, or
|
||||
`@apidevtools/swagger-cli validate`).
|
||||
8. **Cleanup**: remove `apidoc` → clears the 6 residual build-time vulnerabilities.
|
||||
9. **Docs**: update `AGENTS.md` (annotation convention) + README.
|
||||
|
||||
### Risks / attention points
|
||||
- **YAML indentation** inside comments (frequent error) → swagger-jsdoc fails
|
||||
silently if malformed.
|
||||
- **Authentication**: the required headers (checkHeaders/isAuthenticated) must be
|
||||
documented, otherwise endpoints look public.
|
||||
- **Redoc is read-only** (no "try it"); if interactive testing is needed, use
|
||||
**Swagger UI** instead (same spec, no extra cost).
|
||||
- **`apidocorderturnaround`**: the configured group order must be carried over to
|
||||
Redoc tags (otherwise it is lost).
|
||||
- **Wildcard** (`/*`) and protected routes must be documented explicitly.
|
||||
- **Volume**: many routes → progressive migration, validate per group.
|
||||
|
||||
### Alternatives (considered / rejected)
|
||||
- **Swagger UI**: enables "try it" — prefer it if that need exists (otherwise Redoc,
|
||||
cleaner).
|
||||
- **Scribe**: PHP/Laravel (not applicable).
|
||||
- **tsoa / nestjs/swagger**: TypeScript (too heavy a change).
|
||||
- **Postman collections**: loses the in-code documentation.
|
||||
|
||||
---
|
||||
|
||||
## Project 2 — Migration `openpgp v5 → v6`
|
||||
|
||||
> Independent project. Do not mix with Project 1.
|
||||
|
||||
### Why
|
||||
- Direct dependency `openpgp: ^5.10.1` (installed 5.11.3) — **end of life, no more
|
||||
security patches** (npm deprecation warning).
|
||||
- Current npm latest line: `openpgp@^6` (6.3.x).
|
||||
|
||||
### Impact
|
||||
Used in: `models/Pagans.js`, `models/Blockchain.js`, `models/CoreLock.js`,
|
||||
`models/APX3.js`, `models/UptimeTracker.js`, `models/Tribes.js`,
|
||||
`routes/alerts.js` + unittests `Pagansunittest.js`, `CoreLockunittest.js`.
|
||||
|
||||
v5 API in use: `generateKey`, `readKey(s)`, `readPrivateKey`, `readSignature`,
|
||||
`readCleartextMessage`, `createMessage`, `createCleartextMessage`, `decryptKey`,
|
||||
`sign`, `verify`.
|
||||
|
||||
### Steps
|
||||
1. Feature branch (branch model Part F: `features/*` → `develop`).
|
||||
2. Bump `openpgp@^6` in `package.json`.
|
||||
3. Adapt the API calls (v6 changed signatures: `generateKey`, `readKey`,
|
||||
`sign`/`verify`, `decrypt` — different return objects).
|
||||
4. Adapt and **re-run the unit tests**:
|
||||
`node models/unittest/Pagansunittest.js` and
|
||||
`node models/unittest/CoreLockunittest.js`.
|
||||
5. Compatibility tests: key generation, sign/verify, encrypt/decrypt, cleartext
|
||||
(threads).
|
||||
6. **Verify reading existing keys/messages** (backward compatibility of data
|
||||
already stored).
|
||||
7. Verify the blockchain still validates **historical signatures**.
|
||||
8. Commit + push (governance) → `update.sh` on the towns.
|
||||
|
||||
### Risks
|
||||
- API heavily changed → significant effort, do it **in isolation** (not with
|
||||
Project 1).
|
||||
- Backward compatibility of existing PGP keys and on-chain signatures must be
|
||||
confirmed.
|
||||
|
||||
---
|
||||
|
||||
## Cross-cutting reminders
|
||||
- After both projects, `npm audit` should be at **0 vulnerabilities**.
|
||||
- Keep `allowScripts` in `package.json` up to date if bcrypt/sharp/esbuild change
|
||||
versions.
|
||||
- `package-lock.json` is now versioned (un-ignored 2026-08) — keep it in sync on
|
||||
every dependency change.
|
||||
- Push to gitea required to distribute (nation zero is `warn` policy → direct push
|
||||
possible; production → sages process, Part F).
|
||||
Reference in New Issue
Block a user