ep_media_upload 0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 DCastelone
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -0,0 +1,266 @@
+# ep_media_upload – BETA: Etherpad Media Upload Plugin
+
+## Overview
+
+A lightweight Etherpad plugin that adds file upload capability via an S3 presigned URL workflow. Upon successful upload, a hyperlink is inserted into the document using the same format as `ep_hyperlinked_text`, making the two plugins fully compatible.
+
+---
+
+## Features
+
+### Toolbar Integration
+- **Paperclip icon** button in the left editbar menu
+- Button is **hidden in read-only mode** (uses `acl-write` class)
+- Triggers native file picker dialog on click
+
+### Upload Workflow
+- **Client-side presigned URL pattern** (identical to ep_images_extended)
+  1. Client requests presigned PUT URL from Etherpad server
+  2. Server generates presigned URL using AWS SDK v3 (credentials from environment variables, not settings.json)
+  3. Client uploads file directly to S3 (server never touches file)
+  4. On success, client inserts hyperlink into document
+- **No base64 or local storage options** – S3 only
+- **Scalable & secure**: Server only generates presigned URLs, no file handling
+
+### File Restrictions
+- **Allowed file types**: Configurable via `settings.json` (array of extensions without dots)
+- **Maximum file size**: Configurable via `settings.json` (in bytes)
+
+### Document Integration
+- On upload success, inserts a **hyperlink** into the document
+- **Link text**: Original filename (e.g., "quarterly-report.pdf")
+- **Link URL**: S3 public/CDN URL for direct download
+- **Hyperlink format**: 100% compatible with `ep_hyperlinked_text` plugin
+  - Uses `hyperlink` attribute with URL value
+  - Renders as clickable `<a>` tag with `target="_blank"`
+
+### Upload Feedback UI
+- **Progress modal** during upload:
+  - Shows "Uploading..." message
+  - Basic visual indicator (e.g., spinner or progress text)
+- **Success state**: Brief confirmation, then modal dismisses
+- **Error state**: Shows error message with dismiss button
+- Modal positioned center-screen (similar to ep_images_extended loader)
+
+---
+
+## Configuration (settings.json)
+
+```jsonc
+"ep_media_upload": {
+  "storage": {
+    "type": "s3_presigned",       // Only supported type
+    "region": "us-east-1",        // AWS region
+    "bucket": "my-bucket-name",   // S3 bucket name
+    "keyPrefix": "uploads/",      // Optional S3 key prefix (for CloudFront path-based routing)
+    "publicURL": "https://cdn.example.com/uploads/",  // Optional CDN URL (should include prefix if using keyPrefix)
+    "expires": 900                // Presigned URL expiry in seconds (default 600)
+  },
+  "fileTypes": ["pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "mp3", "mp4", "wav", "mov", "zip", "txt"],
+  "maxFileSize": 52428800         // 50 MB in bytes
+}
+```
+
+### Storage Options Explained
+
+| Option | Description |
+|--------|-------------|
+| `type` | Must be `"s3_presigned"` (only supported storage type) |
+| `region` | AWS region (e.g., `"us-east-1"`) |
+| `bucket` | S3 bucket name |
+| `keyPrefix` | Optional prefix for S3 keys (e.g., `"uploads/"` → keys become `uploads/padId/uuid.ext`) |
+| `publicURL` | Optional CDN/custom URL base. If using `keyPrefix`, include it in this URL. |
+| `expires` | Presigned URL expiry in seconds (default: 600) |
+
+**Example with CloudFront path-based routing:**
+```jsonc
+"storage": {
+  "type": "s3_presigned",
+  "region": "us-east-1",
+  "bucket": "my-bucket",
+  "keyPrefix": "uploads/",                              // S3 key: uploads/padId/uuid.pdf
+  "publicURL": "https://d123.cloudfront.net/uploads/"   // Public URL includes prefix
+}
+```
+
+### Environment Variables (AWS Credentials)
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `AWS_SESSION_TOKEN` (optional, for temporary credentials)
+
+---
+
+## File Structure
+
+```
+ep_media_upload/
+├── ep.json                 # Plugin manifest (hooks registration)
+├── index.js                # Server-side hooks (presign endpoint, clientVars)
+├── package.json            # NPM package definition
+├── locales/
+│   └── en.json             # English translations
+├── static/
+│   ├── css/
+│   │   └── ep_media_upload.css   # Modal styles
+│   └── js/
+│       └── clientHooks.js        # Client-side upload logic
+└── templates/
+    ├── uploadButton.ejs          # Toolbar button HTML
+    └── uploadModal.ejs           # Progress/error modal HTML
+```
+
+---
+
+## Hook Registration (ep.json)
+
+### Client Hooks
+- `postToolbarInit` – Register toolbar button command
+- `postAceInit` – (Optional) Any initialization after editor ready
+
+### Server Hooks
+- `eejsBlock_editbarMenuLeft` – Inject toolbar button HTML
+- `eejsBlock_body` – Inject modal HTML
+- `expressConfigure` – Register `/p/:padId/pluginfw/ep_media_upload/s3_presign` endpoint
+- `clientVars` – Pass config to client (fileTypes, maxFileSize, storageType)
+- `loadSettings` – Sync settings to runtime
+
+---
+
+## Server Endpoint: Presign
+
+### Route
+```
+GET /p/:padId/pluginfw/ep_media_upload/s3_presign?name=<filename>&type=<mimetype>
+```
+
+### Authentication
+- Validates session (cookie-based or express session)
+- Rate limiting: Max 30 requests per IP per minute (configurable)
+
+### Response
+```json
+{
+  "signedUrl": "https://bucket.s3.region.amazonaws.com/padId/uuid.ext?...",
+  "publicUrl": "https://cdn.example.com/padId/uuid.ext"
+}
+```
+
+### Security
+- File extension validated against allowed `fileTypes`
+- Unique filename generated: `<padId>/<uuid>.<ext>`
+- MIME type passed to S3 for proper Content-Type header
+
+---
+
+## Client Upload Flow
+
+1. User clicks paperclip button
+2. File picker opens (native `<input type="file">`)
+3. User selects file
+4. **Validation** (client-side):
+   - Check file extension against `clientVars.ep_media_upload.fileTypes`
+   - Check file size against `clientVars.ep_media_upload.maxFileSize`
+   - Show error modal if validation fails
+5. **Show upload modal** with "Uploading..." state
+6. **Request presigned URL** from server
+7. **PUT file to S3** using presigned URL
+8. **On success**:
+   - Show brief success message
+   - Dismiss modal
+   - Insert hyperlink at cursor position using `ace_doInsertMediaLink()`
+9. **On failure**:
+   - Show error message in modal
+   - User dismisses manually
+
+---
+
+## Hyperlink Insertion
+
+Uses the same mechanism as `ep_hyperlinked_text`:
+
+```javascript
+// Insert text with hyperlink attribute
+const filename = file.name;  // e.g., "report.pdf"
+const url = publicUrl;       // e.g., "https://cdn.example.com/padId/abc123.pdf"
+
+// Insert filename text at cursor
+editorInfo.ace_replaceRange(cursorPos, cursorPos, filename);
+
+// Apply hyperlink attribute to the inserted text
+docMan.setAttributesOnRange(
+  [cursorPos[0], cursorPos[1]],
+  [cursorPos[0], cursorPos[1] + filename.length],
+  [['hyperlink', url]]
+);
+```
+
+This ensures:
+- Full compatibility with ep_hyperlinked_text rendering
+- Clickable links that open in new tab
+- Proper HTML export with `<a>` tags
+
+---
+
+## Error Handling
+
+| Error | User Message |
+|-------|--------------|
+| Invalid file type | "File type not allowed. Allowed types: pdf, doc, ..." |
+| File too large | "File is too large. Maximum size: 50 MB." |
+| Presign request failed | "Upload failed. Please try again." |
+| S3 upload failed | "Upload failed. Please try again." |
+| Network error | "Network error. Please check your connection." |
+
+---
+
+## Compatibility Notes
+
+- **Etherpad version**: Requires >= 1.8.6 (for ESM Settings module compatibility)
+- **Node.js version**: >= 18.0.0
+- **ep_hyperlinked_text**: Fully compatible – inserted links render/export identically
+- **Read-only pads**: Upload button automatically hidden
+
+---
+
+## Security Considerations
+
+1. **No server-side file handling**: Files never touch the Etherpad server
+2. **Authentication required**: Presign endpoint validates session
+3. **Rate limiting**: Prevents presign endpoint abuse
+4. **File type allowlist**: Only configured extensions accepted
+5. **Unique filenames**: UUIDs prevent enumeration/overwrites
+6. **CORS on S3**: Bucket must allow PUT from pad origins
+
+---
+
+## S3 Bucket CORS Configuration
+
+Required CORS policy for the S3 bucket:
+
+```json
+[
+  {
+    "AllowedOrigins": ["https://your-etherpad-domain.com"],
+    "AllowedMethods": ["PUT"],
+    "AllowedHeaders": ["Content-Type"],
+    "MaxAgeSeconds": 3000
+  }
+]
+```
+
+---
+
+## Dependencies
+
+```json
+{
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.555.0",
+    "@aws-sdk/s3-request-presigner": "^3.555.0"
+  },
+  "peerDependencies": {
+    "ep_etherpad-lite": ">=1.8.6"
+  }
+}
+```
+

