@gentleduck/upload 0.2.5 → 0.3.0

package/dist/strategies/index.d.ts

@@ -1,56 +1,2 @@
-import { f as IntentMap, l as UploadResultBase, n as StrategyRegistry, o as CursorMap, r as UploadStrategy, t as StrategyCtx } from "../strategy.types-gg9ZStRe.js";
-
-//#region src/strategies/multipart/index.d.ts
-type MultipartIntent = {
-  strategy: 'multipart';
-  fileId: string;
-  uploadId: string;
-  partSize: number;
-  partCount: number;
-  parts?: Array<{
-    partNumber: number;
-    url: string;
-    headers?: Record<string, string>;
-  }>;
-};
-type MultipartCursor = {
-  done: Array<{
-    partNumber: number;
-    etag: string;
-    size: number;
-  }>;
-  /**
-   * Marks that the multipart session was completed on the backend (parts assembled).
-   * This prevents re-sending completeMultipart on resume.
-   */
-  completed?: true;
-};
-declare function multipartStrategy<M extends IntentMap & {
-  multipart: MultipartIntent;
-}, C extends CursorMap<M> & {
-  multipart?: MultipartCursor;
-}, P extends string = string, R extends UploadResultBase = UploadResultBase>(opts?: {
-  maxPartConcurrency?: number;
-}): UploadStrategy<M, C, P, R, 'multipart'>;
-//#endregion
-//#region src/strategies/post/index.d.ts
-type PostIntent = {
-  /** Strategy identifier - must be 'post' */strategy: 'post'; /** Backend file identifier */
-  fileId: string; /** Presigned POST URL (form action) */
-  url: string; /** Form fields to include before the file */
-  fields: Record<string, string>; /** Optional expiration timestamp for the presigned URL */
-  expiresAt?: string;
-};
-type PostCursor = {
-  /** Bytes uploaded (for progress display only) */uploadedBytes: number;
-};
-declare function PostStrategy<M extends IntentMap & {
-  post: PostIntent;
-}, C extends CursorMap<M> & {
-  post?: PostCursor;
-}, P extends string = string, R extends UploadResultBase = UploadResultBase>(): UploadStrategy<M, C, P, R, 'post'>;
-//#endregion
-//#region src/strategies/registry/index.d.ts
-declare function createStrategyRegistry<M extends IntentMap, C extends CursorMap<M>, P extends string = string, R extends UploadResultBase = UploadResultBase>(): StrategyRegistry<M, C, P, R>;
-//#endregion
-export { MultipartCursor, MultipartIntent, PostCursor, PostIntent, PostStrategy, type StrategyCtx, type StrategyRegistry, type UploadStrategy, createStrategyRegistry, multipartStrategy };
+import { a as PutStrategy, c as MultipartStrategy, i as PutIntent, l as multipartStrategy, n as TusStrategy, o as PostIntent, r as createStrategyRegistry, s as PostStrategy, t as TusIntent } from "../index-KROXtLQh.js";
+export { MultipartStrategy, PostIntent, PostStrategy, PutIntent, PutStrategy, TusIntent, TusStrategy, createStrategyRegistry, multipartStrategy };

package/dist/strategies/index.js

