chore: import upstream snapshot with attribution

python/tests/server/auth/test_config.py

@@ -0,0 +1,208 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import pytest
+
+from mirage.server.auth.config import (AuthMode, JWTConfig,
+                                       resolve_auth_config,
+                                       resolve_local_token)
+from mirage.server.daemon_config import ALLOWED_KEYS
+
+
+@pytest.mark.no_host_override
+def test_resolve_local_token_env_wins(tmp_path):
+    f = tmp_path / "auth_token"
+    f.write_text("from-file")
+    got = resolve_local_token(env={"MIRAGE_AUTH_TOKEN": "from-env"},
+                              token_file=f)
+    assert got == "from-env"
+
+
+@pytest.mark.no_host_override
+def test_resolve_local_token_falls_back_to_file(tmp_path):
+    f = tmp_path / "auth_token"
+    f.write_text("from-file")
+    got = resolve_local_token(env={}, token_file=f)
+    assert got == "from-file"
+
+
+@pytest.mark.no_host_override
+def test_resolve_local_token_returns_none_when_no_source(tmp_path):
+    f = tmp_path / "missing"
+    got = resolve_local_token(env={}, token_file=f)
+    assert got is None
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_default_is_local_no_token(tmp_path):
+    cfg = resolve_auth_config(env={}, token_file=tmp_path / "missing")
+    assert cfg.mode == "local"
+    assert cfg.local_token is None
+    assert cfg.bearer_token is None
+    assert cfg.jwt is None
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_local_with_env(tmp_path):
+    cfg = resolve_auth_config(env={"MIRAGE_AUTH_TOKEN": "lt"},
+                              token_file=tmp_path / "missing")
+    assert cfg.mode == "local"
+    assert cfg.local_token == "lt"
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_token_mode_requires_env(tmp_path):
+    with pytest.raises(RuntimeError, match="MIRAGE_AUTH_TOKEN"):
+        resolve_auth_config(env={"MIRAGE_AUTH_MODE": "token"},
+                            token_file=tmp_path / "missing")
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_token_mode_uses_env_token(tmp_path):
+    cfg = resolve_auth_config(env={
+        "MIRAGE_AUTH_MODE": "token",
+        "MIRAGE_AUTH_TOKEN": "operator-pat"
+    },
+                              token_file=tmp_path / "missing")
+    assert cfg.mode == "token"
+    assert cfg.bearer_token == "operator-pat"
+    assert cfg.local_token is None
+    assert cfg.jwt is None
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_jwt_mode_requires_key(tmp_path):
+    with pytest.raises(RuntimeError, match="MIRAGE_JWT_PUBKEY"):
+        resolve_auth_config(env={
+            "MIRAGE_AUTH_MODE": "jwt",
+            "MIRAGE_JWT_ALG": "RS256"
+        },
+                            token_file=tmp_path / "missing")
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_jwt_mode_requires_alg(tmp_path):
+    with pytest.raises(RuntimeError, match="MIRAGE_JWT_ALG"):
+        resolve_auth_config(env={
+            "MIRAGE_AUTH_MODE": "jwt",
+            "MIRAGE_JWT_PUBKEY": "-----BEGIN"
+        },
+                            token_file=tmp_path / "missing")
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_jwt_mode_inline_key(tmp_path):
+    cfg = resolve_auth_config(env={
+        "MIRAGE_AUTH_MODE": "jwt",
+        "MIRAGE_JWT_PUBKEY":
+        "-----BEGIN PUBLIC KEY-----\nFAKE\n-----END PUBLIC KEY-----",
+        "MIRAGE_JWT_ALG": "RS256",
+        "MIRAGE_JWT_ISSUER": "https://issuer.example",
+        "MIRAGE_JWT_AUDIENCE": "mirage-daemon",
+        "MIRAGE_JWT_AUTHORIZED_PARTIES":
+        "https://app.example,https://other.example",
+        "MIRAGE_JWT_CLOCK_SKEW_SECONDS": "12",
+    },
+                              token_file=tmp_path / "missing")
+    assert cfg.mode == "jwt"
+    assert cfg.jwt is not None
+    assert isinstance(cfg.jwt, JWTConfig)
+    assert "FAKE" in cfg.jwt.key
+    assert cfg.jwt.algorithm == "RS256"
+    assert cfg.jwt.issuer == "https://issuer.example"
+    assert cfg.jwt.audience == "mirage-daemon"
+    assert cfg.jwt.authorized_parties == ("https://app.example",
+                                          "https://other.example")
+    assert cfg.jwt.clock_skew_seconds == 12
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_jwt_mode_pubkey_from_file(tmp_path):
+    key_file = tmp_path / "jwt.pub"
+    key_file.write_text(
+        "-----BEGIN PUBLIC KEY-----\nFROMFILE\n-----END PUBLIC KEY-----")
+    cfg = resolve_auth_config(env={
+        "MIRAGE_AUTH_MODE": "jwt",
+        "MIRAGE_JWT_PUBKEY_FILE": str(key_file),
+        "MIRAGE_JWT_ALG": "RS256",
+    },
+                              token_file=tmp_path / "missing")
+    assert cfg.mode == "jwt"
+    assert cfg.jwt is not None
+    assert "FROMFILE" in cfg.jwt.key
+    assert cfg.jwt.clock_skew_seconds == 5  # default mirrors Clerk
+
+
+@pytest.mark.no_host_override
+def test_resolve_auth_config_unknown_mode_raises(tmp_path):
+    with pytest.raises(RuntimeError, match="MIRAGE_AUTH_MODE"):
+        resolve_auth_config(env={"MIRAGE_AUTH_MODE": "wat"},
+                            token_file=tmp_path / "missing")
+
+
+def test_auth_mode_from_config_table(tmp_path):
+    cfg = resolve_auth_config(env={"MIRAGE_AUTH_TOKEN": "tok"},
+                              table={"auth_mode": "token"})
+    assert cfg.mode == AuthMode.TOKEN
+    assert cfg.bearer_token == "tok"
+
+
+def test_env_auth_mode_beats_config_table(tmp_path):
+    cfg = resolve_auth_config(env={"MIRAGE_AUTH_MODE": "local"},
+                              token_file=tmp_path / "missing",
+                              table={"auth_mode": "token"})
+    assert cfg.mode == AuthMode.LOCAL
+
+
+def test_jwt_settings_from_config_table(tmp_path):
+    key_file = tmp_path / "pub.pem"
+    key_file.write_text("KEYDATA")
+    cfg = resolve_auth_config(env={},
+                              table={
+                                  "auth_mode": "jwt",
+                                  "jwt_pubkey_file": str(key_file),
+                                  "jwt_alg": "RS256",
+                                  "jwt_issuer": "https://issuer",
+                                  "jwt_audience": "aud",
+                                  "jwt_authorized_parties": "a,b",
+                                  "jwt_clock_skew": 9,
+                              })
+    assert cfg.mode == AuthMode.JWT
+    assert cfg.jwt is not None
+    assert cfg.jwt.key == "KEYDATA"
+    assert cfg.jwt.algorithm == "RS256"
+    assert cfg.jwt.issuer == "https://issuer"
+    assert cfg.jwt.audience == "aud"
+    assert cfg.jwt.authorized_parties == ("a", "b")
+    assert cfg.jwt.clock_skew_seconds == 9
+
+
+def test_env_jwt_alg_beats_config_table(tmp_path):
+    key_file = tmp_path / "pub.pem"
+    key_file.write_text("KEYDATA")
+    cfg = resolve_auth_config(env={
+        "MIRAGE_AUTH_MODE": "jwt",
+        "MIRAGE_JWT_PUBKEY_FILE": str(key_file),
+        "MIRAGE_JWT_ALG": "ES256",
+    },
+                              table={"jwt_alg": "RS256"})
+    assert cfg.jwt is not None
+    assert cfg.jwt.algorithm == "ES256"
+
+
+def test_secret_keys_have_no_config_key():
+    assert "jwt_pubkey" not in ALLOWED_KEYS
+    assert "MIRAGE_AUTH_TOKEN" not in ALLOWED_KEYS
+    assert "auth_mode" in ALLOWED_KEYS
+    assert "jwt_alg" in ALLOWED_KEYS

