Add outgoing webhooks on file arrival

When a file lands in a user's storage, POST a JSON event ({event, at, file}) to each of their
active webhooks (optionally filtered to one folder), HMAC-SHA256 signed when a secret is set.

- Webhook model (+ migration); dispatch fired from the shared storeUserFile pipeline, so app
  uploads, the REST API and (soon) WebDAV all trigger it. Best-effort, never blocks the upload;
  last status/error recorded.
- SSRF-guarded: target URLs are validated (no localhost/private/non-http) at create AND at send.
- The app's /files upload route now goes through storeUserFile too, removing duplicated ingest
  logic and centralising webhook dispatch.
- Account ▸ Webhooks UI: add (url/secret/folder), Test button, status/last-error, delete.
  FR/EN parity (450).

Author: softpython2884

apps/api/prisma/migrations/20260622150000_webhooks/migration.sql

@@ -0,0 +1,20 @@
+-- CreateTable
+CREATE TABLE "Webhook" (
+    "id" TEXT NOT NULL,
+    "ownerId" TEXT NOT NULL,
+    "url" TEXT NOT NULL,
+    "secret" TEXT,
+    "folderId" TEXT,
+    "active" BOOLEAN NOT NULL DEFAULT true,
+    "lastStatus" INTEGER,
+    "lastError" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "Webhook_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "Webhook_ownerId_idx" ON "Webhook"("ownerId");
+
+-- AddForeignKey
+ALTER TABLE "Webhook" ADD CONSTRAINT "Webhook_ownerId_fkey" FOREIGN KEY ("ownerId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

apps/api/prisma/schema.prisma

@@ -70,6 +70,7 @@ model User {
   shares          ShareLink[]
   recoveryCodes   RecoveryCode[]
   apiTokens       ApiToken[]
+  webhooks        Webhook[]
 
   @@index([email])
 }
@@ -295,6 +296,24 @@ model ApiToken {
   @@index([ownerId])
 }
 
+// An outgoing webhook: POSTed when a file lands in the owner's storage (optionally limited to
+// one folder). `secret` (if set) signs the body with HMAC-SHA256. lastStatus/lastError record
+// the most recent delivery for the UI.
+model Webhook {
+  id         String   @id @default(cuid())
+  ownerId    String
+  owner      User     @relation(fields: [ownerId], references: [id], onDelete: Cascade)
+  url        String
+  secret     String?
+  folderId   String?
+  active     Boolean  @default(true)
+  lastStatus Int?
+  lastError  String?
+  createdAt  DateTime @default(now())
+
+  @@index([ownerId])
+}
+
 // A shareable link to a SERVER-mode file or folder. ZK targets can't be shared (the
 // server can't decrypt them). The opaque `token` is the URL slug.
 model ShareLink {

apps/api/src/lib/serialize.ts

@@ -11,6 +11,7 @@ import type {
   RemoteUploadJob,
   ShareLink,
   User,
+  Webhook,
 } from '@prisma/client';
 import type {
   PublicApiToken,
@@ -20,8 +21,22 @@ import type {
   PublicRemoteJob,
   PublicShare,
   PublicUser,
+  PublicWebhook,
 } from '@opencoperlock/shared';
 
+export function toPublicWebhook(w: Webhook): PublicWebhook {
+  return {
+    id: w.id,
+    url: w.url,
+    hasSecret: w.secret !== null && w.secret.length > 0,
+    folderId: w.folderId,
+    active: w.active,
+    lastStatus: w.lastStatus,
+    lastError: w.lastError,
+    createdAt: w.createdAt.toISOString(),
+  };
+}
+
 export function toPublicApiToken(t: ApiToken): PublicApiToken {
   return {
     id: t.id,

apps/api/src/routes/account.ts

@@ -3,16 +3,32 @@
  * permanently delete your account. Both are scoped strictly to the requesting user.
  */
 import type { FastifyPluginAsync } from 'fastify';
-import { passwordConfirmSchema, createQuickCodeSchema, createApiTokenSchema } from '@opencoperlock/shared';
+import {
+  passwordConfirmSchema,
+  createQuickCodeSchema,
+  createApiTokenSchema,
+  createWebhookSchema,
+  assertAllowedUrl,
+  SsrfError,
+} from '@opencoperlock/shared';
 import { prisma } from '../db.js';
 import { parseOr400 } from '../lib/validate.js';
 import { verifyPassword, hashPassword } from '../services/password.js';
 import { remainingRecoveryCodes } from '../services/recovery.js';
-import { toPublicFile, toPublicFolder, toPublicShare, toPublicUser, toPublicQuickCode, toPublicApiToken } from '../lib/serialize.js';
+import {
+  toPublicFile,
+  toPublicFolder,
+  toPublicShare,
+  toPublicUser,
+  toPublicQuickCode,
+  toPublicApiToken,
+  toPublicWebhook,
+} from '../lib/serialize.js';
 import { clearSessionCookie } from '../lib/cookies.js';
 import { audit } from '../services/audit.js';
 import { generateUniqueQuickCode, isCodeTakenError } from '../services/quickCode.js';
 import { generateToken } from '../services/apiToken.js';
+import { sendTestEvent } from '../services/webhooks.js';
 
 export const accountRoutes: FastifyPluginAsync = async (app) => {
   app.addHook('preHandler', app.requireAuth);
@@ -83,6 +99,56 @@ export const accountRoutes: FastifyPluginAsync = async (app) => {
     return { ok: true };
   });
 
+  // ── Outgoing webhooks ────────────────────────────────────────────────────────
+  app.get('/webhooks', async (req) => {
+    const hooks = await prisma.webhook.findMany({ where: { ownerId: req.user!.id }, orderBy: { createdAt: 'desc' } });
+    return { webhooks: hooks.map(toPublicWebhook) };
+  });
+
+  app.post('/webhooks', async (req, reply) => {
+    const body = parseOr400(reply, createWebhookSchema, req.body);
+    if (!body) return;
+    // Reject localhost / private / non-http targets up front (SSRF). Re-checked at send time too.
+    try {
+      assertAllowedUrl(body.url);
+    } catch (err) {
+      if (err instanceof SsrfError) return reply.code(400).send({ error: err.message });
+      throw err;
+    }
+    if (body.folderId) {
+      const folder = await prisma.folder.findFirst({ where: { id: body.folderId, ownerId: req.user!.id } });
+      if (!folder) return reply.code(404).send({ error: 'Folder not found' });
+    }
+    const hook = await prisma.webhook.create({
+      data: {
+        ownerId: req.user!.id,
+        url: body.url,
+        secret: body.secret ?? null,
+        folderId: body.folderId ?? null,
+      },
+    });
+    await audit(req, 'account.webhook.create', { target: hook.id });
+    return reply.code(201).send({ webhook: toPublicWebhook(hook) });
+  });
+
+  app.post('/webhooks/:id/test', async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const hook = await prisma.webhook.findFirst({ where: { id, ownerId: req.user!.id } });
+    if (!hook) return reply.code(404).send({ error: 'Webhook not found' });
+    await sendTestEvent(hook);
+    const updated = await prisma.webhook.findUnique({ where: { id } });
+    return { webhook: updated ? toPublicWebhook(updated) : null };
+  });
+
+  app.delete('/webhooks/:id', async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const existing = await prisma.webhook.findFirst({ where: { id, ownerId: req.user!.id } });
+    if (!existing) return reply.code(404).send({ error: 'Webhook not found' });
+    await prisma.webhook.delete({ where: { id } });
+    await audit(req, 'account.webhook.delete', { target: id });
+    return { ok: true };
+  });
+
   // ── Personal API tokens ──────────────────────────────────────────────────────
   app.get('/api-tokens', async (req) => {
     const tokens = await prisma.apiToken.findMany({

apps/api/src/routes/files.ts

@@ -2,21 +2,12 @@ import type { FastifyPluginAsync } from 'fastify';
 import { updateFileSchema } from '@opencoperlock/shared';
 import { prisma } from '../db.js';
 import { parseOr400 } from '../lib/validate.js';
-import { newStorageKey } from '../storage/index.js';
-import {
-  FileTooLargeError,
-  InfectedFileError,
-  ingestPlaintext,
-} from '../services/ingest.js';
+import { FileTooLargeError, InfectedFileError } from '../services/ingest.js';
+import { storeUserFile, QuotaExhaustedError } from '../services/upload.js';
 import { decryptServerFile } from '../services/download.js';
 import { trashFile } from '../services/trash.js';
-import {
-  findVersionTarget,
-  isVersionable,
-  pruneVersions,
-  snapshotVersion,
-} from '../services/versioning.js';
-import { adjustUsage, remainingAllowance } from '../services/quota.js';
+import { pruneVersions, snapshotVersion } from '../services/versioning.js';
+import { adjustUsage } from '../services/quota.js';
 import { toPublicFile } from '../lib/serialize.js';
 import { audit } from '../services/audit.js';
 
@@ -52,63 +43,22 @@ export const fileRoutes: FastifyPluginAsync = async (app) => {
     const part = await req.file();
     if (!part) return reply.code(400).send({ error: 'No file provided' });
 
-    const allowance = await remainingAllowance(req.user!.id);
-    if (allowance <= 0) return reply.code(413).send({ error: 'Storage quota exhausted' });
-
-    const storageKey = newStorageKey();
     try {
-      const result = await ingestPlaintext(app.ctx, part.file, { maxBytes: allowance, storageKey });
-
-      // Versioning: re-uploading a text-like file under the same name keeps the old
-      // content as a version instead of creating a duplicate row.
-      const existing = isVersionable(part.filename, part.mimetype)
-        ? await findVersionTarget(req.user!.id, folderId ?? null, part.filename)
-        : null;
-
-      if (existing) {
-        await snapshotVersion(existing);
-        const file = await prisma.fileObject.update({
-          where: { id: existing.id },
-          data: {
-            sizeBytes: BigInt(result.sizeBytes),
-            mimeType: part.mimetype,
-            storageKey: result.storageKey,
-            wrappedKey: result.wrappedKey,
-            iv: result.iv,
-            authTag: result.authTag,
-            sha256: result.sha256,
-            avStatus: result.avStatus,
-          },
-        });
-        // New content adds to usage; the retained version keeps the old size.
-        await adjustUsage(req.user!.id, result.sizeBytes);
-        const freed = await pruneVersions(app.ctx, file.id);
-        if (freed > 0) await adjustUsage(req.user!.id, -freed);
-        await audit(req, 'file.version', { target: file.id });
-        return reply.code(201).send({ file: toPublicFile(file) });
-      }
-
-      const file = await prisma.fileObject.create({
-        data: {
-          ownerId: req.user!.id,
-          folderId: folderId ?? null,
-          name: part.filename,
-          sizeBytes: BigInt(result.sizeBytes),
-          mimeType: part.mimetype,
-          storageKey: result.storageKey,
-          encMode: 'SERVER',
-          wrappedKey: result.wrappedKey,
-          iv: result.iv,
-          authTag: result.authTag,
-          sha256: result.sha256,
-          avStatus: result.avStatus,
-        },
+      // Shared pipeline: quota + antivirus + server-side encryption + text-file versioning,
+      // plus outgoing-webhook dispatch — identical to the REST API and WebDAV.
+      const { file, versioned } = await storeUserFile(app.ctx, {
+        ownerId: req.user!.id,
+        folderId: folderId ?? null,
+        stream: part.file,
+        filename: part.filename,
+        mimetype: part.mimetype,
       });
-      await adjustUsage(req.user!.id, result.sizeBytes);
-      await audit(req, 'file.upload', { target: file.id });
+      await audit(req, versioned ? 'file.version' : 'file.upload', { target: file.id });
       return reply.code(201).send({ file: toPublicFile(file) });
     } catch (err) {
-      await app.ctx.storage.delete(storageKey).catch(() => {});
+      if (err instanceof QuotaExhaustedError) {
+        return reply.code(413).send({ error: 'Storage quota exhausted' });
+      }
       if (err instanceof FileTooLargeError) {
         return reply.code(413).send({ error: 'Upload exceeds your available quota' });
       }

apps/api/src/services/upload.ts

@@ -11,6 +11,7 @@ import { newStorageKey } from '../storage/index.js';
 import { ingestPlaintext } from './ingest.js';
 import { adjustUsage, remainingAllowance } from './quota.js';
 import { findVersionTarget, isVersionable, pruneVersions, snapshotVersion } from './versioning.js';
+import { dispatchFileEvent } from './webhooks.js';
 
 export class QuotaExhaustedError extends Error {
   constructor() {
@@ -62,6 +63,7 @@ export async function storeUserFile(ctx: AppContext, opts: StoreFileOpts): Promi
       await adjustUsage(opts.ownerId, result.sizeBytes);
       const freed = await pruneVersions(ctx, file.id);
       if (freed > 0) await adjustUsage(opts.ownerId, -freed);
+      void dispatchFileEvent(opts.ownerId, file, 'file.updated');
       return { file, versioned: true };
     }
 
@@ -82,6 +84,7 @@ export async function storeUserFile(ctx: AppContext, opts: StoreFileOpts): Promi
       },
     });
     await adjustUsage(opts.ownerId, result.sizeBytes);
+    void dispatchFileEvent(opts.ownerId, file, 'file.created');
     return { file, versioned: false };
   } catch (err) {
     await ctx.storage.delete(storageKey).catch(() => {});

apps/api/src/services/webhooks.ts

@@ -0,0 +1,57 @@
+/**
+ * Outgoing webhooks: when a file lands in a user's storage we POST a small JSON event to each of
+ * their active webhooks (optionally filtered to one folder). Delivery is best-effort and never
+ * blocks the upload; the last status/error is recorded for the UI.
+ *
+ * The body is signed with HMAC-SHA256 when a secret is set (header X-OpenCoperLock-Signature),
+ * and every target URL is re-checked against the SSRF guard at send time so a webhook can't be
+ * pointed at localhost or a private address.
+ */
+import { createHmac } from 'node:crypto';
+import type { FileObject, Webhook } from '@prisma/client';
+import { assertAllowedUrl } from '@opencoperlock/shared';
+import { prisma } from '../db.js';
+import { toPublicFile } from '../lib/serialize.js';
+
+export type WebhookEvent = 'file.created' | 'file.updated';
+
+const TIMEOUT_MS = 8000;
+
+function sign(secret: string, body: string): string {
+  return `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`;
+}
+
+async function deliver(hook: Webhook, body: string): Promise<void> {
+  try {
+    assertAllowedUrl(hook.url); // re-validate at send time (defence in depth)
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      'user-agent': 'OpenCoperLock-Webhook/1',
+    };
+    if (hook.secret) headers['x-opencoperlock-signature'] = sign(hook.secret, body);
+    const res = await fetch(hook.url, { method: 'POST', headers, body, signal: AbortSignal.timeout(TIMEOUT_MS) });
+    await prisma.webhook.update({
+      where: { id: hook.id },
+      data: { lastStatus: res.status, lastError: res.ok ? null : `HTTP ${res.status}` },
+    });
+  } catch (err) {
+    await prisma.webhook
+      .update({ where: { id: hook.id }, data: { lastStatus: 0, lastError: String(err).slice(0, 200) } })
+      .catch(() => {});
+  }
+}
+
+/** Fire matching webhooks for a stored file. Fire-and-forget — callers should not await it. */
+export async function dispatchFileEvent(ownerId: string, file: FileObject, event: WebhookEvent): Promise<void> {
+  const hooks = await prisma.webhook.findMany({ where: { ownerId, active: true } });
+  const matching = hooks.filter((h) => !h.folderId || h.folderId === file.folderId);
+  if (matching.length === 0) return;
+  const body = JSON.stringify({ event, at: new Date().toISOString(), file: toPublicFile(file) });
+  await Promise.all(matching.map((h) => deliver(h, body)));
+}
+
+/** Send a one-off test ping to a single webhook (used by the "Test" button). */
+export async function sendTestEvent(hook: Webhook): Promise<void> {
+  const body = JSON.stringify({ event: 'ping', at: new Date().toISOString(), message: 'OpenCoperLock test event' });
+  await deliver(hook, body);
+}