Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -17,10 +17,12 @@
},
"dependencies": {
"@hivegrid/billing": "workspace:*",
"@hivegrid/chat": "workspace:*",
"@hivegrid/config": "workspace:*",
"@hivegrid/db": "workspace:*",
"@hivegrid/error-reporter": "workspace:*",
"@hivegrid/foundation": "workspace:*",
"@hivegrid/integrations": "workspace:*",
"@hivegrid/logger": "workspace:*",
"@hivegrid/metrics": "workspace:*",
"@hivegrid/observability": "workspace:*",
@@ -29,25 +31,31 @@
"@hivegrid/realtime": "workspace:*",
"@hivegrid/shared-store": "workspace:*",
"@hivegrid/storage": "workspace:*",
"@hono/node-server": "^1.19.6",
"@hono/node-server": "2.0.11",
"@opentelemetry/api": "^1.9.0",
"@opentelemetry/auto-instrumentations-node": "^0.76.0",
"@opentelemetry/core": "^2.7.1",
"@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
"@opentelemetry/resources": "^2.7.1",
"@opentelemetry/sdk-node": "^0.218.0",
"@opentelemetry/sdk-trace-base": "^2.7.1",
"@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
"@opentelemetry/instrumentation-aws-sdk": "^0.75.0",
"@opentelemetry/instrumentation-http": "^0.220.0",
"@opentelemetry/instrumentation-ioredis": "^0.68.0",
"@opentelemetry/instrumentation-pg": "^0.72.0",
"@opentelemetry/instrumentation-pino": "^0.66.0",
"@opentelemetry/instrumentation-undici": "^0.30.0",
"@opentelemetry/resources": "^2.9.0",
"@opentelemetry/sdk-node": "^0.220.0",
"@opentelemetry/sdk-trace-base": "^2.9.0",
"@opentelemetry/semantic-conventions": "^1.40.0",
"@sentry/node": "^10.53.1",
"bcryptjs": "^2.4.3",
"hono": "^4.12.17",
"argon2": "^0.44.0",
"bcryptjs": "^3.0.3",
"hono": "^4.12.29",
"jsonwebtoken": "^9.0.0",
"ws": "8.21.0",
"zod": "^3.25.72"
},
"devDependencies": {
"@types/bcryptjs": "^2.4.2",
"@types/jsonwebtoken": "^9.0.6",
"@types/node": "^25.6.0",
"@types/ws": "^8.18.1",
"tsx": "^4.6.2",
"typescript": "^5.3.2"
}
@@ -35,7 +35,7 @@ await build({
bundle: true,
platform: "node",
format: "esm",
target: "node20",
target: "node24",
sourcemap,
banner: {
js: 'import { createRequire as __hivegridCreateRequire } from "node:module"; const require = __hivegridCreateRequire(import.meta.url);',
@@ -58,6 +58,10 @@ function isExternalRuntimePackage(specifier) {
specifier.startsWith("@prisma/client/") ||
specifier === "@prisma/adapter-pg" ||
specifier.startsWith("@prisma/adapter-pg/") ||
specifier === "pg" ||
specifier.startsWith("pg/") ||
specifier === "argon2" ||
specifier.startsWith("argon2/") ||
specifier === "jsonwebtoken" ||
specifier.startsWith("jsonwebtoken/") ||
specifier === "pino" ||
@@ -0,0 +1,81 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import {
PUBLIC_ANALYTICS_OVERVIEW_CACHE_TTL_MS,
getCachedPublicAnalyticsOverview,
resetPublicAnalyticsOverviewCacheForTests,
} from "./analytics-overview-cache.js";
const overview = {
uniqueVisitors: 1,
pageViews: 2,
events: 3,
liveVisitors: 1,
top: { sources: [], httpReferrers: [], urls: [], routes: [], os: [], devices: [], countries: [], via: [], medium: [], campaign: [], user: [] },
charts: { pageViewsAndUniqueVisitors: [] },
};
describe("public analytics overview cache", () => {
afterEach(() => {
resetPublicAnalyticsOverviewCacheForTests();
});
it("coalesces a concurrent burst into one aggregate query", async () => {
let resolveQuery!: (value: typeof overview) => void;
const getAnalyticsOverview = vi.fn(() => new Promise<typeof overview>((resolve) => (resolveQuery = resolve)));
const dependencies = { getAnalyticsOverview };
const reads = Array.from({ length: 20 }, () =>
getCachedPublicAnalyticsOverview({ dependencies: dependencies as never, scope: "platform-global", period: "last-30-days", now: 1_000 })
);
expect(getAnalyticsOverview).toHaveBeenCalledOnce();
resolveQuery(overview);
await expect(Promise.all(reads)).resolves.toEqual(Array.from({ length: 20 }, () => overview));
});
it("reuses a resolved value only inside the bounded freshness window", async () => {
const getAnalyticsOverview = vi.fn(async () => overview);
const dependencies = { getAnalyticsOverview };
await getCachedPublicAnalyticsOverview({ dependencies: dependencies as never, scope: "platform-global", period: "last-7-days", now: 1_000 });
await getCachedPublicAnalyticsOverview({
dependencies: dependencies as never,
scope: "platform-global",
period: "last-7-days",
now: 1_000 + PUBLIC_ANALYTICS_OVERVIEW_CACHE_TTL_MS - 1,
});
await getCachedPublicAnalyticsOverview({
dependencies: dependencies as never,
scope: "platform-global",
period: "last-7-days",
now: 1_000 + PUBLIC_ANALYTICS_OVERVIEW_CACHE_TTL_MS,
});
expect(getAnalyticsOverview).toHaveBeenCalledTimes(2);
});
it("evicts failed aggregate queries instead of poisoning the cache", async () => {
const getAnalyticsOverview = vi.fn().mockRejectedValueOnce(new Error("database unavailable")).mockResolvedValueOnce(overview);
const dependencies = { getAnalyticsOverview };
await expect(
getCachedPublicAnalyticsOverview({ dependencies: dependencies as never, scope: "platform-global", period: "last-hour", now: 1_000 })
).rejects.toThrow("database unavailable");
await expect(
getCachedPublicAnalyticsOverview({ dependencies: dependencies as never, scope: "platform-global", period: "last-hour", now: 1_001 })
).resolves.toEqual(overview);
expect(getAnalyticsOverview).toHaveBeenCalledTimes(2);
});
it("separates cache entries by the explicit global scope and period key", async () => {
const getAnalyticsOverview = vi.fn(async () => overview);
const dependencies = { getAnalyticsOverview };
await getCachedPublicAnalyticsOverview({ dependencies: dependencies as never, scope: "platform-global", period: "last-hour", now: 1_000 });
await getCachedPublicAnalyticsOverview({ dependencies: dependencies as never, scope: "platform-global", period: "last-7-days", now: 1_000 });
expect(getAnalyticsOverview).toHaveBeenNthCalledWith(1, { period: "last-hour", portalId: null });
expect(getAnalyticsOverview).toHaveBeenNthCalledWith(2, { period: "last-7-days", portalId: null });
});
});
@@ -0,0 +1,61 @@
import type { AnalyticsOverview, AnalyticsPeriod, ApiAppDependencies } from "./app-dependencies.js";
export const PUBLIC_ANALYTICS_OVERVIEW_CACHE_TTL_MS = 5_000;
export type PublicAnalyticsOverviewScope = "platform-global";
type PublicAnalyticsOverviewDependencies = Pick<ApiAppDependencies, "getAnalyticsOverview">;
type CacheEntry = {
dependencies: PublicAnalyticsOverviewDependencies;
expiresAt: number;
value?: AnalyticsOverview;
pending?: Promise<AnalyticsOverview>;
};
type CacheKey = `${PublicAnalyticsOverviewScope}:${AnalyticsPeriod}`;
const cache = new Map<CacheKey, CacheEntry>();
/**
* Coalesces simultaneous public dashboard reads and keeps the expensive
* aggregate query off Postgres for a short, bounded freshness window.
*/
export async function getCachedPublicAnalyticsOverview(input: {
dependencies: PublicAnalyticsOverviewDependencies;
scope: PublicAnalyticsOverviewScope;
period: AnalyticsPeriod;
now?: number;
}): Promise<AnalyticsOverview> {
const now = input.now ?? Date.now();
const key: CacheKey = `${input.scope}:${input.period}`;
const current = cache.get(key);
if (current?.dependencies === input.dependencies && current.expiresAt > now) {
if (current.value) return current.value;
if (current.pending) return current.pending;
}
const pending = input.dependencies.getAnalyticsOverview({ period: input.period, portalId: null });
const next: CacheEntry = {
dependencies: input.dependencies,
expiresAt: now + PUBLIC_ANALYTICS_OVERVIEW_CACHE_TTL_MS,
pending,
};
cache.set(key, next);
try {
const value = await pending;
if (cache.get(key) === next) {
next.value = value;
next.pending = undefined;
}
return value;
} catch (error) {
if (cache.get(key) === next) {
cache.delete(key);
}
throw error;
}
}
export function resetPublicAnalyticsOverviewCacheForTests(): void {
cache.clear();
}
@@ -1,6 +1,8 @@
import type { ApiRequestIdVariables } from "./middleware/request-id.js";
import type { HttpBindings } from "@hono/node-server";
export type ApiEnv = {
Bindings: HttpBindings;
Variables: ApiRequestIdVariables;
};
@@ -1,24 +1,18 @@
import {
createUniqueLegacyTenantIpAddress,
adminGetAllLegacyTenants,
adminGetAllLegacyTenantSummaries,
findPlatformOperatorByUserId,
findLegacyTenantById,
findLegacyTenantByIdOrSlug,
type LegacyTenantWithDetails,
} from "@hivegrid/db/accounts.server";
import {
createLegacyApiKeyLog,
findLegacyApiKeyByKey,
setLegacyApiKeyLogStatus,
} from "@hivegrid/db/api-keys.server";
import {
listWorkspaceAuthProviders,
revalidateWorkspaceContext,
type WorkspaceAuthProviderDto,
} from "@hivegrid/db/auth-providers.server";
import { createLegacyApiKeyLog, findLegacyApiKeyByKeyWithRlsBootstrap, setLegacyApiKeyLogStatus } from "@hivegrid/db/api-keys.server";
import { listWorkspaceAuthProviders, revalidateWorkspaceContext, type WorkspaceAuthProviderDto } from "@hivegrid/db/auth-providers.server";
import {
createAnalyticsEvent,
createAnalyticsPageView,
findFeatureFlagByName,
findAnalyticsPortalForTenant,
getAnalyticsOverview,
getAnalyticsSettings,
getOrCreateAnalyticsUniqueVisitor,
@@ -34,6 +28,7 @@ import {
findLegacyAuthUserById,
findLegacyLoginUserByEmail,
recordLegacyLogin,
upgradeLegacyUserPasswordHash,
type LegacyAuthUser,
type LegacyLoginUser,
} from "@hivegrid/db/users.server";
@@ -44,15 +39,28 @@ import {
type LegacyEventWebhookAttemptUpdate,
} from "@hivegrid/db/event-webhook-attempts.server";
import { createLegacyEvent } from "@hivegrid/db/events.server";
import { markEmailSequenceDeliveryBounced, type MarkEmailSequenceDeliveryBouncedInput, type EmailSequenceProviderWebhookResult } from "@hivegrid/db/email-sequences.server";
import {
markEmailSequenceDeliveryBounced,
type MarkEmailSequenceDeliveryBouncedInput,
type EmailSequenceProviderWebhookResult,
} from "@hivegrid/db/email-sequences.server";
import {
markCampaignOutboundEmailBounced,
type CampaignOutboundEmailBounceResult,
type MarkCampaignOutboundEmailBouncedInput,
} from "@hivegrid/db/email-campaign-bounces.server";
import { ingestTenantInboundEmail, type TenantInboundEmailInput, type TenantInboundEmailResult } from "@hivegrid/db/email-inbound.server";
import { recordEmailSuppression } from "@hivegrid/db/email-suppression.server";
import { findExportJobForDownload, type ExportJobDownloadRecord } from "@hivegrid/db/export-jobs.server";
import { readExportProgressFromSharedStore } from "./export-progress.js";
import {
correlateCheckoutSessionProviderInvoice,
getCheckoutSessionStatus,
getTenantSubscription,
type TenantSubscriptionWithDetails,
} from "@hivegrid/db/subscriptions.server";
import { applyLagoSubscriptionSync, applyMolliePaymentSync } from "@hivegrid/db/billing-sync.server";
import { applyLagoSubscriptionSync, applyMolliePaymentSync, resolveLagoSubscriptionProductKind } from "@hivegrid/db/billing-sync.server";
import { reserveRecurringInvoiceCollection } from "@hivegrid/db/recurring-invoice-collection.server";
import { getTenantApiUsage } from "@hivegrid/db/usage.server";
import {
createPublicWebhookIngestionLog,
@@ -71,7 +79,17 @@ import {
} from "@hivegrid/db/workspace-invites.server";
import { getDbClient } from "@hivegrid/db/client.server";
import { getNotificationStreamSnapshot, type NotificationStreamCursor, type NotificationStreamSnapshot } from "@hivegrid/db/notifications.server";
import bcrypt from "bcryptjs";
import { recordAdminEmailEvent, type RecordAdminEmailEventInput, type RecordAdminEmailEventResult } from "@hivegrid/db/admin-email-events.server";
import { ingestAdminBccEmail, type IngestAdminBccEmailResult } from "@hivegrid/db/admin-email-domain.server";
import { findAdminEmailMatchCandidates } from "@hivegrid/db/admin-email-sync.server";
import { authenticatePlatformLeadSourceCredential, ingestPlatformLead } from "@hivegrid/db/platform-leads.server";
import {
resolveEmailSequenceProviderMessageRlsIdentity,
resolveEventWebhookAttemptRlsIdentity,
resolveOutboundEmailClickRlsIdentity,
resolvePublicWebhookRlsIdentity,
resolveTenantInboundAddressRlsIdentity,
} from "@hivegrid/db/rls-resolvers.server";
import {
checkLoginRateLimit,
recordFailedLoginAttempt,
@@ -81,25 +99,31 @@ import {
} from "./auth/login-rate-limit.js";
import { apiSessionStore } from "./auth/session/session-store.js";
import {
createMemoryIdempotencyStorageClient,
type IdempotencyStorageClient,
} from "./idempotency/store.js";
createPersistentApiSession,
getActivePersistentApiSession,
revokePersistentApiSession,
rotatePersistentApiSession,
} from "./auth/session/persistent-session-store.js";
import { verifySupportedPassword } from "./auth/password.js";
import { createMemoryIdempotencyStorageClient, type IdempotencyStorageClient } from "./idempotency/store.js";
import { createSharedStoreIdempotencyStorageClient } from "./idempotency/shared-store-client.js";
import { getSharedStore } from "./shared-store.js";
import { createStorageFile, createStorageSignedDownloadUrl, type CreateStorageSignedDownloadUrlInput, type StorageSignedDownloadUrlResult } from "./storage.js";
import { createStorageSignedDownloadUrl, type CreateStorageSignedDownloadUrlInput, type StorageSignedDownloadUrlResult } from "./storage.js";
import {
queueLegacyEventWebhookAttemptDelivery,
type QueueLegacyEventWebhookAttemptDeliveryInput,
type QueueLegacyEventWebhookAttemptDeliveryResult,
} from "./webhookDeliveryQueue.js";
import {
queueExportArtifactRetention,
type QueueExportArtifactRetentionInput,
type QueueExportArtifactRetentionResult,
} from "./exportRetentionQueue.js";
import { queueExportArtifactRetention, type QueueExportArtifactRetentionInput, type QueueExportArtifactRetentionResult } from "./exportRetentionQueue.js";
import { listPublicApiResource } from "./public-api/read-service.js";
import type { PublicApiListInput, PublicApiListResult } from "./public-api/resources.js";
import { createDefaultLagoInvoicePaymentStatusUpdater, createDefaultMollieWebhookResolver } from "./billing/mollie-webhook-route.js";
import {
createDefaultLagoInvoicePaymentStatusUpdater,
createDefaultLagoPaidSubscriptionEnsurer,
createDefaultLagoPendingSubscriptionTerminator,
createDefaultLagoProductSubscriptionTerminator,
createDefaultMollieWebhookResolver,
} from "./billing/mollie-webhook-route.js";
export { defaultAnalyticsPeriod, isAnalyticsPeriod };
export type {
@@ -127,82 +151,119 @@ type AnalyticsEventCreateData = {
value?: string;
url?: string;
route?: string;
featureFlagId?: string;
portalId?: string | null;
portalUserId?: string | null;
portalId: null;
portalUserId: null;
};
type AnalyticsPageViewCreateData = {
uniqueVisitorId: string;
url: string;
route?: string;
portalId?: string | null;
portalUserId?: string | null;
portalId: null;
portalUserId: null;
};
type AnonymousPlatformAnalyticsInfo = Omit<AnalyticsInfo, "userId" | "portalId" | "portalUserId" | "userAnalyticsId"> & {
userAnalyticsId: string;
userId: null;
portalId: null;
portalUserId: null;
};
export type ApiAppDependencies = {
findLegacyApiKeyByKey: typeof findLegacyApiKeyByKey;
findLegacyApiKeyByKey: typeof findLegacyApiKeyByKeyWithRlsBootstrap;
createLegacyApiKeyLog: typeof createLegacyApiKeyLog;
setLegacyApiKeyLogStatus: typeof setLegacyApiKeyLogStatus;
createUniqueLegacyTenantIpAddress: typeof createUniqueLegacyTenantIpAddress;
createAnalyticsEvent(data: AnalyticsEventCreateData): Promise<void>;
createAnalyticsPageView(data: AnalyticsPageViewCreateData): Promise<void>;
findFeatureFlagByName(name: string): Promise<{ id: string } | null>;
findAnalyticsPortalForTenant(args: { portalId: string; tenantId: string }): Promise<{ id: string; tenantId: string } | null>;
getAnalyticsOverview(args: { period: AnalyticsPeriod; portalId: string | null | undefined }): Promise<AnalyticsOverview>;
findLegacyAuthUserById(userId: string): Promise<LegacyAuthUser | null>;
findLegacyEventWebhookAttemptById(id: string): Promise<LegacyEventWebhookAttempt | null>;
resolveEventWebhookAttemptRlsIdentity: typeof resolveEventWebhookAttemptRlsIdentity;
createLegacyEvent: typeof createLegacyEvent;
applyLagoSubscriptionSync: typeof import("@hivegrid/db/billing-sync.server").applyLagoSubscriptionSync;
resolveLagoSubscriptionProductKind: typeof import("@hivegrid/db/billing-sync.server").resolveLagoSubscriptionProductKind;
applyMolliePaymentSync: typeof import("@hivegrid/db/billing-sync.server").applyMolliePaymentSync;
correlateCheckoutSessionProviderInvoice: typeof import("@hivegrid/db/subscriptions.server").correlateCheckoutSessionProviderInvoice;
getCheckoutSessionStatus: typeof import("@hivegrid/db/subscriptions.server").getCheckoutSessionStatus;
reserveRecurringInvoiceCollection: typeof import("@hivegrid/db/recurring-invoice-collection.server").reserveRecurringInvoiceCollection;
resolveMollieWebhookPayment: ReturnType<typeof createDefaultMollieWebhookResolver>;
ensureLagoPaidSubscription: ReturnType<typeof createDefaultLagoPaidSubscriptionEnsurer>;
terminateLagoPendingSubscription: ReturnType<typeof createDefaultLagoPendingSubscriptionTerminator>;
terminateLagoProductSubscription: ReturnType<typeof createDefaultLagoProductSubscriptionTerminator>;
updateLagoInvoicePaymentStatus: ReturnType<typeof createDefaultLagoInvoicePaymentStatusUpdater>;
findLegacyLoginUserByEmail(email: string): Promise<LegacyLoginUser | null>;
adminGetAllLegacyTenants(): Promise<LegacyTenantWithDetails[]>;
adminGetAllLegacyTenantSummaries: typeof adminGetAllLegacyTenantSummaries;
findPlatformOperatorByUserId: typeof findPlatformOperatorByUserId;
findLegacyTenantById(id: string): Promise<LegacyTenantWithDetails | null>;
findLegacyTenantByIdOrSlug(idOrSlug: string): Promise<{ id: string } | null>;
getTenantSubscription: typeof getTenantSubscription;
getTenantApiUsage: typeof getTenantApiUsage;
listPublicApiResource(input: PublicApiListInput): Promise<PublicApiListResult>;
findPublicIncomingWebhookEndpoint: typeof findPublicIncomingWebhookEndpoint;
resolvePublicWebhookRlsIdentity: typeof resolvePublicWebhookRlsIdentity;
createPublicWebhookIngestionLog: typeof createPublicWebhookIngestionLog;
ingestPublicLeadWebhook(input: Parameters<typeof ingestPublicLeadWebhook>[0]): Promise<IngestPublicLeadWebhookResult>;
createInboundSupportTicketFromEmail(input: InboundSupportTicketInput): Promise<InboundSupportTicketResult>;
ingestTenantInboundEmail(input: TenantInboundEmailInput): Promise<TenantInboundEmailResult>;
resolveTenantInboundAddressRlsIdentity: typeof resolveTenantInboundAddressRlsIdentity;
markEmailSequenceDeliveryBounced(input: MarkEmailSequenceDeliveryBouncedInput): Promise<EmailSequenceProviderWebhookResult>;
markCampaignOutboundEmailBounced(input: MarkCampaignOutboundEmailBouncedInput): Promise<CampaignOutboundEmailBounceResult>;
resolveEmailSequenceProviderMessageRlsIdentity: typeof resolveEmailSequenceProviderMessageRlsIdentity;
resolveOutboundEmailClickRlsIdentity: typeof resolveOutboundEmailClickRlsIdentity;
recordSuppression: typeof recordEmailSuppression;
findExportJobForDownload(args: { id: string; tenantId: string }): Promise<ExportJobDownloadRecord | null>;
readExportProgress(args: { exportJobId: string; tenantId: string }): Promise<{ processedRows: number; totalEstimate: number | null; updatedAt: string | null } | null>;
readExportProgress(args: {
exportJobId: string;
tenantId: string;
}): Promise<{ processedRows: number; totalEstimate: number | null; updatedAt: string | null } | null>;
getAnalyticsSettings(): Promise<{ public: boolean; ignorePages: string } | null>;
getOrCreateAnalyticsUniqueVisitor(args: { cookie: string; fromUrl?: string; fromRoute?: string; analytics: AnalyticsInfo }): Promise<AnalyticsUniqueVisitor>;
updateAnalyticsUniqueVisitorSource(visitor: AnalyticsUniqueVisitor, analytics: AnalyticsInfo): Promise<void>;
getOrCreateAnalyticsUniqueVisitor(args: {
cookie: string;
fromUrl?: string;
fromRoute?: string;
analytics: AnonymousPlatformAnalyticsInfo;
}): Promise<AnalyticsUniqueVisitor>;
updateAnalyticsUniqueVisitorSource(visitor: AnalyticsUniqueVisitor, analytics: AnonymousPlatformAnalyticsInfo): Promise<void>;
updateLegacyEventWebhookAttempt(args: { id: string; tenantId: string | null }, data: LegacyEventWebhookAttemptUpdate): Promise<void>;
queueLegacyEventWebhookAttemptDelivery(input: QueueLegacyEventWebhookAttemptDeliveryInput): Promise<QueueLegacyEventWebhookAttemptDeliveryResult>;
queueExportArtifactRetention(input: QueueExportArtifactRetentionInput): Promise<QueueExportArtifactRetentionResult>;
getNotificationStreamSnapshot(filters: { tenantId: string; userId: string; afterCursor?: NotificationStreamCursor | null }): Promise<NotificationStreamSnapshot>;
getNotificationStreamSnapshot(filters: {
tenantId: string;
userId: string;
afterCursor?: NotificationStreamCursor | null;
}): Promise<NotificationStreamSnapshot>;
authenticatePlatformLeadSourceCredential: typeof authenticatePlatformLeadSourceCredential;
ingestPlatformLead: typeof ingestPlatformLead;
recordAdminEmailEvent(input: RecordAdminEmailEventInput): Promise<RecordAdminEmailEventResult>;
findAdminEmailMatchCandidates(normalizedEmail: string | null): ReturnType<typeof findAdminEmailMatchCandidates>;
ingestAdminBccEmail(input: Parameters<typeof ingestAdminBccEmail>[1]): Promise<IngestAdminBccEmailResult>;
createWorkspaceInvite(input: Parameters<typeof createWorkspaceInvite>[0]): Promise<WorkspaceInviteCreateResult>;
listWorkspaceInvites(input: Parameters<typeof listWorkspaceInvites>[0]): Promise<WorkspaceInviteDto[]>;
acceptWorkspaceInvite(input: Parameters<typeof acceptWorkspaceInvite>[0]): Promise<WorkspaceInviteDto>;
revokeWorkspaceInvite(input: Parameters<typeof revokeWorkspaceInvite>[0]): Promise<WorkspaceInviteDto>;
listWorkspaceAuthProviders(input: Parameters<typeof listWorkspaceAuthProviders>[0]): Promise<WorkspaceAuthProviderDto[]>;
revalidateWorkspaceContext(input: Parameters<typeof revalidateWorkspaceContext>[0]): ReturnType<typeof revalidateWorkspaceContext>;
uploadFile(bucketId: string, path: string, file: UploadBody, contentType?: string): Promise<{ id: string; publicUrl: string | null }>;
createSignedDownloadUrl(bucketId: string, input: CreateStorageSignedDownloadUrlInput): Promise<StorageSignedDownloadUrlResult>;
recordLegacyLogin(userId: string): Promise<void>;
comparePassword(password: string, passwordHash: string): Promise<boolean>;
upgradeLegacyPasswordHash(userId: string, currentHash: string, upgradedHash: string): Promise<boolean>;
checkLoginRateLimit(request: LoginRateLimitRequest): ReturnType<typeof checkLoginRateLimit>;
recordFailedLoginAttempt(request: LoginRateLimitRequest): Promise<void>;
recordSuccessfulLogin(request: Pick<LoginRateLimitRequest, "account">): Promise<void>;
resetLoginRateLimiter(): Promise<void>;
resetApiSessionStore(): void;
createApiSession(userId: string): ReturnType<typeof apiSessionStore.createSession>;
getActiveApiSession(sessionId: string): ReturnType<typeof apiSessionStore.getActiveSession>;
rotateApiSession(sessionId: string): ReturnType<typeof apiSessionStore.rotateSession>;
revokeApiSession(sessionId: string): ReturnType<typeof apiSessionStore.revokeSession>;
createApiSession(userId: string): ReturnType<typeof createPersistentApiSession>;
getActiveApiSession(sessionId: string): ReturnType<typeof getActivePersistentApiSession>;
rotateApiSession(sessionId: string, userId: string): ReturnType<typeof rotatePersistentApiSession>;
revokeApiSession(sessionId: string, userId: string): ReturnType<typeof revokePersistentApiSession>;
getIdempotencyClient(): IdempotencyStorageClient;
checkReadiness(): Promise<void>;
};
type UploadBody = Parameters<typeof createStorageFile>[2];
/**
* Idempotency-storage backend selection (Phase 03 #38).
*
@@ -225,33 +286,49 @@ function resolveIdempotencyClient(): IdempotencyStorageClient {
}
const defaultApiAppDependencies: ApiAppDependencies = {
findLegacyApiKeyByKey,
findLegacyApiKeyByKey: findLegacyApiKeyByKeyWithRlsBootstrap,
createLegacyApiKeyLog,
setLegacyApiKeyLogStatus,
createUniqueLegacyTenantIpAddress,
createAnalyticsEvent,
createAnalyticsPageView,
findFeatureFlagByName,
findAnalyticsPortalForTenant,
getAnalyticsOverview,
findLegacyAuthUserById,
findLegacyEventWebhookAttemptById,
resolveEventWebhookAttemptRlsIdentity,
createLegacyEvent,
applyLagoSubscriptionSync,
resolveLagoSubscriptionProductKind,
applyMolliePaymentSync,
correlateCheckoutSessionProviderInvoice,
getCheckoutSessionStatus,
reserveRecurringInvoiceCollection,
resolveMollieWebhookPayment: createDefaultMollieWebhookResolver(),
ensureLagoPaidSubscription: createDefaultLagoPaidSubscriptionEnsurer(),
terminateLagoPendingSubscription: createDefaultLagoPendingSubscriptionTerminator(),
terminateLagoProductSubscription: createDefaultLagoProductSubscriptionTerminator(),
updateLagoInvoicePaymentStatus: createDefaultLagoInvoicePaymentStatusUpdater(),
findLegacyLoginUserByEmail,
adminGetAllLegacyTenants,
adminGetAllLegacyTenantSummaries,
findPlatformOperatorByUserId,
findLegacyTenantById,
findLegacyTenantByIdOrSlug,
getTenantSubscription,
getTenantApiUsage,
listPublicApiResource,
findPublicIncomingWebhookEndpoint,
resolvePublicWebhookRlsIdentity,
createPublicWebhookIngestionLog,
ingestPublicLeadWebhook,
createInboundSupportTicketFromEmail,
ingestTenantInboundEmail,
resolveTenantInboundAddressRlsIdentity,
markEmailSequenceDeliveryBounced,
markCampaignOutboundEmailBounced,
resolveEmailSequenceProviderMessageRlsIdentity,
resolveOutboundEmailClickRlsIdentity,
recordSuppression: recordEmailSuppression,
findExportJobForDownload,
readExportProgress: readExportProgressFromSharedStore,
@@ -262,25 +339,30 @@ const defaultApiAppDependencies: ApiAppDependencies = {
queueLegacyEventWebhookAttemptDelivery,
queueExportArtifactRetention,
getNotificationStreamSnapshot,
authenticatePlatformLeadSourceCredential,
ingestPlatformLead,
recordAdminEmailEvent: (input) => recordAdminEmailEvent(getDbClient(), input),
findAdminEmailMatchCandidates: (normalizedEmail) => findAdminEmailMatchCandidates(getDbClient(), normalizedEmail),
ingestAdminBccEmail: (input) => ingestAdminBccEmail(getDbClient(), input),
createWorkspaceInvite,
listWorkspaceInvites,
acceptWorkspaceInvite,
revokeWorkspaceInvite,
listWorkspaceAuthProviders,
revalidateWorkspaceContext,
uploadFile: createStorageFile,
createSignedDownloadUrl: createStorageSignedDownloadUrl,
recordLegacyLogin,
comparePassword: bcrypt.compare,
comparePassword: verifySupportedPassword,
upgradeLegacyPasswordHash: upgradeLegacyUserPasswordHash,
checkLoginRateLimit,
recordFailedLoginAttempt,
recordSuccessfulLogin,
resetLoginRateLimiter: resetLoginRateLimiterForTests,
resetApiSessionStore: apiSessionStore.reset,
createApiSession: apiSessionStore.createSession,
getActiveApiSession: apiSessionStore.getActiveSession,
rotateApiSession: apiSessionStore.rotateSession,
revokeApiSession: apiSessionStore.revokeSession,
createApiSession: createPersistentApiSession,
getActiveApiSession: getActivePersistentApiSession,
rotateApiSession: rotatePersistentApiSession,
revokeApiSession: revokePersistentApiSession,
getIdempotencyClient() {
return resolveIdempotencyClient();
},
@@ -304,6 +386,10 @@ export function configureApiAppDependenciesForTests(dependencies: Partial<ApiApp
apiAppDependencies = {
...defaultApiAppDependencies,
getIdempotencyClient: () => idempotencyClient,
createApiSession: async (userId) => apiSessionStore.createSession(userId),
getActiveApiSession: async (sessionId) => apiSessionStore.getActiveSession(sessionId),
rotateApiSession: async (sessionId) => apiSessionStore.rotateSession(sessionId),
revokeApiSession: async (sessionId) => apiSessionStore.revokeSession(sessionId),
...dependencies,
};
File diff suppressed because it is too large. Load diff
@@ -3,6 +3,7 @@ import { cors } from "hono/cors";
import { isMetricsEnabled } from "@hivegrid/metrics";
import { getApiAppDependencies, configureApiAppDependenciesForTests, type ApiAppDependencies } from "./app-dependencies.js";
import type { ApiEnv } from "./api-types.js";
import { postLagoBillingWebhookRequest } from "./billing/lago-webhook-route.js";
import { postMollieBillingWebhookRequest } from "./billing/mollie-webhook-route.js";
import { getAllowedCorsOrigin } from "./cors.js";
import { apiLogger } from "./logger.js";
@@ -18,15 +19,21 @@ import { apiErrorReporter } from "./sentry.js";
import { registerPublicApiReadRoutes } from "./routes/public-api-routes.js";
import { registerAccountsRoutes } from "./routes/accounts-routes.js";
import { registerAnalyticsRoutes } from "./routes/analytics-routes.js";
import { registerAdminEmailRoutes } from "./routes/admin-email-routes.js";
import { registerAuthRoutes } from "./routes/auth-routes.js";
import { registerDevicesRoutes } from "./routes/devices-routes.js";
import { registerMaintenanceRoutes } from "./routes/maintenance-routes.js";
import { handleApiMetricsRequest } from "./routes/metrics.js";
import { registerNotificationRoutes } from "./routes/notifications-routes.js";
import { registerPlatformLeadRoutes } from "./routes/platform-lead-routes.js";
import { handleApiStatusRequest } from "./routes/status.js";
import { registerSystemRoutes } from "./routes/system-routes.js";
import { registerWorkspaceRoutes } from "./routes/workspace-routes.js";
import { getUsageRequest } from "./usage/usage-route.js";
import { checkCachedApiReadiness } from "./readiness-cache.js";
import { postAircallWebhookRequest } from "./telephony/aircall-webhook-route.js";
import { postHalloPetraWebhookRequest } from "./telephony/hallopetra-webhook-route.js";
import { postAdminAircallWebhookRequest } from "./telephony/admin-aircall-webhook-route.js";
export { configureApiAppDependenciesForTests };
export type { ApiAppDependencies };
@@ -60,7 +67,7 @@ app.use(
app.get("/status", (c) =>
handleApiStatusRequest(c, {
checkDb: () => getApiAppDependencies().checkReadiness(),
checkDb: checkCachedApiReadiness,
getRevision: () => process.env.APP_REVISION?.trim() ?? "",
getRegion: () => process.env.APP_REGION?.trim() ?? process.env.FLY_REGION?.trim() ?? "",
getUptimeSeconds: () => process.uptime(),
@@ -97,12 +104,10 @@ app.use(
"x-account-id",
"x-analytics-token",
"x-api-key",
"x-filename",
"x-request-id",
"x-tenant-id",
"x-hivegrid-tenant-id",
"x-hivegrid-user-id",
"x-storage-object-status",
"webhook-id",
"webhook-timestamp",
"webhook-signature",
@@ -120,13 +125,21 @@ registerAuthRoutes(app);
registerAccountsRoutes(app);
registerAnalyticsRoutes(app);
registerNotificationRoutes(app);
registerPlatformLeadRoutes(app);
registerWorkspaceRoutes(app);
registerMaintenanceRoutes(app);
registerAdminEmailRoutes(app);
registerDevicesRoutes(app);
registerPublicApiReadRoutes(app);
app.get("/v1/usage", (c) => getUsageRequest(c, getApiAppDependencies()));
app.post("/v1/billing/lago/webhooks", (c) => postLagoBillingWebhookRequest(c, getApiAppDependencies()));
app.post("/v1/billing/mollie/webhooks", (c) => postMollieBillingWebhookRequest(c, getApiAppDependencies()));
app.post("/v1/webhooks/telephony/aircall", (c) => postAircallWebhookRequest(c));
app.post("/v1/webhooks/telephony/hallopetra", (c) => postHalloPetraWebhookRequest(c));
app.post("/v1/webhooks/admin-telephony/aircall", (c) =>
postAdminAircallWebhookRequest(c)
);
app.notFound(createNotFoundHandler());
app.onError(createErrorHandler({ reporter: apiErrorReporter }));
@@ -12,6 +12,7 @@ const baseConfig: ApiConfig = {
webAppHost: "app.localhost:3000",
adminAppHost: "admin.localhost:3000",
apiHost: "api.localhost:3000",
portalAppHost: "portal.localhost:3000",
protocol: "http",
},
origins: {},
@@ -28,7 +29,7 @@ const baseConfig: ApiConfig = {
};
describe("serializeApiAuthCookie", () => {
test("serializes production API auth cookies with shared hardened attributes", () => {
test("serializes production API auth cookies with host-only hardened attributes", () => {
const config = {
...baseConfig,
nodeEnv: "production",
@@ -37,13 +38,14 @@ describe("serializeApiAuthCookie", () => {
webAppHost: "app.example.com",
adminAppHost: "admin.example.com",
apiHost: "api.example.com",
portalAppHost: "portal.example.com",
protocol: "https",
},
} satisfies ApiConfig;
const cookie = serializeApiAuthCookie("signed.jwt.value", config);
expect(cookie).toContain("hivegrid_api_session=signed.jwt.value");
expect(cookie).toContain("Domain=example.com");
expect(cookie).not.toContain("Domain=");
expect(cookie).toContain("SameSite=Lax");
expect(cookie).toContain("Secure");
expect(cookie).toContain("HttpOnly");
@@ -75,7 +77,7 @@ describe("serializeApiAuthCookie", () => {
expect(cookie).not.toContain(baseConfig.jwtSecret);
});
test("serializes expired API auth cookies with hardened shared attributes", () => {
test("serializes expired API auth cookies with host-only hardened attributes", () => {
const config = {
...baseConfig,
nodeEnv: "production",
@@ -84,6 +86,7 @@ describe("serializeApiAuthCookie", () => {
webAppHost: "app.example.com",
adminAppHost: "admin.example.com",
apiHost: "api.example.com",
portalAppHost: "portal.example.com",
protocol: "https",
},
} satisfies ApiConfig;
@@ -92,7 +95,7 @@ describe("serializeApiAuthCookie", () => {
expect(cookie).toContain("hivegrid_api_session=");
expect(cookie).toContain("Max-Age=0");
expect(cookie).toContain("Expires=Thu, 01 Jan 1970 00:00:00 GMT");
expect(cookie).toContain("Domain=example.com");
expect(cookie).not.toContain("Domain=");
expect(cookie).toContain("SameSite=Lax");
expect(cookie).toContain("Secure");
expect(cookie).toContain("HttpOnly");
@@ -11,26 +11,32 @@ import {
recordSuccessfulLogin,
resetLoginRateLimiterForTests,
__resetLoginRateLimitStoreForTests,
__setLoginRateLimitKeySecretForTests,
__setLoginRateLimitStoreForTests,
} from "./login-rate-limit.js";
const TEST_KEY_SECRET = "test-login-rate-limit-key-secret-32-bytes";
let testStore: ReturnType<typeof createSharedStore>;
function request(account: string | undefined = "User@Example.com", ip: string | undefined = "203.0.113.10") {
return {
account,
// Trusted proxy-set header — the limiter no longer trusts X-Forwarded-For.
headers: ip ? { "cf-connecting-ip": ip } : {},
headers: ip ? { "cf-connecting-ip": ip, "x-forwarded-for": `${ip}, 173.245.48.10` } : {},
};
}
async function failAttempts(count: number, input = request()) {
for (let index = 0; index < count; index += 1) {
await recordFailedLoginAttempt(input);
const reservation = await checkLoginRateLimit(input);
if (reservation.allowed) await recordFailedLoginAttempt(input);
}
}
beforeEach(() => {
// Fresh isolated memory store per test so keys never bleed across cases.
__setLoginRateLimitStoreForTests(createSharedStore({ namespace: "test-login-rate-limit" }));
testStore = createSharedStore({ namespace: "test-login-rate-limit" });
__setLoginRateLimitStoreForTests(testStore);
__setLoginRateLimitKeySecretForTests(TEST_KEY_SECRET);
});
afterEach(async () => {
@@ -41,12 +47,10 @@ afterEach(async () => {
describe("login rate limiter (shared-store)", () => {
test("allows through the last permitted attempt and blocks after the IP threshold", async () => {
for (let index = 0; index < LOGIN_RATE_LIMIT_IP_ATTEMPTS - 1; index += 1) {
await recordFailedLoginAttempt(request(`user-${index}@example.com`, "198.51.100.10"));
await checkLoginRateLimit(request(`user-${index}@example.com`, "198.51.100.10"));
}
expect(await checkLoginRateLimit(request("next@example.com", "198.51.100.10"))).toMatchObject({ allowed: true });
await recordFailedLoginAttempt(request("last@example.com", "198.51.100.10"));
expect(await checkLoginRateLimit(request("blocked@example.com", "198.51.100.10"))).toMatchObject({
allowed: false,
scope: "ip",
@@ -57,7 +61,7 @@ describe("login rate limiter (shared-store)", () => {
test("tracks account attempts across different IP buckets", async () => {
for (let index = 0; index < LOGIN_RATE_LIMIT_ACCOUNT_ATTEMPTS; index += 1) {
await recordFailedLoginAttempt(request("Shared@Example.com", `203.0.113.${index + 1}`));
await checkLoginRateLimit(request("Shared@Example.com", `203.0.113.${index + 1}`));
}
expect(await checkLoginRateLimit(request(" shared@example.com ", "203.0.113.99"))).toMatchObject({
@@ -77,28 +81,43 @@ describe("login rate limiter (shared-store)", () => {
expect(await checkLoginRateLimit(request("fresh@example.com", "203.0.113.2"))).toMatchObject({ allowed: true });
});
test("prefers trusted proxy headers and ignores spoofable X-Forwarded-For", () => {
// Cloudflare's CF-Connecting-IP wins over an attacker-forged X-Forwarded-For.
test("binds Cloudflare client headers to a verified proxy peer", () => {
expect(
deriveLoginRateLimitClientIp({
headers: new Headers({ "x-forwarded-for": "1.2.3.4, 10.0.0.1", "cf-connecting-ip": "198.51.100.7" }),
headers: new Headers({ "x-forwarded-for": "1.2.3.4, 173.245.48.10", "cf-connecting-ip": "198.51.100.7" }),
remoteAddress: "198.51.100.9",
}),
).toBe("198.51.100.7");
// X-Real-IP is the next trusted fallback.
expect(deriveLoginRateLimitClientIp({ headers: { "x-real-ip": "198.51.100.8" }, remoteAddress: "198.51.100.9" })).toBe("198.51.100.8");
// A lone X-Forwarded-For is NOT trusted -> falls through to remoteAddress.
expect(deriveLoginRateLimitClientIp({ headers: { "x-forwarded-for": "203.0.113.9" }, remoteAddress: "198.51.100.9" })).toBe("198.51.100.9");
expect(deriveLoginRateLimitClientIp({ headers: { "cf-connecting-ip": "198.51.100.8" }, remoteAddress: "198.51.100.9" })).toBe("198.51.100.9");
expect(deriveLoginRateLimitClientIp({ headers: { "x-real-ip": "203.0.113.8" }, remoteAddress: "198.51.100.9" })).toBe("198.51.100.9");
expect(deriveLoginRateLimitClientIp({ headers: { "x-forwarded-for": "1.2.3.4, 203.0.113.9" }, remoteAddress: "198.51.100.10" })).toBe(
"203.0.113.9",
);
expect(deriveLoginRateLimitClientIp({ remoteAddress: "198.51.100.9" })).toBe("198.51.100.9");
expect(deriveLoginRateLimitClientIp({})).toBe("unknown");
});
test("handles missing Headers values and multi-value proxy header records", () => {
expect(
deriveLoginRateLimitClientIp({
headers: new Headers({ "x-forwarded-for": "1.2.3.4, 203.0.113.200" }),
remoteAddress: "198.51.100.20",
}),
).toBe("203.0.113.200");
expect(
deriveLoginRateLimitClientIp({
headers: { "cf-connecting-ip": ["198.51.100.21", "198.51.100.22"] },
remoteAddress: "198.51.100.23",
}),
).toBe("198.51.100.23");
});
test("resets only the normalized account bucket after successful login", async () => {
await failAttempts(LOGIN_RATE_LIMIT_ACCOUNT_ATTEMPTS, request("Reset@Example.com", "203.0.113.11"));
await failAttempts(LOGIN_RATE_LIMIT_IP_ATTEMPTS, request("other@example.com", "203.0.113.12"));
expect(await checkLoginRateLimit(request("reset@example.com", "203.0.113.13"))).toMatchObject({ allowed: false, scope: "account" });
await recordSuccessfulLogin({ account: " reset@example.com " });
await recordSuccessfulLogin(request(" reset@example.com ", "203.0.113.13"));
expect(await checkLoginRateLimit(request("reset@example.com", "203.0.113.13"))).toMatchObject({ allowed: true });
expect(await checkLoginRateLimit(request("fresh@example.com", "203.0.113.12"))).toMatchObject({ allowed: false, scope: "ip" });
@@ -106,7 +125,7 @@ describe("login rate limiter (shared-store)", () => {
test("normalizes malformed or missing accounts into one bounded account bucket", async () => {
for (const account of [undefined, null, "", " ", 123]) {
await recordFailedLoginAttempt({ ...request(undefined, "203.0.113.30"), account });
await checkLoginRateLimit({ ...request(undefined, "203.0.113.30"), account });
}
expect(await checkLoginRateLimit({ ...request(undefined, "203.0.113.31"), account: undefined })).toMatchObject({
@@ -131,6 +150,59 @@ describe("login rate limiter (shared-store)", () => {
expect(serialized).not.toContain(rawPassword);
});
test("stores only HMAC-derived IP and account buckets", async () => {
const rawEmail = "Redis.Visible@example.com";
const rawIp = "203.0.113.44";
await checkLoginRateLimit(request(rawEmail, rawIp));
const keys: string[] = [];
for await (const key of testStore.scan("rl:fixed:login-rate-limit:*")) keys.push(key);
const serialized = keys.join("\n");
expect(keys).toHaveLength(2);
expect(serialized).not.toContain(rawEmail);
expect(serialized).not.toContain(rawEmail.toLowerCase());
expect(serialized).not.toContain(rawIp);
expect(serialized).toMatch(/[a-f0-9]{64}/u);
});
test("fails closed without a pseudonymization secret", async () => {
__setLoginRateLimitKeySecretForTests(null);
await expect(checkLoginRateLimit(request("user@example.com", "203.0.113.45"))).resolves.toMatchObject({
allowed: false,
scope: "ip",
accountFingerprint: "acct_unavailable",
});
});
test("atomically caps a parallel verifier burst", async () => {
const input = request("parallel@example.com", "198.51.100.77");
const results = await Promise.all(
Array.from({ length: LOGIN_RATE_LIMIT_ACCOUNT_ATTEMPTS * 4 }, () => checkLoginRateLimit(input)),
);
expect(results.filter((result) => result.allowed)).toHaveLength(LOGIN_RATE_LIMIT_ACCOUNT_ATTEMPTS);
expect(results.filter((result) => !result.allowed)).toHaveLength(LOGIN_RATE_LIMIT_ACCOUNT_ATTEMPTS * 3);
});
test("does not let an already-blocked IP poison another account bucket", async () => {
const blockedIp = "198.51.100.78";
for (let index = 0; index < LOGIN_RATE_LIMIT_IP_ATTEMPTS; index += 1) {
await checkLoginRateLimit(request(`source-${index}@example.com`, blockedIp));
}
for (let index = 0; index < LOGIN_RATE_LIMIT_ACCOUNT_ATTEMPTS * 2; index += 1) {
expect(await checkLoginRateLimit(request("victim@example.com", blockedIp))).toMatchObject({
allowed: false,
scope: "ip",
});
}
expect(await checkLoginRateLimit(request("victim@example.com", "198.51.100.79"))).toMatchObject({
allowed: true,
});
});
test("uses the redis adapter when REDIS_URL is set", () => {
// Verify the store wiring picks the RedisAdapter when REDIS_URL is
// provided. We don't actually open a Redis connection — we inject a
@@ -1,4 +1,8 @@
import { createHmac } from "node:crypto";
import { getTrustedProxyClientIp } from "@hivegrid/foundation/trusted-client-ip";
import { createFixedWindowRateLimiter, type FixedWindowRateLimiter, type SharedStore } from "@hivegrid/shared-store";
import { getApiRuntimeConfig } from "../config.js";
import { getSharedStore } from "../shared-store.js";
export const LOGIN_RATE_LIMIT_WINDOW_MS = 60_000;
@@ -9,6 +13,7 @@ const LOGIN_RATE_LIMIT_WINDOW_SECONDS = Math.ceil(LOGIN_RATE_LIMIT_WINDOW_MS / 1
const UNKNOWN_CLIENT_IP = "unknown";
const UNKNOWN_ACCOUNT_KEY = "unknown-account";
const FINGERPRINT_PREFIX = "acct_";
const UNAVAILABLE_ACCOUNT_FINGERPRINT = `${FINGERPRINT_PREFIX}unavailable`;
export type LoginRateLimitScope = "ip" | "account";
@@ -47,6 +52,19 @@ type Limiters = {
let limiters: Limiters | null = null;
let storeFactory: () => SharedStore = () => getSharedStore();
let keySecretFactory: () => string = defaultKeySecret;
function defaultKeySecret(): string {
const secret = getApiRuntimeConfig().jwtSecret?.trim();
if (!secret) {
throw new Error("API login rate-limit key secret is unavailable.");
}
return secret;
}
function pseudonymousBucketKey(scope: "account" | "ip", value: string): string {
return createHmac("sha256", keySecretFactory()).update(`v1\0${scope}\0${value}`).digest("hex");
}
function getLimiters(): Limiters {
if (limiters !== null) {
@@ -74,53 +92,66 @@ function getLimiters(): Limiters {
export async function checkLoginRateLimit(request: LoginRateLimitRequest): Promise<LoginRateLimitResult> {
const clientIp = deriveLoginRateLimitClientIp(request);
const accountKey = normalizeLoginRateLimitAccount(request.account);
const accountFingerprint = createLoginRateLimitAccountFingerprint(accountKey);
const { ip, account, store } = getLimiters();
try {
const accountFingerprint = createLoginRateLimitAccountFingerprint(accountKey);
const { ip, account } = getLimiters();
const ipState = await readCounter(store, "login-rate-limit:ip", clientIp);
if (ipState.count >= LOGIN_RATE_LIMIT_IP_ATTEMPTS) {
// Reserve before the expensive password comparison. Each consume is an
// atomic Lua operation, so a parallel burst cannot send every request
// through bcrypt. HMAC-derived bucket keys keep raw IPs and enumerable
// account identifiers out of Redis. Check IP first so an already-blocked
// source cannot poison arbitrary account buckets without reaching a
// verifier.
const ipReservation = await ip.consume(pseudonymousBucketKey("ip", clientIp));
if (!ipReservation.allowed) {
return {
allowed: false,
scope: "ip",
retryAfterSeconds: retryAfterSeconds(ipReservation.resetAt),
clientIp,
accountFingerprint,
};
}
const accountReservation = await account.consume(pseudonymousBucketKey("account", accountKey));
if (!accountReservation.allowed) {
return {
allowed: false,
scope: "account",
retryAfterSeconds: retryAfterSeconds(accountReservation.resetAt),
clientIp,
accountFingerprint,
};
}
return {
allowed: true,
clientIp,
accountFingerprint,
};
} catch {
// A missing secret or unavailable shared store must not silently remove
// brute-force protection. Return only a fixed non-PII diagnostic marker.
return {
allowed: false,
scope: "ip",
retryAfterSeconds: Math.max(1, ipState.ttlSeconds),
clientIp,
accountFingerprint,
retryAfterSeconds: LOGIN_RATE_LIMIT_WINDOW_SECONDS,
clientIp: UNKNOWN_CLIENT_IP,
accountFingerprint: UNAVAILABLE_ACCOUNT_FINGERPRINT,
};
}
const accountState = await readCounter(store, "login-rate-limit:account", accountKey);
if (accountState.count >= LOGIN_RATE_LIMIT_ACCOUNT_ATTEMPTS) {
return {
allowed: false,
scope: "account",
retryAfterSeconds: Math.max(1, accountState.ttlSeconds),
clientIp,
accountFingerprint,
};
}
// Silence unused-var: the limiter objects are kept on the cached `Limiters`
// because `recordFailedLoginAttempt` consumes them on the write path.
void ip;
void account;
return {
allowed: true,
clientIp,
accountFingerprint,
};
}
export async function recordFailedLoginAttempt(request: LoginRateLimitRequest): Promise<void> {
const { ip, account } = getLimiters();
const clientIp = deriveLoginRateLimitClientIp(request);
const accountKey = normalizeLoginRateLimitAccount(request.account);
await Promise.all([ip.consume(clientIp), account.consume(accountKey)]);
// The attempt was already reserved atomically by checkLoginRateLimit before
// password verification. Keep this compatibility hook while callers migrate;
// consuming again here would double-count every failed password.
void request;
}
export async function recordSuccessfulLogin(request: Pick<LoginRateLimitRequest, "account">): Promise<void> {
const { account } = getLimiters();
await account.reset(normalizeLoginRateLimitAccount(request.account));
await account.reset(pseudonymousBucketKey("account", normalizeLoginRateLimitAccount(request.account)));
}
export async function resetLoginRateLimiterForTests(): Promise<void> {
@@ -152,39 +183,30 @@ export function __setLoginRateLimitStoreForTests(store: SharedStore): void {
storeFactory = () => store;
}
/** Test seam: provide an isolated HMAC key without loading production config. */
export function __setLoginRateLimitKeySecretForTests(secret: string | null): void {
keySecretFactory = () => {
const normalized = secret?.trim();
if (!normalized) throw new Error("API login rate-limit key secret is unavailable.");
return normalized;
};
}
/** Test seam: revert to the default factory (real shared-store singleton). */
export function __resetLoginRateLimitStoreForTests(): void {
limiters = null;
storeFactory = () => getSharedStore();
keySecretFactory = defaultKeySecret;
}
// Trusted, proxy-set headers only. The leftmost X-Forwarded-For value is
// client-controlled, so keying the login throttle on it let an attacker reset
// their bucket by rotating the header (credential-stuffing bypass).
const TRUSTED_LOGIN_IP_HEADERS = ["cf-connecting-ip", "true-client-ip", "x-real-ip"] as const;
export function deriveLoginRateLimitClientIp(request: Pick<LoginRateLimitRequest, "headers" | "remoteAddress">): string {
for (const headerName of TRUSTED_LOGIN_IP_HEADERS) {
const value = readHeader(request.headers, headerName)?.trim();
if (value) {
return value;
}
}
const remoteAddress = request.remoteAddress?.trim();
return remoteAddress || UNKNOWN_CLIENT_IP;
return getTrustedProxyClientIp((name) => readHeader(request.headers, name), request.remoteAddress) ?? UNKNOWN_CLIENT_IP;
}
export function createLoginRateLimitAccountFingerprint(account: unknown): string {
const normalized = normalizeLoginRateLimitAccount(account);
let hash = 0x811c9dc5;
for (let index = 0; index < normalized.length; index += 1) {
hash ^= normalized.charCodeAt(index);
hash = Math.imul(hash, 0x01000193) >>> 0;
}
return `${FINGERPRINT_PREFIX}${hash.toString(16).padStart(8, "0")}`;
const digest = createHmac("sha256", keySecretFactory()).update(`v1\0account-log\0${normalized}`).digest("hex");
return `${FINGERPRINT_PREFIX}${digest.slice(0, 24)}`;
}
function normalizeLoginRateLimitAccount(account: unknown): string {
@@ -196,22 +218,8 @@ function normalizeLoginRateLimitAccount(account: unknown): string {
return normalized || UNKNOWN_ACCOUNT_KEY;
}
/**
* Peek at the current counter and remaining TTL without incrementing.
* The shared-store fixed-window helper only exposes `consume()` (which
* always increments) and `reset()`, so we read the underlying key
* directly to keep `checkLoginRateLimit` side-effect-free.
*/
async function readCounter(store: SharedStore, prefix: string, key: string): Promise<{ count: number; ttlSeconds: number }> {
const suffix = `rl:fixed:${prefix}:${key}`;
const raw = await store.get(suffix);
const count = raw === null ? 0 : Number.parseInt(raw, 10) || 0;
// The memory adapter does not expose a `ttl` helper, so derive a
// best-effort retry window from the configured window length. Redis
// counter TTL is enforced by the limiter on `consume`, so a fresh
// request entering the window gets the full window-seconds back.
const ttlSeconds = count > 0 ? LOGIN_RATE_LIMIT_WINDOW_SECONDS : 0;
return { count, ttlSeconds };
function retryAfterSeconds(resetAt: Date): number {
return Math.max(1, Math.ceil((resetAt.getTime() - Date.now()) / 1000));
}
function readHeader(headers: LoginRateLimitRequest["headers"], name: string): string | undefined {
@@ -0,0 +1,52 @@
import argon2 from "argon2";
import bcrypt from "bcryptjs";
import { describe, expect, test } from "vitest";
import { DUMMY_PASSWORD_HASH, hashCurrentPassword, isLegacyBcryptHash, verifySupportedPassword } from "./password.js";
describe("verifySupportedPassword", () => {
test("verifies current Argon2id hashes", async () => {
const hash = await argon2.hash("correct horse battery staple", {
type: argon2.argon2id,
memoryCost: 19_456,
timeCost: 2,
parallelism: 1,
});
await expect(verifySupportedPassword("correct horse battery staple", hash)).resolves.toBe(true);
await expect(verifySupportedPassword("wrong password", hash)).resolves.toBe(false);
});
test("keeps bcrypt as a verify-only legacy format", async () => {
const hash = await bcrypt.hash("legacy password", 4);
await expect(verifySupportedPassword("legacy password", hash)).resolves.toBe(true);
await expect(verifySupportedPassword("wrong password", hash)).resolves.toBe(false);
});
test("rejects bcrypt credentials that would be silently truncated after 72 bytes", async () => {
const exactPrefix = "x".repeat(72);
const hash = await bcrypt.hash(exactPrefix, 4);
await expect(verifySupportedPassword(exactPrefix, hash)).resolves.toBe(true);
await expect(verifySupportedPassword(`${exactPrefix}attacker-controlled-suffix`, hash)).resolves.toBe(false);
});
test("rejects unknown and corrupt hashes without throwing", async () => {
await expect(verifySupportedPassword("password", "not-a-password-hash")).resolves.toBe(false);
await expect(verifySupportedPassword("password", "$argon2id$corrupt")).resolves.toBe(false);
await expect(verifySupportedPassword("password", "$2b$corrupt")).resolves.toBe(false);
});
test("uses a structurally valid Argon2id dummy hash", async () => {
expect(DUMMY_PASSWORD_HASH).toMatch(/^\$argon2id\$/);
await expect(verifySupportedPassword("not-the-dummy-password", DUMMY_PASSWORD_HASH)).resolves.toBe(false);
});
test("creates current hashes and identifies only legacy bcrypt hashes", async () => {
const currentHash = await hashCurrentPassword("new password");
expect(currentHash).toMatch(/^\$argon2id\$/);
expect(isLegacyBcryptHash(currentHash)).toBe(false);
expect(isLegacyBcryptHash(await bcrypt.hash("legacy password", 4))).toBe(true);
});
});
@@ -0,0 +1,59 @@
import bcrypt from "bcryptjs";
const ARGON2_PREFIX_RE = /^\$argon2(?:i|d|id)\$/;
const BCRYPT_PREFIX_RE = /^\$2[abxy]\$/;
const BCRYPT_MAX_PASSWORD_BYTES = 72;
const ARGON2_OPTIONS = {
memoryCost: 19_456,
timeCost: 2,
parallelism: 1,
} as const;
// This hash uses the same Argon2id parameters as the web password hasher. It
// is intentionally not tied to a real account and is used only to make the
// unknown/passwordless-account paths perform a real password verification.
export const DUMMY_PASSWORD_HASH =
"$argon2id$v=19$m=19456,t=2,p=1$CGZ841jS/Rerhh41+cREiw$piaCzFMbzHjq946K2t0iN7iMI/389iUpLNm2HROGO4Y";
let argon2ModulePromise: Promise<typeof import("argon2")> | undefined;
function loadArgon2() {
argon2ModulePromise ??= import("argon2");
return argon2ModulePromise;
}
export function isLegacyBcryptHash(passwordHash: string): boolean {
return BCRYPT_PREFIX_RE.test(passwordHash);
}
export async function hashCurrentPassword(password: string): Promise<string> {
const argon2 = await loadArgon2();
return await argon2.hash(password, { ...ARGON2_OPTIONS, type: argon2.argon2id });
}
/**
* Verify current Argon2 hashes and legacy bcrypt hashes without allowing an
* unknown/corrupt hash format to escape as an authentication error detail.
* Argon2 is loaded lazily so non-login API processes do not pay its native
* module startup cost.
*/
export async function verifySupportedPassword(password: string, passwordHash: string): Promise<boolean> {
try {
if (ARGON2_PREFIX_RE.test(passwordHash)) {
const argon2 = await loadArgon2();
return await argon2.verify(passwordHash, password);
}
if (BCRYPT_PREFIX_RE.test(passwordHash)) {
// bcrypt silently truncates after 72 bytes. Reject an overlong legacy
// credential so a different suffix cannot authenticate as the same key.
if (Buffer.byteLength(password, "utf8") > BCRYPT_MAX_PASSWORD_BYTES) {
return false;
}
return await bcrypt.compare(password, passwordHash);
}
} catch {
return false;
}
return false;
}
@@ -0,0 +1,178 @@
// @vitest-environment node
import { beforeEach, describe, expect, test, vi } from "vitest";
const rlsMocks = vi.hoisted(() => ({
getDbClient: vi.fn(),
resolveUserSessionRlsIdentity: vi.fn(),
runWithRlsContext: vi.fn((_context: unknown, operation: () => unknown) => operation()),
}));
vi.mock("@hivegrid/db/client.server", () => ({ getDbClient: rlsMocks.getDbClient }));
vi.mock("@hivegrid/db/rls-resolvers.server", () => ({
resolveUserSessionRlsIdentity: rlsMocks.resolveUserSessionRlsIdentity,
}));
vi.mock("@hivegrid/db/rls-context.server", () => ({ runWithRlsContext: rlsMocks.runWithRlsContext }));
import {
createPersistentApiSession,
getActivePersistentApiSession,
hashApiSessionId,
revokePersistentApiSession,
rotatePersistentApiSession,
type ApiSessionPersistenceClient,
} from "./persistent-session-store.js";
function createFakeClient(now: () => Date): ApiSessionPersistenceClient {
const rows = new Map<string, { userId: string; createdAt: Date; expiresAt: Date; revokedAt: Date | null }>();
const client: ApiSessionPersistenceClient = {
userSession: {
async create({ data }) {
if (rows.has(data.tokenHash)) throw new Error("duplicate token hash");
const row = { userId: data.userId, createdAt: now(), expiresAt: data.expiresAt, revokedAt: null };
rows.set(data.tokenHash, row);
return { ...row };
},
async findUnique({ where }) {
const row = rows.get(where.tokenHash);
return row ? { ...row } : null;
},
async updateMany({ where, data }) {
const row = rows.get(where.tokenHash);
if (
!row ||
row.userId !== where.userId ||
row.revokedAt !== null ||
row.expiresAt.getTime() <= where.expiresAt.gt.getTime()
) {
return { count: 0 };
}
row.revokedAt = data.revokedAt;
return { count: 1 };
},
},
async $transaction(callback) {
return callback(client);
},
};
return client;
}
describe("persistent API sessions", () => {
beforeEach(() => {
vi.clearAllMocks();
});
test("stores only a hash and resolves an active opaque session", async () => {
const current = new Date("2026-07-12T10:00:00.000Z");
const client = createFakeClient(() => current);
const session = await createPersistentApiSession("user_1", {
client,
now: () => current,
generateSessionId: () => "opaque-session-secret",
});
expect(session).toMatchObject({ sessionId: "opaque-session-secret", userId: "user_1", createdAt: current });
expect(hashApiSessionId(session.sessionId)).not.toContain(session.sessionId);
await expect(getActivePersistentApiSession(session.sessionId, { client, now: () => current })).resolves.toMatchObject(session);
});
test("binds revocation to both the session and user", async () => {
const current = new Date("2026-07-12T10:00:00.000Z");
const client = createFakeClient(() => current);
const session = await createPersistentApiSession("user_1", { client, now: () => current, generateSessionId: () => "session-1" });
await expect(revokePersistentApiSession(session.sessionId, "other_user", { client, now: () => current })).resolves.toBeUndefined();
await expect(revokePersistentApiSession(session.sessionId, "user_1", { client, now: () => current })).resolves.toMatchObject({
sessionId: "session-1",
userId: "user_1",
revokeReason: "logout",
});
await expect(getActivePersistentApiSession(session.sessionId, { client, now: () => current })).resolves.toBeUndefined();
});
test("allows only one winner when the same refresh session is rotated concurrently", async () => {
const current = new Date("2026-07-12T10:00:00.000Z");
const client = createFakeClient(() => current);
const session = await createPersistentApiSession("user_1", { client, now: () => current, generateSessionId: () => "session-old" });
let nextId = 0;
const results = await Promise.all(
Array.from({ length: 8 }, () =>
rotatePersistentApiSession(session.sessionId, "user_1", {
client,
now: () => current,
generateSessionId: () => `session-new-${++nextId}`,
}),
),
);
expect(results.filter((result) => result.rotated)).toHaveLength(1);
expect(results.filter((result) => !result.rotated)).toHaveLength(7);
});
test("uses cryptographically random identifiers and real-time clocks when seams are omitted", async () => {
const client = createFakeClient(() => new Date());
const session = await createPersistentApiSession("user_1", { client });
expect(session.sessionId).toMatch(/^[A-Za-z0-9_-]{43}$/);
await expect(getActivePersistentApiSession(session.sessionId, { client })).resolves.toMatchObject({
sessionId: session.sessionId,
userId: "user_1",
});
const rotated = await rotatePersistentApiSession(session.sessionId, "user_1", { client });
expect(rotated).toMatchObject({ rotated: true });
if (!rotated.rotated) throw new Error("Expected the active session to rotate");
expect(rotated.session.sessionId).not.toBe(session.sessionId);
await expect(revokePersistentApiSession(rotated.session.sessionId, "user_1", { client })).resolves.toMatchObject({
sessionId: rotated.session.sessionId,
revokeReason: "logout",
});
});
test("binds default persistence operations to the resolved user RLS identity", async () => {
const current = new Date("2026-07-12T10:00:00.000Z");
const client = createFakeClient(() => current);
rlsMocks.getDbClient.mockReturnValue(client);
rlsMocks.resolveUserSessionRlsIdentity.mockResolvedValue({ resourceId: "session_1", userId: "user_1" });
const session = await createPersistentApiSession("user_1", {
now: () => current,
generateSessionId: () => "session-1",
});
await expect(getActivePersistentApiSession(session.sessionId, { now: () => current })).resolves.toMatchObject(session);
const rotated = await rotatePersistentApiSession(session.sessionId, "user_1", {
now: () => current,
generateSessionId: () => "session-2",
});
expect(rotated).toMatchObject({ rotated: true });
if (!rotated.rotated) throw new Error("Expected the active session to rotate");
await expect(revokePersistentApiSession(rotated.session.sessionId, "user_1", { now: () => current })).resolves.toMatchObject({
sessionId: "session-2",
userId: "user_1",
revokeReason: "logout",
});
expect(rlsMocks.resolveUserSessionRlsIdentity).toHaveBeenCalledWith(hashApiSessionId(session.sessionId));
expect(rlsMocks.runWithRlsContext.mock.calls.map(([context]) => context)).toEqual([
{ userId: "user_1" },
{ userId: "user_1" },
{ userId: "user_1" },
{ userId: "user_1" },
]);
});
test("fails closed before binding RLS when the opaque session cannot be resolved", async () => {
const client = createFakeClient(() => new Date("2026-07-12T10:00:00.000Z"));
rlsMocks.getDbClient.mockReturnValue(client);
rlsMocks.resolveUserSessionRlsIdentity.mockResolvedValue(null);
await expect(getActivePersistentApiSession("unknown-session")).resolves.toBeUndefined();
expect(rlsMocks.resolveUserSessionRlsIdentity).toHaveBeenCalledWith(hashApiSessionId("unknown-session"));
expect(rlsMocks.runWithRlsContext).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,178 @@
import { createHash, randomBytes } from "node:crypto";
import { getDbClient } from "@hivegrid/db/client.server";
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
import { resolveUserSessionRlsIdentity } from "@hivegrid/db/rls-resolvers.server";
import type { ApiSessionRecord, RotateApiSessionResult } from "./session-store.js";
const API_SESSION_TTL_MS = 60 * 60 * 1000;
type ApiSessionRow = {
userId: string;
createdAt: Date;
expiresAt: Date;
revokedAt: Date | null;
};
export type ApiSessionPersistenceClient = {
userSession: {
create(args: {
data: {
userId: string;
tokenHash: string;
expiresAt: Date;
userAgent: string;
deviceLabel: string;
};
select: { userId: true; createdAt: true; expiresAt: true; revokedAt: true };
}): Promise<ApiSessionRow>;
findUnique(args: {
where: { tokenHash: string };
select: { userId: true; createdAt: true; expiresAt: true; revokedAt: true };
}): Promise<ApiSessionRow | null>;
updateMany(args: {
where: { tokenHash: string; userId: string; revokedAt: null; expiresAt: { gt: Date } };
data: { revokedAt: Date };
}): Promise<{ count: number }>;
};
$transaction<T>(callback: (tx: ApiSessionPersistenceClient) => Promise<T>): Promise<T>;
};
type ApiSessionPersistenceOptions = {
client?: ApiSessionPersistenceClient;
now?: () => Date;
generateSessionId?: () => string;
};
export async function createPersistentApiSession(
userId: string,
options: ApiSessionPersistenceOptions = {},
): Promise<ApiSessionRecord> {
const client = options.client ?? (getDbClient() as unknown as ApiSessionPersistenceClient);
const operation = () => createSessionWithClient(client, userId, options.now ?? (() => new Date()), options.generateSessionId ?? generateApiSessionId);
return options.client ? operation() : runWithRlsContext({ userId }, operation);
}
export async function getActivePersistentApiSession(
sessionId: string,
options: Pick<ApiSessionPersistenceOptions, "client" | "now"> = {},
): Promise<ApiSessionRecord | undefined> {
const client = options.client ?? (getDbClient() as unknown as ApiSessionPersistenceClient);
if (!options.client) {
const tokenHash = hashApiSessionId(sessionId);
const identity = await resolveUserSessionRlsIdentity(tokenHash);
if (!identity) return undefined;
return runWithRlsContext({ userId: identity.userId }, () =>
getActivePersistentApiSession(sessionId, { ...options, client }),
);
}
const now = options.now?.() ?? new Date();
const row = await client.userSession.findUnique({
where: { tokenHash: hashApiSessionId(sessionId) },
select: { userId: true, createdAt: true, expiresAt: true, revokedAt: true },
});
if (!row || row.revokedAt !== null || row.expiresAt.getTime() <= now.getTime()) return undefined;
return toApiSessionRecord(sessionId, row);
}
export async function rotatePersistentApiSession(
sessionId: string,
userId: string,
options: ApiSessionPersistenceOptions = {},
): Promise<RotateApiSessionResult> {
const client = options.client ?? (getDbClient() as unknown as ApiSessionPersistenceClient);
if (!options.client) {
return runWithRlsContext({ userId }, () => rotatePersistentApiSession(sessionId, userId, { ...options, client }));
}
const now = options.now ?? (() => new Date());
const generateSessionId = options.generateSessionId ?? generateApiSessionId;
return client.$transaction(async (tx) => {
const revokedAt = now();
const claimed = await tx.userSession.updateMany({
where: {
tokenHash: hashApiSessionId(sessionId),
userId,
revokedAt: null,
expiresAt: { gt: revokedAt },
},
data: { revokedAt },
});
if (claimed.count !== 1) return { rotated: false, reason: "unknown" };
const session = await createSessionWithClient(tx, userId, now, generateSessionId);
return {
rotated: true,
previous: {
sessionId,
userId,
createdAt: revokedAt,
revokedAt,
revokeReason: "refresh",
},
session,
};
});
}
export async function revokePersistentApiSession(
sessionId: string,
userId: string,
options: Pick<ApiSessionPersistenceOptions, "client" | "now"> = {},
): Promise<ApiSessionRecord | undefined> {
const client = options.client ?? (getDbClient() as unknown as ApiSessionPersistenceClient);
if (!options.client) {
return runWithRlsContext({ userId }, () => revokePersistentApiSession(sessionId, userId, { ...options, client }));
}
const revokedAt = options.now?.() ?? new Date();
const result = await client.userSession.updateMany({
where: {
tokenHash: hashApiSessionId(sessionId),
userId,
revokedAt: null,
expiresAt: { gt: revokedAt },
},
data: { revokedAt },
});
if (result.count !== 1) return undefined;
return { sessionId, userId, createdAt: revokedAt, revokedAt, revokeReason: "logout" };
}
export function hashApiSessionId(sessionId: string): string {
return createHash("sha256").update(`hivegrid-api-session:${sessionId}`).digest("hex");
}
function generateApiSessionId(): string {
return randomBytes(32).toString("base64url");
}
async function createSessionWithClient(
client: ApiSessionPersistenceClient,
userId: string,
now: () => Date,
generateSessionId: () => string,
): Promise<ApiSessionRecord> {
const sessionId = generateSessionId();
const createdAt = now();
const row = await client.userSession.create({
data: {
userId,
tokenHash: hashApiSessionId(sessionId),
expiresAt: new Date(createdAt.getTime() + API_SESSION_TTL_MS),
userAgent: "HiveGrid API",
deviceLabel: "API session",
},
select: { userId: true, createdAt: true, expiresAt: true, revokedAt: true },
});
return toApiSessionRecord(sessionId, row);
}
function toApiSessionRecord(sessionId: string, row: ApiSessionRow): ApiSessionRecord {
return {
sessionId,
userId: row.userId,
createdAt: row.createdAt,
revokedAt: row.revokedAt ?? undefined,
};
}
@@ -0,0 +1,50 @@
// @vitest-environment node
import jwt from "jsonwebtoken";
import { describe, expect, test } from "vitest";
import { createApiSessionToken, verifyApiSessionToken } from "./session-token.js";
const SECRET = "a-purpose-specific-api-session-secret";
describe("API session JWT contract", () => {
test("binds type, issuer, audience, subject, user and server session", () => {
const token = createApiSessionToken({ userId: "user_1", sessionId: "session_1", secret: SECRET });
expect(verifyApiSessionToken(token, SECRET)).toMatchObject({
type: "api_session",
iss: "hivegrid-api",
aud: "hivegrid-api-session",
sub: "user_1",
userId: "user_1",
sessionId: "session_1",
});
});
test.each([
jwt.sign({ userId: "user_1", sessionId: "session_1" }, SECRET),
jwt.sign({ userId: "user_1", sessionId: "session_1", type: "api_session" }, SECRET, {
issuer: "other-service",
audience: "hivegrid-api-session",
subject: "user_1",
}),
jwt.sign({ userId: "user_1", sessionId: "session_1", type: "api_session" }, SECRET, {
issuer: "hivegrid-api",
audience: "other-audience",
subject: "user_1",
}),
])("rejects legacy or cross-purpose tokens", (token) => {
expect(() => verifyApiSessionToken(token, SECRET)).toThrow();
});
test("rejects a token whose subject is not the claimed user", () => {
const token = jwt.sign({ userId: "user_1", sessionId: "session_1", type: "api_session" }, SECRET, {
algorithm: "HS256",
issuer: "hivegrid-api",
audience: "hivegrid-api-session",
subject: "user_2",
});
expect(verifyApiSessionToken(token, SECRET)).toBeNull();
});
});
@@ -0,0 +1,47 @@
import jwt, { type JwtPayload } from "jsonwebtoken";
const API_SESSION_ISSUER = "hivegrid-api";
const API_SESSION_AUDIENCE = "hivegrid-api-session";
const API_SESSION_TOKEN_TYPE = "api_session";
export type ApiSessionTokenClaims = JwtPayload & {
userId: string;
sessionId: string;
type: typeof API_SESSION_TOKEN_TYPE;
};
export function createApiSessionToken(input: { userId: string; sessionId: string; secret: string }): string {
return jwt.sign(
{
userId: input.userId,
sessionId: input.sessionId,
type: API_SESSION_TOKEN_TYPE,
},
input.secret,
{
algorithm: "HS256",
audience: API_SESSION_AUDIENCE,
issuer: API_SESSION_ISSUER,
subject: input.userId,
expiresIn: "1h",
},
);
}
export function verifyApiSessionToken(token: string, secret: string): ApiSessionTokenClaims | null {
const decoded = jwt.verify(token, secret, {
algorithms: ["HS256"],
audience: API_SESSION_AUDIENCE,
issuer: API_SESSION_ISSUER,
});
if (
typeof decoded === "string" ||
decoded.type !== API_SESSION_TOKEN_TYPE ||
typeof decoded.userId !== "string" ||
typeof decoded.sessionId !== "string" ||
decoded.sub !== decoded.userId
) {
return null;
}
return decoded as ApiSessionTokenClaims;
}
@@ -0,0 +1,418 @@
import { createHmac } from "node:crypto";
import type { ApiConfig } from "@hivegrid/config";
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
import { createSharedStore, MemoryAdapter } from "@hivegrid/shared-store";
import { Hono } from "hono";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { resetApiRuntimeConfigForTests, setApiRuntimeConfigForTests } from "../config.js";
import type { ApiErrorEnv } from "../middleware/error-envelope.js";
import { __resetPublicIngressRateLimitDependenciesForTests, __setPublicIngressRateLimitDependenciesForTests } from "../public-ingress-rate-limit.js";
import { postLagoBillingWebhookRequest, verifyLagoWebhookSignature, type LagoBillingWebhookDependencies } from "./lago-webhook-route.js";
const WEBHOOK_SECRET = "lago-webhook-secret-with-at-least-32-bytes";
const TEST_API_CONFIG: ApiConfig = {
appName: "Test API",
nodeEnv: "test",
revision: "unknown",
listen: { port: 3001 },
routing: {
appBaseDomain: "localhost:3000",
webAppHost: "app.localhost:3000",
adminAppHost: "admin.localhost:3000",
apiHost: "api.localhost:3000",
portalAppHost: "portal.localhost:3000",
protocol: "http",
},
origins: {},
apiAccessToken: "test-api-access-token",
jwtSecret: "test-jwt-secret-with-32-bytes-padding",
analytics: {},
mailjet: {},
lago: { webhookSecret: WEBHOOK_SECRET, timeoutMs: 10_000 },
mollie: { timeoutMs: 10_000 },
apiKeys: { allowLegacyPlaintextFallback: true },
storage: {},
};
beforeEach(() => {
setApiRuntimeConfigForTests(TEST_API_CONFIG);
__setPublicIngressRateLimitDependenciesForTests({
store: createSharedStore({ namespace: "lago-webhook-rate-limit-test", adapter: new MemoryAdapter() }),
keySecret: "lago-webhook-rate-limit-key-secret",
});
});
afterEach(() => {
resetApiRuntimeConfigForTests();
__resetPublicIngressRateLimitDependenciesForTests();
});
function subscriptionPayload(overrides: Record<string, unknown> = {}) {
return {
webhook_type: "subscription.started",
object_type: "subscription",
organization_id: "organization_1",
subscription: {
lago_id: "lago_subscription_1",
external_id: "subscription_1",
external_customer_id: "tenant_1",
plan_code: "starter",
status: "active",
current_billing_period_started_at: "2026-07-01T00:00:00Z",
current_billing_period_ending_at: "2026-08-01T00:00:00Z",
},
...overrides,
};
}
function buildDependencies(overrides: Partial<LagoBillingWebhookDependencies> = {}): LagoBillingWebhookDependencies {
return {
findLegacyTenantById: vi.fn(async () => {
expect(getRlsExecutionContext()).toMatchObject({ tenantId: "tenant_1" });
return { id: "tenant_1", name: "Acme" } as never;
}),
applyLagoSubscriptionSync: vi.fn(async (input) => {
expect(getRlsExecutionContext()).toMatchObject({ tenantId: "tenant_1" });
return {
tenantId: input.tenantId,
provider: "lago" as const,
idempotencyKey: input.eventKey,
replayed: false,
status: "active" as const,
};
}),
reserveRecurringInvoiceCollection: vi.fn(async () => ({
collectionId: "hgrc_invoice_1",
disposition: "queued" as const,
})),
resolveLagoSubscriptionProductKind: vi.fn(async () => "base_plan" as const),
...overrides,
};
}
function buildApp(dependencies: LagoBillingWebhookDependencies) {
const app = new Hono<ApiErrorEnv>();
app.post("/v1/billing/lago/webhooks", (c) => postLagoBillingWebhookRequest(c, dependencies));
return app;
}
function signedRequest(app: ReturnType<typeof buildApp>, payload: unknown, headers: Record<string, string> = {}) {
const rawBody = typeof payload === "string" ? payload : JSON.stringify(payload);
const signature = createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("base64");
return app.request("/v1/billing/lago/webhooks", {
method: "POST",
headers: {
"content-type": "application/json",
"x-lago-signature": signature,
"x-lago-signature-algorithm": "hmac",
"x-lago-unique-key": "provider-event-1",
...headers,
},
body: rawBody,
});
}
describe("postLagoBillingWebhookRequest", () => {
it("verifies Lago HMAC and applies a tenant-scoped subscription event", async () => {
const dependencies = buildDependencies();
const response = await signedRequest(buildApp(dependencies), subscriptionPayload());
expect(response.status).toBe(200);
await expect(response.json()).resolves.toEqual({
received: true,
provider: "lago",
webhookType: "subscription.started",
disposition: "synced",
synced: true,
replayed: false,
billingStatus: "active",
});
expect(dependencies.findLegacyTenantById).toHaveBeenCalledWith("tenant_1");
expect(dependencies.applyLagoSubscriptionSync).toHaveBeenCalledWith({
tenantId: "tenant_1",
eventKey: expect.stringMatching(/^lago:webhook:[a-f0-9]{64}$/u),
lagoSubscriptionId: "subscription_1",
billingProviderSubscriptionId: "lago_subscription_1",
status: "active",
planCode: "starter",
productKind: "base_plan",
currentPeriodStart: new Date("2026-07-01T00:00:00Z"),
currentPeriodEnd: new Date("2026-08-01T00:00:00Z"),
receivedAt: expect.any(Date),
});
});
it("surfaces a replay returned by the persistent billing sync boundary", async () => {
const dependencies = buildDependencies({
applyLagoSubscriptionSync: vi.fn(async (input) => ({
tenantId: input.tenantId,
provider: "lago" as const,
idempotencyKey: input.eventKey,
replayed: true,
status: "active" as const,
})),
});
const response = await signedRequest(buildApp(dependencies), subscriptionPayload());
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({
disposition: "replayed",
synced: false,
replayed: true,
});
});
it("rejects an invalid signature before parsing or tenant access", async () => {
const dependencies = buildDependencies();
const response = await signedRequest(buildApp(dependencies), "{not-json", {
"x-lago-signature": Buffer.alloc(32, 1).toString("base64"),
});
expect(response.status).toBe(401);
await expect(response.json()).resolves.toMatchObject({
error: { code: "invalid_webhook_signature" },
});
expect(dependencies.findLegacyTenantById).not.toHaveBeenCalled();
expect(dependencies.applyLagoSubscriptionSync).not.toHaveBeenCalled();
});
it("does not let a recurring add-on lifecycle event replace the tenant base plan", async () => {
const dependencies = buildDependencies({
resolveLagoSubscriptionProductKind: vi.fn(async () => "recurring_add_on" as const),
});
const response = await signedRequest(
buildApp(dependencies),
subscriptionPayload({
subscription: {
...subscriptionPayload().subscription,
plan_code: "customer_portal_monthly",
},
})
);
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({ disposition: "ignored" });
expect(dependencies.resolveLagoSubscriptionProductKind).toHaveBeenCalledWith("customer_portal_monthly");
expect(dependencies.applyLagoSubscriptionSync).not.toHaveBeenCalled();
});
it.each([
["missing signature", { "x-lago-signature": "" }],
["unsupported algorithm", { "x-lago-signature-algorithm": "jwt" }],
["missing unique key", { "x-lago-unique-key": "" }],
["non-canonical signature", { "x-lago-signature": "not_base64" }],
])("rejects %s", async (_label, headers) => {
const dependencies = buildDependencies();
const response = await signedRequest(buildApp(dependencies), subscriptionPayload(), headers);
expect(response.status).toBe(401);
expect(dependencies.findLegacyTenantById).not.toHaveBeenCalled();
expect(dependencies.applyLagoSubscriptionSync).not.toHaveBeenCalled();
});
it("rejects authenticated malformed JSON without tenant access", async () => {
const dependencies = buildDependencies();
const response = await signedRequest(buildApp(dependencies), "{not-json");
expect(response.status).toBe(400);
await expect(response.json()).resolves.toMatchObject({
error: { code: "invalid_request" },
});
expect(dependencies.findLegacyTenantById).not.toHaveBeenCalled();
});
it("acknowledges signed invoice events without mutating subscription state", async () => {
const dependencies = buildDependencies();
const response = await signedRequest(buildApp(dependencies), {
webhook_type: "invoice.created",
object_type: "invoice",
organization_id: "organization_1",
invoice: {
lago_id: "invoice_1",
external_customer_id: "tenant_1",
},
});
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({
webhookType: "invoice.created",
disposition: "ignored",
synced: false,
});
expect(dependencies.findLegacyTenantById).toHaveBeenCalledWith("tenant_1");
expect(dependencies.applyLagoSubscriptionSync).not.toHaveBeenCalled();
expect(dependencies.reserveRecurringInvoiceCollection).not.toHaveBeenCalled();
});
it("queues a finalized pending subscription invoice for recurring collection", async () => {
const dependencies = buildDependencies();
const response = await signedRequest(buildApp(dependencies), {
webhook_type: "invoice.created",
object_type: "invoice",
organization_id: "organization_1",
invoice: {
lago_id: "invoice_2026_08",
external_customer_id: "tenant_1",
invoice_type: "subscription",
status: "finalized",
payment_status: "pending",
currency: "EUR",
total_amount_cents: 23_681,
created_at: "2026-08-01T00:00:00Z",
billing_periods: [{
external_subscription_id: "subscription_1",
lago_subscription_id: "lago_subscription_1",
invoicing_reason: "subscription_periodic",
}],
},
});
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({
disposition: "queued",
recurringCollectionId: "hgrc_invoice_1",
});
expect(dependencies.reserveRecurringInvoiceCollection).toHaveBeenCalledWith({
tenantId: "tenant_1",
invoiceExternalId: "invoice_2026_08",
lagoSubscriptionId: "subscription_1",
billingProviderSubscriptionId: "lago_subscription_1",
invoicingReason: "subscription_periodic",
invoiceCreatedAt: new Date("2026-08-01T00:00:00.000Z"),
amountCents: 23_681,
currency: "EUR",
receivedAt: expect.any(Date),
});
expect(dependencies.applyLagoSubscriptionSync).not.toHaveBeenCalled();
});
it("returns retryable unavailable while the local billing mirror is not ready", async () => {
const dependencies = buildDependencies({
reserveRecurringInvoiceCollection: vi.fn(async () => ({
collectionId: "hgrc_invoice_1",
disposition: "not_ready" as const,
})),
});
const response = await signedRequest(buildApp(dependencies), {
webhook_type: "invoice.created",
object_type: "invoice",
organization_id: "organization_1",
invoice: {
lago_id: "invoice_2026_08",
external_customer_id: "tenant_1",
invoice_type: "subscription",
status: "finalized",
payment_status: "pending",
currency: "EUR",
total_amount_cents: 23_681,
created_at: "2026-08-01T00:00:00Z",
billing_periods: [{
external_subscription_id: "subscription_1",
lago_subscription_id: "lago_subscription_1",
invoicing_reason: "subscription_starting",
}],
},
});
expect(response.status).toBe(503);
await expect(response.json()).resolves.toMatchObject({
error: { code: "dependency_unavailable" },
});
});
it.each([
["missing reason", [{ external_subscription_id: "subscription_1", lago_subscription_id: "lago_subscription_1" }]],
["future reason", [{ external_subscription_id: "subscription_1", lago_subscription_id: "lago_subscription_1", invoicing_reason: "subscription_adjusted" }]],
["multiple subscriptions", [
{ external_subscription_id: "subscription_1", lago_subscription_id: "lago_subscription_1", invoicing_reason: "subscription_periodic" },
{ external_subscription_id: "subscription_2", lago_subscription_id: "lago_subscription_2", invoicing_reason: "subscription_periodic" },
]],
])("returns retryable unavailable for %s on a collectible subscription invoice", async (_label, billingPeriods) => {
const dependencies = buildDependencies();
const response = await signedRequest(buildApp(dependencies), {
webhook_type: "invoice.created",
object_type: "invoice",
organization_id: "organization_1",
invoice: {
lago_id: "invoice_uncorrelated",
external_customer_id: "tenant_1",
invoice_type: "subscription",
status: "finalized",
payment_status: "pending",
currency: "EUR",
total_amount_cents: 23_681,
created_at: "2026-08-01T00:00:00Z",
billing_periods: billingPeriods,
},
});
expect(response.status).toBe(503);
await expect(response.json()).resolves.toMatchObject({ error: { code: "dependency_unavailable" } });
expect(dependencies.reserveRecurringInvoiceCollection).not.toHaveBeenCalled();
});
it("acknowledges a signed event for a deleted tenant without revealing tenant state", async () => {
const dependencies = buildDependencies({
findLegacyTenantById: vi.fn(async () => null),
});
const response = await signedRequest(buildApp(dependencies), subscriptionPayload());
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({
disposition: "ignored",
synced: false,
});
expect(dependencies.applyLagoSubscriptionSync).not.toHaveBeenCalled();
});
it("acknowledges pending subscriptions without prematurely changing the local plan", async () => {
const dependencies = buildDependencies();
const response = await signedRequest(
buildApp(dependencies),
subscriptionPayload({
webhook_type: "subscription.created",
subscription: {
...subscriptionPayload().subscription,
status: "pending",
},
})
);
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({ disposition: "ignored" });
expect(dependencies.applyLagoSubscriptionSync).not.toHaveBeenCalled();
});
it("fails closed when the Lago webhook secret is not configured", async () => {
setApiRuntimeConfigForTests({
...TEST_API_CONFIG,
lago: { timeoutMs: 10_000 },
});
const dependencies = buildDependencies();
const response = await signedRequest(buildApp(dependencies), subscriptionPayload());
expect(response.status).toBe(503);
await expect(response.json()).resolves.toMatchObject({
error: { code: "dependency_unavailable" },
});
expect(dependencies.findLegacyTenantById).not.toHaveBeenCalled();
});
});
describe("verifyLagoWebhookSignature", () => {
it("accepts the canonical Lago base64 HMAC contract", () => {
const rawBody = JSON.stringify(subscriptionPayload());
const signature = createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("base64");
expect(verifyLagoWebhookSignature({ rawBody, signature, webhookSecret: WEBHOOK_SECRET })).toBe(true);
});
it("rejects malformed base64 and signatures for a changed body", () => {
const signature = createHmac("sha256", WEBHOOK_SECRET).update("{}").digest("base64");
expect(verifyLagoWebhookSignature({ rawBody: "{}", signature: "not_base64", webhookSecret: WEBHOOK_SECRET })).toBe(false);
expect(verifyLagoWebhookSignature({ rawBody: '{"changed":true}', signature, webhookSecret: WEBHOOK_SECRET })).toBe(false);
});
});
@@ -0,0 +1,283 @@
import { createHash, createHmac, timingSafeEqual } from "node:crypto";
import { isLagoV1WebhookEvent, parseLagoWebhookEvent, resolveLagoWebhookTenantId, type LagoWebhookEvent } from "@hivegrid/billing";
import type { BillingSyncResult } from "@hivegrid/db/billing-sync.server";
import type { ReserveRecurringInvoiceCollectionResult } from "@hivegrid/db/recurring-invoice-collection.server";
import type { Context } from "hono";
import { ZodError } from "zod";
import type { ApiAppDependencies } from "../app.js";
import { getApiRuntimeConfig } from "../config.js";
import { apiError, type ApiErrorEnv } from "../middleware/error-envelope.js";
import { applyPublicIngressRateLimitHeaders, checkPublicIngressRateLimit } from "../public-ingress-rate-limit.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { apiErrorReporter } from "../sentry.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
const LAGO_SIGNATURE_HEADER = "x-lago-signature";
const LAGO_SIGNATURE_ALGORITHM_HEADER = "x-lago-signature-algorithm";
const LAGO_UNIQUE_KEY_HEADER = "x-lago-unique-key";
const MAX_LAGO_UNIQUE_KEY_LENGTH = 512;
export type LagoBillingWebhookDependencies = Pick<
ApiAppDependencies,
"applyLagoSubscriptionSync" | "findLegacyTenantById" | "reserveRecurringInvoiceCollection" | "resolveLagoSubscriptionProductKind"
>;
export async function postLagoBillingWebhookRequest(c: Context<ApiErrorEnv>, dependencies: LagoBillingWebhookDependencies) {
const webhookSecret = getApiRuntimeConfig().lago.webhookSecret?.trim();
if (!webhookSecret) {
return apiError(c, 503, "dependency_unavailable", "Lago billing webhook configuration is unavailable.");
}
const clientIp = getTrustedClientIp(c.req.raw) || "unknown";
for (const [scope, bucket] of [
["lago-webhook-ip", clientIp],
["lago-webhook-global", "global"],
] as const) {
const rateLimit = await checkPublicIngressRateLimit(scope, bucket);
applyPublicIngressRateLimitHeaders((name, value) => c.header(name, value), rateLimit);
if (!rateLimit.allowed) {
return rateLimit.unavailable
? apiError(c, 503, "rate_limit_unavailable", "Lago webhook processing is temporarily unavailable.")
: apiError(c, 429, "rate_limited", "Too many Lago webhook requests. Try again later.");
}
}
const algorithm = c.req.header(LAGO_SIGNATURE_ALGORITHM_HEADER)?.trim().toLowerCase();
const signature = c.req.header(LAGO_SIGNATURE_HEADER)?.trim();
const uniqueKey = c.req.header(LAGO_UNIQUE_KEY_HEADER)?.trim();
if (algorithm !== "hmac" || !signature || !uniqueKey || uniqueKey.length > MAX_LAGO_UNIQUE_KEY_LENGTH) {
return apiError(c, 401, "invalid_webhook_signature", "Lago webhook authentication failed.");
}
const rawBody = await c.req.text();
if (!verifyLagoWebhookSignature({ rawBody, signature, webhookSecret })) {
return apiError(c, 401, "invalid_webhook_signature", "Lago webhook authentication failed.");
}
let event: LagoWebhookEvent;
try {
event = parseLagoWebhookEvent(JSON.parse(rawBody));
} catch (error) {
if (error instanceof SyntaxError || error instanceof ZodError) {
return apiError(c, 400, "invalid_request", "Invalid Lago webhook payload.");
}
throw error;
}
if (!isLagoV1WebhookEvent(event)) {
return apiError(c, 400, "invalid_provider_payload", "Lago webhook payload is missing provider references.");
}
const tenantId = resolveLagoWebhookTenantId(event);
if (!tenantId) {
return acceptedResponse(c, event, null, "ignored");
}
return runWithVerifiedApiRlsContext({ tenantId }, async () => {
const tenant = await dependencies.findLegacyTenantById(tenantId);
if (!tenant) {
return acceptedResponse(c, event, null, "ignored");
}
const recurringInvoice = resolveRecurringInvoiceCollectionInput(event, tenantId);
if (recurringInvoice) {
const collection = await dependencies.reserveRecurringInvoiceCollection(recurringInvoice);
if (collection.disposition === "not_ready") {
return apiError(c, 503, "dependency_unavailable", "Recurring invoice collection is waiting for the local billing mirror.");
}
return acceptedResponse(
c,
event,
null,
collection.disposition === "queued" ? "queued" : collection.disposition === "replayed" ? "replayed" : "ignored",
collection
);
}
if (isUnresolvedRecurringInvoiceCandidate(event)) {
await apiErrorReporter.report({
component: "api",
operation: "billing.lago-recurring-invoice-correlation-invalid",
severity: "error",
tenantId,
invoiceExternalId: event.invoice?.lago_id,
});
return apiError(c, 503, "dependency_unavailable", "Recurring invoice correlation is incomplete; Lago must retry this event.");
}
const subscription = event.object_type === "subscription" ? event.subscription : undefined;
const status = subscription ? resolveSubscriptionStatus(event.webhook_type!, subscription.status) : null;
if (!subscription || !status) {
return acceptedResponse(c, event, null, "ignored");
}
const productKind = await dependencies.resolveLagoSubscriptionProductKind(subscription.plan_code);
// Product acquisitions have their own fenced Mollie ledger and durable
// provider side effects. A generic Lago lifecycle event must never grant
// an add-on or replace the tenant's base plan as a side effect.
if (productKind !== "base_plan") {
return acceptedResponse(c, event, null, "ignored");
}
const result = await dependencies.applyLagoSubscriptionSync({
tenantId,
eventKey: lagoWebhookEventKey(uniqueKey),
lagoSubscriptionId: subscription.external_id,
billingProviderSubscriptionId: subscription.lago_id,
status,
planCode: subscription.plan_code,
productKind,
...(subscription.plan_code.endsWith("_annual_sepa")
? {
billingCadence: "annual_sepa",
commitmentEndsAt: parseProviderDate(subscription.ending_at),
}
: {}),
currentPeriodStart: parseProviderDate(subscription.current_billing_period_started_at),
currentPeriodEnd: parseProviderDate(subscription.current_billing_period_ending_at),
receivedAt: new Date(),
});
return acceptedResponse(c, event, result, result.replayed ? "replayed" : "synced");
});
}
function isUnresolvedRecurringInvoiceCandidate(event: LagoWebhookEvent): boolean {
const invoice = event.object_type === "invoice" ? event.invoice : undefined;
const status = invoice?.status?.trim().toLowerCase();
return Boolean(
invoice &&
event.webhook_type?.trim().toLowerCase() === "invoice.created" &&
invoice.invoice_type?.trim().toLowerCase() === "subscription" &&
(status === "finalized" || status === "pending") &&
invoice.payment_status?.trim().toLowerCase() === "pending"
);
}
export function verifyLagoWebhookSignature(input: { rawBody: string; signature: string; webhookSecret: string }): boolean {
const provided = decodeCanonicalBase64(input.signature);
if (!provided) return false;
const expected = createHmac("sha256", input.webhookSecret).update(input.rawBody).digest();
return provided.length === expected.length && timingSafeEqual(provided, expected);
}
function decodeCanonicalBase64(value: string): Buffer | null {
if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value)) {
return null;
}
const decoded = Buffer.from(value, "base64");
return decoded.toString("base64") === value ? decoded : null;
}
function lagoWebhookEventKey(uniqueKey: string): string {
return `lago:webhook:${createHash("sha256").update(uniqueKey).digest("hex")}`;
}
function resolveSubscriptionStatus(webhookType: string, payloadStatus: string | null | undefined): string | null {
const normalized = payloadStatus?.trim().toLowerCase().replaceAll("-", "_");
if (
normalized === "active" ||
normalized === "trial" ||
normalized === "trialing" ||
normalized === "past_due" ||
normalized === "failed" ||
normalized === "payment_failed" ||
normalized === "paused" ||
normalized === "suspended" ||
normalized === "frozen" ||
normalized === "cancelled" ||
normalized === "canceled" ||
normalized === "terminated"
) {
return normalized;
}
const type = webhookType.trim().toLowerCase();
if (type.endsWith(".started")) return "active";
if (type.endsWith(".terminated") || type.endsWith(".cancelled") || type.endsWith(".canceled")) {
return "terminated";
}
return null;
}
function parseProviderDate(value: string | null | undefined): Date | null {
const normalized = value?.trim();
if (!normalized) return null;
const timestamp = Date.parse(normalized);
return Number.isFinite(timestamp) ? new Date(timestamp) : null;
}
function resolveRecurringInvoiceCollectionInput(
event: LagoWebhookEvent,
tenantId: string
): Parameters<LagoBillingWebhookDependencies["reserveRecurringInvoiceCollection"]>[0] | null {
const invoice = event.object_type === "invoice" ? event.invoice : undefined;
if (!invoice || event.webhook_type?.trim().toLowerCase() !== "invoice.created") return null;
if (
invoice.invoice_type?.trim().toLowerCase() !== "subscription" ||
invoice.status?.trim().toLowerCase() !== "finalized" ||
invoice.payment_status?.trim().toLowerCase() !== "pending" ||
!Number.isSafeInteger(invoice.total_amount_cents) ||
(invoice.total_amount_cents ?? 0) <= 0
) {
return null;
}
const currency = invoice.currency?.trim().toUpperCase();
const invoiceCreatedAt = parseProviderDate(invoice.created_at);
if (!currency || !/^[A-Z]{3}$/u.test(currency) || !invoiceCreatedAt) return null;
const subscriptionReferences = [
...new Map(
(invoice.billing_periods ?? [])
.map((period) => ({
externalId: period.external_subscription_id?.trim() || null,
providerId: period.lago_subscription_id?.trim() || null,
invoicingReason: period.invoicing_reason,
}))
.filter(
(
reference
): reference is {
externalId: string;
providerId: string;
invoicingReason: "subscription_starting" | "subscription_periodic";
} =>
Boolean(
reference.externalId &&
reference.providerId &&
(reference.invoicingReason === "subscription_starting" || reference.invoicingReason === "subscription_periodic")
)
)
.map((reference) => [`${reference.externalId}\0${reference.providerId}\0${reference.invoicingReason}`, reference])
).values(),
];
if (subscriptionReferences.length !== 1) return null;
const subscriptionReference = subscriptionReferences[0]!;
return {
tenantId,
invoiceExternalId: invoice.lago_id,
lagoSubscriptionId: subscriptionReference.externalId,
billingProviderSubscriptionId: subscriptionReference.providerId,
invoicingReason: subscriptionReference.invoicingReason,
invoiceCreatedAt,
amountCents: invoice.total_amount_cents!,
currency,
receivedAt: new Date(),
};
}
function acceptedResponse(
c: Context<ApiErrorEnv>,
event: LagoWebhookEvent,
result: BillingSyncResult | null,
disposition: "synced" | "queued" | "replayed" | "ignored",
collection: ReserveRecurringInvoiceCollectionResult | null = null
) {
return c.json({
received: true,
provider: "lago",
webhookType: event.webhook_type,
disposition,
synced: disposition === "synced",
replayed: result?.replayed ?? false,
billingStatus: result?.status ?? null,
...(collection ? { recurringCollectionId: collection.collectionId } : {}),
});
}
@@ -1,10 +1,13 @@
import {
createLagoBillingGateway,
createMolliePaymentGateway,
ensureActiveLagoSubscription,
LagoBillingGatewayError,
MolliePaymentGatewayError,
reservationFromProviderExpiry,
resolveMollieWebhookPayment,
type BillingGatewayInvoice,
type BillingGatewaySubscription,
type PaymentGatewayPayment,
} from "@hivegrid/billing";
import type { ApplyLagoSubscriptionSyncInput, ApplyMolliePaymentSyncInput, BillingSyncResult } from "@hivegrid/db/billing-sync.server";
@@ -13,20 +16,59 @@ import type { Context } from "hono";
import type { ApiAppDependencies } from "../app.js";
import { getApiRuntimeConfig } from "../config.js";
import { apiError, type ApiErrorEnv } from "../middleware/error-envelope.js";
import { applyPublicIngressRateLimitHeaders, checkPublicIngressRateLimit } from "../public-ingress-rate-limit.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { apiErrorReporter } from "../sentry.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
type MollieWebhookInput = URLSearchParams | FormData | Record<string, unknown>;
type LagoInvoicePaymentStatusUpdateInput = {
tenantId: string;
invoiceExternalId: string;
lagoSubscriptionId: string | null;
lagoProviderSubscriptionId?: string | null;
amountCents: number | null;
paymentStatus: BillingGatewayInvoice["paymentStatus"];
correlationMode: "exact" | "legacy_tenant_amount_fallback";
};
type LagoInvoicePaymentStatusUpdater = (input: LagoInvoicePaymentStatusUpdateInput) => Promise<BillingGatewayInvoice | null>;
type LagoProductSubscriptionTerminator = (input: { subscriptionExternalId: string }) => Promise<void>;
type LagoPaidSubscriptionEnsurer = (input: {
tenantId: string;
subscriptionExternalId: string;
lagoPlanCode: string;
seatQuantity: number;
basePlanCode?: string | null;
endingAt?: Date | null;
}) => Promise<BillingGatewaySubscription>;
type LagoPendingSubscriptionTerminator = (input: { subscriptionExternalId: string }) => Promise<void>;
type ProductAcquisitionQuarantineCategory = "partial_refund" | "payment_quarantined";
const LAGO_INVOICE_DETAIL_CANDIDATE_LIMIT = 50;
const LAGO_INVOICE_DETAIL_ATTEMPTS_PER_CANDIDATE = 2;
const LAGO_INVOICE_DETAIL_REQUEST_LIMIT = LAGO_INVOICE_DETAIL_CANDIDATE_LIMIT * LAGO_INVOICE_DETAIL_ATTEMPTS_PER_CANDIDATE;
type ProductAcquisitionQuarantineReporter = (event: {
tenantId: string;
productAcquisitionId: string;
providerPaymentId: string;
category: ProductAcquisitionQuarantineCategory;
}) => void | Promise<void>;
export type MollieBillingWebhookDependencies = Pick<
ApiAppDependencies,
"applyLagoSubscriptionSync" | "applyMolliePaymentSync" | "findLegacyTenantById" | "resolveMollieWebhookPayment" | "updateLagoInvoicePaymentStatus"
>;
| "applyLagoSubscriptionSync"
| "applyMolliePaymentSync"
| "correlateCheckoutSessionProviderInvoice"
| "findLegacyTenantById"
| "getCheckoutSessionStatus"
| "resolveMollieWebhookPayment"
| "ensureLagoPaidSubscription"
| "terminateLagoPendingSubscription"
| "terminateLagoProductSubscription"
| "updateLagoInvoicePaymentStatus"
| "reserveRecurringInvoiceCollection"
> & {
reportProductAcquisitionQuarantine?: ProductAcquisitionQuarantineReporter;
};
export async function postMollieBillingWebhookRequest(c: Context<ApiErrorEnv>, dependencies: MollieBillingWebhookDependencies) {
const config = getApiRuntimeConfig();
@@ -34,6 +76,20 @@ export async function postMollieBillingWebhookRequest(c: Context<ApiErrorEnv>, d
return apiError(c, 503, "dependency_unavailable", "Mollie billing webhook configuration is unavailable.");
}
const clientIp = getTrustedClientIp(c.req.raw) || "unknown";
for (const [scope, bucket] of [
["mollie-webhook-ip", clientIp],
["mollie-webhook-global", "global"],
] as const) {
const rateLimit = await checkPublicIngressRateLimit(scope, bucket);
applyPublicIngressRateLimitHeaders((name, value) => c.header(name, value), rateLimit);
if (!rateLimit.allowed) {
return rateLimit.unavailable
? apiError(c, 503, "rate_limit_unavailable", "Mollie webhook processing is temporarily unavailable.")
: apiError(c, 429, "rate_limited", "Too many Mollie webhook requests. Try again later.");
}
}
const input = await parseMollieWebhookInput(c);
let payment: PaymentGatewayPayment;
try {
@@ -56,32 +112,209 @@ export async function postMollieBillingWebhookRequest(c: Context<ApiErrorEnv>, d
if (!tenantId || !invoiceExternalId) {
return apiError(c, 400, "invalid_provider_payload", "Mollie payment metadata is missing billing references.");
}
const tenant = await dependencies.findLegacyTenantById(tenantId);
if (!tenant) {
return apiError(c, 400, "invalid_provider_payload", "Mollie payment metadata references an unknown tenant.");
if (payment.metadata.billingFlow === "product_acquisition" && !hasCompleteProductAcquisitionMetadata(payment)) {
return apiError(c, 400, "invalid_provider_payload", "Mollie product acquisition metadata is incomplete.");
}
if (
payment.metadata.billingFlow === "recurring_invoice" &&
(!metadataString(payment.metadata.paymentExternalId) || !metadataString(payment.metadata.lagoSubscriptionId))
) {
return apiError(c, 400, "invalid_provider_payload", "Mollie recurring invoice metadata is incomplete.");
}
const receivedAt = new Date();
const result = await dependencies.applyMolliePaymentSync(buildMollieSyncInput(payment, tenantId, invoiceExternalId, receivedAt));
const invoicePaymentStatus = toLagoInvoicePaymentStatus(payment.status);
if (invoicePaymentStatus) {
try {
await dependencies.updateLagoInvoicePaymentStatus({
tenantId,
invoiceExternalId,
amountCents: payment.amountCents,
paymentStatus: invoicePaymentStatus,
});
} catch (error) {
if (error instanceof LagoBillingGatewayError) {
return apiError(c, 503, "provider_unavailable", "Lago invoice payment status sync failed.");
}
throw error;
return runWithVerifiedApiRlsContext({ tenantId }, async () => {
const tenant = await dependencies.findLegacyTenantById(tenantId);
if (!tenant) {
return apiError(c, 400, "invalid_provider_payload", "Mollie payment metadata references an unknown tenant.");
}
const selfServiceCheckoutId = isSelfServicePayment(payment) ? metadataString(payment.metadata.paymentExternalId) : null;
const selfServiceCheckout = selfServiceCheckoutId ? await dependencies.getCheckoutSessionStatus({ id: selfServiceCheckoutId, tenantId }) : null;
if (isSelfServicePayment(payment) && (!selfServiceCheckoutId || !selfServiceCheckout)) {
return apiError(c, 400, "invalid_provider_payload", "Mollie self-service payment has no matching checkout ledger row.");
}
const storedInvoiceExternalId = selfServiceCheckout?.invoiceExternalId?.trim() || null;
const hasDurableSelfServiceInvoice = Boolean(storedInvoiceExternalId && storedInvoiceExternalId !== invoiceExternalId);
const correlatedInvoiceExternalId = storedInvoiceExternalId ?? invoiceExternalId;
const receivedAt = new Date();
const result = await dependencies.applyMolliePaymentSync(buildMollieSyncInput(payment, tenantId, correlatedInvoiceExternalId, receivedAt));
const productAcquisition = payment.metadata.billingFlow === "product_acquisition";
const recurringInvoice = payment.metadata.billingFlow === "recurring_invoice";
let updatedLagoInvoice: BillingGatewayInvoice | null = null;
if (productAcquisition && result.productAcquisitionDisposition === "quarantined" && !result.replayed) {
await reportProductAcquisitionQuarantine(payment, tenantId, dependencies);
}
// Product-acquisition Lago effects are published transactionally by the
// accepted ledger transition and executed by the worker. Keeping them out
// of this request removes the crash window between DB commit and provider
// mutation, and prevents stale/quarantined webhooks targeting metadata.
if (!productAcquisition && requiresRecurringProductTermination(payment)) {
try {
await dependencies.terminateLagoProductSubscription({
subscriptionExternalId: metadataString(payment.metadata.lagoSubscriptionId)!,
});
} catch (error) {
if (error instanceof LagoBillingGatewayError) {
return apiError(c, 503, "provider_unavailable", "Lago product subscription cleanup failed.");
}
throw error;
}
}
let paidSelfServiceSubscription: BillingGatewaySubscription | null = null;
if (requiresImmediateSelfServiceActivation(payment, receivedAt)) {
const lagoPlanCode = metadataString(payment.metadata.lagoPlanCode);
const seatQuantity = payment.metadata.seatQuantity;
if (!lagoPlanCode || !seatQuantity) {
return apiError(c, 400, "invalid_provider_payload", "Mollie self-service payment metadata is incomplete.");
}
try {
paidSelfServiceSubscription = await dependencies.ensureLagoPaidSubscription({
tenantId,
subscriptionExternalId: metadataString(payment.metadata.lagoSubscriptionId)!,
lagoPlanCode,
seatQuantity,
basePlanCode: metadataString(payment.metadata.planCode),
endingAt: metadataDate(payment.metadata.commitmentEndsAt),
});
} catch (error) {
if (error instanceof LagoBillingGatewayError) {
return apiError(c, 503, "provider_unavailable", "Lago subscription activation failed.");
}
throw error;
}
} else if (requiresPendingSelfServiceTermination(payment)) {
try {
await dependencies.terminateLagoPendingSubscription({
subscriptionExternalId: metadataString(payment.metadata.lagoSubscriptionId)!,
});
} catch (error) {
if (error instanceof LagoBillingGatewayError) {
return apiError(c, 503, "provider_unavailable", "Lago pending subscription cleanup failed.");
}
throw error;
}
}
const invoicePaymentStatus = toLagoInvoicePaymentStatus(payment.status);
const shouldUpdateLagoInvoice =
!productAcquisition && invoicePaymentStatus !== null && (!isSelfServicePayment(payment) || payment.status === "paid" || hasDurableSelfServiceInvoice);
if (shouldUpdateLagoInvoice && invoicePaymentStatus) {
try {
updatedLagoInvoice = await dependencies.updateLagoInvoicePaymentStatus({
tenantId,
invoiceExternalId: correlatedInvoiceExternalId,
lagoSubscriptionId: metadataString(payment.metadata.lagoSubscriptionId),
lagoProviderSubscriptionId: paidSelfServiceSubscription?.providerSubscriptionId ?? metadataString(payment.metadata.lagoProviderSubscriptionId),
amountCents: payment.amountCents,
paymentStatus: invoicePaymentStatus,
correlationMode: recurringInvoice || hasDurableSelfServiceInvoice ? "exact" : "legacy_tenant_amount_fallback",
});
if ((recurringInvoice || requiresImmediateSelfServiceActivation(payment, receivedAt)) && !updatedLagoInvoice) {
return apiError(c, 503, "provider_unavailable", "Lago invoice payment status could not be correlated.");
}
} catch (error) {
if (error instanceof LagoBillingGatewayError) {
return apiError(c, 503, "provider_unavailable", "Lago invoice payment status sync failed.");
}
throw error;
}
}
if (isSelfServicePayment(payment) && payment.status === "paid" && updatedLagoInvoice && selfServiceCheckoutId) {
const lagoSubscriptionId = metadataString(payment.metadata.lagoSubscriptionId);
if (!lagoSubscriptionId) {
return apiError(c, 400, "invalid_provider_payload", "Mollie self-service payment metadata is incomplete.");
}
await dependencies.correlateCheckoutSessionProviderInvoice({
id: selfServiceCheckoutId,
tenantId,
providerPaymentId: payment.providerPaymentId,
lagoSubscriptionId,
sourceInvoiceExternalId: correlatedInvoiceExternalId,
providerInvoiceExternalId: updatedLagoInvoice.providerInvoiceId,
});
}
// Product acquisitions are granted exclusively by the fenced Mollie
// ledger transition above. The generic Lago mirror cannot distinguish a
// stale retry or quarantined paid event and must never create an
// entitlement as a side effect of either.
const subscriptionResult =
productAcquisition || recurringInvoice
? null
: await syncLagoSubscriptionFromPaidMolliePayment(
payment,
tenantId,
updatedLagoInvoice?.providerInvoiceId ?? correlatedInvoiceExternalId,
receivedAt,
dependencies,
paidSelfServiceSubscription
);
if (requiresImmediateSelfServiceActivation(payment, receivedAt) && updatedLagoInvoice) {
const lagoSubscriptionId = metadataString(payment.metadata.lagoSubscriptionId);
const billingProviderSubscriptionId = paidSelfServiceSubscription?.providerSubscriptionId ?? metadataString(payment.metadata.lagoProviderSubscriptionId);
if (!lagoSubscriptionId || !billingProviderSubscriptionId || !payment.amountCents || !payment.currency) {
return apiError(c, 400, "invalid_provider_payload", "Mollie self-service payment metadata is incomplete.");
}
const collection = await dependencies.reserveRecurringInvoiceCollection({
tenantId,
invoiceExternalId: updatedLagoInvoice.providerInvoiceId,
lagoSubscriptionId,
billingProviderSubscriptionId,
invoicingReason: "subscription_starting",
invoiceCreatedAt: parseProviderInvoiceDate(updatedLagoInvoice.issuingDate, receivedAt),
amountCents: payment.amountCents,
currency: payment.currency,
receivedAt,
});
if (collection.disposition === "not_ready" || collection.disposition === "queued") {
return apiError(c, 503, "provider_unavailable", "Initial Lago invoice settlement is not ready.");
}
}
return c.json(toMollieWebhookResponse(payment, result, subscriptionResult));
});
}
function parseProviderInvoiceDate(value: string | null | undefined, fallback: Date): Date {
if (!value) return fallback;
const timestamp = Date.parse(value);
return Number.isFinite(timestamp) ? new Date(timestamp) : fallback;
}
async function reportProductAcquisitionQuarantine(
payment: PaymentGatewayPayment,
tenantId: string,
dependencies: MollieBillingWebhookDependencies
): Promise<void> {
const productAcquisitionId = metadataString(payment.metadata.productAcquisitionId);
if (!productAcquisitionId) return;
const event = {
tenantId,
productAcquisitionId,
providerPaymentId: payment.providerPaymentId,
category: productAcquisitionQuarantineCategory(payment),
} satisfies Parameters<ProductAcquisitionQuarantineReporter>[0];
try {
if (dependencies.reportProductAcquisitionQuarantine) {
await dependencies.reportProductAcquisitionQuarantine(event);
return;
}
await apiErrorReporter.report({
component: "api",
operation: "billing.product_acquisition.quarantined",
severity: "error",
...event,
});
} catch {
// Observability must never alter the acknowledged provider webhook.
}
const subscriptionResult = await syncLagoSubscriptionFromPaidMolliePayment(payment, tenantId, invoiceExternalId, receivedAt, dependencies);
return c.json(toMollieWebhookResponse(payment, result, subscriptionResult));
}
function productAcquisitionQuarantineCategory(payment: PaymentGatewayPayment): ProductAcquisitionQuarantineCategory {
const refundedCents = payment.amountRefundedCents;
return typeof refundedCents === "number" && typeof payment.amountCents === "number" && refundedCents > 0 && refundedCents < payment.amountCents
? "partial_refund"
: "payment_quarantined";
}
export function createDefaultMollieWebhookResolver() {
@@ -102,7 +335,7 @@ export function createDefaultMollieWebhookResolver() {
}
export function createDefaultLagoInvoicePaymentStatusUpdater(): LagoInvoicePaymentStatusUpdater {
return async ({ tenantId, invoiceExternalId, amountCents, paymentStatus }) => {
return async ({ tenantId, invoiceExternalId, lagoSubscriptionId, lagoProviderSubscriptionId, amountCents, paymentStatus, correlationMode }) => {
const config = getApiRuntimeConfig();
if (!config.lago.apiUrl || !config.lago.apiKey) {
throw new LagoBillingGatewayError("Lago invoice sync configuration is unavailable.", "CONFIG_INVALID");
@@ -119,16 +352,209 @@ export function createDefaultLagoInvoicePaymentStatusUpdater(): LagoInvoicePayme
if (!(error instanceof LagoBillingGatewayError) || error.status !== 404) throw error;
}
const invoices = await gateway.listInvoices({ tenantId, perPage: 50 });
const matchingInvoice = invoices
.filter((invoice) => {
if (invoice.paymentStatus !== "pending") return false;
if (typeof amountCents === "number" && invoice.totalAmountCents !== amountCents) return false;
return invoice.providerInvoiceId.trim().length > 0;
})
.sort(compareInvoicesNewestFirst)[0];
if (!matchingInvoice) return null;
return gateway.updateInvoicePaymentStatus(matchingInvoice.providerInvoiceId, paymentStatus);
// Product acquisitions carry a ledger/acquisition id for recurring add-ons
// and an exact Lago invoice id for one-off products. Falling back to a
// tenant-wide amount match could settle an unrelated invoice with the same
// price, so this flow must fail closed when the exact id is not an invoice.
if (correlationMode === "exact") return null;
if (!lagoSubscriptionId) return null;
const invoiceDetails = new Map<string, BillingGatewayInvoice>();
const invoiceDetailAttempts = new Map<string, number>();
let invoiceDetailRequests = 0;
for (let attempt = 0; attempt < 12; attempt += 1) {
const invoices = await gateway.listInvoices({ tenantId, perPage: LAGO_INVOICE_DETAIL_CANDIDATE_LIMIT });
const candidates = invoices
.filter((invoice) => invoiceMatchesCheckoutSummary(invoice, { tenantId, amountCents, paymentStatus }))
.sort(compareInvoicesNewestFirst);
// Lago v1.50 omits `billing_periods` from invoice-list responses even
// though invoice detail contains the exact subscription identity. Walk
// the bounded page progressively and cache details so retries never hit
// the same ten rows forever. Every candidate gets the same two transient
// retry opportunities under one hard request ceiling.
const missingDetails = candidates
.filter(
(invoice) =>
invoiceNeedsDetailForSubscriptionCorrelation(invoice, lagoProviderSubscriptionId) &&
!invoiceDetails.has(invoice.providerInvoiceId) &&
(invoiceDetailAttempts.get(invoice.providerInvoiceId) ?? 0) < LAGO_INVOICE_DETAIL_ATTEMPTS_PER_CANDIDATE
)
.sort((left, right) => {
const attemptCompare = (invoiceDetailAttempts.get(left.providerInvoiceId) ?? 0) - (invoiceDetailAttempts.get(right.providerInvoiceId) ?? 0);
return attemptCompare !== 0 ? attemptCompare : compareInvoicesNewestFirst(left, right);
})
.slice(0, Math.min(10, LAGO_INVOICE_DETAIL_REQUEST_LIMIT - invoiceDetailRequests));
for (const candidate of missingDetails) {
invoiceDetailAttempts.set(candidate.providerInvoiceId, (invoiceDetailAttempts.get(candidate.providerInvoiceId) ?? 0) + 1);
invoiceDetailRequests += 1;
const detail = await gateway.getInvoice(candidate.providerInvoiceId);
if (
detail &&
invoiceDetailMatchesSummary(detail, candidate, paymentStatus) &&
!invoiceNeedsDetailForSubscriptionCorrelation(detail, lagoProviderSubscriptionId)
) {
invoiceDetails.set(candidate.providerInvoiceId, detail);
}
}
const allCandidatesResolved = candidates.every(
(candidate) =>
!invoiceNeedsDetailForSubscriptionCorrelation(candidate, lagoProviderSubscriptionId) || invoiceDetails.has(candidate.providerInvoiceId)
);
if (allCandidatesResolved) {
const exactMatches = candidates
.map((candidate) =>
invoiceNeedsDetailForSubscriptionCorrelation(candidate, lagoProviderSubscriptionId)
? invoiceDetails.get(candidate.providerInvoiceId) ?? null
: candidate
)
.filter((invoice): invoice is BillingGatewayInvoice =>
Boolean(
invoice &&
invoiceMatchesSubscription(invoice, {
tenantId,
lagoSubscriptionId,
lagoProviderSubscriptionId,
amountCents,
paymentStatus,
})
)
);
// The subscription identity should map to exactly one starting
// invoice. Ambiguity must never settle whichever row happened to sort
// first.
if (exactMatches.length > 1) return null;
const [matchingInvoice] = exactMatches;
if (matchingInvoice) {
if (matchingInvoice.paymentStatus === paymentStatus) return matchingInvoice;
return gateway.updateInvoicePaymentStatus(matchingInvoice.providerInvoiceId, paymentStatus);
}
}
if (attempt < 11) await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
}
return null;
};
}
function invoiceMatchesSubscription(
invoice: BillingGatewayInvoice,
expected: {
tenantId: string;
lagoSubscriptionId: string;
lagoProviderSubscriptionId?: string | null;
amountCents: number | null;
paymentStatus: BillingGatewayInvoice["paymentStatus"];
}
): boolean {
if (!invoiceMatchesCheckoutSummary(invoice, expected)) return false;
return Boolean(
invoice.billingPeriods?.some(
(period) =>
period.externalSubscriptionId === expected.lagoSubscriptionId &&
(!expected.lagoProviderSubscriptionId || period.providerSubscriptionId === expected.lagoProviderSubscriptionId) &&
period.invoicingReason === "subscription_starting"
)
);
}
function invoiceMatchesCheckoutSummary(
invoice: BillingGatewayInvoice,
expected: {
tenantId: string;
amountCents: number | null;
paymentStatus: BillingGatewayInvoice["paymentStatus"];
}
): boolean {
return (
invoice.providerInvoiceId.trim().length > 0 &&
invoice.externalCustomerId === expected.tenantId &&
invoice.invoiceType === "subscription" &&
invoice.status === "finalized" &&
(invoice.paymentStatus === "pending" || invoice.paymentStatus === expected.paymentStatus) &&
typeof expected.amountCents === "number" &&
invoice.totalAmountCents === expected.amountCents
);
}
function invoiceNeedsDetailForSubscriptionCorrelation(invoice: BillingGatewayInvoice, expectedProviderSubscriptionId?: string | null): boolean {
const periods = invoice.billingPeriods ?? [];
return (
periods.length === 0 ||
periods.some(
(period) =>
!period.externalSubscriptionId || !period.invoicingReason || (Boolean(expectedProviderSubscriptionId) && !period.providerSubscriptionId)
)
);
}
function invoiceDetailMatchesSummary(
detail: BillingGatewayInvoice,
summary: BillingGatewayInvoice,
expectedPaymentStatus: BillingGatewayInvoice["paymentStatus"]
): boolean {
return (
detail.providerInvoiceId === summary.providerInvoiceId &&
detail.externalCustomerId === summary.externalCustomerId &&
detail.invoiceType === summary.invoiceType &&
detail.status === summary.status &&
(detail.paymentStatus === summary.paymentStatus || detail.paymentStatus === expectedPaymentStatus) &&
detail.totalAmountCents === summary.totalAmountCents &&
detail.currency?.trim().toUpperCase() === summary.currency?.trim().toUpperCase()
);
}
export function createDefaultLagoProductSubscriptionTerminator(): LagoProductSubscriptionTerminator {
return async ({ subscriptionExternalId }) => {
const config = getApiRuntimeConfig();
if (!config.lago.apiUrl || !config.lago.apiKey) {
throw new LagoBillingGatewayError("Lago subscription cleanup configuration is unavailable.", "CONFIG_INVALID");
}
const gateway = createLagoBillingGateway({
apiUrl: config.lago.apiUrl,
apiKey: config.lago.apiKey,
timeoutMs: config.lago.timeoutMs,
});
await gateway.terminateSubscription(subscriptionExternalId);
};
}
export function createDefaultLagoPaidSubscriptionEnsurer(): LagoPaidSubscriptionEnsurer {
return async ({ tenantId, subscriptionExternalId, lagoPlanCode, seatQuantity, basePlanCode, endingAt }) => {
const config = getApiRuntimeConfig();
if (!config.lago.apiUrl || !config.lago.apiKey) {
throw new LagoBillingGatewayError("Lago subscription activation configuration is unavailable.", "CONFIG_INVALID");
}
const gateway = createLagoBillingGateway({
apiUrl: config.lago.apiUrl,
apiKey: config.lago.apiKey,
timeoutMs: config.lago.timeoutMs,
});
return ensureActiveLagoSubscription(gateway, {
tenantId,
subscriptionExternalId,
planCode: lagoPlanCode,
seatQuantity,
name: `${basePlanCode ?? "base-plan"} (${seatQuantity} seats)`,
endingAt,
paymentMethodType: "manual",
consolidateInvoice: false,
});
};
}
export function createDefaultLagoPendingSubscriptionTerminator(): LagoPendingSubscriptionTerminator {
return async ({ subscriptionExternalId }) => {
const config = getApiRuntimeConfig();
if (!config.lago.apiUrl || !config.lago.apiKey) {
throw new LagoBillingGatewayError("Lago pending subscription cleanup configuration is unavailable.", "CONFIG_INVALID");
}
const gateway = createLagoBillingGateway({
apiUrl: config.lago.apiUrl,
apiKey: config.lago.apiKey,
timeoutMs: config.lago.timeoutMs,
});
await gateway.terminatePendingSubscription(subscriptionExternalId);
};
}
@@ -149,18 +575,42 @@ async function parseMollieWebhookInput(c: Context): Promise<MollieWebhookInput>
return new URLSearchParams(await c.req.text());
}
function buildMollieSyncInput(
payment: PaymentGatewayPayment,
tenantId: string,
invoiceExternalId: string,
receivedAt: Date
): ApplyMolliePaymentSyncInput {
function buildMollieSyncInput(payment: PaymentGatewayPayment, tenantId: string, invoiceExternalId: string, receivedAt: Date): ApplyMolliePaymentSyncInput {
const productKind = productAcquisitionKind(payment);
const paymentExpiresAt = metadataDate(payment.expiresAt);
const paymentPaidAt = metadataDate(payment.paidAt);
return {
tenantId,
eventKey: buildMollieWebhookEventKey(payment),
mollieCustomerId: metadataString(payment.metadata.mollieCustomerId),
providerPaymentId: payment.providerPaymentId,
paymentExternalId: payment.externalId ?? payment.providerPaymentId,
paymentAmountCents: payment.amountCents,
paymentAmountRefundedCents: payment.amountRefundedCents,
paymentCurrency: payment.currency,
...(productKind
? {
paymentExpiresAt,
paymentPaidAt,
reservationExpiresAt: reservationFromProviderExpiry(paymentExpiresAt),
}
: {}),
invoiceExternalId,
lagoSubscriptionId: metadataString(payment.metadata.lagoSubscriptionId),
lagoProviderSubscriptionId: metadataString(payment.metadata.lagoProviderSubscriptionId),
status: payment.status,
productKind,
productAcquisitionId: metadataString(payment.metadata.productAcquisitionId),
productScopeKey: metadataString(payment.metadata.productScopeKey),
subscriptionProductId: metadataString(payment.metadata.subscriptionProductId),
subscriptionPriceId: metadataString(payment.metadata.subscriptionPriceId),
storageAddOnCodes: payment.metadata.storageAddOnCodes,
recurringInvoiceCollection: payment.metadata.billingFlow === "recurring_invoice",
selfServiceCheckout: payment.metadata.billingFlow === "self_service_new" || payment.metadata.billingFlow === "self_service_change",
preserveSubscriptionStatus:
(isSelfServicePayment(payment) && payment.status === "paid") ||
(payment.metadata.billingFlow === "self_service_change" &&
(payment.status === "failed" || payment.status === "expired" || payment.status === "canceled")),
receivedAt,
};
}
@@ -171,8 +621,14 @@ function buildMollieWebhookEventKey(payment: PaymentGatewayPayment): string {
}
function toLagoInvoicePaymentStatus(paymentStatus: PaymentGatewayPayment["status"]): BillingGatewayInvoice["paymentStatus"] | null {
if (paymentStatus === "paid" || paymentStatus === "authorized") return "succeeded";
if (paymentStatus === "failed" || paymentStatus === "expired" || paymentStatus === "canceled" || paymentStatus === "refunded" || paymentStatus === "charged_back") {
if (paymentStatus === "paid") return "succeeded";
if (
paymentStatus === "failed" ||
paymentStatus === "expired" ||
paymentStatus === "canceled" ||
paymentStatus === "refunded" ||
paymentStatus === "charged_back"
) {
return "failed";
}
return null;
@@ -184,33 +640,133 @@ function buildLagoSyncInputFromPayment(
invoiceExternalId: string,
receivedAt: Date
): ApplyLagoSubscriptionSyncInput | null {
if (payment.status !== "paid" && payment.status !== "authorized") return null;
const planCode = payment.metadata.planCode?.trim();
const lagoSubscriptionId = payment.metadata.lagoSubscriptionId?.trim();
if (payment.status !== "paid") return null;
const planCode = metadataString(payment.metadata.planCode);
const lagoSubscriptionId = metadataString(payment.metadata.lagoSubscriptionId);
if (!planCode || !lagoSubscriptionId) return null;
const trialEndsAt = futureMetadataDate(payment.metadata.trialEndsAt, receivedAt);
return {
tenantId,
eventKey: `mollie:lago:${payment.providerPaymentId}:${payment.status}`.replace(/[^A-Za-z0-9._:-]/gu, "_").slice(0, 256),
lagoCustomerId: payment.metadata.lagoCustomerId,
lagoCustomerId: metadataString(payment.metadata.lagoCustomerId),
lagoSubscriptionId,
billingProviderSubscriptionId: metadataString(payment.metadata.lagoProviderSubscriptionId),
fromCheckoutSessionId: metadataString(payment.metadata.paymentExternalId),
planCode,
productKind: productAcquisitionKind(payment),
subscriptionPriceId: metadataString(payment.metadata.subscriptionPriceId),
seatQuantity: payment.metadata.seatQuantity,
officeSeatQuantity: payment.metadata.officeSeatQuantity,
fieldSeatQuantity: payment.metadata.fieldSeatQuantity,
billingCadence: metadataString(payment.metadata.billingCadence),
commitmentEndsAt: metadataDate(payment.metadata.commitmentEndsAt),
storageAddOnCodes: payment.metadata.storageAddOnCodes,
invoiceExternalId,
status: "active",
status: trialEndsAt ? "trial" : "active",
...(trialEndsAt ? { trialStartsAt: receivedAt, trialEndsAt } : {}),
receivedAt,
};
}
function productAcquisitionKind(payment: PaymentGatewayPayment): "recurring_add_on" | "one_time_setup" | undefined {
if (payment.metadata.billingFlow !== "product_acquisition") return undefined;
return payment.metadata.productKind === "recurring_add_on" || payment.metadata.productKind === "one_time_setup" ? payment.metadata.productKind : undefined;
}
function hasCompleteProductAcquisitionMetadata(payment: PaymentGatewayPayment): boolean {
const kind = productAcquisitionKind(payment);
return Boolean(
kind &&
metadataString(payment.metadata.productAcquisitionId) &&
metadataString(payment.metadata.productScopeKey) &&
metadataString(payment.metadata.subscriptionProductId) &&
metadataString(payment.metadata.subscriptionPriceId) &&
(kind !== "recurring_add_on" || metadataString(payment.metadata.lagoSubscriptionId))
);
}
function requiresRecurringProductTermination(payment: PaymentGatewayPayment): boolean {
if (productAcquisitionKind(payment) !== "recurring_add_on") return false;
return (
payment.status === "failed" ||
payment.status === "expired" ||
payment.status === "canceled" ||
payment.status === "refunded" ||
payment.status === "charged_back"
);
}
function isSelfServicePayment(payment: PaymentGatewayPayment): boolean {
return payment.metadata.billingFlow === "self_service_new" || payment.metadata.billingFlow === "self_service_change";
}
function requiresImmediateSelfServiceActivation(payment: PaymentGatewayPayment, receivedAt: Date): boolean {
if (!isSelfServicePayment(payment) || payment.status !== "paid" || !metadataString(payment.metadata.lagoSubscriptionId)) return false;
if (futureMetadataDate(payment.metadata.trialEndsAt, receivedAt)) return false;
return !hasDeferredPlanChange(payment, receivedAt);
}
function requiresPendingSelfServiceTermination(payment: PaymentGatewayPayment): boolean {
if (!isSelfServicePayment(payment) || !metadataString(payment.metadata.lagoSubscriptionId)) return false;
return payment.status === "failed" || payment.status === "expired" || payment.status === "canceled";
}
function metadataString(value: unknown): string | null {
return typeof value === "string" ? value.trim() || null : null;
}
const ISO_TIMESTAMP_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|[+-](\d{2}):(\d{2}))$/u;
function isValidIsoTimestamp(value: string): boolean {
const match = ISO_TIMESTAMP_PATTERN.exec(value);
if (!match) return false;
const [, yearPart, monthPart, dayPart, hourPart, minutePart, secondPart, offsetHourPart, offsetMinutePart] = match;
const year = Number(yearPart);
const month = Number(monthPart);
const day = Number(dayPart);
const hour = Number(hourPart);
const minute = Number(minutePart);
const second = Number(secondPart);
const offsetHour = Number(offsetHourPart ?? 0);
const offsetMinute = Number(offsetMinutePart ?? 0);
const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0;
return day >= 1 && day <= daysInMonth && hour <= 23 && minute <= 59 && second <= 59 && offsetHour <= 23 && offsetMinute <= 59;
}
function metadataDate(value: unknown): Date | null {
const normalized = metadataString(value);
if (!normalized || !isValidIsoTimestamp(normalized)) return null;
const timestamp = Date.parse(normalized);
return Number.isFinite(timestamp) ? new Date(timestamp) : null;
}
function futureMetadataDate(value: unknown, receivedAt: Date): Date | null {
const date = metadataDate(value);
return date && date.getTime() > receivedAt.getTime() ? date : null;
}
function hasDeferredPlanChange(payment: PaymentGatewayPayment, receivedAt: Date): boolean {
if (payment.metadata.changeEffectiveAt !== "period_end") return false;
return futureMetadataDate(payment.metadata.changeEffectiveAtDate, receivedAt) !== null;
}
async function syncLagoSubscriptionFromPaidMolliePayment(
payment: PaymentGatewayPayment,
tenantId: string,
invoiceExternalId: string,
receivedAt: Date,
dependencies: MollieBillingWebhookDependencies
dependencies: MollieBillingWebhookDependencies,
paidSelfServiceSubscription?: BillingGatewaySubscription | null
): Promise<BillingSyncResult | null> {
const input = buildLagoSyncInputFromPayment(payment, tenantId, invoiceExternalId, receivedAt);
if (!input) return null;
return dependencies.applyLagoSubscriptionSync(input);
const deferredUntil = hasDeferredPlanChange(payment, receivedAt) ? futureMetadataDate(payment.metadata.changeEffectiveAtDate, receivedAt) : null;
return dependencies.applyLagoSubscriptionSync({
...input,
...(paidSelfServiceSubscription ? { billingProviderSubscriptionId: paidSelfServiceSubscription.providerSubscriptionId } : {}),
...(deferredUntil ? { deferredUntil } : {}),
});
}
function toMollieWebhookResponse(payment: PaymentGatewayPayment, result: BillingSyncResult, subscriptionResult: BillingSyncResult | null) {
@@ -2,12 +2,12 @@ import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
// Mock the two-tier cache + shared-store seams so the test exercises the real
// publisher singleton/env-gating logic without a Redis connection.
const { createTwoTierCacheMock, invalidateMock, getSharedStoreMock } = vi.hoisted(() => {
const { createTwoTierCacheMock, invalidateMock, getCrossAppCacheStoreMock } = vi.hoisted(() => {
const invalidateMock = vi.fn().mockResolvedValue(undefined);
return {
invalidateMock,
createTwoTierCacheMock: vi.fn(() => ({ invalidate: invalidateMock })),
getSharedStoreMock: vi.fn(() => ({ namespace: "subscription" })),
getCrossAppCacheStoreMock: vi.fn(() => ({ namespace: "cross-app-cache" })),
};
});
@@ -16,7 +16,7 @@ vi.mock("@hivegrid/shared-store", () => ({
}));
vi.mock("../shared-store.js", () => ({
getSharedStore: getSharedStoreMock,
getCrossAppCacheStore: getCrossAppCacheStoreMock,
}));
const { publishSubscriptionInvalidation, __resetSubscriptionCachePublisherForTests } = await import(
@@ -28,7 +28,7 @@ const ORIGINAL_FLAG = process.env.CACHE_INVALIDATION_ENABLED;
beforeEach(() => {
createTwoTierCacheMock.mockClear();
invalidateMock.mockClear();
getSharedStoreMock.mockClear();
getCrossAppCacheStoreMock.mockClear();
__resetSubscriptionCachePublisherForTests();
delete process.env.CACHE_INVALIDATION_ENABLED;
});
@@ -65,7 +65,10 @@ describe("publishSubscriptionInvalidation", () => {
expect(createTwoTierCacheMock).toHaveBeenCalledTimes(1);
expect(createTwoTierCacheMock).toHaveBeenCalledWith(
expect.objectContaining({ namespace: "subscription" }),
expect.objectContaining({
namespace: "subscription",
store: expect.objectContaining({ namespace: "cross-app-cache" }),
}),
);
expect(invalidateMock).toHaveBeenCalledWith("tenant_1");
});
@@ -1,5 +1,5 @@
import { createTwoTierCache, type TwoTierCache } from "@hivegrid/shared-store";
import { getSharedStore } from "../shared-store.js";
import { getCrossAppCacheStore } from "../shared-store.js";
import { apiLogger } from "../logger.js";
/**
@@ -13,7 +13,8 @@ import { apiLogger } from "../logger.js";
* subscribers consume.
*
* Sym-coupled with apps/web/app/utils/services/.server/subscriptionCache.server.ts.
* Namespace and channel MUST match: `subscription` / `invalidate`.
* The SharedStore namespace is explicitly `cross-app-cache`; the cache
* namespace and channel MUST match: `subscription` / `invalidate`.
*/
const TTL_SECONDS = 60; // unused on this side; required by createTwoTierCache
@@ -28,7 +29,7 @@ function pubsubEnabled(): boolean {
function getPublisher(): TwoTierCache<unknown> {
if (publisherSingleton) return publisherSingleton;
publisherSingleton = createTwoTierCache<unknown>({
store: getSharedStore(),
store: getCrossAppCacheStore(),
namespace: "subscription",
ttlSeconds: TTL_SECONDS,
pubsubEnabled: pubsubEnabled(),
@@ -0,0 +1,77 @@
import { MemoryAdapter, createSharedStore } from "@hivegrid/shared-store";
import { afterEach, describe, expect, it, vi } from "vitest";
import { CHAT_CONNECTION_LEASE_TTL_MS, CHAT_MAX_CONNECTIONS_PER_SESSION, CHAT_MAX_CONNECTIONS_PER_USER, createChatConnectionAdmission } from "./admission.js";
const adapters: MemoryAdapter[] = [];
function setup() {
const adapter = new MemoryAdapter();
adapters.push(adapter);
const store = createSharedStore({ namespace: "api-chat-admission-test", adapter });
return createChatConnectionAdmission(store);
}
function identity(connectionId: string, sessionId = "session_1", userId = "user_1") {
return { tenantId: "tenant_1", userId, sessionId, connectionId };
}
afterEach(async () => {
vi.useRealTimers();
await Promise.allSettled(adapters.splice(0).map((adapter) => adapter.close()));
});
describe("chat connection admission", () => {
it("enforces the distributed per-session cap atomically", async () => {
const admission = setup();
const results = await Promise.all(
Array.from({ length: CHAT_MAX_CONNECTIONS_PER_SESSION + 1 }, (_, index) => admission.acquire(identity(`connection_${index}`)))
);
expect(results.filter(Boolean)).toHaveLength(CHAT_MAX_CONNECTIONS_PER_SESSION);
expect(results.filter((allowed) => !allowed)).toHaveLength(1);
});
it("enforces the per-user cap across sessions and isolates tenants", async () => {
const admission = setup();
for (let index = 0; index < CHAT_MAX_CONNECTIONS_PER_USER; index += 1) {
await expect(admission.acquire(identity(`connection_${index}`, `session_${Math.floor(index / CHAT_MAX_CONNECTIONS_PER_SESSION)}`))).resolves.toBe(true);
}
await expect(admission.acquire(identity("connection_denied", "session_fresh"))).resolves.toBe(false);
await expect(admission.acquire({ tenantId: "tenant_2", userId: "user_1", sessionId: "session_fresh", connectionId: "connection_allowed" })).resolves.toBe(
true
);
});
it("refreshes idempotently, releases immediately, and reclaims expired leases", async () => {
vi.useFakeTimers();
vi.setSystemTime(new Date("2026-07-15T12:00:00.000Z"));
const admission = setup();
const first = identity("connection_1");
await expect(admission.acquire(first)).resolves.toBe(true);
await expect(admission.refresh(first)).resolves.toBe(true);
await admission.release(first);
await expect(admission.acquire(identity("connection_2"))).resolves.toBe(true);
for (let index = 3; index <= CHAT_MAX_CONNECTIONS_PER_SESSION + 1; index += 1) {
await expect(admission.acquire(identity(`connection_${index}`))).resolves.toBe(true);
}
await expect(admission.acquire(identity("connection_denied"))).resolves.toBe(false);
vi.advanceTimersByTime(CHAT_CONNECTION_LEASE_TTL_MS + 1);
await expect(admission.acquire(identity("connection_reclaimed"))).resolves.toBe(true);
});
it("fails closed on a corrupted registry", async () => {
const admission = setup();
const adapter = adapters.at(-1);
if (!adapter) throw new Error("Expected a test adapter");
await admission.acquire(identity("connection_1"));
const keys: string[] = [];
for await (const key of adapter.scan("*")) keys.push(key);
await adapter.set(keys[0] ?? "missing", "not-json");
await expect(admission.acquire(identity("connection_2"))).rejects.toThrow(/registry/i);
});
});
@@ -0,0 +1,256 @@
import { MemoryAdapter, createSharedStore, type SharedStore } from "@hivegrid/shared-store";
export const CHAT_CONNECTION_LEASE_TTL_MS = 45_000;
export const CHAT_MAX_CONNECTIONS_PER_SESSION = 8;
export const CHAT_MAX_CONNECTIONS_PER_USER = 16;
const LEASE_STORAGE_TTL_MULTIPLIER = 2;
const MAX_ID_LENGTH = 191;
const MAX_CONNECTION_ID_LENGTH = 128;
const CONNECTION_ADMISSION_SCRIPT = `
local time = redis.call("TIME")
local now = (tonumber(time[1]) * 1000) + math.floor(tonumber(time[2]) / 1000)
local ttl = tonumber(ARGV[1])
local connection_id = ARGV[2]
local action = ARGV[3]
local max_session = tonumber(ARGV[4])
local max_user = tonumber(ARGV[5])
if not ttl or ttl <= 0 or connection_id == "" or
(action ~= "acquire" and action ~= "release") or
not max_session or max_session <= 0 or not max_user or max_user < max_session then
return redis.error_reply("invalid chat connection admission arguments")
end
local function read_registry(key)
local registry = {}
local raw = redis.call("GET", key)
if raw then
local ok, decoded = pcall(cjson.decode, raw)
if not ok or type(decoded) ~= "table" then
return nil
end
registry = decoded
end
for id, expires_at in pairs(registry) do
if type(id) ~= "string" or type(expires_at) ~= "number" then
return nil
end
if expires_at <= now then
registry[id] = nil
end
end
return registry
end
local function count_registry(registry)
local count = 0
for _ in pairs(registry) do
count = count + 1
end
return count
end
local function persist_registry(key, registry)
if count_registry(registry) == 0 then
redis.call("DEL", key)
else
redis.call("SET", key, cjson.encode(registry), "PX", ttl * ${LEASE_STORAGE_TTL_MULTIPLIER})
end
end
local session_registry = read_registry(KEYS[1])
local user_registry = read_registry(KEYS[2])
if not session_registry or not user_registry then
return redis.error_reply("invalid chat connection admission registry")
end
if action == "release" then
session_registry[connection_id] = nil
user_registry[connection_id] = nil
persist_registry(KEYS[1], session_registry)
persist_registry(KEYS[2], user_registry)
return "released"
end
local already_admitted = session_registry[connection_id] ~= nil and user_registry[connection_id] ~= nil
if not already_admitted and
(count_registry(session_registry) >= max_session or count_registry(user_registry) >= max_user) then
persist_registry(KEYS[1], session_registry)
persist_registry(KEYS[2], user_registry)
return "denied"
end
session_registry[connection_id] = now + ttl
user_registry[connection_id] = now + ttl
persist_registry(KEYS[1], session_registry)
persist_registry(KEYS[2], user_registry)
return "allowed"
`;
export type ChatConnectionIdentity = {
tenantId: string;
userId: string;
sessionId: string;
connectionId: string;
};
export type ChatConnectionAdmission = {
acquire(identity: ChatConnectionIdentity): Promise<boolean>;
refresh(identity: ChatConnectionIdentity): Promise<boolean>;
release(identity: ChatConnectionIdentity): Promise<void>;
};
export function createChatConnectionAdmission(baseStore: SharedStore): ChatConnectionAdmission {
const store = createSharedStore({ namespace: "chat-realtime-admission", adapter: baseStore.adapter });
const execute = async (input: ChatConnectionIdentity, action: "acquire" | "release"): Promise<"allowed" | "denied" | "released"> => {
const identity = normalizeIdentity(input);
const result = await store.eval(
CONNECTION_ADMISSION_SCRIPT,
[sessionLeaseKey(identity), userLeaseKey(identity)],
[
String(CHAT_CONNECTION_LEASE_TTL_MS),
identity.connectionId,
action,
String(CHAT_MAX_CONNECTIONS_PER_SESSION),
String(CHAT_MAX_CONNECTIONS_PER_USER),
String(Date.now()),
]
);
if (result === "allowed" || result === "denied" || result === "released") return result;
throw new Error("chat connection admission returned an invalid result");
};
return {
async acquire(identity) {
return (await execute(identity, "acquire")) === "allowed";
},
async refresh(identity) {
return (await execute(identity, "acquire")) === "allowed";
},
async release(identity) {
await execute(identity, "release");
},
};
}
function normalizeIdentity(input: ChatConnectionIdentity): ChatConnectionIdentity {
return {
tenantId: normalizeIdentifier(input.tenantId, "tenantId", MAX_ID_LENGTH),
userId: normalizeIdentifier(input.userId, "userId", MAX_ID_LENGTH),
sessionId: normalizeIdentifier(input.sessionId, "sessionId", MAX_ID_LENGTH),
connectionId: normalizeIdentifier(input.connectionId, "connectionId", MAX_CONNECTION_ID_LENGTH),
};
}
function normalizeIdentifier(value: string, label: string, maxLength: number): string {
if (typeof value !== "string" || value.length === 0 || value.length > maxLength || value !== value.trim() || value.includes("\u0000")) {
throw new Error(`chat connection ${label} is invalid`);
}
return value;
}
function sessionLeaseKey(identity: ChatConnectionIdentity): string {
return `session:${encodeKeyPart(identity.tenantId)}:${encodeKeyPart(identity.userId)}:${encodeKeyPart(identity.sessionId)}`;
}
function userLeaseKey(identity: ChatConnectionIdentity): string {
return `user:${encodeKeyPart(identity.tenantId)}:${encodeKeyPart(identity.userId)}`;
}
function encodeKeyPart(value: string): string {
return Buffer.from(value, "utf8").toString("base64url");
}
type LeaseRegistry = Record<string, number>;
async function runAdmissionInMemory(adapter: MemoryAdapter, keys: string[], args: string[]): Promise<"allowed" | "denied" | "released"> {
if (keys.length !== 2 || args.length !== 6) throw new Error("invalid chat connection admission arguments");
const [ttlRaw, connectionId, action, maxSessionRaw, maxUserRaw, nowRaw] = args;
const ttl = requirePositiveInteger(ttlRaw, "ttl");
const maxSession = requirePositiveInteger(maxSessionRaw, "session limit");
const maxUser = requirePositiveInteger(maxUserRaw, "user limit");
const now = Number(nowRaw);
if (!connectionId || (action !== "acquire" && action !== "release") || maxUser < maxSession || !Number.isFinite(now)) {
throw new Error("invalid chat connection admission arguments");
}
const sessionRegistry = pruneRegistry(parseRegistry(await adapter.get(keys[0])), now);
const userRegistry = pruneRegistry(parseRegistry(await adapter.get(keys[1])), now);
if (action === "release") {
delete sessionRegistry[connectionId];
delete userRegistry[connectionId];
await persistRegistries(adapter, keys, sessionRegistry, userRegistry, ttl);
return "released";
}
const alreadyAdmitted = sessionRegistry[connectionId] !== undefined && userRegistry[connectionId] !== undefined;
if (!alreadyAdmitted && (Object.keys(sessionRegistry).length >= maxSession || Object.keys(userRegistry).length >= maxUser)) {
await persistRegistries(adapter, keys, sessionRegistry, userRegistry, ttl);
return "denied";
}
sessionRegistry[connectionId] = now + ttl;
userRegistry[connectionId] = now + ttl;
await persistRegistries(adapter, keys, sessionRegistry, userRegistry, ttl);
return "allowed";
}
function parseRegistry(raw: string | null): LeaseRegistry {
if (raw === null) return Object.create(null) as LeaseRegistry;
let parsed: unknown;
try {
parsed = JSON.parse(raw) as unknown;
} catch {
throw new Error("invalid chat connection admission registry");
}
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
throw new Error("invalid chat connection admission registry");
}
const registry = Object.create(null) as LeaseRegistry;
for (const [connectionId, expiresAt] of Object.entries(parsed)) {
if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) {
throw new Error("invalid chat connection admission registry");
}
registry[connectionId] = expiresAt;
}
return registry;
}
function pruneRegistry(registry: LeaseRegistry, now: number): LeaseRegistry {
for (const [connectionId, expiresAt] of Object.entries(registry)) {
if (expiresAt <= now) delete registry[connectionId];
}
return registry;
}
async function persistRegistries(
adapter: MemoryAdapter,
keys: string[],
sessionRegistry: LeaseRegistry,
userRegistry: LeaseRegistry,
ttlMs: number
): Promise<void> {
await Promise.all([persistRegistry(adapter, keys[0], sessionRegistry, ttlMs), persistRegistry(adapter, keys[1], userRegistry, ttlMs)]);
}
async function persistRegistry(adapter: MemoryAdapter, key: string | undefined, registry: LeaseRegistry, ttlMs: number): Promise<void> {
if (!key) throw new Error("invalid chat connection admission key");
if (Object.keys(registry).length === 0) {
await adapter.del(key);
return;
}
const stored = await adapter.set(key, JSON.stringify(registry), {
ttlSeconds: Math.ceil((ttlMs * LEASE_STORAGE_TTL_MULTIPLIER) / 1_000),
});
if (!stored) throw new Error("chat connection admission registry could not be stored");
}
function requirePositiveInteger(value: string | undefined, label: string): number {
const parsed = Number(value);
if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new Error(`invalid chat connection ${label}`);
return parsed;
}
MemoryAdapter.registerScript(CONNECTION_ADMISSION_SCRIPT, runAdmissionInMemory);
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,487 @@
import { CHAT_EVENT_NAMES, type ChatServerEvent } from "@hivegrid/realtime";
import { MemoryAdapter, createSharedStore, type SharedStore } from "@hivegrid/shared-store";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
CHAT_PRESENCE_LEASE_TTL_MS,
CHAT_PRESENCE_SNAPSHOT_MAX_USERS,
CHAT_PRESENCE_UNCHANGED_PUBLISH_INTERVAL_MS,
CHAT_REALTIME_NAMESPACE,
CHAT_TYPING_LEASE_TTL_MS,
createChatRoomHub,
type ChatRoomHub,
type ChatRoomHubDiagnostic,
} from "./room-hub.js";
const occurredAt = "2026-07-15T12:00:00.000Z";
const message = {
id: "message_1",
clientMessageId: "client_message_1",
authorUserId: "user_1",
body: "Hello team",
bodyFormat: "markdown",
parentMessageId: null,
mentions: [],
attachmentIds: [],
linkPreviews: [],
createdAt: occurredAt,
updatedAt: occurredAt,
editedAt: null,
deletedAt: null,
} as const;
function persistentEvent(overrides: Record<string, unknown> = {}): Record<string, unknown> {
return {
event: CHAT_EVENT_NAMES.messageCreated,
cursor: "stream_1:1",
requestId: "request_1",
tenantId: "tenant_1",
chatId: "chat_1",
occurredAt,
data: { message },
...overrides,
};
}
function ephemeralEvent(overrides: Record<string, unknown> = {}): Record<string, unknown> {
return {
event: CHAT_EVENT_NAMES.typingStarted,
cursor: null,
requestId: "request_typing",
tenantId: "tenant_1",
chatId: "chat_1",
occurredAt,
data: { userId: "user_2" },
...overrides,
};
}
function leaseActor(overrides: Partial<{ tenantId: string; chatId: string; userId: string; connectionId: string; occurredAt: Date }> = {}) {
return {
tenantId: "tenant_1",
chatId: "chat_1",
userId: "user_1",
connectionId: "connection_1",
occurredAt: new Date(occurredAt),
...overrides,
};
}
type Harness = {
adapter: MemoryAdapter;
baseStore: SharedStore;
hub: ChatRoomHub;
diagnostics: ChatRoomHubDiagnostic[];
};
const harnesses: Harness[] = [];
function createHarness(adapter = new MemoryAdapter()): Harness {
const baseStore = createSharedStore({ namespace: "api-test", adapter });
const diagnostics: ChatRoomHubDiagnostic[] = [];
const hub = createChatRoomHub(baseStore, { onDiagnostic: (diagnostic) => diagnostics.push(diagnostic) });
const harness = { adapter, baseStore, hub, diagnostics };
harnesses.push(harness);
return harness;
}
async function flushFanout(): Promise<void> {
await new Promise((resolve) => setTimeout(resolve, 0));
await new Promise((resolve) => setTimeout(resolve, 0));
}
afterEach(async () => {
const current = harnesses.splice(0);
await Promise.allSettled(current.map(({ hub }) => hub.close()));
const adapters = new Set(current.map(({ adapter }) => adapter));
await Promise.allSettled([...adapters].map((adapter) => adapter.close()));
});
describe("chat Redis room hub", () => {
it("publishes exact validated events on the namespaced persistent and ephemeral channels", async () => {
const { adapter, hub } = createHarness();
const persistentPayloads: string[] = [];
const ephemeralPayloads: string[] = [];
const stopPersistent = await adapter.subscribe(`shared-store:${CHAT_REALTIME_NAMESPACE}:ch:persistent:tenant_1:chat_1`, (payload) => {
persistentPayloads.push(payload);
});
const stopEphemeral = await adapter.subscribe(`shared-store:${CHAT_REALTIME_NAMESPACE}:ch:ephemeral:tenant_1:chat_1`, (payload) => {
ephemeralPayloads.push(payload);
});
expect(await hub.publish(persistentEvent())).toBe(1);
expect(await hub.publish(ephemeralEvent())).toBe(1);
await flushFanout();
expect(JSON.parse(persistentPayloads[0]!)).toEqual(persistentEvent());
expect(JSON.parse(ephemeralPayloads[0]!)).toEqual(ephemeralEvent());
await stopPersistent();
await stopEphemeral();
});
it("activates subscriptions before returning so the gateway can gap-fill without a subscribe race", async () => {
const { adapter, hub } = createHarness();
const received: ChatServerEvent[] = [];
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
received.push(event);
});
await adapter.publish(`shared-store:${CHAT_REALTIME_NAMESPACE}:ch:persistent:tenant_1:chat_1`, JSON.stringify(persistentEvent()));
await flushFanout();
expect(received).toHaveLength(1);
expect(received[0]).toMatchObject({ event: CHAT_EVENT_NAMES.messageCreated, chatId: "chat_1" });
});
it("fans one Redis subscription out to independent local subscribers", async () => {
const { hub, diagnostics } = createHarness();
const first = vi.fn(() => {
throw new Error("subscriber contained private-token");
});
const second = vi.fn();
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, first);
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, second);
expect(await hub.publish(persistentEvent())).toBe(1);
await flushFanout();
expect(first).toHaveBeenCalledOnce();
expect(second).toHaveBeenCalledOnce();
expect(diagnostics).toContainEqual({ code: "subscriber_failed", transport: "persistent", tenantId: "tenant_1", chatId: "chat_1" });
expect(JSON.stringify(diagnostics)).not.toContain("private-token");
});
it("isolates tenant, channel, and transport fanout", async () => {
const { hub } = createHarness();
const received = vi.fn();
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, received);
expect(await hub.publish(persistentEvent({ chatId: "chat_2", cursor: "stream_2:1" }))).toBe(0);
expect(await hub.publish(persistentEvent({ tenantId: "tenant_2", cursor: "stream_2:2" }))).toBe(0);
expect(await hub.publish(ephemeralEvent())).toBe(1);
await flushFanout();
expect(received).toHaveBeenCalledOnce();
expect(received).toHaveBeenCalledWith(expect.objectContaining({ event: CHAT_EVENT_NAMES.typingStarted, tenantId: "tenant_1", chatId: "chat_1" }));
});
it("drops malformed, wrong-transport, and wrong-scope Redis payloads without logging payloads or secrets", async () => {
const { adapter, hub, diagnostics } = createHarness();
const received = vi.fn();
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, received);
const persistentChannel = `shared-store:${CHAT_REALTIME_NAMESPACE}:ch:persistent:tenant_1:chat_1`;
await adapter.publish(persistentChannel, "{private-token");
await adapter.publish(persistentChannel, JSON.stringify(ephemeralEvent()));
await adapter.publish(persistentChannel, JSON.stringify(persistentEvent({ chatId: "chat_2", authorization: "private-token" })));
await flushFanout();
expect(received).not.toHaveBeenCalled();
expect(diagnostics).toEqual([
{ code: "invalid_payload", transport: "persistent", tenantId: "tenant_1", chatId: "chat_1" },
{ code: "invalid_payload", transport: "persistent", tenantId: "tenant_1", chatId: "chat_1" },
{ code: "invalid_payload", transport: "persistent", tenantId: "tenant_1", chatId: "chat_1" },
]);
expect(JSON.stringify(diagnostics)).not.toContain("private-token");
expect(JSON.stringify(diagnostics)).not.toContain("authorization");
});
it("aggregates presence across connections and gives online precedence over away", async () => {
const { hub } = createHarness();
const received: ChatServerEvent[] = [];
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
received.push(event);
});
expect(await hub.touchPresence({ ...leaseActor(), presence: "away" })).toBe("away");
expect(await hub.touchPresence({ ...leaseActor({ connectionId: "connection_2" }), presence: "online" })).toBe("online");
expect(await hub.releasePresence(leaseActor({ connectionId: "connection_2" }))).toBe("away");
expect(await hub.releasePresence(leaseActor())).toBe("offline");
expect(await hub.releasePresence(leaseActor())).toBe("unchanged");
await flushFanout();
expect(received.map((event) => event.event)).toEqual([
CHAT_EVENT_NAMES.presenceAway,
CHAT_EVENT_NAMES.presenceOnline,
CHAT_EVENT_NAMES.presenceAway,
CHAT_EVENT_NAMES.presenceOffline,
]);
});
it("shares a channel presence snapshot across replicas and removes released or expired users", async () => {
let now = new Date(occurredAt).getTime();
const adapter = new MemoryAdapter({ now: () => now });
const first = createHarness(adapter);
const second = createHarness(adapter);
const scope = { tenantId: "tenant_1", chatId: "chat_1" };
await first.hub.touchPresence({ ...leaseActor({ userId: "user_1", occurredAt: new Date(now) }), presence: "online" });
await second.hub.touchPresence({ ...leaseActor({ userId: "user_2", connectionId: "connection_2", occurredAt: new Date(now) }), presence: "away" });
expect((await second.hub.getPresenceSnapshot(scope, new Date(now))).map((event) => ({ userId: event.data.userId, presence: event.data.presence }))).toEqual(
[
{ userId: "user_1", presence: "online" },
{ userId: "user_2", presence: "away" },
]
);
await first.hub.releasePresence(leaseActor({ userId: "user_1", occurredAt: new Date(now) }));
expect((await second.hub.getPresenceSnapshot(scope, new Date(now))).map((event) => ({ userId: event.data.userId, presence: event.data.presence }))).toEqual(
[{ userId: "user_2", presence: "away" }]
);
now += CHAT_PRESENCE_LEASE_TTL_MS + 1;
expect(await first.hub.getPresenceSnapshot(scope, new Date(now))).toEqual([]);
});
it("bounds the channel presence registry and snapshot without scanning keys", async () => {
const { hub } = createHarness();
for (let index = 0; index <= CHAT_PRESENCE_SNAPSHOT_MAX_USERS; index += 1) {
const suffix = String(index).padStart(4, "0");
await hub.touchPresence({
...leaseActor({ userId: `user_${suffix}`, connectionId: `connection_${suffix}` }),
presence: "online",
});
}
const snapshot = await hub.getPresenceSnapshot({ tenantId: "tenant_1", chatId: "chat_1" }, new Date(occurredAt));
expect(snapshot).toHaveLength(CHAT_PRESENCE_SNAPSHOT_MAX_USERS);
expect(snapshot.some((event) => event.data.userId === "user_0000")).toBe(false);
expect(snapshot.some((event) => event.data.userId === `user_${String(CHAT_PRESENCE_SNAPSHOT_MAX_USERS).padStart(4, "0")}`)).toBe(true);
}, 10_000);
it("renews the 45-second presence lease without republishing an unchanged state more than every 30 seconds", async () => {
let now = new Date(occurredAt).getTime();
const adapter = new MemoryAdapter({ now: () => now });
const { hub } = createHarness(adapter);
const received: ChatServerEvent[] = [];
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
received.push(event);
});
await hub.touchPresence({ ...leaseActor({ occurredAt: new Date(now) }), presence: "online" });
now += 15_000;
await hub.touchPresence({ ...leaseActor({ occurredAt: new Date(now) }), presence: "online" });
now += CHAT_PRESENCE_UNCHANGED_PUBLISH_INTERVAL_MS - 15_000;
await hub.touchPresence({ ...leaseActor({ occurredAt: new Date(now) }), presence: "online" });
now += 1_000;
await hub.touchPresence({ ...leaseActor({ occurredAt: new Date(now) }), presence: "away" });
now += 15_000;
expect(await hub.touchPresence({ ...leaseActor({ connectionId: "connection_2", occurredAt: new Date(now) }), presence: "online" })).toBe("online");
expect(await hub.releasePresence(leaseActor({ connectionId: "connection_2", occurredAt: new Date(now) }))).toBe("away");
await flushFanout();
expect(received.map((event) => event.event)).toEqual([
CHAT_EVENT_NAMES.presenceOnline,
CHAT_EVENT_NAMES.presenceOnline,
CHAT_EVENT_NAMES.presenceAway,
CHAT_EVENT_NAMES.presenceOnline,
CHAT_EVENT_NAMES.presenceAway,
]);
});
it("keeps typing active until the final connection lease is released", async () => {
const { hub } = createHarness();
const received: ChatServerEvent[] = [];
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
received.push(event);
});
expect(await hub.touchTyping(leaseActor())).toBe("started");
expect(await hub.touchTyping(leaseActor({ connectionId: "connection_2" }))).toBe("started");
expect(await hub.releaseTyping(leaseActor())).toBe("started");
expect(await hub.releaseTyping(leaseActor({ connectionId: "connection_2" }))).toBe("stopped");
expect(await hub.releaseTyping(leaseActor({ connectionId: "connection_2" }))).toBe("unchanged");
await flushFanout();
expect(received.map((event) => event.event)).toEqual([
CHAT_EVENT_NAMES.typingStarted,
CHAT_EVENT_NAMES.typingStarted,
CHAT_EVENT_NAMES.typingStarted,
CHAT_EVENT_NAMES.typingStopped,
]);
});
it("prunes expired presence and typing connections before computing aggregates", async () => {
let now = new Date(occurredAt).getTime();
const adapter = new MemoryAdapter({ now: () => now });
const { hub } = createHarness(adapter);
const received: ChatServerEvent[] = [];
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
received.push(event);
});
await hub.touchPresence({ ...leaseActor({ occurredAt: new Date(now) }), presence: "online" });
now += CHAT_PRESENCE_LEASE_TTL_MS + 1;
expect(await hub.touchPresence({ ...leaseActor({ connectionId: "connection_2", occurredAt: new Date(now) }), presence: "away" })).toBe("away");
expect(await hub.releasePresence(leaseActor({ connectionId: "connection_2", occurredAt: new Date(now) }))).toBe("offline");
await hub.touchTyping(leaseActor({ occurredAt: new Date(now) }));
now += CHAT_TYPING_LEASE_TTL_MS + 1;
expect(await hub.touchTyping(leaseActor({ connectionId: "connection_2", occurredAt: new Date(now) }))).toBe("started");
expect(await hub.releaseTyping(leaseActor({ connectionId: "connection_2", occurredAt: new Date(now) }))).toBe("stopped");
await flushFanout();
expect(received.map((event) => event.event)).toEqual([
CHAT_EVENT_NAMES.presenceOnline,
CHAT_EVENT_NAMES.presenceAway,
CHAT_EVENT_NAMES.presenceOffline,
CHAT_EVENT_NAMES.typingStarted,
CHAT_EVENT_NAMES.typingStarted,
CHAT_EVENT_NAMES.typingStopped,
]);
});
it("publishes terminal states when a delayed release prunes the final expired lease", async () => {
let now = new Date(occurredAt).getTime();
const adapter = new MemoryAdapter({ now: () => now });
const { hub } = createHarness(adapter);
const received: ChatServerEvent[] = [];
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
received.push(event);
});
await hub.touchPresence({ ...leaseActor({ occurredAt: new Date(now) }), presence: "online" });
await hub.touchTyping(leaseActor({ occurredAt: new Date(now) }));
const startedAt = now;
now += CHAT_TYPING_LEASE_TTL_MS + 1;
expect(await hub.releaseTyping(leaseActor({ occurredAt: new Date(now) }))).toBe("stopped");
now = startedAt + CHAT_PRESENCE_LEASE_TTL_MS + 1;
expect(await hub.releasePresence(leaseActor({ occurredAt: new Date(now) }))).toBe("offline");
await flushFanout();
expect(received.slice(-2).map((event) => event.event)).toEqual([CHAT_EVENT_NAMES.typingStopped, CHAT_EVENT_NAMES.presenceOffline]);
});
it("isolates lease registries by tenant, channel, and user", async () => {
const { hub } = createHarness();
const tenantOneChatOne: ChatServerEvent[] = [];
const tenantOneChatTwo: ChatServerEvent[] = [];
const tenantTwoChatOne: ChatServerEvent[] = [];
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
tenantOneChatOne.push(event);
});
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_2" }, (event) => {
tenantOneChatTwo.push(event);
});
await hub.subscribe({ tenantId: "tenant_2", chatId: "chat_1" }, (event) => {
tenantTwoChatOne.push(event);
});
await hub.touchPresence({ ...leaseActor(), presence: "online" });
await hub.touchPresence({ ...leaseActor({ userId: "user_2" }), presence: "online" });
await hub.touchPresence({ ...leaseActor({ chatId: "chat_2" }), presence: "online" });
await hub.touchPresence({ ...leaseActor({ tenantId: "tenant_2" }), presence: "online" });
expect(await hub.releasePresence(leaseActor())).toBe("offline");
expect(await hub.releasePresence(leaseActor({ userId: "user_2" }))).toBe("offline");
expect(await hub.releasePresence(leaseActor({ chatId: "chat_2" }))).toBe("offline");
expect(await hub.releasePresence(leaseActor({ tenantId: "tenant_2" }))).toBe("offline");
await flushFanout();
expect(tenantOneChatOne).toHaveLength(4);
expect(tenantOneChatOne.every((event) => event.tenantId === "tenant_1" && event.chatId === "chat_1")).toBe(true);
expect(tenantOneChatTwo).toHaveLength(2);
expect(tenantOneChatTwo.every((event) => event.tenantId === "tenant_1" && event.chatId === "chat_2")).toBe(true);
expect(tenantTwoChatOne).toHaveLength(2);
expect(tenantTwoChatOne.every((event) => event.tenantId === "tenant_2" && event.chatId === "chat_1")).toBe(true);
});
it("serializes concurrent multi-replica lease releases to a stable final state", async () => {
const adapter = new MemoryAdapter();
const first = createHarness(adapter);
const second = createHarness(adapter);
const received: ChatServerEvent[] = [];
await first.hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
received.push(event);
});
await first.hub.touchPresence({ ...leaseActor(), presence: "online" });
await second.hub.touchPresence({ ...leaseActor({ connectionId: "connection_2" }), presence: "online" });
const results = await Promise.all([first.hub.releasePresence(leaseActor()), second.hub.releasePresence(leaseActor({ connectionId: "connection_2" }))]);
await flushFanout();
expect(new Set(results)).toEqual(new Set(["online", "offline"]));
expect(received.at(-1)?.event).toBe(CHAT_EVENT_NAMES.presenceOffline);
});
it("fails closed on invalid actors and corrupted lease state", async () => {
const { adapter, hub } = createHarness();
const received: ChatServerEvent[] = [];
await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, (event) => {
received.push(event);
});
await hub.touchPresence({ ...leaseActor(), presence: "online" });
await flushFanout();
const leaseKeys: string[] = [];
for await (const key of adapter.scan(`shared-store:${CHAT_REALTIME_NAMESPACE}:lease:presence:*`)) leaseKeys.push(key);
expect(leaseKeys).toHaveLength(1);
await adapter.set(leaseKeys[0]!, "{private-token");
await expect(hub.touchPresence({ ...leaseActor({ connectionId: "connection_2" }), presence: "online" })).rejects.toThrow(
/invalid chat presence lease registry/
);
await expect(hub.touchPresence({ ...leaseActor({ userId: " user_1" }), presence: "online" })).rejects.toThrow(/userId is invalid/);
await expect(hub.touchTyping(leaseActor({ occurredAt: new Date(Number.NaN) }))).rejects.toThrow(/valid Date/);
await flushFanout();
expect(received).toHaveLength(1);
expect(JSON.stringify(received)).not.toContain("private-token");
});
it("validates the presence publish state before mutating the lease registry", async () => {
const { adapter, hub } = createHarness();
await hub.touchPresence({ ...leaseActor(), presence: "online" });
await flushFanout();
const publishKeys: string[] = [];
for await (const key of adapter.scan(`shared-store:${CHAT_REALTIME_NAMESPACE}:lease:presence-published:*`)) publishKeys.push(key);
expect(publishKeys).toHaveLength(1);
await adapter.set(publishKeys[0]!, "{corrupted");
await expect(hub.touchPresence({ ...leaseActor({ connectionId: "connection_2" }), presence: "online" })).rejects.toThrow(
/invalid chat presence publish state/
);
await adapter.del(publishKeys[0]!);
expect(await hub.releasePresence(leaseActor())).toBe("offline");
});
it("unsubscribes locally and tears down the room only after the final subscriber leaves", async () => {
const { hub } = createHarness();
const first = vi.fn();
const second = vi.fn();
const firstSubscription = await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, first);
const secondSubscription = await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, second);
await firstSubscription.unsubscribe();
await firstSubscription.unsubscribe();
expect(await hub.publish(persistentEvent())).toBe(1);
await flushFanout();
expect(first).not.toHaveBeenCalled();
expect(second).toHaveBeenCalledOnce();
await secondSubscription.unsubscribe();
expect(await hub.publish(persistentEvent())).toBe(0);
});
it("closes idempotently without closing the injected process store", async () => {
const { baseStore, hub } = createHarness();
const subscription = await hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, vi.fn());
await Promise.all([hub.close(), hub.close()]);
await subscription.unsubscribe();
await expect(hub.publish(persistentEvent())).rejects.toThrow(/hub is closed/);
await expect(hub.subscribe({ tenantId: "tenant_1", chatId: "chat_1" }, vi.fn())).rejects.toThrow(/hub is closed/);
await expect(hub.touchPresence({ ...leaseActor(), presence: "online" })).rejects.toThrow(/hub is closed/);
await expect(hub.touchTyping(leaseActor())).rejects.toThrow(/hub is closed/);
await expect(baseStore.set("still-open", "yes")).resolves.toBe(true);
});
it("rejects invalid publish payloads and non-canonical room scope before touching Redis", async () => {
const { hub } = createHarness();
await expect(hub.publish({ ...persistentEvent(), cursor: "0" })).rejects.toThrow(/positive persisted sequence/);
await expect(hub.subscribe({ tenantId: "tenant:1", chatId: "chat_1" }, vi.fn())).rejects.toThrow(/canonical identifiers/);
await expect(hub.subscribe({ tenantId: "tenant_1", chatId: "chat*" }, vi.fn())).rejects.toThrow(/canonical identifiers/);
});
});
@@ -0,0 +1,978 @@
import { randomUUID } from "node:crypto";
import {
CHAT_EVENT_NAMES,
assertChatEventInScope,
isEphemeralChatEvent,
isPersistentChatEvent,
normalizeChatEventScope,
validateChatServerEvent,
type ChatConnectionPresence,
type ChatEventScope,
type ChatPresenceEvent,
type ChatServerEvent,
} from "@hivegrid/realtime";
import { MemoryAdapter, createSharedStore, resolveSharedStoreChannel, type SharedStore } from "@hivegrid/shared-store";
export const CHAT_REALTIME_NAMESPACE = "chat-realtime";
export const CHAT_PRESENCE_LEASE_TTL_MS = 45_000;
export const CHAT_PRESENCE_UNCHANGED_PUBLISH_INTERVAL_MS = 30_000;
export const CHAT_PRESENCE_SNAPSHOT_MAX_USERS = 1_000;
export const CHAT_TYPING_LEASE_TTL_MS = 5_000;
const MAX_REDIS_EVENT_LENGTH = 256 * 1024;
const CHANNEL_SCOPE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
const MAX_USER_ID_LENGTH = 191;
const MAX_CONNECTION_ID_LENGTH = 128;
const LEASE_STORAGE_TTL_MULTIPLIER = 2;
const PRESENCE_LEASE_SCRIPT = `
local time = redis.call("TIME")
local now = (tonumber(time[1]) * 1000) + math.floor(tonumber(time[2]) / 1000)
local ttl = tonumber(ARGV[1])
local publish_interval = tonumber(ARGV[9])
local connection_id = ARGV[2]
local action = ARGV[3]
local channel = ARGV[4]
local user_id = ARGV[10]
local snapshot_limit = tonumber(ARGV[11])
if not ttl or ttl <= 0 or not publish_interval or publish_interval <= 0 or
not snapshot_limit or snapshot_limit <= 0 or connection_id == "" or user_id == "" then
return redis.error_reply("invalid chat presence lease arguments")
end
if action ~= "online" and action ~= "away" and action ~= "release" then
return redis.error_reply("invalid chat presence lease action")
end
local snapshot_state_type = redis.call("TYPE", KEYS[3]).ok
local snapshot_expiry_type = redis.call("TYPE", KEYS[4]).ok
if (snapshot_state_type ~= "none" and snapshot_state_type ~= "hash") or
(snapshot_expiry_type ~= "none" and snapshot_expiry_type ~= "zset") then
return redis.error_reply("invalid chat presence snapshot registry")
end
local leases = {}
local pruned = 0
local raw = redis.call("GET", KEYS[1])
if raw then
local ok, decoded = pcall(cjson.decode, raw)
if not ok or type(decoded) ~= "table" then
return redis.error_reply("invalid chat presence lease registry")
end
leases = decoded
end
local previous_presence = nil
local previous_published_at = nil
local publish_state_raw = redis.call("GET", KEYS[2])
if publish_state_raw then
local ok, publish_state = pcall(cjson.decode, publish_state_raw)
if not ok or type(publish_state) ~= "table" or
(publish_state.presence ~= "online" and publish_state.presence ~= "away" and publish_state.presence ~= "offline") or
type(publish_state.publishedAt) ~= "number" then
return redis.error_reply("invalid chat presence publish state")
end
previous_presence = publish_state.presence
previous_published_at = publish_state.publishedAt
end
for id, lease in pairs(leases) do
if type(id) ~= "string" or type(lease) ~= "table" or type(lease.expiresAt) ~= "number" or
(lease.presence ~= "online" and lease.presence ~= "away") then
return redis.error_reply("invalid chat presence lease entry")
end
if lease.expiresAt <= now then
leases[id] = nil
pruned = pruned + 1
end
end
local had_connection = leases[connection_id] ~= nil
if action == "release" then
leases[connection_id] = nil
else
leases[connection_id] = { presence = action, expiresAt = now + ttl }
end
local online = 0
local away = 0
local aggregate_expires_at = 0
for _, lease in pairs(leases) do
if lease.presence == "online" then
online = online + 1
else
away = away + 1
end
if lease.expiresAt > aggregate_expires_at then
aggregate_expires_at = lease.expiresAt
end
end
if online + away == 0 then
redis.call("DEL", KEYS[1])
else
redis.call("SET", KEYS[1], cjson.encode(leases), "PX", ttl * ${LEASE_STORAGE_TTL_MULTIPLIER})
end
local aggregate = "offline"
local payload = ARGV[7]
if online > 0 then
aggregate = "online"
payload = ARGV[5]
elseif away > 0 then
aggregate = "away"
payload = ARGV[6]
end
local expired_users = redis.call("ZRANGEBYSCORE", KEYS[4], "-inf", now)
for _, expired_user_id in ipairs(expired_users) do
redis.call("HDEL", KEYS[3], expired_user_id)
redis.call("ZREM", KEYS[4], expired_user_id)
end
if aggregate == "offline" then
redis.call("HDEL", KEYS[3], user_id)
redis.call("ZREM", KEYS[4], user_id)
else
redis.call("HSET", KEYS[3], user_id, aggregate)
redis.call("ZADD", KEYS[4], aggregate_expires_at, user_id)
end
while redis.call("ZCARD", KEYS[4]) > snapshot_limit do
local oldest_users = redis.call("ZRANGE", KEYS[4], 0, 0)
if #oldest_users == 0 then
break
end
redis.call("HDEL", KEYS[3], oldest_users[1])
redis.call("ZREM", KEYS[4], oldest_users[1])
end
if redis.call("HLEN", KEYS[3]) == 0 then
redis.call("DEL", KEYS[3], KEYS[4])
else
redis.call("PEXPIRE", KEYS[3], ttl * ${LEASE_STORAGE_TTL_MULTIPLIER})
redis.call("PEXPIRE", KEYS[4], ttl * ${LEASE_STORAGE_TTL_MULTIPLIER})
end
if action == "release" and not had_connection and pruned == 0 then
return "unchanged"
end
if previous_presence ~= aggregate or not previous_published_at or now - previous_published_at >= publish_interval then
redis.call("PUBLISH", channel, payload)
redis.call("SET", KEYS[2], cjson.encode({ presence = aggregate, publishedAt = now }), "PX", ttl * ${LEASE_STORAGE_TTL_MULTIPLIER})
elseif publish_state_raw then
redis.call("PEXPIRE", KEYS[2], ttl * ${LEASE_STORAGE_TTL_MULTIPLIER})
end
return aggregate
`;
const PRESENCE_SNAPSHOT_SCRIPT = `
local time = redis.call("TIME")
local now = (tonumber(time[1]) * 1000) + math.floor(tonumber(time[2]) / 1000)
local limit = tonumber(ARGV[1])
if not limit or limit <= 0 then
return redis.error_reply("invalid chat presence snapshot arguments")
end
local snapshot_state_type = redis.call("TYPE", KEYS[1]).ok
local snapshot_expiry_type = redis.call("TYPE", KEYS[2]).ok
if (snapshot_state_type ~= "none" and snapshot_state_type ~= "hash") or
(snapshot_expiry_type ~= "none" and snapshot_expiry_type ~= "zset") then
return redis.error_reply("invalid chat presence snapshot registry")
end
local expired_users = redis.call("ZRANGEBYSCORE", KEYS[2], "-inf", now)
for _, expired_user_id in ipairs(expired_users) do
redis.call("HDEL", KEYS[1], expired_user_id)
redis.call("ZREM", KEYS[2], expired_user_id)
end
while redis.call("ZCARD", KEYS[2]) > limit do
local oldest_users = redis.call("ZRANGE", KEYS[2], 0, 0)
if #oldest_users == 0 then
break
end
redis.call("HDEL", KEYS[1], oldest_users[1])
redis.call("ZREM", KEYS[2], oldest_users[1])
end
local users = redis.call("ZRANGE", KEYS[2], 0, limit - 1)
local snapshot = {}
for _, user_id in ipairs(users) do
local presence = redis.call("HGET", KEYS[1], user_id)
if presence ~= "online" and presence ~= "away" then
return redis.error_reply("invalid chat presence snapshot entry")
end
table.insert(snapshot, { userId = user_id, presence = presence })
end
if redis.call("ZCARD", KEYS[2]) == 0 then
redis.call("DEL", KEYS[1], KEYS[2])
end
return cjson.encode(snapshot)
`;
const TYPING_LEASE_SCRIPT = `
local time = redis.call("TIME")
local now = (tonumber(time[1]) * 1000) + math.floor(tonumber(time[2]) / 1000)
local ttl = tonumber(ARGV[1])
local connection_id = ARGV[2]
local action = ARGV[3]
local channel = ARGV[4]
if not ttl or ttl <= 0 or connection_id == "" then
return redis.error_reply("invalid chat typing lease arguments")
end
if action ~= "touch" and action ~= "release" then
return redis.error_reply("invalid chat typing lease action")
end
local leases = {}
local pruned = 0
local raw = redis.call("GET", KEYS[1])
if raw then
local ok, decoded = pcall(cjson.decode, raw)
if not ok or type(decoded) ~= "table" then
return redis.error_reply("invalid chat typing lease registry")
end
leases = decoded
end
for id, expires_at in pairs(leases) do
if type(id) ~= "string" or type(expires_at) ~= "number" then
return redis.error_reply("invalid chat typing lease entry")
end
if expires_at <= now then
leases[id] = nil
pruned = pruned + 1
end
end
local had_connection = leases[connection_id] ~= nil
if action == "release" then
leases[connection_id] = nil
else
leases[connection_id] = now + ttl
end
local active = 0
for _ in pairs(leases) do
active = active + 1
end
if active == 0 then
redis.call("DEL", KEYS[1])
else
redis.call("SET", KEYS[1], cjson.encode(leases), "PX", ttl * ${LEASE_STORAGE_TTL_MULTIPLIER})
end
if action == "release" and not had_connection and pruned == 0 then
return "unchanged"
end
if active > 0 then
redis.call("PUBLISH", channel, ARGV[5])
return "started"
end
redis.call("PUBLISH", channel, ARGV[6])
return "stopped"
`;
type ChatRoomTransport = "persistent" | "ephemeral";
export type ChatRoomHubDiagnostic = {
code: "invalid_payload" | "subscriber_failed";
transport: ChatRoomTransport;
tenantId: string;
chatId: string;
};
export type ChatRoomSubscriber = (event: ChatServerEvent) => void | Promise<void>;
export type ChatRoomSubscription = {
unsubscribe(): Promise<void>;
};
type ChatLeaseActor = ChatEventScope & {
userId: string;
connectionId: string;
occurredAt: Date;
};
export type ChatPresenceLeaseInput = ChatLeaseActor & {
presence: Exclude<ChatConnectionPresence, "offline">;
};
export type ChatTypingLeaseInput = ChatLeaseActor;
export type ChatLeaseReleaseInput = ChatLeaseActor;
export type ChatPresenceLeaseResult = ChatConnectionPresence | "unchanged";
export type ChatTypingLeaseResult = "started" | "stopped" | "unchanged";
export type ChatRoomHub = {
/** Resolves only after both Redis channels are active, so callers can gap-fill without a subscribe race. */
subscribe(scope: ChatEventScope, subscriber: ChatRoomSubscriber): Promise<ChatRoomSubscription>;
publish(event: unknown): Promise<number>;
/** Refreshes one connection lease and atomically publishes the user-level aggregate presence. */
touchPresence(input: ChatPresenceLeaseInput): Promise<ChatPresenceLeaseResult>;
/** Releases one connection without publishing offline while another connection remains active. */
releasePresence(input: ChatLeaseReleaseInput): Promise<ChatPresenceLeaseResult>;
/** Reads the bounded, TTL-pruned channel presence snapshot without scanning Redis. */
getPresenceSnapshot(scope: ChatEventScope, occurredAt: Date): Promise<ChatPresenceEvent[]>;
/** Refreshes one typing lease and atomically publishes the user-level typing state. */
touchTyping(input: ChatTypingLeaseInput): Promise<ChatTypingLeaseResult>;
/** Releases one typing lease and publishes stopped only after the final active connection leaves. */
releaseTyping(input: ChatLeaseReleaseInput): Promise<ChatTypingLeaseResult>;
close(): Promise<void>;
};
export type CreateChatRoomHubOptions = {
onDiagnostic?: (diagnostic: ChatRoomHubDiagnostic) => void;
};
type SubscriberEntry = {
handler: ChatRoomSubscriber;
};
type RoomState = {
scope: ChatEventScope;
subscribers: Set<SubscriberEntry>;
opening: Promise<void>;
persistentUnsubscribe: (() => Promise<void>) | null;
ephemeralUnsubscribe: (() => Promise<void>) | null;
teardown: Promise<void> | null;
};
export function createChatRoomHub(baseStore: SharedStore, options: CreateChatRoomHubOptions = {}): ChatRoomHub {
const store = createSharedStore({ namespace: CHAT_REALTIME_NAMESPACE, adapter: baseStore.adapter });
const rooms = new Map<string, RoomState>();
let closed = false;
let closePromise: Promise<void> | null = null;
const reportDiagnostic = (diagnostic: ChatRoomHubDiagnostic): void => {
try {
options.onDiagnostic?.(diagnostic);
} catch {
// Diagnostics must never break event delivery.
}
};
const handlePayload = async (room: RoomState, transport: ChatRoomTransport, raw: string): Promise<void> => {
let event: ChatServerEvent;
try {
if (raw.length > MAX_REDIS_EVENT_LENGTH) {
throw new Error("chat room payload exceeds its maximum length");
}
event = validateChatServerEvent(JSON.parse(raw) as unknown);
assertChatEventInScope(event, room.scope);
if (transport === "persistent" ? !isPersistentChatEvent(event) : !isEphemeralChatEvent(event)) {
throw new Error("chat room payload uses the wrong transport");
}
} catch {
reportDiagnostic({ code: "invalid_payload", transport, tenantId: room.scope.tenantId, chatId: room.scope.chatId });
return;
}
const deliveries = [...room.subscribers].map(async ({ handler }) => {
try {
await handler(event);
} catch {
reportDiagnostic({ code: "subscriber_failed", transport, tenantId: room.scope.tenantId, chatId: room.scope.chatId });
}
});
await Promise.all(deliveries);
};
const openRoom = async (room: RoomState): Promise<void> => {
const persistentChannel = channelName("persistent", room.scope);
const ephemeralChannel = channelName("ephemeral", room.scope);
const persistentUnsubscribe = await store.subscribe(persistentChannel, (raw) => handlePayload(room, "persistent", raw));
room.persistentUnsubscribe = persistentUnsubscribe;
try {
room.ephemeralUnsubscribe = await store.subscribe(ephemeralChannel, (raw) => handlePayload(room, "ephemeral", raw));
} catch (error) {
room.persistentUnsubscribe = null;
await persistentUnsubscribe();
throw error;
}
};
const teardownRoom = (roomKey: string, room: RoomState): Promise<void> => {
if (room.teardown) return room.teardown;
if (rooms.get(roomKey) === room) {
// Remove the draining room immediately so a concurrent subscriber opens fresh Redis listeners.
rooms.delete(roomKey);
}
room.teardown = (async () => {
try {
await room.opening;
} catch {
// A partial open cleans up its own subscription.
}
const disposers = [room.ephemeralUnsubscribe, room.persistentUnsubscribe].filter((dispose): dispose is () => Promise<void> => dispose !== null);
room.ephemeralUnsubscribe = null;
room.persistentUnsubscribe = null;
await Promise.allSettled(disposers.map((dispose) => dispose()));
})();
return room.teardown;
};
return {
async subscribe(scopeInput, subscriber) {
if (closed) throw new Error("chat room hub is closed");
if (typeof subscriber !== "function") throw new Error("chat room subscriber must be a function");
const scope = normalizeRoomScope(scopeInput);
const roomKey = scopeKey(scope);
let room = rooms.get(roomKey);
if (!room) {
room = {
scope,
subscribers: new Set(),
opening: Promise.resolve(),
persistentUnsubscribe: null,
ephemeralUnsubscribe: null,
teardown: null,
};
rooms.set(roomKey, room);
room.opening = openRoom(room);
}
const entry: SubscriberEntry = { handler: subscriber };
room.subscribers.add(entry);
try {
await room.opening;
} catch (error) {
room.subscribers.delete(entry);
if (room.subscribers.size === 0) {
await teardownRoom(roomKey, room);
}
throw error;
}
if (closed) {
room.subscribers.delete(entry);
if (room.subscribers.size === 0) {
await teardownRoom(roomKey, room);
}
throw new Error("chat room hub is closed");
}
let unsubscribed = false;
return {
async unsubscribe() {
if (unsubscribed) return;
unsubscribed = true;
room.subscribers.delete(entry);
if (room.subscribers.size === 0) {
await teardownRoom(roomKey, room);
}
},
};
},
async publish(input) {
if (closed) throw new Error("chat room hub is closed");
const event = validateChatServerEvent(input);
const scope = normalizeRoomScope({ tenantId: event.tenantId, chatId: event.chatId });
const transport: ChatRoomTransport = isPersistentChatEvent(event) ? "persistent" : "ephemeral";
const payload = JSON.stringify(event);
if (payload.length > MAX_REDIS_EVENT_LENGTH) {
throw new Error("chat room payload exceeds its maximum length");
}
return store.publish(channelName(transport, scope), payload);
},
async touchPresence(input) {
if (closed) throw new Error("chat room hub is closed");
return executePresenceLease(store, input, input.presence);
},
async releasePresence(input) {
if (closed) throw new Error("chat room hub is closed");
return executePresenceLease(store, input, "release");
},
async getPresenceSnapshot(scopeInput, occurredAt) {
if (closed) throw new Error("chat room hub is closed");
const scope = normalizeRoomScope(scopeInput);
if (!(occurredAt instanceof Date) || !Number.isFinite(occurredAt.getTime())) {
throw new Error("chat presence snapshot occurredAt must be a valid Date");
}
const result = await store.eval(
PRESENCE_SNAPSHOT_SCRIPT,
[presenceSnapshotStateKey(scope), presenceSnapshotExpiryKey(scope)],
[String(CHAT_PRESENCE_SNAPSHOT_MAX_USERS), String(occurredAt.getTime())]
);
return parsePresenceSnapshotResult(result, scope, occurredAt);
},
async touchTyping(input) {
if (closed) throw new Error("chat room hub is closed");
return executeTypingLease(store, input, "touch");
},
async releaseTyping(input) {
if (closed) throw new Error("chat room hub is closed");
return executeTypingLease(store, input, "release");
},
close() {
if (closePromise) return closePromise;
closed = true;
closePromise = Promise.allSettled([...rooms.entries()].map(([key, room]) => teardownRoom(key, room))).then(() => undefined);
return closePromise;
},
};
}
function normalizeRoomScope(input: ChatEventScope): ChatEventScope {
const scope = normalizeChatEventScope(input);
if (!CHANNEL_SCOPE_ID_PATTERN.test(scope.tenantId) || !CHANNEL_SCOPE_ID_PATTERN.test(scope.chatId)) {
throw new Error("chat room scope must use canonical identifiers");
}
return scope;
}
function channelName(transport: ChatRoomTransport, scope: ChatEventScope): string {
return `${transport}:${scope.tenantId}:${scope.chatId}`;
}
function scopeKey(scope: ChatEventScope): string {
return `${scope.tenantId}:${scope.chatId}`;
}
async function executePresenceLease(
store: SharedStore,
input: ChatPresenceLeaseInput | ChatLeaseReleaseInput,
action: "online" | "away" | "release"
): Promise<ChatPresenceLeaseResult> {
const actor = normalizeLeaseActor(input);
const requestId = randomUUID();
const onlinePayload = serializeLeaseEvent({
event: CHAT_EVENT_NAMES.presenceOnline,
cursor: null,
requestId,
tenantId: actor.tenantId,
chatId: actor.chatId,
occurredAt: actor.occurredAt.toISOString(),
data: { userId: actor.userId, presence: "online" },
});
const awayPayload = serializeLeaseEvent({
event: CHAT_EVENT_NAMES.presenceAway,
cursor: null,
requestId,
tenantId: actor.tenantId,
chatId: actor.chatId,
occurredAt: actor.occurredAt.toISOString(),
data: { userId: actor.userId, presence: "away" },
});
const offlinePayload = serializeLeaseEvent({
event: CHAT_EVENT_NAMES.presenceOffline,
cursor: null,
requestId,
tenantId: actor.tenantId,
chatId: actor.chatId,
occurredAt: actor.occurredAt.toISOString(),
data: { userId: actor.userId, presence: "offline" },
});
const result = await store.eval(
PRESENCE_LEASE_SCRIPT,
[leaseKey("presence", actor), presencePublishKey(actor), presenceSnapshotStateKey(actor), presenceSnapshotExpiryKey(actor)],
[
String(CHAT_PRESENCE_LEASE_TTL_MS),
actor.connectionId,
action,
resolveSharedStoreChannel(store, channelName("ephemeral", actor)),
onlinePayload,
awayPayload,
offlinePayload,
String(actor.occurredAt.getTime()),
String(CHAT_PRESENCE_UNCHANGED_PUBLISH_INTERVAL_MS),
actor.userId,
String(CHAT_PRESENCE_SNAPSHOT_MAX_USERS),
]
);
if (result === "online" || result === "away" || result === "offline" || result === "unchanged") {
return result;
}
throw new Error("chat presence lease returned an invalid result");
}
async function executeTypingLease(
store: SharedStore,
input: ChatTypingLeaseInput | ChatLeaseReleaseInput,
action: "touch" | "release"
): Promise<ChatTypingLeaseResult> {
const actor = normalizeLeaseActor(input);
const requestId = randomUUID();
const startedPayload = serializeLeaseEvent({
event: CHAT_EVENT_NAMES.typingStarted,
cursor: null,
requestId,
tenantId: actor.tenantId,
chatId: actor.chatId,
occurredAt: actor.occurredAt.toISOString(),
data: { userId: actor.userId },
});
const stoppedPayload = serializeLeaseEvent({
event: CHAT_EVENT_NAMES.typingStopped,
cursor: null,
requestId,
tenantId: actor.tenantId,
chatId: actor.chatId,
occurredAt: actor.occurredAt.toISOString(),
data: { userId: actor.userId },
});
const result = await store.eval(
TYPING_LEASE_SCRIPT,
[leaseKey("typing", actor)],
[
String(CHAT_TYPING_LEASE_TTL_MS),
actor.connectionId,
action,
resolveSharedStoreChannel(store, channelName("ephemeral", actor)),
startedPayload,
stoppedPayload,
String(actor.occurredAt.getTime()),
]
);
if (result === "started" || result === "stopped" || result === "unchanged") {
return result;
}
throw new Error("chat typing lease returned an invalid result");
}
function normalizeLeaseActor(input: ChatLeaseActor): ChatLeaseActor {
const scope = normalizeRoomScope(input);
const userId = normalizeLeaseIdentifier(input.userId, "userId", MAX_USER_ID_LENGTH);
const connectionId = normalizeLeaseIdentifier(input.connectionId, "connectionId", MAX_CONNECTION_ID_LENGTH);
if (!(input.occurredAt instanceof Date) || !Number.isFinite(input.occurredAt.getTime())) {
throw new Error("chat lease occurredAt must be a valid Date");
}
return { ...scope, userId, connectionId, occurredAt: input.occurredAt };
}
function normalizeLeaseIdentifier(value: string, label: string, maxLength: number): string {
if (typeof value !== "string" || value.length === 0 || value.length > maxLength || value !== value.trim() || value.includes("\u0000")) {
throw new Error(`chat lease ${label} is invalid`);
}
return value;
}
function leaseKey(kind: "presence" | "typing", actor: ChatLeaseActor): string {
return `lease:${kind}:${encodeLeaseKeyPart(actor.tenantId)}:${encodeLeaseKeyPart(actor.chatId)}:${encodeLeaseKeyPart(actor.userId)}`;
}
function presencePublishKey(actor: ChatLeaseActor): string {
return `lease:presence-published:${encodeLeaseKeyPart(actor.tenantId)}:${encodeLeaseKeyPart(actor.chatId)}:${encodeLeaseKeyPart(actor.userId)}`;
}
function presenceSnapshotStateKey(scope: ChatEventScope): string {
return `presence-snapshot:state:${encodeLeaseKeyPart(scope.tenantId)}:${encodeLeaseKeyPart(scope.chatId)}`;
}
function presenceSnapshotExpiryKey(scope: ChatEventScope): string {
return `presence-snapshot:expiry:${encodeLeaseKeyPart(scope.tenantId)}:${encodeLeaseKeyPart(scope.chatId)}`;
}
function encodeLeaseKeyPart(value: string): string {
return Buffer.from(value, "utf8").toString("base64url");
}
function serializeLeaseEvent(event: unknown): string {
const payload = JSON.stringify(validateChatServerEvent(event));
if (payload.length > MAX_REDIS_EVENT_LENGTH) {
throw new Error("chat lease event exceeds its maximum length");
}
return payload;
}
function parsePresenceSnapshotResult(result: unknown, scope: ChatEventScope, occurredAt: Date): ChatPresenceEvent[] {
if (typeof result !== "string" || result.length > MAX_REDIS_EVENT_LENGTH) {
throw new Error("chat presence snapshot returned an invalid result");
}
let parsed: unknown;
try {
parsed = JSON.parse(result) as unknown;
} catch {
throw new Error("chat presence snapshot returned invalid JSON");
}
if (!Array.isArray(parsed) || parsed.length > CHAT_PRESENCE_SNAPSHOT_MAX_USERS) {
throw new Error("chat presence snapshot returned an invalid result");
}
return parsed.map((entry) => {
if (!isRecord(entry) || typeof entry.userId !== "string" || (entry.presence !== "online" && entry.presence !== "away")) {
throw new Error("invalid chat presence snapshot entry");
}
const userId = normalizeLeaseIdentifier(entry.userId, "snapshot userId", MAX_USER_ID_LENGTH);
return validateChatServerEvent({
event: entry.presence === "online" ? CHAT_EVENT_NAMES.presenceOnline : CHAT_EVENT_NAMES.presenceAway,
cursor: null,
requestId: randomUUID(),
tenantId: scope.tenantId,
chatId: scope.chatId,
occurredAt: occurredAt.toISOString(),
data: { userId, presence: entry.presence },
}) as ChatPresenceEvent;
});
}
type PresenceLeaseRegistry = Record<string, { presence: "online" | "away"; expiresAt: number }>;
type TypingLeaseRegistry = Record<string, number>;
type PresencePublishState = { presence: ChatConnectionPresence; publishedAt: number };
type PresenceSnapshotRegistry = Record<string, { presence: Exclude<ChatConnectionPresence, "offline">; expiresAt: number }>;
async function runPresenceLeaseInMemory(adapter: MemoryAdapter, keys: string[], args: string[]): Promise<ChatPresenceLeaseResult> {
if (keys.length !== 4 || args.length !== 11) throw new Error("invalid chat presence lease arguments");
const [ttlRaw, connectionId, action, channel, onlinePayload, awayPayload, offlinePayload, nowRaw, publishIntervalRaw, userId, snapshotLimitRaw] = args;
const ttl = requirePositiveNumber(ttlRaw, "presence ttl");
const now = requireFiniteNumber(nowRaw, "presence clock");
const publishInterval = requirePositiveNumber(publishIntervalRaw, "presence publish interval");
const snapshotLimit = requirePositiveNumber(snapshotLimitRaw, "presence snapshot limit");
if (!connectionId || !channel || !userId || (action !== "online" && action !== "away" && action !== "release")) {
throw new Error("invalid chat presence lease arguments");
}
const registry = parsePresenceRegistry(await adapter.get(keys[0]));
const previousPublish = parsePresencePublishState(await adapter.get(keys[1]));
const snapshot = parsePresenceSnapshotRegistry(await adapter.get(keys[2]));
let pruned = 0;
for (const [id, lease] of Object.entries(registry)) {
if (lease.expiresAt <= now) {
delete registry[id];
pruned += 1;
}
}
for (const [snapshotUserId, entry] of Object.entries(snapshot)) {
if (entry.expiresAt <= now) delete snapshot[snapshotUserId];
}
const hadConnection = registry[connectionId] !== undefined;
if (action === "release") {
delete registry[connectionId];
} else {
registry[connectionId] = { presence: action, expiresAt: now + ttl };
}
let online = 0;
let away = 0;
let aggregateExpiresAt = 0;
for (const lease of Object.values(registry)) {
if (lease.presence === "online") online += 1;
else away += 1;
aggregateExpiresAt = Math.max(aggregateExpiresAt, lease.expiresAt);
}
await persistMemoryRegistry(adapter, keys[0], registry, ttl);
const aggregate: ChatConnectionPresence = online > 0 ? "online" : away > 0 ? "away" : "offline";
if (aggregate === "offline") delete snapshot[userId];
else snapshot[userId] = { presence: aggregate, expiresAt: aggregateExpiresAt };
trimMemoryPresenceSnapshot(snapshot, snapshotLimit);
await persistMemoryPresenceSnapshot(adapter, keys[2], keys[3], snapshot, ttl);
if (action === "release" && !hadConnection && pruned === 0) return "unchanged";
const payload = aggregate === "online" ? onlinePayload : aggregate === "away" ? awayPayload : offlinePayload;
if (!payload) throw new Error("invalid chat presence lease payload");
if (previousPublish?.presence !== aggregate || now - previousPublish.publishedAt >= publishInterval) {
await adapter.publish(channel, payload);
const stored = await adapter.set(keys[1], JSON.stringify({ presence: aggregate, publishedAt: now } satisfies PresencePublishState), {
ttlSeconds: Math.ceil((ttl * LEASE_STORAGE_TTL_MULTIPLIER) / 1000),
});
if (!stored) throw new Error("chat presence publish state could not be stored");
} else {
await adapter.expire(keys[1], Math.ceil((ttl * LEASE_STORAGE_TTL_MULTIPLIER) / 1000));
}
return aggregate;
}
async function runPresenceSnapshotInMemory(adapter: MemoryAdapter, keys: string[], args: string[]): Promise<string> {
if (keys.length !== 2 || args.length !== 2) throw new Error("invalid chat presence snapshot arguments");
const limit = requirePositiveNumber(args[0], "presence snapshot limit");
const now = requireFiniteNumber(args[1], "presence snapshot clock");
const snapshot = parsePresenceSnapshotRegistry(await adapter.get(keys[0]));
for (const [userId, entry] of Object.entries(snapshot)) {
if (entry.expiresAt <= now) delete snapshot[userId];
}
trimMemoryPresenceSnapshot(snapshot, limit);
await persistMemoryPresenceSnapshot(adapter, keys[0], keys[1], snapshot, CHAT_PRESENCE_LEASE_TTL_MS);
return JSON.stringify(
Object.entries(snapshot)
.sort(([left], [right]) => left.localeCompare(right))
.slice(0, limit)
.map(([userId, entry]) => ({ userId, presence: entry.presence }))
);
}
function trimMemoryPresenceSnapshot(snapshot: PresenceSnapshotRegistry, limit: number): void {
const overflow = Object.entries(snapshot).length - limit;
if (overflow <= 0) return;
const oldest = Object.entries(snapshot)
.sort(([leftUserId, left], [rightUserId, right]) => left.expiresAt - right.expiresAt || leftUserId.localeCompare(rightUserId))
.slice(0, overflow);
for (const [userId] of oldest) delete snapshot[userId];
}
async function runTypingLeaseInMemory(adapter: MemoryAdapter, keys: string[], args: string[]): Promise<ChatTypingLeaseResult> {
if (keys.length !== 1 || args.length !== 7) throw new Error("invalid chat typing lease arguments");
const [ttlRaw, connectionId, action, channel, startedPayload, stoppedPayload, nowRaw] = args;
const ttl = requirePositiveNumber(ttlRaw, "typing ttl");
const now = requireFiniteNumber(nowRaw, "typing clock");
if (!connectionId || !channel || (action !== "touch" && action !== "release")) {
throw new Error("invalid chat typing lease arguments");
}
const registry = parseTypingRegistry(await adapter.get(keys[0]));
let pruned = 0;
for (const [id, expiresAt] of Object.entries(registry)) {
if (expiresAt <= now) {
delete registry[id];
pruned += 1;
}
}
const hadConnection = registry[connectionId] !== undefined;
if (action === "release") {
delete registry[connectionId];
} else {
registry[connectionId] = now + ttl;
}
const active = Object.keys(registry).length;
await persistMemoryRegistry(adapter, keys[0], registry, ttl);
if (action === "release" && !hadConnection && pruned === 0) return "unchanged";
const result: ChatTypingLeaseResult = active > 0 ? "started" : "stopped";
const payload = result === "started" ? startedPayload : stoppedPayload;
if (!payload) throw new Error("invalid chat typing lease payload");
await adapter.publish(channel, payload);
return result;
}
function parsePresenceRegistry(raw: string | null): PresenceLeaseRegistry {
if (raw === null) return Object.create(null) as PresenceLeaseRegistry;
const parsed = parseRegistryRecord(raw, "presence");
const registry = Object.create(null) as PresenceLeaseRegistry;
for (const [connectionId, value] of Object.entries(parsed)) {
if (
!isRecord(value) ||
(value.presence !== "online" && value.presence !== "away") ||
typeof value.expiresAt !== "number" ||
!Number.isFinite(value.expiresAt)
) {
throw new Error("invalid chat presence lease entry");
}
registry[connectionId] = { presence: value.presence, expiresAt: value.expiresAt };
}
return registry;
}
function parseTypingRegistry(raw: string | null): TypingLeaseRegistry {
if (raw === null) return Object.create(null) as TypingLeaseRegistry;
const parsed = parseRegistryRecord(raw, "typing");
const registry = Object.create(null) as TypingLeaseRegistry;
for (const [connectionId, expiresAt] of Object.entries(parsed)) {
if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) {
throw new Error("invalid chat typing lease entry");
}
registry[connectionId] = expiresAt;
}
return registry;
}
function parsePresencePublishState(raw: string | null): PresencePublishState | null {
if (raw === null) return null;
let parsed: unknown;
try {
parsed = JSON.parse(raw) as unknown;
} catch {
throw new Error("invalid chat presence publish state");
}
if (
!isRecord(parsed) ||
(parsed.presence !== "online" && parsed.presence !== "away" && parsed.presence !== "offline") ||
typeof parsed.publishedAt !== "number" ||
!Number.isFinite(parsed.publishedAt)
) {
throw new Error("invalid chat presence publish state");
}
return { presence: parsed.presence, publishedAt: parsed.publishedAt };
}
function parsePresenceSnapshotRegistry(raw: string | null): PresenceSnapshotRegistry {
if (raw === null) return Object.create(null) as PresenceSnapshotRegistry;
const parsed = parseRegistryRecord(raw, "presence snapshot");
const snapshot = Object.create(null) as PresenceSnapshotRegistry;
for (const [userId, value] of Object.entries(parsed)) {
normalizeLeaseIdentifier(userId, "snapshot userId", MAX_USER_ID_LENGTH);
if (
!isRecord(value) ||
(value.presence !== "online" && value.presence !== "away") ||
typeof value.expiresAt !== "number" ||
!Number.isFinite(value.expiresAt)
) {
throw new Error("invalid chat presence snapshot entry");
}
snapshot[userId] = { presence: value.presence, expiresAt: value.expiresAt };
}
return snapshot;
}
function parseRegistryRecord(raw: string, kind: "presence" | "typing" | "presence snapshot"): Record<string, unknown> {
let parsed: unknown;
try {
parsed = JSON.parse(raw) as unknown;
} catch {
throw new Error(`invalid chat ${kind} lease registry`);
}
if (!isRecord(parsed)) throw new Error(`invalid chat ${kind} lease registry`);
return parsed;
}
async function persistMemoryPresenceSnapshot(
adapter: MemoryAdapter,
stateKey: string,
expiryKey: string,
snapshot: PresenceSnapshotRegistry,
leaseTtlMs: number
): Promise<void> {
if (Object.keys(snapshot).length === 0) {
await Promise.all([adapter.del(stateKey), adapter.del(expiryKey)]);
return;
}
const ttlSeconds = Math.ceil((leaseTtlMs * LEASE_STORAGE_TTL_MULTIPLIER) / 1000);
const [stateStored, expiryStored] = await Promise.all([
adapter.set(stateKey, JSON.stringify(snapshot), { ttlSeconds }),
adapter.set(expiryKey, JSON.stringify(Object.fromEntries(Object.entries(snapshot).map(([userId, entry]) => [userId, entry.expiresAt]))), { ttlSeconds }),
]);
if (!stateStored || !expiryStored) throw new Error("chat presence snapshot could not be stored");
}
async function persistMemoryRegistry(
adapter: MemoryAdapter,
key: string,
registry: PresenceLeaseRegistry | TypingLeaseRegistry,
leaseTtlMs: number
): Promise<void> {
if (Object.keys(registry).length === 0) {
await adapter.del(key);
return;
}
const stored = await adapter.set(key, JSON.stringify(registry), {
ttlSeconds: Math.ceil((leaseTtlMs * LEASE_STORAGE_TTL_MULTIPLIER) / 1000),
});
if (!stored) throw new Error("chat lease registry could not be stored");
}
function requirePositiveNumber(value: string | undefined, label: string): number {
const parsed = requireFiniteNumber(value, label);
if (parsed <= 0) throw new Error(`invalid chat ${label}`);
return parsed;
}
function requireFiniteNumber(value: string | undefined, label: string): number {
const parsed = Number(value);
if (value === undefined || !Number.isFinite(parsed)) throw new Error(`invalid chat ${label}`);
return parsed;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
MemoryAdapter.registerScript(PRESENCE_LEASE_SCRIPT, runPresenceLeaseInMemory);
MemoryAdapter.registerScript(PRESENCE_SNAPSHOT_SCRIPT, runPresenceSnapshotInMemory);
MemoryAdapter.registerScript(TYPING_LEASE_SCRIPT, runTypingLeaseInMemory);
@@ -4,6 +4,16 @@ import { getApiRuntimeConfig, resetApiRuntimeConfigForTests, setApiRuntimeConfig
const originalEnv = { ...process.env };
const PRODUCTION_SECRETS = {
session: "session-secret-value-with-at-least-32-characters",
crypto: "crypto-secret-value-with-at-least-32-characters",
adminConnection: "admin-connection-key-with-at-least-32-characters",
apiAccess: "api-access-token-value-with-at-least-32-characters",
jwt: "jwt-secret-value-with-at-least-32-characters",
analytics: "analytics-token-value-with-at-least-32-characters",
auditChain: "audit-chain-secret-value-with-at-least-32-characters",
} as const;
const REQUIRED_PRODUCTION_ENV = {
APP_NAME: "Production API",
DATABASE_URL: "postgres://example.invalid/app",
@@ -11,22 +21,20 @@ const REQUIRED_PRODUCTION_ENV = {
WEB_APP_HOST: "app.example.com",
ADMIN_APP_HOST: "admin.example.com",
API_HOST: "api.example.com",
SESSION_SECRET: "session-secret-value",
CRYPTO_SECRET: "crypto-secret-value",
API_ACCESS_TOKEN: "api-access-token-value",
JWT_SECRET: "jwt-secret-value",
ANALYTICS_TOKEN: "analytics-token-value",
SESSION_SECRET: PRODUCTION_SECRETS.session,
CRYPTO_SECRET: PRODUCTION_SECRETS.crypto,
ADMIN_CONNECTION_MASTER_KEY: PRODUCTION_SECRETS.adminConnection,
API_ACCESS_TOKEN: PRODUCTION_SECRETS.apiAccess,
JWT_SECRET: PRODUCTION_SECRETS.jwt,
ANALYTICS_TOKEN: PRODUCTION_SECRETS.analytics,
AUDIT_CHAIN_SECRET: PRODUCTION_SECRETS.auditChain,
API_PORT: "8081",
APP_PROTOCOL: "https",
};
const SECRET_VALUES = [
"api-access-token-value",
"jwt-secret-value",
...Object.values(PRODUCTION_SECRETS),
"secret-like-invalid-port-value",
"session-secret-value",
"crypto-secret-value",
"analytics-token-value",
];
afterEach(() => {
@@ -51,12 +59,13 @@ describe("getApiRuntimeConfig", () => {
webAppHost: "app.example.com",
adminAppHost: "admin.example.com",
apiHost: "api.example.com",
portalAppHost: "portal.example.com",
protocol: "https",
},
apiAccessToken: "api-access-token-value",
jwtSecret: "jwt-secret-value",
apiAccessToken: PRODUCTION_SECRETS.apiAccess,
jwtSecret: PRODUCTION_SECRETS.jwt,
analytics: {
token: "analytics-token-value",
token: PRODUCTION_SECRETS.analytics,
},
});
});
@@ -130,6 +139,7 @@ describe("getApiRuntimeConfig", () => {
webAppHost: "app.override.localhost",
adminAppHost: "admin.override.localhost",
apiHost: "api.override.localhost",
portalAppHost: "portal.override.localhost",
protocol: "http",
},
origins: {},
@@ -13,6 +13,7 @@ const TEST_API_CONFIG: ApiConfig = {
webAppHost: "app.localhost:3000",
adminAppHost: "admin.localhost:3000",
apiHost: "api.localhost:3000",
portalAppHost: "portal.localhost:3000",
protocol: "http",
},
origins: {
@@ -7,9 +7,13 @@ type MutatingMethod = "POST" | "PATCH" | "DELETE";
type ProtectionClass =
| "jwt-auth"
| "service-token"
| "platform-source-credential"
| "service-or-tenant-api-key"
| "optional-api-key-validation"
| "webhook-signature"
| "provider-hmac-webhook"
| "provider-body-token-webhook"
| "provider-header-token-webhook"
| "provider-refetch-webhook"
| "public-analytics-token"
| "public-widget"
@@ -28,9 +32,13 @@ type InventoryEntry = MutatingRoute & {
const allowedProtectionClasses = new Set<ProtectionClass>([
"jwt-auth",
"service-token",
"platform-source-credential",
"service-or-tenant-api-key",
"optional-api-key-validation",
"webhook-signature",
"provider-hmac-webhook",
"provider-body-token-webhook",
"provider-header-token-webhook",
"provider-refetch-webhook",
"public-analytics-token",
"public-widget",
@@ -64,9 +72,9 @@ const expectedInventory: InventoryEntry[] = [
},
{
method: "POST",
path: "/v1/ai/upload",
protectionClass: "service-token",
note: "Writes uploaded content using configured S3-compatible storage credentials for the API runtime.",
path: "/v1/platform/leads",
protectionClass: "platform-source-credential",
note: "Server-to-server lead ingestion requires a rotatable source-scoped bearer capability and mandatory source-partitioned idempotency rather than browser CSRF state.",
},
{
method: "POST",
@@ -74,6 +82,24 @@ const expectedInventory: InventoryEntry[] = [
protectionClass: "webhook-signature",
note: "Creates support tickets only after Mailjet webhook Basic-Auth credentials verify.",
},
{
method: "POST",
path: "/v1/email/inbound-mailjet",
protectionClass: "webhook-signature",
note: "Ingests tenant inbound mail only after Mailjet webhook Basic-Auth credentials verify.",
},
{
method: "POST",
path: "/v1/admin-sales/email/provider-events",
protectionClass: "provider-hmac-webhook",
note: "Accepts provider-neutral admin email lifecycle events only after timestamp-bound HMAC verification over the exact bounded request body.",
},
{
method: "POST",
path: "/v1/admin-sales/email/bcc-inbound",
protectionClass: "webhook-signature",
note: "Accepts external Admin Sales mail copies only after provider Basic-Auth and a signed rotatable recipient capability both verify.",
},
{
method: "POST",
path: "/v1/analytics/events",
@@ -98,12 +124,36 @@ const expectedInventory: InventoryEntry[] = [
protectionClass: "webhook-signature",
note: "Accepts sequence provider bounce events only after Mailjet webhook Basic-Auth credentials verify.",
},
{
method: "POST",
path: "/v1/billing/lago/webhooks",
protectionClass: "provider-hmac-webhook",
note: "Accepts Lago lifecycle events only after provider HMAC verification over the exact bounded request body and deduplicates subscription writes by the provider event key.",
},
{
method: "POST",
path: "/v1/billing/mollie/webhooks",
protectionClass: "provider-refetch-webhook",
note: "Accepts only a Mollie payment id, then verifies and expands it by refetching the payment from Mollie server-side before any DB write.",
},
{
method: "POST",
path: "/v1/webhooks/telephony/aircall",
protectionClass: "provider-body-token-webhook",
note: "Authenticates the bounded provider-issued body token against its stored hash and encrypted connection credential before tenant RLS binding, persistence, or queueing.",
},
{
method: "POST",
path: "/v1/webhooks/telephony/hallopetra",
protectionClass: "provider-header-token-webhook",
note: "Authenticates the dedicated bearer webhook secret against its stored hash and encrypted connection credential before tenant RLS binding, persistence, or queueing.",
},
{
method: "POST",
path: "/v1/webhooks/admin-telephony/aircall",
protectionClass: "provider-body-token-webhook",
note: "Authenticates the bounded provider-issued body token against its stored hash before AdminUser RLS binding and idempotent Admin Sales call persistence.",
},
{
method: "POST",
path: "/v1/webhooks/incoming/:tenant/:slug",
@@ -143,14 +193,14 @@ const expectedInventory: InventoryEntry[] = [
{
method: "POST",
path: "/v1/devices/register",
protectionClass: "service-token",
note: "Mobile push-token registration requires a service-token bearer credential carrying user identity; body userId + tenantId are reconciled against the authenticated principal downstream.",
protectionClass: "jwt-auth",
note: "Mobile push-token registration derives the owner exclusively from a verified active API-session JWT and rejects caller-supplied identity overrides.",
},
{
method: "POST",
path: "/v1/devices/revoke",
protectionClass: "service-token",
note: "Mobile push-token revocation requires a service-token bearer credential; revokes by token hash without echoing the raw token.",
protectionClass: "jwt-auth",
note: "Mobile push-token revocation derives the owner exclusively from a verified active API-session JWT and never echoes the raw token.",
},
];
@@ -26,23 +26,38 @@ describe("parseMailjetSequenceWebhookPayload", () => {
});
test("treats blocked and spam as bounces and normalizes casing/spacing", () => {
const blocked = parseMailjetSequenceWebhookPayload(
JSON.stringify({ event: " Blocked ", MessageID: "m-blocked", time: 1700000000 }),
);
const spam = parseMailjetSequenceWebhookPayload(
JSON.stringify({ event: "SPAM", MessageID: "m-spam", time: 1700000000 }),
);
const blocked = parseMailjetSequenceWebhookPayload(JSON.stringify({ event: " Blocked ", MessageID: "m-blocked", time: 1700000000 }));
const spam = parseMailjetSequenceWebhookPayload(JSON.stringify({ event: "SPAM", MessageID: "m-spam", time: 1700000000 }));
expect(blocked).toMatchObject({ ok: true, action: "bounce", eventType: "blocked", providerMessageId: "m-blocked" });
expect(spam).toMatchObject({ ok: true, action: "bounce", eventType: "spam", providerMessageId: "m-spam" });
});
test("resolves campaign CustomID and distinguishes soft from hard bounces", () => {
expect(
parseMailjetSequenceWebhookPayload(JSON.stringify({ event: "bounce", Message_GUID: "m-soft", CustomID: "campaign_out_123", hard_bounce: false }))
).toMatchObject({
ok: true,
action: "bounce",
outboundEmailId: "campaign_out_123",
bounceKind: "weich",
});
expect(
parseMailjetSequenceWebhookPayload(JSON.stringify({ event: "bounce", Message_GUID: "m-hard", CustomID: "campaign_out_456", hard_bounce: true }))
).toMatchObject({
ok: true,
action: "bounce",
outboundEmailId: "campaign_out_456",
bounceKind: "hart",
});
});
test("folds the first event of a batched array payload", () => {
const result = parseMailjetSequenceWebhookPayload(
JSON.stringify([
{ event: "bounce", MessageID: "first", time: 1700000000, error: "user unknown" },
{ event: "bounce", MessageID: "second" },
]),
])
);
expect(result).toMatchObject({
@@ -72,9 +87,7 @@ describe("parseMailjetSequenceWebhookPayload", () => {
});
test("interprets a unix-seconds timestamp", () => {
const result = parseMailjetSequenceWebhookPayload(
JSON.stringify({ event: "bounce", MessageID: "m", time: 1700000000 }),
);
const result = parseMailjetSequenceWebhookPayload(JSON.stringify({ event: "bounce", MessageID: "m", time: 1700000000 }));
expect(result).toMatchObject({ ok: true, action: "bounce" });
if (result.ok && result.action === "bounce") {
expect(result.bouncedAt.getTime()).toBe(1700000000 * 1000);
@@ -82,9 +95,7 @@ describe("parseMailjetSequenceWebhookPayload", () => {
});
test("interprets a unix-millis timestamp without re-scaling", () => {
const result = parseMailjetSequenceWebhookPayload(
JSON.stringify({ event: "bounce", MessageID: "m", time: 1700000000000 }),
);
const result = parseMailjetSequenceWebhookPayload(JSON.stringify({ event: "bounce", MessageID: "m", time: 1700000000000 }));
if (result.ok && result.action === "bounce") {
expect(result.bouncedAt.getTime()).toBe(1700000000000);
} else {
@@ -93,9 +104,7 @@ describe("parseMailjetSequenceWebhookPayload", () => {
});
test("parses an ISO-8601 timestamp string", () => {
const result = parseMailjetSequenceWebhookPayload(
JSON.stringify({ event: "bounce", MessageID: "m", time: "2026-01-02T03:04:05.000Z" }),
);
const result = parseMailjetSequenceWebhookPayload(JSON.stringify({ event: "bounce", MessageID: "m", time: "2026-01-02T03:04:05.000Z" }));
if (result.ok && result.action === "bounce") {
expect(result.bouncedAt.toISOString()).toBe("2026-01-02T03:04:05.000Z");
} else {
@@ -104,18 +113,12 @@ describe("parseMailjetSequenceWebhookPayload", () => {
});
test("falls back to `now` for an unparseable timestamp", () => {
const result = parseMailjetSequenceWebhookPayload(
JSON.stringify({ event: "bounce", MessageID: "m", time: "definitely-not-a-date" }),
NOW,
);
const result = parseMailjetSequenceWebhookPayload(JSON.stringify({ event: "bounce", MessageID: "m", time: "definitely-not-a-date" }), NOW);
expect(result).toMatchObject({ ok: true, action: "bounce", bouncedAt: NOW });
});
test("reads event id and reason from a nested data envelope", () => {
const result = parseMailjetSequenceWebhookPayload(
JSON.stringify({ data: { event: "bounce", MessageID: "nested-id", error: "mailbox full" } }),
NOW,
);
const result = parseMailjetSequenceWebhookPayload(JSON.stringify({ data: { event: "bounce", MessageID: "nested-id", error: "mailbox full" } }), NOW);
expect(result).toMatchObject({
ok: true,
@@ -1,10 +1,10 @@
import type { Context } from "hono";
import type {
EmailSequenceProviderWebhookResult,
MarkEmailSequenceDeliveryBouncedInput,
} from "@hivegrid/db/email-sequences.server";
import type { CampaignOutboundEmailBounceResult, MarkCampaignOutboundEmailBouncedInput } from "@hivegrid/db/email-campaign-bounces.server";
import type { EmailSequenceProviderWebhookResult, MarkEmailSequenceDeliveryBouncedInput } from "@hivegrid/db/email-sequences.server";
import type { RlsBootstrapIdentity } from "@hivegrid/db/rls-resolvers.server";
import type { ApiEnv } from "../api-types.js";
import { apiError } from "../middleware/error-envelope.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { verifyMailjetWebhookAuth } from "../webhooks/mailjet-webhook-auth.js";
import { parseMailjetSuppressionSignal } from "../webhooks/mailjet-suppression.js";
@@ -15,7 +15,10 @@ const MAILJET_BOUNCE_EVENT_TYPES = new Set(["bounce", "blocked", "spam"]);
export type EmailSequenceProviderWebhookDependencies = {
webhookSecret: string | null | undefined;
resolveEmailSequenceProviderMessageRlsIdentity(providerMessageId: string): Promise<RlsBootstrapIdentity | null>;
markEmailSequenceDeliveryBounced(input: MarkEmailSequenceDeliveryBouncedInput): Promise<EmailSequenceProviderWebhookResult>;
resolveCampaignOutboundEmailRlsIdentity(outboundEmailId: string): Promise<RlsBootstrapIdentity | null>;
markCampaignOutboundEmailBounced(input: MarkCampaignOutboundEmailBouncedInput): Promise<CampaignOutboundEmailBounceResult>;
// AK-P14a: optional per-tenant suppression-list write. When wired, a bounce /
// complaint additionally suppresses the recipient (best-effort, never fails the
// webhook). Absent in tests that only assert the sequence reconciliation.
@@ -33,7 +36,9 @@ type ParsedMailjetSequenceWebhook =
action: "bounce";
eventType: string;
providerMessageId: string;
outboundEmailId: string | null;
bouncedAt: Date;
bounceKind: "hart" | "weich";
errorMessage: string;
}
| {
@@ -41,10 +46,7 @@ type ParsedMailjetSequenceWebhook =
error: string;
};
export async function postMailjetEmailSequenceWebhookRequest(
c: Context<ApiEnv>,
deps: EmailSequenceProviderWebhookDependencies
) {
export async function postMailjetEmailSequenceWebhookRequest(c: Context<ApiEnv>, deps: EmailSequenceProviderWebhookDependencies) {
const authResult = verifyMailjetWebhookAuth({
secret: deps.webhookSecret,
headers: c.req.header(),
@@ -65,9 +67,11 @@ export async function postMailjetEmailSequenceWebhookRequest(
if (deps.recordSuppression) {
const signal = parseMailjetSuppressionSignal(rawBody);
if (signal.action === "suppress") {
await deps
.recordSuppression({ tenantId: signal.tenantId, emailAddress: signal.emailAddress, reason: signal.suppressionReason, detail: signal.detail })
.catch(() => undefined);
await runWithVerifiedApiRlsContext({ tenantId: signal.tenantId }, () =>
deps
.recordSuppression?.({ tenantId: signal.tenantId, emailAddress: signal.emailAddress, reason: signal.suppressionReason, detail: signal.detail })
.catch(() => undefined)
);
}
}
@@ -79,19 +83,56 @@ export async function postMailjetEmailSequenceWebhookRequest(
return c.json({ accepted: true, status: "ignored" }, 202);
}
try {
const result = await deps.markEmailSequenceDeliveryBounced({
providerMessageId: payloadResult.providerMessageId,
bouncedAt: payloadResult.bouncedAt,
errorMessage: payloadResult.errorMessage,
});
if (result.status === "unknown_delivery") {
if (payloadResult.outboundEmailId) {
const identity = await deps.resolveCampaignOutboundEmailRlsIdentity(payloadResult.outboundEmailId).catch(() => null);
if (!identity) {
return c.json({ accepted: true, status: "ignored" }, 202);
}
return c.json({ accepted: true, status: result.status }, 202);
} catch {
return apiError(c, 500, "email_sequence_webhook_failed", "Email sequence provider webhook could not be processed.");
return runWithVerifiedApiRlsContext({ tenantId: identity.tenantId }, async () => {
try {
const result = await deps.markCampaignOutboundEmailBounced({
tenantId: identity.tenantId,
outboundEmailId: payloadResult.outboundEmailId!,
bouncedAt: payloadResult.bouncedAt,
bounceKind: payloadResult.bounceKind,
providerEventType: payloadResult.eventType,
});
if (result.status === "unknown_delivery") {
return c.json({ accepted: true, status: "ignored" }, 202);
}
if (result.outboundEmailId !== identity.resourceId) {
return apiError(c, 500, "email_sequence_webhook_failed", "Email campaign provider webhook could not be processed.");
}
return c.json({ accepted: true, status: result.status }, 202);
} catch {
return apiError(c, 500, "email_sequence_webhook_failed", "Email campaign provider webhook could not be processed.");
}
});
}
const identity = await deps.resolveEmailSequenceProviderMessageRlsIdentity(payloadResult.providerMessageId).catch(() => null);
if (!identity) {
return c.json({ accepted: true, status: "ignored" }, 202);
}
return runWithVerifiedApiRlsContext({ tenantId: identity.tenantId }, async () => {
try {
const result = await deps.markEmailSequenceDeliveryBounced({
providerMessageId: payloadResult.providerMessageId,
bouncedAt: payloadResult.bouncedAt,
errorMessage: payloadResult.errorMessage,
});
if (result.status === "unknown_delivery") {
return c.json({ accepted: true, status: "ignored" }, 202);
}
if (result.deliveryId !== identity.resourceId) {
return apiError(c, 500, "email_sequence_webhook_failed", "Email sequence provider webhook could not be processed.");
}
return c.json({ accepted: true, status: result.status }, 202);
} catch {
return apiError(c, 500, "email_sequence_webhook_failed", "Email sequence provider webhook could not be processed.");
}
});
}
export function parseMailjetSequenceWebhookPayload(rawBody: string, now: Date = new Date()): ParsedMailjetSequenceWebhook {
@@ -111,7 +152,9 @@ export function parseMailjetSequenceWebhookPayload(rawBody: string, now: Date =
return { ok: false, error: "Mailjet sequence webhook payload must be an object." };
}
const eventType = normalizeEventType(readFirstStringAt(payload, [["event"], ["type"], ["event_type"], ["data", "event"], ["data", "type"], ["data", "event_type"]]));
const eventType = normalizeEventType(
readFirstStringAt(payload, [["event"], ["type"], ["event_type"], ["data", "event"], ["data", "type"], ["data", "event_type"]])
);
if (!eventType || !isBounceEventType(eventType)) {
return { ok: true, action: "ignore", eventType: eventType ?? "unknown" };
}
@@ -146,6 +189,14 @@ export function parseMailjetSequenceWebhookPayload(rawBody: string, now: Date =
["data", "timestamp"],
]);
const bouncedAt = parseProviderTimestamp(timestamp) ?? now;
const outboundEmailId = readFirstStringAt(payload, [
["CustomID"],
["customId"],
["custom_id"],
["data", "CustomID"],
["data", "customId"],
["data", "custom_id"],
]);
const reason = readFirstStringAt(payload, [
["error"],
["error_related_to"],
@@ -163,17 +214,31 @@ export function parseMailjetSequenceWebhookPayload(rawBody: string, now: Date =
action: "bounce",
eventType,
providerMessageId,
outboundEmailId: outboundEmailId?.startsWith("campaign_out_") ? outboundEmailId : null,
bouncedAt,
bounceKind: readBounceKind(payload, eventType),
errorMessage: reason ? `${eventType}: ${reason}` : eventType,
};
}
function readBounceKind(payload: Record<string, unknown>, eventType: string): "hart" | "weich" {
if (eventType !== "bounce") return "hart";
const value = readPath(payload, ["hard_bounce"]) ?? readPath(payload, ["hardBounce"]) ?? readPath(payload, ["data", "hard_bounce"]);
if (value === false || value === 0 || (typeof value === "string" && ["false", "0", "no"].includes(value.trim().toLowerCase()))) {
return "weich";
}
return "hart";
}
function isBounceEventType(eventType: string) {
return MAILJET_BOUNCE_EVENT_TYPES.has(eventType);
}
function normalizeEventType(value: string | undefined) {
return value?.trim().toLowerCase().replace(/[\s-]+/g, "_");
return value
?.trim()
.toLowerCase()
.replace(/[\s-]+/g, "_");
}
function parseProviderTimestamp(value: string | undefined) {
@@ -0,0 +1,76 @@
import { createServer } from "node:http";
import { afterEach, describe, expect, it } from "vitest";
import {
API_HEADERS_TIMEOUT_MS,
API_KEEP_ALIVE_TIMEOUT_MS,
API_MAX_HEADERS,
API_MAX_REQUESTS_PER_SOCKET,
API_REQUEST_TIMEOUT_MS,
hardenApiHttpServer,
removeWebSessionCookie,
} from "./http-server.js";
const servers: ReturnType<typeof createServer>[] = [];
afterEach(() => {
for (const server of servers.splice(0)) server.close();
});
describe("API HTTP server hardening", () => {
it("bounds slow headers, request bodies and connection reuse", () => {
const server = createServer();
servers.push(server);
expect(hardenApiHttpServer(server)).toBe(server);
expect(server.headersTimeout).toBe(API_HEADERS_TIMEOUT_MS);
expect(server.requestTimeout).toBe(API_REQUEST_TIMEOUT_MS);
expect(server.keepAliveTimeout).toBe(API_KEEP_ALIVE_TIMEOUT_MS);
expect(server.maxHeadersCount).toBe(API_MAX_HEADERS);
expect(server.maxRequestsPerSocket).toBe(API_MAX_REQUESTS_PER_SOCKET);
});
});
describe("removeWebSessionCookie", () => {
it("removes only the parent-domain web credential before API handling", async () => {
const request = new Request("https://api.example.test/v1/workspaces", {
method: "POST",
headers: {
cookie:
"theme=dark; hivegrid_session=legacy; hivegrid_app_session=app-local; __Host-hivegrid_app_session=app-prod; hivegrid_admin_session=admin-local; __Host-hivegrid_admin_session=admin-prod; hivegrid_api_session=api-session; hivegrid_session_backup=keep",
"content-type": "application/json",
},
body: JSON.stringify({ ok: true }),
});
const sanitized = removeWebSessionCookie(request);
expect(sanitized).not.toBe(request);
expect(sanitized.headers.get("cookie")).toBe("theme=dark; hivegrid_api_session=api-session; hivegrid_session_backup=keep");
await expect(sanitized.json()).resolves.toEqual({ ok: true });
});
it("removes a request that contains only current web-session cookie names", () => {
const request = new Request("https://api.example.test/v1/health", {
headers: { cookie: "__Host-hivegrid_app_session=app; __Host-hivegrid_admin_session=admin" },
});
expect(removeWebSessionCookie(request).headers.has("cookie")).toBe(false);
});
it("deletes the Cookie header when it contains only the web session", () => {
const request = new Request("https://api.example.test/status", {
headers: { cookie: "hivegrid_session=signed-web-session" },
});
expect(removeWebSessionCookie(request).headers.has("cookie")).toBe(false);
});
it("keeps request identity when no web session is present", () => {
const request = new Request("https://api.example.test/status", {
headers: { cookie: "hivegrid_api_session=api-session" },
});
expect(removeWebSessionCookie(request)).toBe(request);
});
});
@@ -0,0 +1,57 @@
import type { Server } from "node:http";
export const API_HEADERS_TIMEOUT_MS = 10_000;
export const API_REQUEST_TIMEOUT_MS = 30_000;
export const API_KEEP_ALIVE_TIMEOUT_MS = 5_000;
export const API_MAX_HEADERS = 100;
export const API_MAX_REQUESTS_PER_SOCKET = 1_000;
const WEB_SESSION_COOKIE_NAMES = new Set([
// Current host-only app/admin names (local HTTP and secure production).
"hivegrid_app_session",
"hivegrid_admin_session",
"__Host-hivegrid_app_session",
"__Host-hivegrid_admin_session",
// Remove the retired parent-domain name during the rollout as well.
"hivegrid_session",
]);
export function hardenApiHttpServer(server: Server): Server {
server.headersTimeout = API_HEADERS_TIMEOUT_MS;
server.requestTimeout = API_REQUEST_TIMEOUT_MS;
server.keepAliveTimeout = API_KEEP_ALIVE_TIMEOUT_MS;
server.maxHeadersCount = API_MAX_HEADERS;
server.maxRequestsPerSocket = API_MAX_REQUESTS_PER_SOCKET;
return server;
}
/**
* Web authentication is host-only and separate for app.* and admin.*. Strip
* both current names plus the retired parent-domain cookie defensively so a
* stale browser cookie can never reach API tracing, logging, or route logic.
*/
export function removeWebSessionCookie(request: Request): Request {
const cookie = request.headers.get("cookie");
if (!cookie) {
return request;
}
const sanitized = cookie
.split(";")
.map((part) => part.trim())
.filter((part) => {
const separator = part.indexOf("=");
const name = part.slice(0, separator === -1 ? part.length : separator).trim();
return part.length > 0 && !WEB_SESSION_COOKIE_NAMES.has(name);
})
.join("; ");
if (sanitized === cookie) {
return request;
}
const headers = new Headers(request.headers);
if (sanitized) {
headers.set("cookie", sanitized);
} else {
headers.delete("cookie");
}
return new Request(request, { headers });
}
@@ -9,6 +9,12 @@ function makeClient(now?: () => number) {
}
const SCOPE = "api:tenant:t1";
const TENANT_ID = "t1";
const PARTITION_KEY = `tenant:${TENANT_ID}`;
const tenantOwnership = { tenantId: TENANT_ID, partitionKey: PARTITION_KEY, systemOwned: false } as const;
const uniqueWhere = (scope: string, key: string) => ({
idempotency_key_partition_scope_key: { partitionKey: PARTITION_KEY, scope, key },
});
/**
* `IdempotencyStorageClient.findUnique` is typed via an intersection of
@@ -24,6 +30,7 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
const { client } = makeClient(() => 1_000);
await client.idempotencyKey.create({
data: {
...tenantOwnership,
scope: SCOPE,
key: "k1",
requestHash: "hash-1",
@@ -35,7 +42,7 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
});
const found = await client.idempotencyKey.findUnique({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "k1" } },
where: uniqueWhere(SCOPE, "k1"),
});
expect(found).not.toBeNull();
@@ -51,7 +58,7 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
it("returns null for an unknown key", async () => {
const { client } = makeClient();
const found = await client.idempotencyKey.findUnique({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "missing" } },
where: uniqueWhere(SCOPE, "missing"),
});
expect(found).toBeNull();
});
@@ -59,6 +66,7 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
it("throws a Prisma-style P2002 when the same scope+key is claimed twice", async () => {
const { client } = makeClient();
const data = {
...tenantOwnership,
scope: SCOPE,
key: "dup",
requestHash: "h",
@@ -76,6 +84,7 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
const { client } = makeClient(() => 5_000);
await client.idempotencyKey.create({
data: {
...tenantOwnership,
scope: SCOPE,
key: "k2",
requestHash: "h",
@@ -86,15 +95,15 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
},
});
const before = await client.idempotencyKey.findUnique({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "k2" } },
where: uniqueWhere(SCOPE, "k2"),
});
await client.idempotencyKey.update({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "k2" } },
where: uniqueWhere(SCOPE, "k2"),
data: { responseStatus: 200, responseBody: { done: true }, responseHeaders: { h: "v" } },
});
const after = await client.idempotencyKey.findUnique({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "k2" } },
where: uniqueWhere(SCOPE, "k2"),
});
expect(after?.responseStatus).toBe(200);
@@ -108,7 +117,7 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
const { client } = makeClient();
await expect(
client.idempotencyKey.update({
where: { idempotency_key_scope_key: { scope: SCOPE, key: "ghost" } },
where: uniqueWhere(SCOPE, "ghost"),
data: { responseStatus: 200 },
}),
).rejects.toThrow(/not found/i);
@@ -117,6 +126,7 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
it("deleteMany with scope+key removes exactly that entry", async () => {
const { client } = makeClient();
const base = {
...tenantOwnership,
scope: SCOPE,
requestHash: "h",
responseStatus: 200,
@@ -127,13 +137,13 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
await client.idempotencyKey.create({ data: { ...base, key: "a" } });
await client.idempotencyKey.create({ data: { ...base, key: "b" } });
await client.idempotencyKey.deleteMany?.({ where: { scope: SCOPE, key: "a" } });
await client.idempotencyKey.deleteMany?.({ where: { partitionKey: PARTITION_KEY, scope: SCOPE, key: "a" } });
expect(
await client.idempotencyKey.findUnique({ where: { idempotency_key_scope_key: { scope: SCOPE, key: "a" } } }),
await client.idempotencyKey.findUnique({ where: uniqueWhere(SCOPE, "a") }),
).toBeNull();
expect(
await client.idempotencyKey.findUnique({ where: { idempotency_key_scope_key: { scope: SCOPE, key: "b" } } }),
await client.idempotencyKey.findUnique({ where: uniqueWhere(SCOPE, "b") }),
).not.toBeNull();
});
@@ -141,6 +151,7 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
const { client } = makeClient(() => 10_000);
await client.idempotencyKey.create({
data: {
...tenantOwnership,
scope: SCOPE,
key: "fresh",
requestHash: "h",
@@ -153,17 +164,18 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
// Cut-off earlier than the entry's expiry → entry is kept.
await client.idempotencyKey.deleteMany?.({
where: { scope: SCOPE, key: "fresh", expiresAt: { lte: new Date(20_000) } },
where: { partitionKey: PARTITION_KEY, scope: SCOPE, key: "fresh", expiresAt: { lte: new Date(20_000) } },
});
expect(
await client.idempotencyKey.findUnique({ where: { idempotency_key_scope_key: { scope: SCOPE, key: "fresh" } } }),
await client.idempotencyKey.findUnique({ where: uniqueWhere(SCOPE, "fresh") }),
).not.toBeNull();
});
it("deleteMany scoped to one scope leaves other scopes intact", async () => {
const { client } = makeClient();
const base = {
...tenantOwnership,
requestHash: "h",
responseStatus: 200,
responseBody: null,
@@ -173,15 +185,16 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
await client.idempotencyKey.create({ data: { ...base, scope: "api:system", key: "x" } });
await client.idempotencyKey.create({ data: { ...base, scope: "api:tenant:other", key: "y" } });
await client.idempotencyKey.deleteMany?.({ where: { scope: "api:system" } });
await client.idempotencyKey.deleteMany?.({ where: { partitionKey: PARTITION_KEY, scope: "api:system" } });
expect(await client.idempotencyKey.count?.({ where: { scope: "api:system" } })).toBe(0);
expect(await client.idempotencyKey.count?.({ where: { scope: "api:tenant:other" } })).toBe(1);
expect(await client.idempotencyKey.count?.({ where: { partitionKey: PARTITION_KEY, scope: "api:system" } })).toBe(0);
expect(await client.idempotencyKey.count?.({ where: { partitionKey: PARTITION_KEY, scope: "api:tenant:other" } })).toBe(1);
});
it("count tallies only entries in the requested scope", async () => {
const { client } = makeClient();
const base = {
...tenantOwnership,
requestHash: "h",
responseStatus: 200,
responseBody: null,
@@ -192,14 +205,14 @@ describe("createSharedStoreIdempotencyStorageClient — Prisma-shaped contract",
await client.idempotencyKey.create({ data: { ...base, scope: SCOPE, key: "2" } });
await client.idempotencyKey.create({ data: { ...base, scope: "api:system", key: "3" } });
expect(await client.idempotencyKey.count?.({ where: { scope: SCOPE } })).toBe(2);
expect(await client.idempotencyKey.count?.({ where: { partitionKey: PARTITION_KEY, scope: SCOPE } })).toBe(2);
});
});
describe("createSharedStoreIdempotencyStorageClient — driven through createIdempotencyStore", () => {
it("stores then replays a successful operation", async () => {
const { client } = makeClient();
const idempotency = createIdempotencyStore({ client, scope: SCOPE });
const idempotency = createIdempotencyStore({ client, tenantId: TENANT_ID, scope: SCOPE });
const response = { status: 200, headers: {}, body: { value: 1 } };
const first = await idempotency.run("key-A", "fp-A", async () => response);
@@ -218,7 +231,7 @@ describe("createSharedStoreIdempotencyStorageClient — driven through createIde
it("reports a conflict when the same key arrives with a different fingerprint", async () => {
const { client } = makeClient();
const idempotency = createIdempotencyStore({ client, scope: SCOPE });
const idempotency = createIdempotencyStore({ client, tenantId: TENANT_ID, scope: SCOPE });
await idempotency.run("key-B", "fp-1", async () => ({ status: 200, headers: {}, body: null }));
const conflict = await idempotency.run("key-B", "fp-2", async () => ({ status: 200, headers: {}, body: null }));
@@ -236,8 +249,8 @@ describe("createSharedStoreIdempotencyStorageClient — driven through createIde
const replicaB = createSharedStoreIdempotencyStorageClient({
store: createSharedStore({ namespace: "api", adapter }),
});
const storeA = createIdempotencyStore({ client: replicaA, scope: SCOPE });
const storeB = createIdempotencyStore({ client: replicaB, scope: SCOPE });
const storeA = createIdempotencyStore({ client: replicaA, tenantId: TENANT_ID, scope: SCOPE });
const storeB = createIdempotencyStore({ client: replicaB, tenantId: TENANT_ID, scope: SCOPE });
const stored = await storeA.run("shared-key", "fp", async () => ({
status: 201,
@@ -34,6 +34,9 @@ import type { IdempotencyStorageClient } from "./store.js";
type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
type PersistedEntry = {
tenantId: string | null;
partitionKey: string;
systemOwned: boolean;
scope: string;
key: string;
requestHash: string;
@@ -51,8 +54,8 @@ function hex(value: string): string {
return Buffer.from(value, "utf8").toString("hex");
}
function suffixFor(scope: string, key: string): string {
return `${KEY_PREFIX}:${hex(scope)}:${hex(key)}`;
function suffixFor(partitionKey: string, scope: string, key: string): string {
return `${KEY_PREFIX}:${hex(partitionKey)}:${hex(scope)}:${hex(key)}`;
}
function ttlSecondsUntil(expiresAt: number | null, now: () => number): number | undefined {
@@ -101,10 +104,15 @@ export function createSharedStoreIdempotencyStorageClient(
return {
idempotencyKey: {
async findUnique({ where }) {
const { scope, key } = where.idempotency_key_scope_key;
const entry = await readEntry(suffixFor(scope, key));
const { partitionKey, scope, key } = where.idempotency_key_partition_scope_key;
const entry = await readEntry(suffixFor(partitionKey, scope, key));
if (!entry) return null;
return {
tenantId: entry.tenantId,
partitionKey: entry.partitionKey,
systemOwned: entry.systemOwned,
scope: entry.scope,
key: entry.key,
requestHash: entry.requestHash,
responseStatus: entry.responseStatus,
responseBody: entry.responseBody ?? null,
@@ -117,6 +125,9 @@ export function createSharedStoreIdempotencyStorageClient(
async create({ data }) {
const expiresAt = data.expiresAt ? data.expiresAt.getTime() : null;
const entry: PersistedEntry = {
tenantId: data.tenantId,
partitionKey: data.partitionKey,
systemOwned: data.systemOwned,
scope: data.scope,
key: data.key,
requestHash: data.requestHash,
@@ -127,7 +138,7 @@ export function createSharedStoreIdempotencyStorageClient(
expiresAt,
};
const ttlSeconds = ttlSecondsUntil(expiresAt, now);
const written = await store.set(suffixFor(data.scope, data.key), JSON.stringify(entry), {
const written = await store.set(suffixFor(data.partitionKey, data.scope, data.key), JSON.stringify(entry), {
nx: true,
...(ttlSeconds !== undefined ? { ttlSeconds } : {}),
});
@@ -139,8 +150,8 @@ export function createSharedStoreIdempotencyStorageClient(
},
async update({ where, data }) {
const { scope, key } = where.idempotency_key_scope_key;
const suffix = suffixFor(scope, key);
const { partitionKey, scope, key } = where.idempotency_key_partition_scope_key;
const suffix = suffixFor(partitionKey, scope, key);
const existing = await readEntry(suffix);
if (!existing) {
throw new Error("Idempotency key reservation not found.");
@@ -161,8 +172,8 @@ export function createSharedStoreIdempotencyStorageClient(
const where = args?.where;
// Targeted single-key delete — no scan needed.
if (where?.scope && where?.key) {
const suffix = suffixFor(where.scope, where.key);
if (where?.partitionKey && where.scope && where.key) {
const suffix = suffixFor(where.partitionKey, where.scope, where.key);
if (where.expiresAt?.lte) {
const entry = await readEntry(suffix);
const cutoff = where.expiresAt.lte.getTime();
@@ -179,6 +190,7 @@ export function createSharedStoreIdempotencyStorageClient(
// by TTL so this stays cheap; it is never on the request hot path.
const cutoff = where?.expiresAt?.lte ? where.expiresAt.lte.getTime() : null;
for await (const { suffix, entry } of iterateEntries()) {
if (where?.partitionKey && entry.partitionKey !== where.partitionKey) continue;
if (where?.scope && entry.scope !== where.scope) continue;
if (where?.key && entry.key !== where.key) continue;
if (cutoff !== null && !(entry.expiresAt !== null && entry.expiresAt <= cutoff)) continue;
@@ -187,9 +199,11 @@ export function createSharedStoreIdempotencyStorageClient(
},
async count(args) {
const partitionKey = args?.where?.partitionKey;
const scope = args?.where?.scope;
let total = 0;
for await (const { entry } of iterateEntries()) {
if (partitionKey && entry.partitionKey !== partitionKey) continue;
if (scope && entry.scope !== scope) continue;
total += 1;
}
@@ -7,6 +7,8 @@ const response: StoredIdempotencyResponse = {
body: { ok: true, nested: { count: 1 } },
};
const systemOwnership = { systemOwned: true } as const;
function fingerprint(parsedBody: unknown = { name: "Ada" }) {
return createRequestFingerprint({
method: "post",
@@ -20,7 +22,7 @@ function fingerprint(parsedBody: unknown = { name: "Ada" }) {
describe("idempotency store", () => {
test("stores the first successful response for a valid key", async () => {
const store = createIdempotencyStore({ now: () => 1000 });
const store = createIdempotencyStore({ ...systemOwnership, now: () => 1000 });
await expect(store.recordSuccess(" key_1 ", fingerprint(), response)).resolves.toEqual({
type: "stored",
@@ -31,7 +33,7 @@ describe("idempotency store", () => {
});
test("replays the stored response for the same key and fingerprint", async () => {
const store = createIdempotencyStore({ now: () => 1000 });
const store = createIdempotencyStore({ ...systemOwnership, now: () => 1000 });
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
@@ -44,7 +46,7 @@ describe("idempotency store", () => {
});
test("rejects a repeated key with a changed body fingerprint", async () => {
const store = createIdempotencyStore({ now: () => 1000 });
const store = createIdempotencyStore({ ...systemOwnership, now: () => 1000 });
const originalFingerprint = fingerprint({ name: "Ada" });
const changedFingerprint = fingerprint({ name: "Grace" });
@@ -59,7 +61,7 @@ describe("idempotency store", () => {
});
test("isolates records by idempotency key", async () => {
const store = createIdempotencyStore();
const store = createIdempotencyStore(systemOwnership);
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
@@ -69,11 +71,11 @@ describe("idempotency store", () => {
test("isolates API idempotency keys by tenant scope", async () => {
const client = createMemoryIdempotencyStorageClient();
const tenantOneStore = createIdempotencyStore({ client, scope: createApiIdempotencyScope({ tenantId: "tenant_1" }) });
const tenantTwoStore = createIdempotencyStore({ client, scope: createApiIdempotencyScope({ tenantId: "tenant_2" }) });
const tenantOneStore = createIdempotencyStore({ client, tenantId: "tenant_1", scope: createApiIdempotencyScope({ tenantId: "tenant_1" }) });
const tenantTwoStore = createIdempotencyStore({ client, tenantId: "tenant_2", scope: createApiIdempotencyScope({ tenantId: "tenant_2" }) });
const requestFingerprint = createRequestFingerprint({
method: "POST",
route: "/v1/entities/:entity/rows",
route: "/v1/contacts",
tenantId: "same-shape",
parsedBody: { name: "Ada" },
});
@@ -94,7 +96,7 @@ describe("idempotency store", () => {
});
test("bypasses malformed or missing idempotency keys", async () => {
const store = createIdempotencyStore();
const store = createIdempotencyStore(systemOwnership);
const requestFingerprint = fingerprint();
expect(normalizeIdempotencyKey(undefined)).toBeNull();
@@ -107,7 +109,7 @@ describe("idempotency store", () => {
test("prunes old records by max age", async () => {
let now = 1000;
const store = createIdempotencyStore({ maxAgeMs: 10, now: () => now });
const store = createIdempotencyStore({ ...systemOwnership, maxAgeMs: 10, now: () => now });
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
@@ -118,7 +120,7 @@ describe("idempotency store", () => {
});
test("caps growth by evicting the oldest entries when max entries is exceeded", async () => {
const store = createIdempotencyStore({ maxEntries: 1 });
const store = createIdempotencyStore({ ...systemOwnership, maxEntries: 1 });
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
@@ -150,7 +152,7 @@ describe("idempotency store", () => {
});
test("returns cloned response bodies instead of sharing mutable references", async () => {
const store = createIdempotencyStore();
const store = createIdempotencyStore(systemOwnership);
const requestFingerprint = fingerprint();
const originalResponse: StoredIdempotencyResponse = {
status: 200,
@@ -171,7 +173,7 @@ describe("idempotency store", () => {
});
test("clear resets all stored idempotency records", async () => {
const store = createIdempotencyStore();
const store = createIdempotencyStore(systemOwnership);
const requestFingerprint = fingerprint();
await store.recordSuccess("key_1", requestFingerprint, response);
@@ -186,7 +188,7 @@ describe("idempotency store", () => {
const findUnique = vi.spyOn(client.idempotencyKey, "findUnique");
const create = vi.spyOn(client.idempotencyKey, "create");
const update = vi.spyOn(client.idempotencyKey, "update");
const store = createIdempotencyStore({ client, now: () => 1000 });
const store = createIdempotencyStore({ ...systemOwnership, client, now: () => 1000 });
const operation = vi.fn(async () => response);
const requestFingerprint = fingerprint();
@@ -197,6 +199,9 @@ describe("idempotency store", () => {
expect(findUnique).toHaveBeenCalled();
expect(create).toHaveBeenCalledWith({
data: expect.objectContaining({
tenantId: null,
partitionKey: "system",
systemOwned: true,
scope: "api",
key: "key_1",
responseStatus: 0,
@@ -205,7 +210,7 @@ describe("idempotency store", () => {
}),
});
expect(update).toHaveBeenCalledWith({
where: { idempotency_key_scope_key: { scope: "api", key: "key_1" } },
where: { idempotency_key_partition_scope_key: { partitionKey: "system", scope: "api", key: "key_1" } },
data: expect.objectContaining({
responseStatus: response.status,
responseBody: response.body,
@@ -216,11 +221,14 @@ describe("idempotency store", () => {
test("reports an in-flight database reservation without running the operation", async () => {
const client = createMemoryIdempotencyStorageClient({ now: () => 1000 });
const store = createIdempotencyStore({ client, now: () => 1000 });
const store = createIdempotencyStore({ ...systemOwnership, client, now: () => 1000 });
const requestFingerprint = fingerprint();
const requestHash = JSON.stringify(requestFingerprint);
await client.idempotencyKey.create({
data: {
tenantId: null,
partitionKey: "system",
systemOwned: true,
scope: "api",
key: "key_reserved",
requestHash,
@@ -1,5 +1,12 @@
import { createHash } from "node:crypto";
import { CatalogError, foundationErrors, withIdempotency, type IdempotencyClient } from "@hivegrid/foundation";
import {
CatalogError,
foundationErrors,
resolveIdempotencyOwnership,
withIdempotency,
type IdempotencyClient,
type IdempotencyOwnership,
} from "@hivegrid/foundation";
export type IdempotencyKey = string;
export type RequestFingerprint = string;
@@ -26,7 +33,7 @@ export type IdempotencyFingerprintInput = {
parsedBody?: JsonValue;
};
export type IdempotencyStoreOptions = {
export type IdempotencyStoreOptions = IdempotencyOwnership & {
client?: IdempotencyStorageClient;
maxAgeMs?: number;
maxEntries?: number;
@@ -35,6 +42,11 @@ export type IdempotencyStoreOptions = {
};
type StoredEntry = {
tenantId?: string | null;
partitionKey?: string;
systemOwned?: boolean;
scope?: string;
key?: string;
requestHash: string;
responseStatus: number;
responseBody: JsonValue | null;
@@ -44,9 +56,13 @@ type StoredEntry = {
};
type IdempotencyKeyDelegate = IdempotencyClient["idempotencyKey"] & {
findUnique(args: { where: { idempotency_key_scope_key: { scope: string; key: string } } }): Promise<StoredEntry | null>;
deleteMany?(args?: { where?: { scope?: string; key?: string; expiresAt?: { lte?: Date } } }): Promise<unknown>;
count?(args?: { where?: { scope?: string } }): Promise<number>;
findUnique(args: {
where: { idempotency_key_partition_scope_key: { partitionKey: string; scope: string; key: string } };
}): Promise<StoredEntry | null>;
deleteMany?(args?: {
where?: { partitionKey?: string; scope?: string; key?: string; expiresAt?: { lte?: Date } };
}): Promise<unknown>;
count?(args?: { where?: { partitionKey?: string; scope?: string } }): Promise<number>;
};
export type IdempotencyStorageClient = Omit<IdempotencyClient, "idempotencyKey"> & {
@@ -107,19 +123,25 @@ export function createRequestFingerprint(input: IdempotencyFingerprintInput): Re
return createHash("sha256").update(stableStringify(safeInput)).digest("hex");
}
export function createApiIdempotencyScope(input: Pick<IdempotencyFingerprintInput, "tenantId">): string {
return input.tenantId ? `${DEFAULT_SCOPE}:tenant:${input.tenantId}` : `${DEFAULT_SCOPE}:system`;
export function createApiIdempotencyScope(input: { tenantId: string }): string {
const tenantId = input.tenantId.trim();
if (!tenantId) {
throw new Error("API idempotency requires a non-empty tenantId.");
}
return `${DEFAULT_SCOPE}:tenant:${tenantId}`;
}
export function createIdempotencyStore(options: IdempotencyStoreOptions = {}): IdempotencyStore {
export function createIdempotencyStore(options: IdempotencyStoreOptions): IdempotencyStore {
const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
const now = options.now ?? Date.now;
const scope = options.scope ?? DEFAULT_SCOPE;
const client = options.client ?? createMemoryIdempotencyStorageClient({ maxEntries: options.maxEntries ?? DEFAULT_MAX_ENTRIES, now });
const ownership = resolveIdempotencyOwnership(options);
const ownershipInput: IdempotencyOwnership = ownership.systemOwned ? { systemOwned: true } : { tenantId: ownership.tenantId! };
const expiresAt = () => new Date(now() + maxAgeMs);
const findEntry = async (key: IdempotencyKey) => findStoredEntry(client, scope, key, now);
const findEntry = async (key: IdempotencyKey) => findStoredEntry(client, ownership.partitionKey, scope, key, now);
return {
async recordSuccess(key, fingerprint, response) {
@@ -141,7 +163,7 @@ export function createIdempotencyStore(options: IdempotencyStoreOptions = {}): I
try {
const createdAt = now();
const response = await withIdempotency(
{ scope, key: normalizedKey, fingerprint, expiresAt: expiresAt() },
{ ...ownershipInput, scope, key: normalizedKey, fingerprint, expiresAt: expiresAt() },
createExpiringIdempotencyClient(client, now),
async () => {
const operationResponse = await operation();
@@ -216,14 +238,14 @@ export function createIdempotencyStore(options: IdempotencyStoreOptions = {}): I
return { type: "replay", response: normalizeStoredResponse(existing), createdAt: entryCreatedAt(existing, now()) };
},
async clear() {
await client.idempotencyKey.deleteMany?.({ where: { scope } });
await client.idempotencyKey.deleteMany?.({ where: { partitionKey: ownership.partitionKey, scope } });
},
async size() {
await this.prune();
return client.idempotencyKey.count?.({ where: { scope } }) ?? 0;
return client.idempotencyKey.count?.({ where: { partitionKey: ownership.partitionKey, scope } }) ?? 0;
},
async prune() {
await client.idempotencyKey.deleteMany?.({ where: { scope, expiresAt: { lte: new Date(now()) } } });
await client.idempotencyKey.deleteMany?.({ where: { partitionKey: ownership.partitionKey, scope, expiresAt: { lte: new Date(now()) } } });
},
};
}
@@ -231,8 +253,8 @@ export function createIdempotencyStore(options: IdempotencyStoreOptions = {}): I
export function createMemoryIdempotencyStorageClient(options: { maxEntries?: number; now?: () => number } = {}): IdempotencyStorageClient {
const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
const now = options.now ?? Date.now;
const rows = new Map<string, StoredEntry & { scope: string; key: string }>();
const rowKey = (scope: string, key: string) => `${scope}:${key}`;
const rows = new Map<string, StoredEntry>();
const rowKey = (partitionKey: string, scope: string, key: string) => `${partitionKey}:${scope}:${key}`;
const pruneOverflow = () => {
while (rows.size > maxEntries) {
@@ -249,14 +271,18 @@ export function createMemoryIdempotencyStorageClient(options: { maxEntries?: num
return {
idempotencyKey: {
async findUnique({ where }) {
return rows.get(rowKey(where.idempotency_key_scope_key.scope, where.idempotency_key_scope_key.key)) ?? null;
const unique = where.idempotency_key_partition_scope_key;
return rows.get(rowKey(unique.partitionKey, unique.scope, unique.key)) ?? null;
},
async create({ data }) {
const key = rowKey(data.scope, data.key);
const key = rowKey(data.partitionKey, data.scope, data.key);
if (rows.has(key)) {
throw Object.assign(new Error("Unique constraint failed on idempotency key"), { code: "P2002" });
}
rows.set(rowKey(data.scope, data.key), {
rows.set(key, {
tenantId: data.tenantId,
partitionKey: data.partitionKey,
systemOwned: data.systemOwned,
scope: data.scope,
key: data.key,
requestHash: data.requestHash,
@@ -269,7 +295,8 @@ export function createMemoryIdempotencyStorageClient(options: { maxEntries?: num
pruneOverflow();
},
async update({ where, data }) {
const key = rowKey(where.idempotency_key_scope_key.scope, where.idempotency_key_scope_key.key);
const unique = where.idempotency_key_partition_scope_key;
const key = rowKey(unique.partitionKey, unique.scope, unique.key);
const existing = rows.get(key);
if (!existing) {
throw new Error("Idempotency key reservation not found.");
@@ -288,6 +315,9 @@ export function createMemoryIdempotencyStorageClient(options: { maxEntries?: num
if (where?.scope && row.scope !== where.scope) {
continue;
}
if (where?.partitionKey && row.partitionKey !== where.partitionKey) {
continue;
}
if (where?.key && row.key !== where.key) {
continue;
}
@@ -299,7 +329,8 @@ export function createMemoryIdempotencyStorageClient(options: { maxEntries?: num
},
async count(args) {
const scope = args?.where?.scope;
return scope ? [...rows.values()].filter((row) => row.scope === scope).length : rows.size;
const partitionKey = args?.where?.partitionKey;
return [...rows.values()].filter((row) => (!scope || row.scope === scope) && (!partitionKey || row.partitionKey === partitionKey)).length;
},
},
};
@@ -314,8 +345,9 @@ function createExpiringIdempotencyClient(client: IdempotencyStorageClient, now:
if (existing?.expiresAt && existing.expiresAt.getTime() <= now()) {
await client.idempotencyKey.deleteMany?.({
where: {
scope: args.where.idempotency_key_scope_key.scope,
key: args.where.idempotency_key_scope_key.key,
partitionKey: args.where.idempotency_key_partition_scope_key.partitionKey,
scope: args.where.idempotency_key_partition_scope_key.scope,
key: args.where.idempotency_key_partition_scope_key.key,
expiresAt: { lte: new Date(now()) },
},
});
@@ -337,11 +369,19 @@ function createExpiringIdempotencyClient(client: IdempotencyStorageClient, now:
};
}
async function findStoredEntry(client: IdempotencyStorageClient, scope: string, key: IdempotencyKey, now: () => number) {
const existing = await client.idempotencyKey.findUnique({ where: { idempotency_key_scope_key: { scope, key } } });
async function findStoredEntry(
client: IdempotencyStorageClient,
partitionKey: string,
scope: string,
key: IdempotencyKey,
now: () => number,
) {
const existing = await client.idempotencyKey.findUnique({
where: { idempotency_key_partition_scope_key: { partitionKey, scope, key } },
});
if (existing?.expiresAt && existing.expiresAt.getTime() <= now()) {
await client.idempotencyKey.deleteMany?.({ where: { scope, key, expiresAt: { lte: new Date(now()) } } });
await client.idempotencyKey.deleteMany?.({ where: { partitionKey, scope, key, expiresAt: { lte: new Date(now()) } } });
return null;
}
@@ -67,7 +67,14 @@ describe("api-key isolation fixtures", () => {
test("merges nested config patches without losing other defaults", () => {
patchApiIsolationConfig({
listen: { port: 4242 },
routing: { appBaseDomain: "tenant-2.test", webAppHost: "app.tenant-2.test", adminAppHost: "admin.tenant-2.test", apiHost: "api.tenant-2.test", protocol: "https" },
routing: {
appBaseDomain: "tenant-2.test",
webAppHost: "app.tenant-2.test",
adminAppHost: "admin.tenant-2.test",
apiHost: "api.tenant-2.test",
portalAppHost: "portal.tenant-2.test",
protocol: "https",
},
origins: { web: "https://web.tenant-2.test" },
analytics: { token: "analytics_tenant2" },
mailjet: { webhookSecret: "mailer_tenant2_whsec" },
@@ -78,7 +85,12 @@ describe("api-key isolation fixtures", () => {
apiAccessToken: "service-secret",
jwtSecret: "scope-secret",
listen: { port: 4242 },
routing: { apiHost: "api.tenant-2.test", appBaseDomain: "tenant-2.test", protocol: "https" },
routing: {
apiHost: "api.tenant-2.test",
portalAppHost: "portal.tenant-2.test",
appBaseDomain: "tenant-2.test",
protocol: "https",
},
origins: { web: "https://web.tenant-2.test" },
analytics: { token: "analytics_tenant2" },
mailjet: { webhookSecret: "mailer_tenant2_whsec" },
@@ -18,6 +18,7 @@ export const TEST_API_CONFIG: ApiConfig = {
webAppHost: "app.localhost:3000",
adminAppHost: "admin.localhost:3000",
apiHost: "api.localhost:3000",
portalAppHost: "portal.localhost:3000",
protocol: "http",
},
origins: {},
@@ -3,10 +3,18 @@ import { describe, expect, it } from "vitest";
import { createAuditContextMiddleware, extractActorIp, extractActorUserAgent, getAuditContext, runWithAuditContext } from "./audit-context.js";
describe("extractActorIp", () => {
it("prefers cf-connecting-ip, then x-real-ip, then x-forwarded-for first hop", () => {
expect(extractActorIp((n) => (n === "cf-connecting-ip" ? "1.1.1.1" : "9.9.9.9"))).toBe("1.1.1.1");
it("accepts Cloudflare headers only behind a verified Cloudflare hop", () => {
expect(
extractActorIp((n) => {
if (n === "cf-connecting-ip") return "1.1.1.1";
if (n === "x-forwarded-for") return "9.9.9.9, 173.245.48.10";
return null;
}),
).toBe("1.1.1.1");
expect(extractActorIp((n) => (n === "cf-connecting-ip" ? "1.1.1.1" : null), "9.9.9.9")).toBe("9.9.9.9");
expect(extractActorIp((n) => (n === "x-real-ip" ? "2.2.2.2" : null))).toBe("2.2.2.2");
expect(extractActorIp((n) => (n === "x-forwarded-for" ? "3.3.3.3, 8.8.8.8" : null))).toBe("3.3.3.3");
expect(extractActorIp((n) => (n === "x-forwarded-for" ? "3.3.3.3, 8.8.8.8" : null))).toBe("8.8.8.8");
expect(extractActorIp((n) => (n === "cf-connecting-ip" ? "not-an-ip" : null))).toBeNull();
});
it("returns null for missing or oversized values", () => {
@@ -43,7 +51,8 @@ describe("audit context async local storage", () => {
const c = {
req: {
header(name: string): string | undefined {
if (name === "x-forwarded-for") return "172.16.0.5, 8.8.8.8";
if (name === "cf-connecting-ip") return "172.16.0.5";
if (name === "x-forwarded-for") return "203.0.113.250, 173.245.48.10";
if (name === "user-agent") return "Test/1.0";
return undefined;
},
@@ -1,5 +1,6 @@
import { AsyncLocalStorage } from "node:async_hooks";
import type { MiddlewareHandler } from "hono";
import { getTrustedClientIpFromHeaderLookup } from "../trusted-client-ip.js";
/**
* Phase 10 Task #67 — Audit auto-capture middleware (API).
@@ -23,16 +24,11 @@ export type AuditContext = {
const auditContextStore = new AsyncLocalStorage<AuditContext>();
const FORWARDED_HEADERS = ["cf-connecting-ip", "x-real-ip", "x-forwarded-for"] as const;
export function extractActorIp(headerLookup: (name: string) => string | null | undefined): string | null {
for (const name of FORWARDED_HEADERS) {
const raw = headerLookup(name);
if (typeof raw !== "string") continue;
const first = raw.split(",")[0]?.trim();
if (first && first.length > 0 && first.length <= 64) return first;
}
return null;
export function extractActorIp(
headerLookup: (name: string) => string | null | undefined,
immediatePeerIp?: string | null,
): string | null {
return getTrustedClientIpFromHeaderLookup(headerLookup, immediatePeerIp) || null;
}
export function extractActorUserAgent(headerLookup: (name: string) => string | null | undefined): string | null {
@@ -47,7 +43,7 @@ export function extractActorUserAgent(headerLookup: (name: string) => string | n
export function createAuditContextMiddleware(): MiddlewareHandler {
return async (c, next) => {
const ctx: AuditContext = {
actorIp: extractActorIp((n) => c.req.header(n)),
actorIp: extractActorIp((n) => c.req.header(n), c.env?.incoming?.socket.remoteAddress),
actorUserAgent: extractActorUserAgent((n) => c.req.header(n)),
requestId: (c.get("requestId") as string | undefined) ?? null,
};
@@ -13,11 +13,11 @@ function createTestApp() {
const readHandler = vi.fn((c) => c.json({ ok: true, requestId: c.get("requestId") }));
app.use("*", createRequestIdMiddleware());
app.use("*", createBodyLimitMiddleware({ jsonLimitBytes: 100, uploadLimitBytes: 1_000 }));
app.use("*", createBodyLimitMiddleware({ jsonLimitBytes: 100, platformLeadLimitBytes: 80 }));
app.post("/v1/analytics/events", writeHandler);
app.post("/v1/ai/upload", writeHandler);
app.post("/v1/platform/leads", writeHandler);
app.post("/v1/widgets/:id", writeHandler);
app.get("/v1/entities/widgets/rows", readHandler);
app.get("/v1/contacts", readHandler);
return { app, readHandler, writeHandler };
}
@@ -78,39 +78,37 @@ describe("createBodyLimitMiddleware", () => {
expect(writeHandler).not.toHaveBeenCalled();
});
test.each(["/v1/ai/upload", "/v1/ai/upload/tenant_1/asset.png"])(
"uses the explicit upload limit for AI upload requests at %s before handlers run",
async (path) => {
const { app, writeHandler } = createTestApp();
test("applies the stricter platform-lead limit before credential or persistence work", async () => {
const { app, writeHandler } = createTestApp();
const response = await app.request(path, {
method: "POST",
headers: {
"content-length": "1001",
"content-type": "application/octet-stream",
"x-request-id": "req_body_limit_upload",
},
body: "upload-secret-content",
});
const response = await app.request("/v1/platform/leads", {
method: "POST",
headers: {
"content-length": "81",
"content-type": "application/json",
"x-request-id": "req_platform_lead_body_limit",
},
body: JSON.stringify({ message: "sensitive lead body that must never reach the handler" }),
});
const responseText = await response.text();
expect(response.status).toBe(413);
expect(response.headers.get("x-request-id")).toBe("req_body_limit_upload");
expect(response.headers.get(BODY_LIMIT_HEADER)).toBe("1000");
await expect(response.json()).resolves.toEqual({
error: {
code: "body_too_large",
message: "Request body is too large.",
requestId: "req_body_limit_upload",
},
});
expect(writeHandler).not.toHaveBeenCalled();
}
);
expect(response.status).toBe(413);
expect(response.headers.get(BODY_LIMIT_HEADER)).toBe("80");
expect(responseText).not.toContain("sensitive lead body");
expect(JSON.parse(responseText)).toEqual({
error: {
code: "body_too_large",
message: "Request body is too large.",
requestId: "req_platform_lead_body_limit",
},
});
expect(writeHandler).not.toHaveBeenCalled();
});
test("allows GET requests even when content-length exceeds write limits", async () => {
const { app, readHandler } = createTestApp();
const response = await app.request("/v1/entities/widgets/rows", {
const response = await app.request("/v1/contacts", {
method: "GET",
headers: {
"content-length": "999999",
@@ -2,26 +2,25 @@ import type { MiddlewareHandler } from "hono";
import { apiError, type ApiErrorEnv } from "./error-envelope.js";
export const DEFAULT_JSON_BODY_LIMIT_BYTES = 1_048_576;
export const DEFAULT_UPLOAD_BODY_LIMIT_BYTES = 10_485_760;
export const PLATFORM_LEAD_JSON_BODY_LIMIT_BYTES = 65_536;
export const BODY_LIMIT_HEADER = "x-api-body-limit";
const WRITE_METHODS = new Set(["POST", "PUT", "PATCH"]);
type BodyLimitRule = {
limitBytes: number;
pathPrefix?: string;
};
type BodyLimitMiddlewareOptions = {
jsonLimitBytes?: number;
uploadLimitBytes?: number;
uploadPathPrefix?: string;
platformLeadLimitBytes?: number;
platformLeadPath?: string;
};
export function createBodyLimitMiddleware(options: BodyLimitMiddlewareOptions = {}): MiddlewareHandler<ApiErrorEnv> {
const jsonLimitBytes = options.jsonLimitBytes ?? DEFAULT_JSON_BODY_LIMIT_BYTES;
const uploadLimitBytes = options.uploadLimitBytes ?? DEFAULT_UPLOAD_BODY_LIMIT_BYTES;
const uploadPathPrefix = options.uploadPathPrefix ?? "/v1/ai/upload";
const platformLeadLimitBytes = options.platformLeadLimitBytes ?? PLATFORM_LEAD_JSON_BODY_LIMIT_BYTES;
const platformLeadPath = options.platformLeadPath ?? "/v1/platform/leads";
return async (c, next) => {
const method = c.req.method.toUpperCase();
@@ -30,7 +29,11 @@ export function createBodyLimitMiddleware(options: BodyLimitMiddlewareOptions =
return;
}
const rule = getBodyLimitRule(c.req.path, { jsonLimitBytes, uploadLimitBytes, uploadPathPrefix });
const rule = getBodyLimitRule(c.req.path, {
jsonLimitBytes,
platformLeadLimitBytes,
platformLeadPath,
});
const contentLength = parseContentLength(c.req.header("content-length"));
c.header(BODY_LIMIT_HEADER, String(rule.limitBytes));
@@ -47,8 +50,8 @@ export function createBodyLimitMiddleware(options: BodyLimitMiddlewareOptions =
}
function getBodyLimitRule(path: string, options: Required<BodyLimitMiddlewareOptions>): BodyLimitRule {
if (path === options.uploadPathPrefix || path.startsWith(`${options.uploadPathPrefix}/`)) {
return { limitBytes: options.uploadLimitBytes, pathPrefix: options.uploadPathPrefix };
if (path === options.platformLeadPath) {
return { limitBytes: options.platformLeadLimitBytes };
}
return { limitBytes: options.jsonLimitBytes };
@@ -1,13 +1,15 @@
import { reportError, type ErrorReporter } from "@hivegrid/error-reporter";
import type { Context } from "hono";
import { HTTPException } from "hono/http-exception";
import type { HttpBindings } from "@hono/node-server";
import { apiLogger } from "../logger.js";
import type { ApiRequestIdVariables } from "./request-id.js";
type ApiErrorStatus = 400 | 401 | 402 | 403 | 404 | 409 | 410 | 411 | 413 | 415 | 429 | 500 | 503;
type ApiErrorStatus = 400 | 401 | 402 | 403 | 404 | 409 | 410 | 411 | 413 | 415 | 422 | 429 | 500 | 503;
export type ApiErrorParams = Record<string, string | number | boolean | null>;
export type ApiErrorEnv = {
Bindings: HttpBindings;
Variables: ApiRequestIdVariables;
};
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it } from "vitest";
import {
__getApiOtelConfigForTests,
__resetApiOtelForTests,
createApiInstrumentations,
initApiOtel,
parseOtlpHeaders,
parseSamplerArg,
@@ -94,6 +95,17 @@ describe("readApiOtelConfig", () => {
});
describe("initApiOtel", () => {
it("registers only the remote I/O and logging instrumentations used by the API", () => {
expect(createApiInstrumentations().map((instrumentation) => instrumentation.instrumentationName)).toEqual([
"@opentelemetry/instrumentation-http",
"@opentelemetry/instrumentation-undici",
"@opentelemetry/instrumentation-pg",
"@opentelemetry/instrumentation-ioredis",
"@opentelemetry/instrumentation-aws-sdk",
"@opentelemetry/instrumentation-pino",
]);
});
it("is a no-op when OTEL_EXPORTER_OTLP_ENDPOINT is unset", () => {
const sdk = initApiOtel({
endpoint: undefined,
@@ -2,14 +2,13 @@
* OpenTelemetry bootstrap for the API process.
*
* MUST be imported as the very first statement in `apps/api/src/server.ts`
* so the auto-instrumentations can hook Node modules (`http`, `hono`,
* `prisma`, `bullmq`, `redis`, ...) before they are required for the first
* time. The hook order is verified by `apps/api/src/server.ts` keeping
* so the explicit instrumentations can hook Node modules before they are
* required for the first time. The hook order is verified by `apps/api/src/server.ts` keeping
* `import "./otel.js"` above every other import.
*
* No-op behaviour:
* - When `OTEL_EXPORTER_OTLP_ENDPOINT` is empty/unset the SDK is never
* constructed and the auto-instrumentations are never registered, so
* constructed and the instrumentations are never registered, so
* local development and Sentry-only staging keep working unchanged.
*
* Sentry-coexistence:
@@ -24,8 +23,13 @@
import { hostname } from "node:os";
import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { AwsInstrumentation } from "@opentelemetry/instrumentation-aws-sdk";
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { IORedisInstrumentation } from "@opentelemetry/instrumentation-ioredis";
import { PgInstrumentation } from "@opentelemetry/instrumentation-pg";
import { PinoInstrumentation } from "@opentelemetry/instrumentation-pino";
import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { BatchSpanProcessor, ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
@@ -48,6 +52,17 @@ const DEFAULT_SERVICE_NAME = "hivegrid-api";
const DEFAULT_SERVICE_NAMESPACE = "hivegrid";
const DEFAULT_TRACES_SAMPLER_ARG = 0.1;
export function createApiInstrumentations() {
return [
new HttpInstrumentation(),
new UndiciInstrumentation(),
new PgInstrumentation(),
new IORedisInstrumentation(),
new AwsInstrumentation(),
new PinoInstrumentation(),
];
}
/**
* Parses the OTel sampler ratio (0..1). Falls back to `fallback` on missing
* or malformed input. Symmetric clamp matches `parseSampleRate` in `sentry.ts`.
@@ -136,11 +151,7 @@ export function initApiOtel(config: ApiOtelConfig = readApiOtelConfig()): NodeSD
resource,
sampler,
spanProcessors: [new PIISpanProcessor(new BatchSpanProcessor(exporter))],
instrumentations: [
getNodeAutoInstrumentations({
"@opentelemetry/instrumentation-fs": { enabled: false },
}),
],
instrumentations: createApiInstrumentations(),
});
sdk.start();
@@ -1,7 +1,7 @@
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
import { PLUGIN_HOOK_ENTITY_CREATED } from "@hivegrid/plugin-runtime";
// The entity-row hook test mocks this module out entirely; here we exercise the
// The entity hook test mocks this module out entirely; here we exercise the
// REAL `emitPluginHookFireAndForget` and only stub the @hivegrid/db seams so the
// transaction/outbox plumbing and both error branches run without a database.
const { getDbClientMock, publishOutboxEventMock } = vi.hoisted(() => ({
@@ -184,7 +184,7 @@ export const publicApiOpenApiPaths = {
post: {
operationId: "receivePublicApiIncomingWebhook",
description:
"Tenant-scoped incoming lead webhook. The endpoint authenticates by the endpoint's configured mode: API key, HMAC token/signature, or URL/header token. Successful requests create an InboxLead and queue webhook.received automation executions.",
"Tenant-scoped incoming lead webhook. Credentials are verified before payload, billing, or ingestion work. HMAC timestamps have a five-minute freshness window and exact signed replays are deduplicated through the persistent idempotency store. Successful requests create an InboxLead and queue webhook.received automation executions.",
security: [{ apiKeyHeader: [] }, { webhookTokenHeader: [] }, { webhookHmac: [] }],
parameters: [
{
@@ -219,7 +219,7 @@ export const publicApiOpenApiPaths = {
name: "X-HiveGrid-Timestamp",
in: "header",
required: false,
description: "Unix timestamp used in the HMAC signing input '<timestamp>.<rawBody>'. Required for hmac endpoint mode.",
description: "Unix timestamp used in the HMAC signing input '<timestamp>.<rawBody>'. Required for hmac mode and accepted only within five minutes of server time.",
schema: { type: "string" },
},
{
@@ -291,8 +291,10 @@ export const publicApiOpenApiPaths = {
"402": apiErrorResponse("Tenant plan or billing state blocks webhook writes.", ["payment_required"]),
"403": apiErrorResponse("API key scope does not allow incoming webhooks.", ["insufficient_scope"]),
"404": apiErrorResponse("Tenant or incoming webhook endpoint was not found.", ["not_found"]),
"409": apiErrorResponse("An identical HMAC webhook is already being processed or conflicts with its replay fingerprint.", ["webhook_in_progress", "webhook_replay_conflict"]),
"429": apiErrorResponse("Hourly key or tenant rate limit exceeded.", ["rate_limit_exceeded"]),
"500": apiErrorResponse("Webhook ingestion failed with a redacted request-ID-correlated envelope.", ["webhook_ingestion_failed"]),
"503": apiErrorResponse("Persistent webhook replay protection is unavailable; ingestion fails closed.", ["webhook_replay_guard_unavailable"]),
},
},
},
@@ -0,0 +1,48 @@
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import { describe, expect, it } from "vitest";
function source(path: string): string {
return readFileSync(resolve(process.cwd(), path), "utf8");
}
describe("public ingress ordering", () => {
it("throttles unauthenticated API-key validation before parsing or database lookup", () => {
const route = source("apps/api/src/routes/auth-routes.ts");
const start = route.indexOf('app.post("/v1/api-keys/validate"');
const rateLimit = route.indexOf("await checkPublicIngressRateLimit", start);
const bodyParse = route.indexOf("await readJsonBody", start);
const credentialLookup = route.indexOf("findLegacyApiKeyByKey", start);
expect(start).toBeGreaterThanOrEqual(0);
expect(rateLimit).toBeGreaterThan(start);
expect(rateLimit).toBeLessThan(bodyParse);
expect(rateLimit).toBeLessThan(credentialLookup);
});
it("throttles analytics by IP before parsing and by visitor before writes", () => {
const route = source("apps/api/src/routes/analytics-routes.ts");
const start = route.indexOf("async function postAnalyticsEventRequest");
const ipLimit = route.indexOf("await enforceAnalyticsIngressRateLimit", start);
const bodyParse = route.indexOf("await readJsonBody", start);
const visitorLimit = route.indexOf("await enforceAnalyticsVisitorRateLimit", start);
const visitorLookup = route.indexOf("getOrCreateAnalyticsUniqueVisitor", start);
expect(ipLimit).toBeGreaterThan(start);
expect(ipLimit).toBeLessThan(bodyParse);
expect(visitorLimit).toBeGreaterThan(bodyParse);
expect(visitorLimit).toBeLessThan(visitorLookup);
});
it("throttles Mollie ingress before body parsing and provider refetch", () => {
const route = source("apps/api/src/billing/mollie-webhook-route.ts");
const start = route.indexOf("export async function postMollieBillingWebhookRequest");
const rateLimit = route.indexOf("await checkPublicIngressRateLimit", start);
const bodyParse = route.indexOf("await parseMollieWebhookInput", start);
const providerRefetch = route.indexOf("await dependencies.resolveMollieWebhookPayment", start);
expect(rateLimit).toBeGreaterThan(start);
expect(rateLimit).toBeLessThan(bodyParse);
expect(rateLimit).toBeLessThan(providerRefetch);
});
});
@@ -0,0 +1,83 @@
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { createSharedStore, MemoryAdapter, type SharedStore } from "@hivegrid/shared-store";
import {
ANALYTICS_VISITOR_REQUESTS_PER_MINUTE,
API_KEY_VALIDATION_IP_REQUESTS_PER_MINUTE,
PLATFORM_LEAD_PREAUTH_IP_REQUESTS_PER_MINUTE,
__resetPublicIngressRateLimitDependenciesForTests,
__setPublicIngressRateLimitDependenciesForTests,
checkPublicIngressRateLimit,
} from "./public-ingress-rate-limit.js";
const KEY_SECRET = "test-public-ingress-key-secret-with-32-bytes";
describe("public ingress rate limits", () => {
let store: SharedStore;
beforeEach(() => {
store = createSharedStore({ namespace: "public-ingress-test", adapter: new MemoryAdapter() });
__setPublicIngressRateLimitDependenciesForTests({ store, keySecret: KEY_SECRET });
});
afterEach(async () => {
__resetPublicIngressRateLimitDependenciesForTests();
await store.close();
});
it("bounds analytics writes per visitor across source addresses", async () => {
for (let attempt = 0; attempt < ANALYTICS_VISITOR_REQUESTS_PER_MINUTE; attempt += 1) {
await expect(checkPublicIngressRateLimit("analytics-visitor", "visitor@example.test")).resolves.toMatchObject({ allowed: true });
}
await expect(checkPublicIngressRateLimit("analytics-visitor", "visitor@example.test")).resolves.toMatchObject({
allowed: false,
unavailable: false,
headers: expect.objectContaining({ "Retry-After": expect.any(String) }),
});
});
it("does not put raw IP addresses or visitor identifiers into shared-store keys", async () => {
await checkPublicIngressRateLimit("analytics-ip", "203.0.113.42");
await checkPublicIngressRateLimit("analytics-visitor", "visitor@example.test");
const keys: string[] = [];
for await (const key of store.adapter.scan("shared-store:public-ingress-test:*")) keys.push(key);
expect(keys).toHaveLength(2);
expect(keys.join("\n")).not.toContain("203.0.113.42");
expect(keys.join("\n")).not.toContain("visitor@example.test");
});
it("fails closed when the HMAC key is unavailable", async () => {
__setPublicIngressRateLimitDependenciesForTests({ store, keySecret: null });
await expect(checkPublicIngressRateLimit("api-key-validation-ip", "203.0.113.42")).resolves.toEqual({
allowed: false,
unavailable: true,
retryAfterSeconds: 60,
headers: { "Retry-After": "60" },
});
});
it("caps unauthenticated API-key validation work before credential lookup", async () => {
for (let attempt = 0; attempt < API_KEY_VALIDATION_IP_REQUESTS_PER_MINUTE; attempt += 1) {
await checkPublicIngressRateLimit("api-key-validation-ip", "198.51.100.4");
}
await expect(checkPublicIngressRateLimit("api-key-validation-ip", "198.51.100.4")).resolves.toMatchObject({
allowed: false,
unavailable: false,
});
});
it("caps platform-lead requests per client before source-credential lookup", async () => {
for (let attempt = 0; attempt < PLATFORM_LEAD_PREAUTH_IP_REQUESTS_PER_MINUTE; attempt += 1) {
await checkPublicIngressRateLimit("platform-lead-preauth-ip", "203.0.113.60");
}
await expect(checkPublicIngressRateLimit("platform-lead-preauth-ip", "203.0.113.60")).resolves.toMatchObject({
allowed: false,
unavailable: false,
});
});
});
@@ -0,0 +1,142 @@
import { createHmac } from "node:crypto";
import { createFixedWindowRateLimiter, type FixedWindowRateLimiter, type SharedStore } from "@hivegrid/shared-store";
import { getApiRuntimeConfig } from "./config.js";
import { getSharedStore } from "./shared-store.js";
export const PUBLIC_INGRESS_RATE_LIMIT_WINDOW_SECONDS = 60;
export const ANALYTICS_IP_REQUESTS_PER_MINUTE = 300;
export const ANALYTICS_VISITOR_REQUESTS_PER_MINUTE = 120;
export const API_KEY_VALIDATION_IP_REQUESTS_PER_MINUTE = 120;
export const PLATFORM_LEAD_PREAUTH_IP_REQUESTS_PER_MINUTE = 120;
export const LAGO_WEBHOOK_IP_REQUESTS_PER_MINUTE = 600;
export const LAGO_WEBHOOK_GLOBAL_REQUESTS_PER_MINUTE = 3_000;
export const MOLLIE_WEBHOOK_IP_REQUESTS_PER_MINUTE = 600;
export const MOLLIE_WEBHOOK_GLOBAL_REQUESTS_PER_MINUTE = 3_000;
export type PublicIngressRateLimitScope =
| "analytics-ip"
| "analytics-visitor"
| "api-key-validation-ip"
| "platform-lead-preauth-ip"
| "lago-webhook-ip"
| "lago-webhook-global"
| "mollie-webhook-ip"
| "mollie-webhook-global";
type PublicIngressRule = {
max: number;
prefix: string;
};
const PUBLIC_INGRESS_RULES: Record<PublicIngressRateLimitScope, PublicIngressRule> = {
"analytics-ip": { max: ANALYTICS_IP_REQUESTS_PER_MINUTE, prefix: "public-ingress:analytics:ip" },
"analytics-visitor": { max: ANALYTICS_VISITOR_REQUESTS_PER_MINUTE, prefix: "public-ingress:analytics:visitor" },
"api-key-validation-ip": { max: API_KEY_VALIDATION_IP_REQUESTS_PER_MINUTE, prefix: "public-ingress:api-key-validation:ip" },
"platform-lead-preauth-ip": {
max: PLATFORM_LEAD_PREAUTH_IP_REQUESTS_PER_MINUTE,
prefix: "public-ingress:platform-lead:preauth:ip",
},
"lago-webhook-ip": { max: LAGO_WEBHOOK_IP_REQUESTS_PER_MINUTE, prefix: "public-ingress:lago:ip" },
"lago-webhook-global": { max: LAGO_WEBHOOK_GLOBAL_REQUESTS_PER_MINUTE, prefix: "public-ingress:lago:global" },
"mollie-webhook-ip": { max: MOLLIE_WEBHOOK_IP_REQUESTS_PER_MINUTE, prefix: "public-ingress:mollie:ip" },
"mollie-webhook-global": { max: MOLLIE_WEBHOOK_GLOBAL_REQUESTS_PER_MINUTE, prefix: "public-ingress:mollie:global" },
};
export type PublicIngressRateLimitResult =
| {
allowed: true;
headers: Record<string, string>;
}
| {
allowed: false;
unavailable: boolean;
retryAfterSeconds: number;
headers: Record<string, string>;
};
let limiters = new Map<PublicIngressRateLimitScope, FixedWindowRateLimiter>();
let storeFactory: () => SharedStore = () => getSharedStore();
let keySecretFactory: () => string = defaultKeySecret;
function defaultKeySecret(): string {
const secret = getApiRuntimeConfig().jwtSecret?.trim();
if (!secret) {
throw new Error("Public ingress rate-limit key secret is unavailable.");
}
return secret;
}
function limiterFor(scope: PublicIngressRateLimitScope): FixedWindowRateLimiter {
const cached = limiters.get(scope);
if (cached) {
return cached;
}
const rule = PUBLIC_INGRESS_RULES[scope];
const limiter = createFixedWindowRateLimiter({
store: storeFactory(),
prefix: rule.prefix,
windowSeconds: PUBLIC_INGRESS_RATE_LIMIT_WINDOW_SECONDS,
max: rule.max,
});
limiters.set(scope, limiter);
return limiter;
}
function pseudonymousBucketKey(scope: PublicIngressRateLimitScope, value: string): string {
return createHmac("sha256", keySecretFactory())
.update(`v1\0${scope}\0${value || "unknown"}`)
.digest("hex");
}
export async function checkPublicIngressRateLimit(scope: PublicIngressRateLimitScope, value: string): Promise<PublicIngressRateLimitResult> {
const rule = PUBLIC_INGRESS_RULES[scope];
try {
const decision = await limiterFor(scope).consume(pseudonymousBucketKey(scope, value));
const retryAfterSeconds = Math.max(1, Math.ceil((decision.resetAt.getTime() - Date.now()) / 1_000));
const headers = {
"X-RateLimit-Limit": String(rule.max),
"X-RateLimit-Remaining": String(Math.max(0, decision.remaining)),
"X-RateLimit-Reset": String(Math.ceil(decision.resetAt.getTime() / 1_000)),
"X-RateLimit-Scope": scope,
};
return decision.allowed
? { allowed: true, headers }
: {
allowed: false,
unavailable: false,
retryAfterSeconds,
headers: { ...headers, "Retry-After": String(retryAfterSeconds) },
};
} catch {
return {
allowed: false,
unavailable: true,
retryAfterSeconds: PUBLIC_INGRESS_RATE_LIMIT_WINDOW_SECONDS,
headers: { "Retry-After": String(PUBLIC_INGRESS_RATE_LIMIT_WINDOW_SECONDS) },
};
}
}
export function applyPublicIngressRateLimitHeaders(setHeader: (name: string, value: string) => void, result: PublicIngressRateLimitResult): void {
for (const [name, value] of Object.entries(result.headers)) {
setHeader(name, value);
}
}
export function __setPublicIngressRateLimitDependenciesForTests(input: { store: SharedStore; keySecret?: string | null }): void {
limiters = new Map();
storeFactory = () => input.store;
keySecretFactory = () => {
const value = input.keySecret?.trim();
if (!value) throw new Error("Public ingress rate-limit key secret is unavailable.");
return value;
};
}
export function __resetPublicIngressRateLimitDependenciesForTests(): void {
limiters = new Map();
storeFactory = () => getSharedStore();
keySecretFactory = defaultKeySecret;
}
@@ -0,0 +1,40 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { configureApiAppDependenciesForTests } from "./app-dependencies.js";
import { API_READINESS_CACHE_TTL_MS, checkCachedApiReadiness, resetApiReadinessCacheForTests } from "./readiness-cache.js";
describe("API readiness cache", () => {
let restoreDependencies: (() => void) | undefined;
afterEach(() => {
restoreDependencies?.();
restoreDependencies = undefined;
resetApiReadinessCacheForTests();
});
it("coalesces parallel probes and rechecks after the one-second window", async () => {
let release!: () => void;
const checkReadiness = vi.fn(() => new Promise<void>((resolve) => (release = resolve)));
restoreDependencies = configureApiAppDependenciesForTests({ checkReadiness });
const probes = Array.from({ length: 25 }, () => checkCachedApiReadiness(1_000));
expect(checkReadiness).toHaveBeenCalledOnce();
release();
await Promise.all(probes);
await checkCachedApiReadiness(1_000 + API_READINESS_CACHE_TTL_MS - 1);
expect(checkReadiness).toHaveBeenCalledOnce();
checkReadiness.mockResolvedValueOnce(undefined);
await checkCachedApiReadiness(1_000 + API_READINESS_CACHE_TTL_MS);
expect(checkReadiness).toHaveBeenCalledTimes(2);
});
it("briefly coalesces failing probes without converting failure into success", async () => {
const checkReadiness = vi.fn().mockRejectedValue(new Error("database unavailable"));
restoreDependencies = configureApiAppDependenciesForTests({ checkReadiness });
await expect(Promise.all([checkCachedApiReadiness(1_000), checkCachedApiReadiness(1_000)])).rejects.toThrow("database unavailable");
expect(checkReadiness).toHaveBeenCalledOnce();
});
});
@@ -0,0 +1,37 @@
import { getApiAppDependencies, type ApiAppDependencies } from "./app-dependencies.js";
export const API_READINESS_CACHE_TTL_MS = 1_000;
type ReadinessDependencies = Pick<ApiAppDependencies, "checkReadiness">;
let cached:
| {
dependencies: ReadinessDependencies;
expiresAt: number;
pending: Promise<void>;
}
| undefined;
export function checkCachedApiReadiness(now = Date.now()): Promise<void> {
const dependencies = getApiAppDependencies();
if (cached?.dependencies === dependencies && cached.expiresAt > now) {
return cached.pending;
}
let pending: Promise<void>;
try {
pending = Promise.resolve(dependencies.checkReadiness());
} catch (error) {
pending = Promise.reject(error);
}
cached = {
dependencies,
expiresAt: now + API_READINESS_CACHE_TTL_MS,
pending,
};
return pending;
}
export function resetApiReadinessCacheForTests(): void {
cached = undefined;
}
@@ -0,0 +1,38 @@
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
import { describe, expect, test } from "vitest";
import { runWithVerifiedApiRlsContext } from "./rls-context.js";
describe("API RLS context", () => {
test("isolates concurrent verified tenant requests", async () => {
const contexts = await Promise.all([
runWithVerifiedApiRlsContext({ tenantId: "tenant-a", userId: "user-a" }, async () => {
await Promise.resolve();
return getRlsExecutionContext();
}),
runWithVerifiedApiRlsContext({ tenantId: "tenant-b", userId: "user-b" }, async () => {
await Promise.resolve();
return getRlsExecutionContext();
}),
]);
expect(contexts[0]).toMatchObject({ tenantId: "tenant-a", userId: "user-a" });
expect(contexts[1]).toMatchObject({ tenantId: "tenant-b", userId: "user-b" });
expect(getRlsExecutionContext()).toBeNull();
});
test("leaves system work context-free when no verified identity is bound", async () => {
await Promise.resolve();
expect(getRlsExecutionContext()).toBeNull();
});
test("supports a verified platform operator without inventing a tenant scope", async () => {
const context = await runWithVerifiedApiRlsContext({ userId: "operator-a" }, async () => {
await Promise.resolve();
return getRlsExecutionContext();
});
expect(context).toEqual({ userId: "operator-a" });
expect(getRlsExecutionContext()).toBeNull();
});
});
@@ -0,0 +1,19 @@
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
export type VerifiedApiRlsIdentity =
| {
tenantId: string;
userId?: string;
}
| {
tenantId?: never;
userId: string;
};
/**
* Binds a tenant or platform operator only after the caller has authenticated
* the credential and resolved the identity from a trusted API boundary.
*/
export function runWithVerifiedApiRlsContext<T>(identity: VerifiedApiRlsIdentity, operation: () => T): T {
return runWithRlsContext(identity, operation);
}
@@ -38,7 +38,7 @@ function isRouteMethod(value: string): value is RouteMethod {
}
function documentedRouteKeys(text: string) {
return Array.from(text.matchAll(/^\| `([A-Z]+) (\/[^`]+)` \|/gm), (match) => {
return Array.from(text.matchAll(/^\|\s+`([A-Z]+) (\/[^`]+)`\s+\|/gm), (match) => {
const method = match[1] ?? "";
const path = match[2] ?? "";
if (!isRouteMethod(method)) {
@@ -62,9 +62,11 @@ describe("route access inventory documentation", () => {
test("documents every classified route key from the typed inventory exactly once", () => {
const routeKeys = routeAccessInventory.map(routeAccessKey);
const missingRouteKeys = missingItems(routeKeys, routeAccessInventoryDoc);
const extraRouteKeys = documentedRouteKeys(routeAccessInventoryDoc).filter((key) => !routeKeys.includes(key)).sort();
const extraRouteKeys = documentedRouteKeys(routeAccessInventoryDoc)
.filter((key) => !routeKeys.includes(key))
.sort();
const duplicateRouteKeys = routeKeys
.filter((key) => routeAccessInventoryDoc.match(new RegExp(String.raw`\| \`${escapeRegExp(key)}\` \|`, "g"))?.length !== 1)
.filter((key) => routeAccessInventoryDoc.match(new RegExp(String.raw`\|\s+\`${escapeRegExp(key)}\`\s+\|`, "g"))?.length !== 1)
.sort();
expect(missingRouteKeys, `Missing route access inventory document route keys:\n${missingRouteKeys.join("\n")}`).toEqual([]);
@@ -73,16 +75,13 @@ describe("route access inventory documentation", () => {
});
test("keeps access classes and verification commands visible for future route changes", () => {
const missingAccessClasses = missingItems(
Array.from(new Set(routeAccessInventory.map((entry) => `\`${entry.accessClass}\``))),
routeAccessInventoryDoc,
);
const missingAccessClasses = missingItems(Array.from(new Set(routeAccessInventory.map((entry) => `\`${entry.accessClass}\``))), routeAccessInventoryDoc);
const missingVerificationCommands = missingItems(
[
"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",
],
routeAccessInventoryDoc,
routeAccessInventoryDoc
);
expect(missingAccessClasses, `Missing route access class legend entries:\n${missingAccessClasses.join("\n")}`).toEqual([]);
@@ -96,7 +95,7 @@ describe("route access inventory documentation", () => {
expect(
leakedMarkers.map((result) => `${result.pattern} matched ${JSON.stringify(result.match)}`),
`Forbidden secret-like markers in route access inventory document:\n${leakedMarkers.map((result) => `${result.pattern} matched ${JSON.stringify(result.match)}`).join("\n")}`,
`Forbidden secret-like markers in route access inventory document:\n${leakedMarkers.map((result) => `${result.pattern} matched ${JSON.stringify(result.match)}`).join("\n")}`
).toEqual([]);
});
});
@@ -12,7 +12,13 @@ type OpenApiOperation = {
const appSourcePath = join(dirname(fileURLToPath(import.meta.url)), "app.ts");
const allowedAccessClasses = new Set<string>(routeAccessClasses);
const documentedOpenApiPaths = new Set(["/healthz", "/readyz", "/status", "/metrics", ...Object.keys(openApiDocument.paths).filter((path) => path.startsWith("/v1/"))]);
const documentedOpenApiPaths = new Set([
"/healthz",
"/readyz",
"/status",
"/metrics",
...Object.keys(openApiDocument.paths).filter((path) => path.startsWith("/v1/")),
]);
const sensitiveTextPattern = /\b(secret|password|token|api[-_ ]?key|bearer|credential|jwt|email|user id|userid)\s*[:=]\s*[^\s,;]+/i;
function toOpenApiPath(path: string) {
@@ -28,6 +34,9 @@ function getOpenApiOperation(route: Pick<RouteAccessInventoryEntry, "method" | "
}
function expectedSecurityFor(entry: RouteAccessInventoryEntry) {
if (entry.path === "/v1/billing/lago/webhooks") {
return [{ lagoWebhookHmac: [], lagoWebhookSignatureAlgorithm: [], lagoWebhookUniqueKey: [] }];
}
if (
[
"/v1/session/current-user",
@@ -49,16 +58,26 @@ function expectedSecurityFor(entry: RouteAccessInventoryEntry) {
return undefined;
case "public-analytics-token":
return [{ analyticsTokenHeader: [] }];
case "public-analytics-overview":
return [];
case "canonical-redirect":
return undefined;
case "webhook-signature":
return [{ mailjetWebhookAuth: [] }];
case "provider-hmac-webhook":
return [{ providerWebhookHmac: [], providerWebhookTimestamp: [] }];
case "provider-body-token-webhook":
return [];
case "provider-header-token-webhook":
return [{ bearerAuth: [] }];
case "provider-refetch-webhook":
return [];
case "jwt-auth":
return [{ apiSessionBearer: [] }];
case "service-token":
return [{ bearerAuth: [] }];
case "platform-source-credential":
return [{ platformLeadSourceBearer: [] }];
case "service-or-tenant-api-key":
return [{ bearerAuth: [] }, { apiKeyHeader: [] }];
case "optional-api-key-validation":
@@ -111,8 +130,18 @@ describe("route access inventory", () => {
test("uses supported classes, non-empty rationales, and redacted sensitive-data descriptions", () => {
const malformedEntries = routeAccessInventory
.filter((entry) => !allowedAccessClasses.has(entry.accessClass) || entry.rationale.trim().length === 0 || (typeof entry.sensitiveData === "string" && entry.sensitiveData.trim().length === 0) || sensitiveTextPattern.test(entry.rationale) || (typeof entry.sensitiveData === "string" && sensitiveTextPattern.test(entry.sensitiveData)))
.map((entry) => `${routeAccessKey(entry)} class=${entry.accessClass} rationale=${JSON.stringify(entry.rationale)} sensitiveData=${JSON.stringify(entry.sensitiveData)}`);
.filter(
(entry) =>
!allowedAccessClasses.has(entry.accessClass) ||
entry.rationale.trim().length === 0 ||
(typeof entry.sensitiveData === "string" && entry.sensitiveData.trim().length === 0) ||
sensitiveTextPattern.test(entry.rationale) ||
(typeof entry.sensitiveData === "string" && sensitiveTextPattern.test(entry.sensitiveData))
)
.map(
(entry) =>
`${routeAccessKey(entry)} class=${entry.accessClass} rationale=${JSON.stringify(entry.rationale)} sensitiveData=${JSON.stringify(entry.sensitiveData)}`
);
expect(malformedEntries, `Invalid route access inventory fields:\n${malformedEntries.join("\n")}`).toEqual([]);
});
@@ -135,6 +164,42 @@ describe("route access inventory", () => {
}
});
test("inventories account reads as service-token routes with an explicit verified operator identity", () => {
const accountEntries = routeAccessInventory.filter((entry) => ["/v1/accounts", "/v1/accounts/:id"].includes(entry.path));
expect(accountEntries.map(routeAccessKey).sort()).toEqual(["GET /v1/accounts", "GET /v1/accounts/:id"]);
for (const entry of accountEntries) {
expect(entry.accessClass).toBe("service-token");
expect(entry.rationale).toMatch(/operator user identifier.*RLS-protected AdminUser/i);
const operation = getOpenApiOperation(entry) as { parameters?: Array<Record<string, unknown>> } | undefined;
expect(operation?.parameters).toContainEqual(expect.objectContaining({ name: "x-hivegrid-operator-user-id", in: "header", required: true }));
}
});
test("inventories device writes with API-session identity and ownership-scoped RLS", () => {
const deviceEntries = routeAccessInventory.filter((entry) => ["/v1/devices/register", "/v1/devices/revoke"].includes(entry.path));
expect(deviceEntries.map(routeAccessKey).sort()).toEqual(["POST /v1/devices/register", "POST /v1/devices/revoke"]);
for (const entry of deviceEntries) {
expect(entry.accessClass).toBe("jwt-auth");
expect(entry.rationale).toMatch(/API-session JWT.*RLS/i);
expect(entry.sensitiveData).toMatch(/never (?:returns?|returning|echo(?:es|ing)).*raw/i);
expect(getOpenApiOperation(entry)?.security).toEqual([{ apiSessionBearer: [] }]);
}
});
test("inventories platform lead ingestion as a source-scoped pre-tenant capability", () => {
const entry = routeAccessInventory.find((candidate) => candidate.path === "/v1/platform/leads");
expect(entry).toMatchObject({
method: "POST",
accessClass: "platform-source-credential",
sensitiveData: expect.stringMatching(/omitting.*capability.*lead data/i),
});
expect(entry?.rationale).toMatch(/source-scoped bearer capability.*revalidated atomically.*pre-tenant/i);
expect(entry ? getOpenApiOperation(entry)?.security : undefined).toEqual([{ platformLeadSourceBearer: [] }]);
});
test("documents matching OpenAPI security metadata for represented OpenAPI routes", () => {
const missingOpenApiOperations = routeAccessInventory
.filter((entry) => documentedOpenApiPaths.has(toOpenApiPath(entry.path)) && !getOpenApiOperation(entry))
@@ -2,15 +2,20 @@ 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;
@@ -33,41 +38,41 @@ export function routeAccessKey(route: Pick<RouteAccessInventoryEntry, "method" |
}
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: "/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",
@@ -114,15 +119,18 @@ export const routeAccessInventory = [
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.",
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/ai/upload",
accessClass: "service-token",
rationale: "AI upload writes request content through configured S3-compatible service storage credentials and depends on server-side upload configuration.",
sensitiveData: "Consumes uploaded file content and may return a public storage URL.",
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",
@@ -131,33 +139,63 @@ export const routeAccessInventory = [
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 is public-facing and scoped by analytics payload identifiers rather than browser session state.",
sensitiveData: "Consumes analytics identifiers, URLs, routes, and event labels.",
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 is public-facing and scoped by analytics payload identifiers plus ignore-page settings.",
sensitiveData: "Consumes analytics identifiers, URLs, and route names.",
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-token",
rationale: "Public analytics overview requires the analytics token header before returning aggregate metrics.",
sensitiveData: "Returns aggregate analytics counts and top-level chart data.",
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 overview requires service credentials before returning tenant or portal scoped metrics.",
sensitiveData: "Returns aggregate analytics metrics that may be scoped to a portal identifier.",
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",
@@ -170,14 +208,16 @@ export const routeAccessInventory = [
method: "GET",
path: "/v1/accounts",
accessClass: "service-token",
rationale: "Account listing requires service credentials before returning tenant account metadata and subscription summaries.",
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 before returning one tenant account metadata and subscription summary.",
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.",
},
{
@@ -227,21 +267,62 @@ export const routeAccessInventory = [
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.",
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.",
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.",
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",
@@ -255,14 +336,16 @@ export const routeAccessInventory = [
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.",
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.",
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",
@@ -310,28 +393,33 @@ export const routeAccessInventory = [
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.",
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.",
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: "service-token",
rationale: "Mobile push-token registration requires a service credential (bearer/API-key) carrying user identity; the body's userId + tenantId are reconciled against the authenticated principal downstream.",
sensitiveData: "Persists device-bound push token. Stored token is hashed at rest; response contains only the registration id + masked token preview.",
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: "service-token",
rationale: "Mobile push-token revocation requires a service credential; the handler revokes by token hash and never echoes the raw token.",
sensitiveData: "Returns revocation confirmation without echoing the device token or push provider internals.",
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[];
@@ -1,10 +1,13 @@
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import type { LegacyTenantWithDetails, TenantSubscriptionWithDetails } from "../app-dependencies.js";
import { getApiAppDependencies } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { apiError } from "../middleware/error-envelope.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { requireServiceCredential } from "./shared.js";
const OPERATOR_USER_ID_HEADER = "x-hivegrid-operator-user-id";
export function registerAccountsRoutes(app: Hono<ApiEnv>) {
app.get("/v1/accounts", async (c) => {
const unauthorized = requireServiceCredential(c);
@@ -12,14 +15,35 @@ export function registerAccountsRoutes(app: Hono<ApiEnv>) {
return unauthorized;
}
const dependencies = getApiAppDependencies();
const tenants = await dependencies.adminGetAllLegacyTenants();
const data = tenants.map((tenant) => serializeAccountTenant(tenant, tenant.subscription));
const operatorUserId = readOperatorUserId(c);
if (!operatorUserId) {
return operatorIdentityRequired(c);
}
return c.json({
success: true,
total_results: data.length,
data,
const dependencies = getApiAppDependencies();
return runWithVerifiedApiRlsContext({ userId: operatorUserId }, async () => {
const operator = await dependencies.findPlatformOperatorByUserId(operatorUserId);
if (!operator || operator.userId !== operatorUserId) {
return operatorIdentityRequired(c);
}
const tenantSummaries = await dependencies.adminGetAllLegacyTenantSummaries();
const tenants: LegacyTenantWithDetails[] = [];
for (const tenantSummary of tenantSummaries) {
const tenant = await runWithVerifiedApiRlsContext({ tenantId: tenantSummary.id }, () =>
dependencies.findLegacyTenantById(tenantSummary.id)
);
if (tenant) {
tenants.push(tenant);
}
}
const data = tenants.map((tenant) => serializeAccountTenant(tenant, tenant.subscription));
return c.json({
success: true,
total_results: data.length,
data,
});
});
});
@@ -34,24 +58,50 @@ export function registerAccountsRoutes(app: Hono<ApiEnv>) {
return apiError(c, 400, "invalid_request", "Account id is required.");
}
const operatorUserId = readOperatorUserId(c);
if (!operatorUserId) {
return operatorIdentityRequired(c);
}
const dependencies = getApiAppDependencies();
const tenantSimple = await dependencies.findLegacyTenantByIdOrSlug(id);
if (!tenantSimple) {
return apiError(c, 404, "account_not_found", "Account was not found.");
}
return runWithVerifiedApiRlsContext({ userId: operatorUserId }, async () => {
const operator = await dependencies.findPlatformOperatorByUserId(operatorUserId);
if (!operator || operator.userId !== operatorUserId) {
return operatorIdentityRequired(c);
}
const tenant = await dependencies.findLegacyTenantById(tenantSimple.id);
if (!tenant) {
return apiError(c, 404, "account_not_found", "Account was not found.");
}
const tenantSimple = await dependencies.findLegacyTenantByIdOrSlug(id);
if (!tenantSimple) {
return apiError(c, 404, "account_not_found", "Account was not found.");
}
return c.json({
success: true,
data: serializeAccountTenant(tenant, await dependencies.getTenantSubscription(tenant.id)),
return runWithVerifiedApiRlsContext({ tenantId: tenantSimple.id }, async () => {
const tenant = await dependencies.findLegacyTenantById(tenantSimple.id);
if (!tenant) {
return apiError(c, 404, "account_not_found", "Account was not found.");
}
return c.json({
success: true,
data: serializeAccountTenant(tenant, await dependencies.getTenantSubscription(tenant.id)),
});
});
});
});
}
function readOperatorUserId(c: Context<ApiEnv>): string | null {
const userId = c.req.header(OPERATOR_USER_ID_HEADER)?.trim();
if (!userId || userId.length > 191 || userId.includes("\u0000")) {
return null;
}
return userId;
}
function operatorIdentityRequired(c: Context<ApiEnv>) {
return apiError(c, 403, "operator_identity_required", "A verified platform operator identity is required.");
}
function serializeAccountTenant(tenant: LegacyTenantWithDetails, subscription: TenantSubscriptionWithDetails | null) {
return {
id: tenant.id,
@@ -0,0 +1,152 @@
import { Hono } from "hono";
import { describe, expect, it, vi } from "vitest";
import { createAdminBccCapability } from "@hivegrid/integrations";
import type { ApiEnv } from "../api-types.js";
import { postAdminEmailBccInbound } from "./admin-email-routes.js";
const webhookSecret = "mailjet-webhook".padEnd(40, "x");
const capabilitySecret = "admin-bcc-capability".padEnd(40, "x");
const inboundDomain = "bcc.hivegrid.de";
const capability = createAdminBccCapability({
adminUserId: "admin-user-1",
inboundDomain,
secret: capabilitySecret,
randomBytes: () => new Uint8Array(8).fill(5),
});
function buildApp() {
const candidatesFor = vi.fn(async () => [
{
id: "contact-1",
kind: "contact" as const,
primary: false,
openDealIds: ["deal-1"],
},
]);
const ingest = vi.fn(async () => ({
status: "created" as const,
messageId: "message-1",
}));
const app = new Hono<ApiEnv>();
app.post("/v1/admin-sales/email/bcc-inbound", (c) =>
postAdminEmailBccInbound(c, {
webhookSecret,
capabilitySecret,
inboundDomain,
candidatesFor,
ingest,
})
);
return { app, candidatesFor, ingest };
}
function basicAuth(secret = webhookSecret) {
return `Basic ${Buffer.from(`mailjet:${secret}`).toString("base64")}`;
}
function payload(overrides: Record<string, unknown> = {}) {
return JSON.stringify({
messageId: "provider-message-1",
from: "sales@hivegrid.de",
to: capability.normalizedAddress,
headers: { To: "buyer@example.com" },
subject: "Demo",
text: "Hallo",
sentAt: "2026-07-24T10:00:00.000Z",
...overrides,
});
}
describe("admin email BCC inbound API", () => {
it("authenticates provider and signed recipient before binding Admin RLS", async () => {
const { app, candidatesFor, ingest } = buildApp();
const response = await app.request(
"/v1/admin-sales/email/bcc-inbound",
{
method: "POST",
body: payload(),
headers: {
"content-type": "application/json",
authorization: basicAuth(),
},
}
);
expect(response.status).toBe(201);
await expect(response.json()).resolves.toEqual({
accepted: true,
status: "created",
messageId: "message-1",
});
expect(candidatesFor).toHaveBeenCalledWith("buyer@example.com");
expect(ingest).toHaveBeenCalledWith(
expect.objectContaining({
adminUserId: "admin-user-1",
localPartHash: capability.localPartHash,
fromAddress: "sales@hivegrid.de",
toAddresses: ["buyer@example.com"],
match: expect.objectContaining({
status: "matched",
contactId: "contact-1",
dealId: "deal-1",
}),
})
);
});
it("rejects unauthenticated provider input before capability or DB access", async () => {
const { app, candidatesFor, ingest } = buildApp();
const response = await app.request(
"/v1/admin-sales/email/bcc-inbound",
{
method: "POST",
body: payload(),
headers: { "content-type": "application/json" },
}
);
expect(response.status).toBe(401);
expect(candidatesFor).not.toHaveBeenCalled();
expect(ingest).not.toHaveBeenCalled();
});
it("ignores tampered capabilities and payloads without an original recipient", async () => {
const { app, ingest } = buildApp();
const tampered = capability.normalizedAddress.replace(
"admin-user-1",
"admin-user-2"
);
const unknown = await app.request(
"/v1/admin-sales/email/bcc-inbound",
{
method: "POST",
body: payload({ to: tampered }),
headers: {
"content-type": "application/json",
authorization: basicAuth(),
},
}
);
expect(unknown.status).toBe(202);
await expect(unknown.json()).resolves.toMatchObject({
reason: "unknown-recipient",
});
const noCounterpart = await app.request(
"/v1/admin-sales/email/bcc-inbound",
{
method: "POST",
body: payload({ headers: {} }),
headers: {
"content-type": "application/json",
authorization: basicAuth(),
},
}
);
expect(noCounterpart.status).toBe(202);
await expect(noCounterpart.json()).resolves.toMatchObject({
reason: "counterpart-required",
});
expect(ingest).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,103 @@
import { Hono } from "hono";
import { describe, expect, it, vi } from "vitest";
import { signAdminEmailProviderEvent } from "@hivegrid/integrations/admin-email-provider-events";
import type { ApiEnv } from "../api-types.js";
import { postAdminEmailProviderEvent } from "./admin-email-routes.js";
const secret = "admin-email-provider-events".padEnd(40, "x");
function buildApp(record = vi.fn(async () => ({ status: "recorded" as const, eventId: "event-1", messageId: "message-1" }))) {
const app = new Hono<ApiEnv>();
app.post("/v1/admin-sales/email/provider-events", (c) =>
postAdminEmailProviderEvent(c, { webhookSecret: secret, record })
);
return { app, record };
}
describe("admin email provider event API", () => {
it("authenticates a normalized event and binds it to the admin owner", async () => {
const now = new Date();
const body = JSON.stringify({
adminUserId: "admin-1",
scheduledEmailId: "scheduled-1",
type: "bounced",
eventId: "provider-event-1",
occurredAt: now.toISOString(),
recipient: "buyer@example.com",
});
const { app, record } = buildApp();
const response = await app.request("/v1/admin-sales/email/provider-events", {
method: "POST",
body,
headers: {
"content-type": "application/json",
"x-hivegrid-timestamp": String(now.getTime()),
"x-hivegrid-signature": signAdminEmailProviderEvent({
body,
timestamp: String(now.getTime()),
secret,
}),
},
});
expect(response.status).toBe(201);
await expect(response.json()).resolves.toEqual({
accepted: true,
status: "recorded",
});
expect(record).toHaveBeenCalledWith(
expect.objectContaining({
adminUserId: "admin-1",
scheduledEmailId: "scheduled-1",
type: "bounced",
eventKey: "provider-event-1",
})
);
});
it("rejects unsigned input before any database access", async () => {
const { app, record } = buildApp();
const response = await app.request("/v1/admin-sales/email/provider-events", {
method: "POST",
body: "{}",
headers: {
"content-type": "application/json",
"x-hivegrid-timestamp": String(Date.now()),
},
});
expect(response.status).toBe(401);
expect(record).not.toHaveBeenCalled();
});
it("rejects an authenticated but invalid provider payload as a bad request", async () => {
const now = new Date();
const body = JSON.stringify({
adminUserId: "admin-1",
scheduledEmailId: "scheduled-1",
type: "opened",
eventId: "provider-event-1",
occurredAt: now.toISOString(),
});
const { app, record } = buildApp();
const response = await app.request("/v1/admin-sales/email/provider-events", {
method: "POST",
body,
headers: {
"content-type": "application/json",
"x-hivegrid-timestamp": String(now.getTime()),
"x-hivegrid-signature": signAdminEmailProviderEvent({
body,
timestamp: String(now.getTime()),
secret,
}),
},
});
expect(response.status).toBe(400);
await expect(response.json()).resolves.toMatchObject({
error: { code: "invalid_request" },
});
expect(record).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,222 @@
import {
decideAdminEmailMatch,
verifyAdminBccCapability,
} from "@hivegrid/integrations";
import { verifyAdminEmailProviderEvent } from "@hivegrid/integrations/admin-email-provider-events";
import { Hono, type Context } from "hono";
import {
getApiAppDependencies,
type ApiAppDependencies,
} from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { getApiRuntimeConfig } from "../config.js";
import { apiError } from "../middleware/error-envelope.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { verifyMailjetWebhookAuth } from "../webhooks/mailjet-webhook-auth.js";
import { parseInboundEmailPayload } from "./inbound-email-payload.js";
export function registerAdminEmailRoutes(app: Hono<ApiEnv>) {
app.post("/v1/admin-sales/email/provider-events", (c) =>
postAdminEmailProviderEvent(c, {
webhookSecret:
getApiRuntimeConfig().adminEmail?.eventWebhookSecret ?? "",
record: getApiAppDependencies().recordAdminEmailEvent,
})
);
app.post("/v1/admin-sales/email/bcc-inbound", (c) =>
postAdminEmailBccInbound(c, {
webhookSecret: getApiRuntimeConfig().mailjet.webhookSecret,
capabilitySecret:
getApiRuntimeConfig().adminEmail?.bccCapabilitySecret ?? "",
inboundDomain:
getApiRuntimeConfig().adminEmail?.bccInboundDomain ?? "",
candidatesFor:
getApiAppDependencies().findAdminEmailMatchCandidates,
ingest: getApiAppDependencies().ingestAdminBccEmail,
})
);
}
export async function postAdminEmailBccInbound(
c: Context<ApiEnv>,
dependencies: {
readonly webhookSecret: string | undefined;
readonly capabilitySecret: string;
readonly inboundDomain: string;
readonly candidatesFor: ApiAppDependencies["findAdminEmailMatchCandidates"];
readonly ingest: ApiAppDependencies["ingestAdminBccEmail"];
}
) {
const providerAuth = verifyMailjetWebhookAuth({
secret: dependencies.webhookSecret,
headers: c.req.header(),
});
if (!providerAuth.ok) {
return apiError(
c,
providerAuth.reason === "missing-secret" ? 503 : 401,
providerAuth.reason === "missing-secret"
? "dependency_unavailable"
: "invalid_webhook_signature",
providerAuth.reason === "missing-secret"
? "Admin email BCC ingestion is not configured."
: "Admin email BCC provider authentication failed."
);
}
if (
dependencies.capabilitySecret.length < 32 ||
!dependencies.inboundDomain
) {
return apiError(
c,
503,
"dependency_unavailable",
"Admin email BCC capability verification is not configured."
);
}
const rawBody = await c.req.raw.text();
const payload = parseInboundEmailPayload(rawBody);
if (!payload.ok) {
return apiError(c, 400, "invalid_request", payload.error);
}
const capabilities = payload.value.recipientEmails.flatMap((address) => {
const capability = verifyAdminBccCapability({
address,
inboundDomain: dependencies.inboundDomain,
secret: dependencies.capabilitySecret,
});
return capability ? [capability] : [];
});
if (capabilities.length !== 1) {
return c.json(
{
accepted: true,
status: "ignored",
reason:
capabilities.length === 0
? "unknown-recipient"
: "ambiguous-recipient",
},
202
);
}
const capability = capabilities[0]!;
const originalRecipients = payload.value.originalRecipientEmails.filter(
(address) =>
!verifyAdminBccCapability({
address,
inboundDomain: dependencies.inboundDomain,
secret: dependencies.capabilitySecret,
})
);
if (originalRecipients.length === 0) {
return c.json(
{
accepted: true,
status: "ignored",
reason: "counterpart-required",
},
202
);
}
return runWithVerifiedApiRlsContext(
{ userId: capability.adminUserId },
async () => {
const candidates = await dependencies.candidatesFor(
originalRecipients[0]!.trim().toLowerCase()
);
const match = decideAdminEmailMatch({
message: {
direction: "outbound",
from: { address: payload.value.fromEmail },
to: originalRecipients.map((address) => ({ address })),
subject: payload.value.subject,
isNewsletter: false,
},
mailboxAddresses: [payload.value.fromEmail],
candidates,
});
const result = await dependencies.ingest({
adminUserId: capability.adminUserId,
localPartHash: capability.localPartHash,
providerMessageId: payload.value.messageId,
internetMessageId: payload.value.messageId,
fromAddress: payload.value.fromEmail,
toAddresses: originalRecipients,
subject: payload.value.subject,
bodyText: payload.value.message,
bodyHtml: payload.value.htmlMessage,
occurredAt: payload.value.occurredAt ?? new Date(),
match,
});
return c.json(
{
accepted: true,
status: result.status,
...(result.status === "created"
? { messageId: result.messageId }
: result.status === "duplicate"
? { messageId: result.messageId }
: { reason: result.reason }),
},
result.status === "created" ? 201 : 202
);
}
);
}
export async function postAdminEmailProviderEvent(
c: Context<ApiEnv>,
dependencies: {
readonly webhookSecret: string;
readonly record: ApiAppDependencies["recordAdminEmailEvent"];
}
) {
const body = await c.req.raw.text();
const verified = verifyAdminEmailProviderEvent({
body,
timestamp: c.req.header("x-hivegrid-timestamp"),
signature: c.req.header("x-hivegrid-signature"),
secret: dependencies.webhookSecret,
});
if (!verified.ok) {
const unavailable = verified.reason === "not_configured";
const invalidPayload = verified.reason === "invalid_payload";
return apiError(
c,
unavailable ? 503 : invalidPayload ? 400 : 401,
unavailable
? "dependency_unavailable"
: invalidPayload
? "invalid_request"
: "invalid_webhook_signature",
unavailable
? "Admin email provider events are not configured."
: invalidPayload
? "Admin email provider event payload is invalid."
: "Admin email provider event authentication failed."
);
}
const result = await runWithVerifiedApiRlsContext(
{ userId: verified.event.adminUserId },
() =>
dependencies.record({
adminUserId: verified.event.adminUserId,
scheduledEmailId: verified.event.scheduledEmailId,
type: verified.event.type,
eventKey: verified.event.eventId,
occurredAt: verified.event.occurredAt,
recipient: verified.event.recipient,
metadata: verified.event.metadata,
})
);
return c.json(
{
accepted: true,
status: result.status,
...(result.status === "ignored" ? { reason: result.reason } : {}),
},
result.status === "recorded" ? 201 : 202
);
}
@@ -1,13 +1,19 @@
import { Hono, type Context } from "hono";
import { runWithIsolatedPlatformAnalyticsRlsContext } from "@hivegrid/db/rls-context.server";
import { getCachedPublicAnalyticsOverview } from "../analytics-overview-cache.js";
import { defaultAnalyticsPeriod, getApiAppDependencies, isAnalyticsPeriod } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { authenticateServiceRequest } from "../auth.js";
import { authenticateServiceRequest, isValidServiceToken } from "../auth.js";
import { getApiRuntimeConfig } from "../config.js";
import { apiError } from "../middleware/error-envelope.js";
import { applyPublicIngressRateLimitHeaders, checkPublicIngressRateLimit } from "../public-ingress-rate-limit.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { parseAnalyticsEventPayload, parseAnalyticsPageViewPayload } from "../validation/request-schemas.js";
import { readJsonBody } from "./shared.js";
const analyticsIgnorePagesCacheTtlMs = 5_000;
const OPERATOR_USER_ID_HEADER = "x-hivegrid-operator-user-id";
type AnalyticsDependencies = ReturnType<typeof getApiAppDependencies>;
@@ -33,7 +39,11 @@ async function getCachedAnalyticsIgnoredPages(dependencies: AnalyticsDependencie
}
const settings = await dependencies.getAnalyticsSettings();
const ignoredPages = settings?.ignorePages?.split(",").map((item) => item.trim()).filter(Boolean) ?? [];
const ignoredPages =
settings?.ignorePages
?.split(",")
.map((item) => item.trim())
.filter(Boolean) ?? [];
analyticsIgnorePagesCache = {
dependencies,
expiresAt: now + analyticsIgnorePagesCacheTtlMs,
@@ -52,7 +62,7 @@ function validateAnalyticsTokenRequest(c: Context<ApiEnv>) {
}
const token = c.req.header("x-analytics-token");
if (token !== analyticsToken) {
if (!token || !isValidServiceToken(token, analyticsToken)) {
return apiError(c, 401, "unauthorized", "Invalid analytics token.");
}
return null;
@@ -64,35 +74,43 @@ async function postAnalyticsEventRequest(c: Context<ApiEnv>) {
return unauthorized;
}
const rateLimited = await enforceAnalyticsIngressRateLimit(c);
if (rateLimited) {
return rateLimited;
}
const body = await readJsonBody(c.req.raw);
const payload = parseAnalyticsEventPayload(body);
if (!payload.ok) {
return apiError(c, 400, "invalid_request", payload.error.message, { params: payload.error.params });
}
const visitorRateLimited = await enforceAnalyticsVisitorRateLimit(c, payload.value.analytics.userAnalyticsId);
if (visitorRateLimited) {
return visitorRateLimited;
}
try {
const dependencies = getApiAppDependencies();
const analyticsId = payload.value.analytics.userAnalyticsId;
const visitor = await dependencies.getOrCreateAnalyticsUniqueVisitor({
cookie: analyticsId,
fromUrl: payload.value.url,
fromRoute: payload.value.route,
analytics: payload.value.analytics,
});
await runWithIsolatedPlatformAnalyticsRlsContext(async () => {
const analytics = toAnonymousPlatformAnalytics(payload.value.analytics);
const visitor = await dependencies.getOrCreateAnalyticsUniqueVisitor({
cookie: analytics.userAnalyticsId,
fromUrl: payload.value.url,
fromRoute: payload.value.route,
analytics,
});
const featureFlag = payload.value.category === "featureFlag" ? await dependencies.findFeatureFlagByName(payload.value.action) : null;
await dependencies.createAnalyticsEvent({
uniqueVisitorId: visitor.id,
action: payload.value.action,
category: payload.value.category,
label: payload.value.label,
value: payload.value.value,
url: payload.value.url,
route: payload.value.route,
featureFlagId: featureFlag?.id,
portalId: payload.value.analytics.portalId ?? null,
portalUserId: payload.value.analytics.portalUserId ?? null,
await dependencies.createAnalyticsEvent({
uniqueVisitorId: visitor.id,
action: payload.value.action,
category: payload.value.category,
label: payload.value.label,
value: payload.value.value,
url: payload.value.url,
route: payload.value.route,
portalId: null,
portalUserId: null,
});
});
return c.json({ success: true }, 201);
@@ -107,34 +125,47 @@ async function postAnalyticsPageViewRequest(c: Context<ApiEnv>) {
return unauthorized;
}
const rateLimited = await enforceAnalyticsIngressRateLimit(c);
if (rateLimited) {
return rateLimited;
}
const body = await readJsonBody(c.req.raw);
const payload = parseAnalyticsPageViewPayload(body);
if (!payload.ok) {
return apiError(c, 400, "invalid_request", payload.error.message, { params: payload.error.params });
}
const visitorRateLimited = await enforceAnalyticsVisitorRateLimit(c, payload.value.analytics.userAnalyticsId);
if (visitorRateLimited) {
return visitorRateLimited;
}
try {
const dependencies = getApiAppDependencies();
const ignoredPages = await getCachedAnalyticsIgnoredPages(dependencies);
if (ignoredPages.some((ignoredPage) => payload.value.url.includes(ignoredPage))) {
return c.body(null, 204);
}
const ignored = await runWithIsolatedPlatformAnalyticsRlsContext(async () => {
const ignoredPages = await getCachedAnalyticsIgnoredPages(dependencies);
if (ignoredPages.some((ignoredPage) => payload.value.url.includes(ignoredPage))) {
return true;
}
const analyticsId = payload.value.analytics.userAnalyticsId;
const visitor = await dependencies.getOrCreateAnalyticsUniqueVisitor({
cookie: analyticsId,
fromUrl: payload.value.url,
fromRoute: payload.value.route,
analytics: payload.value.analytics,
});
await dependencies.updateAnalyticsUniqueVisitorSource(visitor, payload.value.analytics);
await dependencies.createAnalyticsPageView({
uniqueVisitorId: visitor.id,
url: payload.value.url,
route: payload.value.route,
portalId: payload.value.analytics.portalId ?? null,
portalUserId: payload.value.analytics.portalUserId ?? null,
const analytics = toAnonymousPlatformAnalytics(payload.value.analytics);
const visitor = await dependencies.getOrCreateAnalyticsUniqueVisitor({
cookie: analytics.userAnalyticsId,
fromUrl: payload.value.url,
fromRoute: payload.value.route,
analytics,
});
await dependencies.updateAnalyticsUniqueVisitorSource(visitor, analytics);
await dependencies.createAnalyticsPageView({
uniqueVisitorId: visitor.id,
url: payload.value.url,
route: payload.value.route,
portalId: null,
portalUserId: null,
});
return false;
});
if (ignored) return c.body(null, 204);
return c.json({ success: true }, 201);
} catch {
@@ -143,15 +174,9 @@ async function postAnalyticsPageViewRequest(c: Context<ApiEnv>) {
}
async function getPublicAnalyticsRequest(c: Context<ApiEnv>) {
const unauthorized = validateAnalyticsTokenRequest(c);
if (unauthorized) {
return unauthorized;
}
const dependencies = getApiAppDependencies();
const settings = await dependencies.getAnalyticsSettings();
if (!settings?.public) {
return apiError(c, 403, "forbidden", "Public analytics overview is disabled.");
const rateLimited = await enforceAnalyticsIngressRateLimit(c);
if (rateLimited) {
return rateLimited;
}
const periodParam = c.req.query("period") ?? defaultAnalyticsPeriod;
@@ -160,12 +185,42 @@ async function getPublicAnalyticsRequest(c: Context<ApiEnv>) {
}
try {
return c.json(await dependencies.getAnalyticsOverview({ period: periodParam, portalId: null }));
const dependencies = getApiAppDependencies();
return await runWithIsolatedPlatformAnalyticsRlsContext(async () => {
const settings = await dependencies.getAnalyticsSettings();
if (!settings?.public) {
return apiError(c, 403, "forbidden", "Public analytics overview is disabled.");
}
return c.json(await getCachedPublicAnalyticsOverview({ dependencies, scope: "platform-global", period: periodParam }));
});
} catch {
return apiError(c, 500, "analytics_overview_failed", "Analytics overview could not be loaded.");
}
}
async function enforceAnalyticsIngressRateLimit(c: Context<ApiEnv>): Promise<Response | null> {
const clientIp = getTrustedClientIp(c.req.raw) || c.env?.incoming?.socket.remoteAddress?.trim() || "unknown";
const result = await checkPublicIngressRateLimit("analytics-ip", clientIp);
applyPublicIngressRateLimitHeaders((name, value) => c.header(name, value), result);
if (result.allowed) {
return null;
}
return result.unavailable
? apiError(c, 503, "rate_limit_unavailable", "Analytics ingestion is temporarily unavailable.")
: apiError(c, 429, "rate_limited", "Too many analytics requests. Try again later.");
}
async function enforceAnalyticsVisitorRateLimit(c: Context<ApiEnv>, visitorId: string): Promise<Response | null> {
const result = await checkPublicIngressRateLimit("analytics-visitor", visitorId);
applyPublicIngressRateLimitHeaders((name, value) => c.header(name, value), result);
if (result.allowed) {
return null;
}
return result.unavailable
? apiError(c, 503, "rate_limit_unavailable", "Analytics ingestion is temporarily unavailable.")
: apiError(c, 429, "rate_limited", "Too many analytics requests. Try again later.");
}
async function getAdminAnalyticsRequest(c: Context<ApiEnv>) {
const principal = authenticateServiceRequest(c.req.raw, getApiRuntimeConfig());
if (!principal) {
@@ -177,5 +232,66 @@ async function getAdminAnalyticsRequest(c: Context<ApiEnv>) {
return apiError(c, 400, "invalid_period", "Invalid period.", { params: { period: periodParam } });
}
return c.json(await getApiAppDependencies().getAnalyticsOverview({ period: periodParam, portalId: c.req.query("portalId") }));
const operatorUserId = readBoundedIdentifier(c.req.header(OPERATOR_USER_ID_HEADER));
if (!operatorUserId) {
return operatorIdentityRequired(c);
}
const rawPortalId = c.req.query("portalId");
const rawTenantId = c.req.query("tenantId");
const portalId = rawPortalId === undefined ? null : readBoundedIdentifier(rawPortalId);
const tenantId = rawTenantId === undefined ? null : readBoundedIdentifier(rawTenantId);
if ((rawPortalId !== undefined && !portalId) || (rawTenantId !== undefined && !tenantId) || Boolean(portalId) !== Boolean(tenantId)) {
return apiError(c, 400, "invalid_request", "portalId and tenantId must be provided together as valid identifiers.");
}
const dependencies = getApiAppDependencies();
return runWithVerifiedApiRlsContext({ userId: operatorUserId }, async () => {
const operator = await dependencies.findPlatformOperatorByUserId(operatorUserId);
if (!operator || operator.userId !== operatorUserId) {
return operatorIdentityRequired(c);
}
try {
if (!portalId || !tenantId) {
return await runWithIsolatedPlatformAnalyticsRlsContext(async () =>
c.json(await dependencies.getAnalyticsOverview({ period: periodParam, portalId: null }))
);
}
return await runWithVerifiedApiRlsContext({ tenantId }, async () => {
const portal = await dependencies.findAnalyticsPortalForTenant({ portalId, tenantId });
if (!portal || portal.id !== portalId || portal.tenantId !== tenantId) {
return apiError(c, 404, "analytics_portal_not_found", "Analytics portal was not found for the tenant scope.");
}
return c.json(await dependencies.getAnalyticsOverview({ period: periodParam, portalId: portal.id }));
});
} catch {
return apiError(c, 500, "analytics_overview_failed", "Analytics overview could not be loaded.");
}
});
}
function toAnonymousPlatformAnalytics(analytics: {
userAnalyticsId: string;
userAgent?: Parameters<AnalyticsDependencies["getOrCreateAnalyticsUniqueVisitor"]>[0]["analytics"]["userAgent"];
referrer?: Parameters<AnalyticsDependencies["getOrCreateAnalyticsUniqueVisitor"]>[0]["analytics"]["referrer"];
region?: Parameters<AnalyticsDependencies["getOrCreateAnalyticsUniqueVisitor"]>[0]["analytics"]["region"];
}) {
return {
...analytics,
userId: null,
portalId: null,
portalUserId: null,
} as const;
}
function readBoundedIdentifier(value: string | undefined): string | null {
const normalized = value?.trim();
if (!normalized || normalized.length > 191 || normalized.includes("\u0000")) return null;
return normalized;
}
function operatorIdentityRequired(c: Context<ApiEnv>) {
return apiError(c, 403, "operator_identity_required", "A verified platform operator identity is required.");
}
@@ -0,0 +1,33 @@
import { describe, expect, it } from "vitest";
import { apiDocsLocales, getApiDocsCopy, resolveApiDocsLocale } from "./api-docs-i18n.js";
describe("API docs localization", () => {
it("defaults to the product locale", () => {
expect(resolveApiDocsLocale(undefined)).toBe("de");
});
it("honors supported browser languages and quality weights", () => {
expect(resolveApiDocsLocale("en-GB,en;q=0.9,de;q=0.8")).toBe("en");
expect(resolveApiDocsLocale("en;q=0.5,de-DE;q=0.9")).toBe("de");
expect(resolveApiDocsLocale("uk-UA,pl;q=0.9", apiDocsLocales)).toBe("uk");
expect(resolveApiDocsLocale("hu-HU,ru;q=0.9", apiDocsLocales)).toBe("hu");
});
it("ignores catalog-ready languages that are not runtime-enabled", () => {
expect(resolveApiDocsLocale("pl-PL,ru;q=0.9", ["de", "en"])).toBe("de");
});
it("falls back safely for unsupported languages", () => {
expect(resolveApiDocsLocale("fr-FR,es;q=0.8")).toBe("de");
});
it("keeps every supported catalog complete", () => {
const referenceKeys = Object.keys(getApiDocsCopy("de").copy).sort();
for (const locale of apiDocsLocales) {
const localized = getApiDocsCopy(locale, apiDocsLocales).copy;
expect(Object.keys(localized).sort()).toEqual(referenceKeys);
expect(Object.values(localized).every((value) => value.trim().length > 0)).toBe(true);
}
});
});
@@ -0,0 +1,202 @@
import { defaultEnabledLocales, normalizeLocaleCandidate, type SupportedLocale } from "@hivegrid/i18n";
export const apiDocsLocales = ["de", "en", "pl", "ru", "uk", "hu"] as const;
export type ApiDocsLocale = (typeof apiDocsLocales)[number];
export type ApiDocsCopy = {
readonly pageTitle: string;
readonly heading: string;
readonly description: string;
readonly operationsLabel: string;
readonly loadingSpec: string;
readonly rawSpec: string;
readonly operationFallback: string;
readonly noDescription: string;
readonly parameters: string;
readonly noParameters: string;
readonly responses: string;
readonly noResponses: string;
readonly tryRequest: string;
readonly apiKeyLabel: string;
readonly apiKeyPlaceholder: string;
readonly queryLabel: string;
readonly queryPlaceholder: string;
readonly sendRequest: string;
readonly responsePlaceholder: string;
readonly loading: string;
};
const API_DOCS_COPY: Readonly<Record<ApiDocsLocale, ApiDocsCopy>> = {
de: {
pageTitle: "API-Dokumentation",
heading: "API-Dokumentation",
description: "OpenAPI-3.1-Explorer für den kanonischen API-Host.",
operationsLabel: "API-Vorgänge",
loadingSpec: "/v1/openapi.json wird geladen …",
rawSpec: "OpenAPI-JSON (Rohdaten)",
operationFallback: "Vorgang",
noDescription: "Keine Beschreibung vorhanden.",
parameters: "Parameter",
noParameters: "Keine Parameter.",
responses: "Antworten",
noResponses: "Keine Antworten dokumentiert.",
tryRequest: "Anfrage testen",
apiKeyLabel: "API-Schlüssel",
apiKeyPlaceholder: "API-Schlüssel des Kontos einfügen",
queryLabel: "Abfrageparameter",
queryPlaceholder: "limit=10&fields=id,name",
sendRequest: "Anfrage senden",
responsePlaceholder: "Die Antwort erscheint hier.",
loading: "Wird geladen …",
},
en: {
pageTitle: "API Documentation",
heading: "API Documentation",
description: "OpenAPI 3.1 explorer for the canonical API host.",
operationsLabel: "API operations",
loadingSpec: "Loading /v1/openapi.json…",
rawSpec: "Raw OpenAPI JSON",
operationFallback: "Operation",
noDescription: "No description available.",
parameters: "Parameters",
noParameters: "No parameters.",
responses: "Responses",
noResponses: "No documented responses.",
tryRequest: "Try request",
apiKeyLabel: "API key",
apiKeyPlaceholder: "Paste account API key",
queryLabel: "Query string",
queryPlaceholder: "limit=10&fields=id,name",
sendRequest: "Send request",
responsePlaceholder: "The response appears here.",
loading: "Loading…",
},
pl: {
pageTitle: "Dokumentacja API",
heading: "Dokumentacja API",
description: "Eksplorator OpenAPI 3.1 dla kanonicznego hosta API.",
operationsLabel: "Operacje API",
loadingSpec: "Ładowanie /v1/openapi.json…",
rawSpec: "Surowy JSON OpenAPI",
operationFallback: "Operacja",
noDescription: "Brak opisu.",
parameters: "Parametry",
noParameters: "Brak parametrów.",
responses: "Odpowiedzi",
noResponses: "Brak udokumentowanych odpowiedzi.",
tryRequest: "Wypróbuj żądanie",
apiKeyLabel: "Klucz API",
apiKeyPlaceholder: "Klucz API konta",
queryLabel: "Ciąg zapytania",
queryPlaceholder: "limit=10&fields=id,name",
sendRequest: "Wyślij żądanie",
responsePlaceholder: "Odpowiedź pojawi się tutaj.",
loading: "Ładowanie…",
},
ru: {
pageTitle: "Документация API",
heading: "Документация API",
description: "Обозреватель OpenAPI 3.1 для канонического хоста API.",
operationsLabel: "Операции API",
loadingSpec: "Загрузка /v1/openapi.json…",
rawSpec: "Исходный JSON OpenAPI",
operationFallback: "Операция",
noDescription: "Описание отсутствует.",
parameters: "Параметры",
noParameters: "Параметры отсутствуют.",
responses: "Ответы",
noResponses: "Документированные ответы отсутствуют.",
tryRequest: "Проверить запрос",
apiKeyLabel: "Ключ API",
apiKeyPlaceholder: "Ключ API учётной записи",
queryLabel: "Строка запроса",
queryPlaceholder: "limit=10&fields=id,name",
sendRequest: "Отправить запрос",
responsePlaceholder: "Ответ появится здесь.",
loading: "Загрузка…",
},
uk: {
pageTitle: "Документація API",
heading: "Документація API",
description: "Оглядач OpenAPI 3.1 для канонічного хоста API.",
operationsLabel: "Операції API",
loadingSpec: "Завантаження /v1/openapi.json…",
rawSpec: "Вихідний JSON OpenAPI",
operationFallback: "Операція",
noDescription: "Опис відсутній.",
parameters: "Параметри",
noParameters: "Параметри відсутні.",
responses: "Відповіді",
noResponses: "Документовані відповіді відсутні.",
tryRequest: "Перевірити запит",
apiKeyLabel: "Ключ API",
apiKeyPlaceholder: "Ключ API облікового запису",
queryLabel: "Рядок запиту",
queryPlaceholder: "limit=10&fields=id,name",
sendRequest: "Надіслати запит",
responsePlaceholder: "Відповідь з’явиться тут.",
loading: "Завантаження…",
},
hu: {
pageTitle: "API-dokumentáció",
heading: "API-dokumentáció",
description: "OpenAPI 3.1-böngésző a kanonikus API-gazdagéphez.",
operationsLabel: "API-műveletek",
loadingSpec: "A /v1/openapi.json betöltése…",
rawSpec: "Nyers OpenAPI JSON",
operationFallback: "Művelet",
noDescription: "Nincs leírás.",
parameters: "Paraméterek",
noParameters: "Nincsenek paraméterek.",
responses: "Válaszok",
noResponses: "Nincsenek dokumentált válaszok.",
tryRequest: "Kérés kipróbálása",
apiKeyLabel: "API-kulcs",
apiKeyPlaceholder: "Fiók API-kulcsa",
queryLabel: "Lekérdezési karakterlánc",
queryPlaceholder: "limit=10&fields=id,name",
sendRequest: "Kérés küldése",
responsePlaceholder: "A válasz itt jelenik meg.",
loading: "Betöltés…",
},
};
export function resolveApiDocsLocale(
acceptLanguage: string | undefined,
enabledLocales: readonly SupportedLocale[] = defaultEnabledLocales
): ApiDocsLocale {
if (!acceptLanguage?.trim()) return "de";
const preferences = acceptLanguage
.split(",")
.map((entry, index) => {
const [rawTag, ...parameters] = entry.trim().split(";");
const qualityParameter = parameters.find((parameter) => parameter.trim().startsWith("q="));
const quality = qualityParameter ? Number(qualityParameter.trim().slice(2)) : 1;
return {
tag: rawTag?.toLowerCase() ?? "",
quality: Number.isFinite(quality) ? quality : 0,
index,
};
})
.filter((entry) => entry.quality > 0)
.sort((left, right) => right.quality - left.quality || left.index - right.index);
for (const preference of preferences) {
const locale = normalizeLocaleCandidate(preference.tag);
if (locale && enabledLocales.includes(locale)) return locale;
}
return "de";
}
export function getApiDocsCopy(
acceptLanguage: string | undefined,
enabledLocales: readonly SupportedLocale[] = defaultEnabledLocales
): {
readonly locale: ApiDocsLocale;
readonly copy: ApiDocsCopy;
} {
const locale = resolveApiDocsLocale(acceptLanguage, enabledLocales);
return { locale, copy: API_DOCS_COPY[locale] };
}
@@ -1,5 +1,4 @@
import { Hono } from "hono";
import jwt from "jsonwebtoken";
import { getApiAppDependencies } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { authenticateServiceRequest, extractApiKeyFromRequest, extractBearerToken, isValidServiceToken } from "../auth.js";
@@ -7,20 +6,11 @@ import { serializeApiAuthCookie, serializeExpiredApiAuthCookie } from "../auth/c
import { getApiRuntimeConfig } from "../config.js";
import { apiError } from "../middleware/error-envelope.js";
import { parseApiKeyValidationPayload, parseLoginCredentialsPayload } from "../validation/request-schemas.js";
import {
createLoginRateLimitRequest,
createLoginRateLimitResponse,
getApiSessionIdFromJwt,
getBearerToken,
getLegacyUserIdFromJwt,
readJsonBody,
} from "./shared.js";
// A valid bcrypt hash compared against when the account does not exist or has
// no password, so the response time of a failed login is independent of whether
// the email maps to a real password account (prevents account enumeration via
// timing). Mirrors the web AuthService DUMMY_PASSWORD_HASH.
const DUMMY_PASSWORD_HASH = "$2a$10$7EqJtq98hPqEX7fNZaFWoOhi8VfIf6z9SjG8/aYx8vvjE5LiE3D0C";
import { createApiSessionToken, verifyApiSessionToken } from "../auth/session/session-token.js";
import { createLoginRateLimitRequest, createLoginRateLimitResponse, getBearerToken, readJsonBody } from "./shared.js";
import { DUMMY_PASSWORD_HASH, hashCurrentPassword, isLegacyBcryptHash } from "../auth/password.js";
import { applyPublicIngressRateLimitHeaders, checkPublicIngressRateLimit } from "../public-ingress-rate-limit.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
const AUTH_INVALID_CREDENTIALS_MESSAGE = "Authentication failed.";
const AUTH_INVALID_TOKEN_MESSAGE = "Authentication token is invalid or expired.";
@@ -83,10 +73,25 @@ export function registerAuthRoutes(app: Hono<ApiEnv>) {
}
await dependencies.recordSuccessfulLogin({ account: email });
await dependencies.recordLegacyLogin(user.id);
const config = getApiRuntimeConfig();
const session = dependencies.createApiSession(user.id);
const token = jwt.sign({ userId: user.id, sessionId: session.sessionId }, config.jwtSecret!, { expiresIn: "1h" });
if (user.totpEnabledAt) {
return apiError(c, 403, "mfa_required", "This account requires the interactive MFA login flow.");
}
if (user.pendingDeletion || user.pseudonymized || user.active === false) {
return apiError(c, 403, "account_unavailable", "This account cannot start an API session.");
}
if (isLegacyBcryptHash(user.passwordHash)) {
// Best-effort compare-and-swap migration: the successful login remains
// available if persistence is temporarily unavailable, while a racing
// password change cannot be overwritten with the stale credential.
const upgradedHash = await hashCurrentPassword(password);
await dependencies.upgradeLegacyPasswordHash(user.id, user.passwordHash, upgradedHash).catch(() => false);
}
await dependencies.recordLegacyLogin(user.id);
const session = await dependencies.createApiSession(user.id);
const token = createApiSessionToken({ userId: user.id, sessionId: session.sessionId, secret: config.jwtSecret! });
const response = c.json({ token, user: { id: user.id, email: user.email } });
response.headers.append("Set-Cookie", serializeApiAuthCookie(token, config));
return response;
@@ -103,14 +108,14 @@ export function registerAuthRoutes(app: Hono<ApiEnv>) {
}
const dependencies = getApiAppDependencies();
const decoded = jwt.verify(token, getApiRuntimeConfig().jwtSecret!);
const userId = getLegacyUserIdFromJwt(decoded);
const sessionId = getApiSessionIdFromJwt(decoded);
if (!userId || !sessionId) {
const decoded = verifyApiSessionToken(token, getApiRuntimeConfig().jwtSecret!);
if (!decoded) {
return apiError(c, 401, "invalid_token", AUTH_INVALID_TOKEN_MESSAGE);
}
const userId = decoded.userId;
const sessionId = decoded.sessionId;
const session = dependencies.getActiveApiSession(sessionId);
const session = await dependencies.getActiveApiSession(sessionId);
if (!session || session.userId !== userId) {
return apiError(c, 401, "invalid_token", AUTH_INVALID_TOKEN_MESSAGE);
}
@@ -119,14 +124,18 @@ export function registerAuthRoutes(app: Hono<ApiEnv>) {
if (!user) {
return apiError(c, 400, "invalid_credentials", AUTH_INVALID_CREDENTIALS_MESSAGE);
}
if (user.totpEnabledAt || user.pendingDeletion || user.pseudonymized || user.active === false) {
await dependencies.revokeApiSession(sessionId, userId);
return apiError(c, 401, "invalid_token", AUTH_INVALID_TOKEN_MESSAGE);
}
const rotation = dependencies.rotateApiSession(sessionId);
const rotation = await dependencies.rotateApiSession(sessionId, userId);
if (!rotation.rotated || rotation.session.userId !== userId) {
return apiError(c, 401, "invalid_token", AUTH_INVALID_TOKEN_MESSAGE);
}
const config = getApiRuntimeConfig();
const newToken = jwt.sign({ userId, sessionId: rotation.session.sessionId }, config.jwtSecret!, { expiresIn: "1h" });
const newToken = createApiSessionToken({ userId, sessionId: rotation.session.sessionId, secret: config.jwtSecret! });
const response = c.json({ token: newToken, user: { id: user.id, email: user.email } });
response.headers.append("Set-Cookie", serializeApiAuthCookie(newToken, config));
return response;
@@ -135,7 +144,7 @@ export function registerAuthRoutes(app: Hono<ApiEnv>) {
}
});
app.post("/v1/auth/logout", (c) => {
app.post("/v1/auth/logout", async (c) => {
const config = getApiRuntimeConfig();
try {
const token = getBearerToken(c.req.raw);
@@ -144,19 +153,22 @@ export function registerAuthRoutes(app: Hono<ApiEnv>) {
}
const dependencies = getApiAppDependencies();
const decoded = jwt.verify(token, config.jwtSecret!);
const userId = getLegacyUserIdFromJwt(decoded);
const sessionId = getApiSessionIdFromJwt(decoded);
if (!userId || !sessionId) {
const decoded = verifyApiSessionToken(token, config.jwtSecret!);
if (!decoded) {
return apiError(c, 401, "invalid_token", AUTH_INVALID_TOKEN_MESSAGE);
}
const userId = decoded.userId;
const sessionId = decoded.sessionId;
const session = dependencies.getActiveApiSession(sessionId);
const session = await dependencies.getActiveApiSession(sessionId);
if (!session || session.userId !== userId) {
return apiError(c, 401, "invalid_token", AUTH_INVALID_TOKEN_MESSAGE);
}
dependencies.revokeApiSession(sessionId);
const revoked = await dependencies.revokeApiSession(sessionId, userId);
if (!revoked) {
return apiError(c, 401, "invalid_token", AUTH_INVALID_TOKEN_MESSAGE);
}
const response = c.json({ success: true });
response.headers.append("Set-Cookie", serializeExpiredApiAuthCookie(config));
return response;
@@ -166,6 +178,15 @@ export function registerAuthRoutes(app: Hono<ApiEnv>) {
});
app.post("/v1/api-keys/validate", async (c) => {
const clientIp = getTrustedClientIp(c.req.raw) || c.env?.incoming?.socket.remoteAddress?.trim() || "unknown";
const rateLimit = await checkPublicIngressRateLimit("api-key-validation-ip", clientIp);
applyPublicIngressRateLimitHeaders((name, value) => c.header(name, value), rateLimit);
if (!rateLimit.allowed) {
return rateLimit.unavailable
? apiError(c, 503, "rate_limit_unavailable", "API-key validation is temporarily unavailable.")
: apiError(c, 429, "rate_limited", "Too many API-key validation requests. Try again later.");
}
const body = await readJsonBody(c.req.raw);
const payload = parseApiKeyValidationPayload(body);
if (body !== undefined && !payload.ok) {
@@ -180,7 +201,9 @@ export function registerAuthRoutes(app: Hono<ApiEnv>) {
const apiKey = extractApiKeyFromRequest(c.req.raw, payload.ok ? payload.value : undefined);
if (!apiKey) {
return apiError(c, 400, "api_key_required", API_KEY_REQUIRED_MESSAGE, { params: { credential: "api_key", sources: "body.apiKey,x-api-key,service-bearer" } });
return apiError(c, 400, "api_key_required", API_KEY_REQUIRED_MESSAGE, {
params: { credential: "api_key", sources: "body.apiKey,x-api-key,service-bearer" },
});
}
if (isValidServiceToken(apiKey, config)) {
@@ -1,26 +1,52 @@
import { describe, expect, it, beforeEach, afterEach, vi } from "vitest";
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
import { Hono } from "hono";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { configureApiAppDependenciesForTests } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { createApiSessionToken } from "../auth/session/session-token.js";
import { resetApiRuntimeConfigForTests, setApiRuntimeConfigForTests } from "../config.js";
import { registerDevicesRoutes } from "./devices-routes.js";
import { setApiRuntimeConfigForTests, resetApiRuntimeConfigForTests } from "../config.js";
const TEST_TOKEN = "test-service-token";
const TEST_USER_ID = "u-1";
let mockStore: Map<string, { id: string; userId: string; tenantId: string | null; platform: string; token: string; pushProvider: string; appVersion: string | null; createdAt: Date; lastSeenAt: Date; revokedAt: Date | null }>;
type StoredDeviceToken = {
id: string;
userId: string;
tenantId: string | null;
platform: string;
token: string;
pushProvider: string;
appVersion: string | null;
createdAt: Date;
lastSeenAt: Date;
revokedAt: Date | null;
};
let mockStore: Map<string, StoredDeviceToken>;
let resetApiAppDependencies: () => void;
let findLegacyAuthUserById: ReturnType<typeof vi.fn>;
let revalidateWorkspaceContext: ReturnType<typeof vi.fn>;
let getActiveApiSession: ReturnType<typeof vi.fn>;
vi.mock("@hivegrid/db/device-tokens.server", () => ({
parseDevicePlatform: (value: unknown) => {
return value === "web" ? value : null;
},
parsePushProvider: (value: unknown) => {
return value === "webpush" ? value : null;
},
async registerDeviceToken(input: { userId: string; tenantId: string | null; platform: "web"; token: string; pushProvider?: "webpush"; appVersion?: string | null }) {
parseDevicePlatform: (value: unknown) => (value === "web" ? value : null),
parsePushProvider: (value: unknown) => (value === "webpush" ? value : null),
async registerDeviceToken(input: {
userId: string;
tenantId: string | null;
platform: "web";
token: string;
pushProvider?: "webpush";
appVersion?: string | null;
}) {
const provider = input.pushProvider ?? "webpush";
const now = new Date();
const existing = mockStore.get(input.token);
if (existing) {
existing.userId = input.userId;
if (existing.userId !== input.userId) {
throw new Error("token owner mismatch");
}
existing.tenantId = input.tenantId;
existing.platform = input.platform;
existing.pushProvider = provider;
@@ -44,9 +70,11 @@ vi.mock("@hivegrid/db/device-tokens.server", () => ({
mockStore.set(input.token, row);
return row;
},
async revokeDeviceToken(token: string) {
const row = mockStore.get(token);
if (!row) return null;
async revokeDeviceToken(input: { token: string; userId: string; tenantId: string | null }) {
const row = mockStore.get(input.token);
if (!row || row.userId !== input.userId || row.tenantId !== input.tenantId) {
return null;
}
row.revokedAt = new Date();
return row;
},
@@ -63,113 +91,255 @@ beforeEach(() => {
setApiRuntimeConfigForTests({
apiAccessToken: TEST_TOKEN,
jwtSecret: "jwt",
routing: { appBaseDomain: "example.com", webAppHost: "app.example.com", adminAppHost: "admin.example.com", apiHost: "api.example.com", protocol: "https" },
routing: {
appBaseDomain: "example.com",
webAppHost: "app.example.com",
adminAppHost: "admin.example.com",
apiHost: "api.example.com",
portalAppHost: "portal.example.com",
protocol: "https",
},
apiKeys: { allowLegacyPlaintextFallback: false },
} as never);
findLegacyAuthUserById = vi.fn(async (userId: string) => {
expect(getRlsExecutionContext()).toMatchObject({ userId });
return {
id: userId,
email: `${userId}@example.test`,
totpEnabledAt: null,
pendingDeletion: false,
pseudonymized: false,
active: true,
};
});
revalidateWorkspaceContext = vi.fn(async ({ tenantId, userId }: { tenantId?: string | null; userId?: string | null }) => {
expect(getRlsExecutionContext()).toMatchObject({ tenantId, userId });
return { valid: true as const, tenantId: tenantId ?? "", userId: userId ?? "", membership: {} as never };
});
getActiveApiSession = vi.fn(async (sessionId: string) => {
expect(getRlsExecutionContext()).toMatchObject({ userId: TEST_USER_ID });
return { sessionId, userId: TEST_USER_ID, createdAt: new Date() };
});
resetApiAppDependencies = configureApiAppDependenciesForTests({ findLegacyAuthUserById, revalidateWorkspaceContext, getActiveApiSession });
});
afterEach(() => {
resetApiAppDependencies();
resetApiRuntimeConfigForTests();
});
function postRegister(app: ReturnType<typeof buildApp>, body: unknown, auth: string | null = `Bearer ${TEST_TOKEN}`) {
function postRegister(
app: ReturnType<typeof buildApp>,
body: unknown,
options: { auth?: string | null; identityHeader?: string | null } = {},
) {
const auth = options.auth === undefined ? `Bearer ${createTestApiSessionToken()}` : options.auth;
return app.request("/v1/devices/register", {
method: "POST",
headers: {
"content-type": "application/json",
...(auth ? { authorization: auth } : {}),
...(options.identityHeader ? { "x-hivegrid-user-id": options.identityHeader } : {}),
},
body: JSON.stringify(body),
});
}
function postRevoke(
app: ReturnType<typeof buildApp>,
body: unknown,
options: { auth?: string | null; identityHeader?: string | null } = {},
) {
const auth = options.auth === undefined ? `Bearer ${createTestApiSessionToken()}` : options.auth;
return app.request("/v1/devices/revoke", {
method: "POST",
headers: {
"content-type": "application/json",
...(auth ? { authorization: auth } : {}),
...(options.identityHeader ? { "x-hivegrid-user-id": options.identityHeader } : {}),
},
body: JSON.stringify(body),
});
}
function createTestApiSessionToken(userId = TEST_USER_ID, sessionId = "session-1") {
return createApiSessionToken({ userId, sessionId, secret: "jwt" });
}
describe("POST /v1/devices/register", () => {
it("rejects requests without service credentials", async () => {
const app = buildApp();
const response = await postRegister(app, {}, null);
it("rejects requests without an API session JWT", async () => {
const response = await postRegister(buildApp(), {}, { auth: null });
expect(response.status).toBe(401);
});
it("rejects a service token without a user-bearing API session", async () => {
const response = await postRegister(buildApp(), { platform: "web", token: "tok-1" }, { auth: `Bearer ${TEST_TOKEN}` });
expect(response.status).toBe(401);
await expect(response.json()).resolves.toMatchObject({ error: { code: "invalid_token" } });
});
it("rejects a signed JWT whose persistent session is inactive", async () => {
getActiveApiSession.mockResolvedValueOnce(undefined);
const response = await postRegister(buildApp(), { platform: "web", token: "tok-1" });
expect(response.status).toBe(401);
});
it("rejects non-object bodies", async () => {
const app = buildApp();
const response = await app.request("/v1/devices/register", {
const response = await buildApp().request("/v1/devices/register", {
method: "POST",
headers: { "content-type": "application/json", authorization: `Bearer ${TEST_TOKEN}` },
headers: {
"content-type": "application/json",
authorization: `Bearer ${createTestApiSessionToken()}`,
},
body: "not-json",
});
expect(response.status).toBe(400);
});
it("rejects missing userId", async () => {
const app = buildApp();
const response = await postRegister(app, { platform: "web", token: "t" });
expect(response.status).toBe(400);
const json = (await response.json()) as { error: { params: { field: string } } };
expect(json.error.params.field).toBe("userId");
it("rejects body and header attempts to override the JWT owner", async () => {
const bodyOverride = await postRegister(buildApp(), { userId: "u-2", platform: "web", token: "tok-1" });
expect(bodyOverride.status).toBe(400);
await expect(bodyOverride.json()).resolves.toMatchObject({ error: { code: "device_identity_override_not_allowed" } });
const headerOverride = await postRegister(
buildApp(),
{ platform: "web", token: "tok-1" },
{ identityHeader: "u-2" },
);
expect(headerOverride.status).toBe(400);
await expect(headerOverride.json()).resolves.toMatchObject({ error: { code: "device_identity_override_not_allowed" } });
expect(mockStore).toHaveLength(0);
});
it("rejects unknown platform", async () => {
it("rejects unknown platforms and missing tokens", async () => {
const app = buildApp();
const response = await postRegister(app, { userId: "u1", platform: "wear", token: "t" });
expect(response.status).toBe(400);
expect((await postRegister(app, { platform: "wear", token: "t" })).status).toBe(400);
const missingToken = await postRegister(app, { platform: "web" });
expect(missingToken.status).toBe(400);
await expect(missingToken.json()).resolves.toMatchObject({ error: { params: { field: "token" } } });
});
it("rejects missing token", async () => {
const app = buildApp();
const response = await postRegister(app, { userId: "u1", platform: "web" });
expect(response.status).toBe(400);
const json = (await response.json()) as { error: { params: { field: string } } };
expect(json.error.params.field).toBe("token");
it("validates the JWT owner and active session inside user RLS before registering", async () => {
const response = await postRegister(buildApp(), { platform: "web", token: "tok-1", appVersion: "1.2.3" });
expect(response.status).toBe(200);
expect(getActiveApiSession).toHaveBeenCalledWith("session-1");
expect(findLegacyAuthUserById).toHaveBeenCalledWith(TEST_USER_ID);
expect(revalidateWorkspaceContext).not.toHaveBeenCalled();
await expect(response.json()).resolves.toMatchObject({
success: true,
data: { userId: TEST_USER_ID, tenantId: null, platform: "web", pushProvider: "webpush", appVersion: "1.2.3" },
});
});
it("upserts a valid registration and defaults the push provider", async () => {
const app = buildApp();
const response = await postRegister(app, {
userId: "u-1",
tenantId: "t-1",
it("rejects a JWT owner whose account no longer exists", async () => {
findLegacyAuthUserById.mockResolvedValueOnce(null);
const response = await postRegister(buildApp(), { platform: "web", token: "tok-1" });
expect(response.status).toBe(401);
expect(mockStore).toHaveLength(0);
});
it("revalidates active membership inside tenant/user RLS before registering", async () => {
const response = await postRegister(buildApp(), {
tenantId: "tenant-1",
platform: "web",
token: "tok-1",
appVersion: "1.2.3",
});
expect(response.status).toBe(200);
const json = (await response.json()) as { success: boolean; data: { pushProvider: string; platform: string; appVersion: string | null } };
expect(json.success).toBe(true);
expect(json.data.platform).toBe("web");
expect(json.data.pushProvider).toBe("webpush");
expect(json.data.appVersion).toBe("1.2.3");
expect(mockStore.size).toBe(1);
expect(revalidateWorkspaceContext).toHaveBeenCalledWith({ tenantId: "tenant-1", userId: TEST_USER_ID });
expect(findLegacyAuthUserById).toHaveBeenCalledWith(TEST_USER_ID);
});
it("is idempotent: re-registering the same token bumps lastSeenAt without duplicating", async () => {
it("keeps same-owner registration idempotent without duplicating rows", async () => {
const app = buildApp();
await postRegister(app, { userId: "u-1", tenantId: null, platform: "web", token: "tok-x" });
const second = await postRegister(app, { userId: "u-1", tenantId: null, platform: "web", token: "tok-x" });
await postRegister(app, { platform: "web", token: "tok-x" });
const second = await postRegister(app, { platform: "web", token: "tok-x" });
expect(second.status).toBe(200);
expect(mockStore.size).toBe(1);
expect(mockStore).toHaveLength(1);
});
it("fails closed instead of reassigning a token owned by another user", async () => {
mockStore.set("tok-x", {
id: "dt-foreign",
userId: "u-2",
tenantId: null,
platform: "web",
token: "tok-x",
pushProvider: "webpush",
appVersion: null,
createdAt: new Date(),
lastSeenAt: new Date(),
revokedAt: null,
});
const response = await postRegister(buildApp(), { platform: "web", token: "tok-x" });
expect(response.status).toBe(500);
expect(mockStore.get("tok-x")?.userId).toBe("u-2");
});
});
describe("POST /v1/devices/revoke", () => {
it("revokes a known token", async () => {
it("rejects missing or service-token-only authentication", async () => {
expect((await postRevoke(buildApp(), { token: "tok-a" }, { auth: null })).status).toBe(401);
expect((await postRevoke(buildApp(), { token: "tok-a" }, { auth: `Bearer ${TEST_TOKEN}` })).status).toBe(401);
});
it("rejects body and header attempts to override the JWT owner", async () => {
expect((await postRevoke(buildApp(), { token: "tok-a", userId: "u-2" })).status).toBe(400);
expect((await postRevoke(buildApp(), { token: "tok-a" }, { identityHeader: "u-2" })).status).toBe(400);
});
it("revokes only the matching tenantless owner's token without echoing it", async () => {
const app = buildApp();
await postRegister(app, { userId: "u-1", platform: "web", token: "tok-a" });
const response = await app.request("/v1/devices/revoke", {
method: "POST",
headers: { "content-type": "application/json", authorization: `Bearer ${TEST_TOKEN}` },
body: JSON.stringify({ token: "tok-a" }),
});
await postRegister(app, { platform: "web", token: "tok-a" });
const response = await postRevoke(app, { token: "tok-a" });
expect(response.status).toBe(200);
const json = (await response.json()) as { data: { revokedAt: string | null } };
expect(json.data.revokedAt).not.toBeNull();
const responseText = await response.text();
expect(responseText).not.toContain("tok-a");
expect(JSON.parse(responseText)).toMatchObject({ success: true, data: { id: "dt-1", revokedAt: expect.any(String) } });
});
it("revalidates tenant membership before revoking a tenant token", async () => {
const app = buildApp();
await postRegister(app, { tenantId: "tenant-1", platform: "web", token: "tok-a" });
revalidateWorkspaceContext.mockClear();
const response = await postRevoke(app, { token: "tok-a", tenantId: "tenant-1" });
expect(response.status).toBe(200);
expect(revalidateWorkspaceContext).toHaveBeenCalledWith({ tenantId: "tenant-1", userId: TEST_USER_ID });
});
it("hides tokens owned by another user or tenant", async () => {
mockStore.set("tok-a", {
id: "dt-foreign",
userId: "u-2",
tenantId: "tenant-1",
platform: "web",
token: "tok-a",
pushProvider: "webpush",
appVersion: null,
createdAt: new Date(),
lastSeenAt: new Date(),
revokedAt: null,
});
const wrongUser = await postRevoke(buildApp(), { token: "tok-a", tenantId: "tenant-1" });
expect(wrongUser.status).toBe(404);
expect(mockStore.get("tok-a")?.revokedAt).toBeNull();
mockStore.get("tok-a")!.userId = TEST_USER_ID;
const wrongTenant = await postRevoke(buildApp(), { token: "tok-a", tenantId: "tenant-2" });
expect(wrongTenant.status).toBe(404);
expect(mockStore.get("tok-a")?.revokedAt).toBeNull();
});
it("returns 404 for unknown tokens", async () => {
const app = buildApp();
const response = await app.request("/v1/devices/revoke", {
method: "POST",
headers: { "content-type": "application/json", authorization: `Bearer ${TEST_TOKEN}` },
body: JSON.stringify({ token: "missing" }),
});
const response = await postRevoke(buildApp(), { token: "missing" });
expect(response.status).toBe(404);
});
});
@@ -6,12 +6,10 @@
* The endpoint upserts by `token` (globally unique) so the same payload
* can be replayed on every cold start without producing duplicate rows.
*
* Authentication: service-credential (bearer or API-key) — the web
* client forwards its session bearer through the same auth pipeline as
* every other API call. `userId` and `tenantId` come from the request
* body because the wrapping service-token has no inherent identity in
* the HiveGrid auth model; downstream calls verify these against
* the authenticated principal.
* Authentication: the bearer must be a verified, active API session JWT.
* The device owner comes exclusively from the signed session claims. An
* optional tenant is accepted only after the active membership has been
* revalidated inside the matching tenant/user RLS context.
*
* @see packages/db/src/device-tokens.server.ts
*/
@@ -23,12 +21,20 @@ import {
type DeviceTokenRecord,
} from "@hivegrid/db/device-tokens.server";
import { Hono, type Context } from "hono";
import { getApiAppDependencies } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { verifyApiSessionToken } from "../auth/session/session-token.js";
import { getApiRuntimeConfig } from "../config.js";
import { apiError } from "../middleware/error-envelope.js";
import { requireServiceCredential, readJsonBody, isPlainObject } from "./shared.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import {
handleWorkspaceContextRevalidationError,
getBearerToken,
readJsonBody,
isPlainObject,
} from "./shared.js";
const MAX_TOKEN_LENGTH = 4_096;
const MAX_USER_ID_LENGTH = 128;
const MAX_TENANT_ID_LENGTH = 128;
const MAX_APP_VERSION_LENGTH = 64;
@@ -38,32 +44,35 @@ export function registerDevicesRoutes(app: Hono<ApiEnv>) {
}
async function postDeviceRegisterRequest(c: Context<ApiEnv>) {
const unauthorized = requireServiceCredential(c);
if (unauthorized) {
return unauthorized;
const sessionIdentity = await authenticateDeviceUser(c);
if (!sessionIdentity) {
return invalidDeviceSession(c);
}
const userId = sessionIdentity.userId;
const body = await readJsonBody(c.req.raw);
if (!isPlainObject(body)) {
return apiError(c, 400, "invalid_request", "Request body must be a JSON object.", { params: { reason: "body_invalid", bodyType: "device_register" } });
}
const userId = typeof body.userId === "string" ? body.userId.trim() : "";
if (body.userId !== undefined || c.req.header("x-hivegrid-user-id") !== undefined) {
return apiError(c, 400, "device_identity_override_not_allowed", "Device user identity must come from the authenticated API session.");
}
const tenantIdRaw = typeof body.tenantId === "string" ? body.tenantId.trim() : "";
const platform = parseDevicePlatform(body.platform);
const token = typeof body.token === "string" ? body.token.trim() : "";
const pushProvider = parsePushProvider(body.pushProvider) ?? undefined;
const appVersion = typeof body.appVersion === "string" ? body.appVersion.trim() : "";
if (!userId) {
return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_required", field: "userId" } });
}
if (userId.length > MAX_USER_ID_LENGTH) {
return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_too_long", field: "userId", max: MAX_USER_ID_LENGTH } });
}
if (tenantIdRaw.length > MAX_TENANT_ID_LENGTH) {
return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_too_long", field: "tenantId", max: MAX_TENANT_ID_LENGTH } });
}
if (tenantIdRaw.includes("\u0000")) {
return apiError(c, 400, "invalid_request", "Request validation failed.", {
params: { reason: "field_value_invalid", field: "tenantId" },
});
}
if (!platform) {
return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_value_invalid", field: "platform", allowed: "web" } });
}
@@ -77,68 +86,146 @@ async function postDeviceRegisterRequest(c: Context<ApiEnv>) {
return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_too_long", field: "appVersion", max: MAX_APP_VERSION_LENGTH } });
}
let record: DeviceTokenRecord;
try {
record = await registerDeviceToken({
userId,
tenantId: tenantIdRaw || null,
platform,
token,
pushProvider,
appVersion: appVersion || null,
});
} catch {
return apiError(c, 500, "device_token_register_failed", "Device token could not be registered.");
}
const tenantId = tenantIdRaw || null;
return runWithVerifiedApiRlsContext(tenantId ? { tenantId, userId } : { userId }, async () => {
const identityError = await validateDeviceTenantIdentity(c, userId, tenantId);
if (identityError) {
return identityError;
}
return c.json(
{
success: true,
data: {
id: record.id,
userId: record.userId,
tenantId: record.tenantId,
platform: record.platform,
pushProvider: record.pushProvider,
appVersion: record.appVersion,
createdAt: record.createdAt.toISOString(),
lastSeenAt: record.lastSeenAt.toISOString(),
let record: DeviceTokenRecord;
try {
record = await registerDeviceToken({
userId,
tenantId,
platform,
token,
pushProvider,
appVersion: appVersion || null,
});
} catch {
return apiError(c, 500, "device_token_register_failed", "Device token could not be registered.");
}
return c.json(
{
success: true,
data: {
id: record.id,
userId: record.userId,
tenantId: record.tenantId,
platform: record.platform,
pushProvider: record.pushProvider,
appVersion: record.appVersion,
createdAt: record.createdAt.toISOString(),
lastSeenAt: record.lastSeenAt.toISOString(),
},
},
},
200,
);
200,
);
});
}
async function postDeviceRevokeRequest(c: Context<ApiEnv>) {
const unauthorized = requireServiceCredential(c);
if (unauthorized) {
return unauthorized;
const sessionIdentity = await authenticateDeviceUser(c);
if (!sessionIdentity) {
return invalidDeviceSession(c);
}
const userId = sessionIdentity.userId;
const body = await readJsonBody(c.req.raw);
if (!isPlainObject(body)) {
return apiError(c, 400, "invalid_request", "Request body must be a JSON object.", { params: { reason: "body_invalid", bodyType: "device_revoke" } });
}
if (body.userId !== undefined || c.req.header("x-hivegrid-user-id") !== undefined) {
return apiError(c, 400, "device_identity_override_not_allowed", "Device user identity must come from the authenticated API session.");
}
const token = typeof body.token === "string" ? body.token.trim() : "";
const tenantIdRaw = typeof body.tenantId === "string" ? body.tenantId.trim() : "";
if (!token) {
return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_required", field: "token" } });
}
const record = await revokeDeviceToken(token);
if (!record) {
return apiError(c, 404, "device_token_not_found", "Device token was not found.");
if (token.length > MAX_TOKEN_LENGTH) {
return apiError(c, 400, "invalid_request", "Request validation failed.", {
params: { reason: "field_too_long", field: "token", max: MAX_TOKEN_LENGTH },
});
}
if (tenantIdRaw.length > MAX_TENANT_ID_LENGTH || tenantIdRaw.includes("\u0000")) {
return apiError(c, 400, "invalid_request", "Request validation failed.", {
params: { reason: "field_value_invalid", field: "tenantId" },
});
}
return c.json(
{
success: true,
data: {
id: record.id,
token: record.token,
revokedAt: record.revokedAt?.toISOString() ?? null,
const tenantId = tenantIdRaw || null;
return runWithVerifiedApiRlsContext(tenantId ? { tenantId, userId } : { userId }, async () => {
const identityError = await validateDeviceTenantIdentity(c, userId, tenantId);
if (identityError) {
return identityError;
}
const record = await revokeDeviceToken({ token, userId, tenantId });
if (!record) {
return apiError(c, 404, "device_token_not_found", "Device token was not found.");
}
return c.json(
{
success: true,
data: {
id: record.id,
revokedAt: record.revokedAt?.toISOString() ?? null,
},
},
},
200,
);
200,
);
});
}
function invalidDeviceSession(c: Context<ApiEnv>) {
return apiError(c, 401, "invalid_token", "A valid API session token is required.");
}
async function authenticateDeviceUser(c: Context<ApiEnv>): Promise<{ userId: string } | null> {
const token = getBearerToken(c.req.raw);
if (!token) {
return null;
}
const dependencies = getApiAppDependencies();
try {
const decoded = verifyApiSessionToken(token, getApiRuntimeConfig().jwtSecret!);
if (!decoded) {
return null;
}
return runWithVerifiedApiRlsContext({ userId: decoded.userId }, async () => {
const session = await dependencies.getActiveApiSession(decoded.sessionId);
if (!session || session.userId !== decoded.userId) {
return null;
}
const user = await dependencies.findLegacyAuthUserById(decoded.userId);
if (!user || user.id !== decoded.userId || user.pendingDeletion || user.pseudonymized || user.active === false) {
return null;
}
return { userId: decoded.userId };
});
} catch {
return null;
}
}
async function validateDeviceTenantIdentity(c: Context<ApiEnv>, userId: string, tenantId: string | null) {
if (!tenantId) {
return null;
}
try {
await getApiAppDependencies().revalidateWorkspaceContext({ tenantId, userId });
return null;
} catch (error) {
return handleWorkspaceContextRevalidationError(c, error);
}
}
@@ -0,0 +1,128 @@
export type InboundEmailPayload = {
messageId: string;
toEmail: string;
fromEmail: string;
subject: string;
message: string;
htmlMessage: string | null;
recipientEmails: string[];
originalRecipientEmails: string[];
occurredAt: Date | null;
};
export function parseInboundEmailPayload(rawBody: string):
| { ok: true; value: InboundEmailPayload }
| { ok: false; error: string } {
let payload: unknown;
try {
payload = JSON.parse(rawBody) as unknown;
} catch {
return { ok: false, error: "Inbound email payload must be valid JSON." };
}
if (!isRecord(payload)) {
return { ok: false, error: "Inbound email payload must be an object." };
}
const messageId = readString(payload, "messageId") ?? readString(payload, "message_id") ?? readString(payload, "id");
const subject = readString(payload, "subject") ?? "";
const textMessage = readString(payload, "text") ?? readString(payload, "textBody") ?? readString(payload, "text_body");
const htmlMessage = readString(payload, "html") ?? readString(payload, "htmlBody") ?? readString(payload, "html_body") ?? null;
const message = textMessage ?? htmlMessage;
const fromEmail = readEmail(payload.from) ?? readString(payload, "fromEmail") ?? readString(payload, "from_email") ?? readString(payload, "from");
const recipientEmails = [
...readEmails(payload.to),
...readEmails(payload.cc),
...readEmails(payload.bcc),
...readEmails(payload.recipients),
...readEmails(payload.recipient),
...readEmails(readString(payload, "toEmail")),
...readEmails(readString(payload, "to_email")),
];
const headers = isRecord(payload.headers)
? payload.headers
: isRecord(payload.Headers)
? payload.Headers
: {};
const originalRecipientEmails = [
...readEmails(readCaseInsensitive(headers, "to")),
...readEmails(readCaseInsensitive(headers, "cc")),
...readEmails(readCaseInsensitive(headers, "x-original-to")),
...readEmails(payload.originalTo),
...readEmails(payload.original_to),
];
const toEmail = recipientEmails[0];
const occurredAt = readOptionalDate(
readString(payload, "sentAt") ??
readString(payload, "sent_at") ??
readString(payload, "date")
);
if (!messageId || !fromEmail || !toEmail || !message) {
return { ok: false, error: "Inbound email payload is missing messageId, fromEmail, toEmail, or message." };
}
return {
ok: true,
value: {
messageId,
fromEmail,
toEmail,
subject,
message,
htmlMessage,
recipientEmails,
originalRecipientEmails: [
...new Set(
originalRecipientEmails.map((email) => email.trim().toLowerCase())
),
],
occurredAt,
},
};
}
function readOptionalDate(value: string | undefined): Date | null {
if (!value) return null;
const parsed = new Date(value);
return Number.isNaN(parsed.getTime()) ? null : parsed;
}
function readCaseInsensitive(
record: Record<string, unknown>,
key: string
): unknown {
const match = Object.keys(record).find(
(candidate) => candidate.toLowerCase() === key
);
return match ? record[match] : undefined;
}
function readString(record: Record<string, unknown>, key: string) {
const value = record[key];
return typeof value === "string" && value.trim() ? value.trim() : undefined;
}
function readEmail(value: unknown): string | undefined {
if (typeof value === "string") {
return value.trim() || undefined;
}
if (isRecord(value)) {
return readString(value, "email") ?? readString(value, "address");
}
return undefined;
}
function readEmails(value: unknown): string[] {
if (!Array.isArray(value)) {
if (typeof value === "string" || isRecord(value)) {
const email = readEmail(value);
return email ? [email] : [];
}
return [];
}
return value.flatMap((item) => readEmails(item));
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
@@ -1,18 +1,15 @@
import { authorizeStorageObjectAccess, authorizeStorageUploadConstraints } from "@hivegrid/storage";
import { Hono, type Context } from "hono";
import { getApiAppDependencies, type ExportJobDownloadRecord, type LegacyEventWebhookAttempt } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { authenticateServiceRequest } from "../auth.js";
import { getApiRuntimeConfig } from "../config.js";
import { normalizeIdempotencyKey } from "../idempotency/store.js";
import { postMailjetEmailSequenceWebhookRequest } from "../email-sequences/provider-webhook-route.js";
import { apiError } from "../middleware/error-envelope.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { verifyMailjetWebhookAuth } from "../webhooks/mailjet-webhook-auth.js";
import {
missingApiTenantScopeError,
parseMaintenanceTake,
parseOptionalTenantId,
parseStorageObjectStatus,
readOptionalJsonObjectBody,
requireWorkspaceServiceCredential,
authenticateServiceCredentialRequest,
@@ -20,17 +17,18 @@ import {
forbiddenApiKeyScopeError,
} from "./shared.js";
import { resolveApiTenantScope } from "../auth/scope.js";
const AI_UPLOAD_MAX_BYTES = 10 * 1024 * 1024;
const AI_UPLOAD_ALLOWED_CONTENT_TYPES = ["image/png", "image/jpeg", "image/webp", "application/pdf", "text/plain", "text/csv", "application/json"];
import { parseInboundEmailPayload } from "./inbound-email-payload.js";
export function registerMaintenanceRoutes(app: Hono<ApiEnv>) {
app.post("/v1/ai/upload", uploadAiFileRequest);
app.post("/v1/support/inbound-email", postSupportInboundEmailRequest);
app.post("/v1/email/inbound-mailjet", postTenantInboundEmailRequest);
app.post("/v1/email-sequences/mailjet/webhooks", (c) =>
postMailjetEmailSequenceWebhookRequest(c, {
webhookSecret: getApiRuntimeConfig().mailjet.webhookSecret,
markEmailSequenceDeliveryBounced: getApiAppDependencies().markEmailSequenceDeliveryBounced,
resolveEmailSequenceProviderMessageRlsIdentity: getApiAppDependencies().resolveEmailSequenceProviderMessageRlsIdentity,
markCampaignOutboundEmailBounced: getApiAppDependencies().markCampaignOutboundEmailBounced,
resolveCampaignOutboundEmailRlsIdentity: getApiAppDependencies().resolveOutboundEmailClickRlsIdentity,
// AK-P14a: a bounce/complaint also suppresses the recipient (best-effort).
recordSuppression: getApiAppDependencies().recordSuppression,
})
@@ -60,167 +58,28 @@ async function postSupportInboundEmailRequest(c: Context<ApiEnv>) {
return apiError(c, 400, "invalid_request", payloadResult.error);
}
const result = await getApiAppDependencies().createInboundSupportTicketFromEmail(payloadResult.value);
if (result.status === "unknown-recipient") {
const dependencies = getApiAppDependencies();
const identity = await dependencies.resolveTenantInboundAddressRlsIdentity([payloadResult.value.toEmail]).catch(() => null);
if (!identity) {
return c.json({ accepted: true, status: "ignored" }, 202);
}
return c.json({ accepted: true, status: result.status, ticketId: result.ticketId }, result.status === "created" ? 201 : 202);
}
async function uploadAiFileRequest(c: Context<ApiEnv>) {
const principal = authenticateServiceRequest(c.req.raw, getApiRuntimeConfig());
if (!principal) {
return apiError(c, 401, "unauthorized", "A valid service credential is required.");
}
const { storage } = getApiRuntimeConfig();
if (!storage.endpoint || !storage.region || !storage.bucket || !storage.accessKeyId || !storage.secretAccessKey) {
return apiError(c, 401, "upload_config_missing", "AI upload storage is not configured.");
}
try {
const file = c.req.raw.body || "";
const tenantScope = parseOptionalTenantId(c);
if (!tenantScope.ok) {
return apiError(c, 400, "invalid_request", tenantScope.error);
}
const tenantId = tenantScope.value ?? "";
if (!tenantId) {
return missingApiTenantScopeError(c);
}
const filename = c.req.header("x-filename") || "file.txt";
const contentType = c.req.header("content-type") || "text/plain";
const contentLength = parseContentLength(c.req.header("content-length"));
if (contentLength === null) {
return apiError(c, 411, "content_length_required", "AI upload requires a valid Content-Length header.");
}
const constraintDecision = authorizeStorageUploadConstraints({
operation: "upload",
contentType,
byteSize: contentLength,
allowedContentTypes: AI_UPLOAD_ALLOWED_CONTENT_TYPES,
maxBytes: AI_UPLOAD_MAX_BYTES,
metadata: { requestId: c.get("requestId") },
return runWithVerifiedApiRlsContext({ tenantId: identity.tenantId }, async () => {
const result = await dependencies.createInboundSupportTicketFromEmail({
messageId: payloadResult.value.messageId,
fromEmail: payloadResult.value.fromEmail,
toEmail: payloadResult.value.toEmail,
subject: payloadResult.value.subject,
message: payloadResult.value.message,
});
if (constraintDecision) {
const status = constraintDecision.reason === "object_too_large" ? 413 : 415;
return apiError(c, status, constraintDecision.reason, "AI upload storage access denied.");
}
const fileType = `.${contentType.split("/")[1]}`;
const finalName = filename.includes(fileType) ? filename : `${filename}${fileType}`;
const path = `tenants/${tenantId}/${new Date().getTime()}-${finalName}`;
if (finalName.includes("/") || finalName.includes("\\")) {
return apiError(c, 400, "invalid_key", "AI upload storage access denied.");
}
const storageStatus = parseStorageObjectStatus(c.req.header("x-storage-object-status"));
const accessDecision = authorizeStorageObjectAccess({ tenantId, key: path, operation: "upload", status: storageStatus });
if (!accessDecision.allowed) {
const status = accessDecision.reason === "invalid_tenant" || accessDecision.reason === "invalid_key" ? 400 : 403;
return apiError(c, status, accessDecision.reason, "AI upload storage access denied.");
if (result.status === "unknown-recipient") {
return c.json({ accepted: true, status: "ignored" }, 202);
}
const dependencies = getApiAppDependencies();
const tenant = await dependencies.findLegacyTenantById(tenantId);
if (!tenant) {
return apiError(c, 404, "tenant_not_found", "AI upload tenant was not found.");
}
if (!tenant.active || tenant.deactivatedReason) {
return apiError(c, 403, "tenant_inactive", "AI upload tenant is not active.");
}
const response = await dependencies.uploadFile(storage.bucket, accessDecision.key, file, contentType);
return c.json({ success: true, url: response.publicUrl });
} catch {
return apiError(c, 500, "ai_upload_failed", "AI file upload failed.");
}
return c.json({ accepted: true, status: result.status, ticketId: result.ticketId }, result.status === "created" ? 201 : 202);
});
}
function parseContentLength(contentLength: string | undefined): number | null {
if (contentLength === undefined) {
return null;
}
const parsed = Number(contentLength);
return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
}
type InboundEmailPayload = {
messageId: string;
toEmail: string;
fromEmail: string;
subject: string;
message: string;
};
function parseInboundEmailPayload(rawBody: string): { ok: true; value: InboundEmailPayload } | { ok: false; error: string } {
let payload: unknown;
try {
payload = JSON.parse(rawBody) as unknown;
} catch {
return { ok: false, error: "Inbound email payload must be valid JSON." };
}
if (!isRecord(payload)) {
return { ok: false, error: "Inbound email payload must be an object." };
}
const messageId = readString(payload, "messageId") ?? readString(payload, "message_id") ?? readString(payload, "id");
const subject = readString(payload, "subject") ?? "";
const message = readString(payload, "text") ?? readString(payload, "textBody") ?? readString(payload, "text_body") ?? readString(payload, "html") ?? readString(payload, "htmlBody") ?? readString(payload, "html_body");
const fromEmail = readEmail(payload.from) ?? readString(payload, "fromEmail") ?? readString(payload, "from_email") ?? readString(payload, "from");
const toEmail = readEmail(payload.to) ?? readFirstEmail(payload.to) ?? readString(payload, "toEmail") ?? readString(payload, "to_email") ?? readString(payload, "recipient");
if (!messageId || !fromEmail || !toEmail || !message) {
return { ok: false, error: "Inbound email payload is missing messageId, fromEmail, toEmail, or message." };
}
return {
ok: true,
value: {
messageId,
fromEmail,
toEmail,
subject,
message,
},
};
}
function readString(record: Record<string, unknown>, key: string) {
const value = record[key];
return typeof value === "string" && value.trim() ? value.trim() : undefined;
}
function readEmail(value: unknown): string | undefined {
if (typeof value === "string") {
return value.trim() || undefined;
}
if (isRecord(value)) {
return readString(value, "email") ?? readString(value, "address");
}
return undefined;
}
function readFirstEmail(value: unknown): string | undefined {
if (!Array.isArray(value)) {
return undefined;
}
for (const item of value) {
const email = readEmail(item);
if (email) {
return email;
}
}
return undefined;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
async function postEventWebhookAttemptRequest(c: Context<ApiEnv>) {
let attempt: LegacyEventWebhookAttempt | null = null;
async function postTenantInboundEmailRequest(c: Context<ApiEnv>) {
const authResult = verifyMailjetWebhookAuth({
secret: getApiRuntimeConfig().mailjet.webhookSecret,
headers: c.req.header(),
@@ -234,38 +93,98 @@ async function postEventWebhookAttemptRequest(c: Context<ApiEnv>) {
}
const rawBody = await c.req.raw.text();
const payloadResult = parseInboundEmailPayload(rawBody);
if (!payloadResult.ok) {
return apiError(c, 400, "invalid_request", payloadResult.error);
}
try {
const dependencies = getApiAppDependencies();
const attemptId = c.req.param("id") || "";
attempt = await dependencies.findLegacyEventWebhookAttemptById(attemptId);
if (!attempt) {
throw new Error("Invalid event webhook attempt");
const dependencies = getApiAppDependencies();
const identity = await dependencies.resolveTenantInboundAddressRlsIdentity(payloadResult.value.recipientEmails).catch(() => null);
if (!identity) {
return c.json({ accepted: true, status: "ignored", reason: "unknown-recipient" }, 202);
}
return runWithVerifiedApiRlsContext({ tenantId: identity.tenantId }, async () => {
const result = await dependencies.ingestTenantInboundEmail({
messageId: payloadResult.value.messageId,
fromEmail: payloadResult.value.fromEmail,
toEmail: payloadResult.value.toEmail,
recipientEmails: payloadResult.value.recipientEmails,
subject: payloadResult.value.subject,
textBody: payloadResult.value.message,
htmlBody: payloadResult.value.htmlMessage,
});
if (result.status === "ignored") {
return c.json({ accepted: true, status: "ignored", reason: result.reason }, 202);
}
await dependencies.updateLegacyEventWebhookAttempt({ id: attempt.id, tenantId: attempt.tenantId }, { startedAt: new Date() });
let queueResult;
return c.json(
{
accepted: true,
status: result.status,
emailId: result.emailId,
purpose: result.purpose,
...(result.status === "created"
? { leadId: result.leadId, kontaktId: result.kontaktId, projektId: result.projektId, activityId: result.activityId }
: {}),
},
result.status === "created" ? 201 : 202
);
});
}
async function postEventWebhookAttemptRequest(c: Context<ApiEnv>) {
const authResult = verifyMailjetWebhookAuth({
secret: getApiRuntimeConfig().mailjet.webhookSecret,
headers: c.req.header(),
});
if (!authResult.ok) {
if (authResult.reason === "missing-secret") {
return apiError(c, 500, "webhook_signing_not_configured", "Mailjet webhook authentication is not configured.");
}
return apiError(c, 401, "invalid_webhook_signature", `Invalid Mailjet webhook credentials: ${authResult.reason}.`);
}
const rawBody = await c.req.raw.text();
const dependencies = getApiAppDependencies();
const attemptId = c.req.param("id") || "";
const identity = await dependencies.resolveEventWebhookAttemptRlsIdentity(attemptId).catch(() => null);
if (!identity) {
return apiError(c, 400, "webhook_delivery_failed", "Webhook delivery request could not be accepted.");
}
return runWithVerifiedApiRlsContext({ tenantId: identity.tenantId }, async () => {
const attempt = await dependencies.findLegacyEventWebhookAttemptById(identity.resourceId).catch(() => null);
if (!attempt || attempt.id !== attemptId || attempt.tenantId !== identity.tenantId) {
return apiError(c, 400, "webhook_delivery_failed", "Webhook delivery request could not be accepted.");
}
try {
queueResult = await dependencies.queueLegacyEventWebhookAttemptDelivery({ attempt, body: JSON.parse(rawBody) as unknown, requestId: c.get("requestId") });
} catch {
await markWebhookAttemptUnavailable(attempt);
return apiError(c, 503, "maintenance_queue_unavailable", "Webhook delivery queue is unavailable.");
}
await dependencies.updateLegacyEventWebhookAttempt({ id: attempt.id, tenantId: attempt.tenantId }, { startedAt: new Date() });
let queueResult;
try {
queueResult = await dependencies.queueLegacyEventWebhookAttemptDelivery({
attempt,
body: JSON.parse(rawBody) as unknown,
requestId: c.get("requestId"),
});
} catch {
await markWebhookAttemptUnavailable(attempt);
return apiError(c, 503, "maintenance_queue_unavailable", "Webhook delivery queue is unavailable.");
}
if (!queueResult.enqueued) {
await markWebhookAttemptUnavailable(attempt);
return apiError(c, 503, "maintenance_queue_unavailable", "Webhook delivery queue is unavailable.");
}
return c.json({}, 200);
} catch {
if (attempt) {
await getApiAppDependencies().updateLegacyEventWebhookAttempt(
if (!queueResult.enqueued) {
await markWebhookAttemptUnavailable(attempt);
return apiError(c, 503, "maintenance_queue_unavailable", "Webhook delivery queue is unavailable.");
}
return c.json({}, 200);
} catch {
await dependencies.updateLegacyEventWebhookAttempt(
{ id: attempt.id, tenantId: attempt.tenantId },
{ finishedAt: new Date(), success: false, status: 400, message: "Webhook delivery request could not be accepted." }
);
return apiError(c, 400, "webhook_delivery_failed", "Webhook delivery request could not be accepted.");
}
return apiError(c, 400, "webhook_delivery_failed", "Webhook delivery request could not be accepted.");
}
});
}
async function markWebhookAttemptUnavailable(attempt: LegacyEventWebhookAttempt) {
@@ -345,47 +264,49 @@ async function getExportDownloadUrlRequest(c: Context<ApiEnv>) {
return apiError(c, 400, "invalid_request", "tenantId is required.");
}
try {
const exportJob = await getApiAppDependencies().findExportJobForDownload({ id: exportJobId, tenantId: lookupTenantId });
if (!exportJob) {
const apiKeyMissing = apiKeyScopedMissingResourceError(c, principal);
if (apiKeyMissing) {
return apiKeyMissing;
return runWithVerifiedApiRlsContext({ tenantId: lookupTenantId }, async () => {
try {
const exportJob = await getApiAppDependencies().findExportJobForDownload({ id: exportJobId, tenantId: lookupTenantId });
if (!exportJob) {
const apiKeyMissing = apiKeyScopedMissingResourceError(c, principal);
if (apiKeyMissing) {
return apiKeyMissing;
}
return apiError(c, 404, "export_job_not_found", `Export job ${exportJobId} not found.`);
}
return apiError(c, 404, "export_job_not_found", `Export job ${exportJobId} not found.`);
}
if (exportJob.errorName === "ExportPaused") {
return apiError(c, 409, "export_job_paused", "Export job is paused and cannot be downloaded.");
}
if (exportJob.status !== "COMPLETED") {
return apiError(c, 409, "export_job_not_completed", "Export job is not completed.");
}
if (!exportJob.artifactBucket || !exportJob.artifactKey) {
return apiError(c, 409, "export_artifact_missing", "Export artifact is not available.");
}
if (exportJob.expiresAt && exportJob.expiresAt.getTime() <= Date.now()) {
return apiError(c, 409, "export_job_expired", "Export job has expired.");
}
if (exportJob.errorName === "ExportPaused") {
return apiError(c, 409, "export_job_paused", "Export job is paused and cannot be downloaded.");
}
if (exportJob.status !== "COMPLETED") {
return apiError(c, 409, "export_job_not_completed", "Export job is not completed.");
}
if (!exportJob.artifactBucket || !exportJob.artifactKey) {
return apiError(c, 409, "export_artifact_missing", "Export artifact is not available.");
}
if (exportJob.expiresAt && exportJob.expiresAt.getTime() <= Date.now()) {
return apiError(c, 409, "export_job_expired", "Export job has expired.");
}
const signedUrl = await getApiAppDependencies().createSignedDownloadUrl(exportJob.artifactBucket, {
key: exportJob.artifactKey,
expiresInSeconds: 300,
responseContentDisposition: `attachment; filename="${exportJob.id}.${getExportArtifactExtension(exportJob)}"`,
});
const signedUrl = await getApiAppDependencies().createSignedDownloadUrl(exportJob.artifactBucket, {
key: exportJob.artifactKey,
expiresInSeconds: 300,
responseContentDisposition: `attachment; filename="${exportJob.id}.${getExportArtifactExtension(exportJob)}"`,
});
return c.json({
exportJobId: exportJob.id,
requestId: c.get("requestId"),
method: signedUrl.method,
url: signedUrl.url,
expiresAt: signedUrl.expiresAt.toISOString(),
expiresInSeconds: signedUrl.expiresInSeconds,
headers: signedUrl.headers,
});
} catch {
return apiError(c, 500, "export_download_url_failed", "Export download URL could not be created.");
}
return c.json({
exportJobId: exportJob.id,
requestId: c.get("requestId"),
method: signedUrl.method,
url: signedUrl.url,
expiresAt: signedUrl.expiresAt.toISOString(),
expiresInSeconds: signedUrl.expiresInSeconds,
headers: signedUrl.headers,
});
} catch {
return apiError(c, 500, "export_download_url_failed", "Export download URL could not be created.");
}
});
}
function getExportArtifactExtension(exportJob: Pick<ExportJobDownloadRecord, "format" | "artifactKey">) {
@@ -420,7 +341,9 @@ async function getExportProgressRequest(c: Context<ApiEnv>) {
return apiError(c, 400, "invalid_request", "tenantId is required.");
}
const progress = await getApiAppDependencies().readExportProgress({ exportJobId, tenantId: lookupTenantId });
const progress = await runWithVerifiedApiRlsContext({ tenantId: lookupTenantId }, () =>
getApiAppDependencies().readExportProgress({ exportJobId, tenantId: lookupTenantId })
);
if (!progress) {
return c.json({ exportJobId, processedRows: 0, totalEstimate: null, updatedAt: null, requestId: c.get("requestId") });
}
@@ -12,6 +12,7 @@ import type { ApiEnv } from "../api-types.js";
import { authenticateServiceRequest } from "../auth.js";
import { getApiRuntimeConfig } from "../config.js";
import { apiError } from "../middleware/error-envelope.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { handleWorkspaceContextRevalidationError } from "./shared.js";
export function registerNotificationRoutes(app: Hono<ApiEnv>) {
@@ -25,9 +26,7 @@ async function getNotificationStreamRequest(c: Context<ApiEnv>) {
}
const requestId: string = c.get("requestId");
const scopeResult:
| { ok: true; scope: ReturnType<typeof normalizeNotificationStreamScope> }
| { ok: false; error: string } = (() => {
const scopeResult: { ok: true; scope: ReturnType<typeof normalizeNotificationStreamScope> } | { ok: false; error: string } = (() => {
try {
return {
ok: true,
@@ -49,49 +48,53 @@ async function getNotificationStreamRequest(c: Context<ApiEnv>) {
const { scope } = scopeResult;
const dependencies = getApiAppDependencies();
try {
await dependencies.revalidateWorkspaceContext({ tenantId: scope.tenantId, userId: scope.userId });
await runWithVerifiedApiRlsContext({ tenantId: scope.tenantId, userId: scope.userId }, () =>
dependencies.revalidateWorkspaceContext({ tenantId: scope.tenantId, userId: scope.userId })
);
} catch (error) {
return handleWorkspaceContextRevalidationError(c, error);
}
const afterCursor = scope.afterCursor ?? null;
const stream = new ReadableStream<Uint8Array>({
async start(controller) {
const encoder = new TextEncoder();
const write = (chunk: string) => controller.enqueue(encoder.encode(chunk));
const writeRealtimeEvent = (event: Parameters<typeof assertNotificationEventInAppScope>[0]) => {
assertNotificationEventInAppScope(event, scope);
write(serializeRealtimeEvent(event));
};
return runWithVerifiedApiRlsContext({ tenantId: scope.tenantId, userId: scope.userId }, async () => {
const encoder = new TextEncoder();
const write = (chunk: string) => controller.enqueue(encoder.encode(chunk));
const writeRealtimeEvent = (event: Parameters<typeof assertNotificationEventInAppScope>[0]) => {
assertNotificationEventInAppScope(event, scope);
write(serializeRealtimeEvent(event));
};
try {
const snapshot = await dependencies.getNotificationStreamSnapshot({ tenantId: scope.tenantId, userId: scope.userId, afterCursor });
const cursor = snapshot.cursor ?? afterCursor ?? "initial";
writeRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationSnapshot,
requestId,
tenantId: scope.tenantId,
userId: scope.userId,
cursor,
items: snapshot.items,
});
write(serializeRealtimeComment(`keepalive ${JSON.stringify({ requestId, cursor })}`));
writeRealtimeEvent({ event: REALTIME_EVENT_NAMES.keepalive, requestId, tenantId: scope.tenantId, userId: scope.userId, cursor });
} catch {
const cursor = afterCursor ?? "error";
write(
serializeRealtimeEvent({
event: REALTIME_EVENT_NAMES.error,
try {
const snapshot = await dependencies.getNotificationStreamSnapshot({ tenantId: scope.tenantId, userId: scope.userId, afterCursor });
const cursor = snapshot.cursor ?? afterCursor ?? "initial";
writeRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationSnapshot,
requestId,
tenantId: scope.tenantId,
userId: scope.userId,
cursor,
code: "notification_stream_failed",
message: "Notification stream snapshot failed.",
})
);
} finally {
controller.close();
}
items: snapshot.items,
});
write(serializeRealtimeComment(`keepalive ${JSON.stringify({ requestId, cursor })}`));
writeRealtimeEvent({ event: REALTIME_EVENT_NAMES.keepalive, requestId, tenantId: scope.tenantId, userId: scope.userId, cursor });
} catch {
const cursor = afterCursor ?? "error";
write(
serializeRealtimeEvent({
event: REALTIME_EVENT_NAMES.error,
requestId,
tenantId: scope.tenantId,
userId: scope.userId,
cursor,
code: "notification_stream_failed",
message: "Notification stream snapshot failed.",
})
);
} finally {
controller.close();
}
});
},
});
@@ -0,0 +1,396 @@
import {
AdminLeadIngestionError,
type PlatformLeadS2SInput,
type PlatformLeadSourceAuthentication,
} from "@hivegrid/db/platform-leads.server";
import { MemoryAdapter, createSharedStore } from "@hivegrid/shared-store";
import { Hono } from "hono";
import { afterEach, describe, expect, test, vi } from "vitest";
import type { ApiEnv } from "../api-types.js";
import { BODY_LIMIT_HEADER, PLATFORM_LEAD_JSON_BODY_LIMIT_BYTES } from "../middleware/body-limit.js";
import { createRequestIdMiddleware } from "../middleware/request-id.js";
import {
PLATFORM_LEAD_ROUTE,
createPlatformLeadSourceRateLimiter,
postPlatformLeadRequest,
type PlatformLeadRouteDependencies,
} from "./platform-lead-routes.js";
const SOURCE_CREDENTIAL = "source_credential_abcdefghijklmnopqrstuvwxyz0123456789";
const SOURCE: PlatformLeadSourceAuthentication = {
sourceId: "source_1",
sourceKey: "website",
rateLimitPerMinute: 2,
};
const LEAD = {
id: "lead_1",
status: "new" as const,
createdAt: "2026-07-16T12:00:00.000Z",
};
afterEach(() => {
delete process.env.PLATFORM_LEADS_INGRESS_ENABLED;
});
function createDependencies(overrides: Partial<PlatformLeadRouteDependencies> = {}) {
const authenticatePlatformLeadSourceCredential = vi.fn(async (_credential: string) => SOURCE);
const ingestPlatformLead = vi.fn(async (_input: PlatformLeadS2SInput) => ({ outcome: "created" as const, lead: LEAD }));
const checkSourceRateLimit = vi.fn(async (_source: PlatformLeadSourceAuthentication) => ({
allowed: true as const,
headers: {
"X-RateLimit-Limit": "2",
"X-RateLimit-Remaining": "1",
"X-RateLimit-Reset": "1784203260",
"X-RateLimit-Scope": "platform-lead-source",
},
}));
const checkPreAuthRateLimit = vi.fn(async (_request: Request) => ({ allowed: true as const, headers: {} }));
const dependencies: PlatformLeadRouteDependencies = {
authenticatePlatformLeadSourceCredential,
ingestPlatformLead,
checkPreAuthRateLimit,
checkSourceRateLimit,
...overrides,
};
return { dependencies, authenticatePlatformLeadSourceCredential, ingestPlatformLead, checkPreAuthRateLimit, checkSourceRateLimit };
}
function buildApp(dependencies: PlatformLeadRouteDependencies) {
const app = new Hono<ApiEnv>();
app.use("*", createRequestIdMiddleware());
app.post(PLATFORM_LEAD_ROUTE, (context) => postPlatformLeadRequest(context, dependencies));
return app;
}
function postLead(
app: ReturnType<typeof buildApp>,
body: unknown,
options: {
credential?: string | null;
idempotencyKey?: string | null;
contentType?: string | null;
contentLength?: string | null;
} = {},
) {
const credential = options.credential === undefined ? SOURCE_CREDENTIAL : options.credential;
const idempotencyKey = options.idempotencyKey === undefined ? "submission_1" : options.idempotencyKey;
const contentType = options.contentType === undefined ? "application/json" : options.contentType;
const contentLength = options.contentLength === undefined ? null : options.contentLength;
return app.request(PLATFORM_LEAD_ROUTE, {
method: "POST",
headers: {
"x-request-id": "req_platform_lead",
...(credential === null ? {} : { authorization: `Bearer ${credential}` }),
...(idempotencyKey === null ? {} : { "idempotency-key": idempotencyKey }),
...(contentType === null ? {} : { "content-type": contentType }),
...(contentLength === null ? {} : { "content-length": contentLength }),
},
body: typeof body === "string" ? body : JSON.stringify(body),
});
}
describe("POST /v1/platform/leads", () => {
test("authenticates the source, normalizes the bounded payload, and creates a lead", async () => {
const { dependencies, authenticatePlatformLeadSourceCredential, ingestPlatformLead, checkSourceRateLimit } =
createDependencies();
const response = await postLead(buildApp(dependencies), {
firstName: " Petra ",
email: "petra@example.test",
utmSource: "campaign",
metadata: { formId: "contact-form", consent: true },
});
expect(response.status).toBe(201);
expect(response.headers.get("idempotency-replayed")).toBe("false");
expect(response.headers.get("x-ratelimit-scope")).toBe("platform-lead-source");
const responseBody = await response.json();
expect(responseBody).toEqual(LEAD);
expect(authenticatePlatformLeadSourceCredential).toHaveBeenCalledWith(SOURCE_CREDENTIAL);
expect(checkSourceRateLimit).toHaveBeenCalledWith(SOURCE);
expect(ingestPlatformLead).toHaveBeenCalledWith({
channel: "s2s",
sourceId: SOURCE.sourceId,
sourceCredential: SOURCE_CREDENTIAL,
idempotencyKey: "submission_1",
requestFingerprint: expect.stringMatching(/^[a-f0-9]{64}$/u),
payload: {
firstName: "Petra",
email: "petra@example.test",
utmSource: "campaign",
metadata: { formId: "contact-form", consent: true },
},
});
expect(JSON.stringify(responseBody)).not.toContain(SOURCE_CREDENTIAL);
expect(JSON.stringify(responseBody)).not.toContain(SOURCE.sourceId);
});
test("replays an identical request and rejects reuse with a different request hash", async () => {
let stored: { fingerprint: string; lead: typeof LEAD } | undefined;
const ingestPlatformLead = vi.fn(async (input: PlatformLeadS2SInput) => {
if (!stored) {
stored = { fingerprint: input.requestFingerprint, lead: LEAD };
return { outcome: "created" as const, lead: LEAD };
}
if (stored.fingerprint !== input.requestFingerprint) {
throw new AdminLeadIngestionError("IDEMPOTENCY_CONFLICT", "conflict");
}
return { outcome: "replayed" as const, lead: stored.lead };
});
const { dependencies } = createDependencies({ ingestPlatformLead });
const app = buildApp(dependencies);
const created = await postLead(app, { company: "HiveGrid" });
const replayed = await postLead(app, { company: "HiveGrid" });
const conflict = await postLead(app, { company: "Partner GmbH" });
expect(created.status).toBe(201);
expect(created.headers.get("idempotency-replayed")).toBe("false");
expect(replayed.status).toBe(201);
expect(replayed.headers.get("idempotency-replayed")).toBe("true");
expect(await replayed.json()).toEqual(await created.json());
expect(conflict.status).toBe(409);
await expect(conflict.json()).resolves.toMatchObject({
error: { code: "idempotency_key_conflict", requestId: "req_platform_lead" },
});
});
test("partitions the request fingerprint by authenticated source identity", async () => {
const fingerprints: string[] = [];
const ingestPlatformLead = vi.fn(async (input: PlatformLeadS2SInput) => {
fingerprints.push(input.requestFingerprint);
return { outcome: "created" as const, lead: LEAD };
});
const authenticatePlatformLeadSourceCredential = vi
.fn<(credential: string) => Promise<PlatformLeadSourceAuthentication | null>>()
.mockResolvedValueOnce(SOURCE)
.mockResolvedValueOnce({ ...SOURCE, sourceId: "source_2", sourceKey: "partner" });
const { dependencies } = createDependencies({ authenticatePlatformLeadSourceCredential, ingestPlatformLead });
const app = buildApp(dependencies);
expect((await postLead(app, { company: "HiveGrid" })).status).toBe(201);
expect((await postLead(app, { company: "HiveGrid" })).status).toBe(201);
expect(fingerprints).toHaveLength(2);
expect(fingerprints[0]).not.toBe(fingerprints[1]);
});
test.each([
["missing", null],
["malformed", "short"],
])("rejects %s source credentials before source lookup", async (_case, credential) => {
const { dependencies, authenticatePlatformLeadSourceCredential, ingestPlatformLead } = createDependencies();
const response = await postLead(buildApp(dependencies), { company: "HiveGrid" }, { credential });
expect(response.status).toBe(401);
await expect(response.json()).resolves.toMatchObject({ error: { code: "unauthorized" } });
expect(authenticatePlatformLeadSourceCredential).not.toHaveBeenCalled();
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test("caps unauthenticated work before credential lookup and fails closed with retry headers", async () => {
const checkPreAuthRateLimit = vi.fn(async (_request: Request) => ({
allowed: false as const,
unavailable: false,
retryAfterSeconds: 13,
headers: { "Retry-After": "13", "X-RateLimit-Scope": "platform-lead-preauth-ip" },
}));
const { dependencies, authenticatePlatformLeadSourceCredential, ingestPlatformLead } = createDependencies({ checkPreAuthRateLimit });
const response = await postLead(buildApp(dependencies), { company: "HiveGrid" }, { credential: "invalid" });
expect(response.status).toBe(429);
expect(response.headers.get("retry-after")).toBe("13");
expect(response.headers.get("x-ratelimit-scope")).toBe("platform-lead-preauth-ip");
expect(authenticatePlatformLeadSourceCredential).not.toHaveBeenCalled();
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test("rejects an unknown or revoked source credential", async () => {
const authenticatePlatformLeadSourceCredential = vi.fn(async (_credential: string) => null);
const { dependencies, ingestPlatformLead } = createDependencies({ authenticatePlatformLeadSourceCredential });
const response = await postLead(buildApp(dependencies), { company: "HiveGrid" });
expect(response.status).toBe(401);
expect(authenticatePlatformLeadSourceCredential).toHaveBeenCalledWith(SOURCE_CREDENTIAL);
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test.each([
["missing", null],
["empty", " "],
["too long", "x".repeat(201)],
["control character", `submission_${String.fromCharCode(127)}`],
])("requires a valid Idempotency-Key when it is %s", async (_case, idempotencyKey) => {
const { dependencies, ingestPlatformLead } = createDependencies();
const response = await postLead(buildApp(dependencies), { company: "HiveGrid" }, { idempotencyKey });
expect(response.status).toBe(400);
await expect(response.json()).resolves.toMatchObject({ error: { code: "idempotency_key_required" } });
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test.each([
["invalid JSON", "{not-json"],
["missing usable contact or message data", { utmSource: "campaign" }],
["body-selected source", { company: "HiveGrid", source: "attacker-selected" }],
["unsupported metadata", { company: "HiveGrid", metadata: { rawPayload: "not allowed" } }],
])("rejects %s without echoing lead data", async (_case, body) => {
const { dependencies, ingestPlatformLead } = createDependencies();
const response = await postLead(buildApp(dependencies), body);
const responseText = await response.text();
expect(response.status).toBe(400);
expect(responseText).toContain("invalid_request");
expect(responseText).not.toContain("attacker-selected");
expect(responseText).not.toContain("rawPayload");
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test("requires an application/json request body", async () => {
const { dependencies, ingestPlatformLead } = createDependencies();
const response = await postLead(buildApp(dependencies), "company=HiveGrid", { contentType: "text/plain" });
expect(response.status).toBe(400);
await expect(response.json()).resolves.toMatchObject({ error: { code: "invalid_request" } });
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test("enforces the actual UTF-8 body limit even when the declared length is smaller", async () => {
const { dependencies, ingestPlatformLead } = createDependencies();
const response = await postLead(
buildApp(dependencies),
{ message: "x".repeat(PLATFORM_LEAD_JSON_BODY_LIMIT_BYTES) },
{ contentLength: "10" },
);
expect(response.status).toBe(413);
expect(response.headers.get(BODY_LIMIT_HEADER)).toBe(String(PLATFORM_LEAD_JSON_BODY_LIMIT_BYTES));
await expect(response.json()).resolves.toMatchObject({ error: { code: "body_too_large" } });
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test("returns source-specific 429 headers before payload parsing or persistence", async () => {
const checkSourceRateLimit = vi.fn(async (_source: PlatformLeadSourceAuthentication) => ({
allowed: false as const,
unavailable: false,
retryAfterSeconds: 17,
headers: {
"Retry-After": "17",
"X-RateLimit-Limit": "2",
"X-RateLimit-Remaining": "0",
"X-RateLimit-Reset": "1784203260",
"X-RateLimit-Scope": "platform-lead-source",
},
}));
const { dependencies, ingestPlatformLead } = createDependencies({ checkSourceRateLimit });
const response = await postLead(buildApp(dependencies), "{not-json");
expect(response.status).toBe(429);
expect(response.headers.get("retry-after")).toBe("17");
expect(response.headers.get("x-ratelimit-limit")).toBe("2");
await expect(response.json()).resolves.toMatchObject({
error: { code: "rate_limited", params: { retryAfterSeconds: 17 } },
});
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test("fails closed when the source rate-limit store is unavailable", async () => {
const checkSourceRateLimit = vi.fn(async (_source: PlatformLeadSourceAuthentication) => ({
allowed: false as const,
unavailable: true,
retryAfterSeconds: 60,
headers: { "Retry-After": "60" },
}));
const { dependencies, ingestPlatformLead } = createDependencies({ checkSourceRateLimit });
const response = await postLead(buildApp(dependencies), { company: "HiveGrid" });
expect(response.status).toBe(503);
expect(response.headers.get("retry-after")).toBe("60");
await expect(response.json()).resolves.toMatchObject({ error: { code: "rate_limit_unavailable" } });
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
test.each([
[new AdminLeadIngestionError("VALIDATION", "private validation detail"), 400, "invalid_request"],
[new AdminLeadIngestionError("AUTHENTICATION", "private auth detail"), 401, "unauthorized"],
[new AdminLeadIngestionError("SOURCE_DISABLED", "private source detail"), 401, "unauthorized"],
[new AdminLeadIngestionError("IDEMPOTENCY_IN_PROGRESS", "private replay detail"), 409, "idempotency_key_in_progress"],
[new Error("private persistence detail"), 503, "platform_lead_unavailable"],
])("maps domain failures to redacted API errors", async (error, status, code) => {
const ingestPlatformLead = vi.fn(async (_input: PlatformLeadS2SInput) => {
throw error;
});
const { dependencies } = createDependencies({ ingestPlatformLead });
const response = await postLead(buildApp(dependencies), { company: "HiveGrid" });
const responseText = await response.text();
expect(response.status).toBe(status);
expect(responseText).toContain(code);
expect(responseText).not.toContain(error.message);
});
test("supports a fail-closed rollback switch without source or persistence work", async () => {
process.env.PLATFORM_LEADS_INGRESS_ENABLED = "off";
const { dependencies, authenticatePlatformLeadSourceCredential, ingestPlatformLead } = createDependencies();
const response = await postLead(buildApp(dependencies), { company: "HiveGrid" });
expect(response.status).toBe(404);
expect(authenticatePlatformLeadSourceCredential).not.toHaveBeenCalled();
expect(ingestPlatformLead).not.toHaveBeenCalled();
});
});
describe("platform lead source rate limiter", () => {
test("applies the configured source limit without storing the raw source identity", async () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "platform-lead-rate-limit-test", adapter });
const checkSourceRateLimit = createPlatformLeadSourceRateLimiter({
getStore: () => store,
getKeySecret: () => "rate-limit-hmac-secret",
});
const first = await checkSourceRateLimit(SOURCE);
const second = await checkSourceRateLimit(SOURCE);
const third = await checkSourceRateLimit(SOURCE);
const storedKeys: string[] = [];
for await (const key of store.scan("*")) storedKeys.push(key);
expect(first).toMatchObject({ allowed: true, headers: { "X-RateLimit-Remaining": "1" } });
expect(second).toMatchObject({ allowed: true, headers: { "X-RateLimit-Remaining": "0" } });
expect(third).toMatchObject({ allowed: false, unavailable: false, headers: { "Retry-After": expect.any(String) } });
expect(storedKeys).toHaveLength(1);
expect(storedKeys.join("\n")).not.toContain(SOURCE.sourceId);
expect(storedKeys.join("\n")).not.toContain(SOURCE.sourceKey);
});
test("fails closed for invalid source configuration or unavailable shared storage", async () => {
const invalidSourceCheck = createPlatformLeadSourceRateLimiter({
getStore: () => createSharedStore({ namespace: "unused", adapter: new MemoryAdapter() }),
getKeySecret: () => "rate-limit-hmac-secret",
});
const unavailableStoreCheck = createPlatformLeadSourceRateLimiter({
getStore: () => {
throw new Error("store unavailable");
},
getKeySecret: () => "rate-limit-hmac-secret",
});
await expect(invalidSourceCheck({ ...SOURCE, rateLimitPerMinute: 0 })).resolves.toMatchObject({
allowed: false,
unavailable: true,
});
await expect(unavailableStoreCheck(SOURCE)).resolves.toMatchObject({ allowed: false, unavailable: true });
});
});
@@ -0,0 +1,339 @@
import { createHmac } from "node:crypto";
import {
AdminLeadIngestionError,
type PlatformLeadPayload,
type PlatformLeadSourceAuthentication,
} from "@hivegrid/db/platform-leads.server";
import { createFixedWindowRateLimiter } from "@hivegrid/shared-store";
import { Hono, type Context } from "hono";
import { z } from "zod";
import { getApiAppDependencies, type ApiAppDependencies } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { extractBearerToken } from "../auth.js";
import { getApiRuntimeConfig } from "../config.js";
import { createRequestFingerprint, type JsonValue } from "../idempotency/store.js";
import { BODY_LIMIT_HEADER, PLATFORM_LEAD_JSON_BODY_LIMIT_BYTES } from "../middleware/body-limit.js";
import { apiError } from "../middleware/error-envelope.js";
import {
checkPublicIngressRateLimit,
type PublicIngressRateLimitResult,
} from "../public-ingress-rate-limit.js";
import { getSharedStore } from "../shared-store.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
export const PLATFORM_LEAD_ROUTE = "/v1/platform/leads";
export const PLATFORM_LEAD_RATE_LIMIT_WINDOW_SECONDS = 60;
const PLATFORM_LEAD_CREDENTIAL_PATTERN = /^[A-Za-z0-9._~-]{32,512}$/u;
const PLATFORM_LEAD_IDEMPOTENCY_KEY_MAX_LENGTH = 200;
const PLATFORM_LEAD_METADATA_MAX_BYTES = 4_096;
const optionalText = (maxLength: number) =>
z.preprocess(
(value) => (typeof value === "string" && value.trim() === "" ? undefined : value),
z.string().trim().max(maxLength).nullable().optional(),
);
const metadataValueSchema = z.union([z.string().max(500), z.number().finite(), z.boolean(), z.null()]);
const platformLeadMetadataSchema = z
.object({
consent: metadataValueSchema.optional(),
formId: metadataValueSchema.optional(),
formName: metadataValueSchema.optional(),
legacyId: metadataValueSchema.optional(),
legacyStore: metadataValueSchema.optional(),
locale: metadataValueSchema.optional(),
productInterest: metadataValueSchema.optional(),
submissionId: metadataValueSchema.optional(),
})
.strict()
.superRefine((value, context) => {
if (Buffer.byteLength(JSON.stringify(value), "utf8") > PLATFORM_LEAD_METADATA_MAX_BYTES) {
context.addIssue({ code: z.ZodIssueCode.custom, message: "metadata is too large" });
}
});
export const platformLeadPayloadSchema = z
.object({
externalId: optionalText(256),
sourceDetail: optionalText(500),
firstName: optionalText(200),
lastName: optionalText(200),
email: optionalText(320),
phone: optionalText(100),
company: optionalText(300),
message: optionalText(8_000),
utmSource: optionalText(500),
utmMedium: optionalText(500),
utmCampaign: optionalText(500),
utmTerm: optionalText(500),
utmContent: optionalText(500),
referrer: optionalText(2_048),
landingPage: optionalText(2_048),
metadata: platformLeadMetadataSchema.nullable().optional(),
})
.strict()
.superRefine((value, context) => {
if (![value.email, value.phone, value.company, value.firstName, value.lastName, value.message].some(Boolean)) {
context.addIssue({
code: z.ZodIssueCode.custom,
message: "at least one contact or message field is required",
});
}
});
export type PlatformLeadSourceRateLimitResult =
| { allowed: true; headers: Record<string, string> }
| {
allowed: false;
unavailable: boolean;
retryAfterSeconds: number;
headers: Record<string, string>;
};
export type PlatformLeadRouteDependencies = Pick<
ApiAppDependencies,
"authenticatePlatformLeadSourceCredential" | "ingestPlatformLead"
> & {
checkPreAuthRateLimit(request: Request): Promise<PublicIngressRateLimitResult>;
checkSourceRateLimit(source: PlatformLeadSourceAuthentication): Promise<PlatformLeadSourceRateLimitResult>;
};
type PlatformLeadRateLimiterOptions = {
getStore?: typeof getSharedStore;
getKeySecret?: () => string;
};
export function createPlatformLeadSourceRateLimiter(options: PlatformLeadRateLimiterOptions = {}) {
const getStore = options.getStore ?? getSharedStore;
const getKeySecret = options.getKeySecret ?? (() => getApiRuntimeConfig().jwtSecret?.trim() ?? "");
const limiters = new Map<number, ReturnType<typeof createFixedWindowRateLimiter>>();
return async (source: PlatformLeadSourceAuthentication): Promise<PlatformLeadSourceRateLimitResult> => {
try {
if (!source.sourceId.trim() || !Number.isInteger(source.rateLimitPerMinute) || source.rateLimitPerMinute < 1) {
throw new Error("Platform lead source rate-limit configuration is invalid.");
}
const keySecret = getKeySecret();
if (!keySecret) {
throw new Error("Platform lead source rate-limit key secret is unavailable.");
}
let limiter = limiters.get(source.rateLimitPerMinute);
if (!limiter) {
limiter = createFixedWindowRateLimiter({
store: getStore(),
prefix: `platform-leads:source:${source.rateLimitPerMinute}`,
windowSeconds: PLATFORM_LEAD_RATE_LIMIT_WINDOW_SECONDS,
max: source.rateLimitPerMinute,
});
limiters.set(source.rateLimitPerMinute, limiter);
}
const sourceBucket = createHmac("sha256", keySecret).update(`v1\0${source.sourceId}`, "utf8").digest("hex");
const decision = await limiter.consume(sourceBucket);
const retryAfterSeconds = Math.max(1, Math.ceil((decision.resetAt.getTime() - Date.now()) / 1_000));
const headers = {
"X-RateLimit-Limit": String(source.rateLimitPerMinute),
"X-RateLimit-Remaining": String(Math.max(0, decision.remaining)),
"X-RateLimit-Reset": String(Math.ceil(decision.resetAt.getTime() / 1_000)),
"X-RateLimit-Scope": "platform-lead-source",
};
return decision.allowed
? { allowed: true, headers }
: {
allowed: false,
unavailable: false,
retryAfterSeconds,
headers: { ...headers, "Retry-After": String(retryAfterSeconds) },
};
} catch {
return {
allowed: false,
unavailable: true,
retryAfterSeconds: PLATFORM_LEAD_RATE_LIMIT_WINDOW_SECONDS,
headers: { "Retry-After": String(PLATFORM_LEAD_RATE_LIMIT_WINDOW_SECONDS) },
};
}
};
}
const checkDefaultSourceRateLimit = createPlatformLeadSourceRateLimiter();
export function registerPlatformLeadRoutes(app: Hono<ApiEnv>) {
app.post("/v1/platform/leads", (context) => postPlatformLeadRequest(context, defaultPlatformLeadRouteDependencies()));
}
export async function postPlatformLeadRequest(context: Context<ApiEnv>, dependencies: PlatformLeadRouteDependencies) {
if (isPlatformLeadIngressDisabled()) {
return apiError(context, 404, "not_found", "Endpoint not found.");
}
const preAuthRateLimit = await dependencies.checkPreAuthRateLimit(context.req.raw);
if (!preAuthRateLimit.allowed) {
applyRateLimitHeaders(context, preAuthRateLimit.headers);
return preAuthRateLimit.unavailable
? apiError(context, 503, "rate_limit_unavailable", "Platform lead intake is temporarily unavailable. Try again later.")
: apiError(context, 429, "rate_limited", "Too many platform lead requests. Try again later.", {
params: { retryAfterSeconds: preAuthRateLimit.retryAfterSeconds },
});
}
const sourceCredential = extractBearerToken(context.req.raw)?.trim() ?? "";
if (!PLATFORM_LEAD_CREDENTIAL_PATTERN.test(sourceCredential)) {
return apiError(context, 401, "unauthorized", "A valid platform lead source credential is required.");
}
let source: PlatformLeadSourceAuthentication | null;
try {
source = await dependencies.authenticatePlatformLeadSourceCredential(sourceCredential);
} catch (error) {
return handlePlatformLeadIngestionError(context, error);
}
if (!source) {
return apiError(context, 401, "unauthorized", "A valid platform lead source credential is required.");
}
const rateLimit = await dependencies.checkSourceRateLimit(source);
applyRateLimitHeaders(context, rateLimit.headers);
if (!rateLimit.allowed) {
return rateLimit.unavailable
? apiError(context, 503, "rate_limit_unavailable", "Platform lead intake is temporarily unavailable. Try again later.")
: apiError(context, 429, "rate_limited", "Too many platform lead requests. Try again later.", {
params: { retryAfterSeconds: rateLimit.retryAfterSeconds },
});
}
const idempotencyKey = normalizePlatformLeadIdempotencyKey(context.req.header("idempotency-key"));
if (!idempotencyKey) {
return apiError(context, 400, "idempotency_key_required", "A valid Idempotency-Key header is required.");
}
const contentType = context.req.header("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
if (contentType !== "application/json") {
return apiError(context, 400, "invalid_request", "Platform lead requests require an application/json body.");
}
const boundedBody = await readBoundedPlatformLeadBody(context.req.raw);
if (boundedBody.outcome === "too_large") {
context.header(BODY_LIMIT_HEADER, String(PLATFORM_LEAD_JSON_BODY_LIMIT_BYTES));
return apiError(context, 413, "body_too_large", "Request body is too large.");
}
if (boundedBody.outcome === "unreadable") {
return apiError(context, 400, "invalid_request", "Platform lead request body must be valid JSON.");
}
let rawBody: unknown;
try {
rawBody = JSON.parse(boundedBody.text);
} catch {
return apiError(context, 400, "invalid_request", "Platform lead request body must be valid JSON.");
}
const parsedPayload = platformLeadPayloadSchema.safeParse(rawBody);
if (!parsedPayload.success) {
return apiError(context, 400, "invalid_request", "Platform lead payload is invalid. Check the documented fields and try again.");
}
const payload = parsedPayload.data satisfies PlatformLeadPayload;
const requestFingerprint = createRequestFingerprint({
method: "POST",
route: PLATFORM_LEAD_ROUTE,
entityId: source.sourceId,
parsedBody: toJsonValue(payload),
});
try {
const result = await dependencies.ingestPlatformLead({
channel: "s2s",
sourceId: source.sourceId,
sourceCredential,
idempotencyKey,
requestFingerprint,
payload,
});
context.header("Idempotency-Replayed", result.outcome === "replayed" ? "true" : "false");
return context.json(result.lead, 201);
} catch (error) {
return handlePlatformLeadIngestionError(context, error);
}
}
function defaultPlatformLeadRouteDependencies(): PlatformLeadRouteDependencies {
const dependencies = getApiAppDependencies();
return {
authenticatePlatformLeadSourceCredential: dependencies.authenticatePlatformLeadSourceCredential,
ingestPlatformLead: dependencies.ingestPlatformLead,
checkPreAuthRateLimit: (request) =>
checkPublicIngressRateLimit("platform-lead-preauth-ip", getTrustedClientIp(request) || "unknown"),
checkSourceRateLimit: checkDefaultSourceRateLimit,
};
}
function normalizePlatformLeadIdempotencyKey(value: string | undefined) {
const normalized = value?.trim();
if (!normalized || normalized.length > PLATFORM_LEAD_IDEMPOTENCY_KEY_MAX_LENGTH || /[\u0000-\u001f\u007f]/u.test(normalized)) {
return null;
}
return normalized;
}
function handlePlatformLeadIngestionError(context: Context<ApiEnv>, error: unknown) {
if (error instanceof AdminLeadIngestionError) {
switch (error.code) {
case "VALIDATION":
return apiError(context, 400, "invalid_request", "Platform lead payload is invalid. Check the documented fields and try again.");
case "AUTHENTICATION":
case "SOURCE_DISABLED":
return apiError(context, 401, "unauthorized", "A valid, enabled platform lead source credential is required.");
case "IDEMPOTENCY_CONFLICT":
return apiError(context, 409, "idempotency_key_conflict", "Idempotency-Key was already used for a different platform lead request.");
case "IDEMPOTENCY_IN_PROGRESS":
return apiError(context, 409, "idempotency_key_in_progress", "A platform lead request with this Idempotency-Key is already being processed.");
}
}
return apiError(context, 503, "platform_lead_unavailable", "Platform lead intake is temporarily unavailable. Try again later.");
}
function applyRateLimitHeaders(context: Context<ApiEnv>, headers: Record<string, string>) {
for (const [name, value] of Object.entries(headers)) {
context.header(name, value);
}
}
function isPlatformLeadIngressDisabled() {
const value = process.env.PLATFORM_LEADS_INGRESS_ENABLED?.trim().toLowerCase();
return value === "0" || value === "false" || value === "off";
}
type BoundedPlatformLeadBody =
| { outcome: "ok"; text: string }
| { outcome: "too_large" }
| { outcome: "unreadable" };
async function readBoundedPlatformLeadBody(request: Request): Promise<BoundedPlatformLeadBody> {
if (!request.body) return { outcome: "ok", text: "" };
const reader = request.body.getReader();
const chunks: Uint8Array[] = [];
let totalBytes = 0;
try {
for (;;) {
const { done, value } = await reader.read();
if (done) break;
totalBytes += value.byteLength;
if (totalBytes > PLATFORM_LEAD_JSON_BODY_LIMIT_BYTES) {
await reader.cancel();
return { outcome: "too_large" };
}
chunks.push(value);
}
const bytes = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
return { outcome: "ok", text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
} catch {
return { outcome: "unreadable" };
} finally {
reader.releaseLock();
}
}
function toJsonValue(value: unknown): JsonValue {
return JSON.parse(JSON.stringify(value)) as JsonValue;
}
@@ -1,3 +1,5 @@
import { createHash } from "node:crypto";
import { formatTenantApiUsagePlanTitle, SUBSCRIPTION_FEATURE_LIMIT } from "@hivegrid/db/usage.server";
import { verifyPublicApiSecret, verifyPublicWebhookHmacWithPresentedSecret, type PublicWebhookPayload } from "@hivegrid/db/public-api.server";
import { Hono, type Context } from "hono";
@@ -5,12 +7,17 @@ import { Hono, type Context } from "hono";
import { extractApiKeyFromRequest } from "../auth.js";
import { getApiRuntimeConfig } from "../config.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
import { apiLogger } from "../logger.js";
import { apiError } from "../middleware/error-envelope.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import type { ApiEnv } from "../api-types.js";
import type { ApiAppDependencies } from "../app-dependencies.js";
import { getApiAppDependencies } from "../app-dependencies.js";
import { checkPublicApiRateLimit, checkPublicApiScopes, publicApiReadScopeForResource, type PublicApiRateLimitResult } from "../public-api/auth.js";
import { parsePublicApiListQuery, publicApiResources, type PublicApiResourceName } from "../public-api/resources.js";
import { createIdempotencyStore, type JsonValue, type StoredIdempotencyResponse } from "../idempotency/store.js";
const PUBLIC_WEBHOOK_REPLAY_TTL_MS = 10 * 60 * 1000;
type PublicApiRouteDependencies = Pick<
ApiAppDependencies,
@@ -22,9 +29,11 @@ type PublicApiRouteDependencies = Pick<
| "getTenantApiUsage"
| "listPublicApiResource"
| "findLegacyTenantByIdOrSlug"
| "resolvePublicWebhookRlsIdentity"
| "findPublicIncomingWebhookEndpoint"
| "createPublicWebhookIngestionLog"
| "ingestPublicLeadWebhook"
| "getIdempotencyClient"
>;
export function registerPublicApiReadRoutes(app: Hono<ApiEnv>) {
@@ -43,7 +52,7 @@ async function getPublicApiResourceRequest(c: Context<ApiEnv>, resource: PublicA
const startTime = performance.now();
const apiKeyValue = extractApiKeyFromRequest(c.req.raw, undefined);
if (!apiKeyValue) {
await createPublicApiErrorLog(c, dependencies, endpoint, "Missing API key", 401);
recordPublicApiPreAuthFailure(c, endpoint, "Missing API key", 401);
return apiError(c, 401, "unauthorized", "Valid API key credentials are required.");
}
@@ -51,104 +60,101 @@ async function getPublicApiResourceRequest(c: Context<ApiEnv>, resource: PublicA
allowPlaintextFallback: getApiRuntimeConfig().apiKeys.allowLegacyPlaintextFallback,
});
if (!apiKey) {
await createPublicApiErrorLog(c, dependencies, endpoint, "Invalid API key", 401);
recordPublicApiPreAuthFailure(c, endpoint, "Invalid API key", 401);
return apiError(c, 401, "unauthorized", "Valid API key credentials are required.");
}
const apiKeyLog = await dependencies.createLegacyApiKeyLog({
tenantId: apiKey.tenantId,
apiKeyId: apiKey.id,
endpoint,
ip: getClientIpAddress(c.req.raw) ?? "",
method: c.req.method,
params: serializeRequestSearchParams(c.req.raw),
alias: apiKey.alias,
tenantName: apiKey.tenant.name,
});
const fail = async (status: 400 | 402 | 403 | 429 | 500, code: string, message: string, params?: Record<string, string | number | boolean | null>) => {
await dependencies.setLegacyApiKeyLogStatus({ id: apiKeyLog.id, tenantId: apiKey.tenantId }, { status, error: message, startTime });
return params ? apiError(c, status, code, message, { params }) : apiError(c, status, code, message);
};
if (apiKey.tenant.deactivatedReason) {
return fail(403, "tenant_inactive", "Account is inactive.");
}
if (!apiKey.active) {
return fail(400, "api_key_inactive", "API key is inactive.");
}
if (apiKey.expires && apiKey.expires < new Date()) {
return fail(400, "api_key_expired", "API key is expired.");
}
const scopeCheck = checkPublicApiScopes(apiKey.scopes, [publicApiReadScopeForResource(resource)]);
if (!scopeCheck.ok) {
return fail(scopeCheck.status, scopeCheck.code, scopeCheck.message, { requiredScopes: scopeCheck.requiredScopes.join(",") });
}
const rateLimit = await checkPublicApiRateLimit({ apiKeyId: apiKey.id, tenantId: apiKey.tenantId });
applyRateLimitHeaders(c, rateLimit);
if (!rateLimit.allowed) {
return fail(rateLimit.status, rateLimit.code, rateLimit.message);
}
const query = parsePublicApiListQuery(publicApiResources[resource], new URL(c.req.url).searchParams);
if (!query.ok) {
return fail(400, query.code, query.message, query.params);
}
await dependencies
.createUniqueLegacyTenantIpAddress({
ip: getClientIpAddress(c.req.raw) ?? "Unknown",
fromUrl: endpoint,
return runWithVerifiedApiRlsContext({ tenantId: apiKey.tenantId }, async () => {
const apiKeyLog = await dependencies.createLegacyApiKeyLog({
tenantId: apiKey.tenantId,
apiKeyId: apiKey.id,
})
.catch(() => undefined);
const tenantSubscription = await dependencies.getTenantSubscription(apiKey.tenantId);
const usage = await dependencies.getTenantApiUsage(apiKey.tenantId, tenantSubscription);
if (!usage?.enabled) {
return fail(402, "payment_required", "Public API access is disabled or exhausted for this tenant.", {
plan: usage ? formatTenantApiUsagePlanTitle(usage) : "API access not included",
remaining: usage ? (usage.type === SUBSCRIPTION_FEATURE_LIMIT.included ? "included" : String(usage.remaining)) : "0",
endpoint,
ip: getClientIpAddress(c.req.raw) ?? "",
method: c.req.method,
params: serializeRequestSearchParams(c.req.raw),
alias: apiKey.alias,
tenantName: apiKey.tenant.name,
});
}
try {
const result = await dependencies.listPublicApiResource({ tenantId: apiKey.tenantId, resource, query: query.value });
await dependencies.setLegacyApiKeyLogStatus({ id: apiKeyLog.id, tenantId: apiKey.tenantId }, { status: 200, startTime });
return c.json({
data: result.data,
pageInfo: result.pageInfo,
meta: {
resource,
readOnly: true,
requestId: c.get("requestId"),
},
});
} catch {
return fail(500, "public_api_read_failed", "Public API read request failed.");
}
const fail = async (status: 400 | 402 | 403 | 429 | 500, code: string, message: string, params?: Record<string, string | number | boolean | null>) => {
await dependencies.setLegacyApiKeyLogStatus({ id: apiKeyLog.id, tenantId: apiKey.tenantId }, { status, error: message, startTime });
return params ? apiError(c, status, code, message, { params }) : apiError(c, status, code, message);
};
if (apiKey.tenant.deactivatedReason) {
return fail(403, "tenant_inactive", "Account is inactive.");
}
if (!apiKey.active) {
return fail(400, "api_key_inactive", "API key is inactive.");
}
if (apiKey.expires && apiKey.expires < new Date()) {
return fail(400, "api_key_expired", "API key is expired.");
}
const scopeCheck = checkPublicApiScopes(apiKey.scopes, [publicApiReadScopeForResource(resource)]);
if (!scopeCheck.ok) {
return fail(scopeCheck.status, scopeCheck.code, scopeCheck.message, { requiredScopes: scopeCheck.requiredScopes.join(",") });
}
const rateLimit = await checkPublicApiRateLimit({ apiKeyId: apiKey.id, tenantId: apiKey.tenantId });
applyRateLimitHeaders(c, rateLimit);
if (!rateLimit.allowed) {
return fail(rateLimit.status, rateLimit.code, rateLimit.message);
}
const query = parsePublicApiListQuery(publicApiResources[resource], new URL(c.req.url).searchParams);
if (!query.ok) {
return fail(400, query.code, query.message, query.params);
}
await dependencies
.createUniqueLegacyTenantIpAddress({
ip: getClientIpAddress(c.req.raw) ?? "Unknown",
fromUrl: endpoint,
tenantId: apiKey.tenantId,
apiKeyId: apiKey.id,
})
.catch(() => undefined);
const tenantSubscription = await dependencies.getTenantSubscription(apiKey.tenantId);
const usage = await dependencies.getTenantApiUsage(apiKey.tenantId, tenantSubscription);
if (!usage?.enabled) {
return fail(402, "payment_required", "Public API access is disabled or exhausted for this tenant.", {
plan: usage ? formatTenantApiUsagePlanTitle(usage) : "API access not included",
remaining: usage ? (usage.type === SUBSCRIPTION_FEATURE_LIMIT.included ? "included" : String(usage.remaining)) : "0",
});
}
try {
const result = await dependencies.listPublicApiResource({ tenantId: apiKey.tenantId, resource, query: query.value });
await dependencies.setLegacyApiKeyLogStatus({ id: apiKeyLog.id, tenantId: apiKey.tenantId }, { status: 200, startTime });
return c.json({
data: result.data,
pageInfo: result.pageInfo,
meta: {
resource,
readOnly: true,
requestId: c.get("requestId"),
},
});
} catch {
return fail(500, "public_api_read_failed", "Public API read request failed.");
}
});
}
async function createPublicApiErrorLog(
c: Context<ApiEnv>,
dependencies: Pick<PublicApiRouteDependencies, "createLegacyApiKeyLog">,
endpoint: string,
error: string,
status: number
) {
await dependencies.createLegacyApiKeyLog({
tenantId: null,
apiKeyId: null,
endpoint,
ip: getClientIpAddress(c.req.raw) ?? "",
method: c.req.method,
params: serializeRequestSearchParams(c.req.raw),
error,
status,
});
function recordPublicApiPreAuthFailure(c: Context<ApiEnv>, endpoint: string, error: string, status: number) {
apiLogger.warn(
{
requestId: c.get("requestId"),
endpoint,
method: c.req.method,
sourceIp: getClientIpAddress(c.req.raw) ?? "",
status,
reason: error,
},
"Public API credential rejected before tenant bootstrap"
);
}
function getClientIpAddress(request: Request) {
@@ -180,27 +186,58 @@ async function postPublicIncomingWebhookRequest(c: Context<ApiEnv>) {
if (!tenantParam || !slug) {
return apiError(c, 404, "not_found", "Webhook endpoint was not found.");
}
const tenant = await dependencies.findLegacyTenantByIdOrSlug(tenantParam);
if (!tenant) {
return apiError(c, 404, "not_found", "Webhook endpoint was not found.");
}
const endpoint = await dependencies.findPublicIncomingWebhookEndpoint({ tenantId: tenant.id, slug });
if (!endpoint || endpoint.status !== "active") {
await createWebhookIngestionFailure(dependencies, {
tenantId: tenant.id,
endpointId: endpoint?.id ?? null,
endpointSlug: slug,
authMode: endpoint?.authMode ?? null,
requestId: c.get("requestId"),
sourceIp: getClientIpAddress(c.req.raw),
status: 404,
result: "endpoint_not_found",
error: "Webhook endpoint was not found.",
});
const identity = await dependencies.resolvePublicWebhookRlsIdentity(tenantParam, slug).catch(() => null);
if (!identity) {
return apiError(c, 404, "not_found", "Webhook endpoint was not found.");
}
return runWithVerifiedApiRlsContext({ tenantId: identity.tenantId }, async () => {
const tenant = await dependencies.findLegacyTenantByIdOrSlug(tenantParam);
if (!tenant || tenant.id !== identity.tenantId) {
return apiError(c, 404, "not_found", "Webhook endpoint was not found.");
}
const endpoint = await dependencies.findPublicIncomingWebhookEndpoint({ tenantId: tenant.id, slug });
if (!endpoint || endpoint.id !== identity.resourceId || endpoint.status !== "active") {
return apiError(c, 404, "not_found", "Webhook endpoint was not found.");
}
const rawBody = await c.req.text();
const rawBody = await c.req.text();
const authResult = await authenticateIncomingWebhookRequest(c, endpoint, rawBody, dependencies);
if (!authResult.ok) {
if (authResult.rateLimit) {
applyRateLimitHeaders(c, authResult.rateLimit);
}
if (authResult.apiKeyLogId) {
await dependencies.setLegacyApiKeyLogStatus(
{ id: authResult.apiKeyLogId, tenantId: tenant.id },
{ status: authResult.status, error: authResult.message, startTime }
);
}
return apiError(c, authResult.status, authResult.code, authResult.message);
}
if (authResult.rateLimit) {
applyRateLimitHeaders(c, authResult.rateLimit);
}
const processAuthenticatedRequest = () => processAuthenticatedIncomingWebhookRequest({ c, dependencies, tenant, endpoint, rawBody, authResult, startTime });
if (endpoint.authMode === "hmac") {
return runReplayProtectedHmacWebhook({ c, dependencies, tenantId: tenant.id, endpointId: endpoint.id, rawBody }, processAuthenticatedRequest);
}
return processAuthenticatedRequest();
});
}
async function processAuthenticatedIncomingWebhookRequest(input: {
c: Context<ApiEnv>;
dependencies: PublicApiRouteDependencies;
tenant: { id: string };
endpoint: NonNullable<Awaited<ReturnType<PublicApiRouteDependencies["findPublicIncomingWebhookEndpoint"]>>>;
rawBody: string;
authResult: { ok: true; rateLimit?: PublicApiRateLimitResult; apiKeyLogId?: string };
startTime: number;
}) {
const { c, dependencies, tenant, endpoint, rawBody, authResult, startTime } = input;
const parsedBody = parseWebhookJsonBody(rawBody);
if (!parsedBody.ok) {
await createWebhookIngestionFailure(dependencies, {
@@ -231,37 +268,6 @@ async function postPublicIncomingWebhookRequest(c: Context<ApiEnv>) {
});
}
const authResult = await authenticateIncomingWebhookRequest(c, endpoint, rawBody, dependencies);
if (!authResult.ok) {
if (authResult.rateLimit) {
applyRateLimitHeaders(c, authResult.rateLimit);
}
if (authResult.apiKeyLogId) {
await dependencies.setLegacyApiKeyLogStatus(
{ id: authResult.apiKeyLogId, tenantId: tenant.id },
{ status: authResult.status, error: authResult.message, startTime }
);
}
await createWebhookIngestionFailure(dependencies, {
tenantId: tenant.id,
endpointId: endpoint.id,
endpointSlug: endpoint.slug,
authMode: endpoint.authMode,
requestId: c.get("requestId"),
sourceIp: getClientIpAddress(c.req.raw),
status: authResult.status,
result: authResult.code,
error: authResult.message,
});
return apiError(c, authResult.status, authResult.code, authResult.message);
}
if (authResult.rateLimit) {
applyRateLimitHeaders(c, authResult.rateLimit);
if (!authResult.rateLimit.allowed) {
return apiError(c, authResult.rateLimit.status, authResult.rateLimit.code, authResult.rateLimit.message);
}
}
try {
const result = await dependencies.ingestPublicLeadWebhook({
tenantId: tenant.id,
@@ -298,6 +304,72 @@ async function postPublicIncomingWebhookRequest(c: Context<ApiEnv>) {
}
}
class WebhookOperationResponseError extends Error {
constructor(readonly response: Response) {
super("Authenticated webhook operation returned a retryable server error.");
this.name = "WebhookOperationResponseError";
}
}
async function runReplayProtectedHmacWebhook(
input: {
c: Context<ApiEnv>;
dependencies: PublicApiRouteDependencies;
tenantId: string;
endpointId: string;
rawBody: string;
},
operation: () => Promise<Response>
): Promise<Response> {
const timestamp = input.c.req.header("X-HiveGrid-Timestamp") ?? "";
const signature = input.c.req.header("X-HiveGrid-Signature") ?? "";
const replayKey = createHash("sha256").update(`${input.endpointId}\0${timestamp}\0${signature}`).digest("hex");
const fingerprint = createHash("sha256").update(`${input.endpointId}\0${timestamp}\0${input.rawBody}`).digest("hex");
try {
const idempotencyStore = createIdempotencyStore({
client: input.dependencies.getIdempotencyClient(),
tenantId: input.tenantId,
maxAgeMs: PUBLIC_WEBHOOK_REPLAY_TTL_MS,
scope: `api:tenant:${input.tenantId}:incoming-webhook:${input.endpointId}`,
});
const result = await idempotencyStore.run(replayKey, fingerprint, async () => {
const response = await operation();
if (response.status >= 500) {
throw new WebhookOperationResponseError(response);
}
return serializeWebhookResponse(response);
});
if (result.type === "conflict") {
return apiError(input.c, 409, "webhook_replay_conflict", "Webhook replay fingerprint conflicts with the original request.");
}
if (result.type === "in_progress") {
return apiError(input.c, 409, "webhook_in_progress", "Webhook request is already being processed.");
}
return replayWebhookResponse(result.response);
} catch (error) {
if (error instanceof WebhookOperationResponseError) {
return error.response;
}
return apiError(input.c, 503, "webhook_replay_guard_unavailable", "Webhook replay protection is temporarily unavailable.");
}
}
async function serializeWebhookResponse(response: Response): Promise<StoredIdempotencyResponse> {
const body = (await response.clone().json()) as JsonValue;
return {
status: response.status,
headers: Object.fromEntries(response.headers.entries()),
body,
};
}
function replayWebhookResponse(response: StoredIdempotencyResponse): Response {
const headers = new Headers(response.headers);
headers.set("Content-Type", "application/json; charset=UTF-8");
return new Response(JSON.stringify(response.body), { status: response.status, headers });
}
async function authenticateIncomingWebhookRequest(
c: Context<ApiEnv>,
endpoint: Awaited<ReturnType<PublicApiRouteDependencies["findPublicIncomingWebhookEndpoint"]>> & {},
@@ -208,7 +208,11 @@ export function parseMaintenanceTake(body: unknown): ParseResult<number | undefi
}
export function createLoginRateLimitRequest(c: Context<ApiEnv>, account: string): LoginRateLimitRequest {
return { headers: c.req.raw.headers, remoteAddress: null, account };
return {
headers: c.req.raw.headers,
remoteAddress: c.env?.incoming?.socket.remoteAddress ?? null,
account,
};
}
export function createLoginRateLimitResponse(c: Context<ApiEnv>, block: LoginRateLimitBlocked) {
@@ -282,7 +286,7 @@ export class ApiRouteError extends Error {
export async function runIdempotentJson(
c: Context<ApiEnv>,
input: Parameters<typeof createRequestFingerprint>[0],
input: Parameters<typeof createRequestFingerprint>[0] & { tenantId: string },
operation: () => Promise<{ status: number; body: JsonValue }>,
) {
const idempotencyKey = c.req.header("idempotency-key");
@@ -291,7 +295,11 @@ export async function runIdempotentJson(
}
const fingerprint = createRequestFingerprint(input);
const idempotencyStore = createIdempotencyStore({ client: getApiAppDependencies().getIdempotencyClient(), scope: createApiIdempotencyScope(input) });
const idempotencyStore = createIdempotencyStore({
client: getApiAppDependencies().getIdempotencyClient(),
tenantId: input.tenantId,
scope: createApiIdempotencyScope(input),
});
const result = await idempotencyStore.run(idempotencyKey, fingerprint, async () => {
const response = await operation();
return {
@@ -1,9 +1,13 @@
import { randomBytes } from "node:crypto";
import { parseEnabledLocales } from "@hivegrid/i18n";
import { Hono, type Context } from "hono";
import { getApiAppDependencies } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { getApiRuntimeConfig } from "../config.js";
import { createOpenApiDocument } from "../openapi.js";
import { apiLogger } from "../logger.js";
import { escapeHtml } from "./shared.js";
import { checkCachedApiReadiness } from "../readiness-cache.js";
import { getApiDocsCopy } from "./api-docs-i18n.js";
function apiHealthResponse(c: Context<ApiEnv>) {
return c.json({
@@ -20,14 +24,19 @@ export function registerSystemRoutes(app: Hono<ApiEnv>) {
app.get("/readyz", async (c) => {
try {
await getApiAppDependencies().checkReadiness();
await checkCachedApiReadiness();
return c.json({
status: "ready",
service: "api",
revision: getApiRuntimeConfig().revision,
requestId: c.get("requestId"),
});
} catch {
} catch (error) {
const code = error && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : undefined;
apiLogger.error(
{ dependency: "database", error: { name: error instanceof Error ? error.name : "Error", ...(code ? { code } : {}) } },
"API readiness dependency unavailable"
);
return c.json(
{
status: "not_ready",
@@ -48,16 +57,41 @@ export function registerSystemRoutes(app: Hono<ApiEnv>) {
});
app.get("/v1/docs", (c) => {
const appName = getApiRuntimeConfig().appName;
const runtimeConfig = getApiRuntimeConfig();
const appName = runtimeConfig.appName;
const enabledLocales = parseEnabledLocales(process.env.I18N_ENABLED_LOCALES, {
allowReviewLocales: runtimeConfig.nodeEnv !== "production" || process.env.SENTRY_ENVIRONMENT?.trim().toLowerCase() === "staging",
});
const { locale, copy } = getApiDocsCopy(c.req.header("accept-language"), enabledLocales);
const browserCopy = JSON.stringify(copy).replaceAll("<", "\\u003c");
const nonce = randomBytes(18).toString("base64url");
c.header("cache-control", "no-store");
c.header("content-language", locale);
c.header(
"content-security-policy",
[
"default-src 'none'",
"base-uri 'none'",
"connect-src 'self'",
"font-src 'self'",
"form-action 'none'",
"frame-ancestors 'none'",
"img-src 'self' data:",
`script-src 'nonce-${nonce}' 'strict-dynamic'`,
"script-src-attr 'none'",
`style-src 'nonce-${nonce}'`,
"style-src-attr 'none'",
].join("; ")
);
return c.html(`<!doctype html>
<html lang="en">
<html lang="${locale}">
<head>
<meta charset="utf-8">
<title>API Documentation | ${escapeHtml(appName)}</title>
<meta property="og:title" content="API Documentation | ${escapeHtml(appName)}">
<title>${escapeHtml(copy.pageTitle)} | ${escapeHtml(appName)}</title>
<meta property="og:title" content="${escapeHtml(copy.pageTitle)} | ${escapeHtml(appName)}">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
<style nonce="${nonce}">
:root { color-scheme: dark; }
body { margin: 0; background: #0f172a; color: #e2e8f0; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
header { border-bottom: 1px solid #334155; padding: 20px 24px; }
@@ -89,25 +123,26 @@ export function registerSystemRoutes(app: Hono<ApiEnv>) {
</head>
<body>
<header>
<h1>API Documentation</h1>
<h1>${escapeHtml(copy.heading)}</h1>
<div class="toolbar">
<span class="muted">Swagger-style OpenAPI 3.1 explorer for the canonical API host.</span>
<span class="muted">${escapeHtml(copy.description)}</span>
<a href="/v1/openapi.json">OpenAPI JSON</a>
</div>
</header>
<main>
<nav class="nav" id="operation-nav" aria-label="API operations">
<span class="muted">Loading /v1/openapi.json...</span>
<nav class="nav" id="operation-nav" aria-label="${escapeHtml(copy.operationsLabel)}">
<span class="muted">${escapeHtml(copy.loadingSpec)}</span>
</nav>
<section>
<div id="operation-detail" class="operation"></div>
<details id="raw-panel">
<summary>Raw OpenAPI JSON</summary>
<summary>${escapeHtml(copy.rawSpec)}</summary>
<pre id="openapi-json"></pre>
</details>
</section>
</main>
<script>
<script nonce="${nonce}">
const copy = ${browserCopy};
const nav = document.getElementById("operation-nav");
const detail = document.getElementById("operation-detail");
const raw = document.getElementById("openapi-json");
@@ -154,19 +189,19 @@ export function registerSystemRoutes(app: Hono<ApiEnv>) {
const responses = Object.entries(entry.operation.responses ?? {});
detail.innerHTML = '<div class="operation-header"><span class="method">' + escapeText(entry.method) + '</span><span class="path">' + escapeText(entry.path) + '</span></div>'
+ '<div class="section grid">'
+ '<span class="badge">' + escapeText(entry.operation.operationId ?? "operation") + '</span>'
+ '<p>' + escapeText(entry.operation.description ?? "No description.") + '</p>'
+ '<h2>Parameters</h2>'
+ (parameters.length ? parameters.map((parameter) => '<div class="row"><code>' + escapeText(parameter.in) + ' ' + escapeText(parameter.name) + '</code><span>' + escapeText(parameter.description ?? "") + '</span></div>').join("") : '<p class="muted">No parameters.</p>')
+ '<h2>Responses</h2>'
+ (responses.length ? responses.map(([status, response]) => '<div class="row"><code>' + escapeText(status) + '</code><span>' + escapeText(response.description ?? "") + '</span></div>').join("") : '<p class="muted">No documented responses.</p>')
+ '<h2>Try request</h2>'
+ '<span class="badge">' + escapeText(entry.operation.operationId ?? copy.operationFallback) + '</span>'
+ '<p>' + escapeText(entry.operation.description ?? copy.noDescription) + '</p>'
+ '<h2>' + escapeText(copy.parameters) + '</h2>'
+ (parameters.length ? parameters.map((parameter) => '<div class="row"><code>' + escapeText(parameter.in) + ' ' + escapeText(parameter.name) + '</code><span>' + escapeText(parameter.description ?? "") + '</span></div>').join("") : '<p class="muted">' + escapeText(copy.noParameters) + '</p>')
+ '<h2>' + escapeText(copy.responses) + '</h2>'
+ (responses.length ? responses.map(([status, response]) => '<div class="row"><code>' + escapeText(status) + '</code><span>' + escapeText(response.description ?? "") + '</span></div>').join("") : '<p class="muted">' + escapeText(copy.noResponses) + '</p>')
+ '<h2>' + escapeText(copy.tryRequest) + '</h2>'
+ '<div class="try-grid">'
+ '<label>x-api-key<input id="try-api-key" type="password" autocomplete="off" placeholder="Paste tenant API key"></label>'
+ '<label>Query string<input id="try-query" type="text" placeholder="limit=10&fields=id,name"></label>'
+ '<button id="try-button" type="button">Send request</button>'
+ '<label>' + escapeText(copy.apiKeyLabel) + '<input id="try-api-key" type="password" autocomplete="off" placeholder="' + escapeText(copy.apiKeyPlaceholder) + '"></label>'
+ '<label>' + escapeText(copy.queryLabel) + '<input id="try-query" type="text" placeholder="' + escapeText(copy.queryPlaceholder) + '"></label>'
+ '<button id="try-button" type="button">' + escapeText(copy.sendRequest) + '</button>'
+ '</div>'
+ '<pre id="try-result" aria-live="polite">Response appears here.</pre>'
+ '<pre id="try-result" aria-live="polite">' + escapeText(copy.responsePlaceholder) + '</pre>'
+ '</div>';
document.getElementById("try-button")?.addEventListener("click", sendTryRequest);
}
@@ -185,7 +220,7 @@ export function registerSystemRoutes(app: Hono<ApiEnv>) {
}
const result = document.getElementById("try-result");
const apiKey = document.getElementById("try-api-key")?.value.trim() ?? "";
result.textContent = "Loading...";
result.textContent = copy.loading;
fetch(buildTryRequestUrl(currentEntry), {
method: currentEntry.method,
headers: apiKey ? { "x-api-key": apiKey } : {},
@@ -2,6 +2,7 @@ import { Hono, type Context } from "hono";
import { getApiAppDependencies } from "../app-dependencies.js";
import type { ApiEnv } from "../api-types.js";
import { apiError } from "../middleware/error-envelope.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import {
parseWorkspaceContextRevalidationPayload,
parseWorkspaceInviteAcceptPayload,
@@ -47,11 +48,13 @@ async function getWorkspaceAuthProvidersRequest(c: Context<ApiEnv>) {
}
try {
const providers = await getApiAppDependencies().listWorkspaceAuthProviders({
tenantId,
kind: parseWorkspaceAuthProviderKindQuery(c.req.query("kind")),
enabled: parseOptionalBooleanQuery(c.req.query("enabled")),
});
const providers = await runWithVerifiedApiRlsContext({ tenantId }, () =>
getApiAppDependencies().listWorkspaceAuthProviders({
tenantId,
kind: parseWorkspaceAuthProviderKindQuery(c.req.query("kind")),
enabled: parseOptionalBooleanQuery(c.req.query("enabled")),
})
);
return c.json({ providers: providers.map(toWorkspaceAuthProviderApiResponse) });
} catch {
@@ -61,7 +64,7 @@ async function getWorkspaceAuthProvidersRequest(c: Context<ApiEnv>) {
async function requireActiveWorkspaceTenant(c: Context<ApiEnv>, tenantId: string) {
try {
const tenant = await getApiAppDependencies().findLegacyTenantById(tenantId);
const tenant = await runWithVerifiedApiRlsContext({ tenantId }, () => getApiAppDependencies().findLegacyTenantById(tenantId));
if (!tenant) {
return apiError(c, 404, "tenant_not_found", "Workspace tenant was not found.");
}
@@ -92,7 +95,9 @@ async function postWorkspaceContextRevalidateRequest(c: Context<ApiEnv>) {
}
try {
const context = await getApiAppDependencies().revalidateWorkspaceContext({ tenantId, userId: payload.value.userId });
const context = await runWithVerifiedApiRlsContext({ tenantId, userId: payload.value.userId }, () =>
getApiAppDependencies().revalidateWorkspaceContext({ tenantId, userId: payload.value.userId })
);
return c.json({
context: {
valid: context.valid,
@@ -122,11 +127,13 @@ async function getWorkspaceInvitesRequest(c: Context<ApiEnv>) {
}
try {
const invites = await getApiAppDependencies().listWorkspaceInvites({
tenantId,
status: parseWorkspaceInviteStatusQuery(c.req.query("status")),
email: c.req.query("email"),
});
const invites = await runWithVerifiedApiRlsContext({ tenantId }, () =>
getApiAppDependencies().listWorkspaceInvites({
tenantId,
status: parseWorkspaceInviteStatusQuery(c.req.query("status")),
email: c.req.query("email"),
})
);
return c.json({ invites: invites.map(toWorkspaceInviteApiResponse) });
} catch {
@@ -156,14 +163,16 @@ async function postWorkspaceInviteRequest(c: Context<ApiEnv>) {
}
try {
const invite = await getApiAppDependencies().createWorkspaceInvite({
tenantId,
email: payload.value.email,
firstName: payload.value.firstName,
lastName: payload.value.lastName,
type: payload.value.type,
expiresAt: payload.value.expiresAt ? new Date(payload.value.expiresAt) : null,
});
const invite = await runWithVerifiedApiRlsContext({ tenantId }, () =>
getApiAppDependencies().createWorkspaceInvite({
tenantId,
email: payload.value.email,
firstName: payload.value.firstName,
lastName: payload.value.lastName,
type: payload.value.type,
expiresAt: payload.value.expiresAt ? new Date(payload.value.expiresAt) : null,
})
);
return c.json({ invite: toWorkspaceInviteApiResponse(invite), token: invite.token }, 201);
} catch (error) {
@@ -197,12 +206,15 @@ async function postWorkspaceInviteAcceptRequest(c: Context<ApiEnv>) {
}
try {
const invite = await getApiAppDependencies().acceptWorkspaceInvite({
tenantId,
inviteId,
token: payload.value.token,
acceptedByUserId: payload.value.userId ?? "",
});
const acceptedByUserId = payload.value.userId ?? "";
const invite = await runWithVerifiedApiRlsContext({ tenantId }, () =>
getApiAppDependencies().acceptWorkspaceInvite({
tenantId,
inviteId,
token: payload.value.token,
acceptedByUserId,
})
);
return c.json({ invite: toWorkspaceInviteApiResponse(invite) });
} catch (error) {
@@ -233,11 +245,14 @@ async function postWorkspaceInviteRevokeRequest(c: Context<ApiEnv>) {
}
try {
const invite = await getApiAppDependencies().revokeWorkspaceInvite({
tenantId,
inviteId,
revokedByUserId: payload.value.revokedByUserId ?? "",
});
const revokedByUserId = payload.value.revokedByUserId ?? "";
const invite = await runWithVerifiedApiRlsContext({ tenantId }, () =>
getApiAppDependencies().revokeWorkspaceInvite({
tenantId,
inviteId,
revokedByUserId,
})
);
return c.json({ invite: toWorkspaceInviteApiResponse(invite) });
} catch (error) {
return handleWorkspaceInviteError(c, error);
@@ -65,6 +65,10 @@ describe("readApiSentryConfig", () => {
it("forwards the release tag", () => {
expect(readApiSentryConfig({ SENTRY_RELEASE: "abc123" }).release).toBe("abc123");
});
it("falls back to the immutable image revision when SENTRY_RELEASE is empty", () => {
expect(readApiSentryConfig({ SENTRY_RELEASE: "", APP_REVISION: "sha-api" }).release).toBe("sha-api");
});
});
describe("initApiSentry", () => {
@@ -41,7 +41,7 @@ export function readApiSentryConfig(env: NodeJS.ProcessEnv = process.env): ApiSe
return {
dsn: env.SENTRY_DSN_API || undefined,
environment: env.SENTRY_ENVIRONMENT || nodeEnv || undefined,
release: env.SENTRY_RELEASE || undefined,
release: env.SENTRY_RELEASE || env.APP_REVISION || undefined,
tracesSampleRate: parseSampleRate(env.SENTRY_TRACES_SAMPLE_RATE, tracesDefault),
profilesSampleRate: parseSampleRate(env.SENTRY_PROFILES_SAMPLE_RATE, DEFAULT_PROFILES_SAMPLE_RATE),
};
@@ -5,18 +5,36 @@
// unset, so this contract is safe in every environment.
import "./otel.js";
import { createServer, type Server } from "node:http";
import { serve } from "@hono/node-server";
import { app } from "./app.js";
import { getApiRuntimeConfig } from "./config.js";
import { apiLogger } from "./logger.js";
import { getSharedStore } from "./shared-store.js";
import { hardenApiHttpServer, removeWebSessionCookie } from "./http-server.js";
import { assertRlsRuntimeReady } from "@hivegrid/db/rls-runtime-readiness.server";
import { attachChatGateway } from "./chat/gateway.js";
serve(
// Resolve shared infrastructure before binding a port. In production the
// shared-store factory rejects a missing REDIS_URL instead of silently using
// process-local state for authentication limits and caches.
getSharedStore();
const rlsReadiness = await assertRlsRuntimeReady();
if (!rlsReadiness.ready) {
apiLogger.warn({ diagnostics: rlsReadiness.diagnostics }, "RLS runtime is running in audit mode with failed checks");
}
const server = serve(
{
fetch: app.fetch,
fetch: (request, env) => app.fetch(removeWebSessionCookie(request), env),
port: getApiRuntimeConfig().listen.port,
createServer,
},
(info) => {
apiLogger.info({ port: info.port }, "API listening");
},
}
);
const httpServer = hardenApiHttpServer(server as Server);
attachChatGateway(httpServer);
@@ -1,6 +1,11 @@
import { afterEach, describe, expect, test, vi } from "vitest";
import { __resetSharedStoreForTests, __setSharedStoreFactoryForTests, getSharedStore } from "./shared-store.js";
import {
__resetSharedStoreForTests,
__setSharedStoreFactoryForTests,
getCrossAppCacheStore,
getSharedStore,
} from "./shared-store.js";
afterEach(() => {
__resetSharedStoreForTests();
@@ -50,4 +55,12 @@ describe("api shared-store singleton", () => {
if (originalRedisUrl !== undefined) process.env.REDIS_URL = originalRedisUrl;
}
});
test("binds cross-app cache traffic to the shared namespace and adapter", () => {
const local = getSharedStore();
const crossApp = getCrossAppCacheStore();
expect(crossApp.namespace).toBe("cross-app-cache");
expect(crossApp.adapter).toBe(local.adapter);
expect(getCrossAppCacheStore()).toBe(crossApp);
});
});
@@ -7,6 +7,7 @@ import { createSharedStore, type SharedStore } from "@hivegrid/shared-store";
* is reused across the API lifetime.
*/
let cachedStore: SharedStore | null = null;
let crossAppCacheStore: SharedStore | null = null;
let factory: () => SharedStore = () => createSharedStore({ namespace: "api", redisUrl: process.env.REDIS_URL });
export function getSharedStore(): SharedStore {
@@ -16,6 +17,18 @@ export function getSharedStore(): SharedStore {
return cachedStore;
}
/**
* Shared namespace for cache invalidations exchanged with other apps. It
* reuses this process's adapter/connection while making the wire channel
* independent from the app-local `api` namespace.
*/
export function getCrossAppCacheStore(): SharedStore {
if (crossAppCacheStore === null) {
crossAppCacheStore = createSharedStore({ namespace: "cross-app-cache", adapter: getSharedStore().adapter });
}
return crossAppCacheStore;
}
/**
* Test seam: override the factory and clear the cached instance. Tests
* call this to inject a SharedStore that uses an in-memory adapter or a
@@ -24,10 +37,12 @@ export function getSharedStore(): SharedStore {
export function __setSharedStoreFactoryForTests(next: () => SharedStore): void {
factory = next;
cachedStore = null;
crossAppCacheStore = null;
}
/** Test seam: reset to the default factory and drop the cached instance. */
export function __resetSharedStoreForTests(): void {
factory = () => createSharedStore({ namespace: "api", redisUrl: process.env.REDIS_URL });
cachedStore = null;
crossAppCacheStore = null;
}
@@ -13,6 +13,7 @@ const baseConfig = {
webAppHost: "app.localhost:3000",
adminAppHost: "admin.localhost:3000",
apiHost: "api.localhost:3000",
portalAppHost: "portal.localhost:3000",
protocol: "http",
},
origins: {},
@@ -13,6 +13,7 @@ const baseConfig = {
webAppHost: "app.localhost:3000",
adminAppHost: "admin.localhost:3000",
apiHost: "api.localhost:3000",
portalAppHost: "portal.localhost:3000",
protocol: "http",
},
origins: {},
@@ -3,26 +3,22 @@ import { createHash, createHmac } from "node:crypto";
import {
StorageAdapterError,
createS3SignedUrlAdapter,
createS3StorageAdapter,
type CreateSignedDownloadUrlInput,
type S3StorageAdapterConfig,
type SignedDownloadSignerInput,
type SignedDownloadUrlResult,
type StorageAdapter,
type UploadBody,
} from "@hivegrid/storage";
import { getApiRuntimeConfig } from "./config.js";
/**
* Caches the per-config S3 storage adapter, signed-URL adapter and the per-day
* Caches the per-config signed-URL adapter and the per-day
* SigV4 signing key to avoid reconstructing them on every hot-path call.
*
* Cache key intentionally hashes the secret access key (never stores it raw)
* and includes endpoint/region/accessKeyId/forcePathStyle so a credential
* rotation transparently misses the cache and rebuilds the adapter.
*/
const storageAdapterCache = new Map<string, StorageAdapter>();
const signedUrlAdapterCache = new Map<string, ReturnType<typeof createS3SignedUrlAdapter>>();
const signingKeyCache = new Map<string, Buffer>();
@@ -44,16 +40,6 @@ function storageAdapterCacheKey(config: S3StorageAdapterConfig): string {
.digest("hex");
}
function getCachedStorageAdapter(config: S3StorageAdapterConfig): StorageAdapter {
const key = storageAdapterCacheKey(config);
let adapter = storageAdapterCache.get(key);
if (!adapter) {
adapter = createS3StorageAdapter(config);
storageAdapterCache.set(key, adapter);
}
return adapter;
}
function getCachedSignedUrlAdapter(config: S3StorageAdapterConfig) {
const key = storageAdapterCacheKey(config);
let adapter = signedUrlAdapterCache.get(key);
@@ -75,7 +61,6 @@ function getCachedSignedUrlAdapter(config: S3StorageAdapterConfig) {
/** Test-only: drop cached adapters and signing keys. */
export function resetStorageCachesForTests() {
storageAdapterCache.clear();
signedUrlAdapterCache.clear();
signingKeyCache.clear();
}
@@ -83,7 +68,6 @@ export function resetStorageCachesForTests() {
/** Test-only: inspect cache sizes for assertions. */
export function storageCacheStatsForTests() {
return {
adapters: storageAdapterCache.size,
signedUrlAdapters: signedUrlAdapterCache.size,
signingKeys: signingKeyCache.size,
};
@@ -104,28 +88,6 @@ function createStorageAdapterConfig(bucket: string): S3StorageAdapterConfig {
};
}
export async function createStorageFile(
bucketId: string,
path: string,
file: UploadBody,
contentType?: string,
): Promise<{
id: string;
publicUrl: string | null;
}> {
const adapter = getCachedStorageAdapter(createStorageAdapterConfig(bucketId));
const createdFile = await adapter.putObject({
key: path,
body: file,
contentType,
});
return {
id: createdFile.key,
publicUrl: createdFile.publicUrl,
};
}
export type CreateStorageSignedDownloadUrlInput = CreateSignedDownloadUrlInput;
export type StorageSignedDownloadUrlResult = Pick<SignedDownloadUrlResult, "url" | "method" | "expiresAt" | "expiresInSeconds" | "headers">;
@@ -0,0 +1,98 @@
import { Hono } from "hono";
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { ApiEnv } from "../api-types.js";
import {
postAdminAircallWebhookRequest,
type AdminAircallWebhookRouteDependencies,
} from "./admin-aircall-webhook-route.js";
function dependencies(): AdminAircallWebhookRouteDependencies {
return {
checkClientRateLimit: vi.fn(async () => true),
checkConnectionRateLimit: vi.fn(async () => true),
resolveIdentity: vi.fn(async () => ({
resourceId: "phone-connection-1",
userId: "admin-1",
})),
process: vi.fn(async () => undefined),
};
}
function buildApp(deps: AdminAircallWebhookRouteDependencies) {
const app = new Hono<ApiEnv>();
app.post("/v1/webhooks/admin-telephony/aircall", (c) =>
postAdminAircallWebhookRequest(c, deps)
);
return app;
}
const payload = JSON.stringify({
token: "provider-body-token",
resource: "call",
event: "call.created",
timestamp: 1_785_321_000,
data: { id: 123 },
});
describe("POST /v1/webhooks/admin-telephony/aircall", () => {
let deps: AdminAircallWebhookRouteDependencies;
beforeEach(() => {
deps = dependencies();
});
it("resolves only the token hash and processes under the resolved admin identity", async () => {
const response = await buildApp(deps).request(
"/v1/webhooks/admin-telephony/aircall",
{ method: "POST", body: payload }
);
expect(response.status).toBe(202);
expect(deps.resolveIdentity).toHaveBeenCalledWith(
expect.stringMatching(/^[a-f0-9]{64}$/u)
);
expect(deps.process).toHaveBeenCalledWith({
phoneConnectionId: "phone-connection-1",
adminUserId: "admin-1",
payload: JSON.parse(payload),
});
expect(JSON.stringify(vi.mocked(deps.resolveIdentity).mock.calls)).not
.toContain("provider-body-token");
});
it("neutral-acks malformed and unknown tokens without disclosing connection state", async () => {
const malformed = await buildApp(deps).request(
"/v1/webhooks/admin-telephony/aircall",
{ method: "POST", body: "{" }
);
expect(malformed.status).toBe(202);
expect(deps.resolveIdentity).not.toHaveBeenCalled();
vi.mocked(deps.resolveIdentity).mockResolvedValueOnce(null);
const unknown = await buildApp(deps).request(
"/v1/webhooks/admin-telephony/aircall",
{ method: "POST", body: payload }
);
expect(unknown.status).toBe(202);
expect(deps.process).not.toHaveBeenCalled();
});
it("returns a neutral retryable response for throttling and transient processing failures", async () => {
vi.mocked(deps.checkConnectionRateLimit).mockResolvedValueOnce(false);
const throttled = await buildApp(deps).request(
"/v1/webhooks/admin-telephony/aircall",
{ method: "POST", body: payload }
);
expect(throttled.status).toBe(503);
vi.mocked(deps.process).mockRejectedValueOnce(
new Error("database unavailable")
);
const failed = await buildApp(deps).request(
"/v1/webhooks/admin-telephony/aircall",
{ method: "POST", body: payload }
);
expect(failed.status).toBe(503);
});
});
@@ -0,0 +1,228 @@
import { createHash, createHmac } from "node:crypto";
import { getDbClient } from "@hivegrid/db/client.server";
import { sealAdminConnectionCredentials } from "@hivegrid/db/crypto/admin-connection-envelope.server";
import { resolveAdminAircallWebhookRlsIdentity } from "@hivegrid/db/rls-resolvers.server";
import {
AdminTelephonyRecordingError,
createPrismaAdminTelephonyRecordingRepository,
} from "@hivegrid/db/admin-telephony-recordings.server";
import {
createPrismaAdminTelephonyRepository,
} from "@hivegrid/db/admin-telephony.server";
import {
parseAircallWebhookEvent,
} from "@hivegrid/integrations";
import { processVerifiedAdminTelephonyEvent } from "@hivegrid/integrations/admin-telephony-worker.server";
import { createFixedWindowRateLimiter } from "@hivegrid/shared-store";
import type { Context } from "hono";
import type { ApiEnv } from "../api-types.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { getSharedStore } from "../shared-store.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
const MAX_BODY_BYTES = 256 * 1_024;
const MAX_TOKEN_BYTES = 2_048;
const RATE_LIMIT_WINDOW_SECONDS = 60;
const RATE_LIMIT_PER_CLIENT = 1_200;
const RATE_LIMIT_PER_CONNECTION = 600;
export type AdminAircallWebhookRouteDependencies = {
readonly checkClientRateLimit: (request: Request) => Promise<boolean>;
readonly checkConnectionRateLimit: (tokenHash: string) => Promise<boolean>;
readonly resolveIdentity: (
tokenHash: string
) => Promise<{ resourceId: string; userId: string } | null>;
readonly process: (input: {
phoneConnectionId: string;
adminUserId: string;
payload: unknown;
}) => Promise<void>;
};
export async function postAdminAircallWebhookRequest(
c: Context<ApiEnv>,
dependencies: AdminAircallWebhookRouteDependencies =
defaultAdminAircallWebhookDependencies()
) {
try {
if (!(await dependencies.checkClientRateLimit(c.req.raw))) {
return neutral(c, 503);
}
} catch {
return neutral(c, 503);
}
const payload = await readBoundedJson(c.req.raw);
const token = readWebhookToken(payload);
if (!token) return neutral(c);
const tokenHash = createHash("sha256").update(token, "utf8").digest("hex");
try {
if (!(await dependencies.checkConnectionRateLimit(tokenHash))) {
return neutral(c, 503);
}
const identity = await dependencies.resolveIdentity(tokenHash);
if (!identity) return neutral(c);
await dependencies.process({
phoneConnectionId: identity.resourceId,
adminUserId: identity.userId,
payload,
});
} catch {
// A non-2xx response asks Aircall to retry. Domain writes are idempotent.
return neutral(c, 503);
}
return neutral(c);
}
function defaultAdminAircallWebhookDependencies(): AdminAircallWebhookRouteDependencies {
return {
checkClientRateLimit: async (request) => {
const secret =
process.env.SESSION_SECRET?.trim() ??
process.env.CRYPTO_SECRET?.trim();
if (!secret) throw new Error("admin_aircall_rate_limit_unavailable");
const clientKey = createHmac("sha256", secret)
.update(getTrustedClientIp(request) || "unknown", "utf8")
.digest("hex");
const limiter = createFixedWindowRateLimiter({
store: getSharedStore(),
prefix: "admin-aircall-webhook-client",
windowSeconds: RATE_LIMIT_WINDOW_SECONDS,
max: RATE_LIMIT_PER_CLIENT,
});
return (await limiter.consume(clientKey)).allowed;
},
checkConnectionRateLimit: async (tokenHash) => {
const limiter = createFixedWindowRateLimiter({
store: getSharedStore(),
prefix: "admin-aircall-webhook-connection",
windowSeconds: RATE_LIMIT_WINDOW_SECONDS,
max: RATE_LIMIT_PER_CONNECTION,
});
return (await limiter.consume(tokenHash)).allowed;
},
resolveIdentity: resolveAdminAircallWebhookRlsIdentity,
process: processAdminAircallPayload,
};
}
async function processAdminAircallPayload(input: {
phoneConnectionId: string;
adminUserId: string;
payload: unknown;
}) {
const normalized = parseAircallWebhookEvent(input.payload);
if (!normalized.ok) return;
await runWithVerifiedApiRlsContext(
{ userId: input.adminUserId },
async () => {
const db = getDbClient();
const phoneConnection = await db.adminPhoneConnection.findFirst({
where: {
id: input.phoneConnectionId,
adminUserId: input.adminUserId,
archivedAt: null,
connection: {
provider: "aircall",
capability: "telephony",
status: { in: ["active", "degraded"] },
archivedAt: null,
},
},
select: { id: true },
});
if (!phoneConnection) return;
await processVerifiedAdminTelephonyEvent({
phoneConnectionId: phoneConnection.id,
adminUserId: input.adminUserId,
event: normalized.event,
repository: createPrismaAdminTelephonyRepository(db),
queueRecording: async (recording) => {
const source = await sealAdminConnectionCredentials(
recording.providerRecordingUrl
);
try {
await createPrismaAdminTelephonyRecordingRepository(db).queue({
adminUserId: recording.adminUserId,
callSessionId: recording.callSessionId,
source,
now: recording.occurredAt,
actor: {
adminUserId: recording.adminUserId,
reason: "Verifizierte Aircall-Aufzeichnung vormerken",
},
});
} catch (error) {
if (
error instanceof AdminTelephonyRecordingError &&
[
"recording_disabled",
"recording_policy_incomplete",
"recording_consent_not_confirmed",
].includes(error.code)
) {
return;
}
throw error;
}
},
});
}
);
}
function neutral(c: Context<ApiEnv>, status: 202 | 503 = 202) {
return c.body(null, status);
}
async function readBoundedJson(request: Request): Promise<unknown | null> {
const contentLength = request.headers.get("content-length");
if (contentLength !== null) {
const parsed = Number(contentLength);
if (
!Number.isSafeInteger(parsed) ||
parsed < 0 ||
parsed > MAX_BODY_BYTES
) {
return null;
}
}
if (!request.body) return null;
const reader = request.body.getReader();
const decoder = new TextDecoder();
let totalBytes = 0;
let text = "";
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
totalBytes += value.byteLength;
if (totalBytes > MAX_BODY_BYTES) {
await reader.cancel();
return null;
}
text += decoder.decode(value, { stream: true });
}
text += decoder.decode();
return JSON.parse(text) as unknown;
} catch {
return null;
} finally {
reader.releaseLock();
}
}
function readWebhookToken(payload: unknown): string | null {
if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
return null;
}
const token = (payload as Record<string, unknown>).token;
if (
typeof token !== "string" ||
token.length === 0 ||
Buffer.byteLength(token, "utf8") > MAX_TOKEN_BYTES
) {
return null;
}
return token;
}
@@ -0,0 +1,131 @@
import { Hono } from "hono";
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { ApiEnv } from "../api-types.js";
import { postAircallWebhookRequest, type AircallWebhookRouteDependencies } from "./aircall-webhook-route.js";
const event = {
provider: "aircall",
providerEvent: "call.created",
type: "created" as const,
dedupeKey: "aircall:call.created:123:1:-",
providerCallId: "123",
occurredAtIso: "2026-07-15T10:00:00.000Z",
direction: "inbound" as const,
status: "ringing",
externalNumber: "+49301234567",
lineId: "1",
lineNumber: "+49309999999",
providerUserId: null,
providerUserEmail: null,
startedAtIso: "2026-07-15T10:00:00.000Z",
answeredAtIso: null,
endedAtIso: null,
durationSeconds: null,
missed: false,
missedReason: null,
recordingUrl: null,
voicemailUrl: null,
};
function dependencies(): AircallWebhookRouteDependencies {
return {
checkClientRateLimit: vi.fn(async () => true),
checkConnectionRateLimit: vi.fn(async () => true),
authenticateAndNormalize: vi.fn(async () => ({ tenantId: "tenant-1", connectionId: "connection-1", event })),
persistEvent: vi.fn(async () => ({ eventId: "event-1" })),
enqueue: vi.fn(async () => undefined),
};
}
function buildApp(deps: AircallWebhookRouteDependencies) {
const app = new Hono<ApiEnv>();
app.post("/v1/webhooks/telephony/aircall", (c) => postAircallWebhookRequest(c, deps));
return app;
}
function requestBody(overrides: Record<string, unknown> = {}) {
return JSON.stringify({ token: "raw-provider-token", resource: "call", event: "call.created", data: { id: 123 }, ...overrides });
}
describe("POST /v1/webhooks/telephony/aircall", () => {
let deps: AircallWebhookRouteDependencies;
beforeEach(() => {
deps = dependencies();
});
it("rate-limits before parsing, authenticates by token hash and enqueues only persisted ids", async () => {
const response = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
expect(response.status).toBe(202);
expect(deps.checkClientRateLimit).toHaveBeenCalledOnce();
expect(deps.checkConnectionRateLimit).toHaveBeenCalledWith(expect.stringMatching(/^[a-f0-9]{64}$/u));
expect(deps.authenticateAndNormalize).toHaveBeenCalledWith(
expect.stringMatching(/^[a-f0-9]{64}$/u),
expect.objectContaining({ token: "raw-provider-token" }),
);
expect(deps.persistEvent).toHaveBeenCalledWith({ tenantId: "tenant-1", connectionId: "connection-1", event });
expect(deps.enqueue).toHaveBeenCalledWith({ tenantId: "tenant-1", connectionId: "connection-1", eventId: "event-1" });
expect(JSON.stringify(vi.mocked(deps.persistEvent).mock.calls)).not.toContain("raw-provider-token");
expect(await response.text()).toBe("");
});
it("neutral-acks malformed and unknown requests but keeps throttled deliveries retryable", async () => {
const malformed = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: "{" });
expect(malformed.status).toBe(202);
expect(deps.authenticateAndNormalize).not.toHaveBeenCalled();
vi.mocked(deps.authenticateAndNormalize).mockResolvedValueOnce(null);
const unknown = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
expect(unknown.status).toBe(202);
expect(deps.persistEvent).not.toHaveBeenCalled();
vi.mocked(deps.checkClientRateLimit).mockResolvedValueOnce(false);
const limited = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
expect(limited.status).toBe(503);
expect(deps.authenticateAndNormalize).toHaveBeenCalledTimes(1);
vi.mocked(deps.checkConnectionRateLimit).mockResolvedValueOnce(false);
const connectionLimited = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
expect(connectionLimited.status).toBe(503);
expect(deps.authenticateAndNormalize).toHaveBeenCalledTimes(1);
});
it("returns a retryable neutral 503 when rate-limit storage, persistence or queueing fails", async () => {
vi.mocked(deps.checkClientRateLimit).mockRejectedValueOnce(new Error("redis unavailable"));
const rateLimitFailure = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
expect(rateLimitFailure.status).toBe(503);
vi.mocked(deps.persistEvent).mockRejectedValueOnce(new Error("database unavailable"));
const databaseFailure = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
expect(databaseFailure.status).toBe(503);
vi.mocked(deps.enqueue).mockRejectedValueOnce(new Error("queue unavailable"));
const queueFailure = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
expect(queueFailure.status).toBe(503);
});
it("re-enqueues the persisted event id when Aircall retries after a queue outage", async () => {
vi.mocked(deps.enqueue).mockRejectedValueOnce(new Error("queue unavailable"));
const first = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
const retry = await buildApp(deps).request("/v1/webhooks/telephony/aircall", { method: "POST", body: requestBody() });
expect(first.status).toBe(503);
expect(retry.status).toBe(202);
expect(deps.persistEvent).toHaveBeenCalledTimes(2);
expect(deps.enqueue).toHaveBeenNthCalledWith(1, { tenantId: "tenant-1", connectionId: "connection-1", eventId: "event-1" });
expect(deps.enqueue).toHaveBeenNthCalledWith(2, { tenantId: "tenant-1", connectionId: "connection-1", eventId: "event-1" });
});
it("rejects oversized bodies before authentication", async () => {
const response = await buildApp(deps).request("/v1/webhooks/telephony/aircall", {
method: "POST",
body: requestBody({ padding: "x".repeat(300_000) }),
});
expect(response.status).toBe(202);
expect(deps.authenticateAndNormalize).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,265 @@
import { createHash, createHmac, randomUUID } from "node:crypto";
import { decryptTenantField } from "@hivegrid/db/crypto/tenant-envelope.server";
import { getDbClient } from "@hivegrid/db/client.server";
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
import { resolveAircallWebhookRlsIdentity } from "@hivegrid/db/rls-resolvers.server";
import { aircallTelephonyProvider, type TelephonyCallEvent } from "@hivegrid/integrations";
import {
TELEPHONY_WEBHOOK_QUEUE_NAME,
buildTelephonyWebhookJob,
enqueueTelephonyWebhookJob,
resolveRedisConnectionOptionsFromProcessEnv,
type TelephonyWebhookQueue,
} from "@hivegrid/queue";
import { createFixedWindowRateLimiter } from "@hivegrid/shared-store";
import type { Context } from "hono";
import type { ApiEnv } from "../api-types.js";
import { getSharedStore } from "../shared-store.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
const MAX_BODY_BYTES = 256 * 1_024;
const MAX_TOKEN_BYTES = 2_048;
const RATE_LIMIT_WINDOW_SECONDS = 60;
const RATE_LIMIT_PER_CLIENT = 1_200;
const RATE_LIMIT_PER_CONNECTION = 600;
const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
type AuthenticatedAircallEvent = {
tenantId: string;
connectionId: string;
event: TelephonyCallEvent;
};
export type AircallWebhookRouteDependencies = {
checkClientRateLimit(request: Request): Promise<boolean>;
checkConnectionRateLimit(webhookTokenHash: string): Promise<boolean>;
authenticateAndNormalize(webhookTokenHash: string, payload: unknown): Promise<AuthenticatedAircallEvent | null>;
persistEvent(input: AuthenticatedAircallEvent): Promise<{ eventId: string }>;
enqueue(input: { tenantId: string; connectionId: string; eventId: string }): Promise<void>;
};
function neutral(c: Context<ApiEnv>, status: 202 | 503 = 202) {
return c.body(null, status);
}
/** Public Aircall ingress. Responses never reveal tenant or credential state. */
export async function postAircallWebhookRequest(
c: Context<ApiEnv>,
dependencies: AircallWebhookRouteDependencies = defaultAircallWebhookDependencies(),
) {
try {
// Aircall treats every 2xx response as accepted. A throttled, otherwise
// valid delivery must remain retryable instead of being lost silently.
if (!(await dependencies.checkClientRateLimit(c.req.raw))) return neutral(c, 503);
} catch {
return neutral(c, 503);
}
const payload = await readBoundedJson(c.req.raw);
const token = readWebhookToken(payload);
if (!token) return neutral(c);
const webhookTokenHash = hashWebhookToken(token);
try {
if (!(await dependencies.checkConnectionRateLimit(webhookTokenHash))) return neutral(c, 503);
} catch {
return neutral(c, 503);
}
let authenticated: AuthenticatedAircallEvent | null;
try {
authenticated = await dependencies.authenticateAndNormalize(webhookTokenHash, payload);
} catch {
return neutral(c, 503);
}
if (!authenticated) return neutral(c);
try {
const persisted = await dependencies.persistEvent(authenticated);
await dependencies.enqueue({
tenantId: authenticated.tenantId,
connectionId: authenticated.connectionId,
eventId: persisted.eventId,
});
} catch {
// Aircall retries non-2xx responses. Persistence is idempotent, so a retry
// can safely enqueue an event that survived a temporary queue outage.
return neutral(c, 503);
}
return neutral(c);
}
function defaultAircallWebhookDependencies(): AircallWebhookRouteDependencies {
return {
checkClientRateLimit: async (request) => {
const secret = process.env.CRYPTO_SECRET?.trim() || process.env.SESSION_SECRET?.trim();
if (!secret) throw new Error("Aircall webhook rate-limit key secret is unavailable.");
const clientKey = createHmac("sha256", secret)
.update(getTrustedClientIp(request) || "unknown", "utf8")
.digest("hex");
const limiter = createFixedWindowRateLimiter({
store: getSharedStore(),
prefix: "aircall-webhook-client",
windowSeconds: RATE_LIMIT_WINDOW_SECONDS,
max: RATE_LIMIT_PER_CLIENT,
});
return (await limiter.consume(clientKey)).allowed;
},
checkConnectionRateLimit: async (webhookTokenHash) => {
const limiter = createFixedWindowRateLimiter({
store: getSharedStore(),
prefix: "aircall-webhook-connection",
windowSeconds: RATE_LIMIT_WINDOW_SECONDS,
max: RATE_LIMIT_PER_CONNECTION,
});
return (await limiter.consume(webhookTokenHash)).allowed;
},
authenticateAndNormalize: authenticateAndNormalizeAircallEvent,
persistEvent: persistAircallEvent,
enqueue: enqueueAircallEvent,
};
}
async function authenticateAndNormalizeAircallEvent(webhookTokenHash: string, payload: unknown): Promise<AuthenticatedAircallEvent | null> {
if (!SHA256_PATTERN.test(webhookTokenHash)) return null;
const identity = await resolveAircallWebhookRlsIdentity(webhookTokenHash);
if (!identity) return null;
return runWithRlsContext({ tenantId: identity.tenantId }, async () => {
const db = getDbClient();
const connection = await db.telephonyConnection.findFirst({
where: {
id: identity.resourceId,
tenantId: identity.tenantId,
provider: "aircall",
webhookTokenHash,
},
select: { id: true, dataConnectionId: true },
});
if (!connection) return null;
const dataConnection = await db.dataConnection.findFirst({
where: {
id: connection.dataConnectionId,
tenantId: identity.tenantId,
appId: "aircall",
archivedAt: null,
connectionStatus: { in: ["active", "degraded"] },
},
select: { credentialsCiphertext: true },
});
if (!dataConnection?.credentialsCiphertext) return null;
const plaintext = await decryptTenantField(identity.tenantId, dataConnection.credentialsCiphertext, {
client: db as never,
});
const credentials = parseCredentialRecord(plaintext);
const expectedToken = typeof credentials.webhookToken === "string" ? credentials.webhookToken : "";
const normalized = aircallTelephonyProvider.normalizeWebhook(payload, expectedToken);
return normalized.ok
? { tenantId: identity.tenantId, connectionId: connection.id, event: normalized.event }
: null;
});
}
async function persistAircallEvent(input: AuthenticatedAircallEvent): Promise<{ eventId: string }> {
return runWithRlsContext({ tenantId: input.tenantId }, async () => {
const db = getDbClient();
const eventId = randomUUID();
const inserted = await db.telephonyWebhookEvent.createMany({
data: {
id: eventId,
tenantId: input.tenantId,
connectionId: input.connectionId,
eventType: input.event.providerEvent,
dedupeKey: input.event.dedupeKey,
authenticationValid: true,
notificationPayload: input.event as never,
processingStatus: "pending",
},
skipDuplicates: true,
});
if (inserted.count === 1) return { eventId };
const existing = await db.telephonyWebhookEvent.findUnique({
where: { tenantId_dedupeKey: { tenantId: input.tenantId, dedupeKey: input.event.dedupeKey } },
select: { id: true },
});
if (!existing) throw new Error("Aircall webhook idempotency conflict could not be re-read.");
return { eventId: existing.id };
});
}
async function enqueueAircallEvent(input: { tenantId: string; connectionId: string; eventId: string }): Promise<void> {
const connection = resolveRedisConnectionOptionsFromProcessEnv();
if (!connection) throw new Error("Aircall webhook queue is unavailable.");
const queueRuntimeModule = "@hivegrid/queue/runtime";
const runtime = (await import(/* @vite-ignore */ queueRuntimeModule)) as unknown as {
createQueue(queueName: string, options: { connection: unknown }): TelephonyWebhookQueue;
};
const queue = runtime.createQueue(TELEPHONY_WEBHOOK_QUEUE_NAME, { connection });
try {
await enqueueTelephonyWebhookJob(
queue,
buildTelephonyWebhookJob({
tenantId: input.tenantId,
connectionId: input.connectionId,
webhookEventId: input.eventId,
}),
);
} finally {
await queue.close();
}
}
async function readBoundedJson(request: Request): Promise<unknown | null> {
const contentLength = request.headers.get("content-length");
if (contentLength !== null) {
const parsed = Number(contentLength);
if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > MAX_BODY_BYTES) return null;
}
if (!request.body) return null;
const reader = request.body.getReader();
const decoder = new TextDecoder();
let totalBytes = 0;
let text = "";
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
totalBytes += value.byteLength;
if (totalBytes > MAX_BODY_BYTES) {
await reader.cancel();
return null;
}
text += decoder.decode(value, { stream: true });
}
text += decoder.decode();
return JSON.parse(text) as unknown;
} catch {
return null;
} finally {
reader.releaseLock();
}
}
function readWebhookToken(payload: unknown): string | null {
if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
const token = (payload as Record<string, unknown>).token;
if (typeof token !== "string" || token.length === 0 || Buffer.byteLength(token, "utf8") > MAX_TOKEN_BYTES) return null;
return token;
}
function hashWebhookToken(token: string): string {
return createHash("sha256").update(token, "utf8").digest("hex");
}
function parseCredentialRecord(plaintext: string): Record<string, unknown> {
const value = JSON.parse(plaintext) as unknown;
if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Aircall credentials are invalid.");
return value as Record<string, unknown>;
}
@@ -0,0 +1,124 @@
import { Hono } from "hono";
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { ApiEnv } from "../api-types.js";
import {
postHalloPetraWebhookRequest,
type HalloPetraWebhookRouteDependencies,
} from "./hallopetra-webhook-route.js";
const event = {
provider: "hallopetra",
providerEvent: "post_call",
type: "ended" as const,
dedupeKey: "hallopetra:post_call:call-456:webhook-123",
providerCallId: "call-456",
occurredAtIso: "2026-08-01T08:30:00.000Z",
direction: "inbound" as const,
status: "completed",
externalNumber: "+49301234567",
lineId: null,
lineNumber: null,
providerUserId: null,
providerUserEmail: null,
startedAtIso: "2026-08-01T08:28:25.000Z",
answeredAtIso: "2026-08-01T08:28:25.000Z",
endedAtIso: "2026-08-01T08:30:00.000Z",
durationSeconds: 95,
missed: false,
missedReason: null,
recordingUrl: null,
voicemailUrl: null,
};
function dependencies(): HalloPetraWebhookRouteDependencies {
return {
now: () => new Date("2026-08-01T08:30:00.000Z"),
checkClientRateLimit: vi.fn(async () => true),
checkConnectionRateLimit: vi.fn(async () => true),
authenticateAndNormalize: vi.fn(async () => ({ tenantId: "tenant-1", connectionId: "connection-1", event })),
persistEvent: vi.fn(async () => ({ eventId: "event-1" })),
enqueue: vi.fn(async () => undefined),
};
}
function buildApp(deps: HalloPetraWebhookRouteDependencies) {
const app = new Hono<ApiEnv>();
app.post("/v1/webhooks/telephony/hallopetra", (c) => postHalloPetraWebhookRequest(c, deps));
return app;
}
const body = JSON.stringify({
webhook_id: "webhook-123",
data: { id: "call-456", duration: 95, phone: "+49301234567", summary: "Terminwunsch" },
});
describe("POST /v1/webhooks/telephony/hallopetra", () => {
let deps: HalloPetraWebhookRouteDependencies;
beforeEach(() => {
deps = dependencies();
});
it("hashes the custom bearer secret and persists only the normalized event", async () => {
const response = await buildApp(deps).request("/v1/webhooks/telephony/hallopetra", {
method: "POST",
headers: { authorization: "Bearer separate-webhook-secret", "content-type": "application/json" },
body,
});
expect(response.status).toBe(202);
expect(deps.checkConnectionRateLimit).toHaveBeenCalledWith(expect.stringMatching(/^[a-f0-9]{64}$/u));
expect(deps.authenticateAndNormalize).toHaveBeenCalledWith(
expect.stringMatching(/^[a-f0-9]{64}$/u),
"separate-webhook-secret",
"2026-08-01T08:30:00.000Z",
expect.objectContaining({ webhook_id: "webhook-123" }),
);
expect(deps.persistEvent).toHaveBeenCalledWith({ tenantId: "tenant-1", connectionId: "connection-1", event });
expect(JSON.stringify(vi.mocked(deps.persistEvent).mock.calls)).not.toContain("separate-webhook-secret");
expect(await response.text()).toBe("");
});
it("neutral-acks missing or malformed authorization without parsing tenant state", async () => {
const missing = await buildApp(deps).request("/v1/webhooks/telephony/hallopetra", { method: "POST", body });
expect(missing.status).toBe(202);
expect(deps.authenticateAndNormalize).not.toHaveBeenCalled();
const malformed = await buildApp(deps).request("/v1/webhooks/telephony/hallopetra", {
method: "POST",
headers: { authorization: "Basic nope" },
body,
});
expect(malformed.status).toBe(202);
expect(deps.authenticateAndNormalize).not.toHaveBeenCalled();
});
it("keeps throttled and dependency-failed deliveries retryable", async () => {
vi.mocked(deps.checkClientRateLimit).mockResolvedValueOnce(false);
const limited = await buildApp(deps).request("/v1/webhooks/telephony/hallopetra", {
method: "POST",
headers: { authorization: "Bearer secret" },
body,
});
expect(limited.status).toBe(503);
vi.mocked(deps.enqueue).mockRejectedValueOnce(new Error("queue unavailable"));
const failed = await buildApp(deps).request("/v1/webhooks/telephony/hallopetra", {
method: "POST",
headers: { authorization: "Bearer secret" },
body,
});
expect(failed.status).toBe(503);
});
it("rejects oversized bodies before normalization", async () => {
const response = await buildApp(deps).request("/v1/webhooks/telephony/hallopetra", {
method: "POST",
headers: { authorization: "Bearer secret" },
body: JSON.stringify({ padding: "x".repeat(300_000) }),
});
expect(response.status).toBe(202);
expect(deps.authenticateAndNormalize).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,283 @@
import { createHash, createHmac, randomUUID } from "node:crypto";
import { decryptTenantField } from "@hivegrid/db/crypto/tenant-envelope.server";
import { getDbClient } from "@hivegrid/db/client.server";
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
import { resolveHalloPetraWebhookRlsIdentity } from "@hivegrid/db/rls-resolvers.server";
import { hallopetraTelephonyProvider, type TelephonyCallEvent } from "@hivegrid/integrations";
import {
TELEPHONY_WEBHOOK_QUEUE_NAME,
buildTelephonyWebhookJob,
enqueueTelephonyWebhookJob,
resolveRedisConnectionOptionsFromProcessEnv,
type TelephonyWebhookQueue,
} from "@hivegrid/queue";
import { createFixedWindowRateLimiter } from "@hivegrid/shared-store";
import type { Context } from "hono";
import type { ApiEnv } from "../api-types.js";
import { getSharedStore } from "../shared-store.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
const MAX_BODY_BYTES = 256 * 1_024;
const MAX_SECRET_BYTES = 2_048;
const RATE_LIMIT_WINDOW_SECONDS = 60;
const RATE_LIMIT_PER_CLIENT = 1_200;
const RATE_LIMIT_PER_CONNECTION = 600;
const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
type AuthenticatedHalloPetraEvent = {
tenantId: string;
connectionId: string;
event: TelephonyCallEvent;
};
export type HalloPetraWebhookRouteDependencies = {
now(): Date;
checkClientRateLimit(request: Request): Promise<boolean>;
checkConnectionRateLimit(webhookTokenHash: string): Promise<boolean>;
authenticateAndNormalize(
webhookTokenHash: string,
webhookSecret: string,
receivedAtIso: string,
payload: unknown,
): Promise<AuthenticatedHalloPetraEvent | null>;
persistEvent(input: AuthenticatedHalloPetraEvent): Promise<{ eventId: string }>;
enqueue(input: { tenantId: string; connectionId: string; eventId: string }): Promise<void>;
};
function neutral(c: Context<ApiEnv>, status: 202 | 503 = 202) {
return c.body(null, status);
}
/** Public HalloPetra ingress. Responses never reveal tenant or secret state. */
export async function postHalloPetraWebhookRequest(
c: Context<ApiEnv>,
dependencies: HalloPetraWebhookRouteDependencies = defaultHalloPetraWebhookDependencies(),
) {
try {
if (!(await dependencies.checkClientRateLimit(c.req.raw))) return neutral(c, 503);
} catch {
return neutral(c, 503);
}
const webhookSecret = readBearerSecret(c.req.raw.headers.get("authorization"));
if (!webhookSecret) return neutral(c);
const webhookTokenHash = hashWebhookToken(webhookSecret);
try {
if (!(await dependencies.checkConnectionRateLimit(webhookTokenHash))) return neutral(c, 503);
} catch {
return neutral(c, 503);
}
const payload = await readBoundedJson(c.req.raw);
if (payload === null) return neutral(c);
let authenticated: AuthenticatedHalloPetraEvent | null;
try {
authenticated = await dependencies.authenticateAndNormalize(
webhookTokenHash,
webhookSecret,
dependencies.now().toISOString(),
payload,
);
} catch {
return neutral(c, 503);
}
if (!authenticated) return neutral(c);
try {
const persisted = await dependencies.persistEvent(authenticated);
await dependencies.enqueue({
tenantId: authenticated.tenantId,
connectionId: authenticated.connectionId,
eventId: persisted.eventId,
});
} catch {
return neutral(c, 503);
}
return neutral(c);
}
function defaultHalloPetraWebhookDependencies(): HalloPetraWebhookRouteDependencies {
return {
now: () => new Date(),
checkClientRateLimit: async (request) => {
const secret = process.env.CRYPTO_SECRET?.trim() || process.env.SESSION_SECRET?.trim();
if (!secret) throw new Error("HalloPetra webhook rate-limit key secret is unavailable.");
const clientKey = createHmac("sha256", secret)
.update(getTrustedClientIp(request) || "unknown", "utf8")
.digest("hex");
const limiter = createFixedWindowRateLimiter({
store: getSharedStore(),
prefix: "hallopetra-webhook-client",
windowSeconds: RATE_LIMIT_WINDOW_SECONDS,
max: RATE_LIMIT_PER_CLIENT,
});
return (await limiter.consume(clientKey)).allowed;
},
checkConnectionRateLimit: async (webhookTokenHash) => {
const limiter = createFixedWindowRateLimiter({
store: getSharedStore(),
prefix: "hallopetra-webhook-connection",
windowSeconds: RATE_LIMIT_WINDOW_SECONDS,
max: RATE_LIMIT_PER_CONNECTION,
});
return (await limiter.consume(webhookTokenHash)).allowed;
},
authenticateAndNormalize: authenticateAndNormalizeHalloPetraEvent,
persistEvent: persistHalloPetraEvent,
enqueue: enqueueHalloPetraEvent,
};
}
async function authenticateAndNormalizeHalloPetraEvent(
webhookTokenHash: string,
webhookSecret: string,
receivedAtIso: string,
payload: unknown,
): Promise<AuthenticatedHalloPetraEvent | null> {
if (!SHA256_PATTERN.test(webhookTokenHash)) return null;
const identity = await resolveHalloPetraWebhookRlsIdentity(webhookTokenHash);
if (!identity) return null;
return runWithRlsContext({ tenantId: identity.tenantId }, async () => {
const db = getDbClient();
const connection = await db.telephonyConnection.findFirst({
where: {
id: identity.resourceId,
tenantId: identity.tenantId,
provider: "hallopetra",
webhookTokenHash,
},
select: { id: true, dataConnectionId: true },
});
if (!connection) return null;
const dataConnection = await db.dataConnection.findFirst({
where: {
id: connection.dataConnectionId,
tenantId: identity.tenantId,
appId: "hallopetra",
archivedAt: null,
connectionStatus: { in: ["active", "degraded"] },
},
select: { credentialsCiphertext: true },
});
if (!dataConnection?.credentialsCiphertext) return null;
const plaintext = await decryptTenantField(identity.tenantId, dataConnection.credentialsCiphertext, {
client: db as never,
});
const credentials = parseCredentialRecord(plaintext);
const expectedSecret = typeof credentials.webhookSecret === "string" ? credentials.webhookSecret : "";
const normalized = hallopetraTelephonyProvider.normalizeWebhook(
{ token: webhookSecret, receivedAtIso, body: payload },
expectedSecret,
);
return normalized.ok
? { tenantId: identity.tenantId, connectionId: connection.id, event: normalized.event }
: null;
});
}
async function persistHalloPetraEvent(input: AuthenticatedHalloPetraEvent): Promise<{ eventId: string }> {
return runWithRlsContext({ tenantId: input.tenantId }, async () => {
const db = getDbClient();
const eventId = randomUUID();
const inserted = await db.telephonyWebhookEvent.createMany({
data: {
id: eventId,
tenantId: input.tenantId,
connectionId: input.connectionId,
eventType: input.event.providerEvent,
dedupeKey: input.event.dedupeKey,
authenticationValid: true,
notificationPayload: input.event as never,
processingStatus: "pending",
},
skipDuplicates: true,
});
if (inserted.count === 1) return { eventId };
const existing = await db.telephonyWebhookEvent.findUnique({
where: { tenantId_dedupeKey: { tenantId: input.tenantId, dedupeKey: input.event.dedupeKey } },
select: { id: true },
});
if (!existing) throw new Error("HalloPetra webhook idempotency conflict could not be re-read.");
return { eventId: existing.id };
});
}
async function enqueueHalloPetraEvent(input: { tenantId: string; connectionId: string; eventId: string }): Promise<void> {
const connection = resolveRedisConnectionOptionsFromProcessEnv();
if (!connection) throw new Error("HalloPetra webhook queue is unavailable.");
const queueRuntimeModule = "@hivegrid/queue/runtime";
const runtime = (await import(/* @vite-ignore */ queueRuntimeModule)) as unknown as {
createQueue(queueName: string, options: { connection: unknown }): TelephonyWebhookQueue;
};
const queue = runtime.createQueue(TELEPHONY_WEBHOOK_QUEUE_NAME, { connection });
try {
await enqueueTelephonyWebhookJob(
queue,
buildTelephonyWebhookJob({
tenantId: input.tenantId,
connectionId: input.connectionId,
webhookEventId: input.eventId,
}),
);
} finally {
await queue.close();
}
}
async function readBoundedJson(request: Request): Promise<unknown | null> {
const contentLength = request.headers.get("content-length");
if (contentLength !== null) {
const parsed = Number(contentLength);
if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > MAX_BODY_BYTES) return null;
}
if (!request.body) return null;
const reader = request.body.getReader();
const decoder = new TextDecoder();
let totalBytes = 0;
let text = "";
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
totalBytes += value.byteLength;
if (totalBytes > MAX_BODY_BYTES) {
await reader.cancel();
return null;
}
text += decoder.decode(value, { stream: true });
}
text += decoder.decode();
return JSON.parse(text) as unknown;
} catch {
return null;
} finally {
reader.releaseLock();
}
}
function readBearerSecret(header: string | null): string | null {
if (!header) return null;
const match = /^Bearer ([^\s]+)$/iu.exec(header.trim());
if (!match?.[1] || Buffer.byteLength(match[1], "utf8") > MAX_SECRET_BYTES) return null;
return match[1];
}
function hashWebhookToken(token: string): string {
return createHash("sha256").update(token, "utf8").digest("hex");
}
function parseCredentialRecord(plaintext: string): Record<string, unknown> {
const value = JSON.parse(plaintext) as unknown;
if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("HalloPetra credentials are invalid.");
return value as Record<string, unknown>;
}
@@ -1,10 +1,4 @@
// Trusted, proxy-set client-IP headers in order of preference. These are set
// by the edge/proxy and OVERWRITE any client-supplied value, so — unlike the
// leftmost X-Forwarded-For entry or X-Client-IP — they cannot be spoofed by the
// client. Every public request in this estate passes through Cloudflare
// (proxied), which sets CF-Connecting-IP; X-Real-IP is the immediate reverse
// proxy (Traefik) hop as a fallback for non-Cloudflare paths.
const TRUSTED_IP_HEADERS = ["cf-connecting-ip", "true-client-ip", "x-real-ip"] as const;
import { getTrustedProxyClientIp } from "@hivegrid/foundation/trusted-client-ip";
/**
* Read the client IP from a trusted header only. Use for security-sensitive
@@ -12,12 +6,13 @@ const TRUSTED_IP_HEADERS = ["cf-connecting-ip", "true-client-ip", "x-real-ip"] a
* to rotate their apparent IP by forging X-Forwarded-For. Returns the empty
* string when no trusted header is present so callers can key a shared bucket.
*/
export function getTrustedClientIp(request: Request): string {
for (const headerName of TRUSTED_IP_HEADERS) {
const value = request.headers.get(headerName)?.trim();
if (value) {
return value;
}
}
return "";
export function getTrustedClientIp(request: Request, immediatePeerIp?: string | null): string {
return getTrustedClientIpFromHeaderLookup((name) => request.headers.get(name), immediatePeerIp);
}
export function getTrustedClientIpFromHeaderLookup(
lookup: (name: string) => string | null | undefined,
immediatePeerIp?: string | null,
): string {
return getTrustedProxyClientIp(lookup, immediatePeerIp) ?? "";
}
@@ -1,6 +1,7 @@
import { Hono } from "hono";
import type { ApiConfig } from "@hivegrid/config";
import type { LegacyApiKeySimple } from "@hivegrid/db/api-keys.server";
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
import { SUBSCRIPTION_FEATURE_LIMIT, type TenantApiUsageFeature } from "@hivegrid/db/usage.server";
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
@@ -20,6 +21,7 @@ const TEST_API_CONFIG: ApiConfig = {
webAppHost: "app.localhost:3000",
adminAppHost: "admin.localhost:3000",
apiHost: "api.localhost:3000",
portalAppHost: "portal.localhost:3000",
protocol: "http",
},
origins: {},
@@ -77,7 +79,12 @@ function buildDeps(options: { apiKey?: LegacyApiKeySimple | null; usage?: Tenant
const apiKey = options.apiKey === undefined ? createApiKeyFixture() : options.apiKey;
const mocks = {
findLegacyApiKeyByKey: vi.fn(async () => apiKey),
createLegacyApiKeyLog: vi.fn(async (data: { tenantId?: string | null }) => ({ id: "api_key_log_usage_1", tenantId: data.tenantId ?? null })),
createLegacyApiKeyLog: vi.fn(async (data: { tenantId?: string | null }) => {
if (data.tenantId) {
expect(getRlsExecutionContext()).toMatchObject({ tenantId: data.tenantId });
}
return { id: "api_key_log_usage_1", tenantId: data.tenantId ?? null };
}),
setLegacyApiKeyLogStatus: vi.fn(async () => ({ count: 1 })),
createUniqueLegacyTenantIpAddress: vi.fn(async () => {
if (options.ipLoggingError) {
@@ -115,7 +122,23 @@ async function requestUsage(dependencies: UsageRouteDependencies, headers: Recor
}
describe("getUsageRequest", () => {
test("rejects missing API keys and records an unauthenticated usage log", async () => {
test("binds the verified API-key tenant around scoped usage dependencies", async () => {
const { dependencies, mocks } = buildDeps({ usage: createUsageFixture() });
let contextDuringTenantRead: ReturnType<typeof getRlsExecutionContext> = null;
mocks.getTenantSubscription.mockImplementation(async () => {
await Promise.resolve();
contextDuringTenantRead = getRlsExecutionContext();
return null;
});
const response = await requestUsage(dependencies, { "x-api-key": "tenant-secret" });
expect(response.status).toBe(200);
expect(contextDuringTenantRead).toMatchObject({ tenantId: "tenant_usage_1" });
expect(getRlsExecutionContext()).toBeNull();
});
test("rejects missing API keys without writing a global API-key log", async () => {
const { dependencies, mocks } = buildDeps();
const response = await requestUsage(dependencies);
@@ -129,20 +152,11 @@ describe("getUsageRequest", () => {
},
});
expect(mocks.findLegacyApiKeyByKey).not.toHaveBeenCalled();
expect(mocks.createLegacyApiKeyLog).toHaveBeenCalledWith({
tenantId: null,
apiKeyId: null,
endpoint: "/v1/usage",
ip: "",
method: "GET",
params: "source=test",
error: "Invalid API Key",
status: 401,
});
expect(mocks.createLegacyApiKeyLog).not.toHaveBeenCalled();
expect(mocks.setLegacyApiKeyLogStatus).not.toHaveBeenCalled();
});
test("rejects invalid API keys after lookup and records an unauthenticated usage log", async () => {
test("rejects invalid API keys after lookup without writing a global API-key log", async () => {
const { dependencies, mocks } = buildDeps({ apiKey: null });
const response = await requestUsage(dependencies, { "x-api-key": "invalid-secret" });
@@ -156,15 +170,7 @@ describe("getUsageRequest", () => {
},
});
expect(mocks.findLegacyApiKeyByKey).toHaveBeenCalledWith("invalid-secret", undefined, "usage-route-secret", { allowPlaintextFallback: true });
expect(mocks.createLegacyApiKeyLog).toHaveBeenCalledWith(
expect.objectContaining({
tenantId: null,
apiKeyId: null,
endpoint: "/v1/usage",
error: "Invalid API Key",
status: 401,
}),
);
expect(mocks.createLegacyApiKeyLog).not.toHaveBeenCalled();
expect(mocks.setLegacyApiKeyLogStatus).not.toHaveBeenCalled();
});
@@ -186,7 +192,7 @@ describe("getUsageRequest", () => {
});
expect(mocks.setLegacyApiKeyLogStatus).toHaveBeenCalledWith(
{ id: "api_key_log_usage_1", tenantId: "tenant_usage_1" },
expect.objectContaining({ status: 403, error: "Account is inactive." }),
expect.objectContaining({ status: 403, error: "Account is inactive." })
);
expect(mocks.createUniqueLegacyTenantIpAddress).not.toHaveBeenCalled();
expect(mocks.getTenantApiUsage).not.toHaveBeenCalled();
@@ -207,7 +213,7 @@ describe("getUsageRequest", () => {
});
expect(mocks.setLegacyApiKeyLogStatus).toHaveBeenCalledWith(
{ id: "api_key_log_usage_1", tenantId: "tenant_usage_1" },
expect.objectContaining({ status: 400, error: "API key is inactive." }),
expect.objectContaining({ status: 400, error: "API key is inactive." })
);
expect(mocks.createUniqueLegacyTenantIpAddress).not.toHaveBeenCalled();
expect(mocks.getTenantApiUsage).not.toHaveBeenCalled();
@@ -228,7 +234,7 @@ describe("getUsageRequest", () => {
});
expect(mocks.setLegacyApiKeyLogStatus).toHaveBeenCalledWith(
{ id: "api_key_log_usage_1", tenantId: "tenant_usage_1" },
expect.objectContaining({ status: 400, error: "API key is expired." }),
expect.objectContaining({ status: 400, error: "API key is expired." })
);
expect(mocks.createUniqueLegacyTenantIpAddress).not.toHaveBeenCalled();
expect(mocks.getTenantApiUsage).not.toHaveBeenCalled();
@@ -237,7 +243,11 @@ describe("getUsageRequest", () => {
test("swallows IP logging failures and still returns usage", async () => {
const { dependencies, mocks } = buildDeps({ ipLoggingError: new Error("ip write failed") });
const response = await requestUsage(dependencies, { "x-api-key": "valid-secret", "cf-connecting-ip": "203.0.113.10" });
const response = await requestUsage(dependencies, {
"x-api-key": "valid-secret",
"cf-connecting-ip": "203.0.113.10",
"x-forwarded-for": "173.245.48.5",
});
expect(response.status).toBe(200);
await expect(response.json()).resolves.toEqual({ plan: "" });
@@ -251,7 +261,7 @@ describe("getUsageRequest", () => {
expect(mocks.getTenantApiUsage).toHaveBeenCalledWith("tenant_usage_1", null);
expect(mocks.setLegacyApiKeyLogStatus).toHaveBeenCalledWith(
{ id: "api_key_log_usage_1", tenantId: "tenant_usage_1" },
expect.objectContaining({ status: 200 }),
expect.objectContaining({ status: 200 })
);
});
@@ -271,7 +281,7 @@ describe("getUsageRequest", () => {
});
expect(mocks.setLegacyApiKeyLogStatus).toHaveBeenCalledWith(
{ id: "api_key_log_usage_1", tenantId: "tenant_usage_1" },
expect.objectContaining({ status: 402, error: "API usage is disabled or exhausted." }),
expect.objectContaining({ status: 402, error: "API usage is disabled or exhausted." })
);
});
@@ -292,7 +302,7 @@ describe("getUsageRequest", () => {
expect(body).not.toHaveProperty("remaining");
expect(mocks.setLegacyApiKeyLogStatus).toHaveBeenCalledWith(
{ id: "api_key_log_usage_1", tenantId: "tenant_usage_1" },
expect.objectContaining({ status: 200 }),
expect.objectContaining({ status: 200 })
);
});
});
@@ -5,6 +5,8 @@ import { extractApiKeyFromRequest } from "../auth.js";
import { getApiRuntimeConfig } from "../config.js";
import { getTrustedClientIp } from "../trusted-client-ip.js";
import { apiError, type ApiErrorEnv } from "../middleware/error-envelope.js";
import { runWithVerifiedApiRlsContext } from "../rls-context.js";
import { apiLogger } from "../logger.js";
import type { ApiAppDependencies } from "../app.js";
type UsageRouteDependencies = Pick<
@@ -23,7 +25,7 @@ export async function getUsageRequest(c: Context<ApiErrorEnv>, dependencies: Usa
const config = getApiRuntimeConfig();
const apiKeyValue = extractApiKeyFromRequest(c.req.raw, undefined);
if (!apiKeyValue) {
await createApiUsageErrorLog(c, dependencies, endpoint, "Invalid API Key", 401);
recordApiUsagePreAuthFailure(c, endpoint, "Missing API key", 401);
return apiError(c, 401, "unauthorized", "Valid API key credentials are required.");
}
@@ -31,75 +33,72 @@ export async function getUsageRequest(c: Context<ApiErrorEnv>, dependencies: Usa
allowPlaintextFallback: config.apiKeys.allowLegacyPlaintextFallback,
});
if (!apiKey) {
await createApiUsageErrorLog(c, dependencies, endpoint, "Invalid API Key", 401);
recordApiUsagePreAuthFailure(c, endpoint, "Invalid API key", 401);
return apiError(c, 401, "unauthorized", "Valid API key credentials are required.");
}
const apiKeyLog = await dependencies.createLegacyApiKeyLog({
tenantId: apiKey.tenantId,
apiKeyId: apiKey.id,
endpoint,
ip: getClientIpAddress(c.req.raw) ?? "",
method: c.req.method,
params: serializeRequestSearchParams(c.req.raw),
alias: apiKey.alias,
tenantName: apiKey.tenant.name,
});
const fail = async (status: 400 | 402 | 403, code: string, message: string) => {
await dependencies.setLegacyApiKeyLogStatus({ id: apiKeyLog.id, tenantId: apiKey.tenantId }, { status, error: message, startTime });
return apiError(c, status, code, message);
};
if (apiKey.tenant.deactivatedReason) {
return fail(403, "tenant_inactive", "Account is inactive.");
}
if (!apiKey.active) {
return fail(400, "api_key_inactive", "API key is inactive.");
}
if (apiKey.expires && apiKey.expires < new Date()) {
return fail(400, "api_key_expired", "API key is expired.");
}
await dependencies
.createUniqueLegacyTenantIpAddress({
ip: getClientIpAddress(c.req.raw) ?? "Unknown",
fromUrl: endpoint,
return runWithVerifiedApiRlsContext({ tenantId: apiKey.tenantId }, async () => {
const apiKeyLog = await dependencies.createLegacyApiKeyLog({
tenantId: apiKey.tenantId,
apiKeyId: apiKey.id,
})
.catch(() => undefined);
endpoint,
ip: getClientIpAddress(c.req.raw) ?? "",
method: c.req.method,
params: serializeRequestSearchParams(c.req.raw),
alias: apiKey.alias,
tenantName: apiKey.tenant.name,
});
const tenantSubscription = await dependencies.getTenantSubscription(apiKey.tenantId);
const usage = await dependencies.getTenantApiUsage(apiKey.tenantId, tenantSubscription);
if (usage && !usage.enabled) {
return fail(402, "payment_required", "API usage is disabled or exhausted.");
}
const fail = async (status: 400 | 402 | 403, code: string, message: string) => {
await dependencies.setLegacyApiKeyLogStatus({ id: apiKeyLog.id, tenantId: apiKey.tenantId }, { status, error: message, startTime });
return apiError(c, status, code, message);
};
await dependencies.setLegacyApiKeyLogStatus({ id: apiKeyLog.id, tenantId: apiKey.tenantId }, { status: 200, startTime });
return c.json({
plan: usage ? formatTenantApiUsagePlanTitle(usage) : "",
remaining: usage?.type === SUBSCRIPTION_FEATURE_LIMIT.included ? undefined : usage?.remaining,
if (apiKey.tenant.deactivatedReason) {
return fail(403, "tenant_inactive", "Account is inactive.");
}
if (!apiKey.active) {
return fail(400, "api_key_inactive", "API key is inactive.");
}
if (apiKey.expires && apiKey.expires < new Date()) {
return fail(400, "api_key_expired", "API key is expired.");
}
await dependencies
.createUniqueLegacyTenantIpAddress({
ip: getClientIpAddress(c.req.raw) ?? "Unknown",
fromUrl: endpoint,
tenantId: apiKey.tenantId,
apiKeyId: apiKey.id,
})
.catch(() => undefined);
const tenantSubscription = await dependencies.getTenantSubscription(apiKey.tenantId);
const usage = await dependencies.getTenantApiUsage(apiKey.tenantId, tenantSubscription);
if (usage && !usage.enabled) {
return fail(402, "payment_required", "API usage is disabled or exhausted.");
}
await dependencies.setLegacyApiKeyLogStatus({ id: apiKeyLog.id, tenantId: apiKey.tenantId }, { status: 200, startTime });
return c.json({
plan: usage ? formatTenantApiUsagePlanTitle(usage) : "",
remaining: usage?.type === SUBSCRIPTION_FEATURE_LIMIT.included ? undefined : usage?.remaining,
});
});
}
async function createApiUsageErrorLog(
c: Context<ApiErrorEnv>,
dependencies: Pick<UsageRouteDependencies, "createLegacyApiKeyLog">,
endpoint: string,
error: string,
status: number,
) {
await dependencies.createLegacyApiKeyLog({
tenantId: null,
apiKeyId: null,
endpoint,
ip: getClientIpAddress(c.req.raw) ?? "",
method: c.req.method,
params: serializeRequestSearchParams(c.req.raw),
error,
status,
});
function recordApiUsagePreAuthFailure(c: Context<ApiErrorEnv>, endpoint: string, error: string, status: number) {
apiLogger.warn(
{
requestId: c.get("requestId"),
endpoint,
method: c.req.method,
sourceIp: getClientIpAddress(c.req.raw) ?? "",
status,
reason: error,
},
"API usage credential rejected before tenant bootstrap"
);
}
function getClientIpAddress(request: Request) {
@@ -1,5 +1,8 @@
import { describe, expect, test } from "vitest";
import {
ANALYTICS_COOKIE_ID_MAX_LENGTH,
ANALYTICS_URL_MAX_LENGTH,
API_KEY_MAX_LENGTH,
parseAnalyticsEventPayload,
parseAnalyticsPageViewPayload,
parseApiKeyValidationPayload,
@@ -41,7 +44,15 @@ describe("request schema validators", () => {
expectValidationError(parseLoginCredentialsPayload(null), { reason: "body_invalid", bodyType: "login_credentials" });
expectValidationError(parseLoginCredentialsPayload([]), { reason: "body_invalid", bodyType: "login_credentials" });
expectValidationError(parseLoginCredentialsPayload({ password: "present" }), { reason: "field_required", field: "email" });
expectValidationError(parseLoginCredentialsPayload({ email: 123, password: secretValue }), { reason: "field_type_invalid", field: "email", expected: "string" });
expectValidationError(parseLoginCredentialsPayload({ email: 123, password: secretValue }), {
reason: "field_type_invalid",
field: "email",
expected: "string",
});
expectValidationError(parseLoginCredentialsPayload({ email: "user@example.com", password: "x".repeat(1_025) }), {
reason: "field_value_invalid",
field: "password",
});
});
test("accepts API-key validation bodies without leaking invalid secret-like values", () => {
@@ -49,10 +60,14 @@ describe("request schema validators", () => {
expect(parseApiKeyValidationPayload({})).toEqual({ ok: true, value: {} });
expectErrorWithoutSecret(parseApiKeyValidationPayload({ apiKey: { plaintext: secretValue } }));
expectValidationError(parseApiKeyValidationPayload({ apiKey: "k".repeat(API_KEY_MAX_LENGTH + 1) }), {
reason: "field_value_invalid",
field: "apiKey",
});
expectValidationError(parseApiKeyValidationPayload(null), { reason: "body_invalid", bodyType: "api_key_validation" });
});
test("accepts valid analytics events with optional string fields", () => {
test("accepts valid anonymous analytics events with optional string fields", () => {
expect(
parseAnalyticsEventPayload({
action: "clicked",
@@ -63,11 +78,11 @@ describe("request schema validators", () => {
route: "/page",
analytics: {
userAnalyticsId: "visitor-1",
portalId: "portal-1",
portalUserId: "portal-user-1",
referrer: "https://referrer.test",
referrer: { http: "https://referrer.test/path?token=redacted", source: "newsletter" },
userAgent: { type: "desktop", os: { family: "Linux" }, browser: { name: "Firefox" } },
},
}),
ignored: "must-not-survive-validation",
})
).toEqual({
ok: true,
value: {
@@ -79,9 +94,8 @@ describe("request schema validators", () => {
route: "/page",
analytics: {
userAnalyticsId: "visitor-1",
portalId: "portal-1",
portalUserId: "portal-user-1",
referrer: "https://referrer.test",
referrer: { http: "https://referrer.test/path?token=redacted", source: "newsletter" },
userAgent: { type: "desktop", os: { family: "Linux" }, browser: { name: "Firefox" } },
},
},
});
@@ -89,10 +103,49 @@ describe("request schema validators", () => {
test("rejects malformed analytics event bodies and analytics fields without echoing values", () => {
expectValidationError(parseAnalyticsEventPayload([]), { reason: "body_invalid", bodyType: "analytics_event" });
expectValidationError(parseAnalyticsEventPayload({ category: "featureFlag", analytics: { userAnalyticsId: "visitor-1" } }), { reason: "field_required", field: "action" });
expectValidationError(parseAnalyticsEventPayload({ action: "clicked", category: 42, analytics: { userAnalyticsId: "visitor-1" } }), { reason: "field_type_invalid", field: "category", expected: "string" });
expectValidationError(parseAnalyticsEventPayload({ action: "clicked", category: "featureFlag", analytics: null }), { reason: "field_type_invalid", field: "analytics", expected: "object" });
expectErrorWithoutSecret(parseAnalyticsEventPayload({ action: "clicked", category: "featureFlag", analytics: { userAnalyticsId: { token: secretValue } } }));
expectValidationError(parseAnalyticsEventPayload({ category: "featureFlag", analytics: { userAnalyticsId: "visitor-1" } }), {
reason: "field_required",
field: "action",
});
expectValidationError(parseAnalyticsEventPayload({ action: "clicked", category: 42, analytics: { userAnalyticsId: "visitor-1" } }), {
reason: "field_type_invalid",
field: "category",
expected: "string",
});
expectValidationError(parseAnalyticsEventPayload({ action: "clicked", category: "featureFlag", analytics: null }), {
reason: "field_type_invalid",
field: "analytics",
expected: "object",
});
expectErrorWithoutSecret(
parseAnalyticsEventPayload({ action: "clicked", category: "featureFlag", analytics: { userAnalyticsId: { token: secretValue } } })
);
expectValidationError(
parseAnalyticsEventPayload({
action: "clicked",
category: "featureFlag",
analytics: { userAnalyticsId: "v".repeat(ANALYTICS_COOKIE_ID_MAX_LENGTH + 1) },
}),
{ reason: "field_value_invalid", field: "analytics.userAnalyticsId" }
);
expectValidationError(
parseAnalyticsEventPayload({
action: "clicked",
category: "featureFlag",
url: "u".repeat(ANALYTICS_URL_MAX_LENGTH + 1),
analytics: { userAnalyticsId: "visitor-1" },
}),
{ reason: "field_value_invalid", field: "url" }
);
});
test.each(["userId", "portalId", "portalUserId"])("rejects browser-supplied analytics identity field %s", (field) => {
const result = parseAnalyticsEventPayload({
action: "clicked",
category: "button",
analytics: { userAnalyticsId: "visitor-1", [field]: secretValue },
});
expectErrorWithoutSecret(result);
});
test("accepts and rejects analytics page-view payloads", () => {
@@ -100,12 +153,16 @@ describe("request schema validators", () => {
ok: true,
value: { url: "https://example.test", analytics: { userAnalyticsId: "visitor-1" } },
});
expect(parseAnalyticsPageViewPayload({ url: "https://example.test", route: "/home", analytics: { userAnalyticsId: "visitor-1", portalId: null } })).toEqual({
expect(parseAnalyticsPageViewPayload({ url: "https://example.test", route: "/home", analytics: { userAnalyticsId: "visitor-1" } })).toEqual({
ok: true,
value: { url: "https://example.test", route: "/home", analytics: { userAnalyticsId: "visitor-1", portalId: null } },
value: { url: "https://example.test", route: "/home", analytics: { userAnalyticsId: "visitor-1" } },
});
expectValidationError(parseAnalyticsPageViewPayload(null), { reason: "body_invalid", bodyType: "analytics_page_view" });
expectValidationError(parseAnalyticsPageViewPayload({ url: 123, analytics: { userAnalyticsId: "visitor-1" } }), { reason: "field_type_invalid", field: "url", expected: "string" });
expectValidationError(parseAnalyticsPageViewPayload({ url: 123, analytics: { userAnalyticsId: "visitor-1" } }), {
reason: "field_type_invalid",
field: "url",
expected: "string",
});
expectErrorWithoutSecret(parseAnalyticsPageViewPayload({ url: "https://example.test", analytics: { userAnalyticsId: secretValue, portalId: 123 } }));
});
@@ -116,7 +173,11 @@ describe("request schema validators", () => {
});
expectValidationError(parseRelationshipCreatePayload(null), { reason: "body_invalid", bodyType: "relationship" });
expectValidationError(parseRelationshipCreatePayload({ child: "row-child" }), { reason: "field_required", field: "parent" });
expectValidationError(parseRelationshipCreatePayload({ parent: secretValue, child: 7 }), { reason: "field_type_invalid", field: "child", expected: "string" });
expectValidationError(parseRelationshipCreatePayload({ parent: secretValue, child: 7 }), {
reason: "field_type_invalid",
field: "child",
expected: "string",
});
});
test("entity row bodies only require non-array JSON objects and preserve arbitrary data", () => {
@@ -136,7 +197,7 @@ describe("request schema validators", () => {
lastName: "Lovelace",
type: 2,
expiresAt: "2026-06-01T12:00:00.000Z",
}),
})
).toEqual({
ok: true,
value: {
@@ -152,9 +213,20 @@ describe("request schema validators", () => {
test("rejects malformed workspace invite create payloads without echoing values", () => {
expectValidationError(parseWorkspaceInviteCreatePayload(null), { reason: "body_invalid", bodyType: "workspace_invite_create" });
expectValidationError(parseWorkspaceInviteCreatePayload({ firstName: "Ada", lastName: "Lovelace", type: 2 }), { reason: "field_required", field: "email" });
expectValidationError(parseWorkspaceInviteCreatePayload({ email: 7, firstName: "Ada", lastName: "Lovelace", type: 2 }), { reason: "field_type_invalid", field: "email", expected: "string" });
expectValidationError(parseWorkspaceInviteCreatePayload({ email: "member@example.com", firstName: secretValue, lastName: "Lovelace", type: "2" }), { reason: "field_type_invalid", field: "type", expected: "number" });
expectValidationError(parseWorkspaceInviteCreatePayload({ email: "member@example.com", firstName: "Ada", lastName: "Lovelace", type: 2, expiresAt: "tomorrow" }), { reason: "field_value_invalid", field: "expiresAt", expected: "datetime" });
expectValidationError(parseWorkspaceInviteCreatePayload({ email: 7, firstName: "Ada", lastName: "Lovelace", type: 2 }), {
reason: "field_type_invalid",
field: "email",
expected: "string",
});
expectValidationError(parseWorkspaceInviteCreatePayload({ email: "member@example.com", firstName: secretValue, lastName: "Lovelace", type: "2" }), {
reason: "field_type_invalid",
field: "type",
expected: "number",
});
expectValidationError(
parseWorkspaceInviteCreatePayload({ email: "member@example.com", firstName: "Ada", lastName: "Lovelace", type: 2, expiresAt: "tomorrow" }),
{ reason: "field_value_invalid", field: "expiresAt", expected: "datetime" }
);
expectErrorWithoutSecret(parseWorkspaceInviteCreatePayload({ email: "member@example.com", firstName: secretValue, lastName: 99, type: 2 }));
});
@@ -162,7 +234,11 @@ describe("request schema validators", () => {
expect(parseWorkspaceInviteAcceptPayload({ token: secretValue, userId: "user_1" })).toEqual({ ok: true, value: { token: secretValue, userId: "user_1" } });
expectValidationError(parseWorkspaceInviteAcceptPayload(null), { reason: "body_invalid", bodyType: "workspace_invite_accept" });
expectValidationError(parseWorkspaceInviteAcceptPayload({ userId: "user_1" }), { reason: "field_required", field: "token" });
expectValidationError(parseWorkspaceInviteAcceptPayload({ token: { plaintext: secretValue }, userId: "user_1" }), { reason: "field_type_invalid", field: "token", expected: "string" });
expectValidationError(parseWorkspaceInviteAcceptPayload({ token: { plaintext: secretValue }, userId: "user_1" }), {
reason: "field_type_invalid",
field: "token",
expected: "string",
});
expectErrorWithoutSecret(parseWorkspaceInviteAcceptPayload({ token: secretValue, userId: 123 }));
});
@@ -173,16 +249,27 @@ describe("request schema validators", () => {
});
expect(parseWorkspaceInviteRevokePayload({})).toEqual({ ok: true, value: {} });
expectValidationError(parseWorkspaceInviteRevokePayload([]), { reason: "body_invalid", bodyType: "workspace_invite_revoke" });
expectValidationError(parseWorkspaceInviteRevokePayload({ reason: 404, revokedByUserId: secretValue }), { reason: "field_type_invalid", field: "reason", expected: "string" });
expectValidationError(parseWorkspaceInviteRevokePayload({ reason: 404, revokedByUserId: secretValue }), {
reason: "field_type_invalid",
field: "reason",
expected: "string",
});
expectErrorWithoutSecret(parseWorkspaceInviteRevokePayload({ reason: "duplicate", revokedByUserId: { token: secretValue } }));
});
test("accepts and rejects workspace context revalidation payloads without echoing secret-like values", () => {
expect(parseWorkspaceContextRevalidationPayload({ userId: "user_1" })).toEqual({ ok: true, value: { userId: "user_1" } });
expect(parseWorkspaceContextRevalidationPayload({ userId: "user_1", providerSlug: "okta" })).toEqual({ ok: true, value: { userId: "user_1", providerSlug: "okta" } });
expect(parseWorkspaceContextRevalidationPayload({ userId: "user_1", providerSlug: "okta" })).toEqual({
ok: true,
value: { userId: "user_1", providerSlug: "okta" },
});
expectValidationError(parseWorkspaceContextRevalidationPayload(null), { reason: "body_invalid", bodyType: "workspace_context_revalidation" });
expectValidationError(parseWorkspaceContextRevalidationPayload({ providerSlug: "okta" }), { reason: "field_required", field: "userId" });
expectValidationError(parseWorkspaceContextRevalidationPayload({ userId: 123, providerSlug: secretValue }), { reason: "field_type_invalid", field: "userId", expected: "string" });
expectValidationError(parseWorkspaceContextRevalidationPayload({ userId: 123, providerSlug: secretValue }), {
reason: "field_type_invalid",
field: "userId",
expected: "string",
});
expectErrorWithoutSecret(parseWorkspaceContextRevalidationPayload({ userId: "user_1", providerSlug: { secret: secretValue } }));
});
});
Loaded 100 of 5955 files, more files were not shown because too many files have changed in this diff. Show more