paperless-ngx: strict values.schema.json and null-safe hardening

Largest values surface of the programme, and the first chart where the
null-safety covers two workloads.

1. values.schema.json (#68): additionalProperties: false on every
   chart-owned object level, including files.barcodes, ocr (with enums
   for the 3.x modes), scripts, tikaGotenberg, the oidc provider block
   and the SMB CronJob.

2. Null-safety for hardening, probes and resources (#99), for the server
   AND the SMB consume-mover CronJob. It reuses the defaultedDict helper
   the barcodes block already introduced (#61) instead of adding a second
   mechanism - one merge helper, now with more callers.

   The server's pod context is consumed twice: as the pod securityContext
   and by the /run-ownership init container, which chowns /run to
   runAsUser:runAsGroup because s6-overlay refuses to start unless /run is
   owned by the runtime uid. Both reads now go through the same helper, so
   the chown cannot disagree with the context it has to match. Erasing
   that block used to abort rendering with a nil-pointer error; it now
   falls back to the defaults like every other chart.

The CronJob has no probes (documented exception), so only its two
contexts and resources are covered.

files.storage stays deliberately not null-safe: an erased value yields an
invalid PVC, which is the loud class #99 excludes.

Rendering is byte-identical to 11.0.0, both with the CI values (which
include the #61 regression guard) and with the production paperless-jk
bundle values.

paperless-ngx/Chart.yaml

@@ -5,7 +5,7 @@ icon: https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/dev/src-ui/s
 
 type: application
 
-version: 11.0.0+up3.0.5
+version: 12.0.0+up3.0.5
 
 appVersion: 3.0.5
 

paperless-ngx/templates/_helpers.tpl

@@ -189,3 +189,133 @@ fallback for the case where an override has erased the block.
       "asn" (dict "enabled" true) -}}
 {{- include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" . "path" "paperless.files.barcodes") -}}
 {{- end -}}
+
+{{/*
+Pick one sub-block out of a values block that may itself be null.
+
+Input: dict "block" <dict|nil> "key" <string> "path" <string>.
+Returns YAML of dict "value" <the sub-block, may be nil>, after rejecting a
+non-mapping block with a message that names the values path. Needed because
+".Values.paperless.securityContext" can itself be erased.
+*/}}
+{{- define "paperless-ngx.subBlock" -}}
+{{- $block := .block -}}
+{{- if kindIs "invalid" $block -}}
+{{- $block = dict -}}
+{{- end -}}
+{{- if not (kindIs "map" $block) -}}
+{{- fail (printf "%s must be a mapping or null, got %s (%v)" .path (kindOf $block) $block) -}}
+{{- end -}}
+{{- toYaml (dict "value" (index $block .key)) -}}
+{{- end -}}
+
+{{/*
+The effective security contexts, probes and resources of both workloads
+(issue #99), built on the same defaultedDict the barcodes block already uses
+(issue #61) - one mechanism, not two.
+
+The defaults below MUST stay in sync with the corresponding blocks in
+values.yaml, which stays the documented, user-facing place for them; this copy
+is only the fallback for the case where an override has erased the block.
+
+The pod context is consumed twice: as the pod's securityContext and by the
+/run-ownership init container, which chowns the /run emptyDir to
+runAsUser:runAsGroup because s6-overlay refuses to start unless /run is OWNED
+by the runtime uid. Both reads go through this helper, so the chown can never
+disagree with the context it is supposed to match.
+*/}}
+{{- define "paperless-ngx.podSecurityContext" -}}
+{{- $given := (fromYaml (include "paperless-ngx.subBlock" (dict "block" . "key" "pod" "path" "paperless.securityContext"))).value -}}
+{{- $defaults := dict
+      "runAsNonRoot" true
+      "runAsUser" 1000
+      "runAsGroup" 1000
+      "fsGroup" 1000
+      "fsGroupChangePolicy" "Always" -}}
+{{- include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" $given "path" "paperless.securityContext.pod") -}}
+{{- end -}}
+
+{{- define "paperless-ngx.containerSecurityContext" -}}
+{{- $given := (fromYaml (include "paperless-ngx.subBlock" (dict "block" . "key" "container" "path" "paperless.securityContext"))).value -}}
+{{- $defaults := dict
+      "allowPrivilegeEscalation" false
+      "readOnlyRootFilesystem" true
+      "runAsNonRoot" true
+      "capabilities" (dict "drop" (list "ALL")) -}}
+{{- include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" $given "path" "paperless.securityContext.container") -}}
+{{- end -}}
+
+{{- define "paperless-ngx.livenessProbe" -}}
+{{- $defaults := dict
+      "httpGet" (dict "path" "/" "port" 8000)
+      "periodSeconds" 30
+      "failureThreshold" 3
+      "successThreshold" 1
+      "timeoutSeconds" 5 -}}
+{{- include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" . "path" "paperless.livenessProbe") -}}
+{{- end -}}
+
+{{- define "paperless-ngx.readinessProbe" -}}
+{{- $defaults := dict
+      "httpGet" (dict "path" "/" "port" 8000)
+      "periodSeconds" 10
+      "failureThreshold" 3
+      "successThreshold" 1
+      "timeoutSeconds" 5 -}}
+{{- include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" . "path" "paperless.readinessProbe") -}}
+{{- end -}}
+
+{{/*
+The startup budget is deliberately large (10s x 60 = 600s): paperless runs
+database migrations on startup, and since 3.0 the first start after an upgrade
+also rebuilds the search index from scratch (Whoosh -> Tantivy).
+*/}}
+{{- define "paperless-ngx.startupProbe" -}}
+{{- $defaults := dict
+      "httpGet" (dict "path" "/" "port" 8000)
+      "periodSeconds" 10
+      "failureThreshold" 60
+      "timeoutSeconds" 5 -}}
+{{- include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" . "path" "paperless.startupProbe") -}}
+{{- end -}}
+
+{{- define "paperless-ngx.effectiveResources" -}}
+{{- $defaults := dict
+      "limitFactor" 3
+      "requests" (dict "cpu" 0.2 "memory" "1024Mi" "ephemeralStorage" "200Mi") -}}
+{{- $merged := fromYaml (include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" . "path" "paperless.resources")) -}}
+{{- include "paperless-ngx.resources" $merged -}}
+{{- end -}}
+
+{{/*
+The same three fallbacks for the SMB consume-mover CronJob. It has no probes
+(documented exception), so only the two contexts and resources apply.
+*/}}
+{{- define "paperless-ngx.cron.podSecurityContext" -}}
+{{- $given := (fromYaml (include "paperless-ngx.subBlock" (dict "block" . "key" "pod" "path" "smbConnection.cron.securityContext"))).value -}}
+{{- $defaults := dict
+      "runAsNonRoot" true
+      "runAsUser" 1000
+      "runAsGroup" 1000
+      "fsGroup" 1000
+      "fsGroupChangePolicy" "Always" -}}
+{{- include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" $given "path" "smbConnection.cron.securityContext.pod") -}}
+{{- end -}}
+
+{{- define "paperless-ngx.cron.containerSecurityContext" -}}
+{{- $given := (fromYaml (include "paperless-ngx.subBlock" (dict "block" . "key" "container" "path" "smbConnection.cron.securityContext"))).value -}}
+{{- $defaults := dict
+      "allowPrivilegeEscalation" false
+      "readOnlyRootFilesystem" true
+      "runAsNonRoot" true
+      "capabilities" (dict "drop" (list "ALL")) -}}
+{{- include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" $given "path" "smbConnection.cron.securityContext.container") -}}
+{{- end -}}
+
+{{- define "paperless-ngx.cron.effectiveResources" -}}
+{{- $defaults := dict
+      "limitFactor" 3
+      "requests" (dict "cpu" "10m" "memory" "16Mi" "ephemeralStorage" "10Mi") -}}
+{{- $merged := fromYaml (include "paperless-ngx.defaultedDict" (dict "defaults" $defaults "given" . "path" "smbConnection.cron.resources")) -}}
+{{- include "paperless-ngx.resources" $merged -}}
+{{- end -}}

paperless-ngx/templates/paperless-consume.cronjob.yaml

@@ -14,13 +14,13 @@ spec:
         spec:
           automountServiceAccountToken: false
           securityContext:
-            {{- toYaml .Values.smbConnection.cron.securityContext.pod | nindent 12 }}
+            {{- include "paperless-ngx.cron.podSecurityContext" .Values.smbConnection.cron.securityContext | nindent 12 }}
           containers:
             - name: paperless-consume-cronjob
               image: "{{ .Values.paperless.busybox.image.repository }}:{{ .Values.paperless.busybox.image.tag }}"
               imagePullPolicy: IfNotPresent
               securityContext:
-                {{- toYaml .Values.smbConnection.cron.securityContext.container | nindent 16 }}
+                {{- include "paperless-ngx.cron.containerSecurityContext" .Values.smbConnection.cron.securityContext | nindent 16 }}
               command:
                 - /bin/sh
                 - -c
@@ -33,7 +33,7 @@ spec:
                   mountPath: "/mnt/consume"
                   readOnly: false
               resources:
-                {{- include "paperless-ngx.resources" .Values.smbConnection.cron.resources | nindent 16 }}
+                {{- include "paperless-ngx.cron.effectiveResources" .Values.smbConnection.cron.resources | nindent 16 }}
           restartPolicy: Never
           volumes:
             - name: smb-share

paperless-ngx/templates/paperless-server.sfs.yaml

@@ -23,7 +23,7 @@ spec:
     spec:
       automountServiceAccountToken: false
       securityContext:
-        {{- toYaml .Values.paperless.securityContext.pod | nindent 8 }}
+        {{- include "paperless-ngx.podSecurityContext" .Values.paperless.securityContext | nindent 8 }}
       initContainers:
         # s6-overlay refuses to start unless /run is owned by the runtime uid,
         # but emptyDirs are always created root-owned. This minimal init
@@ -36,7 +36,8 @@ spec:
           command:
             - sh
             - -c
-            - chown {{ .Values.paperless.securityContext.pod.runAsUser }}:{{ .Values.paperless.securityContext.pod.runAsGroup }} /run
+            {{- $podCtx := fromYaml (include "paperless-ngx.podSecurityContext" .Values.paperless.securityContext) }}
+            - chown {{ $podCtx.runAsUser }}:{{ $podCtx.runAsGroup }} /run
           securityContext:
             runAsNonRoot: false
             runAsUser: 0
@@ -64,7 +65,7 @@ spec:
           image: "ghcr.io/paperless-ngx/paperless-ngx:{{ .Chart.AppVersion }}"
           imagePullPolicy: IfNotPresent
           securityContext:
-            {{- toYaml .Values.paperless.securityContext.container | nindent 12 }}
+            {{- include "paperless-ngx.containerSecurityContext" .Values.paperless.securityContext | nindent 12 }}
           ports:
             - containerPort: 8000
               protocol: TCP
@@ -229,13 +230,13 @@ spec:
             - mountPath: /run
               name: run
           resources:
-            {{- include "paperless-ngx.resources" .Values.paperless.resources | nindent 12 }}
+            {{- include "paperless-ngx.effectiveResources" .Values.paperless.resources | nindent 12 }}
           readinessProbe:
-            {{- toYaml .Values.paperless.readinessProbe | nindent 12 }}
+            {{- include "paperless-ngx.readinessProbe" .Values.paperless.readinessProbe | nindent 12 }}
           livenessProbe:
-            {{- toYaml .Values.paperless.livenessProbe | nindent 12 }}
+            {{- include "paperless-ngx.livenessProbe" .Values.paperless.livenessProbe | nindent 12 }}
           startupProbe:
-            {{- toYaml .Values.paperless.startupProbe | nindent 12 }}
+            {{- include "paperless-ngx.startupProbe" .Values.paperless.startupProbe | nindent 12 }}
       restartPolicy: Always
       volumes:
         - name: tmp

paperless-ngx/values.schema.json

@@ -0,0 +1,363 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "title": "paperless-ngx values",
+  "description": "Strict values schema (issue #68). additionalProperties is false on every chart-owned object level, so a key that the chart does not read is rejected at render time instead of being silently ignored. The only objects that stay open are the ones passed verbatim into the Kubernetes pod spec (probes, security contexts, global) - the chart does not interpret their contents, so it cannot judge which keys are meaningful. The hardening, probe and resources blocks of BOTH workloads, and the barcodes block from issue #61, additionally accept null, because an erased block falls back to the chart defaults (issues #61 and #99).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "global": {
+      "description": "Helm's conventional cross-chart values. Unused by this chart, kept open so an umbrella install cannot break on it.",
+      "type": "object"
+    },
+    "scaleDown": {
+      "type": "boolean"
+    },
+    "secrets": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "redisSecretRef": {
+          "type": ["string", "null"]
+        },
+        "databaseSecretRef": {
+          "type": ["string", "null"]
+        },
+        "paperlessSecretRef": {
+          "type": ["string", "null"]
+        },
+        "smbConnectionSecretRef": {
+          "type": ["string", "null"]
+        },
+        "oidcSecretRef": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "ingress": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "clusterIssuer": {
+          "type": ["string", "null"]
+        },
+        "domain": {
+          "type": ["string", "null"]
+        },
+        "className": {
+          "type": ["string", "null"]
+        },
+        "annotations": {
+          "description": "Extra Ingress annotations, merged with the cert-manager and upload-size annotations the chart always sets. Free-form keys by nature.",
+          "type": "object"
+        }
+      }
+    },
+    "paperless": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "replicas": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "busybox": {
+          "description": "Auxiliary image for the /run-ownership init container and the SMB consume-mover CronJob. Pinned independently of appVersion.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "image": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "repository": {
+                  "type": ["string", "null"]
+                },
+                "tag": {
+                  "type": ["string", "number", "null"]
+                }
+              }
+            }
+          }
+        },
+        "ocr": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "languages": {
+              "type": ["string", "null"]
+            },
+            "mode": {
+              "description": "paperless-ngx 3.x modes. The 2.x values skip/skip_noarchive were removed upstream; skip maps to auto.",
+              "type": ["string", "null"],
+              "enum": ["auto", "redo", "force", "off", null]
+            },
+            "archiveFileGeneration": {
+              "description": "Archive (PDF/A) generation, decoupled from OCR in 3.0.",
+              "type": ["string", "null"],
+              "enum": ["auto", "always", "never", null]
+            },
+            "rotate_pages": {
+              "type": ["string", "boolean", "null"]
+            },
+            "output_type": {
+              "type": ["string", "null"]
+            }
+          }
+        },
+        "files": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "filenameFormat": {
+              "type": ["string", "null"]
+            },
+            "storage": {
+              "description": "Size of the media PVC. Not null-safe on purpose: an erased value yields an invalid PVC rather than a silently degraded workload.",
+              "type": ["string", "null"]
+            },
+            "maxUploadFileSize": {
+              "type": ["string", "null"]
+            },
+            "barcodes": {
+              "description": "May be null / empty: the chart then falls back to these defaults instead of letting a childless key erase them (issue #61). To switch barcode handling off, set enabled: false explicitly.",
+              "type": ["object", "null"],
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "barcodeString": {
+                  "type": ["string", "null"]
+                },
+                "retainBarcodePage": {
+                  "type": "boolean"
+                },
+                "asn": {
+                  "type": ["object", "null"],
+                  "additionalProperties": false,
+                  "properties": {
+                    "enabled": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            },
+            "deleteDuplicates": {
+              "description": "paperless-ngx 3.0 no longer rejects duplicates by default; true restores the 2.x behaviour.",
+              "type": "boolean"
+            },
+            "tikaGotenberg": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "description": "Boolean or string - all three production bundles write it as the string \"true\", and the value is passed straight through as PAPERLESS_TIKA_ENABLED. Note that the template gates on truthiness, so the STRING \"false\" still renders the block (and keeps the two endpoints required) even though the env value it emits is \"false\"; use a real boolean false to switch the block off.",
+                  "type": ["boolean", "string", "null"]
+                },
+                "tikaEndpoint": {
+                  "type": ["string", "null"]
+                },
+                "gotenbergEndpoint": {
+                  "type": ["string", "null"]
+                }
+              }
+            }
+          }
+        },
+        "scripts": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "postConsumptionScripts": {
+              "type": ["array", "null"]
+            },
+            "preConsumptionScripts": {
+              "type": ["array", "null"]
+            }
+          }
+        },
+        "livenessProbe": {
+          "$ref": "#/definitions/probe"
+        },
+        "readinessProbe": {
+          "$ref": "#/definitions/probe"
+        },
+        "startupProbe": {
+          "$ref": "#/definitions/probe"
+        },
+        "env": {
+          "$ref": "#/definitions/env"
+        },
+        "resources": {
+          "$ref": "#/definitions/resources"
+        },
+        "securityContext": {
+          "$ref": "#/definitions/securityContext"
+        }
+      }
+    },
+    "smbConnection": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "server": {
+          "type": ["string", "null"]
+        },
+        "cronJob": {
+          "description": "Cron schedule of the consume-mover job.",
+          "type": ["string", "null"]
+        },
+        "cron": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "securityContext": {
+              "$ref": "#/definitions/securityContext"
+            },
+            "resources": {
+              "$ref": "#/definitions/resources"
+            }
+          }
+        }
+      }
+    },
+    "oidc": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "autoLoginWithProvider": {
+          "type": "boolean"
+        },
+        "disableRegularLogin": {
+          "type": "boolean"
+        },
+        "provider": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": ["string", "null"]
+            },
+            "name": {
+              "type": ["string", "null"]
+            },
+            "clientId": {
+              "type": ["string", "null"]
+            },
+            "discoveryUrl": {
+              "type": ["string", "null"]
+            },
+            "tokenAuthMethod": {
+              "description": "Explicit token endpoint auth method (e.g. client_secret_basic). Some providers need this since the allauth update in paperless-ngx 3.0.",
+              "type": ["string", "null"]
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "resources": {
+      "description": "May be null / empty: the chart then falls back to its default requests and computed limits (issue #99) instead of rendering a container without resource accounting.",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "limitFactor": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "requests": {
+          "$ref": "#/definitions/resourceList"
+        },
+        "limits": {
+          "$ref": "#/definitions/resourceList"
+        }
+      }
+    },
+    "resourceList": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "cpu": {
+          "type": ["string", "number", "null"]
+        },
+        "memory": {
+          "type": ["string", "number", "null"]
+        },
+        "ephemeral-storage": {
+          "type": ["string", "number", "null"]
+        },
+        "ephemeralStorage": {
+          "type": ["string", "number", "null"]
+        }
+      }
+    },
+    "env": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "value": {
+            "type": "string"
+          },
+          "valueFrom": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "secretKeyRef": {
+                "$ref": "#/definitions/keyRef"
+              },
+              "configMapKeyRef": {
+                "$ref": "#/definitions/keyRef"
+              }
+            }
+          }
+        }
+      }
+    },
+    "keyRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "key"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "key": {
+          "type": "string"
+        }
+      }
+    },
+    "securityContext": {
+      "description": "May be null / empty at any level: the chart then falls back to its hardening defaults (issue #99) instead of rendering an unhardened workload. For the server the pod context is consumed twice - as the pod's securityContext and by the /run-ownership init container, which chowns /run to runAsUser:runAsGroup because s6-overlay requires /run to be owned by the runtime uid.",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "pod": {
+          "description": "Merged onto the chart's pod hardening defaults and rendered as the pod's securityContext; kept open because the chart does not interpret the individual fields.",
+          "type": ["object", "null"]
+        },
+        "container": {
+          "description": "Merged onto the chart's container hardening defaults and rendered as the container's securityContext; kept open because the chart does not interpret the individual fields.",
+          "type": ["object", "null"]
+        }
+      }
+    },
+    "probe": {
+      "description": "Merged onto the chart's probe defaults and rendered as a container probe; kept open because the chart does not interpret the individual fields. May be null / empty, which means the defaults apply (issue #99) rather than the probe disappearing.",
+      "type": ["object", "null"]
+    }
+  }
+}