platform-auth 0.4.0__tar.gz

platform_auth-0.4.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: platform-auth
+Version: 0.4.0
+Summary: Shared SaaS platform authentication and authorization helpers
+Requires-Python: <3.14,>=3.12
+Requires-Dist: boto3==1.34.162
+Requires-Dist: botocore==1.34.162
+Requires-Dist: fastapi==0.115.6
+Requires-Dist: pydantic==2.10.4

platform_auth-0.4.0/README.md

@@ -0,0 +1,162 @@
+# platform-auth-service
+
+Shared SaaS platform authentication and authorization service/library.
+
+This project owns platform-level concepts:
+
+- tenants
+- memberships
+- roles and permissions
+- plans
+- entitlements
+- quotas
+- usage counters
+- tenant subscriptions
+- manual payment records
+- usage adjustments
+- invitations
+- tenant settings
+- logout/session revocation support
+- audit logs
+- reusable `platform_auth` Python package
+
+It does not own product-specific logic such as CVE ingestion, darkweb monitoring, IOC processing, or credential-leak detection.
+
+## Current deployment model
+
+Recommended production mode:
+
+```text
+Existing Cognito handles signup/login/refresh.
+API Gateway validates JWT.
+platform-auth-service resolves the user from Users table.
+platform-auth-service enforces tenant/membership/role/plan/quota checks.
+```
+
+## Local quick start
+
+```bash
+make install
+cp .env.example .env
+make test
+make local-up
+make local-init
+make local-seed-plans
+make local-api
+```
+
+In another terminal, run the local API smoke test:
+
+```bash
+make smoke-api
+```
+
+`smoke-api` is a local-only integration check. It expects
+`AUTH_LOCAL_DEV_MODE=true`, calls `http://localhost:8000` by default, and uses
+mock auth headers such as `X-User-Id`. It is not a Cognito/JWT smoke test for
+AWS deployments.
+
+Test public API:
+
+```bash
+curl http://localhost:8000/health
+curl http://localhost:8000/api/plans
+```
+
+Create tenant in local mock-auth mode:
+
+```bash
+curl -X POST http://localhost:8000/api/tenants \
+  -H "Content-Type: application/json" \
+  -H "X-User-Id: user-1" \
+  -d '{"name":"Acme Corp","planId":"trial"}'
+```
+
+Use returned tenant ID:
+
+```bash
+curl http://localhost:8000/api/tenants/<tenantId> \
+  -H "X-User-Id: user-1" \
+  -H "X-Tenant-Id: <tenantId>"
+```
+
+Local admin/operator request:
+
+```bash
+curl http://localhost:8000/api/admin/plans \
+  -H "X-User-Id: operator-1" \
+  -H "X-Platform-Role: operator"
+```
+
+## AWS deployment
+
+See:
+
+- `docs/deployment.md`
+- `docs/users-table.md`
+- `docs/tables.md`
+- `docs/apis.md`
+- `docs/library-usage.md`
+- `docs/platform-auth-library.md`
+- `docs/swagger.md`
+
+## Packaging the library
+
+The installable package name is:
+
+```text
+platform-auth
+```
+
+Import path:
+
+```python
+import platform_auth
+```
+
+Early-stage Git dependency example:
+
+```text
+platform-auth @ git+ssh://git@github.com/your-org/platform-auth-service.git@<tag-or-sha>
+```
+
+
+## Swagger / OpenAPI
+
+When the local API is running:
+
+```text
+Swagger UI:   http://localhost:8000/docs
+ReDoc:        http://localhost:8000/redoc
+OpenAPI JSON: http://localhost:8000/openapi.json
+```
+
+Export the OpenAPI document:
+
+```bash
+make export-openapi
+```
+
+## Cognito Post Confirmation user provisioning
+
+This version supports the preferred production path for creating application users:
+
+```text
+Cognito signup + email confirmation -> Post Confirmation Lambda -> Users DynamoDB table
+```
+
+If deploying with an existing Cognito User Pool, deploy with `createUsersTable=true`, then attach the trigger:
+
+```bash
+make attach-post-confirmation
+```
+
+Configure these in `.env` first:
+
+```text
+COGNITO_USER_POOL_ID=<existing-user-pool-id>
+POST_CONFIRMATION_LAMBDA_ARN=<output-from-cdk>
+AWS_REGION=<region>
+```
+
+See `docs/cognito-post-confirmation.md` and `docs/users-table.md` for details.

