DEV Community: H. Kamran

Remotely Access Your Home Assistant Instance Securely

H. Kamran — Sat, 04 May 2024 00:31:57 +0000

If you want to access your Home Assistant instance outside your local network, you have a few options. You could try port-forwarding port 8123 or whatever port you use, expose your reverse proxy, or you could sign up for Nabu Casa's subscription service. But what about Cloudflare Tunnels?

Prerequisites

Before we begin, there are two things you'll need:

A Cloudflare account
A domain linked to that Cloudflare account

Set up the tunnel

Create the tunnel

First, connect the tunnel from your server to Cloudflare. If you have not already done so, create a new tunnel in the Zero Trust dashboard by going to Networks > Tunnels. Give your tunnel a name that means something to you (only you will be able to see it in this dashboard). Select the Docker tab and copy the docker run command because we will need it in a second. Next, let's configure traffic routing from the tunnel to the service. Enter the domain and subdomain, then select the type of service. Since this is for Home Assistant, set the type to HTTP. Assuming that you followed the instructions on setting Home Assistant up with Compose, your Home Assistant container's network_mode is host, therefore, the service URL should be host.docker.internal:8123.

Connect the tunnel

Because this guide assumes you are using Docker Compose, add a new service for the tunnel connector in your compose.yml or docker-compose.yml file that you are using for Home Assistant. Make sure to replace [your token here] with the token from the docker run command you copied earlier.

tunnel:
  image: cloudflare/cloudflared:latest
  command: tunnel --no-autoupdate run --token [your token here]
  depends_on:
    - homeassistant # or whatever the Home Assistant service (not the container name!) is named in the Compose file
  environment:
    TZ: "[your timezone]"
  restart: always
  extra_hosts:
    - "host.docker.internal:host-gateway" # Required to use `host.docker.internal`

Once the Compose file has been updated, run docker compose up -d or the equivalent in whatever container system is running on your system. This will pull the cloudflared¹ image and then establish a tunnel to Cloudflare. If all is well, you should be able to reload the Zero Trust dashboard and see that the tunnel status is healthy. Try visiting your site in a new tab and see if it is accessible. If you get a 400 Bad Request error, you may need to update the http.trusted_proxies array in your configuration.yaml file. For more information on host.docker.internal, check out this Stack Overflow answer.

Secure the tunnel

At this point, your tunnel is set up and you can use Home Assistant from outside your network, but right now it is very insecure.

There are two parts to this step. Part one allows connections from any browser or device, as long as it is not the mobile apps. Part two allows connections exclusively from the mobile apps. For the best experience, follow both parts.

Part One: Cloudflare Access

Cloudflare Access is part of Cloudflare's Zero Trust offering. It is designed to secure apps by placing an identity portal in front. To configure it, go to the Zero Trust dashboard, then Access > Applications. Ensure you have configured an identity provider in Settings > Authentication first. Click "Add an application", then select the "Self-hosted" option. Choose an application name, and be aware that this will be visible to those who visit the public URL. I set mine to "Home Assistant". After that, enter the same domain and subdomain that you configured for the tunnel. Then click "Next" to advance to the policy configuration page.

The policy configuration page is where you configure who can access the site. If you have previously created Access Groups, you can select those here. Regardless of whether you use a group or not, you still have to enter a policy name and add your rules. For example, I configured my policies to only allow users who have specific emails and are in the United States. I did this by going to the "Include" section, setting the selector to "Emails", then adding comma-separated emails in the value field. I then added a "Require" rule that ensures the visitor is in the U.S.

Finally, click "Next" and then "Add application". Your Home Assistant instance is now secured. Try visiting your site again from a normal browser window and also from a private window.

The downside to using Access is that the Home Assistant mobile apps cannot handle it right now,² but there is another way to secure the tunnel and allow the mobile apps to work.

Part Two: mTLS Certificates

mTLS certificates, or mutual TLS certificates, are a way of securely connecting to services without credentials. Cloudflare has support for this through the Zero Trust dashboard, but that requires an Enterprise plan. Instead, we will use their client certificates offering.

Note: The iOS companion app does not support mTLS. See the discussion in #1788 and the comment from Franck Nijhof (one of the Home Assistant maintainers) on PR #2144 for more information.

To get started, one change needs to be made to the tunnel configuration. Go to Access > Tunnels, and select the tunnel you created earlier and click the "Configure" button. Under the "Public Hostname" tab, add another hostname. The service options should be set to the same thing you have set for the existing hostname. I recommend using the same domain and subdomain as the main hostname with -mobile added to the subdomain. For example, if the main subdomain is ha, then use ha-mobile as the subdomain for this hostname.

