athena-python-docx 0.45.0__tar.gz → 0.45.1__tar.gz

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.45.0
+Version: 0.45.1
 Summary: Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.45.0"
+__version__ = "0.45.1"
 
 from docx.api import Document
 from docx._buffer import discard_all, flush_all

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/docx/_asset_token.py

@@ -17,6 +17,14 @@ Creating a document (``Document.create``, its upload) keeps the key of 1, 2 or
 API creates it instead (``docx._public_create``). A token goes only to its own
 document's routes.
 
+An Athena runtime credential (a computer's, a session VM's or a notebook
+kernel's ``ATHENA_API_KEY``: ``athcomp_``, ``athsvm_``, ``athnb_``) is never
+sent to DOCX Studio, which takes none, nor to Athena's older creation routes
+outside its public API: a call that would send one (another document's routes,
+an Athena without the studio-token route, no ``ATHENA_API_URL``, a create or an
+upload Athena's public API cannot take) refuses before any request, naming what
+to set (:func:`is_runtime_credential`).
+
 A token is minted once per (agora, key, asset, access) for the whole process,
 again 90 seconds before it expires, and once more when the studio answers 401.
 A read mints a read-only token (``{"access": "view"}``: the version check, the
@@ -70,6 +78,16 @@ PUBLIC_API_PREFIX = "/api/v0"
 VIEW = "view"
 EDIT = "edit"
 
+#: How the credentials Athena mints for a runtime begin: a computer's, a session
+#: VM's and a notebook kernel's own ``ATHENA_API_KEY``. Only Athena's public API
+#: takes one; a studio never does.
+RUNTIME_CREDENTIAL_PREFIXES = ("athcomp_", "athsvm_", "athnb_")
+
+
+def is_runtime_credential(key: str | None) -> bool:
+    """Whether ``key`` is a credential Athena minted for a runtime, which no studio takes."""
+    return bool(key) and str(key).startswith(RUNTIME_CREDENTIAL_PREFIXES)
+
 #: Minted again this long before Athena's ``expires_at_ms``.
 REFRESH_BEFORE_EXPIRY_SECONDS = 90.0
 #: The longest a token is held, whatever the local clock says (Athena's lifetime).

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/docx/_http.py

@@ -54,6 +54,29 @@ def _resolve_api_key(api_key: str | None) -> str | None:
     return api_key or os.environ.get(_API_KEY_ENV) or os.environ.get("ATHENA_API_KEY")
 
 
+def _refuse_runtime_credential(*, key: str | None, action: str) -> None:
+    """Refuse, before any request, to send an Athena runtime credential where
+    Athena's public API could not take the call.
+
+    A computer's, session VM's or notebook's own ``ATHENA_API_KEY`` is accepted
+    only by Athena's public API (``/api/v0``). Reaching this point means that
+    API could not take the create (no ``ATHENA_API_URL``, or an Athena older
+    than its creation routes), and DOCX Studio and agora's older routes refuse
+    the credential.
+    """
+    from docx._asset_token import is_runtime_credential
+
+    if is_runtime_credential(key):
+        raise AuthenticationError(
+            f"Cannot {action}: ATHENA_API_KEY here is an Athena runtime credential (a "
+            "computer's, session's or notebook's own key), which only Athena's public "
+            "API accepts, and that API could not take this call (ATHENA_API_URL is "
+            "unset, or that Athena predates it). Set ATHENA_API_URL, or set "
+            "ATHENA_DOCX_API_KEY (or pass api_key=) to an Athena API key DOCX Studio "
+            "accepts.",
+        )
+
+
 def _derive_agora_base_url(docx_base_url: str) -> str | None:
     """Best-effort derive an Agora base URL from a docx-studio base URL.
 
@@ -153,6 +176,7 @@ def create_empty_document(
             "Pass api_key= to Document.create() or set the env var "
             "(or set ATHENA_API_KEY as a fallback).",
         )
+    _refuse_runtime_credential(key=resolved_key, action="create the document on DOCX Studio")
 
     url: str = resolved_base.rstrip("/") + "/docs/empty"
     # The document is born as its creator's: its first write is signed as the
@@ -406,6 +430,7 @@ def upload_document(
             "Pass api_key= to Document.create() or set the env var "
             "(or set ATHENA_API_KEY as a fallback).",
         )
+    _refuse_runtime_credential(key=resolved_key, action="upload the document through agora")
 
     if not os.path.exists(docx_path):
         raise SessionError(f"DOCX file not found: {docx_path}")

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/docx/_http_doc.py

@@ -51,6 +51,7 @@ from docx._asset_token import (
     SigningUnavailable,
     StudioToken,
     TokenMinter,
+    is_runtime_credential,
 )
 from docx._batching import call_abandoned, note_progress
 from docx._buffer import CommandBuffer, keep_reported_message
@@ -1155,6 +1156,15 @@ class HttpClient:
         is sent once more with a newly minted one: docx-studio refused it before
         acting on it, so nothing is applied twice."""
         bearer, grant = self._bearer(asset_id=asset_id, access=access)
+        if grant is None and is_runtime_credential(bearer):
+            raise AuthenticationError(
+                f"DOCX Studio takes no Athena runtime credential, and this client "
+                f"carries no token of {asset_id}. ATHENA_API_KEY here is a computer's, "
+                "session's or notebook's own key, which only Athena's public API "
+                "accepts. Open the document by its asset id (asset_...) with "
+                "ATHENA_API_URL set, or set ATHENA_DOCX_API_KEY (or pass api_key=) to "
+                "an Athena API key DOCX Studio accepts."
+            )
         try:
             return send(bearer)
         except AuthenticationError as exc:

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.45.0"
+version = "0.45.1"
 description = "Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack"
 readme = "README.md"
 license = "MIT"

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/tests/test_asset_tokens.py

@@ -38,6 +38,8 @@ ASSET = "asset_8eaf4c95-0d4e-4f4e-9a8f-0b1c2d3e4f50"
 OTHER = "asset_1c2d3e4f-0d4e-4f4e-9a8f-0b1c2d3e4f51"
 # Shaped like the scoped credentials Athena puts in ATHENA_API_KEY.
 SCOPED_KEY = "athcomp_scoped-credential"
+# A person's Athena API key, which DOCX Studio takes as it is.
+PERSON_KEY = "person-api-key"
 MINT_URL = f"{AGORA}/api/v0/assets/{ASSET}/studio-token"
 
 
@@ -231,12 +233,34 @@ def test_without_athena_api_url_athena_api_key_is_the_bearer_as_before(
     world: _World, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     monkeypatch.delenv("ATHENA_API_URL")
+    monkeypatch.setenv("ATHENA_API_KEY", PERSON_KEY)
     world.studio.append(_applied())
 
     _batch(_client())
 
     assert world.mint_calls() == []
-    assert [call.bearer for call in world.studio_calls()] == [SCOPED_KEY]
+    assert [call.bearer for call in world.studio_calls()] == [PERSON_KEY]
+
+
+@pytest.mark.parametrize("prefix", ["athcomp_", "athsvm_", "athnb_"])
+def test_a_runtime_credential_never_goes_to_the_studio(
+    world: _World, monkeypatch: pytest.MonkeyPatch, prefix: str
+) -> None:
+    # Without ATHENA_API_URL nothing mints a token, and DOCX Studio takes no
+    # computer's, session VM's or notebook's own key: refused before sending.
+    monkeypatch.delenv("ATHENA_API_URL")
+    monkeypatch.setenv("ATHENA_API_KEY", f"{prefix}credential")
+    client = _client()
+
+    with pytest.raises(AuthenticationError, match="takes no Athena runtime credential") as caught:
+        _batch(client)
+    with pytest.raises(AuthenticationError, match="takes no Athena runtime credential"):
+        client.get_layout(ASSET)
+    with pytest.raises(AuthenticationError, match="takes no Athena runtime credential"):
+        _batch(_client(api_key=f"{prefix}credential"))
+
+    assert "ATHENA_DOCX_API_KEY" in str(caught.value)
+    assert world.calls == []
 
 
 @pytest.mark.parametrize(
@@ -284,15 +308,34 @@ def test_a_token_goes_only_to_its_own_documents_routes(world: _World) -> None:
     client = _client()
 
     _batch(client)
-    _batch(client, OTHER)
+    # Another document gets no token, and the scoped key is never sent to the
+    # studio in its place.
+    with pytest.raises(AuthenticationError, match="takes no Athena runtime credential"):
+        _batch(client, OTHER)
 
     assert [(call.url, call.bearer) for call in world.studio_calls()] == [
         (f"{STUDIO}/docs/{ASSET}/commands", f"aat_{ASSET}_edit_1"),
-        (f"{STUDIO}/docs/{OTHER}/commands", SCOPED_KEY),
     ]
     assert len(world.mint_calls()) == 1
 
 
+def test_with_a_person_key_another_documents_routes_keep_the_key(
+    world: _World, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("ATHENA_API_KEY", PERSON_KEY)
+    world.mints.append(world.mint_ok())
+    world.studio.append(_applied())
+    client = _client()
+
+    _batch(client)
+    _batch(client, OTHER)
+
+    assert [(call.url, call.bearer) for call in world.studio_calls()] == [
+        (f"{STUDIO}/docs/{ASSET}/commands", f"aat_{ASSET}_edit_1"),
+        (f"{STUDIO}/docs/{OTHER}/commands", PERSON_KEY),
+    ]
+
+
 # --- read and write access -----------------------------------------------------
 
 
@@ -452,7 +495,10 @@ def test_a_503_falls_back_to_a_studio_key_set_since(
     assert len(world.mint_calls()) == 1
 
 
-def test_an_athena_without_the_mint_route_gets_athena_api_key_as_before(world: _World) -> None:
+def test_an_athena_without_the_mint_route_gets_athena_api_key_as_before(
+    world: _World, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("ATHENA_API_KEY", PERSON_KEY)
     # An Athena older than the route: FastAPI's bare 404 for a path no route matches.
     world.mints.append(_response(404, {"detail": "Not Found"}))
     world.studio.extend([_response(200, {"pageCount": 1, "pages": []}), _applied()])
@@ -462,7 +508,19 @@ def test_an_athena_without_the_mint_route_gets_athena_api_key_as_before(world: _
     _batch(client)
 
     assert len(world.mint_calls()) == 1
-    assert [call.bearer for call in world.studio_calls()] == [SCOPED_KEY, SCOPED_KEY]
+    assert [call.bearer for call in world.studio_calls()] == [PERSON_KEY, PERSON_KEY]
+
+
+def test_an_athena_without_the_mint_route_never_gets_the_scoped_key_sent_on(
+    world: _World,
+) -> None:
+    world.mints.append(_response(404, {"detail": "Not Found"}))
+    client = _client()
+
+    with pytest.raises(AuthenticationError, match="takes no Athena runtime credential"):
+        client.get_layout(ASSET)
+
+    assert world.studio_calls() == []
 
 
 def test_athenas_own_asset_not_found_stays_final(world: _World) -> None:

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/tests/test_public_create.py

@@ -31,6 +31,8 @@ STUDIO = "https://docx.example.com"
 AGORA = "https://agora.example.com"
 ASSET = "asset_8eaf4c95-0d4e-4f4e-9a8f-0b1c2d3e4f50"
 SCOPED_KEY = "athcomp_scoped-credential"
+# A person's Athena API key, which DOCX Studio takes as it is.
+PERSON_KEY = "person-api-key"
 CREATE_URL = f"{AGORA}/api/v0/assets/create"
 FROM_FILE_URL = f"{AGORA}/api/v0/assets/create-from-file"
 CREATED = {"asset_id": ASSET, "title": "Memo", "workspace_id": "ws_1"}
@@ -187,7 +189,7 @@ def test_the_sandbox_workspace_and_the_agent_run_are_named(
     [
         ({"ATHENA_DOCX_API_KEY": "studio-key"}, None, "studio-key"),
         ({}, "explicit-key", "explicit-key"),
-        ({"ATHENA_API_URL": None}, None, SCOPED_KEY),
+        ({"ATHENA_API_URL": None, "ATHENA_API_KEY": PERSON_KEY}, None, PERSON_KEY),
     ],
 )
 def test_a_studio_key_an_explicit_key_or_no_api_url_keep_docx_studio(
@@ -216,7 +218,53 @@ def test_a_studio_key_an_explicit_key_or_no_api_url_keep_docx_studio(
     assert sent[0].get_header("Authorization") == f"Bearer {expected_bearer}"
 
 
-def test_an_athena_without_the_word_document_type_gets_docx_studio(athena: _Athena) -> None:
+@pytest.mark.parametrize("prefix", ["athcomp_", "athsvm_", "athnb_"])
+def test_without_athena_api_url_a_runtime_credential_never_goes_to_docx_studio(
+    athena: _Athena, monkeypatch: pytest.MonkeyPatch, prefix: str, docx_file: Path
+) -> None:
+    monkeypatch.delenv("ATHENA_API_URL")
+    monkeypatch.setenv("ATHENA_API_KEY", f"{prefix}credential")
+
+    with patch("docx._http.urllib.request.urlopen") as urlopen:
+        with pytest.raises(AuthenticationError, match="Athena runtime credential"):
+            create_empty_document(name="Memo")
+        with pytest.raises(AuthenticationError, match="Athena runtime credential"):
+            upload_document(docx_path=str(docx_file), agora_base_url=AGORA)
+
+    urlopen.assert_not_called()
+    assert athena.calls == []
+
+
+def test_an_athena_without_the_word_document_type_never_gets_a_runtime_credential(
+    athena: _Athena,
+) -> None:
+    athena.answers.append(
+        _response(
+            422,
+            {
+                "detail": [
+                    {
+                        "type": "value_error",
+                        "loc": ["body", "asset_type"],
+                        "msg": "Value error, Unsupported asset type: 'word_document'.",
+                    }
+                ]
+            },
+        )
+    )
+
+    with patch("docx._http.urllib.request.urlopen") as urlopen:
+        with pytest.raises(AuthenticationError, match="Athena runtime credential"):
+            create_empty_document(name="Memo")
+
+    urlopen.assert_not_called()
+    assert len(athena.calls) == 1
+
+
+def test_an_athena_without_the_word_document_type_gets_docx_studio(
+    athena: _Athena, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("ATHENA_API_KEY", PERSON_KEY)
     athena.answers.append(
         _response(
             422,
@@ -242,7 +290,7 @@ def test_an_athena_without_the_word_document_type_gets_docx_studio(athena: _Athe
 
     assert created["asset_id"] == ASSET
     assert [request.full_url for request in sent] == [f"{STUDIO}/docs/empty"]
-    assert sent[0].get_header("Authorization") == f"Bearer {SCOPED_KEY}"
+    assert sent[0].get_header("Authorization") == f"Bearer {PERSON_KEY}"
 
 
 @pytest.mark.parametrize(
@@ -324,10 +372,25 @@ def test_document_create_from_a_file_goes_through_athena(
     assert athena.calls[0].params == {"title": "Memo"}
 
 
+def test_an_athena_without_create_from_file_never_gets_a_runtime_credential(
+    athena: _Athena,
+    docx_file: Path,
+) -> None:
+    athena.answers.append(_response(405, {"detail": "Method Not Allowed"}))
+
+    with patch("docx._http.urllib.request.urlopen") as urlopen:
+        with pytest.raises(AuthenticationError, match="Athena runtime credential"):
+            upload_document(docx_path=str(docx_file), agora_base_url=AGORA)
+
+    urlopen.assert_not_called()
+
+
 def test_an_athena_without_create_from_file_gets_the_agora_upload(
     athena: _Athena,
     docx_file: Path,
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
+    monkeypatch.setenv("ATHENA_API_KEY", PERSON_KEY)
     # /assets/{asset_id} takes GET and PATCH only, so an older Athena answers 405.
     athena.answers.append(_response(405, {"detail": "Method Not Allowed"}))
     sent: list[Any] = []
@@ -345,7 +408,7 @@ def test_an_athena_without_create_from_file_gets_the_agora_upload(
         f"{AGORA}/api/docx-studio/assets",
         f"{AGORA}/api/docx-studio/assets/{ASSET}/import",
     ]
-    assert sent[0].get_header("Authorization") == f"Bearer {SCOPED_KEY}"
+    assert sent[0].get_header("Authorization") == f"Bearer {PERSON_KEY}"
 
 
 def test_a_file_athena_cannot_import_raises(athena: _Athena, docx_file: Path) -> None:

{athena_python_docx-0.45.0 → athena_python_docx-0.45.1}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "athena-python-docx"
-version = "0.45.0"
+version = "0.45.1"
 source = { editable = "." }
 dependencies = [
     { name = "athena-references" },