splent-feature-apikeys 0.1.1__tar.gz

splent_feature_apikeys-0.1.1/MANIFEST.in

@@ -0,0 +1,8 @@
+# Jinja templates (feature views + hook fragments)
+recursive-include src/splent_io/splent_feature_apikeys/templates *.html
+
+# Alembic migration config and scripts
+recursive-include src/splent_io/splent_feature_apikeys/migrations *.py *.ini *.mako
+
+# Compiled translation catalogs
+recursive-include src/splent_io/splent_feature_apikeys/translations *.mo *.po

splent_feature_apikeys-0.1.1/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: splent_feature_apikeys
+Version: 0.1.1
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# splent_feature_apikeys
+
+Developer API tokens for a SPLENT product. A port of the UVLHub `apikeys`
+feature to SPLENT conventions, and the only place in a product where a
+password is exchanged for a credential a machine can carry.
+
+It owns tokens and nothing else. It does not know what the tokens are used
+for, and it never touches the `auth` feature: credentials are checked through
+the `AuthenticationService` that auth already registers.
+
+## The model
+
+`ApiToken` belongs to one user and keeps:
+
+| Column         | Meaning                                                    |
+|----------------|------------------------------------------------------------|
+| `user_id`      | Owner, foreign key to auth's `user.id`                     |
+| `name`         | Human label chosen by the owner                            |
+| `token_hash`   | sha256 of the plaintext, hex. The plaintext is never stored |
+| `prefix`       | First 15 characters of the plaintext, indexed, safe to show |
+| `scopes`       | Comma separated, as in UVLHub                              |
+| `created_at`, `expires_at`, `revoked_at`, `last_used_at` | lifecycle |
+
+A plaintext token looks like `splent_<64 hex characters>`. The `splent_`
+label makes a leaked token greppable; the prefix makes verification a single
+indexed lookup instead of a table scan.
+
+## Scopes
+
+`read_spl` and `write_spl`. Unknown names are dropped, and a request that
+asks for nothing but unknown names is refused rather than silently producing
+a token that can do nothing.
+
+## The service
+
+`ApiTokenService`, registered under that name in the service locator.
+
+```python
+api_token_service = service_proxy("ApiTokenService")
+
+row, plaintext = api_token_service.mint(user, "laptop", ["write_spl"], ttl_days=90)
+api_token_service.verify(plaintext)       # row, or None if unknown/revoked/expired
+api_token_service.find(plaintext)         # row whatever its state, to explain a refusal
+api_token_service.revoke(row.id, user)    # only the owner can revoke
+api_token_service.touch(row)              # last_used_at, at most once every 5 minutes
+api_token_service.authenticate(email, password)  # (user, None) or (None, reason)
+```
+
+`mint` returns the plaintext once. Nothing else in the product can ever
+produce it again.
+
+## Guarding a route
+
+```python
+from splent_io.splent_feature_apikeys.decorators import require_token
+
+@some_bp.route("/api/v1/spls", methods=["POST"])
+@require_token("write_spl")
+def publish():
+    g.api_user   # the owner
+    g.api_token  # the presenting token
+```
+
+`require_token()` with no scope accepts any usable token. For routes where a
+token is one of several ways in, call `resolve_token(scope)` directly: it
+returns `(api_token, None)` or `(None, (response, status))`.
+
+## Endpoints
+
+| Method | Path                            | Auth              |
+|--------|---------------------------------|-------------------|
+| POST   | `/api/v1/auth/tokens`           | email + password  |
+| GET    | `/api/v1/auth/whoami`           | Bearer token      |
+| DELETE | `/api/v1/auth/tokens/current`   | Bearer token      |
+
+```bash
+curl -X POST https://<product>/api/v1/auth/tokens \
+     -H "Content-Type: application/json" \
+     -d '{"email": "dev@example.com", "password": "...", "name": "laptop"}'
+
+curl https://<product>/api/v1/auth/whoami \
+     -H "Authorization: Bearer splent_..."
+```
+
+Omitting `ttl_days` gives the product default; sending it as `null` gives a
+token that never expires.
+
+Failed credential attempts are throttled per caller and account. Users are
+created inactive and an administrator activates them, so an account still
+waiting is answered with `403` and a message that says exactly that, never
+with "wrong password".
+
+## Pages
+
+- `/developer/tokens` — the owner's tokens, by prefix, with a revoke button.
+- `/developer/tokens/new` — create one; the plaintext is shown once.
+
+A link appears in the authenticated sidebar
+(`layout.authenticated_sidebar` hook).
+
+## Configuration
+
+| Variable                       | Default | Meaning                          |
+|--------------------------------|---------|----------------------------------|
+| `APIKEYS_DEFAULT_TTL_DAYS`     | 90      | Life of a token when none is asked |
+| `APIKEYS_MAX_LOGIN_ATTEMPTS`   | 5       | Failed attempts per window       |
+| `APIKEYS_LOGIN_WINDOW_SECONDS` | 300     | Length of that window            |
+
+All three have working defaults, so the feature needs no `.env` entry.
+
+## Install
+
+```bash
+splent feature:install splent-io/splent_feature_apikeys
+splent db:migrate splent_feature_apikeys
+splent db:upgrade
+```
+
+## Tests
+
+```bash
+splent feature:test splent_feature_apikeys
+```