platform_auth-0.4.0/platform_auth/__init__.py

@@ -0,0 +1,5 @@
+from platform_auth.models import AuthContext
+
+__version__ = '0.2.0'
+
+__all__ = ['AuthContext']

platform_auth-0.4.0/platform_auth/config.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+
+
+def env(name: str, default: str | None = None) -> str:
+    value = os.getenv(name, default)
+    if value is None:
+        raise RuntimeError(f"Missing required environment variable: {name}")
+    return value
+
+
+def optional_env(name: str) -> str | None:
+    return os.getenv(name)
+
+
+def local_dev_mode() -> bool:
+    return os.getenv("AUTH_LOCAL_DEV_MODE", "false").lower() == "true"

platform_auth-0.4.0/platform_auth/dynamodb.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+
+import boto3
+from boto3.resources.base import ServiceResource
+from botocore.client import BaseClient
+
+
+def _common_kwargs() -> dict:
+    endpoint_url = os.getenv("AWS_ENDPOINT_URL")
+    kwargs = {
+        "region_name": os.getenv("AWS_REGION", os.getenv("AWS_DEFAULT_REGION", "us-east-1")),
+        "endpoint_url": endpoint_url,
+    }
+    if endpoint_url:
+        kwargs.update(
+            aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID", "test"),
+            aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY", "test"),
+            aws_session_token=os.getenv("AWS_SESSION_TOKEN", "test"),
+        )
+    return kwargs
+
+
+@lru_cache(maxsize=1)
+def dynamodb_resource() -> ServiceResource:
+    return boto3.resource("dynamodb", **_common_kwargs())
+
+
+@lru_cache(maxsize=1)
+def dynamodb_client() -> BaseClient:
+    return boto3.client("dynamodb", **_common_kwargs())

