rustbasic-passport 0.1.1

OAuth2 server and personal access tokens for Rust applications, a port of laravel/passport for the RustBasic ecosystem.
Documentation
# 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

| Fitur Passport (Laravel)                      | Implementasi di rustbasic-passport                                |
| --------------------------------------------- | ----------------------------------------------------------------- |
| 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