@@ -1 +1 @@
-import{t as e}from"../async-DxRWu4le.js";function t(e){return e instanceof Error&&(e.name===`AbortError`||/abort/i.test(e.message))}function n(n){let r=Math.max(1,n?.maxPartConcurrency??4);return{id:`multipart`,resumable:!0,async start(n){let i=n.intent,a=n.file.size,o=Math.max(1,i.partSize),s=Math.max(1,i.partCount??Math.ceil(a/o)),c=n.readCursor(),l=new Map;if(c?.done)for(let e of c.done)l.set(e.partNumber,{etag:e.etag,size:e.size});let u=c?.completed===!0,d=new Map,f=0;for(let e of l.values())f+=e.size;let p=()=>{let e=0;for(let t of d.values())e+=t;n.reportProgress({uploadedBytes:f+e,totalBytes:a})},m=[];for(let e=1;e<=s;e++){if(l.has(e))continue;let t=(e-1)*o,n=Math.min(a,t+o);m.push({partNumber:e,start:t,end:n})}if(m.length===0){u||await y(),p();return}let h=m.slice(),g=new Set,_=async e=>{let t=i.parts?.find(t=>t.partNumber===e);if(t)return t;if(!n.api.multipart?.signPart)throw Error(`multipart.signPart is missing in UploadApi. Implement it to call your backend sign-part endpoint.`);let r=await n.api.multipart.signPart({fileId:i.fileId,uploadId:i.uploadId,partNumber:e},{signal:n.signal});return{partNumber:e,url:r.url,headers:r.headers}},v=async(r,i=0)=>{try{let e=n.file.slice(r.start,r.end),t=e.size,i=await _(r.partNumber),a=await n.transport.put({url:i.url,body:e,headers:i.headers,signal:n.signal,onProgress:e=>{d.set(r.partNumber,e),p()}});d.delete(r.partNumber);let o=a.etag;if(!o)throw Error(`Missing ETag from upload part response. Ensure MinIO/S3 CORS exposes ETag (Access-Control-Expose-Headers: ETag).`);f+=t,l.set(r.partNumber,{etag:o,size:t});let s={done:Array.from(l.entries()).map(([e,t])=>({partNumber:e,etag:t.etag,size:t.size})).sort((e,t)=>e.partNumber-t.partNumber)};n.persistCursor(s),p()}catch(a){if(d.delete(r.partNumber),n.signal?.aborted||t(a))throw a;if(i<3){let t=a instanceof Error?a.message:String(a);if(/network/i.test(t)||/timeout/i.test(t)||/5\d\d/.test(t)||/ECONNRESET/i.test(t)||/EHOSTUNREACH/i.test(t))return await e(2**i*500),v(r,i+1)}throw a}};for(;h.length>0||g.size>0;){for(;h.length>0&&g.size<r;){let e=h.shift();if(!e)break;let t,n=v(e).finally(()=>{t&&g.delete(t)});t=n,g.add(n)}g.size>0&&await Promise.race(g)}await y(),p();async function y(){if(u)return;if(!n.api.multipart?.completeMultipart)throw Error(`multipart.completeMultipart is missing in UploadApi. Implement it to call your backend complete endpoint.`);let e=Array.from(l.entries()).map(([e,t])=>({partNumber:e,etag:t.etag})).sort((e,t)=>e.partNumber-t.partNumber);if(e.length!==s)throw Error(`Cannot complete multipart: expected ${s} parts, got ${e.length}`);await n.api.multipart.completeMultipart({fileId:i.fileId,uploadId:i.uploadId,parts:e},{signal:n.signal});let t={done:Array.from(l.entries()).map(([e,t])=>({partNumber:e,etag:t.etag,size:t.size})).sort((e,t)=>e.partNumber-t.partNumber),completed:!0};n.persistCursor(t)}}}}function r(){return{id:`post`,resumable:!1,async start(e){let t=e.intent;if(!t.url)throw Error(`Direct strategy: intent missing url/uploadUrl`);await e.transport.postForm({url:t.url,file:e.file,fields:t.fields,filename:e.file.name,signal:e.signal,onProgress(t,n){e.reportProgress({uploadedBytes:t,totalBytes:n})}})}}}function i(){let e={};return{get(t){return e[t]},has(t){return Object.hasOwn(e,t)},set(t){e[t.id]=t}}}export{r as PostStrategy,i as createStrategyRegistry,n as multipartStrategy};
+import{a as e,i as t,n,r,t as i}from"../strategies-CUF0s68j.js";export{t as PostStrategy,r as PutStrategy,i as TusStrategy,n as createStrategyRegistry,e as multipartStrategy};

package/dist/strategies-CUF0s68j.js

