keys.ts · Source

keys.tspackages/storage/src/keys.tsraw ← src8,832 B← Back to the app
1/**
2 * @factory/storage — object key layout (PURE).
3 *
4 * The key layout is THE contract between every pipeline stage
5 * (TASK-0101 Requirement 2, docs/tasks/phase-09-files.md):
6 *
7 * ```
8 * files/{workspaceId}/{fileId}/{version}/{safeName}
9 * thumbs/{workspaceId}/{fileId}/{size}/{safeName}
10 * ```
11 *
12 *  - `files/` — the private uploads bucket (`S3_BUCKET_FILES`).
13 *  - `thumbs/` — the read-only-serving bucket (`S3_BUCKET_THUMBS`); serving
14 *    is still server-authorized (signed URLs only, no public bucket).
15 *
16 * Rules:
17 *  - Deterministic — no clock, no randomness (same input ⇒ same key); the
18 *    ONLY non-determinism is the collision suffix (`-<8 hex>`), appended by
19 *    the caller when two files in the same workspace + file slot share a
20 *    sanitized name (see {@link withCollisionSuffix}).
21 *  - Workspace isolation is by KEY PREFIX + permission checks, NOT by bucket
22 *    ACL (one bucket per environment, all workspaces share it) — documented
23 *    decision, TASK-0101 Requirement 2.
24 *  - Names are sanitized ({@link sanitizeFilename}) so no path component,
25 *    control char, or unsafe byte can survive into a key — path traversal is
26 *    impossible by construction.
27 */
28 
29/** Max length of the sanitized name segment (extension included). */
30export const MAX_KEY_NAME_LENGTH = 180;
31 
32/** Thumbnail sizes (px wide). 480 is the primary UI thumbnail. */
33export const THUMBNAIL_SIZES = ["160", "480", "1280"] as const;
34export type ThumbnailSize = (typeof THUMBNAIL_SIZES)[number];
35 
36export const THUMBNAIL_SIZE_WIDTH: Record<ThumbnailSize, number> = {
37  "160": 160,
38  "480": 480,
39  "1280": 1280,
40};
41 
42/**
43 * Sanitize a user-supplied file name for use as a key segment
44 * (TASK-0101 Requirement 2).
45 *
46 * 1. Strip ANY path components — both `/` and `\` separators and Windows
47 *    drives (`C:\` collapses to the basename), so `../../etc/passwd` →
48 *    `passwd`.
49 * 2. Replace every char in `[\x00-\x1f\x7f<>:"\\/*?|]` with `_`
50 *    (control chars, DEL, and the filesystem-forbidden set).
51 * 3. Cap the STEM at {@link MAX_KEY_NAME_LENGTH} WITHOUT losing the
52 *    extension (the extension is re-attached after truncation, and is
53 *    preserved case-insensitively — `UPPER.PNG` keeps `.PNG`).
54 *
55 * Pure and deterministic; never throws on hostile input.
56 */
57export function sanitizeFilename(name: string): string {
58  let base = name;
59  // 1) basename across BOTH path separators — traversal is impossible.
60  const lastSep = Math.max(base.lastIndexOf("/"), base.lastIndexOf("\\"));
61  if (lastSep !== -1) base = base.slice(lastSep + 1);
62 
63  // 2) control chars + the filesystem-forbidden set → underscore. Backslash
64  //    is in the forbidden set (replaced) — it never survives a key.
65  base = base.replace(/[\x00-\x1f\x7f<>:"\\/*?|]/g, "_");
66 
67  // 2b) empty or dots-only (hidden dotfiles stripped) → 'file'.
68  if (base === "" || /^\.+$/.test(base)) base = "file";
69 
70  // 3) cap the TOTAL (stem + extension) at 180 chars, extension preserved
71  //    (case-insensitive).
72  const dot = base.lastIndexOf(".");
73  if (dot > 0 && dot < base.length - 1) {
74    const stem = base.slice(0, dot);
75    const ext = base.slice(dot);
76    if (stem.length + ext.length > MAX_KEY_NAME_LENGTH) {
77      base = stem.slice(0, Math.max(1, MAX_KEY_NAME_LENGTH - ext.length)) + ext;
78    }
79  } else if (base.length > MAX_KEY_NAME_LENGTH) {
80    base = base.slice(0, MAX_KEY_NAME_LENGTH);
81  }
82 
83  return base === "" ? "file" : base;
84}
85 
86/**
87 * Append a collision suffix (`-<8 hex>`) to a sanitized name when two files
88 * would otherwise map to the same key. The hex fragment comes from the
89 * caller (e.g. a slice of the file id) so the result stays deterministic
90 * for a given file. The stem is re-capped so the segment stays ≤ 180 chars
91 * INCLUDING the suffix + extension.
92 */
93export function withCollisionSuffix(name: string, hex: string): string {
94  const suffix = `-${hex.slice(0, 8).padEnd(8, "0")}`;
95  const dot = name.lastIndexOf(".");
96  if (dot > 0 && dot < name.length - 1) {
97    const stem = name.slice(0, dot);
98    const ext = name.slice(dot);
99    const maxStem = Math.max(1, MAX_KEY_NAME_LENGTH - suffix.length - ext.length);
100    return stem.slice(0, maxStem) + suffix + ext;
101  }
102  const max = Math.max(1, MAX_KEY_NAME_LENGTH - suffix.length);
103  return name.slice(0, max) + suffix;
104}
105 
106/** Parts of a file object key. */
107export interface FileKeyParts {
108  workspaceId: string;
109  fileId: string;
110  /** Version number (1 for the first upload). */
111  version: number;
112  /** Original file name (sanitized here). */
113  name: string;
114}
115 
116/**
117 * Build the S3 key of a file object in the `files` bucket.
118 *
119 * `buildFileKey({ workspaceId: "wsp_1", fileId: "fil_1", version: 1, name: "a.png" })`
120 * → `files/wsp_1/fil_1/1/a.png`
121 */
122export function buildFileKey(parts: FileKeyParts): string {
123  if (!Number.isInteger(parts.version) || parts.version < 1) {
124    throw new Error(`version must be a positive integer, got ${parts.version}`);
125  }
126  const safe = sanitizeFilename(parts.name);
127  return `files/${parts.workspaceId}/${parts.fileId}/${parts.version}/${safe}`;
128}
129 
130/** Parts of a thumbnail key. */
131export interface ThumbKeyParts {
132  workspaceId: string;
133  fileId: string;
134  /** Size tag: "160" | "480" | "1280" (px wide). */
135  size: ThumbnailSize;
136  /** Original file name (sanitized here). */
137  name: string;
138  /**
139   * Output extension of the artifact. Images keep the source format
140   * (`png`/`jpeg`/`webp`); PDF/video artifacts are `png`.
141   */
142  ext: string;
143}
144 
145/**
146 * Build the S3 key of a thumbnail artifact in the `thumbs` bucket.
147 *
148 * `buildThumbKey({ workspaceId: "wsp_1", fileId: "fil_1", size: "480", name: "a.png", ext: "png" })`
149 * → `thumbs/wsp_1/fil_1/480/a.png`
150 */
151export function buildThumbKey(parts: ThumbKeyParts): string {
152  if (!THUMBNAIL_SIZES.includes(parts.size)) {
153    throw new Error(`unknown thumbnail size: ${parts.size}`);
154  }
155  const safe = sanitizeFilename(parts.name);
156  const ext = parts.ext.replace(/^\./, "").toLowerCase();
157  return `thumbs/${parts.workspaceId}/${parts.fileId}/${parts.size}/${safe}.${ext}`;
158}
159 
160/** The `files/` key prefix (one workspace's whole file tree). */
161export function workspaceFilePrefix(workspaceId: string): string {
162  return `files/${workspaceId}/`;
163}
164 
165/** The `thumbs/` key prefix (one workspace's whole thumbnail tree). */
166export function workspaceThumbPrefix(workspaceId: string): string {
167  return `thumbs/${workspaceId}/`;
168}
169 
170/** Parsed form of a file key (the inverse of {@link buildFileKey}). */
171export interface ParsedFileKey {
172  workspaceId: string;
173  fileId: string;
174  version: number;
175  /** Sanitized file name. */
176  name: string;
177}
178 
179const PARSE_FILE_KEY_RE = /^files\/([^/]+)\/([^/]+)\/(\d+)\/(.+)$/;
180 
181/**
182 * Parse a `files/` object key back into its parts. Throws on anything
183 * malformed — never guesses.
184 */
185export function parseFileKey(key: string): ParsedFileKey {
186  const m = PARSE_FILE_KEY_RE.exec(key);
187  if (!m) throw new Error(`malformed file key: ${key}`);
188  const [, workspaceId, fileId, versionStr, name] = m;
189  const version = Number(versionStr);
190  if (!Number.isSafeInteger(version) || version < 1) {
191    throw new Error(`malformed file key version: ${key}`);
192  }
193  if (name === undefined || name === "" || name.includes("/") || name.includes("\\")) {
194    throw new Error(`malformed file key name: ${key}`);
195  }
196  return { workspaceId: workspaceId!, fileId: fileId!, version, name: name! };
197}
198 
199/** Parsed form of a thumbnail key (the inverse of {@link buildThumbKey}). */
200export interface ParsedThumbKey {
201  workspaceId: string;
202  fileId: string;
203  size: ThumbnailSize;
204  /** Sanitized source file name. */
205  name: string;
206  ext: string;
207}
208 
209const PARSE_THUMB_KEY_RE = /^thumbs\/([^/]+)\/([^/]+)\/(160|480|1280)\/(.+)$/;
210 
211/**
212 * Parse a `thumbs/` object key back into its parts. Throws on anything
213 * malformed — never guesses.
214 */
215export function parseThumbKey(key: string): ParsedThumbKey {
216  const m = PARSE_THUMB_KEY_RE.exec(key);
217  if (!m) throw new Error(`malformed thumbnail key: ${key}`);
218  const nameDot = m[4]!.lastIndexOf(".");
219  const name = nameDot > 0 ? m[4]!.slice(0, nameDot) : m[4]!;
220  const ext = nameDot > 0 ? m[4]!.slice(nameDot + 1) : "";
221  return {
222    workspaceId: m[1]!,
223    fileId: m[2]!,
224    size: m[3] as ThumbnailSize,
225    name,
226    ext,
227  };
228}
229 
230/**
231 * True if `key` lies within `prefix` (prefix must end with `/` for a
232 * directory-style check; bare key equality is also allowed).
233 *
234 * Used for workspace-scoped listing/deletion:
235 * `isWithinBucketPrefix(key, workspaceFilePrefix("wsp_1"))` → the workspace's
236 * whole file tree.
237 */
238export function isWithinBucketPrefix(key: string, prefix: string): boolean {
239  if (key === prefix) return true;
240  if (!prefix.endsWith("/")) return key.startsWith(prefix + "/");
241  return key.startsWith(prefix) && key.length > prefix.length;
242}
243