phzyx-auth 0.1.0__tar.gz

phzyx_auth-0.1.0/.gitignore

@@ -0,0 +1,87 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.eggs/
+dist/
+!packages/admin/web/dist/
+!packages/admin/web/dist/**
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+examples/**/.venv/
+
+# uv / packaging
+# uv.lock is committed for reproducible workspace installs
+
+# Testing / coverage
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+coverage.json
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# Type checkers / IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# Node (AdminBoard SPA + sites)
+node_modules/
+.pnpm-store/
+packages/admin/web/node_modules/
+# Built SPA is committed for offline wheel/demo convenience (M4);
+# rebuild via packages/admin/web `npm run build` when sources change.
+# packages/admin/web/dist/
+
+# Local tooling
+.justfile.local
+packages/admin/web/node_modules/
+dist-release/
+
+# Local demo SQLite
+examples/**/*.db
+examples/**/media/
+
+
+# Admin web tooling
+packages/admin/web/test-results/
+packages/admin/web/playwright-report/
+packages/admin/web/blob-report/
+
+# Private: research, design plans, AI agent helpers (local only — do not push)
+# Files remain on disk; they are untracked for remotes.
+research/
+AGENTS.md
+AGENT_TO_AGENT.md
+docs/agent-rules.md
+.cursor/
+.claude/
+.grok/
+

phzyx_auth-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: phzyx-auth
+Version: 0.1.0
+Summary: Phzyx Auth — secure-by-default identity, sessions, JWT, API keys, RBAC (Forge battery)
+Project-URL: Homepage, https://phzyx.xyz
+Project-URL: Repository, https://github.com/phzyxyz/forge
+Author: Athul Nandaswaroop
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: argon2-cffi>=23
+Requires-Dist: phzyx-forge<0.2,>=0.1.0
+Requires-Dist: pydantic>=2
+Requires-Dist: pyjwt>=2.8
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == 'fastapi'
+Provides-Extra: litestar
+Requires-Dist: litestar>=2.12; extra == 'litestar'
+Provides-Extra: mfa
+Requires-Dist: pyotp>=2.9; extra == 'mfa'
+Provides-Extra: oauth
+Requires-Dist: authlib>=1.3; extra == 'oauth'
+Requires-Dist: httpx>=0.27; extra == 'oauth'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Provides-Extra: webauthn
+Requires-Dist: webauthn>=2.0; extra == 'webauthn'
+Description-Content-Type: text/markdown
+
+# phzyx-auth
+
+Secure-by-default authentication & authorization for Phzyx apps and AdminBoard.
+
+**Public battery** for Forge (depends on `phzyx-forge` on PyPI).
+
+```bash
+uv add 'phzyx-forge[auth]'
+# or
+uv add 'phzyx-auth[fastapi]'
+```
+
+## Status (0.1.0)
+
+**Phase A + B shipped** (memory backends; ORM-backed stores next):
+
+| Area | What you get |
+|------|----------------|
+| Passwords | Argon2id, policy min length |
+| Sessions | Opaque cookie sessions (hashed at rest), idle + absolute TTL |
+| JWT | HS256 access + rotating refresh |
+| API keys | `phx_` prefix, scopes, list/revoke |
+| RBAC | Groups/Permissions models, Principal, `ensure_*` + Depends + decorators |
+| Lockout | Failed-login counter + rate limits + audit log |
+| Reset / change | Forgot/reset (anti-enum), change password, revoke sessions |
+| Email verify | Token issue + verify (`email_verified` flag) |
+| CSRF | Double-submit cookie + `X-CSRF-Token` for session mutations |
+| WebSocket | `websocket_principal` (cookie / Bearer / API key, close 4401) |
+| AdminBoard | `PhzyxAuthz` permission bridge |
+| CLI | `phzyx-auth create-superuser` |
+
+**Later:** OAuth IdPs (Phase D stub in `oauth.py`), MFA/passkeys (E), orgs (F), Redis rate limit, ORM session store.
+
+## Quick start (FastAPI)
+
+```python
+from fastapi import Depends, FastAPI
+from phzyx.auth import AuthConfig, AuthService, Principal
+from phzyx.auth.adapters.fastapi import mount_auth, require_user
+
+app = FastAPI()
+svc = AuthService(
+    config=AuthConfig(
+        secret="use-PHZYX_AUTH_SECRET-32+bytes-in-prod!!",
+        production=False,
+        cookie_secure=False,
+    )
+)
+mount_auth(app, svc)
+
+@app.get("/private")
+async def private(user: Principal = Depends(require_user)):
+    return {"email": user.email}
+```
+
+```bash
+# create staff superuser (in-memory unless you wire persistence)
+phzyx-auth create-superuser --email admin@example.com --password 'longpassword1'
+```
+
+### SPA cookie flow
+
+1. `POST /auth/login` → sets `phzyx_session` (HttpOnly) + `phzyx_csrf` + returns `csrf_token`
+2. Mutating requests with the session cookie must send header `X-CSRF-Token: <csrf_token>`
+3. Bearer JWT / `X-API-Key` skip CSRF
+
+### In-body checks (no middleware)
+
+```python
+from phzyx.auth.guards import ensure_authenticated, ensure_permissions
+
+p = svc.resolve_principal(session_token=cookie, authorization=authz, api_key=key)
+user = ensure_authenticated(p)
+ensure_permissions(user, ["posts:create"])
+```
+
+## Security defaults
+
+- Argon2id hashing  
+- Secrets ≥ 32 bytes (HS256 / pepper)  
+- Opaque sessions + short JWT access  
+- API keys hashed at rest  
+- Lockout + IP/email rate limits  
+- Password reset anti-enumeration  
+- Extensible `AbstractUser`  
+
+**Research (do not re-derive):** [`research/plan/20_phzyx_auth.md`](../../research/plan/20_phzyx_auth.md)  
+**Tracker:** [`PHZYX_ROADMAP.html`](../../PHZYX_ROADMAP.html) track **AUTH**.

