<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: INNERLUXES</title>
    <description>The latest articles on DEV Community by INNERLUXES (@innerluxes).</description>
    <link>https://dev.to/innerluxes</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4155527%2Fbb21b91e-fc68-4232-b4d7-a605d5dc602a.png</url>
      <title>DEV Community: INNERLUXES</title>
      <link>https://dev.to/innerluxes</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/innerluxes"/>
    <language>en</language>
    <item>
      <title>The Permission Model Is the Product: Occupational Health Case Management on Salesforce</title>
      <dc:creator>INNERLUXES</dc:creator>
      <pubDate>Sun, 15 Nov 2026 20:10:56 +0000</pubDate>
      <link>https://dev.to/innerluxes/the-permission-model-is-the-product-occupational-health-case-management-on-salesforce-5ddg</link>
      <guid>https://dev.to/innerluxes/the-permission-model-is-the-product-occupational-health-case-management-on-salesforce-5ddg</guid>
      <description>&lt;p&gt;An occupational health case moves through examination, restriction, treatment and return to work. Five roles touch it: a physician, a nurse, a case manager, the employer and a safety officer. Each one needs a different slice of the same record, and one of them must never see the diagnosis.&lt;/p&gt;

&lt;p&gt;That sentence is the whole engineering problem. The employer is entitled to know whether a worker can lift, climb or drive. The employer is not entitled to know why. If that distinction is not expressed in the data model, no amount of sharing rules will hold it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Spreadsheets fail for a reason that is not convenience
&lt;/h2&gt;

&lt;p&gt;Shared drives and paper forms do not fail because they are old. They fail because they cannot enforce who sees what, and they cannot prove afterwards who looked. Both halves matter. An audit question six months later is answered from a system or it is not answered at all.&lt;/p&gt;

&lt;h2&gt;
  
  
  Model the case as several objects, not one
&lt;/h2&gt;

&lt;p&gt;The temptation is a single fat record with a hundred fields. It is faster to build and it leaks immediately, because the moment the employer is allowed to see the restriction they can also see whatever clinical field sits beside it.&lt;/p&gt;

&lt;p&gt;What works instead:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;separate objects for the case, the encounter, the exposure event, the restriction, the surveillance result, the employer account and the worker record&lt;/li&gt;
&lt;li&gt;junction objects for the common real world case where the employer of record is not the site where the work happens&lt;/li&gt;
&lt;li&gt;restrictions that carry a start date, an end date and a review owner, so an expired restriction is a state rather than a note somebody forgot&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Record types and field level security then have something real to attach to. Employers see fitness and restriction outcomes. Clinical detail stays with clinical roles.&lt;/p&gt;

&lt;h2&gt;
  
  
  Governed picklists are a privacy control
&lt;/h2&gt;

&lt;p&gt;Free text classification is usually argued about as a reporting problem. It is worse than that. Somebody types a diagnosis into a logistics notes field, and now the sensitive detail lives in a field that nobody classified as sensitive and no sharing rule protects.&lt;/p&gt;

&lt;p&gt;Replacing free text with governed picklists fixes the reporting and closes that hole at the same time.&lt;/p&gt;

&lt;h2&gt;
  
  
  Put regulated thresholds in data, not in code
&lt;/h2&gt;

&lt;p&gt;Take blood lead level monitoring as the example. Enrollment, testing frequency, thresholds and follow up actions are all rules that change when a regulation changes.&lt;/p&gt;

&lt;p&gt;If they live in code, every regulatory update is a release, and under deadline pressure somebody adds a field to an existing object that quietly inherits whatever sharing that object already had. That is how a privacy regression ships.&lt;/p&gt;

&lt;p&gt;If they live as records, the update is a configuration edit. The periodic reports come off the same records, so the report and the rule cannot drift apart.&lt;/p&gt;

&lt;h2&gt;
  
  
  Correspondence belongs to the case
&lt;/h2&gt;

&lt;p&gt;Inbound and outbound fax and email get logged as case activities rather than living in somebody's mailbox. Documents hang off the case with version history, classification and retention rules. This is unglamorous and it is the part that answers the audit.&lt;/p&gt;

&lt;h2&gt;
  
  
  Give outsiders a surface built for outsiders
&lt;/h2&gt;

&lt;p&gt;Employers and referring clinicians need real time visibility. The wrong answer is a stripped down copy of the internal application with fields hidden by CSS. The right answer is an external community, which gives them a purpose built surface and does not consume internal user licences.&lt;/p&gt;

&lt;h2&gt;
  
  
  Migration is where the old sins surface
&lt;/h2&gt;

&lt;p&gt;Legacy data arrives with duplicates and years of free text classifications that now have to map onto a governed vocabulary. Some of it will not map cleanly, and that is a decision for a human, not a script.&lt;/p&gt;

&lt;p&gt;Rehearse the whole thing in a full sandbox and validate historical caseloads before cutover. The migration is also the only moment you get a clean look at how bad the old classification really was.&lt;/p&gt;

&lt;h2&gt;
  
  
  The rule worth keeping
&lt;/h2&gt;

&lt;p&gt;Design the permission model before you design a single screen. Everything else in this build is downstream of that one choice, and it is the only part that is genuinely expensive to retrofit.&lt;/p&gt;

&lt;p&gt;Full write up: &lt;a href="https://innerluxes.dev/case-studies/occupational-health-case-management?utm_source=devto&amp;amp;utm_medium=article" rel="noopener noreferrer"&gt;Occupational Health Case Management Platforms on Salesforce&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Where do you draw the line between what an employer is entitled to see and what stays clinical?&lt;/p&gt;

</description>
      <category>architecture</category>
      <category>salesforce</category>
      <category>healthcare</category>
      <category>security</category>
    </item>
    <item>
      <title>The Old Screen Was the Real Spec: Rewriting a Streaming Portal From AngularJS to React</title>
      <dc:creator>INNERLUXES</dc:creator>
      <pubDate>Fri, 13 Nov 2026 19:49:26 +0000</pubDate>
      <link>https://dev.to/innerluxes/the-old-screen-was-the-real-spec-rewriting-a-streaming-portal-from-angularjs-to-react-4h46</link>
      <guid>https://dev.to/innerluxes/the-old-screen-was-the-real-spec-rewriting-a-streaming-portal-from-angularjs-to-react-4h46</guid>
      <description>&lt;p&gt;Rewriting a legacy frontend is usually described as a coding problem. It almost never is. It is a specification problem wearing a coding problem's clothes, and the teams that get this wrong ship a different, undocumented application instead of a modernized version of the one operators already trust.&lt;/p&gt;

&lt;p&gt;Here is how a streaming operations portal came off AngularJS and onto React without breaking the people who use it every day.&lt;/p&gt;

&lt;h2&gt;
  
  
  The portal that would not stay still
&lt;/h2&gt;

&lt;p&gt;Dense, long lived screens. Driven by asynchronous backend jobs. Built originally on AngularJS, then grown for years until two way binding had become unpredictable and features that should have touched one part of the screen reached into several controllers at once.&lt;/p&gt;

&lt;p&gt;The API documentation behind it was incomplete. That one fact decided everything that followed, because it meant the only honest description of how the system actually behaved was the UI itself, inferred from watching network traffic rather than read from a spec.&lt;/p&gt;

&lt;p&gt;So the rewrite had to reproduce the old portal's behavior exactly, not a cleaned up guess at what that behavior was supposed to be. &lt;strong&gt;The old screen was the real specification.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Three tiers, one place to change things
&lt;/h2&gt;

&lt;p&gt;The React replacement was structured in three component tiers:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Base library&lt;/strong&gt; supplying generic, unopinionated components.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Shared middle layer&lt;/strong&gt; fixing spacing, typography, form controls, table density and empty states in one place.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Feature components&lt;/strong&gt; holding only domain logic, nothing about how things look.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The payoff is boring but real: a design change is made once. Before, a spacing fix meant hunting through every controller that happened to touch that part of the UI. After, it is one edit in the middle tier.&lt;/p&gt;

&lt;h2&gt;
  
  
  Async state needs more than a reducer
&lt;/h2&gt;

&lt;p&gt;Redux-Saga sits between actions and reducers, and on this project it earned its place doing two specific jobs a plain reducer does not do cleanly:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Sequencing requests that depend on each other.&lt;/li&gt;
&lt;li&gt;Cancelling work still in flight when an operator navigates away from a screen mid load.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Without that second one, a slow response from a screen the user already left lands late and overwrites newer state with stale data.&lt;/p&gt;

&lt;p&gt;Every entity in the store was normalized, so the same underlying record could not drift into two different shapes in two different parts of the state tree. That is the classic source of bugs where two views of the same object quietly disagree with each other.&lt;/p&gt;

&lt;h2&gt;
  
  
  The rule that was actually about trust, not architecture
&lt;/h2&gt;

&lt;p&gt;The single decision that mattered most was not a pattern name. It was a rule about when the UI is allowed to guess.&lt;/p&gt;

&lt;p&gt;Live telemetry and device health data got their own state slice, entirely separate from form state. An incoming status update could refresh on screen without ever interrupting someone mid edit on a form elsewhere on the same page. Two different data lifecycles, kept from colliding.&lt;/p&gt;

&lt;p&gt;Optimistic updates were allowed for ordinary metadata changes. They were &lt;strong&gt;banned outright for hardware commands&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;A screen that shows a device as on before the device has confirmed it turned on is not a faster screen. It is a screen that lies, and the cost of that lie is paid in operator trust the first time the device does not actually respond. Confirmed state only, no exceptions, for anything connected to physical hardware.&lt;/p&gt;

&lt;p&gt;If you take one thing from this write up, take that line and draw it in your own app.&lt;/p&gt;

&lt;h2&gt;
  
  
  Building and shipping without a finished backend
&lt;/h2&gt;

&lt;p&gt;The API contract was settled before a line of UI code was written. Mock requests and responses generated from that contract did double duty: they were the data the frontend team built against before the real backend existed, and later they became contract tests that caught any drift once it was live.&lt;/p&gt;

&lt;p&gt;Cutover ran route by route rather than as a single flag flip. The legacy AngularJS layer and the new React layer lived side by side under one authenticated session, so operators moved one screen at a time and nothing was ever stood up that the old portal could not fall back to.&lt;/p&gt;

