@softure-ai/files 0.0.0-stage → 0.1.2
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.
- package/CHANGELOG.md +26 -0
- package/LICENSE +21 -0
- package/README.md +213 -2
- package/dist/contract.d.ts +51 -0
- package/dist/contract.d.ts.map +1 -0
- package/dist/contract.js +4 -0
- package/dist/contract.js.map +1 -0
- package/dist/index.d.ts +45 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +49 -0
- package/dist/index.js.map +1 -0
- package/dist/jobs/index.d.ts +12 -0
- package/dist/jobs/index.d.ts.map +1 -0
- package/dist/jobs/index.js +22 -0
- package/dist/jobs/index.js.map +1 -0
- package/dist/messages/en.d.ts +17 -0
- package/dist/messages/en.d.ts.map +1 -0
- package/dist/messages/en.js +17 -0
- package/dist/messages/en.js.map +1 -0
- package/dist/messages/index.d.ts +24 -0
- package/dist/messages/index.d.ts.map +1 -0
- package/dist/messages/index.js +10 -0
- package/dist/messages/index.js.map +1 -0
- package/dist/next/context.d.ts +4 -0
- package/dist/next/context.d.ts.map +1 -0
- package/dist/next/context.js +13 -0
- package/dist/next/context.js.map +1 -0
- package/dist/next/index.d.ts +3 -0
- package/dist/next/index.d.ts.map +1 -0
- package/dist/next/index.js +5 -0
- package/dist/next/index.js.map +1 -0
- package/dist/next/route.d.ts +3 -0
- package/dist/next/route.d.ts.map +1 -0
- package/dist/next/route.js +11 -0
- package/dist/next/route.js.map +1 -0
- package/dist/options.d.ts +26 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/options.js +59 -0
- package/dist/options.js.map +1 -0
- package/dist/schema.d.ts +214 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +19 -0
- package/dist/schema.js.map +1 -0
- package/dist/server/context.d.ts +13 -0
- package/dist/server/context.d.ts.map +1 -0
- package/dist/server/context.js +19 -0
- package/dist/server/context.js.map +1 -0
- package/dist/server/files.d.ts +48 -0
- package/dist/server/files.d.ts.map +1 -0
- package/dist/server/files.js +104 -0
- package/dist/server/files.js.map +1 -0
- package/dist/server/health.d.ts +4 -0
- package/dist/server/health.d.ts.map +1 -0
- package/dist/server/health.js +20 -0
- package/dist/server/health.js.map +1 -0
- package/dist/server/index.d.ts +15 -0
- package/dist/server/index.d.ts.map +1 -0
- package/dist/server/index.js +17 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/keys.d.ts +14 -0
- package/dist/server/keys.d.ts.map +1 -0
- package/dist/server/keys.js +47 -0
- package/dist/server/keys.js.map +1 -0
- package/dist/server/links.d.ts +30 -0
- package/dist/server/links.d.ts.map +1 -0
- package/dist/server/links.js +122 -0
- package/dist/server/links.js.map +1 -0
- package/dist/server/local-storage.d.ts +7 -0
- package/dist/server/local-storage.d.ts.map +1 -0
- package/dist/server/local-storage.js +83 -0
- package/dist/server/local-storage.js.map +1 -0
- package/dist/server/names.d.ts +11 -0
- package/dist/server/names.d.ts.map +1 -0
- package/dist/server/names.js +32 -0
- package/dist/server/names.js.map +1 -0
- package/dist/server/options.d.ts +8 -0
- package/dist/server/options.d.ts.map +1 -0
- package/dist/server/options.js +31 -0
- package/dist/server/options.js.map +1 -0
- package/dist/server/privacy.d.ts +16 -0
- package/dist/server/privacy.d.ts.map +1 -0
- package/dist/server/privacy.js +39 -0
- package/dist/server/privacy.js.map +1 -0
- package/dist/server/prune.d.ts +13 -0
- package/dist/server/prune.d.ts.map +1 -0
- package/dist/server/prune.js +34 -0
- package/dist/server/prune.js.map +1 -0
- package/dist/server/queries.d.ts +7 -0
- package/dist/server/queries.d.ts.map +1 -0
- package/dist/server/queries.js +17 -0
- package/dist/server/queries.js.map +1 -0
- package/dist/server/s3-storage.d.ts +33 -0
- package/dist/server/s3-storage.d.ts.map +1 -0
- package/dist/server/s3-storage.js +223 -0
- package/dist/server/s3-storage.js.map +1 -0
- package/dist/server/save.d.ts +29 -0
- package/dist/server/save.d.ts.map +1 -0
- package/dist/server/save.js +141 -0
- package/dist/server/save.js.map +1 -0
- package/dist/server/serve.d.ts +11 -0
- package/dist/server/serve.d.ts.map +1 -0
- package/dist/server/serve.js +108 -0
- package/dist/server/serve.js.map +1 -0
- package/dist/server/sigv4.d.ts +23 -0
- package/dist/server/sigv4.d.ts.map +1 -0
- package/dist/server/sigv4.js +57 -0
- package/dist/server/sigv4.js.map +1 -0
- package/dist/storage.d.ts +32 -0
- package/dist/storage.d.ts.map +1 -0
- package/dist/storage.js +10 -0
- package/dist/storage.js.map +1 -0
- package/dist/testing/index.d.ts +3 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +4 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/links.d.ts +22 -0
- package/dist/testing/links.d.ts.map +1 -0
- package/dist/testing/links.js +30 -0
- package/dist/testing/links.js.map +1 -0
- package/dist/testing/memory-storage.d.ts +11 -0
- package/dist/testing/memory-storage.d.ts.map +1 -0
- package/dist/testing/memory-storage.js +52 -0
- package/dist/testing/memory-storage.js.map +1 -0
- package/migrations/0001_create_files.sql +32 -0
- package/module.json +24 -0
- package/package.json +72 -4
- package/src/contract.ts +59 -0
- package/src/index.ts +53 -0
- package/src/jobs/index.ts +23 -0
- package/src/messages/en.ts +16 -0
- package/src/messages/index.ts +13 -0
- package/src/next/context.ts +14 -0
- package/src/next/index.ts +4 -0
- package/src/next/route.ts +11 -0
- package/src/options.ts +64 -0
- package/src/schema.ts +22 -0
- package/src/server/context.ts +32 -0
- package/src/server/files.ts +133 -0
- package/src/server/health.ts +20 -0
- package/src/server/index.ts +45 -0
- package/src/server/keys.ts +56 -0
- package/src/server/links.ts +152 -0
- package/src/server/local-storage.ts +87 -0
- package/src/server/names.ts +35 -0
- package/src/server/options.ts +34 -0
- package/src/server/privacy.ts +53 -0
- package/src/server/prune.ts +46 -0
- package/src/server/queries.ts +19 -0
- package/src/server/s3-storage.ts +255 -0
- package/src/server/save.ts +167 -0
- package/src/server/serve.ts +106 -0
- package/src/server/sigv4.ts +82 -0
- package/src/storage.ts +43 -0
- package/src/testing/index.ts +3 -0
- package/src/testing/links.ts +47 -0
- package/src/testing/memory-storage.ts +64 -0
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// The public link route, mounted with one line:
|
|
2
|
+
// `app/f/[...link]/route.ts → export { serveFileLinkRoute as GET, serveFileLinkRoute as HEAD } from "@softure-ai/files/next";`
|
|
3
|
+
// It reads no session: a link is protected by its signature, so the route must stay outside the app's sign-in guard
|
|
4
|
+
// and the edge's sign-in (README §4). The path is read from the request URL, not from Next's params.
|
|
5
|
+
import { getFilesContext } from "./context.js";
|
|
6
|
+
import { serveFileLink } from "../server/serve.js";
|
|
7
|
+
|
|
8
|
+
/** `GET` and `HEAD /f/<id>/<expiry>/<signature>/<name>`. */
|
|
9
|
+
export async function serveFileLinkRoute(request: Request): Promise<Response> {
|
|
10
|
+
return serveFileLink(await getFilesContext(), request);
|
|
11
|
+
}
|
package/src/options.ts
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
// The options an app passes to `files({ ... })` in softure.config.ts, parsed at startup. The storage driver is an
|
|
2
|
+
// object the app builds (`createLocalStorage`, `createS3Storage`); building one touches neither the disk nor the
|
|
3
|
+
// network, so `next build` runs without the folder or the bucket's secrets.
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
import { isFileStorage, type FileStorage } from "./storage.js";
|
|
6
|
+
|
|
7
|
+
const MIB = 1024 * 1024;
|
|
8
|
+
const DAY_SECONDS = 24 * 60 * 60;
|
|
9
|
+
|
|
10
|
+
/** A file kind: lowercase letters, digits, `_` and `-`, starting with a letter, at most 32 characters. */
|
|
11
|
+
export const FILE_KIND_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/;
|
|
12
|
+
/** The kind of a file saved without one. */
|
|
13
|
+
export const DEFAULT_FILE_KIND = "file";
|
|
14
|
+
|
|
15
|
+
export const filesOptionsSchema = z.strictObject({
|
|
16
|
+
/** Where the bytes live: `createLocalStorage({ dir })`, `createS3Storage({ ... })` or `createMemoryStorage()`. */
|
|
17
|
+
storage: z.custom<FileStorage>(isFileStorage, "must be a storage driver such as createLocalStorage({ dir })"),
|
|
18
|
+
/** The largest file `saveFile` accepts. */
|
|
19
|
+
maxFileBytes: z
|
|
20
|
+
.number()
|
|
21
|
+
.int()
|
|
22
|
+
.min(1)
|
|
23
|
+
.max(Number.MAX_SAFE_INTEGER)
|
|
24
|
+
.default(100 * MIB),
|
|
25
|
+
/** The bytes one owner may keep in live files; null: no quota. */
|
|
26
|
+
quotaBytesPerOwner: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).nullable().default(null),
|
|
27
|
+
/** Saving content an owner already has (same SHA-256) answers the existing file instead of a second copy. */
|
|
28
|
+
dedupe: z.boolean().default(false),
|
|
29
|
+
/** The lifetime of a file saved without `expiresAt` or `ttlSeconds`; null: kept until deleted. */
|
|
30
|
+
defaultTtlSeconds: z
|
|
31
|
+
.number()
|
|
32
|
+
.int()
|
|
33
|
+
.min(60)
|
|
34
|
+
.max(3650 * DAY_SECONDS)
|
|
35
|
+
.nullable()
|
|
36
|
+
.default(null),
|
|
37
|
+
links: z
|
|
38
|
+
.strictObject({
|
|
39
|
+
/** The longest lifetime `createFileLink` grants. */
|
|
40
|
+
maxTtlSeconds: z
|
|
41
|
+
.number()
|
|
42
|
+
.int()
|
|
43
|
+
.min(60)
|
|
44
|
+
.max(365 * DAY_SECONDS)
|
|
45
|
+
.default(7 * DAY_SECONDS),
|
|
46
|
+
/** How a link hands the file over: a download (`attachment`) or shown in the browser (`inline`). */
|
|
47
|
+
disposition: z.enum(["attachment", "inline"]).default("attachment"),
|
|
48
|
+
})
|
|
49
|
+
.default({ maxTtlSeconds: 7 * DAY_SECONDS, disposition: "attachment" }),
|
|
50
|
+
health: z
|
|
51
|
+
.strictObject({
|
|
52
|
+
/** Below this many free bytes (when the driver can tell) the health check fails. */
|
|
53
|
+
minFreeBytes: z
|
|
54
|
+
.number()
|
|
55
|
+
.int()
|
|
56
|
+
.min(0)
|
|
57
|
+
.max(Number.MAX_SAFE_INTEGER)
|
|
58
|
+
.default(1024 * MIB),
|
|
59
|
+
})
|
|
60
|
+
.default({ minFreeBytes: 1024 * MIB }),
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
export type FilesOptionsInput = z.input<typeof filesOptionsSchema>;
|
|
64
|
+
export type FilesOptions = z.output<typeof filesOptionsSchema>;
|
package/src/schema.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Drizzle view of the module's table (migrations/0001_create_files.sql). The migration is the source of truth;
|
|
2
|
+
// this file only types the queries.
|
|
3
|
+
import { bigint, integer, pgSchema, text, timestamp, uuid } from "drizzle-orm/pg-core";
|
|
4
|
+
|
|
5
|
+
export const filesSchema = pgSchema("files");
|
|
6
|
+
|
|
7
|
+
export const files = filesSchema.table("files", {
|
|
8
|
+
id: uuid("id").primaryKey(),
|
|
9
|
+
ownerId: text("owner_id").notNull(),
|
|
10
|
+
sha256: text("sha256").notNull(),
|
|
11
|
+
size: bigint("size", { mode: "number" }).notNull(),
|
|
12
|
+
contentType: text("content_type").notNull(),
|
|
13
|
+
originalName: text("original_name").notNull(),
|
|
14
|
+
kind: text("kind").notNull(),
|
|
15
|
+
storageKey: text("storage_key").notNull(),
|
|
16
|
+
linkGeneration: integer("link_generation").notNull(),
|
|
17
|
+
expiresAt: timestamp("expires_at", { withTimezone: true }),
|
|
18
|
+
deletedAt: timestamp("deleted_at", { withTimezone: true }),
|
|
19
|
+
createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
export type FileRow = typeof files.$inferSelect;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
// What every server function receives, and the mapping from a row to the file the app sees.
|
|
2
|
+
import type { ModuleContext } from "@softure-ai/core";
|
|
3
|
+
import type { Queryable } from "@softure-ai/db";
|
|
4
|
+
import type { StoredFile } from "../contract.js";
|
|
5
|
+
import type { FileRow } from "../schema.js";
|
|
6
|
+
|
|
7
|
+
export type Env = Readonly<Record<string, string | undefined>>;
|
|
8
|
+
|
|
9
|
+
/** The module context; `env` defaults to `process.env` (the link keyring). */
|
|
10
|
+
export interface FilesContext extends ModuleContext<Queryable> {
|
|
11
|
+
readonly env?: Env;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export function toStoredFile(row: FileRow): StoredFile {
|
|
15
|
+
return {
|
|
16
|
+
id: row.id,
|
|
17
|
+
ownerId: row.ownerId,
|
|
18
|
+
sha256: row.sha256,
|
|
19
|
+
size: row.size,
|
|
20
|
+
contentType: row.contentType,
|
|
21
|
+
name: row.originalName,
|
|
22
|
+
kind: row.kind,
|
|
23
|
+
expiresAt: row.expiresAt,
|
|
24
|
+
createdAt: row.createdAt,
|
|
25
|
+
};
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** The storage key of a file: two levels of fan-out by its id, so no folder holds more than 256 entries per level. */
|
|
29
|
+
export function getStorageKey(fileId: string): string {
|
|
30
|
+
const hex = fileId.replaceAll("-", "");
|
|
31
|
+
return `${hex.slice(0, 2)}/${hex.slice(2, 4)}/${fileId}`;
|
|
32
|
+
}
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
// Reading, listing and deleting stored files. Only live files (neither deleted nor expired) are found; an owner
|
|
2
|
+
// filter makes another owner's file read as missing.
|
|
3
|
+
import { err, errorLogLabel, ok, type Err, type Ok } from "@softure-ai/core";
|
|
4
|
+
import { and, desc, eq, isNull, type SQL } from "drizzle-orm";
|
|
5
|
+
import type { ByteRange, FilesLookupErrorCode, StoredFile } from "../contract.js";
|
|
6
|
+
import { files, type FileRow } from "../schema.js";
|
|
7
|
+
import { toStoredFile, type FilesContext } from "./context.js";
|
|
8
|
+
import { getFilesOptions } from "./options.js";
|
|
9
|
+
import { isLive, sumOwnerBytes } from "./queries.js";
|
|
10
|
+
|
|
11
|
+
const DEFAULT_LIST_LIMIT = 100;
|
|
12
|
+
const MAX_LIST_LIMIT = 1000;
|
|
13
|
+
|
|
14
|
+
export interface FileLookupOptions {
|
|
15
|
+
/** Only this owner's file; another owner's reads as missing. */
|
|
16
|
+
readonly ownerId?: string;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** The live row with this id, or undefined. Not a uuid reads as missing. */
|
|
20
|
+
export async function findLiveRow(ctx: FilesContext, fileId: string, options: FileLookupOptions = {}): Promise<FileRow | undefined> {
|
|
21
|
+
if (!UUID_PATTERN.test(fileId)) return undefined;
|
|
22
|
+
const conditions: SQL[] = [eq(files.id, fileId), isLive(ctx.clock.now())];
|
|
23
|
+
if (options.ownerId !== undefined) conditions.push(eq(files.ownerId, options.ownerId));
|
|
24
|
+
const [row] = await ctx.db
|
|
25
|
+
.select()
|
|
26
|
+
.from(files)
|
|
27
|
+
.where(and(...conditions));
|
|
28
|
+
return row;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
|
|
32
|
+
|
|
33
|
+
/** A live file, or null. */
|
|
34
|
+
export async function findFile(ctx: FilesContext, fileId: string, options: FileLookupOptions = {}): Promise<StoredFile | null> {
|
|
35
|
+
const row = await findLiveRow(ctx, fileId, options);
|
|
36
|
+
return row === undefined ? null : toStoredFile(row);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export interface OpenFileOptions extends FileLookupOptions {
|
|
40
|
+
/** Only these bytes; `end` past the file is clipped to its last byte. */
|
|
41
|
+
readonly range?: ByteRange;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export interface OpenedFile {
|
|
45
|
+
readonly file: StoredFile;
|
|
46
|
+
readonly body: ReadableStream<Uint8Array>;
|
|
47
|
+
/** The bytes `body` carries; the whole file when no range was asked. */
|
|
48
|
+
readonly range: ByteRange | null;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export type OpenFileResult = Ok<OpenedFile> | Err<FilesLookupErrorCode>;
|
|
52
|
+
|
|
53
|
+
/** A live file's bytes as a stream. A row whose bytes are missing from storage reads as not found (and is logged). */
|
|
54
|
+
export async function openFile(ctx: FilesContext, fileId: string, options: OpenFileOptions = {}): Promise<OpenFileResult> {
|
|
55
|
+
const row = await findLiveRow(ctx, fileId, options);
|
|
56
|
+
if (row === undefined) return err("files.not_found");
|
|
57
|
+
const range = options.range === undefined ? null : clipRange(options.range, row.size);
|
|
58
|
+
if (range === false) return err("files.range_not_satisfiable");
|
|
59
|
+
const body = await getFilesOptions(ctx.config).storage.get(row.storageKey, range ?? undefined);
|
|
60
|
+
if (body === null) {
|
|
61
|
+
console.error(`@softure-ai/files: file ${row.id} has a row but no bytes in storage`);
|
|
62
|
+
return err("files.not_found");
|
|
63
|
+
}
|
|
64
|
+
return ok({ file: toStoredFile(row), body, range });
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** The range within a file of `size` bytes, or false when it starts past the end (or is malformed). */
|
|
68
|
+
export function clipRange(range: ByteRange, size: number): ByteRange | false {
|
|
69
|
+
const isValid = Number.isSafeInteger(range.start) && Number.isSafeInteger(range.end) && range.start >= 0 && range.end >= range.start;
|
|
70
|
+
if (!isValid || range.start >= size) return false;
|
|
71
|
+
return { start: range.start, end: Math.min(range.end, size - 1) };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
export interface ListFilesInput {
|
|
75
|
+
readonly ownerId: string;
|
|
76
|
+
readonly kind?: string;
|
|
77
|
+
/** At most this many, newest first; 100 by default, at most 1000. */
|
|
78
|
+
readonly limit?: number;
|
|
79
|
+
readonly offset?: number;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** An owner's live files, newest first. */
|
|
83
|
+
export async function listFiles(ctx: FilesContext, input: ListFilesInput): Promise<StoredFile[]> {
|
|
84
|
+
const limit = Math.min(Math.max(Math.trunc(input.limit ?? DEFAULT_LIST_LIMIT), 1), MAX_LIST_LIMIT);
|
|
85
|
+
const offset = Math.max(Math.trunc(input.offset ?? 0), 0);
|
|
86
|
+
const conditions: SQL[] = [eq(files.ownerId, input.ownerId), isLive(ctx.clock.now())];
|
|
87
|
+
if (input.kind !== undefined) conditions.push(eq(files.kind, input.kind));
|
|
88
|
+
const rows = await ctx.db
|
|
89
|
+
.select()
|
|
90
|
+
.from(files)
|
|
91
|
+
.where(and(...conditions))
|
|
92
|
+
.orderBy(desc(files.createdAt), desc(files.id))
|
|
93
|
+
.limit(limit)
|
|
94
|
+
.offset(offset);
|
|
95
|
+
return rows.map(toStoredFile);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** The bytes an owner keeps in live files, the figure the quota is checked against. */
|
|
99
|
+
export async function getOwnerUsage(ctx: FilesContext, ownerId: string): Promise<number> {
|
|
100
|
+
return sumOwnerBytes(ctx.db, ownerId, ctx.clock.now());
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
export type DeleteFileResult = Ok<undefined> | Err<"files.not_found">;
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Deletes a file: it stops being found and served at once, its bytes leave storage, then its row goes. When the
|
|
107
|
+
* storage delete fails the row stays marked deleted and `pruneFiles` finishes the job.
|
|
108
|
+
*/
|
|
109
|
+
export async function deleteFile(ctx: FilesContext, fileId: string, options: FileLookupOptions = {}): Promise<DeleteFileResult> {
|
|
110
|
+
if (!UUID_PATTERN.test(fileId)) return err("files.not_found");
|
|
111
|
+
const conditions: SQL[] = [eq(files.id, fileId), isNull(files.deletedAt)];
|
|
112
|
+
if (options.ownerId !== undefined) conditions.push(eq(files.ownerId, options.ownerId));
|
|
113
|
+
const [marked] = await ctx.db
|
|
114
|
+
.update(files)
|
|
115
|
+
.set({ deletedAt: ctx.clock.now() })
|
|
116
|
+
.where(and(...conditions))
|
|
117
|
+
.returning();
|
|
118
|
+
if (marked === undefined) return err("files.not_found");
|
|
119
|
+
await removeMarkedFile(ctx, marked);
|
|
120
|
+
return ok();
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** Removes a deleted or expired file's bytes and then its row; answers whether both went. */
|
|
124
|
+
export async function removeMarkedFile(ctx: FilesContext, row: FileRow): Promise<boolean> {
|
|
125
|
+
try {
|
|
126
|
+
await getFilesOptions(ctx.config).storage.delete(row.storageKey);
|
|
127
|
+
} catch (error) {
|
|
128
|
+
console.error(`@softure-ai/files: deleting the bytes of file ${row.id} failed, pruneFiles retries: ${errorLogLabel(error)}`);
|
|
129
|
+
return false;
|
|
130
|
+
}
|
|
131
|
+
await ctx.db.delete(files).where(eq(files.id, row.id));
|
|
132
|
+
return true;
|
|
133
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
// The module's readiness probe for `GET /api/health` of `@softure-ai/ops`: the table answers (`softure migrate`
|
|
2
|
+
// ran), and the storage takes a write and keeps at least `health.minFreeBytes` free when its driver can tell.
|
|
3
|
+
import { err, ok, type HealthCheck } from "@softure-ai/core";
|
|
4
|
+
import type { Queryable } from "@softure-ai/db";
|
|
5
|
+
import { sql } from "drizzle-orm";
|
|
6
|
+
import { getFilesOptions } from "./options.js";
|
|
7
|
+
|
|
8
|
+
export type FilesHealthErrorCode = "files.storage_unwritable" | "files.storage_low_space";
|
|
9
|
+
|
|
10
|
+
export const checkFilesHealth: HealthCheck = async (context) => {
|
|
11
|
+
// Core types `db` as unknown; the health route passes the @softure-ai/db handle.
|
|
12
|
+
const db = context.db as Queryable;
|
|
13
|
+
await db.execute(sql`select 1 from files.files limit 0`);
|
|
14
|
+
const options = getFilesOptions(context.config);
|
|
15
|
+
const check = await options.storage.check?.();
|
|
16
|
+
if (check === undefined) return ok();
|
|
17
|
+
if (!check.isWritable) return err("files.storage_unwritable");
|
|
18
|
+
if (check.freeBytes !== null && check.freeBytes < options.health.minFreeBytes) return err("files.storage_low_space");
|
|
19
|
+
return ok();
|
|
20
|
+
};
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
// Server-only API of @softure-ai/files. Every function receives the module context (`{ db, clock, config }`, plus
|
|
2
|
+
// an optional `env` for the link keyring) and never reads request scope.
|
|
3
|
+
export { getStorageKey, type Env, type FilesContext } from "./context.js";
|
|
4
|
+
export {
|
|
5
|
+
clipRange,
|
|
6
|
+
deleteFile,
|
|
7
|
+
findFile,
|
|
8
|
+
getOwnerUsage,
|
|
9
|
+
listFiles,
|
|
10
|
+
openFile,
|
|
11
|
+
type DeleteFileResult,
|
|
12
|
+
type FileLookupOptions,
|
|
13
|
+
type ListFilesInput,
|
|
14
|
+
type OpenedFile,
|
|
15
|
+
type OpenFileOptions,
|
|
16
|
+
type OpenFileResult,
|
|
17
|
+
} from "./files.js";
|
|
18
|
+
export { checkFilesHealth, type FilesHealthErrorCode } from "./health.js";
|
|
19
|
+
export { FILES_LINK_KEYS_ENV, generateFilesLinkKey, readLinkKeyring, type LinkKeyring, type LinkKeyringResult } from "./keys.js";
|
|
20
|
+
export {
|
|
21
|
+
createFileLink,
|
|
22
|
+
revokeFileLinks,
|
|
23
|
+
verifyFileLink,
|
|
24
|
+
type CreateFileLinkInput,
|
|
25
|
+
type CreateFileLinkResult,
|
|
26
|
+
type RevokeFileLinksResult,
|
|
27
|
+
type VerifiedLink,
|
|
28
|
+
type VerifyFileLinkResult,
|
|
29
|
+
} from "./links.js";
|
|
30
|
+
export { createLocalStorage, type LocalStorageOptions } from "./local-storage.js";
|
|
31
|
+
export { DEFAULT_CONTENT_TYPE, formatContentDisposition, normalizeContentType, sanitizeFileName } from "./names.js";
|
|
32
|
+
export { getFilesModule, getFilesOptions, getLinksRoute } from "./options.js";
|
|
33
|
+
export { deleteFilesUserData, exportFilesUserData, filesPrivacyContributor, type FilesDeletionReport, type FilesUserData } from "./privacy.js";
|
|
34
|
+
export { pruneFiles, type PruneFilesOptions, type PruneFilesReport } from "./prune.js";
|
|
35
|
+
export {
|
|
36
|
+
createS3Storage,
|
|
37
|
+
S3_ACCESS_KEY_ID_ENV,
|
|
38
|
+
S3_SECRET_ACCESS_KEY_ENV,
|
|
39
|
+
S3StorageError,
|
|
40
|
+
splitIntoParts,
|
|
41
|
+
type S3StorageOptions,
|
|
42
|
+
} from "./s3-storage.js";
|
|
43
|
+
export { saveFile, type SaveFileInput, type SaveFileResult } from "./save.js";
|
|
44
|
+
export { parseRangeHeader, serveFileLink } from "./serve.js";
|
|
45
|
+
export { EMPTY_PAYLOAD_SHA256, encodeRfc3986, signRequest, type SigV4Credentials, type SignRequestInput } from "./sigv4.js";
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
// The link signing keyring from `SOFTURE_FILES_LINK_KEYS` (`<id>:<base64 of 32 bytes>[,<id>:<key>…]`), the same
|
|
2
|
+
// format as `@softure-ai/connections`: the first key signs, every key verifies. A key is rotated by putting a new
|
|
3
|
+
// one first and dropping the old one after the longest link lifetime. Failures are codes; a key never reaches an
|
|
4
|
+
// error or a log.
|
|
5
|
+
import { randomBytes } from "node:crypto";
|
|
6
|
+
import { err, ok, type Err, type Ok } from "@softure-ai/core";
|
|
7
|
+
import type { Env } from "./context.js";
|
|
8
|
+
|
|
9
|
+
export const FILES_LINK_KEYS_ENV = "SOFTURE_FILES_LINK_KEYS";
|
|
10
|
+
|
|
11
|
+
const KEY_ID_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
|
|
12
|
+
const KEY_BYTES = 32;
|
|
13
|
+
|
|
14
|
+
/** The keys, the signing one first. */
|
|
15
|
+
export interface LinkKeyring {
|
|
16
|
+
readonly current: Buffer;
|
|
17
|
+
readonly keys: readonly Buffer[];
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export type LinkKeyringResult = Ok<LinkKeyring> | Err<"files.link_key_missing" | "files.link_key_invalid">;
|
|
21
|
+
|
|
22
|
+
/** Parses the keyring from the environment. Never echoes the value it read. */
|
|
23
|
+
export function readLinkKeyring(env: Env = process.env): LinkKeyringResult {
|
|
24
|
+
const raw = env[FILES_LINK_KEYS_ENV]?.trim();
|
|
25
|
+
if (raw === undefined || raw === "") return err("files.link_key_missing");
|
|
26
|
+
const ids = new Set<string>();
|
|
27
|
+
const keys: Buffer[] = [];
|
|
28
|
+
for (const entry of raw.split(",")) {
|
|
29
|
+
const parsed = parseKeyEntry(entry.trim());
|
|
30
|
+
if (parsed === null || ids.has(parsed.id)) return err("files.link_key_invalid");
|
|
31
|
+
ids.add(parsed.id);
|
|
32
|
+
keys.push(parsed.key);
|
|
33
|
+
}
|
|
34
|
+
const [current] = keys;
|
|
35
|
+
// The split always yields one entry, so a parsed list has a current key.
|
|
36
|
+
return current === undefined ? err("files.link_key_invalid") : ok({ current, keys });
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function parseKeyEntry(entry: string): { id: string; key: Buffer } | null {
|
|
40
|
+
const separator = entry.indexOf(":");
|
|
41
|
+
if (separator <= 0) return null;
|
|
42
|
+
const id = entry.slice(0, separator);
|
|
43
|
+
const encoded = entry.slice(separator + 1);
|
|
44
|
+
if (!KEY_ID_PATTERN.test(id) || !/^[A-Za-z0-9+/_-]+={0,2}$/.test(encoded)) return null;
|
|
45
|
+
// Node's base64 decoder takes both alphabets, standard and URL-safe.
|
|
46
|
+
const key = Buffer.from(encoded, "base64");
|
|
47
|
+
return key.length === KEY_BYTES ? { id, key } : null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** A new keyring entry, `<id>:<base64url of 32 random bytes>`, for `SOFTURE_FILES_LINK_KEYS`. */
|
|
51
|
+
export function generateFilesLinkKey(id: string = new Date().toISOString().slice(0, 10).replaceAll("-", "")): string {
|
|
52
|
+
if (!KEY_ID_PATTERN.test(id)) {
|
|
53
|
+
throw new RangeError("generateFilesLinkKey: the id must be 1 to 32 letters, digits, _ or -");
|
|
54
|
+
}
|
|
55
|
+
return `${id}:${randomBytes(KEY_BYTES).toString("base64url")}`;
|
|
56
|
+
}
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
// Public links: `<route>/<id>/<expiry>/<generation>.<mac>/<name>`, where `expiry` is a Unix time in seconds,
|
|
2
|
+
// `generation` the file's link generation when the link was made and `mac` an HMAC-SHA256 (base64url) over all four
|
|
3
|
+
// parts under the keyring's first key. The MAC and the expiry are checked before any database read, so a forged or
|
|
4
|
+
// stale link costs no query; the generation is then compared with the row, so `revokeFileLinks` (which bumps it)
|
|
5
|
+
// kills every link made before.
|
|
6
|
+
import { createHmac, timingSafeEqual } from "node:crypto";
|
|
7
|
+
import { err, ok, type Err, type Ok } from "@softure-ai/core";
|
|
8
|
+
import { and, eq, isNull, sql, type SQL } from "drizzle-orm";
|
|
9
|
+
import type { FileLink, FilesKeyErrorCode } from "../contract.js";
|
|
10
|
+
import { files } from "../schema.js";
|
|
11
|
+
import type { FilesContext } from "./context.js";
|
|
12
|
+
import { findLiveRow, UUID_PATTERN, type FileLookupOptions } from "./files.js";
|
|
13
|
+
import { readLinkKeyring, type LinkKeyring } from "./keys.js";
|
|
14
|
+
import { sanitizeFileName } from "./names.js";
|
|
15
|
+
import { getFilesOptions, getLinksRoute } from "./options.js";
|
|
16
|
+
|
|
17
|
+
const MAC_CONTEXT = "softure-files-link/v1";
|
|
18
|
+
const MAC_PATTERN = /^[A-Za-z0-9_-]{43}$/;
|
|
19
|
+
const EXPIRY_PATTERN = /^[1-9]\d{0,11}$/;
|
|
20
|
+
const GENERATION_PATTERN = /^[1-9]\d{0,9}$/;
|
|
21
|
+
|
|
22
|
+
export interface CreateFileLinkInput extends FileLookupOptions {
|
|
23
|
+
/** How long the link works, at most `links.maxTtlSeconds`; a file that expires sooner ends the link with it. */
|
|
24
|
+
readonly ttlSeconds: number;
|
|
25
|
+
/** The name the receiver sees; the file's own name when omitted. Sanitised like a saved name. */
|
|
26
|
+
readonly downloadName?: string;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export type CreateFileLinkResult = Ok<FileLink> | Err<"files.not_found" | "files.invalid_input" | FilesKeyErrorCode>;
|
|
30
|
+
|
|
31
|
+
/** A signed public link to a live file. */
|
|
32
|
+
export async function createFileLink(ctx: FilesContext, fileId: string, input: CreateFileLinkInput): Promise<CreateFileLinkResult> {
|
|
33
|
+
const options = getFilesOptions(ctx.config);
|
|
34
|
+
if (!Number.isSafeInteger(input.ttlSeconds) || input.ttlSeconds < 1 || input.ttlSeconds > options.links.maxTtlSeconds) {
|
|
35
|
+
return err("files.invalid_input");
|
|
36
|
+
}
|
|
37
|
+
const keyring = readLinkKeyring(ctx.env ?? process.env);
|
|
38
|
+
if (!keyring.ok) return keyring;
|
|
39
|
+
const row = await findLiveRow(ctx, fileId, input);
|
|
40
|
+
if (row === undefined) return err("files.not_found");
|
|
41
|
+
|
|
42
|
+
const nowSeconds = Math.floor(ctx.clock.now().getTime() / 1000);
|
|
43
|
+
const fileEndSeconds = row.expiresAt === null ? Infinity : Math.floor(row.expiresAt.getTime() / 1000);
|
|
44
|
+
const expiry = Math.min(nowSeconds + input.ttlSeconds, fileEndSeconds);
|
|
45
|
+
const name = input.downloadName === undefined ? row.originalName : sanitizeFileName(input.downloadName);
|
|
46
|
+
const generation = String(row.linkGeneration);
|
|
47
|
+
const mac = signLink(keyring.value.current, {
|
|
48
|
+
fileId: row.id,
|
|
49
|
+
expiry: String(expiry),
|
|
50
|
+
generation,
|
|
51
|
+
name,
|
|
52
|
+
});
|
|
53
|
+
const path = `${getLinksRoute(ctx.config)}/${row.id}/${String(expiry)}/${generation}.${mac}/${encodeURIComponent(name)}`;
|
|
54
|
+
return ok({
|
|
55
|
+
url: new URL(path, ctx.config.appOrigin).toString(),
|
|
56
|
+
path,
|
|
57
|
+
expiresAt: new Date(expiry * 1000),
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export type RevokeFileLinksResult = Ok<undefined> | Err<"files.not_found">;
|
|
62
|
+
|
|
63
|
+
/** Stops every link made so far for a file; links made afterwards work. */
|
|
64
|
+
export async function revokeFileLinks(ctx: FilesContext, fileId: string, options: FileLookupOptions = {}): Promise<RevokeFileLinksResult> {
|
|
65
|
+
if (!UUID_PATTERN.test(fileId)) return err("files.not_found");
|
|
66
|
+
const conditions: SQL[] = [eq(files.id, fileId), isNull(files.deletedAt)];
|
|
67
|
+
if (options.ownerId !== undefined) conditions.push(eq(files.ownerId, options.ownerId));
|
|
68
|
+
const updated = await ctx.db
|
|
69
|
+
.update(files)
|
|
70
|
+
.set({ linkGeneration: sql`${files.linkGeneration} + 1` })
|
|
71
|
+
.where(and(...conditions))
|
|
72
|
+
.returning({ id: files.id });
|
|
73
|
+
return updated.length === 0 ? err("files.not_found") : ok();
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** What a link's path says, once its MAC and expiry are checked. */
|
|
77
|
+
export interface VerifiedLink {
|
|
78
|
+
readonly fileId: string;
|
|
79
|
+
readonly expiresAt: Date;
|
|
80
|
+
readonly generation: number;
|
|
81
|
+
readonly name: string;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export type VerifyFileLinkResult = Ok<VerifiedLink> | Err<"files.not_found" | FilesKeyErrorCode>;
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Checks a link path (the request's pathname) without touching the database: its shape, its MAC under any key of
|
|
88
|
+
* the keyring, and that it has not expired. Every refusal of the link itself is `files.not_found`.
|
|
89
|
+
*/
|
|
90
|
+
export function verifyFileLink(ctx: Pick<FilesContext, "clock" | "config" | "env">, pathname: string): VerifyFileLinkResult {
|
|
91
|
+
const parts = splitLinkPath(getLinksRoute(ctx.config), pathname);
|
|
92
|
+
if (parts === null) return err("files.not_found");
|
|
93
|
+
const keyring = readLinkKeyring(ctx.env ?? process.env);
|
|
94
|
+
if (!keyring.ok) return keyring;
|
|
95
|
+
if (!hasValidMac(keyring.value, parts)) return err("files.not_found");
|
|
96
|
+
const expiresAt = new Date(Number(parts.expiry) * 1000);
|
|
97
|
+
if (expiresAt.getTime() <= ctx.clock.now().getTime()) return err("files.not_found");
|
|
98
|
+
return ok({
|
|
99
|
+
fileId: parts.fileId,
|
|
100
|
+
expiresAt,
|
|
101
|
+
generation: Number(parts.generation),
|
|
102
|
+
name: parts.name,
|
|
103
|
+
});
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
interface LinkParts {
|
|
107
|
+
readonly fileId: string;
|
|
108
|
+
readonly expiry: string;
|
|
109
|
+
readonly generation: string;
|
|
110
|
+
readonly name: string;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
interface SplitLink extends LinkParts {
|
|
114
|
+
readonly mac: string;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function splitLinkPath(route: string, pathname: string): SplitLink | null {
|
|
118
|
+
if (!pathname.startsWith(`${route}/`)) return null;
|
|
119
|
+
const segments = pathname.slice(route.length + 1).split("/");
|
|
120
|
+
if (segments.length !== 4) return null;
|
|
121
|
+
const [fileId = "", expiry = "", signature = "", encodedName = ""] = segments;
|
|
122
|
+
const [generation = "", mac = "", extra] = signature.split(".");
|
|
123
|
+
const isWellFormed =
|
|
124
|
+
UUID_PATTERN.test(fileId) && EXPIRY_PATTERN.test(expiry) && GENERATION_PATTERN.test(generation) && MAC_PATTERN.test(mac) && extra === undefined;
|
|
125
|
+
if (!isWellFormed || encodedName === "") return null;
|
|
126
|
+
try {
|
|
127
|
+
return {
|
|
128
|
+
fileId,
|
|
129
|
+
expiry,
|
|
130
|
+
generation,
|
|
131
|
+
mac,
|
|
132
|
+
name: decodeURIComponent(encodedName),
|
|
133
|
+
};
|
|
134
|
+
} catch {
|
|
135
|
+
// A malformed percent escape: not a link this module made.
|
|
136
|
+
return null;
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
function signLink(key: Buffer, parts: LinkParts): string {
|
|
141
|
+
return createHmac("sha256", key).update([MAC_CONTEXT, parts.fileId, parts.expiry, parts.generation, parts.name].join("\n")).digest("base64url");
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function hasValidMac(keyring: LinkKeyring, parts: SplitLink): boolean {
|
|
145
|
+
// Compared as text: a base64url MAC has spare bits, so decoded bytes would accept a few spellings of one MAC.
|
|
146
|
+
const given = Buffer.from(parts.mac, "ascii");
|
|
147
|
+
// Every key is tried, so the time taken does not tell which one matched.
|
|
148
|
+
return keyring.keys.reduce((isMatch, key) => {
|
|
149
|
+
const expected = Buffer.from(signLink(key, parts), "ascii");
|
|
150
|
+
return timingSafeEqual(expected, given) || isMatch;
|
|
151
|
+
}, false);
|
|
152
|
+
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
// The local disk driver: one folder (a Docker volume on a one-VPS app), objects at `<dir>/<key>`. A write goes to
|
|
2
|
+
// a partial file next to its target and is renamed into place once complete, so a reader never sees half a file and
|
|
3
|
+
// a failed write leaves nothing. Creating the driver touches nothing; the folder is made on the first write.
|
|
4
|
+
import { randomUUID } from "node:crypto";
|
|
5
|
+
import { createReadStream, createWriteStream } from "node:fs";
|
|
6
|
+
import { mkdir, rename, rm, stat, statfs, writeFile } from "node:fs/promises";
|
|
7
|
+
import { dirname, join, resolve } from "node:path";
|
|
8
|
+
import { Readable } from "node:stream";
|
|
9
|
+
import { pipeline } from "node:stream/promises";
|
|
10
|
+
import type { ByteRange } from "../contract.js";
|
|
11
|
+
import type { FileBody, FileStorage, StorageCheck } from "../storage.js";
|
|
12
|
+
|
|
13
|
+
const KEY_PATTERN = /^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)*$/;
|
|
14
|
+
const PROBE_DIR = ".health";
|
|
15
|
+
const PARTIAL_SUFFIX = ".partial";
|
|
16
|
+
|
|
17
|
+
export interface LocalStorageOptions {
|
|
18
|
+
/** The folder the files live in, absolute or relative to the working directory (e.g. `/data/files`). */
|
|
19
|
+
readonly dir: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function createLocalStorage(options: LocalStorageOptions): FileStorage {
|
|
23
|
+
const root = resolve(options.dir);
|
|
24
|
+
|
|
25
|
+
function getPath(key: string): string {
|
|
26
|
+
// Keys come from file ids; anything else is a bug, and must never reach the disk as a path.
|
|
27
|
+
if (!KEY_PATTERN.test(key)) throw new RangeError("@softure-ai/files: a storage key must be lowercase letters, digits, - and /");
|
|
28
|
+
return join(root, key);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
return {
|
|
32
|
+
kind: "local",
|
|
33
|
+
async put(body: FileBody, key: string) {
|
|
34
|
+
const target = getPath(key);
|
|
35
|
+
const partial = `${target}.${randomUUID()}${PARTIAL_SUFFIX}`;
|
|
36
|
+
await mkdir(dirname(target), { recursive: true });
|
|
37
|
+
try {
|
|
38
|
+
await pipeline(Readable.from(body), createWriteStream(partial, { flags: "wx" }));
|
|
39
|
+
await rename(partial, target);
|
|
40
|
+
} catch (error) {
|
|
41
|
+
await rm(partial, { force: true });
|
|
42
|
+
throw error;
|
|
43
|
+
}
|
|
44
|
+
},
|
|
45
|
+
async get(key: string, range?: ByteRange) {
|
|
46
|
+
const path = getPath(key);
|
|
47
|
+
if ((await statOrNull(path)) === null) return null;
|
|
48
|
+
const stream = createReadStream(path, range === undefined ? {} : { start: range.start, end: range.end });
|
|
49
|
+
// Node's web stream type is structurally the DOM one; the cast bridges the two declarations.
|
|
50
|
+
return Readable.toWeb(stream) as unknown as ReadableStream<Uint8Array>;
|
|
51
|
+
},
|
|
52
|
+
async head(key: string) {
|
|
53
|
+
const stats = await statOrNull(getPath(key));
|
|
54
|
+
return stats === null ? null : { size: stats.size };
|
|
55
|
+
},
|
|
56
|
+
async delete(key: string) {
|
|
57
|
+
await rm(getPath(key), { force: true });
|
|
58
|
+
},
|
|
59
|
+
async check(): Promise<StorageCheck> {
|
|
60
|
+
const probe = join(root, PROBE_DIR, `${randomUUID()}.probe`);
|
|
61
|
+
let isWritable = true;
|
|
62
|
+
try {
|
|
63
|
+
await mkdir(dirname(probe), { recursive: true });
|
|
64
|
+
await writeFile(probe, "ok");
|
|
65
|
+
await rm(probe, { force: true });
|
|
66
|
+
} catch {
|
|
67
|
+
isWritable = false;
|
|
68
|
+
}
|
|
69
|
+
try {
|
|
70
|
+
const stats = await statfs(root);
|
|
71
|
+
return { isWritable, freeBytes: stats.bavail * stats.bsize };
|
|
72
|
+
} catch {
|
|
73
|
+
return { isWritable, freeBytes: null };
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
async function statOrNull(path: string) {
|
|
80
|
+
try {
|
|
81
|
+
const stats = await stat(path);
|
|
82
|
+
return stats.isFile() ? stats : null;
|
|
83
|
+
} catch (error) {
|
|
84
|
+
if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
|
|
85
|
+
throw error;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
// Names and media types that come from users, made safe to store and to send back in a header or a URL.
|
|
2
|
+
|
|
3
|
+
const MAX_NAME_LENGTH = 255;
|
|
4
|
+
const FALLBACK_NAME = "file";
|
|
5
|
+
/** `type/subtype` with optional parameters, as the table's check allows. */
|
|
6
|
+
const CONTENT_TYPE_PATTERN = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*(;[ -~]*)?$/;
|
|
7
|
+
export const DEFAULT_CONTENT_TYPE = "application/octet-stream";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* The last path part of `name` without control characters, slashes or backslashes, trimmed and at most 255
|
|
11
|
+
* characters (by code point); `file` when nothing is left.
|
|
12
|
+
*/
|
|
13
|
+
export function sanitizeFileName(name: string): string {
|
|
14
|
+
const base = name.split(/[/\\]/).at(-1) ?? "";
|
|
15
|
+
// eslint-disable-next-line no-control-regex -- control characters are exactly what the name must not carry
|
|
16
|
+
const cleaned = base.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").trim();
|
|
17
|
+
const clipped = [...cleaned].slice(0, MAX_NAME_LENGTH).join("").trim();
|
|
18
|
+
return clipped === "" || clipped === "." || clipped === ".." ? FALLBACK_NAME : clipped;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** The media type with its type and subtype lowercased, or null when it is not one the table accepts. */
|
|
22
|
+
export function normalizeContentType(contentType: string): string | null {
|
|
23
|
+
const trimmed = contentType.trim();
|
|
24
|
+
const separator = trimmed.indexOf(";");
|
|
25
|
+
const essence = (separator === -1 ? trimmed : trimmed.slice(0, separator)).trim().toLowerCase();
|
|
26
|
+
const normalized = separator === -1 ? essence : `${essence}${trimmed.slice(separator)}`;
|
|
27
|
+
return normalized.length <= 255 && CONTENT_TYPE_PATTERN.test(normalized) ? normalized : null;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** A `Content-Disposition` value with an ASCII fallback name and the UTF-8 name (RFC 6266, RFC 8187). */
|
|
31
|
+
export function formatContentDisposition(disposition: "attachment" | "inline", name: string): string {
|
|
32
|
+
const fallback = name.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_");
|
|
33
|
+
const encoded = encodeURIComponent(name).replace(/['()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
|
|
34
|
+
return `${disposition}; filename="${fallback}"; filename*=UTF-8''${encoded}`;
|
|
35
|
+
}
|