Next, go to the main Cloudflare dashboard and open the Client Certificates page (under SSL/TLS). Click "Create Certificate" and ensure the private key type is set to "RSA (2048)". I left the certificate validity at 10 years. Then create the certificate.

Ensure the key format is PEM, then copy the certificate into a file called cf-client.pem, and the private key into cf-client.key. You can change these filenames, but I recommend keeping the extensions. Make sure you make a backup as you will not be able to see this certificate again. Under the "Hosts" header, click the "Edit" button next to "None", then type in the second URL you created for the tunnel, e.g. ha-mobile.yourdomain.com. Click "Save". This ensures that the subdomain can be used with mTLS.

Now that the certificate has been created, it needs to be transferred to a device running the mobile app. But before that, it needs to be converted into a PKCS #12 (PFX) archive. Assuming your computer has OpenSSL installed, it's easy to generate a PFX file. In the same directory as the .pem and .key files you created earlier, run the following command, replacing cf-client.key and cf-client.pem with your filenames:

openssl pkcs12 -export -out cf-client.pfx -inkey cf-client.key -in cf-client.pem

A prompt for an export password will appear. Android failed to install the PFX I generated without a password, so make sure to add one. After that, you should have a PFX file that is ready to be installed. Transfer it securely to your device and install it by tapping the file. Enter the export password you created, then select "VPN & app user certificate" in the pop-up. Your certificate is now installed and ready for use.

Open the Home Assistant app, select your server, and set your external URL (the "Home Assistant URL") to the URL you set up for mTLS authentication. If you are connected to your local network, disconnect and try accessing Home Assistant. You should be able to use Home Assistant outside your local network now.

Conclusion

If you have any questions, need any help, or have any suggestions, feel free to contact me on Twitter, Mastodon, or Bluesky, or leave a comment.

If you have any improvements to any of my articles or notes, please leave a comment or submit a pull request.

The name cloudflared comes from the Unix tradition of naming servers with a "-d" suffix standing for "daemon". (text adapted from Cloudflare) ↩
The Home Assistant maintainers have rejected all attempts to add additional authentication methods to the companion app, as evidenced by PR #3510, PR #4160, PR #2144 and issue #167. The official guidance from them is to use a browser instead. ↩

Securing Your Digital Life

H. Kamran — Fri, 16 Jun 2023 06:46:42 +0000

Your digital self controls your life. Lose your password, and you're locked out of a potentially important email or bank account. It's even worse if you don't have any recovery systems set up. But what's worse is if you are hacked. Your digital self, ripped away. Your social media accounts, your connection to friends, family, and others, disappearing in an instant. However, there are proactive measures you can take.

Passwords

The first thing you can do is ensure you have strong passwords. Try entering your most commonly used passwords into Security.org's tool, and see how long it takes to crack your password. According to a 2021 Statista survey, 64% of U.S. respondents had passwords 8–11 characters.¹ Assuming a mix of numbers, uppercase and lowercase letters, an 11-character password will take ten months to crack.²

The easiest way to secure your password is to get a password manager. I recommend against using Google's password manager, given that it's built into your browser, so if your browser is compromised, there goes your passwords. If you use an iOS/iPadOS or Safari on macOS, Apple has a password manager built-in that's secured by end-to-end encryption, as well as encrypted locally by the onboard chips until the password is needed. Alternatively, if you use multiple platforms, or prefer not to use Apple's offering, there's Bitwarden, 1Password, and Dashlane to name a few. Definitely don't use LastPass, their security has been well covered in the media.

If you choose to use a third-party password manager, make sure to set a strong password for that. Bitwarden created a password and passphrase generator that you can use to create a master password.

No matter what password manager you use, the first step is to add all your existing passwords to it. Whenever you create a new account, generate a strong password using the tool. I recommend at least 20 characters using a mix of numbers, uppercase and lowercase letters, and four or more symbols. Go through all your passwords and strengthen them by changing your passwords.

Breach Alerts

The number one rule when it comes to passwords is do not reuse them. Many services, including 500px, Adobe, Audi, Bitly, and many others, have been breached, resulting in passwords, emails, and other sensitive information being stolen. A wonderful, free service called Have I Been Pwned (HIBP), created by security researcher Troy Hunt and used by companies and governments around the world, shows users which of their accounts have been breached³, and can also inform them as soon as a breach is published. I highly recommend putting your emails into the service to check if any associated accounts have been breached, and if they have, change the passwords. The other thing I highly recommend is signing up for HIBP notifications on all your emails. This will allow you to know almost immediately if your account was leaked in a breach.