package/ep.json

@@ -0,0 +1,20 @@
+{
+  "parts": [
+    {
+      "name": "main",
+      "client_hooks": {
+        "postToolbarInit": "ep_media_upload/static/js/clientHooks",
+        "aceInitialized": "ep_media_upload/static/js/clientHooks",
+        "postAceInit": "ep_media_upload/static/js/clientHooks"
+      },
+      "hooks": {
+        "eejsBlock_editbarMenuLeft": "ep_media_upload/index",
+        "eejsBlock_body": "ep_media_upload/index",
+        "expressConfigure": "ep_media_upload/index",
+        "clientVars": "ep_media_upload/index",
+        "loadSettings": "ep_media_upload/index"
+      }
+    }
+  ]
+}
+

package/index.js

@@ -0,0 +1,361 @@
+'use strict';
+
+const eejs = require('ep_etherpad-lite/node/eejs/');
+// Compat: Etherpad 2.4+ uses ESM for Settings. Support both CJS and ESM.
+const settingsModule = require('ep_etherpad-lite/node/utils/Settings');
+const settings = settingsModule.default || settingsModule;
+const { randomUUID } = require('crypto');
+const path = require('path');
+const url = require('url');
+
+// Security Manager for pad access verification
+let securityManager;
+try {
+  securityManager = require('ep_etherpad-lite/node/db/SecurityManager');
+} catch (e) {
+  console.warn('[ep_media_upload] SecurityManager not available');
+}
+
+// AWS SDK v3 for presigned URLs
+let S3Client, PutObjectCommand, getSignedUrl;
+try {
+  ({ S3Client, PutObjectCommand } = require('@aws-sdk/client-s3'));
+  ({ getSignedUrl } = require('@aws-sdk/s3-request-presigner'));
+} catch (e) {
+  console.warn('[ep_media_upload] AWS SDK not installed; s3_presigned storage will not work.');
+}
+
+// Simple logger
+const logger = {
+  debug: console.debug.bind(console),
+  info: console.info.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+};
+
+// ============================================================================
+// Rate Limiter with Periodic Cleanup
+// ============================================================================
+const _presignRateStore = new Map();
+const PRESIGN_RATE_WINDOW_MS = 60 * 1000;   // 1 minute
+const PRESIGN_RATE_MAX = 30;                // max 30 presigns per IP per min
+const RATE_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // cleanup every 5 minutes
+
+// Periodic cleanup to prevent memory leak from stale IPs
+setInterval(() => {
+  const now = Date.now();
+  for (const [ip, stamps] of _presignRateStore.entries()) {
+    const validStamps = stamps.filter((t) => t > now - PRESIGN_RATE_WINDOW_MS);
+    if (validStamps.length === 0) {
+      _presignRateStore.delete(ip);
+    } else {
+      _presignRateStore.set(ip, validStamps);
+    }
+  }
+}, RATE_CLEANUP_INTERVAL_MS).unref(); // unref() so it doesn't prevent process exit
+
+// Utility: basic per-IP sliding-window rate limit
+const _rateLimitCheck = (ip) => {
+  const now = Date.now();
+  let stamps = _presignRateStore.get(ip) || [];
+  stamps = stamps.filter((t) => t > now - PRESIGN_RATE_WINDOW_MS);
+  if (stamps.length >= PRESIGN_RATE_MAX) return false;
+  stamps.push(now);
+  _presignRateStore.set(ip, stamps);
+  return true;
+};
+
+// ============================================================================
+// Input Validation Helpers
+// ============================================================================
+
+/**
+ * Validate padId to prevent path traversal and injection attacks.
+ * Returns true if valid, false if invalid.
+ */
+const isValidPadId = (padId) => {
+  if (!padId || typeof padId !== 'string') return false;
+  // Reject path traversal sequences
+  if (padId.includes('..')) return false;
+  // Reject null bytes
+  if (padId.includes('\0')) return false;
+  // Allow alphanumeric, hyphens, underscores, and $ (for group pads)
+  // This is permissive but still prevents dangerous characters
+  const safePattern = /^[a-zA-Z0-9_\-$]+$/;
+  return safePattern.test(padId);
+};
+
+/**
+ * Validate filename extension.
+ * Returns the extension (without dot, lowercase) or null if invalid.
+ */
+const getValidExtension = (filename) => {
+  if (!filename || typeof filename !== 'string') return null;
+  const ext = path.extname(filename);
+  if (!ext || ext === '.') return null; // No extension or just a dot
+  return ext.slice(1).toLowerCase(); // Remove leading dot
+};
+
+/**
+ * MIME type to extension mapping for validation.
+ * Maps file extensions to their valid MIME types.
+ */
+const EXTENSION_MIME_MAP = {
+  // Documents
+  pdf: ['application/pdf'],
+  doc: ['application/msword'],
+  docx: ['application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+  xls: ['application/vnd.ms-excel'],
+  xlsx: ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+  ppt: ['application/vnd.ms-powerpoint'],
+  pptx: ['application/vnd.openxmlformats-officedocument.presentationml.presentation'],
+  txt: ['text/plain'],
+  rtf: ['application/rtf', 'text/rtf'],
+  csv: ['text/csv', 'text/plain', 'application/csv'],
+  
+  // Images
+  jpg: ['image/jpeg'],
+  jpeg: ['image/jpeg'],
+  png: ['image/png'],
+  gif: ['image/gif'],
+  webp: ['image/webp'],
+  bmp: ['image/bmp'],
+  svg: ['image/svg+xml'],
+  
+  // Audio
+  mp3: ['audio/mpeg', 'audio/mp3'],
+  wav: ['audio/wav', 'audio/wave', 'audio/x-wav'],
+  ogg: ['audio/ogg'],
+  m4a: ['audio/mp4', 'audio/x-m4a'],
+  flac: ['audio/flac'],
+  
+  // Video
+  mp4: ['video/mp4'],
+  mov: ['video/quicktime'],
+  avi: ['video/x-msvideo'],
+  mkv: ['video/x-matroska'],
+  webm: ['video/webm'],
+  
+  // Archives
+  zip: ['application/zip', 'application/x-zip-compressed'],
+  rar: ['application/vnd.rar', 'application/x-rar-compressed'],
+  '7z': ['application/x-7z-compressed'],
+  tar: ['application/x-tar'],
+  gz: ['application/gzip', 'application/x-gzip'],
+};
+
+/**
+ * Validate that the MIME type matches the file extension.
+ * Returns true if valid, false if mismatch detected.
+ * If extension is not in our map, we allow it (permissive for unknown types).
+ */
+const isValidMimeForExtension = (extension, mimeType) => {
+  if (!extension || !mimeType) return false;
+  
+  const allowedMimes = EXTENSION_MIME_MAP[extension.toLowerCase()];
+  
+  // If we don't have a mapping for this extension, allow any MIME type
+  // (permissive approach for uncommon file types)
+  if (!allowedMimes) return true;
+  
+  // Check if the provided MIME type matches any allowed MIME for this extension
+  const normalizedMime = mimeType.toLowerCase().split(';')[0].trim(); // Handle "text/plain; charset=utf-8"
+  return allowedMimes.some(allowed => allowed === normalizedMime);
+};
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+/**
+ * loadSettings hook
+ * Sync ep_media_upload config into the runtime Settings singleton
+ */
+exports.loadSettings = (hookName, args, cb) => {
+  try {
+    const runtimeSettings = settingsModule.default || settingsModule;
+    if (args && args.settings && args.settings.ep_media_upload) {
+      runtimeSettings.ep_media_upload = args.settings.ep_media_upload;
+    }
+  } catch (e) {
+    console.warn('[ep_media_upload] Failed to sync settings:', e);
+  }
+  cb();
+};
+
+/**
+ * clientVars hook
+ * Exposes plugin settings to client code via clientVars
+ */
+exports.clientVars = (hookName, args, cb) => {
+  const pluginSettings = {
+    storageType: 's3_presigned',
+  };
+
+  if (!settings.ep_media_upload) {
+    settings.ep_media_upload = {};
+  }
+
+  // Pass allowed file types
+  if (settings.ep_media_upload.fileTypes) {
+    pluginSettings.fileTypes = settings.ep_media_upload.fileTypes;
+  }
+
+  // Pass max file size
+  if (settings.ep_media_upload.maxFileSize) {
+    pluginSettings.maxFileSize = settings.ep_media_upload.maxFileSize;
+  }
+
+  return cb({ ep_media_upload: pluginSettings });
+};
+
+/**
+ * eejsBlock_editbarMenuLeft hook
+ * Inject toolbar button
+ */
+exports.eejsBlock_editbarMenuLeft = (hookName, args, cb) => {
+  if (args.renderContext.isReadOnly) return cb();
+  args.content += eejs.require('ep_media_upload/templates/uploadButton.ejs');
+  return cb();
+};
+
+/**
+ * eejsBlock_body hook
+ * Inject modal HTML and CSS
+ */
+exports.eejsBlock_body = (hookName, args, cb) => {
+  const modal = eejs.require('ep_media_upload/templates/uploadModal.ejs');
+  args.content += modal;
+  args.content += "<link href='../static/plugins/ep_media_upload/static/css/ep_media_upload.css' rel='stylesheet'>";
+  return cb();
+};
+
+/**
+ * expressConfigure hook
+ * Register the S3 presign endpoint
+ */
+exports.expressConfigure = (hookName, context) => {
+  logger.info('[ep_media_upload] Registering presign endpoint');
+
+  // Route: GET /p/:padId/pluginfw/ep_media_upload/s3_presign
+  context.app.get('/p/:padId/pluginfw/ep_media_upload/s3_presign', async (req, res) => {
+    const { padId } = req.params;
+
+    /* ------------------ Validate padId ------------------ */
+    if (!isValidPadId(padId)) {
+      return res.status(400).json({ error: 'Invalid pad ID' });
+    }
+
+    /* ------------------ Pad Access Verification ------------------ */
+    // Use Etherpad's SecurityManager to verify user has access to this pad
+    if (securityManager) {
+      try {
+        const sessionCookie = req.cookies?.sessionID || null;
+        const token = req.cookies?.token || null;
+        const user = req.session?.user || null;
+
+        const accessResult = await securityManager.checkAccess(padId, sessionCookie, token, user);
+        if (accessResult.accessStatus !== 'grant') {
+          return res.status(403).json({ error: 'Access denied to this pad' });
+        }
+      } catch (authErr) {
+        logger.error('[ep_media_upload] Access check error:', authErr);
+        return res.status(500).json({ error: 'Access verification failed' });
+      }
+    } else {
+      // Fallback: basic cookie check if SecurityManager unavailable
+      const hasExpressSession = req.session && (req.session.user || req.session.authorId);
+      const hasPadCookie = req.cookies && (req.cookies.sessionID || req.cookies.token);
+      if (!hasExpressSession && !hasPadCookie) {
+        return res.status(401).json({ error: 'Authentication required' });
+      }
+    }
+
+    /* ------------------ Rate limiting --------------------- */
+    const ip = req.ip || req.headers['x-forwarded-for'] || req.connection?.remoteAddress || 'unknown';
+    if (!_rateLimitCheck(ip)) {
+      return res.status(429).json({ error: 'Too many presign requests' });
+    }
+
+    try {
+      const storageCfg = settings.ep_media_upload && settings.ep_media_upload.storage;
+      if (!storageCfg || storageCfg.type !== 's3_presigned') {
+        return res.status(400).json({ error: 's3_presigned storage not configured' });
+      }
+
+      if (!S3Client || !PutObjectCommand || !getSignedUrl) {
+        return res.status(500).json({ error: 'AWS SDK not available on server' });
+      }
+
+      const { bucket, region, publicURL, expires, keyPrefix } = storageCfg;
+      if (!bucket || !region) {
+        return res.status(500).json({ error: 'Invalid S3 configuration: missing bucket or region' });
+      }
+
+      const { name, type } = req.query;
+      if (!name || !type) {
+        return res.status(400).json({ error: 'Missing name or type query parameters' });
+      }
+
+      /* ------------- Extension validation ------------ */
+      const extName = getValidExtension(name);
+      if (!extName) {
+        return res.status(400).json({ error: 'Invalid filename: missing extension' });
+      }
+
+      /* ------------- Extension allow-list ------------ */
+      if (settings.ep_media_upload && settings.ep_media_upload.fileTypes && Array.isArray(settings.ep_media_upload.fileTypes)) {
+        const allowedExts = settings.ep_media_upload.fileTypes;
+        if (!allowedExts.includes(extName)) {
+          return res.status(400).json({ error: 'File type not allowed' });
+        }
+      }
+
+      /* ------------- MIME type validation ------------ */
+      // Prevent MIME type spoofing (e.g., uploading .txt with Content-Type: text/html)
+      if (!isValidMimeForExtension(extName, type)) {
+        logger.warn(`[ep_media_upload] MIME mismatch: ext=${extName}, type=${type}`);
+        return res.status(400).json({ error: 'MIME type does not match file extension' });
+      }
+
+      // Build S3 key with optional prefix for path-based routing (e.g., CloudFront origins)
+      const prefix = keyPrefix || '';
+      const safeExt = `.${extName}`;
+      const objectPath = `${padId}/${randomUUID()}${safeExt}`;  // e.g., "myPad/abc123.pdf"
+      const key = `${prefix}${objectPath}`;                     // e.g., "uploads/myPad/abc123.pdf"
+
+      const s3Client = new S3Client({ region }); // credentials from env / IAM role
+
+      // Extract original filename for Content-Disposition header
+      // This ensures files download with their original name instead of the UUID
+      const originalFilename = path.basename(name);
+      const safeFilename = originalFilename.replace(/[^\w\-_.]/g, '_'); // Sanitize for header
+
+      const putCommand = new PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        ContentType: type,
+        // Force download instead of opening in browser
+        ContentDisposition: `attachment; filename="${safeFilename}"`,
+      });
+
+      const signedUrl = await getSignedUrl(s3Client, putCommand, { expiresIn: expires || 600 });
+
+      // Build public URL:
+      // - If custom publicURL is set (e.g., CDN), it already includes the prefix path
+      // - If no publicURL, use direct S3 URL with full key
+      let publicUrl;
+      if (publicURL) {
+        publicUrl = new url.URL(objectPath, publicURL).toString();
+      } else {
+        const s3Base = `https://${bucket}.s3.${region}.amazonaws.com/`;
+        publicUrl = new url.URL(key, s3Base).toString();
+      }
+
+      return res.json({ signedUrl, publicUrl });
+    } catch (err) {
+      logger.error('[ep_media_upload] S3 presign error', err);
+      return res.status(500).json({ error: 'Failed to generate presigned URL' });
+    }
+  });
+};

