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 JUDGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,5 +114,5 @@ Tests: `bun run test` in `engine/` and `apps/be/`, `bun run test` in `apps/fe/`,

- Everything runs on NEAR testnet. NEAR Intents has no testnet, so cross-chain payments are real signed quotes, never sent.
- Agent Market agents are real and priced live, but nobody is hired, because the market is paid in USDC on mainnet.
- The AI runs on the team's own NEAR AI Cloud credits, so judges pay nothing.
- The AI runs on the team's own NEAR AI Cloud credits, so judges pay nothing. Because that credit is shared, usage is limited during the hackathon (20 messages per guest, 60 runs an hour per account, Autopilot at most every 15 minutes); over a limit the API answers `429`. On mainnet each owner pays from their own credits and these limits go away.
- More detail: [README.md](README.md), https://docs.hellonear.xyz and https://trust.hellonear.xyz.
30 changes: 28 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -538,6 +538,31 @@ Each layer stops an attack on its own; the ones further down do not trust the on
**Why not a capped function-call key?** NEAR function-call access keys cannot transfer NEAR, and their `allowance` is a gas budget for the key's whole life, not a spending cap ([docs](https://docs.near.org/protocol/accounts-contracts/access-keys)). The spending rules therefore live in the wallet's policy, which OutLayer checks in its TEE before every signature.


### Security review (14 Nov 2026, AI-assisted)

On 14 Nov 2026 the team ran a read-only security review of this repository and the hosted API with Claude Code (Claude Opus 5.5 for the review, Claude Fable 5.2 for the fixes). **This is not an independent audit:** it is an AI-assisted review by the team's own tools, and a human approved every change. What it looked for: leaked secrets, what the public API gives away, and ways to exhaust the shared NEAR AI credit or overload the API.

| Checked | Result |
|---|---|
| Secrets in the repository and its full git history | None found. No `.env` file was ever committed; each `.env.example` holds names only |
| What the hosted API reveals (`/v1/health`, `/v1/status`, error answers) | Status, timings and error codes only: no keys, URLs or stack traces |
| Cross-site requests (CSRF) | A state-changing request from another origin answers `403 bad_origin` (tried against the hosted API) |
| Request size | Bodies over 256 KB answer `413` |
| Sign-in | One-time nonce, consumed before the signature check; the signature must come from a full-access key of the account |
| Internal payment and mail routes | Loopback only, plus the engine key and a per-Mind token |

| Found | Fixed by |
|---|---|
| Only guests had run limits. A wallet sign-in needs just a free testnet account, so a script could start runs without limit on the shared credit | Run limits for every account: 60 an hour, 300 a day, and a daily total for all users (`429 run_rate_limited`, `429 daily_capacity_reached`) |
| An Autopilot job could be scheduled every minute, and nothing limited how many jobs were on | At most every 15 minutes, 5 jobs on per Mind and 10 per owner, 100 scheduled runs a day per owner |
| `POST /v1/auth/challenge` had no limit and stores a row per call | 60 per IP per hour (`429 auth_rate_limited`) |

