Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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" ||
|
||||
|
||||
+81
@@ -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 }));
|
||||
|
||||
+7
-4
@@ -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");
|
||||
|
||||
+89
-17
@@ -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;
|
||||
}
|
||||
+178
@@ -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();
|
||||
});
|
||||
});
|
||||
+178
@@ -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,
|
||||
};
|
||||
}
|
||||
+50
@@ -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;
|
||||
}
|
||||
+418
@@ -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 } : {}),
|
||||
});
|
||||
}
|
||||
+1561
-40
File diff suppressed because it is too large.
Load diff
+606
-50
@@ -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) {
|
||||
|
||||
Vendored
+8
-5
@@ -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");
|
||||
});
|
||||
|
||||
Vendored
+4
-3
@@ -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.",
|
||||
},
|
||||
];
|
||||
|
||||
|
||||
+27
-24
@@ -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,
|
||||
|
||||
+88
-23
@@ -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 });
|
||||
}
|
||||
+32
-19
@@ -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,
|
||||
|
||||
+23
-9
@@ -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;
|
||||
}
|
||||
|
||||
|
||||
+14
-2
@@ -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: {},
|
||||
|
||||
+13
-4
@@ -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,
|
||||
};
|
||||
|
||||
+28
-30
@@ -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);
|
||||
});
|
||||
});
|
||||
+83
@@ -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);
|
||||
}
|
||||
+8
-9
@@ -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([]);
|
||||
});
|
||||
});
|
||||
+68
-3
@@ -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,
|
||||
|
||||
+152
@@ -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();
|
||||
});
|
||||
});
|
||||
+103
@@ -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)) {
|
||||
|
||||
+238
-68
@@ -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);
|
||||
}
|
||||
}
|
||||
+128
@@ -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;
|
||||
}
|
||||
+146
-223
@@ -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") });
|
||||
}
|
||||
|
||||
+38
-35
@@ -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();
|
||||
}
|
||||
});
|
||||
},
|
||||
});
|
||||
|
||||
|
||||
+396
@@ -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;
|
||||
}
|
||||
+211
-139
@@ -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">;
|
||||
|
||||
|
||||
+98
@@ -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);
|
||||
});
|
||||
});
|
||||
+228
@@ -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;
|
||||
}
|
||||
+131
@@ -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();
|
||||
});
|
||||
});
|
||||
+265
@@ -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>;
|
||||
}
|
||||
+124
@@ -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();
|
||||
});
|
||||
});
|
||||
+283
@@ -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) {
|
||||
|
||||
+112
-25
@@ -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
Reference in new issue
Block a user