Multi-factor Authentication

Multi-factor authentication, also known as two-factor authentication, 2FA, or MFA, is where a user is required to enter two or more verification methods before authentication can proceed. You should enable multi-factor authentication on all your accounts, especially for those accounts that secure personal identifiable information (PII)⁴. Some key accounts that should absolutely be secured, even if you don't use MFA on any other service, include your financial accounts (including revenue agencies like the U.S. Internal Revenue Service, the Canada Revenue Agency, AFIP, etc.), your government accounts (e.g. Login.gov, Singpass, etc.), and your healthcare accounts (e.g. insurance, patient portals (like MyChart), etc.).

Don't just take my word for it. Many government agencies, including, but certainly not limited to, the U.S. Cybersecurity and Infrastructure Security Agency (CISA), the UK National Cyber Security Centre, and the Australian Cyber Security Centre, recommend MFA.

When you enable MFA, try to avoid text messages, phone calls, and email as authentication methods. Text messages and phone calls are susceptible to a SIM swap scam, which is when a malicious person contacts a mobile service provider to change the SIM which has phone calls and text messages routed to it. For more information on SIM swap scams, check out the Wikipedia page or this Norton article.

The best method to use is FIDO2, also known as WebAuthn. FIDO2 uses physical security keys, such as Yubico's YubiKey series or Google's Titan keys, or mobile devices. These devices make up phishing-resistant MFA. This name was given because the token that is generated for MFA will not work with any site other than the site it was registered with. It's recommended to register at least two keys per account in case you lose one. Some, like Apple, require at least two keys. The U.S. federal government requires phishing-resistant MFA through the Federal Zero Trust Strategy. The U.S. National Institute of Standards and Technology (NIST) is recommending phishing-resistant MFA through the draft version of SP 800-63-4 (Digital Identity Guidelines)⁵. Many companies, including Cloudflare and Figma, have mandated FIDO2 security keys because they are phishing-resistant.

In the event that the site doesn't offer FIDO2 or you don't have a FIDO2-capable device, the other recommended method is time-based one-time password (TOTP), popularized by Google Authenticator. Nowadays, there are countless apps that can generate TOTP, including iOS/iPadOS' built-in authenticator (I personally only recommend using it if you only use iOS/iPadOS and Safari on macOS), Authy (a cross-platform synced authenticator), and Google Authenticator. I personally use Authenticator Pro (an open-source authenticator for Android) on my Android devices, and OTP Auth on my iOS devices. Most password managers offer to store TOTP keys in their vaults for you, but that means that all your eggs are in one basket.

I try to avoid proprietary MFA solutions like Symantec VIP, which a lot of U.S. financial institutions love⁶. Instead, and only for those services, I use SMS MFA. One big problem with SMS MFA is if you travel, you don't necessarily have access to your texts. To prevent losing access to those services that use SMS, you could use a service like Google Voice as the phone number for MFA codes.

If you're curious about what MFA options a service offers, check out 2FA Directory⁷, a directory of sites that support, and don't support, MFA. If a service is not there, add it by following our contribution guide.

Reviewing Account Access

Have you ever been asked to sign in with Google, Twitter, Apple, Facebook, or some other social platform? When you do that, those platforms share some data. For example, with Google, it might be allowing an app to access your Google Drive to store configuration⁸. Or with Twitter, an app may want the ability to view Tweets that you've posted and accounts you follow. It's a good practice to periodically go through your platform's security dashboards to review what apps have access to what. The table below contains links to the dashboards of the most common platforms. If you don't recognize an app or device linked to your account, remove it.

In addition to checking what apps are linked to your account, make sure to review what devices are currently logged in to your account.

| Platform | App Access | Logged-in Devices | |----------|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------| | Apple | Sign-In and Security (under Sign in with Apple) | Devices | | Facebook | Apps and Websites | Where you're logged in | | Google | Apps with access to your account | Your devices | | Twitter | Connected Apps | Sessions |

Privacy Rights

If you're in the European Economic Area, Canada, the U.S. states of California, Colorado, Utah, Virginia, or another area that has comprehensive data privacy legislation, you have a few rights. EEA residents are protected by the General Data Protection Regulation (GDPR), Canadian residents are protected by the Personal Information Protection and Electronic Documents Act (PIPEDA), California residents are covered by the California Consumer Privacy Act (CCPA) and the California Privacy Rights Act (CPRA), and so on, so forth. These regulations give individuals the right to know what personal information an entity⁹ collects, the right to delete personal information collected, the right to opt-out of the sale of your personal information, and the right to not be discriminated against for exercising your rights.

