@mieweb/pulsevault 0.0.1

package/dist/lib/deeplinks.d.ts

@@ -0,0 +1,32 @@
+export type ConfigureDestinationLinkOptions = {
+    /** Full origin of the PulseVault server, e.g. `https://example.com` or `http://192.168.1.10:3030`. */
+    server: string;
+    /** Opaque token forwarded to the server's `authorize` hook. Omit for unauthenticated servers. */
+    token?: string;
+    /** Human-readable name shown in the Pulse app's destination list. Defaults to the server hostname. */
+    name?: string;
+};
+export type UploadLinkOptions = {
+    /** Full origin of the PulseVault server. */
+    server: string;
+    /** Opaque token forwarded to the server's `authorize` hook. Omit for unauthenticated servers. */
+    token?: string;
+    /**
+     * Server-side video UUID. Used as both the app's local draft key and the
+     * `videoid` in `Upload-Metadata`, so the app skips `POST /reserve`.
+     * Generate with `crypto.randomUUID()`.
+     */
+    videoid: string;
+};
+/**
+ * Build a `pulsecam://` deep link that adds this server as a saved upload
+ * destination in the Pulse app. No server request is made when the link is
+ * opened — the app stores the config locally.
+ */
+export declare function buildConfigureDestinationLink(opts: ConfigureDestinationLinkOptions): string;
+/**
+ * Build a `pulsecam://` deep link that opens the Pulse app directly on the
+ * upload screen for a specific draft, pointed at this server.
+ */
+export declare function buildUploadLink(opts: UploadLinkOptions): string;
+//# sourceMappingURL=deeplinks.d.ts.map

package/dist/lib/deeplinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplinks.d.ts","sourceRoot":"","sources":["../../src/lib/deeplinks.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,sGAAsG;IACtG,MAAM,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sGAAsG;IACtG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,+BAA+B,GACpC,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAI/D"}

package/dist/lib/deeplinks.js

@@ -0,0 +1,24 @@
+/**
+ * Build a `pulsecam://` deep link that adds this server as a saved upload
+ * destination in the Pulse app. No server request is made when the link is
+ * opened — the app stores the config locally.
+ */
+export function buildConfigureDestinationLink(opts) {
+    const params = new URLSearchParams({ mode: "configure_destination", server: opts.server });
+    if (opts.token)
+        params.set("token", opts.token);
+    if (opts.name)
+        params.set("name", opts.name);
+    return `pulsecam://?${params.toString()}`;
+}
+/**
+ * Build a `pulsecam://` deep link that opens the Pulse app directly on the
+ * upload screen for a specific draft, pointed at this server.
+ */
+export function buildUploadLink(opts) {
+    const params = new URLSearchParams({ mode: "upload", videoid: opts.videoid, server: opts.server });
+    if (opts.token)
+        params.set("token", opts.token);
+    return `pulsecam://?${params.toString()}`;
+}
+//# sourceMappingURL=deeplinks.js.map

package/dist/lib/deeplinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplinks.js","sourceRoot":"","sources":["../../src/lib/deeplinks.ts"],"names":[],"mappings":"AAsBA;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,IAAqC;IAErC,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,uBAAuB,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3F,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAChD,IAAI,IAAI,CAAC,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,eAAe,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAuB;IACrD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACnG,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAChD,OAAO,eAAe,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC5C,CAAC"}

package/dist/lib/errors.d.ts

@@ -0,0 +1,6 @@
+export type PulseVaultErrorBody = {
+    ok: false;
+    error: string;
+};
+export declare function pulseVaultError(error: string): PulseVaultErrorBody;
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAElE"}

package/dist/lib/errors.js

