joshquinlan/burhlib
Watch
1
0
Fork
You've already forked burhlib
 0
Code Issues Pull requests Wiki Activity
No description
6 commits 1 branch 4 tags 178 KiB
  • Go 95.6%
  • Makefile 4.4%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Josh Quinlan bb8f471e93
 feat(openapi): describe invitations and the recovery address 
An invitation creates the account pending and sends an enrolment
link: the account cannot sign in until somebody accepts and sets
credentials, so an invitation that is never taken up leaves nothing
usable behind. Cancelling removes the pending account; resending
issues a fresh link and kills the earlier ones; an accepted
invitation cannot be cancelled, because the account is live and is
managed as a user.

The recovery address joins the user shapes: it also receives reset
links, so losing the primary inbox does not mean losing the account,
and it is never a sign-in identifier.
2026-08-28 18:24:00 +01:00
api feat(openapi): describe invitations and the recovery address 2026-08-28 18:24:00 +01:00
id feat(id): key every entity with a prefixed ULID 2026-08-27 23:31:23 +01:00
openapi feat(openapi): describe invitations and the recovery address 2026-08-28 18:24:00 +01:00
problem feat(openapi): describe the directory, tokens, audit and settings 2026-08-28 00:11:03 +01:00
.gitignore build(api): generate the client and server contract from the spec 2026-08-28 00:13:18 +01:00
.golangci.yml feat(openapi): describe the API contract and embed it 2026-08-27 23:09:32 +01:00
go.mod build(api): generate the client and server contract from the spec 2026-08-28 00:13:18 +01:00
go.sum build(api): generate the client and server contract from the spec 2026-08-28 00:13:18 +01:00
LICENSE feat(openapi): describe the API contract and embed it 2026-08-27 23:09:32 +01:00
Makefile build(api): generate the client and server contract from the spec 2026-08-28 00:13:18 +01:00
README.md feat(openapi): describe the API contract and embed it 2026-08-27 23:09:32 +01:00

README.md

burhlib

The contract between a burh identity provider and everything that talks to it.

openapi/burh.v1.yaml is the source of truth for the administration and self-service API. The server's handlers and the Go client in this repository are both generated from it, so the description cannot drift away from the implementation. Anyone writing their own administration interface, in any language, should start here.

Status

Early development. The document currently fixes the conventions every endpoint obeys; resources are being added as the server implements them.

What is here

Path Contents
openapi/burh.v1.yaml The API description, OpenAPI 3.1
openapi The description, embedded for serving at runtime

Conventions the description fixes

  • Authentication is a bearer token: either an administrator's session token or an issued API token, whose scopes decide what it may do.
  • Errors are application/problem+json as defined by RFC 9457, with stable urn:burh:error:* types and a request_id that appears in the server's logs, traces and audit trail.
  • Collections page by opaque cursor, returning next_cursor until they are exhausted.
  • Mutable resources carry an ETag, and updates require If-Match, so two administrators cannot silently overwrite one another.
  • Rate limits are reported with the IETF RateLimit header fields.

Using it

go get forge.quinlan.cloud/joshquinlan/burhlib

import "forge.quinlan.cloud/joshquinlan/burhlib/openapi"

// openapi.Spec holds the description, ready to serve.

Building

Go 1.26 or newer, and golangci-lint on PATH.

make check      # lint, and validate the description

The test suite parses the description and fails if it is not valid OpenAPI 3.1, so a broken edit cannot be committed quietly.

Contributing

Changes to the description are changes to a published contract: they arrive with a reason, and breaking ones with a version. Otherwise the usual conventions apply, including Conventional Commits messages.

Licence

Apache-2.0. See LICENSE.