Buun Group Developers
Pages

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.

Markdown

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 to PRODUCTS in @buun-group/core by a change to buun-group/buungroup-app, and the package published, before anything else names it.

The rules that are easy to get wrong

RuleCheck
Accept a token only when aud is exactly your own addressA token for the gateway or another product is refused, with a test
Insist on typ: at+jwt and alg: ES256An ID token sent as an access token is refused, with a test
Take the issuer and your own address from wrangler.jsonc vars, per environmentNo address is read from a token or a request
Link an existing user by address only when it is verified on both sidesAn unverified address makes a new user, with a test
Answer 401 with WWW-Authenticate: Bearer error="invalid_token" for any token that failsThe gateway trades again on a 401 and on nothing else
Never log a token, and never forward oneSearch the code for the header name before shipping
Never keep a plan in a token or a long cacheAsk /oauth/plans each time it matters
Keep your own sign-in working beside Buun Identity'sPick the check by the token's iss, then verify everything

The steps

  1. 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, iss checked on return, tokens checked as on Tokens and keys. Test: a wrong state is refused; a wrong iss is refused.
  2. Plans. Read /oauth/plans where the product decides what a person may do. Test: a cancelled plan stops access at the next request.
  3. The MCP server. Make it accept Buun Identity tokens as on Accepting Buun Identity tokens. Test every refusal in the table there.
  4. Tools. Give each tool a stable name, an honest description, readOnlyHint or destructiveHint, and an input schema under 32 KB. Staff approve each version before an agent sees it: Tool review.
  5. The gateway. Ask for, or make as a reviewed change to buun-group/buungroup-gateway, a catalogue entry for each environment with acceptsIdentityTokens: true, and a resource server in the staff console for each MCP address: How the gateway works.
  6. 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

ThingWhere
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 portalbuun-group/buungroup-app, apps/identity and apps/account
The gatewaybuun-group/buungroup-gateway
The staff consolebuun-group/buungroup-staff
These pages, as Markdownbuun-group/buungroup-app, apps/developers/content, and on this site at /<page>.md