A full list of rights can be found by clicking on the corresponding legislation from the following non-exhaustive list of links: GDPR (EEA), PIPEDA (Canada), CCPA/CPRA (California), CPA (Colorado), UCPA (Utah), and VCDPA (Virginia).

Conclusion

If you have any questions or need any help, feel free to contact me on Twitter or Mastodon.

If you have any improvements to any of my articles or notes, please submit a pull request.

Thank you for reading!

Average number of characters for a password in the United States in 2021 — Statista ↩
Are Your Passwords in the Green? — Hive Systems ↩
For more information, check out Troy's post on how he verifies data breaches before putting them in HIBP ↩
PII is defined as "information that can be used to distinguish or trace an individual’s identity" (source: U.S. General Services Administration). Some examples of PII include your full name, your national ID number/Social Security Number/your country's equivalent, financial account numbers (including credit and debit card numbers), address, phone number, and more. A more comprehensive list can be found on Matomo Analytics's website. ↩
NIST's Digital Identity Guidelines provides technical requirements for U.S. federal agencies implementing account services (source: NIST). While intended for federal agencies, many companies follow the guidelines or use them as a guideline. ↩
U.S. financial institutions, please follow Vanguard's example and support FIDO2! ↩
Full disclosure: I am a maintainer of the site ↩
If an app is asking to access your entire Google Drive, check if it really needs that permission. For example, a game requesting that permission probably doesn't need that, and is using it for promotional or other purposes. Google offers developers a scoped permission that limits an app's access to a dedicated folder created just for them in your Google Drive. You might see this permission as "View and manage its own configuration in your Google Drive", or something similar. ↩
The definition of an entity depends on the legislation. For example, under the GDPR, entities refer to "a company or entity which processes personal data as part of the activities of one of its branches established in the EU, regardless of where the data is processed; or a company established outside the EU and is offering goods/services (paid or for free) or is monitoring the behaviour of individuals in the EU" (source: Who does the data protection law apply to?). For another example, under the PIPEDA, entities are defined as "private-sector organizations across Canada that collect, use or disclose personal information in the course of a commercial activity" (source: PIPEDA in brief). For one last example, under the CCPA/CPRA, an entity is defined as a for-profit business that meets any of the following: have a gross annual revenue of over $25 million; buy, sell, or share the personal information of 100,000 or more California residents, households, or devices; or derive 50% or more of their annual revenue from selling California residents’ personal information (source: Cal Civ. Code § 1798.140(d)). ↩

Installing a Newer Version of Python on Amazon EC2

H. Kamran — Wed, 03 May 2023 16:37:28 +0000

I recently worked on a Python project that used Python 3.11 and Poetry. When I went to deploy it on Amazon's Elastic Compute Cloud, better known by its moniker EC2, I ran into a major hurdle. EC2, running Amazon Linux 2, had Python 3.7.11. The project required 3.11, so I needed to compile Python from source.

Dependencies

I started by updating packages in YUM, the package manager for Amazon Linux 2, with sudo yum update. Then I installed some development dependencies, namely the aptly-named "Development Tools" group and a few others with the following command.

sudo yum groupinstall "Development Tools"
sudo yum install libffi-devel bzip2-devel

One more dependency is needed: OpenSSL. The openssl-devel package included in the repositories with Amazon Linux 2 is 1.0.7, but Python 3 currently requires 1.1.1 or newer. This version is available through the openssl11-devel package. To install it, uninstall openssl-devel, then install openssl11-devel.

sudo yum uninstall openssl-devel
sudo yum install openssl11-devel

Compilation

With the development dependencies installed, the next step was to download the Python source code. The Python Software Foundation maintains tarballs of every Python version released, and they're available through this user-friendly page or their plain directory listing. Either way, find the Python version your project needs, then copy the link to the file that ends in .tgz, which is the gzipped tarball. With the link to the Python source in hand, download it with wget, then extract the archive.

sudo wget https://www.python.org/ftp/python/3.11.1/Python-3.11.1.tgz
sudo tar xzf Python-3.11.1.tgz
cd Python-3.11.1

