Building a product, for agents
The brief an agent follows when it builds a new Buun Group product, or adds Buun Identity to one, without reading the Buun Group repositories. Each step is something to do, then something to check.
Before writing code
- Read llms-full.txt once: it is every page here in one file.
- The product runs on Cloudflare Workers. Its MCP server is a Worker of its own, on
mcp.<product domain>, with its MCP endpoint at/mcp-oauth. - Pick the product id: lower case letters, one word, such as
plotwork. It must be added toPRODUCTSin@buun-group/coreby a change tobuun-group/buungroup-app, and the package published, before anything else names it.
The rules that are easy to get wrong
| Rule | Check |
|---|---|
Accept a token only when aud is exactly your own address | A token for the gateway or another product is refused, with a test |
Insist on typ: at+jwt and alg: ES256 | An ID token sent as an access token is refused, with a test |
Take the issuer and your own address from wrangler.jsonc vars, per environment | No address is read from a token or a request |
| Link an existing user by address only when it is verified on both sides | An unverified address makes a new user, with a test |
Answer 401 with WWW-Authenticate: Bearer error="invalid_token" for any token that fails | The gateway trades again on a 401 and on nothing else |
| Never log a token, and never forward one | Search the code for the header name before shipping |
| Never keep a plan in a token or a long cache | Ask /oauth/plans each time it matters |
| Keep your own sign-in working beside Buun Identity's | Pick the check by the token's iss, then verify everything |
The steps
- Sign-in on the website. Ask staff for a Buun Group product client with your redirect addresses. Build the sign-in flow: PKCE S256,
state,isschecked on return, tokens checked as on Tokens and keys. Test: a wrongstateis refused; a wrongissis refused. - Plans. Read
/oauth/planswhere the product decides what a person may do. Test: a cancelled plan stops access at the next request. - The MCP server. Make it accept Buun Identity tokens as on Accepting Buun Identity tokens. Test every refusal in the table there.
- Tools. Give each tool a stable name, an honest description,
readOnlyHintordestructiveHint, and an input schema under 32 KB. Staff approve each version before an agent sees it: Tool review. - The gateway. Ask for, or make as a reviewed change to
buun-group/buungroup-gateway, a catalogue entry for each environment withacceptsIdentityTokens: true, and a resource server in the staff console for each MCP address: How the gateway works. - Test on one machine as on Local development:
pnpm dev:exchange, a plan for yourself,claude mcp add --transport http buun-local http://localhost:28502/mcp, approve the tools, call one.
Asking the person
Stop and ask before anything outward-facing: deploying, setting a secret, applying a remote migration, publishing a package, or registering a client or resource server in a deployed environment. Everything on a developer's machine is safe to do.
Where things are
| Thing | Where |
|---|---|
| Product ids, scopes, the client schema | @buun-group/core on GitHub Packages, buun-group/buungroup-app packages/core |
| The design system | @buun-group/ui, the same repository, packages/ui |
| The issuer and the portal | buun-group/buungroup-app, apps/identity and apps/account |
| The gateway | buun-group/buungroup-gateway |
| The staff console | buun-group/buungroup-staff |
| These pages, as Markdown | buun-group/buungroup-app, apps/developers/content, and on this site at /<page>.md |