platform_auth-0.4.0/platform_auth/errors.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class PlatformAuthError(Exception):
+    code: str
+    message: str
+    status_code: int = 403
+    details: dict[str, Any] | None = None
+
+    def to_response(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {'error': self.code, 'message': self.message}
+        if self.details:
+            payload['details'] = self.details
+        return payload
+
+
+class UnauthorizedError(PlatformAuthError):
+    def __init__(self, message: str = 'Authentication required') -> None:
+        super().__init__('UNAUTHORIZED', message, 401)
+
+
+class TenantRequiredError(PlatformAuthError):
+    def __init__(self) -> None:
+        super().__init__('TENANT_REQUIRED', 'Tenant context is required', 400)
+
+
+class TenantForbiddenError(PlatformAuthError):
+    def __init__(self, message: str = 'Tenant access is forbidden') -> None:
+        super().__init__('TENANT_FORBIDDEN', message, 403)
+
+
+class PermissionDeniedError(PlatformAuthError):
+    def __init__(self, permission: str) -> None:
+        super().__init__(
+            'PERMISSION_DENIED',
+            'User does not have the required permission',
+            403,
+            {'permission': permission},
+        )
+
+
+class FeatureNotIncludedError(PlatformAuthError):
+    def __init__(self, feature: str) -> None:
+        super().__init__(
+            'FEATURE_NOT_INCLUDED_IN_PLAN',
+            'Feature is not included in the tenant plan',
+            403,
+            {'feature': feature},
+        )
+
+
+class SubscriptionInactiveError(PlatformAuthError):
+    def __init__(self, subscription_status: str) -> None:
+        super().__init__(
+            'SUBSCRIPTION_INACTIVE',
+            'Tenant subscription is not active',
+            403,
+            {'subscriptionStatus': subscription_status},
+        )
+
+
+class QuotaExceededError(PlatformAuthError):
+    def __init__(self, metric_key: str, current: int, limit: int) -> None:
+        super().__init__(
+            'QUOTA_EXCEEDED',
+            'Quota exceeded',
+            429,
+            {'metric': metric_key, 'current': current, 'limit': limit},
+        )
+
+
+class ValidationError(PlatformAuthError):
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(code, message, 400, details)
+
+
+class AuthConfigurationError(PlatformAuthError):
+    def __init__(self, message: str) -> None:
+        super().__init__('AUTH_CONFIGURATION_ERROR', message, 500)

platform_auth-0.4.0/platform_auth/fastapi/dependencies.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import Depends, Header, HTTPException, Request
+
+from platform_auth.config import local_dev_mode
+from platform_auth.errors import PlatformAuthError, UnauthorizedError
+from platform_auth.models import AuthContext
+from platform_auth.services.factory import access_service
+
+
+def _claims_from_request(request: Request) -> dict[str, Any]:
+    event = request.scope.get("aws.event") or {}
+    claims = (
+        event.get("requestContext", {})
+        .get("authorizer", {})
+        .get("jwt", {})
+        .get("claims", {})
+    )
+    if claims:
+        return dict(claims)
+
+    if local_dev_mode():
+        user_id = request.headers.get("x-user-id")
+        if user_id:
+            return {
+                "sub": user_id,
+                "userId": user_id,
+                "email": request.headers.get("x-user-email", f"{user_id}@local.test"),
+                "platformRole": request.headers.get("x-platform-role"),
+                "userStatus": request.headers.get("x-user-status", "active"),
+            }
+
+    raise UnauthorizedError()
+
+
+def require_access(
+    *,
+    permission: str | None = None,
+    feature: str | None = None,
+    quota: str | None = None,
+    quota_amount: int = 1,
+    platform_admin_required: bool = False,
+) -> Callable[..., AuthContext]:
+    def dependency(request: Request, x_tenant_id: str | None = Header(default=None, alias="X-Tenant-Id")) -> AuthContext:
+        try:
+            claims = _claims_from_request(request)
+            return access_service().require_access(
+                claims=claims,
+                tenant_id=x_tenant_id,
+                permission=permission,
+                feature=feature,
+                quota=quota,
+                quota_amount=quota_amount,
+                platform_admin_required=platform_admin_required,
+            )
+        except PlatformAuthError as exc:
+            raise HTTPException(status_code=exc.status_code, detail=exc.to_response()) from exc
+    return dependency
+
+
+def require_authenticated_user(request: Request) -> AuthContext:
+    try:
+        claims = _claims_from_request(request)
+        return access_service().require_authenticated_user(claims=claims)
+    except PlatformAuthError as exc:
+        raise HTTPException(status_code=exc.status_code, detail=exc.to_response()) from exc

platform_auth-0.4.0/platform_auth/models.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+TenantStatus = Literal["pending", "active", "suspended", "deleted"]
+SubscriptionStatus = Literal["trialing", "active", "past_due", "suspended", "canceled", "expired"]
+MembershipStatus = Literal["active", "inactive", "invited"]
+PlanStatus = Literal["draft", "active", "deprecated", "retired", "disabled"]
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    user_id: str
+    tenant_id: str | None
+    role: str | None = None
+    platform_role: str | None = None
+    plan_id: str | None = None
+    subscription_status: str | None = None
+    permissions: list[str] = field(default_factory=list)
+    request_id: str | None = None
+    claims: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Tenant:
+    tenant_id: str
+    name: str
+    status: str
+    plan_id: str
+    subscription_status: str
+
+
+@dataclass(frozen=True)
+class Membership:
+    tenant_id: str
+    user_id: str
+    role: str
+    status: str
+
+
+@dataclass(frozen=True)
+class Plan:
+    plan_id: str
+    name: str
+    status: str
+    visibility: str = "public"
+    billing_mode: str = "manual"
+    currency: str = "USD"
+    monthly_price: int | None = None
+    annual_price: int | None = None
+    trial_days: int | None = None
+    description: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+@dataclass(frozen=True)
+class EntitlementSet:
+    plan_id: str
+    features: dict[str, bool]
+
+
+@dataclass(frozen=True)
+class QuotaSet:
+    plan_id: str
+    limits: dict[str, int]
+
+
+@dataclass(frozen=True)
+class TenantOverride:
+    tenant_id: str
+    feature_overrides: dict[str, bool] = field(default_factory=dict)
+    quota_overrides: dict[str, int] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class UsageCounter:
+    tenant_id: str
+    period: str
+    metric_key: str
+    value: int
+
+
+@dataclass(frozen=True)
+class TenantSubscription:
+    tenant_id: str
+    plan_id: str
+    status: str
+    billing_mode: str = "manual"
+    billing_cycle: str = "monthly"
+    currency: str = "USD"
+    price: int | None = None
+    current_period_start: str | None = None
+    current_period_end: str | None = None
+    trial_ends_at: str | None = None
+    payment_status: str = "pending"
+    last_payment_at: str | None = None
+    next_payment_due_at: str | None = None
+    updated_at: str | None = None
+
+
+@dataclass(frozen=True)
+class PaymentRecord:
+    payment_id: str
+    tenant_id: str
+    amount: int
+    currency: str
+    method: str
+    status: str
+    reference: str | None = None
+    paid_at: str | None = None
+    notes: str | None = None
+    created_by: str | None = None
+    created_at: str | None = None
+
+
+@dataclass(frozen=True)
+class UsageAdjustment:
+    adjustment_id: str
+    tenant_id: str
+    period: str
+    metric_key: str
+    delta: int
+    reason: str
+    created_by: str
+    created_at: str
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    tenant_id: str | None
+    user_id: str | None
+    action: str
+    resource_type: str | None = None
+    resource_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=lambda: datetime.utcnow().isoformat() + "Z")