Next, run the configure script, which will check to ensure that the necessary dependencies are installed: sudo ./configure --enable-optimizations. The --enable-optimizations flag optimizes the binary. After that finishes, there will be a Makefile. Before proceeding, decide whether this new version should replace the system version, or if it should be installed alongside. I recommend the latter, and that's what I used. If you decided to replace the system version, use sudo make install. If you decided to install it alongside, use sudo make altinstall. On my t2.micro instance, it took about 35 minutes to build.

Shell Configuration

Python installs to /usr/local/bin, but the PATH doesn't contain it. To add this folder to the PATH, open the ~/.bashrc file in your favourite text editor and add the following to the end.

export PATH=/usr/local/bin:$PATH

Reload the .bashrc file by running source ~/.bashrc, then try opening a Python shell with python3.11. Replace 3.11 with whatever Python version was installed.

Conclusion

If you have any questions or need any help, feel free to contact me on Twitter or Mastodon.

If you have any improvements to any of my articles or notes, please submit a pull request.

Thank you for reading!

Collecting Beta Testers and Cleaning TestFlight CSVs

H. Kamran — Wed, 26 Apr 2023 00:03:48 +0000

My friend Andrew Zheng recently started accepting beta testers for his new app via Google Forms. Forms comes with Google Sheets support built-in, so it's easy to get set up. However, a couple problems quickly surfaced.

First up, Andrew's form was set up with two fields: name and email.

Name	Email
Andrew Zheng	`aheze@getfind.app`
Joe Smith	`joe@smith.com`

TestFlight requires a CSV with three columns: first name, last name, and email.

First Name	Last Name	Email
Andrew	Zheng	`aheze@getfind.app`
Joe	Smith	`joe@smith.com`

The data needs to be converted first.

Parsing the Responses

To convert the two-column data to the three-column CSV, we first created a new sheet. We placed headers at the top for our own reference, First Name, Last Name, and Email, then created a formula to extract each part from the first sheet. The first sheet, named "Testers", contained all the responses from the form. To split the name, we started by using the SEARCH function, the Google Sheet/Excel equivalent of index/indexOf/index(where:), to check if there was a space in the name that we could use to split: SEARCH(" ", Testers!$B2). If there was, the formula used the LEFT function to create a substring up to that space:
LEFT(Testers!$B2, SEARCH(" ", Testers!$B2)). If not, it returned the original content of the cell. The full formula for the first name column is as follows.

=IF(ISNUMBER(SEARCH(" ", Testers!$B2)), LEFT(Testers!$B2, SEARCH(" ", Testers!$B2)), Testers!$B2)

The last name column has a similar formula, with two differences. The first is that the RIGHT function is used instead of LEFT. RIGHT returns a substring starting
from the end of the string. Because the RIGHT function is used, the SEARCH call inside it has to be subtracted from the total length of the string: LEN(Testers!$B2) - SEARCH(" ", Testers!$B2). The full formula for the last name column is below.

=IF(ISNUMBER(SEARCH(" ", Testers!$B2)), RIGHT(Testers!$B2, LEN(Testers!$B2) - SEARCH(" ", Testers!$B2)), Testers!$B2)

The email formula is very simple, just a reference to the cell in the responses sheet: =Testers!$C2. The three formulas are copied to all the rows in the sheet.

Cleaning the Responses

The next step was to upload it to TestFlight, but TestFlight threw an error with the most helpful message ever: "An error has occurred. Try again later." Apple, being its usual helpful self, opted to not provide any useful information that could help fix the errors with the CSV. After much trial and error, my friend was able to successfully import his CSV. But the amount of work it took to hunt down errors in a CSV led me to create TestFlight Cleaner. TestFlight Cleaner cleans your tester CSVs for you, and optionally shows why it's removing some entries.

TestFlight Cleaner

The first thing I had to do was figure out how to import a CSV and parse it using JavaScript. After reading through Stack Overflow, I stumbled upon the FileReader API, which has a convenient readAsText function. Since my website uses Next.js (which uses React), I used a useState hook to store the File object that the file input would provide, then I accessed that in a function. The function converts the file to text using the aforementioned function, then begins to process the CSV.

The first step is to turn the raw data into a two-dimensional array. The CSV text was split using the newline character \n, then each row was split using a comma as a delimiter. This output was stored in another useState
hook.

The next step is triggered via a useEffect hook monitoring the csvData useState hook, which is set by the processCsv function in the previous step. This step is the error-checking step. The first check is a column count. If it detects more or less than three columns, the step fails, and the user is prompted to fix the CSV. The other error is a malformed email check, which checks if an email contains an @ sign and matches a comprehensive regular expression. If this check fails, it lets the user know and continues, because it can bypass these rows. Finally, another useState hook is used to inform another useEffect hook that this step is complete.