python/tests/server/auth/test_jwt.py

@@ -0,0 +1,202 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import time
+from dataclasses import dataclass
+
+import jwt as pyjwt
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from mirage.server.auth.config import JWTConfig
+from mirage.server.auth.jwt import JWTVerificationError, verify_jwt
+
+
+@dataclass
+class KeyPair:
+    private_pem: bytes
+    public_pem: bytes
+
+
+@pytest.fixture(scope="module")
+def rsa_keys() -> KeyPair:
+    private_key = rsa.generate_private_key(public_exponent=65537,
+                                           key_size=2048)
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    public_pem = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return KeyPair(private_pem=private_pem, public_pem=public_pem)
+
+
+def _make_cfg(rsa_keys: KeyPair, **overrides) -> JWTConfig:
+    base = dict(
+        key=rsa_keys.public_pem.decode(),
+        algorithm="RS256",
+        issuer=None,
+        audience=None,
+        authorized_parties=(),
+        clock_skew_seconds=5,
+    )
+    base.update(overrides)
+    return JWTConfig(**base)
+
+
+def _sign(rsa_keys: KeyPair,
+          claims: dict,
+          *,
+          alg: str = "RS256",
+          headers: dict | None = None) -> str:
+    return pyjwt.encode(claims,
+                        rsa_keys.private_pem,
+                        algorithm=alg,
+                        headers=headers)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_accepts_valid_rs256(rsa_keys):
+    cfg = _make_cfg(rsa_keys)
+    token = _sign(rsa_keys, {"sub": "user-1", "exp": int(time.time()) + 60})
+    claims = verify_jwt(token, cfg)
+    assert claims["sub"] == "user-1"
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_rejects_alg_none(rsa_keys):
+    cfg = _make_cfg(rsa_keys)
+    token = pyjwt.encode({
+        "sub": "x",
+        "exp": int(time.time()) + 60
+    },
+                         key="",
+                         algorithm="none")
+    with pytest.raises(JWTVerificationError):
+        verify_jwt(token, cfg)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_rejects_alg_confusion(rsa_keys):
+    cfg = _make_cfg(rsa_keys, algorithm="RS256")
+    token = pyjwt.encode({
+        "sub": "x",
+        "exp": int(time.time()) + 60
+    },
+                         key="shared-secret",
+                         algorithm="HS256")
+    with pytest.raises(JWTVerificationError):
+        verify_jwt(token, cfg)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_rejects_missing_exp(rsa_keys):
+    cfg = _make_cfg(rsa_keys)
+    token = _sign(rsa_keys, {"sub": "x"})
+    with pytest.raises(JWTVerificationError):
+        verify_jwt(token, cfg)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_rejects_expired(rsa_keys):
+    cfg = _make_cfg(rsa_keys, clock_skew_seconds=0)
+    token = _sign(rsa_keys, {"sub": "x", "exp": int(time.time()) - 60})
+    with pytest.raises(JWTVerificationError):
+        verify_jwt(token, cfg)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_accepts_within_clock_skew(rsa_keys):
+    cfg = _make_cfg(rsa_keys, clock_skew_seconds=30)
+    token = _sign(rsa_keys, {"sub": "x", "exp": int(time.time()) - 5})
+    claims = verify_jwt(token, cfg)
+    assert claims["sub"] == "x"
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_rejects_wrong_issuer(rsa_keys):
+    cfg = _make_cfg(rsa_keys, issuer="https://issuer.example")
+    token = _sign(
+        rsa_keys, {
+            "sub": "x",
+            "exp": int(time.time()) + 60,
+            "iss": "https://attacker.example",
+        })
+    with pytest.raises(JWTVerificationError):
+        verify_jwt(token, cfg)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_rejects_wrong_audience(rsa_keys):
+    cfg = _make_cfg(rsa_keys, audience="mirage-daemon")
+    token = _sign(rsa_keys, {
+        "sub": "x",
+        "exp": int(time.time()) + 60,
+        "aud": "something-else",
+    })
+    with pytest.raises(JWTVerificationError):
+        verify_jwt(token, cfg)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_rejects_unauthorized_party(rsa_keys):
+    cfg = _make_cfg(rsa_keys, authorized_parties=("https://app.example", ))
+    token = _sign(
+        rsa_keys, {
+            "sub": "x",
+            "exp": int(time.time()) + 60,
+            "azp": "https://attacker.example",
+        })
+    with pytest.raises(JWTVerificationError):
+        verify_jwt(token, cfg)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_accepts_matching_authorized_party(rsa_keys):
+    cfg = _make_cfg(rsa_keys,
+                    authorized_parties=("https://app.example",
+                                        "https://other.example"))
+    token = _sign(rsa_keys, {
+        "sub": "x",
+        "exp": int(time.time()) + 60,
+        "azp": "https://other.example",
+    })
+    claims = verify_jwt(token, cfg)
+    assert claims["sub"] == "x"
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_rejects_bad_typ_header(rsa_keys):
+    cfg = _make_cfg(rsa_keys)
+    token = _sign(rsa_keys, {
+        "sub": "x",
+        "exp": int(time.time()) + 60
+    },
+                  headers={"typ": "NotAJWT"})
+    with pytest.raises(JWTVerificationError):
+        verify_jwt(token, cfg)
+
+
+@pytest.mark.no_host_override
+def test_verify_jwt_accepts_missing_typ_header(rsa_keys):
+    # Some issuers omit `typ` entirely. PyJWT does not require it,
+    # and we should not force it when it's absent.
+    cfg = _make_cfg(rsa_keys)
+    token = _sign(rsa_keys, {"sub": "x", "exp": int(time.time()) + 60})
+    claims = verify_jwt(token, cfg)
+    assert claims["sub"] == "x"

