@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.
Files changed (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +35 -0
  3. package/dist/ArchiveProvider.d.ts +32 -0
  4. package/dist/ArchiveProvider.d.ts.map +1 -0
  5. package/dist/ArchiveProvider.js +91 -0
  6. package/dist/ArchiveProvider.js.map +1 -0
  7. package/dist/GcsDriver.d.ts +41 -0
  8. package/dist/GcsDriver.d.ts.map +1 -0
  9. package/dist/GcsDriver.js +387 -0
  10. package/dist/GcsDriver.js.map +1 -0
  11. package/dist/S3Driver.d.ts +50 -0
  12. package/dist/S3Driver.d.ts.map +1 -0
  13. package/dist/S3Driver.js +642 -0
  14. package/dist/S3Driver.js.map +1 -0
  15. package/dist/StaticMiddleware.d.ts +46 -0
  16. package/dist/StaticMiddleware.d.ts.map +1 -0
  17. package/dist/StaticMiddleware.js +121 -0
  18. package/dist/StaticMiddleware.js.map +1 -0
  19. package/dist/StorageManager.d.ts +178 -0
  20. package/dist/StorageManager.d.ts.map +1 -0
  21. package/dist/StorageManager.js +405 -0
  22. package/dist/StorageManager.js.map +1 -0
  23. package/dist/errors.d.ts +11 -0
  24. package/dist/errors.d.ts.map +1 -0
  25. package/dist/errors.js +14 -0
  26. package/dist/errors.js.map +1 -0
  27. package/dist/expiry.d.ts +15 -0
  28. package/dist/expiry.d.ts.map +1 -0
  29. package/dist/expiry.js +26 -0
  30. package/dist/expiry.js.map +1 -0
  31. package/dist/index.d.ts +17 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +17 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/mime-types.d.ts +17 -0
  36. package/dist/mime-types.d.ts.map +1 -0
  37. package/dist/mime-types.js +47 -0
  38. package/dist/mime-types.js.map +1 -0
  39. package/dist/services/main.d.ts +19 -0
  40. package/dist/services/main.d.ts.map +1 -0
  41. package/dist/services/main.js +33 -0
  42. package/dist/services/main.js.map +1 -0
  43. package/dist/signed-route.d.ts +61 -0
  44. package/dist/signed-route.d.ts.map +1 -0
  45. package/dist/signed-route.js +155 -0
  46. package/dist/signed-route.js.map +1 -0
  47. package/dist/testing/FakeStorage.d.ts +72 -0
  48. package/dist/testing/FakeStorage.d.ts.map +1 -0
  49. package/dist/testing/FakeStorage.js +266 -0
  50. package/dist/testing/FakeStorage.js.map +1 -0
  51. package/package.json +67 -0
  52. package/src/ArchiveProvider.ts +134 -0
  53. package/src/GcsDriver.ts +490 -0
  54. package/src/S3Driver.ts +791 -0
  55. package/src/StaticMiddleware.ts +175 -0
  56. package/src/StorageManager.ts +627 -0
  57. package/src/errors.ts +14 -0
  58. package/src/expiry.ts +41 -0
  59. package/src/index.ts +41 -0
  60. package/src/mime-types.ts +51 -0
  61. package/src/services/main.ts +41 -0
  62. package/src/signed-route.ts +223 -0
  63. 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
+ }