sealkeep 0.8.1 → 0.11.0

package/dist/src/source-reader.js

@@ -0,0 +1,715 @@
+import { createHash } from "node:crypto";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { createGunzip } from "node:zlib";
+import { decryptArchiveBodyChunks, unsqueezeStream, validateEnvelope, x25519PrivateKeyFromRaw } from "../packages/sealkeep-crypto/src/index.js";
+import { chunkWindowForRange, openChunkWindow, supportsChunkAccess } from "../packages/sealkeep-crypto/src/chunk-access.js";
+import { collectChunks, LEGACY_BUFFER_LIMIT_BYTES, MAX_FRAME_METADATA_BYTES } from "./byte-stream.js";
+import { fail, isSealkeepError } from "./errors.js";
+import { isV2 } from "./types.js";
+import { findArchive, listArchives, readConfig, resolveDeltaChain, teamSpaceOf } from "./vault.js";
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+export const envelopeDigest = (envelope) => digest(JSON.stringify(envelope));
+const validHash = (value) => typeof value === "string" && /^[a-f0-9]{64}$/i.test(value);
+export function sourceReference(id, facts, scope = {}) {
+    return { version: 1, archiveId: id, envelopeArchiveId: facts.envelopeArchiveId ?? id,
+        sourceSha256: facts.sourceSha256, sourceBytes: facts.sourceBytes, ciphertextSha256: facts.ciphertextSha256, ...scope };
+}
+export async function resolveSourceReference(dataDir, phrase, archiveId, project, projectKey) {
+    const { pullBoundTeamProjectIndex, archiveCatalogFacts } = await import("./search.js");
+    const binding = teamSpaceOf(await readConfig(dataDir), project, projectKey);
+    if (binding) {
+        const access = await pullBoundTeamProjectIndex(dataDir, phrase, project, [], projectKey, { sourceFactsOnly: true });
+        if (!access)
+            return fail("forbidden", "The current Team source catalog is unavailable");
+        const id = Object.keys(access.index.archives).find((candidate) => candidate === archiveId
+            || access.index.meta?.[candidate]?.archiveRecord?.envelopeArchiveId === archiveId);
+        if (!id)
+            return fail("archive_not_found", "The archive is absent from the current Team project catalog");
+        const { facts } = teamCatalogEntry(access, id);
+        return sourceReference(id, facts, { project, ...(projectKey ? { projectKey } : {}), spaceKey: binding.spaceKey });
+    }
+    const record = await findArchive(dataDir, archiveId);
+    const facts = archiveCatalogFacts(record);
+    if (!facts || !isV2(record) || record.source.project !== project || (projectKey && record.source.projectKey !== projectKey)) {
+        return fail("archive_not_found", "The archive does not belong to the selected project");
+    }
+    return sourceReference(record.id, facts, { project, ...(projectKey ? { projectKey } : {}) });
+}
+function matchesSource(id, facts, source) {
+    return (facts.envelopeArchiveId ?? id) === source.envelopeArchiveId
+        && facts.sourceSha256 === source.sourceSha256 && facts.sourceBytes === source.sourceBytes
+        && facts.ciphertextSha256 === source.ciphertextSha256;
+}
+function catalogEntry(index, id, spaceKey) {
+    const line = index.archives[id];
+    const facts = index.meta?.[id]?.archiveRecord;
+    if (!line || (spaceKey !== undefined && line[3] !== spaceKey) || !facts || facts.v !== 1
+        || !Number.isSafeInteger(facts.sourceBytes) || facts.sourceBytes < 0
+        || !Number.isSafeInteger(facts.storedBytes) || facts.storedBytes <= 0
+        || !Number.isSafeInteger(facts.chunks) || facts.chunks < 1
+        || !validHash(facts.sourceSha256) || !validHash(facts.ciphertextSha256)
+        || (facts.envelopeSha256 !== undefined && !validHash(facts.envelopeSha256))) {
+        return fail("ciphertext_integrity_failed", "The shared source has no valid authenticated catalog entry");
+    }
+    const base = facts.delta?.baseBytes ?? 0;
+    if (!Number.isSafeInteger(base) || base < 0 || (facts.delta && (!facts.delta.baseArchiveId || base <= 0 || base >= facts.sourceBytes))) {
+        return fail("ciphertext_integrity_failed", "The shared source has an invalid dependency range");
+    }
+    return { line, facts, plaintextBytes: facts.sourceBytes - base };
+}
+export function teamCatalogEntry(access, id) {
+    return catalogEntry(access.index, id, access.spaceKey);
+}
+function verifyEnvelope(id, envelope, entry) {
+    const { facts, plaintextBytes } = entry;
+    validateEnvelope(envelope, facts.storedBytes);
+    const rawBytes = envelope.manifest.compression === undefined ? envelope.manifest.plaintextBytes : envelope.manifest.originalBytes;
+    const rawHash = envelope.manifest.compression === undefined ? envelope.manifest.plaintextSha256 : envelope.manifest.originalSha256;
+    if (envelope.archiveId !== (facts.envelopeArchiveId ?? id) || envelope.suite !== facts.algorithm
+        || envelope.chunks.length !== facts.chunks || rawBytes !== plaintextBytes
+        || (!facts.delta && rawHash !== facts.sourceSha256)
+        || (facts.envelopeSha256 && envelopeDigest(envelope) !== facts.envelopeSha256)) {
+        fail("ciphertext_integrity_failed", "The shared envelope does not match the cited source");
+    }
+}
+function recordFor(dataDir, id, envelope, entry) {
+    const { facts, line } = entry;
+    return { version: 2, id, createdAt: facts.createdAt,
+        source: { path: line[1] ?? `archive ${id}`, agent: line[0] ?? "unknown", bytes: facts.sourceBytes,
+            sha256: facts.sourceSha256, ...(line[2] ? { project: line[2] } : {}),
+            ...(line[3] ? { projectScope: line[3] } : {}), ...(line[4] ? { projectKey: line[4] } : {}) },
+        cipher: { algorithm: envelope.suite, ciphertextSha256: facts.ciphertextSha256, storedBytes: facts.storedBytes, chunks: facts.chunks },
+        envelope, objectPath: join(dataDir, "never-materialised", `${id}.skarchive`),
+        ...(facts.delta ? { delta: facts.delta } : {}), ...(facts.supersedes ? { supersedes: facts.supersedes } : {}) };
+}
+/** Shared by search snippets, context reads and explicit Team restoration. */
+export async function resolveTeamArchive(dataDir, id, access, limits = {}) {
+    const { createTeamReadGuard, pullTeamCiphertextStream, unframeObject } = await import("./cloud.js");
+    const entry = teamCatalogEntry(access, id);
+    const maxWire = limits.maxWireBytes ?? LEGACY_BUFFER_LIMIT_BYTES;
+    const maxDecoded = limits.maxDecodedBytes ?? LEGACY_BUFFER_LIMIT_BYTES;
+    if (entry.facts.storedBytes + 8 > maxWire || entry.facts.sourceBytes > maxDecoded) {
+        return fail("provider_unsupported", "This source needs a verified partial read or a larger explicit restore budget", { reason: "partial_read_unsupported" });
+    }
+    const guard = access.readGuard ?? await createTeamReadGuard(dataDir, access.spaceKey, [id], access.membershipVersion, { signal: limits.signal });
+    await guard.assertCurrent([id]);
+    const framed = await collectChunks(await pullTeamCiphertextStream(dataDir, access.spaceKey, id, undefined, { signal: limits.signal, maxBytes: maxWire }), maxWire);
+    const { envelope, ciphertext } = unframeObject(framed);
+    if (!envelope || ciphertext.length !== entry.facts.storedBytes || digest(ciphertext) !== entry.facts.ciphertextSha256) {
+        fail("ciphertext_integrity_failed", "The downloaded object does not match the cited source");
+    }
+    verifyEnvelope(id, envelope, entry);
+    await guard.assertCurrent();
+    return { record: recordFor(dataDir, id, envelope, entry),
+        teamRead: { ...access, framed, grants: new Set([id]), assertCurrent: guard.assertCurrent }, guard };
+}
+async function openWhole(envelope, ciphertext, unlock, maxBytes, signal) {
+    const compressed = envelope.manifest.compression !== undefined;
+    const expected = compressed ? envelope.manifest.originalBytes : envelope.manifest.plaintextBytes;
+    const expectedHash = compressed ? envelope.manifest.originalSha256 : envelope.manifest.plaintextSha256;
+    if (!Number.isSafeInteger(expected) || expected < 0 || expected > maxBytes || !validHash(expectedHash)) {
+        return fail("provider_unsupported", "The source exceeds this read's decompression budget", { reason: "decoded_budget_exceeded" });
+    }
+    const chunks = decryptArchiveBodyChunks(envelope, ciphertext, unlock);
+    const codec = envelope.manifest.compression;
+    const expand = () => codec === "gzip" || codec === "gzip-chunk" ? createGunzip()
+        : codec === "zstd" || codec === "zstd-chunk" ? unsqueezeStream()
+            : fail("ciphertext_integrity_failed", "Unsupported source compression");
+    async function* plaintext() {
+        if (!codec) {
+            for (const chunk of chunks) {
+                signal?.throwIfAborted();
+                yield chunk;
+            }
+            return;
+        }
+        const groups = codec.endsWith("-chunk") ? chunks.map((chunk) => [chunk]) : [chunks];
+        for (const group of groups) {
+            const stream = Readable.from(group).pipe(expand());
+            try {
+                for await (const chunk of stream) {
+                    signal?.throwIfAborted();
+                    yield Buffer.from(chunk);
+                }
+            }
+            finally {
+                stream.destroy();
+            }
+        }
+    }
+    try {
+        const bytes = await collectChunks(plaintext(), maxBytes);
+        if (bytes.length !== expected || digest(bytes) !== expectedHash) {
+            bytes.fill(0);
+            fail("plaintext_integrity_failed", "The source did not reproduce its authenticated original bytes");
+        }
+        return bytes;
+    }
+    finally {
+        for (const chunk of chunks)
+            chunk.fill(0);
+    }
+}
+async function personalReadGuard(dataDir, signal) {
+    const { cloudToken, cloudAuthGeneration, cloudUrl, readCloudAuthSnapshot } = await import("./cloud.js");
+    await cloudToken(dataDir, undefined, { signal }); // Complete any renewal before pinning the read.
+    const snapshot = () => readCloudAuthSnapshot(dataDir, async () => ({
+        token: await cloudToken(dataDir, undefined, { signal, renew: false }),
+        generation: await cloudAuthGeneration(dataDir), origin: cloudUrl(), vaultId: (await readConfig(dataDir)).vaultId,
+    }));
+    const initial = await snapshot();
+    return async () => {
+        signal?.throwIfAborted();
+        const current = await snapshot();
+        if (current.token !== initial.token || current.generation !== initial.generation
+            || current.origin !== initial.origin || current.vaultId !== initial.vaultId)
+            fail("unauthorized", "The account changed during the source read");
+    };
+}
+async function localCiphertext(record, signal) {
+    const handle = await open(record.objectPath, "r").catch(() => null);
+    if (!handle)
+        return null;
+    try {
+        if ((await handle.stat()).size !== record.cipher.storedBytes)
+            fail("ciphertext_integrity_failed", "The local source has an unexpected stored size");
+        const bytes = Buffer.alloc(record.cipher.storedBytes);
+        try {
+            let at = 0;
+            while (at < bytes.length) {
+                signal?.throwIfAborted();
+                const read = await handle.read(bytes, at, bytes.length - at, at);
+                if (!read.bytesRead)
+                    fail("ciphertext_integrity_failed", "The local source is truncated");
+                at += read.bytesRead;
+            }
+            if (digest(bytes) !== record.cipher.ciphertextSha256)
+                fail("ciphertext_integrity_failed", "The local source ciphertext failed verification");
+            return bytes;
+        }
+        catch (error) {
+            bytes.fill(0);
+            throw error;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readPersonalRemoteSource(dataDir, phrase, source, range, maxWire, maxDecoded, signal, chunkIndex, allowMissingIndex = false, managedFolder = false) {
+    const assertCurrent = await personalReadGuard(dataDir, signal);
+    const { loadPersonalSourceFacts } = await import("./search.js");
+    let decodedBytes = 0;
+    const index = await loadPersonalSourceFacts(dataDir, phrase, { signal, maxIndexBytes: maxWire, maxIndexDecodedBytes: maxDecoded,
+        onIndexDecoded(bytes) { decodedBytes += bytes; } }).catch((error) => {
+        // A retained local record can still use the existing bounded whole-body
+        // path when no index was built. A damaged index is never such a fallback.
+        if (allowMissingIndex && isSealkeepError(error) && error.code === "invalid_argument")
+            return null;
+        throw error;
+    });
+    if (!index)
+        return null;
+    const facts = index.meta?.[source.archiveId]?.archiveRecord;
+    const line = index.archives[source.archiveId];
+    if (!facts || !line || !matchesSource(source.archiveId, facts, source)
+        || (source.project && line[2] !== source.project) || (source.projectKey && line[4] !== source.projectKey)) {
+        return fail("ciphertext_integrity_failed", "The personal catalog does not match this immutable project citation");
+    }
+    const entry = catalogEntry(index, source.archiveId);
+    if ((managedFolder || range.start > 0 || range.end < source.sourceBytes) && !facts.delta && facts.envelopeSha256) {
+        return readPersonalRange(dataDir, phrase, source, range, entry, maxWire, maxDecoded, decodedBytes, assertCurrent, signal, chunkIndex, managedFolder);
+    }
+    if (facts.storedBytes + 8 > maxWire || facts.sourceBytes > maxDecoded - decodedBytes) {
+        return fail("provider_unsupported", !facts.envelopeSha256
+            ? "This source catalog predates authenticated chunk mappings; bounded reading requires an authenticated catalog upgrade"
+            : "This personal source exceeds the bounded whole-object reader", { reason: "partial_read_unsupported" });
+    }
+    const { pullCiphertextStream, unframeObject } = await import("./cloud.js");
+    const chain = [];
+    let current = source.archiveId;
+    while (current) {
+        if (chain.length >= 16 || chain.includes(current))
+            fail("ciphertext_integrity_failed", "The personal dependency chain is cyclic or too deep");
+        const entry = catalogEntry(index, current);
+        if ((source.project && entry.line[2] !== source.project) || (source.projectKey && entry.line[4] !== source.projectKey))
+            fail("forbidden", "A source dependency does not belong to the cited project");
+        chain.unshift(current);
+        const delta = entry.facts.delta;
+        if (delta && catalogEntry(index, delta.baseArchiveId).facts.sourceBytes !== delta.baseBytes)
+            fail("ciphertext_integrity_failed", "The personal dependency has an inconsistent prefix");
+        current = delta?.baseArchiveId;
+    }
+    const parts = [];
+    const assembled = createHash("sha256");
+    let originalBytes = 0;
+    let wireBytes = 0;
+    let record;
+    try {
+        for (const ref of chain) {
+            const entry = catalogEntry(index, ref);
+            if (entry.facts.storedBytes + 8 > maxWire - wireBytes || entry.plaintextBytes > maxDecoded - decodedBytes)
+                fail("provider_unsupported", "The personal dependency exceeds the aggregate read budget");
+            await assertCurrent();
+            const framed = await collectChunks(await pullCiphertextStream(dataDir, ref, undefined, { signal, maxBytes: maxWire - wireBytes }), maxWire - wireBytes);
+            wireBytes += framed.length;
+            const { envelope, ciphertext } = unframeObject(framed);
+            if (!envelope || ciphertext.length !== entry.facts.storedBytes || digest(ciphertext) !== entry.facts.ciphertextSha256)
+                fail("ciphertext_integrity_failed", "The personal object does not match the source catalog");
+            verifyEnvelope(ref, envelope, entry);
+            const part = await openWhole(envelope, ciphertext, { phrase }, maxDecoded - decodedBytes, signal);
+            parts.push(part);
+            decodedBytes += part.length;
+            originalBytes += part.length;
+            assembled.update(part);
+            if (originalBytes !== entry.facts.sourceBytes || assembled.copy().digest("hex") !== entry.facts.sourceSha256)
+                fail("plaintext_integrity_failed", "The personal dependency prefix did not reproduce its cited bytes");
+            if (ref === source.archiveId)
+                record = recordFor(dataDir, ref, envelope, entry);
+        }
+        if (!record || originalBytes !== source.sourceBytes || assembled.digest("hex") !== source.sourceSha256)
+            fail("plaintext_integrity_failed", "The personal source did not reproduce the cited bytes");
+        await assertCurrent();
+        const whole = Buffer.concat(parts);
+        const bytes = Buffer.from(whole.subarray(range.start, range.end));
+        whole.fill(0);
+        if (bytes.length !== range.end - range.start)
+            fail("plaintext_integrity_failed", "The personal source returned an incomplete interval");
+        return { source, record, bytes, byteStart: range.start, byteEnd: range.end, wireBytes, decodedBytes, assertCurrent };
+    }
+    finally {
+        for (const part of parts)
+            part.fill(0);
+    }
+}
+/** The encrypted catalog, not a plaintext local record or caller hint,
+ * authenticates the complete raw-to-ciphertext mapping before any chunk use. */
+async function readPersonalRange(dataDir, phrase, source, range, entry, maxWire, maxDecoded, decodedBytes, assertCurrent, signal, chunkIndex, managedFolder = false) {
+    const { pullCiphertextRange } = await import("./cloud.js");
+    const { managedChunkRefs } = await import("./managed-chunks.js");
+    const folder = managedFolder ? managedChunkRefs(source.archiveId, entry.facts.chunks) : undefined;
+    let descriptor;
+    let wireBytes = 0;
+    const pull = async (offset, length, ref = folder?.envelope ?? source.archiveId, expectedChunk) => {
+        if (!Number.isSafeInteger(length) || length < 1 || length > maxWire - wireBytes)
+            fail("provider_unsupported", "The source exceeded its aggregate wire budget");
+        await assertCurrent();
+        const value = await pullCiphertextRange(dataDir, ref, offset, length, undefined, {
+            signal, maxBytes: maxWire - wireBytes,
+            async onDescriptor(current) {
+                if (expectedChunk) {
+                    if (current.bytes !== expectedChunk.storedBytes || current.ciphertextSha256 !== expectedChunk.sha256)
+                        fail("ciphertext_integrity_failed", "The managed chunk descriptor does not match its authenticated envelope");
+                }
+                else {
+                    if (descriptor && (descriptor.vaultRef !== current.vaultRef || descriptor.bytes !== current.bytes
+                        || descriptor.ciphertextSha256 !== current.ciphertextSha256))
+                        fail("ciphertext_integrity_failed", "The personal object changed between range reads");
+                    descriptor ??= current;
+                }
+                await assertCurrent();
+            },
+        });
+        wireBytes += value.length;
+        return value;
+    };
+    const header = await pull(0, 8);
+    if (header.subarray(0, 4).toString("ascii") !== "VLA1")
+        fail("ciphertext_integrity_failed", "The personal source frame is invalid");
+    const metadataBytes = header.readUInt32BE(4);
+    if (!metadataBytes)
+        fail("ciphertext_integrity_failed", "The personal source envelope is empty");
+    if (metadataBytes > MAX_FRAME_METADATA_BYTES || metadataBytes > maxWire - wireBytes)
+        fail("provider_unsupported", "The source envelope exceeds the wire budget");
+    if (!folder && descriptor.bytes !== 8 + metadataBytes + entry.facts.storedBytes)
+        fail("ciphertext_integrity_failed", "The personal frame size does not match its authenticated catalog");
+    const metadata = await pull(8, metadataBytes);
+    let envelope;
+    try {
+        envelope = JSON.parse(metadata.toString("utf8"));
+    }
+    catch {
+        return fail("ciphertext_integrity_failed", "The personal source envelope is invalid");
+    }
+    verifyEnvelope(source.archiveId, envelope, entry);
+    if (!entry.facts.envelopeSha256 || envelopeDigest(envelope) !== entry.facts.envelopeSha256)
+        fail("ciphertext_integrity_failed", "The personal source has no authenticated chunk mapping");
+    if (!supportsChunkAccess(envelope))
+        fail("provider_unsupported", "This personal source predates independent compression", { reason: "partial_read_unsupported" });
+    if (chunkIndex !== undefined && range.start === 0) {
+        if (chunkIndex >= envelope.chunks.length)
+            fail("invalid_argument", "The chunk hint is outside this source");
+        const size = range.end - range.start;
+        range.start = envelope.chunks.slice(0, chunkIndex).reduce((n, chunk) => n + chunk.rawBytes, 0);
+        range.end = Math.min(source.sourceBytes, range.start + size);
+    }
+    const window = chunkWindowForRange(envelope, range.start, range.end);
+    const expandedBytes = envelope.chunks.slice(window.firstIndex, window.lastIndex + 1).reduce((n, chunk) => n + chunk.rawBytes, 0);
+    if (expandedBytes > maxDecoded - decodedBytes)
+        fail("provider_unsupported", "The source chunks exceed the aggregate decompression budget", { reason: "decoded_budget_exceeded" });
+    let stored;
+    if (folder) {
+        // The local layout is only a routing hint. The encrypted catalog digest
+        // above authenticates every offset/hash before any chunk is selected.
+        if (window.storedLength > maxWire - wireBytes)
+            fail("provider_unsupported", "The source exceeded its aggregate wire budget");
+        const parts = [];
+        try {
+            for (let i = window.firstIndex; i <= window.lastIndex; i++) {
+                const chunk = envelope.chunks[i];
+                parts.push(await pull(0, chunk.storedBytes, folder.chunks[i], chunk));
+            }
+            stored = Buffer.concat(parts);
+        }
+        finally {
+            for (const part of parts)
+                part.fill(0);
+        }
+    }
+    else
+        stored = await pull(8 + metadataBytes + window.storedOffset, window.storedLength);
+    let bytes;
+    try {
+        const wholeSource = range.start === 0 && range.end === source.sourceBytes;
+        if (wholeSource && (stored.length !== entry.facts.storedBytes || digest(stored) !== entry.facts.ciphertextSha256)) {
+            fail("ciphertext_integrity_failed", "The complete source chunks do not match their authenticated ciphertext");
+        }
+        bytes = openChunkWindow(envelope, window, stored, { phrase }, { maxStoredBytes: maxWire, maxExpandedBytes: maxDecoded - decodedBytes, signal });
+        decodedBytes += expandedBytes;
+        if (bytes.length !== range.end - range.start)
+            fail("plaintext_integrity_failed", "The personal source returned an incomplete interval");
+        if (wholeSource && digest(bytes) !== source.sourceSha256)
+            fail("plaintext_integrity_failed", "The complete source chunks do not reproduce the cited source");
+        await assertCurrent();
+        return { source, record: recordFor(dataDir, source.archiveId, envelope, entry), bytes,
+            byteStart: range.start, byteEnd: range.end, wireBytes, decodedBytes, assertCurrent };
+    }
+    catch (error) {
+        bytes?.fill(0);
+        throw error;
+    }
+    finally {
+        stored.fill(0);
+    }
+}
+function readLimit(value, fallback) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 1 || result > LEGACY_BUFFER_LIMIT_BYTES) {
+        fail("invalid_argument", `Read budgets must be integers between 1 and ${LEGACY_BUFFER_LIMIT_BYTES}`);
+    }
+    return result;
+}
+/** Resolves the exact immutable source again for every read; citations are never permissions. */
+export async function readSourceBytes(dataDir, phrase, source, options = {}) {
+    if (source.version !== 1 || !source.archiveId || !source.envelopeArchiveId || !validHash(source.sourceSha256)
+        || !validHash(source.ciphertextSha256) || !Number.isSafeInteger(source.sourceBytes) || source.sourceBytes < 0) {
+        return fail("invalid_argument", "A complete immutable search source reference is required");
+    }
+    const maxWire = readLimit(options.maxWireBytes, 8 * 1024 * 1024);
+    const maxDecoded = readLimit(options.maxDecodedBytes, 16 * 1024 * 1024);
+    const range = { ...(options.range ?? { start: 0, end: source.sourceBytes }) };
+    if (options.chunkIndex !== undefined && (!Number.isSafeInteger(options.chunkIndex) || options.chunkIndex < 0))
+        fail("invalid_argument", "chunkIndex must be a non-negative integer");
+    if (!Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0
+        || range.end < range.start || range.end > source.sourceBytes || range.end - range.start > maxDecoded) {
+        return fail("provider_unsupported", "The requested source range exceeds the bounded read", { reason: "decoded_budget_exceeded" });
+    }
+    options.signal?.throwIfAborted();
+    if (!source.spaceKey) {
+        const record = await findArchive(dataDir, source.archiveId).catch((error) => {
+            if (isSealkeepError(error) && error.code === "archive_not_found")
+                return null;
+            throw error;
+        });
+        if (!record) {
+            const remote = await readPersonalRemoteSource(dataDir, phrase, source, range, maxWire, maxDecoded, options.signal, options.chunkIndex);
+            return remote ?? fail("archive_not_found", "The personal source has no authenticated catalog");
+        }
+        if (!isV2(record) || record.envelope.archiveId !== source.envelopeArchiveId || record.source.sha256 !== source.sourceSha256
+            || record.source.bytes !== source.sourceBytes || record.cipher.ciphertextSha256 !== source.ciphertextSha256
+            || (source.projectKey && record.source.projectKey !== source.projectKey)
+            || (source.project && record.source.project !== source.project)) {
+            return fail("ciphertext_integrity_failed", "The local source no longer matches this immutable citation");
+        }
+        const partial = range.start > 0 || range.end < source.sourceBytes;
+        // A managed chunk folder has no single archive-id object, even when a
+        // small citation fits wholly in the caller's unchanged byte budgets.
+        const managedFolder = record.remote?.provider === "vaultline" && record.remote.layout?.kind === "chunks";
+        if ((partial || managedFolder) && !record.delta && supportsChunkAccess(record.envelope)) {
+            const handle = await open(record.objectPath, "r").catch(() => null);
+            if (handle && !partial) {
+                // Keep the existing complete local-body verification when it exists.
+                await handle.close();
+            }
+            else if (!handle) {
+                const remote = await readPersonalRemoteSource(dataDir, phrase, source, range, maxWire, maxDecoded, options.signal, options.chunkIndex, true, managedFolder);
+                if (remote)
+                    return remote;
+            }
+            else {
+                try {
+                    if (options.chunkIndex !== undefined && range.start === 0) {
+                        const size = range.end - range.start;
+                        if (options.chunkIndex >= record.envelope.chunks.length)
+                            fail("invalid_argument", "The chunk hint is outside this source");
+                        range.start = record.envelope.chunks.slice(0, options.chunkIndex).reduce((n, chunk) => n + chunk.rawBytes, 0);
+                        range.end = Math.min(source.sourceBytes, range.start + size);
+                    }
+                    const window = chunkWindowForRange(record.envelope, range.start, range.end);
+                    if (window.storedLength > maxWire)
+                        fail("provider_unsupported", "The source chunks exceed the read budget");
+                    const stored = Buffer.alloc(window.storedLength);
+                    try {
+                        let offset = 0;
+                        while (offset < stored.length) {
+                            options.signal?.throwIfAborted();
+                            const result = await handle.read(stored, offset, stored.length - offset, window.storedOffset + offset);
+                            if (!result.bytesRead)
+                                fail("ciphertext_integrity_failed", "The source range is truncated");
+                            offset += result.bytesRead;
+                        }
+                        const bytes = openChunkWindow(record.envelope, window, stored, { phrase }, { maxStoredBytes: maxWire, maxExpandedBytes: maxDecoded, signal: options.signal });
+                        if (bytes.length !== range.end - range.start) {
+                            bytes.fill(0);
+                            fail("plaintext_integrity_failed", "The source returned an incomplete interval");
+                        }
+                        return { source, record, bytes, byteStart: range.start, byteEnd: range.end, wireBytes: 0,
+                            decodedBytes: record.envelope.chunks.slice(window.firstIndex, window.lastIndex + 1).reduce((n, c) => n + c.rawBytes, 0), assertCurrent: async () => { } };
+                    }
+                    finally {
+                        stored.fill(0);
+                    }
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+        }
+        if (record.source.bytes > maxDecoded || record.cipher.storedBytes > maxWire) {
+            return fail("provider_unsupported", "This source requires a verified bounded range read", { reason: "partial_read_unsupported" });
+        }
+        const chain = record.delta ? resolveDeltaChain(await listArchives(dataDir), record) : [record];
+        const parts = [];
+        const assembled = createHash("sha256");
+        let decodedBytes = 0;
+        let wireBytes = 0;
+        let storedBytes = 0;
+        let assertCurrent = async () => { };
+        let remote = false;
+        try {
+            for (const link of chain) {
+                if (!isV2(link))
+                    fail("provider_unsupported", "The dependency predates the bounded source reader", { reason: "partial_read_unsupported" });
+                storedBytes += link.cipher.storedBytes;
+                if (storedBytes > maxWire)
+                    fail("provider_unsupported", "The dependency chain exceeds the aggregate stored-byte budget");
+                let ciphertext = await localCiphertext(link, options.signal);
+                if (!ciphertext) {
+                    if (!remote) {
+                        assertCurrent = await personalReadGuard(dataDir, options.signal);
+                        remote = true;
+                    }
+                    await assertCurrent();
+                    const { pullCiphertextStream, unframeObject } = await import("./cloud.js");
+                    const framed = await collectChunks(await pullCiphertextStream(dataDir, link.id, undefined, { signal: options.signal, maxBytes: maxWire - wireBytes }), maxWire - wireBytes);
+                    wireBytes += framed.length;
+                    const opened = unframeObject(framed);
+                    if (!opened.envelope || opened.ciphertext.length !== link.cipher.storedBytes
+                        || digest(opened.ciphertext) !== link.cipher.ciphertextSha256
+                        || envelopeDigest(opened.envelope) !== envelopeDigest(link.envelope))
+                        fail("ciphertext_integrity_failed", "The remote dependency does not match its local catalog");
+                    ciphertext = opened.ciphertext;
+                }
+                try {
+                    const part = await openWhole(link.envelope, ciphertext, { phrase }, maxDecoded - decodedBytes, options.signal);
+                    parts.push(part);
+                    decodedBytes += part.length;
+                    assembled.update(part);
+                    if (decodedBytes !== link.source.bytes || assembled.copy().digest("hex") !== link.source.sha256) {
+                        fail("plaintext_integrity_failed", "A dependency prefix did not reproduce its authenticated source");
+                    }
+                }
+                finally {
+                    ciphertext.fill(0);
+                }
+            }
+            const whole = Buffer.concat(parts);
+            if (whole.length !== source.sourceBytes || digest(whole) !== source.sourceSha256)
+                fail("plaintext_integrity_failed", "Source hash mismatch");
+            const bytes = Buffer.from(whole.subarray(range.start, range.end));
+            whole.fill(0);
+            try {
+                if (bytes.length !== range.end - range.start)
+                    fail("plaintext_integrity_failed", "The dependency chain returned an incomplete interval");
+                await assertCurrent();
+                return { source, record, bytes, byteStart: range.start, byteEnd: range.end, wireBytes, decodedBytes, assertCurrent };
+            }
+            catch (error) {
+                bytes.fill(0);
+                throw error;
+            }
+        }
+        finally {
+            for (const part of parts)
+                part.fill(0);
+        }
+    }
+    if (!source.project)
+        fail("invalid_argument", "A Team citation must include its locally confirmed project");
+    const binding = teamSpaceOf(await readConfig(dataDir), source.project, source.projectKey);
+    if (!binding || binding.spaceKey !== source.spaceKey)
+        fail("forbidden", "The citation does not belong to this confirmed project");
+    const { pullBoundTeamProjectIndex } = await import("./search.js");
+    let indexWireBytes = 0;
+    const current = await pullBoundTeamProjectIndex(dataDir, phrase, source.project, [], source.projectKey, {
+        signal: options.signal, maxIndexBytes: maxWire, maxIndexDecodedBytes: maxDecoded, strictErrors: true, sourceFactsOnly: true,
+        onProgress(bytes) {
+            indexWireBytes += bytes;
+            if (indexWireBytes > maxWire)
+                fail("provider_unsupported", "Index synchronization exceeded the read's aggregate wire budget");
+        },
+    });
+    if (!current || current.spaceKey !== source.spaceKey)
+        fail("forbidden", "The current Team source index is unavailable");
+    const access = current;
+    const id = Object.keys(access.index.archives).find((candidate) => {
+        const facts = access.index.meta?.[candidate]?.archiveRecord;
+        return facts && matchesSource(candidate, facts, source);
+    });
+    if (!id)
+        fail("archive_not_found", "This exact source version is absent from the current authorized Team catalog");
+    const { createTeamReadGuard, pullTeamCiphertextRange, pullTeamCiphertextStream, unframeObject } = await import("./cloud.js");
+    const guard = current.readGuard;
+    await guard.assertCurrent([id]);
+    const { ensureTeamIdentity } = await import("./team-presence.js");
+    const privateRaw = Buffer.from((await ensureTeamIdentity(dataDir, phrase)).privateKey, "base64");
+    let wireBytes = indexWireBytes;
+    let decodedBytes = current.indexDecodedBytes;
+    const used = new Set();
+    let headRecord;
+    const partial = range.start > 0 || range.end < source.sourceBytes;
+    if (partial && options.chunkIndex !== undefined && teamCatalogEntry(access, id).facts.delta) {
+        privateRaw.fill(0);
+        return fail("provider_unsupported", "This large delta snapshot needs an authenticated logical-chunk locator; use an exact byte cursor or explicit restore", { reason: "partial_read_unsupported" });
+    }
+    try {
+        const privateKey = x25519PrivateKeyFromRaw(privateRaw);
+        async function readLink(ref, start, end, depth = 0) {
+            if (depth >= 16 || used.has(ref))
+                fail("ciphertext_integrity_failed", "The source dependency chain is cyclic or too deep");
+            used.add(ref);
+            await guard.assertCurrent(used);
+            const entry = teamCatalogEntry(access, ref);
+            const base = entry.facts.delta?.baseBytes ?? 0;
+            const parts = [];
+            try {
+                if (entry.facts.delta && start < base) {
+                    const previous = teamCatalogEntry(access, entry.facts.delta.baseArchiveId);
+                    if (previous.facts.sourceBytes !== base)
+                        fail("ciphertext_integrity_failed", "The source dependency does not match its prefix");
+                    parts.push(await readLink(entry.facts.delta.baseArchiveId, start, Math.min(end, base), depth + 1));
+                }
+                if (end > base) {
+                    let localStart = Math.max(start, base) - base;
+                    let localEnd = end - base;
+                    const rangeRead = partial && entry.facts.envelopeSha256;
+                    let envelope;
+                    if (rangeRead) {
+                        const pull = async (offset, length) => {
+                            if (length > maxWire - wireBytes)
+                                fail("provider_unsupported", "The source exceeded its aggregate wire budget");
+                            const value = await pullTeamCiphertextRange(dataDir, access.spaceKey, ref, offset, length, undefined, { signal: options.signal, maxBytes: maxWire - wireBytes, expectedMembershipVersion: access.membershipVersion, readGuard: guard });
+                            wireBytes += value.length;
+                            return value;
+                        };
+                        const header = await pull(0, 8);
+                        if (header.subarray(0, 4).toString("ascii") !== "VLA1")
+                            fail("ciphertext_integrity_failed", "The shared source frame is invalid");
+                        const length = header.readUInt32BE(4);
+                        if (length > MAX_FRAME_METADATA_BYTES || length > maxWire - wireBytes)
+                            fail("provider_unsupported", "The source envelope exceeds the wire budget");
+                        const metadata = await pull(8, length);
+                        try {
+                            envelope = JSON.parse(metadata.toString("utf8"));
+                        }
+                        catch {
+                            return fail("ciphertext_integrity_failed", "The shared source envelope is invalid");
+                        }
+                        verifyEnvelope(ref, envelope, entry);
+                        if (!supportsChunkAccess(envelope))
+                            fail("provider_unsupported", "This source predates independent compression", { reason: "partial_read_unsupported" });
+                        if (ref === id && !entry.facts.delta && options.chunkIndex !== undefined && range.start === 0) {
+                            if (options.chunkIndex >= envelope.chunks.length)
+                                fail("invalid_argument", "The chunk hint is outside this source");
+                            const size = localEnd - localStart;
+                            localStart = envelope.chunks.slice(0, options.chunkIndex).reduce((n, chunk) => n + chunk.rawBytes, 0);
+                            localEnd = Math.min(entry.plaintextBytes, localStart + size);
+                            range.start = localStart;
+                            range.end = localEnd;
+                        }
+                        const window = chunkWindowForRange(envelope, localStart, localEnd);
+                        const stored = await pull(8 + length + window.storedOffset, window.storedLength);
+                        try {
+                            parts.push(openChunkWindow(envelope, window, stored, { privateKey }, { maxStoredBytes: maxWire, maxExpandedBytes: maxDecoded - decodedBytes, signal: options.signal }));
+                            decodedBytes += envelope.chunks.slice(window.firstIndex, window.lastIndex + 1).reduce((n, chunk) => n + chunk.rawBytes, 0);
+                        }
+                        finally {
+                            stored.fill(0);
+                        }
+                    }
+                    else {
+                        if (entry.plaintextBytes > maxDecoded - decodedBytes || entry.facts.storedBytes + 8 > maxWire - wireBytes) {
+                            fail("provider_unsupported", "This source has no authenticated bounded range map within the read budget", { reason: "partial_read_unsupported" });
+                        }
+                        const framed = await collectChunks(await pullTeamCiphertextStream(dataDir, access.spaceKey, ref, undefined, { signal: options.signal, maxBytes: maxWire - wireBytes }), maxWire - wireBytes);
+                        wireBytes += framed.length;
+                        const opened = unframeObject(framed);
+                        if (!opened.envelope || opened.ciphertext.length !== entry.facts.storedBytes || digest(opened.ciphertext) !== entry.facts.ciphertextSha256) {
+                            fail("ciphertext_integrity_failed", "The source object does not match the authenticated catalog");
+                        }
+                        envelope = opened.envelope;
+                        verifyEnvelope(ref, envelope, entry);
+                        const whole = await openWhole(envelope, opened.ciphertext, { privateKey }, maxDecoded - decodedBytes, options.signal);
+                        decodedBytes += whole.length;
+                        parts.push(Buffer.from(whole.subarray(localStart, localEnd)));
+                        whole.fill(0);
+                    }
+                    if (ref === id)
+                        headRecord = recordFor(dataDir, ref, envelope, entry);
+                }
+                return Buffer.concat(parts);
+            }
+            finally {
+                for (const part of parts)
+                    part.fill(0);
+            }
+        }
+        const bytes = await readLink(id, range.start, range.end);
+        try {
+            if (bytes.length !== range.end - range.start)
+                fail("plaintext_integrity_failed", "The source did not reproduce the exact requested byte interval");
+            if (!partial && (bytes.length !== source.sourceBytes || digest(bytes) !== source.sourceSha256))
+                fail("plaintext_integrity_failed", "The dependency chain did not reproduce the cited source");
+            await guard.assertCurrent(used);
+            // A range entirely in a base still returns the head's source facts.
+            if (!headRecord) {
+                const entry = teamCatalogEntry(access, id);
+                headRecord = { version: 2, id, createdAt: entry.facts.createdAt,
+                    source: { path: entry.line[1] ?? `archive ${id}`, agent: entry.line[0] ?? "unknown", bytes: source.sourceBytes, sha256: source.sourceSha256 },
+                    cipher: { algorithm: entry.facts.algorithm, storedBytes: entry.facts.storedBytes, ciphertextSha256: entry.facts.ciphertextSha256, chunks: entry.facts.chunks },
+                    objectPath: join(dataDir, "never-materialised", `${id}.skarchive`) };
+            }
+            return { source, record: headRecord, bytes, byteStart: range.start, byteEnd: range.end, wireBytes, decodedBytes,
+                assertCurrent: () => guard.assertCurrent(used) };
+        }
+        catch (error) {
+            bytes.fill(0);
+            throw error;
+        }
+    }
+    finally {
+        privateRaw.fill(0);
+    }
+}