feat(security): verify argon2id password hashing via occ selftest (NSW-957)

[printminion-co]

Adds occ ncw_tools:security:selftest, which verifies that this instance hashes passwords with argon2id and emits a structured evidence artifact for C5 control PSS-07 (Credential Storage Security).

Ticket: NSW-957. Supersedes the shell-based approach in nextcloud-workspace/images!114.

Why it lives here rather than in a shell script

The original proposal verified the algorithm from a standalone PHP script in the nc-manager container, outside the Nextcloud runtime. That is what caused its central defect: it compared oc_users.password against the literal prefix $argon2id$, but Hasher::hash() returns 3 . '|' . password_hash(...) and Database::createUser() stores exactly that — so the column holds 3|$argon2id$v=19$… and the comparison could never match. The self-test reported a permanent FAIL on a correctly configured instance.

Inside the app we get IHasher (the authority on the algorithm), IConfig (the effective merged config, not one file), IDBConnection (correct driver, table prefix and replica handling instead of a raw PDO DSN hardcoded to MySQL) — and unit tests, which is what actually prevents a recurrence.

What it checks

1. Configured algorithm — hashes a random probe through IHasher and classifies the result. This is the algorithm every new password receives.
2. Stored distribution — counts the algorithms actually present in oc_users, so the evidence attests the real user population rather than a fixture. Passes when every row is argon2id or empty (empty = SSO-only accounts, not a downgrade).
3. Hardening config — asserts hashing_default_password is false (the one system value that silently downgrades Hasher to PASSWORD_DEFAULT), bruteforce and rate-limit protection enabled, overwriteprotocol https, and passwordsalt/secret present. Reports the effective argon2 cost parameters as evidence.
4. --round-trip (opt-in) — the ticket's literal scenario: create a disposable user, read its stored hash back from the database, classify it, delete it. Off by default so the command is safe against a production instance; enabled via Helm only on the dedicated self-test instance, which has no live users. The test user never receives an email address.

Output

--output=json writes the artifact to stdout; the same artifact is logged through LoggerInterface, which reaches Kibana via log_type=errorlog. Exit 0 = PASS, 1 = FAIL, 2 = usage error.

stdout is JSON-only — all diagnostics go to stderr — because nc-manager/bin/selftest.sh pipes it into jq. A FAIL still prints the complete artifact before exiting 1, since that is exactly the case the evidence needs to capture.

No field ever carries hash material, a salt, or a secret value. Only algorithm names, counts, booleans and cost parameters. The secret checks are keyed passwordsalt_present / secret_present so actual: true cannot be misread as a value. There is a unit test for this invariant.

The artifact is a published contract

The shape is consumed across four repos — nc-manager/bin/send-report.sh reads it with jq and forwards it to the report endpoint — so it ships as a JSON Schema, docs/security-selftest.schema.json (draft 2020-12), and both test suites validate real artifacts against it. The schema cannot describe something the command no longer emits, and a consumer can validate what it receives instead of trusting the sender.

It pins more than field types. The verdict invariants are where the evidence value is:

• a top-level PASS requires both sections to have passed
• a passing password_hashing requires argon2id, no round-trip failure, and not one surveyed row outside the tolerated argon2id/empty buckets
• a SKIPPED round trip must report nothing, and one that passed must show argon2id with cleaned_up: true
• stored_distribution keys are restricted to the algorithms HashAlgorithm can report, so a typo cannot invent a bucket
• additionalProperties is false throughout, so an accidental new field is a violation rather than a silent addition to a frozen contract

Checked against the artifact a real instance produces and against fifteen mutations of it — a PASS claimed over a failing section, a PASS alongside bcrypt rows, a SKIPPED round trip carrying a cleaned_up flag, parameters as [], a bogus distribution bucket, a timestamp without its Z — each of which the schema rejects. A unit test asserts the schema's pinned schema_version still matches SecuritySelfTest::SCHEMA_VERSION.

Two decisions worth a reviewer's attention

Hashes are classified by algorithm marker, not by password_get_info(). PHP registers the argon2 handlers under the same condition that defines the constants (HAVE_ARGON2LIB || HAVE_LIBSODIUM), so on a build without argon2 support password_get_info() reports unknown for a perfectly good $argon2id$ hash. That is precisely the build this self-test exists to catch, and it is the build on which stored_distribution has to stay truthful: those rows really are argon2id, and reporting them as unknown would blur the finding instead of sharpening it. Marker matching is what upstream's own handlers do anyway. parametersFromStoredHash() is the one place that still needs the registered handler and degrades to an empty map without it, which is sound because the cost parameters are evidence and never asserted.

