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 files in proto/ are vendored copies; the st-peter server repo is the source of truth. scripts/sync-protos.sh refreshes them and keeps VERSION aligned with the server. Two surfaces are vendored: auth (authentication + roles-with-verification) and admin (AuthAdminService — user administration and targeted-role management, actor-credentialed: aura-users authorizes the acting admin by its own assignability rules).

Versioning

Every release is tagged at the same version as the st-peter server it targets (see VERSION). A client tagged v0.2.x speaks the wire contract of st-peter v0.2.1+ (client patch releases may lead the server within a minor line when they only expose existing server surface — v0.2.2 adds API-key wrappers). 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; roles shared-vs-local

st-peter answers who is this token? — every client returns the verified identity plus the user's roles, with a ~60s token-verify cache. The role rule: roles shared among microservices live in st-peter as targeted roles (role + scope + opaque target_id + optional expiry — e.g. cms-admin targeted at an organization), granted/revoked through the admin surface; truly service-local roles stay inside that service (a local table keyed by the st-peter user_id by value, no cross-DB FK). Either way, the authorization semantics — what a role means, permission mapping — are the consuming service's own concern: 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 + all roles, cached ~60s
• verify_token_scoped(token, scopes) — roles filtered to the caller's scope(s) (e.g. ["cms"]); cached per (token, scopes)
• 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
• verify_api_key(key) — service-credential path: the key's owning service user + roles (cached); Rust adds create_api_key / list_api_keys / revoke_api_key management wrappers
• bearer(...) helper + the shared aura_session cookie name

The admin surface (AdminClient — Rust first; Go/TS expose the generated stubs): assign_role / unassign_role (targeted + time-bound grants), get_assignable_roles / get_assignable_targets, get_user_with_roles, search_users, get_users_by_role, create_user / delete_user / restore_user, get_user_sessions / clear_user_sessions — every call carries an Actor { user_id, token }.

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.2" }

Go:

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

TypeScript (package.json):

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