Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,432 @@
import { authorizeStorageObjectAccess, authorizeStorageUploadConstraints } from "@toolctrl/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 { verifyMailjetWebhookAuth } from "../webhooks/mailjet-webhook-auth.js";
import {
missingApiTenantScopeError,
parseMaintenanceTake,
parseOptionalTenantId,
parseStorageObjectStatus,
readOptionalJsonObjectBody,
requireWorkspaceServiceCredential,
authenticateServiceCredentialRequest,
apiKeyScopedMissingResourceError,
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"];
export function registerMaintenanceRoutes(app: Hono<ApiEnv>) {
app.post("/v1/ai/upload", uploadAiFileRequest);
app.post("/v1/support/inbound-email", postSupportInboundEmailRequest);
app.post("/v1/email-sequences/mailjet/webhooks", (c) =>
postMailjetEmailSequenceWebhookRequest(c, {
webhookSecret: getApiRuntimeConfig().mailjet.webhookSecret,
markEmailSequenceDeliveryBounced: getApiAppDependencies().markEmailSequenceDeliveryBounced,
})
);
app.post("/v1/events/webhooks/attempts/:id", postEventWebhookAttemptRequest);
app.post("/v1/maintenance/export-retention/enqueue", postExportRetentionEnqueueRequest);
app.get("/v1/exports/:exportJobId/download-url", getExportDownloadUrlRequest);
app.get("/v1/exports/:exportJobId/progress", getExportProgressRequest);
}
async function postSupportInboundEmailRequest(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 payloadResult = parseInboundEmailPayload(rawBody);
if (!payloadResult.ok) {
return apiError(c, 400, "invalid_request", payloadResult.error);
}
const result = await getApiAppDependencies().createInboundSupportTicketFromEmail(payloadResult.value);
if (result.status === "unknown-recipient") {
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") },
});
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.");
}
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.");
}
}
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;
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();
try {
const dependencies = getApiAppDependencies();
const attemptId = c.req.param("id") || "";
attempt = await dependencies.findLegacyEventWebhookAttemptById(attemptId);
if (!attempt) {
throw new Error("Invalid event webhook attempt");
}
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(
{ 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.");
}
}
async function markWebhookAttemptUnavailable(attempt: LegacyEventWebhookAttempt) {
await getApiAppDependencies().updateLegacyEventWebhookAttempt(
{ id: attempt.id, tenantId: attempt.tenantId },
{ finishedAt: new Date(), success: false, status: 503, message: "Webhook delivery queue is unavailable." }
);
}
async function postExportRetentionEnqueueRequest(c: Context<ApiEnv>) {
const credentialError = requireWorkspaceServiceCredential(c);
if (credentialError) {
return credentialError;
}
const bodyResult = await readOptionalJsonObjectBody(c.req.raw);
if (!bodyResult.ok) {
return apiError(c, 400, "invalid_request", bodyResult.error);
}
const body = bodyResult.value;
const unexpectedKeys = Object.keys(body ?? {}).filter((key) => key !== "take");
if (unexpectedKeys.length > 0) {
return apiError(c, 400, "invalid_request", "Unexpected export retention enqueue fields.");
}
const rawIdempotencyKey = c.req.header("idempotency-key");
const idempotencyKey = normalizeIdempotencyKey(rawIdempotencyKey) ?? undefined;
if (rawIdempotencyKey !== undefined && !idempotencyKey) {
return apiError(c, 400, "invalid_request", "Idempotency-Key header must be a non-empty string when provided.");
}
const takeResult = parseMaintenanceTake(body);
if (!takeResult.ok) {
return apiError(c, 400, "invalid_request", takeResult.error);
}
const requestId = c.get("requestId");
let queueResult;
try {
queueResult = await getApiAppDependencies().queueExportArtifactRetention({ requestId, idempotencyKey, take: takeResult.value });
} catch {
return apiError(c, 503, "maintenance_queue_unavailable", "Maintenance queue is unavailable: queue enqueue failed.");
}
if (!queueResult.enqueued) {
if (queueResult.reason === "maintenance-worker-disabled") {
return apiError(c, 503, "maintenance_queue_unavailable", "Maintenance queue is unavailable: export retention worker is disabled.");
}
return apiError(c, 503, "maintenance_queue_unavailable", "Maintenance queue is unavailable: missing Redis connection.");
}
return c.json({ enqueued: true, task: "expired-export-artifacts", jobId: String(queueResult.job.id ?? ""), requestId }, 202);
}
async function getExportDownloadUrlRequest(c: Context<ApiEnv>) {
const principal = await authenticateServiceCredentialRequest(c);
if (!principal) {
return apiError(c, 401, "unauthorized", "A valid service credential or API key is required.");
}
const exportJobId = c.req.param("exportJobId");
if (!exportJobId) {
return apiError(c, 400, "invalid_request", "Expected exportJobId.");
}
const requestedTenantScope = parseOptionalTenantId(c);
if (!requestedTenantScope.ok) {
return apiError(c, 400, "invalid_request", requestedTenantScope.error);
}
const resolvedTenantScope = resolveApiTenantScope(principal, requestedTenantScope.value);
if (!resolvedTenantScope.allowed) {
return forbiddenApiKeyScopeError(c);
}
const lookupTenantId = resolvedTenantScope.tenantId;
if (!lookupTenantId) {
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 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.");
}
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.");
}
}
function getExportArtifactExtension(exportJob: Pick<ExportJobDownloadRecord, "format" | "artifactKey">) {
const artifactExtension = exportJob.artifactKey?.match(/\.([A-Za-z0-9]+)$/)?.[1]?.toLowerCase();
if (artifactExtension && ["csv", "json", "xlsx"].includes(artifactExtension)) {
return artifactExtension;
}
return exportJob.format;
}
async function getExportProgressRequest(c: Context<ApiEnv>) {
const principal = await authenticateServiceCredentialRequest(c);
if (!principal) {
return apiError(c, 401, "unauthorized", "A valid service credential or API key is required.");
}
const exportJobId = c.req.param("exportJobId");
if (!exportJobId) {
return apiError(c, 400, "invalid_request", "Expected exportJobId.");
}
const requestedTenantScope = parseOptionalTenantId(c);
if (!requestedTenantScope.ok) {
return apiError(c, 400, "invalid_request", requestedTenantScope.error);
}
const resolvedTenantScope = resolveApiTenantScope(principal, requestedTenantScope.value);
if (!resolvedTenantScope.allowed) {
return forbiddenApiKeyScopeError(c);
}
const lookupTenantId = resolvedTenantScope.tenantId;
if (!lookupTenantId) {
return apiError(c, 400, "invalid_request", "tenantId is required.");
}
const progress = await getApiAppDependencies().readExportProgress({ exportJobId, tenantId: lookupTenantId });
if (!progress) {
return c.json({ exportJobId, processedRows: 0, totalEstimate: null, updatedAt: null, requestId: c.get("requestId") });
}
return c.json({
exportJobId,
processedRows: progress.processedRows,
totalEstimate: progress.totalEstimate,
updatedAt: progress.updatedAt,
requestId: c.get("requestId"),
});
}