@c9up/archive 0.1.3
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/LICENSE +21 -0
- package/README.md +35 -0
- package/dist/ArchiveProvider.d.ts +32 -0
- package/dist/ArchiveProvider.d.ts.map +1 -0
- package/dist/ArchiveProvider.js +91 -0
- package/dist/ArchiveProvider.js.map +1 -0
- package/dist/GcsDriver.d.ts +41 -0
- package/dist/GcsDriver.d.ts.map +1 -0
- package/dist/GcsDriver.js +387 -0
- package/dist/GcsDriver.js.map +1 -0
- package/dist/S3Driver.d.ts +50 -0
- package/dist/S3Driver.d.ts.map +1 -0
- package/dist/S3Driver.js +642 -0
- package/dist/S3Driver.js.map +1 -0
- package/dist/StaticMiddleware.d.ts +46 -0
- package/dist/StaticMiddleware.d.ts.map +1 -0
- package/dist/StaticMiddleware.js +121 -0
- package/dist/StaticMiddleware.js.map +1 -0
- package/dist/StorageManager.d.ts +178 -0
- package/dist/StorageManager.d.ts.map +1 -0
- package/dist/StorageManager.js +405 -0
- package/dist/StorageManager.js.map +1 -0
- package/dist/errors.d.ts +11 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +14 -0
- package/dist/errors.js.map +1 -0
- package/dist/expiry.d.ts +15 -0
- package/dist/expiry.d.ts.map +1 -0
- package/dist/expiry.js +26 -0
- package/dist/expiry.js.map +1 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +17 -0
- package/dist/index.js.map +1 -0
- package/dist/mime-types.d.ts +17 -0
- package/dist/mime-types.d.ts.map +1 -0
- package/dist/mime-types.js +47 -0
- package/dist/mime-types.js.map +1 -0
- package/dist/services/main.d.ts +19 -0
- package/dist/services/main.d.ts.map +1 -0
- package/dist/services/main.js +33 -0
- package/dist/services/main.js.map +1 -0
- package/dist/signed-route.d.ts +61 -0
- package/dist/signed-route.d.ts.map +1 -0
- package/dist/signed-route.js +155 -0
- package/dist/signed-route.js.map +1 -0
- package/dist/testing/FakeStorage.d.ts +72 -0
- package/dist/testing/FakeStorage.d.ts.map +1 -0
- package/dist/testing/FakeStorage.js +266 -0
- package/dist/testing/FakeStorage.js.map +1 -0
- package/package.json +67 -0
- package/src/ArchiveProvider.ts +134 -0
- package/src/GcsDriver.ts +490 -0
- package/src/S3Driver.ts +791 -0
- package/src/StaticMiddleware.ts +175 -0
- package/src/StorageManager.ts +627 -0
- package/src/errors.ts +14 -0
- package/src/expiry.ts +41 -0
- package/src/index.ts +41 -0
- package/src/mime-types.ts +51 -0
- package/src/services/main.ts +41 -0
- package/src/signed-route.ts +223 -0
- package/src/testing/FakeStorage.ts +372 -0
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Static file serving middleware.
|
|
3
|
+
*
|
|
4
|
+
* Serves files from a directory with cache headers and ETag support.
|
|
5
|
+
*
|
|
6
|
+
* Usage:
|
|
7
|
+
* const staticMiddleware = new StaticMiddleware({ root: 'public' })
|
|
8
|
+
* middleware.use(staticMiddleware.handle.bind(staticMiddleware))
|
|
9
|
+
*
|
|
10
|
+
* @implements MISS-25
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { createHash } from "node:crypto";
|
|
14
|
+
import * as fs from "node:fs";
|
|
15
|
+
import * as fsp from "node:fs/promises";
|
|
16
|
+
import * as path from "node:path";
|
|
17
|
+
import { DEFAULT_EXTENSIONS, inferMimeType } from "./mime-types.js";
|
|
18
|
+
import { VISIBILITY_SIDECAR_SUFFIX } from "./StorageManager.js";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Minimal request/response contract the static-file handler needs.
|
|
22
|
+
* Matches Ream's `HttpContext` structurally (public surface only) —
|
|
23
|
+
* avoids importing the concrete class so tests can build plain-object
|
|
24
|
+
* mocks without `as unknown as T` double-casts.
|
|
25
|
+
*/
|
|
26
|
+
export interface StaticMiddlewareResponse {
|
|
27
|
+
status(code: number): StaticMiddlewareResponse;
|
|
28
|
+
header(name: string, value: string): StaticMiddlewareResponse;
|
|
29
|
+
sendBuffer(buf: Buffer): void;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface StaticMiddlewareHttpContext {
|
|
33
|
+
request: {
|
|
34
|
+
method(): string;
|
|
35
|
+
path(): string;
|
|
36
|
+
header(name: string): string | undefined;
|
|
37
|
+
};
|
|
38
|
+
response: StaticMiddlewareResponse;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export interface StaticConfig {
|
|
42
|
+
/** Root directory to serve files from. */
|
|
43
|
+
root: string;
|
|
44
|
+
/** URL prefix (default: /static). */
|
|
45
|
+
prefix?: string;
|
|
46
|
+
/** Max-age for Cache-Control header in seconds (default: 86400 = 1 day). */
|
|
47
|
+
maxAge?: number;
|
|
48
|
+
/** File extensions to serve (default: common web assets). */
|
|
49
|
+
extensions?: string[];
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export class StaticMiddleware {
|
|
53
|
+
#root: string;
|
|
54
|
+
#prefix: string;
|
|
55
|
+
#maxAge: number;
|
|
56
|
+
#extensions: Set<string>;
|
|
57
|
+
|
|
58
|
+
constructor(config: StaticConfig) {
|
|
59
|
+
const prefix = config.prefix ?? "/static";
|
|
60
|
+
// Reject an empty-string prefix — it would make every GET on an
|
|
61
|
+
// allow-listed extension resolve to a file under `root`, which
|
|
62
|
+
// is rarely what a caller wants and always a misconfiguration
|
|
63
|
+
// risk. Require the caller to pick a real URL prefix.
|
|
64
|
+
if (prefix === "") {
|
|
65
|
+
throw new Error(
|
|
66
|
+
"StaticMiddleware: prefix cannot be empty. Use '/static' (default) or a specific path like '/assets'.",
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
const resolved = path.resolve(config.root);
|
|
70
|
+
// Canonicalise the root so the realpath check in handle() can
|
|
71
|
+
// detect symlink-based escapes consistently.
|
|
72
|
+
this.#root = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
|
|
73
|
+
this.#prefix = prefix;
|
|
74
|
+
this.#maxAge = config.maxAge ?? 86400;
|
|
75
|
+
this.#extensions = new Set(config.extensions ?? DEFAULT_EXTENSIONS);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
async handle(
|
|
79
|
+
ctx: StaticMiddlewareHttpContext,
|
|
80
|
+
next: () => Promise<void>,
|
|
81
|
+
): Promise<void> {
|
|
82
|
+
if (ctx.request.method() !== "GET" && ctx.request.method() !== "HEAD") {
|
|
83
|
+
return next();
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const reqPath = ctx.request.path();
|
|
87
|
+
// Match the prefix exactly: `/static/foo` matches prefix `/static`, but
|
|
88
|
+
// `/staticx/foo` must NOT match. Require the char after the prefix to be
|
|
89
|
+
// `/` or end-of-string.
|
|
90
|
+
if (!reqPath.startsWith(this.#prefix)) {
|
|
91
|
+
return next();
|
|
92
|
+
}
|
|
93
|
+
const afterPrefix = reqPath[this.#prefix.length];
|
|
94
|
+
if (afterPrefix !== undefined && afterPrefix !== "/") {
|
|
95
|
+
return next();
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
// Strip prefix and resolve file path
|
|
99
|
+
const relativePath = reqPath.slice(this.#prefix.length) || "/index.html";
|
|
100
|
+
|
|
101
|
+
// Visibility sidecars are an implementation detail of LocalDriver
|
|
102
|
+
// — never serve them, even if the static root happens to overlap
|
|
103
|
+
// the storage root. Check BEFORE the extension allow-list because
|
|
104
|
+
// `.archive-visibility.json` has a `.json` extension that would
|
|
105
|
+
// otherwise pass. Case-insensitive to defeat
|
|
106
|
+
// `.ARCHIVE-VISIBILITY.JSON` variants on case-insensitive
|
|
107
|
+
// filesystems (macOS default, Windows).
|
|
108
|
+
if (relativePath.toLowerCase().endsWith(VISIBILITY_SIDECAR_SUFFIX)) {
|
|
109
|
+
return next();
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
const ext = path.extname(relativePath).toLowerCase();
|
|
113
|
+
|
|
114
|
+
if (!this.#extensions.has(ext)) {
|
|
115
|
+
return next();
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
// Prevent path traversal (lexical check first).
|
|
119
|
+
const filePath = path.resolve(this.#root, relativePath.replace(/^\//, ""));
|
|
120
|
+
if (
|
|
121
|
+
!filePath.startsWith(this.#root + path.sep) &&
|
|
122
|
+
filePath !== this.#root
|
|
123
|
+
) {
|
|
124
|
+
return next();
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
let stat: Awaited<ReturnType<typeof fsp.stat>>;
|
|
128
|
+
let realPath: string;
|
|
129
|
+
try {
|
|
130
|
+
stat = await fsp.stat(filePath);
|
|
131
|
+
if (!stat.isFile()) return next();
|
|
132
|
+
// Realpath guard — defeats symlink-based escapes where a
|
|
133
|
+
// symlink inside `root` points to a file outside it.
|
|
134
|
+
realPath = await fsp.realpath(filePath);
|
|
135
|
+
if (
|
|
136
|
+
!realPath.startsWith(this.#root + path.sep) &&
|
|
137
|
+
realPath !== this.#root
|
|
138
|
+
) {
|
|
139
|
+
return next();
|
|
140
|
+
}
|
|
141
|
+
} catch {
|
|
142
|
+
return next();
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
const etag = createHash("md5")
|
|
146
|
+
.update(`${stat.size}-${stat.mtimeMs}`)
|
|
147
|
+
.digest("hex");
|
|
148
|
+
|
|
149
|
+
// ETag check — 304 Not Modified
|
|
150
|
+
const ifNoneMatch = ctx.request.header("if-none-match");
|
|
151
|
+
if (ifNoneMatch === etag) {
|
|
152
|
+
ctx.response.status(304);
|
|
153
|
+
return;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
const mime = inferMimeType(ext);
|
|
157
|
+
ctx.response.header("Content-Type", mime);
|
|
158
|
+
ctx.response.header("Content-Length", String(stat.size));
|
|
159
|
+
ctx.response.header("Cache-Control", `public, max-age=${this.#maxAge}`);
|
|
160
|
+
ctx.response.header("ETag", etag);
|
|
161
|
+
|
|
162
|
+
if (ctx.request.method() === "HEAD") {
|
|
163
|
+
ctx.response.status(200);
|
|
164
|
+
return;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
// Read the canonicalised path — closes the symlink TOCTOU window
|
|
168
|
+
// between the realpath check above and the read. `filePath` could
|
|
169
|
+
// resolve through a symlink that was swapped after we validated it.
|
|
170
|
+
const content = await fsp.readFile(realPath);
|
|
171
|
+
// Send the raw Buffer — NOT content.toString() which would destroy binary
|
|
172
|
+
// data (PNG, PDF, ZIP, etc.) by interpreting it as UTF-8.
|
|
173
|
+
ctx.response.status(200).sendBuffer(content);
|
|
174
|
+
}
|
|
175
|
+
}
|