nodebb-plugin-cloudflare-r2 1.0.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

package/README.md

@@ -0,0 +1,53 @@
+# nodebb-plugin-cloudflare-r2 (env)
+
+Upload provider for **NodeBB v4.x** that stores uploads in **Cloudflare R2** (S3-compatible).
+
+This build is **env-first** (no ACP settings page). Configure using environment variables.
+
+## Environment variables
+
+Required:
+- `NODEBB_R2_ACCESS_KEY_ID`
+- `NODEBB_R2_SECRET_ACCESS_KEY`
+- `NODEBB_R2_BUCKET`
+- `NODEBB_R2_ENDPOINT` (example: `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`)
+
+Optional:
+- `NODEBB_R2_REGION` (default: `auto`)
+- `NODEBB_R2_UPLOAD_PATH` (default: empty)
+- `NODEBB_R2_HOST` (public base URL returned to NodeBB; default: `https://<bucket>`)
+- `NODEBB_R2_FORCE_PATH_STYLE` (`true|false`, default: `false`)
+
+Notes:
+- `endpoint` is the **S3 API endpoint** (cloudflarestorage.com)
+- `host` is the **public URL base** (custom domain / CDN / public bucket URL)
+
+## Install
+
+```bash
+cd /path/to/nodebb
+npm i /path/to/nodebb-plugin-cloudflare-r2
+./nodebb build
+./nodebb restart
+```
+
+Enable plugin in ACP → Extend → Plugins.
+
+## Docker Compose example
+
+```yaml
+environment:
+  NODEBB_R2_ACCESS_KEY_ID: "xxx"
+  NODEBB_R2_SECRET_ACCESS_KEY: "yyy"
+  NODEBB_R2_BUCKET: "my-bucket"
+  NODEBB_R2_ENDPOINT: "https://<ACCOUNT_ID>.r2.cloudflarestorage.com"
+  NODEBB_R2_REGION: "auto"
+  NODEBB_R2_UPLOAD_PATH: "uploads"
+  NODEBB_R2_HOST: "https://cdn.example.com"
+  NODEBB_R2_FORCE_PATH_STYLE: "false"
+```
+
+## What it does
+- Hooks: `filter:uploadImage`, `filter:uploadFile`
+- Validates extensions using the **original filename** (fixes drag&drop tmp-path issues)
+- Streams uploads to R2 (does not read entire file into RAM)

package/library.js

