spatialdds 0.5.2__tar.gz → 0.5.4__tar.gz

{spatialdds-0.5.2 → spatialdds-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.5.2
+Version: 0.5.4
 Summary: SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command.
 Author: Open AR Cloud
 License: Apache-2.0
@@ -419,7 +419,7 @@ an object the app had already discarded. If you called `register()` before
 `make_app()`, 0.4.0 and 0.5.0 worked; if you called it after, the command lane
 advertised nothing and refused every POST.
 
-0.5.2 makes `notify` safe from the thread its own docstring invited. It put
+0.5.2 made `notify` safe from the thread its own docstring invited. It put
 onto the subscriber queue directly, and `asyncio.Queue.put_nowait` from a
 foreign thread enqueues without waking the loop — so a backend reading a bus
 in a thread fed a parked subscriber nothing until the loop woke for some other
@@ -428,7 +428,50 @@ pumping 202 samples into two registered subscriber queues delivered 0 live
 events. If you call `notify` only from the serving loop, 0.5.0 and 0.5.1 were
 correct for you.
 
-## Not in 0.5.2
+0.5.3 let a browser reach this gateway at all. `Authorization` is not a
+CORS-safelisted request header, so a cross-origin request carrying one is
+preceded by an `OPTIONS` preflight — and no `OPTIONS` was routed, so aiohttp
+answered `405 Allow: GET,HEAD,POST` and the browser stopped there without
+making the request. Two consequences, both found from outside by a real page
+rather than by a gate here: **N.6 was unreachable from a browser for every
+access class**, because a command always carries a credential and so always
+preflights, which no reclassification can change; and a `public-cacheable`
+`GET` that answers `200` with `Access-Control-Allow-Origin: *` failed outright
+if the client volunteered a credential it did not need.
+
+An authorized operator-scoped response now also carries the asking origin,
+echoed, with `Vary: Origin, Authorization`. The previous reasoning was that a
+gated resource should never be CORS-open because its credential "must not be
+invited to attach ambiently" — right about the risk and wrong about the
+mechanism. `Access-Control-Allow-Credentials` is what issues that invitation,
+this package sets it nowhere, and a `Bearer` token the page holds and chooses
+to attach is the opposite of ambient. Refusing the origin never kept a
+credential out; it made an authorized `200` unreadable by the client that had
+authorized itself. The body is still `no-store`, the credential is still
+required, and nothing is newly reachable without one.
+
+If your clients are not browsers, 0.5.0 through 0.5.2 were correct for you:
+nothing else changes, and no response loses a header it had.
+
+0.5.4 finishes what 0.5.3 started, and the gap is instructive. 0.5.3 threaded
+the asking origin through the three places that build a response from
+`_cache_headers` and missed the two that build one by hand: the N.6 command
+lane's own reply, and **every N.8 problem document**. So a command published
+and the page could not read the outcome --- a cross-origin `fetch` rejects a
+response with no allowed origin, so a client saw a failure for a command that
+had in fact succeeded --- and a `401`, `409` or `400` was unreadable by the
+client it was written for, which is N.8 failing at the one thing that
+distinguishes it from a bare status.
+
+The fix is a one-rule middleware rather than a fourth and fifth call site:
+where a response names no origin and the request had one, echo it with
+`Vary: Origin`. `_cache_headers` remains the place that decides cacheability
+and reach together and is unchanged where it already acts. Threading it
+explicitly was tried first and is what missed two paths.
+
+If your clients are not browsers, nothing here changes anything for you.
+
+## Not in 0.5.4
 
 Stated so nobody waits for them: no async API, no caching beyond ETag
 revalidation, no retry policy, no MCAP tooling beyond the journal the server

{spatialdds-0.5.2 → spatialdds-0.5.4}/README.md

@@ -395,7 +395,7 @@ an object the app had already discarded. If you called `register()` before
 `make_app()`, 0.4.0 and 0.5.0 worked; if you called it after, the command lane
 advertised nothing and refused every POST.
 
-0.5.2 makes `notify` safe from the thread its own docstring invited. It put
+0.5.2 made `notify` safe from the thread its own docstring invited. It put
 onto the subscriber queue directly, and `asyncio.Queue.put_nowait` from a
 foreign thread enqueues without waking the loop — so a backend reading a bus
 in a thread fed a parked subscriber nothing until the loop woke for some other
@@ -404,7 +404,50 @@ pumping 202 samples into two registered subscriber queues delivered 0 live
 events. If you call `notify` only from the serving loop, 0.5.0 and 0.5.1 were
 correct for you.
 
-## Not in 0.5.2
+0.5.3 let a browser reach this gateway at all. `Authorization` is not a
+CORS-safelisted request header, so a cross-origin request carrying one is
+preceded by an `OPTIONS` preflight — and no `OPTIONS` was routed, so aiohttp
+answered `405 Allow: GET,HEAD,POST` and the browser stopped there without
+making the request. Two consequences, both found from outside by a real page
+rather than by a gate here: **N.6 was unreachable from a browser for every
+access class**, because a command always carries a credential and so always
+preflights, which no reclassification can change; and a `public-cacheable`
+`GET` that answers `200` with `Access-Control-Allow-Origin: *` failed outright
+if the client volunteered a credential it did not need.
+
+An authorized operator-scoped response now also carries the asking origin,
+echoed, with `Vary: Origin, Authorization`. The previous reasoning was that a
+gated resource should never be CORS-open because its credential "must not be
+invited to attach ambiently" — right about the risk and wrong about the
+mechanism. `Access-Control-Allow-Credentials` is what issues that invitation,
+this package sets it nowhere, and a `Bearer` token the page holds and chooses
+to attach is the opposite of ambient. Refusing the origin never kept a
+credential out; it made an authorized `200` unreadable by the client that had
+authorized itself. The body is still `no-store`, the credential is still
+required, and nothing is newly reachable without one.
+
+If your clients are not browsers, 0.5.0 through 0.5.2 were correct for you:
+nothing else changes, and no response loses a header it had.
+
+0.5.4 finishes what 0.5.3 started, and the gap is instructive. 0.5.3 threaded
+the asking origin through the three places that build a response from
+`_cache_headers` and missed the two that build one by hand: the N.6 command
+lane's own reply, and **every N.8 problem document**. So a command published
+and the page could not read the outcome --- a cross-origin `fetch` rejects a
+response with no allowed origin, so a client saw a failure for a command that
+had in fact succeeded --- and a `401`, `409` or `400` was unreadable by the
+client it was written for, which is N.8 failing at the one thing that
+distinguishes it from a bare status.
+
+The fix is a one-rule middleware rather than a fourth and fifth call site:
+where a response names no origin and the request had one, echo it with
+`Vary: Origin`. `_cache_headers` remains the place that decides cacheability
+and reach together and is unchanged where it already acts. Threading it
+explicitly was tried first and is what missed two paths.
+
+If your clients are not browsers, nothing here changes anything for you.
+
+## Not in 0.5.4
 
 Stated so nobody waits for them: no async API, no caching beyond ETag
 revalidation, no retry policy, no MCAP tooling beyond the journal the server

{spatialdds-0.5.2 → spatialdds-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spatialdds"
-version = "0.5.2"
+version = "0.5.4"
 description = "SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command."
 readme = "README.md"
 requires-python = ">=3.9"

{spatialdds-0.5.2 → spatialdds-0.5.4}/spatialdds/__init__.py

@@ -37,7 +37,7 @@ __all__ = [
     "content_manifest", "geo_anchor", "service_uri", "content_uri",
 ]
 
-__version__ = "0.5.2"
+__version__ = "0.5.4"
 #: The SpatialDDS-spec commit whose Appendix N and generated artifacts this
 #: package implements. Package versions and specification versions move
 #: independently; this is the one that says what the wire looks like.

{spatialdds-0.5.2 → spatialdds-0.5.4}/spatialdds/server/gw_http.py

@@ -91,20 +91,55 @@ def _problem(status: int, slug: str, title: str, detail: str,
                         headers={"Cache-Control": "no-store"})
 
 
-def _cache_headers(access: str, doc_ttl: int | None = None) -> dict[str, str]:
+#: What a cross-origin reader may see beyond the body. Without it the ETag and
+#: the access class are served and unreadable, which is the instrument failing
+#: to report what it measures.
+EXPOSE_HEADERS = ("ETag, X-SpatialDDS-Topic, X-SpatialDDS-Type, "
+                  "X-SpatialDDS-Access")
+
+#: Request headers a browser may send to this gateway. `Authorization` is the
+#: one that matters and the one that is not CORS-safelisted, so a request
+#: carrying it preflights; `Content-Type` is needed for any JSON body, and
+#: `If-None-Match` for conditional GETs.
+ALLOW_HEADERS = "Authorization, Content-Type, If-None-Match"
+
+#: Methods this gateway serves. Stated once so the preflight answer and the
+#: `Allow` header on a refusal cannot drift apart.
+ALLOW_METHODS = "GET, HEAD, POST, PUT, DELETE, OPTIONS"
+
+#: How long a browser may cache a preflight. Ten minutes: long enough that a
+#: page does not preflight every command, short enough that changing the
+#: policy takes effect inside a session.
+PREFLIGHT_MAX_AGE = 600
+
+
+def _cache_headers(access: str, doc_ttl: int | None = None,
+                   origin: str | None = None) -> dict[str, str]:
     """Cacheability, reach, and auth decided together or not at all.
 
     The CORS header lives in this branch rather than in a middleware for the
     same reason the cache header does: a public-cacheable resource is one a
     client may read without presenting anything, so there is no origin that
-    should be refused it, and an operator-scoped resource is gated by a
-    credential a browser must not be invited to attach ambiently. Putting the
-    two in one function makes the pairing impossible to drift apart.
-
-    `Access-Control-Expose-Headers` is here because without it a cross-origin
-    reader can see the body but not the ETag or the access class that describes
-    it -- the headers would be served and unreadable, which is the instrument
-    failing to report what it measures.
+    should be refused it. Putting the two in one function makes the pairing
+    impossible to drift apart.
+
+    **An operator-scoped response now carries an echoed origin too, and the
+    reasoning that said otherwise was close to right.** It read: gated by "a
+    credential a browser must not be invited to attach ambiently". The
+    invitation is real and `Access-Control-Allow-Origin` is not how it is
+    issued --- `Access-Control-Allow-Credentials` is. Cookies and HTTP auth
+    ride along only when that header says so and the client asks for
+    `credentials: 'include'`; this gateway sets it nowhere and never will, so
+    nothing here is ambient. A `Bearer` token in an `Authorization` header is
+    the opposite of ambient: the page had to hold it and choose to attach it.
+
+    Refusing the origin did not keep that credential out. It made an
+    authorized response unreadable by the client that authorized itself ---
+    measured from `SpatialDDS-demo`'s browser lane, where a page holding a
+    valid token could not read a word of a 200 it had earned. So the origin is
+    echoed rather than `*`, with `Vary: Origin`, which keeps a shared cache
+    from serving one origin's answer to another; the body stays `no-store`
+    regardless, and the credential is still required. No gate is weakened.
     """
     if access == gateway.PUBLIC:
         # N.4: where a public-cacheable resource is a manifest carrying its own
@@ -113,15 +148,116 @@ def _cache_headers(access: str, doc_ttl: int | None = None) -> dict[str, str]:
         age = gateway.PUBLIC_MAX_AGE if doc_ttl is None else doc_ttl
         return {"Cache-Control": f"public, max-age={age}",
                 "Access-Control-Allow-Origin": "*",
-                "Access-Control-Expose-Headers":
-                    "ETag, X-SpatialDDS-Topic, X-SpatialDDS-Type, "
-                    "X-SpatialDDS-Access"}
-    # Operator-scoped. Never cacheable and never CORS-open, by the same
-    # decision that gated it. `doc_ttl` is ignored here deliberately: N.4
-    # grants no lifetime to a gated resource whatever `ttl_sec` it carries,
-    # because the cache that would honour it is the shared one the gate exists
-    # to keep the body out of.
-    return {"Cache-Control": "no-store", "Vary": "Authorization"}
+                "Access-Control-Expose-Headers": EXPOSE_HEADERS}
+    # Operator-scoped. Never cacheable, by the same decision that gated it.
+    # `doc_ttl` is ignored here deliberately: N.4 grants no lifetime to a gated
+    # resource whatever `ttl_sec` it carries, because the cache that would
+    # honour it is the shared one the gate exists to keep the body out of.
+    headers = {"Cache-Control": "no-store", "Vary": "Authorization"}
+    if origin:
+        # Echoed, not `*`: a wildcard on a response that varies by credential
+        # is the combination a shared cache can get wrong, and there is no
+        # reason to name an origin this request did not come from.
+        headers["Access-Control-Allow-Origin"] = origin
+        headers["Vary"] = "Origin, Authorization"
+        headers["Access-Control-Expose-Headers"] = EXPOSE_HEADERS
+    return headers
+
+
+@web.middleware
+async def _reach(request: web.Request, handler) -> web.StreamResponse:
+    """Make sure every answer names the origin that asked for it.
+
+    **A backstop, not the policy.** `_cache_headers` remains the single place
+    that decides cacheability and reach together, and where it has already set
+    `Access-Control-Allow-Origin` this changes nothing. What it covers is the
+    responses that set no reach at all, because they are built by hand rather
+    than through that function --- and the reason it exists is that threading
+    the origin explicitly through every construction site was tried first, in
+    0.5.3, and missed two:
+
+    * `post_command`'s `202`. The command published and the page could not
+      read the outcome: a cross-origin `fetch` rejects a response with no
+      allowed origin, so `bindingCommand` in the demo's client landed in its
+      `catch` with no status at all, for a command that had in fact succeeded.
+    * **Every N.8 problem document.** `_problem` set `no-store` and nothing
+      else, so a `401`, `409` or `400` was unreadable by the client it was
+      written for. N.8 exists to hand a client a *reason*; a reason a browser
+      cannot read is the surface failing at the one thing that distinguishes
+      it from a bare status.
+
+    Both were found by curling the running demo after 0.5.3 shipped, not by
+    this repository's gates --- the same way the original defect was found,
+    which is the lesson repeating rather than a new one.
+
+    Only the origin is echoed here, and only when absent. `Vary: Origin` goes
+    with it so a shared cache cannot serve one origin's answer to another; the
+    `Expose-Headers` set is added for the same reason it is on a GET, since a
+    reader that cannot see the ETag cannot revalidate. `Allow-Credentials` is
+    still set nowhere.
+    """
+    response = await handler(request)
+    origin = request.headers.get("Origin")
+    if origin and "Access-Control-Allow-Origin" not in response.headers:
+        response.headers["Access-Control-Allow-Origin"] = origin
+        vary = response.headers.get("Vary")
+        response.headers["Vary"] = f"{vary}, Origin" if vary else "Origin"
+        response.headers.setdefault("Access-Control-Expose-Headers",
+                                    EXPOSE_HEADERS)
+    return response
+
+
+async def preflight(request: web.Request) -> web.Response:
+    """Answer the `OPTIONS` a browser sends before a credentialed request.
+
+    **Why this route has to exist, and why nothing in the specification said
+    so.** `Authorization` is not a CORS-safelisted request header, so a
+    cross-origin request carrying one is preceded by a preflight. This gateway
+    routed no `OPTIONS` at all, so aiohttp answered `405` with
+    `Allow: GET,HEAD,POST` --- and the browser stopped there, never making the
+    request. Two consequences, both measured against 0.5.2 from a page on
+    another origin:
+
+    * N.6 was unreachable from a browser for **every** access class, because a
+      command always carries a credential. Reclassifying a lane cannot help:
+      the preflight is triggered by the request, not by what the resource is.
+    * A `public-cacheable` GET that answers `200` with
+      `Access-Control-Allow-Origin: *` failed outright if the client
+      volunteered a credential it did not need.
+
+    Both are fixed here rather than in Appendix N, because nothing in N
+    forbade any of it --- a conforming endpoint could simply omit it, which is
+    the separate gap filed for the specification: a binding whose flagship
+    client is a browser should have to *state* its preflight behaviour.
+
+    `Allow-Credentials` is deliberately absent. It is the header that would
+    invite cookies and HTTP auth to ride along ambiently, and this gateway
+    wants the opposite: a credential the page holds and chooses to attach.
+
+    A bare `OPTIONS` with no `Origin` is not a preflight; it gets the same
+    `Allow` list as a courtesy, which also keeps `ALLOW_METHODS` the single
+    place that answer is written.
+    """
+    origin = request.headers.get("Origin")
+    headers = {"Allow": ALLOW_METHODS}
+    if origin:
+        headers.update({
+            "Access-Control-Allow-Origin": origin,
+            "Access-Control-Allow-Methods": ALLOW_METHODS,
+            # Echo what was asked for when it was asked, so a header this
+            # gateway has not thought of is refused rather than blanket-allowed,
+            # and fall back to the list above for a preflight that names none.
+            "Access-Control-Allow-Headers":
+                request.headers.get("Access-Control-Request-Headers")
+                or ALLOW_HEADERS,
+            "Access-Control-Max-Age": str(PREFLIGHT_MAX_AGE),
+            "Access-Control-Expose-Headers": EXPOSE_HEADERS,
+            # The answer depends on all three, so a cache must not reuse it
+            # across different ones.
+            "Vary": "Origin, Access-Control-Request-Method, "
+                    "Access-Control-Request-Headers",
+        })
+    return web.Response(status=204, headers=headers)
 
 
 def _authorized(request: web.Request, token: str | None) -> bool:
@@ -145,7 +281,9 @@ def _json_response(request: web.Request, doc: Any, access: str,
                    doc_ttl: int | None = None) -> web.Response:
     """One JSON resource, with its ETag, its cache class, and 304 handling."""
     etag = _etag(doc)
-    headers = {"ETag": etag, **_cache_headers(access, doc_ttl),
+    headers = {"ETag": etag,
+               **_cache_headers(access, doc_ttl,
+                                request.headers.get("Origin")),
                **(extra or {})}
     if request.headers.get("If-None-Match", "") == etag:
         return web.Response(status=304, headers=headers)
@@ -473,7 +611,9 @@ def _written(request: web.Request, doc: Any, created: bool,
         if not created else web.Response(
             body=_body(doc), status=201, content_type="application/json",
             headers={"ETag": _etag(doc),
-                     **_cache_headers(gateway.OPERATOR), **extra})
+                     **_cache_headers(gateway.OPERATOR, None,
+                                      request.headers.get("Origin")),
+                     **extra})
 
 
 def _running_loop():
@@ -741,7 +881,9 @@ async def delete_instance(request: web.Request) -> web.Response:
                      {"event": "dispose", "topic": topic, "key": key,
                       "reason": reason})
     return web.Response(status=204,
-                        headers=_cache_headers(gateway.OPERATOR))
+                        headers=_cache_headers(
+                            gateway.OPERATOR, None,
+                            request.headers.get("Origin")))
 
 
 async def put_manifest(request: web.Request) -> web.Response:
