velocity-python 0.2.7__tar.gz → 0.2.9__tar.gz

{velocity_python-0.2.7/src/velocity_python.egg-info → velocity_python-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.2.7
+Version: 0.2.9
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -267,7 +267,6 @@ What changed in each release, and what callers must do before upgrading, is in
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |
 | Security | `docs/SECURITY.md` | Pre-commit hooks, credential scanning |
 | Changelog | `CHANGELOG.md` | Per-release breaking changes, deploy ordering, additions and fixes |
-| Improvement Backlog | `docs/IMPROVEMENT_BACKLOG.md` | Proposed and deferred library improvements |
 
 ---
 

{velocity_python-0.2.7 → velocity_python-0.2.9}/README.md

@@ -174,7 +174,6 @@ What changed in each release, and what callers must do before upgrading, is in
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |
 | Security | `docs/SECURITY.md` | Pre-commit hooks, credential scanning |
 | Changelog | `CHANGELOG.md` | Per-release breaking changes, deploy ordering, additions and fixes |
-| Improvement Backlog | `docs/IMPROVEMENT_BACKLOG.md` | Proposed and deferred library improvements |
 
 ---
 

{velocity_python-0.2.7 → velocity_python-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.2.7"
+version = "0.2.9"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.2.7"
+__version__ = version = "0.2.9"
 
 import importlib as _importlib
 

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity/aws/authz.py

@@ -935,6 +935,33 @@ def is_protected(table_name):
     return table_name in _PROTECTED
 
 
+# Tables whose rows are confidential (the security audit: everyone's sign-ins,
+# addresses, refusals). The generic Data actions READ them only on a handler
+# that lists the table in ``confidential_reads`` (an explicit opt-in, e.g. an
+# operators-only console), in every mode: ``gate`` records nothing, so even a
+# permitted read there would be unaudited.
+_CONFIDENTIAL = set()
+
+
+def confidential_tables(*names):
+    """Mark tables generic Data reads refuse unless the handler opts in (see
+    ``DataServiceMixin.confidential_reads``), whatever ``authz_mode`` says.
+    Combine with :func:`protect_tables` to refuse writes as well."""
+    _CONFIDENTIAL.update(name for name in names if isinstance(name, str) and name)
+
+
+def is_confidential(table_name):
+    return table_name in _CONFIDENTIAL
+
+
+# velocity's own audit sink (capabilities.security.EVENTS_TABLE): append-only
+# and confidential on every site, registered here so the rule never depends on
+# which modules a handler happened to import (VelocityAudit SEC-12 follow-up).
+SECURITY_EVENTS_TABLE = "sys_security_events"
+protect_tables(SECURITY_EVENTS_TABLE)
+confidential_tables(SECURITY_EVENTS_TABLE)
+
+
 # ── the action index ───────────────────────────────────────────────────────
 
 # id(rules tuple) -> (the tuple, {key: its rules in order}), where key is the
@@ -1319,6 +1346,15 @@ def _describe(resource):
     return f"{resource.type}:{resource.id}"
 
 
+def record_confidential_read(handler, tx, context, table):
+    """Record one generic read of a confidential table by a handler that opted
+    in (``confidential_reads``) as ``privileged_access``; False when it could
+    not be recorded (the caller refuses the read). The opt-in serves an
+    operators-only console; every use of it is still on the record."""
+    decision = Decision(True, rule="confidential_reads", audit=True, action=DATA_READ)
+    return bool(_record(handler, tx, context, decision, Resource(TABLE, table)))
+
+
 def _record(handler, tx, context, decision, resource):
     # imported here: the capabilities package pulls in more than a pure
     # decision module should load at import
@@ -1330,6 +1366,16 @@ def _record(handler, tx, context, decision, resource):
         if isinstance(session.get("masquerade"), dict)
         else None
     ) or session.get("email_address")
+    # the subject API Gateway's authorizer verified (the real caller, also
+    # under masquerade), and its issuer, so the record names an identity and
+    # not only an email
+    sub = session.get("sub") or None
+    provider = session.get("authentication_provider")
+    issuer = session.get("iss") or (
+        "https://" + provider.split(",", 1)[0].strip()
+        if isinstance(provider, str) and provider.strip()
+        else None
+    )
     return record_event(
         tx,
         PRIVILEGED_ACCESS,
@@ -1337,4 +1383,6 @@ def _record(handler, tx, context, decision, resource):
         aws_event=getattr(handler, "aws_event", None),
         context=context,
         user_email=actor,
+        user_sub=sub,
+        detail={"iss": issuer} if issuer else None,
     )

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity/aws/capabilities/security.py

@@ -20,6 +20,15 @@ Attach :class:`SecurityMixin` FIRST in a handler's bases; it runs in
 ``beforeAction`` ahead of auth and every action, and is a no-op unless the
 site's ``sys_capabilities`` row for ``security`` is enabled. A refusal raises
 :class:`AccessError` (a 403) after committing a ``sys_security_events`` row.
+
+``sys_security_events`` itself is a CORE table (``SCHEMA``, in
+``velocity.aws.schema``'s ``core`` group), not the capability's: it is
+velocity's one audit sink — refusals, masquerade grants, sign-ins — and every
+site keeps it whether or not the guards are on (VelocityAudit SEC-12: with the
+table capability-owned, a site without ``security`` silently dropped its
+masquerade audit). Pruning stays here (``security_events_days``, default 365 to
+match a one-year audit retention); a site without the capability lists the
+table in the ``retention`` capability instead.
 """
 
 from __future__ import annotations
@@ -46,6 +55,48 @@ log = logging.getLogger(__name__)
 
 EVENTS_TABLE = "sys_security_events"
 RATE_TABLE = "sys_rate_limit"
+EVENT_COLUMNS = {
+    "guard": "TEXT",
+    "reason": "TEXT",
+    "ip": "TEXT",
+    "country": "TEXT",
+    "path": "TEXT",
+    "action": "TEXT",
+    "user_email": "TEXT",
+    "user_agent": "TEXT",
+    "user_sub": "TEXT",
+    "detail": "JSONB",
+    # when it happened (a sign-in trigger fired), which a queue can write
+    # later than sys_created; defaults to the time of writing
+    "occurred_at": "TIMESTAMPTZ",
+}
+# Append-only and confidential on every site: authz registers the table as
+# protected (no generic write) and confidential (generic reads need an opt-in
+# or enforce) itself, so the rule holds whether or not this module is imported.
+# core infrastructure (velocity.aws.schema "core"): every site has the table
+SCHEMA = {
+    EVENTS_TABLE: {
+        "columns": dict(EVENT_COLUMNS),
+        "indexes": [
+            {
+                "columns": ["sys_created"],
+                "name": "idx__sys_security_events__sys_created",
+            },
+            {
+                "columns": ["guard", "sys_created"],
+                "name": "idx__sys_security_events__guard",
+            },
+            {
+                "columns": ["user_sub", "sys_created"],
+                "name": "idx__sys_security_events__user_sub",
+            },
+            {
+                "columns": ["user_sub", "occurred_at"],
+                "name": "idx__sys_security_events__user_sub_occurred",
+            },
+        ],
+    },
+}
 CACHE_TTL_SECONDS = 60  # per-container cache of the switches + site row
 
 SWITCHES = {
@@ -59,7 +110,7 @@ SWITCHES = {
 KNOBS = {
     "security_rate_limit_per_minute": "120",
     "security_payload_max_bytes": "1000000",
-    "security_events_days": "90",
+    "security_events_days": "365",
 }
 
 
@@ -275,30 +326,62 @@ def enforce(tx, aws_event, context, *, now=None):
     return config
 
 
-def record_event(tx, guard, reason, *, aws_event=None, context=None, user_email=None):
+def record_event(
+    tx,
+    guard,
+    reason,
+    *,
+    aws_event=None,
+    context=None,
+    user_email=None,
+    user_sub=None,
+    detail=None,
+    occurred_at=None,
+):
     """Append one ``sys_security_events`` row and commit it — an audit row
     must survive whatever the caller does next (typically raise). The one
-    audit sink for the framework: the request guards, masquerade grants, and
-    anything else security-relevant write here. Silent when the table is not
-    provisioned in this site, and an audit failure never breaks the request.
-    Returns True when a row was written."""
+    audit sink for the framework: the request guards, masquerade grants,
+    sign-ins, and anything else security-relevant write here. ``user_sub`` is
+    the identity provider's subject; ``detail`` a JSON-able dict of facts that
+    have no column; ``occurred_at`` when it happened, if not now (an event
+    relayed through a queue). Silent when the table is not provisioned in this site, and
+    an audit failure never breaks the request. Returns True when a row was
+    written.
+
+    A table created before ``user_sub``/``detail`` existed (a site whose schema
+    lane has not run since) still records the row without them: on a locked
+    schema an unknown column would otherwise lose the whole event."""
     try:
         table = tx.table(EVENTS_TABLE)
         if not table.exists():
             return False
         facts = request_facts(aws_event)
-        table.insert(
-            {
-                "guard": guard,
-                "reason": reason,
-                "ip": facts["ip"],
-                "country": facts["country"],
-                "path": facts["path"],
-                "action": _action(context) if context is not None else "",
-                "user_email": user_email,
-                "user_agent": facts["user_agent"][:512],
-            }
-        )
+        row = {
+            "guard": guard,
+            "reason": reason,
+            "ip": facts["ip"],
+            "country": facts["country"],
+            "path": facts["path"],
+            "action": _action(context) if context is not None else "",
+            "user_email": user_email,
+            "user_agent": facts["user_agent"][:512],
+        }
+        extra = {
+            "user_sub": user_sub,
+            "detail": detail,
+            "occurred_at": occurred_at or datetime.datetime.now(datetime.timezone.utc),
+        }
+        extra = {k: v for k, v in extra.items() if v is not None}
+        if extra:
+            try:
+                have = {c.lower() for c in table.sys_columns()}
+            except Exception:
+                # can't tell which newer columns exist: the event still lands
+                # with the columns every version of the table has
+                log.warning("security event %s: columns unknown", guard, exc_info=True)
+                have = set()
+            row.update({k: v for k, v in extra.items() if k in have})
+        table.insert(row)
         tx.commit()
         return True
     except Exception:
@@ -386,16 +469,9 @@ class Security(Capability):
         ),
     )
     schema = {
-        EVENTS_TABLE: {
-            "guard": "TEXT",
-            "reason": "TEXT",
-            "ip": "TEXT",
-            "country": "TEXT",
-            "path": "TEXT",
-            "action": "TEXT",
-            "user_email": "TEXT",
-            "user_agent": "TEXT",
-        },
+        # the events table is core (module SCHEMA); listed here too so turning
+        # the capability on in an older site still ensures it
+        EVENTS_TABLE: dict(EVENT_COLUMNS),
         RATE_TABLE: {"bucket": "TEXT", "window_start": "TIMESTAMPTZ", "hits": "BIGINT"},
     }
     schedules = (("prune", HOURLY),)
