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

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.