Petstore

petstore is an example app that extends the Swagger Petstore API definition (openapi.yaml) with a server, petstore-server, that serves every operation from memory. Optionally, the server is an AAuth resource: each operation asks an AI agent for exactly the trust it needs.

Run the Server

go run ./cmd/petstore-server --listen 127.0.0.1:8080
curl 'http://127.0.0.1:8080/v2/pet/findByStatus?status=available'

The store starts with six pets and keeps everything in memory. The spec is served at /openapi.yaml and /openapi.json, with servers pointing at the server, so tools that load an OpenAPI document find it there.

Run It as an AAuth Resource

With --auth aauth, each operation requires what its x-aauth annotation in openapi.yaml says:

Operations	Requires	What the agent does
findPetsByStatus, findPetsByTags, getPetById, getInventory, loginUser, logoutUser	the agent's identity	signs the request with its agent token
getOrderById, user operations	the person	presents a person token from its person server
placeOrder, deleteOrder	an auth token for write:orders	asks the person to approve, then presents the auth token
addPet, updatePet, updatePetWithForm, deletePet, uploadFile	an auth token for write:pets	the same, for write:pets

Orders belong to the person who placed them: another person's order is not found.

The quickest way to try it is behind the aauth-go sandbox, which runs an agent provider and a person server and serves the Petstore as https://petstore.aauth.test:

aauth-sandbox init
petstore-server --listen 127.0.0.1:8080 --auth aauth \
  --url https://petstore.aauth.test \
  --trust https://ps.aauth.test \
  --ca-file ~/.aauth-sandbox/ca.pem
aauth-sandbox serve --upstream petstore=http://127.0.0.1:8080

Flag	Meaning
--auth	none (default) or aauth
--url	the resource's public URL and AAuth identifier
--trust	a person server whose tokens to accept (repeatable)
--ca-file	an extra root CA for fetching issuers' keys, such as the sandbox CA
--listen	the address to listen on, plain HTTP (default :8080)

The resource metadata is at /.well-known/aauth-resource.json, with the scope descriptions a person server shows on its consent page.

To test agents and AAuth implementations against the Petstore, see the interop guide.

Container

docker build -t petstore-server .
docker run --rm -p 127.0.0.1:8080:8080 petstore-server

References

1. OpenAPI Initiative
2. OpenAPI Tools
3. Sagger.io API Reference