@@ -0,0 +1 @@
+import{d as e,m as t}from"./core-BVgloTiP.js";function n(e){let t=/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(e);if(!t||t[1]===void 0||t[2]===void 0)return null;let n=parseInt(t[1],16),r=parseInt(t[2],16);return!Number.isFinite(n)||!Number.isFinite(r)||n<0||n>65535||r<0||r>65535?null:`${n>>8&255}.${n&255}.${r>>8&255}.${r&255}`}function r(e){let t=e.startsWith(`[`)&&e.endsWith(`]`)?e.slice(1,-1):e;t.endsWith(`.`)&&(t=t.slice(0,-1));let i=/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(t);if(i){let e=Number(i[1]),t=Number(i[2]),n=Number(i[3]),r=Number(i[4]);return e>255||t>255||n>255||r>255?!1:e===127||e===10||e===192&&t===168||e===172&&t>=16&&t<=31||e===169&&t===254||e===0||e===100&&t>=64&&t<=127||e>=224&&e<=239||e>=240}if(t.includes(`:`)){let e=t.toLowerCase();if(e===`::1`||e===`0:0:0:0:0:0:0:1`||e===`::`||e===`0:0:0:0:0:0:0:0`||/^f[cd][0-9a-f]{0,2}:/.test(e)||/^fe[89ab][0-9a-f]?:/.test(e)||/^ff[0-9a-f]{0,2}:/.test(e))return!0;let i=null;if(e.startsWith(`::ffff:`)?i=e.slice(7):e.startsWith(`0:0:0:0:0:ffff:`)&&(i=e.slice(15)),i!==null){if(i.includes(`.`))return r(i);let e=n(i);return e?r(e):!1}if(e.startsWith(`::`)&&e.includes(`.`)){let t=e.slice(2);if(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.test(t))return r(t)}if(e.startsWith(`2002:`)){let t=/^2002:([0-9a-f]{1,4}):([0-9a-f]{1,4})(?::|$)/.exec(e);if(t){let e=n(`${t[1]}:${t[2]}`);if(e)return r(e)}}if(e.startsWith(`64:ff9b:`)||e.startsWith(`0064:ff9b:`)){let t=e.startsWith(`0064:`)?e.slice(10):e.slice(8);if(t.includes(`.`)){let e=/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(t);if(e?.[1]!==void 0)return r(e[1])}let i=t.split(`:`).filter(e=>e.length>0);if(i.length>=2){let e=n(`${i[i.length-2]}:${i[i.length-1]}`);if(e)return r(e)}}return!1}return!1}function i(e,t,n={}){if(typeof e!=`string`||e.length===0)throw Error(`${t} returned an invalid URL (empty or non-string)`);if(e.length>8192)throw Error(`${t} URL exceeds 8192-byte length cap`);if(e.includes(`..`))throw Error(`${t} URL contains forbidden ".." segment`);let i;try{i=new URL(e)}catch{throw Error(`${t} returned a malformed URL`)}if(i.protocol!==`http:`&&i.protocol!==`https:`)throw Error(`${t} URL has forbidden protocol "${i.protocol}"`);if(n.allowedHosts&&n.allowedHosts.length>0){let e=i.host.toLowerCase();if(!n.allowedHosts.map(e=>e.toLowerCase()).includes(e))throw Error(`${t} URL host is not in the configured allow-list`)}if(!n.allowPrivateHosts&&r(i.hostname))throw Error(`${t} URL points to a private/loopback host`)}function a(e){return e instanceof Error&&(e.name===`AbortError`||/abort/i.test(e.message))}function o(e){let t=e instanceof Error?e.message:String(e);return/network/i.test(t)||/timeout/i.test(t)||/5\d\d/.test(t)||/ECONNRESET/i.test(t)||/EHOSTUNREACH/i.test(t)}async function s(t,n={}){let r=Math.max(0,n.maxRetries??3),i=n.retryable??o,s=0;for(;;)try{return await t(s)}catch(t){if(n.signal?.aborted||a(t)||s>=r||!i(t))throw t;await e(2**s*500),s++}}let c=!1;function l(e,t={}){(!t.allowedHosts||t.allowedHosts.length===0)&&!c&&(c=!0,console.warn("[duck-upload] multipartStrategy: no `allowedHosts` configured. Signed part URLs will be host-unrestricted. Set MultipartStrategy.Config.allowedHosts to lock the upload host.")),i(e,`multipart.signPart`,t)}function u(e){let n=Math.max(1,e?.maxPartConcurrency??4),r=e?.allowedHosts??[],i=e?.allowPrivateHosts===!0;return{id:`multipart`,resumable:!0,async start(e){let a=e.intent,o=e.file.size,c=Math.max(1,a.partSize),u=Math.max(1,a.partCount??Math.ceil(o/c)),d=e.readCursor(),f=new Map;if(d?.done)for(let e of d.done)f.set(e.partNumber,{etag:e.etag,size:e.size});let p=d?.completed===!0,m=new Map,h=0;for(let e of f.values())h+=e.size;let g=()=>{let t=0;for(let e of m.values())t+=e;e.reportProgress({uploadedBytes:h+t,totalBytes:o})},_=[];for(let e=1;e<=u;e++){if(f.has(e))continue;let t=(e-1)*c,n=Math.min(o,t+c);_.push({partNumber:e,start:t,end:n})}if(_.length===0){p||await S(),g();return}let v=_.slice(),y=new Set,b=async n=>{let r=a.parts?.find(e=>e.partNumber===n);if(r)return r;if(!e.api.multipart?.signPart)throw new t(`validation_failed`,{message:`multipart.signPart is missing in UploadApi. Implement it to call your backend sign-part endpoint.`});let i=await e.api.multipart.signPart({fileId:a.fileId,uploadId:a.uploadId,partNumber:n,attempt:e.attempt},{localId:e.localId,purpose:e.purpose,file:e.file,intent:e.intent,signal:e.signal,fingerprint:e.fingerprint,attempt:e.attempt,createdAt:e.createdAt,steps:e.steps,meta:e.meta,lastError:e.lastError});return{partNumber:n,url:i.url,headers:i.headers}},x=n=>s(async()=>{try{let a=e.file.slice(n.start,n.end),o=a.size,s=await b(n.partNumber);l(s.url,{allowedHosts:r,allowPrivateHosts:i});let c=await e.transport.put({url:s.url,body:a,headers:s.headers??{},signal:e.signal,onProgress:e=>{m.set(n.partNumber,e),g()}});m.delete(n.partNumber);let u=c.etag;if(!u)throw new t(`upload_failed`,{message:`Missing ETag from upload part response. Ensure MinIO/S3 CORS exposes ETag (Access-Control-Expose-Headers: ETag).`});h+=o,f.set(n.partNumber,{etag:u,size:o});let d={done:Array.from(f.entries()).map(([e,t])=>({partNumber:e,etag:t.etag,size:t.size})).sort((e,t)=>e.partNumber-t.partNumber)};e.persistCursor(d),g()}catch(e){throw m.delete(n.partNumber),e}},{signal:e.signal});for(;v.length>0||y.size>0;){for(;v.length>0&&y.size<n;){let e=v.shift();if(!e)break;let t,n=x(e).finally(()=>{t&&y.delete(t)});t=n,y.add(n)}y.size>0&&await Promise.race(y)}await S(),g();async function S(){if(p)return;if(!e.api.multipart?.completeMultipart)throw new t(`validation_failed`,{message:`multipart.completeMultipart is missing in UploadApi. Implement it to call your backend complete endpoint.`});let n=Array.from(f.entries()).map(([e,t])=>({partNumber:e,etag:t.etag})).sort((e,t)=>e.partNumber-t.partNumber);if(n.length!==u)throw new t(`complete_failed`,{message:`Cannot complete multipart: expected ${u} parts, got ${n.length}`});await e.api.multipart.completeMultipart({fileId:a.fileId,uploadId:a.uploadId,parts:n},{localId:e.localId,purpose:e.purpose,file:e.file,intent:e.intent,signal:e.signal,fingerprint:e.fingerprint,attempt:e.attempt,createdAt:e.createdAt,steps:e.steps,meta:e.meta,lastError:e.lastError});let r={done:Array.from(f.entries()).map(([e,t])=>({partNumber:e,etag:t.etag,size:t.size})).sort((e,t)=>e.partNumber-t.partNumber),completed:!0};e.persistCursor(r)}}}}let d=!1;function f(e={}){let n=e.allowedHosts??[],r=e.allowPrivateHosts===!0;return{id:`post`,resumable:!1,async start(a){let o=a.intent;if(!o.url)throw new t(`validation_failed`,{message:`post.start: intent missing url`});n.length===0&&!d&&(d=!0,console.warn("[duck-upload] PostStrategy: no `allowedHosts` configured. Presigned POST URLs will be host-unrestricted. Set PostStrategy.Config.allowedHosts to lock the upload host.")),i(o.url,`post.intent`,{allowedHosts:n,allowPrivateHosts:r}),await s(()=>a.transport.postForm({url:o.url,file:a.file,fields:o.fields,filename:a.file.name,signal:a.signal,onProgress(e,t){a.reportProgress({uploadedBytes:e,totalBytes:t})}}),{signal:a.signal,...e.maxRetries===void 0?{}:{maxRetries:e.maxRetries}})}}}let p=!1;function m(e={}){let n=e.allowedHosts??[],r=e.allowPrivateHosts===!0;return{id:`put`,resumable:!1,async start(a){let o=a.intent;if(!o.url)throw new t(`validation_failed`,{message:`put.start: intent missing url`});n.length===0&&!p&&(p=!0,console.warn("[duck-upload] PutStrategy: no `allowedHosts` configured. Presigned PUT URLs will be host-unrestricted. Set PutStrategy.Config.allowedHosts to lock the upload host.")),i(o.url,`put.intent`,{allowedHosts:n,allowPrivateHosts:r});let c=a.file.size;await s(()=>a.transport.put({url:o.url,body:a.file,headers:o.headers??{},signal:a.signal,onProgress(e,t){a.reportProgress({uploadedBytes:e,totalBytes:t||c})}}),{signal:a.signal,...e.maxRetries===void 0?{}:{maxRetries:e.maxRetries}})}}}function h(){let e={};return{get(t){return e[t]},has(t){return Object.hasOwn(e,t)},set(t){e[t.id]=t}}}let g=!1;function _(e,t){let n=e?.[t]??e?.[t.toLowerCase()];if(n===void 0)return null;let r=Number(n);return Number.isInteger(r)&&r>=0?r:null}function v(e={}){let n=e.allowedHosts??[],r=e.allowPrivateHosts===!0,a=e.chunkSize,o=e.maxRetries===void 0?{}:{maxRetries:e.maxRetries};return{id:`tus`,resumable:!0,async start(e){let c=e.intent;if(!c.url)throw new t(`validation_failed`,{message:`tus.start: intent missing url`});n.length===0&&!g&&(g=!0,console.warn("[duck-upload] TusStrategy: no `allowedHosts` configured. tus upload URLs will be host-unrestricted. Set TusStrategy.Config.allowedHosts to lock the upload host.")),i(c.url,`tus.intent`,{allowedHosts:n,allowPrivateHosts:r});let l=c.url,u=e.file.size,d=Math.max(1,c.chunkSize??a??8388608),f={"Tus-Resumable":`1.0.0`,...c.headers??{}},p=e.readCursor()?.offset??0;if(e.transport.head){let t=e.transport.head;try{let n=_((await s(()=>t({url:l,headers:f,signal:e.signal}),{signal:e.signal,...o})).headers,`upload-offset`);n!==null&&(p=n)}catch(t){if(e.signal?.aborted||t instanceof Error&&t.name===`AbortError`)throw t}}for(p>u&&(p=u),e.reportProgress({uploadedBytes:p,totalBytes:u});p<u;){if(e.signal?.aborted)throw new DOMException(`The operation was aborted.`,`AbortError`);let n=p,r=Math.min(u,n+d),i=e.file.slice(n,r),a=_((await s(()=>e.transport.patch({url:l,body:i,headers:{...f,"Upload-Offset":String(n),"Content-Type":`application/offset+octet-stream`},signal:e.signal,onProgress:t=>{e.reportProgress({uploadedBytes:n+t,totalBytes:u})}}),{signal:e.signal,...o})).headers,`upload-offset`);if(p=a===null?r:a,p<=n)throw new t(`upload_failed`,{message:`tus: server did not advance Upload-Offset (stuck at ${p} of ${u}).`});e.persistCursor({offset:p}),e.reportProgress({uploadedBytes:p,totalBytes:u})}}}}export{u as a,f as i,h as n,m as r,v as t};