&lt;h2&gt;
  
  
  What actually changed
&lt;/h2&gt;

&lt;p&gt;No benchmark numbers here, and the outcomes that mattered were not benchmarks anyway:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Behavior stayed consistent with what operators already expected, right through the migration.&lt;/li&gt;
&lt;li&gt;Race conditions on quickly navigated screens stopped happening.&lt;/li&gt;
&lt;li&gt;Live health data kept refreshing without disrupting whatever someone was in the middle of editing.&lt;/li&gt;
&lt;li&gt;A single design change finally propagated everywhere instead of being re-applied controller by controller.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;None of that required new business logic. It required treating the existing screen as ground truth, drawing one hard line around physical hardware state, and shipping the migration in pieces small enough that nothing operators depended on broke along the way.&lt;/p&gt;

&lt;p&gt;Full case study: &lt;a href="https://innerluxes.dev/case-studies/netherlands-client-updates-streaming-software?utm_source=devto&amp;amp;utm_medium=article" rel="noopener noreferrer"&gt;https://innerluxes.dev/case-studies/netherlands-client-updates-streaming-software?utm_source=devto&amp;amp;utm_medium=article&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Curious where other people draw the optimistic update line. Do you allow it anywhere near physical state, or is it metadata only for you too?&lt;/p&gt;

</description>
      <category>react</category>
      <category>javascript</category>
      <category>webdev</category>
      <category>architecture</category>
    </item>
    <item>
      <title>An Electron Preload Script Is a Security Boundary, Not a Convenience Layer</title>
      <dc:creator>INNERLUXES</dc:creator>
      <pubDate>Wed, 11 Nov 2026 10:22:26 +0000</pubDate>
      <link>https://dev.to/innerluxes/an-electron-preload-script-is-a-security-boundary-not-a-convenience-layer-3b3p</link>
      <guid>https://dev.to/innerluxes/an-electron-preload-script-is-a-security-boundary-not-a-convenience-layer-3b3p</guid>
      <description>&lt;p&gt;A ticket comes in. The support team wants the desktop app to open a vendor's dashboard inside a tab instead of kicking the user out to the browser. The dashboard is a normal web page on a domain nobody on the team controls. The change is small: point a window at a URL, ship it.&lt;/p&gt;

&lt;p&gt;That ticket is where most Electron security incidents start. Not at a line of code that looks dangerous, but at a product decision that quietly moves untrusted content inside a process that can read the user's disk.&lt;/p&gt;

&lt;p&gt;The useful way to think about an Electron app is that the preload script is a security boundary, in the same sense that an HTTP handler is a security boundary. Everything on the far side of it is hostile until proven otherwise, and the job of the code at the boundary is to decide what crosses.&lt;/p&gt;

&lt;h2&gt;
  
  
  The shape of the mistake
&lt;/h2&gt;

&lt;p&gt;Here is the preload that ships. It is three lines and it reviews fine, because it looks like plumbing.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// preload.js&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;contextBridge&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ipcRenderer&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'electron'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="n"&gt;contextBridge&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;exposeInMainWorld&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'api'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;send&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;ipcRenderer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;send&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;invoke&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;ipcRenderer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;invoke&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The Electron documentation calls this out directly. It "directly exposes a powerful API without any kind of argument filtering", and the consequence is stated just as plainly: "This would allow any website to send arbitrary IPC messages, which you do not want to be possible."&lt;/p&gt;

&lt;p&gt;The developer who wrote it was not careless. They were building a generic bridge so the renderer team would not have to ask for a new channel every week. That is a reasonable engineering instinct and it is exactly the instinct that has to be resisted here, because a generic bridge is a generic bridge for the attacker too. Every IPC handler in the main process, including the one somebody adds next quarter to write a file, is now reachable from whatever page is loaded.&lt;/p&gt;

&lt;p&gt;The documented rule is the opposite shape: "You should not directly expose Electron's APIs, especially IPC, to untrusted web content in your preload scripts."&lt;/p&gt;

&lt;h2&gt;
  
  
  The defaults are already on your side
&lt;/h2&gt;

&lt;p&gt;Three of the settings that used to cause most of the damage are now defaults, and it is worth knowing which Electron version made each one a default, because the dangerous pattern in a real codebase is usually not a setting that was never turned on. It is a setting that was explicitly turned off in 2021 to make something work, with a comment that nobody has revisited since.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Setting&lt;/th&gt;
&lt;th&gt;Secure state&lt;/th&gt;
&lt;th&gt;Default since&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;contextIsolation&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;enabled&lt;/td&gt;
&lt;td&gt;Electron 12.0.0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;nodeIntegration&lt;/code&gt; for remote content&lt;/td&gt;
&lt;td&gt;disabled&lt;/td&gt;
&lt;td&gt;Electron 5.0.0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sandbox&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;enabled&lt;/td&gt;
&lt;td&gt;Electron 20.0.0&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;So the audit question is not "did we enable context isolation". It is "does anything in this repository set these to the insecure value", which is a grep, and it should be a test.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// A test that fails the build, not a comment in a config file.&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;DANGEROUS&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'nodeIntegration'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'webSecurity'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'allowRunningInsecureContent'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                   &lt;span class="s1"&gt;'experimentalFeatures'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'enableBlinkFeatures'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'webviewTag'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;

&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'no window disables a security default'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;file&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="nf"&gt;browserWindowSources&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;key&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="no"&gt;DANGEROUS&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="ow"&gt;not&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toMatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;RegExp&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`${key}\\s*:\\s*true`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="ow"&gt;not&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toMatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;contextIsolation&lt;/span&gt;\&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="o"&gt;*:&lt;/span&gt;\&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="ow"&gt;not&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toMatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sandbox&lt;/span&gt;\&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="o"&gt;*:&lt;/span&gt;\&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A grep-based test is crude and it is still the single highest-value test in an Electron codebase, because the failure it catches is a one-word diff in a file that reviewers skim.&lt;/p&gt;

&lt;p&gt;The documentation is unambiguous about the worst combination: "Under no circumstances should you load and execute remote code with Node.js integration enabled."&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 1: expose verbs, not transports
&lt;/h2&gt;

&lt;p&gt;The bridge should describe what the application can do, not how messages travel. The documented pattern is one narrow method per message.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// preload.js&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;contextBridge&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ipcRenderer&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'electron'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="n"&gt;contextBridge&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;exposeInMainWorld&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'myAPI'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;loadPreferences&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;ipcRenderer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;invoke&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'load-prefs'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Read that against the earlier version. &lt;code&gt;api.invoke&lt;/code&gt; is an open door whose shape depends on every handler registered anywhere in the main process. &lt;code&gt;myAPI.loadPreferences&lt;/code&gt; is a door with one thing behind it, and the set of things a compromised renderer can ask for is now a list you can print out and review.&lt;/p&gt;

&lt;p&gt;The practical test for any method you are about to expose is to assume the renderer is already hostile and ask what the worst call looks like. &lt;code&gt;readFile(path)&lt;/code&gt; fails that test immediately. &lt;code&gt;loadPreferences()&lt;/code&gt; passes, because the path is chosen by the main process and the renderer cannot influence it.&lt;/p&gt;

&lt;p&gt;One implementation note that costs people an afternoon: the bridge serialises what crosses it, and the documentation warns that "you can't send custom prototypes or symbols over the bridge". Class instances arrive as plain objects with their methods missing. Design the bridge to pass data, not behaviour.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 2: the main process validates, every time
&lt;/h2&gt;

&lt;p&gt;Argument filtering in the preload is a courtesy. It runs in a context the renderer cannot reach under context isolation, which is good, but the handler in the main process is the thing that actually holds the privilege, so that is where the check belongs.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// main.js&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;path&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'node:path'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="n"&gt;ipcMain&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;handle&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'open-project'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nf"&gt;isTrustedSender&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'rejected sender'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="s1"&gt;'string'&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;!/^&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;z0&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;9&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="mi"&gt;64&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;$&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'invalid project name'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;file&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;PROJECT_ROOT&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sb"&gt;`${name}.json`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="c1"&gt;// name cannot contain a separator or a dot, so this cannot escape PROJECT_ROOT&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;readProject&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two things are happening there and both are on the checklist. The allow-list regular expression is validation. &lt;code&gt;isTrustedSender&lt;/code&gt; is the item the documentation lists as "Validate the &lt;code&gt;sender&lt;/code&gt; of all IPC messages", and it exists because a handler does not know which frame called it unless it asks. An application that loads any remote content, in a window or a &lt;code&gt;&amp;lt;webview&amp;gt;&lt;/code&gt;, has frames in it that should never be able to reach an application handler at all.&lt;/p&gt;

&lt;p&gt;Validate by comparing the sender's origin against what you expect, and fail closed when it does not match. Do not infer trust from the channel name. Channel names are strings and the renderer picks them.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 3: remote content gets its own renderer, or no renderer at all
&lt;/h2&gt;

&lt;p&gt;Back to the ticket at the top. The vendor dashboard has to appear somewhere. The documented framing is the one to argue from: "A security issue exists whenever you receive code from an untrusted source (e.g. a remote server) and execute it locally."&lt;/p&gt;

&lt;p&gt;The options are not equal.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A &lt;code&gt;BrowserWindow&lt;/code&gt; with no preload at all, sandboxed, node integration off, loading only that origin. The page gets no bridge, so there is nothing for it to call.&lt;/li&gt;
&lt;li&gt;A &lt;code&gt;&amp;lt;webview&amp;gt;&lt;/code&gt; tag, which the docs suggest controlling from the main process, without &lt;code&gt;allowpopups&lt;/code&gt;, with its options verified rather than accepted from markup.&lt;/li&gt;
&lt;li&gt;An external browser via &lt;code&gt;shell.openExternal&lt;/code&gt;, which the checklist warns against using with untrusted content, meaning the URL has to come from your code and not from the page.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The option that keeps getting chosen because it is one line is the one where the vendor page is loaded into a window that already has the application's preload attached. That window now exposes your bridge to a third party's JavaScript, and to whatever their advertising script loaded this morning.&lt;/p&gt;

&lt;p&gt;If the dashboard genuinely needs to talk to the application, the direction of the dependency should invert: the main process fetches what it needs from the vendor's API and renders it in your own page, and the untrusted markup never executes with any privilege at all.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 4: permissions are granted unless you say otherwise
&lt;/h2&gt;

