stapel-forms 0.2.0__py3-none-any.whl

stapel_forms/CONFIG.MD

@@ -0,0 +1,81 @@
+# CONFIG.MD — stapel-forms
+
+Config registry for **stapel-forms** (`static-scaffold-and-config.md` §2).
+One row per configuration key the module reads, its **source** (`env` = the
+process environment / the `STAPEL_FORMS` settings dict), what it is for,
+whether it is required, and its default.
+
+All keys are read through `forms_settings`
+(`stapel_forms.conf.AppSettings`, namespace `STAPEL_FORMS`).
+Resolution order per key: `settings.STAPEL_FORMS` dict → a flat Django
+setting of the same name → environment variable → the default below.
+There are no `import_strings` keys in this module.
+
+## stapel-forms
+
+### Schema surface (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| FIELD_KINDS | env | allowlist of stapel-attributes kinds a form schema may use. A kind registered in the attributes registry but absent here cannot be asked on a public URL. Kinds implying binary payloads are absent by construction — there is no anonymous attachment path (check `stapel_forms.E001` refuses kinds nothing answers for; `E002` refuses an empty list). | no | the ten builtins: string, int, float, bool, select, date, header, hex_color, hierarchical_select, convertible_unit |
+| MAX_FIELDS_PER_FORM | env | ceiling on fields in a published version; also bounds the CSV column count. | no | 64 |
+
+### Abuse ladder (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| MAX_SUBMISSION_BYTES | env | `Content-Length` gate applied BEFORE the JSON parse; over it is 413 `error.413.forms_body_too_large`. 0 disables. | no | 65536 |
+| MAX_SUBMISSIONS_PER_FORM | env | per-form row cap bounding what one leaked public link can cost; past it the submit answers 409 `error.409.forms_submission_cap`. 0 disables. | no | 10000 |
+| MAX_OPEN_FORMS_PER_WORKSPACE | env | ceiling on simultaneously open forms in one workspace. 0 disables. | no | 100 |
+| SUBMIT_THROTTLE | env | DRF scoped rate for the anonymous submit, per client IP (netintel-resolved, never raw XFF). A library cannot own `DEFAULT_THROTTLE_RATES`, so the rate lives here. `None` disables — a conscious act. | no | 20/h |
+| PUBLIC_SCHEMA_THROTTLE | env | same, for the anonymous schema fetch — the enumeration backstop. `None` disables. | no | 120/h |
+| ALLOW_UNCAPTCHAED_PUBLIC | env | the confession switch. Off: a deployment with an open public form and no `STAPEL_CAPTCHA["SECRET"]` gets `stapel_forms.W001`. On: the warning is silenced because the host says the refusal is deliberate. | no | False |
+
+### Respondent privacy (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| STORE_CLIENT_META | env | persist the respondent's IP and user-agent on each submission. Off: nothing needs them on disk — throttling and netintel classification work off the live request and the cache. On: that data falls under the same retention clock as the answers. | no | False |
+| RETENTION_DAYS | env | how long a response lives before the purge destroys it. A per-form `settings.retention_days` may only SHORTEN this; lengthening past the ceiling requires raising it here, so one form cannot rewrite the deployment's promise. `None` keeps answers forever — an explicit host decision. | no | 365 |
+| PURGE_SCHEDULE | env | crontab kwargs for the retention beat entry (`get_forms_beat_schedule()`). Cadence is configuration, not a literal. | no | {"hour": 4, "minute": 40} |
+
+### Notifications (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| NOTIFY_COOLDOWN_SECONDS | env | minimum gap between auto-notify letters for one form; submissions inside the window fold into the next letter as a count. Keyed on the form, not the caller — the protected resource is the owner's inbox. Admin-initiated resend is deliberately NOT subject to it. 0 notifies every time. | no | 600 |
+
+### Versioning (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| ACCEPT_PREVIOUS_VERSION_SECONDS | env | grace window during which a submit naming the previous version is still accepted after a publish. 0 (strict) refuses it wholesale with 409 `error.409.forms_version_superseded`, so the renderer refetches and tells the respondent rather than half-validating against a schema they never saw. | no | 0 |
+
+### Response review (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| MAX_PAGE_SIZE | env | service-side cap on `?limit=` for the keyset response listing. | no | 100 |
+| EXPORT_PAGE_SIZE | env | rows per CSV export request; the continuation cursor comes back in the `X-Forms-Next-Before` header rather than materializing the whole table. | no | 1000 |
+
+## Keys this module READS from other namespaces
+
+| Key | Owner | Why it matters here |
+|-----|-------|---------------------|
+| STAPEL_CAPTCHA["SECRET"] | stapel-core | with no backend configured the captcha verifier is a no-op and every bot that finds a public link is accepted; `stapel_forms.W001` says so. |
+| STAPEL_WORKSPACES["ROLES"] | stapel-workspaces | grants `forms.*` to roles. Without a grant every admin request denies; only `owner` has `*` by default. An entry REPLACES a whole role — there is no deep merge. |
+| STAPEL_GDPR["DATA_OWNERS"] | stapel-gdpr | must include `"forms"`, or the erasure closure never completes (`gdpr.E002`; `stapel_forms.W003` warns from this side). |
+| STAPEL_NOTIFICATIONS["TYPES"] | stapel-notifications | the host-side bridge for `forms.submission_received` / `forms.submission_resend` until the upstream `NOTIFICATION_ROUTING` entries land. See MODULE.md §9. |
+| CELERY_BEAT_SCHEDULE | the host | must contain an entry whose `task` is `stapel_forms.tasks.purge_expired_submissions`, or retention never runs (`stapel_forms.W002`). |
+| DATA_PLANE_APPS | the host | isolation-tier hosts list `forms`. No schema impact. |
+
+## Per-form settings (not deployment config)
+
+`Form.settings` is a JSON blob on the row, edited over the API, not a Django
+setting. Recognized keys:
+
+| Key | Purpose |
+|-----|---------|
+| notify_emails | `[str]` — email destinations for the auto-notify and resend. |
+| notify_telegram_chat_ids | `[str]` — telegram chat destinations (no account behind them; stapel-core 0.31 `telegram_chat_id`). |
+| retention_days | `int` — shortens this form's retention below `RETENTION_DAYS`. Lengthening past the module ceiling is refused with `error.400.forms_invalid_retention`. |

