@softure-ai/files 0.1.2 → 0.3.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 (115) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +237 -10
  3. package/dist/client/index.d.ts +3 -0
  4. package/dist/client/index.d.ts.map +1 -0
  5. package/dist/client/index.js +6 -0
  6. package/dist/client/index.js.map +1 -0
  7. package/dist/client/send-upload.d.ts +26 -0
  8. package/dist/client/send-upload.d.ts.map +1 -0
  9. package/dist/client/send-upload.js +66 -0
  10. package/dist/client/send-upload.js.map +1 -0
  11. package/dist/client/upload-queue.d.ts +52 -0
  12. package/dist/client/upload-queue.d.ts.map +1 -0
  13. package/dist/client/upload-queue.js +164 -0
  14. package/dist/client/upload-queue.js.map +1 -0
  15. package/dist/contract.d.ts +41 -1
  16. package/dist/contract.d.ts.map +1 -1
  17. package/dist/index.d.ts +40 -1
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +17 -4
  20. package/dist/index.js.map +1 -1
  21. package/dist/mcp/index.d.ts +65 -0
  22. package/dist/mcp/index.d.ts.map +1 -0
  23. package/dist/mcp/index.js +131 -0
  24. package/dist/mcp/index.js.map +1 -0
  25. package/dist/messages/en.d.ts +20 -0
  26. package/dist/messages/en.d.ts.map +1 -1
  27. package/dist/messages/en.js +20 -0
  28. package/dist/messages/en.js.map +1 -1
  29. package/dist/messages/index.d.ts +20 -0
  30. package/dist/messages/index.d.ts.map +1 -1
  31. package/dist/next/index.d.ts +2 -0
  32. package/dist/next/index.d.ts.map +1 -1
  33. package/dist/next/index.js +4 -2
  34. package/dist/next/index.js.map +1 -1
  35. package/dist/next/stored-file-route.d.ts +25 -0
  36. package/dist/next/stored-file-route.d.ts.map +1 -0
  37. package/dist/next/stored-file-route.js +14 -0
  38. package/dist/next/stored-file-route.js.map +1 -0
  39. package/dist/next/upload-route.d.ts +3 -0
  40. package/dist/next/upload-route.d.ts.map +1 -0
  41. package/dist/next/upload-route.js +11 -0
  42. package/dist/next/upload-route.js.map +1 -0
  43. package/dist/options.d.ts +6 -0
  44. package/dist/options.d.ts.map +1 -1
  45. package/dist/options.js +27 -0
  46. package/dist/options.js.map +1 -1
  47. package/dist/schema.d.ts +255 -0
  48. package/dist/schema.d.ts.map +1 -1
  49. package/dist/schema.js +17 -2
  50. package/dist/schema.js.map +1 -1
  51. package/dist/server/index.d.ts +7 -3
  52. package/dist/server/index.d.ts.map +1 -1
  53. package/dist/server/index.js +7 -3
  54. package/dist/server/index.js.map +1 -1
  55. package/dist/server/options.d.ts +2 -0
  56. package/dist/server/options.d.ts.map +1 -1
  57. package/dist/server/options.js +8 -0
  58. package/dist/server/options.js.map +1 -1
  59. package/dist/server/privacy.d.ts +6 -1
  60. package/dist/server/privacy.d.ts.map +1 -1
  61. package/dist/server/privacy.js +6 -3
  62. package/dist/server/privacy.js.map +1 -1
  63. package/dist/server/prune.d.ts +4 -0
  64. package/dist/server/prune.d.ts.map +1 -1
  65. package/dist/server/prune.js +4 -2
  66. package/dist/server/prune.js.map +1 -1
  67. package/dist/server/save.d.ts +15 -0
  68. package/dist/server/save.d.ts.map +1 -1
  69. package/dist/server/save.js +11 -9
  70. package/dist/server/save.js.map +1 -1
  71. package/dist/server/serve-upload.d.ts +6 -0
  72. package/dist/server/serve-upload.d.ts.map +1 -0
  73. package/dist/server/serve-upload.js +110 -0
  74. package/dist/server/serve-upload.js.map +1 -0
  75. package/dist/server/serve.d.ts +15 -0
  76. package/dist/server/serve.d.ts.map +1 -1
  77. package/dist/server/serve.js +38 -14
  78. package/dist/server/serve.js.map +1 -1
  79. package/dist/server/upload-page.d.ts +5 -0
  80. package/dist/server/upload-page.d.ts.map +1 -0
  81. package/dist/server/upload-page.js +87 -0
  82. package/dist/server/upload-page.js.map +1 -0
  83. package/dist/server/upload-tokens.d.ts +9 -0
  84. package/dist/server/upload-tokens.d.ts.map +1 -0
  85. package/dist/server/upload-tokens.js +43 -0
  86. package/dist/server/upload-tokens.js.map +1 -0
  87. package/dist/server/uploads.d.ts +73 -0
  88. package/dist/server/uploads.d.ts.map +1 -0
  89. package/dist/server/uploads.js +403 -0
  90. package/dist/server/uploads.js.map +1 -0
  91. package/migrations/0002_create_uploads.sql +33 -0
  92. package/module.json +9 -4
  93. package/package.json +17 -2
  94. package/src/client/index.ts +12 -0
  95. package/src/client/send-upload.ts +89 -0
  96. package/src/client/upload-queue.ts +220 -0
  97. package/src/contract.ts +45 -1
  98. package/src/index.ts +32 -5
  99. package/src/mcp/index.ts +206 -0
  100. package/src/messages/en.ts +20 -0
  101. package/src/next/index.ts +10 -2
  102. package/src/next/stored-file-route.ts +43 -0
  103. package/src/next/upload-route.ts +11 -0
  104. package/src/options.ts +28 -0
  105. package/src/schema.ts +20 -2
  106. package/src/server/index.ts +21 -3
  107. package/src/server/options.ts +8 -0
  108. package/src/server/privacy.ts +12 -4
  109. package/src/server/prune.ts +8 -2
  110. package/src/server/save.ts +25 -11
  111. package/src/server/serve-upload.ts +116 -0
  112. package/src/server/serve.ts +51 -14
  113. package/src/server/upload-page.ts +96 -0
  114. package/src/server/upload-tokens.ts +43 -0
  115. 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
