opencode-session-port 0.0.0-stage → 0.1.0

package/src/core/crypto/envelope.ts

@@ -0,0 +1,232 @@
+/**
+ * PROVISIONAL SessionPort artifact envelope (format assumptions only).
+ *
+ * ============================ NOT FROZEN ============================
+ * The exact artifact header layout, framing, AAD construction, and format
+ * versioning are OPEN (O-02) and this module is a minimal, isolated,
+ * provisional versioned envelope built only so the container can round-trip
+ * under tests. Do not treat these bytes as a published/frozen format, do not
+ * write compatibility claims against them, and resolve the format question
+ * with the owner/Oracle Gate 2 before any release.
+ * ===================================================================
+ *
+ * Every format-level assumption lives in this one module so the rest of the
+ * crypto code does not bake in framing details.
+ *
+ * Provisional layout (all integers big-endian where relevant):
+ *
+ *   offset  size  field
+ *   0       8     magic "SESSPORT"
+ *   8       1     format version (1)
+ *   9       1     KDF algorithm id (2 = crypto_pwhash_ALG_ARGON2ID13)
+ *   10      1     allow-listed KDF profile code (1..255)
+ *   11      1     cipher id (1 = XChaCha20-Poly1305 secretstream)
+ *   12      1     compression id (1 = gzip, RFC 1952)
+ *   13      1     flags (0; any other value rejected)
+ *   14      2     reserved (0; any other value rejected)
+ *   16      16    per-artifact Argon2id salt (must equal crypto_pwhash_SALTBYTES)
+ *   32      16    per-artifact identity (O-22; random, authenticated, not secret)
+ *   48      24    secretstream header (crypto_secretstream_xchacha20poly1305_HEADERBYTES)
+ *   72      ..    frames: uint32 BE ciphertext byte length, then ciphertext
+ *
+ * The owner-selected O-22 identity was appended at offset 32, preserving every
+ * prior field offset; the fixed header length therefore changed from 32 to 48
+ * bytes. This is a PROVISIONAL layout change, not a backward-compatibility
+ * decision: no artifact format has been frozen or released, so no
+ * compatibility with any prior provisional bytes is claimed or required.
+ *
+ * Each frame's AAD is: full 48-byte envelope header || uint32 BE frame
+ * sequence (starting at 0) || uint32 BE ciphertext byte length. This binds the
+ * header — including the identity — ordering, and framing lengths to the
+ * authenticated ciphertext, so tampering with any identity byte fails
+ * authentication.
+ *
+ * Only a valid secretstream final tag terminates a well-formed artifact.
+ */
+import { ARTIFACT_IDENTITY_BYTES } from "../contracts/crypto.ts";
+import { CryptoContainerError } from "./errors.ts";
+
+/** ASCII "SESSPORT" — provisional magic bytes. */
+export const ENVELOPE_MAGIC = Uint8Array.from([0x53, 0x45, 0x53, 0x53, 0x50, 0x4f, 0x52, 0x54]);
+
+/** Provisional envelope format version. Unknown versions must be rejected. */
+export const ENVELOPE_FORMAT_VERSION = 1;
+
+export const ENVELOPE_HEADER_FLAGS_OFFSET = 13;
+export const ENVELOPE_HEADER_RESERVED_OFFSET = 14;
+export const ENVELOPE_HEADER_SALT_OFFSET = 16;
+export const ENVELOPE_HEADER_SALT_BYTES = 16;
+/** O-22 identity appended after the salt; placement remains PROVISIONAL (O-02). */
+export const ENVELOPE_IDENTITY_OFFSET = 32;
+export const ENVELOPE_IDENTITY_BYTES = ARTIFACT_IDENTITY_BYTES;
+/** Fixed header: metadata, salt (16..31), and identity (32..47). */
+export const ENVELOPE_HEADER_BYTES = ENVELOPE_IDENTITY_OFFSET + ENVELOPE_IDENTITY_BYTES;
+export const ENVELOPE_PROFILE_CODE_MIN = 1;
+export const ENVELOPE_PROFILE_CODE_MAX = 255;
+
+/**
+ * Wire algorithm ids are fixed by the provisional format and validated
+ * against the pinned runtime during factory construction. They are not
+ * per-artifact tunables and never select implementation behavior.
+ */
+export const ENVELOPE_KDF_ARGON2ID13 = 2;
+export const ENVELOPE_CIPHER_SECRETSTREAM_XCHACHA20POLY1305 = 1;
+export const ENVELOPE_COMPRESSION_GZIP = 1;
+export const ENVELOPE_FLAGS_NONE = 0;
+
+/** Must equal crypto_secretstream_xchacha20poly1305_HEADERBYTES (asserted at runtime). */
+export const ENVELOPE_SECRETSTREAM_HEADER_BYTES = 24;
+/** Must equal crypto_secretstream_xchacha20poly1305_ABYTES (asserted at runtime). */
+export const ENVELOPE_FRAME_OVERHEAD_BYTES = 17;
+
+export const FRAME_LENGTH_BYTES = 4;
+export const FRAME_MAX_CIPHERTEXT_BYTES = 0xffffffff;
+export const FRAME_AAD_BYTES = ENVELOPE_HEADER_BYTES + 8;
+
+export interface EnvelopeHeaderFields {
+	readonly profileCode: number;
+	/** Per-artifact KDF salt; copied. */
+	readonly salt: Uint8Array;
+	/** Per-artifact O-22 identity; must be exactly `ARTIFACT_IDENTITY_BYTES`; copied. */
+	readonly artifactIdentity: Uint8Array;
+}
+
+export interface DecodedEnvelopeHeader {
+	readonly profileCode: number;
+	/** Copy owned by the caller; clear with best-effort zeroing once used. */
+	readonly salt: Uint8Array;
+	/**
+	 * Caller-owned copy of the authenticated identity bytes. Opaque, public
+	 * (not secret); the caller must not mutate the returned copy.
+	 */
+	readonly artifactIdentity: Uint8Array;
+}
+
+function invalidHeader(message: string): never {
+	throw new CryptoContainerError("invalid-header", message);
+}
+
+/** Encodes a fresh 48-byte envelope header. Ownership transfers to the caller. */
+export function encodeEnvelopeHeader(fields: EnvelopeHeaderFields): Uint8Array {
+	const { profileCode, salt, artifactIdentity } = fields;
+	if (
+		!Number.isSafeInteger(profileCode) ||
+		profileCode < ENVELOPE_PROFILE_CODE_MIN ||
+		profileCode > ENVELOPE_PROFILE_CODE_MAX
+	) {
+		invalidHeader("policy profile code is outside the encodable range");
+	}
+	if (!(salt instanceof Uint8Array) || salt.length !== ENVELOPE_HEADER_SALT_BYTES) {
+		invalidHeader("KDF salt must be exactly the envelope salt size");
+	}
+	if (!(artifactIdentity instanceof Uint8Array) || artifactIdentity.length !== ENVELOPE_IDENTITY_BYTES) {
+		invalidHeader("artifact identity must be exactly the envelope identity size");
+	}
+	const out = new Uint8Array(ENVELOPE_HEADER_BYTES);
+	out.set(ENVELOPE_MAGIC, 0);
+	out[8] = ENVELOPE_FORMAT_VERSION;
+	out[9] = ENVELOPE_KDF_ARGON2ID13;
+	out[10] = profileCode;
+	out[11] = ENVELOPE_CIPHER_SECRETSTREAM_XCHACHA20POLY1305;
+	out[12] = ENVELOPE_COMPRESSION_GZIP;
+	out[13] = ENVELOPE_FLAGS_NONE;
+	out[14] = 0;
+	out[15] = 0;
+	out.set(salt, ENVELOPE_HEADER_SALT_OFFSET);
+	out.set(artifactIdentity, ENVELOPE_IDENTITY_OFFSET);
+	return out;
+}
+
+/**
+ * Strictly decodes and pre-validates an envelope header. Rejects wrong magic,
+ * unknown versions/algorithms, and any nonzero flag/reserved byte. Does NOT
+ * resolve the profile code; the caller must resolve it through an allow-list
+ * before any KDF work.
+ */
+export function decodeEnvelopeHeader(bytes: Uint8Array): DecodedEnvelopeHeader {
+	if (!(bytes instanceof Uint8Array) || bytes.length !== ENVELOPE_HEADER_BYTES) {
+		invalidHeader("envelope header must be exactly the fixed header size");
+	}
+	for (let index = 0; index < ENVELOPE_MAGIC.length; index += 1) {
+		if (bytes[index] !== ENVELOPE_MAGIC[index]) invalidHeader("unrecognized artifact magic");
+	}
+	if (bytes[8] !== ENVELOPE_FORMAT_VERSION) {
+		throw new CryptoContainerError("unsupported-format-version", "unsupported artifact format version");
+	}
+	if (bytes[9] !== ENVELOPE_KDF_ARGON2ID13) {
+		throw new CryptoContainerError("unsupported-algorithm", "unsupported KDF algorithm id");
+	}
+	if (bytes[11] !== ENVELOPE_CIPHER_SECRETSTREAM_XCHACHA20POLY1305) {
+		throw new CryptoContainerError("unsupported-algorithm", "unsupported cipher id");
+	}
+	if (bytes[12] !== ENVELOPE_COMPRESSION_GZIP) {
+		throw new CryptoContainerError("unsupported-algorithm", "unsupported compression id");
+	}
+	if (bytes[ENVELOPE_HEADER_FLAGS_OFFSET] !== ENVELOPE_FLAGS_NONE) invalidHeader("unknown header flags are not allowed");
+	if (bytes[ENVELOPE_HEADER_RESERVED_OFFSET] !== 0 || bytes[ENVELOPE_HEADER_RESERVED_OFFSET + 1] !== 0) {
+		invalidHeader("nonzero reserved header bytes are not allowed");
+	}
+	return {
+		profileCode: bytes[10]!,
+		salt: bytes.slice(ENVELOPE_HEADER_SALT_OFFSET, ENVELOPE_HEADER_SALT_OFFSET + ENVELOPE_HEADER_SALT_BYTES),
+		artifactIdentity: bytes.slice(
+			ENVELOPE_IDENTITY_OFFSET,
+			ENVELOPE_IDENTITY_OFFSET + ENVELOPE_IDENTITY_BYTES,
+		),
+	};
+}
+
+function requireUint32(value: number, field: string): number {
+	if (!Number.isSafeInteger(value) || value < 0 || value > FRAME_MAX_CIPHERTEXT_BYTES) {
+		throw new CryptoContainerError("invalid-frame", `${field} is outside the uint32 framing range`);
+	}
+	return value;
+}
+
+/** Builds a 4-byte BE frame ciphertext-length prefix. */
+export function encodeFrameLengthPrefix(ciphertextBytes: number): Uint8Array {
+	const out = new Uint8Array(FRAME_LENGTH_BYTES);
+	new DataView(out.buffer).setUint32(0, requireUint32(ciphertextBytes, "frame ciphertext length"), false);
+	return out;
+}
+
+/** Reads a 4-byte BE frame ciphertext-length prefix. */
+export function decodeFrameLength(prefix: Uint8Array): number {
+	if (!(prefix instanceof Uint8Array) || prefix.length !== FRAME_LENGTH_BYTES) {
+		throw new CryptoContainerError("invalid-frame", "frame length prefix must be exactly four bytes");
+	}
+	return new DataView(prefix.buffer, prefix.byteOffset, FRAME_LENGTH_BYTES).getUint32(0, false);
+}
+
+/** Encodes a frame prefix plus ciphertext into one fresh buffer. */
+export function encodeFrame(ciphertext: Uint8Array): Uint8Array {
+	if (!(ciphertext instanceof Uint8Array)) {
+		throw new CryptoContainerError("cipher-failure", "ciphertext must be a byte array");
+	}
+	const out = new Uint8Array(FRAME_LENGTH_BYTES + ciphertext.length);
+	out.set(encodeFrameLengthPrefix(ciphertext.length), 0);
+	out.set(ciphertext, FRAME_LENGTH_BYTES);
+	return out;
+}
+
+/**
+ * AAD for one secretstream frame: envelope header || frame sequence ||
+ * ciphertext length. Both sides must construct this identically.
+ */
+export function buildFrameAad(
+	envelopeHeader: Uint8Array,
+	sequence: number,
+	ciphertextBytes: number,
+): Uint8Array {
+	if (!(envelopeHeader instanceof Uint8Array) || envelopeHeader.length !== ENVELOPE_HEADER_BYTES) {
+		throw new CryptoContainerError("invalid-header", "AAD requires the full fixed envelope header");
+	}
+	requireUint32(sequence, "frame sequence");
+	requireUint32(ciphertextBytes, "frame ciphertext length");
+	const aad = new Uint8Array(FRAME_AAD_BYTES);
+	aad.set(envelopeHeader, 0);
+	const view = new DataView(aad.buffer);
+	view.setUint32(ENVELOPE_HEADER_BYTES, sequence, false);
+	view.setUint32(ENVELOPE_HEADER_BYTES + 4, ciphertextBytes, false);
+	return aad;
+}

