@softure-ai/files 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +113 -10
  3. package/dist/contract.d.ts +41 -1
  4. package/dist/contract.d.ts.map +1 -1
  5. package/dist/index.d.ts +35 -1
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +17 -4
  8. package/dist/index.js.map +1 -1
  9. package/dist/mcp/index.d.ts +41 -0
  10. package/dist/mcp/index.d.ts.map +1 -0
  11. package/dist/mcp/index.js +114 -0
  12. package/dist/mcp/index.js.map +1 -0
  13. package/dist/messages/en.d.ts +15 -0
  14. package/dist/messages/en.d.ts.map +1 -1
  15. package/dist/messages/en.js +14 -0
  16. package/dist/messages/en.js.map +1 -1
  17. package/dist/messages/index.d.ts +15 -0
  18. package/dist/messages/index.d.ts.map +1 -1
  19. package/dist/next/index.d.ts +1 -0
  20. package/dist/next/index.d.ts.map +1 -1
  21. package/dist/next/index.js +2 -1
  22. package/dist/next/index.js.map +1 -1
  23. package/dist/next/upload-route.d.ts +3 -0
  24. package/dist/next/upload-route.d.ts.map +1 -0
  25. package/dist/next/upload-route.js +11 -0
  26. package/dist/next/upload-route.js.map +1 -0
  27. package/dist/options.d.ts +6 -0
  28. package/dist/options.d.ts.map +1 -1
  29. package/dist/options.js +27 -0
  30. package/dist/options.js.map +1 -1
  31. package/dist/schema.d.ts +255 -0
  32. package/dist/schema.d.ts.map +1 -1
  33. package/dist/schema.js +17 -2
  34. package/dist/schema.js.map +1 -1
  35. package/dist/server/index.d.ts +6 -2
  36. package/dist/server/index.d.ts.map +1 -1
  37. package/dist/server/index.js +6 -2
  38. package/dist/server/index.js.map +1 -1
  39. package/dist/server/options.d.ts +2 -0
  40. package/dist/server/options.d.ts.map +1 -1
  41. package/dist/server/options.js +8 -0
  42. package/dist/server/options.js.map +1 -1
  43. package/dist/server/privacy.d.ts +6 -1
  44. package/dist/server/privacy.d.ts.map +1 -1
  45. package/dist/server/privacy.js +6 -3
  46. package/dist/server/privacy.js.map +1 -1
  47. package/dist/server/prune.d.ts +4 -0
  48. package/dist/server/prune.d.ts.map +1 -1
  49. package/dist/server/prune.js +4 -2
  50. package/dist/server/prune.js.map +1 -1
  51. package/dist/server/save.d.ts +15 -0
  52. package/dist/server/save.d.ts.map +1 -1
  53. package/dist/server/save.js +11 -9
  54. package/dist/server/save.js.map +1 -1
  55. package/dist/server/serve-upload.d.ts +6 -0
  56. package/dist/server/serve-upload.d.ts.map +1 -0
  57. package/dist/server/serve-upload.js +110 -0
  58. package/dist/server/serve-upload.js.map +1 -0
  59. package/dist/server/upload-page.d.ts +5 -0
  60. package/dist/server/upload-page.d.ts.map +1 -0
  61. package/dist/server/upload-page.js +94 -0
  62. package/dist/server/upload-page.js.map +1 -0
  63. package/dist/server/upload-tokens.d.ts +9 -0
  64. package/dist/server/upload-tokens.d.ts.map +1 -0
  65. package/dist/server/upload-tokens.js +43 -0
  66. package/dist/server/upload-tokens.js.map +1 -0
  67. package/dist/server/uploads.d.ts +73 -0
  68. package/dist/server/uploads.d.ts.map +1 -0
  69. package/dist/server/uploads.js +403 -0
  70. package/dist/server/uploads.js.map +1 -0
  71. package/migrations/0002_create_uploads.sql +33 -0
  72. package/module.json +9 -4
  73. package/package.json +12 -2
  74. package/src/contract.ts +45 -1
  75. package/src/index.ts +32 -5
  76. package/src/mcp/index.ts +169 -0
  77. package/src/messages/en.ts +14 -0
  78. package/src/next/index.ts +2 -1
  79. package/src/next/upload-route.ts +11 -0
  80. package/src/options.ts +28 -0
  81. package/src/schema.ts +20 -2
  82. package/src/server/index.ts +20 -2
  83. package/src/server/options.ts +8 -0
  84. package/src/server/privacy.ts +12 -4
  85. package/src/server/prune.ts +8 -2
  86. package/src/server/save.ts +25 -11
  87. package/src/server/serve-upload.ts +116 -0
  88. package/src/server/upload-page.ts +103 -0
  89. package/src/server/upload-tokens.ts +43 -0
  90. package/src/server/uploads.ts +437 -0