The third step is to clean the CSV using a reducer. There are two settings the user can apply that affect this function: specifying the first row as the header row, and leaving malformed/duplicated rows in the preview.

Detecting Duplicates

The first part of this step is to check if the email has appeared in any preceding rows. If it has and the leave duplicated rows setting is active, it outputs a "duplicate" flag, and adds it to the array. If it has and the setting is inactive, it returns the existing array.

Checking for Malformed Emails

The next part is to check for malformed emails, achieved by performing a similar check as step two. If the leave malformed rows setting is active, it outputs a "malformed" flag, then adds it to the array. If neither of these parts are triggered, the reducer does the regular invalid character cleaning.

Cleaning Up Invalid Characters

The cleaning process strips all characters that aren't alphanumeric, periods, dashes, spaces or non-English characters from the first and last names. The email gets line break characters stripped. Finally, the function sets a useState hook with the cleaned data, and another useState hook with any duplicated emails. The duplicated emails hook is set only if the leave duplicated rows setting is active.

The final step is to make the preview. It loops over the two-dimensional cleaned CSV data to create a table, and if a malformed or duplicate flag is set, it places a colour on the email. Red signifies malformed and yellow signifies duplicated.

After a user requests an export using the button below the preview, a Blob is created by iterating over the cleaned rows to form it back into a CSV. An anchor element is created, with its URL set to the output of
URL.createObjectURL. A download attribute is also set, which sets the filename to "TestFlight Testers - Cleaned.csv". This element is then added to the DOM, clicked, then removed. The object URL is also revoked.

I hope that this tool comes in handy for you. If it does or you have any feedback, please contact me on Twitter or Mastodon. Thank you for reading!

Adding Wildcard Subdomain Support to macOS

H. Kamran — Mon, 16 Jan 2023 05:36:28 +0000