splent_feature_apikeys-0.1.1/README.md

@@ -0,0 +1,123 @@
+# splent_feature_apikeys
+
+Developer API tokens for a SPLENT product. A port of the UVLHub `apikeys`
+feature to SPLENT conventions, and the only place in a product where a
+password is exchanged for a credential a machine can carry.
+
+It owns tokens and nothing else. It does not know what the tokens are used
+for, and it never touches the `auth` feature: credentials are checked through
+the `AuthenticationService` that auth already registers.
+
+## The model
+
+`ApiToken` belongs to one user and keeps:
+
+| Column         | Meaning                                                    |
+|----------------|------------------------------------------------------------|
+| `user_id`      | Owner, foreign key to auth's `user.id`                     |
+| `name`         | Human label chosen by the owner                            |
+| `token_hash`   | sha256 of the plaintext, hex. The plaintext is never stored |
+| `prefix`       | First 15 characters of the plaintext, indexed, safe to show |
+| `scopes`       | Comma separated, as in UVLHub                              |
+| `created_at`, `expires_at`, `revoked_at`, `last_used_at` | lifecycle |
+
+A plaintext token looks like `splent_<64 hex characters>`. The `splent_`
+label makes a leaked token greppable; the prefix makes verification a single
+indexed lookup instead of a table scan.
+
+## Scopes
+
+`read_spl` and `write_spl`. Unknown names are dropped, and a request that
+asks for nothing but unknown names is refused rather than silently producing
+a token that can do nothing.
+
+## The service
+
+`ApiTokenService`, registered under that name in the service locator.
+
+```python
+api_token_service = service_proxy("ApiTokenService")
+
+row, plaintext = api_token_service.mint(user, "laptop", ["write_spl"], ttl_days=90)
+api_token_service.verify(plaintext)       # row, or None if unknown/revoked/expired
+api_token_service.find(plaintext)         # row whatever its state, to explain a refusal
+api_token_service.revoke(row.id, user)    # only the owner can revoke
+api_token_service.touch(row)              # last_used_at, at most once every 5 minutes
+api_token_service.authenticate(email, password)  # (user, None) or (None, reason)
+```
+
+`mint` returns the plaintext once. Nothing else in the product can ever
+produce it again.
+
+## Guarding a route
+
+```python
+from splent_io.splent_feature_apikeys.decorators import require_token
+
+@some_bp.route("/api/v1/spls", methods=["POST"])
+@require_token("write_spl")
+def publish():
+    g.api_user   # the owner
+    g.api_token  # the presenting token
+```
+
+`require_token()` with no scope accepts any usable token. For routes where a
+token is one of several ways in, call `resolve_token(scope)` directly: it
+returns `(api_token, None)` or `(None, (response, status))`.
+
+## Endpoints
+
+| Method | Path                            | Auth              |
+|--------|---------------------------------|-------------------|
+| POST   | `/api/v1/auth/tokens`           | email + password  |
+| GET    | `/api/v1/auth/whoami`           | Bearer token      |
+| DELETE | `/api/v1/auth/tokens/current`   | Bearer token      |
+
+```bash
+curl -X POST https://<product>/api/v1/auth/tokens \
+     -H "Content-Type: application/json" \
+     -d '{"email": "dev@example.com", "password": "...", "name": "laptop"}'
+
+curl https://<product>/api/v1/auth/whoami \
+     -H "Authorization: Bearer splent_..."
+```
+
+Omitting `ttl_days` gives the product default; sending it as `null` gives a
+token that never expires.
+
+Failed credential attempts are throttled per caller and account. Users are
+created inactive and an administrator activates them, so an account still
+waiting is answered with `403` and a message that says exactly that, never
+with "wrong password".
+
+## Pages
+
+- `/developer/tokens` — the owner's tokens, by prefix, with a revoke button.
+- `/developer/tokens/new` — create one; the plaintext is shown once.
+
+A link appears in the authenticated sidebar
+(`layout.authenticated_sidebar` hook).
+
+## Configuration
+
+| Variable                       | Default | Meaning                          |
+|--------------------------------|---------|----------------------------------|
+| `APIKEYS_DEFAULT_TTL_DAYS`     | 90      | Life of a token when none is asked |
+| `APIKEYS_MAX_LOGIN_ATTEMPTS`   | 5       | Failed attempts per window       |
+| `APIKEYS_LOGIN_WINDOW_SECONDS` | 300     | Length of that window            |
+
+All three have working defaults, so the feature needs no `.env` entry.
+
+## Install
+
+```bash
+splent feature:install splent-io/splent_feature_apikeys
+splent db:migrate splent_feature_apikeys
+splent db:upgrade
+```
+
+## Tests
+
+```bash
+splent feature:test splent_feature_apikeys
+```

