BlueGit

timfa filemanager

Files

filemanager / server / api / v1.js

v1.js

v1.js 34.2 KiB Download Raw
1'use strict';
2
3// Public, versioned file API for sync clients (phones, desktops, services).
4// Auth: Bearer access tokens from /oauth/token or personal access tokens.
5// Every request is checked with the same permission helpers as the web UI,
6// so a token can never see or change more than its user.
7
8const express = require('express');
9const fs = require('fs');
10const path = require('path');
11const crypto = require('crypto');
12const { pipeline } = require('stream/promises');
13const { Transform } = require('stream');
14
15const store = require('./store');
16const syncIndex = require('./sync-index');
17const { getDb } = require('../db');
18const { getClientIp } = require('../auth');
19const { logError } = require('../logger');
20const { publicBaseUrl } = require('../public-url');
21const filesRouter = require('../routes/files');
22const { deleteIndexUnder, rewriteIndexPaths, reindexDirectoryTree } = require('../search-index');
23const { enqueueFileHash } = require('../file-hash-queue');
24
25const helpers = filesRouter.helpers;
26const router = express.Router();
27const json = express.json({ limit: '256kb' });
28
29const USER_ROOT_ID = '~';
30const GB = 1024 ** 3;
31const MB = 1024 ** 2;
32const DEFAULTS = {
33 maxUploadBytes: 10 * GB,
34 maxChunkBytes: 64 * MB,
35 maxOpenUploadsPerUser: 20,
36 uploadTtlHours: 24,
37 maxHashBytes: 4 * GB,
38 scanIntervalSeconds: 15,
39 maxSyncEntries: 500000,
40};
41const API_UPLOAD_DIR_DEFAULT = path.join(__dirname, '../../api-uploads');
42
43// ---------------------------------------------------------------------------
44// Helpers
45// ---------------------------------------------------------------------------
46
47class ApiError extends Error
48{
49 constructor (status, code, message, extra)
50 {
51 super(message);
52 this.status = status;
53 this.code = code;
54 this.extra = extra;
55 }
56}
57
58function apiConfig (config)
59{
60 const raw = config && typeof config.api === 'object' && config.api ? config.api : {};
61 const out = { ...DEFAULTS };
62 for (const k of Object.keys(DEFAULTS))
63 {
64 const v = Number(raw[k]);
65 if (Number.isFinite(v) && v > 0) out[k] = v;
66 }
67 out.uploadDir = typeof raw.uploadDir === 'string' && raw.uploadDir.trim() ? raw.uploadDir.trim() : API_UPLOAD_DIR_DEFAULT;
68 return out;
69}
70
71function sendError (res, err)
72{
73 if (!(err instanceof ApiError))
74 {
75 logError('API v1 request failed', err);
76 err = new ApiError(500, 'internal_error', 'Internal server error.');
77 }
78 if (res.headersSent) { res.destroy(); return; }
79 res.status(err.status).json({ error: err.code, message: err.message, ...(err.extra || {}) });
80}
81
82const wrap = (fn) => (req, res) => Promise.resolve(fn(req, res)).catch((err) => sendError(res, err));
83
84function parseEtag (value)
85{
86 const v = String(value || '').trim();
87 if (!v) return null;
88 return v.replace(/^W\//, '').replace(/^"|"$/g, '');
89}
90
91function loadApiUser (username)
92{
93 const row = getDb().prepare('SELECT id, username, is_admin, permissions FROM users WHERE username = ?').get([username]);
94 if (!row) return null;
95 let permissions = {};
96 try { permissions = JSON.parse(row.permissions || '{}'); } catch { permissions = {}; }
97 return { id: row.id, username: row.username, isAdmin: row.is_admin === 1, permissions };
98}
99
100function authenticate (req, res, next)
101{
102 const header = req.get('authorization') || '';
103 const token = header.startsWith('Bearer ') ? header.slice(7).trim() : '';
104 const resolved = store.resolveBearer(token);
105 const user = resolved ? loadApiUser(resolved.grant.username) : null;
106 if (!resolved || !user)
107 {
108 res.set('WWW-Authenticate', 'Bearer error="invalid_token"');
109 return res.status(401).json({ error: 'invalid_token', message: 'Missing, invalid, expired or revoked access token.' });
110 }
111 store.touchGrant(resolved.grant.id, getClientIp(req));
112 req.user = user;
113 req.apiGrant = resolved.grant;
114 req.apiScopes = resolved.scopes;
115 next();
116}
117
118function requireScope (scope)
119{
120 return (req, res, next) =>
121 {
122 if (!req.apiScopes.includes(scope))
123 {
124 res.set('WWW-Authenticate', `Bearer error="insufficient_scope", scope="${scope}"`);
125 return res.status(403).json({ error: 'insufficient_scope', message: `This token lacks the ${scope} scope.` });
126 }
127 next();
128 };
129}
130
131/** Roots visible to the user, keyed by a stable id used in virtual paths. */
132function rootsForUser (user)
133{
134 const { config, roots } = helpers.loadConfigAndRoots();
135 const aliases = config.rootAliases && typeof config.rootAliases === 'object' ? config.rootAliases : {};
136 const list = [];
137 const userFolder = helpers.getUserFolderPath(config, user.username);
138 if (userFolder)
139 {
140 try { fs.mkdirSync(userFolder, { recursive: true }); } catch { /* non-fatal */ }
141 list.push({ id: USER_ROOT_ID, name: 'My Folder', abs: path.resolve(userFolder), writable: true, isUserFolder: true });
142 }
143 const seen = new Set(list.map((r) => r.id));
144 for (const r of roots)
145 {
146 const label = path.basename(r);
147 if (!helpers.canRead(user, label) || seen.has(label)) continue;
148 const info = helpers.resolveRootForUser(r, roots, user, config);
149 seen.add(label);
150 list.push({
151 id: label,
152 name: String(aliases[path.resolve(r)] || '').trim() || label,
153 abs: path.resolve(r),
154 writable: !!(info && helpers.canWriteInfo(user, info)),
155 isUserFolder: false,
156 });
157 }
158 return { config, roots, list };
159}
160
161function validSegment (s)
162{
163 return s && s !== '.' && s !== '..' && !s.includes('\0') && !s.includes('\\') && Buffer.byteLength(s) <= 255;
164}
165
166/**
167 * Resolve a virtual path ("/<root>/a/b") for the user. Throws ApiError.
168 * Returns { root, rel, abs, vpath, config, info }.
169 */
170function resolvePath (user, vpath, { write = false, ctx } = {})
171{
172 const raw = String(vpath == null ? '' : vpath);
173 if (!raw.startsWith('/')) throw new ApiError(400, 'invalid_path', 'Paths must start with /<root-id>/.');
174 if (raw.length > 4096) throw new ApiError(400, 'invalid_path', 'Path too long.');
175 const parts = raw.split('/').slice(1).filter((p, i, arr) => !(p === '' && i === arr.length - 1));
176 if (!parts.length || parts.some((p) => !validSegment(p))) throw new ApiError(400, 'invalid_path', 'Invalid path segment.');
177 const c = ctx || rootsForUser(user);
178 const root = c.list.find((r) => r.id === parts[0]);
179 if (!root) throw new ApiError(404, 'not_found', 'No such root.');
180 const rel = parts.slice(1).join('/');
181 const abs = rel ? path.join(root.abs, ...parts.slice(1)) : root.abs;
182
183 // Same checks as the web UI, so the API can never exceed the user's rights.
184 const info = helpers.resolveRootForUser(abs, c.roots, user, c.config);
185 if (!info || !helpers.canReadInfo(user, info)) throw new ApiError(404, 'not_found', 'Not found.');
186 if (write && !helpers.canWriteInfo(user, info)) throw new ApiError(403, 'forbidden', 'You do not have write access here.');
187
188 // Refuse paths that escape the root through symlinks.
189 let probe = abs;
190 while (probe !== root.abs && !fs.existsSync(probe)) probe = path.dirname(probe);
191 try
192 {
193 const realRoot = fs.realpathSync(root.abs);
194 const realProbe = fs.realpathSync(probe);
195 if (realProbe !== realRoot && !realProbe.startsWith(realRoot + path.sep)) throw new ApiError(404, 'not_found', 'Not found.');
196 } catch (err)
197 {
198 if (err instanceof ApiError) throw err;
199 }
200
201 return { root, rel, abs, vpath: '/' + [root.id, ...parts.slice(1)].join('/'), config: c.config, info, ctx: c };
202}
203
204function lstatOrNull (abs)
205{
206 try { return fs.lstatSync(abs); } catch { return null; }
207}
208
209function knownSha256 (abs, stat)
210{
211 const row = getDb().prepare('SELECT size, mtime_ms, sha256 FROM api_hashes WHERE abs_path = ?').get([abs]);
212 if (row && Number(row.size) === stat.size && Number(row.mtime_ms) === Math.floor(stat.mtimeMs)) return row.sha256;
213 return null;
214}
215
216function rememberSha256 (abs, stat, sha)
217{
218 getDb().prepare(`INSERT INTO api_hashes (abs_path, size, mtime_ms, sha256) VALUES (?, ?, ?, ?)
219 ON CONFLICT(abs_path) DO UPDATE SET size = excluded.size, mtime_ms = excluded.mtime_ms, sha256 = excluded.sha256`)
220 .run([abs, stat.size, Math.floor(stat.mtimeMs), sha]);
221}
222
223async function computeSha256 (abs)
224{
225 const h = crypto.createHash('sha256');
226 await pipeline(fs.createReadStream(abs), h);
227 return h.digest('hex');
228}
229
230function entryJson (rootId, rel, stat, abs)
231{
232 const e = syncIndex.entryFromStat(rel, stat);
233 const out = {
234 id: e.file_id,
235 path: '/' + (rel ? `${rootId}/${rel}` : rootId),
236 name: rel ? path.posix.basename(rel) : rootId,
237 type: e.is_dir ? 'folder' : 'file',
238 size: e.size,
239 mtime: new Date(e.mtime_ms).toISOString(),
240 mtime_ms: e.mtime_ms,
241 version: e.version,
242 };
243 if (!e.is_dir) out.sha256 = abs ? knownSha256(abs, stat) : null;
244 return out;
245}
246
247function currentEntry (p)
248{
249 const st = lstatOrNull(p.abs);
250 return st ? entryJson(p.root.id, p.rel, st, p.abs) : null;
251}
252
253/**
254 * Optimistic concurrency for writes to `p`:
255 * - If-None-Match: * -> target must not exist (412)
256 * - If-Match: <ver> -> target must exist with that version (412)
257 * - neither -> 409 when the target exists, unless overwrite=true
258 */
259function checkPreconditions (p, { ifMatch, ifNoneMatch, overwrite })
260{
261 const st = lstatOrNull(p.abs);
262 const current = st ? entryJson(p.root.id, p.rel, st, p.abs) : null;
263 if (ifNoneMatch === '*' && st) throw new ApiError(412, 'precondition_failed', 'Target already exists.', { current });
264 if (ifMatch)
265 {
266 if (!st) throw new ApiError(412, 'precondition_failed', 'Target no longer exists.', { current: null });
267 if (ifMatch !== '*' && ifMatch !== current.version) throw new ApiError(412, 'precondition_failed', 'Target was changed by someone else.', { current });
268 }
269 if (st && st.isDirectory()) throw new ApiError(409, 'conflict', 'A folder exists at this path.', { current });
270 if (st && !ifMatch && !overwrite) throw new ApiError(409, 'conflict', 'Target exists. Send If-Match with its version, or overwrite=true.', { current });
271 return st;
272}
273
274function requireParentFolder (p)
275{
276 const parent = path.dirname(p.abs);
277 const st = lstatOrNull(parent);
278 if (!st || !st.isDirectory()) throw new ApiError(409, 'parent_missing', 'Parent folder does not exist.');
279}
280
281function boolParam (v)
282{
283 return v === true || v === 'true' || v === '1' || v === 1;
284}
285
286function parseMtime (v)
287{
288 if (v == null || v === '') return null;
289 const n = Number(v);
290 if (Number.isFinite(n) && n > 0) return n;
291 const d = Date.parse(String(v));
292 if (Number.isFinite(d)) return d;
293 throw new ApiError(400, 'invalid_request', 'mtime must be epoch milliseconds or an ISO date.');
294}
295
296function recordUploadMeta (abs, username)
297{
298 const db = getDb();
299 const uploadedAt = new Date().toISOString();
300 const existing = db.prepare('SELECT file_path FROM file_meta WHERE file_path = ?').get([abs]);
301 if (existing)
302 {
303 db.prepare('UPDATE file_meta SET uploader = ?, sha256 = NULL, uploaded_at = ? WHERE file_path = ?').run([username, uploadedAt, abs]);
304 } else
305 {
306 db.prepare('INSERT INTO file_meta (file_path, uploader, downloaders, watched_by, uploaded_at, sha256) VALUES (?, ?, ?, ?, ?, ?)')
307 .run([abs, username, '[]', '{}', uploadedAt, null]);
308 }
309 try { enqueueFileHash(abs); } catch { /* best effort */ }
310 Promise.resolve().then(() => reindexDirectoryTree(path.dirname(abs))).catch(() => {});
311}
312
313function tempPathIn (dir)
314{
315 return path.join(dir, `${syncIndex.TEMP_PREFIX}${crypto.randomBytes(8).toString('hex')}.part`);
316}
317
318function limitStream (max, onTooBig)
319{
320 let total = 0;
321 return new Transform({
322 transform (chunk, enc, cb)
323 {
324 total += chunk.length;
325 if (total > max) return cb(onTooBig());
326 cb(null, chunk);
327 },
328 });
329}
330
331/** Move a finished temp file into place atomically and apply mtime. */
332function finalizeFile (tempAbs, p, mtimeMs)
333{
334 if (mtimeMs)
335 {
336 const t = new Date(mtimeMs);
337 fs.utimesSync(tempAbs, t, t);
338 }
339 fs.renameSync(tempAbs, p.abs);
340}
341
342function checkQuota (p, addedBytes)
343{
344 if (!p.info || !p.info.isUserFolder) return;
345 const msg = helpers.checkUserFolderSizeLimit(p.config, p.reqUsername, addedBytes);
346 if (msg) throw new ApiError(507, 'quota_exceeded', msg);
347}
348
349// ---------------------------------------------------------------------------
350// Routes
351// ---------------------------------------------------------------------------
352
353router.use((req, res, next) =>
354{
355 res.set('Access-Control-Allow-Origin', '*');
356 res.set('Access-Control-Allow-Headers', 'Authorization, Content-Type, If-Match, If-None-Match, Range, If-Range, Upload-Offset, X-Mtime');
357 res.set('Access-Control-Allow-Methods', 'GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS');
358 res.set('Access-Control-Expose-Headers', 'ETag, Content-Range, Accept-Ranges, Upload-Offset, Location, Content-Length');
359 if (req.method === 'OPTIONS') return res.status(204).end();
360 next();
361});
362
363router.get('/', (req, res) =>
364{
365 const base = publicBaseUrl(req);
366 res.json({ name: 'filemanager', api: 'v1', openapi: `${base}/api/v1/openapi.json`, oauth: `${base}/.well-known/oauth-authorization-server` });
367});
368
369router.get('/openapi.json', (req, res) =>
370{
371 const spec = JSON.parse(fs.readFileSync(path.join(__dirname, '../../docs/openapi.json'), 'utf8'));
372 const base = publicBaseUrl(req);
373 spec.servers = [{ url: `${base}/api/v1` }];
374 const flow = spec.components.securitySchemes.oauth2.flows.authorizationCode;
375 flow.authorizationUrl = `${base}/oauth/authorize`;
376 flow.tokenUrl = `${base}/oauth/token`;
377 flow.refreshUrl = `${base}/oauth/token`;
378 res.json(spec);
379});
380
381router.use(authenticate);
382
383router.get('/me', (req, res) =>
384{
385 const { config, list } = rootsForUser(req.user);
386 const a = apiConfig(config);
387 res.json({
388 username: req.user.username,
389 scopes: req.apiScopes,
390 grant: { id: req.apiGrant.id, kind: req.apiGrant.kind, name: req.apiGrant.name },
391 roots: list.map((r) => ({ id: r.id, name: r.name, writable: r.writable && req.apiScopes.includes('files:write') })),
392 limits: { maxUploadBytes: a.maxUploadBytes, maxChunkBytes: a.maxChunkBytes, maxListLimit: 1000, maxDeltaLimit: 1000 },
393 trash: false,
394 });
395});
396
397router.get('/roots', requireScope('files:read'), (req, res) =>
398{
399 const { list } = rootsForUser(req.user);
400 res.json({ roots: list.map((r) => ({ id: r.id, name: r.name, path: '/' + r.id, writable: r.writable && req.apiScopes.includes('files:write') })) });
401});
402
403router.get('/files/metadata', requireScope('files:read'), wrap(async (req, res) =>
404{
405 const p = resolvePath(req.user, req.query.path);
406 const st = lstatOrNull(p.abs);
407 if (!st || st.isSymbolicLink()) throw new ApiError(404, 'not_found', 'Not found.');
408 if (boolParam(req.query.hash) && st.isFile() && !knownSha256(p.abs, st))
409 {
410 const a = apiConfig(p.config);
411 if (st.size > a.maxHashBytes) throw new ApiError(413, 'too_large', `Hashing on demand is limited to ${a.maxHashBytes} bytes.`);
412 const sha = await computeSha256(p.abs);
413 const st2 = lstatOrNull(p.abs);
414 if (st2 && st2.size === st.size && st2.mtimeMs === st.mtimeMs) rememberSha256(p.abs, st2, sha);
415 }
416 const e = currentEntry(p);
417 res.set('ETag', `"${e.version}"`);
418 res.json(e);
419}));
420
421router.get('/files/list', requireScope('files:read'), wrap(async (req, res) =>
422{
423 const p = resolvePath(req.user, req.query.path);
424 const st = lstatOrNull(p.abs);
425 if (!st) throw new ApiError(404, 'not_found', 'Not found.');
426 if (!st.isDirectory()) throw new ApiError(400, 'not_a_folder', 'Path is not a folder.');
427 const limit = Math.max(1, Math.min(1000, Number(req.query.limit) || 500));
428 const offset = Math.max(0, Number(req.query.page_token) || 0);
429 const names = (await fs.promises.readdir(p.abs)).filter((n) => !syncIndex.isIgnoredName(n)).sort();
430 const page = names.slice(offset, offset + limit);
431 const entries = [];
432 for (const n of page)
433 {
434 const childAbs = path.join(p.abs, n);
435 const cst = lstatOrNull(childAbs);
436 if (!cst || cst.isSymbolicLink() || (!cst.isFile() && !cst.isDirectory())) continue;
437 entries.push(entryJson(p.root.id, p.rel ? `${p.rel}/${n}` : n, cst, childAbs));
438 }
439 const next = offset + limit < names.length ? String(offset + limit) : null;
440 res.json({ folder: currentEntry(p), entries, next_page_token: next });
441}));
442
443function downloadHandler (req, res)
444{
445 let p;
446 try { p = resolvePath(req.user, req.query.path); } catch (err) { return sendError(res, err); }
447 const st = lstatOrNull(p.abs);
448 if (!st || !st.isFile()) return sendError(res, new ApiError(st ? 400 : 404, st ? 'not_a_file' : 'not_found', st ? 'Path is not a file.' : 'Not found.'));
449 const e = entryJson(p.root.id, p.rel, st, p.abs);
450 res.set('ETag', `"${e.version}"`);
451 res.set('X-File-Id', e.id);
452 if (e.sha256) res.set('Digest', `sha-256=${Buffer.from(e.sha256, 'hex').toString('base64')}`);
453 res.set('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(e.name)}`);
454 const inm = String(req.get('if-none-match') || '').split(',').map(parseEtag);
455 if (inm.includes(e.version) || inm.includes('*')) return res.status(304).end();
456 res.sendFile(p.abs, { dotfiles: 'allow', etag: false, lastModified: true, acceptRanges: true, cacheControl: false }, (err) =>
457 {
458 if (err && !res.headersSent) sendError(res, new ApiError(err.status || 500, 'download_failed', 'Download failed.'));
459 });
460}
461
462router.get('/files/content', requireScope('files:read'), downloadHandler);
463router.head('/files/content', requireScope('files:read'), downloadHandler);
464
465router.put('/files/content', requireScope('files:write'), wrap(async (req, res) =>
466{
467 const p = resolvePath(req.user, req.query.path, { write: true });
468 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Cannot write to a root.');
469 p.reqUsername = req.user.username;
470 const a = apiConfig(p.config);
471 const pre = { ifMatch: parseEtag(req.get('if-match')), ifNoneMatch: parseEtag(req.get('if-none-match')), overwrite: boolParam(req.query.overwrite) };
472 const mtime = parseMtime(req.query.mtime || req.get('x-mtime'));
473 requireParentFolder(p);
474 checkPreconditions(p, pre);
475 const declared = req.get('content-length') != null ? Number(req.get('content-length')) : null;
476 if (declared != null && declared > a.maxUploadBytes) throw new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes; use /uploads for large files.`);
477 if (declared != null) checkQuota(p, declared);
478
479 const temp = tempPathIn(path.dirname(p.abs));
480 const hash = crypto.createHash('sha256');
481 let size = 0;
482 try
483 {
484 await pipeline(
485 req,
486 limitStream(a.maxUploadBytes, () => new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes.`)),
487 new Transform({ transform (chunk, enc, cb) { size += chunk.length; hash.update(chunk); cb(null, chunk); } }),
488 fs.createWriteStream(temp, { flags: 'wx' }),
489 );
490 const sha = hash.digest('hex');
491 const expected = req.get('x-content-sha256');
492 if (expected && expected.toLowerCase() !== sha) throw new ApiError(422, 'checksum_mismatch', 'Uploaded content does not match X-Content-SHA256.');
493 if (declared == null) checkQuota(p, size);
494 checkPreconditions(p, pre); // re-check right before the atomic replace
495 const existed = !!lstatOrNull(p.abs);
496 finalizeFile(temp, p, mtime);
497 const st = fs.lstatSync(p.abs);
498 rememberSha256(p.abs, st, sha);
499 recordUploadMeta(p.abs, req.user.username);
500 syncIndex.markDirty(p.root.abs);
501 const e = entryJson(p.root.id, p.rel, st, p.abs);
502 res.set('ETag', `"${e.version}"`);
503 res.status(existed ? 200 : 201).json(e);
504 } finally
505 {
506 fs.rmSync(temp, { force: true });
507 }
508}));
509
510router.post('/folders', requireScope('files:write'), json, wrap(async (req, res) =>
511{
512 const p = resolvePath(req.user, req.body && req.body.path, { write: true });
513 if (!p.rel) throw new ApiError(409, 'conflict', 'Root already exists.');
514 const st = lstatOrNull(p.abs);
515 if (st)
516 {
517 if (st.isDirectory() && boolParam(req.body.exist_ok)) return res.status(200).json(currentEntry(p));
518 throw new ApiError(409, 'conflict', 'Something already exists at this path.', { current: currentEntry(p) });
519 }
520 if (boolParam(req.body.parents))
521 {
522 fs.mkdirSync(p.abs, { recursive: true });
523 } else
524 {
525 requireParentFolder(p);
526 fs.mkdirSync(p.abs);
527 }
528 syncIndex.markDirty(p.root.abs);
529 res.status(201).json(currentEntry(p));
530}));
531
532router.post('/files/move', requireScope('files:write'), json, wrap(async (req, res) =>
533{
534 const body = req.body || {};
535 const ctx = rootsForUser(req.user);
536 const from = resolvePath(req.user, body.from, { write: true, ctx });
537 const to = resolvePath(req.user, body.to, { write: true, ctx });
538 if (!from.rel || !to.rel) throw new ApiError(400, 'invalid_path', 'Roots cannot be moved or replaced.');
539 const st = lstatOrNull(from.abs);
540 if (!st) throw new ApiError(404, 'not_found', 'Source not found.');
541 const ifMatch = parseEtag(body.if_match || req.get('if-match'));
542 const cur = entryJson(from.root.id, from.rel, st, from.abs);
543 if (ifMatch && ifMatch !== '*' && ifMatch !== cur.version) throw new ApiError(412, 'precondition_failed', 'Source was changed by someone else.', { current: cur });
544 if (from.abs === to.abs) return res.json(cur);
545 if (to.abs.startsWith(from.abs + path.sep)) throw new ApiError(400, 'invalid_path', 'Cannot move a folder into itself.');
546 requireParentFolder(to);
547 const dst = lstatOrNull(to.abs);
548 // Case-only renames on case-insensitive filesystems resolve to the same inode.
549 const sameNode = dst && dst.ino === st.ino && dst.dev === st.dev;
550 if (dst && !sameNode)
551 {
552 if (!boolParam(body.overwrite)) throw new ApiError(409, 'conflict', 'Destination exists.', { current: currentEntry(to) });
553 if (dst.isDirectory() || st.isDirectory()) throw new ApiError(409, 'conflict', 'Folders are never overwritten.', { current: currentEntry(to) });
554 }
555 if (to.info && to.info.isUserFolder && from.root.abs !== to.root.abs)
556 {
557 to.reqUsername = req.user.username;
558 checkQuota(to, st.isDirectory() ? 0 : st.size);
559 }
560 helpers.movePathWithFallback(from.abs, to.abs);
561 helpers.rewriteMetaPaths(from.abs, to.abs);
562 try { rewriteIndexPaths(from.abs, to.abs); } catch { /* best effort */ }
563 getDb().prepare('DELETE FROM api_hashes WHERE abs_path = ?').run([from.abs]);
564 syncIndex.markDirty(from.root.abs);
565 syncIndex.markDirty(to.root.abs);
566 res.json(currentEntry(to));
567}));
568
569router.delete('/files', requireScope('files:write'), wrap(async (req, res) =>
570{
571 const p = resolvePath(req.user, req.query.path, { write: true });
572 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Roots cannot be deleted.');
573 if (p.ctx.roots.map((r) => path.resolve(r)).includes(path.resolve(p.abs))) throw new ApiError(400, 'invalid_path', 'Configured roots cannot be deleted.');
574 const st = lstatOrNull(p.abs);
575 if (!st) throw new ApiError(404, 'not_found', 'Not found.');
576 const ifMatch = parseEtag(req.get('if-match'));
577 const cur = entryJson(p.root.id, p.rel, st, p.abs);
578 if (ifMatch && ifMatch !== '*' && ifMatch !== cur.version) throw new ApiError(412, 'precondition_failed', 'Target was changed by someone else.', { current: cur });
579 if (st.isDirectory())
580 {
581 const children = fs.readdirSync(p.abs);
582 if (children.length && !boolParam(req.query.recursive)) throw new ApiError(409, 'folder_not_empty', 'Folder is not empty; pass recursive=true.');
583 fs.rmSync(p.abs, { recursive: true, force: true });
584 } else
585 {
586 fs.unlinkSync(p.abs);
587 }
588 getDb().prepare('DELETE FROM file_meta WHERE file_path = ? OR file_path LIKE ?').run([p.abs, p.abs + path.sep + '%']);
589 getDb().prepare('DELETE FROM api_hashes WHERE abs_path = ? OR abs_path LIKE ?').run([p.abs, p.abs + path.sep + '%']);
590 try { deleteIndexUnder(p.abs); } catch { /* best effort */ }
591 syncIndex.markDirty(p.root.abs);
592 res.status(204).end();
593}));
594
595// ---------------------------------------------------------------------------
596// Delta / change feed
597// ---------------------------------------------------------------------------
598
599function encodeCursor (obj)
600{
601 return Buffer.from(JSON.stringify(obj)).toString('base64url');
602}
603
604function decodeCursor (raw)
605{
606 try
607 {
608 const c = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
609 if (c && typeof c === 'object') return c;
610 } catch { /* fallthrough */ }
611 throw new ApiError(400, 'invalid_cursor', 'Malformed cursor.');
612}
613
614function rootTag (root)
615{
616 return crypto.createHash('sha256').update(root.abs).digest('base64url').slice(0, 12);
617}
618
619router.get('/delta', requireScope('files:read'), wrap(async (req, res) =>
620{
621 const ctx = rootsForUser(req.user);
622 let rootId = req.query.root;
623 let cursor = null;
624 if (req.query.cursor)
625 {
626 cursor = decodeCursor(req.query.cursor);
627 rootId = rootId || cursor.r;
628 }
629 const root = ctx.list.find((r) => r.id === rootId);
630 if (!root) throw new ApiError(404, 'not_found', 'Unknown root; pass root=<id> from /roots.');
631 if (cursor && (cursor.r !== root.id || cursor.k !== rootTag(root))) throw new ApiError(400, 'invalid_cursor', 'Cursor belongs to another root.');
632 const a = apiConfig(ctx.config);
633 const limit = Math.max(1, Math.min(1000, Number(req.query.limit) || 500));
634
635 let state;
636 try
637 {
638 state = await syncIndex.ensureFresh(root.abs, root.abs, { intervalMs: a.scanIntervalSeconds * 1000, maxEntries: a.maxSyncEntries });
639 } catch (err)
640 {
641 if (err && err.code === 'too_many_entries') throw new ApiError(507, 'too_many_entries', err.message);
642 throw err;
643 }
644
645 const toPath = (rel) => '/' + (rel ? `${root.id}/${rel}` : root.id);
646 const base = { r: root.id, k: rootTag(root), g: state.generation };
647
648 if (cursor && cursor.g !== state.generation) throw new ApiError(410, 'cursor_expired', 'Cursor is no longer valid; start again without a cursor.');
649
650 if (!cursor || cursor.m === 's')
651 {
652 const seq = cursor ? Number(cursor.s) : syncIndex.currentSeq();
653 const offset = cursor ? Number(cursor.o) || 0 : 0;
654 if (cursor && seq < state.min_seq) throw new ApiError(410, 'cursor_expired', 'Cursor is no longer valid; start again without a cursor.');
655 const rows = syncIndex.listEntries(root.abs, offset, limit);
656 const more = rows.length === limit;
657 return res.json({
658 reset: !cursor,
659 entries: rows.map((r) => ({
660 change: 'exists', id: r.file_id, path: toPath(r.rel_path), type: r.is_dir ? 'folder' : 'file',
661 size: r.size, mtime_ms: r.mtime_ms, version: r.version,
662 })),
663 cursor: encodeCursor(more ? { ...base, m: 's', s: seq, o: offset + rows.length } : { ...base, m: 'c', s: seq }),
664 has_more: more,
665 });
666 }
667
668 const after = Number(cursor.s) || 0;
669 if (after < state.min_seq) throw new ApiError(410, 'cursor_expired', 'Changes since this cursor were pruned; start again without a cursor.');
670 const rows = syncIndex.listChanges(root.abs, after, limit);
671 const last = rows.length ? rows[rows.length - 1].seq : after;
672 res.json({
673 reset: false,
674 entries: rows.map((r) => ({
675 change: r.change, id: r.file_id, path: toPath(r.rel_path),
676 old_path: r.old_rel_path != null ? toPath(r.old_rel_path) : undefined,
677 type: r.is_dir ? 'folder' : 'file',
678 size: r.size, mtime_ms: r.mtime_ms, version: r.version,
679 })),
680 cursor: encodeCursor({ ...base, m: 'c', s: last }),
681 has_more: rows.length === limit,
682 });
683}));
684
685// ---------------------------------------------------------------------------
686// Resumable uploads
687// ---------------------------------------------------------------------------
688
689function purgeExpiredUploads (uploadDir)
690{
691 const d = getDb();
692 const expired = d.prepare('SELECT id FROM api_uploads WHERE expires_at < ?').all([Date.now()]);
693 for (const r of expired)
694 {
695 fs.rmSync(path.join(uploadDir, `${r.id}.part`), { force: true });
696 d.prepare('DELETE FROM api_uploads WHERE id = ?').run([r.id]);
697 }
698}
699
700function getUploadFor (req, uploadDir)
701{
702 const id = String(req.params.id || '');
703 if (!/^[A-Za-z0-9_-]{10,64}$/.test(id)) throw new ApiError(404, 'not_found', 'Upload not found.');
704 const row = getDb().prepare('SELECT * FROM api_uploads WHERE id = ?').get([id]);
705 if (!row || row.username !== req.user.username || row.grant_id !== req.apiGrant.id || row.expires_at < Date.now())
706 {
707 throw new ApiError(404, 'not_found', 'Upload not found or expired.');
708 }
709 row.file = path.join(uploadDir, `${row.id}.part`);
710 return row;
711}
712
713function uploadJson (row)
714{
715 return { id: row.id, path: row.target, size: row.size, offset: row.received, expires_at: new Date(row.expires_at).toISOString() };
716}
717
718router.post('/uploads', requireScope('files:write'), json, wrap(async (req, res) =>
719{
720 const body = req.body || {};
721 const p = resolvePath(req.user, body.path, { write: true });
722 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Cannot write to a root.');
723 p.reqUsername = req.user.username;
724 const a = apiConfig(p.config);
725 const size = Number(body.size);
726 if (!Number.isInteger(size) || size < 0) throw new ApiError(400, 'invalid_request', 'size (bytes) is required.');
727 if (size > a.maxUploadBytes) throw new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes.`);
728 const sha = body.sha256 ? String(body.sha256).toLowerCase() : null;
729 if (sha && !/^[0-9a-f]{64}$/.test(sha)) throw new ApiError(400, 'invalid_request', 'sha256 must be 64 hex characters.');
730 const pre = { ifMatch: parseEtag(body.if_match), ifNoneMatch: body.if_none_match === '*' ? '*' : null, overwrite: boolParam(body.overwrite) };
731 requireParentFolder(p);
732 checkPreconditions(p, pre);
733 checkQuota(p, size);
734
735 fs.mkdirSync(a.uploadDir, { recursive: true, mode: 0o700 });
736 purgeExpiredUploads(a.uploadDir);
737 const open = getDb().prepare('SELECT COUNT(*) AS n FROM api_uploads WHERE username = ?').get([req.user.username]).n;
738 if (open >= a.maxOpenUploadsPerUser) throw new ApiError(429, 'too_many_uploads', 'Too many unfinished uploads; finish or cancel some first.');
739
740 const id = crypto.randomBytes(18).toString('base64url');
741 const t = Date.now();
742 fs.writeFileSync(path.join(a.uploadDir, `${id}.part`), Buffer.alloc(0), { mode: 0o600 });
743 getDb().prepare(`INSERT INTO api_uploads (id, grant_id, username, target, size, received, sha256, mtime_ms, if_match, if_none_match, overwrite, created_at, expires_at)
744 VALUES (?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?)`)
745 .run([id, req.apiGrant.id, req.user.username, p.vpath, size, sha, parseMtime(body.mtime), pre.ifMatch, pre.ifNoneMatch ? 1 : 0, pre.overwrite ? 1 : 0, t, t + a.uploadTtlHours * 3600000]);
746 const row = getDb().prepare('SELECT * FROM api_uploads WHERE id = ?').get([id]);
747 res.set('Location', `/api/v1/uploads/${id}`);
748 res.set('Upload-Offset', '0');
749 res.status(201).json({ ...uploadJson(row), max_chunk_bytes: a.maxChunkBytes });
750}));
751
752router.get('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
753{
754 const { config } = helpers.loadConfigAndRoots();
755 const row = getUploadFor(req, apiConfig(config).uploadDir);
756 res.set('Upload-Offset', String(row.received));
757 res.json(uploadJson(row));
758}));
759
760router.patch('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
761{
762 const { config } = helpers.loadConfigAndRoots();
763 const a = apiConfig(config);
764 const row = getUploadFor(req, a.uploadDir);
765 const offset = Number(req.get('upload-offset'));
766 if (!Number.isInteger(offset)) throw new ApiError(400, 'invalid_request', 'Upload-Offset header is required.');
767 if (offset !== row.received)
768 {
769 res.set('Upload-Offset', String(row.received));
770 throw new ApiError(409, 'offset_mismatch', `Expected offset ${row.received}.`, { offset: row.received });
771 }
772 const remaining = row.size - row.received;
773 const max = Math.min(a.maxChunkBytes, remaining);
774 let written = 0;
775 try
776 {
777 await pipeline(
778 req,
779 limitStream(max, () => new ApiError(413, 'too_large', `Chunk too large (max ${max} bytes here).`)),
780 new Transform({ transform (chunk, enc, cb) { written += chunk.length; cb(null, chunk); } }),
781 fs.createWriteStream(row.file, { flags: 'r+', start: row.received }),
782 );
783 } catch (err)
784 {
785 // Keep only fully confirmed bytes; a client resumes from the stored offset.
786 fs.truncateSync(row.file, row.received);
787 throw err instanceof ApiError ? err : new ApiError(400, 'upload_interrupted', 'Chunk upload was interrupted.');
788 }
789 const received = row.received + written;
790 getDb().prepare('UPDATE api_uploads SET received = ? WHERE id = ?').run([received, row.id]);
791 res.set('Upload-Offset', String(received));
792 res.json({ ...uploadJson({ ...row, received }) });
793}));
794
795router.post('/uploads/:id/complete', requireScope('files:write'), wrap(async (req, res) =>
796{
797 const { config } = helpers.loadConfigAndRoots();
798 const a = apiConfig(config);
799 const row = getUploadFor(req, a.uploadDir);
800 if (row.received !== row.size) throw new ApiError(409, 'incomplete', `Only ${row.received} of ${row.size} bytes received.`, { offset: row.received });
801 const p = resolvePath(req.user, row.target, { write: true });
802 p.reqUsername = req.user.username;
803 const sha = await computeSha256(row.file);
804 if (row.sha256 && row.sha256 !== sha)
805 {
806 fs.rmSync(row.file, { force: true });
807 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
808 throw new ApiError(422, 'checksum_mismatch', 'Uploaded content does not match sha256; upload discarded.');
809 }
810 requireParentFolder(p);
811 const pre = { ifMatch: row.if_match, ifNoneMatch: row.if_none_match ? '*' : null, overwrite: !!row.overwrite };
812 checkPreconditions(p, pre);
813 checkQuota(p, row.size);
814
815 const temp = tempPathIn(path.dirname(p.abs));
816 try
817 {
818 try { fs.renameSync(row.file, temp); } catch { fs.copyFileSync(row.file, temp); fs.rmSync(row.file, { force: true }); }
819 checkPreconditions(p, pre);
820 const existed = !!lstatOrNull(p.abs);
821 finalizeFile(temp, p, row.mtime_ms);
822 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
823 const st = fs.lstatSync(p.abs);
824 rememberSha256(p.abs, st, sha);
825 recordUploadMeta(p.abs, req.user.username);
826 syncIndex.markDirty(p.root.abs);
827 const e = entryJson(p.root.id, p.rel, st, p.abs);
828 res.set('ETag', `"${e.version}"`);
829 res.status(existed ? 200 : 201).json(e);
830 } catch (err)
831 {
832 // Lost a race after staging (target changed meanwhile): discard; the client starts a new upload.
833 fs.rmSync(temp, { force: true });
834 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
835 throw err;
836 }
837}));
838
839router.delete('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
840{
841 const { config } = helpers.loadConfigAndRoots();
842 const row = getUploadFor(req, apiConfig(config).uploadDir);
843 fs.rmSync(row.file, { force: true });
844 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
845 res.status(204).end();
846}));
847
848router.use((req, res) => res.status(404).json({ error: 'not_found', message: 'Unknown API endpoint.' }));
849
850router.ApiError = ApiError;
851module.exports = router;