python/tests/server/auth/test_middleware.py

@@ -0,0 +1,200 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import time
+from dataclasses import dataclass
+
+import jwt as pyjwt
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from httpx import ASGITransport, AsyncClient
+
+from mirage.server import build_app
+from mirage.server.auth.config import AuthConfig, JWTConfig
+
+
+@dataclass
+class KeyPair:
+    private_pem: bytes
+    public_pem: bytes
+
+
+@pytest.fixture(scope="module")
+def rsa_keys() -> KeyPair:
+    private_key = rsa.generate_private_key(public_exponent=65537,
+                                           key_size=2048)
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    public_pem = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return KeyPair(private_pem=private_pem, public_pem=public_pem)
+
+
+def _client(app, headers=None):
+    transport = ASGITransport(app=app)
+    return AsyncClient(transport=transport,
+                       base_url="http://test",
+                       headers=headers or {})
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_local_mode_accepts_correct_bearer():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="local",
+                                           local_token="correct-token"))
+    async with _client(app, {"Authorization": "Bearer correct-token"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 200
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_local_mode_rejects_wrong_bearer():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="local",
+                                           local_token="correct-token"))
+    async with _client(app, {"Authorization": "Bearer wrong-token"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 401
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_local_mode_rejects_missing_header():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="local",
+                                           local_token="correct-token"))
+    async with _client(app) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 401
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_local_mode_no_token_lets_everything_through():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="local", local_token=None))
+    async with _client(app) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 200
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_token_mode_accepts_correct_token():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="token",
+                                           bearer_token="operator-pat"))
+    async with _client(app, {"Authorization": "Bearer operator-pat"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 200
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_token_mode_rejects_wrong_token():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="token",
+                                           bearer_token="operator-pat"))
+    async with _client(app, {"Authorization": "Bearer something-else"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 401
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_token_mode_rejects_jwt_shaped_value():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="token",
+                                           bearer_token="operator-pat"))
+    fake_jwt = "aaaa.bbbb.cccc"
+    async with _client(app, {"Authorization": f"Bearer {fake_jwt}"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 401
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_jwt_mode_accepts_valid_signed(rsa_keys):
+    jwt_cfg = JWTConfig(key=rsa_keys.public_pem.decode(), algorithm="RS256")
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="jwt", jwt=jwt_cfg))
+    token = pyjwt.encode({
+        "sub": "agent",
+        "exp": int(time.time()) + 60
+    },
+                         rsa_keys.private_pem,
+                         algorithm="RS256")
+    async with _client(app, {"Authorization": f"Bearer {token}"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 200
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_jwt_mode_rejects_opaque_bearer(rsa_keys):
+    jwt_cfg = JWTConfig(key=rsa_keys.public_pem.decode(), algorithm="RS256")
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="jwt", jwt=jwt_cfg))
+    async with _client(app, {"Authorization": "Bearer not-a-jwt"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 401
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_jwt_mode_rejects_expired(rsa_keys):
+    jwt_cfg = JWTConfig(key=rsa_keys.public_pem.decode(),
+                        algorithm="RS256",
+                        clock_skew_seconds=0)
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="jwt", jwt=jwt_cfg))
+    token = pyjwt.encode({
+        "sub": "agent",
+        "exp": int(time.time()) - 60
+    },
+                         rsa_keys.private_pem,
+                         algorithm="RS256")
+    async with _client(app, {"Authorization": f"Bearer {token}"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 401
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_health_endpoint_always_open():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="local",
+                                           local_token="some-token"))
+    async with _client(app) as c:
+        r = await c.get("/v1/health")
+        assert r.status_code == 200
+
+
+@pytest.mark.no_auth_override
+@pytest.mark.asyncio
+async def test_authorization_header_without_bearer_prefix_rejected():
+    app = build_app(idle_grace_seconds=10.0,
+                    auth_config=AuthConfig(mode="local",
+                                           local_token="correct-token"))
+    async with _client(app, {"Authorization": "correct-token"}) as c:
+        r = await c.get("/v1/workspaces")
+        assert r.status_code == 401