package/locales/en.json

@@ -0,0 +1,12 @@
+{
+  "ep_media_upload.toolbar.upload.title": "Upload File",
+  "ep_media_upload.error.title": "Upload Error",
+  "ep_media_upload.error.fileType": "File type not allowed.",
+  "ep_media_upload.error.fileSize": "File is too large. Maximum size is {{maxallowed}} MB.",
+  "ep_media_upload.error.uploadFailed": "Upload failed. Please try again.",
+  "ep_media_upload.error.networkError": "Network error. Please check your connection.",
+  "ep_media_upload.status.uploading": "Uploading...",
+  "ep_media_upload.status.success": "Upload complete!",
+  "ep_media_upload.button.close": "Close"
+}
+

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "ep_media_upload",
+  "description": "beta - Upload files to S3 and insert hyperlinks into the pad. Compatible with ep_hyperlinked_text.",
+  "version": "0.1.0",
+  "author": {
+    "name": "DCastelone",
+    "url": "https://github.com/dcastelone"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.555.0",
+    "@aws-sdk/s3-request-presigner": "^3.555.0"
+  },
+  "peerDependencies": {
+    "ep_etherpad-lite": ">=1.8.6"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "etherpad",
+    "plugin",
+    "ep",
+    "media",
+    "upload",
+    "s3",
+    "file",
+    "attachment"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dcastelone/ep_media_upload"
+  },
+  "bugs": {
+    "url": "https://github.com/dcastelone/ep_media_upload/issues"
+  },
+  "homepage": "https://github.com/dcastelone/ep_media_upload"
+}
+

