nodus-auth 0.1.0__tar.gz

nodus_auth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shawn Knight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodus_auth-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: nodus-auth
+Version: 0.1.0
+Summary: JWT, API key auth, bcrypt hashing, and scoped principals for AI-native platforms
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-auth
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-auth
+Keywords: auth,jwt,api-key,bcrypt,nodus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-jose>=3.5.0
+Requires-Dist: passlib>=1.7.4
+Requires-Dist: bcrypt<5.0,>=4.0.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Dynamic: license-file
+
+# nodus-auth
+
+**JWT issuance/validation, API key hashing, bcrypt passwords, and scoped
+principals for AI-native platforms.**
+
+Standalone auth primitives — no FastAPI required. All core functions work
+with any Python web framework or no framework at all.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-auth
+```
+
+> **bcrypt version note:** This package pins `bcrypt>=4.0.1,<5.0` because
+> `passlib 1.7.4` is incompatible with bcrypt 5.x. Do not upgrade bcrypt
+> beyond 4.x in the same environment.
+
+---
+
+## What it provides
+
+| Component | Purpose |
+|---|---|
+| `KeyRing` / `create_access_token` / `decode_access_token` | JWT issuance and verification with key rotation |
+| `hash_password` / `verify_password` | bcrypt password hashing via passlib |
+| `generate_key` / `hash_key` | API key generation and SHA-256 storage hash |
+| `AuthPrincipal` / `Scopes` | Resolved identity with scope-based access control |
+| `LoginRequest` / `RegisterRequest` / `TokenResponse` | Pydantic request/response schemas |
+| `parse_user_id` / `require_user_id` | UUID parsing helpers |
+| `AuthSettings` | pydantic-settings config for SECRET_KEY, ALGORITHM, expiry |
+
+---
+
+## JWT tokens
+
+```python
+from nodus_auth import AuthSettings, create_access_token, decode_access_token, InvalidTokenError
+
+settings = AuthSettings(SECRET_KEY="my-secret-key-32-chars-minimum")
+token = create_access_token({"sub": "user-123"}, settings=settings)
+
+try:
+    payload = decode_access_token(token, settings=settings)
+    user_id = payload["sub"]
+except InvalidTokenError:
+    # expired, malformed, or wrong key
+    ...
+```
+
+### Key rotation
+
+```python
+from nodus_auth import KeyRing, create_access_token, decode_access_token, AuthSettings
+
+ring = KeyRing(active="key-v1", grace_hours=24)
+settings = AuthSettings(SECRET_KEY="key-v1")
+token = create_access_token({"sub": "u1"}, settings=settings, key_ring=ring)
+
+ring.rotate("key-v2")  # tokens signed with key-v1 still verify for 24 hours
+payload = decode_access_token(token, settings=settings, key_ring=ring)  # OK
+```
+
+`decode_access_token` tries the active key first, then any keys within their
+grace period. Tokens outside their grace window raise `InvalidTokenError`.
+
+---
+
+## Passwords
+
+```python
+from nodus_auth import hash_password, verify_password
+
+hashed = hash_password("correct-horse-battery-staple")
+assert verify_password("correct-horse-battery-staple", hashed)
+assert not verify_password("wrong-password", hashed)
+```
+
+---
+
+## API keys
+
+```python
+from nodus_auth import generate_key, hash_key
+
+raw_key, key_hash = generate_key()
+# Deliver raw_key to the caller once; store key_hash in the database
+assert hash_key(raw_key) == key_hash
+```
+
+`generate_key()` uses `secrets.token_urlsafe`. The raw key is never stored;
+the SHA-256 hash is used for all comparisons.
+
+---
+
+## Scoped principals
+
+```python
+from nodus_auth import AuthPrincipal, Scopes
+
+principal = AuthPrincipal(
+    user_id="user-123",
+    auth_type="api_key",
+    scopes=[Scopes.MEMORY_READ, Scopes.FLOW_EXECUTE],
+)
+assert principal.has_scope(Scopes.FLOW_EXECUTE)
+assert not principal.has_scope(Scopes.PLATFORM_ADMIN)
+```
+
+`auth_type` is `"jwt"` or `"api_key"`. `Scopes` provides well-known constants:
+`MEMORY_READ`, `MEMORY_WRITE`, `FLOW_EXECUTE`, `FLOW_CREATE`, `PLATFORM_ADMIN`.
+
+---
+
+## AuthSettings
+
+```python
+from nodus_auth import AuthSettings
+
+# Reads from environment variables: SECRET_KEY, ALGORITHM, ACCESS_TOKEN_EXPIRE_MINUTES
+settings = AuthSettings()
+
+# Or explicit:
+settings = AuthSettings(
+    SECRET_KEY="...",
+    ALGORITHM="HS256",
+    ACCESS_TOKEN_EXPIRE_MINUTES=60,
+)
+```
+
+---
+
+## User ID helpers
+
+```python
+from nodus_auth import parse_user_id, require_user_id, parse_user_ids
+import uuid
+
+parse_user_id("550e8400-e29b-41d4-a716-446655440000")  # → UUID
+parse_user_id(None)                                     # → None
+require_user_id("not-a-uuid")                           # raises ValueError
+parse_user_ids(["uid-1", "bad", "uid-2"])              # → [UUID, UUID]  (skips failures)
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `python-jose` | ≥3.5.0 | JWT encoding/decoding |
+| `passlib` | ≥1.7.4 | bcrypt password context |
+| `bcrypt` | ≥4.0.1,<5.0 | bcrypt backend (passlib 1.7.4 incompatible with 5.x) |
+| `pydantic` | ≥2.0.0 | Schemas |
+| `pydantic-settings` | ≥2.0.0 | `AuthSettings` from env vars |
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nodus_auth-0.1.0/README.md