@@ -0,0 +1,232 @@
+\
+'use strict';
+
+/**
+ * nodebb-plugin-cloudflare-r2 (env)
+ * - NodeBB v4.x
+ * - Cloudflare R2 via S3 API
+ * - Configuration via environment variables
+ */
+
+const { S3Client } = require('@aws-sdk/client-s3');
+const { Upload } = require('@aws-sdk/lib-storage');
+
+const fs = require('fs');
+const path = require('path');
+const { v4: uuidv4 } = require('uuid');
+const mime = require('mime-types');
+
+const winston = require.main.require('winston');
+const meta = require.main.require('./src/meta');
+const fileModule = require.main.require('./src/file');
+
+const plugin = {};
+plugin._s3 = null;
+
+function env(name, def = '') {
+  const v = process.env[name];
+  return (v !== undefined && v !== null && String(v).length) ? String(v) : def;
+}
+
+function envBool(name, def = false) {
+  const v = process.env[name];
+  if (v === undefined || v === null || String(v).trim() === '') return def;
+  const s = String(v).toLowerCase().trim();
+  return s === 'true' || s === '1' || s === 'on' || s === 'yes';
+}
+
+function normalizePrefix(prefix) {
+  let p = (prefix || '').trim();
+  if (!p) return '';
+  p = p.replace(/^\/+/, '').replace(/\/+$/, '');
+  return p ? `${p}/` : '';
+}
+
+function normalizeFolder(folder) {
+  let f = (folder || '').trim();
+  if (!f) return '';
+  f = f.replace(/^\/+/, '').replace(/\/+$/, '');
+  return f ? `${f}/` : '';
+}
+
+function getSettings() {
+  // Env-only by design
+  return {
+    accessKeyId: env('NODEBB_R2_ACCESS_KEY_ID'),
+    secretAccessKey: env('NODEBB_R2_SECRET_ACCESS_KEY'),
+    bucket: env('NODEBB_R2_BUCKET'),
+    endpoint: env('NODEBB_R2_ENDPOINT'),
+    region: env('NODEBB_R2_REGION', 'auto'),
+    uploadPath: env('NODEBB_R2_UPLOAD_PATH', ''),
+    host: env('NODEBB_R2_HOST', ''),
+    forcePathStyle: envBool('NODEBB_R2_FORCE_PATH_STYLE', false),
+  };
+}
+
+function assertConfigured(s) {
+  const missing = [];
+  if (!s.accessKeyId) missing.push('NODEBB_R2_ACCESS_KEY_ID');
+  if (!s.secretAccessKey) missing.push('NODEBB_R2_SECRET_ACCESS_KEY');
+  if (!s.bucket) missing.push('NODEBB_R2_BUCKET');
+  if (!s.endpoint) missing.push('NODEBB_R2_ENDPOINT');
+
+  if (missing.length) {
+    throw new Error(`nodebb-plugin-cloudflare-r2 :: Missing env vars: ${missing.join(', ')}`);
+  }
+}
+
+function getS3Client(s) {
+  // Recreate client if settings changed (endpoint/key rotation)
+  const fingerprint = `${s.endpoint}|${s.region}|${s.accessKeyId}|${s.bucket}|${s.forcePathStyle}`;
+  if (plugin._s3 && plugin._s3Fingerprint === fingerprint) return plugin._s3;
+
+  plugin._s3 = new S3Client({
+    region: s.region || 'auto',
+    endpoint: s.endpoint,
+    forcePathStyle: !!s.forcePathStyle,
+    credentials: {
+      accessKeyId: s.accessKeyId,
+      secretAccessKey: s.secretAccessKey,
+    },
+  });
+  plugin._s3Fingerprint = fingerprint;
+  return plugin._s3;
+}
+
+function isExtensionAllowed(originalName, allowed) {
+  const extension = path.extname(originalName || '').toLowerCase();
+  return !(
+    allowed.length > 0 &&
+    (!extension || extension === '.' || !allowed.includes(extension))
+  );
+}
+
+function publicUrlForKey(s, key) {
+  let host = (s.host || '').trim();
+  if (!host) {
+    // Fallback; you should set NODEBB_R2_HOST to a real public URL.
+    host = `https://${s.bucket}`;
+  }
+  if (!/^https?:\/\//i.test(host)) host = `https://${host}`;
+  host = host.replace(/\/+$/, '');
+  return `${host}/${key}`;
+}
+
+async function uploadFromPath({ s, filePath, originalName, folder }) {
+  const allowed = fileModule.allowedExtensions();
+
+  // IMPORTANT: validate against original filename, not tmp path
+  if (!isExtensionAllowed(originalName, allowed)) {
+    throw new Error(`[[error:invalid-file-type, ${allowed.join(', ')}]]`);
+  }
+
+  // Check NodeBB's max upload size (KiB)
+  const st = await fs.promises.stat(filePath);
+  const maxBytes = parseInt(meta.config.maximumFileSize, 10) * 1024;
+  if (Number.isFinite(maxBytes) && st.size > maxBytes) {
+    throw new Error(`[[error:file-too-big, ${meta.config.maximumFileSize}]]`);
+  }
+
+  const prefix = normalizePrefix(s.uploadPath);
+  const folderPrefix = normalizeFolder(folder);
+  const ext = path.extname(originalName);
+  const key = `${prefix}${folderPrefix}${uuidv4()}${ext}`;
+
+  const contentType = mime.lookup(originalName) || 'application/octet-stream';
+
+  const client = getS3Client(s);
+  const stream = fs.createReadStream(filePath);
+
+  const uploader = new Upload({
+    client,
+    params: {
+      Bucket: s.bucket,
+      Key: key,
+      Body: stream,
+      ContentType: contentType,
+      ContentLength: st.size,
+    },
+    queueSize: 4,
+    partSize: 8 * 1024 * 1024,
+    leavePartsOnError: false,
+  });
+
+  await uploader.done();
+
+  return {
+    name: originalName,
+    url: publicUrlForKey(s, key),
+  };
+}
+
+plugin.init = async () => {
+  // Validate early and log helpful info (without secrets)
+  try {
+    const s = getSettings();
+    assertConfigured(s);
+    winston.info(`[cloudflare-r2] enabled (bucket=${s.bucket}, endpoint=${s.endpoint}, region=${s.region}, host=${s.host || '(default)'}, forcePathStyle=${s.forcePathStyle})`);
+  } catch (e) {
+    winston.warn(`[cloudflare-r2] not configured: ${e.message}`);
+  }
+};
+
+plugin.uploadImage = async (data) => {
+  const { image, folder } = data || {};
+  if (!image) throw new Error('invalid image');
+
+  const s = getSettings();
+  assertConfigured(s);
+
+  if (image.url) {
+    // Keeping things secure/simple: do not fetch remote URLs.
+    throw new Error('Remote image URLs are not supported. Please upload the file.');
+  }
+
+  const originalName = image.name || image.originalname || image.filename || 'image';
+  if (!image.path) throw new Error('invalid image path');
+
+  try {
+    return await uploadFromPath({
+      s,
+      filePath: image.path,
+      originalName,
+      folder,
+    });
+  } catch (err) {
+    throw createError(err);
+  }
+};
+
+plugin.uploadFile = async (data) => {
+  const { file, folder } = data || {};
+  if (!file) throw new Error('invalid file');
+  if (!file.path) throw new Error('invalid file path');
+
+  const s = getSettings();
+  assertConfigured(s);
+
+  const originalName = file.name || file.originalname || file.filename || 'file';
+
+  try {
+    return await uploadFromPath({
+      s,
+      filePath: file.path,
+      originalName,
+      folder,
+    });
+  } catch (err) {
+    throw createError(err);
+  }
+};
+
+function createError(err) {
+  const e = err instanceof Error ? err : new Error(String(err));
+  // Preserve i18n style messages (e.g., [[error:...]])
+  if (!/\[\[.*\]\]/.test(e.message)) {
+    e.message = `nodebb-plugin-cloudflare-r2 :: ${e.message}`;
+  }
+  winston.error(e.message);
+  return e;
+}
+
+module.exports = plugin;

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "nodebb-plugin-cloudflare-r2",
+  "version": "1.0.0",
+  "description": "NodeBB v4 upload provider for Cloudflare R2 (S3-compatible) using environment variables",
+  "main": "library.js",
+  "author": "You",
+  "license": "MIT",
+  "keywords": [
+    "nodebb",
+    "cloudflare",
+    "r2",
+    "s3",
+    "uploads"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.540.0",
+    "@aws-sdk/lib-storage": "^3.540.0",
+    "mime-types": "^2.1.35",
+    "uuid": "^9.0.1"
+  },
+  "nbbpm": {
+    "compatibility": "^4.0.0"
+  }
+}

package/plugin.json

@@ -0,0 +1,21 @@
+{
+  "id": "nodebb-plugin-cloudflare-r2",
+  "name": "Cloudflare R2 Uploads (Env)",
+  "description": "Stores NodeBB uploads in Cloudflare R2 via the S3 API. Configured via environment variables.",
+  "url": "https://example.invalid/nodebb-plugin-r2-uploads",
+  "library": "library.js",
+  "hooks": [
+    {
+      "hook": "static:app.load",
+      "method": "init"
+    },
+    {
+      "hook": "filter:uploadImage",
+      "method": "uploadImage"
+    },
+    {
+      "hook": "filter:uploadFile",
+      "method": "uploadFile"
+    }
+  ]
+}