Guides

cargo run --features clap,hickory-dns \
  --bin atpdid -- resolve alice.bsky.social

use std::sync::Arc;
use std::time::Duration;

use atproto_identity::config::DEFAULT_PLC_HOSTNAME;
use atproto_identity::redirect::validated_policy;
use atproto_identity::resolve::{HickoryDnsResolver, InnerIdentityResolver};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Whoever supplied the handle names the hosts this client reaches:
    // check every redirect hop, and bound every request.
    let http_client = reqwest::Client::builder()
        .redirect(validated_policy())
        .timeout(Duration::from_secs(10))
        .build()?;

    let resolver = InnerIdentityResolver {
        // Pass nameservers explicitly, or an empty slice for the system set.
        dns_resolver: Arc::new(HickoryDnsResolver::create_resolver(&[])),
        http_client,
        plc_hostname: DEFAULT_PLC_HOSTNAME.to_string(),
    };

    // Handle to DID to document, and the document must name the handle back.
    let document = resolver.resolve_verified("alice.bsky.social").await?;
    println!("{} — PDS {:?}", document.id, document.pds_endpoints_validated());

    Ok(())
}

cargo run --package atproto-repo --features clap \
  --bin atproto-repo-car -- ls repo.car
cargo run --package atproto-repo --features clap \
  --bin atproto-repo-mst -- ls repo.car

use atproto_repo::CarReader;
use tokio::fs::File;

async fn read_car() -> anyhow::Result<()> {
    let file = File::open("repository.car").await?;
    let mut reader = CarReader::new(file).await?;

    // The roots are the commit CIDs this archive claims to carry.
    println!("roots: {:?}", reader.roots());

    while let Some(block) = reader.next_block().await? {
        println!("{} — {} bytes", block.cid, block.data.len());
    }

    Ok(())
}

use atproto_attestation::{create_inline_attestation, AnyInput};
use atproto_identity::key::{generate_key, KeyType};
use serde_json::json;

fn main() -> anyhow::Result<()> {
    let key = generate_key(KeyType::P256Private)?;

    let record = json!({
        "$type": "app.bsky.feed.post",
        "text": "Hello AT Protocol!",
        "createdAt": "2024-01-01T00:00:00.000Z"
    });

    let metadata = json!({
        "$type": "com.example.inlineSignature",
        "key": "did:key:...",
        "issuer": "did:plc:issuer123",
        "issuedAt": "2024-01-01T00:00:00.000Z"
    });

    // The repository DID is bound into $sig. This is the replay defence.
    let signed = create_inline_attestation(
        AnyInput::Serialize(record),
        AnyInput::Serialize(metadata),
        "did:plc:repo123",
        &key,
    )?;

    println!("{}", serde_json::to_string_pretty(&signed)?);
    Ok(())
}

cargo run --package atproto-attestation --features clap,tokio \
  --bin atproto-attestation-sign -- \
  inline record.json did:plc:repo123 signing.key metadata.json \
  > signed_record.json

cargo run --package atproto-attestation --features clap,tokio \
  --bin atproto-attestation-verify -- signed_record.json did:plc:repo123

use atproto_identity::key::{identify_key, KeyData};
use atproto_oauth::pkce;
use atproto_oauth::resources::{oauth_authorization_server, pds_resources};
use atproto_oauth::workflow::{
    generate_state, oauth_complete, oauth_init, OAuthClient, OAuthRequest,
    OAuthRequestState,
};

// Two distinct keys: this one signs client assertions; the DPoP key,
// passed separately, binds the tokens.
fn client() -> anyhow::Result<OAuthClient> {
    Ok(OAuthClient {
        redirect_uri: "https://your-app.com/callback".to_string(),
        client_id:    "https://your-app.com/client-metadata.json"
            .to_string(),
        private_signing_key_data: identify_key("did:key:zQ3sh...")?,
    })
}

// 1 — Discovery, then the Pushed Authorization Request. Returns where to
//     send the browser, and the PKCE verifier to store with the state.
async fn begin(
    http_client: &reqwest::Client,
    dpop_key: &KeyData,
) -> anyhow::Result<(String, String)> {
    // The PDS named in alice's DID document says which server speaks for it.
    let (_resource, auth_server) =
        pds_resources(http_client, "https://pds.example.com").await?;

    let (pkce_verifier, code_challenge) = pkce::generate();
    let request_state = OAuthRequestState {
        state: generate_state(),
        code_challenge,
        scope: "atproto transition:generic".to_string(),
    };

    let par = oauth_init(
        http_client,
        &client()?,
        dpop_key,
        Some("alice.bsky.social"),
        &auth_server,
        &request_state,
    ).await?;

    // Store an OAuthRequest under request_state.state: the DID, the
    // verifier, and auth_server.issuer. Step 2 cannot run without it.
    Ok((par.request_uri, pkce_verifier))
}

