Initial Commit

packages/api-stack/api/api-plugin-site/src/routes/private-routes.md

@@ -0,0 +1,53 @@
+# `routes/private-routes.ts`
+
+## Purpose
+
+Builds the authenticated Hono route tree for site CRUD and domain management. The factory is intentionally auth-agnostic — the suaveplan convention is that the host application composes auth middleware (`requireAuth()` from `@suaveplan/api-plugin-auth` or any equivalent) at the prefix where this router is mounted. Decoupling auth from the route factory keeps the package usable by any consumer (e.g. a future GraphQL gateway, an admin CLI) without forcing a hard dependency on a specific auth plugin.
+
+## Features
+
+- `POST /sites` — create.
+- `PATCH /sites/{id}` — update name / settings.
+- `POST /sites/{id}/domains` — add domain.
+- `DELETE /sites/{id}/domains` — remove domain.
+- OpenAPI schemas embedded inline via `@hono/zod-openapi` so the generated spec is the contract.
+- Errors propagate as `SiteError` (caught and rendered by the host's global error middleware).
+
+## Usage: Basic
+
+```ts
+import { createPrivateSiteRoutes } from "@suaveplan/api-plugin-site/routes/private-routes";
+
+const privateRouter = createPrivateSiteRoutes({ siteService });
+app.use("/api/v1", requireAuth());
+app.route("/api/v1", privateRouter);
+```
+
+## Usage: Advanced
+
+```ts
+// Layer additional rate-limit + audit middleware on top.
+const privateRouter = createPrivateSiteRoutes({ siteService });
+app.use("/admin", requireAuth(), rateLimit({ key: "site-mutations" }));
+app.route("/admin", privateRouter);
+```
+
+## API Reference
+
+- `interface PrivateSiteRoutesDeps` — `siteService`.
+- `createPrivateSiteRoutes(deps: PrivateSiteRoutesDeps): OpenAPIHono`.
+
+## Recommended middleware
+
+Write routes benefit most from layered rate-limit + audit middleware. The site plugin ships the `MIDDLEWARE_RECOMMENDATIONS` constant (see `src/integration/middleware-recommendations.md`) describing the recommended ceiling and audit category for this group:
+
+- **Rate-limit**: `30 req / 60s` on the `/sites/*` path pattern (`private:write` group). Writes are rare per tenant and warrant the tightest ceiling; this protects the database from runaway clients without inconveniencing legitimate operators.
+- **Audit category**: `data.mutation`. Every successful or failed write produces one `AuditEvent` in the host's configured `AuditStorageAdapter`. Combine with `enableChainIntegrity: true` for a tamper-evident trail.
+
+The recommended layering order — audit OUTERMOST, rate-limit MIDDLE, site routes INNERMOST — is documented end-to-end in `docs/middleware-integration.md` and proven by `src/integration/middleware-composition.integration.test.ts`. The site plugin does not bind either middleware itself; composition stays in the host via the Hono `app.use(prefix, middleware)` pattern.
+
+## Implementation Notes
+
+- The factory accepts a single deps object so future additions (audit, event bus) stay non-breaking.
+- All bodies are Zod-validated via `@hono/zod-openapi` — invalid input is rejected before reaching the service.
+- The "remove domain" endpoint uses a body (not a path segment) so callers can submit the canonical-cased domain string and so the operation can be batched in future without an additional route shape.