@@ -0,0 +1,4 @@
+export function pulseVaultError(error) {
+    return { ok: false, error };
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC"}

package/dist/lib/magic.d.ts

@@ -0,0 +1,50 @@
+import type { FastifyRequest } from "fastify";
+import type { LocalStorage } from "../storage/local.js";
+/**
+ * Optional plugin-level hook: after TUS writes the final byte but before the
+ * upload is marked ready (or the consumer's `onUploadComplete` runs),
+ * validate the payload bytes. Throw to reject — the plugin translates the
+ * throw into a 422 response, calls `storage.remove?.(videoid)` to free the
+ * disk, and never flips the sidecar to `"ready"`.
+ *
+ * The `localPath` field is populated for adapters that expose
+ * `getLocalPath` (the built-in local adapter does). For adapters whose
+ * bytes don't live on local disk (S3, etc.), `localPath` is `null` and the
+ * validator has to fetch bytes through whatever API the adapter provides.
+ */
+export type PulseVaultValidatePayload = (request: FastifyRequest, ctx: {
+    videoid: string;
+    size: number;
+    uploadId: string;
+    /** Absolute local path to the finalized bytes, or `null` if unavailable. */
+    localPath: string | null;
+}) => void | Promise<void>;
+/**
+ * Check whether a file's first bytes match the ISO base media file format
+ * (`ftyp` box at offset 4), which covers MP4, MOV, M4V, 3GP, and related
+ * containers. This is the same check tools like `file(1)` and ffprobe use
+ * to identify MP4-family videos.
+ *
+ * Not a full MP4 parse — just a ~12-byte sniff. Enough to reject uploads
+ * that are obviously not video (PDFs, HTML, random bytes) before the
+ * server ever serves them back as `video/mp4`.
+ */
+export declare function sniffMp4(filePath: string): Promise<boolean>;
+/**
+ * Build a `validatePayload` hook that enforces every uploaded file is a
+ * valid MP4-family container. Only works with `LocalStorage` (or any
+ * adapter that exposes `getLocalPath`) — pulls the path from the storage
+ * and runs `sniffMp4` against it.
+ *
+ * Usage:
+ * ```ts
+ * const storage = createLocalStorage({ workspaceDir: "./data" });
+ * await app.register(pulseVault, {
+ *   storage,
+ *   validatePayload: createMp4Sniffer(storage),
+ *   // ...
+ * });
+ * ```
+ */
+export declare function createMp4Sniffer(storage: LocalStorage): PulseVaultValidatePayload;
+//# sourceMappingURL=magic.d.ts.map

package/dist/lib/magic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic.d.ts","sourceRoot":"","sources":["../../src/lib/magic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,KACE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,YAAY,GACpB,yBAAyB,CAmB3B"}

package/dist/lib/magic.js

@@ -0,0 +1,66 @@
+import fs from "node:fs/promises";
+/**
+ * Check whether a file's first bytes match the ISO base media file format
+ * (`ftyp` box at offset 4), which covers MP4, MOV, M4V, 3GP, and related
+ * containers. This is the same check tools like `file(1)` and ffprobe use
+ * to identify MP4-family videos.
+ *
+ * Not a full MP4 parse — just a ~12-byte sniff. Enough to reject uploads
+ * that are obviously not video (PDFs, HTML, random bytes) before the
+ * server ever serves them back as `video/mp4`.
+ */
+export async function sniffMp4(filePath) {
+    let fd;
+    try {
+        fd = await fs.open(filePath, "r");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const buf = Buffer.alloc(12);
+        const { bytesRead } = await fd.read(buf, 0, 12, 0);
+        if (bytesRead < 12)
+            return false;
+        // Bytes 4..7 must spell "ftyp" (ASCII 0x66 0x74 0x79 0x70). The first
+        // four bytes are the box size and the remaining four after "ftyp" are
+        // the brand (e.g. "isom", "mp42", "qt  ") — brand validation is left
+        // to downstream tools.
+        return (buf[4] === 0x66 &&
+            buf[5] === 0x74 &&
+            buf[6] === 0x79 &&
+            buf[7] === 0x70);
+    }
+    finally {
+        await fd.close();
+    }
+}
+/**
+ * Build a `validatePayload` hook that enforces every uploaded file is a
+ * valid MP4-family container. Only works with `LocalStorage` (or any
+ * adapter that exposes `getLocalPath`) — pulls the path from the storage
+ * and runs `sniffMp4` against it.
+ *
+ * Usage:
+ * ```ts
+ * const storage = createLocalStorage({ workspaceDir: "./data" });
+ * await app.register(pulseVault, {
+ *   storage,
+ *   validatePayload: createMp4Sniffer(storage),
+ *   // ...
+ * });
+ * ```
+ */
+export function createMp4Sniffer(storage) {
+    return async (_request, { videoid }) => {
+        const localPath = await storage.getLocalPath(videoid);
+        if (!localPath) {
+            throw Object.assign(new Error(`Cannot validate upload ${videoid}: no local path available`), { statusCode: 500 });
+        }
+        const ok = await sniffMp4(localPath);
+        if (!ok) {
+            throw Object.assign(new Error("Uploaded bytes are not a valid MP4 (missing ftyp header)"), { statusCode: 422 });
+        }
+    };
+}
+//# sourceMappingURL=magic.js.map

package/dist/lib/magic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic.js","sourceRoot":"","sources":["../../src/lib/magic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AA2BlC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB;IAC7C,IAAI,EAAiB,CAAC;IACtB,IAAI,CAAC;QACH,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7B,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QACnD,IAAI,SAAS,GAAG,EAAE;YAAE,OAAO,KAAK,CAAC;QACjC,sEAAsE;QACtE,sEAAsE;QACtE,qEAAqE;QACrE,uBAAuB;QACvB,OAAO,CACL,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;YACf,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;YACf,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;YACf,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,CAChB,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAqB;IAErB,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACrC,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACtD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,MAAM,CACjB,IAAI,KAAK,CACP,0BAA0B,OAAO,2BAA2B,CAC7D,EACD,EAAE,UAAU,EAAE,GAAG,EAAE,CACpB,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,MAAM,CAAC,MAAM,CACjB,IAAI,KAAK,CAAC,0DAA0D,CAAC,EACrE,EAAE,UAAU,EAAE,GAAG,EAAE,CACpB,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/pulsevaultTus.d.ts

@@ -0,0 +1,56 @@
+import { Server } from "@tus/server";
+import type { FastifyRequest } from "fastify";
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { PulseVaultValidatePayload } from "./magic.js";
+import type { PulseVaultStorage } from "../storage/types.js";
+/**
+ * Context the plugin stashes on each incoming Fastify request for the lifetime
+ * of a TUS call. Shared with the tus hooks via `AsyncLocalStorage` because
+ * `@tus/server` v2 hooks receive a web `Request`, not the FastifyRequest.
+ */
+export type PulseVaultTusContext = {
+    request: FastifyRequest;
+    videoid?: string;
+};
+export declare const pulseVaultTusContext: AsyncLocalStorage<PulseVaultTusContext>;
+export type PulseVaultOnUploadComplete = (request: FastifyRequest, ctx: {
+    videoid: string;
+    size: number;
+    uploadId: string;
+}) => void | Promise<void>;
+export type PulsevaultTusOptions = {
+    storage: PulseVaultStorage;
+    /** Absolute URL path where TUS is mounted, e.g. `/pulsevault/upload`. */
+    tusPath: string;
+    /** Max total upload size in bytes. Use `Infinity` for no cap. */
+    maxSize: number;
+    /**
+     * File extensions allowed in the upload `filename` metadata. Must be
+     * pre-normalized to lowercase and include the leading dot.
+     */
+    allowedExtensions: readonly string[];
+    /**
+     * Optional payload-validation hook. Runs after TUS writes the final byte
+     * but before `markReady` and `onUploadComplete`. Throwing from this hook
+     * causes the plugin to `storage.remove?.(videoid)` and return a 4xx
+     * (default 422) to the client. Use for magic-byte sniffing, virus
+     * scanning, size re-checks — anything that needs the final bytes.
+     */
+    validatePayload?: PulseVaultValidatePayload;
+    /**
+     * Fired once the final byte of an upload has been written *and* any
+     * `validatePayload` has passed. Use this to flip consumer state (DB row,
+     * queue job, audit log). Throwing here returns a 500 — bytes are on disk
+     * and marked ready, but consumer-side work failed.
+     */
+    onUploadComplete?: PulseVaultOnUploadComplete;
+};
+/**
+ * Shape `@tus/server` recognizes for sending an error response. We tag both
+ * `statusCode` and `status_code` so throws originating from either Fastify
+ * conventions (camelCase) or the tus convention (snake_case) surface with the
+ * right HTTP status.
+ */
+export declare function tusError(status: number, body: string): Error;
+export declare function createPulsevaultTusServer(options: PulsevaultTusOptions): Server;
+//# sourceMappingURL=pulsevaultTus.d.ts.map

package/dist/lib/pulsevaultTus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pulsevaultTus.d.ts","sourceRoot":"","sources":["../../src/lib/pulsevaultTus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,oBAAoB,yCAAgD,CAAC;AAElF,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,KACrD,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;CAC/C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAM5D;AAmBD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,oBAAoB,UAyHtE"}

package/dist/lib/pulsevaultTus.js

@@ -0,0 +1,146 @@
+import { Server } from "@tus/server";
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+import { isUuid } from "./uuid.js";
+export const pulseVaultTusContext = new AsyncLocalStorage();
+/**
+ * Shape `@tus/server` recognizes for sending an error response. We tag both
+ * `statusCode` and `status_code` so throws originating from either Fastify
+ * conventions (camelCase) or the tus convention (snake_case) surface with the
+ * right HTTP status.
+ */
+export function tusError(status, body) {
+    return Object.assign(new Error(body), {
+        statusCode: status,
+        status_code: status,
+        body,
+    });
+}
+/** Parse the first path segment of a tus upload id as the videoid. */
+function videoidFromUploadId(id) {
+    const first = id.split("/", 1)[0];
+    return isUuid(first) ? first : undefined;
+}
+/**
+ * Extract a numeric HTTP status from a thrown error, honoring both
+ * `statusCode` (Fastify) and `status_code` (tus).
+ */
+function statusCodeOf(err, fallback) {
+    const e = err;
+    if (typeof e?.statusCode === "number")
+        return e.statusCode;
+    if (typeof e?.status_code === "number")
+        return e.status_code;
+    return fallback;
+}
+export function createPulsevaultTusServer(options) {
+    const { storage, tusPath, maxSize, allowedExtensions, validatePayload, onUploadComplete, } = options;
+    return new Server({
+        path: tusPath,
+        datastore: storage.datastore,
+        maxSize,
+        namingFunction: async (_req, metadata) => {
+            const videoid = metadata?.videoid ?? "";
+            const filename = (metadata?.filename ?? "").trim();
+            if (!isUuid(videoid)) {
+                throw tusError(400, "Upload-Metadata must include a valid `videoid` (UUID).\n");
+            }
+            const ext = path.extname(filename).toLowerCase();
+            if (!ext || !allowedExtensions.includes(ext)) {
+                throw tusError(400, `Upload-Metadata \`filename\` must end with one of: ${allowedExtensions.join(", ")}\n`);
+            }
+            return storage.reserveUpload({ videoid, filename, ext });
+        },
+        generateUrl(_req, { proto, host, path: tusBasePath, id }) {
+            const encoded = Buffer.from(id, "utf8").toString("base64url");
+            return `${proto}://${host}${tusBasePath}/${encoded}`;
+        },
+        getFileIdFromRequest(_req, lastPath) {
+            if (!lastPath) {
+                return;
+            }
+            return Buffer.from(lastPath, "base64url").toString("utf8");
+        },
+        onUploadFinish: async (_req, upload) => {
+            // Completion sequence: validate → markReady → consumer hook. Each step
+            // gates the next; failure anywhere short-circuits with a tus error
+            // (and cleans up disk state for validation failures specifically).
+            const store = pulseVaultTusContext.getStore();
+            if (!store) {
+                // Should not happen — the Fastify layer always establishes a store
+                // before calling into tus. Bail quietly rather than crash.
+                return {};
+            }
+            const videoid = videoidFromUploadId(upload.id);
+            if (!videoid) {
+                return {};
+            }
+            const size = upload.size ?? 0;
+            const uploadId = upload.id;
+            // 1. Validate payload (magic bytes, virus scan, etc.). If this throws
+            //    we wipe the bytes from storage — the client gets a 4xx, the
+            //    sidecar is gone, and they can safely retry with a corrected file.
+            if (validatePayload) {
+                try {
+                    await validatePayload(store.request, {
+                        videoid,
+                        size,
+                        uploadId,
+                        localPath: await resolveLocalPath(storage, videoid),
+                    });
+                }
+                catch (err) {
+                    const status = statusCodeOf(err, 422);
+                    const message = err instanceof Error ? err.message : "Payload validation failed";
+                    try {
+                        await storage.remove?.(videoid);
+                    }
+                    catch (rmErr) {
+                        store.request.log.error({ err: rmErr, videoid }, "pulsevault failed to remove rejected upload");
+                    }
+                    throw tusError(status, `${message}\n`);
+                }
+            }
+            // 2. Flip the sidecar to "ready" so `resolve` will serve the bytes.
+            //    Done *before* the consumer hook so a downstream service that
+            //    reacts to `onUploadComplete` can immediately GET the video.
+            try {
+                await storage.markReady?.(videoid);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "markReady failed";
+                throw tusError(500, `${message}\n`);
+            }
+            // 3. Consumer hook — business logic (DB writes, queue jobs).
+            if (onUploadComplete) {
+                try {
+                    await onUploadComplete(store.request, { videoid, size, uploadId });
+                }
+                catch (err) {
+                    // Propagate as a tus error so the client sees a non-2xx and can
+                    // distinguish "bytes stored but completion hook failed" from
+                    // success. The video is marked ready at this point — consumers
+                    // who want "all-or-nothing" should `storage.remove` before
+                    // throwing.
+                    const message = err instanceof Error ? err.message : "onUploadComplete failed";
+                    throw tusError(500, `${message}\n`);
+                }
+            }
+            return {};
+        },
+    });
+}
+/**
+ * If the adapter exposes `getLocalPath` (the built-in local adapter does),
+ * resolve the videoid to an absolute disk path for `validatePayload`. For
+ * other adapters, returns `null` and the validator is expected to fetch
+ * bytes through whatever API it knows about.
+ */
+async function resolveLocalPath(storage, videoid) {
+    const candidate = storage.getLocalPath;
+    if (typeof candidate !== "function")
+        return null;
+    const result = await candidate(videoid);
+    return typeof result === "string" ? result : null;
+}
+//# sourceMappingURL=pulsevaultTus.js.map

package/dist/lib/pulsevaultTus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pulsevaultTus.js","sourceRoot":"","sources":["../../src/lib/pulsevaultTus.ts"],"names":[],"mappings":"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"}

package/dist/lib/uuid.d.ts

@@ -0,0 +1,2 @@
+export declare function isUuid(value: unknown): value is string;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/lib/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../src/lib/uuid.ts"],"names":[],"mappings":"AAGA,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEtD"}

package/dist/lib/uuid.js

@@ -0,0 +1,5 @@
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isUuid(value) {
+    return typeof value === "string" && UUID_REGEX.test(value);
+}
+//# sourceMappingURL=uuid.js.map

package/dist/lib/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../../src/lib/uuid.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GACd,iEAAiE,CAAC;AAEpE,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC"}

package/dist/routes/pulsevault.d.ts

@@ -0,0 +1,30 @@
+import type { FastifyPluginAsync, FastifyPluginOptions, FastifyRequest } from "fastify";
+import type { PulseVaultCacheOptions } from "../app.js";
+import { type PulseVaultOnUploadComplete } from "../lib/pulsevaultTus.js";
+import type { PulseVaultValidatePayload } from "../lib/magic.js";
+import type { PulseVaultStorage } from "../storage/types.js";
+declare module "fastify" {
+    interface FastifyRequest {
+        pulseVault?: {
+            videoid: string;
+        };
+    }
+}
+export type PulseVaultAuthorizePhase = "create" | "patch" | "resolve" | "delete";
+export type PulseVaultAuthorizeContext = {
+    phase: PulseVaultAuthorizePhase;
+    videoid: string;
+};
+export type PulseVaultAuthorize = (request: FastifyRequest, ctx: PulseVaultAuthorizeContext) => void | Promise<void>;
+export type PulseVaultRoutesOptions = {
+    storage: PulseVaultStorage;
+    maxUploadSize: number;
+    allowedExtensions: readonly string[];
+    cache?: PulseVaultCacheOptions;
+    authorize?: PulseVaultAuthorize;
+    validatePayload?: PulseVaultValidatePayload;
+    onUploadComplete?: PulseVaultOnUploadComplete;
+} & FastifyPluginOptions;
+declare const pulseVaultRoutes: FastifyPluginAsync<PulseVaultRoutesOptions>;
+export default pulseVaultRoutes;
+//# sourceMappingURL=pulsevault.d.ts.map

package/dist/routes/pulsevault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pulsevault.d.ts","sourceRoot":"","sources":["../../src/routes/pulsevault.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EAEpB,cAAc,EAEf,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAGjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,UAAU,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAClC;CACF;AAED,MAAM,MAAM,wBAAwB,GAChC,QAAQ,GACR,OAAO,GACP,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,EAAE,wBAAwB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,0BAA0B,KAC5B,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;CAC/C,GAAG,oBAAoB,CAAC;AA8JzB,QAAA,MAAM,gBAAgB,EAAE,kBAAkB,CAAC,uBAAuB,CA4NjE,CAAC;AAEF,eAAe,gBAAgB,CAAC"}