@@ -0,0 +1,403 @@
1
+ // Upload sessions: a client that cannot hand the server a stream (an assistant in its own sandbox, a phone over a
2
+ // proxy with a body limit) sends a file in chunks to a signed URL, and `finalizeUpload` turns them into a stored file.
3
+ //
4
+ // Every chunk but the last is `chunk_size` bytes and starts at a multiple of it, so "which bytes arrived" is the set
5
+ // of chunk indices in `received_chunks`. Each chunk is its own object in storage (`uploads/<id>/<index>`), written
6
+ // atomically by the driver and recorded only once whole; a recorded chunk is never rewritten, so a finalize reads
7
+ // parts that cannot change under it. The finalize streams the parts in order into `saveFile`, which hashes, counts,
8
+ // applies the quota and dedupe and writes the one final object (multipart on S3), then the parts are removed.
9
+ import { createHash, randomUUID } from "node:crypto";
10
+ import { err, errorLogLabel, ok } from "@softure-ai/core";
11
+ import { and, asc, eq, gt, isNull, lte, sql } from "drizzle-orm";
12
+ import { uploads } from "../schema.js";
13
+ import { deleteFile, findFile, UUID_PATTERN } from "./files.js";
14
+ import { readLinkKeyring } from "./keys.js";
15
+ import { getFilesOptions } from "./options.js";
16
+ import { sumOwnerBytes } from "./queries.js";
17
+ import { saveFile, validateFileDescription } from "./save.js";
18
+ import { signUploadPath } from "./upload-tokens.js";
19
+ const SHA256_PATTERN = /^[0-9a-f]{64}$/;
20
+ const PART_PREFIX = "uploads";
21
+ /** Opens an upload session for `ownerId` and answers the URL the client sends the chunks to. */
22
+ export async function createUpload(ctx, input) {
23
+ const options = getFilesOptions(ctx.config);
24
+ const described = validateFileDescription(input);
25
+ if (!described.ok)
26
+ return described;
27
+ const sha256 = input.sha256?.toLowerCase();
28
+ const ttlSeconds = input.ttlSeconds ?? options.uploads.ttlSeconds;
29
+ const isValid = Number.isSafeInteger(input.size) &&
30
+ input.size >= 1 &&
31
+ (sha256 === undefined || SHA256_PATTERN.test(sha256)) &&
32
+ Number.isSafeInteger(ttlSeconds) &&
33
+ ttlSeconds >= 1 &&
34
+ ttlSeconds <= options.uploads.ttlSeconds;
35
+ if (!isValid)
36
+ return err("files.invalid_input");
37
+ if (input.size > options.maxFileBytes)
38
+ return err("files.too_large");
39
+ if (!isContentTypeAllowed(described.value.contentType, options.uploads.contentTypes))
40
+ return err("files.content_type_not_allowed");
41
+ const keyring = readLinkKeyring(ctx.env ?? process.env);
42
+ if (!keyring.ok)
43
+ return keyring;
44
+ const now = ctx.clock.now();
45
+ const id = randomUUID();
46
+ // Whole seconds, so the URL's expiry and the row's agree.
47
+ const expiresAt = new Date((Math.floor(now.getTime() / 1000) + ttlSeconds) * 1000);
48
+ const chunkSize = options.uploads.chunkBytes;
49
+ const opened = await ctx.db.transaction(async (tx) => {
50
+ // The same lock as saveFile: the quota and the open sessions are read with nothing of this owner changing.
51
+ await tx.execute(sql `select pg_advisory_xact_lock(hashtextextended(${`files:${input.ownerId}`}, 0))`);
52
+ const [open] = await tx
53
+ .select({ count: sql `count(*)::int` })
54
+ .from(uploads)
55
+ .where(and(eq(uploads.ownerId, input.ownerId), isNull(uploads.fileId), gt(uploads.expiresAt, now)));
56
+ if ((open?.count ?? 0) >= options.uploads.maxOpenPerOwner)
57
+ return err("files.too_many_uploads");
58
+ if (options.quotaBytesPerOwner !== null && (await sumOwnerBytes(tx, input.ownerId, now)) + input.size > options.quotaBytesPerOwner) {
59
+ return err("files.quota_exceeded");
60
+ }
61
+ await tx.insert(uploads).values({
62
+ id,
63
+ ownerId: input.ownerId,
64
+ ...described.value,
65
+ size: input.size,
66
+ sha256: sha256 ?? null,
67
+ chunkSize,
68
+ receivedChunks: [],
69
+ expiresAt,
70
+ createdAt: now,
71
+ });
72
+ return ok();
73
+ });
74
+ if (!opened.ok)
75
+ return opened;
76
+ const path = signUploadPath(ctx, keyring.value, id, expiresAt);
77
+ return ok({
78
+ uploadId: id,
79
+ uploadUrl: new URL(path, ctx.config.appOrigin).toString(),
80
+ chunkSize,
81
+ chunkCount: countChunks(input.size, chunkSize),
82
+ expiresAt,
83
+ });
84
+ }
85
+ /** A session that has not expired, or null. A finalized one is answered too (state `finalized`). */
86
+ export async function getUpload(ctx, uploadId, options = {}) {
87
+ const row = await findUploadRow(ctx, uploadId, options);
88
+ return row === undefined ? null : toUploadStatus(row, ctx.clock.now());
89
+ }
90
+ /** Thrown into the driver's write when a body passes its range; the driver drops the partial object. */
91
+ class ChunkOverflowError extends Error {
92
+ constructor() {
93
+ super("@softure-ai/files: the chunk body passed its range");
94
+ }
95
+ }
96
+ /**
97
+ * Stores one chunk of an open session. A chunk that already arrived is answered as is, without reading the body:
98
+ * a client that resends it after a lost answer loses nothing. A storage failure propagates.
99
+ */
100
+ export async function writeUploadChunk(ctx, uploadId, input) {
101
+ const row = await findUploadRow(ctx, uploadId);
102
+ if (row?.fileId !== null || row.expiresAt.getTime() <= ctx.clock.now().getTime())
103
+ return err("files.not_found");
104
+ const index = findChunkIndex(row, input);
105
+ if (index === null)
106
+ return err("files.invalid_range");
107
+ if (row.receivedChunks.includes(index))
108
+ return ok(toUploadStatus(row, ctx.clock.now()));
109
+ const expected = getChunkLength(row, index);
110
+ const storage = getFilesOptions(ctx.config).storage;
111
+ const key = getPartKey(row.id, index);
112
+ let length = 0;
113
+ async function* capped() {
114
+ for await (const chunk of input.body) {
115
+ const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
116
+ length += bytes.byteLength;
117
+ if (length > expected)
118
+ throw new ChunkOverflowError();
119
+ yield bytes;
120
+ }
121
+ }
122
+ try {
123
+ await storage.put(capped(), key);
124
+ }
125
+ catch (error) {
126
+ if (error instanceof ChunkOverflowError)
127
+ return err("files.chunk_length_mismatch");
128
+ throw error;
129
+ }
130
+ if (length !== expected) {
131
+ await deletePartQuietly(storage, key);
132
+ return err("files.chunk_length_mismatch");
133
+ }
134
+ // One statement, so parallel chunks of one session never lose each other's index.
135
+ const [updated] = await ctx.db
136
+ .update(uploads)
137
+ .set({
138
+ receivedChunks: sql `case when ${index}::int = any(${uploads.receivedChunks}) then ${uploads.receivedChunks} else array_append(${uploads.receivedChunks}, ${index}::int) end`,
139
+ })
140
+ .where(and(eq(uploads.id, row.id), isNull(uploads.fileId)))
141
+ .returning();
142
+ // Finalized in the meantime: the part is not needed, and the session no longer takes chunks.
143
+ if (updated === undefined) {
144
+ await deletePartQuietly(storage, key);
145
+ return err("files.not_found");
146
+ }
147
+ return ok(toUploadStatus(updated, ctx.clock.now()));
148
+ }
149
+ /** Thrown into the save when a part is missing from storage. */
150
+ class MissingPartError extends Error {
151
+ index;
152
+ constructor(index) {
153
+ super(`@softure-ai/files: upload part ${String(index)} is missing from storage`);
154
+ this.index = index;
155
+ }
156
+ }
157
+ /** Thrown into the save when the bytes do not match the declared size or SHA-256; the save drops its object. */
158
+ class ContentMismatchError extends Error {
159
+ constructor() {
160
+ super("@softure-ai/files: the uploaded bytes do not match the declared size or SHA-256");
161
+ }
162
+ }
163
+ /**
164
+ * Turns a complete session into a stored file: every chunk present, the size and the declared SHA-256 checked while
165
+ * the parts stream into `saveFile` (quota and dedupe as there), then the parts are removed. Calling it again answers
166
+ * the same file; two parallel calls keep one.
167
+ */
168
+ export async function finalizeUpload(ctx, uploadId, options = {}) {
169
+ const row = await findUploadRow(ctx, uploadId, options);
170
+ if (row === undefined)
171
+ return err("files.not_found");
172
+ if (row.fileId !== null)
173
+ return answerFinalizedFile(ctx, row.fileId);
174
+ const chunkCount = countChunks(row.size, row.chunkSize);
175
+ if (row.receivedChunks.length < chunkCount)
176
+ return err("files.upload_incomplete");
177
+ const storage = getFilesOptions(ctx.config).storage;
178
+ let saved;
179
+ try {
180
+ saved = await saveFile(ctx, {
181
+ ownerId: row.ownerId,
182
+ name: row.originalName,
183
+ contentType: row.contentType,
184
+ kind: row.kind,
185
+ body: readParts(storage, row, chunkCount),
186
+ });
187
+ }
188
+ catch (error) {
189
+ if (error instanceof ContentMismatchError)
190
+ return err("files.checksum_mismatch");
191
+ if (!(error instanceof MissingPartError))
192
+ throw error;
193
+ console.error(`@softure-ai/files: upload ${row.id} lost part ${String(error.index)} in storage; the client must send it again`);
194
+ await ctx.db
195
+ .update(uploads)
196
+ .set({ receivedChunks: sql `array_remove(${uploads.receivedChunks}, ${error.index}::int)` })
197
+ .where(eq(uploads.id, row.id));
198
+ return err("files.upload_incomplete");
199
+ }
200
+ if (!saved.ok)
201
+ return saved;
202
+ const [claimed] = await ctx.db
203
+ .update(uploads)
204
+ .set({ fileId: saved.value.id, finalizedAt: ctx.clock.now() })
205
+ .where(and(eq(uploads.id, row.id), isNull(uploads.fileId)))
206
+ .returning();
207
+ if (claimed === undefined) {
208
+ // Another finalize won: keep its file, drop this copy (unless dedupe answered that very file).
209
+ const winner = await findUploadRow(ctx, row.id);
210
+ const winnerFileId = winner?.fileId ?? null;
211
+ if (winnerFileId !== saved.value.id)
212
+ await deleteFile(ctx, saved.value.id);
213
+ return winnerFileId === null ? err("files.not_found") : answerFinalizedFile(ctx, winnerFileId);
214
+ }
215
+ await deleteParts(storage, row);
216
+ return saved;
217
+ }
218
+ /** Removes sessions whose time is up, with their parts; answers how many went and how many must wait for the next run. */
219
+ export async function pruneUploads(ctx, batchSize) {
220
+ const storage = getFilesOptions(ctx.config).storage;
221
+ const now = ctx.clock.now();
222
+ let deletedUploads = 0;
223
+ let failedUploads = 0;
224
+ for (;;) {
225
+ const rows = await ctx.db
226
+ .select()
227
+ .from(uploads)
228
+ .where(lte(uploads.expiresAt, now))
229
+ .orderBy(asc(uploads.expiresAt), asc(uploads.id))
230
+ .limit(batchSize)
231
+ .offset(failedUploads);
232
+ for (const row of rows) {
233
+ if (await removeUpload(ctx, storage, row))
234
+ deletedUploads += 1;
235
+ else
236
+ failedUploads += 1;
237
+ }
238
+ if (rows.length < batchSize)
239
+ return { deletedUploads, failedUploads };
240
+ }
241
+ }
242
+ /** An owner's sessions with their parts (the privacy deletion); answers how many went and how many stay for prune. */
243
+ export async function deleteOwnerUploads(ctx, ownerId) {
244
+ const storage = getFilesOptions(ctx.config).storage;
245
+ const rows = await ctx.db.select().from(uploads).where(eq(uploads.ownerId, ownerId));
246
+ let deletedUploads = 0;
247
+ for (const row of rows) {
248
+ if (await removeUpload(ctx, storage, row))
249
+ deletedUploads += 1;
250
+ }
251
+ return { deletedUploads, failedUploads: rows.length - deletedUploads };
252
+ }
253
+ /** An owner's sessions that still take chunks (the privacy export). */
254
+ export async function listOpenUploads(ctx, ownerId) {
255
+ const now = ctx.clock.now();
256
+ const rows = await ctx.db
257
+ .select()
258
+ .from(uploads)
259
+ .where(and(eq(uploads.ownerId, ownerId), isNull(uploads.fileId), gt(uploads.expiresAt, now)))
260
+ .orderBy(asc(uploads.createdAt), asc(uploads.id));
261
+ return rows.map((row) => toUploadStatus(row, now));
262
+ }
263
+ /** The storage key of one chunk of a session. */
264
+ export function getPartKey(uploadId, index) {
265
+ return `${PART_PREFIX}/${uploadId}/${String(index)}`;
266
+ }
267
+ /** How many chunks a file of `size` bytes takes. */
268
+ export function countChunks(size, chunkSize) {
269
+ return Math.ceil(size / chunkSize);
270
+ }
271
+ /** The session row, unless it expired. Not a uuid reads as missing. */
272
+ async function findUploadRow(ctx, uploadId, options = {}) {
273
+ if (!UUID_PATTERN.test(uploadId))
274
+ return undefined;
275
+ const conditions = [eq(uploads.id, uploadId), gt(uploads.expiresAt, ctx.clock.now())];
276
+ if (options.ownerId !== undefined)
277
+ conditions.push(eq(uploads.ownerId, options.ownerId));
278
+ const [row] = await ctx.db
279
+ .select()
280
+ .from(uploads)
281
+ .where(and(...conditions));
282
+ return row;
283
+ }
284
+ async function answerFinalizedFile(ctx, fileId) {
285
+ const file = await findFile(ctx, fileId);
286
+ return file === null ? err("files.not_found") : ok(file);
287
+ }
288
+ /** The chunk index a request's range names, or null when it is not exactly one chunk of the session. */
289
+ function findChunkIndex(row, input) {
290
+ if (input.total !== undefined && input.total !== row.size)
291
+ return null;
292
+ if (input.range === null)
293
+ return row.size <= row.chunkSize ? 0 : null;
294
+ const { start, end } = input.range;
295
+ if (!Number.isSafeInteger(start) || start < 0 || start % row.chunkSize !== 0 || start >= row.size)
296
+ return null;
297
+ const index = start / row.chunkSize;
298
+ return end === start + getChunkLength(row, index) - 1 ? index : null;
299
+ }
300
+ function getChunkLength(row, index) {
301
+ return Math.min(row.chunkSize, row.size - index * row.chunkSize);
302
+ }
303
+ /** The parts in order, checked against the declared size and SHA-256 as they pass. */
304
+ async function* readParts(storage, row, chunkCount) {
305
+ const hash = createHash("sha256");
306
+ let size = 0;
307
+ for (let index = 0; index < chunkCount; index += 1) {
308
+ const stream = await storage.get(getPartKey(row.id, index));
309
+ if (stream === null)
310
+ throw new MissingPartError(index);
311
+ const reader = stream.getReader();
312
+ for (;;) {
313
+ const { done, value } = await reader.read();
314
+ if (done)
315
+ break;
316
+ size += value.byteLength;
317
+ hash.update(value);
318
+ yield value;
319
+ }
320
+ }
321
+ if (size !== row.size || (row.sha256 !== null && hash.digest("hex") !== row.sha256))
322
+ throw new ContentMismatchError();
323
+ }
324
+ function toUploadStatus(row, now) {
325
+ const chunkCount = countChunks(row.size, row.chunkSize);
326
+ const received = new Set(row.receivedChunks);
327
+ const missingChunks = Array.from({ length: chunkCount }, (_, index) => index).filter((index) => !received.has(index));
328
+ return {
329
+ uploadId: row.id,
330
+ name: row.originalName,
331
+ contentType: row.contentType,
332
+ size: row.size,
333
+ chunkSize: row.chunkSize,
334
+ chunkCount,
335
+ received: mergeChunkRanges(row, [...received].sort((left, right) => left - right)),
336
+ receivedBytes: [...received].reduce((total, index) => total + getChunkLength(row, index), 0),
337
+ missingChunks,
338
+ state: getUploadState(row, missingChunks.length, now),
339
+ fileId: row.fileId,
340
+ expiresAt: row.expiresAt,
341
+ };
342
+ }
343
+ function getUploadState(row, missingCount, now) {
344
+ if (row.fileId !== null)
345
+ return "finalized";
346
+ if (row.expiresAt.getTime() <= now.getTime())
347
+ return "expired";
348
+ return missingCount === 0 ? "complete" : "open";
349
+ }
350
+ /** Sorted chunk indices as merged byte ranges. */
351
+ function mergeChunkRanges(row, indices) {
352
+ const ranges = [];
353
+ for (const index of indices) {
354
+ const start = index * row.chunkSize;
355
+ const end = start + getChunkLength(row, index) - 1;
356
+ const last = ranges.at(-1);
357
+ if (last !== undefined && last.end + 1 === start)
358
+ ranges[ranges.length - 1] = { start: last.start, end };
359
+ else
360
+ ranges.push({ start, end });
361
+ }
362
+ return ranges;
363
+ }
364
+ /** Whether a normalised media type matches one of the allowed rules (`video/mp4`, `video/*`); null allows any. */
365
+ function isContentTypeAllowed(contentType, rules) {
366
+ if (rules === null)
367
+ return true;
368
+ const essence = contentType.split(";")[0] ?? "";
369
+ const [type = ""] = essence.split("/");
370
+ return rules.some((rule) => rule === essence || rule === `${type}/*`);
371
+ }
372
+ /** Removes a session's parts and then its row; answers whether both went. */
373
+ async function removeUpload(ctx, storage, row) {
374
+ try {
375
+ for (let index = 0; index < countChunks(row.size, row.chunkSize); index += 1)
376
+ await storage.delete(getPartKey(row.id, index));
377
+ }
378
+ catch (error) {
379
+ console.error(`@softure-ai/files: deleting the parts of upload ${row.id} failed, pruneFiles retries: ${errorLogLabel(error)}`);
380
+ return false;
381
+ }
382
+ await ctx.db.delete(uploads).where(eq(uploads.id, row.id));
383
+ return true;
384
+ }
385
+ /** Removes the parts of a finalized session; a failure is logged and the prune of the expired session retries. */
386
+ async function deleteParts(storage, row) {
387
+ try {
388
+ for (let index = 0; index < countChunks(row.size, row.chunkSize); index += 1)
389
+ await storage.delete(getPartKey(row.id, index));
390
+ }
391
+ catch (error) {
392
+ console.error(`@softure-ai/files: deleting the parts of finalized upload ${row.id} failed, pruneFiles retries: ${errorLogLabel(error)}`);
393
+ }
394
+ }
395
+ async function deletePartQuietly(storage, key) {
396
+ try {
397
+ await storage.delete(key);
398
+ }
399
+ catch (error) {
400
+ console.error(`@softure-ai/files: deleting a refused upload part failed: ${errorLogLabel(error)}`);
401
+ }
402
+ }
403
+ //# sourceMappingURL=uploads.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"uploads.js","sourceRoot":"","sources":["../../src/server/uploads.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,33 @@
1
+ -- Upload sessions: a client sends a file in chunks to a signed URL, then `finalizeUpload` turns the chunks into a row
2
+ -- of files.files. Each received chunk is an object in storage under `uploads/<id>/<index>`; `received_chunks` lists
3
+ -- the indices that arrived whole. The state is derived: finalized once `file_id` is set, expired once `expires_at`
4
+ -- has passed, complete once every chunk arrived, open otherwise.
5
+ -- Rollback: DROP TABLE files.uploads; then DELETE FROM softure.migrations WHERE module = 'files' AND version = 2;
6
+ -- (chunk objects left in storage under uploads/ are not touched by a rollback).
7
+ CREATE TABLE uploads (
8
+ id uuid PRIMARY KEY,
9
+ -- The account the upload belongs to. No foreign key: the module works with any account store.
10
+ owner_id text NOT NULL CHECK (char_length(owner_id) BETWEEN 1 AND 200),
11
+ original_name text NOT NULL CHECK (char_length(original_name) BETWEEN 1 AND 255 AND original_name !~ '[/\\[:cntrl:]]'),
12
+ content_type text NOT NULL CHECK (content_type ~ '^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*(;[ -~]*)?$' AND char_length(content_type) <= 255),
13
+ kind text NOT NULL CHECK (kind ~ '^[a-z][a-z0-9_-]{0,31}$'),
14
+ -- The declared size; every chunk is `chunk_size` bytes except the last.
15
+ size bigint NOT NULL CHECK (size >= 1),
16
+ -- The declared SHA-256, checked at finalize when given.
17
+ sha256 text CHECK (sha256 IS NULL OR sha256 ~ '^[0-9a-f]{64}$'),
18
+ chunk_size integer NOT NULL CHECK (chunk_size >= 1),
19
+ received_chunks integer[] NOT NULL DEFAULT '{}',
20
+ -- The stored file, once finalized. No foreign key: the file may be deleted while the session is still kept for an
21
+ -- idempotent finalize.
22
+ file_id uuid,
23
+ expires_at timestamptz NOT NULL,
24
+ created_at timestamptz NOT NULL,
25
+ finalized_at timestamptz,
26
+ CONSTRAINT uploads_expiry_check CHECK (expires_at > created_at),
27
+ CONSTRAINT uploads_finalized_check CHECK ((file_id IS NULL) = (finalized_at IS NULL))
28
+ );
29
+
30
+ -- An owner's open sessions (the per-owner limit, the privacy export and deletion).
31
+ CREATE INDEX uploads_owner_idx ON uploads (owner_id) WHERE file_id IS NULL;
32
+ -- Prune: sessions whose time is up.
33
+ CREATE INDEX uploads_expires_at_idx ON uploads (expires_at);
package/module.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "id": "files",
3
- "version": "0.1.1",
4
- "dependsOn": { "jobs": "^0.1.6?" },
3
+ "version": "0.2.0",
4
+ "dependsOn": { "jobs": "^0.1.6?", "security": "^0.2.5?" },
5
5
  "dbSchema": "files",
