Merge pull request #151 from ConductionNL/fix/register-authorization-not-publicread

fix(register): the template taught publicRead and never taught authorization

Author: rubenvdlinde

README.md

@@ -66,6 +66,44 @@ _Update this diagram during `/app-explore` sessions as the architecture evolves.
 
 _Data model is defined using OpenRegister schemas. See [`openspec/specs/`](openspec/specs/) for feature-level design decisions and [`openspec/architecture/`](openspec/architecture/) for architectural decisions._
 
+#### Who can read a schema
+
+Declare an `authorization` block on **every** schema. Access is decided by
+OpenRegister's RBAC groups and by nothing else — `public` is a special group
+meaning "an anonymous visitor", and `authenticated` means "any logged-in user".
+
+```jsonc
+// authenticated users only — the safe default, and what this template ships
+"authorization": { "read": ["authenticated"] }
+
+// genuinely public content
+"authorization": { "read": ["public"] }
+
+// public, but only once a condition holds — e.g. a publication that is live.
+// RBAC then answers "may they read it" and "is it ready" in one place, instead
+// of every call site having to remember the second question.
+"authorization": {
+  "read": [
+    { "group": "public", "match": { "status": "published" } },
+    "authenticated"
+  ]
+}
+
+// a named group, for role-gated data
+"authorization": { "read": ["some-group-id"] }
+```
+
+> ⚠️ **`x-openregister.publicRead` / `publicWrite` are not a thing.** Earlier
+> versions of this template shipped them and they are not part of
+> OpenRegister's schema contract — nothing reads them, so a schema marked
+> `"publicRead": false` was never protected by that line. They have been
+> removed. If you find them in an app, replace them with an `authorization`
+> block.
+
+> ⚠️ **A schema that declares nothing inherits a default**, which is not a
+> decision anyone made about your data. Declare the block even when the answer
+> is the boring one.
+
 ### Directory Structure
 
 ```

lib/Settings/apptemplate_register.json

@@ -21,14 +21,15 @@
         "icon": "FileDocumentOutline",
         "version": "0.1.0",
         "title": "Example",
-        "description": "Example schema — replace with your app's actual schemas.",
+        "description": "Example schema — replace with your app's actual schemas. NOTE the `authorization` block below: declare one on EVERY schema you add. A schema that declares none inherits whatever OpenRegister's default happens to be, which is not a decision anyone made about your data.",
         "type": "object",
         "required": [
           "title"
         ],
-        "x-openregister": {
-          "publicRead": false,
-          "publicWrite": false
+        "authorization": {
+          "read": [
+            "authenticated"
+          ]
         },
         "properties": {
           "title": {

tests/validate-register.js

@@ -187,13 +187,25 @@ function validateRegister(file, errors, warnings) {
 				`${at}: "properties" is empty — schema looks clobbered (a merge may have replaced it with a stub)`,
 			)
 		// "too thin to be real" heuristic: a schema that declares a lifecycle/calc/notif/agg
-		// elsewhere but here has ≤3 properties and no x-openregister-* at all is suspect.
+		// elsewhere but here has ≤3 properties and nothing else declared at all is suspect.
+		//
+		// `authorization` counts as a declaration. It used not to, and that was
+		// an incentive in the wrong direction: removing a bogus
+		// `x-openregister: { publicRead: … }` block — which is NOT part of
+		// OpenRegister's schema contract and is read by nothing — made this
+		// warning fire, so the tooling rewarded keeping it. Declaring who may
+		// read a schema is at least as strong a sign of a real schema as
+		// declaring a seed.
 		const xKeys = Object.keys(s).filter((k) => k.startsWith('x-openregister'))
-		if (
-			props.length > 0
-			&& props.length <= 3
-			&& xKeys.filter((k) => k !== 'x-openregister-seed').length === 0
-		) {
+		// Boolean() is load-bearing: `s.authorization && …` yields `undefined`
+		// when the key is absent, and `undefined === false` is FALSE — so a
+		// strict comparison here silently disabled the whole heuristic. Caught
+		// by feeding it a genuine stub, which it then failed to flag.
+		const declaresSomething = Boolean(
+			xKeys.filter((k) => k !== 'x-openregister-seed').length > 0
+			|| (s.authorization && typeof s.authorization === 'object'),
+		)
+		if (props.length > 0 && props.length <= 3 && declaresSomething === false) {
 			warnings.push(
 				`${at}: only ${props.length} properties and no x-openregister-* declarations — verify this isn't a stub left by a bad merge`,
 			)