phzyx_auth-0.1.0/README.md

@@ -0,0 +1,88 @@
+# phzyx-auth
+
+Secure-by-default authentication & authorization for Phzyx apps and AdminBoard.
+
+**Public battery** for Forge (depends on `phzyx-forge` on PyPI).
+
+```bash
+uv add 'phzyx-forge[auth]'
+# or
+uv add 'phzyx-auth[fastapi]'
+```
+
+## Status (0.1.0)
+
+**Phase A + B shipped** (memory backends; ORM-backed stores next):
+
+| Area | What you get |
+|------|----------------|
+| Passwords | Argon2id, policy min length |
+| Sessions | Opaque cookie sessions (hashed at rest), idle + absolute TTL |
+| JWT | HS256 access + rotating refresh |
+| API keys | `phx_` prefix, scopes, list/revoke |
+| RBAC | Groups/Permissions models, Principal, `ensure_*` + Depends + decorators |
+| Lockout | Failed-login counter + rate limits + audit log |
+| Reset / change | Forgot/reset (anti-enum), change password, revoke sessions |
+| Email verify | Token issue + verify (`email_verified` flag) |
+| CSRF | Double-submit cookie + `X-CSRF-Token` for session mutations |
+| WebSocket | `websocket_principal` (cookie / Bearer / API key, close 4401) |
+| AdminBoard | `PhzyxAuthz` permission bridge |
+| CLI | `phzyx-auth create-superuser` |
+
+**Later:** OAuth IdPs (Phase D stub in `oauth.py`), MFA/passkeys (E), orgs (F), Redis rate limit, ORM session store.
+
+## Quick start (FastAPI)
+
+```python
+from fastapi import Depends, FastAPI
+from phzyx.auth import AuthConfig, AuthService, Principal
+from phzyx.auth.adapters.fastapi import mount_auth, require_user
+
+app = FastAPI()
+svc = AuthService(
+    config=AuthConfig(
+        secret="use-PHZYX_AUTH_SECRET-32+bytes-in-prod!!",
+        production=False,
+        cookie_secure=False,
+    )
+)
+mount_auth(app, svc)
+
+@app.get("/private")
+async def private(user: Principal = Depends(require_user)):
+    return {"email": user.email}
+```
+
+```bash
+# create staff superuser (in-memory unless you wire persistence)
+phzyx-auth create-superuser --email admin@example.com --password 'longpassword1'
+```
+
+### SPA cookie flow
+
+1. `POST /auth/login` → sets `phzyx_session` (HttpOnly) + `phzyx_csrf` + returns `csrf_token`
+2. Mutating requests with the session cookie must send header `X-CSRF-Token: <csrf_token>`
+3. Bearer JWT / `X-API-Key` skip CSRF
+
+### In-body checks (no middleware)
+
+```python
+from phzyx.auth.guards import ensure_authenticated, ensure_permissions
+
+p = svc.resolve_principal(session_token=cookie, authorization=authz, api_key=key)
+user = ensure_authenticated(p)
+ensure_permissions(user, ["posts:create"])
+```
+
+## Security defaults
+
+- Argon2id hashing  
+- Secrets ≥ 32 bytes (HS256 / pepper)  
+- Opaque sessions + short JWT access  
+- API keys hashed at rest  
+- Lockout + IP/email rate limits  
+- Password reset anti-enumeration  
+- Extensible `AbstractUser`  
+
+**Research (do not re-derive):** [`research/plan/20_phzyx_auth.md`](../../research/plan/20_phzyx_auth.md)  
+**Tracker:** [`PHZYX_ROADMAP.html`](../../PHZYX_ROADMAP.html) track **AUTH**.

