@mieweb/pulsevault 0.0.2 → 0.1.1

package/dist/lib/capability-token.js

@@ -0,0 +1,134 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const DEFAULT_EXPIRY_SECONDS = 1800; // 30 minutes — long enough for one upload session.
+const DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+function base64urlEncode(input) {
+    return Buffer.from(input, 'utf8').toString('base64url');
+}
+function sign(payload, secret) {
+    return createHmac('sha256', secret).update(payload).digest('base64url');
+}
+/** Constant-time string comparison, tolerant of mismatched lengths (returns `false` rather than throwing). */
+function timingSafeEqualStrings(a, b) {
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+/**
+ * Mint a stateless, HMAC-signed capability token scoped to one artifact (or
+ * session-anchor artifact). No server-side session table — verification is a
+ * pure function of `(token, secret)`, so the issuing deployment can rotate
+ * keys, change its TTL policy, or revoke at the artifact level entirely on
+ * its own schedule. See `createCapabilityAuthorize` to use this as the
+ * plugin's `authorize` hook directly.
+ */
+export function issueCapabilityToken(artifactId, secret, opts) {
+    const now = Math.floor(Date.now() / 1000);
+    const claims = {
+        artifactId,
+        iat: now,
+        exp: now + (opts.expirySeconds ?? DEFAULT_EXPIRY_SECONDS),
+        kid: opts.keyId,
+        issuer: opts.issuer,
+    };
+    const payload = base64urlEncode(JSON.stringify(claims));
+    return `${payload}.${sign(payload, secret)}`;
+}
+/**
+ * Verify a token minted by `issueCapabilityToken`. Returns the authorized
+ * `artifactId` on success, or `null` for any failure (malformed token,
+ * unknown `kid`, bad signature, expired, issued too far in the future, or
+ * issuer mismatch) — deliberately collapsed to one failure shape so callers
+ * can't accidentally branch on *why* a token failed and leak which part was
+ * wrong to an attacker.
+ */
+export function verifyCapabilityToken(token, lookupSecret, opts) {
+    const dot = token.indexOf('.');
+    if (dot < 0)
+        return null;
+    const payload = token.slice(0, dot);
+    const signature = token.slice(dot + 1);
+    if (!payload || !signature)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+    // Valid JSON that isn't an object (e.g. the literal `null`, a number, a
+    // string) must fail like every other malformed token — return null rather
+    // than throw on the property access below.
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const claims = parsed;
+    if (typeof claims.artifactId !== 'string' ||
+        typeof claims.iat !== 'number' ||
+        typeof claims.exp !== 'number' ||
+        typeof claims.kid !== 'string' ||
+        typeof claims.issuer !== 'string') {
+        return null;
+    }
+    const secret = lookupSecret(claims.kid);
+    if (!secret)
+        return null;
+    if (!timingSafeEqualStrings(signature, sign(payload, secret)))
+        return null;
+    const tolerance = opts.clockToleranceSeconds ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
+    const now = Math.floor(Date.now() / 1000);
+    if (claims.iat > now + tolerance)
+        return null;
+    if (claims.exp < now - tolerance)
+        return null;
+    if (claims.issuer !== opts.issuer)
+        return null;
+    return { artifactId: claims.artifactId };
+}
+/** Pull a bearer token from the `Authorization` header, falling back to `ctx.token` (the `resolve`-phase query-string forward). */
+function extractToken(request, ctx) {
+    const header = request.headers.authorization;
+    // Match the auth scheme case-insensitively per RFC 7235 (clients may send
+    // `bearer `/`BEARER `); the prefix is fixed-length so the slice is unchanged.
+    if (typeof header === 'string' && /^Bearer /i.test(header)) {
+        return header.slice('Bearer '.length);
+    }
+    return ctx.token;
+}
+/**
+ * Ready-made `authorize` hook backed by `verifyCapabilityToken`. Pass this
+ * directly as the plugin's `authorize` option for a secure-by-default setup
+ * with no custom auth code:
+ *
+ * ```ts
+ * await app.register(pulseVault, {
+ *   // ...
+ *   authorize: createCapabilityAuthorize((kid) => keys[kid] ?? null, {
+ *     issuer: "https://vault.acme-hospital.org",
+ *   }),
+ * });
+ * ```
+ *
+ * Authorizes the request if the token's `artifactId` matches either the
+ * artifact being acted on, or that artifact's `relatedTo` session anchor —
+ * so one token issued for a video also covers its captions/manifest/thumbnail
+ * and (under `uploadUnit: "segment"`) every clip and the ordering manifest
+ * uploaded in the same session, without minting a token per artifact.
+ */
+export function createCapabilityAuthorize(lookupSecret, opts) {
+    return async (request, ctx) => {
+        const token = extractToken(request, ctx);
+        if (!token) {
+            throw Object.assign(new Error('Missing capability token'), { statusCode: 401 });
+        }
+        const verified = verifyCapabilityToken(token, lookupSecret, opts);
+        if (!verified) {
+            throw Object.assign(new Error('Invalid or expired capability token'), { statusCode: 403 });
+        }
+        if (ctx.artifactId !== verified.artifactId && ctx.relatedTo !== verified.artifactId) {
+            throw Object.assign(new Error('Token does not authorize this artifact'), { statusCode: 403 });
+        }
+    };
+}
+//# sourceMappingURL=capability-token.js.map

package/dist/lib/capability-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-token.js","sourceRoot":"","sources":["../../src/lib/capability-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA0B1D,MAAM,sBAAsB,GAAG,IAAI,CAAC,CAAC,mDAAmD;AACxF,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAE3C,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,IAAI,CAAC,OAAe,EAAE,MAAc;IAC3C,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAC1E,CAAC;AAED,8GAA8G;AAC9G,SAAS,sBAAsB,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAkB,EAClB,MAAc,EACd,IAAiC;IAEjC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1C,MAAM,MAAM,GAA0B;QACpC,UAAU;QACV,GAAG,EAAE,GAAG;QACR,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,sBAAsB,CAAC;QACzD,GAAG,EAAE,IAAI,CAAC,KAAK;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC;IACF,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,OAAO,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC;AAC/C,CAAC;AAYD;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,YAA0B,EAC1B,IAAkC;IAElC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAExC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,wEAAwE;IACxE,0EAA0E;IAC1E,2CAA2C;IAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,MAAM,GAAG,MAAwC,CAAC;IACxD,IACE,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ;QACrC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;QAC9B,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;QAC9B,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;QAC9B,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,EACjC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,sBAAsB,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3E,MAAM,SAAS,GAAG,IAAI,CAAC,qBAAqB,IAAI,+BAA+B,CAAC;IAChF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;AAC3C,CAAC;AAED,mIAAmI;AACnI,SAAS,YAAY,CACnB,OAA0B,EAC1B,GAA8C;IAE9C,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC;IAC7C,0EAA0E;IAC1E,8EAA8E;IAC9E,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3D,OAAO,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,yBAAyB,CACvC,YAA0B,EAC1B,IAAkC;IAElC,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,0BAA0B,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,QAAQ,GAAG,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QAClE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,IAAI,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;YACpF,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,wCAAwC,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;QAChG,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/checksum.d.ts

@@ -0,0 +1,45 @@
+import type { S3Storage } from '../storage/s3.js';
+import type { PulseVaultValidatePayload } from './magic.js';
+export type ChecksumAlgorithm = 'sha256' | 'sha1' | 'md5';
+export type ParsedChecksum = {
+    algorithm: ChecksumAlgorithm;
+    digest: string;
+};
+/**
+ * Parse the client-supplied `Upload-Metadata.checksum` value, format
+ * `<algorithm>:<hex digest>` (e.g. `sha256:9f86d0...`). Returns `null` for a
+ * missing or malformed value — checksum verification is opt-in per upload,
+ * not required, unless the caller treats a `null` parse as a rejection.
+ */
+export declare function parseChecksumMetadata(raw: string | undefined | null): ParsedChecksum | null;
+/**
+ * Build a `validatePayload` (or `validateCaptionsPayload`/`validateProjectPayload`)
+ * hook that verifies a client-supplied checksum against the finalized bytes
+ * before the upload is marked ready — for adapters that expose `localPath`
+ * (the built-in local adapter does; see `createS3ChecksumValidator` for S3/R2).
+ *
+ * This is at-rest corruption/tampering detection on the *finished* file, not
+ * a per-chunk integrity check — the TUS protocol's Checksum extension would
+ * cover chunks in flight, but the `@tus/server` version in use doesn't
+ * implement it. This fills the same gap for the finished artifact instead.
+ *
+ * Uploads with no `checksum` metadata are passed through unchanged (the
+ * client opted out); a checksum that's present but doesn't match is rejected
+ * with 422 and the bytes are removed, same semantics as `createMp4Sniffer`.
+ * Chain with another validator (e.g. `createMp4Sniffer`) via `next`:
+ *
+ * ```ts
+ * validatePayload: createChecksumValidator(createMp4Sniffer(storage)),
+ * ```
+ */
+export declare function createChecksumValidator(next?: PulseVaultValidatePayload): PulseVaultValidatePayload;
+/**
+ * `createChecksumValidator` for the S3/R2 backend — streams the whole
+ * finalized object through a hash digest via `S3Storage.digestAll`, since S3
+ * has no local path to hash directly. Only worth using when checksum
+ * verification is explicitly wanted; it's a full extra download per upload,
+ * but (unlike buffering the object via `readAll`) never holds the whole
+ * object in memory at once.
+ */
+export declare function createS3ChecksumValidator(storage: S3Storage, next?: PulseVaultValidatePayload): PulseVaultValidatePayload;
+//# sourceMappingURL=checksum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../../src/lib/checksum.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAG1D,MAAM,MAAM,cAAc,GAAG;IAAE,SAAS,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,cAAc,GAAG,IAAI,CAS3F;AAsBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,CAAC,EAAE,yBAAyB,GAC/B,yBAAyB,CAwB3B;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,yBAAyB,GAC/B,yBAAyB,CAmB3B"}

package/dist/lib/checksum.js

@@ -0,0 +1,105 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+const SUPPORTED_ALGORITHMS = ['sha256', 'sha1', 'md5'];
+/**
+ * Parse the client-supplied `Upload-Metadata.checksum` value, format
+ * `<algorithm>:<hex digest>` (e.g. `sha256:9f86d0...`). Returns `null` for a
+ * missing or malformed value — checksum verification is opt-in per upload,
+ * not required, unless the caller treats a `null` parse as a rejection.
+ */
+export function parseChecksumMetadata(raw) {
+    if (!raw)
+        return null;
+    const sep = raw.indexOf(':');
+    if (sep < 0)
+        return null;
+    const algorithm = raw.slice(0, sep).toLowerCase();
+    const digest = raw.slice(sep + 1).toLowerCase();
+    if (!isSupportedAlgorithm(algorithm))
+        return null;
+    if (!/^[0-9a-f]+$/.test(digest) || digest.length === 0)
+        return null;
+    return { algorithm, digest };
+}
+function isSupportedAlgorithm(value) {
+    return SUPPORTED_ALGORITHMS.includes(value);
+}
+/**
+ * Hashes the file at `path` via a stream instead of `fs.readFile` so a
+ * multi-gigabyte upload (`maxUploadSize: Infinity` is a supported
+ * configuration) never has to be held in memory as a single `Buffer` just to
+ * compute its checksum.
+ */
+async function digestLocalFile(path, algorithm) {
+    const hash = createHash(algorithm);
+    await pipeline(createReadStream(path), hash);
+    return hash.digest('hex');
+}
+function checksumError(message) {
+    return Object.assign(new Error(message), { statusCode: 422 });
+}
+/**
+ * Build a `validatePayload` (or `validateCaptionsPayload`/`validateProjectPayload`)
+ * hook that verifies a client-supplied checksum against the finalized bytes
+ * before the upload is marked ready — for adapters that expose `localPath`
+ * (the built-in local adapter does; see `createS3ChecksumValidator` for S3/R2).
+ *
+ * This is at-rest corruption/tampering detection on the *finished* file, not
+ * a per-chunk integrity check — the TUS protocol's Checksum extension would
+ * cover chunks in flight, but the `@tus/server` version in use doesn't
+ * implement it. This fills the same gap for the finished artifact instead.
+ *
+ * Uploads with no `checksum` metadata are passed through unchanged (the
+ * client opted out); a checksum that's present but doesn't match is rejected
+ * with 422 and the bytes are removed, same semantics as `createMp4Sniffer`.
+ * Chain with another validator (e.g. `createMp4Sniffer`) via `next`:
+ *
+ * ```ts
+ * validatePayload: createChecksumValidator(createMp4Sniffer(storage)),
+ * ```
+ */
+export function createChecksumValidator(next) {
+    return async (request, ctx) => {
+        const checksum = parseChecksumMetadata(ctx.checksum);
+        if (checksum) {
+            if (!ctx.localPath) {
+                // Wrong validator wired for this adapter — a server misconfiguration,
+                // not a bad client payload — so surface 500, not 422 (which would tell
+                // the client their file was rejected).
+                throw Object.assign(new Error('Checksum verification requested but this storage adapter has no local path — use createS3ChecksumValidator for S3/R2 storage'), { statusCode: 500 });
+            }
+            const actual = await digestLocalFile(ctx.localPath, checksum.algorithm);
+            if (actual !== checksum.digest) {
+                throw checksumError(`Checksum mismatch: expected ${checksum.algorithm}:${checksum.digest}, got ${checksum.algorithm}:${actual}`);
+            }
+        }
+        if (next)
+            await next(request, ctx);
+    };
+}
+/**
+ * `createChecksumValidator` for the S3/R2 backend — streams the whole
+ * finalized object through a hash digest via `S3Storage.digestAll`, since S3
+ * has no local path to hash directly. Only worth using when checksum
+ * verification is explicitly wanted; it's a full extra download per upload,
+ * but (unlike buffering the object via `readAll`) never holds the whole
+ * object in memory at once.
+ */
+export function createS3ChecksumValidator(storage, next) {
+    return async (request, ctx) => {
+        const checksum = parseChecksumMetadata(ctx.checksum);
+        if (checksum) {
+            const actual = await storage.digestAll(ctx.artifactId, checksum.algorithm);
+            if (actual === null) {
+                throw Object.assign(new Error(`Cannot validate upload ${ctx.artifactId}: no object bytes available`), { statusCode: 500 });
+            }
+            if (actual !== checksum.digest) {
+                throw checksumError(`Checksum mismatch: expected ${checksum.algorithm}:${checksum.digest}, got ${checksum.algorithm}:${actual}`);
+            }
+        }
+        if (next)
+            await next(request, ctx);
+    };
+}
+//# sourceMappingURL=checksum.js.map

package/dist/lib/checksum.js.map

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

package/dist/lib/deeplinks.d.ts

@@ -1,32 +1,48 @@
-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. */
+    /**
+     * Full base URL the client should upload to — origin *plus* whatever
+     * `prefix` you registered the plugin under (e.g.
+     * `https://vault.example.org/pulsevault`, not just `https://vault.example.org`).
+     * The client builds every request as `${server}/<path>` with no separate
+     * prefix concept of its own. Must be `https://` (or `http://localhost`/a
+     * private IP for local dev).
+     */
     server: string;
-    /** Opaque token forwarded to the server's `authorize` hook. Omit for unauthenticated servers. */
+    /** Opaque token forwarded to the server's `authorize` hook — typically minted with `issueCapabilityToken`. 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()`.
+     * Server-side artifact UUID. Used as both the app's local draft key and the
+     * `artifactId` in `Upload-Metadata`, so the app skips a separate reserve
+     * step. Generate with `crypto.randomUUID()`.
      */
-    videoid: string;
+    artifactId: string;
+    /**
+     * Per-session override of the deployment-wide `uploadUnit` advertised via
+     * `GET /capabilities` (PROTOCOL.md §8). Omit to let the client fall back to
+     * whatever `/capabilities` reports — the same behavior as before this field
+     * existed. Set this when an operator wants "segment" and "merged" sessions
+     * live at the same time (e.g. different pairing flows, a/b testing, a
+     * gradual rollout) rather than one fixed value for the whole deployment:
+     * `/capabilities` can only ever report one current value, and a client
+     * that reads it separately from opening the link is racing whatever the
+     * server was serving at that moment, not the value this specific session
+     * was paired under.
+     */
+    uploadUnit?: 'segment' | 'merged';
 };