@@ -0,0 +1,174 @@
+# nodus-auth
+
+**JWT issuance/validation, API key hashing, bcrypt passwords, and scoped
+principals for AI-native platforms.**
+
+Standalone auth primitives — no FastAPI required. All core functions work
+with any Python web framework or no framework at all.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-auth
+```
+
+> **bcrypt version note:** This package pins `bcrypt>=4.0.1,<5.0` because
+> `passlib 1.7.4` is incompatible with bcrypt 5.x. Do not upgrade bcrypt
+> beyond 4.x in the same environment.
+
+---
+
+## What it provides
+
+| Component | Purpose |
+|---|---|
+| `KeyRing` / `create_access_token` / `decode_access_token` | JWT issuance and verification with key rotation |
+| `hash_password` / `verify_password` | bcrypt password hashing via passlib |
+| `generate_key` / `hash_key` | API key generation and SHA-256 storage hash |
+| `AuthPrincipal` / `Scopes` | Resolved identity with scope-based access control |
+| `LoginRequest` / `RegisterRequest` / `TokenResponse` | Pydantic request/response schemas |
+| `parse_user_id` / `require_user_id` | UUID parsing helpers |
+| `AuthSettings` | pydantic-settings config for SECRET_KEY, ALGORITHM, expiry |
+
+---
+
+## JWT tokens
+
+```python
+from nodus_auth import AuthSettings, create_access_token, decode_access_token, InvalidTokenError
+
+settings = AuthSettings(SECRET_KEY="my-secret-key-32-chars-minimum")
+token = create_access_token({"sub": "user-123"}, settings=settings)
+
+try:
+    payload = decode_access_token(token, settings=settings)
+    user_id = payload["sub"]
+except InvalidTokenError:
+    # expired, malformed, or wrong key
+    ...
+```
+
+### Key rotation
+
+```python
+from nodus_auth import KeyRing, create_access_token, decode_access_token, AuthSettings
+
+ring = KeyRing(active="key-v1", grace_hours=24)
+settings = AuthSettings(SECRET_KEY="key-v1")
+token = create_access_token({"sub": "u1"}, settings=settings, key_ring=ring)
+
+ring.rotate("key-v2")  # tokens signed with key-v1 still verify for 24 hours
+payload = decode_access_token(token, settings=settings, key_ring=ring)  # OK
+```
+
+`decode_access_token` tries the active key first, then any keys within their
+grace period. Tokens outside their grace window raise `InvalidTokenError`.
+
+---
+
+## Passwords
+
+```python
+from nodus_auth import hash_password, verify_password
+
+hashed = hash_password("correct-horse-battery-staple")
+assert verify_password("correct-horse-battery-staple", hashed)
+assert not verify_password("wrong-password", hashed)
+```
+
+---
+
+## API keys
+
+```python
+from nodus_auth import generate_key, hash_key
+
+raw_key, key_hash = generate_key()
+# Deliver raw_key to the caller once; store key_hash in the database
+assert hash_key(raw_key) == key_hash
+```
+
+`generate_key()` uses `secrets.token_urlsafe`. The raw key is never stored;
+the SHA-256 hash is used for all comparisons.
+
+---
+
+## Scoped principals
+
+```python
+from nodus_auth import AuthPrincipal, Scopes
+
+principal = AuthPrincipal(
+    user_id="user-123",
+    auth_type="api_key",
+    scopes=[Scopes.MEMORY_READ, Scopes.FLOW_EXECUTE],
+)
+assert principal.has_scope(Scopes.FLOW_EXECUTE)
+assert not principal.has_scope(Scopes.PLATFORM_ADMIN)
+```
+
+`auth_type` is `"jwt"` or `"api_key"`. `Scopes` provides well-known constants:
+`MEMORY_READ`, `MEMORY_WRITE`, `FLOW_EXECUTE`, `FLOW_CREATE`, `PLATFORM_ADMIN`.
+
+---
+
+## AuthSettings
+
+```python
+from nodus_auth import AuthSettings
+
+# Reads from environment variables: SECRET_KEY, ALGORITHM, ACCESS_TOKEN_EXPIRE_MINUTES
+settings = AuthSettings()
+
+# Or explicit:
+settings = AuthSettings(
+    SECRET_KEY="...",
+    ALGORITHM="HS256",
+    ACCESS_TOKEN_EXPIRE_MINUTES=60,
+)
+```
+
+---
+
+## User ID helpers
+
+```python
+from nodus_auth import parse_user_id, require_user_id, parse_user_ids
+import uuid
+
+parse_user_id("550e8400-e29b-41d4-a716-446655440000")  # → UUID
+parse_user_id(None)                                     # → None
+require_user_id("not-a-uuid")                           # raises ValueError
+parse_user_ids(["uid-1", "bad", "uid-2"])              # → [UUID, UUID]  (skips failures)
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `python-jose` | ≥3.5.0 | JWT encoding/decoding |
+| `passlib` | ≥1.7.4 | bcrypt password context |
+| `bcrypt` | ≥4.0.1,<5.0 | bcrypt backend (passlib 1.7.4 incompatible with 5.x) |
+| `pydantic` | ≥2.0.0 | Schemas |
+| `pydantic-settings` | ≥2.0.0 | `AuthSettings` from env vars |
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nodus_auth-0.1.0/nodus_auth/__init__.py

