Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/security/route-access-inventory.md
T

114 lines
33 KiB
Markdown

# Route Access Inventory
This document publishes the checked Hono API route access classification from `apps/api/src/route-access-inventory.ts`. It is a static security review aid only: it records route boundaries, access classes, rationale, and redacted data-sensitivity notes without changing route handlers, OpenAPI metadata, authorization middleware, or runtime behavior.
Historical-plan note: route keys and access classes in this document are
current only when the focused verification below passes. Do not copy route
paths from older improvement-plan files into this inventory without confirming
the typed source of truth.
## Scope and Source of Truth
- Source of truth: `apps/api/src/route-access-inventory.ts`.
- Scanner reference: `tools/api-inventory/scan-api-routes.ts` discovers `app.get/post/patch/delete` route registrations from `apps/api/src/app.ts` for coverage checks.
- Verification: `apps/api/src/route-access-inventory.test.ts` checks scanner-discovered route coverage and OpenAPI security expectations; `apps/api/src/route-access-inventory-doc.test.ts` checks this document for drift.
- Route keys are written as `METHOD path` and must match the typed inventory exactly once.
- This inventory covers all current Hono API routes, including health, documentation, authentication, analytics, platform-lead ingestion, accounts, usage, notifications, workspaces, entity, relationship, export, webhook, and maintenance surfaces.
- Adjacent coverage: `docs/security/csrf-inventory.md` documents CSRF posture and mutating API route classes. This document references that coverage but does not duplicate its mutating-route-only table.
## Redaction Rules
- Do not include tokens, plaintext credentials, fixture tenant identifiers, customer data, environment variable values, or concrete database identifiers.
- Keep sensitive-data notes categorical and redacted, for example “returns aggregate counts” or “consumes uploaded file content.”
- Do not paste authorization headers, JWTs, API keys, passwords, emails, tenant fixtures, or customer examples into this document.
- Route parameters such as `:entity`, `:rowId`, and `:id` are schema placeholders, not real identifiers.
## Access Class Legend
| Class | Boundary |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `public-health` | Unauthenticated infrastructure health or readiness endpoint exposing only service/dependency status metadata. |
| `public-docs` | Unauthenticated API documentation or schema discovery surface exposing schema metadata only. |
| `service-token` | Service/API-token style boundary, including stored API key or service credential checks where implemented. |
| `platform-source-credential` | Pre-tenant platform-lead boundary using a rotatable, source-scoped bearer capability that selects only its configured source. |
| `service-or-tenant-api-key` | Service credential or tenant-bound stored API-key boundary with route-specific tenant and permission checks. |
| `optional-api-key-validation` | Public validation helper that optionally accepts a presented stored API key or service token and returns redacted validation status. |
| `tenant-api-key` | Tenant-bound stored API-key boundary where the credential scopes the tenant and available usage metadata. |
| `tenant-webhook-credential` | Tenant-bound incoming webhook credential boundary using a stored API key, hashed webhook token, or HMAC signature tied to a tenant endpoint. |
| `provider-body-token-webhook` | Provider webhook ingress authenticated by a bounded write-only token in the request body, resolved through a stored hash and re-verified against the encrypted connection credential before tenant-bound processing. |
| `provider-header-token-webhook` | Provider webhook ingress authenticated by a bounded write-only bearer token in a request header, resolved through a stored hash and re-verified against the encrypted connection credential before tenant-bound processing. |
| `provider-hmac-webhook` | Provider webhook ingress authenticated with the provider-specific HMAC contract over the exact bounded request body before identity context binding or persistence. |
| `jwt-auth` | Bearer JWT authenticated user boundary. |
| `auth-credential-exchange` | Public credential exchange that consumes submitted credentials and issues authenticated API state after validation. |
| `public-analytics-token` | Browser-facing anonymous analytics ingestion capability; it never authorizes analytics reads or identity attribution. |
| `public-analytics-overview` | Unauthenticated tenantless aggregate read enabled only by the operator-controlled public analytics setting and isolated platform analytics RLS context. |
| `webhook-signature` | Signed webhook ingress boundary that verifies provider signing headers before processing an addressed webhook retry. |
| `provider-refetch-webhook` | Provider webhook ingress that trusts only an opaque provider object id, refetches the authoritative record from the provider server-side, and syncs redacted tenant-scoped metadata instead of the posted payload. |
| `canonical-redirect` | Runtime-only compatibility shim that redirects removed API-prefix requests to the canonical API path without reading request data. |
## Full Route Access Table
| Route | Access class | Sensitive data note | Rationale |
| -------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /healthz` | `public-health` | No sensitive data. | Unauthenticated liveness probe returns only service status and request correlation metadata. |
| `GET /readyz` | `public-health` | Dependency health state is exposed without implementation details. | Unauthenticated readiness probe returns redacted dependency status for infrastructure checks. |
| `GET /v1/health` | `public-health` | No sensitive data. | Versioned liveness probe returns only service status and request correlation metadata. |
| `GET /v1/openapi.json` | `public-docs` | No sensitive data. | OpenAPI discovery is intentionally public for client integration and contains schema metadata only. |
| `GET /v1/docs` | `public-docs` | No sensitive data. | Documentation shell is intentionally public and renders the OpenAPI document without runtime data. |
| `GET /v1/session/current-user` | `service-token` | Returns authenticated principal type metadata only. | Current service principal endpoint requires a bearer service token before returning authentication state. |
| `POST /v1/auth/login` | `auth-credential-exchange` | Consumes credentials and returns a JWT plus basic user identity. | Login exchanges submitted email and password credentials for a short-lived JWT after password verification. |
| `POST /v1/auth/refresh-token` | `jwt-auth` | Returns a JWT plus basic user identity. | Refresh requires an existing bearer JWT before issuing a replacement token for the same user. |
| `POST /v1/auth/logout` | `jwt-auth` | Consumes JWT credential material but returns only a success envelope and expired cookie attributes. | Logout requires an existing bearer JWT before revoking the active API session and clearing the API cookie. |
| `POST /v1/api-keys/validate` | `optional-api-key-validation` | Returns redacted stored API-key metadata but never plaintext key material. | API-key validation optionally accepts a presented stored API key or service token and reports redacted validation status without requiring a prior credential. |
| `POST /v1/platform/leads` | `platform-source-credential` | Consumes bounded platform lead contact and attribution data while omitting source capability material and submitted lead data from responses and diagnostics. | Platform lead ingestion requires a rotatable, source-scoped bearer capability; the authenticated capability selects the configured source and is revalidated atomically during pre-tenant persistence. |
| `POST /v1/support/inbound-email` | `webhook-signature` | Consumes signed email metadata and message body while omitting provider payloads and signing material from responses. | Inbound support email verifies Mailjet webhook signing headers before resolving tenant inbound addresses and creating tickets. |
| `POST /v1/email/inbound-mailjet` | `webhook-signature` | Consumes signed email metadata and message body while omitting provider payloads, recipient content, and signing material from responses. | Tenant inbound email verifies Mailjet webhook signing headers before resolving tenant inbound addresses and creating lead/activity records. |
| `POST /v1/analytics/events` | `public-analytics-token` | Consumes an anonymous analytics identifier, URLs, routes, and event labels; authenticated user and portal identifiers are rejected. | Analytics event ingestion accepts only a bounded anonymous visitor identifier and writes tenantless records in the isolated platform analytics RLS context. |
| `POST /v1/analytics/page-views` | `public-analytics-token` | Consumes an anonymous analytics identifier, URLs, and route names; authenticated user and portal identifiers are rejected. | Analytics page-view ingestion accepts only a bounded anonymous visitor identifier and writes tenantless records in the isolated platform analytics RLS context. |
| `GET /v1/analytics/public` | `public-analytics-overview` | Returns tenantless aggregate analytics counts and top-level chart data without user, tenant, or portal attribution. | Public analytics is enabled only by the operator-controlled setting and returns tenantless global aggregates from the isolated platform analytics RLS context. |
| `GET /v1/analytics/admin` | `service-token` | Returns global tenantless aggregates or aggregate metrics for an explicitly tenant-bound portal scope. | Admin analytics requires service credentials plus an operator user identifier verified through the RLS-protected AdminUser row; optional portal reads require an exact tenant and portal pair. |
| `GET /v1/notifications/stream` | `service-token` | Returns bounded, sanitized notification delivery snapshots and cursors without provider payloads, metadata, or raw delivery secrets. | Notification stream requires service credentials before returning tenant and user scoped in-app delivery diagnostics over SSE. |
| `GET /v1/accounts` | `service-token` | Returns tenant identifiers, names, slugs, icons, and subscription summary fields without plaintext secrets. | Account listing requires service credentials before returning tenant account metadata and subscription summaries. |
| `GET /v1/accounts/:id` | `service-token` | Returns tenant identifiers, names, slugs, icons, and subscription summary fields without plaintext secrets. | Account lookup requires service credentials before returning one tenant account metadata and subscription summary. |
| `GET /v1/usage` | `tenant-api-key` | Returns plan and remaining API usage metadata for the credential-scoped tenant. | Usage lookups enter through the canonical API host and validate tenant API-key credentials in the API runtime. |
| `GET /v1/contacts` | `tenant-api-key` | Returns redacted contact fields for the credential-scoped tenant; internal notes and credential material are omitted. | Public API contact reads validate a tenant-bound API-key credential before querying only that credential's tenant scope. |
| `GET /v1/companies` | `tenant-api-key` | Returns redacted organisation contact fields for the credential-scoped tenant; internal notes and credential material are omitted. | Public API company reads validate a tenant-bound API-key credential before querying only that credential's tenant scope. |
| `GET /v1/deals` | `tenant-api-key` | Returns redacted sales-pipeline project fields for the credential-scoped tenant; internal notes and credential material are omitted. | Public API deal reads validate a tenant-bound API-key credential before querying only that credential's tenant scope. |
| `GET /v1/projects` | `tenant-api-key` | Returns redacted project fields for the credential-scoped tenant; internal notes and credential material are omitted. | Public API project reads validate a tenant-bound API-key credential before querying only that credential's tenant scope. |
| `GET /v1/tasks` | `tenant-api-key` | Returns redacted task fields for the credential-scoped tenant; internal notes and credential material are omitted. | Public API task reads validate a tenant-bound API-key credential before querying only that credential's tenant scope. |
| `GET /v1/leads` | `tenant-api-key` | Returns redacted lead-inbox fields for the credential-scoped tenant; raw payloads, anti-spam internals and credential material are omitted. | Public API lead reads validate a tenant-bound API-key credential before querying only that credential's tenant scope. |
| `POST /v1/webhooks/incoming/:tenant/:slug` | `tenant-webhook-credential` | Consumes third-party lead payloads and stores redacted ingestion metadata; API keys, webhook tokens, HMAC material and raw signing secrets are omitted from responses. | Incoming public webhooks enter through the canonical API host, resolve the tenant endpoint, validate the endpoint credential mode and create only tenant-scoped lead intake records. |
| `POST /v1/webhooks/telephony/aircall` | `provider-body-token-webhook` | Consumes bounded call lifecycle metadata and a write-only provider token; responses disclose no tenant, credential, rate-limit, or deduplication state. | Aircall webhook ingress authenticates the provider-issued body token against its stored hash, resolves exactly one tenant connection, and re-verifies the encrypted connection credential before RLS-scoped persistence. |
| `POST /v1/webhooks/telephony/hallopetra` | `provider-header-token-webhook` | Consumes bounded post-call metadata and a write-only webhook secret; responses disclose no tenant, credential, rate-limit, or deduplication state, and native transcripts are not persisted. | HalloPetra webhook ingress authenticates the dedicated bearer secret against its stored hash, resolves exactly one tenant connection, and re-verifies the encrypted connection credential before RLS-scoped persistence. |
| `POST /v1/webhooks/admin-telephony/aircall` | `provider-body-token-webhook` | Consumes bounded call lifecycle metadata and a write-only provider token; neutral responses disclose no AdminUser, connection, credential, rate-limit, or deduplication state. | Admin Aircall webhook ingress authenticates the provider-issued body token against its stored hash, resolves one active AdminUser connection, and binds that AdminUser RLS context before idempotent persistence. |
| `POST /v1/billing/lago/webhooks` | `provider-hmac-webhook` | Consumes tenant-scoped subscription lifecycle metadata while responses omit customer identifiers, provider object identifiers, payloads, and signing material. | Lago billing webhook ingress verifies the provider HMAC over the exact request body before binding the embedded customer tenant and applying replay-safe subscription state changes. |
| `POST /v1/billing/mollie/webhooks` | `provider-refetch-webhook` | Consumes a provider payment id and stores redacted billing lifecycle metadata without returning provider payloads or plaintext credentials. | Mollie billing webhook ingress accepts only the provider payment id, refetches that payment from Mollie server-side, and syncs only tenant-scoped billing metadata from the verified payment. |
| `POST /v1/email-sequences/mailjet/webhooks` | `webhook-signature` | Consumes signed delivery event metadata while responses omit provider payloads, recipient data, and signing material. | Email-sequence provider webhooks verify Mailjet signing headers before correlating bounce events to provider message ids. |
| `POST /v1/admin-sales/email/provider-events` | `provider-hmac-webhook` | Consumes bounded delivery and engagement metadata while responses omit recipient data, provider payloads, signing material, and AdminUser identifiers. | Provider-neutral admin email events require a timestamp-bound HMAC over the exact request body before an AdminUser RLS context is bound and an idempotent event is persisted. |
| `POST /v1/admin-sales/email/bcc-inbound` | `webhook-signature` | Consumes bounded email headers and bodies while responses omit message content, recipient capability material, signing material, and AdminUser identifiers. | Admin BCC ingestion requires provider authentication and one exact signed, rotatable BCC capability before binding the embedded AdminUser RLS context. |
| `GET /v1/workspaces/:tenantId/auth/providers` | `service-token` | Returns redacted OIDC/SAML provider metadata only; client secrets, SAML certificate bodies, private keys, token hashes, invite tokens, and raw metadata documents are omitted. | Workspace auth-provider discovery requires a service token before returning tenant-scoped SSO metadata. |
| `POST /v1/workspaces/:tenantId/context/revalidate` | `service-token` | Consumes tenant and user identifiers and returns a redacted validity envelope without provider secrets, invite tokens, token hashes, or SSO secret material. | Workspace context revalidation requires a service token before confirming tenant/user membership for a context switch. |
| `GET /v1/workspaces/:tenantId/invites` | `service-token` | Returns invite recipient details, lifecycle timestamps, audit user ids, and tokenPrefix only; plaintext tokens and token hashes are omitted. | Workspace invite listing requires a service token before returning tenant-scoped invite lifecycle state. |
| `POST /v1/workspaces/:tenantId/invites` | `service-token` | Consumes invite recipient details and returns the one-time plaintext invite token only in the create response. | Workspace invite creation requires a service token before issuing a tenant-scoped invite token. |
| `POST /v1/workspaces/:tenantId/invites/:inviteId/accept` | `service-token` | Consumes plaintext invite token and returns redacted invite lifecycle metadata without echoing the token. | Workspace invite acceptance requires a service token and a one-time invite token before finalizing tenant membership invitation state. |
| `POST /v1/workspaces/:tenantId/invites/:inviteId/revoke` | `service-token` | Consumes revoke audit metadata and returns redacted invite lifecycle metadata without token material. | Workspace invite revocation requires a service token before finalizing the tenant-scoped invite as revoked. |
| `POST /v1/events/webhooks/attempts/:id` | `webhook-signature` | Consumes signed webhook delivery metadata and an attempt id while omitting provider payloads and signing material from responses. | Webhook retry verifies Mailjet webhook signing headers before looking up or queueing a known delivery attempt. |
| `POST /v1/maintenance/export-retention/enqueue` | `service-token` | Consumes an optional bounded batch size and returns only queue task metadata plus request correlation. | Export artifact retention cleanup is an operator maintenance action and requires service credentials before enqueueing work. |
| `GET /v1/exports/:exportJobId/download-url` | `service-or-tenant-api-key` | Returns a signed artifact URL envelope without artifact bucket/key values, storage credentials, pause reason internals, filters, or object bodies. | Export download URL creation requires service credentials or a tenant-bound stored API key and blocks compliance-paused exports before returning a short-lived signed artifact URL envelope. |
| `GET /v1/exports/:exportJobId/progress` | `service-or-tenant-api-key` | Returns export progress envelope (status, percent, rowCount) — no artifact URLs, no compliance-pause internals, no filters. | Export progress polling requires service credentials or a tenant-bound stored API key; the handler scopes lookups to the caller's tenant and never leaks artifact bucket/key details. |
| `POST /v1/devices/register` | `jwt-auth` | Persists a sensitive device-bound push token; the response contains registration metadata only and never returns the raw token. | Derives the owner exclusively from a verified active API-session JWT; body/header identity overrides are rejected and an optional tenant is membership-revalidated before tenant/user RLS binding. |
| `POST /v1/devices/revoke` | `jwt-auth` | Foreign user or tenant tokens are treated as not found; the response never echoes the raw token or provider internals. | Derives the owner exclusively from a verified active API-session JWT; an optional tenant is membership-revalidated before the ownership-constrained RLS write. |
| `GET /status` | `public-health` | Boolean health state and deployment region tag only — no connection strings, hostnames or stack traces. | Unauthenticated status probe for external uptime monitors. Returns boolean-only health, revision, region, uptime. |
| `GET /metrics` | `service-token` | Prom text-format counters and gauges — includes business KPIs (AI tokens, mail, webhook, queue depth). Token-protected. | Prometheus scrape endpoint requires bearer METRICS_TOKEN. Returns 404 when METRICS_ENABLED is false. |
## Verification Commands
Run focused verification from the repository root after changing Hono routes, OpenAPI security metadata, the typed route access inventory, or this document:
```bash
pnpm exec vitest run apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts
pnpm exec eslint apps/api/src/route-access-inventory.ts apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts --max-warnings=0
```
Expected diagnostics name stale or missing route keys in `METHOD path` form, OpenAPI security drift, redaction matches, and missing required section headings by heading text.