-/**
- * 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.
+ * upload screen for a specific artifact, pointed at this server.
+ *
+ * No `mode` param — there's only one mode, so it was always redundant. `v`
+ * lets the app refuse/explain a future incompatible link shape instead of
+ * misparsing it.
+ *
+ * Throws if `server` isn't `https://` (or the narrow localhost/private-IP dev
+ * exception PROTOCOL.md §3 carves out) — failing fast here, at the one place
+ * that constructs the link, is more reliable than relying on every client to
+ * independently reject a plaintext origin the operator never should have
+ * issued in the first place.
  */
 export declare function buildUploadLink(opts: UploadLinkOptions): string;
 //# sourceMappingURL=deeplinks.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"deeplinks.d.ts","sourceRoot":"","sources":["../../src/lib/deeplinks.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,gJAAgJ;IAChJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CACnC,CAAC;AA4BF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CA0B/D"}

package/dist/lib/deeplinks.js

@@ -1,24 +1,65 @@
+/** Deep-link wire format version. Bump when the param shape changes incompatibly. */
+const LINK_VERSION = '1';
 /**
- * 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.
+ * Private/dev origins allowed over plain http — mirrors the Pulse client's
+ * own `isPrivateDevOrigin` check (PROTOCOL.md §3) exactly, so a link this
+ * helper is willing to build is also one the client is willing to accept.
+ * Never extended beyond non-globally-routable address space (RFC 1918
+ * private ranges, RFC 6598 carrier-grade NAT, link-local) plus
+ * loopback/localhost — never a public IP or domain just because it "looks
+ * internal."
  */