@@ -0,0 +1,63 @@
+"""nodus-auth — JWT, API key auth, bcrypt, scoped principals.
+
+Core JWT:
+    KeyRing              — two-slot signing key ring with rotation support
+    create_access_token  — encode a JWT with configurable expiry
+    decode_access_token  — decode + verify a JWT (tries all keys in ring)
+    InvalidTokenError    — raised on malformed / expired tokens
+
+Password:
+    hash_password        — bcrypt hash via passlib
+    verify_password      — bcrypt verify
+
+API key utilities:
+    hash_key             — SHA-256 hex digest of a raw key
+    generate_key         — generate (raw_key, key_hash) pair
+
+Schemas:
+    LoginRequest         — Pydantic model
+    RegisterRequest      — Pydantic model
+    TokenResponse        — Pydantic model
+    AuthPrincipal        — resolved identity (jwt or api_key)
+    Scopes               — well-known scope string constants
+
+Utilities:
+    parse_user_id        — parse str/UUID/None → UUID | None
+    require_user_id      — parse, raise ValueError on failure
+    parse_user_ids       — batch parse, skip failures
+
+Config:
+    AuthSettings         — pydantic-settings for SECRET_KEY, ALGORITHM, expiry
+"""
+from .config import AuthSettings
+from .jwt import InvalidTokenError, KeyRing, create_access_token, decode_access_token
+from .keys import generate_key, hash_key
+from .password import hash_password, verify_password
+from .schemas import AuthPrincipal, LoginRequest, RegisterRequest, Scopes, TokenResponse
+from .user_ids import parse_user_id, parse_user_ids, require_user_id
+
+__all__ = [
+    # Config
+    "AuthSettings",
+    # JWT
+    "InvalidTokenError",
+    "KeyRing",
+    "create_access_token",
+    "decode_access_token",
+    # Keys
+    "generate_key",
+    "hash_key",
+    # Password
+    "hash_password",
+    "verify_password",
+    # Schemas
+    "AuthPrincipal",
+    "LoginRequest",
+    "RegisterRequest",
+    "Scopes",
+    "TokenResponse",
+    # User IDs
+    "parse_user_id",
+    "parse_user_ids",
+    "require_user_id",
+]

nodus_auth-0.1.0/nodus_auth/config.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings
+
+
+class AuthSettings(BaseSettings):
+    """Minimal auth configuration.  Reads from environment variables by default."""
+
+    SECRET_KEY: str = "dev-secret-change-in-production"
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24  # 24 hours
+
+    model_config = {"env_prefix": "", "extra": "ignore"}

nodus_auth-0.1.0/nodus_auth/jwt.py