&lt;p&gt;This one surprises people, and it is documented: "By default, Electron will automatically approve all permission requests" unless a custom handler is configured. Camera, microphone, geolocation, notifications. A browser asks the user. An Electron app, by default, does not ask anybody.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// main.js&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;ALLOWED&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'clipboard-read'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;defaultSession&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setPermissionRequestHandler&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;webContents&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;permission&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;callback&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;origin&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;webContents&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getURL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;origin&lt;/span&gt;
  &lt;span class="nf"&gt;callback&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;origin&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="no"&gt;APP_ORIGIN&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="no"&gt;ALLOWED&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;permission&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The checklist says to use &lt;code&gt;ses.setPermissionRequestHandler()&lt;/code&gt; in all sessions that load remote content. The word that matters is "all". A second session created for a vendor window does not inherit a handler you installed on the default session.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 5: navigation is the escape hatch everyone forgets
&lt;/h2&gt;

&lt;p&gt;An application window that can navigate anywhere is an application window that can navigate to anywhere an attacker wants, including a page that then sits inside your preload. A single open redirect on a domain you trust is enough to get there, and open redirects are common enough that they are frequently not even treated as bugs.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;on&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'web-contents-created'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;_event&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;contents&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;contents&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;on&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'will-navigate'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;origin&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="no"&gt;APP_ORIGIN&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;preventDefault&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;contents&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setWindowOpenHandler&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;url&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// open externally after your own check, never automatically&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'deny'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Both of these are checklist items: "Disable or limit navigation" and "Disable or limit creation of new windows". They are cheap, they are global, and they survive the next developer who adds a window without reading this page.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 6: the transport-level settings
&lt;/h2&gt;

&lt;p&gt;Three more items from the list, grouped because they share a reason.&lt;/p&gt;

&lt;p&gt;"Only load secure content" rules out plain HTTP for anything the app depends on, including the first load during development, because a development habit becomes a production configuration more often than anyone admits.&lt;/p&gt;

&lt;p&gt;"Do not disable &lt;code&gt;webSecurity&lt;/code&gt;" is usually broken for a local development reason, typically a cross-origin request to an API on another port. The honest fix is a proxy or correct CORS headers on the API. Disabling same-origin policy in a process that also has a bridge to the file system is not a development convenience, it is a different application.&lt;/p&gt;

&lt;p&gt;"Do not enable &lt;code&gt;allowRunningInsecureContent&lt;/code&gt;", which the docs describe as disabling the protection against mixed content, and a restrictive Content-Security-Policy, which the docs suggest starting at &lt;code&gt;script-src 'self'&lt;/code&gt;. A CSP in an Electron app is doing the same job it does on the web, with the difference that the page it protects is a page with native capability behind it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this passes code review
&lt;/h2&gt;

&lt;p&gt;Every item above is a small diff. &lt;code&gt;contextIsolation: false&lt;/code&gt; is one word. Adding &lt;code&gt;invoke&lt;/code&gt; to the bridge is one line that removes work for three other people. Pointing a window at a vendor URL is a product improvement with a ticket number attached.&lt;/p&gt;

&lt;p&gt;None of them reads as a security change, which is why the checks have to be mechanical rather than cultural. A grep test in CI, a sender check in every handler, and a written rule that a new &lt;code&gt;BrowserWindow&lt;/code&gt; needs a reviewer who knows what the preload exposes, will catch more than a security review scheduled for the quarter.&lt;/p&gt;

&lt;h2&gt;
  
  
  The ship checklist
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Nothing in the repository sets &lt;code&gt;nodeIntegration&lt;/code&gt;, &lt;code&gt;webSecurity&lt;/code&gt;, &lt;code&gt;allowRunningInsecureContent&lt;/code&gt;, &lt;code&gt;experimentalFeatures&lt;/code&gt;, &lt;code&gt;enableBlinkFeatures&lt;/code&gt; or &lt;code&gt;webviewTag&lt;/code&gt; to &lt;code&gt;true&lt;/code&gt;, and nothing sets &lt;code&gt;contextIsolation&lt;/code&gt; or &lt;code&gt;sandbox&lt;/code&gt; to &lt;code&gt;false&lt;/code&gt;, enforced by a test.&lt;/li&gt;
&lt;li&gt;The preload exposes named operations only. No &lt;code&gt;ipcRenderer&lt;/code&gt;, no &lt;code&gt;send&lt;/code&gt;, no &lt;code&gt;invoke&lt;/code&gt;, no &lt;code&gt;require&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Every exposed method is safe to call with attacker-chosen arguments, or takes no arguments at all.&lt;/li&gt;
&lt;li&gt;Every &lt;code&gt;ipcMain&lt;/code&gt; handler validates its arguments against an allow-list and rejects unexpected types.&lt;/li&gt;
&lt;li&gt;Every &lt;code&gt;ipcMain&lt;/code&gt; handler validates the sender and fails closed.&lt;/li&gt;
&lt;li&gt;Remote content loads in a window or session with no application preload attached.&lt;/li&gt;
&lt;li&gt;Every session that loads remote content has a permission request handler, and the default is deny.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;will-navigate&lt;/code&gt; is restricted to the application origin, and &lt;code&gt;setWindowOpenHandler&lt;/code&gt; denies by default.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;shell.openExternal&lt;/code&gt; is never called with a URL that came from page content.&lt;/li&gt;
&lt;li&gt;A Content-Security-Policy is set and starts from &lt;code&gt;script-src 'self'&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The Electron version is current, and the fuses that can be flipped for the build have been reviewed.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  The underlying point
&lt;/h2&gt;

&lt;p&gt;Electron gets described as a browser with file system access, and that framing is what leads teams astray, because it suggests the risk is spread evenly across the app. It is not. It is concentrated at one file. Everything the renderer can reach, it reaches through the preload, and the size of your attack surface is literally the number of things listed in &lt;code&gt;exposeInMainWorld&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Keep that list short enough to read aloud in a review, and most of the rest of the checklist becomes defence in depth rather than the only thing standing between a vendor's advertising script and a user's documents folder.&lt;/p&gt;

&lt;p&gt;INNERLUXES builds Chromium-based and Electron desktop applications, and this checklist is the one the team runs before a desktop build ships.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Sources:&lt;/strong&gt; Electron documentation, &lt;a href="https://electronjs.org/docs/latest/tutorial/security" rel="noopener noreferrer"&gt;Security&lt;/a&gt; and &lt;a href="https://electronjs.org/docs/latest/tutorial/context-isolation" rel="noopener noreferrer"&gt;Context Isolation&lt;/a&gt;.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>javascript</category>
      <category>security</category>
      <category>electron</category>
    </item>
    <item>
      <title>Never Let a Display Toggle Write to the Database</title>
      <dc:creator>INNERLUXES</dc:creator>
      <pubDate>Wed, 04 Nov 2026 19:40:04 +0000</pubDate>
      <link>https://dev.to/innerluxes/never-let-a-display-toggle-write-to-the-database-22jp</link>
      <guid>https://dev.to/innerluxes/never-let-a-display-toggle-write-to-the-database-22jp</guid>
      <description>&lt;p&gt;A support ticket arrives. Two users are looking at the same record and reading different numbers. Nothing in the logs. No exception, no failed request, no alert. The row is simply wrong, and nobody can say when it became wrong.&lt;/p&gt;

&lt;p&gt;Trace it far enough and you often land on the same small piece of UI: a dropdown that lets the user change the unit a quantity is displayed in. Kilograms or pounds. Therms or MMBtu. Minutes or hours. Someone built it as a convenience, wired it straight to the field, and it writes back.&lt;/p&gt;

&lt;p&gt;That control is not a formatting feature. It is a write path into your data, and it is almost never treated like one.&lt;/p&gt;

&lt;h2&gt;
  
  
  The shape of the bug
&lt;/h2&gt;

&lt;p&gt;Here is the version that gets shipped. It looks harmless in review.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// The user picks a unit from the dropdown.&lt;/span&gt;
&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;onUnitChange&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;next&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Unit&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;converted&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;convert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;form&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;form&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;unit&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;next&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;form&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;quantity&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;converted&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;   &lt;span class="c1"&gt;// &amp;lt;- the display just wrote to the model&lt;/span&gt;
  &lt;span class="nx"&gt;form&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;unit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;next&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Switch to the other unit and back again, and you have round-tripped the value through two divisions. With a non-terminating ratio you do not get your original number back. Do it four times and the drift is visible. Do it once on a record nobody looks at for a month and it is invisible, permanent, and indistinguishable from a legitimate edit.&lt;/p&gt;

&lt;p&gt;The second failure is worse, because it needs no arithmetic error at all. A user switches the dropdown to read a value in a different unit, does not change anything, and hits save out of habit. The form submits the converted number against the original unit. The record is now off by whatever the conversion factor is.&lt;/p&gt;

&lt;p&gt;Both of these are the same mistake: &lt;strong&gt;the presentation layer was given permission to write.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 1: one canonical unit in storage
&lt;/h2&gt;

&lt;p&gt;Pick a canonical unit per quantity type and store only that. The database does not know about user preferences, locales, or dropdowns.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;measurement&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt;            &lt;span class="nb"&gt;bigint&lt;/span&gt; &lt;span class="k"&gt;PRIMARY&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="c1"&gt;-- always stored in grams; the column name says so&lt;/span&gt;
  &lt;span class="n"&gt;mass_g&lt;/span&gt;        &lt;span class="nb"&gt;numeric&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;recorded_at&lt;/span&gt;   &lt;span class="n"&gt;timestamptz&lt;/span&gt;    &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Put the unit in the column name. &lt;code&gt;mass_g&lt;/code&gt;, &lt;code&gt;duration_ms&lt;/code&gt;, &lt;code&gt;volume_ml&lt;/code&gt;. A column called &lt;code&gt;quantity&lt;/code&gt; with a sibling called &lt;code&gt;unit&lt;/code&gt; invites every consumer to do its own conversion, and they will not all agree. A column called &lt;code&gt;mass_g&lt;/code&gt; cannot be misread by the next person, and it cannot be misread by a reporting query written by someone who never read your code.&lt;/p&gt;

