mirror of
https://github.com/FuelLabs/sway.git
synced 2025-08-07 20:28:43 +00:00
8b29cc39c5
Some checks failed
CI / check-forc-manifest-version (push) Has been cancelled
CI / get-fuel-core-version (push) Has been cancelled
Codspeed Benchmarks / benchmarks (push) Has been cancelled
CI / check-dependency-version-formats (push) Has been cancelled
CI / build-sway-lib-std (push) Has been cancelled
CI / build-sway-examples (push) Has been cancelled
CI / build-reference-examples (push) Has been cancelled
CI / forc-fmt-check-sway-lib-std (push) Has been cancelled
CI / forc-fmt-check-sway-examples (push) Has been cancelled
CI / forc-fmt-check-panic (push) Has been cancelled
CI / check-sdk-harness-test-suite-compatibility (push) Has been cancelled
CI / build-mdbook (push) Has been cancelled
CI / build-forc-doc-sway-lib-std (push) Has been cancelled
CI / build-forc-test-project (push) Has been cancelled
CI / cargo-clippy (push) Has been cancelled
CI / cargo-fmt-check (push) Has been cancelled
CI / cargo-build-workspace (push) Has been cancelled
CI / cargo-toml-fmt-check (push) Has been cancelled
CI / cargo-run-e2e-test-evm (push) Has been cancelled
CI / cargo-test-lib-std (push) Has been cancelled
CI / forc-run-benchmarks (push) Has been cancelled
CI / forc-unit-tests (push) Has been cancelled
CI / forc-pkg-fuels-deps-check (push) Has been cancelled
CI / cargo-test-sway-lsp (push) Has been cancelled
CI / cargo-test-forc (push) Has been cancelled
CI / cargo-test-workspace (push) Has been cancelled
CI / cargo-unused-deps-check (push) Has been cancelled
CI / pre-publish-check (push) Has been cancelled
github pages / deploy (push) Has been cancelled
CI / verifications-complete (push) Has been cancelled
CI / cargo-run-e2e-test (push) Has been cancelled
CI / cargo-run-e2e-test-release (push) Has been cancelled
CI / cargo-test-forc-debug (push) Has been cancelled
CI / cargo-test-forc-client (push) Has been cancelled
CI / cargo-test-forc-mcp (push) Has been cancelled
CI / cargo-test-forc-node (push) Has been cancelled
CI / notify-slack-on-failure (push) Has been cancelled
CI / publish (push) Has been cancelled
CI / publish-sway-lib-std (push) Has been cancelled
CI / Build and upload forc binaries to release (push) Has been cancelled
## Description This PR introduces api-key based auth (and management endpoints for an admin account) for the `forc-mcp` HTTP server. Functionality includes: - Admin-only API key management endpoints for creating, listing, viewing, and deleting API keys - Enhanced rate limiting with separate limits for public and authenticated requests - Flexible authentication modes supporting both public access and API-key-only operation The docs have been updated with details on how to add MCP server with auth for claude and cursor. Addresses https://github.com/FuelLabs/sway/issues/7301 <details> <summary>Admin Endpoints</summary> All admin endpoints require authentication with an admin API key via `X-API-Key` header: #### `POST` `/admin/api-keys` - Creates new user-level API keys - Returns the generated API key (shown only once for security) - Generated keys use secure SHA256 hashing with `mcp_` prefix #### `GET` `/admin/api-keys` - Lists all API keys with usage statistics - Optional include_admin=true query parameter to include admin keys - Shows real-time usage counters and rate limit status #### `GET` `/admin/api-keys/{key_id}` - Retrieves details for a specific API key - Returns `404` for admin keys to maintain security - Includes current usage statistics #### `DELETE` `/admin/api-keys/{key_id}` - Deletes specific API keys - Prevents deletion of admin keys (returns 403) - Returns `204` on successful deletion #### `POST` `/admin/import` - Bulk imports API keys with historical usage data - Supports merge mode (default) or replace mode with `clear_existing: true` - Useful for migration or backup restoration </details> ### Dual-Tier Rate Limiting System #### Public Requests (no API key): - Default: `10` requests/minute, `1,000` requests/day - Tracked by client IP address #### Authenticated Requests (with API key): - Default: `120` requests/minute, `10,000` requests/day - Admin keys have unlimited access - Tracked per API key with usage persistence #### Intelligent Counter Reset Logic - Per-minute counters reset after `60` seconds - Daily counters reset at midnight (UTC date change) ### Authentication Modes - Mixed Mode (Default) - Allows both public and authenticated access - Public requests get lower rate limits - API key holders get higher rate limits - API Keys Only Mode - Set `api_keys_only: true` in configuration - Rejects all requests without valid API key - Suitable for production deployments requiring authentication ### Testing - Unit tests for authentication middleware - Integration tests for admin endpoints - Rate limiting validation tests - API key lifecycle tests (create, use, delete) - Security tests (unauthorized access, role escalation) - Persistence tests (file storage, restart recovery) ## Checklist - [x] I have linked to any relevant issues. - [x] I have commented my code, particularly in hard-to-understand areas. - [x] I have updated the documentation where relevant (API docs, the reference, and the Sway book). - [ ] If my change requires substantial documentation changes, I have [requested support from the DevRel team](https://github.com/FuelLabs/devrel-requests/issues/new/choose) - [x] I have added tests that prove my fix is effective or that my feature works. - [x] I have added (or requested a maintainer to add) the necessary `Breaking*` or `New Feature` labels where relevant. - [x] I have done my best to ensure that my PR adheres to [the Fuel Labs Code Review Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md). - [x] I have requested a review from the relevant team or maintainers. --------- Co-authored-by: z <zees-dev@users.noreply.github.com> Co-authored-by: Joshua Batty <joshpbatty@gmail.com> |
||
|---|---|---|
| .. | ||
| src | ||
| theme | ||
| .gitignore | ||
| .spellcheck.yml | ||
| book.toml | ||
| README.md | ||
| spell-check-custom-words.txt | ||
Documentation
Building From Source
Install mdbook and then open a new terminal session in order to run the subsequent commands
cargo install mdbook
To set up and build the book locally, you must also have mdbook-forc-documenter preprocessor and relevant forc plugins installed.
If you wish to make changes to the Commands or Plugins chapters, please read the next section first.
From the project root, install mdbook-forc-documenter:
cargo install --path ./scripts/mdbook-forc-documenter
You must also install forc plugins that are already documented within the book. You can skip plugins that are going to be removed and install plugins that are going to be added to the book:
cargo install --path ./forc-plugins/forc-client
cargo install --path ./forc-plugins/forc-doc
cargo install --path ./forc-plugins/forc-fmt
cargo install --path ./forc-plugins/forc-lsp
To build book:
mdbook build docs/book
To build the book on strict mode to check if pages should be removed or added within the Forc Reference:
MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs/book
To serve locally:
mdbook serve docs/book
Generating documentation for Forc commands/plugins
The mdbook-forc-documenter preprocessor now automatically handles documenting forc commands and plugins, but some actions have to be taken for the preprocessor to work. Please read the mdbook-forc-documenter README before making changes to Forc commands or plugins.
It is important to note that changing the chapter names Commands and Plugins will affect the behavior of the preprocessor. When renaming the chapters, please make the same change here.