+ }
@@ -1,9 +1,11 @@
1
- // The public link answer, framework-free: `GET` and `HEAD` with `Content-Length`, `Accept-Ranges`, single byte
2
- // ranges (`206`, `416`), `Content-Disposition`, and `Cache-Control: private, no-store` so no CDN keeps a copy. Every
3
- // dead link (forged, expired, revoked, deleted, missing from storage) gets the same `404`. A stored file is user
1
+ // The answer for a stored file, framework-free, behind a public link (`serveFileLink`) or for its signed-in owner
2
+ // (`serveStoredFile`): `GET` and `HEAD` with `Content-Length`, `Accept-Ranges`, single byte ranges (`206`, `416`),
3
+ // `Content-Disposition`, and `Cache-Control: private, no-store` so no CDN keeps a copy. Every dead link or lookup
4
+ // (forged, expired, revoked, deleted, another owner's, missing from storage) gets the same `404`. A stored file is user
4
5
  // content on the app's origin, so it is sent with `nosniff` and a sandboxing CSP: an HTML or SVG file never runs.
5
6
  import { errorLogLabel } from "@softure-ai/core";
6
7
  import type { ByteRange } from "../contract.js";
8
+ import type { FileRow } from "../schema.js";
7
9
  import type { FilesContext } from "./context.js";
8
10
  import { findLiveRow } from "./files.js";
9
11
  import { verifyFileLink } from "./links.js";
@@ -19,8 +21,8 @@ const ALLOWED_METHODS = "GET, HEAD";
19
21
 
20
22
  const NOT_FOUND_BODY = "Not found\n";
21
23
 
