jac-scale 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

jac_scale/impl/webhook.impl.jac

@@ -0,0 +1,212 @@
+"""Implementation of Webhook utilities for Jac Scale.
+
+This module implements HMAC-SHA256 signature generation/verification
+and API key management for webhook authentication.
+"""
+import hmac;
+import hashlib;
+import secrets;
+import jwt;
+import from datetime { UTC, datetime, timedelta }
+import from typing { Any }
+import from jaclang.runtimelib.transport { TransportResponse, Meta }
+import from jac_scale.config_loader { get_scale_config }
+
+# Load JWT config for signing API keys
+glob _jwt_config = get_scale_config().get_jwt_config(),
+     JWT_SECRET = _jwt_config['secret'],
+     JWT_ALGORITHM = _jwt_config['algorithm'];
+
+"""Generate HMAC-SHA256 signature for webhook payload."""
+impl WebhookUtils.generate_signature(payload: bytes, secret: str) -> str {
+    return hmac.new(secret.encode('utf-8'), payload, hashlib.sha256).hexdigest();
+}
+
+"""Verify HMAC-SHA256 signature for webhook payload."""
+impl WebhookUtils.verify_signature(payload: bytes, signature: str, secret: str) -> bool {
+    expected_signature = WebhookUtils.generate_signature(payload, secret);
+    # Use constant-time comparison to prevent timing attacks
+    return hmac.compare_digest(signature.lower(), expected_signature.lower());
+}
+
+"""Generate a cryptographically secure API key."""
+impl WebhookUtils.generate_api_key -> str {
+    return secrets.token_hex(32);
+}
+
+"""Create a JWT-wrapped API key token."""
+impl WebhookUtils.create_api_key_token(
+    api_key_id: str, username: str, name: str, expiry_days: int | None = None
+) -> str {
+    _webhook_config = get_scale_config().get_webhook_config();
+    default_expiry = _webhook_config.get('api_key_expiry_days', 365);
+    payload: dict[str, Any] = {
+        'type': 'api_key',
+        'api_key_id': api_key_id,
+        'sub': username,
+        'name': name,
+        'iat': datetime.now(UTC)
+    };
+    # Add expiry if specified
+    if expiry_days is not None {
+        payload['exp'] = datetime.now(UTC) + timedelta(days=expiry_days);
+    } elif default_expiry > 0 {
+        payload['exp'] = datetime.now(UTC) + timedelta(days=default_expiry);
+    }
+    # If expiry_days is 0 or negative, no expiry is set (permanent key)
+    return jwt.encode(payload, JWT_SECRET, algorithm=JWT_ALGORITHM);
+}
+
+"""Validate an API key token and extract user information."""
+impl WebhookUtils.validate_api_key(api_key: str) -> dict[str, str] | None {
+    try {
+        payload = jwt.decode(api_key, JWT_SECRET, algorithms=[JWT_ALGORITHM]);
+
+        # Verify this is an API key token
+        if payload.get('type') != 'api_key' {
+            return None;
+        }
+
+        return {
+            'username': payload.get('sub', ''),
+            'api_key_id': payload.get('api_key_id', ''),
+            'name': payload.get('name', '')
+        };
+    } except jwt.ExpiredSignatureError {
+        return None;
+    } except jwt.InvalidTokenError {
+        return None;
+    }
+}
+
+"""Extract signature from request header value."""
+impl WebhookUtils.extract_signature(header_value: str) -> str {
+    # Handle prefixed signatures like "sha256=abc123..."
+    if '=' in header_value {
+        parts = header_value.split('=', 1);
+        if len(parts) == 2 {
+            return parts[1];
+        }
+    }
+    return header_value;
+}
+
+"""Create a new API key for a user."""
+impl ApiKeyManager.create_api_key(
+    username: str, name: str, expiry_days: int | None = None
+) -> TransportResponse {
+    # Generate unique API key ID
+    api_key_id = secrets.token_hex(16);
+    # Create the JWT-wrapped API key
+    api_key = WebhookUtils.create_api_key_token(
+        api_key_id=api_key_id, username=username, name=name, expiry_days=expiry_days
+    );
+    created_at = datetime.now(UTC);
+    expires_at: datetime | None = None;
+    _webhook_config = get_scale_config().get_webhook_config();
+    default_expiry = _webhook_config.get('api_key_expiry_days', 365);
+    if expiry_days is not None and expiry_days > 0 {
+        expires_at = created_at + timedelta(days=expiry_days);
+    } elif default_expiry > 0 {
+        expires_at = created_at + timedelta(days=default_expiry);
+    }
+    # Store key metadata (not the key itself for security)
+    self._api_keys[api_key_id] = {
+        'username': username,
+        'name': name,
+        'created_at': created_at.isoformat(),
+        'expires_at': expires_at.isoformat() if expires_at else None,
+        'revoked': False
+    };
+    # Track keys by user
+    if username not in self._user_keys {
+        self._user_keys[username] = [];
+    }
+    self._user_keys[username].append(api_key_id);
+    return TransportResponse.success(
+        data={
+            'api_key': api_key,
+            'api_key_id': api_key_id,
+            'name': name,
+            'created_at': created_at.isoformat(),
+            'expires_at': expires_at.isoformat() if expires_at else None
+        },
+        meta=Meta(extra={'http_status': 201})
+    );
+}
+
+"""List all API keys for a user (metadata only, not the keys)."""
+impl ApiKeyManager.list_api_keys(username: str) -> TransportResponse {
+    user_key_ids = self._user_keys.get(username, []);
+    keys: list[dict[str, Any]] = [];
+    for key_id in user_key_ids {
+        key_info = self._api_keys.get(key_id);
+        if key_info and not key_info.get('revoked', False) {
+            keys.append(
+                {
+                    'api_key_id': key_id,
+                    'name': key_info.get('name', ''),
+                    'created_at': key_info.get('created_at'),
+                    'expires_at': key_info.get('expires_at'),
+                    'active': True
+                }
+            );
+        }
+    }
+    return TransportResponse.success(
+        data={'api_keys': keys}, meta=Meta(extra={'http_status': 200})
+    );
+}
+
+"""Revoke an API key."""
+impl ApiKeyManager.revoke_api_key(username: str, api_key_id: str) -> TransportResponse {
+    # Check if key exists
+    if api_key_id not in self._api_keys {
+        return TransportResponse.fail(
+            code='NOT_FOUND',
+            message=f"API key '{api_key_id}' not found",
+            meta=Meta(extra={'http_status': 404})
+        );
+    }
+    # Check if key belongs to user
+    key_info = self._api_keys[api_key_id];
+    if key_info.get('username') != username {
+        return TransportResponse.fail(
+            code='FORBIDDEN',
+            message='Cannot revoke API key owned by another user',
+            meta=Meta(extra={'http_status': 403})
+        );
+    }
+    # Mark as revoked
+    self._api_keys[api_key_id]['revoked'] = True;
+    return TransportResponse.success(
+        data={'message': f"API key '{api_key_id}' has been revoked"},
+        meta=Meta(extra={'http_status': 200})
+    );
+}
+
+"""Validate an API key and return the associated username."""
+impl ApiKeyManager.validate_api_key(api_key: str) -> str | None {
+    # Decode the JWT to get key info
+    key_info = WebhookUtils.validate_api_key(api_key);
+    if not key_info {
+        return None;
+    }
+    api_key_id = key_info.get('api_key_id', '');
+    # Check if key is still active (not revoked)
+    if not self.is_key_active(api_key_id) {
+        return None;
+    }
+    return key_info.get('username');
+}
+
+"""Check if an API key ID exists and is not revoked."""
+impl ApiKeyManager.is_key_active(api_key_id: str) -> bool {
+    key_info = self._api_keys.get(api_key_id);
+    if not key_info {
+        # Key not in our store - could be from before server restart
+        # Allow it if JWT is valid (handled by validate_api_key)
+        return True;
+    }
+    return not key_info.get('revoked', False);
+}