// 2 — The callback: ?code=…&state=…&iss=…
async fn finish(
    http_client: &reqwest::Client,
    dpop_key: &KeyData,
    stored: &OAuthRequest, // found by state, then deleted
    code: &str,
    iss: Option<&str>,
) -> anyhow::Result<()> {
    // The server the flow began with, not one rediscovered now.
    let auth_server =
        oauth_authorization_server(http_client, &stored.issuer).await?;

    let tokens = oauth_complete(
        http_client,
        &client()?,
        dpop_key,
        code,
        &stored.subject, // expected_subject: a DID, never a handle
        iss,             // must equal stored.issuer (RFC 9207)
        stored,
        &auth_server,
    ).await?;

    println!("{}", tokens.access_token);
    Ok(())
}

use atproto_identity::key::KeyData;
use atproto_identity::model::Document;
use atproto_oauth::workflow::{oauth_refresh, OAuthClient, TokenResponse};

async fn rotate(
    http_client: &reqwest::Client,
    oauth_client: &OAuthClient,
    dpop_key: &KeyData,
    stored_refresh_token: &str,
    did_document: &Document,
) -> anyhow::Result<TokenResponse> {
    let tokens = oauth_refresh(
        http_client,
        oauth_client,
        dpop_key,
        stored_refresh_token,
        did_document,
    ).await?;
    Ok(tokens)
}

# Prompts for the app password, or reads ATPROTO_PASSWORD.
atpxrpc login alice.bsky.social

echo '{
  "repo": "alice.bsky.social",
  "collection": "app.bsky.feed.post",
  "rkey": "3kabcdefghij",
  "record": {
    "$type": "app.bsky.feed.post",
    "text": "hello",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}' | atpxrpc com.atproto.repo.putRecord --body -

use atproto_client::client::{Auth, DPoPAuth};
use atproto_client::com::atproto::repo::{
    create_record, CreateRecordRequest, CreateRecordResponse,
};
use atproto_identity::key::identify_key;
use atproto_record::tid::Tid;
use serde_json::json;

async fn publish(
    http_client: &reqwest::Client,
    document: &atproto_identity::model::Document,
    access_token: &str,
) -> anyhow::Result<()> {
    // The endpoint comes from the account's own DID document.
    let endpoints = document.pds_endpoints_validated();
    let pds = endpoints.first().ok_or_else(|| anyhow::anyhow!("no PDS"))?;

    // Tokens from the OAuth flow are DPoP-bound: the proof key travels
    // with every request, not just the token exchange.
    let auth = Auth::DPoP(DPoPAuth {
        dpop_private_key_data: identify_key("did:key:zDna...")?,
        oauth_access_token: access_token.to_string(),
    });

    let request = CreateRecordRequest {
        repo:       document.id.clone(),
        collection: "app.bsky.feed.post".to_string(),
        record_key: Some(Tid::new().to_string()),
        validate:   true,
        record: json!({
            "$type": "app.bsky.feed.post",
            "text": "hello",
            "createdAt": "2026-01-01T00:00:00.000Z"
        }),
        swap_commit: None,
    };

    match create_record(http_client, &auth, pds, request).await? {
        CreateRecordResponse::StrongRef { uri, cid, .. } => {
            println!("{uri} @ {cid}");
        }
        CreateRecordResponse::Error(err) => {
            // Reached the server; the server said no.
            anyhow::bail!("createRecord refused: {err:?}");
        }
    }
    Ok(())
}

use async_trait::async_trait;
use atproto_jetstream::{
    Ack, ConsumerConfig, CursorStore, EventSink, Filters,
    Frame, JetstreamConsumer,
};
use tokio_util::sync::CancellationToken;

struct Printer;

#[async_trait]
impl EventSink for Printer {
    async fn deliver(&self, frame: Frame) -> Result<Ack, String> {
        if let Frame::Commit(commit) = frame {
            println!("{} {} {}", commit.seq, commit.did, commit.collection);
        }
        Ok(Ack)
    }
}

// `cursors` is yours: the crate will not decide where a cursor lives.
async fn run(cursors: impl CursorStore + 'static) -> anyhow::Result<()> {
    let config = ConsumerConfig::new("jetstream.us-east.bsky.network")
        .filters(Filters::commits_in(vec!["app.bsky.feed.post".to_string()]));

    JetstreamConsumer::new(config, Printer, cursors)
        .run(CancellationToken::new())
        .await?;
    Ok(())
}

use atproto_jetstream::{
    fetch_dictionary, ConsumerConfig, CursorStore, EventSink, JetstreamConsumer,
};

async fn compressed<S: EventSink, C: CursorStore>(
    config: ConsumerConfig,
    sink: S,
    cursors: C,
) -> anyhow::Result<JetstreamConsumer<S, C>> {
    // `None` asks the server for the dictionary it is using now.
    let dictionary =
        fetch_dictionary("jetstream.us-east.bsky.network", None).await?;
    Ok(JetstreamConsumer::new(config, sink, cursors).compression(dictionary))
}