opencode-session-port 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "opencode-session-port",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "private": false,
+  "license": "MIT",
+  "description": "SessionPort: experimental Windows-first OpenCode TUI plugin for password-encrypted session checkpoint and restore.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "session",
+    "checkpoint",
+    "restore",
+    "encryption"
+  ],
+  "type": "module",
+  "files": [
+    "tui.ts",
+    "src/**",
+    "dist/**",
+    "tsconfig.json"
+  ],
+  "exports": {
+    "./tui": "./dist/tui.js"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "verify:package": "bun run scripts/package-verify/verify.ts",
+    "build:tui": "bun run scripts/build-tui.ts",
+    "prepack": "bun run build:tui"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.0.22",
+    "libsodium-wrappers-sumo": "0.8.4",
+    "pako": "3.0.2"
+  },
+  "peerDependencies": {
+    "@opentui/core": "0.5.14",
+    "@opentui/solid": "0.5.14",
+    "solid-js": "1.9.12"
+  },
+  "devDependencies": {
+    "@opentui/core": "0.5.14",
+    "@opentui/solid": "0.5.14",
+    "@types/node": "24.12.2",
+    "solid-js": "1.9.12",
+    "typescript": "5.9.3"
+  }
+}

package/src/core/contracts/crypto.ts

@@ -0,0 +1,66 @@
+/**
+ * One-shot byte source. Each yielded chunk is borrowed: producers must not
+ * mutate it while the consumer is processing it; consumers must copy a chunk
+ * if they retain it after advancing the source.
+ */
+export type ByteSource = AsyncIterable<Uint8Array>;
+
+/** Raw in-memory password bytes; text encoding/normalization remains an explicit open decision. */
+export type PasswordMaterial = Uint8Array;
+
+/**
+ * Fixed byte length of an `ArtifactIdentity` (128 bits). The owner-selected
+ * O-22 scheme (2026-10-09) generates one random identity per checkpoint
+ * artifact; its exact artifact placement remains PROVISIONAL (O-02).
+ */
+export const ARTIFACT_IDENTITY_BYTES = 16;
+
+/**
+ * Opaque per-artifact identity: exactly 16 random bytes (128 bits) generated
+ * once per `seal` and authenticated as part of the artifact. It is public
+ * artifact data, not a secret, and must never be confused with the Argon2
+ * salt. Callers must treat it as opaque and use it only as the stable input
+ * for deterministic remapped-ID derivation (O-22).
+ */
+export type ArtifactIdentity = Uint8Array;
+
+/** Opaque identifier for an explicitly selected, allow-listed crypto policy. */
+export interface CryptoPolicy {
+	/** A code-selected profile identifier; never take policy values from an artifact. */
+	readonly id: string;
+}
+
+/**
+ * Fully authenticated and decompressed bytes, staged in bounded memory.
+ * This value is returned only after the complete stream (including final tag),
+ * clean gzip termination, and configured bounds have all passed. The caller
+ * still must parse/validate the payload and preflight every session before any
+ * import. Ownership of `bytes` transfers exclusively to the caller; callers
+ * MUST treat it as immutable and must not retain/mutate aliases before parsing
+ * and preflight. No partial plaintext stream/callback is exposed by this boundary.
+ */
+export interface AuthenticatedPayload {
+	readonly bytes: Uint8Array;
+
+	/**
+	 * The artifact's authenticated identity, surfaced under the same conditions
+	 * as `bytes`: only after the complete stream (including the final tag),
+	 * clean strict-gzip end-of-input, and every configured bound have passed.
+	 * Caller-owned copy; opaque; never secret. Not exposed on any failure path.
+	 */
+	readonly artifactIdentity: ArtifactIdentity;
+}
+
+/** Crypto service contract. `create` requires an explicit, allow-listed policy; no default profile is implied. */
+export interface CheckpointCrypto {
+	/** Promise boundary permits asynchronous execution; it does not guarantee the synchronous KDF will not block. */
+	seal(plaintext: ByteSource, password: PasswordMaterial): Promise<ByteSource>;
+
+	/** Must reject until the entire artifact has authenticated and decompressed successfully. */
+	openAndStage(artifact: ByteSource, password: PasswordMaterial): Promise<AuthenticatedPayload>;
+}
+
+/** Public construction boundary: omitting policy is a type error; factories must reject unknown IDs. */
+export interface CheckpointCryptoFactory {
+	create(policy: CryptoPolicy): Promise<CheckpointCrypto>;
+}

package/src/core/contracts/index.ts

@@ -0,0 +1,13 @@
+export { encodeJson, snapshotJsonValue } from "./json.ts";
+export type { JsonObject, JsonPrimitive, JsonValue } from "./json.ts";
+export { ARTIFACT_IDENTITY_BYTES } from "./crypto.ts";
+export type {
+	ArtifactIdentity,
+	AuthenticatedPayload,
+	ByteSource,
+	CheckpointCrypto,
+	CheckpointCryptoFactory,
+	CryptoPolicy,
+	PasswordMaterial,
+} from "./crypto.ts";
+export type { CheckpointPayload, SessionRecord } from "./session.ts";

package/src/core/contracts/json.ts

