wallet

Mokshya agent-wallet: public REST API + TEE signing (Shamir/AES-GCM). Use when debugging wallets.mokshya.io, GKE deploy, create/sign HTTP flows, rate limits,...

Security Scan

This is a documentation-only debugging skill for the Mokshya agent wallet; its instructions, declared requirements, and behavior are coherent with the stated purpose and it does not install code or request credentials itself.

Purpose & Capability

The SKILL.md content matches the skill description (debugging wallet flows, TEE signing, GKE deploy issues, and HTTP create/sign routes). It references the API/TEE architecture and gives troubleshooting steps appropriate for that purpose.

Instruction Scope

The instructions reference environment variables (DATABASE_URL, TEE_BASE_URL, INTERNAL_HMAC_SECRET) and deployment scripts, and point to source-file locations for context. They do not instruct the agent to read or exfiltrate unrelated system files or secrets, but they do assume the operator will set/configure secrets when deploying or debugging.

Install Mechanism

No install spec and no code files are present (instruction-only), so nothing will be written to disk or downloaded by the skill itself. This is the lowest-risk install posture.

Credentials

The SKILL.md mentions several sensitive env vars used by the system (e.g., INTERNAL_HMAC_SECRET, TEE_MASTER_KEY) but the skill metadata does not request any credentials. Mentioning those secrets is expected for deployment/debugging documentation, but be aware that real troubleshooting or testing will require supplying secrets to the runtime environment—do not provide TEE_MASTER_KEY to the API and avoid exposing private keys.

Persistence & Privilege

The skill is not marked always:true and does not request any persistent system privileges. Model invocation is allowed by default, which is normal; the skill contains no install-time code that would persist or change agent-wide settings.

Assessment

This skill is documentation-only and appears to honestly describe how the Mokshya wallet, TEE, and API interact. It does not itself request credentials or install code. Before using it: (1) treat the SKILL.md as guidance only—do not paste your TEE_MASTER_KEY or other private keys into an agent prompt or public logs; (2) if you will run the API/TEE flows for testing, ensure DATABASE_URL, TEE_BASE_URL, and INTERNAL_HMAC_SECRET are configured securely in your environment (use secrets management); (3) be cautious when allowing autonomous agent actions that could call POST /sign-transaction — consider restricting model invocation or requiring user confirmation for signing actions; (4) review the referenced upstream repo (https://github.com/mokshyaprotocol/agent-tee-wallet) and your own deployment manifests before connecting to production services.

Agent Wallet — open skill

Single skill file: skills/SKILL.md. Cursor loads it via .cursor/skills/open → skills/. ClawHub: clawhub publish skills.

OpenClaw / ClawHub: Source of truth for how agent_id and the TEE interact. Read before inventing “sequence mismatch” or dual-ID theories.

When to use

• POST /create-agent-wallet, POST /sign-transaction, GET /agent/:id, GET /user/:username.
• Production: wrong wallet, signing fails, /agent/2 vs /user/foo disagree on who owns an id.
• Deploy: GKE, DATABASE_URL, TEE_BASE_URL, INTERNAL_HMAC_SECRET.

WRONG hypotheses — do not use these

1. “The TEE allocates agent_id and can get out of sync with Postgres.”
   False. The API allocates agent_id (allocUsername). The TEE receives agent_id as a string and uses it only as AES-GCM AAD. No TEE wallet table or ID sequence. See api/src/teeClient.ts, tee-app/src/index.ts, tee-app/src/walletCore.ts.

2. “TEE in-memory reset breaks ID alignment.”
   Misleading. TEE is stateless for identities. Ciphertexts live in the API (Share B) and client (key_share).

3. “Fix by having the TEE return agent_id first.”
   Wrong fix. Design is already API-first ID; TEE encrypts with that AAD.

If HTTP lookups disagree on the same numeric id, the usual cause is multiple API replicas + in-memory storage (no DATABASE_URL), not TEE vs Postgres.

Architecture (authoritative)

Layer	Owns agent_id?	Persists Share B?
API (api/)	Yes	Yes (encrypted)
TEE (tee-app/)	No	No
Client	—	Holds key_share

Flow: API allocUsername → TEE create-wallet { agent_id } → API finalizeWallet. Sign: API loads Share B by id, forwards both shares + agent_id to TEE.

Troubleshooting

Symptom	Likely cause	Fix
Same agent_id, different users across requests	Multi-replica API, in-memory DB	Set DATABASE_URL (Postgres); restart API
/ready → "database":"memory" on GKE	Missing DATABASE_URL	deploy/gcp/kubectl-create-all-secrets.sh db-only etc.
502 on create	TEE / HMAC	TEE_BASE_URL, matching INTERNAL_HMAC_SECRET

See api/src/storage/createAgentWalletStorage.ts for the K8s warning when DATABASE_URL is unset.

HTTP routes

Method	Path	Notes
GET	/health, /ready	Liveness / readiness
POST	/create-agent-wallet	{ "username" } → agent_id, key_share, …
POST	/sign-transaction	{ agent_id, key_share, tx_data }
GET	/agent/:agent_id, /user/:username	Public metadata

tx_data: api/src/validation/txSchema.ts — chainId required; build JSON with jq / python3 (base64 key_share breaks in raw shell).

Errors: 409 username taken; 404 not found; 429 + scope; 502 TEE failure.

Environment

• API: api/.env.example — DATABASE_URL required for >1 replica.
• TEE: tee-app/.env.example — never TEE_MASTER_KEY on the API.

Code map

api/src/index.ts, api/src/teeClient.ts, api/src/storage/*, tee-app/src/walletCore.ts, deploy/gcp/README.md.

---

ClawHub publish

Skill format. Published skills are MIT-0; no secrets in this file.

clawhub login
cd /path/to/agent-wallet
clawhub publish skills

Install/sync in OpenClaw so agents load this pack.