&lt;p&gt;Conversion happens on the way out and on the way in at the edge, and nowhere else.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 2: the converted value never travels back
&lt;/h2&gt;

&lt;p&gt;Make display units a view concern that physically cannot reach the write path. The simplest way is to keep the canonical value in the model and derive the displayed one:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Measurement&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;massG&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;     &lt;span class="c1"&gt;// canonical, the only thing persisted&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;display&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;m&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Measurement&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;unit&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Unit&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;fromGrams&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;massG&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;unit&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="nx"&gt;unit&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;onUnitChange&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;next&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Unit&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;viewState&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;unit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;next&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;                  &lt;span class="c1"&gt;// view state only&lt;/span&gt;
  &lt;span class="c1"&gt;// model untouched&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;onUserEdit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;unit&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Unit&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;model&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;massG&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;toGrams&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;parseDecimal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="nx"&gt;unit&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;   &lt;span class="c1"&gt;// convert in, once&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two functions, &lt;code&gt;toGrams&lt;/code&gt; and &lt;code&gt;fromGrams&lt;/code&gt;, and a model that has no &lt;code&gt;unit&lt;/code&gt; field at all. If the model cannot express "quantity in pounds", nothing downstream can accidentally persist one.&lt;/p&gt;

&lt;p&gt;When the stored unit genuinely has to vary - because the source system sends mixed units and you need the original for audit - store both: the canonical value you compute with, and the as-received value and unit you never compute with. Never one field that means different things on different rows.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 3: inexact types are the other half of the same bug
&lt;/h2&gt;

&lt;p&gt;Unit conversion multiplies and divides. If the column is a binary floating point type, every one of those operations is an opportunity to lose the exact value, and the loss compounds silently.&lt;/p&gt;

&lt;p&gt;The PostgreSQL documentation is blunt about this. &lt;code&gt;real&lt;/code&gt; and &lt;code&gt;double precision&lt;/code&gt; are listed as &lt;strong&gt;variable-precision, inexact&lt;/strong&gt;, with 6 and 15 decimal digits of precision respectively. &lt;code&gt;numeric&lt;/code&gt; is &lt;strong&gt;exact&lt;/strong&gt;, with user-specified precision, and the docs say it "is especially recommended for storing monetary amounts and other quantities where exactness is required", with calculations yielding exact results where possible for addition, subtraction and multiplication. The same docs note that &lt;code&gt;numeric&lt;/code&gt; calculations are slower than the floating point types - that is the trade, and for a quantity somebody will reconcile later it is an easy one.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- wrong for anything that gets reconciled&lt;/span&gt;
&lt;span class="n"&gt;volume&lt;/span&gt; &lt;span class="nb"&gt;double&lt;/span&gt; &lt;span class="nb"&gt;precision&lt;/span&gt;

&lt;span class="c1"&gt;-- right&lt;/span&gt;
&lt;span class="n"&gt;volume_m3&lt;/span&gt; &lt;span class="nb"&gt;numeric&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The application side matters just as much. A JavaScript &lt;code&gt;number&lt;/code&gt; is a double. If your API serialises a &lt;code&gt;numeric&lt;/code&gt; column into JSON and the client parses it as a number, you have just thrown away the exactness you paid for in the database. Carry it as a string to the edge and parse it with a decimal library, or do the arithmetic server-side and send the client a formatted result it only displays.&lt;/p&gt;

&lt;p&gt;And define rounding once, in one module, with the rounding mode written down. Two services that round differently will produce two totals, and the argument about which one is correct will cost more than the feature did.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 4: a quantity is not always a single number
&lt;/h2&gt;

&lt;p&gt;This is the modelling mistake that is cheap on day one and brutal to retrofit.&lt;/p&gt;

&lt;p&gt;Sometimes the thing a user calls "the quantity" is a shape spread across a window, not a scalar. A monthly figure that is really a daily rate across a delivery period. A subscription allowance that resets. A forecast with a curve.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// day one, and it leaks into every report before anyone notices&lt;/span&gt;
&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Line&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;quantityG&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;

&lt;span class="c1"&gt;// what it actually is&lt;/span&gt;
&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Line&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;from&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;PlainDate&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;to&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;PlainDate&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;dailyQuantityG&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;     &lt;span class="c1"&gt;// or an explicit per-day profile&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you model it as a scalar, the first question that asks for a daily breakdown forces a migration through every report, export and integration that has already consumed the scalar. Aggregation over a shape is a different operation from summing a column, and you want to discover that before the data is in production.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 5: one concept, three structures
&lt;/h2&gt;

&lt;p&gt;The same trap in a different costume. You have a field that can be set three ways - a fixed value, a value derived from an index, or an offset against a reference. The tempting schema is one table, a &lt;code&gt;type&lt;/code&gt; column, and a handful of nullable columns.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- the shortcut&lt;/span&gt;
&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;price&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;kind&lt;/span&gt;              &lt;span class="nb"&gt;text&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;      &lt;span class="c1"&gt;-- 'fixed' | 'indexed' | 'differential'&lt;/span&gt;
  &lt;span class="n"&gt;fixed_amount&lt;/span&gt;      &lt;span class="nb"&gt;numeric&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;            &lt;span class="c1"&gt;-- null unless kind = 'fixed'&lt;/span&gt;
  &lt;span class="n"&gt;index_code&lt;/span&gt;        &lt;span class="nb"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;               &lt;span class="c1"&gt;-- null unless kind = 'indexed'&lt;/span&gt;
  &lt;span class="n"&gt;index_multiplier&lt;/span&gt;  &lt;span class="nb"&gt;numeric&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;            &lt;span class="c1"&gt;-- null unless ...&lt;/span&gt;
  &lt;span class="n"&gt;base_reference&lt;/span&gt;    &lt;span class="nb"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;offset_amount&lt;/span&gt;     &lt;span class="nb"&gt;numeric&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It works until the first reconciliation. After that, every query that has to understand the field carries a branch, the branches get copied, and two of them disagree. Nothing enforces that &lt;code&gt;fixed_amount&lt;/code&gt; is present exactly when &lt;code&gt;kind = 'fixed'&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Model each variant as its own structure and put the branching in one mapping layer:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Price&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;fixed&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Decimal&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;indexed&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;indexCode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;multiplier&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Decimal&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;differential&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;baseRef&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Decimal&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A discriminated union makes the illegal states unrepresentable in the code, and the exhaustiveness check in your compiler tells you every place that needs updating when a fourth variant arrives. In the database, either use separate tables with a shared parent or add check constraints that make the nullability rules explicit:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;ALTER&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;price&lt;/span&gt; &lt;span class="k"&gt;ADD&lt;/span&gt; &lt;span class="k"&gt;CONSTRAINT&lt;/span&gt; &lt;span class="n"&gt;price_shape&lt;/span&gt; &lt;span class="k"&gt;CHECK&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'fixed'&lt;/span&gt;        &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;fixed_amount&lt;/span&gt; &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;index_code&lt;/span&gt; &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;OR&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'indexed'&lt;/span&gt;   &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;index_code&lt;/span&gt;  &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;fixed_amount&lt;/span&gt; &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;OR&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'differential'&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;base_reference&lt;/span&gt; &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Rule 6: amend, do not overwrite
&lt;/h2&gt;

&lt;p&gt;Once a record has been acted on by somebody else, an in-place &lt;code&gt;UPDATE&lt;/code&gt; destroys the only evidence of what they acted on. "What did this say on the 14th" is a question that gets asked eventually, and the honest answer should not be "we cannot tell you".&lt;/p&gt;

&lt;p&gt;Append amendments instead, and derive the current state:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;measurement_amendment&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt;              &lt;span class="n"&gt;bigserial&lt;/span&gt; &lt;span class="k"&gt;PRIMARY&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;measurement_id&lt;/span&gt;  &lt;span class="nb"&gt;bigint&lt;/span&gt;      &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;REFERENCES&lt;/span&gt; &lt;span class="n"&gt;measurement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="k"&gt;before&lt;/span&gt;          &lt;span class="n"&gt;jsonb&lt;/span&gt;       &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="k"&gt;after&lt;/span&gt;           &lt;span class="n"&gt;jsonb&lt;/span&gt;       &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amended_by&lt;/span&gt;      &lt;span class="nb"&gt;text&lt;/span&gt;        &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amended_at&lt;/span&gt;      &lt;span class="n"&gt;timestamptz&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three rules keep this honest. Every amendment carries who and when, not just what. Deletions are reversals - a new row that negates the previous state - not &lt;code&gt;DELETE&lt;/code&gt; statements, because a deleted row and a row that was never written look identical afterwards. And the reconstruction path gets a test, because an audit trail nobody has ever replayed is a hope, not a guarantee.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 7: concurrency, surfaced rather than swallowed
&lt;/h2&gt;

&lt;p&gt;Two people editing the same record is normal, not an edge case. The default behaviour of a naive update is last-write-wins, and it is silent.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;measurement&lt;/span&gt;
   &lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;mass_g&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;version&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
 &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;
   &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="k"&gt;version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;         &lt;span class="c1"&gt;-- the version the editor loaded&lt;/span&gt;
&lt;span class="c1"&gt;-- 0 rows affected means somebody else got there first&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Check the affected row count and tell the user. A conflict dialog is annoying. A silently discarded edit is a support ticket three weeks later with no evidence attached.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Approach&lt;/th&gt;
&lt;th&gt;What the user sees&lt;/th&gt;
&lt;th&gt;What you can prove later&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Last write wins&lt;/td&gt;
&lt;td&gt;Nothing&lt;/td&gt;
&lt;td&gt;Nothing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Version column, error surfaced&lt;/td&gt;
&lt;td&gt;A conflict they resolve&lt;/td&gt;
&lt;td&gt;Who overwrote what, and when&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Amendment log + version column&lt;/td&gt;
&lt;td&gt;A conflict they resolve&lt;/td&gt;
&lt;td&gt;Full state at any past moment&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Rule 8: bulk import bypasses your form
&lt;/h2&gt;

&lt;p&gt;Every system that reaches a certain size grows a spreadsheet importer, and the importer does not go through your UI. Validation that lives only in the form is not validation.&lt;/p&gt;

