Nova Submit

A self-contained IronClaw WASM tool that encrypts a file with AES-256-GCM and uploads it to a NOVA group on NEAR — in a single call.

Built for the NEAR Legion IronClaw Hackathon, but usable by any IronClaw agent that needs to write an encrypted file to a NOVA group.

What it does

Given a file's content, nova-submit performs the entire NOVA upload sequence inside the compiled WASM component — the agent's language model never touches keys, nonces, ciphertext, session tokens, or the call ordering:

1. POST /api/auth/session-token — obtain a short-lived session token
2. POST /tools/prepare_upload — obtain the group's encryption key and an upload_id
3. AES-256-GCM encrypt the file in-process (RustCrypto aes-gcm)
4. POST /tools/finalize_upload — NOVA pins the ciphertext to IPFS and records the transaction on NEAR
5. return the IPFS cid, the NEAR trans_id, and the plaintext file_hash

The agent calls the tool once with a JSON parameter object and gets back a JSON result. Because the encryption is compiled and deterministic, the model cannot corrupt the byte handling — which is the whole reason this is a WASM tool rather than a script the agent drives.

Parameters

Returns:

{ "cid": "Qm...", "trans_id": "...", "file_hash": "..." }

Usage

Once installed, the agent calls the tool when a task needs it. For example, in the agent chat:

Use the nova-submit tool. account_id is alice.nova-sdk.near, group_id is my-group, filename is report.md, and file_content is ....

The tool returns the CID, which is the permanent reference to the encrypted file in the group.

Capabilities

The tool's capabilities.json grants it network access to exactly two hosts and nothing else:

• nova-sdk.com — for the session-token exchange
• the NOVA MCP server on Phala — for prepare_upload and finalize_upload (the hostname embeds a Phala dstack verification hash and changes on redeploy — see Security notes)

It declares nova_api_key as a host-managed credential. IronClaw injects the key as X-API-Key only for requests to nova-sdk.com; this guest uses that host only for /api/auth/session-token. The key is absent from the model-visible input schema and the guest's request headers.

Security notes

• API key handling. Store the key through IronClaw's NOVA credential setup (or the NOVA_API_KEY deployment environment variable). The host keeps it outside model parameters and limits injection to nova-sdk.com. The source capabilities further declare /api/auth/session-token, but Reborn manifest v3 currently represents credential audiences at host granularity; path-level credential audiences require a future IronClaw contract change.
• Nonce. The WASI p2 sandbox exposes no random number generator, so the 12-byte AES-GCM nonce is derived as SHA-256(upload_id)[..12]. NOVA mints a unique upload_id for every prepare_upload call, keeping the (key, nonce) pair fresh even when a group encryption key is reused.
• Encryption layout. Output is nonce(12) ‖ ciphertext ‖ tag(16), base64-encoded — byte-compatible with the NOVA SDK's encrypt/decrypt (iv = bytes[:12]). A file uploaded by this tool retrieves and decrypts correctly via the NOVA JS SDK and vice versa.
• NOVA MCP hostname. The capabilities file allowlists the NOVA MCP host at 5a5223f7d1bfe777433c496b9d52ff851e927259-8000.dstack-prod5.phala.network. This is a Phala dstack deployment, and the hostname embeds the dstack instance's verification hash — proof the MCP server is the exact build NOVA published. If NOVA redeploys the MCP server, the hash changes and so does the hostname; this tool then stops working until nova-submit-tool.capabilities.json is bumped and a new release is cut. The live hostname is tracked at github.com/jcarbonnell/nova.

Reborn extension format

This tool also ships as a Reborn extension. The release generates the extension manifest from the capabilities artifact; the JSON schemas and LLM prompt docs live alongside the source:

ironhub/
  wit/tool.wit                                            ← shared WIT, used by all tools
  tools/nova-submit/
    Cargo.toml
    src/lib.rs                                            ← `path: "../../wit/tool.wit"`
    nova-submit-tool.capabilities.json                    ← the manifest is generated from this
    schemas/nova-submit/submit_file.input.v1.json         ← input schema
    schemas/nova-submit/raw_output.v1.json                ← output schema
    prompts/nova-submit/submit_file.md                    ← LLM prompt doc
    README.md

The WIT interface (near:agent@0.3.0) is identical for v1 and Reborn, so the same .wasm binary works in both runtimes. The Reborn manifest declares a single capability (nova-submit.invoke) with effects = ["network", "use_secret", "external_write"] and a host-bounded credential for the NOVA API key.

Layout

This crate follows the ironhub layout: the WIT contract is shared at the repo root and referenced via a relative path, with no per-tool build script.

The canonical standalone layout — with wit/tool.wit and build.sh inside the crate — lives at github.com/jcarbonnell/nova/nova-submit-tool and is the development home of the tool.

Build

From the ironhub repo root, or from tools/nova-submit/:

rustup target add wasm32-wasip2
cargo build --release --target wasm32-wasip2

The output is target/wasm32-wasip2/release/nova_submit_tool.wasm. Rename to nova-submit.wasm when packing into a release alongside nova-submit-tool.capabilities.json.

Compatibility

Built against WIT near:agent@0.3.0 (IronClaw 0.28.x). IronClaw evolves quickly; if a future release bumps the WIT version, the tool may need to be rebuilt against the new contract.

License

MIT