Bluesky Social Cookbook

The ATProto Hacker Cookbook is a collection of example projects and scripts designed to help developers get started with AT Protocol (atproto) development. It includes implementations for posting to Bluesky, building bots, exporting repositories, and implementing OAuth services using various languages including Python, TypeScript, and Go.

Available example projects:

* How to make a post in Bluesky (Python)
* Starter kit for a Bluesky bot (TypeScript)
* Download and Inspect Repository (Go)
* OAuth Web Service (Python)
* OAuth Web Service (Go)
* OAuth CLI App (Go)
* XRPC API Server (Go)

When initializing a ClientConfig, you must define the permissions your application requests from the user via the scopes array.

Key Concepts

• atproto scope: Required for all applications to indicate the client is using the ATProto profile of OAuth.
• Granular Scopes: You can request specific permissions, such as repo:app.bsky.feed.post?action=create to allow creating Bluesky posts without granting broader repository access.
• Client Metadata: If hosting at a publicly-reachable hostname (not localhost), you must host a "client metadata" document. The SDK can help generate this via Server.ClientMetadata.

Best Practice: Only request the minimum permissions required for your app to function to improve user trust and security.

Maintaining OAuth sessions requires storing state, including session tokens and refresh tokens. The SDK manages this state via the ClientAuthStore interface.

To use the SDK, you must provide your own implementation of this interface. The example implementation in this repository uses SQLite (sqlitestore.go). For production environments, a Redis-backed implementation is recommended.

Once a user is signed in, you can interact with the ATProto network using agents.

• PdsAgentProvider: Demonstrates how to create an Agent instance to make authenticated requests directly to the user's Personal Data Server (PDS).
• BskyAgentProvider: Demonstrates how to create a BskyAgent to interact with a dedicated appview (such as the Bluesky public API).

An implementation example using both agents is located in app/(authenticated)/index.tsx.

This project demonstrates how to implement a Python web service using Flask and SQLite that authenticates via atproto OAuth. It uses uv for dependency management.

Prerequisites

1. Install uv (installation guide).
2. A globally routed domain name with a valid HTTPS certificate (required for production deployment).

Local Setup

1. Sync dependencies:

   uv sync

2. Configure environment variables:
   • Copy example.env to .env.
   • Generate a FLASK_SECRET_KEY for cookie session security.
   • Generate a FLASK_CLIENT_SECRET_JWK for the OAuth confidential client.
3. Run the service:

   uv run -- flask run

Note: For local testing, the service automatically uses a localhost client ID.

uv sync
# After updating .env with secrets
uv run -- flask run

You can install the binary to your ~/go/bin directory or run it directly from the source code.

# Install the binary
go install

# Or run directly without installing
go run .

To use the create_bsky_post.py script, you must install the requests and bs4 (BeautifulSoup) libraries. You can install them using pip:

pip install requests bs4

You can install go-repo-export directly using the Go toolchain without cloning the repository, or build it from source. Ensure you have the Go programming language toolchain installed first.

# Install and run directly
go install github.com/bluesky-social/cookbook/go-repo-export@latest

go-repo-export [...]

# Or build from source
git clone https://github.com/bluesky-social/cookbook
cd cookbook/go-repo-export
go build ./...

./go-repo-export [...]

To run the service, you must populate the .env file with two specific secrets. Use the following commands to generate them:

1. FLASK_SECRET_KEY: Used for cookie session security. Generate a hex string using Python's secrets module.
2. FLASK_CLIENT_SECRET_JWK: Used for the OAuth confidential client. Run the provided generate_jwk.py script.

# Generate FLASK_SECRET_KEY
uv run python3 -c 'import secrets; print(secrets.token_hex())'

# Generate FLASK_CLIENT_SECRET_JWK
uv run ./generate_jwk.py

To deploy the application to a public-facing server, you must ensure the client metadata document is publicly accessible via HTTPS with a valid certificate. The Authorization Server requires this document during the authentication process.

1. Copy the template metadata file: oauth-client-metadata.example.json to oauth-client-metadata.json.
2. Replace all instances of EXAMPLE.COM with your actual public hostname (ensure the hostname is lowercase).

You can use sed to perform this replacement:

sed s/EXAMPLE.COM/my-real-hostname.com/g oauth-client-metadata.example.json > oauth-client-metadata.json

The create_bsky_post.py script demonstrates how to create posts using the Bluesky API, including various features and embed options. To run the script and see the available options and arguments, execute it from your terminal.

Prerequisites

• Python 3.11 (tested)
• requests package
• bs4 (BeautifulSoup) package

./create_bsky_post.py