@softure-ai/files 0.1.2 → 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 +19 -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,116 @@
1
+ // The upload route, framework-free: `PUT` writes one chunk (`Content-Range: bytes a-b/total`, or no range when the
2
+ // file fits one chunk), `HEAD` answers what arrived in headers so a client can resume, `GET` answers the same as JSON
3
+ // or, to a browser, the upload page. The URL's signature is checked before any database read, and every dead URL
4
+ // (forged, expired, finalized for a `PUT`) gets the same `404`. With the security module enabled each request counts
5
+ // in the `files-upload` bucket, keyed by the session.
6
+ import { errorLogLabel, getModule } from "@softure-ai/core";
7
+ import { consumeRateLimit, subjectKey } from "@softure-ai/security/server";
8
+ import type { UploadStatus } from "../contract.js";
9
+ import type { FilesContext } from "./context.js";
10
+ import { getUpload, writeUploadChunk, type UploadChunkErrorCode } from "./uploads.js";
11
+ import { renderUploadPage } from "./upload-page.js";
12
+ import { verifyUploadPath } from "./upload-tokens.js";
13
+
14
+ /** The security bucket the upload route counts in; `FILES_RATE_LIMIT_BUCKETS` holds its default. */
15
+ export const FILES_UPLOAD_RATE_LIMIT_BUCKET = "files-upload";
16
+
17
+ const BASE_HEADERS = {
18
+ "cache-control": "private, no-store",
19
+ "x-content-type-options": "nosniff",
20
+ "referrer-policy": "no-referrer",
21
+ } as const;
22
+ const ALLOWED_METHODS = "GET, HEAD, PUT";
23
+ const CONTENT_RANGE_PATTERN = /^bytes (\d{1,15})-(\d{1,15})\/(\d{1,15})$/;
24
+ const ERROR_STATUS: Readonly<Record<UploadChunkErrorCode, number>> = {
25
+ "files.not_found": 404,
26
+ "files.invalid_range": 416,
27
+ "files.chunk_length_mismatch": 400,
28
+ };
29
+
30
+ /** Answers a request to an upload URL (`GET`, `HEAD` or `PUT`). */
31
+ export async function serveUpload(ctx: FilesContext, request: Request): Promise<Response> {
32
+ if (request.method !== "GET" && request.method !== "HEAD" && request.method !== "PUT") {
33
+ return new Response(null, { status: 405, headers: { ...BASE_HEADERS, allow: ALLOWED_METHODS } });
34
+ }
35
+ const verified = verifyUploadPath(ctx, new URL(request.url).pathname);
36
+ if (!verified.ok) {
37
+ if (verified.error !== "files.not_found") console.error(`@softure-ai/files: an upload URL could not be checked: ${verified.error}`);
38
+ return answerError("files.not_found");
39
+ }
40
+ const uploadId = verified.value;
41
+ const limited = await countRequest(ctx, uploadId);
42
+ if (limited !== null) return limited;
43
+
44
+ if (request.method === "PUT") return putChunk(ctx, uploadId, request);
45
+ const status = await getUpload(ctx, uploadId);
46
+ if (status === null) return answerError("files.not_found");
47
+ if (request.method === "HEAD") return new Response(null, { status: 200, headers: { ...BASE_HEADERS, ...describeInHeaders(status) } });
48
+ if (acceptsHtml(request)) return renderUploadPage(ctx, status);
49
+ return answerJson(status);
50
+ }
51
+
52
+ async function putChunk(ctx: FilesContext, uploadId: string, request: Request): Promise<Response> {
53
+ const header = request.headers.get("content-range");
54
+ const match = header === null ? null : CONTENT_RANGE_PATTERN.exec(header.trim());
55
+ if (header !== null && match === null) return answerError("files.invalid_range");
56
+ const range = match === null ? null : { start: Number(match[1]), end: Number(match[2]) };
57
+ const declaredLength = request.headers.get("content-length");
58
+ // A body that cannot fit its range is refused before a byte of it is read.
59
+ if (range !== null && declaredLength !== null && Number(declaredLength) !== range.end - range.start + 1) return answerError("files.chunk_length_mismatch");
60
+ try {
61
+ const written = await writeUploadChunk(ctx, uploadId, {
62
+ range,
63
+ ...(match === null ? {} : { total: Number(match[3]) }),
64
+ body: request.body ?? emptyBody(),
65
+ });
66
+ return written.ok ? answerJson(written.value) : answerError(written.error);
67
+ } catch (error) {
68
+ console.error(`@softure-ai/files: storing a chunk of upload ${uploadId} failed: ${errorLogLabel(error)}`);
69
+ throw error;
70
+ }
71
+ }
72
+
73
+ /** Counts the request in the security bucket when the app enabled that module; a `429` when over the limit. */
74
+ async function countRequest(ctx: FilesContext, uploadId: string): Promise<Response | null> {
75
+ const security = getModule(ctx.config, "security");
76
+ if (security === undefined) return null;
77
+ const buckets = (security.options as { buckets?: Record<string, unknown> }).buckets;
78
+ if (buckets?.[FILES_UPLOAD_RATE_LIMIT_BUCKET] === undefined) {
79
+ throw new Error(
80
+ `@softure-ai/files: the security module has no "${FILES_UPLOAD_RATE_LIMIT_BUCKET}" bucket; spread FILES_RATE_LIMIT_BUCKETS into security({ buckets })`,
81
+ );
82
+ }
83
+ const counted = await consumeRateLimit(ctx, { bucket: FILES_UPLOAD_RATE_LIMIT_BUCKET, key: subjectKey(`upload:${uploadId}`) });
84
+ if (counted.ok) return null;
85
+ return new Response(null, { status: 429, headers: { ...BASE_HEADERS, "retry-after": String(counted.retryAfterSeconds) } });
86
+ }
87
+
88
+ /** What arrived, for `HEAD`: `upload-received` lists the byte ranges (`0-1023,2048-2559`), empty when none. */
89
+ function describeInHeaders(status: UploadStatus): Record<string, string> {
90
+ return {
91
+ "upload-state": status.state,
92
+ "upload-size": String(status.size),
93
+ "upload-chunk-size": String(status.chunkSize),
94
+ "upload-received": status.received.map((range) => `${String(range.start)}-${String(range.end)}`).join(","),
95
+ "upload-expires": status.expiresAt.toISOString(),
96
+ };
97
+ }
98
+
99
+ function answerJson(status: UploadStatus): Response {
100
+ return Response.json(
101
+ { ...status, expiresAt: status.expiresAt.toISOString() },
102
+ { status: 200, headers: { ...BASE_HEADERS, ...describeInHeaders(status) } },
103
+ );
104
+ }
105
+
106
+ function answerError(code: UploadChunkErrorCode): Response {
107
+ return Response.json({ error: code }, { status: ERROR_STATUS[code], headers: BASE_HEADERS });
108
+ }
109
+
110
+ function acceptsHtml(request: Request): boolean {
111
+ return (request.headers.get("accept") ?? "").includes("text/html");
112
+ }
113
+
114
+ async function* emptyBody(): AsyncGenerator<Uint8Array> {
115
+ // A PUT without a body: nothing to yield.
116
+ }
@@ -0,0 +1,103 @@
1
+ // The browser fallback for an upload session: a small page on the upload URL itself, for a person on a phone or an
2
+ // assistant that cannot run `curl`. It sends the missing chunks of the chosen file one by one with `fetch`, so a
3
+ // broken connection resumes where it stopped. No framework and no external asset: one inline script and one inline
4
+ // style, allowed by a per-response nonce. The copy comes from the module dictionary (`uploadPage`).
5
+ import { randomBytes } from "node:crypto";
6
+ import { selectMessages } from "@softure-ai/core";
7
+ import type { UploadStatus } from "../contract.js";
8
+ import type { FilesMessages } from "../messages/index.js";
9
+ import type { FilesContext } from "./context.js";
10
+ import { getFilesModule } from "./options.js";
11
+
12
+ const STYLE = `body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:2rem auto;padding:0 1rem}
13
+ button,input{font:inherit}button{margin-top:1rem;padding:.5rem 1rem}progress{width:100%;margin-top:1rem}
14
+ p[role=status]{min-height:1.5em}`;
15
+
16
+ const SCRIPT = `const config = JSON.parse(document.getElementById("upload-config").textContent);
17
+ const input = document.getElementById("file");
18
+ const button = document.getElementById("start");
19
+ const bar = document.getElementById("bar");
20
+ const status = document.getElementById("status");
21
+ const megabytes = (bytes) => (bytes / 1048576).toFixed(1) + " MB";
22
+ function show(text) { status.textContent = text; }
23
+ async function upload() {
24
+ const file = input.files[0];
25
+ if (!file) return;
26
+ if (file.size !== config.size) { show(config.text.wrongSize); return; }
27
+ button.disabled = true;
28
+ try {
29
+ const answer = await fetch(location.href, { headers: { accept: "application/json" } });
30
+ if (!answer.ok) throw new Error("status " + answer.status);
31
+ const state = await answer.json();
32
+ let done = state.receivedBytes;
33
+ for (const index of state.missingChunks) {
34
+ const start = index * config.chunkSize;
35
+ const end = Math.min(start + config.chunkSize, config.size) - 1;
36
+ const sent = await fetch(location.href, { method: "PUT", headers: { "content-range": "bytes " + start + "-" + end + "/" + config.size }, body: file.slice(start, end + 1) });
37
+ if (!sent.ok) throw new Error("status " + sent.status);
38
+ done += end - start + 1;
39
+ bar.value = done / config.size;
40
+ show(config.text.progress.replace("{done}", megabytes(done)).replace("{total}", megabytes(config.size)));
41
+ }
42
+ bar.value = 1;
43
+ show(config.text.done);
44
+ } catch {
45
+ show(config.text.failed);
46
+ button.disabled = false;
47
+ }
48
+ }
49
+ button.addEventListener("click", upload);`;
50
+
51
+ /** The page for a session; a finalized or complete one shows that it is done. */
52
+ export function renderUploadPage(ctx: Pick<FilesContext, "config">, status: UploadStatus): Response {
53
+ const text = (selectMessages(getFilesModule(ctx.config).messages, ctx.config.locale) as FilesMessages).uploadPage;
54
+ const nonce = randomBytes(16).toString("base64");
55
+ const isDone = status.state === "complete" || status.state === "finalized";
56
+ const config = { size: status.size, chunkSize: status.chunkSize, text };
57
+ const expected = text.expected.replace("{name}", status.name).replace("{size}", `${(status.size / 1048576).toFixed(1)} MB`);
58
+ const html = `<!doctype html>
59
+ <html lang="${escapeHtml(ctx.config.locale)}">
60
+ <head>
61
+ <meta charset="utf-8">
62
+ <meta name="viewport" content="width=device-width, initial-scale=1">
63
+ <meta name="robots" content="noindex">
64
+ <title>${escapeHtml(text.title)}</title>
65
+ <style nonce="${nonce}">${STYLE}</style>
66
+ </head>
67
+ <body>
68
+ <h1>${escapeHtml(text.title)}</h1>
69
+ <p>${escapeHtml(text.intro)}</p>
70
+ <p>${escapeHtml(expected)}</p>
71
+ ${
72
+ isDone
73
+ ? `<p role="status">${escapeHtml(text.done)}</p>`
74
+ : `<label for="file">${escapeHtml(text.choose)}</label><br>
75
+ <input id="file" type="file">
76
+ <br><button id="start" type="button">${escapeHtml(text.start)}</button>
77
+ <progress id="bar" max="1" value="${String(status.receivedBytes / status.size)}"></progress>
78
+ <p id="status" role="status"></p>
79
+ <script id="upload-config" type="application/json">${toScriptJson(config)}</script>
80
+ <script nonce="${nonce}">${SCRIPT}</script>`
81
+ }
82
+ </body>
83
+ </html>`;
84
+ return new Response(html, {
85
+ status: 200,
86
+ headers: {
87
+ "content-type": "text/html; charset=utf-8",
88
+ "cache-control": "private, no-store",
89
+ "x-content-type-options": "nosniff",
90
+ "referrer-policy": "no-referrer",
91
+ "content-security-policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'`,
92
+ },
93
+ });
94
+ }
95
+
96
+ function escapeHtml(value: string): string {
97
+ return value.replace(/[&<>"']/g, (char) => `&#${String(char.charCodeAt(0))};`);
98
+ }
99
+
100
+ /** JSON safe inside a `<script>` element: no `<` can close it. */
101
+ function toScriptJson(value: unknown): string {
102
+ return JSON.stringify(value).replace(/</g, "\\u003c");
103
+ }
@@ -0,0 +1,43 @@
1
+ // Upload URLs: `<route>/<id>/<expiry>.<mac>`, where `expiry` is the session's expiry as a Unix time in seconds and
2
+ // `mac` an HMAC-SHA256 (base64url) over both under the link keyring's first key, with a context string of its own so
3
+ // an upload MAC never passes as a link MAC. The MAC and the expiry are checked before any database read, so a forged
4
+ // or stale URL costs no query.
5
+ import { createHmac, timingSafeEqual } from "node:crypto";
6
+ import { err, ok, type Err, type Ok } from "@softure-ai/core";
7
+ import type { FilesKeyErrorCode } from "../contract.js";
8
+ import type { FilesContext } from "./context.js";
9
+ import { UUID_PATTERN } from "./files.js";
10
+ import { readLinkKeyring, type LinkKeyring } from "./keys.js";
11
+ import { getUploadsRoute } from "./options.js";
12
+
13
+ const MAC_CONTEXT = "softure-files-upload/v1";
14
+ const TOKEN_PATTERN = /^([1-9]\d{0,11})\.([A-Za-z0-9_-]{43})$/;
15
+
16
+ /** The path of a session's upload URL. */
17
+ export function signUploadPath(ctx: Pick<FilesContext, "config">, keyring: LinkKeyring, uploadId: string, expiresAt: Date): string {
18
+ const expiry = String(Math.floor(expiresAt.getTime() / 1000));
19
+ return `${getUploadsRoute(ctx.config)}/${uploadId}/${expiry}.${signUpload(keyring.current, uploadId, expiry)}`;
20
+ }
21
+
22
+ /** The session an upload path is for, once its MAC and expiry are checked. Every refusal of the URL is `files.not_found`. */
23
+ export function verifyUploadPath(ctx: Pick<FilesContext, "clock" | "config" | "env">, pathname: string): Ok<string> | Err<"files.not_found" | FilesKeyErrorCode> {
24
+ const route = getUploadsRoute(ctx.config);
25
+ if (!pathname.startsWith(`${route}/`)) return err("files.not_found");
26
+ const segments = pathname.slice(route.length + 1).split("/");
27
+ const [uploadId = "", token = ""] = segments;
28
+ const match = TOKEN_PATTERN.exec(token);
29
+ if (segments.length !== 2 || !UUID_PATTERN.test(uploadId) || match === null) return err("files.not_found");
30
+ const [, expiry = "", mac = ""] = match;
31
+ const keyring = readLinkKeyring(ctx.env ?? process.env);
32
+ if (!keyring.ok) return keyring;
33
+ const given = Buffer.from(mac, "ascii");
34
+ // Every key is tried, so the time taken does not tell which one matched.
35
+ const isValid = keyring.value.keys.reduce((isMatch, key) => timingSafeEqual(Buffer.from(signUpload(key, uploadId, expiry), "ascii"), given) || isMatch, false);
36
+ if (!isValid) return err("files.not_found");
37
+ if (Number(expiry) * 1000 <= ctx.clock.now().getTime()) return err("files.not_found");
38
+ return ok(uploadId);
39
+ }
40
+
41
+ function signUpload(key: Buffer, uploadId: string, expiry: string): string {
42
+ return createHmac("sha256", key).update([MAC_CONTEXT, uploadId, expiry].join("\n")).digest("base64url");
43
+ }