package/static/css/ep_media_upload.css

@@ -0,0 +1,115 @@
+/* ep_media_upload Modal Styles */
+
+.ep-media-upload-modal {
+  display: none;
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background-color: rgba(0, 0, 0, 0.5);
+  z-index: 10000;
+  justify-content: center;
+  align-items: center;
+}
+
+.ep-media-upload-modal.visible {
+  display: flex;
+}
+
+.ep-media-upload-modal-content {
+  background: #fff;
+  border-radius: 8px;
+  padding: 32px 48px;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25);
+  text-align: center;
+  min-width: 280px;
+  max-width: 400px;
+}
+
+.ep-media-upload-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+}
+
+/* Spinner */
+.ep-media-upload-spinner {
+  width: 40px;
+  height: 40px;
+  border: 4px solid #e0e0e0;
+  border-top-color: #1a73e8;
+  border-radius: 50%;
+  animation: ep-media-upload-spin 1s linear infinite;
+}
+
+@keyframes ep-media-upload-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* Icons */
+.ep-media-upload-icon {
+  width: 48px;
+  height: 48px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 24px;
+  font-weight: bold;
+}
+
+.ep-media-upload-icon-success {
+  background-color: #e6f4ea;
+  color: #1e8e3e;
+}
+
+.ep-media-upload-icon-error {
+  background-color: #fce8e6;
+  color: #d93025;
+}
+
+/* Message text */
+.ep-media-upload-message {
+  margin: 0;
+  font-size: 16px;
+  color: #202124;
+  font-weight: 500;
+}
+
+.ep-media-upload-error-text {
+  color: #d93025;
+}
+
+/* Button */
+.ep-media-upload-btn {
+  margin-top: 8px;
+  padding: 8px 24px;
+  font-size: 14px;
+  font-weight: 500;
+  color: #fff;
+  background-color: #1a73e8;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  transition: background-color 0.2s;
+}
+
+.ep-media-upload-btn:hover {
+  background-color: #1557b0;
+}
+
+.ep-media-upload-btn:focus {
+  outline: 2px solid #1a73e8;
+  outline-offset: 2px;
+}
+
+/* Toolbar button icon - paperclip */
+.buttonicon-attachment::before {
+  content: "📎";
+  font-size: 16px;
+}
+