@@ -407,7 +483,7 @@ class Security(Capability):
         if action != "prune":
             raise ValueError(f"security: unknown action {action!r}")
         now = datetime.datetime.now(datetime.timezone.utc)
-        days = int(config.get("security_events_days") or 90)
+        days = int(config.get("security_events_days") or 365)
         return {
             "rate_buckets": tx.table(RATE_TABLE).purge(
                 {"<sys_created": now - datetime.timedelta(hours=1)}

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity/aws/handlers/mixins/data_service.py

@@ -588,6 +588,7 @@ class ExportStream:
     def __enter__(self):
         handler, payload = self.handler, self.payload
         handler._assert_client_table(self.table, "obj")
+        handler._audit_confidential_read(self.tx, self.table, self.context)
         # ``table`` is the only source: it is what passed the table gate and
         # whose hooks and scope run below, so a payload ``obj`` naming any
         # other table is refused rather than read.
@@ -915,6 +916,11 @@ class DataServiceMixin:
     # handler, not in the gate methods' signatures, so a site's override of
     # those keeps working.
     _table_operation = authz.DATA_READ
+    # Confidential tables (``authz.confidential_tables``) this handler serves
+    # to generic reads: an explicit opt-in for a console whose every user is
+    # an operator. Without it such a table is never read through generic Data
+    # (in any authz mode); it is read through its own audited action.
+    confidential_reads = frozenset()
 
     def _client_table_allowed(self, table):
         # lower case only: velocity lower-cases every Table name and
@@ -937,10 +943,30 @@ class DataServiceMixin:
         # ``authz_mode`` say.
         if self._table_operation != authz.DATA_READ and authz.is_protected(table):
             return False
+        # Confidential tables (``authz.confidential_tables``: the security
+        # audit) are read through generic Data only where the handler opted
+        # in. Never by default, and not under ``enforce`` either: ``gate``
+        # answers allow/deny but records nothing, so a super user's read would
+        # go unaudited; the table's own action (``authz.require``) records it.
+        if authz.is_confidential(table) and table not in self.confidential_reads:
+            return False
         return authz.gate(
             self, self._table_operation, authz.Resource(authz.TABLE, table)
         )
 
+    def _audit_confidential_read(self, tx, table, context):
+        """A generic read of a confidential table (only reachable on a handler
+        that lists it in ``confidential_reads``) is recorded as privileged
+        access first, and refused when it can't be: the opt-in keeps an
+        operators' grid working without making its reads invisible. Called by
+        the read ACTIONS right after their table gate (query, read-object,
+        find-object, query-direct, export), never from an overridable seam,
+        so a site's hook override can't skip it."""
+        if not authz.is_confidential(table):
+            return
+        if not authz.record_confidential_read(self, tx, context, table):
+            raise AccessError("That access could not be recorded, so it was refused.")
+
     def _assert_client_table(self, table, label="table"):
         """The table gate every client action passes (SEC 4.2)."""
         ClientInputGuard.table_name(table, label)
@@ -1022,7 +1048,11 @@ class DataServiceMixin:
             if not info:
                 continue
             foreign = info["referenced_table_name"]
-            if not self._client_table_allowed(foreign):
+            # never into a confidential table: its reads are audited by the
+            # actions that open it by name, and a join would skip that
+            if authz.is_confidential(foreign) or not self._client_table_allowed(
+                foreign
+            ):
                 raise AlertError(f"Access to '{table}.{local}>' is not permitted.")
             # A join reads the foreign table's rows without that table's row
             # filter. So someone who reaches only part of it cannot read it
@@ -2053,6 +2083,7 @@ class DataServiceMixin:
         if not obj:
             raise ValueError("Parameter 'object' cannot be empty")
         self._assert_client_table(table_name, "tableName")
+        self._audit_confidential_read(tx, table_name, context)
         if not isinstance(obj, dict):
             raise BadRequestError("Parameter 'object' must be an object")
         if obj.get("sys_id") != NEW_ROW:
@@ -2094,6 +2125,7 @@ class DataServiceMixin:
         if not query or "where" not in query:
             raise ValueError("Parameter 'query' must contain 'where' clause")
         self._assert_client_table(table_name, "tableName")
+        self._audit_confidential_read(tx, table_name, context)
         query["where"] = self._client_where(tx, table_name, query["where"])
 
         row = self.find_hook(
@@ -2254,6 +2286,7 @@ class DataServiceMixin:
         if not table:
             raise ValueError("Parameter 'obj' cannot be empty")
         self._assert_client_table(table, "obj")
+        self._audit_confidential_read(tx, table, context)
         payload["params"] = self._client_query_params(tx, table, payload.get("params"))
 
         result_format = payload.get("result_format")
@@ -2438,6 +2471,7 @@ class DataServiceMixin:
 
         self._assert_direct_access_allowed(table_name)
         self._assert_direct_unscoped(table_name, context)
+        self._audit_confidential_read(tx, table_name, context)
 
         params = self._client_query_params(tx, table_name, payload.get("params", {}))
 

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity/aws/handlers/mixins/tiles_actions.py

@@ -112,6 +112,10 @@ class TilesMixin:
         rule with the viewer filled in, and that where."""
         table = tile["target"]
         self._assert_client_table(table, "target")
+        # A confidential table (the security audit) is never a tile target:
+        # a saved, re-counted filter over it would be an unaudited oracle.
+        if authz.is_confidential(table):
+            raise AlertError(f"'{table}' can't be counted on a tile.")
         rule = tiles.fill_rule(
             tiles.clean_rule(_as_dict(tile.get("rule"))),
             principal,
@@ -218,7 +222,10 @@ class TilesMixin:
             return declared is not None and (
                 not declared.permission or principal.holds(declared.permission)
             )
-        return bool(self._client_table_allowed(str(tile.get("target") or "")))
+        target = str(tile.get("target") or "")
+        if authz.is_confidential(target):
+            return False
+        return bool(self._client_table_allowed(target))
 
     def _tile_public(self, tx, context, tile, principal, today, fresh=False, version=0):
         """One tile as the browser gets it, or None when it is not this

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity/aws/schema.py

@@ -21,7 +21,8 @@ renames or retypes an existing column.
 
 Groups:
 
-* ``core`` — the tables every velocity handler app writes.
+* ``core`` — the tables every velocity handler app writes, including the
+  ``sys_security_events`` audit sink (SEC-12).
 * ``assets`` — ``images`` + ``asset_usage_index`` (:mod:`velocity.aws.assets`).
 * ``payment`` — processor mirror tables (:mod:`velocity.payment.schema`).
 * ``permissions`` — roles, grants and requests (:mod:`velocity.aws.permissions`).
@@ -50,6 +51,7 @@ SCHEMA_SOURCES: Dict[str, Tuple[str, ...]] = {
         "velocity.aws.handlers.mixins.web_handler",
         "velocity.aws.handlers.mixins.session_control",
         "velocity.aws.user_data",
+        "velocity.aws.capabilities.security",
         "velocity.db.migrations",
     ),
     "assets": ("velocity.aws.assets",),

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity/payment/braintree_adapter.py

@@ -113,6 +113,24 @@ def parse_braintree_environment(value: Any = None) -> str:
     return name
 
 
+def _decline_details(transaction: Any) -> Dict[str, Any]:
+    """The processor's own verdict on a declined sale, for callers that decide
+    whether to try the card again: ``processor_response_code``,
+    ``processor_response_text`` and ``processor_response_type``
+    (``approved`` / ``soft_declined`` / ``hard_declined`` -- Braintree's
+    classification; a hard decline will not be approved on retry). Only the
+    keys Braintree set; empty without a transaction (gateway rejection or
+    validation failure)."""
+    if transaction is None:
+        return {}
+    details = {
+        "processor_response_code": _attr(transaction, "processor_response_code"),
+        "processor_response_text": _attr(transaction, "processor_response_text"),
+        "processor_response_type": _attr(transaction, "processor_response_type"),
+    }
+    return {key: value for key, value in details.items() if value not in (None, "")}
+
+
 def _deep_errors(result: Any) -> List[str]:
     errors = getattr(getattr(result, "errors", None), "deep_errors", None) or []
     return [scrub(f"{error.code}: {error.message}") for error in errors]
@@ -556,7 +574,11 @@ class BraintreeAdapter(PaymentProcessorAdapter):
             "expires_at": None,
             "error_message": error_message,
             "metadata": _with_reference(
-                {"braintree_errors": _deep_errors(result)}, order_id
+                {
+                    "braintree_errors": _deep_errors(result),
+                    **_decline_details(result.transaction),
+                },
+                order_id,
             ),
         }
 
@@ -674,7 +696,12 @@ class BraintreeAdapter(PaymentProcessorAdapter):
             )
             error_message = scrub(result.transaction.processor_response_text)
         return failure(
-            "failed", error_message, {"braintree_errors": _deep_errors(result)}
+            "failed",
+            error_message,
+            {
+                "braintree_errors": _deep_errors(result),
+                **_decline_details(result.transaction),
+            },
         )
 
     def find_charge_by_reference(

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity/payment/stripe_adapter.py

@@ -139,6 +139,16 @@ def _amount_captured(payment_intent: Any, charge: Any, requested: Optional[int])
     return 0
 
 
+def _decline_details(error: Any) -> Dict[str, Any]:
+    """``decline_code`` of a card decline (``CardError``): the issuer's reason
+    (``insufficient_funds``, ``lost_card``, ``expired_card`` ...), for callers
+    that decide whether to try the card again. Empty when Stripe gave none."""
+    decline_code = getattr(error, "decline_code", None) or getattr(
+        getattr(error, "error", None), "decline_code", None
+    )
+    return {"decline_code": decline_code} if decline_code else {}
+
+
 class StripeAdapter(PaymentProcessorAdapter):
     """
     Stripe Connect adapter for payment processing.
@@ -664,6 +674,7 @@ class StripeAdapter(PaymentProcessorAdapter):
                     "error_code": e.code,
                     "error_type": type(e).__name__,
                     "idempotency_key": idempotency_key,
+                    **_decline_details(e),
                 },
             }
             if reference:
@@ -824,6 +835,7 @@ class StripeAdapter(PaymentProcessorAdapter):
                     "error_code": e.code,
                     "error_type": type(e).__name__,
                     "idempotency_key": idempotency_key,
+                    **_decline_details(e),
                 },
             }
             if reference:

{velocity_python-0.2.7 → velocity_python-0.2.9/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.2.7
+Version: 0.2.9
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -267,7 +267,6 @@ What changed in each release, and what callers must do before upgrading, is in
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |
 | Security | `docs/SECURITY.md` | Pre-commit hooks, credential scanning |
 | Changelog | `CHANGELOG.md` | Per-release breaking changes, deploy ordering, additions and fixes |
-| Improvement Backlog | `docs/IMPROVEMENT_BACKLOG.md` | Proposed and deferred library improvements |
 
 ---
 

{velocity_python-0.2.7 → velocity_python-0.2.9}/src/velocity_python.egg-info/SOURCES.txt

@@ -377,6 +377,7 @@ tests/test_schema_lock_config_other_backends.py
 tests/test_schema_migrations.py
 tests/test_search_paging_export.py
 tests/test_security_capability.py
+tests/test_security_events_table_gate.py
 tests/test_security_hardening.py
 tests/test_server_cursor.py
 tests/test_session_control.py

{velocity_python-0.2.7 → velocity_python-0.2.9}/tests/test_ensure_infrastructure.py

@@ -74,6 +74,7 @@ def test_core_declares_every_velocity_owned_runtime_table():
         "lambda_metrics",
         "user_data",
         "sys_user_data",
+        "sys_security_events",
         "app_session",
         "sys_feature_flags",
         "sys_capabilities",

{velocity_python-0.2.7 → velocity_python-0.2.9}/tests/test_payment_braintree_adapter.py

@@ -299,3 +299,70 @@ def test_generate_client_token_exhausted_raises_processor_error(monkeypatch):
     with pytest.raises(ProcessorError) as err:
         adapter.generate_client_token(attempts=2)
     assert "after 2 attempts" in str(err.value)
+
+
+def _declined_sale(**transaction):
+    return lambda params: SimpleNamespace(
+        is_success=False,
+        message="generic error",
+        transaction=SimpleNamespace(**transaction) if transaction else None,
+        errors=SimpleNamespace(deep_errors=[]),
+    )
+
+
+def test_charge_failure_carries_the_processor_verdict(monkeypatch):
+    """A hard decline will not be approved on retry; callers (recurring
+    billing) read Braintree's own processor_response_type instead of
+    guessing from the response text."""
+    adapter = build_adapter()
+    monkeypatch.setattr(
+        adapter.gateway.transaction,
+        "sale",
+        _declined_sale(
+            processor_response_text="Closed Card",
+            processor_response_code="2004",
+            processor_response_type="hard_declined",
+        ),
+    )
+
+    result = adapter.charge_stored_payment_method(
+        None, {"amount": 1050, "payment_method": "token_123"}
+    )
+
+    assert result["error_message"] == "Closed Card"
+    assert result["metadata"]["processor_response_type"] == "hard_declined"
+    assert result["metadata"]["processor_response_code"] == "2004"
+    assert result["metadata"]["processor_response_text"] == "Closed Card"
+
+
+def test_gateway_rejection_has_no_processor_verdict(monkeypatch):
+    adapter = build_adapter()
+    monkeypatch.setattr(adapter.gateway.transaction, "sale", _declined_sale())
+
+    result = adapter.charge_stored_payment_method(
+        None, {"amount": 1050, "payment_method": "token_123"}
+    )
+
+    assert result["success"] is False
+    assert "processor_response_type" not in result["metadata"]
+    assert result["metadata"]["braintree_errors"] == []
+
+
+def test_authorize_failure_carries_the_processor_verdict(monkeypatch):
+    adapter = build_adapter()
+    monkeypatch.setattr(
+        adapter.gateway.transaction,
+        "sale",
+        _declined_sale(
+            processor_response_text="Insufficient Funds",
+            processor_response_type="soft_declined",
+        ),
+    )
+
+    result = adapter.authorize_payment(
+        None, {"amount": 1050, "payment_method": "token_123"}
+    )
+
+    assert result["status"] == "failed"
+    assert result["metadata"]["processor_response_type"] == "soft_declined"
+    assert "processor_response_code" not in result["metadata"]