Phase 2: Tuya Cloud Development connector

[hanwencheng]

Context

Tuya is a PaaS for brand-owners — different role from xiaozhi-server (open firmware for makers). Per docs/research/tuya-vs-xiaozhi.md: Tuya's 1.6K stars vs xiaozhi's 26.7K make it the wrong choice for M1 PoC, but its brand-owner reach (thousands of brands shipping IoT through Tuya) makes it the right Phase 2 expansion. "Complement, don't compete" — AgentKeys adds the identity/memory/audit layer that Tuya doesn't try to be.

The Tuya MCP-server hook (announced as part of the "Hey Tuya" upgrade) is the integration surface. Through it, an AgentKeys MCP server appears as a registered tool to any Tuya-platform AI agent — exactly the cross-runtime moat we're building.

Scope (M2)

Tuya Cloud Development app registration

• Create a Tuya Cloud Development account
• Submit an integration app describing AgentKeys' tool surface
• Get app ID + secret for the Cloud Development APIs
• Document the brand-owner authorization scopes we'll request

Webhook receiver

• Endpoint: https://api.agentkeys.io/v1/tuya/events
• Auth: Tuya's signed webhook payload (HMAC verified per their docs)
• Event mapping:
  • Tuya device-paired event → agentkeys.memory.put (record the pairing in memory)
  • Tuya device-action event (lights on, etc.) → agentkeys.audit.append (audit-trail per device action)
  • Tuya device-unpaired → agentkeys.cap.revoke (revoke any cap-tokens tied to that device)

Tuya MCP-server hook

• Register AgentKeys MCP server with Tuya's "Hey Tuya" MCP catalog
• Tools exposed: same 7 active from Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107 (identity.whoami, memory.get/put, permission.check, cap.mint/revoke, audit.append)
• Per-Tuya-tenant auth: Tuya brand-owners get a per-tenant Bearer token (issued via the vendor portal Phase 2: Vendor onboarding portal (tenant tokens + billing + attributed devices) #113)

OAuth flow

• Tuya brand-owner → AgentKeys OAuth: brand-owner authorizes AgentKeys to access their device fleet on Tuya
• Brand-owner's Tuya account links to their AgentKeys vendor tenant (one-to-one)
• Standard OAuth 2.0 authorization code flow

Out of scope (defer)

• Tuya consumer-side flows (we integrate at brand-owner layer, not end-user)
• Reverse direction (AgentKeys → Tuya device control) — that's an orchestration surface, hard line per agent-iam-strategy.md §2.4
• Tuya-specific UI white-labeling (M4)

Acceptance criteria

• A Tuya-platform AI plushie (test device or partner-provided) successfully uses AgentKeys for memory + audit via the Tuya Cloud Development connector — end-to-end demonstrated
• OAuth flow exercised: Tuya brand-owner signs in via Tuya → grants AgentKeys access → AgentKeys provisions vendor tenant → first device authorizes through MCP server
• Webhook signature verification rejects forged events (negative test)
• Same actor_omni across Tuya rail + xiaozhi rail + Volcano Ark rail can read identical memory (cross-rail proof, extending M1's Phase 1: Volcano Ark MCP marketplace registration (PoC) #112 work)

Risks

Risk	Mitigation
Tuya Cloud Development API rate-limits at scale	M2 ships single-tenant capacity; check rate limits during integration test; document in vendor onboarding
Tuya's "Hey Tuya" MCP catalog has approval gating that delays listing	Start submission in week 1; M2 can ship without catalog listing if direct API access works
Tuya brand-owner OAuth scopes don't include what we need for full memory.put	If Tuya's OAuth doesn't grant device-event read, fall back to per-device manual pairing flow

References

• docs/spec/plans/milestones-roadmap.md §3 (M2 scope)
• docs/research/tuya-vs-xiaozhi.md — full Tuya vs xiaozhi analysis + Phase 2 strategic placement
• Tuya Cloud Development docs
• docs/research/agent-iam-strategy.md §5 Phase 2 (where Tuya sits in sequencing)
• Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107 (MCP server — Tuya rail registers the same tool surface)
• Phase 1: Volcano Ark MCP marketplace registration (PoC) #112 (Volcano Ark rail — parallel rail proving cross-platform moat)
• Phase 2: Vendor onboarding portal (tenant tokens + billing + attributed devices) #113 (vendor portal — Tuya brand-owners onboard through here)

Effort

~1-2 weeks. Sequencing:

1. (Days 1-3) Tuya Cloud Development signup + app registration + scope design
2. (Days 3-5) OAuth flow + brand-owner-to-AgentKeys-tenant linking
3. (Days 5-8) Webhook receiver + signature verification + event mapping
4. (Days 8-10) MCP catalog listing submission + integration test
5. (Days 10-14) Live test against a partner-provided Tuya device

Pickup notes for the next agent / developer

• Read tuya-vs-xiaozhi.md first — Tuya is a different category from xiaozhi (PaaS vs open firmware), so the integration pattern differs
• Tuya signup: international developer account at https://www.tuya.com/ — use their Cloud Development tier
• "Hey Tuya" MCP catalog status: check the latest Tuya announcement (was beta as of 2026-05); if not generally available, ship without catalog listing and add when available
• OAuth flow uses standard authz code; library-of-choice for Rust is oauth2 crate
• Webhook signature verification: Tuya docs explain their HMAC scheme; implement carefully (forgeable webhooks = forgeable audit events)
• Don't invent a Tuya-specific tool surface — re-use Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107's 7 active tools through a per-vendor Bearer token
• For cross-rail testing: when this rail goes live, extend the M1 cross-rail test (from Phase 1: Volcano Ark MCP marketplace registration (PoC) #112) to a tri-rail test (xiaozhi + Volcano Ark + Tuya)