@@ -0,0 +1,142 @@
+/** JSON-compatible values accepted at the SessionPort payload boundary. */
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonValue =
+	| JsonPrimitive
+	| readonly JsonValue[]
+	| { readonly [key: string]: JsonValue };
+
+export type JsonObject = { readonly [key: string]: JsonValue };
+
+type VisitFrame = {
+	kind: "visit";
+	value: unknown;
+	path: string;
+	assign: (copy: JsonValue) => void;
+};
+
+type LeaveFrame = { kind: "leave"; value: object };
+
+/**
+ * Copies a JSON-only snapshot, rejecting data that JSON would omit or coerce.
+ * Copies use null prototypes so inherited `toJSON` hooks cannot change the
+ * serialized representation. The traversal is iterative to avoid JS call-stack
+ * recursion. Resource limits are enforced by higher layers.
+ *
+ * `-0` is rejected because JSON.stringify would serialize it as `0`.
+ */
+export function snapshotJsonValue(value: unknown, rootPath = "$"): JsonValue {
+	let root: JsonValue | undefined;
+	const active = new WeakSet<object>();
+	const stack: Array<VisitFrame | LeaveFrame> = [
+		{ kind: "visit", value, path: rootPath, assign: (copy) => (root = copy) },
+	];
+
+	while (stack.length > 0) {
+		const frame = stack.pop()!;
+		if (frame.kind === "leave") {
+			active.delete(frame.value);
+			continue;
+		}
+
+		const current = frame.value;
+		if (current === null || typeof current === "string" || typeof current === "boolean") {
+			frame.assign(current);
+			continue;
+		}
+		if (typeof current === "number") {
+			if (!Number.isFinite(current)) throw new TypeError(`Non-finite number at ${frame.path}`);
+			if (Object.is(current, -0)) throw new TypeError(`Negative zero is not JSON-stable at ${frame.path}`);
+			frame.assign(current);
+			continue;
+		}
+		if (typeof current !== "object") {
+			throw new TypeError(`Non-JSON value (${typeof current}) at ${frame.path}`);
+		}
+		if (active.has(current)) throw new TypeError(`Cyclic value at ${frame.path}`);
+
+		if (Array.isArray(current)) {
+			const prototype = Object.getPrototypeOf(current);
+			if (prototype !== Array.prototype && prototype !== null) {
+				throw new TypeError(`Non-plain array at ${frame.path}`);
+			}
+			const lengthDescriptor = Object.getOwnPropertyDescriptor(current, "length");
+			const length = lengthDescriptor?.value;
+			if (!Number.isSafeInteger(length) || length < 0) {
+				throw new TypeError(`Invalid array length at ${frame.path}`);
+			}
+
+			const values = new Map<number, unknown>();
+			for (const key of Reflect.ownKeys(current)) {
+				if (key === "length") continue;
+				if (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key)) {
+					throw new TypeError(`Non-JSON array property at ${frame.path}`);
+				}
+				const index = Number(key);
+				if (!Number.isSafeInteger(index) || index >= length) {
+					throw new TypeError(`Unsupported array entry at ${frame.path}[${key}]`);
+				}
+				const descriptor = Object.getOwnPropertyDescriptor(current, key);
+				if (!descriptor?.enumerable || !("value" in descriptor)) {
+					throw new TypeError(`Accessor or hidden array entry at ${frame.path}[${key}]`);
+				}
+				values.set(index, descriptor.value);
+			}
+			if (values.size !== length) throw new TypeError(`Sparse array at ${frame.path}`);
+
+			const copy = new Array<JsonValue>(length);
+			Object.setPrototypeOf(copy, null);
+			frame.assign(copy);
+			active.add(current);
+			stack.push({ kind: "leave", value: current });
+			for (let index = length - 1; index >= 0; index--) {
+				stack.push({
+					kind: "visit",
+					value: values.get(index),
+					path: `${frame.path}[${index}]`,
+					assign: (child) => (copy[index] = child),
+				});
+			}
+			continue;
+		}
+
+		const prototype = Object.getPrototypeOf(current);
+		if (prototype !== Object.prototype && prototype !== null) {
+			throw new TypeError(`Non-plain object at ${frame.path}`);
+		}
+		const entries: Array<{ key: string; value: unknown }> = [];
+		for (const key of Reflect.ownKeys(current)) {
+			if (typeof key !== "string") throw new TypeError(`Symbol property at ${frame.path}`);
+			const descriptor = Object.getOwnPropertyDescriptor(current, key);
+			if (!descriptor?.enumerable || !("value" in descriptor)) {
+				throw new TypeError(`Non-enumerable or accessor property at ${frame.path}[${JSON.stringify(key)}]`);
+			}
+			entries.push({ key, value: descriptor.value });
+		}
+
+		const copy = Object.create(null) as { [key: string]: JsonValue };
+		frame.assign(copy);
+		active.add(current);
+		stack.push({ kind: "leave", value: current });
+		for (let index = entries.length - 1; index >= 0; index--) {
+			const entry = entries[index]!;
+			stack.push({
+				kind: "visit",
+				value: entry.value,
+				path: `${frame.path}[${JSON.stringify(entry.key)}]`,
+				assign: (child) => (copy[entry.key] = child),
+			});
+		}
+	}
+
+	if (root === undefined) throw new TypeError("JSON snapshot was not produced");
+	return root;
+}
+
+/** Serializes a detached JSON snapshot; inherited hooks and source mutation cannot rewrite it. */
+export function encodeJson(value: unknown): Uint8Array {
+	const snapshot = snapshotJsonValue(value);
+	const encoded = JSON.stringify(snapshot);
+	if (encoded === undefined) throw new TypeError("Value could not be serialized as JSON");
+	return new TextEncoder().encode(encoded);
+}

package/src/core/contracts/session.ts

@@ -0,0 +1,12 @@
+import type { JsonObject } from "./json.ts";
+
+/** OpenCode transfer object retained as JSON without narrowing message variants. */
+export interface SessionRecord {
+	readonly info: JsonObject;
+	readonly messages: readonly JsonObject[];
+}
+
+/** Payload shared between session collection, serialization, and restore preflight. */
+export interface CheckpointPayload {
+	readonly sessions: readonly SessionRecord[];
+}