-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()}`;
+function isPrivateDevOrigin(url) {
+    if (url.protocol !== 'http:')
+        return false;
+    const host = url.hostname;
+    return (host === 'localhost' ||
+        host === '127.0.0.1' ||
+        /^10\.\d+\.\d+\.\d+$/.test(host) ||
+        /^192\.168\.\d+\.\d+$/.test(host) ||
+        /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/.test(host) ||
+        /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d+\.\d+$/.test(host) || // RFC 6598, 100.64.0.0/10
+        /^169\.254\.\d+\.\d+$/.test(host) // link-local
+    );
 }
 /**
  * Build a `pulsecam://` deep link that opens the Pulse app directly on the
- * upload screen for a specific draft, pointed at this server.
+ * upload screen for a specific artifact, pointed at this server.
+ *
+ * No `mode` param — there's only one mode, so it was always redundant. `v`
+ * lets the app refuse/explain a future incompatible link shape instead of
+ * misparsing it.
+ *
+ * Throws if `server` isn't `https://` (or the narrow localhost/private-IP dev
+ * exception PROTOCOL.md §3 carves out) — failing fast here, at the one place
+ * that constructs the link, is more reliable than relying on every client to
+ * independently reject a plaintext origin the operator never should have
+ * issued in the first place.
  */
 export function buildUploadLink(opts) {
-    const params = new URLSearchParams({ mode: "upload", videoid: opts.videoid, server: opts.server });
+    let server;
+    try {
+        server = new URL(opts.server);
+    }
+    catch {
+        throw new Error(`buildUploadLink: \`server\` is not a valid URL: ${opts.server}`);
+    }
+    if (server.protocol !== 'https:' && !isPrivateDevOrigin(server)) {
+        throw new Error(`buildUploadLink: \`server\` must be https:// (got "${opts.server}") — ` +
+            'the only exception is http://localhost or a private IP literal for local development.');
+    }
+    if (opts.uploadUnit !== undefined && opts.uploadUnit !== 'segment' && opts.uploadUnit !== 'merged') {
+        throw new Error(`buildUploadLink: \`uploadUnit\` must be "segment" or "merged" (got "${opts.uploadUnit}")`);
+    }
+    const params = new URLSearchParams({
+        v: LINK_VERSION,
+        artifactId: opts.artifactId,
+        server: opts.server,
+    });
     if (opts.token)
-        params.set("token", opts.token);
+        params.set('token', opts.token);
+    if (opts.uploadUnit)
+        params.set('uploadUnit', opts.uploadUnit);
     return `pulsecam://?${params.toString()}`;
 }
 //# sourceMappingURL=deeplinks.js.map

