opencode-session-port 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maivand Rahmani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# SessionPort
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Encrypted session checkpoints for OpenCode.**
+
+SessionPort is a local plugin for the OpenCode TUI. It captures the sessions of your current project into a single password-encrypted artifact and restores them in another checkout, worktree, or machine. Artifacts travel with Git or any other channel you choose — SessionPort never runs Git commands itself.
+
+> **Status: experimental pre-release (0.1.0).** SessionPort completed one bounded synthetic checkpoint/restore round trip on Windows with OpenCode v2.0.22. That test used test-only password and project-selector seams and staged source, not the npm tarball. Real modal interactions and loading the packed package in OpenCode have not been verified. The checkpoint format may change; no compatibility, security, or platform-support guarantee is made.
+
+## Commands
+
+- **`/checkpoint [artifact-path]`** — collects the current project's sessions as returned by the host (child/subagent and archived sessions included when the host returns them) and writes one encrypted artifact. It fails cleanly, with no artifact, when the set is empty, a session cannot be captured completely, or the output file already exists.
+- **`/restore <artifact-path>`** — decrypts and validates the artifact before session imports, then restores it into an existing project you select. Restore does not overwrite existing sessions: exact destination matches are skipped, conflicting IDs are remapped deterministically, and parents are imported before children.
+
+Both commands are registered by the plugin as `sessionport.checkpoint` and `sessionport.restore`, and appear in the slash-command list and the command palette.
+
+## Requirements
+
+- OpenCode with the v2 TUI plugin API (exercised with OpenCode v2.0.22).
+- Windows. The current build enables the commands on Windows only; macOS and Linux are intended targets but are not yet enabled or validated.
+
+## Install
+
+Install the package plugin with the OpenCode CLI:
+
+```sh
+opencode plugin add opencode-session-port@0.1.0
+```
+
+Or add it to the `plugins` array in your `opencode.jsonc` (or `opencode.json`):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-session-port@0.1.0"]
+}
+```
+
+These are the documented OpenCode v2 setup paths; the published tarball has not yet been loaded by OpenCode. The final tarball passed npm consumer checks, but a direct Bun package-manager install timed out in the verification environment, so that install path remains unverified.
+
+## Usage
+
+### Checkpoint
+
+```text
+/checkpoint [artifact-path]
+```
+
+Without an argument, the artifact is written to `.sessionport/checkpoint-<UTC timestamp>.sessionport` inside the current project. An argument overrides the location (absolute, or relative to the project). An existing file is never overwritten — a collision fails the checkpoint.
+
+Checkpoint prompts for a password twice in a masked input (paste is allowed); both entries must match. Strength guidance is advisory — weak passwords are not rejected.
+
+### Restore
+
+```text
+/restore <artifact-path>
+```
+
+Restore first asks which existing project to import into, then prompts for the password (up to three attempts). The artifact is fully checked before the first session import. Project resolution may still update bounded host project metadata through OpenCode's public `location.get` API. Imports run parents-first, one session at a time: independent branches continue after a failure, descendants of a failed parent are blocked, and outcomes are reported per session. There is no atomic rollback. A later manual rerun may skip exact matching records, but exact retry behavior on a real host has not been established. Imported sessions are not opened or navigated to automatically.
+
+### Moving artifacts
+
+Move the artifact with Git (commit it, stash it, or sync it your own way) or any other channel. SessionPort never runs Git commands, and the password is never stored with the artifact or in the repository — if you lose it, the artifact cannot be recovered.
+
+## Security notes
+
+- Encryption is mandatory: no plaintext fallback, no plaintext temporary file.
+- Payloads are compressed, then encrypted with an Argon2id-derived key and XChaCha20-Poly1305 secretstream; truncated or tampered artifacts are rejected.
+- Password input is masked and capped at 4 KiB of UTF-8. SessionPort does not intentionally log it, write it to disk, or copy it to the clipboard. JavaScript strings cannot be reliably zeroed; no secure-erasure claim is made.
+- Protection applies to the artifact at rest only. Git history and metadata, a compromised machine, and secrets copied into session content are outside SessionPort's protection; no secure-deletion promise is made.
+- SessionPort makes no model/LLM calls and never replays historical tool calls.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run typecheck
+bun test
+bun run verify:package   # host-free package verification
+```
+
+Design and validation records live under `docs/` in this repository; they are not part of the published package.
+
+## License
+
+MIT © 2026 Maivand Rahmani

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "opencode-session-port",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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/**",
+    "tsconfig.json"
+  ],
+  "exports": {
+    "./tui": "./src/tui.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "verify:package": "bun run scripts/package-verify/verify.ts"
+  },
+  "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.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opentui/core": "0.5.14",
+    "@opentui/solid": "0.5.14",
+    "@types/node": "24.12.2",
+    "solid-js": "1.9.15",
+    "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[];
+}