package/static/js/clientHooks.js

@@ -0,0 +1,277 @@
+'use strict';
+
+/**
+ * ep_media_upload - Client-side hooks
+ * 
+ * Handles file selection, S3 upload via presigned URL, and hyperlink insertion
+ * compatible with ep_hyperlinked_text.
+ */
+
+console.log('[ep_media_upload] Client hooks loaded');
+
+// Store ace context for hyperlink insertion
+let _aceContext = null;
+
+/**
+ * Modal management functions
+ */
+const showModal = (state = 'progress') => {
+  const modal = $('#mediaUploadModal');
+  const progressEl = $('#mediaUploadProgress');
+  const successEl = $('#mediaUploadSuccess');
+  const errorEl = $('#mediaUploadError');
+
+  // Hide all states
+  progressEl.hide();
+  successEl.hide();
+  errorEl.hide();
+
+  // Show requested state
+  if (state === 'progress') {
+    progressEl.show();
+  } else if (state === 'success') {
+    successEl.show();
+  } else if (state === 'error') {
+    errorEl.show();
+  }
+
+  modal.addClass('visible');
+};
+
+const hideModal = () => {
+  $('#mediaUploadModal').removeClass('visible');
+};
+
+const showError = (message) => {
+  $('.ep-media-upload-error-text').text(message);
+  showModal('error');
+};
+
+const showSuccess = () => {
+  showModal('success');
+  // Auto-hide after 1.5 seconds
+  setTimeout(() => {
+    hideModal();
+  }, 1500);
+};
+
+/**
+ * Validate file against configured restrictions
+ */
+const validateFile = (file) => {
+  const config = clientVars.ep_media_upload || {};
+
+  // Check file type
+  if (config.fileTypes && Array.isArray(config.fileTypes)) {
+    const nameParts = file.name.split('.');
+    if (nameParts.length < 2) {
+      const errorMsg = html10n.get('ep_media_upload.error.fileType') || 'File type not allowed.';
+      return { valid: false, error: `${errorMsg} File must have an extension.` };
+    }
+    const ext = nameParts.pop().toLowerCase();
+    if (!config.fileTypes.includes(ext)) {
+      const allowedTypes = config.fileTypes.join(', ');
+      const errorMsg = html10n.get('ep_media_upload.error.fileType') || 'File type not allowed.';
+      return { valid: false, error: `${errorMsg} Allowed: ${allowedTypes}` };
+    }
+  }
+
+  // Check file size
+  if (config.maxFileSize && file.size > config.maxFileSize) {
+    const maxMB = (config.maxFileSize / (1024 * 1024)).toFixed(1);
+    const errorMsg = html10n.get('ep_media_upload.error.fileSize', { maxallowed: maxMB }) 
+      || `File is too large. Maximum size is ${maxMB} MB.`;
+    return { valid: false, error: errorMsg };
+  }
+
+  return { valid: true };
+};
+
+/**
+ * Upload file to S3 using presigned URL
+ */
+const uploadToS3 = async (file) => {
+  // Step 1: Get presigned URL from server
+  const queryParams = $.param({ name: file.name, type: file.type });
+  const presignResponse = await $.getJSON(
+    `${encodeURIComponent(clientVars.padId)}/pluginfw/ep_media_upload/s3_presign?${queryParams}`
+  );
+
+  if (!presignResponse || !presignResponse.signedUrl || !presignResponse.publicUrl) {
+    throw new Error('Invalid presign response from server');
+  }
+
+  // Step 2: Upload directly to S3
+  const uploadResponse = await fetch(presignResponse.signedUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': file.type },
+    body: file,
+  });
+
+  if (!uploadResponse.ok) {
+    throw new Error(`S3 upload failed with status ${uploadResponse.status}`);
+  }
+
+  return presignResponse.publicUrl;
+};
+
+/**
+ * Insert hyperlink at cursor position
+ * Compatible with ep_hyperlinked_text format
+ */
+const doInsertMediaLink = function(url, linkText) {
+  const editorInfo = this.editorInfo;
+  const docMan = this.documentAttributeManager;
+  const rep = editorInfo.ace_getRep();
+
+  if (!editorInfo || !rep || !rep.selStart || !docMan || !url || !linkText) {
+    console.error('[ep_media_upload] Missing context for hyperlink insertion');
+    return;
+  }
+
+  const cursorPos = rep.selStart;
+  const ZWSP = '\u200B'; // Zero-Width Space for boundary
+
+  // Insert: ZWSP + linkText + ZWSP (same pattern as ep_hyperlinked_text)
+  const textToInsert = ZWSP + linkText + ZWSP;
+  editorInfo.ace_replaceRange(cursorPos, cursorPos, textToInsert);
+
+  // Apply hyperlink attribute to the linkText portion (excluding ZWSPs)
+  const linkStart = [cursorPos[0], cursorPos[1] + ZWSP.length];
+  const linkEnd = [cursorPos[0], cursorPos[1] + ZWSP.length + linkText.length];
+
+  docMan.setAttributesOnRange(linkStart, linkEnd, [['hyperlink', url]]);
+
+  // Move cursor after the inserted content
+  const finalPos = [cursorPos[0], cursorPos[1] + textToInsert.length];
+  editorInfo.ace_performSelectionChange(finalPos, finalPos, false);
+
+  console.log('[ep_media_upload] Inserted hyperlink:', linkText, '->', url);
+};
+
+/**
+ * Handle file selection and upload
+ */
+const handleFileUpload = async (file, aceContext) => {
+  // Validate file
+  const validation = validateFile(file);
+  if (!validation.valid) {
+    showError(validation.error);
+    return;
+  }
+
+  // Show progress modal
+  showModal('progress');
+
+  try {
+    // Upload to S3
+    const publicUrl = await uploadToS3(file);
+
+    // Insert hyperlink into document
+    aceContext.callWithAce((ace) => {
+      ace.ace_doInsertMediaLink(publicUrl, file.name);
+    }, 'insertMediaLink', true);
+
+    // Show success
+    showSuccess();
+
+  } catch (err) {
+    console.error('[ep_media_upload] Upload failed:', err);
+    const errorMsg = html10n.get('ep_media_upload.error.uploadFailed') || 'Upload failed. Please try again.';
+    showError(errorMsg);
+  }
+};
+
+/**
+ * aceInitialized hook
+ * Bind the hyperlink insertion function to ace context
+ */
+exports.aceInitialized = (hook, context) => {
+  context.editorInfo.ace_doInsertMediaLink = doInsertMediaLink.bind(context);
+};
+
+/**
+ * postAceInit hook
+ * Set up modal close button handler
+ */
+exports.postAceInit = (hook, context) => {
+  _aceContext = context.ace;
+
+  // Close button handler for error modal
+  $(document).on('click', '#mediaUploadErrorClose', () => {
+    hideModal();
+  });
+
+  // Click outside modal to close (only for error state)
+  $(document).on('click', '#mediaUploadModal', (e) => {
+    if (e.target.id === 'mediaUploadModal' && $('#mediaUploadError').is(':visible')) {
+      hideModal();
+    }
+  });
+};
+
+/**
+ * postToolbarInit hook
+ * Register the mediaUpload toolbar command
+ */
+exports.postToolbarInit = (hook, context) => {
+  const toolbar = context.toolbar;
+
+  toolbar.registerCommand('mediaUpload', () => {
+    // Remove any existing file input (cleanup from previous attempts)
+    $('#mediaUploadFileInput').remove();
+
+    // Create hidden file input
+    const fileInput = $('<input>')
+      .attr({
+        type: 'file',
+        id: 'mediaUploadFileInput',
+        style: 'position:absolute;left:-9999px;'
+      });
+
+    // Add accept attribute if file types are configured
+    if (clientVars.ep_media_upload && clientVars.ep_media_upload.fileTypes) {
+      const accept = clientVars.ep_media_upload.fileTypes
+        .map(ext => `.${ext}`)
+        .join(',');
+      fileInput.attr('accept', accept);
+    }
+
+    $('body').append(fileInput);
+
+    // Cleanup function to remove file input
+    const cleanup = () => {
+      fileInput.off(); // Remove all event handlers
+      fileInput.remove();
+    };
+
+    // Handle file selection - use 'one' so it only fires once
+    fileInput.one('change', (e) => {
+      const files = e.target.files;
+      if (!files || files.length === 0) {
+        cleanup();
+        return;
+      }
+
+      const file = files[0];
+      handleFileUpload(file, context.ace);
+      cleanup();
+    });
+
+    // Handle cancel (user closes file picker without selecting)
+    // The blur/focus trick: when file picker closes, window regains focus
+    $(window).one('focus', () => {
+      // Small delay to allow change event to fire first if file was selected
+      setTimeout(() => {
+        if ($('#mediaUploadFileInput').length > 0) {
+          cleanup();
+        }
+      }, 300);
+    });
+
+    // Trigger file picker
+    fileInput.trigger('click');
+  });
+
+  console.log('[ep_media_upload] Toolbar command registered');
+};