security_config.parameters is a JSON object even when empty. An empty PHP array encodes as [], not {}, so jq '.security_config.parameters.memory_cost' would error with "Cannot index array with memory_cost" rather than return null — the field would change type with its contents. The cast happens in the service rather than at an encode boundary, because both evidence channels serialise the artifact and a cast in the command's JSON branch would have fixed stdout while leaving the Kibana document with []. No schema_version bump: it narrows the field to the object the documentation always claimed.

Verified

Gate	Before	After
test:unit	36 tests / 90 assertions	106 / 260
test:integration	3 / 4	9 / 31 (sqlite)
psalm	clean	clean, 100% inference
cs:check	0 of 31	0 of 37
reuse lint	compliant	compliant

Every commit was verified against each gate individually — lint, cs:check, psalm, test:unit and test:integration — not just the tip, so a bisect never lands on a red commit.

Against a real instance, configured_algorithm reports argon2id from a 3|$argon2id$… stored hash — the case the shell version got wrong — and --round-trip returns stored_algorithm: argon2id, cleaned_up: true with no leftover user. Flipping hashing_default_password to true is caught three ways: configured_algorithm: bcrypt, round_trip.stored_algorithm: bcrypt, and parameters switching from the argon2 triple to {"cost":10}.

Notes for review

• OC\Core\Command\Base and four Symfony Console interfaces are stubbed for psalm under tests/psalm-stubs/, deliberately not under tests/stubs/: that directory is in the autoload-dev classmap, and lib/AppInfo/Application.php requires vendor/autoload.php at runtime, so a dev-mode composer install put the Symfony stubs into the live classmap where they shadowed the real classes in 3rdparty/ and fataled every occ command. Release builds (composer install --no-dev -o) were never affected.
• composer.json / composer.lock add opis/json-schema to require-dev for the artifact validation. Dev-only, so it is absent from release builds.
• Two psalm.xml suppressions were added for the command class and constructors, mirroring the existing entries for Application — findUnusedCode cannot see registrations in appinfo/info.xml.
• security_config.parameters is read from password_get_info() on the probe hash rather than from IConfig, because Hasher clamps the configured values to the algorithm minimums. The reported values are therefore the effective ones.
• Kibana caveat: Nextcloud's log writer serialises nested context arrays into JSON strings. data.result, data.schema_version and data.timestamp are directly queryable; data.instance, data.password_hashing and data.security_config arrive as strings needing a parse. Consumers wanting structured nested fields should use the stdout artifact. Documented in docs/security-selftest.md.
• MySQL was not exercised locally (the dev container has pdo_sqlite / pdo_pgsql only); the phpunit-mysql workflow covers it. The survey uses IQueryBuilder with the unprefixed table name users, so no dialect-specific SQL is involved.

Follow-ups in other repos

• nextcloud-workspace/images!117 — selftest.sh invokes this command and pipes the artifact into send-report.sh. Supersedes !114.
• nextcloud-workspace/helm!150 — a dedicated nextcloud-selftest Job (post-install/post-upgrade at hook weight 10, after nextcloud-manager), its values and gating, and a concept doc in doc/selftest.md. Supersedes !146.
• ncw-server — submodule pointer bump, after this merges.

[Copilot]

🟡 Changes recommended

The hash-version prefix parsing is too permissive (can misclassify invalid prefixed values), and the JSON artifact output path can still short-circuit without emitting an artifact on encoding failure.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds an occ ncw_tools:security:selftest command plus supporting service logic, documentation, and tests to verify that password hashing is argon2id and to emit a structured evidence artifact for C5 control PSS-07 within the real Nextcloud runtime.

Changes:

• Introduces SecuritySelfTest service + SecuritySelfTest occ command that surveys stored hashes, verifies hardening config, and optionally performs a round-trip probe user check.
• Adds HashAlgorithm classifier to correctly interpret Nextcloud’s version-prefixed stored hashes and extract effective cost parameters.
• Adds comprehensive unit + integration test coverage, documentation, and psalm stubs/suppressions needed for static analysis.

File summaries