platform_auth-0.4.0/platform_auth/permissions.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+ROLE_PERMISSIONS: dict[str, set[str]] = {
+    'owner': {'*'},
+    'admin': {
+        'tenant:read',
+        'tenant:update',
+        'tenant.settings:read',
+        'tenant.settings:update',
+        'tenant.members:read',
+        'tenant.members:manage',
+        'tenant.invitations:read',
+        'tenant.invitations:manage',
+        'tenant.usage:read',
+        'tenant.billing:read',
+        'tenant.audit:read',
+    },
+    'member': {
+        'tenant:read',
+        'tenant.settings:read',
+        'tenant.usage:read',
+    },
+    'viewer': {
+        'tenant:read',
+        'tenant.settings:read',
+        'tenant.usage:read',
+    },
+}
+
+PLATFORM_ROLE_PERMISSIONS: dict[str, set[str]] = {
+    'support': {'admin.tenants:read', 'admin.plans:read', 'admin.audit:read'},
+    'operator': {
+        'admin.tenants:read',
+        'admin.tenants:create',
+        'admin.tenants:update',
+        'admin.tenants:manage',
+        'admin.plans:read',
+        'admin.plans:create',
+        'admin.plans:update',
+        'admin.plans:manage',
+        'admin.audit:read',
+    },
+    'super_admin': {'*'},
+}
+
+
+def has_permission(role: str | None, permission: str, *, platform_role: str | None = None) -> bool:
+    if platform_role:
+        platform_permissions = PLATFORM_ROLE_PERMISSIONS.get(platform_role, set())
+        if '*' in platform_permissions or permission in platform_permissions:
+            return True
+
+    if not role:
+        return False
+
+    permissions = ROLE_PERMISSIONS.get(role, set())
+    return '*' in permissions or permission in permissions
+
+
+def permissions_for_role(role: str | None, *, platform_role: str | None = None) -> list[str]:
+    result: set[str] = set()
+    if role:
+        result.update(ROLE_PERMISSIONS.get(role, set()))
+    if platform_role:
+        result.update(PLATFORM_ROLE_PERMISSIONS.get(platform_role, set()))
+    return sorted(result)

