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 ke ekosistem Rust, bagian dari keluarga crate RustBasic (lihat 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

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

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)

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)

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

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)

[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).

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):

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)

[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.

// 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):

.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

# 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.
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