splent_feature_apikeys-0.1.1/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=80.3.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "splent_feature_apikeys"
+version = "0.1.1"
+readme = "README.md"
+requires-python = ">=3.13"
+
+dependencies = [
+
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["*.tests", "*.tests.*"]
+
+[tool.splent]
+cli_version = "1.14.0"
+
+# ── Feature Contract (auto-generated) ────────────────────────────────────────
+# Do not edit manually — re-run `splent feature:contract --write` to refresh.
+# Preserved across refreshes: description, category, tags, env, and
+# requires.features_manual (dependencies invisible to static analysis).
+[tool.splent.contract]
+description = "Developer API tokens: mint, verify, revoke, and a Bearer decorator for the product's own API"
+archetype = "full"
+category = "security"
+tags = ["api", "tokens", "authentication", "developer"]
+
+[tool.splent.contract.provides]
+routes     = ["/api/v1/auth/tokens", "/api/v1/auth/tokens/current", "/api/v1/auth/whoami", "/developer/tokens", "/developer/tokens/<int:token_id>/revoke", "/developer/tokens/new"]
+blueprints = []
+models     = ["ApiToken"]
+commands   = []
+hooks      = ["layout.authenticated_sidebar"]
+services   = ["ApiTokenService"]
+signals    = []
+translations = []
+docker     = []
+
+[tool.splent.contract.requires]
+features = ["auth"]
+env_vars = ["APIKEYS_DEFAULT_TTL_DAYS", "APIKEYS_LOGIN_WINDOW_SECONDS", "APIKEYS_MAX_ACCOUNT_ATTEMPTS", "APIKEYS_MAX_BODY_BYTES", "APIKEYS_MAX_LOGIN_ATTEMPTS", "APIKEYS_THROTTLE_MAX_KEYS"]
+signals  = []
+
+[tool.splent.contract.extensible]
+services  = ["ApiTokenService"]
+templates = ["apikeys/created.html", "apikeys/index.html", "apikeys/new.html", "hooks/sidebar_tokens.html"]
+models    = ["ApiToken"]
+hooks     = ["layout.authenticated_sidebar"]
+routes    = false
+
+# ── Configuration ─────────────────────────────────────────────────────────
+# What this feature reads from the environment, and what it falls back to.
+[tool.splent.config]
+# How long a key issued without an explicit expiry is good for.
+APIKEYS_DEFAULT_TTL_DAYS = 90
+# Rate limiting on the exchange endpoint, which takes a password. The window
+# is per address, the account limit per account, so one address hammering
+# many accounts and many addresses hammering one are both bounded.
+APIKEYS_MAX_LOGIN_ATTEMPTS = 5
+APIKEYS_LOGIN_WINDOW_SECONDS = 300
+APIKEYS_MAX_ACCOUNT_ATTEMPTS = 20
+# The throttle keeps its counters in memory. This caps how many it holds, so
+# a flood of distinct addresses cannot grow it without bound.
+APIKEYS_THROTTLE_MAX_KEYS = 10000
+# Largest body accepted on the token endpoints. They take a short JSON
+# object, and anything larger is not a client that means well.
+APIKEYS_MAX_BODY_BYTES = 8192

splent_feature_apikeys-0.1.1/setup.cfg

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

splent_feature_apikeys-0.1.1/src/splent_feature_apikeys.egg-info/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: splent_feature_apikeys
+Version: 0.1.1
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# splent_feature_apikeys
+
+Developer API tokens for a SPLENT product. A port of the UVLHub `apikeys`
+feature to SPLENT conventions, and the only place in a product where a
+password is exchanged for a credential a machine can carry.
+
+It owns tokens and nothing else. It does not know what the tokens are used
+for, and it never touches the `auth` feature: credentials are checked through
+the `AuthenticationService` that auth already registers.
+
+## The model
+
+`ApiToken` belongs to one user and keeps:
+
+| Column         | Meaning                                                    |
+|----------------|------------------------------------------------------------|
+| `user_id`      | Owner, foreign key to auth's `user.id`                     |
+| `name`         | Human label chosen by the owner                            |
+| `token_hash`   | sha256 of the plaintext, hex. The plaintext is never stored |
+| `prefix`       | First 15 characters of the plaintext, indexed, safe to show |
+| `scopes`       | Comma separated, as in UVLHub                              |
+| `created_at`, `expires_at`, `revoked_at`, `last_used_at` | lifecycle |
+
+A plaintext token looks like `splent_<64 hex characters>`. The `splent_`
+label makes a leaked token greppable; the prefix makes verification a single
+indexed lookup instead of a table scan.
+
+## Scopes
+
+`read_spl` and `write_spl`. Unknown names are dropped, and a request that
+asks for nothing but unknown names is refused rather than silently producing
+a token that can do nothing.
+
+## The service
+
+`ApiTokenService`, registered under that name in the service locator.
+
+```python
+api_token_service = service_proxy("ApiTokenService")
+
+row, plaintext = api_token_service.mint(user, "laptop", ["write_spl"], ttl_days=90)
+api_token_service.verify(plaintext)       # row, or None if unknown/revoked/expired
+api_token_service.find(plaintext)         # row whatever its state, to explain a refusal
+api_token_service.revoke(row.id, user)    # only the owner can revoke
+api_token_service.touch(row)              # last_used_at, at most once every 5 minutes
+api_token_service.authenticate(email, password)  # (user, None) or (None, reason)
+```
+
+`mint` returns the plaintext once. Nothing else in the product can ever
+produce it again.
+
+## Guarding a route
+
+```python
+from splent_io.splent_feature_apikeys.decorators import require_token
+
+@some_bp.route("/api/v1/spls", methods=["POST"])
+@require_token("write_spl")
+def publish():
+    g.api_user   # the owner
+    g.api_token  # the presenting token
+```
+
+`require_token()` with no scope accepts any usable token. For routes where a
+token is one of several ways in, call `resolve_token(scope)` directly: it
+returns `(api_token, None)` or `(None, (response, status))`.
+
+## Endpoints
+
+| Method | Path                            | Auth              |
+|--------|---------------------------------|-------------------|
+| POST   | `/api/v1/auth/tokens`           | email + password  |
+| GET    | `/api/v1/auth/whoami`           | Bearer token      |
+| DELETE | `/api/v1/auth/tokens/current`   | Bearer token      |
+
+```bash
+curl -X POST https://<product>/api/v1/auth/tokens \
+     -H "Content-Type: application/json" \
+     -d '{"email": "dev@example.com", "password": "...", "name": "laptop"}'
+
+curl https://<product>/api/v1/auth/whoami \
+     -H "Authorization: Bearer splent_..."
+```
+
+Omitting `ttl_days` gives the product default; sending it as `null` gives a
+token that never expires.
+
+Failed credential attempts are throttled per caller and account. Users are
+created inactive and an administrator activates them, so an account still
+waiting is answered with `403` and a message that says exactly that, never
+with "wrong password".
+
+## Pages
+
+- `/developer/tokens` — the owner's tokens, by prefix, with a revoke button.
+- `/developer/tokens/new` — create one; the plaintext is shown once.
+
+A link appears in the authenticated sidebar
+(`layout.authenticated_sidebar` hook).
+
+## Configuration
+
+| Variable                       | Default | Meaning                          |
+|--------------------------------|---------|----------------------------------|
+| `APIKEYS_DEFAULT_TTL_DAYS`     | 90      | Life of a token when none is asked |
+| `APIKEYS_MAX_LOGIN_ATTEMPTS`   | 5       | Failed attempts per window       |
+| `APIKEYS_LOGIN_WINDOW_SECONDS` | 300     | Length of that window            |
+
+All three have working defaults, so the feature needs no `.env` entry.
+
+## Install
+
+```bash
+splent feature:install splent-io/splent_feature_apikeys
+splent db:migrate splent_feature_apikeys
+splent db:upgrade
+```
+
+## Tests
+
+```bash
+splent feature:test splent_feature_apikeys
+```

splent_feature_apikeys-0.1.1/src/splent_feature_apikeys.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+MANIFEST.in
+README.md
+pyproject.toml
+src/splent_feature_apikeys.egg-info/PKG-INFO
+src/splent_feature_apikeys.egg-info/SOURCES.txt
+src/splent_feature_apikeys.egg-info/dependency_links.txt
+src/splent_feature_apikeys.egg-info/top_level.txt
+src/splent_io/splent_feature_apikeys/__init__.py
+src/splent_io/splent_feature_apikeys/config.py
+src/splent_io/splent_feature_apikeys/decorators.py
+src/splent_io/splent_feature_apikeys/forms.py
+src/splent_io/splent_feature_apikeys/hooks.py
+src/splent_io/splent_feature_apikeys/models.py
+src/splent_io/splent_feature_apikeys/repositories.py
+src/splent_io/splent_feature_apikeys/routes.py
+src/splent_io/splent_feature_apikeys/services.py
+src/splent_io/splent_feature_apikeys/throttle.py
+src/splent_io/splent_feature_apikeys/migrations/alembic.ini
+src/splent_io/splent_feature_apikeys/migrations/env.py
+src/splent_io/splent_feature_apikeys/migrations/script.py.mako
+src/splent_io/splent_feature_apikeys/migrations/versions/089274640134_splent_feature_apikeys.py
+src/splent_io/splent_feature_apikeys/templates/apikeys/created.html
+src/splent_io/splent_feature_apikeys/templates/apikeys/index.html
+src/splent_io/splent_feature_apikeys/templates/apikeys/new.html
+src/splent_io/splent_feature_apikeys/templates/hooks/sidebar_tokens.html
+src/splent_io/splent_feature_apikeys/translations/es/LC_MESSAGES/messages.mo
+src/splent_io/splent_feature_apikeys/translations/es/LC_MESSAGES/messages.po

splent_feature_apikeys-0.1.1/src/splent_feature_apikeys.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

splent_feature_apikeys-0.1.1/src/splent_feature_apikeys.egg-info/top_level.txt

@@ -0,0 +1 @@
+splent_io

splent_feature_apikeys-0.1.1/src/splent_io/splent_feature_apikeys/__init__.py

@@ -0,0 +1,35 @@
+from splent_framework.blueprints.base_blueprint import create_blueprint
+from splent_framework.services.service_locator import register_service
+
+from splent_io.splent_feature_apikeys.services import ApiTokenService
+
+apikeys_bp = create_blueprint(__name__)
+
+
+def init_feature(app):
+    from splent_io.splent_feature_apikeys.throttle import configure_from_app
+
+    register_service(app, "ApiTokenService", ApiTokenService)
+    # config.inject_config has already run, so the throttle picks up the
+    # product's budget instead of the module defaults.
+    configure_from_app(app)
+    _exempt_token_api_from_csrf(app)
+
+
+def _exempt_token_api_from_csrf(app):
+    """Machine API: trades email+password for a token, or revokes the bearer
+    token it is called with. Neither rides on the session cookie."""
+    csrf = app.extensions.get("splent_csrf")
+    if csrf is None:
+        return
+    from splent_io.splent_feature_apikeys.routes import (
+        api_create_token,
+        api_revoke_current_token,
+    )
+
+    csrf.exempt(api_create_token)
+    csrf.exempt(api_revoke_current_token)
+
+
+def inject_context_vars(app):
+    return {}

splent_feature_apikeys-0.1.1/src/splent_io/splent_feature_apikeys/config.py

@@ -0,0 +1,44 @@
+"""
+apikeys feature configuration.
+
+Injects environment variables into Flask app.config.
+Every value has a working default, so the feature needs no .env entry to run.
+
+To regenerate from source code: splent feature:inject-config splent_feature_apikeys
+"""
+
+import os
+
+
+def inject_config(app):
+    app.config.update(
+        {
+            # Life given to a token when the caller does not ask for one.
+            "APIKEYS_DEFAULT_TTL_DAYS": int(
+                os.getenv("APIKEYS_DEFAULT_TTL_DAYS", "90")
+            ),
+            # Failed credential attempts allowed per caller and window.
+            "APIKEYS_MAX_LOGIN_ATTEMPTS": int(
+                os.getenv("APIKEYS_MAX_LOGIN_ATTEMPTS", "5")
+            ),
+            "APIKEYS_LOGIN_WINDOW_SECONDS": int(
+                os.getenv("APIKEYS_LOGIN_WINDOW_SECONDS", "300")
+            ),
+            # Failed attempts allowed against ONE account from every address
+            # put together, for the distributed case a per address budget
+            # cannot see. Higher than the per address one on purpose, so the
+            # single attacker is caught by their own budget first.
+            "APIKEYS_MAX_ACCOUNT_ATTEMPTS": int(
+                os.getenv("APIKEYS_MAX_ACCOUNT_ATTEMPTS", "20")
+            ),
+            # Hard ceiling on how many throttle buckets one worker holds. The
+            # store is the only thing an unauthenticated caller can make this
+            # process allocate, so it is bounded rather than trusted.
+            "APIKEYS_THROTTLE_MAX_KEYS": int(
+                os.getenv("APIKEYS_THROTTLE_MAX_KEYS", "10000")
+            ),
+            # Largest body POST /api/v1/auth/tokens will read, in bytes. It
+            # carries an e-mail, a password and a label.
+            "APIKEYS_MAX_BODY_BYTES": int(os.getenv("APIKEYS_MAX_BODY_BYTES", "8192")),
+        }
+    )