# rustbasic-passport
OAuth2 server dan Personal Access Token untuk aplikasi Rust — port dari
[`laravel/passport`](https://github.com/laravel/passport) ke ekosistem Rust,
bagian dari keluarga crate **RustBasic** (lihat [`rustbasic-permission`](https://crates.io/crates/rustbasic-permission)).
## Fitur
| Authorization Code Grant (+ PKCE) | `authorization_code` grant, PKCE S256 & plain (RFC 7636) |
| Password Grant | `password` grant dengan `UserProvider` |
| Client Credentials Grant | `client_credentials` grant |
| Refresh Token dengan rotasi | `refresh_token` grant sekali pakai (rotate) |
| Device Authorization Grant (RFC 8628) | `issue_device_code` + `approve_device_code` + `urn:ietf:params:oauth:grant-type:device_code` |
| Personal Access Token | `create_personal_access_token()` + `personal_access` grant |
| Grant Types per client (Passport 13.x) | kolom `grant_types` (`has_grant_type`) menggantikan `personal_access_client`/`password_client` |
| Token JWT ditandatangani RSA (RS256) | crate `jsonwebtoken` + `rsa`, dukungan `kid` untuk key rotation |
| Guard `auth:api` (TokenGuard) | middleware `require_auth` (axum) |
| Middleware `scope:...` | middleware `check_scopes` (`ScopePolicy::any` / `all`) |
| `Passport::routes()` | `axum::router::<S>()` → `/oauth/token`, `/oauth/authorize`, `/oauth/revoke`, `/oauth/device`, `/oauth/device/verify` |
| Integrasi loco.rs | feature `loco`: `loco::routes()` + `Initializer` (Extension) |
| Perintah Artisan `passport:keys` | binary CLI `generate-keys` |
| Migrations `oauth_*` | perintah CLI `install` (SQL: sqlite / postgres / mysql) |
| `Passport::tokensExpireIn()` dll. | `Config` (TTL access / refresh / auth code / PAT) |
## Cara Kerja
1. **Anda** mengimplementasi 6 trait penyimpanan (`ClientStore`,
`AccessTokenStore`, `AuthCodeStore`, `RefreshTokenStore`, `DeviceCodeStore`,
`UserProvider`) di atas database/backend Anda (SQLx, Diesel, in-memory, dll).
2. Susun dengan `StoreBundle`, buat `PassportServer` dengan `SigningKey`
RSA dan `Config`.
3. Panggil `server.issue_token(&TokenRequest)` (grants) atau gunakan
middleware axum untuk melindungi route.
## Penggunaan
### 1. Implementasi store
```rust
use rustbasic_passport::entity::Client;
use rustbasic_passport::error::Error;
use rustbasic_passport::store::ClientStore;
#[async_trait::async_trait]
impl ClientStore for MyDbClientStore {
async fn find_by_id(&self, id: &str) -> Result<Option<Client>, Error> {
// SELECT * FROM oauth_clients WHERE id = ?
}
async fn find_personal_access_client(&self) -> Result<Option<Client>, Error> {
// SELECT * FROM oauth_clients WHERE grant_types LIKE '%personal_access%' AND revoked = 0 LIMIT 1
}
async fn save(&self, client: &Client) -> Result<(), Error> {
// INSERT ... ON CONFLICT (id) DO UPDATE
}
}
// + AccessTokenStore, AuthCodeStore, RefreshTokenStore, DeviceCodeStore, UserProvider
```
### 2. Bangun server
```rust
use rustbasic_passport::jwt::SigningKey;
use rustbasic_passport::server::{Config, PassportServer};
use rustbasic_passport::store::StoreBundle;
let stores = StoreBundle::new(
clients, tokens, auth_codes, refresh_tokens, device_codes, users,
);
let server = PassportServer::new(
stores,
SigningKey::generate("default")?, // atau SigningKey::from_pem(..) dari file oauth-private.key
Config::default(), // atur issuer, TTL, dll di sini
);
```
### 3. Terbitkan token (password grant)
```rust
let resp = server.issue_token(&TokenRequest {
grant_type: Some("password".into()),
client_id: Some("web".into()),
client_secret: Some("secret".into()),
username: Some("user@example.com".into()),
password: Some("password".into()),
scope: Some("read write".into()),
..Default::default()
}).await?;
println!("{}", resp.access_token); // JWT RS256
```
Grant lain cukup ganti `grant_type`:
`authorization_code` (+ `code`, `redirect_uri`, `code_verifier`),
`client_credentials`, `refresh_token`, `personal_access`,
atau `urn:ietf:params:oauth:grant-type:device_code` (+ `device_code`).
### 4. Device Authorization Grant (RFC 8628)
```rust
use rustbasic_passport::server::DeviceAuthorizationRequest;
// Client TV meminta device code (body: client_id, client_secret, scope)
let device = server.issue_device_code(&DeviceAuthorizationRequest {
client_id: Some("tv".into()),
client_secret: Some("secret-tv".into()),
scope: Some("read".into()),
}).await?;
// device.user_code -> tampilkan di layar TV, mis. "BCDF-GHKJ"
// User membuka halaman verifikasi dan memasukkan user_code:
server.approve_device_code("user-1", "bcd fghkj").await?;
// (user_code dinormalisasi otomatis: uppercase, spasi/tanda pisah dibuang)
// TV polling /oauth/token dengan grant_type device_code:
// - belum disetujui -> authorization_pending (polling ulang setelah `interval` detik)
// - polling terlalu cepat -> slow_down
// - disetujui -> access + refresh token
```
### 5. Personal Access Token
```rust
let pat = server
.create_personal_access_token("user-1", "API Token", vec!["read".into()])
.await?;
// pat.access_token -> JWT, pat.token -> AccessToken tersimpan
```
### 6. Integrasi axum (feature `axum`)
```toml
[dependencies]
rustbasic-passport = { version = "0.0", features = ["axum"] }
```
Handler mengambil `PassportServer` lewat **request extension**, bukan router
state — sehingga router `/oauth/*` bisa di-merge bebas, termasuk ke framework
di atas axum yang mengunci tipe state (seperti loco.rs).
```rust
use axum::extract::Extension;
use axum::middleware;
use rustbasic_passport::axum as passport_axum;
use rustbasic_passport::axum::{AuthContext, ScopePolicy};
type MyStores = /* StoreBundle<...> */;
// 1. Rute OAuth (mirip Passport::routes()) — server disuplai satu kali
let server = /* PassportServer::new(...) */;
let app = Router::new()
.merge(passport_axum::router::<MyStores>()) // /oauth/* tanpa state
.layer(Extension(server.clone())); // tersedia di semua route
// 2. API terproteksi
let api = Router::new()
.route("/api/user", get(user_info))
.route_layer(middleware::from_fn_with_state(
ScopePolicy::any(["read"]), // scope: read ATAU ...
passport_axum::check_scopes,
))
.route_layer(middleware::from_fn_with_state(
server.clone(),
passport_axum::require_auth,
));
let app = app.merge(api);
```
Handler mengambil user via `Extension<AuthContext>` (diisi `require_auth`):
```rust
use axum::extract::Extension;
async fn user_info(Extension(ctx): Extension<AuthContext>) -> Json<serde_json::Value> {
Json(serde_json::json!({
"user_id": ctx.user_id,
"client_id": ctx.client_id,
"scopes": ctx.scopes,
}))
}
```
> Catatan: dalam axum, `.route_layer()` terakhir = layer terluar, jadi
> `require_auth` harus didaftarkan **setelah** `check_scopes`.
Respons error mengikuti RFC 6749/6750: `invalid_client`, `invalid_grant`,
`invalid_token`, `insufficient_scope`, dll.
### 7. Integrasi loco.rs (feature `loco`)
```toml
[dependencies]
rustbasic-passport = { version = "0.0", features = ["loco"] }
```
loco.rs membangun semua rute di atas `axum::Router` ber-state `AppContext`;
passport kompatibel karena handler-nya mengambil server via `Extension`.
```rust
// src/app.rs
use loco_rs::prelude::*;
use rustbasic_passport::server::PassportServer;
type MyStores = /* StoreBundle<...> yang diimplementasikan di atas model sea-orm */;
pub struct App;
#[async_trait]
impl Hooks for App {
// ...boot, connect_workers, dst...
// 1. Daftarkan server sebagai Initializer → otomatis terpasang sebagai
// `Extension` di seluruh route (rustbasic_passport::loco impl
// `loco_rs::app::Initializer` untuk `PassportServer`).
async fn initializers(ctx: &AppContext) -> Result<Vec<Box<dyn Initializer>>> {
Ok(vec![Box::new(server)]) // server: PassportServer<MyStores>
}
// 2. Route OAuth /oauth/*
fn routes(ctx: &AppContext) -> AppRoutes {
AppRoutes::with_default_routes()
.add_route(rustbasic_passport::loco::routes::<MyStores>())
}
}
```
Route API terproteksi cukup pakai `require_auth` / `check_scopes` seperti
axum biasa (works di loco karena bersifat self-contained):
```rust
.route_layer(middleware::from_fn_with_state(server.clone(), rustbasic_passport::axum::require_auth))
```
Alternatif bentuk `axum::Router<AppContext>`: `rustbasic_passport::loco::router::<MyStores>()`
(bisa di-merge di `Hooks::before_routes`). Test integrasi nyata dalam router
loco ada di `tests/loco_integration.rs` (`cargo test --features loco-testing`).
## CLI
```bash
# Generate RSA key pair (oauth-private.key / oauth-public.key)
cargo run --bin rustbasic-passport -- generate-keys --output-dir storage/keys
# Cetak skema SQL tabel oauth_* (sqlite | postgres | mysql)
cargo run --bin rustbasic-passport -- install --database postgres
```
## Contoh Lengkap
- `examples/in_memory.rs` — seluruh alur (password, refresh, auth code +
PKCE, device grant, PAT) dengan store in-memory, tanpa framework.
- `examples/axum_server.rs` — server axum lengkap dengan middleware.
```bash
cargo run --example in_memory
cargo run --features axum --example axum_server
cargo test --features loco-testing # test integrasi router loco.rs
```
## Struktur Proyek
```
src/
├── entity.rs # Client (grant_types), AccessToken, AuthCode, RefreshToken, DeviceCode, PAT result
├── store.rs # trait penyimpanan + StoreBundle
├── jwt.rs # SigningKey (RSA RS256), claims, sign/verify
├── server.rs # PassportServer: grants, authorize, validate, revoke
├── axum.rs # (feature) routes, require_auth, check_scopes — berbasis Extension
├── loco.rs # (feature) Routes / Initializer untuk loco.rs
├── error.rs # Error + mapping ke OAuth error response
└── bin/ # CLI: generate-keys, install
```
## Change Log
### v0.0.1 — 2026-08-10 · Audit keamanan & perbaikan
Perbaikan keamanan dari hasil audit:
- **Breking change**: trait `AuthCodeStore` dan `RefreshTokenStore` kini
mewajibkan method `revoke_if_unrevoked(&self, id) -> Result<bool, Error>`
(revoke atomik). Grant `authorization_code` dan `refresh_token` memakai
method ini untuk menegakkan single-use terhadap race condition (TOCTOU):
dua permintaan tukar yang datang bersamaan tidak bisa lagi sama-sama
menghasilkan token. Implementasi wajib atomik, misal:
`UPDATE oauth_auth_codes SET revoked = 1 WHERE id = ? AND revoked = 0`.
- **Breking change**: `RefreshToken` kini membawa `client_id`, dan grant
`refresh_token` memverifikasi bahwa token dipakai oleh client penerbitnya.
Refresh token curian tidak lagi bisa ditebus oleh client lain. Skema SQL
`oauth_refresh_tokens` bertambah kolom `client_id VARCHAR(64) NOT NULL`
(+ index) di semua dialect (sqlite / postgres / mysql).
- **Security fix**: perbandingan client secret dan PKCE `plain` kini
constant-time (`subtle` + SHA-256), tidak lagi rentan timing attack
(`server.rs::constant_time_eq`). Dependency baru: `subtle = "2"`.
Test baru: single-use auth code di bawah konkurensi (8 request simultan,
hanya 1 berhasil) dan penolakan refresh token lintas client.
## Lisensi
MIT