89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# st-peter-client
|
|
|
|
Official client libraries for [st-peter](https://git.awesomike.com/dev/st-peter-lib)
|
|
(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
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```toml
|
|
st-peter-client = { git = "https://git.awesomike.com/pub/st-peter-client.git", tag = "v0.2.0" }
|
|
```
|
|
|
|
Go:
|
|
|
|
```bash
|
|
go get git.awesomike.com/pub/st-peter-client/go@v0.2.0
|
|
```
|
|
|
|
TypeScript (`package.json`):
|
|
|
|
```json
|
|
"@st-peter/client": "git+https://git.awesomike.com/pub/st-peter-client.git#v0.2.0"
|
|
```
|