python/tests/server/auth/test_storage.py

@@ -0,0 +1,60 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import os
+import stat
+
+import pytest
+
+from mirage.server.auth.storage import (default_token_file, ensure_token_file,
+                                        read_token_file)
+from mirage.server.env import ENV_HOME
+
+
+@pytest.mark.no_host_override
+def test_ensure_token_file_creates_with_0o600(tmp_path):
+    target = tmp_path / "subdir" / "auth_token"
+    token = ensure_token_file(target)
+    assert target.exists()
+    assert target.read_text().strip() == token
+    assert token, "minted token must be non-empty"
+    mode = stat.S_IMODE(os.stat(target).st_mode)
+    assert mode == 0o600, f"expected 0o600, got {oct(mode)}"
+
+
+@pytest.mark.no_host_override
+def test_ensure_token_file_is_idempotent(tmp_path):
+    target = tmp_path / "auth_token"
+    first = ensure_token_file(target)
+    second = ensure_token_file(target)
+    assert first == second, "second call must reuse existing token"
+
+
+@pytest.mark.no_host_override
+def test_read_token_file_returns_none_when_missing(tmp_path):
+    target = tmp_path / "absent"
+    assert read_token_file(target) is None
+
+
+@pytest.mark.no_host_override
+def test_read_token_file_returns_stripped_contents(tmp_path):
+    target = tmp_path / "auth_token"
+    target.write_text("  abc-def  \n")
+    assert read_token_file(target) == "abc-def"
+
+
+@pytest.mark.no_host_override
+def test_default_token_file_follows_mirage_home(tmp_path, monkeypatch):
+    monkeypatch.setenv(ENV_HOME, str(tmp_path))
+    assert default_token_file() == tmp_path / "auth_token"