6
- "tables": ["files"],
6
+ "tables": ["files", "uploads"],
7
7
  "env": [
8
8
  {
9
9
  "name": "SOFTURE_FILES_LINK_KEYS",
@@ -12,12 +12,17 @@
12
12
  }
13
13
  ],
14
14
  "switches": [],
15
- "routes": { "links": "/f" },
15
+ "routes": { "links": "/f", "uploads": "/u" },
16
16
  "mount": [
17
17
  {
18
18
  "kind": "route-handler",
19
19
  "path": "app/f/[...link]/route.ts",
20
20
  "export": "serveFileLinkRoute"
21
+ },
22
+ {
23
+ "kind": "route-handler",
24
+ "path": "app/u/[...upload]/route.ts",
25
+ "export": "serveUploadRoute"
21
26
  }
22
27
  ],
23
28
  "privacy": { "exports": true, "deletes": true }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@softure-ai/files",
3
- "version": "0.1.1",
4
- "description": "SOFTURE AI files module: an app's stored files (content hash, size, type, owner, kind, expiry, a per-owner quota, opt-in dedupe) on a storage driver (local disk with atomic writes, S3-compatible with SigV4 and multipart uploads, in memory for tests), streamed and never buffered, public links that expire (HMAC-signed, checked before any database read, revocable per file, a rotating keyring) served by a Next.js route with byte ranges and one 404 for every dead link, a prune job, a privacy contributor and a health check.",
3
+ "version": "0.2.0",
4
+ "description": "SOFTURE AI files module: an app's stored files (content hash, size, type, owner, kind, expiry, a per-owner quota, opt-in dedupe) on a storage driver (local disk with atomic writes, S3-compatible with SigV4 and multipart uploads, in memory for tests), streamed and never buffered, public links that expire (HMAC-signed, checked before any database read, revocable per file, a rotating keyring) served by a Next.js route with byte ranges and one 404 for every dead link, resumable chunked uploads through signed URLs (with a browser page and MCP upload tools), a prune job, a privacy contributor and a health check.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "sideEffects": false,
@@ -47,6 +47,11 @@
47
47
  "types": "./dist/jobs/index.d.ts",