package/src/core/crypto/errors.ts

@@ -0,0 +1,52 @@
+/**
+ * SessionPort crypto container errors.
+ *
+ * PROVISIONAL taxonomy: the user-visible error/report format is still OPEN
+ * (O-15). Codes exist so callers and tests can assert fail-closed behavior
+ * without depending on message text.
+ *
+ * Messages must never contain password, key, salt, or plaintext bytes.
+ */
+export type CryptoErrorCode =
+	| "invalid-policy-definition"
+	| "unknown-policy"
+	| "unknown-kdf-profile"
+	| "invalid-password"
+	| "unsupported-runtime"
+	| "invalid-header"
+	| "unsupported-format-version"
+	| "unsupported-algorithm"
+	| "artifact-too-large"
+	| "invalid-artifact-source"
+	| "truncated-artifact"
+	| "invalid-frame"
+	| "cipher-failure"
+	| "authentication-failed"
+	| "unexpected-tag"
+	| "missing-final-tag"
+	| "trailing-data"
+	| "compressed-limit-exceeded"
+	| "decompressed-limit-exceeded"
+	| "expansion-limit-exceeded"
+	| "gzip-error";
+
+/** Fail-closed crypto container error carrying a stable machine-readable code. */
+export class CryptoContainerError extends Error {
+	readonly code: CryptoErrorCode;
+
+	constructor(code: CryptoErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "CryptoContainerError";
+		this.code = code;
+	}
+}
+
+/** Preserves an existing container error; wraps anything else with a fallback code. */
+export function asCryptoContainerError(
+	error: unknown,
+	fallbackCode: CryptoErrorCode,
+	fallbackMessage: string,
+): CryptoContainerError {
+	if (error instanceof CryptoContainerError) return error;
+	return new CryptoContainerError(fallbackCode, fallbackMessage, { cause: error });
+}