package/package.json

@@ -1,11 +1,12 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@gentleduck/upload",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -52,7 +53,7 @@
     "tsdown": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:",
-    "vitest": "^4.0.18"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/__tests__/emitter.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test, vi } from 'vitest'
+import { createTypedEmitter } from '../core/utils/emitter'
+
+type Events = { foo: { x: number }; bar: { y: string } }
+
+describe('createTypedEmitter', () => {
+  test('emits to subscribers', () => {
+    const e = createTypedEmitter<Events>()
+    const fn = vi.fn()
+    e.on('foo', fn)
+    e.emit('foo', { x: 1 })
+    e.emit('foo', { x: 2 })
+    expect(fn).toHaveBeenCalledTimes(2)
+    expect(fn).toHaveBeenNthCalledWith(1, { x: 1 })
+    expect(fn).toHaveBeenNthCalledWith(2, { x: 2 })
+  })
+
+  test('does not invoke unrelated handlers', () => {
+    const e = createTypedEmitter<Events>()
+    const fooFn = vi.fn()
+    const barFn = vi.fn()
+    e.on('foo', fooFn)
+    e.on('bar', barFn)
+    e.emit('bar', { y: 'z' })
+    expect(fooFn).not.toHaveBeenCalled()
+    expect(barFn).toHaveBeenCalledOnce()
+  })
+
+  test('on returns unsubscriber', () => {
+    const e = createTypedEmitter<Events>()
+    const fn = vi.fn()
+    const off = e.on('foo', fn)
+    off()
+    e.emit('foo', { x: 1 })
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  test('off detaches listener', () => {
+    const e = createTypedEmitter<Events>()
+    const fn = vi.fn()
+    e.on('foo', fn)
+    e.off('foo', fn)
+    e.emit('foo', { x: 1 })
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  test('isolates throwing listeners', () => {
+    const e = createTypedEmitter<Events>()
+    const ok = vi.fn()
+    e.on('foo', () => {
+      throw new Error('boom')
+    })
+    e.on('foo', ok)
+    expect(() => e.emit('foo', { x: 1 })).not.toThrow()
+    expect(ok).toHaveBeenCalledOnce()
+  })
+
+  test('subsequent on() adds the listener for future emits', () => {
+    const e = createTypedEmitter<Events>()
+    const a: number[] = []
+    const b: number[] = []
+    e.on('foo', (p: any) => a.push(p.x))
+    e.on('foo', (p: any) => b.push(p.x))
+
+    for (let i = 0; i < 5; i++) e.emit('foo', { x: i })
+    expect(a).toEqual([0, 1, 2, 3, 4])
+    expect(b).toEqual([0, 1, 2, 3, 4])
+
+    const c: number[] = []
+    e.on('foo', (p: any) => c.push(p.x))
+    e.emit('foo', { x: 99 })
+    expect(c).toEqual([99])
+    expect(a).toEqual([0, 1, 2, 3, 4, 99])
+  })
+
+  test('off() with a non-subscribed callback is a no-op', () => {
+    const e = createTypedEmitter<Events>()
+    const tracker: number[] = []
+    e.on('foo', (p: any) => tracker.push(p.x))
+    const unrelated = (p: { x: number }) => tracker.push(-p.x)
+    expect(() => e.off('foo', unrelated)).not.toThrow()
+    e.emit('foo', { x: 7 })
+    expect(tracker).toEqual([7])
+  })
+})

package/src/__tests__/fingerprint.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from 'vitest'
+import { computeFingerprint, fingerprintMatches } from '../core/utils/fingerprint'
+
+function fileOf(name: string, content: string, type = 'text/plain', lastModified = 0): File {
+  return new File([content], name, { type, lastModified })
+}
+
+describe('computeFingerprint', () => {
+  test('captures name, size, type, lastModified', () => {
+    const f = fileOf('a.txt', 'hello', 'text/plain', 1234)
+    expect(computeFingerprint(f)).toEqual({
+      name: 'a.txt',
+      size: 5,
+      type: f.type,
+      lastModified: 1234,
+    })
+  })
+})
+
+describe('fingerprintMatches', () => {
+  test('same identity matches', () => {
+    const f = fileOf('a.txt', 'hello', 'text/plain', 1234)
+    expect(fingerprintMatches(computeFingerprint(f), computeFingerprint(f))).toBe(true)
+  })
+
+  test('different name does not match', () => {
+    const a = computeFingerprint(fileOf('a.txt', 'hello'))
+    const b = computeFingerprint(fileOf('b.txt', 'hello'))
+    expect(fingerprintMatches(a, b)).toBe(false)
+  })
+
+  test('different size does not match', () => {
+    const a = computeFingerprint(fileOf('a.txt', 'hello'))
+    const b = computeFingerprint(fileOf('a.txt', 'hello!'))
+    expect(fingerprintMatches(a, b)).toBe(false)
+  })
+
+  test('different lastModified does not match', () => {
+    const a = computeFingerprint(fileOf('a.txt', 'hello', 'text/plain', 1))
+    const b = computeFingerprint(fileOf('a.txt', 'hello', 'text/plain', 2))
+    expect(fingerprintMatches(a, b)).toBe(false)
+  })
+
+  test('type difference is intentionally ignored', () => {
+    const a = computeFingerprint(fileOf('a', 'hello', 'text/plain', 1))
+    const b = computeFingerprint(fileOf('a', 'hello', 'application/octet-stream', 1))
+    expect(fingerprintMatches(a, b)).toBe(true)
+  })
+})

package/src/__tests__/guards.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from 'vitest'
+import { isRecord } from '../core/utils/guards'
+
+describe('isRecord', () => {
+  test('plain object', () => {
+    expect(isRecord({})).toBe(true)
+    expect(isRecord({ a: 1 })).toBe(true)
+  })
+
+  test('null', () => {
+    expect(isRecord(null)).toBe(false)
+  })
+
+  test('undefined', () => {
+    expect(isRecord(undefined)).toBe(false)
+  })
+
+  test('primitives', () => {
+    expect(isRecord(0)).toBe(false)
+    expect(isRecord('a')).toBe(false)
+    expect(isRecord(true)).toBe(false)
+  })
+
+  test('arrays are rejected', () => {
+    expect(isRecord([])).toBe(false)
+    expect(isRecord([1, 2, 3])).toBe(false)
+  })
+
+  test('exotic objects are rejected', () => {
+    expect(isRecord(new Date())).toBe(false)
+    expect(isRecord(new Map())).toBe(false)
+    expect(isRecord(new Set())).toBe(false)
+    class Foo {}
+    expect(isRecord(new Foo())).toBe(false)
+  })
+
+  test('null-prototype objects are accepted', () => {
+    expect(isRecord(Object.create(null))).toBe(true)
+  })
+})

package/src/__tests__/id.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, describe, expect, test } from 'vitest'
+import { generateId } from '../core/utils/id'
+
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+describe('generateId', () => {
+  test('starts with the `upload_` prefix', () => {
+    expect(generateId()).toMatch(/^upload_/)
+  })
+
+  test('embeds a v4 UUID after the timestamp', () => {
+    const id = generateId()
+    const match = id.match(/^upload_(\d+)_(.+)$/)
+    expect(match).not.toBeNull()
+    expect(match![2]).toMatch(UUID_V4)
+  })
+
+  test('produces 1000 unique IDs (collision-resistance smoke)', () => {
+    const set = new Set<string>()
+    for (let i = 0; i < 1000; i++) set.add(generateId())
+    expect(set.size).toBe(1000)
+  })
+
+  test('produces unique values across many calls', () => {
+    const set = new Set<string>()
+    for (let i = 0; i < 10_000; i++) set.add(generateId())
+    expect(set.size).toBe(10_000)
+  })
+})
+
+describe('generateId  fallback path (no crypto.randomUUID)', () => {
+  const originalCrypto = (globalThis as { crypto?: Crypto }).crypto
+
+  afterEach(() => {
+    // Restore the original crypto reference for subsequent tests.
+    Object.defineProperty(globalThis, 'crypto', {
+      value: originalCrypto,
+      configurable: true,
+      writable: true,
+    })
+  })
+
+  test('falls back to getRandomValues and still produces a v4-shaped UUID', () => {
+    const fakeCrypto = {
+      // Simulate a runtime that lacks randomUUID but has getRandomValues.
+      getRandomValues: (arr: any) => originalCrypto!.getRandomValues(arr),
+    } as unknown as Crypto
+    Object.defineProperty(globalThis, 'crypto', {
+      value: fakeCrypto,
+      configurable: true,
+      writable: true,
+    })
+    const id = generateId()
+    const match = id.match(/^upload_\d+_(.+)$/)
+    expect(match).not.toBeNull()
+    expect(match![1]).toMatch(UUID_V4)
+  })
+
+  test('throws when neither randomUUID nor getRandomValues are available', () => {
+    Object.defineProperty(globalThis, 'crypto', {
+      value: {} as Crypto,
+      configurable: true,
+      writable: true,
+    })
+    expect(() => generateId()).toThrow(/CSPRNG/)
+  })
+})

package/src/__tests__/mime-sniff.test.ts

@@ -0,0 +1,142 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { validateMimeSignature } from '../core/engine/validation/mime'
+import { __mimeWarnings, mimeMatches, sniffMime } from '../core/utils/mime-sniff'
+
+function bytes(...arr: number[]): Uint8Array<ArrayBuffer> {
+  return new Uint8Array(arr)
+}
+
+describe('sniffMime', () => {
+  test('detects JPEG (FF D8 FF)', () => {
+    expect(sniffMime(bytes(0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10))).toBe('image/jpeg')
+  })
+
+  test('detects PNG (89 50 4E 47 0D 0A 1A 0A)', () => {
+    expect(sniffMime(bytes(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a))).toBe('image/png')
+  })
+
+  test('detects GIF (47 49 46 38)', () => {
+    expect(sniffMime(bytes(0x47, 0x49, 0x46, 0x38, 0x39, 0x61))).toBe('image/gif')
+  })
+
+  test('detects PDF (%PDF)', () => {
+    expect(sniffMime(bytes(0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34))).toBe('application/pdf')
+  })
+
+  test('detects ZIP family (PK..)', () => {
+    expect(sniffMime(bytes(0x50, 0x4b, 0x03, 0x04, 0x14, 0x00))).toBe('application/zip')
+  })
+
+  test('detects MP4 ftyp box', () => {
+    expect(sniffMime(bytes(0x00, 0x00, 0x00, 0x20, 0x66, 0x74, 0x79, 0x70, 0x69, 0x73, 0x6f, 0x6d))).toBe('video/mp4')
+  })
+
+  test('detects WebP (RIFF....WEBP)', () => {
+    expect(sniffMime(bytes(0x52, 0x49, 0x46, 0x46, 0x24, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50))).toBe('image/webp')
+  })
+
+  test('detects WebM/Matroska', () => {
+    expect(sniffMime(bytes(0x1a, 0x45, 0xdf, 0xa3, 0x9f, 0x42))).toBe('video/webm')
+  })
+
+  test('detects MP3 ID3 tag', () => {
+    expect(sniffMime(bytes(0x49, 0x44, 0x33, 0x04, 0x00, 0x00))).toBe('audio/mpeg')
+  })
+
+  test('detects MP3 raw frame sync (FF FB)', () => {
+    expect(sniffMime(bytes(0xff, 0xfb, 0x90, 0x00))).toBe('audio/mpeg')
+  })
+
+  test('returns null on unknown bytes', () => {
+    expect(sniffMime(bytes(0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b))).toBeNull()
+  })
+
+  test('returns null on too-short buffers', () => {
+    expect(sniffMime(bytes(0xff))).toBeNull()
+  })
+})
+
+describe('mimeMatches', () => {
+  test('null sniff is always a match (unknown is not deny)', () => {
+    expect(mimeMatches('image/jpeg', null)).toBe(true)
+  })
+
+  test('exact match', () => {
+    expect(mimeMatches('image/jpeg', 'image/jpeg')).toBe(true)
+  })
+
+  test('empty / octet-stream claim is always a match (no claim made)', () => {
+    expect(mimeMatches('', 'image/jpeg')).toBe(true)
+    expect(mimeMatches('application/octet-stream', 'application/pdf')).toBe(true)
+  })
+
+  test('JPEG common aliases', () => {
+    expect(mimeMatches('image/jpg', 'image/jpeg')).toBe(true)
+    expect(mimeMatches('image/pjpeg', 'image/jpeg')).toBe(true)
+  })
+
+  test('Office DOCX is consistent with ZIP signature', () => {
+    expect(
+      mimeMatches('application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/zip'),
+    ).toBe(true)
+  })
+
+  test('JPEG bytes with claimed PDF type  mismatch', () => {
+    expect(mimeMatches('application/pdf', 'image/jpeg')).toBe(false)
+  })
+})
+
+describe('validateMimeSignature', () => {
+  beforeEach(() => {
+    __mimeWarnings.clear()
+  })
+
+  test('JPEG bytes with claimed PDF type → rejected when strict', async () => {
+    const file = new File([bytes(0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10)], 'evil.pdf', { type: 'application/pdf' })
+    const reason = await validateMimeSignature(file, true)
+    expect(reason).toEqual({ code: 'mime_mismatch', claimed: 'application/pdf', sniffed: 'image/jpeg' })
+  })
+
+  test('JPEG bytes with claimed PDF type → null + console.warn when not strict', async () => {
+    const file = new File([bytes(0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10)], 'evil.pdf', { type: 'application/pdf' })
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const reason = await validateMimeSignature(file, false)
+    expect(reason).toBeNull()
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(String(warnSpy.mock.calls[0]?.[0] ?? '')).toMatch(/MIME mismatch/)
+    // Filename must not appear in the warning: it is untrusted input.
+    expect(String(warnSpy.mock.calls[0]?.[0] ?? '')).not.toMatch(/evil\.pdf/)
+    warnSpy.mockRestore()
+  })
+
+  test('repeated identical mismatches only warn once', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    for (let i = 0; i < 3; i++) {
+      const file = new File([bytes(0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10)], `f-${i}.pdf`, { type: 'application/pdf' })
+      await validateMimeSignature(file, false)
+    }
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    warnSpy.mockRestore()
+  })
+
+  test('matching JPEG+JPEG → accepted', async () => {
+    const file = new File([bytes(0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10)], 'ok.jpg', { type: 'image/jpeg' })
+    expect(await validateMimeSignature(file, true)).toBeNull()
+  })
+
+  test('unknown bytes → accepted (sniff returns null, no mismatch)', async () => {
+    const file = new File(
+      [bytes(0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b)],
+      'mystery.dat',
+      {
+        type: 'application/pdf',
+      },
+    )
+    expect(await validateMimeSignature(file, true)).toBeNull()
+  })
+
+  test('empty file → null (defers to other validators)', async () => {
+    const file = new File([], 'empty.bin')
+    expect(await validateMimeSignature(file, true)).toBeNull()
+  })
+})