48
48
  "default": "./dist/jobs/index.js"
49
49
  },
50
+ "./mcp": {
51
+ "@softure-ai/source": "./src/mcp/index.ts",
52
+ "types": "./dist/mcp/index.d.ts",
53
+ "default": "./dist/mcp/index.js"
54
+ },
50
55
  "./testing": {
51
56
  "@softure-ai/source": "./src/testing/index.ts",
52
57
  "types": "./dist/testing/index.d.ts",
@@ -59,14 +64,19 @@
59
64
  "dependencies": {
60
65
  "@softure-ai/core": "^0.2.7",
61
66
  "@softure-ai/db": "^0.1.14",
67
+ "@softure-ai/security": "^0.2.5",
62
68
  "zod": "^4.6.5"
63
69
  },
64
70
  "peerDependencies": {
71
+ "@modelcontextprotocol/server": "^2.0.0",
65
72
  "@softure-ai/jobs": "^0.1.6",
66
73
  "drizzle-orm": "^0.45.2",
67
74
  "next": "^16.0.0"
68
75
  },
69
76
  "peerDependenciesMeta": {
77
+ "@modelcontextprotocol/server": {
78
+ "optional": true
79
+ },
70
80
  "@softure-ai/jobs": {
71
81
  "optional": true
72
82
  }
package/src/contract.ts CHANGED
@@ -24,7 +24,18 @@ export type FilesLookupErrorCode =
24
24
  /** The asked range starts at or after the end of the file. */
25
25
  | "files.range_not_satisfiable";
26
26
 
27
- export type FilesErrorCode = FilesKeyErrorCode | FilesSaveErrorCode | FilesLookupErrorCode;
27
+ /** Why an upload session could not be created or finalized. */
28
+ export type FilesUploadErrorCode =
29
+ /** The declared media type is not in `uploads.contentTypes`. */
30
+ | "files.content_type_not_allowed"
31
+ /** The owner already has `uploads.maxOpenPerOwner` open sessions. */
32
+ | "files.too_many_uploads"
33
+ /** Not every chunk has arrived yet. */
34
+ | "files.upload_incomplete"
35
+ /** The bytes that arrived do not match the declared SHA-256. */
36
+ | "files.checksum_mismatch";
37
+
38
+ export type FilesErrorCode = FilesKeyErrorCode | FilesSaveErrorCode | FilesLookupErrorCode | FilesUploadErrorCode;
28
39
 
29
40
  /** A stored file as the app sees it. Never carries the storage key. */
30
41
  export interface StoredFile {
@@ -57,3 +68,36 @@ export interface FileLink {
57
68
  readonly path: string;
58
69
  readonly expiresAt: Date;
59
70
  }
71
+
72
+ /** Where an upload session stands: `open` (chunks missing), `complete` (every chunk arrived), `finalized`, `expired`. */
73
+ export type UploadState = "open" | "complete" | "finalized" | "expired";
74
+
75
+ /** A new upload session, as `createUpload` answers it. */
76
+ export interface CreatedUpload {
77
+ readonly uploadId: string;
78
+ /** The absolute URL the client sends the chunks to; it is the only secret the client needs. */
79
+ readonly uploadUrl: string;
80
+ /** The bytes of every chunk but the last. */
81
+ readonly chunkSize: number;
82
+ readonly chunkCount: number;
83
+ readonly expiresAt: Date;
84
+ }
85
+
86
+ /** An upload session as its owner and the upload route see it. */
87
+ export interface UploadStatus {
88
+ readonly uploadId: string;
89
+ readonly name: string;
90
+ readonly contentType: string;
91
+ readonly size: number;
92
+ readonly chunkSize: number;
93
+ readonly chunkCount: number;
94
+ /** The byte ranges that arrived, merged and in order. */
95
+ readonly received: readonly ByteRange[];
96
+ readonly receivedBytes: number;
97
+ /** The indices of the chunks still to send, in order. */
98
+ readonly missingChunks: readonly number[];
99
+ readonly state: UploadState;
100
+ /** The stored file, once finalized. */
101
+ readonly fileId: string | null;
102
+ readonly expiresAt: Date;
103
+ }