package/dist/lib/deeplinks.js.map

@@ -1 +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"}
+{"version":3,"file":"deeplinks.js","sourceRoot":"","sources":["../../src/lib/deeplinks.ts"],"names":[],"mappings":"AAiCA,qFAAqF;AACrF,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CAAC,GAAQ;IAClC,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC1B,OAAO,CACL,IAAI,KAAK,WAAW;QACpB,IAAI,KAAK,WAAW;QACpB,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC;QAChC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC;QACjC,qCAAqC,CAAC,IAAI,CAAC,IAAI,CAAC;QAChD,mDAAmD,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,0BAA0B;QAC5F,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,aAAa;KAChD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,IAAuB;IACrD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,mDAAmD,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,sDAAsD,IAAI,CAAC,MAAM,OAAO;YACtE,uFAAuF,CAC1F,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QACnG,MAAM,IAAI,KAAK,CAAC,uEAAuE,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IAC9G,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,CAAC,EAAE,YAAY;QACf,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IACH,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAChD,IAAI,IAAI,CAAC,UAAU;QAAE,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/D,OAAO,eAAe,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC5C,CAAC"}

package/dist/lib/errors.d.ts

@@ -3,4 +3,11 @@ export type PulseVaultErrorBody = {
     error: string;
 };
 export declare function pulseVaultError(error: string): PulseVaultErrorBody;
