Initial Commit

openspec/archive/2026-05-19-document-site-middleware-integration/proposal.md

@@ -0,0 +1,53 @@
+# Document site middleware integration
+
+**Package**: `@suaveplan/api-plugin-site`
+**Status**: PROPOSED
+**Type**: spec-modification (no new runtime deps)
+
+- **Spec delta**: ./specs/api-plugin-site/spec.md
+
+## Why
+
+The initial `@suaveplan/api-plugin-site` migration (archived 2026-05-19) explicitly excluded JWT / permissions / rate-limit / audit middleware wiring with the following justification:
+
+> JWT / permissions / rate-limit / audit middleware wiring — depends on `@suaveplan/api-plugin-rate-limit` + `@suaveplan/api-plugin-audit` already landed in genesis, but the integration knob is the host app's `app.use(prefix, middleware)` Hono pattern. The site plugin does NOT hard-depend on them so excluding integration from THIS migration does not block consumers from layering them on top.
+
+Both sibling plugins now ship on genesis. The exclusion remains correct in spirit — the site plugin must NOT hard-depend on them so consumers can swap implementations or skip them entirely — but the integration pattern itself is currently undocumented and unverified. Consumers wiring the three packages together today must reconstruct the pattern from first principles and have no test fixture proving the composition works.
+
+This change closes the gap **through documentation + a runnable integration test**, not through new runtime dependencies. The site plugin keeps zero runtime deps on `api-plugin-rate-limit` and `api-plugin-audit`; those packages become `devDependencies` consumed solely by a new integration test that boots the canonical composed-host configuration and asserts (a) site behaviour is unchanged, (b) rate-limit headers appear on responses, (c) audit events are emitted into the in-memory sink.
+
+## What changes
+
+- ADDED: `src/integration/middleware-composition.integration.test.ts` — boots a Hono app with `createSitePlugin` route trees, layered under `rateLimit(...)` and `createAuditMiddleware(...)`, exercises a write route, asserts the four observable outcomes (status, site row persisted, `X-RateLimit-*` headers, audit `events.length === 1`).
+- ADDED: `MIDDLEWARE_RECOMMENDATIONS` — readonly typed bundle (`MiddlewareRecommendation[]`) describing recommended rate-limit windows and audit categories per site route group (public resolve, public read, private write). Pure data; callers consume it to derive their middleware configuration. Not bound by the site plugin itself.
+- ADDED: `src/integration/middleware-recommendations.ts` (+ sibling `.md`) — exports the recommendations bundle and the `MiddlewareRecommendation` type.
+- ADDED: `docs/middleware-integration.md` — package-level guide with the canonical `app.use(prefix, middleware)` Hono sequence, the recommended layering order (audit OUTERMOST → rate-limit MIDDLE → site routes INNERMOST), justification, and a copy-pasteable example.
+- MODIFIED: `src/routes/private-routes.md` — appends a "Recommended middleware" section pointing at `MIDDLEWARE_RECOMMENDATIONS` and explaining why write routes benefit most from both layers.
+- MODIFIED: `README.md` — adds a "Middleware composition" subsection linking to `docs/middleware-integration.md` and `MIDDLEWARE_RECOMMENDATIONS`.
+- MODIFIED: `package.json` — adds `@suaveplan/api-plugin-rate-limit` and `@suaveplan/api-plugin-audit` as **devDependencies only** (consumed by the integration test). NO runtime-dep change.
+- MODIFIED: `src/index.ts` — re-exports `MIDDLEWARE_RECOMMENDATIONS` and `MiddlewareRecommendation`.
+
+### Source mapping
+
+| Concern | New file | Notes |
+|---|---|---|
+| Composed-host integration proof | `src/integration/middleware-composition.integration.test.ts` | Real `rateLimit` middleware + real `createAuditMiddleware` + real `createPrivateSiteRoutes` against in-memory site DB. No mocks. |
+| Typed recommendations consumable by callers | `src/integration/middleware-recommendations.ts` | Pure data + types; zero runtime dep on the middleware plugins. |
+| Package-level guide | `docs/middleware-integration.md` | Allowed exception — explicit docs subfolder permitted per the §0 task brief; supplements the README. |
+| Feature-doc cross-reference | `src/routes/private-routes.md` (modified) | Adds "Recommended middleware" section. |
+
+### Excluded from this change
+
+- JWT / permissions wiring — `api-plugin-auth` has shipped its first chain but the broader permissions plugin family is still in flight; documenting auth integration would risk inverting the dep ordering. Will be revisited once the permissions plugin ships.
+- Hard runtime deps on `api-plugin-rate-limit` / `api-plugin-audit` — explicitly prohibited by §0 task brief and by the original exclusion rationale (composition stays in the host).
+- Helper factory that wires all three plugins together (e.g. `createComposedSiteHost(...)`) — would be either redundant (one-liner around `app.use`) or premature abstraction; the documented pattern + integration test cover the need.
+
+## Migration
+
+No public-API breakage. Consumers already wiring middleware around the site plugin keep their current code; they MAY adopt `MIDDLEWARE_RECOMMENDATIONS` for typed limits but are not required to. The two new packages are devDependencies, so consumer installs are unaffected.
+
+## Impact
+
+### Affected dependents
+
+`bunx turbo ls --filter=...@suaveplan/api-plugin-site` returns zero downstream consumers on genesis (this is still the first landing wave). No dependent sweep required.