fix(service-settings): a clear of an env-pinned setting clears the stored value beneath the pin

An env override in force refused every write, clears included, so the
documented allowed-IP recovery (OS_AUTH_ALLOWED_IP_RANGES set empty) could
not clear the stored list and removing the variable locked the caller out
again. A clear (null/undefined) now goes through the pin; every other write
stays 409 SETTINGS_LOCKED. The refusal copy names the full recovery.

Claude-Session: https://claude.ai/code/session_01Utp6CZjAtpVuoYZBzB9n5i
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/plugins/plugin-auth/src/allowed-ip-ranges.ts

@@ -25,9 +25,13 @@
  * lock out, and it is let through.
  *
  * The way back when locked out anyway — a list saved from another address, or
- * an address that changed — is the settings env override every auth key has:
- * `OS_AUTH_ALLOWED_IP_RANGES` set to an empty value, then a restart. The
- * refusal names it.
+ * an address that changed — is the settings env override every auth key has,
+ * in four steps, and the refusal names them: start the server with
+ * `OS_AUTH_ALLOWED_IP_RANGES` set to an empty value (the override wins over
+ * the stored list, so the gate is open), sign in, clear the stored list (a
+ * settings write of `null` to the key, which the override lets through,
+ * #30385), then remove the variable. Removing it without the clear brings the
+ * stored list back at the next restart.
  */
 
 import { resolveLocale } from '@objectstack/core';
@@ -90,7 +94,10 @@ const COPY: Record<'en' | 'zh-CN' | 'ja-JP' | 'es-ES', RefusalCopy> = {
       'The server cannot establish the address you are connected from, and while any list is set it refuses every '
       + 'such request, your own next sign-in included. Save the list from a connection whose address the server can '
       + 'establish.',
-    recovery: ` If you are locked out, start the server with ${ALLOWED_IP_RANGES_ENV} set to an empty value.`,
+    recovery:
+      ` If you are locked out, start the server with ${ALLOWED_IP_RANGES_ENV} set to an empty value, sign in, `
+      + 'clear the stored list with a settings request that sets allowed_ip_ranges to null '
+      + '(PUT /api/settings/auth), then remove the variable.',
   },
   'zh-CN': {
     outside: (address) =>
@@ -99,7 +106,9 @@ const COPY: Record<'en' | 'zh-CN' | 'ja-JP' | 'es-ES', RefusalCopy> = {
     undetermined:
       '服务器无法确定你当前连接所用的地址；只要设置了列表，这样的请求都会被拒绝，你自己下一次登录也不例外。'
       + '请在服务器能确定地址的连接上保存。',
-    recovery: `如果已被锁在外面，可将环境变量 ${ALLOWED_IP_RANGES_ENV} 设为空值后重启服务器。`,
+    recovery:
+      `如果已被锁在外面：将环境变量 ${ALLOWED_IP_RANGES_ENV} 设为空值后重启服务器并登录，`
+      + '用一次把 allowed_ip_ranges 设为 null 的设置请求（PUT /api/settings/auth）清除已保存的列表，再去掉该环境变量。',
   },
   'ja-JP': {
     outside: (address) =>
@@ -108,7 +117,10 @@ const COPY: Record<'en' | 'zh-CN' | 'ja-JP' | 'es-ES', RefusalCopy> = {
     undetermined:
       'サーバーは現在の接続のアドレスを確定できません。リストが設定されている間はそのようなリクエストはすべて拒否され、'
       + 'ご自身の次回のサインインも同様です。サーバーがアドレスを確定できる接続から保存してください。',
-    recovery: `締め出された場合は、環境変数 ${ALLOWED_IP_RANGES_ENV} を空の値にしてサーバーを再起動してください。`,
+    recovery:
+      `締め出された場合は、環境変数 ${ALLOWED_IP_RANGES_ENV} を空の値にしてサーバーを再起動してサインインし、`
+      + 'allowed_ip_ranges を null にする設定リクエスト（PUT /api/settings/auth）で保存済みのリストを消去してから、'
+      + '環境変数を削除してください。',
   },
   'es-ES': {
     outside: (address) =>
@@ -119,7 +131,10 @@ const COPY: Record<'en' | 'zh-CN' | 'ja-JP' | 'es-ES', RefusalCopy> = {
       'El servidor no puede determinar la dirección desde la que está conectado y, mientras haya una lista, rechaza '
       + 'todas esas solicitudes, incluido su propio próximo inicio de sesión. Guarde la lista desde una conexión cuya '
       + 'dirección el servidor pueda determinar.',
-    recovery: ` Si queda bloqueado, inicie el servidor con ${ALLOWED_IP_RANGES_ENV} con un valor vacío.`,
+    recovery:
+      ` Si queda bloqueado, inicie el servidor con ${ALLOWED_IP_RANGES_ENV} con un valor vacío, inicie sesión, `
+      + 'borre la lista guardada con una solicitud de ajustes que ponga allowed_ip_ranges a null '
+      + '(PUT /api/settings/auth) y después quite la variable.',
   },
 };
 

packages/services/service-settings/src/settings-service.ts

@@ -2340,7 +2340,12 @@ export class SettingsService {
     };
   }
 
-  /** Persist a single key. Throws SettingsLockedError when env-locked. */
+  /**
+   * Persist a single key. Throws SettingsLockedError when an env override in
+   * force pins the key, unless `value` is a clear (`null` / `undefined`), which
+   * clears the stored value beneath the pin and leaves the env value in force
+   * (see {@link setMany}).
+   */
   async set(
     namespace: string,
     key: string,
@@ -2360,6 +2365,14 @@ export class SettingsService {
    * the row it would store names no owner, and the user rung answers only its
    * owner, so no reader would ever see it while the write reported success.
    *
+   * A key an env override in force pins refuses every write with
+   * {@link SettingsLockedError} (`locked-by-env`, ADR-0007 D6) but a clear
+   * (`null` / `undefined`): a clear nulls the row stored beneath the pin, so
+   * the key falls back to its default once the override is removed, and
+   * changes nothing in force — the answer still reads the env value with
+   * `locked: true`. It is judged by the row locks and the write predicates
+   * like any other clear.
+   *
    * `display` picks the language of a write predicate's refusal and hands it
    * the request the write arrived on, and nothing else (see
    * {@link refuseByWritePredicates}).
@@ -2403,7 +2416,23 @@ export class SettingsService {
       // UI refused with `SETTINGS_LOCKED`, and `get()` reporting `locked: false`
       // to a settings page that would then fail its own save. See
       // `effectiveEnvOverride`.
-      if (this.effectiveEnvOverride(reg, namespace, key)) {
+      //
+      // [#30385] A CLEAR goes through the pin (ADR-0007 D6 keeps refusing every
+      // other write): `null` / `undefined`, the spelling every clear in this
+      // service uses, never a value such as `''` that a key would store. The
+      // pin decides what is in force, and a clear changes nothing there — the
+      // env value still wins, and the answer still reads `locked: true` from
+      // `env`. What it does change is the stored value the key falls back to
+      // once the override is removed, and that value is otherwise reachable by
+      // nothing: the override hides it from every read and refuses every
+      // write, so an operator who pinned a key to recover from a bad stored
+      // value (`OS_AUTH_ALLOWED_IP_RANGES=` for an allow-list that locks them
+      // out) gets the same bad value back the moment the pin is lifted. The
+      // clear then meets every judgment a clear meets without a pin — the
+      // Phase 2 row locks and the platform-rung rule below, the write
+      // predicates — so no lock a row carries is bypassed.
+      const clears = patch[key] === null || typeof patch[key] === 'undefined';
+      if (!clears && this.effectiveEnvOverride(reg, namespace, key)) {
         throw new SettingsLockedError(namespace, key);
       }
 

packages/services/service-settings/src/settings-service.types.ts

@@ -594,7 +594,11 @@ export function envKeyOf(namespace: string, key: string): string {
   return `OS_${slug}`;
 }
 
-/** Thrown when a caller tries to write a value pinned by env. */
+/**
+ * Thrown when a caller tries to write a value pinned by env (`locked-by-env`;
+ * a clear — `null` / `undefined` — is not refused, it clears the stored value
+ * beneath the pin), or past a locked row (`locked-by-<scope>`).
+ */
 export class SettingsLockedError extends Error {
   readonly code = 'SETTINGS_LOCKED' as const;
   constructor(