@@ -0,0 +1,133 @@
+"""JWT token creation, decoding, and key rotation."""
+from __future__ import annotations
+
+import os
+import threading
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from jose import JWTError, jwt as _jwt
+
+from .config import AuthSettings
+
+
+class InvalidTokenError(Exception):
+    """Raised when a JWT cannot be decoded, is expired, or fails verification."""
+
+
+class KeyRing:
+    """Two-slot JWT signing key ring supporting zero-downtime rotation.
+
+    Signing always uses the active key.  Verification tries active first, then
+    previous (within the grace window) so tokens issued with the old key remain
+    valid while clients refresh.
+    """
+
+    def __init__(
+        self,
+        active: str,
+        previous: Optional[str] = None,
+        grace_hours: int = 24,
+    ) -> None:
+        self._lock = threading.RLock()
+        self._active = active
+        self._previous = previous
+        self._previous_expires: Optional[datetime] = None
+        self._grace_hours = grace_hours
+        if previous:
+            self._previous_expires = datetime.now(timezone.utc) + timedelta(
+                hours=grace_hours
+            )
+
+    @property
+    def active_key(self) -> str:
+        with self._lock:
+            return self._active
+
+    def rotate(self, new_key: str) -> None:
+        """Promote active → previous (with expiry), set *new_key* as active."""
+        with self._lock:
+            if new_key == self._active:
+                return
+            self._previous = self._active
+            self._previous_expires = datetime.now(timezone.utc) + timedelta(
+                hours=self._grace_hours
+            )
+            self._active = new_key
+
+    def verify_keys(self) -> list[str]:
+        """Return keys to try for verification, most recent first."""
+        with self._lock:
+            keys = [self._active]
+            if self._previous and self._previous_expires:
+                if datetime.now(timezone.utc) < self._previous_expires:
+                    keys.append(self._previous)
+                else:
+                    self._previous = None
+                    self._previous_expires = None
+            return keys
+
+    def reload_from_env(self) -> bool:
+        """Reload active key from SECRET_KEY env var. Returns True if key changed."""
+        new_key = os.getenv("SECRET_KEY", "")
+        if not new_key or new_key == self._active:
+            return False
+        self.rotate(new_key)
+        return True
+
+
+def create_access_token(
+    data: dict,
+    *,
+    settings: Optional[AuthSettings] = None,
+    key_ring: Optional[KeyRing] = None,
+    expires_delta: Optional[timedelta] = None,
+    token_version: int = 0,
+) -> str:
+    """Encode a JWT access token.
+
+    Args:
+        data: Claims to encode (e.g. ``{"sub": user_id}``).
+        settings: Auth settings; defaults to ``AuthSettings()`` (reads env vars).
+        key_ring: Optional pre-configured KeyRing.  When provided, the active
+            key from the ring is used instead of ``settings.SECRET_KEY``.
+        expires_delta: Token lifetime.  Defaults to
+            ``settings.ACCESS_TOKEN_EXPIRE_MINUTES``.
+        token_version: Stamped as ``"tv"`` claim for token invalidation.
+    """
+    cfg = settings or AuthSettings()
+    signing_key = key_ring.active_key if key_ring is not None else cfg.SECRET_KEY
+    to_encode = dict(data)
+    to_encode["tv"] = token_version
+    expire = datetime.now(timezone.utc) + (
+        expires_delta or timedelta(minutes=cfg.ACCESS_TOKEN_EXPIRE_MINUTES)
+    )
+    to_encode["exp"] = expire
+    return _jwt.encode(to_encode, signing_key, algorithm=cfg.ALGORITHM)
+
+
+def decode_access_token(
+    token: str,
+    *,
+    settings: Optional[AuthSettings] = None,
+    key_ring: Optional[KeyRing] = None,
+) -> dict:
+    """Decode and verify a JWT access token.
+
+    When a ``KeyRing`` is provided, all keys in the ring are tried in order
+    (active first, then previous within its grace window).  This allows tokens
+    signed with a recently-rotated key to remain valid during the grace period.
+
+    Raises:
+        InvalidTokenError: If the token is malformed, expired, or cannot be
+            verified by any available key.
+    """
+    cfg = settings or AuthSettings()
+    keys = key_ring.verify_keys() if key_ring is not None else [cfg.SECRET_KEY]
+    last_exc: Optional[Exception] = None
+    for key in keys:
+        try:
+            return _jwt.decode(token, key, algorithms=[cfg.ALGORITHM])
+        except JWTError as exc:
+            last_exc = exc
+    raise InvalidTokenError("Invalid or expired token") from last_exc

nodus_auth-0.1.0/nodus_auth/keys.py

@@ -0,0 +1,25 @@
+"""Platform API key generation and hashing."""
+from __future__ import annotations
+
+import hashlib
+import secrets
+
+_KEY_PREFIX = "nodus_"
+_KEY_TOKEN_BYTES = 32  # 32 bytes → 43-char url-safe base64
+
+
+def hash_key(raw_key: str) -> str:
+    """Return the SHA-256 hex digest of *raw_key*."""
+    return hashlib.sha256(raw_key.encode()).hexdigest()
+
+
+def generate_key(*, prefix: str = _KEY_PREFIX) -> tuple[str, str]:
+    """Generate a new platform API key.
+
+    Returns ``(raw_key, key_hash)``.  *raw_key* is the plaintext key to
+    deliver to the caller — it is never stored.  *key_hash* is the SHA-256
+    hex digest to store in the database.
+    """
+    token = secrets.token_urlsafe(_KEY_TOKEN_BYTES)
+    raw_key = f"{prefix}{token}"
+    return raw_key, hash_key(raw_key)

nodus_auth-0.1.0/nodus_auth/password.py

@@ -0,0 +1,16 @@
+"""Password hashing and verification using bcrypt via passlib."""
+from __future__ import annotations
+
+from passlib.context import CryptContext
+
+_pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+def hash_password(password: str) -> str:
+    """Return a bcrypt hash of *password*."""
+    return _pwd_context.hash(password)
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    """Return True if *plain* matches the bcrypt *hashed* value."""
+    return _pwd_context.verify(plain, hashed)