platform_auth-0.4.0/platform_auth/repositories/audit.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import os
+from uuid import uuid4
+
+from boto3.dynamodb.conditions import Key
+
+from platform_auth.models import AuditEvent
+from platform_auth.repositories.base import DynamoRepository
+
+
+class AuditRepository(DynamoRepository):
+    def __init__(self, table_name: str | None = None) -> None:
+        super().__init__(table_name or os.environ['AUDIT_LOG_TABLE_NAME'])
+
+    def write(self, event: AuditEvent) -> None:
+        event_id = str(uuid4())
+        pk = f'TENANT#{event.tenant_id}' if event.tenant_id else 'PLATFORM'
+        self.table.put_item(
+            Item={
+                'PK': pk,
+                'SK': f'AUDIT#{event.created_at}#{event_id}',
+                'tenantId': event.tenant_id,
+                'userId': event.user_id,
+                'action': event.action,
+                'resourceType': event.resource_type,
+                'resourceId': event.resource_id,
+                'metadata': event.metadata,
+                'createdAt': event.created_at,
+            }
+        )
+
+    def list_for_tenant(self, tenant_id: str, limit: int = 50) -> list[dict]:
+        res = self.table.query(
+            KeyConditionExpression=Key('PK').eq(f'TENANT#{tenant_id}'),
+            ScanIndexForward=False,
+            Limit=limit,
+        )
+        return list(res.get('Items', []))
+
+    def list_platform(self, limit: int = 50) -> list[dict]:
+        res = self.table.query(
+            KeyConditionExpression=Key('PK').eq('PLATFORM'),
+            ScanIndexForward=False,
+            Limit=limit,
+        )
+        return list(res.get('Items', []))

platform_auth-0.4.0/platform_auth/repositories/base.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from platform_auth.dynamodb import dynamodb_resource
+
+
+class DynamoRepository:
+    def __init__(self, table_name: str) -> None:
+        self.table = dynamodb_resource().Table(table_name)

platform_auth-0.4.0/platform_auth/repositories/entitlements.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+
+from platform_auth.models import EntitlementSet
+from platform_auth.repositories.base import DynamoRepository
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace('+00:00', 'Z')
+
+
+class EntitlementRepository(DynamoRepository):
+    def __init__(self, table_name: str | None = None) -> None:
+        super().__init__(table_name or os.environ["ENTITLEMENTS_TABLE_NAME"])
+
+    def get(self, plan_id: str) -> EntitlementSet:
+        res = self.table.get_item(Key={"PK": f"PLAN#{plan_id}", "SK": "ENTITLEMENTS"})
+        item = res.get("Item") or {"features": {}}
+        return EntitlementSet(plan_id=plan_id, features=dict(item.get("features", {})))
+
+    def put(self, plan_id: str, features: dict[str, bool]) -> None:
+        self.table.put_item(
+            Item={
+                "PK": f"PLAN#{plan_id}",
+                "SK": "ENTITLEMENTS",
+                "planId": plan_id,
+                "features": features,
+                "updatedAt": _now(),
+            }
+        )
+
+    def patch(self, plan_id: str, features: dict[str, bool]) -> EntitlementSet:
+        current = self.get(plan_id).features
+        current.update(features)
+        self.put(plan_id, current)
+        return EntitlementSet(plan_id=plan_id, features=current)