package/templates/uploadButton.ejs

@@ -0,0 +1,8 @@
+<li class="separator acl-write"></li>
+
+<li data-type="button" data-key="mediaUpload" class="acl-write" data-l10n-id="ep_media_upload.toolbar.upload.title">
+  <a class="grouped-left ep_media_upload" data-l10n-id="ep_media_upload.toolbar.upload.title" title="Upload File" aria-label="Upload File">
+    <button class="buttonicon ep_media_upload media_upload buttonicon-attachment" aria-label="Upload File"></button>
+  </a>
+</li>
+

package/templates/uploadModal.ejs

@@ -0,0 +1,18 @@
+<div id="mediaUploadModal" class="ep-media-upload-modal">
+  <div class="ep-media-upload-modal-content">
+    <div id="mediaUploadProgress" class="ep-media-upload-state">
+      <div class="ep-media-upload-spinner"></div>
+      <p class="ep-media-upload-message" data-l10n-id="ep_media_upload.status.uploading">Uploading...</p>
+    </div>
+    <div id="mediaUploadSuccess" class="ep-media-upload-state" style="display: none;">
+      <div class="ep-media-upload-icon ep-media-upload-icon-success">✓</div>
+      <p class="ep-media-upload-message" data-l10n-id="ep_media_upload.status.success">Upload complete!</p>
+    </div>
+    <div id="mediaUploadError" class="ep-media-upload-state" style="display: none;">
+      <div class="ep-media-upload-icon ep-media-upload-icon-error">✕</div>
+      <p class="ep-media-upload-message ep-media-upload-error-text"></p>
+      <button id="mediaUploadErrorClose" class="ep-media-upload-btn" data-l10n-id="ep_media_upload.button.close">Close</button>
+    </div>
+  </div>
+</div>
+