+/**
+ * Extract a numeric HTTP status from a thrown error, honoring both `statusCode`
+ * (Fastify convention) and `status_code` (tus convention). Returns `fallback`
+ * when neither is a *valid* HTTP status — a consumer hook throwing
+ * `{ statusCode: 42 }` must degrade to the fallback, not crash `writeHead`.
+ */
+export declare function statusCodeOf(err: unknown, fallback: number): number;
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +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"}
+{"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;AAOD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKnE"}

package/dist/lib/errors.js

@@ -1,4 +1,22 @@
 export function pulseVaultError(error) {
     return { ok: false, error };
 }
+/** A usable HTTP status: an integer in 100–599. Anything else would make `res.writeHead` throw. */
+function isHttpStatus(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599;
+}
+/**
+ * Extract a numeric HTTP status from a thrown error, honoring both `statusCode`
+ * (Fastify convention) and `status_code` (tus convention). Returns `fallback`
+ * when neither is a *valid* HTTP status — a consumer hook throwing
+ * `{ statusCode: 42 }` must degrade to the fallback, not crash `writeHead`.
+ */
+export function statusCodeOf(err, fallback) {
+    const e = err;
+    if (isHttpStatus(e?.statusCode))
+        return e.statusCode;
+    if (isHttpStatus(e?.status_code))
+        return e.status_code;
+    return fallback;
+}
 //# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -1 +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"}