stapel_forms/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-forms — admin-defined forms, anonymous submissions, response review.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``forms_settings`` — resolved app settings (``stapel_forms.conf``).
+"""
+
+__all__ = [
+    "forms_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_forms` stays Django-free.
+_LAZY_EXPORTS = {
+    "forms_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_forms/_capabilities.py

@@ -0,0 +1,48 @@
+"""stapel-forms capabilities.json emitter — thin shim over stapel_tools.capabilities."""
+from pathlib import Path
+
+from stapel_tools.capabilities import axis_group_rules, run_capabilities_cli
+
+
+def main(argv=None):
+    from stapel_forms._codegen import _configure
+
+    _configure()
+    from stapel_forms.conf import DEFAULTS
+    from stapel_forms.urls_v1 import GATE_REGISTRY
+
+    # The CTO-facing axes are the ones that change what the PRODUCT is
+    # allowed to do, not how fast it runs: which field kinds a form may
+    # use, whether respondent IPs are stored, how long answers are kept,
+    # and whether public forms may run without a captcha. Throttle rates,
+    # page sizes, cooldown seconds and the caps are tuning — they bound
+    # abuse, they do not change the deal with the respondent.
+    axes = {
+        "FIELD_KINDS",
+        "STORE_CLIENT_META",
+        "RETENTION_DAYS",
+        "ALLOW_UNCAPTCHAED_PUBLIC",
+        "ACCEPT_PREVIOUS_VERSION_SECONDS",
+    }
+    return run_capabilities_cli(
+        argv,
+        repo=Path(__file__).resolve().parent,
+        canonical_prefix="/forms/api/v1",
+        defaults=DEFAULTS,
+        registry=GATE_REGISTRY,
+        is_axis=lambda k: k in axes,
+        axis_group=axis_group_rules(
+            exact={
+                "FIELD_KINDS": "forms.schema",
+                "STORE_CLIENT_META": "forms.privacy",
+                "RETENTION_DAYS": "forms.privacy",
+                "ALLOW_UNCAPTCHAED_PUBLIC": "forms.public",
+                "ACCEPT_PREVIOUS_VERSION_SECONDS": "forms.public",
+            }
+        ),
+        prog="stapel-forms-capabilities",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_forms/_codegen.py

@@ -0,0 +1,117 @@
+"""stapel-forms contract-emission harness (contract-pipeline.md §2-3).
+
+Emits the module's own contract triad into ``docs/`` from a single-module
+``{forms + core}`` Django instance mounted at the canonical ``/forms/api/v1``
+prefix:
+
+  docs/schema.json   drf-spectacular OpenAPI, this module only, canonical prefix
+  docs/flows.json    generate_flow_docs machine artifact
+  docs/errors.json   generate_error_keys registry (the per-module etalon)
+
+stapel-forms is not mounted in stapel-example-monolith, so there is no
+aggregate slice to diff against for byte-identity — validation is
+standalone (determinism + closure + canonical prefix), see
+``tests/test_contract.py``.
+
+Usage:
+    python -m stapel_forms._codegen --out docs        # `make contract`
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _configure() -> None:
+    """Configure + boot the single-module Django instance for emission."""
+    # `python -m` prepends cwd to sys.path; strip the repo root the way a
+    # flat-layout conftest does, so `import forms`-shaped collisions cannot
+    # shadow anything.
+    repo_root = os.path.dirname(os.path.abspath(__file__))
+    sys.path[:] = [p for p in sys.path if os.path.abspath(p or os.getcwd()) != repo_root]
+
+    from django.conf import settings
+
+    if not settings.configured:
+        from stapel_forms._codegen_settings import settings_kwargs
+
+        settings.configure(
+            **settings_kwargs(root_urlconf="stapel_forms.codegen_urls", contract=True)
+        )
+
+    import django
+
+    django.setup()
+
+    # drf-spectacular froze its settings singleton at import time (before
+    # configure() ran), so it is on drf defaults. The one knob to force is
+    # SCHEMA_PATH_PREFIX: left None, drf derives the operationId prefix
+    # from the common path of all endpoints — "/" across a multi-module
+    # aggregate but "/forms/api" in a single-module harness, which would
+    # strip it to bare anonymous names. Pin it to the aggregate convention.
+    from drf_spectacular.settings import spectacular_settings
+
+    from stapel_forms._codegen_settings import CODEGEN_SCHEMA_PATH_PREFIX
+
+    spectacular_settings.SCHEMA_PATH_PREFIX = CODEGEN_SCHEMA_PATH_PREFIX
+
+    # A real all-modules deployment registers drf-spectacular's JWT-cookie
+    # security-scheme extension as a side effect of its dev-only Swagger
+    # URLs. A single-module harness has no co-mounted sibling to trigger
+    # it, so without this the protected endpoints would emit without their
+    # `security` entry.
+    from stapel_core.django.openapi.swagger import _register_jwt_auth_extension
+
+    _register_jwt_auth_extension()
+
+
+def _require_python_312() -> None:
+    """Abort emission if not running the pinned 3.12 interpreter.
+
+    drf-spectacular renders component descriptions (``Optional[X]`` vs
+    ``X | None``) differently across Python minor versions, so emitting on
+    anything but the CI/monolith pin produces false diffs against the
+    committed docs/*.json.
+    """
+    if sys.version_info[:2] != (3, 12):
+        got = f"{sys.version_info.major}.{sys.version_info.minor}"
+        raise SystemExit(
+            f"stapel-forms contract emission ABORTED: running Python {got}, "
+            "but contracts must be emitted on Python 3.12 (the CI/monolith pin). "
+            "Re-run under a 3.12 interpreter."
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    _require_python_312()
+
+    parser = argparse.ArgumentParser(
+        prog="stapel-forms-contract",
+        description="Emit this module's contract triad (schema.json + flows.json "
+        "+ errors.json) into --out, canonical /forms/api/v1 prefix.",
+    )
+    parser.add_argument("--out", default="docs", help="Output directory (default: docs).")
+    args = parser.parse_args(argv)
+
+    _configure()
+
+    from stapel_tools.codegen import emit_errors, emit_flows, emit_schema
+
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    paths = emit_schema(out / "schema.json")
+    flows = emit_flows(out / "flows.json")
+    errors = emit_errors(out / "errors.json")
+
+    print(
+        f"stapel-forms contract: {paths} paths, {flows} flows, {errors} error keys "
+        f"-> {out}/",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_forms/_codegen_settings.py

@@ -0,0 +1,108 @@
+"""Single-module Django settings for stapel-forms.
+
+One ``settings.configure(...)`` block serves three callers, which is the
+point: the test suite, the contract-emission harness and the capabilities
+emitter cannot drift apart if there is nothing to drift.
+
+  - ``conftest.py`` — the bare test mount (``stapel_forms.tests.urls``);
+  - ``_codegen.py`` / ``make contract`` — the CANONICAL mount
+    (``stapel_forms.codegen_urls`` → ``forms/``; the module's own
+    ``urls.py`` bakes the ``api/v1`` segment in, so the full public prefix
+    is ``/forms/api/v1``), plus drf-spectacular and the production
+    ``REST_FRAMEWORK`` block so the emitted schema matches what a real
+    deployment serves;
+  - ``_capabilities.py``, which reuses ``_codegen._configure``.
+
+``SPECTACULAR_SETTINGS`` is deliberately not set: drf-spectacular builds
+its settings singleton at import time, before a ``configure()``-based
+harness can populate it, so the emitter runs on drf defaults — the state
+every other pair-backend's harness emits under. The one knob that must
+still be forced, ``SCHEMA_PATH_PREFIX``, is patched on the singleton
+directly by the harness.
+"""
+from __future__ import annotations
+
+
+def settings_kwargs(
+    *,
+    root_urlconf: str = "stapel_forms.tests.urls",
+    contract: bool = False,
+) -> dict:
+    """The ``settings.configure(**kwargs)`` for a single-module forms instance."""
+    if contract:
+        # Mirror stapel_core.django.settings.REST_FRAMEWORK exactly (the
+        # config a real deployment emits under). Inlined, not imported, to
+        # dodge the import-time settings read.
+        rest_framework = {
+            "DEFAULT_AUTHENTICATION_CLASSES": [
+                "stapel_core.django.jwt.authentication.JWTCookieAuthentication",
+            ],
+            "DEFAULT_PERMISSION_CLASSES": [
+                "stapel_core.django.api.permissions.IsServiceRequest",
+                "stapel_core.django.api.permissions.IsSuperUser",
+            ],
+            "DEFAULT_RENDERER_CLASSES": [
+                "rest_framework.renderers.JSONRenderer",
+                "rest_framework.renderers.BrowsableAPIRenderer",
+            ],
+            "DEFAULT_SCHEMA_CLASS": "stapel_core.django.openapi.schemas.PermissionAwareAutoSchema",
+            "EXCEPTION_HANDLER": "stapel_core.django.api.errors.stapel_exception_handler",
+        }
+    else:
+        rest_framework = None
+
+    kwargs = dict(
+        SECRET_KEY="test-secret-key-not-for-production",
+        INSTALLED_APPS=[
+            "django.contrib.contenttypes",
+            "django.contrib.auth",
+            "django.contrib.sessions",
+            "django.contrib.admin",
+            "django.contrib.messages",
+            "stapel_core.django.apps.CommonDjangoConfig",
+            "stapel_core.django.users",
+            "rest_framework",
+            "drf_spectacular",
+            "stapel_forms",
+        ],
+        AUTH_USER_MODEL="users.User",
+        DATABASES={
+            "default": {
+                "ENGINE": "django.db.backends.sqlite3",
+                "NAME": ":memory:",
+            }
+        },
+        DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+        USE_TZ=True,
+        ROOT_URLCONF=root_urlconf,
+        CACHES={
+            "default": {
+                "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+            }
+        },
+        # Synchronous in-process comm with schema validation ON, so the
+        # committed contracts in schemas/ are enforced by the tests.
+        STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+        STAPEL_COMM={
+            "OUTBOX_ENABLED": False,
+            "ACTION_TRANSPORT": "inprocess",
+            "VALIDATE_SCHEMAS": True,
+            # An emit outside a transaction is a bug here, not a warning:
+            # the outbox canon is what makes "the row exists" and "the fact
+            # was announced" one decision.
+            "EMIT_OUTSIDE_ATOMIC": "error",
+        },
+        MIGRATION_MODULES={
+            "users": None,
+        },
+    )
+    if rest_framework is not None:
+        kwargs["REST_FRAMEWORK"] = rest_framework
+    return kwargs
+
+
+# The multi-module common path prefix drf-spectacular auto-detects when
+# every pair-backend's schema is emitted inside an all-modules aggregate.
+# Forced on the singleton by the harness so a single-module instance
+# derives the same operationIds.
+CODEGEN_SCHEMA_PATH_PREFIX = "/"

stapel_forms/actions.py

@@ -0,0 +1,51 @@
+"""Action subscriptions of stapel-forms.
+
+Handlers are idempotent-minded (delivery is at-least-once — outbox retries,
+broker redelivery). Transport is chosen by ``STAPEL_COMM`` (in-process in a
+monolith, bus consumer in microservices); the handler code is identical.
+
+Two consumers:
+
+- ``user.deleted`` → the GDPR provider's erasure of an authenticated
+  respondent's answers;
+- this module's OWN ``form.submission.received`` → the notify subscriber.
+  Reacting to our own event rather than calling the notifier inline is
+  what makes the auto-notify survive the transaction: the row is committed
+  before anybody is told about it, and a notification service outage can
+  never roll back a respondent's answer.
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+from .events import FORM_SUBMISSION_RECEIVED
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase a user's form answers (GDPR Art. 17)."""
+    from .gdpr import FormsGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    FormsGDPRProvider().delete(user_id)
+
+
+@on_action(FORM_SUBMISSION_RECEIVED)
+def handle_submission_received(event):
+    """Notify the form's configured recipients, behind the cooldown."""
+    from .models import Form
+    from .notifications import notify_submission_received
+
+    form_id = event.payload.get("form_id")
+    form = Form.objects.filter(id=form_id).first()
+    if form is None:
+        return
+    notify_submission_received(form)
+
+
+__all__ = ["handle_user_deleted", "handle_submission_received"]

stapel_forms/admin.py

@@ -0,0 +1,44 @@
+"""Admin for stapel-forms — an operator peephole, nothing more.
+
+Read-only across the board. Workspace admins are not Django staff: in a
+multi-tenant product the people who author forms and review responses reach
+them through the capability-gated REST surface, never through here. What
+this registration is for is the operator looking at a support ticket.
+
+``Submission`` is ``@access.sensitive`` (models.py), so the staff mandate
+gates even this view at MID clearance — two independent doors, both shut by
+default.
+"""
+from django.contrib import admin
+
+from .models import Form, FormVersion, Submission
+
+
+class _ReadOnlyAdmin(admin.ModelAdmin):
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(Form)
+class FormAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "title", "workspace_id", "state", "deleted_at", "created_at")
+    list_filter = ("state",)
+    search_fields = ("id", "title", "workspace_id", "public_id")
+
+
+@admin.register(FormVersion)
+class FormVersionAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "form", "version", "published_at")
+    search_fields = ("id", "form__id")
+
+
+@admin.register(Submission)
+class SubmissionAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "form", "version", "submitted_at", "submitted_by", "erased_at")
+    search_fields = ("id", "form__id", "workspace_id")

