3.3 KiB

Raw Blame History

st-peter-client

Official client libraries for st-peter (deployed as aura-users) — the central authentication service — over gRPC.

Three clients, one wire contract, versioned in lockstep with the st-peter server:

Language	Path	Package
Rust	`rust/`	`st-peter-client` (crate)
Go	`go/`	`git.awesomike.com/pub/st-peter-client/go` (module)
TypeScript	`ts/`	`@st-peter/client` (npm)

The .proto file in proto/ is a vendored copy; the st-peter server repo is the source of truth. scripts/sync-protos.sh refreshes it and keeps VERSION aligned with the server. Only the auth surface is vendored — services authenticate users; they do not administer st-peter.

Versioning

Every release is tagged at the same version as the st-peter server it targets (see VERSION). A client tagged v0.2.0 speaks the wire contract of st-peter v0.2.0. The gRPC wire format is backward-compatible across patch releases (field numbers and enum integer values are stable), so a client one patch behind a server generally interoperates — but match versions for new surface.

Design: authentication central, authorization local

st-peter answers who is this token? — every client returns the verified identity plus the user's platform roles, with a ~60s token-verify cache. What that identity may do inside a consuming service (media roles, CMS roles, …) is that service's own concern: keep a local roles table keyed by the st-peter user_id by value (no cross-DB FK) and map permissions there. These clients deliberately ship no session/permission types.

The wrapper surface is the same in all three languages:

connect(target) — lazy dial; failures surface on the first call
verify_token(token) — verified user + platform roles, cached ~60s
login(identifier, password) → Authenticated | TwoFactor | Failed
verify_two_factor(two_factor_id, code) — complete an OTP challenge
lookup_user(actor_id, actor_token, identifier) — resolve a user by email/phone/handle (for local role-grant flows)
bearer(...) helper + the shared aura_session cookie name

Layout

proto/      vendored st-peter-auth.proto (source of truth: st-peter repo)
rust/       cargo package; stubs compiled at build time from ../proto
go/         go module; committed stubs in genpb/ (scripts/gen-go.sh)
ts/         npm package; committed stubs in src/genpb (scripts/gen-ts.sh)
scripts/    sync-protos.sh, gen-go.sh, gen-ts.sh
VERSION     the st-peter server version this client targets

Regenerating after a proto change

ST_PETER_REPO=/path/to/st-peter-lib ./scripts/sync-protos.sh
./scripts/gen-go.sh                       # needs protoc-gen-go{,-grpc}
(cd ts && npm install) && ./scripts/gen-ts.sh
cargo check                               # rust stubs regenerate via build.rs

Then tag at v$(cat VERSION).

Consuming

Rust (Cargo.toml):

st-peter-client = { git = "https://git.awesomike.com/pub/st-peter-client.git", tag = "v0.2.0" }

Go:

go get git.awesomike.com/pub/st-peter-client/go@v0.2.0

TypeScript (package.json):

"@st-peter/client": "git+https://git.awesomike.com/pub/st-peter-client.git#v0.2.0"

3.3 KiB Raw Blame History