plain 0.1.0__py3-none-any.whl

plain/preflight/security/csrf.py

@@ -0,0 +1,40 @@
+from plain.runtime import settings
+
+from .. import Warning, register
+
+W003 = Warning(
+    "You don't appear to be using Plain's built-in "
+    "cross-site request forgery protection via the middleware "
+    "('plain.csrf.middleware.CsrfViewMiddleware' is not in your "
+    "MIDDLEWARE). Enabling the middleware is the safest approach "
+    "to ensure you don't leave any holes.",
+    id="security.W003",
+)
+
+W016 = Warning(
+    "You have 'plain.csrf.middleware.CsrfViewMiddleware' in your "
+    "MIDDLEWARE, but you have not set CSRF_COOKIE_SECURE to True. "
+    "Using a secure-only CSRF cookie makes it more difficult for network "
+    "traffic sniffers to steal the CSRF token.",
+    id="security.W016",
+)
+
+
+def _csrf_middleware():
+    return "plain.csrf.middleware.CsrfViewMiddleware" in settings.MIDDLEWARE
+
+
+@register(deploy=True)
+def check_csrf_middleware(package_configs, **kwargs):
+    passed_check = _csrf_middleware()
+    return [] if passed_check else [W003]
+
+
+@register(deploy=True)
+def check_csrf_cookie_secure(package_configs, **kwargs):
+    passed_check = (
+        settings.CSRF_USE_SESSIONS
+        or not _csrf_middleware()
+        or settings.CSRF_COOKIE_SECURE is True
+    )
+    return [] if passed_check else [W016]

plain/preflight/urls.py

@@ -0,0 +1,117 @@
+from collections import Counter
+
+from plain.runtime import settings
+
+from . import Error, Warning, register
+
+
+@register
+def check_url_config(package_configs, **kwargs):
+    if getattr(settings, "ROOT_URLCONF", None):
+        from plain.urls import get_resolver
+
+        resolver = get_resolver()
+        return check_resolver(resolver)
+    return []
+
+
+def check_resolver(resolver):
+    """
+    Recursively check the resolver.
+    """
+    check_method = getattr(resolver, "check", None)
+    if check_method is not None:
+        return check_method()
+    elif not hasattr(resolver, "resolve"):
+        return get_warning_for_invalid_pattern(resolver)
+    else:
+        return []
+
+
+@register
+def check_url_namespaces_unique(package_configs, **kwargs):
+    """
+    Warn if URL namespaces used in applications aren't unique.
+    """
+    if not getattr(settings, "ROOT_URLCONF", None):
+        return []
+
+    from plain.urls import get_resolver
+
+    resolver = get_resolver()
+    all_namespaces = _load_all_namespaces(resolver)
+    counter = Counter(all_namespaces)
+    non_unique_namespaces = [n for n, count in counter.items() if count > 1]
+    errors = []
+    for namespace in non_unique_namespaces:
+        errors.append(
+            Warning(
+                "URL namespace '{}' isn't unique. You may not be able to reverse "
+                "all URLs in this namespace".format(namespace),
+                id="urls.W005",
+            )
+        )
+    return errors
+
+
+def _load_all_namespaces(resolver, parents=()):
+    """
+    Recursively load all namespaces from URL patterns.
+    """
+    url_patterns = getattr(resolver, "url_patterns", [])
+    namespaces = [
+        ":".join(parents + (url.namespace,))
+        for url in url_patterns
+        if getattr(url, "namespace", None) is not None
+    ]
+    for pattern in url_patterns:
+        namespace = getattr(pattern, "namespace", None)
+        current = parents
+        if namespace is not None:
+            current += (namespace,)
+        namespaces.extend(_load_all_namespaces(pattern, current))
+    return namespaces
+
+
+def get_warning_for_invalid_pattern(pattern):
+    """
+    Return a list containing a warning that the pattern is invalid.
+
+    describe_pattern() cannot be used here, because we cannot rely on the
+    urlpattern having regex or name attributes.
+    """
+    if isinstance(pattern, str):
+        hint = (
+            f"Try removing the string '{pattern}'. The list of urlpatterns should not "
+            "have a prefix string as the first element."
+        )
+    elif isinstance(pattern, tuple):
+        hint = "Try using path() instead of a tuple."
+    else:
+        hint = None
+
+    return [
+        Error(
+            "Your URL pattern {!r} is invalid. Ensure that urlpatterns is a list "
+            "of path() and/or re_path() instances.".format(pattern),
+            hint=hint,
+            id="urls.E004",
+        )
+    ]
+
+
+@register
+def check_url_settings(package_configs, **kwargs):
+    errors = []
+    for name in ("ASSETS_URL",):
+        value = getattr(settings, name)
+        if value and not value.endswith("/"):
+            errors.append(E006(name))
+    return errors
+
+
+def E006(name):
+    return Error(
+        f"The {name} setting must end with a slash.",
+        id="urls.E006",
+    )

