0.3.5 jacsnpm and observability (#25)

* cleaner example git push

* npm scaffold

* rough

* wrapped

* progress

* npm untested

* add default replay attack time out

* use refactored libs in npm

* use refactored libs in npm

* fmt

* hybrid python and rust module

* testing inclunding mcp in the jacs python

* cleanup

* cleanup

* fix test

* lint

* ratatui

* try for cli install

* change

* cargo

* makefile

* migrate more to reusable cli

* finishing refactor

* fix refactor

* integrate cli with jacspy

* npm

* packaging node

* starting to add mcp

* mcp client and server

* use proper functions for request response

* npm builds

* broken again

* load agent error

* example setups

* new error

* nope

* better request response example

* better request response example

* update language

* pass npm test

* fixed bug

* change example

* more npm examples

* setting up http client server

* koa and express middleware

* express and koa middleware

* readme

* mcp refactoring

* not working npm mpc, starting over

* switch to typescript

* mcp ts

* server responds

* s

* debug

* debug

* stuck

* mcp

* mcp

* mcp

* mcp

* transport only

* transport only

* ok

* server client not working yet

* server client not working yet

* mcp working

* explain a bit more

* stdio IO in node

* changelog

* observability module

* tests almost passing

* tests pass

* test

* refactor

* consider wasm

* refactor, simplification

* fixed

* more accurate test output

* starting using tracing

* update documentatino

* tracing

* get rid of printlns

* changelog

* push reqs

Author: Hendler

.github/workflows/python.yml

@@ -47,7 +47,8 @@ jobs:
               cd /workspace/jacspy && \
               /opt/python/cp311-cp311/bin/python3.11 -m venv .venv && \
               source .venv/bin/activate && \
-              pip install pytest && \
+              pip install maturin pytest && \
+              pip install fastmcp mcp starlette && \
               make test-python"
 
   # Job to build wheels, runs ONLY on push to main

AGENTS.md

@@ -0,0 +1,10 @@
+Welcome. 
+
+You may use the top level Cargo.toml to understand the repo. 
+jacs/ is the directory with the core library. 
+./jacspy is the python wrapper with  functionality for integrations
+./jacsnpm is the npm/node wrapper with  functionality for integrations
+
+Look for examples in tests for how to use the library.
+README.md and CHANGELOG.md may be useful to understand some future goals and what has been done.
+

CHANGELOG.md

@@ -1,5 +1,6 @@
 # PLANNED
 -  machine fingerprinting v2
+- passkey-client integration
 - encrypt files at rest
 - refine schema usage
 - more getters and setters for documents recognized by schemas
@@ -8,6 +9,8 @@
 - use rcgen to sign certs, and register with ACME
  https://opentelemetry.io/docs/languages/rust/
 . ai.pydantic.dev
+- secure storage of private key for shared server envs https://crates.io/crates/tss-esapi, https://docs.rs/cryptoki/latest/cryptoki/
+
 
 ## 0.4.0
 - Domain integration
@@ -18,6 +21,7 @@
    - pass document string or document id - with optional version instead of string
    - load document whatever storage config is
    - function test output metadata about current config and current agent
+
 ## jacs-mcp 0.1.0
 
  - [] use rmcp
@@ -26,47 +30,79 @@
  - [] https://github.com/modelcontextprotocol/specification/discussions
 
 
-
 --------------------
 
-## 0.3.5
+## 0.3.6
 
-### Register agent
+### jacsnpm
 
- - [] register agent
-    - [] remove requirement to store public key type
+ - [] BUG with STDIO in general
+      fix issues with Stdio mcp client and server log noise - relates to open telemetry being used at rust layer.
+ - [] github actions builder for linux varieties
+ - [] npm install jacs (cli and available to plugin)
+ - [] a2a integration
+ - [] integrate cli
+
+### jacspy
+ - [] publish jacspy to pypi
+ - [] mcp make sure "list" request is signed?
+ - [] some integration tests
+ - [] fastapi, django, flask, guvicorn specific pre-built middleware
+ - [] auto generate agent doc from MCP server list, auto versions (important for A2A as well)
+ - [] fastmcp client and server websocket
+ - [] BUG? demo fastmcp client and server stdio 
+ - [] a2a integration
+  - [] have jacs cli installed along with wheel
+   - [] python based instructions for how to create - cli create agent 
+      1. cli create agent 
+      2. config jacspy to load each agent
+ - [] github actions builder for linux varieties
 
+### JACS core
+ - [] ensure if a user wants standard logging they can use that
+ - [] cli install instructions. a .sh command?
+ - [] expose logging function to jacspy and jacsnpm
+ - [] create centralized logging output without file output  
+ - [] CA for cert
+ - [] register public key in d option 
+ - [] register agent
+ - [] remove requirement to store public key type
  - [] upgrade pqcrypto https://github.com/rustpq/pqcrypto/issues/79
- - [] RBAC integration with header
  - [] diff versions
  - [] bucket integration
- - [] don't store  "jacs_private_key_password":  in config, don't display
- - [] register public key 
- - [] CA for cert
- - [] add timestamp to prevent timing attacks to request/response features
- - [] no_save = false should save document and still return json string instead of message on create document
- - 
+ - [] RBAC integration with header
+ - [] clean io prepping for config of io
+  - [] don't store  "jacs_private_key_password":  in config, don't display
+  - [] minor feature - no_save = false should save document and still return json string instead of message on create document
 
-## jacspy
- - [] install jacs cli with the python wheel
- - [] python based instructions for how to create - cli create agent 
-      1. cli create agent 
-      2. config jacspy to load each agent
+--------------------
 
- - [] auto generate agent doc from MCP server list, auto versions
- - [] traceable, verifiable request logs
- - [] fastmcp client and server stdio
- - [] fastmcp client and server websocket
- - [] publish jacspy to pypi
- - [] github actions builder for linux
- - [] mcp make decorator for @resource
- - [] mcp make sure "list" request is signed
+## 0.3.5
+
+- [x] Update documentation.
+
+### JACS core
+
+ - [x] add timestamp to prevent replay attacks to request/response features
+ - [x] make cli utils available to other libs
+ - [x] *** start effort to channel all logging to jacs -> open telemetry -> fs or elsewhere that doesn't write to stdio on 
+    1. the main traffic for sign and verify
+    2. all logs generated
+
+### jacspy
+
+ - [x] install python mcp libs with the python wheel, use python loader to extend/export jacs.so
 
 ## jacsnpm
+
 proof of concept
 
- - [] typescript mcp client and server
- - [] npm install jacs (cli and available to plugin)
+ - [x] scaffold
+ - [x] use refactored agent trait instead of replicating
+ - [x] typescript mcp client and server tests
+ - [x]  test sse mcp client and server
+ - [x]  node express middleware
+
 
 --------------------
 
@@ -86,7 +122,7 @@ proof of concept
 
  - [x] make decorator for easy use in @tools
  - [x] new local builder
- - [] fastmcp client and server sse
+ - [x] fastmcp client and server sse
  - [x] jacspy test -  sign(content) -> (signature, agentid, agentversion, documentid, documentversion)
  - [x] jacspy test - verify(content, signature, agentid, agentversion) -> bool, error
 

Cargo.toml

@@ -1,12 +1,13 @@
 [workspace]
 members = [
-    "jacs",          
+    "jacs",   
+    "jacsnpm",       
      # "mcp-server",      
     "jacspy"          
 ]
 resolver = "3"
 rust-version = "1.85"
- 
+
 
 readme = "README.md"
 authors = ["HAI.AI <engineering@hai.io>"]

Makefile

@@ -2,20 +2,20 @@
 
 
 build-jacs:
-	cd jacs && cargo install --path . --force
+	cd jacs && cargo install --path . --force  --features cli 
 	~/.cargo/bin/jacs --help 
 	~/.cargo/bin/jacs version
 
 test-jacs:
-	cd jacs && RUST_BACKTRACE=1 cargo test  -- --nocapture
+	cd jacs && RUST_BACKTRACE=1 cargo test --features cli   -- --nocapture
 
 test-jacs-cli:
-	cd jacs && RUST_BACKTRACE=1 cargo test --test cli_tests  -- --nocapture
+	cd jacs && RUST_BACKTRACE=1 cargo test --features cli  --test cli_tests  -- --nocapture
 
 
 
 publish-jacs:
-	cargo publish --dry-run -p jacs
+	cargo publish --features cli  --dry-run -p jacs
 
 
 test: test-jacs test-jacspy

README.md

@@ -1,22 +1,74 @@
 # JACS 
 
-Welcome to JACS (JSON Agent Communication Standard). JACS library provides
+Welcome to JACS (JSON Agent Communication Standard). 
 
-  1. a way to identify, trust and verify AI agents
-  2. authorize Agents
-  3. create, update, and verify documents
+JACS is used by agents to validate the source and identity of data. The data may be ephemeral, changing, or idempotent such as files, identities, logs, http requests. 
 
-This repo and general usage consists of 
+Example uses:
+
+  1. A document is sitting on a server. Where did it come from? Who has access to it?
+  2. An MCP server gets a request from an unknown agent, the oauth flow doesn't guarantee the identity of the client or the server after the initial handshake. 
+  3. a document is modified by multiple human and AI collaborators. Which one is latest, correct version?
+
+This repo includes JACS available in several languages:
 
-  1. a cli tool to bootstrap an agent or documents
-  2. Rust Library for general integrations
-  3. Rust MCP server for LLM usage
-  4. Python MCP server and client integrations for AUTH
-  5. MORE PLANNED
+  1. the main [rust jacs lib](./jacs/) and cli to bootstrap an agent or documents 
+  2. [Python library](./jacspy/) for use as middleware in any http and with MCP
+  3. [Node JS library](./jacsnpm) cli, middleware, and use with MCP
+
+## Python quickstart
+
+Install with `pip install jacs` with example using [fastmcp](https://github.com/jlowin/fastmcp) 
+
+```python
+# server
+import jacs
+from jacs.mcp import JACSMCPServer, JACSMCPClient
+from mcp.server.fastmcp import FastMCP 
+
+# client
+# client = JACSMCPClient(server_url)
+
+# setup
+jacs_config_path = "jacs.server.config.json"
+# set the secret
+# os.environ["JACS_PRIVATE_KEY_PASSWORD"] = "hello"   
+jacs.load(str(jacs_config_path))
+
+mcp = JACSMCPServer(FastMCP("Authenticated Echo Server"))
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+if __name__ == "__main__":
+    mcp.run()
+
+```
+
+## Node JS
+
+```js
+
+
+
+```
+
+
+## Rust
+
+The core library is used in all other implementations. 
+
+`cargo install jacs` is useful for it's cli, but to develop `cargo add jacs` is all that's needed. 
+
+
 
+## License
 
- For more details see [jacs/README.md](jacs/README.md)
- Please note that the [license][./LICENSE] isa  *modified* Apache 2.0, with the [Common Clause](https://commonsclause.com/) preamble. In simple terms, unless you are competing with HAI.AI, you can create commercial products with JACS. 
+The [license][./LICENSE] is a *modified* Apache 2.0, with the [Common Clause](https://commonsclause.com/) preamble. 
+In simple terms, unless you are directly competing with HAI.AI, you can create commercial products with JACS.
+This licensing doesn't work, please reach out to hello@hai.io. 
 
 ------
 2024, 2025 https://hai.ai

jacs/.gitignore

@@ -4,6 +4,8 @@ debug/
 target/
 .idea
 
+
+
 # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
 # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
 Cargo.lock
@@ -17,4 +19,5 @@ Cargo.lock
 jacs.config.json
 .DS_Store
 tests/fixtures/documents/*
-tests/scratch/*
+tests/scratch/*
+opentelemetry-rust

jacs/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jacs"
-version = "0.3.4"
+version = "0.3.5"
 edition = "2024"
 rust-version = "1.85"
 resolver = "3"
@@ -63,7 +63,6 @@ strum = "0.27.1"
 strum_macros = "0.27.0"
 secrecy = "0.10.3"
 aes-gcm = "0.10.3"
-clap = { version = "4.5.4", features = ["derive", "cargo"] }
 regex = "1.11.1"
 mime_guess = "2.0.5"
 flate2 = "1.1.1"
@@ -74,10 +73,26 @@ validator = "0.20.0"
 uuid = { version = "1.16.0", features = ["v4", "v7", "js"] }
 env_logger = "0.11.8"
 futures-util = "0.3.31"
-referencing = "0.29.1"
+referencing = "0.30.0"
 futures-executor = "0.3.31"
 update = "0.0.0"
 getset = "0.1.5"
+clap = { version = "4.5.4", features = ["derive", "cargo"], optional = true }
+ratatui = { version = "0.29.0", optional = true }
+
+
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
+tracing-appender = "0.2"
+tracing-opentelemetry = "0.30.0"
+opentelemetry = { version = "0.30.0", features = [] }
+opentelemetry-otlp = { version = "0.30.0", features = ["http-proto", "reqwest-client"] }
+opentelemetry_sdk = { version = "0.30.0", features = ["rt-tokio"] }
+metrics = "0.24.2"
+metrics-exporter-prometheus = "0.17"
+
+# opentelemetry-prometheus = "0.29.1"
+ 
 
 # libp2p = "0.55.0"
 # [target.'cfg(target_os = "macos")'.dependencies]
@@ -89,12 +104,12 @@ getset = "0.1.5"
 
 [dev-dependencies]
 color-eyre = "0.6"
-criterion = "0.5.1"
+criterion = "0.6.0"
 mdbook = "0.4.48"
 assert_cmd = "2.0"
 predicates = "3.1"
 tempfile = "3.19.1"
-serial_test = "0.6.0"
+serial_test = "3.2.0"
 futures = "0.3"
 
 [lib]
@@ -109,17 +124,22 @@ reqwest = {  version ="0.12.12", features = ["blocking", "json"] }
 walkdir = "2.5.0"
 object_store = { version ="0.12.0", features = ["serde","serde_json", "aws", "http"] }
 
- [target.'cfg(target_arch = "wasm32")'.dependencies]
- wasm-bindgen = "0.2.100"
- web-sys = { version = "0.3", features = ["Storage", "Window"] }
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+wasm-bindgen = "0.2.100"
+web-sys = { version = "0.3", features = ["Storage", "Window"] }
 
 [[bin]]
 name = "jacs"
 path = "src/bin/cli.rs"
+required-features = ["cli"]
+
+[features]
+cli = ["dep:clap", "dep:ratatui"]
 
 [[bench]]
 name = "sign_and_check_sig"
 harness = false
 
 [package.metadata.cargo-install]
 bin = ["jacs"]
+