&lt;p&gt;Three things make an importer safe. The rules live in the domain layer, so the form and the importer call the same code. There is a preview stage that shows exactly what will be created, changed and skipped, before anything is written. And the commit is all-or-nothing, in one transaction, because a half-applied import of a thousand rows is worse than a rejected one - a rejection is obvious, a partial apply looks like success.&lt;/p&gt;

&lt;h2&gt;
  
  
  One calculation, two readers
&lt;/h2&gt;

&lt;p&gt;The last one is not really about data types at all.&lt;/p&gt;

&lt;p&gt;If the total on the screen and the total in the export disagree by a rounding step, users stop trusting the whole system. Downtime is forgivable because it is understood. A number that changes depending on where you read it is not.&lt;/p&gt;

&lt;p&gt;So the aggregate is computed in one place, called by both the screen and the export, with the rounding rules defined once. Not two implementations that are "basically the same". One.&lt;/p&gt;

&lt;h2&gt;
  
  
  Ship checklist
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Every quantity column names its unit (&lt;code&gt;mass_g&lt;/code&gt;, not &lt;code&gt;quantity&lt;/code&gt; plus a &lt;code&gt;unit&lt;/code&gt; column).&lt;/li&gt;
&lt;li&gt;The write model has no display-unit field at all.&lt;/li&gt;
&lt;li&gt;Conversion happens exactly twice: parse in at the edge, format out at the edge.&lt;/li&gt;
&lt;li&gt;Money and reconciled quantities use an exact decimal type, never &lt;code&gt;float&lt;/code&gt; or &lt;code&gt;double precision&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Decimal values cross the API as strings, not JSON numbers.&lt;/li&gt;
&lt;li&gt;Rounding mode and precision are defined in one module and imported everywhere.&lt;/li&gt;
&lt;li&gt;Quantities that are really shapes over a window are modelled as shapes from day one.&lt;/li&gt;
&lt;li&gt;Variant concepts are discriminated unions in code and check constraints in the schema.&lt;/li&gt;
&lt;li&gt;Edits append amendments with actor and timestamp; deletes are reversals.&lt;/li&gt;
&lt;li&gt;Updates carry a version and surface conflicts to the user instead of resolving them.&lt;/li&gt;
&lt;li&gt;The importer shares the domain validation, previews its effect, and commits atomically.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Most of these cost a morning at the start of a project. All of them cost a migration and a trust problem if you add them after the data is live.&lt;/p&gt;

&lt;p&gt;We build and maintain data-entry and data-management systems where the numbers have to reconcile afterwards. The patterns above are the ones we have found worth enforcing from the first screen rather than the first incident.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>programming</category>
      <category>database</category>
      <category>typescript</category>
    </item>
    <item>
      <title>A Tenant Leak Does Not Throw an Error. It Just Returns the Wrong Rows.</title>
      <dc:creator>INNERLUXES</dc:creator>
      <pubDate>Mon, 02 Nov 2026 19:19:25 +0000</pubDate>
      <link>https://dev.to/innerluxes/a-tenant-leak-does-not-throw-an-error-it-just-returns-the-wrong-rows-3icn</link>
      <guid>https://dev.to/innerluxes/a-tenant-leak-does-not-throw-an-error-it-just-returns-the-wrong-rows-3icn</guid>
      <description>&lt;p&gt;Most bugs announce themselves. A tenant leak does not. The query runs, the status code is 200, the page renders, and somebody in one company is looking at another company's payroll.&lt;/p&gt;

&lt;p&gt;That is what makes multi-tenancy different from the rest of the work. There is no stack trace to grep for and no error rate to alert on. The system is behaving exactly as written. It was written wrong.&lt;/p&gt;

&lt;p&gt;This is how we build isolation into multi-tenant products so that a mistake has to get past three independent layers before it reaches a user, and so that every build actively tries to break it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The two ways tenant data actually escapes
&lt;/h2&gt;

&lt;p&gt;In every leak we have looked at, the cause was one of two things.&lt;/p&gt;

&lt;p&gt;The first is a &lt;strong&gt;missing filter&lt;/strong&gt;. Somebody wrote a query without the tenant predicate. Usually it is not the obvious code. It is the admin export, the cron job, the "quick" reporting endpoint, the &lt;code&gt;findById&lt;/code&gt; helper that takes a primary key and nothing else.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Looks harmless. It is the whole bug.&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;getPayslip&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;one&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;SELECT * FROM payslips WHERE id = $1&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;An id is globally unique, so this never throws. It just returns whatever row matches, for whoever asks.&lt;/p&gt;

&lt;p&gt;The second is a &lt;strong&gt;re-derived tenant&lt;/strong&gt;. The request arrives with a verified tenant, and then forty lines deeper, some function reads the tenant again out of a request body, a query string, or a header, because that was convenient at the time.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// The tenant was already established. This throws it away.&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;listEmployees&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;tenantId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tenantId&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;query&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;many&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;SELECT * FROM employees WHERE tenant_id = $1&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Nobody writes this on purpose. It appears a year later, inside a feature that had a legitimate reason to accept a tenant parameter, and it is a direct object reference to every other tenant in the system.&lt;/p&gt;

&lt;p&gt;Both of these are failures of discipline, and discipline does not survive a team of eight and a two-year roadmap. So the rules below are structural. They do not ask anyone to remember anything.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 1: resolve the tenant once, at the edge, and carry it
&lt;/h2&gt;

&lt;p&gt;Tenant resolution happens exactly once per request, as early as possible, from the authenticated session. After that it is read-only context. It is never re-derived from anything the caller supplied.&lt;/p&gt;

&lt;p&gt;In Node, &lt;code&gt;AsyncLocalStorage&lt;/code&gt; is the right tool for this, because it survives &lt;code&gt;await&lt;/code&gt; boundaries without being threaded through every signature.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;AsyncLocalStorage&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;node:async_hooks&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;RequestContext&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;context&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;AsyncLocalStorage&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;RequestContext&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;tenantMiddleware&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;next&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// already authenticated&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;401&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;end&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

  &lt;span class="nx"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;run&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;userId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="nx"&gt;next&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;currentTenant&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getStore&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;No tenant context on this execution path&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;AsyncLocalStorage&lt;/code&gt; lives in &lt;code&gt;node:async_hooks&lt;/code&gt;, was added in v13.10.0 and v12.17.0, and was marked stable in v16.4.0. &lt;code&gt;getStore()&lt;/code&gt; returns &lt;code&gt;undefined&lt;/code&gt; outside a &lt;code&gt;run()&lt;/code&gt; call, which is exactly the behaviour you want: the throw in &lt;code&gt;currentTenant()&lt;/code&gt; means any code path that somehow escaped the middleware fails loudly instead of quietly running unscoped.&lt;/p&gt;

&lt;p&gt;Worth saying plainly: a background job, a queue consumer, or a migration script has no request and therefore no context. Those paths must open their own context explicitly, one tenant at a time. "It is only a cron job" is how the admin export got written without a filter.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 2: let the database refuse, not just the application
&lt;/h2&gt;

&lt;p&gt;Application-level scoping is layer one. It is also the layer most likely to have a hole in it, because it is the layer humans edit every day. Postgres row level security gives you a second layer that does not care how careless the query was.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;ALTER&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;employees&lt;/span&gt; &lt;span class="n"&gt;ENABLE&lt;/span&gt; &lt;span class="k"&gt;ROW&lt;/span&gt; &lt;span class="k"&gt;LEVEL&lt;/span&gt; &lt;span class="k"&gt;SECURITY&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;ALTER&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;employees&lt;/span&gt; &lt;span class="k"&gt;FORCE&lt;/span&gt; &lt;span class="k"&gt;ROW&lt;/span&gt; &lt;span class="k"&gt;LEVEL&lt;/span&gt; &lt;span class="k"&gt;SECURITY&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;POLICY&lt;/span&gt; &lt;span class="n"&gt;tenant_isolation&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;employees&lt;/span&gt;
  &lt;span class="k"&gt;USING&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;tenant_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;current_setting&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'app.tenant_id'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;true&lt;/span&gt;&lt;span class="p"&gt;)::&lt;/span&gt;&lt;span class="n"&gt;uuid&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;WITH&lt;/span&gt; &lt;span class="k"&gt;CHECK&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;tenant_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;current_setting&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'app.tenant_id'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;true&lt;/span&gt;&lt;span class="p"&gt;)::&lt;/span&gt;&lt;span class="n"&gt;uuid&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three details in there carry most of the weight.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Enabling RLS is fail-closed.&lt;/strong&gt; The Postgres documentation is unambiguous: "If no policy exists for the table, a default-deny policy is used, meaning that no rows are visible or can be modified." So the dangerous state is not "RLS on, policy wrong". It is "RLS never enabled on the table somebody added last sprint".&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;FORCE&lt;/code&gt; is not optional.&lt;/strong&gt; By default, "table owners normally bypass row security", and a table owner "can choose to be subject to row security with &lt;code&gt;ALTER TABLE ... FORCE ROW LEVEL SECURITY&lt;/code&gt;". Without &lt;code&gt;FORCE&lt;/code&gt;, an application connecting as the owning role sails straight past every policy you wrote, and your test suite happily agrees that isolation works.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The second argument to &lt;code&gt;current_setting&lt;/code&gt; is what makes it safe.&lt;/strong&gt; With &lt;code&gt;missing_ok&lt;/code&gt; set to true, the function returns NULL instead of throwing when the setting was never set. That matters because &lt;code&gt;tenant_id = NULL&lt;/code&gt; evaluates to NULL, which is not true, so the policy returns no rows. Forget to set the tenant and you get an empty result, not an error and not everybody's data.&lt;/p&gt;

&lt;p&gt;There is one more property that is easy to miss. A policy "will be evaluated for each row prior to any conditions or functions coming from the user's query". So a leaky user-defined function in a &lt;code&gt;WHERE&lt;/code&gt; clause cannot see rows the policy already excluded.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 3: set the tenant per transaction, never per connection
&lt;/h2&gt;

&lt;p&gt;The natural-looking move is to set the tenant right after the connection is checked out of the pool. Do not do that. A pooled connection is handed to the next request when yours is done, and if anything short-circuits before the reset, the next request inherits your tenant.&lt;/p&gt;

