Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "jaynshare"
version = "2.3.1"
version = "2.3.2"
edition = "2024"
rust-version = "1.95"
publish = false
Expand Down
38 changes: 25 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,10 +179,12 @@ own `codex login`; the pool replaces it on every request.
### Claude Desktop Chat on macOS

On an enrolled Mac, install Claude Desktop in `/Applications` or
`~/Applications` and quit the app fully. Run `jaynshare trust-ca add` to trust
the pool's current interception CA in macOS, then start the connection from a
terminal. If a CA rotation is staged, also import and trust that next root from
the enrollment's `ca.pem`; Desktop checks both roots before setup.
`~/Applications` and quit the app fully, then start the connection from a
terminal. When the pool's CA is missing from macOS trust, the command shows its
fingerprint and asks `Install CA globally (needed for Claude Desktop) [y/N]`.
Answer `y` to install it in your login keychain and continue; Enter or `n`
cancels the launch. A staged replacement CA gets the same confirmation if it
is not already trusted. Desktop checks both roots before setup.

```sh
jaynshare desktop # Anthropic account picker
Expand All @@ -207,12 +209,20 @@ Changing accounts never requires quitting Desktop. With `--auto`, existing
sessions keep their server-side account binding; an exhausted account returns an
error instead of switching accounts by itself.

The integration checks Desktop **2.26454.0 with Claude Code 2.1.289**, and
**2.26454.2 or 2.31226.0 with Claude Code 2.1.293**. The 2.31226.0 profile and
startup/title contracts were verified from its installed bundle with mocked
transport; a live Chat test completed on 2.31226.0 before the egress changes.
Other versions, ambiguous managed runtimes, untrusted pool CAs and managed
device policies produce a clear error before profile setup.
Desktop versions are checked automatically. Jaynshare reads the managed runtime
version and bundle checksum from Desktop's installed bundle, checks the matching
verified runtime and runs a synthetic streaming exchange against a temporary
local gateway. This check uses no pooled account, sends no user prompt and runs
once per adapter launch. On first startup it runs after runtime provisioning,
before engine inference is forwarded. Invalid bundle metadata, mismatched runtime
verification, failed checks, untrusted pool CAs and managed device policies
produce a clear error. Existing runtimes are checked before profile setup.
This verifies the engine's protocol, not every Desktop UI feature. Desktop's
private profile format and startup/title contracts can still change and require
a Jaynshare update. The native app blocks ordinary remote debugging and custom
test profiles, so this check does not drive the GUI. The 2.31226.0 profile and
startup/title contracts were inspected from its installed bundle, and its genuine
Claude Code 2.1.293 runtime passed the local streaming check.
An app or verified runtime replacement stops the adapter; quit Desktop
fully and relaunch the command to check compatibility again.

Expand All @@ -222,8 +232,9 @@ uses your enrollment and server identity pin internally. Its native
`egressProxyUrl` points at the same loopback listener; the relay adds the proxy
credential only on its connection to the server. Desktop requires macOS CA
trust and receives `NODE_EXTRA_CA_CERTS` for its child engine. Setup leaves the
system proxy and trust store untouched. Only **Chat** is in scope. Desktop lists the models the pool's
accounts offer through `/v1/models`, and the upstream refuses those an account
system proxy untouched and installs missing CAs only after confirmation. Only
**Chat** is in scope. Desktop lists the models the pool's accounts offer through
`/v1/models`, and the upstream refuses those an account
cannot use; live Chat was checked with Sonnet 4.6. Text and explicitly
permitted local-file access were exercised in the compatibility experiment;
uploaded images, PDFs and text attachments, Cowork, Code, Chrome, connectors,
Expand All @@ -246,7 +257,8 @@ credential; other page requests use opaque tunnels. The relay has no direct
fallback when the VPS is unavailable. Native app and engine routing, first-run
downloads and IPv4/IPv6 failure behavior still need a traffic audit; a strict
guarantee covering every process requires an OS egress policy. The Jaynshare
profile disables Desktop auto-updates; install a checked newer version manually.
profile disables Desktop auto-updates; install a newer version manually, then
relaunch Jaynshare to run its compatibility checks.
Upgrading an existing profile requires stopping the adapter and quitting
Desktop fully before setup adds the proxy and update settings and enables model
discovery. Repeat the trust check and fully relaunch after CA rotation.
Expand Down
13 changes: 11 additions & 2 deletions docs/security-and-privacy.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,11 +170,20 @@ or `jaynshare codex` launches, through `NODE_EXTRA_CA_CERTS` or
`CODEX_CA_CERTIFICATE`. Outside Windows, a Codex launch also sets
`CURL_CA_BUNDLE` to the system's roots plus the CA, so Codex's updater can
fetch its installer; any `curl` run under that Codex trusts the CA too. It
enters the operating system's trust store only if the engineer runs
`jaynshare trust-ca add`, which always asks first. Desktop
enters the operating system's trust store only after confirmation through
`jaynshare trust-ca add` or Desktop's inline
`Install CA globally (needed for Claude Desktop) [y/N]` prompt. Desktop
requires macOS trust for both current and staged roots before profile setup;
Enter or `n` cancels, and `--yes` does not bypass this confirmation.
`trust-ca add` installs only the current root. Desktop's launch also supplies
the CA bundle to its engine through `NODE_EXTRA_CA_CERTS`.
Desktop runtime compatibility uses the installed bundle's embedded version and
checksum, its matching `.verified` marker and a bounded synthetic streaming
exchange with a local mock gateway. The check has a fresh temporary profile,
no tools, no enrolled credential and no pooled-account usage. It does not certify
Desktop's private profile or GUI contracts; changed packaging or protocols can
require a Jaynshare update. Application and checked-runtime replacement still
stop the adapter.
Desktop's egress relay refuses its local Gateway bearer in every Authorization
value, including duplicate headers and alternate casing; destination credentials
continue through the proxy.
Expand Down
2 changes: 1 addition & 1 deletion src/cli/help.rs
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ pub(super) static DOCS: &[VerbDoc] = &[
"desktop",
Engineer,
None,
"Open macOS Claude Desktop Chat through a foreground Gateway that monitors the pool's accounts; its arrow keys and Enter switch account, and closing this command stops the connection. Quit Desktop fully before initial setup",
"Open macOS Claude Desktop Chat through a foreground Gateway that monitors the pool's accounts; its arrow keys and Enter switch account, and closing this command stops the connection. Quit Desktop fully before initial setup; missing pool CAs are installed in macOS trust only after confirmation",
[4, 5, 6, 7, 11, 15, 16],
[
"jaynshare desktop",
Expand Down
1 change: 1 addition & 0 deletions src/cli/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ pub(crate) use control::{
};
use help::Role;
pub(crate) use update::follow;
pub(crate) use verbs::confirm;
use verbs::{
account_add, account_availability, account_list, account_login, account_remove, account_rename,
account_replace, account_show, api, ca_export, ca_rotate, ca_show, client_list, client_rename,
Expand Down
2 changes: 1 addition & 1 deletion src/cli/verbs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1590,7 +1590,7 @@ pub(super) fn typed_line(prompt: &str) -> Result<String, Failure> {
}

/// A skippable confirmation on the controlling terminal.
pub(super) fn confirm(prompt: &str) -> Result<bool, Failure> {
pub(crate) fn confirm(prompt: &str) -> Result<bool, Failure> {
if !std::io::stdin().is_terminal() {
return Err(Failure::local(
21,
Expand Down
133 changes: 78 additions & 55 deletions src/desktop/app.rs
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
//! Compatibility checks against the installed app and its verified managed CLI.

use std::path::{Path, PathBuf};
use std::sync::OnceLock;
use std::time::{Duration, SystemTime};

use tokio::process::Command;
use tokio::sync::OnceCell;

use super::config;
use super::{bundle, compatibility, config};

type Stamp = (u64, SystemTime);

pub struct App {
pub bundle: PathBuf,
runtime: OnceLock<(PathBuf, Vec<(PathBuf, Stamp)>)>,
runtime: OnceCell<(PathBuf, Vec<(PathBuf, Stamp)>)>,
version: String,
runtime_version: &'static str,
expected_runtime: bundle::Runtime,
stamps: Vec<(PathBuf, Stamp)>,
}

Expand Down Expand Up @@ -45,36 +45,38 @@ impl App {
.arg(&plist),
)
.await?;
// shortcut: this private profile format is checked only on these versions; recheck the native app before adding versions.
let runtime_version = match version.as_str() {
"2.26454.0" => "2.1.289",
"2.26454.2" | "2.31226.0" => "2.1.293",
_ => {
return Err(format!(
"Claude Desktop {version} has not been checked; supported versions: 2.26454.0, 2.26454.2 and 2.31226.0"
));
}
};
let stamps = [plist, bundle.join("Contents/Resources/app.asar")]
let archive = bundle.join("Contents/Resources/app.asar");
let stamps = [plist, archive.clone()]
.into_iter()
.map(|path| stamp(&path).map(|stamp| (path, stamp)))
.collect::<Result<_, _>>()?;
let expected_runtime = bundle::runtime(&archive)?;
let app = Self {
bundle,
runtime: OnceLock::new(),
runtime: OnceCell::new(),
version,
runtime_version,
expected_runtime,
stamps,
};
if runtime(runtime_version)?.is_some() {
app.unchanged()?;
if app.find_runtime()?.is_some() {
app.runtime().await?;
}
Ok(app)
}

pub async fn runtime(&self) -> Result<&Path, String> {
if self.runtime.get().is_none() {
let runtime = runtime(self.runtime_version)?.ok_or("Desktop's managed runtime is still provisioning through the proxy; retry after its download finishes")?;
self.runtime.get_or_try_init(|| async {
let runtime = self.find_runtime()?.ok_or("Desktop's managed runtime is still provisioning through the proxy; retry after its download finishes")?;
let marker = runtime
.ancestors()
.nth(4)
.expect("managed bundle")
.join(".verified");
let stamps: Vec<_> = [runtime.clone(), marker]
.into_iter()
.map(|path| stamp(&path).map(|stamp| (path, stamp)))
.collect::<Result<_, _>>()?;
let actual = output(
Command::new(&runtime)
.arg("--version")
Expand All @@ -83,23 +85,23 @@ impl App {
.env("PATH", "/usr/bin:/bin"),
)
.await?;
if actual.split_whitespace().next() != Some(self.runtime_version) {
if actual.split_whitespace().next() != Some(self.expected_runtime.version.as_str()) {
return Err(format!(
"the managed Claude Code runtime is incompatible; expected {}",
self.runtime_version
self.expected_runtime.version
));
}
let marker = runtime
.ancestors()
.nth(4)
.expect("managed bundle")
.join(".verified");
let stamps = [runtime.clone(), marker]
.into_iter()
.map(|path| stamp(&path).map(|stamp| (path, stamp)))
.collect::<Result<_, _>>()?;
let _ = self.runtime.set((runtime, stamps));
}
compatibility::check(&runtime).await?;
if stamps
.iter()
.any(|(path, before)| stamp(path).as_ref() != Ok(before))
{
return Err(
"Desktop's managed runtime changed during its compatibility check".into(),
);
}
Ok::<_, String>((runtime, stamps))
}).await?;
self.unchanged()?;
Ok(&self.runtime.get().expect("verified runtime").0)
}
Expand All @@ -113,7 +115,7 @@ impl App {
stamps
.iter()
.any(|(file, before)| stamp(file).as_ref() != Ok(before))
|| runtime(self.runtime_version).as_ref() != Ok(&Some(path.clone()))
|| self.find_runtime().as_ref() != Ok(&Some(path.clone()))
})
{
return Err(format!(
Expand All @@ -124,6 +126,32 @@ impl App {
Ok(())
}

fn find_runtime(&self) -> Result<Option<PathBuf>, String> {
let expected = &self.expected_runtime;
let directory = config::profile()
.join("claude-code")
.join(&expected.version);
let managed = directory.join(&expected.checksum[..12]);
let binary = managed.join("claude.app/Contents/MacOS/claude");
let marker = managed.join(".verified");
if !binary.is_file() || !marker.is_file() {
return Ok(None);
}
if std::fs::metadata(&marker).map_err(|e| e.to_string())?.len() > 128 {
return Err("Desktop's managed runtime verification marker is invalid".into());
}
if std::fs::read_to_string(marker)
.map_err(|e| e.to_string())?
.trim()
!= expected.checksum
{
return Err(
"Desktop's managed runtime verification does not match its bundled manifest".into(),
);
}
Ok(Some(binary))
}

pub async fn open(&self, ca: &Path) -> Result<(), String> {
output(
Command::new("open")
Expand All @@ -136,27 +164,6 @@ impl App {
}
}

fn runtime(version: &str) -> Result<Option<PathBuf>, String> {
let directory = config::profile().join("claude-code").join(version);
let mut candidates = Vec::new();
let entries = match std::fs::read_dir(&directory) {
Ok(entries) => entries,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(format!("cannot read Desktop's managed runtime: {e}")),
};
for entry in entries {
let path = entry.map_err(|e| e.to_string())?.path();
let binary = path.join("claude.app/Contents/MacOS/claude");
if path.join(".verified").is_file() && binary.is_file() {
candidates.push(binary);
}
}
if candidates.len() > 1 {
return Err("Desktop's active verified runtime is ambiguous".into());
}
Ok(candidates.pop())
}

fn stamp(path: &Path) -> Result<Stamp, String> {
let metadata = std::fs::metadata(path).map_err(|e| format!("{}: {e}", path.display()))?;
Ok((
Expand Down Expand Up @@ -218,3 +225,19 @@ async fn output(command: &mut Command) -> Result<String, String> {
.map(|s| s.trim().to_string())
.map_err(|_| "invalid Desktop version output".into())
}

#[cfg(test)]
mod tests {
use super::*;

#[tokio::test]
#[ignore = "uses the installed macOS Desktop bundle and managed runtime"]
async fn installed_runtime_passes_local_streaming_check() {
let app = App::resolve()
.await
.expect("installed Desktop compatibility");
app.runtime()
.await
.expect("managed runtime streaming check");
}
}
Loading
Loading