phzyx_auth-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "phzyx-auth"
+version = "0.1.0"
+description = "Phzyx Auth — secure-by-default identity, sessions, JWT, API keys, RBAC (Forge battery)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Athul Nandaswaroop" }]
+dependencies = [
+  "phzyx-forge>=0.1.0,<0.2",
+  "pydantic>=2",
+  "argon2-cffi>=23",
+  "PyJWT>=2.8",
+]
+
+[project.optional-dependencies]
+redis = ["redis>=5"]
+oauth = ["authlib>=1.3", "httpx>=0.27"]
+mfa = ["pyotp>=2.9"]
+webauthn = ["webauthn>=2.0"]
+fastapi = ["fastapi>=0.115"]
+litestar = ["litestar>=2.12"]
+
+[project.scripts]
+phzyx-auth = "phzyx.auth.cli:main"
+
+[project.urls]
+Homepage = "https://phzyx.xyz"
+Repository = "https://github.com/phzyxyz/forge"
+
+[tool.uv.sources]
+phzyx-forge = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/phzyx"]

phzyx_auth-0.1.0/src/phzyx/auth/__init__.py

@@ -0,0 +1,141 @@
+"""Phzyx Auth — identity, sessions, JWT, API keys, guards (batteries optional)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from phzyx.auth.admin_bridge import PhzyxAuthz, PhzyxFieldAuthz
+from phzyx.auth.api_keys import IssuedAPIKey, MemoryAPIKeyStore
+from phzyx.auth.audit import AuditLog
+from phzyx.auth.config import AuthConfig
+from phzyx.auth.decorators import (
+    require_auth,
+    require_permissions,
+    require_scopes,
+    require_staff,
+    require_superuser,
+)
+from phzyx.auth.errors import (
+    AuthError,
+    ForbiddenError,
+    InvalidCredentialsError,
+    LockedError,
+    MfaRequiredError,
+    UnauthorizedError,
+    ValidationAuthError,
+)
+from phzyx.auth.models import (
+    AUTH_MODELS,
+    AbstractUser,
+    Group,
+    MFAFactor,
+    OAuthAccount,
+    Permission,
+    User,
+)
+from phzyx.auth.oauth import (
+    AuthlibOAuthProvider,
+    OAuthNotConfiguredError,
+    OAuthProviderConfig,
+    StaticOAuthProvider,
+    build_provider,
+    preset_config,
+)
+from phzyx.auth.orm_stores import (
+    HybridUserMap,
+    OrmAPIKeyStore,
+    OrmPasswordResetStore,
+    OrmSessionStore,
+    OrmUserRepository,
+)
+from phzyx.auth.passkeys import HmacPasskeyBackend, default_passkey_backend, sign_hmac_assertion
+from phzyx.auth.password import PasswordHasher, generate_token, hash_password, verify_password
+from phzyx.auth.principal import Principal, principal_from_user
+from phzyx.auth.rate_limit import MemoryRateLimiter, RedisRateLimiter
+from phzyx.auth.rbac import has_permission, resolve_permissions, seed_resource_permissions
+from phzyx.auth.service import AuthResult, AuthService, MfaChallenge
+from phzyx.auth.service_async import AsyncAuthService
+from phzyx.auth.sessions import MemorySessionStore
+from phzyx.auth.tokens import JwtService, TokenPair
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AUTH_MODELS",
+    "AbstractUser",
+    "AsyncAuthService",
+    "AuditLog",
+    "AuthConfig",
+    "AuthError",
+    "AuthResult",
+    "AuthService",
+    "AuthlibOAuthProvider",
+    "ForbiddenError",
+    "Group",
+    "HmacPasskeyBackend",
+    "InvalidCredentialsError",
+    "IssuedAPIKey",
+    "JwtService",
+    "LockedError",
+    "HybridUserMap",
+    "MFAFactor",
+    "MemoryAPIKeyStore",
+    "MemoryRateLimiter",
+    "MemorySessionStore",
+    "MfaChallenge",
+    "MfaRequiredError",
+    "OAuthAccount",
+    "OAuthNotConfiguredError",
+    "OAuthProviderConfig",
+    "OrmAPIKeyStore",
+    "OrmPasswordResetStore",
+    "OrmSessionStore",
+    "OrmUserRepository",
+    "PasswordHasher",
+    "Permission",
+    "PhzyxAuthz",
+    "PhzyxFieldAuthz",
+    "Principal",
+    "RedisRateLimiter",
+    "StaticOAuthProvider",
+    "TokenPair",
+    "UnauthorizedError",
+    "User",
+    "ValidationAuthError",
+    "__version__",
+    "build_provider",
+    "create_superuser",
+    "default_passkey_backend",
+    "generate_token",
+    "has_permission",
+    "hash_password",
+    "mount_auth",
+    "mount_auth_litestar",
+    "preset_config",
+    "principal_from_user",
+    "require_auth",
+    "require_permissions",
+    "require_scopes",
+    "require_staff",
+    "require_superuser",
+    "resolve_permissions",
+    "sign_hmac_assertion",
+    "seed_resource_permissions",
+    "verify_password",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "mount_auth":
+        from phzyx.auth.adapters.fastapi import mount_auth
+
+        return mount_auth
+    if name == "mount_auth_litestar":
+        from phzyx.auth.adapters.litestar import mount_auth_litestar
+
+        return mount_auth_litestar
+    if name == "create_superuser":
+        from phzyx.auth.cli import create_superuser
+
+        return create_superuser
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

phzyx_auth-0.1.0/src/phzyx/auth/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""Framework adapters (FastAPI, Litestar, …)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["mount_auth", "mount_auth_litestar"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "mount_auth":
+        from phzyx.auth.adapters.fastapi import mount_auth
+
+        return mount_auth
+    if name == "mount_auth_litestar":
+        from phzyx.auth.adapters.litestar import mount_auth_litestar
+
+        return mount_auth_litestar
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")