add-auth
Skill4 starsChanged 4 months agoMITView on GitHub
Add JWT authentication to pico-fastapi controllers. Use when protecting endpoints, adding role-based access control, implementing custom role resolvers, or configuring SecurityContext.
- Installs packages
4 other projects use a version of this.
Adopted by
Most recently taken up by
- flavien-ia/hypervibe-harnesstheir own version, first seen Nov 15, 2026
- flavien-ia/hypervibe-crafttheir own version, first seen Oct 25, 2026
- JoviDeCroock/prachttheir own version, first seen Oct 11, 2026
- T4LEL/Claude-Arsenaltheir own version, first seen Jul 12, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- JoviDeCroock/pracht★ 113same name
- flavien-ia/hypervibe-craft★ 52same name
- flavien-ia/hypervibe-harness★ 52same name
- T4LEL/Claude-Arsenal★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- add-actuatorSkill
- add-appSkill
- add-celery-taskSkill
- add-componentSkill
- add-controllerSkill
- add-repositorySkill
- add-server-authSkill
- add-testsSkill
- add-validationSkill
- init-projectSkill
- pico-conventionsSkill
- releaseSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Add JWT authentication for: $ARGUMENTS
- Distinctive: line 12
Read the codebase to understand existing controllers and patterns, then add authentication following these templates.
- Distinctive: line 129
When roles are stored in a database:
- Very specific: line 203
When liboqs-python is not installed, ML-DSA tokens are rejected with AuthConfigurationError.
- Very specific: line 217
Run PQC tests in Docker: make pqc-test
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add Authentication
Add JWT authentication for: $ARGUMENTS
Read the codebase to understand existing controllers and patterns, then add authentication following these templates.
Protect All Routes (Default)
pico-client-auth protects all routes by default. Just add the dependency and configure:
# application.yaml
auth_client:
issuer: https://auth.example.com
audience: my-apifrom pico_boot import init
from pico_ioc import configuration, YamlTreeSource
from fastapi import FastAPI
config = configuration(YamlTreeSource("application.yaml"))
container = init(modules=["myapp"], config=config)
app = container.get(FastAPI)
# All routes are now protected — pico-client-auth is auto-discoveredPublic Endpoint
from pico_fastapi import controller, get
from pico_client_auth import allow_anonymous
@controller(prefix="/api")
class HealthController:
@get("/health")
@allow_anonymous
async def health(self):
return {"status": "ok"}Role-Protected Endpoint
from pico_fastapi import controller, get, post
from pico_client_auth import SecurityContext, requires_role
@controller(prefix="/api/admin", tags=["admin"])
class AdminController:
def __init__(self, service: AdminService):
self.service = service
@get("/users")
@requires_role("admin")
async def list_users(self):
return await self.service.list_users()
@post("/users/{user_id}/ban")
@requires_role("admin", "moderator")
async def ban_user(self, user_id: str):
return await self.service.ban(user_id)Group-Protected Endpoint
from pico_fastapi import controller, get
from pico_client_auth import requires_group, SecurityContext
@controller(prefix="/api/projects", tags=["projects"])
class ProjectController:
def __init__(self, service: ProjectService):
self.service = service
@get("/{project_id}")
@requires_group("project-alpha", "project-beta")
async def get_project(self, project_id: str):
return await self.service.get(project_id)Access Claims in Services
SecurityContext works anywhere within a request — controllers, services, repositories:
from pico_ioc import component
from pico_client_auth import SecurityContext
@component
class AuditService:
async def log_action(self, action: str):
claims = SecurityContext.require()
print(f"[{claims.sub}] {action}")
async def get_current_org(self) -> str:
return SecurityContext.require().org_id
async def check_group_access(self, group_id: str) -> bool:
return SecurityContext.has_group(group_id)
async def get_user_groups(self) -> tuple[str, ...]:
return SecurityContext.get_groups()Custom Role Resolver (Roles Array)
Override when tokens use a roles array instead of a single role string:
from pico_ioc import component
from pico_client_auth import RoleResolver, TokenClaims
@component
class ArrayRoleResolver:
async def resolve(self, claims: TokenClaims, raw_claims: dict) -> list[str]:
return raw_claims.get("roles", [])Database Role Resolver with TTL Cache
When roles are stored in a database:
import time
from pico_ioc import component
from pico_client_auth import RoleResolver, TokenClaims
@component
class DatabaseRoleResolver:
def __init__(self, role_repository: RoleRepository):
self._repo = role_repository
self._cache: dict[str, tuple[float, list[str]]] = {}
self._ttl = 300 # 5 minutes
async def resolve(self, claims: TokenClaims, raw_claims: dict) -> list[str]:
cached = self._cache.get(claims.sub)
if cached and (time.monotonic() - cached[0]) < self._ttl:
return cached[1]
roles = await self._repo.find_roles_by_user(claims.sub)
self._cache[claims.sub] = (time.monotonic(), roles)
return rolesKeycloak Realm Roles
@component
class KeycloakRoleResolver:
async def resolve(self, claims: TokenClaims, raw_claims: dict) -> list[str]:
realm_access = raw_claims.get("realm_access", {})
return realm_access.get("roles", [])Disable Auth for Development
auth_client:
enabled: falsePost-Quantum (ML-DSA) Authentication
Enable ML-DSA-65 / ML-DSA-87 post-quantum JWT verification:
pip install pico-client-auth[pqc]# application.yaml
auth_client:
issuer: https://auth.example.com
audience: my-api
accepted_algorithms:
- RS256
- ML-DSA-65ML-DSA tokens use the AKP JWK key type with base64url-encoded raw public keys (per draft-ietf-cose-dilithium). The TokenValidator automatically dispatches ML-DSA tokens to pqc_jwt (liboqs) and RS256 tokens to PyJWT.
JWKS response with ML-DSA key:
{
"keys": [
{"kty": "AKP", "kid": "pqc-key-1", "alg": "ML-DSA-65", "pub": "<base64url>"}
]
}Supported algorithms: ML-DSA-65 (NIST Level 3), ML-DSA-87 (NIST Level 5).
When liboqs-python is not installed, ML-DSA tokens are rejected with AuthConfigurationError. RS256 continues to work without liboqs.
Testing PQC
PQC tests skip gracefully without liboqs via pytest.importorskip("oqs"):
def test_pqc_token(mldsa65_keypair, make_pqc_token):
oqs = pytest.importorskip("oqs")
public_key, secret_key = mldsa65_keypair
token = make_pqc_token(secret_key, algorithm="ML-DSA-65")
# ... test with tokenRun PQC tests in Docker: make pqc-test
Checklist
auth_client.issuerandauth_client.audienceconfigured- Public endpoints marked with
@allow_anonymous - Admin endpoints protected with
@requires_role - Group-restricted endpoints protected with
@requires_group SecurityContext.require()used in services (not just controllers)- Custom
RoleResolverregistered if token structure differs from default - Tests use RSA keypair fixture and
make_tokenfactory - If PQC:
accepted_algorithmsincludes ML-DSA variant,pqcextra installed
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