package/src/core/crypto/gzip-stream.ts

@@ -0,0 +1,388 @@
+/**
+ * In-memory gzip streaming helpers.
+ *
+ * Compression still streams through `node:zlib` (fresh output buffers only).
+ * Decompression is implemented over pako 3.0.2's public low-level inflate API
+ * (`ZStream` with gzip-only `windowBits` 31 and the public `input`/`next_in`/
+ * `avail_in`/`output`/`next_out`/`avail_out` fields; no private state, no deep
+ * import, no magic-byte scanning) so member boundaries come from exact
+ * consumed-input positions:
+ *
+ * - one or more complete RFC 1952 members are accepted;
+ * - every byte after the final member rejects, including zero padding
+ *   (owner-decided RFC 1952 §2.2 boundary policy);
+ * - clean EOF is accepted only after at least one complete member;
+ * - the decrypted gzip input is never materialized or copied: at most the
+ *   current borrowed `ByteSource` chunk is retained, and it is released
+ *   before the next chunk is pulled, so a producer (e.g. `decryptFrames`)
+ *   may zero it as soon as the consumer advances;
+ * - compressed bytes are counted and checked against `maxCompressedBytes`
+ *   before each chunk is accepted/processed; output is checked against
+ *   `maxDecompressedBytes` while decoding (a 1-byte probe at the cap
+ *   boundary lets an exact fit still reach `Z_STREAM_END`);
+ * - output stays private until every member/trailer, exact EOF and all caps
+ *   pass; any failure returns nothing, and a success reports both the decoded
+ *   bytes and the total compressed gzip byte count (the same counter the
+ *   compressed cap is enforced against) so callers can apply expansion-ratio
+ *   accounting over decrypted gzip bytes rather than envelope bytes;
+ * - every initialized inflater is ended with a checked `zlibInflateEnd`; a
+ *   teardown failure is surfaced only when no primary failure exists;
+ * - a no-progress guard aborts instead of hanging.
+ *
+ * Ownership: borrowed source chunks are never mutated. Module-owned output
+ * chunks and the inflater scratch buffer are best-effort zeroed on success
+ * and failure; on success the concatenated result is owned by the caller.
+ * This is not secure deletion (A-07).
+ */
+/// <reference types="node" />
+import { Readable, type Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import {
+	Z_BUF_ERROR,
+	Z_DATA_ERROR,
+	Z_MEM_ERROR,
+	Z_NEED_DICT,
+	Z_NO_FLUSH,
+	Z_OK,
+	Z_STREAM_END,
+	Z_STREAM_ERROR,
+	ZStream,
+	zlibInflate,
+	zlibInflateEnd,
+	zlibInflateInit2,
+} from "pako";
+import type { ByteSource } from "../contracts/crypto.ts";
+import { asCryptoContainerError, CryptoContainerError } from "./errors.ts";
+import { bestEffortZero, bestEffortZeroAll, concatChunks } from "./zero.ts";
+
+/**
+ * Streams `source` through gzip and yields fresh output chunks. The producer
+ * yields copies so callers may retain them per the borrowed-chunk contract.
+ */
+export async function* compressStream(
+	source: ByteSource,
+	level: number | undefined,
+): AsyncGenerator<Uint8Array> {
+	const gzip = level === undefined ? createGzip() : createGzip({ level });
+	const input = Readable.from(source);
+	const finished = pipeline(input, gzip);
+	// Attach a handler immediately so an early consumer exit can never surface
+	// as an unhandled rejection; the error is re-surfaced below when relevant.
+	finished.catch(() => {});
+	try {
+		for await (const chunk of gzip) {
+			yield Uint8Array.from(chunk as Uint8Array);
+		}
+		await finished;
+	} finally {
+		input.destroy();
+		gzip.destroy();
+		await finished.catch(() => {});
+	}
+}
+
+function waitForDrain(stream: Writable): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const cleanup = () => {
+			stream.off("drain", onDrain);
+			stream.off("error", onError);
+			stream.off("close", onClose);
+		};
+		const onDrain = () => {
+			cleanup();
+			resolve();
+		};
+		const onError = (error: Error) => {
+			cleanup();
+			reject(error);
+		};
+		const onClose = () => {
+			cleanup();
+			reject(new CryptoContainerError("gzip-error", "gzip stream closed before it could drain"));
+		};
+		stream.on("drain", onDrain);
+		stream.on("error", onError);
+		stream.on("close", onClose);
+	});
+}
+
+/** windowBits = 15 + 16 selects the gzip wrapper (RFC 1952) only. */
+const GZIP_WINDOW_BITS = 31;
+
+/** Upper bound for the inflater output scratch; smaller caps shrink it. */
+const GUNZIP_OUTPUT_SCRATCH_BYTES = 64 * 1024;
+
+/**
+ * @internal TEST-ONLY seams for the strict gzip decoder. NOT part of the
+ * public crypto contract; production callers must not pass them. The
+ * `inflateEnd` override exists because `zlibInflateEnd` cannot naturally fail
+ * for a validly initialized inflater, so teardown classification is
+ * otherwise untestable.
+ */
+export interface GunzipDecoderTestSeams {
+	readonly inflateEnd?: (strm: ZStream) => number;
+}
+
+function gzipStatusError(status: number, zlibMessage: string): CryptoContainerError {
+	const detail = zlibMessage.length > 0 ? ` (${zlibMessage})` : "";
+	if (status === Z_DATA_ERROR) {
+		return new CryptoContainerError("gzip-error", `malformed gzip data (zlib status ${status}${detail})`);
+	}
+	if (status === Z_NEED_DICT) {
+		return new CryptoContainerError(
+			"gzip-error",
+			`gzip stream requires an unsupported preset dictionary (zlib status ${status}${detail})`,
+		);
+	}
+	if (status === Z_STREAM_ERROR) {
+		return new CryptoContainerError("gzip-error", `gzip inflater state error (zlib status ${status}${detail})`);
+	}
+	if (status === Z_MEM_ERROR) {
+		return new CryptoContainerError("gzip-error", `gzip inflater ran out of memory (zlib status ${status}${detail})`);
+	}
+	return new CryptoContainerError("gzip-error", `gzip inflater failed (zlib status ${status}${detail})`);
+}
+
+/**
+ * Success result of a strict bounded gunzip decode. On failure nothing is
+ * returned at all.
+ */
+export interface GunzipBoundedResult {
+	/** Decoded payload bytes; ownership transfers to the caller on success. */
+	readonly bytes: Uint8Array;
+	/**
+	 * Total decrypted compressed gzip bytes consumed across every member,
+	 * counted with the same accumulator the `maxCompressedBytes` cap is
+	 * enforced against. This is the correct denominator for expansion-ratio
+	 * accounting (never total envelope bytes).
+	 */
+	readonly compressedBytes: number;
+}
+
+/**
+ * Strictly decodes one or more complete gzip members from decrypted plaintext.
+ *
+ * Failure semantics: malformed/truncated members, any byte after the final
+ * member (including zero padding), a missing member, a compressed-input cap
+ * violation, a decompressed-output cap violation, an inflater teardown
+ * failure, and any source error all reject; nothing is returned. The staged
+ * output is best-effort zeroed on every path.
+ *
+ * Caps: `maxCompressedBytes` is a required positive safe integer checked
+ * against every pulled chunk before it is accepted/processed (later chunks
+ * are never pulled after a violation). `maxDecompressedBytes` is a
+ * non-negative safe integer checked during decode across all members.
+ *
+ * @internal Exported for the crypto tests; NOT part of the public contract.
+ */
+export async function collectGunzipBounded(
+	source: ByteSource,
+	maxCompressedBytes: number,
+	maxDecompressedBytes: number,
+	seams?: GunzipDecoderTestSeams,
+): Promise<GunzipBoundedResult> {
+	if (!Number.isSafeInteger(maxCompressedBytes) || maxCompressedBytes < 1) {
+		throw new CryptoContainerError("invalid-policy-definition", "maxCompressedBytes must be a positive safe integer");
+	}
+	if (!Number.isSafeInteger(maxDecompressedBytes) || maxDecompressedBytes < 0) {
+		throw new CryptoContainerError(
+			"invalid-policy-definition",
+			"maxDecompressedBytes must be a non-negative safe integer",
+		);
+	}
+
+	const candidate: unknown = source;
+	if (
+		candidate === null ||
+		typeof candidate !== "object" ||
+		typeof (candidate as AsyncIterable<Uint8Array>)[Symbol.asyncIterator] !== "function"
+	) {
+		throw new CryptoContainerError(
+			"invalid-artifact-source",
+			"compressed input must be an async iterable of byte chunks",
+		);
+	}
+	const iterator = (candidate as AsyncIterable<Uint8Array>)[Symbol.asyncIterator]();
+	const inflateEnd = seams?.inflateEnd ?? zlibInflateEnd;
+
+	const output: Uint8Array[] = [];
+	// Bounded inflater scratch. It shrinks for small decompressed caps so the
+	// cap is enforced by the buffer size where possible; at/over the cap a
+	// 1-byte probe detects overflow without producing unbounded output.
+	const scratch = new Uint8Array(Math.min(GUNZIP_OUTPUT_SCRATCH_BYTES, Math.max(1, maxDecompressedBytes)));
+
+	// The current borrowed chunk and the offset of its first unconsumed byte.
+	// `current` is the only compressed input retained; it is dropped before
+	// the next pull so the producer may zero it as soon as it is advanced.
+	let current: Uint8Array | undefined;
+	let currentOffset = 0;
+	let compressedBytes = 0;
+	let decompressedBytes = 0;
+	let sawMember = false;
+	let sourceExhausted = false;
+
+	const releaseCurrent = (): void => {
+		current = undefined;
+		currentOffset = 0;
+	};
+
+	/** Pulls one non-empty chunk; enforces the compressed cap before accepting it. */
+	const pullChunk = async (): Promise<boolean> => {
+		while (true) {
+			const step = await iterator.next();
+			if (step.done === true) {
+				sourceExhausted = true;
+				return false;
+			}
+			const value: unknown = step.value;
+			if (!(value instanceof Uint8Array)) {
+				throw new CryptoContainerError("gzip-error", "compressed source yielded a non-byte chunk");
+			}
+			if (value.length === 0) continue;
+			const seen = compressedBytes + value.length;
+			if (seen > maxCompressedBytes) {
+				compressedBytes = seen;
+				throw new CryptoContainerError(
+					"compressed-limit-exceeded",
+					"compressed gzip input exceeds the policy limit",
+				);
+			}
+			compressedBytes = seen;
+			current = value;
+			currentOffset = 0;
+			return true;
+		}
+	};
+
+	/** Makes at least one unconsumed input byte available for a new member. */
+	const prepareMemberInput = async (): Promise<boolean> => {
+		if (current !== undefined && currentOffset < current.length) return true;
+		releaseCurrent();
+		return pullChunk();
+	};
+
+	/**
+	 * Decodes exactly one member starting at the current position. Member end
+	 * is the exact consumed-input position (`next_in` at `Z_STREAM_END`); any
+	 * unconsumed suffix stays in the borrowed chunk for the next member or the
+	 * trailing-byte check.
+	 */
+	const inflateMember = async (): Promise<void> => {
+		const strm = new ZStream();
+		let initialized = false;
+		let memberComplete = false;
+		let primaryFailure: unknown;
+
+		try {
+			const initStatus = zlibInflateInit2(strm, GZIP_WINDOW_BITS);
+			if (initStatus !== Z_OK) {
+				throw new CryptoContainerError(
+					"gzip-error",
+					`gzip inflater initialization failed (zlib status ${initStatus})`,
+				);
+			}
+			initialized = true;
+			strm.input = current!;
+			strm.next_in = currentOffset;
+			strm.avail_in = current!.length - currentOffset;
+
+			while (true) {
+				if (strm.avail_in === 0) {
+					// The borrowed chunk is fully consumed; release it before
+					// advancing so the producer may zero it.
+					releaseCurrent();
+					if (!(await pullChunk())) {
+						throw new CryptoContainerError("gzip-error", "gzip stream ended inside a member");
+					}
+					strm.input = current!;
+					strm.next_in = 0;
+					strm.avail_in = current!.length;
+				}
+
+				const remainingOutput = maxDecompressedBytes - decompressedBytes;
+				// At/over the cap, decode into a 1-byte probe: any produced byte
+				// is an overflow; zero produced with Z_STREAM_END is an exact fit.
+				const outSize = remainingOutput <= 0 ? 1 : Math.min(scratch.length, remainingOutput);
+				strm.output = scratch;
+				strm.next_out = 0;
+				strm.avail_out = outSize;
+
+				const availBefore = strm.avail_in;
+				const status = zlibInflate(strm, Z_NO_FLUSH);
+				const consumed = availBefore - strm.avail_in;
+				const produced = outSize - strm.avail_out;
+
+				if (produced > 0) {
+					if (remainingOutput <= 0) {
+						throw new CryptoContainerError(
+							"decompressed-limit-exceeded",
+							"decompressed payload exceeds the policy limit",
+						);
+					}
+					decompressedBytes += produced;
+					output.push(Uint8Array.from(scratch.subarray(0, produced)));
+				}
+
+				if (status === Z_STREAM_END) {
+					currentOffset = strm.next_in;
+					memberComplete = true;
+					// `break` (not `return`) so the checked teardown below still
+					// runs before this member is reported as complete.
+					break;
+				}
+				if (status !== Z_OK && status !== Z_BUF_ERROR) {
+					throw gzipStatusError(status, strm.msg);
+				}
+				if (consumed === 0 && produced === 0 && strm.avail_in > 0) {
+					throw new CryptoContainerError(
+						"gzip-error",
+						`gzip inflater made no progress (zlib status ${status}); aborting to avoid a hang`,
+					);
+				}
+			}
+		} catch (error) {
+			primaryFailure = error;
+		} finally {
+			if (initialized) {
+				const endStatus = inflateEnd(strm);
+				if (endStatus !== Z_OK && primaryFailure === undefined) {
+					primaryFailure = new CryptoContainerError(
+						"gzip-error",
+						`gzip inflater teardown failed (zlib status ${endStatus})`,
+					);
+				}
+			}
+		}
+		if (primaryFailure !== undefined) throw primaryFailure;
+		if (!memberComplete) {
+			// Defensive: the loop only exits via `break` at Z_STREAM_END.
+			throw new CryptoContainerError("gzip-error", "gzip inflater did not reach the end of the member");
+		}
+	};
+
+	try {
+		while (true) {
+			if (!(await prepareMemberInput())) break;
+			await inflateMember();
+			sawMember = true;
+		}
+		if (!sawMember) {
+			throw new CryptoContainerError("gzip-error", "compressed input contains no complete gzip member");
+		}
+		return { bytes: concatChunks(output), compressedBytes };
+	} catch (error) {
+		throw asCryptoContainerError(error, "gzip-error", "gzip decompression failed");
+	} finally {
+		// Best-effort clear of every module-owned buffer on success and failure:
+		// staged plaintext output and the inflater scratch. Borrowed chunks are
+		// never cleared here.
+		bestEffortZero(scratch);
+		bestEffortZeroAll(output);
+		if (!sourceExhausted && typeof iterator.return === "function") {
+			// Aborted before EOF: let the producer close and release/zero the
+			// borrowed chunk that may still be outstanding.
+			await iterator.return(undefined).catch(() => {});
+		}
+	}
+}

package/src/core/crypto/index.ts

@@ -0,0 +1,13 @@
+/**
+ * SessionPort crypto module (PROVISIONAL container implementation).
+ *
+ * Public surface for the rest of the plugin. The artifact format and all
+ * numeric policy values remain OPEN/not frozen; production wiring must supply
+ * its own owner-approved policy definitions to
+ * `createCheckpointCryptoFactory` and must not assume defaults.
+ */
+export { createCheckpointCryptoFactory } from "./container.ts";
+export type { CryptoFactoryTestSeams } from "./container.ts";
+export { CryptoContainerError } from "./errors.ts";
+export type { CryptoErrorCode } from "./errors.ts";
+export type { CryptoPolicyDefinition, SodiumPolicyBounds } from "./policy.ts";