plain/runtime/README.md

@@ -0,0 +1,75 @@
+# Runtime
+
+Leverage user-settings at runtime.
+
+## Settings
+
+### Single-file
+
+All of your settings go in `app/settings.py`.
+That's how you do it!
+
+The file itself is not much different than how Django does it,
+but the location,
+and a strong recommendation to only use the one file makes a big difference.
+
+### Environment variables
+
+It seems pretty well-accepted these days that storing settings in env vars is a good idea ([12factor.net](https://12factor.net/config)).
+
+Your settings file should be looking at the environment for secrets or other values that might change between environments. For example:
+
+```python
+# app/settings.py
+STRIPE_SECRET_KEY = environ["STRIPE_SECRET_KEY"]
+```
+
+#### Local development
+
+In local development,
+you should use `.env` files to set these values.
+The `.env` should then be in your `.gitignore`!
+
+It would seem like `.env.dev` would be a good idea,
+but there's a chicken-and-egg problem with that.
+You would then have to prefix most (or all) of your local commands with `PLAIN_ENV=dev` or otherwise configure your environment to do that for you.
+Generally speaking,
+a production `.env` shouldn't be committed in your repo anyway,
+so using `.env` for local development is ok.
+The downside to this is that it's harder to share your local settings with others,
+but these also often contain real secrets which shouldn't be committed to your repo either!
+More advanced `.env` sharing patterns are currently beyond the scope of Plain...
+
+#### Production
+
+TODO
+
+## Minimum required settings
+
+```python
+# SECURITY WARNING: keep the secret key used in production secret!
+SECRET_KEY = environ["SECRET_KEY"]
+
+# SECURITY WARNING: don't run with debug turned on in production!
+DEBUG = environ.get("DEBUG", "false").lower() in ("true", "1", "yes")
+
+MIDDLEWARE = [
+    "plain.middleware.security.SecurityMiddleware",
+    "plain.assets.whitenoise.middleware.WhiteNoiseMiddleware",
+    "plain.sessions.middleware.SessionMiddleware",
+    "plain.middleware.common.CommonMiddleware",
+    "plain.csrf.middleware.CsrfViewMiddleware",
+    "plain.auth.middleware.AuthenticationMiddleware",
+    "plain.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+if DEBUG:
+    INSTALLED_PACKAGES += [
+        "plain.dev",
+    ]
+    MIDDLEWARE += [
+        "plain.dev.RequestsMiddleware",
+    ]
+
+TIME_ZONE = "America/Chicago"
+```

plain/runtime/__init__.py

@@ -0,0 +1,61 @@
+import importlib.metadata
+import sys
+from os import environ
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from .user_settings import LazySettings
+
+try:
+    __version__ = importlib.metadata.version("plainframework")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "dev"
+
+
+# Made available without setup or settings
+APP_PATH = Path.cwd() / "app"
+
+
+# from plain.runtime import settings
+settings = LazySettings()
+
+
+class AppPathNotFound(RuntimeError):
+    pass
+
+
+def setup():
+    """
+    Configure the settings (this happens as a side effect of accessing the
+    first setting), configure logging and populate the app registry.
+    """
+    from plain.logs import configure_logging
+    from plain.packages import packages
+
+    if not APP_PATH.exists():
+        raise AppPathNotFound(
+            "No app directory found. Are you sure you're in a Plain project?"
+        )
+
+    # Automatically put the app dir on the Python path for convenience
+    if APP_PATH not in sys.path:
+        sys.path.insert(0, APP_PATH.as_posix())
+
+    # Load .env files automatically before settings
+    if app_env := environ.get("PLAIN_ENV", ""):
+        load_dotenv(f".env.{app_env}")
+    else:
+        load_dotenv(".env")
+
+    configure_logging(settings.LOGGING)
+
+    packages.populate(settings.INSTALLED_PACKAGES)
+
+
+__all__ = [
+    "setup",
+    "settings",
+    "APP_PATH",
+    "__version__",
+]

plain/runtime/global_settings.py

@@ -0,0 +1,199 @@
+"""
+Default Plain settings. Override these with settings in the module pointed to
+by the PLAIN_SETTINGS_MODULE environment variable.
+"""
+from pathlib import Path
+
+from plain.runtime import APP_PATH as default_app_path
+
+####################
+# CORE             #
+####################
+
+DEBUG: bool = False
+
+PLAIN_TEMP_PATH: Path = default_app_path.parent / ".plain"
+
+# Hosts/domain names that are valid for this site.
+# "*" matches anything, ".example.com" matches example.com and all subdomains
+ALLOWED_HOSTS: list[str] = []
+
+# Local time zone for this installation. All choices can be found here:
+# https://en.wikipedia.org/wiki/List_of_tz_zones_by_name (although not all
+# systems may support all possibilities). When USE_TZ is True, this is
+# interpreted as the default user time zone.
+TIME_ZONE = "America/Chicago"
+
+# If you set this to True, Plain will use timezone-aware datetimes.
+USE_TZ = True
+
+# Default charset to use for all Response objects, if a MIME type isn't
+# manually specified. It's used to construct the Content-Type header.
+DEFAULT_CHARSET = "utf-8"
+
+# List of strings representing installed packages.
+INSTALLED_PACKAGES: list = []
+
+# Whether to append trailing slashes to URLs.
+APPEND_SLASH = True
+
+# A secret key for this particular Plain installation. Used in secret-key
+# hashing algorithms. Set this in your settings, or Plain will complain
+# loudly.
+SECRET_KEY: str
+
+# List of secret keys used to verify the validity of signatures. This allows
+# secret key rotation.
+SECRET_KEY_FALLBACKS: list[str] = []
+
+ROOT_URLCONF = "urls"
+
+# List of upload handler classes to be applied in order.
+FILE_UPLOAD_HANDLERS = [
+    "plain.internal.files.uploadhandler.MemoryFileUploadHandler",
+    "plain.internal.files.uploadhandler.TemporaryFileUploadHandler",
+]
+
+# Maximum size, in bytes, of a request before it will be streamed to the
+# file system instead of into memory.
+FILE_UPLOAD_MAX_MEMORY_SIZE = 2621440  # i.e. 2.5 MB
+
+# Maximum size in bytes of request data (excluding file uploads) that will be
+# read before a SuspiciousOperation (RequestDataTooBig) is raised.
+DATA_UPLOAD_MAX_MEMORY_SIZE = 2621440  # i.e. 2.5 MB
+
+# Maximum number of GET/POST parameters that will be read before a
+# SuspiciousOperation (TooManyFieldsSent) is raised.
+DATA_UPLOAD_MAX_NUMBER_FIELDS = 1000
+
+# Maximum number of files encoded in a multipart upload that will be read
+# before a SuspiciousOperation (TooManyFilesSent) is raised.
+DATA_UPLOAD_MAX_NUMBER_FILES = 100
+
+# Directory in which upload streamed files will be temporarily saved. A value of
+# `None` will make Plain use the operating system's default temporary directory
+# (i.e. "/tmp" on *nix systems).
+FILE_UPLOAD_TEMP_DIR = None
+
+# The numeric mode to set newly-uploaded files to. The value should be a mode
+# you'd pass directly to os.chmod; see
+# https://docs.python.org/library/os.html#files-and-directories.
+FILE_UPLOAD_PERMISSIONS = 0o644
+
+# The numeric mode to assign to newly-created directories, when uploading files.
+# The value should be a mode as you'd pass to os.chmod;
+# see https://docs.python.org/library/os.html#files-and-directories.
+FILE_UPLOAD_DIRECTORY_PERMISSIONS = None
+
+# Default X-Frame-Options header value
+X_FRAME_OPTIONS = "DENY"
+
+USE_X_FORWARDED_HOST = False
+USE_X_FORWARDED_PORT = False
+
+# User-defined overrides for error views by status code
+HTTP_ERROR_VIEWS: dict[int] = {}
+
+# If your Plain app is behind a proxy that sets a header to specify secure
+# connections, AND that proxy ensures that user-submitted headers with the
+# same name are ignored (so that people can't spoof it), set this value to
+# a tuple of (header_name, header_value). For any requests that come in with
+# that header/value, request.is_secure() will return True.
+# WARNING! Only set this if you fully understand what you're doing. Otherwise,
+# you may be opening yourself up to a security risk.
+SECURE_PROXY_SSL_HEADER = None
+
+##############
+# MIDDLEWARE #
+##############
+
+# List of middleware to use. Order is important; in the request phase, these
+# middleware will be applied in the order given, and in the response
+# phase the middleware will be applied in reverse order.
+MIDDLEWARE = [
+    "plain.middleware.security.SecurityMiddleware",
+    "plain.assets.whitenoise.middleware.WhiteNoiseMiddleware",
+    "plain.middleware.common.CommonMiddleware",
+    "plain.csrf.middleware.CsrfViewMiddleware",
+    "plain.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+###########
+# SIGNING #
+###########
+
+SIGNING_BACKEND = "plain.signing.TimestampSigner"
+
+########
+# CSRF #
+########
+
+# Settings for CSRF cookie.
+CSRF_COOKIE_NAME = "csrftoken"
+CSRF_COOKIE_AGE = 60 * 60 * 24 * 7 * 52
+CSRF_COOKIE_DOMAIN = None
+CSRF_COOKIE_PATH = "/"
+CSRF_COOKIE_SECURE = False
+CSRF_COOKIE_HTTPONLY = False
+CSRF_COOKIE_SAMESITE = "Lax"
+CSRF_HEADER_NAME = "HTTP_X_CSRFTOKEN"
+CSRF_TRUSTED_ORIGINS: list[str] = []
+CSRF_USE_SESSIONS = False
+
+###########
+# LOGGING #
+###########
+
+# Custom logging configuration.
+LOGGING = {}
+
+###############
+# ASSETS #
+###############
+
+ASSETS_BACKEND = "plain.assets.whitenoise.storage.CompressedManifestStaticFilesStorage"
+
+# List of finder classes that know how to find assets files in
+# various locations.
+ASSETS_FINDERS = [
+    "plain.assets.finders.FileSystemFinder",
+    "plain.assets.finders.PackageDirectoriesFinder",
+]
+
+# Absolute path to the directory assets files should be collected to.
+# Example: "/var/www/example.com/assets/"
+ASSETS_ROOT = PLAIN_TEMP_PATH / "assets_collected"
+
+# URL that handles the assets files served from ASSETS_ROOT.
+# Example: "http://example.com/assets/", "http://assets.example.com/"
+ASSETS_URL = "/assets/"
+
+####################
+# PREFLIGHT CHECKS #
+####################
+
+# List of all issues generated by system checks that should be silenced. Light
+# issues like warnings, infos or debugs will not generate a message. Silencing
+# serious issues like errors and criticals does not result in hiding the
+# message, but Plain will not stop you from e.g. running server.
+SILENCED_PREFLIGHT_CHECKS = []
+
+#######################
+# SECURITY MIDDLEWARE #
+#######################
+SECURE_CONTENT_TYPE_NOSNIFF = True
+SECURE_CROSS_ORIGIN_OPENER_POLICY = "same-origin"
+SECURE_HSTS_INCLUDE_SUBDOMAINS = False
+SECURE_HSTS_PRELOAD = False
+SECURE_HSTS_SECONDS = 0
+SECURE_REDIRECT_EXEMPT = []
+SECURE_REFERRER_POLICY = "same-origin"
+SECURE_SSL_HOST = None
+SECURE_SSL_REDIRECT = False
+
+#############
+# Templates #
+#############
+
+JINJA_LOADER = "jinja2.loaders.FileSystemLoader"
+JINJA_ENVIRONMENT = "plain.templates.jinja.defaults.create_default_environment"