+{"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;AAED,mGAAmG;AACnG,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,CAAC;AAC9F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY,EAAE,QAAgB;IACzD,MAAM,CAAC,GAAG,GAAsD,CAAC;IACjE,IAAI,YAAY,CAAC,CAAC,EAAE,UAAU,CAAC;QAAE,OAAO,CAAC,CAAC,UAAU,CAAC;IACrD,IAAI,YAAY,CAAC,CAAC,EAAE,WAAW,CAAC;QAAE,OAAO,CAAC,CAAC,WAAW,CAAC;IACvD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/lib/magic.d.ts

@@ -1,10 +1,12 @@
-import type { FastifyRequest } from "fastify";
-import type { LocalStorage } from "../storage/local.js";
+import type { PulseVaultRequest } from './request.js';
+import type { LocalStorage } from '../storage/local.js';
+import type { S3Storage } from '../storage/s3.js';
+import type { UploadKind } from '../storage/types.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
+ * throw into a 422 response, calls `storage.remove?.(artifactId)` to free the
  * disk, and never flips the sidecar to `"ready"`.
  *
  * The `localPath` field is populated for adapters that expose
@@ -12,12 +14,16 @@ import type { LocalStorage } from "../storage/local.js";
  * 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;
+export type PulseVaultValidatePayload = (request: PulseVaultRequest, ctx: {
+    artifactId: string;
     size: number;
     uploadId: string;
+    /** Which artifact kind this upload is. Runs for every kind — branch on this if you only want a check applied to one. */
+    kind: UploadKind;
     /** Absolute local path to the finalized bytes, or `null` if unavailable. */
     localPath: string | null;
+    /** Client-supplied `<algorithm>:<hex>` digest, if `Upload-Metadata.checksum` was sent. */
+    checksum?: string;
 }) => void | Promise<void>;
 /**
  * Check whether a file's first bytes match the ISO base media file format
@@ -47,4 +53,23 @@ export declare function sniffMp4(filePath: string): Promise<boolean>;
  * ```
  */
 export declare function createMp4Sniffer(storage: LocalStorage): PulseVaultValidatePayload;
+/**
+ * `createMp4Sniffer` for the S3 / R2 backend. Instead of opening a local file,
+ * it asks the adapter for the first 12 bytes of the finalized object via a
+ * small ranged GET (`S3Storage.readHeader`) and applies the same `ftyp` check.
+ * Runs in the same lifecycle slot — after `@tus/s3-store` completes the
+ * multipart upload (so the object is readable) but before `markReady` — so a
+ * non-MP4 upload is removed and never served.
+ *
+ * Usage:
+ * ```ts
+ * const storage = await createS3Storage({ ... });
+ * await app.register(pulseVault, {
+ *   storage,
+ *   validatePayload: createS3Mp4Sniffer(storage),
+ *   // ...
+ * });
+ * ```
+ */
+export declare function createS3Mp4Sniffer(storage: S3Storage): PulseVaultValidatePayload;
 //# sourceMappingURL=magic.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"magic.d.ts","sourceRoot":"","sources":["../../src/lib/magic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,wHAAwH;IACxH,IAAI,EAAE,UAAU,CAAC;IACjB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,KACE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAejE;AAaD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,yBAAyB,CAgBjF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,GAAG,yBAAyB,CAehF"}