File	Description
lib/Command/SecuritySelfTest.php	New occ command wrapper that validates options, emits artifact to stdout, and logs structured evidence.
lib/Security/SecuritySelfTest.php	New service that generates the evidence artifact: hasher probe, stored distribution survey, hardening checks, optional round-trip.
lib/Security/HashAlgorithm.php	New classifier for Nextcloud’s stored password hash formats (version-prefixed + legacy) and parameter extraction.
tests/unit/Security/SecuritySelfTestTest.php	Unit tests for artifact shape, pass/fail conditions, distribution counting, and round-trip behavior/invariants.
tests/unit/Security/HashAlgorithmTest.php	Unit tests for hash classification and parameter extraction, including regression cases for version prefixes.
tests/integration/SecuritySelfTestIntegrationTest.php	Integration tests exercising the real DB/user pipeline, including round-trip creation/deletion and “no hash material” invariant.
docs/security-selftest.md	User/operator documentation for the command, artifact schema, failure modes, and Kibana caveats.
docs/README.md	Documentation index updated to include the new security self-test command docs.
appinfo/info.xml	Registers the new occ command with Nextcloud.
psalm.xml	Adds psalm stub directory and suppressions for DI-registered classes/constructors.
tests/psalm-stubs/OC/Core/Command/Base.php	Psalm stub for Nextcloud private OC\Core\Command\Base used by the command.
tests/psalm-stubs/Symfony/Component/Console/Input/InputInterface.php	Psalm stub for Symfony Console input interface used by the command.
tests/psalm-stubs/Symfony/Component/Console/Input/InputOption.php	Psalm stub for Symfony Console InputOption constants used by the command.
tests/psalm-stubs/Symfony/Component/Console/Output/OutputInterface.php	Psalm stub for Symfony Console output interface used by the command.
tests/psalm-stubs/Symfony/Component/Console/Output/ConsoleOutputInterface.php	Psalm stub for ConsoleOutputInterface used to separate stderr from stdout.
REUSE.toml	Adds the new documentation file to REUSE coverage.

Review details

• Files reviewed: 16/16 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[printminion-co]

Good catch — fixed in 563d951, though one level deeper than suggested.

JSON_INVALID_UTF8_SUBSTITUTE alone would have fixed stdout while leaving the other evidence channel exposed: the same report goes to LoggerInterface, and the log writer encodes that context as JSON too, so invalid UTF-8 would drop the Kibana line — which is the channel NSW-957 actually requires. So the sanitising now happens where the untrusted bytes are read (SecuritySelfTest::fromEnvironment(), the source of INSTANCE_NAME / NAMESPACE / ENVIRONMENT), which protects both channels and keeps them consistent. The flag stays on the command as a backstop.

Regression test: testInvalidUtf8InTheEnvironmentStillYieldsAnEncodableArtifact. Confirmed it fails without the fix (Failed asserting that false is true on mb_check_encoding) and passes with it.

[printminion-co]

Deliberate, and I am keeping the behaviour — but you are right that it was undocumented and untested, so 563d951 fixes that.

The loose (int) cast mirrors upstream exactly. OC\Security\Hasher::splitHash():

