@startupjs-ui/file-input 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.2.1](https://github.com/startupjs/startupjs-ui/compare/v0.2.0...v0.2.1) (2026-05-11)
+
+
+### Features
+
+* **file-input:** provide server-side hooks for the 'files' plugin server config to check access to file operations and to transform the file during upload. Add types to the 'files' plugin to work with teamplay's type augmentation. ([bd527ad](https://github.com/startupjs/startupjs-ui/commit/bd527adcc2be0762af8439561cc39dcb44a7f991))
+
+
+
+
+
 # [0.2.0](https://github.com/startupjs/startupjs-ui/compare/v0.1.23...v0.2.0) (2026-05-04)
 
 

package/README.mdx

@@ -93,6 +93,37 @@ FileInput supports multiple storage backends. By default it uses SQLite, but if
 - Requires `AZURE_BLOB_STORAGE_CONNECTION_STRING`.
 - Install the Azure SDK: `yarn add @azure/storage-blob`.
 
+## Server access hooks
+
+By default, file URLs are public to anyone who knows the `fileId`. The `files` model is read-only for direct client access: reads are allowed, while create/update/delete are done through the upload and delete API routes.
+
+Use `$file.getUrl()`, `$file.getDownloadUrl()`, `$.files.getUrl(fileId)`, or `$.files.getDownloadUrl(fileId)` to build file URLs. When StartupJS JWT auth is active and `$.session.token` exists, these helpers automatically append `access_token` to the URL so server `canRead` checks can see `req.session`.
+
+Use plugin server options to add app-specific checks:
+
+```js
+export default {
+  plugins: {
+    files: {
+      server: {
+        canRead: ({ source, session, fileId, file }) => true,
+        canUpload: ({ session, fileId, file, meta, blob }) => true,
+        canDelete: ({ session, fileId, file }) => true,
+        transformUpload: ({ meta, blob }) => ({
+          meta: {
+            ...meta,
+            filename: meta.filename?.toLowerCase()
+          },
+          blob
+        })
+      }
+    }
+  }
+}
+```
+
+`canRead` is reused for both file API reads (`source: 'api'`) and direct `$.files[fileId]` model reads (`source: 'model'`). Return `true` to allow the operation; any other value denies it. If you build file URLs manually, include your own auth token or use the model URL helpers above.
+
 ## Sandbox
 
 <Sandbox

package/files.plugin.d.ts

@@ -0,0 +1,79 @@
+import type { CollectionSpec, Signal, SignalModelConstructor } from 'startupjs'
+
+export interface FileDoc {
+  storageType: string
+  mimeType: string
+  filename?: string
+  encoding?: string
+  extension?: string
+  createdAt: number
+  updatedAt: number
+}
+
+export interface FileAccessContext {
+  source: 'api' | 'model'
+  session?: any
+  fileId: string
+  file?: FileDoc
+  req?: any
+}
+
+export interface FileUploadContext {
+  source: 'api'
+  session?: any
+  fileId?: string
+  file?: FileDoc
+  req: any
+  blob: unknown
+  meta: Partial<FileDoc>
+}
+
+export interface FileDeleteContext {
+  source: 'api'
+  session?: any
+  fileId: string
+  file: FileDoc
+  req: any
+}
+
+export interface FileUploadTransformResult {
+  fileId?: string
+  blob?: unknown
+  meta?: Partial<FileDoc>
+}
+
+export interface FilesPluginServerOptions {
+  canRead?: (context: FileAccessContext) => boolean | Promise<boolean>
+  canUpload?: (context: FileUploadContext) => boolean | Promise<boolean>
+  canDelete?: (context: FileDeleteContext) => boolean | Promise<boolean>
+  transformUpload?: (context: FileUploadContext) => FileUploadTransformResult | void | Promise<FileUploadTransformResult | void>
+}
+
+interface FilesModel extends Signal<FileDoc[]> {
+  addNew (file: Omit<FileDoc, 'createdAt' | 'updatedAt'>): Promise<string>
+  getUrl (fileId: string, extension?: string): string
+  getDownloadUrl (fileId: string, extension?: string): string
+  getUploadUrl (fileId?: string): string
+  getDeleteUrl (fileId: string): string
+}
+
+interface FileModel extends Signal<FileDoc> {
+  getUrl (): string
+  getDownloadUrl (): string
+  getUploadUrl (): string
+  getDeleteUrl (): string
+  getBlob (): Promise<Blob>
+}
+
+type FilesModelConstructor = SignalModelConstructor<FileDoc[], FilesModel>
+type FileModelConstructor = SignalModelConstructor<FileDoc, FileModel>
+
+declare module 'teamplay' {
+  interface TeamplayPluginCollections {
+    '@startupjs-ui/file-input/files': {
+      files: CollectionSpec<FileDoc, FilesModelConstructor, FileModelConstructor>
+    }
+  }
+}
+
+export {}

package/files.plugin.js

@@ -1,4 +1,4 @@
-import { $, BASE_URL, serverOnly, Signal, sub } from 'startupjs'
+import { $, BASE_URL, accessControl, serverOnly, Signal, sub } from 'startupjs'
 import { createPlugin } from 'startupjs/registry'
 import busboy from 'busboy'
 import sharp from 'sharp'
@@ -10,14 +10,26 @@ export default createPlugin({
   name: 'files',
   enabled: true,
   order: 'system ui',
-  isomorphic: () => ({
+  isomorphic: (_options, plugin) => ({
     models: models => {
       return {
         ...models,
         files: {
           default: FilesModel,
           schema,
-          ...models.files
+          ...models.files,
+          access: accessControl(models.files?.access || {
+            read: ({ session, docId, doc }) => {
+              const canRead = getServerOptions(plugin).canRead
+              if (!canRead) return true
+              return canRead({
+                source: 'model',
+                session,
+                fileId: docId,
+                file: doc
+              })
+            }
+          }, { force: true })
         },
         'files.*': {
           default: FileModel,
@@ -26,7 +38,7 @@ export default createPlugin({
       }
     }
   }),
-  server: () => ({
+  server: (options = {}) => ({
     serverRoutes: expressApp => {
       expressApp.get(GET_FILE_URL, async (req, res) => {
         let { fileId } = req.params
@@ -45,6 +57,13 @@ export default createPlugin({
         if (!mimeType) return res.status(500).send(ERRORS.fileMimeTypeNotSet)
         const isVideo = mimeType.startsWith('video/') || isVideoRequest
         if (!storageType) return res.status(500).send(ERRORS.fileStorageTypeNotSet)
+        if (!await isAllowed(options.canRead, {
+          source: 'api',
+          req,
+          session: req.session,
+          fileId,
+          file
+        }, res)) return
 
         // handle client-side caching of files
         const clientEtag = req.get('If-None-Match')
@@ -218,7 +237,7 @@ export default createPlugin({
           stream.on('data', data => buffers.push(data))
 
           stream.on('end', async () => {
-            const blob = Buffer.concat(buffers)
+            let blob = Buffer.concat(buffers)
             meta = { filename, mimeType, encoding, storageType }
             if (!blob) return res.status(500).send('No file was uploaded')
 
@@ -227,6 +246,27 @@ export default createPlugin({
             const extension = meta.filename?.match(/\.([^.]+)$/)?.[1]
             if (extension) meta.extension = extension
             try {
+              const file = fileId ? (await sub($.files[fileId])).get() : undefined
+              const accessContext = {
+                source: 'api',
+                req,
+                session: req.session,
+                fileId,
+                file,
+                blob,
+                meta
+              }
+              if (!await isAllowed(options.canUpload, accessContext, res)) return
+
+              if (options.transformUpload) {
+                const transformed = await options.transformUpload(accessContext)
+                if (transformed) {
+                  if ('fileId' in transformed) fileId = transformed.fileId
+                  if ('blob' in transformed) blob = transformed.blob
+                  if ('meta' in transformed) meta = transformed.meta
+                }
+              }
+
               fileId = await uploadBuffer(blob, { fileId, meta })
             } catch (err) {
               console.error(err)
@@ -247,6 +287,13 @@ export default createPlugin({
         if (!file) return res.status(404).send(ERRORS.fileNotFound)
         const { storageType } = file
         if (!storageType) return res.status(500).send(ERRORS.fileStorageTypeNotSet)
+        if (!await isAllowed(options.canDelete, {
+          source: 'api',
+          req,
+          session: req.session,
+          fileId,
+          file
+        }, res)) return
         try {
           await deleteFile(storageType, fileId)
           await $file.del()
@@ -260,6 +307,23 @@ export default createPlugin({
   })
 })
 
+function getServerOptions (plugin) {
+  return plugin.optionsByEnv?.server || {}
+}
+
+async function isAllowed (hook, context, res) {
+  if (!hook) return true
+  try {
+    if (await hook(context)) return true
+  } catch (err) {
+    console.error(err)
+    res.status(500).send('Error checking file access')
+    return false
+  }
+  res.status(403).send(ERRORS.accessDenied)
+  return false
+}
+
 const schema = {
   storageType: { type: 'string', required: true },
   mimeType: { type: 'string', required: true },
@@ -284,11 +348,11 @@ class FilesModel extends Signal {
   }
 
   getUrl (fileId, extension) {
-    return BASE_URL + getFileUrl(fileId, extension)
+    return getFileUrlWithAccessToken(fileId, extension)
   }
 
   getDownloadUrl (fileId, extension) {
-    return BASE_URL + getFileUrl(fileId, extension) + '?download=true'
+    return getFileUrlWithAccessToken(fileId, extension, { download: true })
   }
 
   getUploadUrl (fileId) {
@@ -302,11 +366,11 @@ class FilesModel extends Signal {
 
 class FileModel extends Signal {
   getUrl () {
-    return BASE_URL + getFileUrl(this.getId(), this.extension.get())
+    return getFileUrlWithAccessToken(this.getId(), this.extension.get())
   }
 
   getDownloadUrl () {
-    return this.getUrl() + '?download=true'
+    return getFileUrlWithAccessToken(this.getId(), this.extension.get(), { download: true })
   }
 
   getUploadUrl () {
@@ -322,7 +386,25 @@ class FileModel extends Signal {
   })
 }
 
+function getFileUrlWithAccessToken (fileId, extension, query = {}) {
+  const token = $.session.token.get()
+  return addQuery(BASE_URL + getFileUrl(fileId, extension), {
+    ...query,
+    ...(token ? { access_token: token } : {})
+  })
+}
+
+function addQuery (url, query) {
+  const search = Object.entries(query)
+    .filter(([, value]) => value != null && value !== false)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+    .join('&')
+  if (!search) return url
+  return url + (url.includes('?') ? '&' : '?') + search
+}
+
 const ERRORS = {
+  accessDenied: 'Access denied',
   fileNotFound: 'File not found',
   fileMimeTypeNotSet: 'File mimeType is not set. This should never happen',
   fileStorageTypeNotSet: 'File storageType is not set. This should never happen'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startupjs-ui/file-input",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -14,7 +14,10 @@
     "./deleteFile": "./deleteFile.ts",
     "./uploadFile": "./uploadFile.ts",
     "./providers": "./providers/index.js",
-    "./files.plugin": "./files.plugin.js"
+    "./files.plugin": {
+      "types": "./files.plugin.d.ts",
+      "default": "./files.plugin.js"
+    }
   },
   "dependencies": {
     "@fortawesome/free-solid-svg-icons": "^7.1.0",
@@ -46,5 +49,5 @@
       "optional": true
     }
   },
-  "gitHead": "0c586b841cba1c9d820542f6eca07470f5ea2659"
+  "gitHead": "38511829e3e4f084aecc79ae563e83286e319249"
 }