Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/api/src/route-access-inventory.ts
T

426 lines
21 KiB
TypeScript

export const routeAccessClasses = [
"public-health",
"public-docs",
"service-token",
"platform-source-credential",
"service-or-tenant-api-key",
"optional-api-key-validation",
"tenant-api-key",
"tenant-webhook-credential",
"provider-body-token-webhook",
"provider-header-token-webhook",
"provider-hmac-webhook",
"webhook-signature",
"provider-refetch-webhook",
"jwt-auth",
"auth-credential-exchange",
"public-analytics-token",
"public-analytics-overview",
"canonical-redirect",
] as const;
export type RouteAccessClass = (typeof routeAccessClasses)[number];
export type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "ALL";
export type RouteAccessKey = `${RouteMethod} ${string}`;
export type RouteAccessInventoryEntry = {
method: RouteMethod;
path: string;
accessClass: RouteAccessClass;
rationale: string;
sensitiveData: boolean | string;
};
export function routeAccessKey(route: Pick<RouteAccessInventoryEntry, "method" | "path">): RouteAccessKey {
return `${route.method} ${route.path}`;
}
export const routeAccessInventory = [
{
method: "GET",
path: "/healthz",
accessClass: "public-health",
rationale: "Unauthenticated liveness probe returns only service status and request correlation metadata.",
sensitiveData: false,
},
{
method: "GET",
path: "/v1/health",
accessClass: "public-health",
rationale: "Unauthenticated versioned liveness probe returns only service status and request correlation metadata.",
sensitiveData: false,
},
{
method: "GET",
path: "/readyz",
accessClass: "public-health",
rationale: "Unauthenticated readiness probe returns redacted dependency status for infrastructure checks.",
sensitiveData: "Dependency health state is exposed without implementation details.",
},
{
method: "GET",
path: "/status",
accessClass: "public-health",
rationale: "Unauthenticated status probe for external uptime monitors. Returns boolean-only health, revision, region, uptime.",
sensitiveData: "Boolean health state and deployment region tag only — no connection strings, hostnames or stack traces.",
},
{
method: "GET",
path: "/metrics",
accessClass: "service-token",
rationale: "Prometheus scrape endpoint requires bearer METRICS_TOKEN. Returns 404 when METRICS_ENABLED is false.",
sensitiveData: "Prom text-format counters and gauges — includes business KPIs (AI tokens, mail, webhook, queue depth). Token-protected.",
},
{
method: "GET",
path: "/v1/openapi.json",
accessClass: "public-docs",
rationale: "OpenAPI discovery is intentionally public for client integration and contains schema metadata only.",
sensitiveData: false,
},
{
method: "GET",
path: "/v1/docs",
accessClass: "public-docs",
rationale: "Documentation shell is intentionally public and renders the OpenAPI document without runtime data.",
sensitiveData: false,
},
{
method: "GET",
path: "/v1/session/current-user",
accessClass: "service-token",
rationale: "Current service principal endpoint requires a bearer service token before returning authentication state.",
sensitiveData: "Returns authenticated principal type metadata only.",
},
{
method: "POST",
path: "/v1/auth/login",
accessClass: "auth-credential-exchange",
rationale: "Login exchanges submitted email and password credentials for a short-lived JWT after password verification.",
sensitiveData: "Consumes credentials and returns a JWT plus basic user identity.",
},
{
method: "POST",
path: "/v1/auth/refresh-token",
accessClass: "jwt-auth",
rationale: "Refresh requires an existing bearer JWT before issuing a replacement token for the same user.",
sensitiveData: "Returns a JWT plus basic user identity.",
},
{
method: "POST",
path: "/v1/auth/logout",
accessClass: "jwt-auth",
rationale: "Logout requires an existing bearer JWT before revoking the active API session and clearing the API cookie.",
sensitiveData: "Consumes JWT credential material but returns only a success envelope and expired cookie attributes.",
},
{
method: "POST",
path: "/v1/api-keys/validate",
accessClass: "optional-api-key-validation",
rationale:
"API-key validation optionally accepts a presented stored API key or service token and reports redacted validation status without requiring a prior credential.",
sensitiveData: "Returns redacted stored API-key metadata but never plaintext key material.",
},
{
method: "POST",
path: "/v1/platform/leads",
accessClass: "platform-source-credential",
rationale:
"Platform lead ingestion requires a rotatable, source-scoped bearer capability; the authenticated credential selects the configured source and is revalidated atomically during pre-tenant persistence.",
sensitiveData:
"Consumes bounded platform lead contact and attribution data while omitting source capability material and submitted lead data from responses and diagnostics.",
},
{
method: "POST",
path: "/v1/support/inbound-email",
accessClass: "webhook-signature",
rationale: "Inbound support email verifies Mailjet webhook Basic-Auth credentials before resolving tenant inbound addresses and creating tickets.",
sensitiveData: "Consumes signed email metadata and message body while omitting provider payloads and signing material from responses.",
},
{
method: "POST",
path: "/v1/email/inbound-mailjet",
accessClass: "webhook-signature",
rationale:
"Tenant inbound email verifies Mailjet webhook Basic-Auth credentials before resolving tenant inbound addresses and creating lead/activity records.",
sensitiveData: "Consumes signed email metadata and message body while omitting provider payloads, recipient content, and signing material from responses.",
},
{
method: "POST",
path: "/v1/admin-sales/email/provider-events",
accessClass: "provider-hmac-webhook",
rationale:
"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.",
sensitiveData:
"Consumes bounded delivery and engagement metadata while responses omit recipient data, provider payloads, signing material, and AdminUser identifiers.",
},
{
method: "POST",
path: "/v1/admin-sales/email/bcc-inbound",
accessClass: "webhook-signature",
rationale:
"Admin BCC ingestion requires both Mailjet HTTP Basic authentication and one exact signed, rotatable BCC capability before binding the embedded AdminUser RLS context.",
sensitiveData:
"Consumes bounded email headers and bodies while responses omit message content, recipient capability material, signing secrets, and AdminUser identifiers.",
},
{
method: "POST",
path: "/v1/analytics/events",
accessClass: "public-analytics-token",
rationale:
"Analytics event ingestion accepts only a bounded anonymous visitor identifier and writes tenantless records in the isolated platform analytics RLS context.",
sensitiveData: "Consumes an anonymous analytics identifier, URLs, routes, and event labels; authenticated user and portal identifiers are rejected.",
},
{
method: "POST",
path: "/v1/analytics/page-views",
accessClass: "public-analytics-token",
rationale:
"Analytics page-view ingestion accepts only a bounded anonymous visitor identifier and writes tenantless records in the isolated platform analytics RLS context.",
sensitiveData: "Consumes an anonymous analytics identifier, URLs, and route names; authenticated user and portal identifiers are rejected.",
},
{
method: "GET",
path: "/v1/analytics/public",
accessClass: "public-analytics-overview",
rationale:
"Public analytics is enabled only by the operator-controlled setting and returns tenantless global aggregates from the isolated platform analytics RLS context.",
sensitiveData: "Returns tenantless aggregate analytics counts and top-level chart data without user, tenant, or portal attribution.",
},
{
method: "GET",
path: "/v1/analytics/admin",
accessClass: "service-token",
rationale:
"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.",
sensitiveData: "Returns global tenantless aggregates or aggregate metrics for an explicitly tenant-bound portal scope.",
},
{
method: "GET",
path: "/v1/notifications/stream",
accessClass: "service-token",
rationale: "Notification stream requires service credentials before returning tenant and user scoped in-app delivery diagnostics over SSE.",
sensitiveData: "Returns bounded, sanitized notification delivery snapshots and cursors without provider payloads, metadata, or raw delivery secrets.",
},
{
method: "GET",
path: "/v1/accounts",
accessClass: "service-token",
rationale:
"Account listing requires service credentials plus an explicit operator user identifier that is rebound and verified through the RLS-protected AdminUser row before global tenant reads.",
sensitiveData: "Returns tenant identifiers, names, slugs, icons, and subscription summary fields without plaintext secrets.",
},
{
method: "GET",
path: "/v1/accounts/:id",
accessClass: "service-token",
rationale:
"Account lookup requires service credentials plus an explicit operator user identifier that is rebound and verified through the RLS-protected AdminUser row before global tenant resolution and tenant-bound detail reads.",
sensitiveData: "Returns tenant identifiers, names, slugs, icons, and subscription summary fields without plaintext secrets.",
},
{
method: "GET",
path: "/v1/usage",
accessClass: "tenant-api-key",
rationale: "Usage lookups enter through the canonical API host and validate tenant API-key credentials in the API runtime.",
sensitiveData: "Returns plan and remaining API usage metadata for the credential-scoped tenant.",
},
{
method: "GET",
path: "/v1/contacts",
accessClass: "tenant-api-key",
rationale: "Public API contact reads validate a tenant-bound API-key credential before querying only that credential's tenant scope.",
sensitiveData: "Returns redacted contact fields for the credential-scoped tenant; internal notes and credential material are omitted.",
},
{
method: "GET",
path: "/v1/companies",
accessClass: "tenant-api-key",
rationale: "Public API company reads validate a tenant-bound API-key credential before querying only that credential's tenant scope.",
sensitiveData: "Returns redacted organisation contact fields for the credential-scoped tenant; internal notes and credential material are omitted.",
},
{
method: "GET",
path: "/v1/deals",
accessClass: "tenant-api-key",
rationale: "Public API deal reads validate a tenant-bound API-key credential before querying only that credential's tenant scope.",
sensitiveData: "Returns redacted sales-pipeline project fields for the credential-scoped tenant; internal notes and credential material are omitted.",
},
{
method: "GET",
path: "/v1/projects",
accessClass: "tenant-api-key",
rationale: "Public API project reads validate a tenant-bound API-key credential before querying only that credential's tenant scope.",
sensitiveData: "Returns redacted project fields for the credential-scoped tenant; internal notes and credential material are omitted.",
},
{
method: "GET",
path: "/v1/tasks",
accessClass: "tenant-api-key",
rationale: "Public API task reads validate a tenant-bound API-key credential before querying only that credential's tenant scope.",
sensitiveData: "Returns redacted task fields for the credential-scoped tenant; internal notes and credential material are omitted.",
},
{
method: "GET",
path: "/v1/leads",
accessClass: "tenant-api-key",
rationale: "Public API lead reads validate a tenant-bound API-key credential before querying only that credential's tenant scope.",
sensitiveData:
"Returns redacted lead-inbox fields for the credential-scoped tenant; raw payloads, anti-spam internals and credential material are omitted.",
},
{
method: "POST",
path: "/v1/webhooks/incoming/:tenant/:slug",
accessClass: "tenant-webhook-credential",
rationale:
"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.",
sensitiveData:
"Consumes third-party lead payloads and stores redacted ingestion metadata; API keys, webhook tokens, HMAC material and raw signing secrets are omitted from responses.",
},
{
method: "POST",
path: "/v1/webhooks/telephony/aircall",
accessClass: "provider-body-token-webhook",
rationale:
"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.",
sensitiveData:
"Consumes bounded call lifecycle metadata and a write-only provider token; responses disclose no tenant, credential, rate-limit, or deduplication state.",
},
{
method: "POST",
path: "/v1/webhooks/telephony/hallopetra",
accessClass: "provider-header-token-webhook",
rationale:
"HalloPetra webhook ingress authenticates a dedicated custom Authorization header secret against its stored hash, resolves exactly one tenant connection, and re-verifies the encrypted connection credential before RLS-scoped persistence.",
sensitiveData:
"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.",
},
{
method: "POST",
path: "/v1/webhooks/admin-telephony/aircall",
accessClass: "provider-body-token-webhook",
rationale:
"Admin Aircall webhook ingress hashes the provider-issued body token, resolves exactly one active AdminUser connection through the security-definer boundary, and binds that AdminUser RLS context before idempotent persistence.",
sensitiveData:
"Consumes bounded call lifecycle metadata and a write-only provider token; neutral responses disclose no AdminUser, connection, credential, rate-limit, or deduplication state.",
},
{
method: "POST",
path: "/v1/billing/lago/webhooks",
accessClass: "provider-hmac-webhook",
rationale:
"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.",
sensitiveData:
"Consumes tenant-scoped subscription lifecycle metadata while responses omit customer identifiers, provider object identifiers, payloads, and signing material.",
},
{
method: "POST",
path: "/v1/billing/mollie/webhooks",
accessClass: "provider-refetch-webhook",
rationale:
"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.",
sensitiveData:
"Consumes a provider payment id and stores redacted billing lifecycle metadata without returning provider payloads or plaintext credentials.",
},
{
method: "POST",
path: "/v1/email-sequences/mailjet/webhooks",
accessClass: "webhook-signature",
rationale: "Email-sequence provider webhooks verify Mailjet Basic-Auth credentials before correlating bounce events to provider message ids.",
sensitiveData: "Consumes delivery event metadata while responses omit provider payloads, recipient data, and credentials.",
},
{
method: "GET",
path: "/v1/workspaces/:tenantId/auth/providers",
accessClass: "service-token",
rationale: "Workspace auth-provider discovery requires a service token before returning tenant-scoped SSO metadata.",
sensitiveData:
"Returns redacted OIDC/SAML provider metadata only; client secrets, SAML certificate bodies, private keys, token hashes, invite tokens, and raw metadata documents are omitted.",
},
{
method: "POST",
path: "/v1/workspaces/:tenantId/context/revalidate",
accessClass: "service-token",
rationale: "Workspace context revalidation requires a service token before confirming tenant/user membership for a context switch.",
sensitiveData:
"Consumes tenant and user identifiers and returns a redacted validity envelope without provider secrets, invite tokens, token hashes, or SSO secret material.",
},
{
method: "GET",
path: "/v1/workspaces/:tenantId/invites",
accessClass: "service-token",
rationale: "Workspace invite listing requires a service token before returning tenant-scoped invite lifecycle state.",
sensitiveData: "Returns invite email, lifecycle timestamps, audit user ids, and tokenPrefix only; plaintext tokens and token hashes are omitted.",
},
{
method: "POST",
path: "/v1/workspaces/:tenantId/invites",
accessClass: "service-token",
rationale: "Workspace invite creation requires a service token before issuing a tenant-scoped invite token.",
sensitiveData: "Consumes invite recipient details and returns the one-time plaintext invite token only in the create response.",
},
{
method: "POST",
path: "/v1/workspaces/:tenantId/invites/:inviteId/accept",
accessClass: "service-token",
rationale: "Workspace invite acceptance requires a service token and a one-time invite token before finalizing tenant membership invitation state.",
sensitiveData: "Consumes plaintext invite token and returns redacted invite lifecycle metadata without echoing the token.",
},
{
method: "POST",
path: "/v1/workspaces/:tenantId/invites/:inviteId/revoke",
accessClass: "service-token",
rationale: "Workspace invite revocation requires a service token before finalizing the tenant-scoped invite as revoked.",
sensitiveData: "Consumes revoke audit metadata and returns redacted invite lifecycle metadata without token material.",
},
{
method: "POST",
path: "/v1/events/webhooks/attempts/:id",
accessClass: "webhook-signature",
rationale: "Webhook retry verifies Mailjet webhook Basic-Auth credentials before looking up or queueing a known delivery attempt.",
sensitiveData: "Consumes signed webhook delivery metadata and an attempt id while omitting provider payloads and signing material from responses.",
},
{
method: "POST",
path: "/v1/maintenance/export-retention/enqueue",
accessClass: "service-token",
rationale: "Export artifact retention cleanup is an operator maintenance action and requires service credentials before enqueueing work.",
sensitiveData: "Consumes an optional bounded batch size and returns only queue task metadata plus request correlation.",
},
{
method: "GET",
path: "/v1/exports/:exportJobId/download-url",
accessClass: "service-or-tenant-api-key",
rationale:
"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.",
sensitiveData:
"Returns a signed artifact URL envelope without artifact bucket/key values, storage credentials, pause reason internals, filters, or object bodies.",
},
{
method: "GET",
path: "/v1/exports/:exportJobId/progress",
accessClass: "service-or-tenant-api-key",
rationale:
"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.",
sensitiveData: "Returns export progress envelope (status, percent, rowCount) — no artifact URLs, no compliance-pause internals, no filters.",
},
{
method: "POST",
path: "/v1/devices/register",
accessClass: "jwt-auth",
rationale:
"Mobile push-token registration derives its user exclusively from a verified active API-session JWT; optional tenant membership is revalidated before tenant/user RLS binding.",
sensitiveData: "Persists a sensitive device-bound push token. The response contains registration metadata only and never returns the raw token.",
},
{
method: "POST",
path: "/v1/devices/revoke",
accessClass: "jwt-auth",
rationale:
"Mobile push-token revocation derives its owner exclusively from a verified active API-session JWT; optional tenant membership is revalidated before the ownership-constrained RLS write.",
sensitiveData: "Foreign user or tenant tokens are treated as not found. The response never echoes the raw device token or provider internals.",
},
] as const satisfies readonly RouteAccessInventoryEntry[];