stapel_forms/apps.py

@@ -0,0 +1,31 @@
+from django.apps import AppConfig
+
+
+class FormsConfig(AppConfig):
+    name = "stapel_forms"
+    label = "forms"
+    verbose_name = "Forms: admin-defined schemas, anonymous submissions, response review"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import-time side effects: system checks, error-key registration,
+        # comm providers. Keep each in its own module.
+        from . import checks  # noqa: F401
+        from . import errors  # noqa: F401
+        from . import functions  # noqa: F401
+
+        # Action subscriptions (in-process in a monolith, bus consumer in
+        # microservices — same code, transport chosen by STAPEL_COMM):
+        # user.deleted, plus this module's own submission event driving the
+        # notify subscriber.
+        from . import actions  # noqa: F401
+
+        # GDPR provider registration (monolith mode). Hosts must ALSO list
+        # "forms" in STAPEL_GDPR["DATA_OWNERS"] — registering without
+        # declaring is gdpr.E002, and the erasure closure never completes.
+        from stapel_core.gdpr import gdpr_registry
+
+        from .gdpr import FormsGDPRProvider
+
+        if FormsGDPRProvider().section not in gdpr_registry.sections:
+            gdpr_registry.register(FormsGDPRProvider())

stapel_forms/authz.py

@@ -0,0 +1,110 @@
+"""The single authorization choke point for the admin surface.
+
+Every access decision about a form or its responses routes through
+:func:`authorize` — there is no second read path. The public respondent
+endpoints (§5.1) are deliberately outside it: they are ``AllowAny`` by
+design and gated by the abuse ladder instead, which is why the public
+presenter is a dedicated envelope and not the admin one with fields
+dropped.
+
+``unavailable`` means the workspaces service rendered no verdict — callers
+answer 503, never 403 ("a routing 404 is not a verdict", stapel-core
+workspaces client canon).
+
+Known limitation, stated rather than papered over: on stapel-core 0.26
+``require_capability`` collapses "denied" and "peer unavailable" into the
+same ``None`` — it logs the outage and returns, so the branch below can
+only fire if a future core raises. Until that core PR lands, a workspaces
+outage renders 403 here, the same as in stapel-docs. The branch stays live
+because the fix belongs in core, not in a per-module workaround that would
+re-implement the capability call and its cache.
+
+The :class:`Principal` form is fixed on day 1 so anonymous-link style
+grants later are an additive branch, not a rewrite: ``user_id=None`` means
+no session at all; ``is_anonymous`` marks an anonymous ACCOUNT of the auth
+axis (which does have a user_id); ``link_token`` carries a presented bearer
+token, unused by the admin surface.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Optional
+from uuid import UUID
+
+logger = logging.getLogger(__name__)
+
+ALLOW = "allow"
+DENY = "deny"
+UNAVAILABLE = "unavailable"
+
+#: Actions and the workspace capability answering each.
+ACTION_CAPABILITIES = {
+    "view": "forms.view",
+    "manage": "forms.manage",
+    "responses.view": "forms.responses.view",
+    "responses.manage": "forms.responses.manage",
+}
+
+#: Declared in full on day 1 so host role overlays never have to migrate.
+#: There is deliberately no separate ``forms.responses.export``: an export
+#: is a read, and core's staff mandate grades view/add/change/delete only.
+CAPABILITIES = (
+    "forms.view",
+    "forms.manage",
+    "forms.responses.view",
+    "forms.responses.manage",
+)
+
+
+@dataclass(frozen=True)
+class Principal:
+    """Who is asking. Built by the view layer, consumed only here."""
+
+    user_id: Optional[UUID]
+    is_anonymous: bool = False
+    link_token: Optional[str] = None
+
+    @classmethod
+    def from_request(cls, request) -> "Principal":
+        user = getattr(request, "user", None)
+        user_id = getattr(user, "pk", None) if getattr(user, "is_authenticated", False) else None
+        is_anon = bool(getattr(user, "is_anonymous_account", False))
+        return cls(user_id=user_id, is_anonymous=is_anon, link_token=None)
+
+
+def authorize(*, workspace_id, principal: Principal, action: str) -> str:
+    """Decide *action* for *principal* on *workspace_id*.
+
+    Returns ``allow`` | ``deny`` | ``unavailable``.
+    """
+    if action not in ACTION_CAPABILITIES:
+        raise ValueError(f"unknown forms action: {action!r}")
+
+    if principal.user_id is not None:
+        from stapel_core.django.workspaces import (
+            WorkspaceLookupUnavailable,
+            require_capability,
+        )
+
+        try:
+            membership = require_capability(
+                workspace_id, principal.user_id, ACTION_CAPABILITIES[action]
+            )
+        except WorkspaceLookupUnavailable:
+            return UNAVAILABLE
+        if membership is not None:
+            return ALLOW
+
+    return DENY
+
+
+__all__ = [
+    "ALLOW",
+    "DENY",
+    "UNAVAILABLE",
+    "ACTION_CAPABILITIES",
+    "CAPABILITIES",
+    "Principal",
+    "authorize",
+]