@sigil-dev/storage 0.0.0-stage → 0.9.31

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/README.md CHANGED
@@ -1,3 +1,25 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # @sigil-dev/storage
2
+
3
+ File uploads for a Grimoire app, in S3 or anything that speaks it (SeaweedFS, MinIO, Cloudflare R2, Backblaze B2), or on disk. Bun's own S3 client, so nothing to install.
4
+
5
+ ```sh
6
+ sigil add storage
7
+ ```
8
+
9
+ ```ts
10
+ // sigil.config.ts
11
+ plugins: [storage()] // s3() when S3_BUCKET is set, disk() in development
12
+
13
+ // an action
14
+ const result = await locals.storage.upload(form.get("avatar"), { prefix: "avatars", types: ["image/*"], maxSize: "5mb" });
15
+ if (!result.ok) return fail(400, { error: result.error });
16
+ await db.users.update(user.id, { avatar: result.file.key });
17
+
18
+ // later
19
+ locals.storage.url(key); // public stores
20
+ await locals.storage.signedUrl(key, "10m"); // private ones
21
+ ```
22
+
23
+ A file's type is read from its bytes, not from what the browser claims, so an HTML page named cat.png is not an image. `image/*` never lets SVG in. Disk stores send anything a browser could run as a download.
24
+
25
+ Docs: https://sigil.cane1712.dev/docs/reference/storage
package/disk.ts ADDED
@@ -0,0 +1,156 @@
1
+ import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
2
+ import { mkdir, rm, stat } from "node:fs/promises";
3
+ import { dirname, isAbsolute, join } from "node:path";
4
+ import { checkKey, type Store } from "./store.ts";
5
+
6
+ export interface DiskOptions {
7
+ /** Where files go, from the project root. Default `storage`; keep it out of git. */
8
+ dir?: string;
9
+ /** Serve every file publicly under this path, e.g. `/files`. Default: private. */
10
+ url?: string;
11
+ /**
12
+ * Signs private links. Default `STORAGE_SECRET`, or a random one per
13
+ * process in development (links then stop working on restart).
14
+ */
15
+ secret?: string;
16
+ }
17
+
18
+ /** Types a browser may show inline. Anything else is sent as a download, so an uploaded .html cannot run on your origin. */
19
+ const INLINE =
20
+ /^(image\/(png|jpeg|gif|webp|avif)|application\/pdf|video\/(mp4|webm)|audio\/(mpeg|ogg|wav))$/;
21
+
22
+ const SIGNED = "/__storage/";
23
+
24
+ /**
25
+ * Files on this machine's disk. For development, and for a single server
26
+ * with a volume; with several machines, use s3().
27
+ */
28
+ export function disk(
29
+ options: DiskOptions = {},
30
+ ): Store & { handle(request: Request): Promise<Response | null> } {
31
+ const root = () => {
32
+ const dir = options.dir ?? "storage";
33
+ return isAbsolute(dir) ? dir : join(process.cwd(), dir);
34
+ };
35
+ const path = (key: string) => join(root(), checkKey(key));
36
+ const publicPath = options.url?.replace(/\/$/, "");
37
+ let devSecret: string | undefined;
38
+ const secret = () => {
39
+ const s = options.secret ?? process.env.STORAGE_SECRET;
40
+ if (s) return s;
41
+ if (process.env.NODE_ENV === "production") {
42
+ throw new Error(
43
+ "storage: private disk links are signed with STORAGE_SECRET, which is not set",
44
+ );
45
+ }
46
+ devSecret ??= randomBytes(32).toString("hex");
47
+ return devSecret;
48
+ };
49
+ const sign = (key: string, expires: number, download: string) =>
50
+ createHmac("sha256", secret())
51
+ .update(`${key}\n${expires}\n${download}`)
52
+ .digest("base64url");
53
+
54
+ const serve = async (key: string, download?: string) => {
55
+ const file = Bun.file(path(key));
56
+ if (!(await file.exists()))
57
+ return new Response("Not Found", { status: 404 });
58
+ const type = file.type.split(";")[0]!;
59
+ const headers: Record<string, string> = {
60
+ "content-type": INLINE.test(type)
61
+ ? file.type
62
+ : "application/octet-stream",
63
+ "x-content-type-options": "nosniff",
64
+ };
65
+ if (download || !INLINE.test(type)) {
66
+ const name = (download || key.split("/").at(-1)!).replace(
67
+ /["\\\r\n]/g,
68
+ "",
69
+ );
70
+ headers["content-disposition"] = `attachment; filename="${name}"`;
71
+ }
72
+ return new Response(file, { headers });
73
+ };
74
+
75
+ return {
76
+ kind: "disk",
77
+ async open() {
78
+ await mkdir(root(), { recursive: true });
79
+ if (!publicPath) secret();
80
+ },
81
+ async put(key, data, type) {
82
+ const p = path(key);
83
+ await mkdir(dirname(p), { recursive: true });
84
+ await Bun.write(
85
+ p,
86
+ typeof data === "string" ? new Blob([data], { type }) : data,
87
+ );
88
+ },
89
+ async get(key) {
90
+ const file = Bun.file(path(key));
91
+ return (await file.exists()) ? file : null;
92
+ },
93
+ async delete(key) {
94
+ const p = path(key);
95
+ const had = await stat(p).then(
96
+ () => true,
97
+ () => false,
98
+ );
99
+ await rm(p, { force: true });
100
+ return had;
101
+ },
102
+ exists: (key) => Bun.file(path(key)).exists(),
103
+ ...(publicPath
104
+ ? { url: (key: string) => `${publicPath}/${checkKey(key)}` }
105
+ : {}),
106
+ async signedUrl(key, seconds, { download }) {
107
+ const expires =
108
+ Math.floor(Date.now() / 1000) + Math.max(1, Math.round(seconds));
109
+ const q = new URLSearchParams({
110
+ expires: String(expires),
111
+ sig: sign(checkKey(key), expires, download ?? ""),
112
+ });
113
+ if (download) q.set("download", download);
114
+ return `${SIGNED}${key}?${q}`;
115
+ },
116
+ /** Answers the public path and signed links; anything else is not its business. */
117
+ async handle(request) {
118
+ if (request.method !== "GET" && request.method !== "HEAD") return null;
119
+ const url = new URL(request.url);
120
+ let pathname: string;
121
+ try {
122
+ pathname = decodeURIComponent(url.pathname);
123
+ } catch {
124
+ return null;
125
+ }
126
+ if (publicPath && pathname.startsWith(`${publicPath}/`)) {
127
+ const key = pathname.slice(publicPath.length + 1);
128
+ try {
129
+ checkKey(key);
130
+ } catch {
131
+ return new Response("Not Found", { status: 404 });
132
+ }
133
+ return serve(key);
134
+ }
135
+ if (!pathname.startsWith(SIGNED)) return null;
136
+ const key = pathname.slice(SIGNED.length);
137
+ const expires = Number(url.searchParams.get("expires"));
138
+ const download = url.searchParams.get("download") ?? "";
139
+ const given = Buffer.from(url.searchParams.get("sig") ?? "");
140
+ let valid = false;
141
+ try {
142
+ const wanted = Buffer.from(sign(checkKey(key), expires, download));
143
+ valid =
144
+ given.length === wanted.length && timingSafeEqual(given, wanted);
145
+ } catch {
146
+ valid = false;
147
+ }
148
+ if (!valid || !(expires * 1000 > Date.now())) {
149
+ return new Response("This link has expired or is not valid", {
150
+ status: 403,
151
+ });
152
+ }
153
+ return serve(key, download || undefined);
154
+ },
155
+ };
156
+ }
package/index.ts ADDED
@@ -0,0 +1,213 @@
1
+ import { type Duration, type GrimoirePlugin, ms } from "@sigil-dev/grimoire";
2
+ import { tmpdir } from "node:os";
3
+ import { join } from "node:path";
4
+ import { disk } from "./disk.ts";
5
+ import { s3 } from "./s3.ts";
6
+ import { allowed, extOf, sniff } from "./sniff.ts";
7
+ import { bytes, checkKey, type Store } from "./store.ts";
8
+
9
+ export { type DiskOptions, disk } from "./disk.ts";
10
+ export { type S3StoreOptions, s3 } from "./s3.ts";
11
+ export { allowed, sniff } from "./sniff.ts";
12
+ export { bytes, checkKey, type Store } from "./store.ts";
13
+
14
+ /** A file once stored. Keep `key` in your table; the rest can be worked out from it. */
15
+ export interface StoredFile {
16
+ key: string;
17
+ size: number;
18
+ type: string;
19
+ /** The name it was uploaded with. Shown to people, never used as a path. */
20
+ name: string;
21
+ /** Where anyone can fetch it, when the store is public. */
22
+ url?: string;
23
+ }
24
+
25
+ export interface UploadOptions {
26
+ /** Largest accepted. Default "10mb". */
27
+ maxSize?: number | string;
28
+ /** What is accepted, by type: `["image/*", "application/pdf"]`. Default: anything. */
29
+ types?: readonly string[];
30
+ /** Put under this folder: `avatars`. */
31
+ prefix?: string;
32
+ /** The exact key, instead of a new random one: replaces what is there. */
33
+ key?: string;
34
+ }
35
+
36
+ export type UploadResult =
37
+ | { ok: true; file: StoredFile }
38
+ | { ok: false; error: string };
39
+
40
+ export interface Storage {
41
+ /**
42
+ * Checks an uploaded file (size, and type by its bytes, not its claim),
43
+ * stores it under a new random key, and says where. A mistake by the
44
+ * visitor is `{ ok: false, error }`, ready for a form.
45
+ */
46
+ upload(file: unknown, options?: UploadOptions): Promise<UploadResult>;
47
+ /** Stores data under `key` as is, with no checks: for files your code made. */
48
+ put(
49
+ key: string,
50
+ data: Blob | ArrayBuffer | Uint8Array | string,
51
+ options?: { type?: string },
52
+ ): Promise<StoredFile>;
53
+ /** The file, or null: `new Response(file)` streams it. */
54
+ get(key: string): Promise<Blob | null>;
55
+ delete(key: string): Promise<boolean>;
56
+ exists(key: string): Promise<boolean>;
57
+ /** The public address, or undefined when the store is private. */
58
+ url(key: string): string | undefined;
59
+ /** An address that works for a while, for a private file. `download` saves it under that name. */
60
+ signedUrl(
61
+ key: string,
62
+ expires: Duration,
63
+ options?: { download?: string },
64
+ ): Promise<string>;
65
+ readonly store: Store;
66
+ }
67
+
68
+ export type StoragePlugin = GrimoirePlugin<{ storage: Storage }> & Storage;
69
+
70
+ let current: Storage | undefined;
71
+
72
+ /** The app's storage, for code without `locals`: a job, a script. */
73
+ export function useStorage(): Storage {
74
+ if (!current)
75
+ throw new Error(
76
+ "storage: no storage plugin. Add one in sigil.config.ts: plugins: [storage()].",
77
+ );
78
+ return current;
79
+ }
80
+
81
+ /**
82
+ * Files for the app: `storage()` in sigil.config.ts, `locals.storage` in a
83
+ * route. Without a store it uses s3() when S3_BUCKET is set and disk() in
84
+ * development; in production with neither, it refuses to start. Under
85
+ * createTestApp it keeps files in a temporary folder, whatever was configured.
86
+ */
87
+ export function storage(store?: Store): StoragePlugin {
88
+ let resolved = store;
89
+ let testing = false;
90
+ let dev = process.env.NODE_ENV !== "production";
91
+ const target = (): Store => {
92
+ if (resolved) return resolved;
93
+ if (testing) {
94
+ // under createTestApp: a folder of this process's own, never the real bucket
95
+ resolved = disk({
96
+ dir: join(tmpdir(), `sigil-storage-test-${process.pid}`),
97
+ secret: "test",
98
+ });
99
+ } else if (process.env.S3_BUCKET) resolved = s3();
100
+ else if (dev) resolved = disk();
101
+ else {
102
+ throw new Error(
103
+ "storage: nowhere to keep files. Set S3_BUCKET (and S3_ENDPOINT for SeaweedFS, MinIO or R2), or pass a store: storage(disk({ dir: '/data' })).",
104
+ );
105
+ }
106
+ return resolved;
107
+ };
108
+ const describe = (
109
+ key: string,
110
+ size: number,
111
+ type: string,
112
+ name: string,
113
+ ): StoredFile => {
114
+ const url = target().url?.(key);
115
+ return { key, size, type, name, ...(url ? { url } : {}) };
116
+ };
117
+
118
+ const methods: Omit<Storage, "store"> = {
119
+ async upload(file, options = {}) {
120
+ if (!(file instanceof Blob) || file.size === 0)
121
+ return { ok: false, error: "Choose a file" };
122
+ const max = bytes(options.maxSize ?? "10mb");
123
+ if (file.size > max) {
124
+ return {
125
+ ok: false,
126
+ error: `The file is larger than ${Math.round(max / 1024 / 1024) || 1} MB`,
127
+ };
128
+ }
129
+ const name = file instanceof File && file.name ? file.name : "file";
130
+ const found = await sniff(file);
131
+ const claimed = file.type.split(";")[0]!.trim().toLowerCase();
132
+ // what the bytes say wins over what the browser said
133
+ const type = found?.type ?? (claimed || "application/octet-stream");
134
+ if (options.types) {
135
+ // a type nothing could confirm passes only when listed by name
136
+ const ok = found
137
+ ? allowed(type, options.types)
138
+ : options.types.includes(type);
139
+ if (!ok)
140
+ return { ok: false, error: "That kind of file is not accepted here" };
141
+ }
142
+ const ext = found?.ext ?? extOf(name);
143
+ const key = options.key
144
+ ? checkKey(options.key)
145
+ : `${options.prefix ? `${checkKey(options.prefix)}/` : ""}${crypto.randomUUID()}.${ext}`;
146
+ await target().put(key, file, type);
147
+ return { ok: true, file: describe(key, file.size, type, name) };
148
+ },
149
+ async put(key, data, options = {}) {
150
+ checkKey(key);
151
+ const type =
152
+ options.type ??
153
+ (data instanceof Blob && data.type
154
+ ? data.type
155
+ : "application/octet-stream");
156
+ await target().put(key, data, type);
157
+ const size =
158
+ typeof data === "string"
159
+ ? Buffer.byteLength(data)
160
+ : data instanceof Blob
161
+ ? data.size
162
+ : data.byteLength;
163
+ return describe(key, size, type, key.split("/").at(-1)!);
164
+ },
165
+ get: (key) => target().get(checkKey(key)),
166
+ delete: (key) => target().delete(checkKey(key)),
167
+ exists: (key) => target().exists(checkKey(key)),
168
+ url: (key) => target().url?.(checkKey(key)),
169
+ async signedUrl(key, expires, options = {}) {
170
+ const t = target();
171
+ if (!t.signedUrl)
172
+ throw new Error(`storage: the ${t.kind} store cannot sign links`);
173
+ return t.signedUrl(checkKey(key), ms(expires, "storage") / 1000, options);
174
+ },
175
+ };
176
+ // `store` is a getter, defined rather than spread: spreading would pick a
177
+ // store while the config loads, and `sigil build` needs none.
178
+ const withStore = <O extends object>(o: O) =>
179
+ Object.defineProperty(o, "store", {
180
+ get: target,
181
+ enumerable: false,
182
+ }) as O & { readonly store: Store };
183
+ const api: Storage = withStore({ ...methods });
184
+
185
+ const plugin = withStore({
186
+ name: "storage",
187
+ ...methods,
188
+ ...(store?.requiredEnv?.length
189
+ ? { requiredEnv: [...store.requiredEnv] }
190
+ : {}),
191
+ config(config: { dev?: boolean; test?: boolean }) {
192
+ dev = config.dev ?? dev;
193
+ if (config.test) {
194
+ testing = true;
195
+ resolved = undefined;
196
+ }
197
+ return config;
198
+ },
199
+ async services() {
200
+ await target().open?.();
201
+ return { storage: api };
202
+ },
203
+ /** A disk store serves its public path and its signed links itself. */
204
+ async onRequest(request: Request, next: () => Promise<Response>) {
205
+ const t = target() as Store & {
206
+ handle?: (r: Request) => Promise<Response | null>;
207
+ };
208
+ return (await t.handle?.(request)) ?? next();
209
+ },
210
+ }) as unknown as StoragePlugin;
211
+ current = api;
212
+ return plugin;
213
+ }
package/package.json CHANGED
@@ -1,6 +1,33 @@
1
1
  {
2
2
  "name": "@sigil-dev/storage",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "description": "File uploads for Grimoire: S3 (or SeaweedFS, MinIO, R2) and disk, with type checks by content and signed links",
4
+ "license": "MIT",
5
+ "homepage": "https://sigil.cane1712.dev/docs/reference/storage",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://git.cane1712.dev/sigil/sigil.git",
9
+ "directory": "packages/storage"
10
+ },
11
+ "module": "index.ts",
12
+ "type": "module",
13
+ "private": false,
14
+ "version": "0.9.31",
15
+ "keywords": [
16
+ "grimoire",
17
+ "sigil",
18
+ "uploads",
19
+ "storage",
20
+ "s3"
21
+ ],
22
+ "files": [
23
+ "*.ts",
24
+ "README.md"
25
+ ],
26
+ "devDependencies": {
27
+ "@types/bun": "latest"
28
+ },
29
+ "peerDependencies": {
30
+ "typescript": "^5",
31
+ "@sigil-dev/grimoire": "0.9.31"
32
+ }
33
+ }
package/s3.ts ADDED
@@ -0,0 +1,91 @@
1
+ import type { S3Client, S3Options } from "bun";
2
+ import { checkKey, type Store } from "./store.ts";
3
+
4
+ export interface S3StoreOptions {
5
+ /** Default `S3_BUCKET`. */
6
+ bucket?: string;
7
+ /** For anything that is not AWS: SeaweedFS, MinIO, R2, Backblaze. Default `S3_ENDPOINT`. */
8
+ endpoint?: string;
9
+ /** Default `S3_REGION`, else us-east-1. */
10
+ region?: string;
11
+ /** Default `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY`, or the shorter `S3_ACCESS_KEY` and `S3_SECRET_KEY`. */
12
+ accessKeyId?: string;
13
+ secretAccessKey?: string;
14
+ /**
15
+ * Where the bucket is readable by anyone, for public files:
16
+ * `https://storage.example.com/avatars`. Without it, files are private
17
+ * and reached through signed links.
18
+ */
19
+ publicUrl?: string;
20
+ /** Put in front of every key: several apps in one bucket. */
21
+ prefix?: string;
22
+ }
23
+
24
+ /**
25
+ * Files in S3, or anything that speaks it: SeaweedFS, MinIO, Cloudflare R2,
26
+ * Backblaze B2. Uses Bun's own client, so nothing to install. Reads the
27
+ * usual S3_* variables when the server starts, not when the config loads.
28
+ */
29
+ export function s3(options: S3StoreOptions = {}): Store {
30
+ let client: S3Client | undefined;
31
+ const prefix = options.prefix ? `${checkKey(options.prefix)}/` : "";
32
+ const at = (key: string) => prefix + checkKey(key);
33
+ const connect = (): S3Client => {
34
+ if (client) return client;
35
+ const bucket = options.bucket ?? process.env.S3_BUCKET;
36
+ if (!bucket)
37
+ throw new Error(
38
+ "storage: s3() needs a bucket: S3_BUCKET, or s3({ bucket })",
39
+ );
40
+ const env = process.env;
41
+ // Bun's names, or the shorter ones many MinIO setups use
42
+ const accessKeyId = options.accessKeyId ?? env.S3_ACCESS_KEY_ID ?? env.S3_ACCESS_KEY;
43
+ const secretAccessKey = options.secretAccessKey ?? env.S3_SECRET_ACCESS_KEY ?? env.S3_SECRET_KEY;
44
+ const endpoint = options.endpoint ?? env.S3_ENDPOINT;
45
+ const settings: S3Options = {
46
+ bucket,
47
+ ...(endpoint ? { endpoint } : {}),
48
+ region: options.region ?? env.S3_REGION ?? "us-east-1",
49
+ ...(accessKeyId ? { accessKeyId } : {}),
50
+ ...(secretAccessKey ? { secretAccessKey } : {}),
51
+ };
52
+ const { S3Client: Client } = require("bun") as typeof import("bun");
53
+ client = new Client(settings);
54
+ return client;
55
+ };
56
+ const publicUrl = options.publicUrl?.replace(/\/$/, "");
57
+
58
+ return {
59
+ kind: "s3",
60
+ requiredEnv: options.bucket ? [] : ["S3_BUCKET"],
61
+ async open() {
62
+ connect();
63
+ },
64
+ async put(key, data, type) {
65
+ await connect().write(at(key), data, { type });
66
+ },
67
+ async get(key) {
68
+ const file = connect().file(at(key));
69
+ return (await file.exists()) ? file : null;
70
+ },
71
+ async delete(key) {
72
+ const c = connect();
73
+ const had = await c.exists(at(key));
74
+ if (had) await c.delete(at(key));
75
+ return had;
76
+ },
77
+ exists: (key) => connect().exists(at(key)),
78
+ ...(publicUrl ? { url: (key: string) => `${publicUrl}/${at(key)}` } : {}),
79
+ async signedUrl(key, seconds, { download }) {
80
+ return connect().presign(at(key), {
81
+ expiresIn: Math.max(1, Math.round(seconds)),
82
+ method: "GET",
83
+ ...(download
84
+ ? {
85
+ contentDisposition: `attachment; filename="${download.replace(/["\\\r\n]/g, "")}"`,
86
+ }
87
+ : {}),
88
+ });
89
+ },
90
+ };
91
+ }
package/sniff.ts ADDED
@@ -0,0 +1,95 @@
1
+ /**
2
+ * What a file is, from its first bytes. The type a browser sends is whatever
3
+ * the client says, and a .png that is really HTML is how an upload form
4
+ * becomes an XSS hole; the bytes are harder to lie with.
5
+ */
6
+ const KNOWN: { type: string; ext: string; test: (b: Uint8Array) => boolean }[] =
7
+ [
8
+ {
9
+ type: "image/png",
10
+ ext: "png",
11
+ test: (b) => starts(b, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
12
+ },
13
+ {
14
+ type: "image/jpeg",
15
+ ext: "jpg",
16
+ test: (b) => starts(b, [0xff, 0xd8, 0xff]),
17
+ },
18
+ {
19
+ type: "image/gif",
20
+ ext: "gif",
21
+ test: (b) => ascii(b, 0, "GIF87a") || ascii(b, 0, "GIF89a"),
22
+ },
23
+ {
24
+ type: "image/webp",
25
+ ext: "webp",
26
+ test: (b) => ascii(b, 0, "RIFF") && ascii(b, 8, "WEBP"),
27
+ },
28
+ {
29
+ type: "image/avif",
30
+ ext: "avif",
31
+ test: (b) =>
32
+ ascii(b, 4, "ftyp") && (ascii(b, 8, "avif") || ascii(b, 8, "avis")),
33
+ },
34
+ { type: "application/pdf", ext: "pdf", test: (b) => ascii(b, 0, "%PDF-") },
35
+ {
36
+ type: "video/mp4",
37
+ ext: "mp4",
38
+ test: (b) =>
39
+ ascii(b, 4, "ftyp") &&
40
+ /^(isom|iso2|mp41|mp42|avc1|M4V |dash)/.test(text(b, 8, 4)),
41
+ },
42
+ {
43
+ type: "video/webm",
44
+ ext: "webm",
45
+ test: (b) => starts(b, [0x1a, 0x45, 0xdf, 0xa3]),
46
+ },
47
+ {
48
+ type: "audio/mpeg",
49
+ ext: "mp3",
50
+ test: (b) =>
51
+ ascii(b, 0, "ID3") || (b[0] === 0xff && (b[1]! & 0xe0) === 0xe0),
52
+ },
53
+ { type: "audio/ogg", ext: "ogg", test: (b) => ascii(b, 0, "OggS") },
54
+ {
55
+ type: "application/zip",
56
+ ext: "zip",
57
+ test: (b) => starts(b, [0x50, 0x4b, 0x03, 0x04]),
58
+ },
59
+ ];
60
+
61
+ function starts(b: Uint8Array, sig: number[]): boolean {
62
+ return sig.every((v, i) => b[i] === v);
63
+ }
64
+ function text(b: Uint8Array, at: number, n: number): string {
65
+ return String.fromCharCode(...b.subarray(at, at + n));
66
+ }
67
+ function ascii(b: Uint8Array, at: number, s: string): boolean {
68
+ return text(b, at, s.length) === s;
69
+ }
70
+
71
+ export interface Sniffed {
72
+ type: string;
73
+ ext: string;
74
+ }
75
+
76
+ export async function sniff(file: Blob): Promise<Sniffed | null> {
77
+ const head = new Uint8Array(await file.slice(0, 32).arrayBuffer());
78
+ const found = KNOWN.find((k) => k.test(head));
79
+ return found ? { type: found.type, ext: found.ext } : null;
80
+ }
81
+
82
+ /** `"image/*"` matches image types, except SVG: it can carry script, so it is only ever allowed by name. */
83
+ export function allowed(type: string, patterns: readonly string[]): boolean {
84
+ return patterns.some((p) => {
85
+ if (p === type) return true;
86
+ if (!p.endsWith("/*")) return false;
87
+ return type.startsWith(p.slice(0, -1)) && type !== "image/svg+xml";
88
+ });
89
+ }
90
+
91
+ /** A file extension for a type nothing sniffed: the name's own, if it is plain. */
92
+ export function extOf(name: string): string {
93
+ const m = /\.([A-Za-z0-9]{1,8})$/.exec(name);
94
+ return m ? m[1]!.toLowerCase() : "bin";
95
+ }
package/store.ts ADDED
@@ -0,0 +1,61 @@
1
+ /** Where files live: disk() or s3(). Keys are checked before a store sees them. */
2
+ export interface Store {
3
+ readonly kind: string;
4
+ /** Variables it cannot work without, checked when the server starts. */
5
+ readonly requiredEnv?: readonly string[];
6
+ put(
7
+ key: string,
8
+ data: Blob | ArrayBuffer | Uint8Array | string,
9
+ type: string,
10
+ ): Promise<void>;
11
+ /** The file, or null. A Blob, so `new Response(file)` streams it. */
12
+ get(key: string): Promise<Blob | null>;
13
+ delete(key: string): Promise<boolean>;
14
+ exists(key: string): Promise<boolean>;
15
+ /** The address anyone can fetch it at, when the store is public. */
16
+ url?(key: string): string;
17
+ /** An address that works for `seconds`, for a private file. */
18
+ signedUrl?(
19
+ key: string,
20
+ seconds: number,
21
+ options: { download?: string },
22
+ ): Promise<string>;
23
+ /** Opened when the server starts: fails the boot instead of the first upload. */
24
+ open?(): Promise<void>;
25
+ }
26
+
27
+ /** Sizes as people write them: 512, "200kb", "5mb", "1.5gb". */
28
+ export function bytes(size: number | string): number {
29
+ if (typeof size === "number") return size;
30
+ const m = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?\s*$/i.exec(size);
31
+ if (!m)
32
+ throw new Error(
33
+ `storage: cannot read "${size}" as a size; use 512, "200kb", "5mb" or "1gb"`,
34
+ );
35
+ const unit = { b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3 }[
36
+ (m[2] ?? "b").toLowerCase() as "b"
37
+ ];
38
+ return Math.round(Number(m[1]) * unit);
39
+ }
40
+
41
+ /**
42
+ * A key is a path inside the store: letters, digits and `- _ . /`, no `..`,
43
+ * no empty segment. A key from a user that reaches a store any other way
44
+ * is how files get written outside it.
45
+ */
46
+ export function checkKey(key: string): string {
47
+ if (
48
+ typeof key !== "string" ||
49
+ key.length === 0 ||
50
+ key.length > 512 ||
51
+ !/^[A-Za-z0-9._\-/]+$/.test(key) ||
52
+ key.startsWith("/") ||
53
+ key.endsWith("/") ||
54
+ key.split("/").some((part) => part === "" || part === "." || part === "..")
55
+ ) {
56
+ throw new Error(
57
+ `storage: "${key}" is not a key: letters, digits, - _ . and / between names`,
58
+ );
59
+ }
60
+ return key;
61
+ }