$explodedString = explode("|", $prefixedHash, 2);
if (\count($explodedString) === 2) {
    if ((int)$explodedString[0] > 0) {

So Nextcloud itself reads 3foo|<hash> as version 3 and verifies the remainder as argon2id — validate() accepts it too. This command produces audit evidence about what the instance actually does, so classifying that value as argon2id is the truthful answer. Tightening to digits-only would report unknown for a value Nextcloud verifies happily, i.e. invent an anomaly rather than report one.

On "as described in the docs/tests": the doc says the classifier splits the prefix "mirroring the private Hasher::splitHash()", which is what it does — it does not claim a digits-only rule. No contradiction, though the intent was too implicit.

A malformed prefix still does not launder a malformed hash: the remainder goes through password_get_info(), so 3foo|nonsense is unknown.

Added: an explanatory comment on stripVersionPrefix(), and four cases pinning the behaviour — 3foo|<argon2id> and " 3|"<argon2id> classify as argon2id, 3foo|nonsense and -1|<argon2id> as unknown.

[Copilot]

🟡 Changes recommended

The new HashAlgorithmTest assumes Argon2 constants are always available and can fatally error on PHP builds without Argon2 support, even though the feature explicitly needs to handle that scenario.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

tests/unit/Security/HashAlgorithmTest.php:120

• This test uses PASSWORD_ARGON2ID directly; if argon2id support is not compiled into PHP, the constant is undefined and the test fatals. Consider skipping the test when argon2id is unavailable and asserting password_hash() produced a string before building the stored value.

	public function testBareArgon2idPrefixIsNotHowNextcloudStoresHashes(): void {
		// Regression guard for the defect this class replaces: a shell check that
		// compared the stored value against the literal '$argon2id$' prefix.
		$stored = '3|' . password_hash('probe', PASSWORD_ARGON2ID);

		$this->assertStringStartsNotWith('$argon2id$', $stored);
		$this->assertStringStartsWith('3|$argon2id$', $stored);
		$this->assertSame(HashAlgorithm::ARGON2ID, HashAlgorithm::fromStoredHash($stored));

tests/unit/Security/HashAlgorithmTest.php:129

• This test uses PASSWORD_ARGON2ID directly; on PHP builds without Argon2 support it will fatal. Skip when argon2id is unavailable and assert password_hash() returns a string before concatenation.

	public function testParametersFromArgon2idHash(): void {
		$stored = '3|' . password_hash('probe', PASSWORD_ARGON2ID, [
			'memory_cost' => 65536,
			'time_cost' => 4,
			'threads' => 1,
		]);

tests/unit/Security/HashAlgorithmTest.php:162

• This test uses PASSWORD_ARGON2ID directly; on PHP builds without Argon2 support it will fatal. Skip when argon2id is unavailable and assert password_hash() returns a string before passing it into parametersFromStoredHash().

	public function testParametersNeverCarryHashMaterial(): void {
		$stored = '3|' . password_hash('probe', PASSWORD_ARGON2ID);

		foreach (HashAlgorithm::parametersFromStoredHash($stored) as $name => $value) {
			$this->assertIsString($name);
			$this->assertIsInt($value);
		}
	}

• Files reviewed: 16/16 changed files
• Comments generated: 1
• Review effort level: Lite

[printminion-co]

Valid, and it led somewhere bigger than the test file — fixed in 2180b7b.

Guarding the four password_hash() call sites alone would not have been enough. PHP registers the argon2 password_get_info() handlers under the same condition that defines the constants (HAVE_ARGON2LIB || HAVE_LIBSODIUM), so on a build without argon2 support password_get_info() reports unknown for a perfectly good $argon2id$ hash. fromStoredHash() classified purely from that call — so on such a build every stored argon2id row would have landed in the unknown bucket of stored_distribution, blurring the finding on exactly the build this self-test exists to catch. The captured fixtures (REAL_STORED_ARGON2ID and friends) would have started failing there too, and those are not among the lines you flagged.

So the classifier now matches on the algorithm marker instead. That is what upstream's own handlers do — argon2 accepts any $argon2id$… string, bcrypt any 60 character $2y… one — and it is identical for every case the suite already pinned. Two deliberate changes where nothing was pinned before, both now covered by tests:

• a prefixed $2a/$2b bcrypt hash classifies as bcrypt rather than unknown, which is what the unprefixed branch has always said about those revisions
• the length check stays, so 1|$2y$10$tooshort is still unknown

parametersFromStoredHash() keeps password_get_info(), since only the registered handler can read the cost fields. It degrades to an empty array without argon2 support, which is sound: the artifact reports parameters as evidence and never asserts on them, and the configured-algorithm check is what turns such a build into a FAIL. Documented on the method and in the doc's failure-mode table.

On the tests themselves:

• the B1 regression guard now uses the captured fixture rather than password_hash(), so the one test that must never be skipped never is
• only the freshly-hashed argon2 provider cases and the argon2 parameters test are conditional, behind a single defined('PASSWORD_ARGON2ID') helper
• verified by forcing that helper to false: 35 tests, 1 skipped, 0 failures, argon2 classification still covered by the fixtures

One more thing this turned up: testParametersFromArgon2idHash asserted the PHP defaults 65536/4/1. password_get_info() seeds its result with those very defaults and only overwrites them when it can parse the hash ($argon2id$garbage reports 65536/4/1 too), so that assertion held even if parsing were broken. It now uses 32768/3/1.

The second half of the note does not apply: password_hash() cannot return a non-string on PHP 8 — it throws — and composer requires ^8.1.

[Copilot]

🔵 Needs a closer look

The integration test registers a global event listener in setUp() without unregistering it, which can accumulate across tests and create avoidable flakiness/memory leaks in the integration suite.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

tests/integration/SecuritySelfTestIntegrationTest.php:52

• The integration test registers a UserCreatedEvent listener in setUp() but never unregisters it. Because the event dispatcher is shared, this can accumulate listeners across tests and keep old test instances alive, causing memory leaks and potentially surprising side effects in longer integration runs.
  tests/psalm-stubs/OC/Core/Command/Base.php:33
• The psalm stub for OC\Core\Command\Base declares configure() without a return type, but subclasses in this repo override it as configure(): void. Even though this is only a stub, keeping signatures consistent avoids confusing static analysis and mirrors the real Symfony/Nextcloud contract more accurately.

• Files reviewed: 16/16 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The changes are cohesive, well-tested (unit + integration), and the security/evidence invariants described in the PR are concretely enforced by automated tests.

Review details

• Files reviewed: 16/16 changed files
• Comments generated: 0 new
• Review effort level: Lite