nodus_auth-0.1.0/nodus_auth/schemas.py

@@ -0,0 +1,72 @@
+"""Auth request/response schemas and principal types."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from pydantic import BaseModel
+
+
+# ── Pydantic request/response models ─────────────────────────────────────────
+
+class LoginRequest(BaseModel):
+    email: str
+    password: str
+
+
+class RegisterRequest(BaseModel):
+    email: str
+    password: str
+    username: str | None = None
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+
+
+# ── Scope constants ───────────────────────────────────────────────────────────
+
+class Scopes:
+    """Well-known platform scope strings."""
+
+    FLOW_READ       = "flow.read"
+    FLOW_EXECUTE    = "flow.execute"
+    MEMORY_READ     = "memory.read"
+    MEMORY_WRITE    = "memory.write"
+    AGENT_RUN       = "agent.run"
+    WEBHOOK_MANAGE  = "webhook.manage"
+    PLATFORM_ADMIN  = "platform.admin"
+
+    ALL: list[str] = [
+        FLOW_READ,
+        FLOW_EXECUTE,
+        MEMORY_READ,
+        MEMORY_WRITE,
+        AGENT_RUN,
+        WEBHOOK_MANAGE,
+        PLATFORM_ADMIN,
+    ]
+
+
+# ── Principal dataclass ───────────────────────────────────────────────────────
+
+@dataclass
+class AuthPrincipal:
+    """Resolved authentication identity.
+
+    ``auth_type="jwt"``    — JWT Bearer token; ``has_scope`` always returns True.
+    ``auth_type="api_key"`` — Platform API key; scope-restricted.
+    """
+
+    user_id: str
+    auth_type: str          # "jwt" | "api_key"
+    scopes: list[str] = field(default_factory=list)
+    key_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def has_scope(self, scope: str) -> bool:
+        """Return True if this principal holds *scope*."""
+        if self.auth_type == "jwt":
+            return True   # JWT users carry full trust
+        return scope in self.scopes or Scopes.PLATFORM_ADMIN in self.scopes

nodus_auth-0.1.0/nodus_auth/user_ids.py

@@ -0,0 +1,35 @@
+"""UUID user ID parsing utilities."""
+from __future__ import annotations
+
+import uuid
+from typing import Iterable
+
+
+def parse_user_id(value: str | uuid.UUID | None) -> uuid.UUID | None:
+    """Parse *value* into a UUID, returning None on failure."""
+    if value is None or value == "":
+        return None
+    if isinstance(value, uuid.UUID):
+        return value
+    try:
+        return uuid.UUID(str(value))
+    except (TypeError, ValueError, AttributeError):
+        return None
+
+
+def require_user_id(value: str | uuid.UUID | None) -> uuid.UUID:
+    """Parse *value* into a UUID. Raises ``ValueError`` if parsing fails."""
+    parsed = parse_user_id(value)
+    if parsed is None:
+        raise ValueError("user_id is required")
+    return parsed
+
+
+def parse_user_ids(values: Iterable[str | uuid.UUID | None]) -> list[uuid.UUID]:
+    """Parse an iterable of values, silently skipping unparseable entries."""
+    parsed: list[uuid.UUID] = []
+    for value in values:
+        user_id = parse_user_id(value)
+        if user_id is not None:
+            parsed.append(user_id)
+    return parsed

nodus_auth-0.1.0/nodus_auth.egg-info/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: nodus-auth
+Version: 0.1.0
+Summary: JWT, API key auth, bcrypt hashing, and scoped principals for AI-native platforms
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-auth
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-auth
+Keywords: auth,jwt,api-key,bcrypt,nodus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-jose>=3.5.0
+Requires-Dist: passlib>=1.7.4
+Requires-Dist: bcrypt<5.0,>=4.0.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Dynamic: license-file
+
+# nodus-auth
+
+**JWT issuance/validation, API key hashing, bcrypt passwords, and scoped
+principals for AI-native platforms.**
+
+Standalone auth primitives — no FastAPI required. All core functions work
+with any Python web framework or no framework at all.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-auth
+```
+
+> **bcrypt version note:** This package pins `bcrypt>=4.0.1,<5.0` because
+> `passlib 1.7.4` is incompatible with bcrypt 5.x. Do not upgrade bcrypt
+> beyond 4.x in the same environment.
+
+---
+
+## What it provides
+
+| Component | Purpose |
+|---|---|
+| `KeyRing` / `create_access_token` / `decode_access_token` | JWT issuance and verification with key rotation |
+| `hash_password` / `verify_password` | bcrypt password hashing via passlib |
+| `generate_key` / `hash_key` | API key generation and SHA-256 storage hash |
+| `AuthPrincipal` / `Scopes` | Resolved identity with scope-based access control |
+| `LoginRequest` / `RegisterRequest` / `TokenResponse` | Pydantic request/response schemas |
+| `parse_user_id` / `require_user_id` | UUID parsing helpers |
+| `AuthSettings` | pydantic-settings config for SECRET_KEY, ALGORITHM, expiry |
+
+---
+
+## JWT tokens
+
+```python
+from nodus_auth import AuthSettings, create_access_token, decode_access_token, InvalidTokenError
+
+settings = AuthSettings(SECRET_KEY="my-secret-key-32-chars-minimum")
+token = create_access_token({"sub": "user-123"}, settings=settings)
+
+try:
+    payload = decode_access_token(token, settings=settings)
+    user_id = payload["sub"]
+except InvalidTokenError:
+    # expired, malformed, or wrong key
+    ...
+```
+
+### Key rotation
+
+```python
+from nodus_auth import KeyRing, create_access_token, decode_access_token, AuthSettings
+
+ring = KeyRing(active="key-v1", grace_hours=24)
+settings = AuthSettings(SECRET_KEY="key-v1")
+token = create_access_token({"sub": "u1"}, settings=settings, key_ring=ring)
+
+ring.rotate("key-v2")  # tokens signed with key-v1 still verify for 24 hours
+payload = decode_access_token(token, settings=settings, key_ring=ring)  # OK
+```
+
+`decode_access_token` tries the active key first, then any keys within their
+grace period. Tokens outside their grace window raise `InvalidTokenError`.
+
+---
+
+## Passwords
+
+```python
+from nodus_auth import hash_password, verify_password
+
+hashed = hash_password("correct-horse-battery-staple")
+assert verify_password("correct-horse-battery-staple", hashed)
+assert not verify_password("wrong-password", hashed)
+```
+
+---
+
+## API keys
+
+```python
+from nodus_auth import generate_key, hash_key
+
+raw_key, key_hash = generate_key()
+# Deliver raw_key to the caller once; store key_hash in the database
+assert hash_key(raw_key) == key_hash
+```
+
+`generate_key()` uses `secrets.token_urlsafe`. The raw key is never stored;
+the SHA-256 hash is used for all comparisons.
+
+---
+
+## Scoped principals
+
+```python
+from nodus_auth import AuthPrincipal, Scopes
+
+principal = AuthPrincipal(
+    user_id="user-123",
+    auth_type="api_key",
+    scopes=[Scopes.MEMORY_READ, Scopes.FLOW_EXECUTE],
+)
+assert principal.has_scope(Scopes.FLOW_EXECUTE)
+assert not principal.has_scope(Scopes.PLATFORM_ADMIN)
+```
+
+`auth_type` is `"jwt"` or `"api_key"`. `Scopes` provides well-known constants:
+`MEMORY_READ`, `MEMORY_WRITE`, `FLOW_EXECUTE`, `FLOW_CREATE`, `PLATFORM_ADMIN`.
+
+---
+
+## AuthSettings
+
+```python
+from nodus_auth import AuthSettings
+
+# Reads from environment variables: SECRET_KEY, ALGORITHM, ACCESS_TOKEN_EXPIRE_MINUTES
+settings = AuthSettings()
+
+# Or explicit:
+settings = AuthSettings(
+    SECRET_KEY="...",
+    ALGORITHM="HS256",
+    ACCESS_TOKEN_EXPIRE_MINUTES=60,
+)
+```
+
+---
+
+## User ID helpers
+
+```python
+from nodus_auth import parse_user_id, require_user_id, parse_user_ids
+import uuid
+
+parse_user_id("550e8400-e29b-41d4-a716-446655440000")  # → UUID
+parse_user_id(None)                                     # → None
+require_user_id("not-a-uuid")                           # raises ValueError
+parse_user_ids(["uid-1", "bad", "uid-2"])              # → [UUID, UUID]  (skips failures)
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `python-jose` | ≥3.5.0 | JWT encoding/decoding |
+| `passlib` | ≥1.7.4 | bcrypt password context |
+| `bcrypt` | ≥4.0.1,<5.0 | bcrypt backend (passlib 1.7.4 incompatible with 5.x) |
+| `pydantic` | ≥2.0.0 | Schemas |
+| `pydantic-settings` | ≥2.0.0 | `AuthSettings` from env vars |
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nodus_auth-0.1.0/nodus_auth.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+nodus_auth/__init__.py
+nodus_auth/config.py
+nodus_auth/jwt.py
+nodus_auth/keys.py
+nodus_auth/password.py
+nodus_auth/schemas.py
+nodus_auth/user_ids.py
+nodus_auth.egg-info/PKG-INFO
+nodus_auth.egg-info/SOURCES.txt
+nodus_auth.egg-info/dependency_links.txt
+nodus_auth.egg-info/requires.txt
+nodus_auth.egg-info/top_level.txt
+tests/test_jwt.py
+tests/test_keys.py
+tests/test_password.py
+tests/test_schemas.py

nodus_auth-0.1.0/nodus_auth.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nodus_auth-0.1.0/nodus_auth.egg-info/requires.txt

@@ -0,0 +1,9 @@
+python-jose>=3.5.0
+passlib>=1.7.4
+bcrypt<5.0,>=4.0.1
+pydantic>=2.0.0
+pydantic-settings>=2.0.0
+
+[dev]
+pytest>=8.0
+pytest-mock>=3.0

nodus_auth-0.1.0/nodus_auth.egg-info/top_level.txt

@@ -0,0 +1 @@
+nodus_auth

nodus_auth-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nodus-auth"
+version = "0.1.0"
+description = "JWT, API key auth, bcrypt hashing, and scoped principals for AI-native platforms"
+authors = [{ name = "Shawn Knight" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["auth", "jwt", "api-key", "bcrypt", "nodus"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "python-jose>=3.5.0",
+  "passlib>=1.7.4",
+  "bcrypt>=4.0.1,<5.0",
+  "pydantic>=2.0.0",
+  "pydantic-settings>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-mock>=3.0"]
+
+[project.urls]
+Homepage = "https://github.com/Masterplanner25/nodus-auth"
+Repository = "https://github.com/Masterplanner25/nodus-auth"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nodus_auth*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nodus_auth-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nodus_auth-0.1.0/tests/test_jwt.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import time
+from datetime import timedelta
+
+import pytest
+
+from nodus_auth import (
+    AuthSettings,
+    InvalidTokenError,
+    KeyRing,
+    create_access_token,
+    decode_access_token,
+)
+
+
+@pytest.fixture
+def settings():
+    return AuthSettings(SECRET_KEY="test-secret-key")
+
+
+# ── create / decode round-trip ────────────────────────────────────────────────
+
+def test_round_trip(settings):
+    token = create_access_token({"sub": "user-1"}, settings=settings)
+    payload = decode_access_token(token, settings=settings)
+    assert payload["sub"] == "user-1"
+
+
+def test_token_version_in_claims(settings):
+    token = create_access_token({"sub": "u1"}, settings=settings, token_version=7)
+    payload = decode_access_token(token, settings=settings)
+    assert payload["tv"] == 7
+
+
+def test_expired_token_raises(settings):
+    token = create_access_token(
+        {"sub": "u1"}, settings=settings, expires_delta=timedelta(seconds=-1)
+    )
+    with pytest.raises(InvalidTokenError):
+        decode_access_token(token, settings=settings)
+
+
+def test_wrong_key_raises(settings):
+    token = create_access_token({"sub": "u1"}, settings=settings)
+    wrong = AuthSettings(SECRET_KEY="completely-different-key")
+    with pytest.raises(InvalidTokenError):
+        decode_access_token(token, settings=wrong)
+
+
+def test_malformed_token_raises(settings):
+    with pytest.raises(InvalidTokenError):
+        decode_access_token("not.a.jwt", settings=settings)
+
+
+# ── KeyRing rotation ──────────────────────────────────────────────────────────
+
+def test_key_ring_round_trip(settings):
+    ring = KeyRing(active=settings.SECRET_KEY)
+    token = create_access_token({"sub": "u1"}, settings=settings, key_ring=ring)
+    payload = decode_access_token(token, settings=settings, key_ring=ring)
+    assert payload["sub"] == "u1"
+
+
+def test_key_ring_grace_period(settings):
+    ring = KeyRing(active=settings.SECRET_KEY, grace_hours=1)
+    # Mint token with old key
+    token = create_access_token({"sub": "u1"}, settings=settings, key_ring=ring)
+    # Rotate to new key
+    ring.rotate("new-secret-key")
+    # Token signed with old key still verifiable during grace period
+    payload = decode_access_token(token, settings=settings, key_ring=ring)
+    assert payload["sub"] == "u1"
+
+
+def test_key_ring_expired_previous_key_rejected():
+    ring = KeyRing(active="key-A", grace_hours=0)
+    cfg = AuthSettings(SECRET_KEY="key-A")
+    token = create_access_token({"sub": "u1"}, settings=cfg, key_ring=ring)
+    ring.rotate("key-B")
+    # grace_hours=0 means previous expires immediately; wait for it
+    time.sleep(0.01)
+    cfg_b = AuthSettings(SECRET_KEY="key-B")
+    with pytest.raises(InvalidTokenError):
+        decode_access_token(token, settings=cfg_b, key_ring=ring)
+
+
+def test_key_ring_active_key_property(settings):
+    ring = KeyRing(active=settings.SECRET_KEY)
+    assert ring.active_key == settings.SECRET_KEY
+    ring.rotate("new-key")
+    assert ring.active_key == "new-key"
+
+
+def test_key_ring_rotate_noop_on_same_key(settings):
+    ring = KeyRing(active=settings.SECRET_KEY)
+    ring.rotate(settings.SECRET_KEY)
+    assert ring.active_key == settings.SECRET_KEY
+    assert ring._previous is None

nodus_auth-0.1.0/tests/test_keys.py

@@ -0,0 +1,42 @@
+from nodus_auth import generate_key, hash_key
+
+
+def test_hash_key_is_deterministic():
+    assert hash_key("abc") == hash_key("abc")
+
+
+def test_hash_key_differs_for_different_inputs():
+    assert hash_key("abc") != hash_key("xyz")
+
+
+def test_hash_key_is_hex_64_chars():
+    h = hash_key("test")
+    assert len(h) == 64
+    int(h, 16)  # must be valid hex
+
+
+def test_generate_key_returns_tuple():
+    raw, hashed = generate_key()
+    assert isinstance(raw, str)
+    assert isinstance(hashed, str)
+
+
+def test_generate_key_hash_matches_raw():
+    raw, hashed = generate_key()
+    assert hash_key(raw) == hashed
+
+
+def test_generate_key_default_prefix():
+    raw, _ = generate_key()
+    assert raw.startswith("nodus_")
+
+
+def test_generate_key_custom_prefix():
+    raw, _ = generate_key(prefix="myapp_")
+    assert raw.startswith("myapp_")
+
+
+def test_generate_key_unique():
+    raw1, _ = generate_key()
+    raw2, _ = generate_key()
+    assert raw1 != raw2

nodus_auth-0.1.0/tests/test_password.py

@@ -0,0 +1,26 @@
+from nodus_auth import hash_password, verify_password
+
+
+def test_hash_is_not_plaintext():
+    h = hash_password("secret")
+    assert h != "secret"
+    assert h.startswith("$2b$")
+
+
+def test_verify_correct_password():
+    h = hash_password("correct-horse")
+    assert verify_password("correct-horse", h) is True
+
+
+def test_verify_wrong_password():
+    h = hash_password("correct-horse")
+    assert verify_password("wrong-horse", h) is False
+
+
+def test_different_hashes_for_same_password():
+    h1 = hash_password("same")
+    h2 = hash_password("same")
+    # bcrypt uses a random salt
+    assert h1 != h2
+    assert verify_password("same", h1) is True
+    assert verify_password("same", h2) is True

nodus_auth-0.1.0/tests/test_schemas.py

@@ -0,0 +1,94 @@
+import uuid
+
+import pytest
+
+from nodus_auth import (
+    AuthPrincipal,
+    LoginRequest,
+    RegisterRequest,
+    Scopes,
+    TokenResponse,
+    parse_user_id,
+    parse_user_ids,
+    require_user_id,
+)
+
+
+# ── Pydantic schemas ──────────────────────────────────────────────────────────
+
+def test_login_request():
+    req = LoginRequest(email="a@b.com", password="pw")
+    assert req.email == "a@b.com"
+
+
+def test_register_request_optional_username():
+    req = RegisterRequest(email="a@b.com", password="pw")
+    assert req.username is None
+
+
+def test_token_response_default_type():
+    r = TokenResponse(access_token="tok")
+    assert r.token_type == "bearer"
+
+
+# ── Scopes ────────────────────────────────────────────────────────────────────
+
+def test_scopes_all_contains_all_constants():
+    assert Scopes.PLATFORM_ADMIN in Scopes.ALL
+    assert Scopes.FLOW_EXECUTE in Scopes.ALL
+    assert len(Scopes.ALL) == 7
+
+
+# ── AuthPrincipal ─────────────────────────────────────────────────────────────
+
+def test_jwt_principal_has_all_scopes():
+    p = AuthPrincipal(user_id="u1", auth_type="jwt")
+    assert p.has_scope(Scopes.FLOW_READ) is True
+    assert p.has_scope("anything") is True
+
+
+def test_api_key_principal_scope_check():
+    p = AuthPrincipal(user_id="u1", auth_type="api_key", scopes=[Scopes.MEMORY_READ])
+    assert p.has_scope(Scopes.MEMORY_READ) is True
+    assert p.has_scope(Scopes.FLOW_EXECUTE) is False
+
+
+def test_api_key_with_platform_admin_has_all_scopes():
+    p = AuthPrincipal(user_id="u1", auth_type="api_key", scopes=[Scopes.PLATFORM_ADMIN])
+    assert p.has_scope(Scopes.FLOW_EXECUTE) is True
+    assert p.has_scope(Scopes.MEMORY_WRITE) is True
+
+
+# ── user_ids ──────────────────────────────────────────────────────────────────
+
+def test_parse_user_id_from_string():
+    uid = uuid.uuid4()
+    assert parse_user_id(str(uid)) == uid
+
+
+def test_parse_user_id_from_uuid():
+    uid = uuid.uuid4()
+    assert parse_user_id(uid) is uid
+
+
+def test_parse_user_id_none():
+    assert parse_user_id(None) is None
+
+
+def test_parse_user_id_empty():
+    assert parse_user_id("") is None
+
+
+def test_parse_user_id_invalid():
+    assert parse_user_id("not-a-uuid") is None
+
+
+def test_require_user_id_raises_on_invalid():
+    with pytest.raises(ValueError):
+        require_user_id("bad")
+
+
+def test_parse_user_ids_skips_invalid():
+    uid = uuid.uuid4()
+    result = parse_user_ids([str(uid), "bad", None, uid])
+    assert result == [uid, uid]