# AGENTS.md — harukibox

> Public agent integration manifest for harukibox SaaS.

## What is harukibox

A Taiwan-based vertical SaaS for Japan-import resellers (日本代購). It manages
products, orders, buyers, shipments, freight allocation, and trend analysis.

Audience: 1-person side-hustle resellers up through small workshops (~5 staff).

## Agent integration surface

| Surface | URL | Purpose |
|---|---|---|
| OAuth Authorization Server Metadata | https://harukibox.com/.well-known/oauth-authorization-server | RFC 8414 discovery |
| OAuth Protected Resource Metadata | https://harukibox.com/.well-known/oauth-protected-resource | RFC 9728 + MCP 2025-06 |
| OpenAPI 3.1 spec | https://harukibox.com/api/agent/openapi.json | REST API schema for ChatGPT GPT Action / generic clients |
| Remote MCP (Streamable HTTP) | https://harukibox.com/api/agent/mcp | POST JSON-RPC 2.0; Bearer auth; MCP 2025-06-18 |
| LLM-readable site overview | https://harukibox.com/llms.txt | What harukibox is, FAQs, scopes |
| Machine-readable pricing | https://harukibox.com/pricing.md | Plan tiers, limits, features |

## Authentication

- OAuth 2.1 (PKCE S256 + RFC 8628 device flow)
- Token format: `hrk_live_<base32>` (access, 90 days), `hrk_refresh_<base32>` (refresh, 365 days)
- Scopes: me / products:read / products:write / registrations:read / registrations:write
  / buyers:read / buyers:write / shippings:read / shippings:write / search

## Recommended client

- Official CLI: `@harukibox/cli` (`harukibox login` opens PKCE flow or device flow)
- Official MCP server: `@harukibox/mcp` (stdio + streamable HTTP, MCP 2025-06 spec)
- Source: https://github.com/cosmopig/harukibox-agent (Bring Your Own Agent — CLI + MCP + recipes)

## Agent capabilities (read)

- List products (with pagination + search + status filter)
- Get product by id
- List orders (registrations) by status / buyer
- List buyers (search by name / phone / email)
- List shipments
- Cross-resource search (products / buyers / registrations)
- Self-introspect: list own tokens

## Agent capabilities (write)

- Create product (with quota enforcement per plan)
- Revoke own tokens

## Rate limits

- Per-IP default: method-based (GET 120/min, POST 30/min)
- Per-token override: `rate_limit_per_minute` field if set
- OAuth /token: 200/min/IP (poll-friendly), with per-grant sub-limits:
  - authorization_code: 10/min/IP
  - refresh_token: 20/min/IP

## Security

- 401 responses include WWW-Authenticate pointing to oauth-protected-resource metadata
- 403 SCOPE_MISSING includes WWW-Authenticate insufficient_scope with required scope
- Refresh token rotation with reuse detection (chain revoke on second use after 5s grace)
- 2FA gate on OAuth approve (defense-in-depth)
- Multi-tenant: organization_id revalidated on every request (IDOR防護)

## Contact

- Support: support@harukibox.com
- CLI / MCP issues: https://github.com/cosmopig/harukibox-agent/issues

Last updated: 2026-05-16