# 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.1` speaks the wire contract of
st-peter `v0.2.1`. 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
- `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.1" }
```

Go:

```bash
go get git.awesomike.com/pub/st-peter-client/go@v0.2.1
```

TypeScript (`package.json`):

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