22
- /** The one answer for every link that does not lead to a live file. */
23
- function notFound(): Response {
24
+ /** The one answer for every link or lookup that does not lead to a live file. */
25
+ export function notFound(): Response {
24
26
  return new Response(NOT_FOUND_BODY, {
25
27
  status: 404,
26
28
  headers: {
@@ -33,12 +35,7 @@ function notFound(): Response {
33
35
 
34
36
  /** Answers a request for a public link (`GET` or `HEAD`). */
35
37
  export async function serveFileLink(ctx: FilesContext, request: Request): Promise<Response> {
36
- if (request.method !== "GET" && request.method !== "HEAD") {
37
- return new Response(null, {
38
- status: 405,
39
- headers: { ...BASE_HEADERS, allow: ALLOWED_METHODS },
40
- });
41
- }
38
+ if (!isReadMethod(request)) return methodNotAllowed();
42
39
  const link = verifyFileLink(ctx, new URL(request.url).pathname);
43
40
  if (!link.ok) {
44
41
  if (link.error !== "files.not_found") console.error(`@softure-ai/files: a link could not be checked: ${link.error}`);
@@ -46,13 +43,53 @@ export async function serveFileLink(ctx: FilesContext, request: Request): Promis
46
43
  }
47
44
  const row = await findLiveRow(ctx, link.value.fileId);
48
45
  if (row?.linkGeneration !== link.value.generation) return notFound();
46
+ const disposition = getFilesOptions(ctx.config).links.disposition;
47
+ return answerStoredFile(ctx, request, row, { name: link.value.name, disposition });
48
+ }
49
+
50
+ export interface ServeStoredFileOptions {
51
+ /** The signed-in user the app's session names; another owner's file reads as missing. */
52
+ readonly ownerId: string;
53
+ /** `inline` (the default: shown in the app's own page, a player or an image) or `attachment` (a download). */
54
+ readonly disposition?: "attachment" | "inline";
55
+ }
56
+
57
+ /**
58
+ * Answers a request (`GET` or `HEAD`) for a stored file on behalf of its signed-in owner: the answer of a public link
59
+ * (single byte ranges, `private, no-store`, `nosniff`, the sandboxing CSP) under the file's stored name, with no link
60
+ * to mint or verify. The caller has already checked the session; a file that is missing, expired, deleted or another
61
+ * owner's gets the same `404`.
62
+ */
63
+ export async function serveStoredFile(ctx: FilesContext, fileId: string, request: Request, options: ServeStoredFileOptions): Promise<Response> {
64
+ if (!isReadMethod(request)) return methodNotAllowed();
65
+ const row = await findLiveRow(ctx, fileId, { ownerId: options.ownerId });
66
+ if (row === undefined) return notFound();
67
+ return answerStoredFile(ctx, request, row, { name: row.originalName, disposition: options.disposition ?? "inline" });
68
+ }
69
+
70
+ function isReadMethod(request: Request): boolean {
71
+ return request.method === "GET" || request.method === "HEAD";
72
+ }
73
+
74
+ function methodNotAllowed(): Response {
75
+ return new Response(null, {
76
+ status: 405,
77
+ headers: { ...BASE_HEADERS, allow: ALLOWED_METHODS },
78
+ });
79
+ }
80
+
81
+ interface StoredFileAnswerOptions {
82
+ readonly name: string;
83
+ readonly disposition: "attachment" | "inline";
84
+ }
49
85
 
50
- const options = getFilesOptions(ctx.config);
86
+ /** The bytes of a live row as the answer to a `GET` or `HEAD`, honouring a single byte range. */
87
+ async function answerStoredFile(ctx: FilesContext, request: Request, row: FileRow, options: StoredFileAnswerOptions): Promise<Response> {
51
88
  const headers: Record<string, string> = {
52
89
  ...BASE_HEADERS,
53
90
  "content-type": row.contentType,
54
91
  "accept-ranges": "bytes",
55
- "content-disposition": formatContentDisposition(options.links.disposition, link.value.name),
92
+ "content-disposition": formatContentDisposition(options.disposition, options.name),
56
93
  "content-security-policy": "sandbox; default-src 'none'",
57
94
  };
58
95
  const range = parseRangeHeader(request.headers.get("range"), row.size);
@@ -69,7 +106,7 @@ export async function serveFileLink(ctx: FilesContext, request: Request): Promis
69
106
 
70
107
  let body: ReadableStream<Uint8Array> | null;
71
108
  try {
72
- body = await options.storage.get(row.storageKey, range ?? undefined);
109
+ body = await getFilesOptions(ctx.config).storage.get(row.storageKey, range ?? undefined);
73
110
  } catch (error) {
74
111
  console.error(`@softure-ai/files: reading file ${row.id} from storage failed: ${errorLogLabel(error)}`);
75
112
  throw error;
@@ -0,0 +1,96 @@
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. The loop is `sendUpload` of `@softure-ai/files/client`, inlined. No
4
+ // framework and no external asset: one inline script and one inline style, allowed by a per-response nonce. The copy
5
+ // comes from the module dictionary (`uploadPage`).
6
+ import { randomBytes } from "node:crypto";
7
+ import { selectMessages } from "@softure-ai/core";
8
+ import { sendUpload } from "../client/send-upload.js";
9
+ import type { UploadStatus } from "../contract.js";
10
+ import type { FilesMessages } from "../messages/index.js";
11
+ import type { FilesContext } from "./context.js";
12
+ import { getFilesModule } from "./options.js";
13
+
14
+ const STYLE = `body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:2rem auto;padding:0 1rem}
15
+ button,input{font:inherit}button{margin-top:1rem;padding:.5rem 1rem}progress{width:100%;margin-top:1rem}
16
+ p[role=status]{min-height:1.5em}`;
17
+
18
+ // The page's script: the client's own `sendUpload`, inlined from its source, then the few lines that wire it to the
19
+ // form. `sendUpload` references nothing outside its body (see `client/send-upload.ts`).
20
+ const SCRIPT = `${sendUpload.toString()}
21
+ const config = JSON.parse(document.getElementById("upload-config").textContent);
22
+ const input = document.getElementById("file");
23
+ const button = document.getElementById("start");
24
+ const bar = document.getElementById("bar");
25
+ const status = document.getElementById("status");
26
+ const megabytes = (bytes) => (bytes / 1048576).toFixed(1) + " MB";
27
+ function show(text) { status.textContent = text; }
28
+ function showProgress(progress) {
29
+ bar.value = progress.totalBytes === 0 ? 1 : progress.sentBytes / progress.totalBytes;
30
+ show(config.text.progress.replace("{done}", megabytes(progress.sentBytes)).replace("{total}", megabytes(progress.totalBytes)));
31
+ }
32
+ async function upload() {
33
+ const file = input.files[0];
34
+ if (!file) return;
35
+ if (file.size !== config.size) { show(config.text.wrongSize); return; }
36
+ button.disabled = true;
37
+ const sent = await sendUpload(file, { uploadUrl: location.href, onProgress: showProgress });
38
+ if (sent.ok) { bar.value = 1; show(config.text.done); return; }
39
+ show(sent.error === "files.upload_expired" ? config.text.expired : config.text.failed);
40
+ button.disabled = sent.error === "files.upload_expired";
41
+ }
42
+ button.addEventListener("click", upload);`;
43
+
44
+ /** The page for a session; a finalized or complete one shows that it is done. */
45
+ export function renderUploadPage(ctx: Pick<FilesContext, "config">, status: UploadStatus): Response {
46
+ const text = (selectMessages(getFilesModule(ctx.config).messages, ctx.config.locale) as FilesMessages).uploadPage;
47
+ const nonce = randomBytes(16).toString("base64");
48
+ const isDone = status.state === "complete" || status.state === "finalized";
49
+ const config = { size: status.size, chunkSize: status.chunkSize, text };
50
+ const expected = text.expected.replace("{name}", status.name).replace("{size}", `${(status.size / 1048576).toFixed(1)} MB`);
51
+ const html = `<!doctype html>
52
+ <html lang="${escapeHtml(ctx.config.locale)}">
53
+ <head>
54
+ <meta charset="utf-8">
55
+ <meta name="viewport" content="width=device-width, initial-scale=1">
56
+ <meta name="robots" content="noindex">
57
+ <title>${escapeHtml(text.title)}</title>
58
+ <style nonce="${nonce}">${STYLE}</style>
59
+ </head>
60
+ <body>
61
+ <h1>${escapeHtml(text.title)}</h1>
62
+ <p>${escapeHtml(text.intro)}</p>
63
+ <p>${escapeHtml(expected)}</p>
64
+ ${
65
+ isDone
66
+ ? `<p role="status">${escapeHtml(text.done)}</p>`
67
+ : `<label for="file">${escapeHtml(text.choose)}</label><br>
68
+ <input id="file" type="file">
69
+ <br><button id="start" type="button">${escapeHtml(text.start)}</button>
70
+ <progress id="bar" max="1" value="${String(status.receivedBytes / status.size)}"></progress>
71
+ <p id="status" role="status"></p>
72
+ <script id="upload-config" type="application/json">${toScriptJson(config)}</script>
73
+ <script nonce="${nonce}">${SCRIPT}</script>`
74
+ }
75
+ </body>
76
+ </html>`;
77
+ return new Response(html, {
78
+ status: 200,
79
+ headers: {
80
+ "content-type": "text/html; charset=utf-8",
81
+ "cache-control": "private, no-store",
82
+ "x-content-type-options": "nosniff",
83
+ "referrer-policy": "no-referrer",
84
+ "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'`,
85
+ },
86
+ });
87
+ }
88
+
89
+ function escapeHtml(value: string): string {
90
+ return value.replace(/[&<>"']/g, (char) => `&#${String(char.charCodeAt(0))};`);
91
+ }
92
+
93
+ /** JSON safe inside a `<script>` element: no `<` can close it. */
94
+ function toScriptJson(value: unknown): string {
95
+ return JSON.stringify(value).replace(/</g, "\\u003c");
96
+ }
@@ -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
+ }