Each fix has tests (`limits for every user` in `apps/be/test/api.test.ts`, `engine/test/autopilot-limits.test.ts`) and ran under the load tests before merge. The limits belong to the [hackathon phase](#hackathon-phase-testnet).

The hosting side was checked by the team on 13 and 14 Nov ([#327](https://github.com/Hellonear-AI/hellonear/issues/327)): the box's firewall lets only the tunnel host reach the app ports, so the per-IP limits see the real visitor; Cloudflare's DDoS protection and managed ruleset are on; and an edge rate limit blocks an IP for 10 seconds after 60 API requests in 10 seconds.

Known limits: scheduled Autopilot runs do not count toward the daily total for all users; they are capped at 100 a day per owner by the engine. The smart contracts were not reviewed beyond their existing tests. No outside party has audited HelloNear.

### What is private, and what HelloNear keeps

The TEE protects the model calls. It does not make HelloNear's own backend blind: a Mind that remembers its owner needs that memory stored somewhere. This table says exactly where the line is.
Expand Down Expand Up @@ -825,6 +850,7 @@ During the hackathon HelloNear runs on **NEAR testnet**, so judges can try every
| **NEAR AI Agent Market (market.near.ai)** | Real agents and real prices (each agent's x402 answer); the Mind picks the cheapest within the owner's budget, but **hires no one**, because the market is paid in USDC on NEAR mainnet | The Mind **hires the agent for real**: one signed USDC transfer (NEP-366) behind the owner's approval card, and the agent's result comes back into the chat. Haggling then moves to the market's job board (post the job with a budget, compare bids, answer one counter) |
| **Haggling** | One offer to the sellers of HelloNear's own testnet data shop (two sellers on the hosted demo) | The same playbook with real sellers and the job board above |
| **Swarm auction** | Contract live and source verified at `auction.hellonear-swarm.testnet`; one round ran with scripted agent accounts, the 20-buyer simulation runs on a local sandbox | Minds join group-buying rounds from the app with their own wallets |
| **Usage limits** | The AI runs on the team's own NEAR AI Cloud credit, shared by everyone, so runs are limited: a guest gets 20 messages; every account gets 60 runs an hour and 300 a day; all users together share a daily total; an Autopilot job runs at most every 15 minutes, with at most 5 jobs on per Mind and 100 scheduled runs a day per owner. Over a limit the API answers `429` | No such limits: each owner pays for their own Minds from their own credits (pay as you go), so usage is bounded by the owner's balance, not by a shared one |
| **Relayer (NEP-366)** | **Live on the hosted demo** for two registry methods (`unequip_skill`, `set_wallet`), paid by `relayer.hellonear-swarm.testnet` | Pays the gas for owners' calls to HelloNear's contracts, so owners never need NEAR for gas |

Also stated plainly:
Expand All @@ -838,12 +864,12 @@ Also stated plainly:

**During the hackathon (now):** everything runs on NEAR testnet so judges can try it for free.
- **Guest mode:** *Continue as guest* makes a temporary user with 20 messages, a Mind from any template, sample inbox and calendar data, and payments from a shared test wallet with HelloNear's limits. No wallet, account or payment needed; data is deleted after 7 days.
- **The AI is on us:** every reply runs on NEAR AI Cloud with the team's own credits.
- **The AI is on us:** every reply runs on NEAR AI Cloud with the team's own credits. Because that credit is shared, runs and Autopilot jobs have limits during the hackathon (see [Hackathon phase](#hackathon-phase-testnet)).
- **Signing in with a NEAR wallet** (Meteor first) gives the full app: your own Mind wallet, limits, freeze, rules, connections and Autopilot.

**After the hackathon:**
- **Mainnet.** Deploy the registry and the Mind wallets on NEAR mainnet; cross-chain stablecoin payments through NEAR Intents can then be sent, not only quoted, under the same limits and approvals.
- **Pay-as-you-go AI credits.** Owners top up credits and pay for what their Minds use. Each run already records its tokens and cost.
- **Pay-as-you-go AI credits.** Owners top up credits and pay for what their Minds use. Each run already records its tokens and cost. The hackathon's run and Autopilot limits then go away: an owner's own balance is the limit.
- **More Mind templates** beyond the three today, each starting with the skills for its job.
- **Hiring on the Agent Market.** On mainnet a Mind can pay a market.near.ai agent itself: the payment is one signed delegate action (NEP-366) for the agent's quoted USDC price, behind the owner's approval card and wallet limits, and the agent's result comes back into the chat.
- **Haggling through the Agent Market's job board.** The Mind posts the owner's job with their budget, compares the bids that come in, answers one counter, and funds the escrow only through the owner's approval card. Today it compares the fixed prices of several agents and picks the cheapest within the budget.
Expand Down
2 changes: 2 additions & 0 deletions apps/be/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ OUTLAYER_URL=
OUTLAYER_CONTRACT_ID=
# Optional, default off: `true` enables POST /v1/auth/demo, the judge try-out mode (#43)
DEMO_MODE=
# Optional, default 3000: runs per UTC day across all users, try-out and wallet; then 429 daily_capacity_reached. 0 = no cap
RUNS_PER_DAY_GLOBAL=
# Optional: the shared demo wallet's OutLayer agent key (wk_…), used by every try-out user's Mind (never commit it)
DEMO_OUTLAYER_API_KEY=
# Composio project API key (ak_…, from the developer dashboard; a personal "For you" ck_… key gets 401). Without it the connection routes answer 503
Expand Down
5 changes: 3 additions & 2 deletions apps/be/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ Backend API: Postgres + pgvector, NEP-413 login, run/event storage + SSE, encryp
- Builder workflows (#20) are stored by the engine; the backend proxies `…/workflows` calls after the ownership check and sends the Mind config and secrets on each run, as for chat.
- A Mind's skills are validated against the engine's `GET /v1/skills` (the whole catalog, cached 60 s), not the skills templates offer: `near-account` and `http-request` are in no template but the Visual Builder needs them. The backend's own `GET /v1/skills` returns the same list for the skill picker. `GET /v1/skills/{skillId}` (#220) passes one skill with its SKILL.md `markdown` through for the skill page (`skill()` in `src/engine.ts`, signed-in users, cached 60 s per found skill; ids not matching `[a-z0-9-]{1,64}` and the engine's 404 answer `404 unknown_skill`).
- **Decided (#42): option B.** The engine's payment tools call `/internal/v1/wallet/*` with `X-Engine-Key` and a wallet token (`src/walletToken.ts`: HMAC with a key derived from `SECRETS_MASTER_KEY`, one Mind, 15 min). The backend adds `walletToken` to chat, approve/decline and builder runs only when the Mind has a wallet; never to Autopilot. `src/payments.ts` calls OutLayer and stores every attempt in `wallet_payments`. Internal routes sit before the session check and answer only on loopback (`isLoopback`, else `404`; the engine runs next to the backend, the tunnel comes from another host); keep all three checks.
- **Judge try-out mode (#43, `src/demo.ts`)**, on only with `DEMO_MODE=true`. `POST /v1/auth/demo` makes a fresh user (`is_demo`, `demo:<random>`, which no NEAR account can be). Limits in `config.demo`: 20 runs per user, 60 runs and 10 sign-ups per IP per hour (in memory, IP from `CF-Connecting-IP`: only the tunnel host can reach the backend), 2 payments per user that are sent or pending (checked and inserted in one transaction under a per-user advisory lock, `sendPayment`'s `cap`); the hourly windows are swept every 10 minutes. Owner actions (`denyDemo`) answer `403 demo_not_allowed`. Their Minds pay from the shared demo wallet (`DEMO_OUTLAYER_API_KEY`, `keyOf` in `src/wallets.ts`). Runs carry `demo: true` so the engine uses a sample inbox. Demo users are deleted after 7 days (at start and daily). Every finished run logs `run usage` (tokens, cost) to the journal.
- **Judge try-out mode (#43, `src/demo.ts`)**, on only with `DEMO_MODE=true`. `POST /v1/auth/demo` makes a fresh user (`is_demo`, `demo:<random>`, which no NEAR account can be). Limits in `config.demo`: 20 runs per user, 60 runs and 10 sign-ups per IP per hour (in memory, IP from `CF-Connecting-IP`: only the tunnel host can reach the backend), 2 payments per user that are sent or pending (checked and inserted in one transaction under a per-user advisory lock, `sendPayment`'s `cap`); the hourly windows are swept every 10 minutes. Owner actions (`denyDemo`) answer `403 demo_not_allowed`. Their Minds pay from the shared demo wallet (`DEMO_OUTLAYER_API_KEY`, `keyOf` in `src/wallets.ts`). Runs carry `demo: true` so the engine uses a sample inbox. Demo users are deleted after 7 days (at start and daily). Every finished run logs `run usage` (tokens, cost) to the journal. The limits for every user (next point) apply to try-out users as well.
- **Run limits for every user (`config.limits`, `assertRunAllowed` in `src/demo.ts`):** a wallet login only needs a free testnet account, so the try-out limits alone do not protect the shared NEAR AI credit. Every place that starts or resumes a run (chat, `resumeRun`, builder workflow runs, Attack Playground runs, `runTelegramChat`) calls `assertRunAllowed`; a new route that reaches the engine's run routes must too. After the try-out's own checks, for every user: 60 runs in the last hour and 300 per UTC day (`429 run_rate_limited { limit, window: "hour" | "day" }`, counted from `runs` through `minds.user_id`, served by `minds_user` + `runs_mind`), then one cap for all users per UTC day (`RUNS_PER_DAY_GLOBAL`, default 3000, `0` = off; `429 daily_capacity_reached { limit }`; one `count(*)` on `runs.started_at` at most every 5 s, bumped in memory in between; no index on `started_at` alone, add one if `runs` grows large). Deleting a Mind deletes its runs, so the hourly limit is also an in-memory window per user (it counts approve/decline answers too; both in-memory windows, the try-out's per IP and this one, are checked before either is recorded, so a refused run uses no slot) and the day's global count never goes down in a process; a restart forgets both, the stored runs remain. A user at a limit cannot answer a waiting approval until the window moves (same as a try-out at 20). `POST /v1/auth/challenge`: 60 per IP per hour (`429 auth_rate_limited`, `assertChallengeAllowed`, the same in-memory windows as the try-out's). **Autopilot's scheduled runs are not counted here:** Mastra schedules fire them inside the engine, they store no row in `runs` and pass no backend route; the engine has its own limits for them (`engine/src/autopilotLimits.ts`). **Hackathon phase only:** these limits exist because every run is paid from the team's shared credit on testnet; on mainnet owners pay from their own credits and the owner's balance replaces them. Tests (`limits for every user` in `test/api.test.ts`) lower `config.limits`; the suite turns the global cap and the challenge limit off (the local Postgres keeps old runs, every sign-in is from loopback) and `load/api.ts` raises the run limits, so keep that when adding tests that sign in or run a lot.
- **Attack Playground (#129):** `POST /v1/attacks/{id}/runs` runs the engine's scenario on a hidden playground Mind per user and attack (`minds.playground_attack`, migration 008; `playgroundMind` in `src/minds.ts`). It counts as a demo Mind for the wallet (`isDemoMind`: shared demo wallet, and the payment cap counts only demo-wallet payments, so an owner's own payments don't use it up), runs with `demo: true` and `secrets: []`, is left out of `listMinds`, and every `/v1/minds/{id}` route answers 404 for it. Approve/decline add its `attackId` (`playgroundAttackOf`).
- App connections (#13): the Composio user id is our `users.id`, which the engine already receives as `userId`. Toolkits: `gmail`, `googlecalendar` (#57), `googlemeet` (#97, Meet links for the engine's `googlecalendar_create_meeting`; auth config `ac_ISu09_uuoKCK`, scopes `meetings.space.created` + `meetings.space.settings`), and for #194: `googlesheets`, `googledrive`, `googledocs`, `slack`, `discord`, `notion`, `outlook`, `hubspot` (#195–#201, Composio-managed OAuth2, a Connect Link made for each on 11 Nov; the backend only connects, lists and disconnects them, the engine decides which actions a Mind runs), and `zoom` (#246, Composio-managed OAuth2, toolkit read live 11 Nov; no Connect Link made for it yet; the Telegram card for `zoom_create_meeting` is in `src/approvals.ts`) (`TOOLKITS` in `src/connections.ts`, slugs checked live against Composio). `POST /v1/connections/{toolkit}` creates a Tool Router session for that user and a Connect Link (callback `{FE_ORIGIN}/connections?toolkit={toolkit}`), removing unfinished attempts first; never trust the callback's query string, re-read `GET /v1/connections`. Composio-managed OAuth (no Google app of our own). Tests use `test/fake-composio.ts`.
- **Paid data (#150, `src/shop.ts`):** `GET /internal/v1/shop/{item}` answers 402 with a price and `SHOP_PAY_TO`; with `?tx=` it serves a live NEAR RPC report only for this Mind's own `sent` payment row (to `SHOP_PAY_TO`, at least the price, last hour), confirmed by RPC `tx` (success, signer = the Mind's wallet), and records the hash in `shop_purchases` (009) so it is used once. Plain `rpc.testnet.near.org` forgets transactions after a few days, hence the one-hour window. `SHOP_PAY_TO` must be on the paying wallet's address list. Tests use the fake OutLayer's `/rpc` (`tx`, `status`, `gas_price`).
Expand All @@ -65,4 +66,4 @@ Backend API: Postgres + pgvector, NEP-413 login, run/event storage + SSE, encryp

## Env

See `.env.example`: `DATABASE_URL`, `ENGINE_URL`, `ENGINE_API_KEY`, `SECRETS_MASTER_KEY` (32 bytes base64; losing it loses every stored secret), optional `PORT`, `FE_ORIGIN`, `AUTH_RECIPIENT`, `NEAR_RPC_URL`, `COOKIE_SECURE`, `OUTLAYER_URL`, `OUTLAYER_CONTRACT_ID`, `DEMO_MODE`, `DEMO_OUTLAYER_API_KEY`, `COMPOSIO_API_KEY`, `COMPOSIO_URL`, `AGENTMAIL_API_KEY`, `AGENTMAIL_API_KEY_2`, `AGENTMAIL_URL`, `DEMO_AGENTMAIL_INBOX`, `TEE_EXPLORER_URL`, `SHOP_PAY_TO`, `SHOP_SELLERS`, `RELAYER_ACCOUNT_ID`, `RELAYER_PRIVATE_KEY`, `REGISTRY_CONTRACT_ID`, `STATUS_ONECLICK_URL`, `STATUS_MARKET_URL`, `STATUS_NEAR_RPC_URL`. `.env` is gitignored; never commit it.
See `.env.example`: `DATABASE_URL`, `ENGINE_URL`, `ENGINE_API_KEY`, `SECRETS_MASTER_KEY` (32 bytes base64; losing it loses every stored secret), optional `PORT`, `FE_ORIGIN`, `AUTH_RECIPIENT`, `NEAR_RPC_URL`, `COOKIE_SECURE`, `OUTLAYER_URL`, `OUTLAYER_CONTRACT_ID`, `DEMO_MODE`, `DEMO_OUTLAYER_API_KEY`, `RUNS_PER_DAY_GLOBAL`, `COMPOSIO_API_KEY`, `COMPOSIO_URL`, `AGENTMAIL_API_KEY`, `AGENTMAIL_API_KEY_2`, `AGENTMAIL_URL`, `DEMO_AGENTMAIL_INBOX`, `TEE_EXPLORER_URL`, `SHOP_PAY_TO`, `SHOP_SELLERS`, `RELAYER_ACCOUNT_ID`, `RELAYER_PRIVATE_KEY`, `REGISTRY_CONTRACT_ID`, `STATUS_ONECLICK_URL`, `STATUS_MARKET_URL`, `STATUS_NEAR_RPC_URL`. `.env` is gitignored; never commit it.
4 changes: 4 additions & 0 deletions apps/be/load/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ process.env.TELEGRAM_WEBHOOK_BASE = 'https://load.hellonear.test'
const { server } = await import('../src/server.ts')
const { migrate, pool, query } = await import('../src/db.ts')
const { newId, randomToken, sha256 } = await import('../src/crypto.ts')
// A virtual user here makes far more runs in a few seconds than a person does in an hour, and the local Postgres keeps
// the runs of earlier load and test runs. The limits are raised, not turned off, so their counting stays in the measured path.
const { config } = await import('../src/config.ts')
Object.assign(config.limits, { runsPerUserPerHour: Infinity, runsPerUserPerDay: Infinity, runsPerDayGlobal: Number.MAX_SAFE_INTEGER })
await migrate()
await new Promise<void>((r) => server.listen(0, r))
const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
Expand Down
Loading
Loading