107 lines
4.5 KiB
Markdown
107 lines
4.5 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` 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
|
|
|
|
```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.2" }
|
|
```
|
|
|
|
Go:
|
|
|
|
```bash
|
|
go get git.awesomike.com/pub/st-peter-client/go@v0.2.2
|
|
```
|
|
|
|
TypeScript (`package.json`):
|
|
|
|
```json
|
|
"@st-peter/client": "git+https://git.awesomike.com/pub/st-peter-client.git#v0.2.2"
|
|
```
|