For several years now, I've been using IP addresses and ports to access services that I run on my home server. However, I decided it was time to switch to using a domain instead. I had heard about Traefik and Caddy
in r/HomeServer and r/homelab](https://www.reddit.com/r/homelab/) and chose to try out Traefik, mainly because it had native support for Docker labels.

The first few steps involved installing Traefik with Docker, adding HTTPS support through Let's Encrypt, and reconfiguring my web containers to use it. The next step was to add a dnsmasq rule to my Pi-hole so that all requests would be redirected to the subdomain I chose (I used servername.mydomain.com as the base host in Traefik). However, on my Mac, I'm not always using my Pi-hole's DNS, usually when I need to circumvent the ad-blocking. I accomplish this through macOS' native support for network locations.

After doing a bit of research, I found out I could use dnsmasq on my Mac to do accomplish wildcard subdomains, just like I did on the Pi-hole, and it worked wonderfully once I got it to work.

I used Homebrew to install and configure dnsmasq: brew install dnsmasq. I then opened the configuration file for dnsmasq from its place in /usr/local/etc/dnsmasq.conf and added the line below. If you changed the location of your Homebrew install, run brew --prefix, then replace /usr/local with the value.

address=/servername.mydomain.com/10.90.100.1

This line configures the routing, and redirects all requests made to servername.mydomain.com and its subdomains to 10.90.100.1. Make sure to replace 10.90.100.1 with the IP you want to redirect to. If you're interested in knowing why dnsmasq redirects all redirects to both the base domain and its subdomains to the IP, this Stack Overflow answer explains why.

To start dnsmasq, run sudo brew services start dnsmasq. Homebrew will handle autostarting the daemon and ensuring it stays alive. I found this to be simpler than the common method of copying the Homebrew launch daemon plist to /Library/LaunchDaemons and manually telling launchctl to load it.

If you were to try running a command such as ping to see if your wildcard subdomain redirection worked, you'd be sorely disappointed, because there are two more steps. Create a folder in /etc named resolver, and place a file in there. The file can be named anything, but I like to use the hostname of my computer. In that file, add nameserver 127.0.0.1. This tells macOS' DNS resolution to use your new dnsmasq as a DNS server. For example, I would run sudo mkdir /etc/resolver, then sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/my-computer-hostname'. Verify that the entry was added with scutil --dns. An output similar to the following should be shown.

resolver #8
  domain   : my-computer-hostname
  nameserver[0] : 127.0.0.1
  flags    : Request A records, Request AAAA records
  reach    : 0x00030002 (Reachable,Local Address,Directly Reachable Address)

After that, add the DNS server to macOS via the Network panel in System Preferences or the Wi-Fi panel in System Settings. If your Mac is running Ventura or newer, click "Details", otherwise click "Advanced". Then, navigate to the "DNS" tab. Click the plus button and type in 127.0.0.1 and then hit enter. For more information on 127.0.0.1, check out its Wikipedia article. Back to System Preferences, click the OK button, then click Apply. If you're running Ventura or newer, just click the OK button and it will save and apply the settings. Once the icon is disabled and greyed out, flush your DNS cache. You can do that with sudo dscacheutil -flushcache and sudo killall -HUP mDNSResponder. Now, try your ping command again, and you should get a response. If it does, try accessing the service through your browser.

If you have any questions or need any help, feel free to contact me on Twitter or Mastodon.

I hope that this article is useful for you! Thank you for reading!

Generate TypeScript Declaration Files for JavaScript Files

H. Kamran — Mon, 09 May 2022 19:44:17 +0000

I've been moving a few utilities that I use in multiple projects to npm libraries. But I needed an easy, reliable way to generate TypeScript declarations, since I primarily use TypeScript.

Open your project and ensure you have a package.json
Install the typescript library as a development dependency
- With pnpm: pnpm i -D typescript
- With npm: npm i -D typescript
- With yarn: yarn add typescript -D

Add JSDoc tags to your functions, variables, classes, etc.

For example, here's a snippet from one of my utilities:

/**
* Apply classes that result in a true condition
* @param {string[]} classes
* @returns A list of classes
*
* @example
* classNames("block truncate", selected ? "font-medium" : "font-normal")
*/
export const classNames = (...classes) => {
return classes.filter(Boolean).join(" ");
};

Add the prepare script (or whichever one you want to use) to the scripts object in package.json

For example, mine looks like this:
```
"scripts": {
"prepare": "tsc --declaration --emitDeclarationOnly --allowJs index.js"
},
```
This command runs tsc, the TypeScript compiler, and tells it to only generate .d.ts files (declaration files). Be sure to replace index.js with your JavaScript files.

The prepare script runs before a npm package is packed (typically with npm publish or npm pack, or the equivalents with other package managers).
Run your npm script
- With pnpm: pnpm prepare or pnpm run prepare
- With npm: npm run prepare
- With yarn: yarn run prepare

Using the classNames function above, the TypeScript compiler generated the following declaration:

export function classNames(...classes: string[]): string;

If you have any questions, send a tweet my way. I hope that this guide comes in handy for you, thanks for reading!

Dark Mode Toggle for Vue.js Apps with Vuetify

H. Kamran — Thu, 04 Jun 2020 23:55:08 +0000

Photo: Material.io

I use Vue.js and Vuetify for almost all of my websites and I’m a huge supporter of dark mode. One of the many reasons I chose Vuetify is because it has dark mode support out-of-the-box. So, without further ado, let me guide you through easily changing the dark mode state.

Setting the Default Dark Mode State

In order to set the default dark mode state, we have to open the plugin file for Vuetify, which is available at src/plugins/vuetify.js. By default, the file should look like the following.

import Vue from "vue";
import Vuetify from "vuetify/lib";

Vue.use(Vuetify);

export default new Vuetify({});

To set the default state, we have to create a new object in the constructor called theme, and inside of that, set a variable called dark to true.

export default new Vuetify({
    theme: {
        dark: true
    }
});

But if we want to change it from the user-facing interface, we have to use the variable provided by Vuetify.

Setting the Dark Mode State From the Interface

A copy of the final code is available at the bottom.

Before even adding the theme state-changing code, you have to decide where to put the code. You only have to put it in one location, preferably a location that is persistent, such as your App.vue or a component that is present on all pages, such as a navigation bar. With that decided, we can actually get to work.

In your file (I’m using a component that I’ve called NavigationBar), go to the script tag. There should be an export statement present. If not, go ahead and create it. The contents of the script tag should look similar to this:

export default {
    name: "NavigationBar"
}

First, we need to add the method that will be called when the user clicks on a button. Underneath the name parameter, add a new object called methods.

export default {
    name: "NavigationBar",
    methods: {}
}

I’m going to call my method toggleDarkMode, but feel free to call it whatever you’d like. This method is going to set the dark mode variable (this.$vuetify.theme.dark) to the inverse of what it is currently set to (if the theme is currently light, then this variable will be false), then set a local storage variable called darkTheme to the value of that variable.

methods: {
    toggleDarkMode: function() {
        this.$vuetify.theme.dark = !this.$vuetify.theme.dark;
        localStorage.setItem("darkTheme", this.$vuetify.theme.dark.toString());
    }
}

With the function implemented, we now have to make it so that site will automatically pick up the theme state from the browser with the prefers-color-scheme CSS media query and/or the local storage state. The prefers-color-scheme state is set by your system.

To accomplish our task, we will use a Vue lifecycle hook called mounted which is called, as you may have guessed, when the component is mounted. We’ll add mounted() {} underneath the methods object.

export default {
    name: "NavigationBar",
    methods: { ... },
    mounted() {}
}

We will first check what the value of our local storage variable is. If it exists, this.$vuetify.theme.dark is set to the value of the variable. If it doesn’t, we’ll check whether the user has dark mode enabled on their system, and set it to that.

mounted() {
    const theme = localStorage.getItem("darkTheme");

    // Check if the user has set the theme state before
    if (theme) {
        if (theme === "true") {
            this.$vuetify.theme.dark = true;
        } else {
            this.$vuetify.theme.dark = false;
        }
    } else if (
        window.matchMedia &&
        window.matchMedia("(prefers-color-scheme: dark)").matches
    ) {
        this.$vuetify.theme.dark = true;
        localStorage.setItem(
            "darkTheme",
            this.$vuetify.theme.dark.toString()
        );
    }
}

All that’s left is to add a button to toggle the state. In the template tag, add the following:

<v-btn icon @click="toggleDarkMode">
    <v-icon>mdi-theme-light-dark</v-icon>
</v-btn>

The code above is simple. It creates a Vuetify icon button, tells it to use the theme-light-dark icon from Material Design Icons and to add an event handler, which on click, calls the toggleDarkMode method.

That’s it. You’re finished! As I mentioned earlier, the final code is available on this GitHub Gist.

Thanks for reading!

Getting balenaEtcher to Work on macOS Catalina

H. Kamran — Fri, 31 Jan 2020 01:38:24 +0000

I just recently upgraded to macOS Catalina, and needed to flash a microSD card for my Raspberry Pi. However, balenaEtcher was throwing an error when trying to flash the image.

After a little while, I realized that Catalina included some extra privacy protections. I went into System Preferences and turned on “Full Disk Access” for balenaEtcher. But lo and behold, the error still persisted.

The Solution

After doing a bit of research, I found that balenaEtcher, and Etcher (the former name of balenaEtcher), had a command-line utility to launch the app.

sudo /Applications/balenaEtcher.app/Contents/MacOS/balenaEtcher

The command booted up a graphical interface of balenaEtcher, the difference that, because of the “sudo” in the command, it ran under the root user. This bypassed the security/privacy restrictions placed (wisely) by Apple on Catalina.

Extracting PKGs on macOS

H. Kamran — Thu, 30 Jan 2020 14:31:01 +0000

Photo by: seth schwiet on Unsplash

Let's say you're on a computer where you don’t have administrative access, but you really need to use this one piece of software. In my case, this was Apple’s SF Symbols app. There’s a pretty simple way to extract the payload from the package (.PKG).

To get started, you first need two things. A macOS-equipped computer and a DMG with a PKG inside, or just a PKG. This tutorial will detail both.

Extracting the Package Contents

If your PKG is inside of a DMG, start here

To extract the payload from a PKG inside of a DMG, we need to mount the DMG. There are two ways to do this. You can either use the Finder (double-click the DMG to mount it) or use the terminal with the following command: hdiutil attach [path to your DMG]. For example, hdiutil attach ~/Downloads/SF\ Symbols.dmg.

PKG Extraction

Now is where we have to use the terminal. In your terminal, navigate to the folder just above where you want your PKG to be extracted. An example command is as follows: cd ~/Documents.

You can then proceed to extract the PKG with: pkgutil --expand-full [package to PKG] [folder to extract to]. For example, pkgutil --expand-full /Volumes/SFSymbols/SF\ Symbols.pkg extracted_package.

The contents of the PKG are now available in the extracted_package folder. With the SF Symbols.pkg extracted, it has three directories: Distribution and Resources, SFSymbols.pkg.

The content of the PKG is stored in the (in my case) SFSymbols.pkg folder.

The folder hierarchy of the Payload folder (extracted_package/[package name]/Payload) is very simple. The directories are the places to put the files. For example, the directory Applications has SF Symbols.app, because that needs to be put in the Applications folder on your computer.

Once you have extracted the Payload, you can eject the volume (if you are using a DMG) or delete the PKG, as you no longer need it.