Vienna Human

Vienna Human is a single Next.js App Router project for one direct-merchant, B2B-first human-in-the-loop operator in Vienna. It serves the public website, REST API, MCP Streamable HTTP server, x402 quote acceptance endpoint, operator dashboard, discovery manifests, private deliverable storage, webhook delivery, and receipt verification metadata from one checkout.

It is intentionally narrow: one verified operator, one service area, manual review before acceptance, no marketplace claim, no A2A endpoint claim, and no unsafe "anything in the real world" labor. The named principal is the customer; an AI agent may act as the principal's technical interface.

Scope

Implemented:

• Public pages for services, pricing, trust, legal placeholders, agent docs, and request intake.
• REST quote/task API under /api/v1/*.
• MCP tools at /mcp using mcp-handler 2.x and @modelcontextprotocol/server 2.x.
• x402 v2 REST payment protection for POST /api/v1/quotes/{id}/accept.
• Bazaar discovery metadata through @x402/extensions/bazaar.
• Operator dashboard with Better Auth username/password login, quote sending, messages, lifecycle actions, evidence upload, and signed completion receipts.
• PostgreSQL persistence through Drizzle migrations.
• Private local storage or S3-compatible storage for attachments.
• Bearer-protected customer access to task report, customer-visible messages, attachments, and authenticated download routes.
• Signed outbound webhooks with pg-boss retries, atomic claims, SSRF controls, and a CRON_SECRET-protected retry route.
• A publishable OpenClaw/ClawHub skill at skills/vienna-human/SKILL.md.

Not implemented:

• Native paid MCP transport. @x402/mcp 2.21.0 still has an SDK compatibility boundary with the MCP v1/v2 package split used here, so MCP returns the canonical paid REST URL.
• Automated on-chain reconciliation/finality and a verifiable refund ledger. Bare refund transitions are disabled.
• Attachment malware quarantine/scanning and phishing-resistant operator MFA; both are production launch gates.
• Automated legal, tax, accounting, consumer-rights, or trade-license decisions.
• Marketplace dispatch, multi-operator routing, escrow marketplace behavior, A2A protocol endpoints, or unmanaged public file hosting.

Discovery Flow

1. Crawlers or agents find /llms.txt, /.well-known/ai-catalog.json, /openapi.json, /mcp-card.json, /server.json, /agent.json, or /mcp.
2. They read capability and safety boundaries before submitting work.
3. A buyer or agent submits a quote request with an Idempotency-Key.
4. The response includes a high-entropy task access token. Identical retries replay the same usable token; conflicting retries return 409.
5. The operator manually screens and sends a quote with explicit EUR economics, explicit USDC atomic amount, and FX snapshot.
6. The buyer accepts through the bearer-protected x402 REST endpoint.
7. Customer-visible task state, messages, final report, receipt, and attachments are retrieved through bearer-protected REST or MCP.

Discovery and permissions caveat: catalog surfaces are public, but task data is not. Discovery does not grant authority to inspect private reports, attachments, internal messages, operator sessions, payment metadata, or webhook secrets.

Agent Layers

Layer	Surface	Role	Authority
Crawl	/, /docs, /llms.txt, sitemap, robots	Understand service and policies	Public read only
Catalog	/.well-known/ai-catalog.json, /mcp-card.json, /server.json	Registry metadata	Public read only
REST	/openapi.json, /api/v1/*	Quote/task/payment/deliverable API	Bearer token for private task data
MCP	/mcp	Tool-call interface for agents	Tool inputs include task access token for private task reads
Payment	/api/v1/quotes/{id}/accept	x402 quote funding	Bearer token plus valid x402 settlement
Operator	/operator/*	Manual review, quotes, evidence, completion	Better Auth database session
Webhooks	Registered HTTPS endpoints	Customer system notification	HMAC signed event envelope

Roles Of External Standards

• x402: payment requirement and settlement boundary for quote acceptance. This app refuses production mock funding.
• Bazaar: discovery hints for the dynamic paid REST endpoint. The route uses declareDiscoveryExtension and registers bazaarResourceServerExtension; actual indexing still depends on a compatible facilitator and real settlement.
• MCP: agent tool interface for quote requests, quote lookup, task lookup, messages, events, and cancellation.
• ARD 1.0 draft catalog: coarse service discovery at /.well-known/ai-catalog.json.
• Firecrawl/OpenClaw/ClawHub-style crawlers and SEO tools: can index public pages and manifests, but they are not authorization systems or payment transports.

Architecture

• Next.js 16.3 App Router route handlers and server actions.
• One Next.js project; no separate API service.
• PostgreSQL with Drizzle schema and SQL migrations in drizzle/.
• Zod schemas shared across REST, MCP, and operator actions.
• server-only domain/repository modules for privileged operations.
• Local private upload volume by default; S3-compatible presigned PUT/GET when configured.
• Ed25519 JWS receipts with public JWKS and did:web metadata.
• Better Auth owns operator credentials, cookies, sessions, revocation, trusted-origin checks, and login throttling; provisioning and authorization enforce exactly one user.
• rate-limiter-flexible with its direct PostgreSQL adapter owns atomic REST/MCP/form counters.
• pg-boss owns webhook job claims, retry/backoff, expiry, and retention in PostgreSQL.

Task State

Core lifecycle:

submitted -> screening -> quoted -> payment_required -> funded -> scheduled -> in_progress -> evidence_submitted -> completed

Side exits:

clarification_required, rejected, expired, cancelled, refunded, failed, disputed

The event timeline is append-only. Customer REST/MCP reads never return internal messages. Final report text is stored in Postgres and returned only after bearer authorization.

Security And Trust

• Task IDs are not secrets. Private task access requires the bearer task access token.
• Task access tokens are hashed for authorization and wrapped as compact JWE (jose, dir + A256GCM) with TASK_ACCESS_TOKEN_ENCRYPTION_KEY for idempotent replay. They are never stored in plaintext.
• Better Auth manages operator password hashing and HttpOnly/SameSite/Secure database sessions; public signup is disabled, provisioning refuses a second user, and authorization requires exactly one user.
• REST mutations and MCP POST use rate-limiter-flexible's atomic PostgreSQL backend; Better Auth rate-limits its own endpoints.
• TRUST_PROXY=false gives Better Auth no client-IP headers and makes REST/MCP ignore X-Forwarded-For/X-Real-IP; enable only behind a proxy that overwrites them and blocks direct origin access.
• Local uploads are streamed with declared byte size/content type checks, hard 50 MiB limit, server-side SHA-256, and expected-hash comparison when provided.
• S3 presigned uploads bind content type, content length, and expected checksum metadata. Finalization uses HeadObject; compatible providers must expose ChecksumSHA256 or preserve signed x-amz-meta-expected-sha256.
• Attachment downloads require bearer auth. Local mode serves private files after auth; S3 mode redirects to a short-lived presigned GET after auth.
• Webhooks use ipaddr.js to allow only globally unicast destinations, apply a five-second DNS timeout, reject redirects, pin the validated address for TLS, sign an RFC 8785-canonical envelope, and claim one pg-boss job immediately before each bounded attempt.
• Receipt signing keys are separate from payment wallet keys.

Payment Design

Commercial quotes are in EUR, but x402 funding requires explicit usdcAtomicAmount and FX metadata:

• eurAmountCents
• usdcAtomicAmount
• rate
• source
• retrievedAt

The app does not infer production USDC from EUR cents. Mock mode may derive a clearly marked mock amount only outside production. recordSettlement is idempotent by provider/network/payment ID or transaction, permits one payment row per quote, rejects failed or transaction-less settlement results, and refuses mismatched duplicates.

Mock mode records settlement before returning funded. Real x402 returns payment_verified_settlement_pending only after the SDK’s settlement step; clients must re-fetch canonical task state. A settled-on-chain but unpersisted hook is an operational reconciliation incident, not permission to start work.

Manual Vs Automated

Activity	Automated	Manual
Public discovery	Routes/manifests generated by app	Registry submission
Quote request validation	Zod, safety flags, idempotency	Acceptance/rejection
Pricing	Schema requires EUR/USDC/FX snapshot	Operator chooses amount and scope
Payment	x402 verification/settlement hook	Wallet/facilitator setup
Evidence	Hashing, private storage, receipt inclusion	Real-world task work
Completion	Receipt signing	Report writing and quality review
Webhooks	Signed dispatch and retry route	Endpoint registration and monitoring
Legal/compliance	Template placeholders	Counsel/accounting/business setup

Austrian/EU Launch Checklist

Not legal advice. Before production, review at least:

• Legal operator identity, address, contact, and imprint.
• Austrian trade/business registration and WKO guidance for the actual service category.
• B2B-only positioning, customer eligibility, and any consumer-law consequences if changed.
• VAT/tax treatment, invoicing, bookkeeping, and evidence retention.
• GDPR roles, lawful basis, retention, access/deletion process, subprocessors, and cross-border transfer issues.
• Refund/cancellation/dispute terms.
• Liability limits and prohibited task language.
• Public photography, privacy, workplace, store, venue, transport, and safety rules.
• Wallet custody, sanctions/AML screening expectations, and accounting for USDC settlement.

Build Sequence

1. Install dependencies and read local Next docs in node_modules/next/dist/docs/.
2. Generate secrets and .env.local.
3. Start Postgres, run migrations, and provision the operator with npm run operator:create.
4. Run tests, lint, typecheck, db:check, and build.
5. Configure receipt keys and verify Better Auth login/logout.
6. Configure local or S3 storage.
7. Configure Base Sepolia x402 and test a real quote acceptance.
8. Validate OpenAPI, MCP initialization/tools/list, Bazaar extension shape, and ARD/MCP registry manifests.
9. Deploy with Dokploy/Docker Compose and persistent volumes.
10. Register cron for /api/internal/webhooks/retry.
11. Complete every evidence-backed gate in docs/production-launch-gates.md before mainnet production.

Source Links

• Next.js Route Handlers: https://nextjs.org/docs/app/api-reference/file-conventions/route
• Next.js App Router docs: https://nextjs.org/docs/app
• MCP Streamable HTTP transport: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
• MCP 2026-07-28 release notes: https://blog.modelcontextprotocol.io/posts/2026-07-28/
• x402 extensions overview: https://docs.x402.org/extensions/overview
• x402 Bazaar docs: https://docs.cdp.coinbase.com/x402/bazaar
• Drizzle migrations: https://orm.drizzle.team/docs/migrations
• Better Auth Next.js integration: https://www.better-auth.com/docs/integrations/next
• pg-boss queues/jobs: https://pgboss.io/api/queues and https://pgboss.io/api/jobs
• Dokploy Docker Compose: https://docs.dokploy.com/docs/core/docker-compose
• Telegram Bot API: https://core.telegram.org/bots/api

More Docs

See docs/setup.md, docs/architecture.md, docs/security.md, docs/api.md, docs/deployment.md, docs/operations.md, docs/legal-safety.md, docs/discovery.md, docs/testing.md, and docs/production-launch-gates.md.