feat: add OpenAPI, error spec, vector index, and a one-command runner#15
Closed
trqlmao wants to merge 1 commit into
Closed
feat: add OpenAPI, error spec, vector index, and a one-command runner#15trqlmao wants to merge 1 commit into
trqlmao wants to merge 1 commit into
Conversation
Close the gap between the turnkey crypto path and the wire/transport
layer, where most "get it right first try" friction lives for both
humans and LLMs implementing AVP.
- openapi.yaml: OpenAPI 3.1 description of the HTTP/JSON profile — every
path, method, status code, and error response — referencing the JSON
Schema shapes so the route surface is machine-readable and
stub-generatable. The gRPC profile had proto/avp.proto; HTTP had only a
prose route table.
- schema + SPEC §6: define the error body { error, code?, detail? } and a
status→code table, and state that every non-2xx is terminal while a
stale-version push is a 200 with conflict:true. The five reference
servers already emit { error, detail? }; `code` is additive, so they
stay conformant.
- SPEC §11: reword conformance to map each requirement to the vector that
actually exists (Ed25519 anchors the challenge signature; the
payload-AEAD epoch-tamper case anchors rotation correctness) instead of
implying standalone challenge/token and rotation vector files that do
not exist. Dedicated vectors for those paths are noted as welcome
additions.
- vectors/index.json: machine-readable index of the vectors (file, kind,
spec section, RFC anchors) so a harness can enumerate them without
hardcoding filenames.
- Taskfile.yml: `task test` runs the conformance suite and every
language's example tests in one command, mirroring the CI jobs.
Cross-linked from README, IMPLEMENTING.md, llms.txt, examples/README.md,
and vectors/README.md; recorded under CHANGELOG [Unreleased].
Owner
Author
|
Superseded by #16, which was stacked on this branch and merged to main with all four commits (the doc/wire-surface commit from this PR plus the conformance suite, the house-style em-dash fix, and the CLAUDE.md update). Nothing here is unmerged. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft for review. Closes the gap between AVP's turnkey crypto path and its wire/transport layer — the layer where most "implement it right first try" friction lives for humans and LLMs.
What's in it
openapi.yamlproto/avp.proto; HTTP had only a prose route table. Now every path/method/status/error is machine-readable + stub-generatable.$refs the JSON Schema (no shape duplication).schema/avp.schema.json($defs/Error),SPEC.md§6,IMPLEMENTING.md{ error, code?, detail? }+ a status→code table; states every non-2xx is terminal while a stale-versionpushis a200withconflict:true. All five reference servers already emit{ error, detail? }, socodeis additive and they stay conformant.SPEC.md§11vectors/index.json,vectors/README.mdTaskfile.yml,examples/README.mdtask testruns conformance + all five example suites, mirroring CI.Cross-linked from README / IMPLEMENTING / llms.txt; recorded in CHANGELOG
[Unreleased].Verified
$refs resolve to schema$defs;Errordef present.schema/avp.schema.json,vectors/index.jsonparse as JSON;openapi.yaml,Taskfile.ymlparse as YAML.{ error, detail? }bodies remain conformant to the newErrordef.Deliberately out of scope (follow-ups)
auth-challenge.json+rotation.jsonvectors (would need real generated values, wired into the 5 example suites).proto/avp.protohas no running code today).examples/*.jsonare illustrative fakes).SPEC.md§7 is still(reserved).Notes
openapi.yamluses external relative$refintoschema/avp.schema.json— valid OpenAPI 3.1 (2020-12 JSON Schema); some tooling may want a bundle step.Taskfile.ymlis go-task; each target needs only its own toolchain.