Document authentication system added in PR #24

[Copilot]

PR #24 added JWT-based authentication with OAuth2 client credentials flow, scope-based permissions, and client management endpoints. This updates the README to document the new authentication system.

Configuration

• Added FASTPUBSUB_AUTH_ENABLED (default: false), FASTPUBSUB_AUTH_SECRET_KEY, FASTPUBSUB_AUTH_ALGORITHM, and FASTPUBSUB_AUTH_ACCESS_TOKEN_EXPIRE_MINUTES environment variables

CLI Commands

• generate_secret_key - Generates cryptographically secure secret for JWT signing
• create_client <name> <scopes> <is_active> - Creates OAuth client with specified permissions

Scopes

Global scopes: * (admin), topics:{create,read,delete,publish}, subscriptions:{create,read,delete,consume}, clients:{create,update,read,delete}

Object-specific scopes: topics:publish:my-topic-id restricts publish to single topic

API Reference

• Authentication flow: POST /oauth/token with client_id/client_secret returns JWT access token
• Client management: Full CRUD at /clients endpoint (create, get, list, update, delete)
• Token usage: Include Authorization: Bearer <token> header on authenticated requests
• Token revocation: Updating a client increments token_version, invalidating existing tokens

Examples

# Generate secret and create admin client
docker run --rm allisson/fastpubsub generate_secret_key
docker run --rm \
  -e FASTPUBSUB_AUTH_ENABLED=true \
  -e FASTPUBSUB_AUTH_SECRET_KEY=<generated-secret> \
  allisson/fastpubsub create_client "Admin" "*" true

# Get access token
curl -X POST http://localhost:8000/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id": "<id>", "client_secret": "<secret>"}'

# Use token
curl -H "Authorization: Bearer <token>" http://localhost:8000/topics

Troubleshooting

• 401 errors: Verify FASTPUBSUB_AUTH_ENABLED=true on server, token not expired (30min default), client active
• 403 errors: Check client has required scope (e.g., topics:publish or topics:publish:specific-topic)

Original prompt

Update the README.md with the recent changes of #24

Some additional information:

• Authentication is optional and controlled by the env FASTPUBSUB_AUTH_ENABLED, which has a default value of false.

• To enable authentication, you must set the envs FASTPUBSUB_AUTH_ENABLED=true and FASTPUBSUB_AUTH_SECRET_KEY=my-super-secret-key.

• There is a command called generate_secret_key that generates a secure secret key for use.

• There is a command called create_client that generates a new client via the CLI.

• Regarding scopes, we have the following valid global scopes:
  “*” -> admin mode, can do anything.
  “topics:create” -> can create a new topic.
  “topics:read” -> can list or get a topic.
  “topics:delete” -> can delete a topic.
  “topics:publish” -> can publish a message to the topic.
  “subscriptions:create” -> can create a new subscription.
  “subscriptions:read” -> can list or get a subscription.
  “subscriptions:delete” -> can delete a subscription.
  “subscriptions:consume” -> can consume messages from subscription.
  “clients:create” -> can create a new client.
  “clients:update” -> can update a client.
  “clients:read” -> can list or get a client.
  “clients:delete” -> can delete a client.

• We can have scopes per object. For a client to publish to only one topic, we can set a scope “topics:publish:my-topic-id.”

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.