@@ -902,7 +1044,7 @@ def make_app(state: gateway.State, base: str, token: str | None,
     embedder passes `publish_enabled=False, live_subscriptions=True` and gets
     the live lane with no write surface at all.
     """
-    app = web.Application()
+    app = web.Application(middlewares=[_reach])
     app["state"] = state
     app["base"] = base.rstrip("/")
     app["token"] = token
@@ -959,5 +1101,18 @@ def make_app(state: gateway.State, base: str, token: str | None,
         web.delete("/{scene}/{stream}/{type}/{version}/{key}",
                    delete_instance),
         web.put(gateway.RESOLVE_PATH, put_manifest),
+        # The preflight, on every path that can be asked for cross-origin
+        # with a credential or a JSON body. Mirrors the routes above rather
+        # than using a catch-all, so a path this gateway does not serve still
+        # 404s on OPTIONS instead of promising a method nobody implements.
+        web.options(f"{WELL_KNOWN}/schemas", preflight),
+        web.options(f"{WELL_KNOWN}/schemas/{{type}}", preflight),
+        web.options(f"{WELL_KNOWN}/search", preflight),
+        web.options(f"{WELL_KNOWN}/bootstrap", preflight),
+        web.options(f"{WELL_KNOWN}/resolver", preflight),
+        web.options(gateway.RESOLVE_PATH, preflight),
+        web.options(f"{ASSET_PATH}/{{name}}", preflight),
+        web.options("/{scene}/{stream}/{type}/{version}", preflight),
+        web.options("/{scene}/{stream}/{type}/{version}/{key}", preflight),
     ])
     return app

{spatialdds-0.5.2 → spatialdds-0.5.4}/spatialdds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.5.2
+Version: 0.5.4
 Summary: SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command.
 Author: Open AR Cloud
 License: Apache-2.0
@@ -419,7 +419,7 @@ an object the app had already discarded. If you called `register()` before
 `make_app()`, 0.4.0 and 0.5.0 worked; if you called it after, the command lane
 advertised nothing and refused every POST.
 
-0.5.2 makes `notify` safe from the thread its own docstring invited. It put
+0.5.2 made `notify` safe from the thread its own docstring invited. It put
 onto the subscriber queue directly, and `asyncio.Queue.put_nowait` from a
 foreign thread enqueues without waking the loop — so a backend reading a bus
 in a thread fed a parked subscriber nothing until the loop woke for some other
@@ -428,7 +428,50 @@ pumping 202 samples into two registered subscriber queues delivered 0 live
 events. If you call `notify` only from the serving loop, 0.5.0 and 0.5.1 were
 correct for you.
 
-## Not in 0.5.2
+0.5.3 let a browser reach this gateway at all. `Authorization` is not a
+CORS-safelisted request header, so a cross-origin request carrying one is
+preceded by an `OPTIONS` preflight — and no `OPTIONS` was routed, so aiohttp
+answered `405 Allow: GET,HEAD,POST` and the browser stopped there without
+making the request. Two consequences, both found from outside by a real page
+rather than by a gate here: **N.6 was unreachable from a browser for every
+access class**, because a command always carries a credential and so always
+preflights, which no reclassification can change; and a `public-cacheable`
+`GET` that answers `200` with `Access-Control-Allow-Origin: *` failed outright
+if the client volunteered a credential it did not need.
+
+An authorized operator-scoped response now also carries the asking origin,
+echoed, with `Vary: Origin, Authorization`. The previous reasoning was that a
+gated resource should never be CORS-open because its credential "must not be
+invited to attach ambiently" — right about the risk and wrong about the
+mechanism. `Access-Control-Allow-Credentials` is what issues that invitation,
+this package sets it nowhere, and a `Bearer` token the page holds and chooses
+to attach is the opposite of ambient. Refusing the origin never kept a
+credential out; it made an authorized `200` unreadable by the client that had
+authorized itself. The body is still `no-store`, the credential is still
+required, and nothing is newly reachable without one.
+
+If your clients are not browsers, 0.5.0 through 0.5.2 were correct for you:
+nothing else changes, and no response loses a header it had.
+
+0.5.4 finishes what 0.5.3 started, and the gap is instructive. 0.5.3 threaded
+the asking origin through the three places that build a response from
+`_cache_headers` and missed the two that build one by hand: the N.6 command
+lane's own reply, and **every N.8 problem document**. So a command published
+and the page could not read the outcome --- a cross-origin `fetch` rejects a
+response with no allowed origin, so a client saw a failure for a command that
+had in fact succeeded --- and a `401`, `409` or `400` was unreadable by the
+client it was written for, which is N.8 failing at the one thing that
+distinguishes it from a bare status.
+
+The fix is a one-rule middleware rather than a fourth and fifth call site:
+where a response names no origin and the request had one, echo it with
+`Vary: Origin`. `_cache_headers` remains the place that decides cacheability
+and reach together and is unchanged where it already acts. Threading it
+explicitly was tried first and is what missed two paths.
+
+If your clients are not browsers, nothing here changes anything for you.
+
+## Not in 0.5.4
 
 Stated so nobody waits for them: no async API, no caching beyond ETag
 revalidation, no retry policy, no MCAP tooling beyond the journal the server