# 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"
```