Skip to content

README.md

Latest commit

 

History

History
106 lines (82 loc) · 4.13 KB

README.md

File metadata and controls

106 lines (82 loc) · 4.13 KB
Raw

prism_lib_rs

中文

Rust SDK for integrating Prism OAuth 2.0 / OpenID Connect into Rust services. Port of @siiway/prism.

Features

  • OAuth 2.0 Authorization Code + PKCE flow
  • Token management: exchange, refresh, introspect, revoke
  • OpenID Connect discovery + userinfo
  • Local ML-DSA-65 JWT verification via fips204 — no client secret needed
  • Resource APIs: profile, apps, teams, domains, webhooks, social/GPG, admin, site, 2FA, app scope permissions, team-scoped tokens
  • App-to-app event channels: SSE stream + WebSocket URL builder
  • Async/await over reqwest, serde-typed responses, thiserror-derived PrismError

Install

[dependencies]
prism_lib_rs = { git = "https://github.com/siiway/prism_lib_rs" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Quick start

use prism_lib_rs::{PrismClient, PrismClientOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let prism = PrismClient::new(
        PrismClientOptions::new(
            "https://prism.siiway.org",
            "your-client-id",
            "http://localhost:3000/callback",
        )
        .with_scopes(vec!["openid".into(), "profile".into(), "email".into()]),
    );

    // 1. Redirect user to Prism for login.
    let auth = prism.create_authorization_url(None)?;
    // store auth.pkce.code_verifier, then send the user to auth.url

    // 2. Exchange the code coming back from the callback.
    let tokens = prism
        .exchange_code("code-from-callback", Some(&auth.pkce.code_verifier), None)
        .await?;

    // 3. Look up the authenticated user.
    let user = prism.get_user_info(&tokens.access_token).await?;
    println!("{}", user.sub);

    // 4. Refresh (requires the `offline_access` scope).
    if let Some(rt) = tokens.refresh_token {
        let _ = prism.refresh_token(&rt).await?;
    }
    Ok(())
}

API overview

Namespace What it covers
prism.profile() /oauth/me/profile read/update
prism.apps() Personal + team-owned OAuth apps
prism.teams() / prism.team_scope() Team CRUD, invites, domains, apps; team-scoped tokens
prism.domains() User domain DNS TXT verification
prism.webhooks() User-scoped webhooks
prism.social() Linked social accounts + GPG keys
prism.app_notifications() App webhooks + SSE / WS event stream
prism.app_scope_permissions() Custom scope definitions + access rules
prism.site() / prism.admin() Site-read + full admin surface
prism.two_factor() Step-up 2FA challenge / verify / parse-callback

Top-level helpers on PrismClient: create_authorization_url, build_authorization_url, exchange_code, refresh_token, introspect_token, revoke_token, get_user_info, get_public_profile, get_public_team_profile, get_public_gpg_keys, list_consents, revoke_consent, revoke_consent_token, get_site_info, health, discover, jwks.

Standalone: verify_token for local ML-DSA-65 token verification.

Documentation

The full guide lives under docs/ and is a VitePress site (run with bun):

cd docs
bun install
bun run dev

It covers OAuth flow, token verification, resource APIs, streaming events, and error handling — in both English and 中文.

License

GNU General Public License v3.0. See LICENSE for the full text.