halkyon_app: data locations as precise as a country or a state

An operator's DATA_LOCATION and BACKUP_LOCATION may name a subdivision
(ISO 3166-2, US-CA, DE-BY) besides the EU or a country. The app adds
"(EU)" to a member country and the country to a subdivision ("Germany
(EU)", "California, United States", "Bavaria, Germany (EU)"), in
English and German, and shows the most specific flag there is: a
subdivision's own where the flag package has one, else its country's.
Subdivision names come from Unicode CLDR 48.2 (tool/subdivision_names.py),
bundled with their licence, which the app registers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

packages/halkyon_base_server/README.md

@@ -92,7 +92,9 @@ The passwords it reads: `serverSideSessionKeyHashPepper`; for GitHub `githubClie
 `githubClientSecret`; for email `emailSignInPepper` and `emailSmtpHost`,
 `emailSmtpPort`, `emailSmtpUser`, `emailSmtpPassword`, `emailFrom`. Never change either
 pepper once people sign in: every session or address hash would be lost. The environment:
-`SOURCE_URL`, `DATA_LOCATION`, `BACKUP_LOCATION`.
+`SOURCE_URL`, `DATA_LOCATION`, `BACKUP_LOCATION`: where the instance keeps people's data
+and its backups, each `EU`, a country's code (`DE`) or a subdivision's (ISO 3166-2,
+`US-CA`, `DE-BY`), the backups also `none`; where the disks are, not which law governs.
 
 ## Developing it
 

packages/halkyon_base_server/lib/src/generated/instance/instance_basics.dart

@@ -73,9 +73,9 @@ abstract class InstanceBasics
   int minimumAppBuild;
 
   /// Where this instance keeps people's data, as its operator says
-  /// (DATA_LOCATION): a country's code (ISO 3166-1 alpha-2, `CH`) or `EU`;
-  /// where the disks are, not which law governs. Null where the operator
-  /// says nothing.
+  /// (DATA_LOCATION): `EU`, a country's code (ISO 3166-1 alpha-2, `DE`) or a
+  /// subdivision's (ISO 3166-2, `US-CA`, `DE-BY`), in capitals; where the
+  /// disks are, not which law governs. Null where the operator says nothing.
   String? dataLocation;
 
   /// Where it keeps its backups (BACKUP_LOCATION): as [dataLocation], or

packages/halkyon_base_server/lib/src/instance/data_location.dart

@@ -4,9 +4,10 @@ import 'dart:io';
 const noBackups = 'none';
 
 /// Where this instance keeps people's data, as its operator says
-/// (`DATA_LOCATION`, decided 2026-10-18): a country's code (ISO 3166-1
-/// alpha-2, `CH`) or `EU`. Where the disks are, not which law governs: an
-/// operator living elsewhere is bound by their own country's courts too.
+/// (`DATA_LOCATION`, decided 2026-10-18): `EU`, a country's code (ISO 3166-1
+/// alpha-2, `DE`) or, more precisely, a subdivision's (ISO 3166-2, `US-CA`,
+/// `DE-BY`; decided 2026-10-19). Where the disks are, not which law governs:
+/// an operator living elsewhere is bound by their own country's courts too.
 /// Null where the operator says nothing.
 String? dataLocation() =>
     dataLocationFrom(Platform.environment['DATA_LOCATION']);
@@ -16,13 +17,19 @@ String? dataLocation() =>
 String? backupLocation() =>
     backupLocationFrom(Platform.environment['BACKUP_LOCATION']);
 
-/// [value] as a location: two letters, in capitals; null for anything
-/// else.
+/// [value] as a location, in capitals: a country's two letters, or a
+/// subdivision's code, the country's two letters, a hyphen and one to three
+/// letters or digits (`US-CA`, `FR-75`); null for anything else. The
+/// European Union has no subdivisions.
 String? dataLocationFrom(String? value) {
   final code = value?.trim().toUpperCase();
-  return code != null && RegExp(r'^[A-Z]{2}$').hasMatch(code) ? code : null;
+  return code != null && _location.hasMatch(code) && !code.startsWith('EU-')
+      ? code
+      : null;
 }
 
+final _location = RegExp(r'^[A-Z]{2}(-[A-Z0-9]{1,3})?$');
+
 /// [value] as the backups' location: as [dataLocationFrom], or [noBackups].
 String? backupLocationFrom(String? value) =>
     value?.trim().toLowerCase() == noBackups

packages/halkyon_base_server/lib/src/instance/instance_basics.spy.yaml

@@ -20,9 +20,9 @@ fields:
   ### server still works with; older apps ask to be updated.
   minimumAppBuild: int
   ### Where this instance keeps people's data, as its operator says
-  ### (DATA_LOCATION): a country's code (ISO 3166-1 alpha-2, `CH`) or `EU`;
-  ### where the disks are, not which law governs. Null where the operator
-  ### says nothing.
+  ### (DATA_LOCATION): `EU`, a country's code (ISO 3166-1 alpha-2, `DE`) or a
+  ### subdivision's (ISO 3166-2, `US-CA`, `DE-BY`), in capitals; where the
+  ### disks are, not which law governs. Null where the operator says nothing.
   dataLocation: String?
   ### Where it keeps its backups (BACKUP_LOCATION): as [dataLocation], or
   ### `none` where it keeps none. Null where the operator says nothing.

packages/halkyon_base_server/test/unit/data_location_test.dart

@@ -8,8 +8,19 @@ void main() {
       expect(dataLocationFrom('EU'), 'EU');
     });
 
+    test("is a subdivision's code (ISO 3166-2): a state, a canton, a "
+        'region', () {
+      expect(dataLocationFrom('US-CA'), 'US-CA');
+      expect(dataLocationFrom('DE-BY'), 'DE-BY');
+      expect(dataLocationFrom('GB-SCT'), 'GB-SCT');
+      // Some countries number theirs.
+      expect(dataLocationFrom('FR-75'), 'FR-75');
+      expect(dataLocationFrom('JP-13'), 'JP-13');
+    });
+
     test('is read in either case, around spaces', () {
       expect(dataLocationFrom(' ch '), 'CH');
+      expect(dataLocationFrom(' us-ca '), 'US-CA');
     });
 
     test('is nothing where it is unset, empty or no code', () {
@@ -17,6 +28,11 @@ void main() {
       expect(dataLocationFrom(''), isNull);
       expect(dataLocationFrom('Switzerland'), isNull);
       expect(dataLocationFrom('C1'), isNull);
+      expect(dataLocationFrom('US-'), isNull);
+      expect(dataLocationFrom('US-CALI'), isNull);
+      expect(dataLocationFrom('US CA'), isNull);
+      expect(dataLocationFrom('USA-CA'), isNull);
+      expect(dataLocationFrom('EU-DE'), isNull);
     });
 
     test('is never "none": the data is somewhere', () {
@@ -25,8 +41,9 @@ void main() {
   });
 
   group('Where the operator says its backups are', () {
-    test("is a country's code or the European Union's", () {
+    test("is a country's code, a subdivision's or the European Union's", () {
       expect(backupLocationFrom('ch'), 'CH');
+      expect(backupLocationFrom('fi-18'), 'FI-18');
       expect(backupLocationFrom('EU'), 'EU');
     });