jac_scale/jserver/impl/jfast_api.impl.jac

@@ -379,6 +379,10 @@ impl JFastApiServer._create_endpoint_function(
     if accepts_kwargs {
         param_strs.append('request: Request');
         param_mapping['__request__'] = 'request';
+        # If the callback also explicitly accepts a request parameter, map it
+        if needs_request {
+            param_mapping['request'] = 'request';
+        }
     } elif needs_request {
         param_strs.append('request: Request');
         param_mapping['request'] = 'request';

jac_scale/plugin_config.jac

@@ -34,7 +34,7 @@ class JacScalePluginConfig {
                     "nested": {
                         "secret": {
                             "type": "string",
-                            "default": "supersecretkey",
+                            "default": "supersecretkey_for_testing_only!",
                             "description": "Secret key for JWT signing"
                         },
                         "algorithm": {

jac_scale/serve.jac

@@ -6,7 +6,9 @@ import from pathlib { Path }
 import from pydantic { BaseModel, Field }
 import from typing { Any }
 import jwt;
+import json;
 import from os { getenv }
+import from fastapi { Request }
 import from fastapi.middleware.cors { CORSMiddleware }
 import from fastapi.responses { HTMLResponse, JSONResponse, Response, RedirectResponse }
 import from jac_scale.jserver.jfast_api { JFastApiServer }
@@ -24,6 +26,7 @@ import from enum { StrEnum }
 import from fastapi_sso.sso.google { GoogleSSO }
 import from jac_scale.utils { generate_random_password }
 import from jac_scale.config_loader { get_scale_config }
+import from jac_scale.webhook { ApiKeyManager, WebhookUtils }
 import from typing { AsyncGenerator }
 import from inspect { isgenerator }
 import from fastapi.responses { StreamingResponse }
@@ -41,10 +44,13 @@ enum Platforms ( StrEnum ) { GOOGLE = 'google' }
 
 enum Operations ( StrEnum ) { LOGIN = 'login', REGISTER = 'register' }
 
+enum TransportType ( StrEnum ) { HTTP = 'http', WEBHOOK = 'webhook' }
+
 obj JacAPIServer(JServer) {
     # HMR (Hot Module Replacement) support fields
     has _hmr_pending: bool = False,
-        _hot_reloader: Any | None = None;
+        _hot_reloader: Any | None = None,
+        _api_key_manager: ApiKeyManager | None = None;
 
     def postinit -> None;
     def login(username: str, password: str) -> TransportResponse;
@@ -72,12 +78,15 @@ obj JacAPIServer(JServer) {
     ) -> Callable[..., TransportResponse];
 
     def create_walker_parameters(
-        walker_name: str, invoke_on_root: bool
+        walker_name: str, invoke_on_root: bool, method: HTTPMethod = HTTPMethod.POST
     ) -> list[APIParameter];
 
     def register_walkers_endpoints -> None;
     def create_function_callback(func_name: str) -> Callable[..., TransportResponse];
-    def create_function_parameters(func_name: str) -> list[APIParameter];
+    def create_function_parameters(
+        func_name: str, method: HTTPMethod = HTTPMethod.POST
+    ) -> list[APIParameter];
+
     def register_functions_endpoints -> None;
     def render_page_callback -> Callable[..., HTMLResponse];
     def render_base_route_callback(app_name: str) -> Callable[..., HTMLResponse];
@@ -89,12 +98,29 @@ obj JacAPIServer(JServer) {
     def register_root_asset_endpoint -> None;
     def serve_root_asset(file_path: str) -> Response;
     def _configure_openapi_security -> None;
-    def start(dev: bool = False) -> None;
+    def start(dev: bool = False, no_client: bool = False) -> None;
     # HMR (Hot Module Replacement) dynamic routing methods
     def enable_hmr(hot_reloader: Any) -> None;
     def register_dynamic_walker_endpoint -> None;
     def register_dynamic_function_endpoint -> None;
     def register_dynamic_introspection_endpoints -> None;
+    # Webhook support methods
+    def get_api_key_manager -> ApiKeyManager;
+    def create_api_key(
+        name: str, expiry_days: int | None = None, Authorization: str | None = None
+    ) -> TransportResponse;
+
+    def list_api_keys(Authorization: str | None = None) -> TransportResponse;
+    def revoke_api_key(
+        api_key_id: str, Authorization: str | None = None
+    ) -> TransportResponse;
+
+    def register_api_key_endpoints -> None;
+    def register_webhook_endpoints -> None;
+    def create_webhook_callback(walker_name: str) -> Callable[..., TransportResponse];
+    def create_webhook_parameters(walker_name: str) -> list[APIParameter];
+    def register_dynamic_webhook_endpoint -> None;
+    def get_transport_type_for_walker(walker_name: str) -> str;
 }
 
 class UpdateUsernameRequest(BaseModel) {

jac_scale/tests/fixtures/test_api.jac

@@ -186,3 +186,63 @@ walker : pub PublicFileUpload {
         };
     }
 }
+
+# ============================================================================
+# Webhook Walkers
+# ============================================================================
+"""Test 1: Webhook walker with multiple fields using @restspec(webhook=True).
+This walker should be accessible ONLY via /webhook/PaymentReceived endpoint."""
+@restspec(webhook=True)
+walker PaymentReceived {
+    has payment_id: str,
+        order_id: str,
+        amount: float,
+        currency: str = 'USD';
+
+    can process with `root entry {
+        response = {
+            "status": "success",
+            "message": f"Payment {self.payment_id} processed successfully.",
+            "payment_id": self.payment_id,
+            "order_id": self.order_id,
+            "amount": self.amount,
+            "currency": self.currency
+        };
+        report response;
+    }
+}
+
+"""Test 2: Normal walker without @restspec(webhook=True) (defaults to HTTP).
+This walker should be accessible via /walker/NormalPayment endpoint, NOT /webhook/."""
+walker NormalPayment {
+    has payment_id: str,
+        order_id: str,
+        amount: float,
+        currency: str = 'USD';
+
+    can process with `root entry {
+        response = {
+            "status": "success",
+            "message": f"Normal payment {self.payment_id} processed.",
+            "payment_id": self.payment_id,
+            "order_id": self.order_id,
+            "amount": self.amount,
+            "currency": self.currency,
+            "transport": "http"
+        };
+        report response;
+    }
+}
+
+"""Test 3: Minimal webhook walker with ONLY @restspec(webhook=True).
+This walker should be accessible ONLY via /webhook/MinimalWebhook endpoint."""
+@restspec(webhook=True)
+walker MinimalWebhook {
+    can process with `root entry {
+        report {
+            "status": "received",
+            "message": "Minimal webhook executed successfully",
+            "transport": "webhook"
+        };
+    }
+}

jac_scale/tests/fixtures/test_restspec.jac

@@ -35,3 +35,54 @@ def get_func() -> dict {
 def custom_path_func() -> dict {
     return {"message": "custom_path_func executed", "path": "/custom/func"};
 }
+
+"""Walker with POST method via restspec decorator."""
+@restspec(method=HTTPMethod.POST)
+walker : pub PostWalker {
+    can post_data with `root entry {
+        report {"message": "PostWalker executed", "method": "POST"};
+    }
+}
+
+"""Walker with default method (POST)."""
+walker : pub DefaultWalker {
+    can post_data with `root entry {
+        report {"message": "DefaultWalker executed", "method": "DEFAULT"};
+    }
+}
+
+"""Function with POST method via restspec decorator."""
+@restspec(method=HTTPMethod.POST)
+def post_func() -> dict {
+    return {"message": "post_func executed", "method": "POST"};
+}
+
+"""Function with default method (POST)."""
+def default_func() -> dict {
+    return {"message": "default_func executed", "method": "DEFAULT"};
+}
+
+"""Walker with GET method and parameters."""
+@restspec(method=HTTPMethod.GET)
+walker : pub GetWalkerWithParams {
+    has name: str;
+    has age: int;
+
+    can get_data with `root entry {
+        report {
+            "message": "GetWalkerWithParams executed",
+            "name": self.name,
+            "age": self.age
+        };
+    }
+}
+
+"""Function with GET method and parameters."""
+@restspec(method=HTTPMethod.GET)
+def get_func_with_params(name: str, age: int) -> dict {
+    return {
+        "message": "get_func_with_params executed",
+        "name": name,
+        "age": age
+    };
+}

jac_scale/tests/test_restspec.py

@@ -139,6 +139,22 @@ class TestRestSpec:
         assert data["reports"][0]["message"] == "CustomPathWalker executed"
         assert data["reports"][0]["path"] == "/custom/walker"
 
+    def test_post_method_walker(self) -> None:
+        """Test walker with explicit POST method."""
+        response = requests.post(f"{self.base_url}/walker/PostWalker", timeout=5)
+        assert response.status_code == 200
+        data = self._extract_data(response.json())
+        assert data["reports"][0]["message"] == "PostWalker executed"
+        assert data["reports"][0]["method"] == "POST"
+
+    def test_default_method_walker(self) -> None:
+        """Test walker with default method (POST)."""
+        response = requests.post(f"{self.base_url}/walker/DefaultWalker", timeout=5)
+        assert response.status_code == 200
+        data = self._extract_data(response.json())
+        assert data["reports"][0]["message"] == "DefaultWalker executed"
+        assert data["reports"][0]["method"] == "DEFAULT"
+
     def test_custom_method_func(self) -> None:
         """Test function with custom GET method."""
         requests.post(
@@ -176,6 +192,79 @@ class TestRestSpec:
         assert data["result"]["message"] == "custom_path_func executed"
         assert data["result"]["path"] == "/custom/func"
 
+    def test_post_method_func(self) -> None:
+        """Test function with explicit POST method."""
+        # Use existing user token if possible, but simplest is fresh login
+        login = requests.post(
+            f"{self.base_url}/user/login", json={"username": "u1", "password": "p1"}
+        )
+        token = self._extract_data(login.json())["token"]
+
+        response = requests.post(
+            f"{self.base_url}/function/post_func",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=5,
+        )
+        assert response.status_code == 200
+        data = self._extract_data(response.json())
+        assert data["result"]["message"] == "post_func executed"
+        assert data["result"]["method"] == "POST"
+
+    def test_default_method_func(self) -> None:
+        """Test function with default method (POST)."""
+        # Use existing user token if possible, but simplest is fresh login
+        login = requests.post(
+            f"{self.base_url}/user/login", json={"username": "u1", "password": "p1"}
+        )
+        token = self._extract_data(login.json())["token"]
+
+        response = requests.post(
+            f"{self.base_url}/function/default_func",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=5,
+        )
+        assert response.status_code == 200
+        data = self._extract_data(response.json())
+        assert data["result"]["message"] == "default_func executed"
+        assert data["result"]["method"] == "DEFAULT"
+
+    def test_get_walker_with_params(self) -> None:
+        """Test walker with GET method and query parameters."""
+        # Parameters should be passed as query string
+        params: dict[str, str | int] = {"name": "Alice", "age": 30}
+        response = requests.get(
+            f"{self.base_url}/walker/GetWalkerWithParams",
+            params=params,
+            timeout=5,
+        )
+        assert response.status_code == 200
+        data = self._extract_data(response.json())
+        assert data["reports"][0]["message"] == "GetWalkerWithParams executed"
+        assert data["reports"][0]["name"] == "Alice"
+        assert data["reports"][0]["age"] == 30
+
+    def test_get_func_with_params(self) -> None:
+        """Test function with GET method and query parameters."""
+        # Use existing user token if possible, but simplest is fresh login
+        login = requests.post(
+            f"{self.base_url}/user/login", json={"username": "u1", "password": "p1"}
+        )
+        token = self._extract_data(login.json())["token"]
+
+        # Parameters should be passed as query string
+        params: dict[str, str | int] = {"name": "Bob", "age": 40}
+        response = requests.get(
+            f"{self.base_url}/function/get_func_with_params",
+            headers={"Authorization": f"Bearer {token}"},
+            params=params,
+            timeout=5,
+        )
+        assert response.status_code == 200
+        data = self._extract_data(response.json())
+        assert data["result"]["message"] == "get_func_with_params executed"
+        assert data["result"]["name"] == "Bob"
+        assert data["result"]["age"] == 40
+
     def test_openapi_specs(self) -> None:
         """Verify OpenAPI documentation reflects custom paths and methods."""
         spec = requests.get(f"{self.base_url}/openapi.json").json()
@@ -190,3 +279,11 @@ class TestRestSpec:
         assert "/walker/GetWalker" in paths
         assert "get" in paths["/walker/GetWalker"]
         assert "post" not in paths["/walker/GetWalker"]
+
+        assert "/walker/PostWalker" in paths
+        assert "post" in paths["/walker/PostWalker"]
+        assert "get" not in paths["/walker/PostWalker"]
+
+        assert "/walker/DefaultWalker" in paths
+        assert "post" in paths["/walker/DefaultWalker"]
+        assert "get" not in paths["/walker/DefaultWalker"]