&lt;p&gt;Bind it to the transaction instead, so the database tears it down for you.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;withTenantTx&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;fn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Tx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;tenantId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;currentTenant&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// is_local = true  -&amp;gt;  dies with this transaction&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;none&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;SELECT set_config('app.tenant_id', $1, true)&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;fn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;set_config(name, value, true)&lt;/code&gt; is the function form of &lt;code&gt;SET LOCAL&lt;/code&gt;: per the docs, "if &lt;code&gt;is_local&lt;/code&gt; is true, the new value will only apply during the current transaction". There is no reset to forget, no &lt;code&gt;finally&lt;/code&gt; block to get wrong, and a rollback cleans it up like everything else.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where the connection pooler bites
&lt;/h2&gt;

&lt;p&gt;If PgBouncer sits between the application and Postgres, the pooling mode changes what session state means. Its own feature map lists these as never compatible with transaction pooling:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Feature&lt;/th&gt;
&lt;th&gt;Session pooling&lt;/th&gt;
&lt;th&gt;Transaction pooling&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;SET / RESET&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Never&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LISTEN / NOTIFY&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Never&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PREPARE / DEALLOCATE&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Never&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WITH HOLD CURSOR&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Never&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Session-level advisory locks&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Never&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;This is the strongest practical argument for rule 3. A session-level &lt;code&gt;SET&lt;/code&gt; is listed as "Never" under transaction pooling, because the server connection underneath you can change between statements. Inside an explicit transaction the pooler holds one server connection for the life of that transaction, and &lt;code&gt;SET LOCAL&lt;/code&gt; expires with it, so the tenant setting cannot outlive the work it belongs to. The PgBouncer docs do not call out &lt;code&gt;SET LOCAL&lt;/code&gt; specifically, so if you run a pooler, verify this against your own configuration rather than taking it on trust.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 4: the application role must not own the tables
&lt;/h2&gt;

&lt;p&gt;This one is short and it undoes everything above when you get it wrong.&lt;/p&gt;

&lt;p&gt;Superusers and roles carrying the &lt;code&gt;BYPASSRLS&lt;/code&gt; attribute "always bypass the row security system when accessing a table". Table owners bypass it too unless you used &lt;code&gt;FORCE&lt;/code&gt;. So the role your application connects as should own nothing, inherit nothing, and hold no &lt;code&gt;BYPASSRLS&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;ROLE&lt;/span&gt; &lt;span class="n"&gt;app_runtime&lt;/span&gt; &lt;span class="n"&gt;LOGIN&lt;/span&gt; &lt;span class="n"&gt;PASSWORD&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s1"&gt;'pw'&lt;/span&gt; &lt;span class="n"&gt;NOBYPASSRLS&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;GRANT&lt;/span&gt; &lt;span class="k"&gt;SELECT&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;INSERT&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;UPDATE&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;DELETE&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="k"&gt;ALL&lt;/span&gt; &lt;span class="n"&gt;TABLES&lt;/span&gt; &lt;span class="k"&gt;IN&lt;/span&gt; &lt;span class="k"&gt;SCHEMA&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="k"&gt;TO&lt;/span&gt; &lt;span class="n"&gt;app_runtime&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;-- migrations run as a different role that DOES own the tables&lt;/span&gt;
&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;ROLE&lt;/span&gt; &lt;span class="n"&gt;app_migrator&lt;/span&gt; &lt;span class="n"&gt;LOGIN&lt;/span&gt; &lt;span class="n"&gt;PASSWORD&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s1"&gt;'mpw'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then assert it, because a later migration can quietly change it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;rolname&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;rolsuper&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;rolbypassrls&lt;/span&gt;
&lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;pg_roles&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;rolname&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'app_runtime'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;-- expect: f, f&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Rule 5: USING hides rows, WITH CHECK stops you writing them
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;USING&lt;/code&gt; is the read filter. &lt;code&gt;WITH CHECK&lt;/code&gt; governs rows being inserted or modified. If you give a policy only a &lt;code&gt;USING&lt;/code&gt; clause, Postgres "implicitly provides a &lt;code&gt;WITH CHECK&lt;/code&gt; clause identical to its &lt;code&gt;USING&lt;/code&gt; clause" for the commands that need one, which is usually what you want.&lt;/p&gt;

&lt;p&gt;Where this bites is a policy written only &lt;code&gt;FOR SELECT&lt;/code&gt;. Reads are then isolated and writes are not, so an insert can create a row belonging to another tenant that the author of the insert can never see again. The row is real, it is in the other tenant's exports, and nothing in your logs points at it.&lt;/p&gt;

&lt;p&gt;Write both clauses explicitly. It costs one line and it removes an argument from every future code review.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 6: prove isolation on every build
&lt;/h2&gt;

&lt;p&gt;The only isolation you can trust is the kind something actively tries to break. This test belongs in CI, not in a quarterly review.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;tenant B cannot read tenant A rows by primary key&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;seedTenant&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;A&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;seedTenant&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;B&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;row&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;asTenant&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
    &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;one&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;INSERT INTO employees (tenant_id, name) VALUES ($1, $2) RETURNING id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
           &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Ada&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;]));&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;leaked&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;asTenant&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
    &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;oneOrNone&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;SELECT * FROM employees WHERE id = $1&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;]));&lt;/span&gt;

  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;leaked&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toBeNull&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;          &lt;span class="c1"&gt;// not "throws", not "403" — no row&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;every tenant-scoped table has RLS enabled and forced&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;bad&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;many&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`
    SELECT c.relname
    FROM pg_class c
    JOIN pg_namespace n ON n.oid = c.relnamespace
    WHERE n.nspname = 'app'
      AND c.relkind = 'r'
      AND EXISTS (SELECT 1 FROM information_schema.columns
                  WHERE table_schema = 'app'
                    AND table_name = c.relname
                    AND column_name = 'tenant_id')
      AND (c.relrowsecurity = false OR c.relforcerowsecurity = false)`&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;bad&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toEqual&lt;/span&gt;&lt;span class="p"&gt;([]);&lt;/span&gt;            &lt;span class="c1"&gt;// catches the table added last sprint&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The second test is the one that pays for itself. Nobody forgets isolation on the table they are thinking about. They forget it on the table they added at 6pm on a Friday, and no amount of code review reliably catches a missing &lt;code&gt;ALTER TABLE&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  The part that is not about queries at all
&lt;/h2&gt;

&lt;p&gt;Two operational facts tend to arrive late and expensively.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Migrations fan out.&lt;/strong&gt; With a database per tenant, a schema change is not one migration, it is N of them, and it will fail somewhere in the middle. An all-or-nothing migration across hundreds of databases is neither atomic nor finishable, so the runner has to be resumable, idempotent, and able to report which tenants are on which version. Build that before you need it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;One tenant can stall another.&lt;/strong&gt; A large export, an unbounded report, a runaway join — in a shared deployment these consume shared resources, and the tenant who did nothing wrong is the one who files the ticket. Reporting queries belong on a read replica, long jobs belong in a queue with per-tenant concurrency limits, and bulk imports should be idempotent and reversible because somebody will upload the same file twice.&lt;/p&gt;

&lt;h2&gt;
  
  
  A checklist before shipping a tenant-scoped feature
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Tenant resolved once, from the authenticated session only.&lt;/li&gt;
&lt;li&gt;No function anywhere accepts a tenant id as a parameter from the caller.&lt;/li&gt;
&lt;li&gt;New tables with a &lt;code&gt;tenant_id&lt;/code&gt; have &lt;code&gt;ENABLE&lt;/code&gt; &lt;strong&gt;and&lt;/strong&gt; &lt;code&gt;FORCE ROW LEVEL SECURITY&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Every policy has both &lt;code&gt;USING&lt;/code&gt; and &lt;code&gt;WITH CHECK&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;current_setting('app.tenant_id', true)&lt;/code&gt; — the &lt;code&gt;true&lt;/code&gt; is present.&lt;/li&gt;
&lt;li&gt;Tenant is set with &lt;code&gt;SET LOCAL&lt;/code&gt; / &lt;code&gt;set_config(..., true)&lt;/code&gt;, inside the transaction.&lt;/li&gt;
&lt;li&gt;The runtime role is not a superuser, has no &lt;code&gt;BYPASSRLS&lt;/code&gt;, and owns no tables.&lt;/li&gt;
&lt;li&gt;A cross-tenant read test runs in CI and fails the build.&lt;/li&gt;
&lt;li&gt;A catalog test asserts RLS on every tenant-scoped table.&lt;/li&gt;
&lt;li&gt;Background jobs open an explicit tenant context per tenant.&lt;/li&gt;
&lt;li&gt;Reporting runs on a replica; bulk imports are idempotent.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;None of this is clever. That is the point. Isolation should be the boring part of the system, enforced in three places that would all have to fail together, and checked by something that runs whether anyone remembers to think about it or not.&lt;/p&gt;




&lt;p&gt;We are the engineering team at INNERLUXES. We build multi-tenant platforms and integrate them with existing enterprise systems, which is where most of the above was learned the slow way.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>programming</category>
      <category>postgres</category>
      <category>node</category>
    </item>
    <item>
      <title>Manifest V3 Service Workers: Why Your Chrome Extension Keeps Losing State</title>
      <dc:creator>INNERLUXES</dc:creator>
      <pubDate>Wed, 28 Oct 2026 21:04:03 +0000</pubDate>
      <link>https://dev.to/innerluxes/manifest-v3-service-workers-why-your-chrome-extension-keeps-losing-state-5g</link>
      <guid>https://dev.to/innerluxes/manifest-v3-service-workers-why-your-chrome-extension-keeps-losing-state-5g</guid>
      <description>&lt;p&gt;The bug report always reads the same way. The extension works. Then the user leaves it alone for a minute, comes back, clicks the toolbar icon, and nothing happens. Or the badge count is wrong. Or the auth token the popup needs has vanished. Reload the extension and everything is fine again, which makes the whole thing look like a ghost.&lt;/p&gt;

&lt;p&gt;It is not a ghost. In Manifest V3 the background page is gone and a service worker took its place, and a service worker is not a process that stays running. Chrome starts it when an event needs it and shuts it down when nothing does. Every piece of state held in a module-scope variable goes with it.&lt;/p&gt;

&lt;p&gt;This post covers the exact lifecycle numbers, the five rules that follow from them, and the reason the bug never reproduces while you are watching it in DevTools.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Chrome actually does to your worker
&lt;/h2&gt;

&lt;p&gt;Four behaviours matter, and all four are documented:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Idle for 30 seconds and the worker is terminated.&lt;/strong&gt; Receiving an event or calling an extension API resets that timer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A single event or API call that runs longer than 5 minutes is killed.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A &lt;code&gt;fetch()&lt;/code&gt; whose response takes more than 30 seconds to arrive is killed.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Global variables do not survive.&lt;/strong&gt; The next event starts a fresh JavaScript instance with every module global back at its initial value.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;There is no &lt;code&gt;chrome.runtime.keepAlive()&lt;/code&gt;. There is no manifest key that asks for a persistent worker. The lifecycle is not a setting, it is the contract.&lt;/p&gt;

&lt;p&gt;Two narrow exceptions are worth knowing. Since Chrome 116, four APIs that put a prompt in front of the user are allowed to run past the five-minute ceiling, because the clock is really the user's: &lt;code&gt;desktopCapture.chooseDesktopMedia()&lt;/code&gt;, &lt;code&gt;identity.launchWebAuthFlow()&lt;/code&gt;, &lt;code&gt;management.uninstall()&lt;/code&gt; and &lt;code&gt;permissions.request()&lt;/code&gt;. Also since Chrome 116, an active WebSocket connection extends the worker's life, and every message sent or received over that socket resets the idle timer.&lt;/p&gt;

&lt;p&gt;Everything below follows from those four behaviours.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 1: register every listener at the top level, synchronously
&lt;/h2&gt;

&lt;p&gt;This is the single most common cause of "my extension responds to nothing until I reload it".&lt;/p&gt;

&lt;p&gt;When an event arrives for a sleeping worker, Chrome boots the worker, runs the script top to bottom, and then dispatches the event. If the listener for that event is not registered by the time the first turn of the event loop finishes, the event is already gone. It is not queued.&lt;/p&gt;

&lt;p&gt;So this breaks:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// background.js — BROKEN&lt;/span&gt;
&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;settings&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;settings&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="c1"&gt;// registered one microtask too late; the event that woke us is already lost&lt;/span&gt;
  &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onClicked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;openPanel&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And this breaks for the same reason:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// background.js — ALSO BROKEN&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;settings&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;settings&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// top-level await&lt;/span&gt;
&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onMessage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;handleMessage&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Top-level &lt;code&gt;await&lt;/code&gt; is legal in a service worker module and it still loses you the wake-up event, because the registration now happens after the initial evaluation.&lt;/p&gt;

&lt;p&gt;The fix is to register first and load state inside the handler:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// background.js — CORRECT&lt;/span&gt;
&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onClicked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tab&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;settings&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;defaults&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;settings&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;openPanel&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tab&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onMessage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;msg&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;sender&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;sendResponse&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;handleMessage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;msg&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;sender&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;then&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;sendResponse&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// keep the message channel open for the async reply&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onInstalled&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;seedDefaults&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onStartup&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;resyncFromServer&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three details in that block earn their place:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;return true&lt;/code&gt; from an &lt;code&gt;onMessage&lt;/code&gt; listener is what keeps the channel open for an asynchronous &lt;code&gt;sendResponse&lt;/code&gt;. Without it the port closes the moment the listener returns and the sender's callback gets &lt;code&gt;undefined&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;onInstalled&lt;/code&gt; fires on install and on update. It is the right place to write default settings and to call &lt;code&gt;chrome.alarms.create&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;onStartup&lt;/code&gt; fires when the browser profile starts. It is the right place to rebuild anything that lives only in memory.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A useful habit is to keep &lt;code&gt;background.js&lt;/code&gt; as nothing but a list of top-level listener registrations plus imports, and push all the work into other modules. If the file has any conditional or awaited code above a registration, that is the bug.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 2: module scope is a cache, never a source of truth
&lt;/h2&gt;

&lt;p&gt;A variable at module scope in a service worker is a cache with an eviction policy you do not control. Treat it exactly that way.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// BROKEN — token is gone 30 seconds after the last event&lt;/span&gt;
&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;authToken&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;getToken&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;authToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;authToken&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fetchToken&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;authToken&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The version that survives:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;getToken&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;authToken&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;authExpiry&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;authToken&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;authExpiry&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]);&lt;/span&gt;

  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;authToken&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;authExpiry&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="nx"&gt;_000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;authToken&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;fresh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fetchToken&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;set&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;authToken&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;fresh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;authExpiry&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;fresh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;expiresIn&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;fresh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Pick the storage area deliberately:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Need&lt;/th&gt;
&lt;th&gt;Use&lt;/th&gt;
&lt;th&gt;Notes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Secrets and session state&lt;/td&gt;
&lt;td&gt;&lt;code&gt;chrome.storage.session&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;In memory, cleared when the browser closes, not written to disk&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Settings that must persist&lt;/td&gt;
&lt;td&gt;&lt;code&gt;chrome.storage.local&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Survives restarts and updates&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Settings that follow the user&lt;/td&gt;
&lt;td&gt;&lt;code&gt;chrome.storage.sync&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Small quotas, per-item size limits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Large structured data&lt;/td&gt;
&lt;td&gt;IndexedDB&lt;/td&gt;
&lt;td&gt;Use when a quota or a query pattern rules out &lt;code&gt;storage&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fetched assets&lt;/td&gt;
&lt;td&gt;CacheStorage&lt;/td&gt;
&lt;td&gt;Same API as in a page worker&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;code&gt;localStorage&lt;/code&gt; and &lt;code&gt;sessionStorage&lt;/code&gt; are not available in an extension service worker at all, which is its own source of confusion when porting a Manifest V2 background page.&lt;/p&gt;

&lt;p&gt;One more trap: &lt;code&gt;chrome.storage&lt;/code&gt; reads and writes are asynchronous, and two events can wake the worker close together. If a counter matters, do not read, add one and write. Serialise the update behind a promise chain, or keep the counter somewhere that gives you an atomic operation.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 3: &lt;code&gt;setTimeout&lt;/code&gt; and &lt;code&gt;setInterval&lt;/code&gt; are not timers any more
&lt;/h2&gt;

&lt;p&gt;A timer longer than the idle window simply does not fire, because the worker holding it is gone before the callback is due.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// BROKEN — the worker is terminated long before this runs&lt;/span&gt;
&lt;span class="nf"&gt;setInterval&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;syncWithServer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;15&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;60&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Use &lt;code&gt;chrome.alarms&lt;/code&gt;, which lives in the browser rather than in the worker and wakes the worker up to deliver the event:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onInstalled&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;alarms&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sync&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;periodInMinutes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;15&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;alarms&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onAlarm&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;alarm&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;alarm&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sync&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;syncWithServer&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Notes that save time:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The minimum period is 30 seconds as of Chrome 120. Earlier versions clamp to one minute, and in a released extension anything under a minute was silently rounded up.&lt;/li&gt;
&lt;li&gt;Alarms persist across worker restarts but not across extension updates reliably, so create them in &lt;code&gt;onInstalled&lt;/code&gt; rather than assuming they are still there.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;chrome.alarms.create&lt;/code&gt; with the same name replaces the existing alarm instead of adding a second one, which makes it safe to call on every install and update.&lt;/li&gt;
&lt;li&gt;Short &lt;code&gt;setTimeout&lt;/code&gt; calls inside a single event handler are fine. The rule is about anything that needs to outlive the current event.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Rule 4: design for a 5-minute ceiling
&lt;/h2&gt;

&lt;p&gt;A long import, a bulk upload, a full re-index: any one of these can exceed five minutes in one event handler and be killed mid-way, leaving half-written state behind.&lt;/p&gt;

&lt;p&gt;The pattern that holds up is a queue plus an alarm. Write the work items to storage, process a bounded batch per wake-up, and let the alarm bring the worker back for the next batch.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;BATCH&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;25&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;alarms&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onAlarm&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;drain-queue&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;queue&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;queue&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;alarms&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;clear&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;drain-queue&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;batch&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;BATCH&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;done&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;processBatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;batch&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// returns the ids it finished&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;set&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;item&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;done&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;includes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)),&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Because each wake-up re-reads the queue and removes only what finished, a termination at any point costs one batch of work, not the job. The same shape makes the job resumable after a browser restart for free.&lt;/p&gt;

&lt;p&gt;The 30-second &lt;code&gt;fetch()&lt;/code&gt; limit deserves its own line. If a request to your own backend can legitimately take longer than that, the extension is the wrong place to wait for it. Return a job id immediately and poll.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 5: ports and sockets, and what they actually keep alive
&lt;/h2&gt;

&lt;p&gt;A long-lived connection from a content script or popup via &lt;code&gt;chrome.runtime.connect()&lt;/code&gt; keeps the worker alive while the port is open, and messages across it reset the idle timer. That is useful and it is also a trap, because the port closes when the popup closes or the tab navigates, and the worker then goes to sleep on the usual 30-second clock. Any code that assumed the port is still there needs an &lt;code&gt;onDisconnect&lt;/code&gt; handler:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onConnect&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;port&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;onTick&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;port&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;postMessage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nf"&gt;subscribe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;onTick&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;port&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onDisconnect&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;unsubscribe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;onTick&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On the content script side, reconnect rather than assume:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;port&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;port&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;panel&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="nx"&gt;port&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onMessage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;render&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;port&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;onDisconnect&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addListener&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;port&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nf"&gt;setTimeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// the worker was asleep; try again&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;An open WebSocket extends the worker's lifetime since Chrome 116, which makes a push connection viable, but it does not make it permanent. Treat every reconnect as normal operation and keep the server side idempotent.&lt;/p&gt;

&lt;p&gt;What does not work is a keepalive loop that pings itself to stay awake. It burns battery, it is a review flag, and Chrome has closed off the versions of the trick that used to work. If the design needs a process that never sleeps, that process belongs on a server, not in a browser extension.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule 6: anything that needs a DOM goes in an offscreen document
&lt;/h2&gt;

&lt;p&gt;A service worker has no &lt;code&gt;document&lt;/code&gt;, no &lt;code&gt;DOMParser&lt;/code&gt;, no &lt;code&gt;Audio&lt;/code&gt;, no canvas, and no clipboard. Code ported from a Manifest V2 background page hits this within minutes.&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;chrome.offscreen&lt;/code&gt; API creates a hidden document for exactly these cases:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;ensureOffscreen&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;existing&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getContexts&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;contextTypes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;OFFSCREEN_DOCUMENT&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;existing&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;chrome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;offscreen&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createDocument&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;offscreen.html&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;reasons&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;DOM_PARSER&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
    &lt;span class="na"&gt;justification&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Parse HTML returned by the sync endpoint&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two things to keep in mind. The &lt;code&gt;reasons&lt;/code&gt; array is reviewed, so it has to be honest. And the offscreen document has its own lifetime, so close it when the work is done rather than leaving it open as a back door to a persistent background page.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why it works on your machine
&lt;/h2&gt;

&lt;p&gt;This is the part that wastes the most days.&lt;/p&gt;

&lt;p&gt;While DevTools is attached to the service worker, Chrome does not terminate it. The worker you are inspecting is immortal, so none of the bugs above can reproduce. The state stays in memory, the interval keeps firing, the token is still there, and the conclusion is that the report must be wrong.&lt;/p&gt;

&lt;p&gt;Reproduce it properly instead:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Open &lt;code&gt;chrome://extensions&lt;/code&gt;, find the extension, and close any DevTools window attached to the worker.&lt;/li&gt;
&lt;li&gt;Open the card's &lt;strong&gt;service worker&lt;/strong&gt; link only when you need the console, and remember that opening it changes the behaviour you are testing.&lt;/li&gt;
&lt;li&gt;On the extensions page, the worker's status shows when it is inactive. Click &lt;strong&gt;Service worker&lt;/strong&gt; and it starts; wait 30 seconds without touching the extension and it stops.&lt;/li&gt;
&lt;li&gt;Exercise the feature cold: trigger the event with the worker already stopped, not immediately after a reload.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;A faster loop is to make the assumption testable in code. A single accessor for every piece of cross-event state, with a log line on a cache miss, turns "it loses the token sometimes" into a line in the console the first time the worker restarts.&lt;/p&gt;

&lt;h2&gt;
  
  
  The checklist
&lt;/h2&gt;

&lt;p&gt;Before shipping a Manifest V3 worker, confirm each of these:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Every &lt;code&gt;addListener&lt;/code&gt; call runs during initial evaluation, with no &lt;code&gt;await&lt;/code&gt;, condition or callback above it.&lt;/li&gt;
&lt;li&gt;No &lt;code&gt;await&lt;/code&gt; at the top level of the worker entry file.&lt;/li&gt;
&lt;li&gt;No cross-event state in module scope that is not backed by &lt;code&gt;chrome.storage&lt;/code&gt;, IndexedDB or CacheStorage.&lt;/li&gt;
&lt;li&gt;No &lt;code&gt;setInterval&lt;/code&gt;, and no &lt;code&gt;setTimeout&lt;/code&gt; expected to outlive the current event. Alarms instead, created in &lt;code&gt;onInstalled&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Every alarm handler checks &lt;code&gt;alarm.name&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Every long job is a queue drained in bounded batches, resumable after a kill at any point.&lt;/li&gt;
&lt;li&gt;No &lt;code&gt;fetch()&lt;/code&gt; on the critical path that can exceed 30 seconds.&lt;/li&gt;
&lt;li&gt;Every port has an &lt;code&gt;onDisconnect&lt;/code&gt; handler on both sides, and the content script reconnects.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;onMessage&lt;/code&gt; listeners that reply asynchronously &lt;code&gt;return true&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;DOM work is in an offscreen document that gets closed.&lt;/li&gt;
&lt;li&gt;The feature has been tested once with the worker cold and DevTools closed.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Most Manifest V3 migrations that are described as unstable are not fighting a Chrome bug. They are running Manifest V2 assumptions about a page that never went away on a worker that is designed to. Once state lives in storage, timers live in alarms and listeners are registered in the first turn of the event loop, the worker being terminated stops being an event worth handling.&lt;/p&gt;




&lt;p&gt;Written by the engineering team at Innerluxes. We build Chromium browsers and browser extensions, so this checklist comes out of migrations and audits rather than from the spec alone. If there is a lifecycle case here that does not match what you are seeing, the comments are a good place for it.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>javascript</category>
      <category>chrome</category>
      <category>programming</category>
    </item>
    <item>
      <title>Mobile Health App Development: Architecture and Security Basics for Developers</title>
      <dc:creator>INNERLUXES</dc:creator>
      <pubDate>Thu, 01 Oct 2026 17:57:49 +0000</pubDate>
      <link>https://dev.to/innerluxes/mobile-health-app-development-architecture-and-security-basics-for-developers-1j65</link>
      <guid>https://dev.to/innerluxes/mobile-health-app-development-architecture-and-security-basics-for-developers-1j65</guid>
      <description>&lt;p&gt;Mobile health (mHealth) apps are one of the fastest-growing areas in software. Patients want to book visits, track vitals, and message doctors from their phones. But building a health app is different from building a typical consumer app, because the data you handle is highly sensitive.&lt;/p&gt;

&lt;p&gt;This post covers the architecture and security basics we think every developer should know before starting &lt;strong&gt;mobile health app development&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Makes Health Apps Different?
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Sensitive data:&lt;/strong&gt; diagnoses, lab results, and prescriptions need strong protection.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Regulation:&lt;/strong&gt; depending on your market, you may need to follow HIPAA, GDPR, or local laws.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Trust:&lt;/strong&gt; one data leak can end a product and hurt real people.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reliability:&lt;/strong&gt; users depend on reminders, records, and alerts working correctly.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  A Simple, Safe Architecture
&lt;/h2&gt;

&lt;p&gt;A pattern that works well for most projects:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Mobile App  -&amp;gt;  API Gateway  -&amp;gt;  Backend Services  -&amp;gt;  Encrypted Database
                    |
              Auth + Audit Logs
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Mobile app:&lt;/strong&gt; UI only. Keep as little sensitive data on the device as possible.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;API gateway:&lt;/strong&gt; handles authentication, rate limiting, and request validation.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Backend services:&lt;/strong&gt; business logic, appointments, messaging.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Database:&lt;/strong&gt; encrypted at rest, with strict access control.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Audit logs:&lt;/strong&gt; record who accessed which record and when.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Keeping logic and data on the server makes it easier to secure, update, and audit.&lt;/p&gt;

&lt;h2&gt;
  
  
  Security Checklist
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Use HTTPS (TLS) everywhere.&lt;/strong&gt; Never send health data over plain HTTP.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add multi-factor authentication&lt;/strong&gt; for patients and staff.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Apply role-based access control.&lt;/strong&gt; A receptionist should not see clinical notes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep PHI out of logs, analytics, and push notifications.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Store tokens in the platform keystore,&lt;/strong&gt; not in plain text.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Set session timeouts&lt;/strong&gt; and auto-logout on inactivity.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Test regularly&lt;/strong&gt; with security scans and penetration tests.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Example: Storing a Token Securely in Flutter
&lt;/h2&gt;

&lt;p&gt;Do not keep access tokens in &lt;code&gt;SharedPreferences&lt;/code&gt;. Use secure storage, which relies on the iOS Keychain and Android Keystore:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight dart"&gt;&lt;code&gt;&lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="s"&gt;'package:flutter_secure_storage/flutter_secure_storage.dart'&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="n"&gt;storage&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;FlutterSecureStorage&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="n"&gt;Future&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;void&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;saveToken&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="kd"&gt;async&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;storage&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="na"&gt;write&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nl"&gt;key:&lt;/span&gt; &lt;span class="s"&gt;'access_token'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;value:&lt;/span&gt; &lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;Future&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;readToken&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="kd"&gt;async&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;storage&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="na"&gt;read&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nl"&gt;key:&lt;/span&gt; &lt;span class="s"&gt;'access_token'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;Future&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;void&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;clearToken&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="kd"&gt;async&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;storage&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="na"&gt;delete&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nl"&gt;key:&lt;/span&gt; &lt;span class="s"&gt;'access_token'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Always clear the token on logout.&lt;/p&gt;

&lt;h2&gt;
  
  
  Features to Build First
&lt;/h2&gt;

&lt;p&gt;For version 1, keep the scope small:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Secure sign-up and login&lt;/li&gt;
&lt;li&gt;Patient profile&lt;/li&gt;
&lt;li&gt;Appointment booking and reminders&lt;/li&gt;
&lt;li&gt;Secure messaging&lt;/li&gt;
&lt;li&gt;Simple provider dashboard&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Add wearable sync, analytics, or AI features after you collect feedback from real users.&lt;/p&gt;

&lt;h2&gt;
  
  
  Common Mistakes
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Treating compliance as a final-week task&lt;/li&gt;
&lt;li&gt;Sending patient names or details in push notifications&lt;/li&gt;
&lt;li&gt;Using third-party SDKs that collect data you did not plan for&lt;/li&gt;
&lt;li&gt;Skipping accessibility, even though many patients are elderly&lt;/li&gt;
&lt;li&gt;No plan for updates after launch&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Native or Cross-Platform?
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Approach&lt;/th&gt;
&lt;th&gt;Good for&lt;/th&gt;
&lt;th&gt;Trade-off&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Native (Swift, Kotlin)&lt;/td&gt;
&lt;td&gt;Deep device features, best performance&lt;/td&gt;
&lt;td&gt;Two codebases&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Flutter / React Native&lt;/td&gt;
&lt;td&gt;Faster delivery, one codebase&lt;/td&gt;
&lt;td&gt;Some features need native code&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;For most health apps, cross-platform is a solid starting point.&lt;/p&gt;

&lt;h2&gt;
  
  
  Final Thoughts
&lt;/h2&gt;

&lt;p&gt;Good mobile health app development comes down to a simple idea: protect user data first, keep the first release focused, and improve with real feedback.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;We are the team at Innerluxes, and we work on &lt;a href="https://innerluxes.dev/healthcare/mobile" rel="noopener noreferrer"&gt;mobile health app development&lt;/a&gt; for clinics and startups. If you have questions about architecture or security, drop them in the comments and I will be happy to help.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This article is for general information only and is not legal or compliance advice. Check the regulations that apply to your market.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>healthcare</category>
      <category>mobile</category>
      <category>security</category>
      <category>flutter</category>
    </item>
  </channel>
</rss>
