Skip to content

docs: say what the refresh secret protects, and stop disowning shipped modules - #353

Open
Jaro-c wants to merge 1 commit into
developfrom
docs/refresh-secret-and-scope
Open

Jaro-c wants to merge 1 commit into
developfrom
docs/refresh-secret-and-scope

Conversation

@Jaro-c

@Jaro-c Jaro-c commented Sep 7, 2026

Copy link
Copy Markdown
Member

Two pages had drifted from the code in the same direction: both describe a smaller library than the one that ships.

docs/key-management.md called refresh_secret.key the "HMAC-SHA256 key for refresh token hashing" and stopped there. Since auth/field shipped, that file is also what auth/field runs HKDF-SHA256 over to derive the AES-256-GCM column key and the blind index key, so it is the root of every encrypted column in the consumer database. The page an operator reads before touching key material never said so. It carries a "Rotating the signing key (zero downtime)" section for the Ed25519 pair and had no counterpart for this file, and six lines above the table it tells the reader to delete key files to regenerate.

docs/field.md already had the warning and linked here. The warning existed in one direction only, and the missing direction is the one the operator is standing in when they do the destructive thing: rotating a token hashing secret has an understood worst case, everyone logs in again, and under the current wiring the same action is irreversible data loss.

docs/secure-login.md section 8 listed MFA / TOTP, password-reset flows and email verification as the reader own job. auth/totp and auth/credential cover all three. The recipe page whose closing line is "authcore removes the cryptographic mistakes" was sending people to hand roll exactly that.

On the test

It guards the second class rather than the instance, and its limit is written into the test rather than left to be found later. It matches the directory name under auth/, so it would have caught "MFA / TOTP" and would not have caught "password-reset flows", which is auth/credential under a description. One of the two instances. A green run is not evidence the docs describe the current module set.

Its first run failed on a sentence that is true: "Breached-password rejection is intentionally not part of authcore" is correct and deliberate, per #133 and #118, and a plain substring match read it as a denial that auth/password exists. The matcher is token bounded now, with a hyphen counting as part of a word and a slash counting as a boundary so auth/totp still matches.

I checked it fails in the direction that matters by restoring the exact bullet that was on develop and watching it go red naming auth/totp.

This is a docs and test change, so by the release rule it is a change a consumer receives and should ride the next tag rather than being held.

Closes #345
Closes #346

…d modules

Two pages had drifted apart from the code in the same direction: they
described a smaller library than the one that ships.

docs/key-management.md called refresh_secret.key the "HMAC-SHA256 key
for refresh token hashing" and left it there. Since auth/field shipped,
that file is also the HKDF root of every column encryption key and every
blind index key, so it is the root of every encrypted column in the
consumer database. The page an operator reads before rotating key
material never said so, and it carries a rotation section for the
Ed25519 pair with no counterpart for this file. docs/field.md had the
warning; the direction that was missing is the one the operator is
standing in when they do the destructive thing.

docs/secure-login.md section 8 listed MFA / TOTP, password reset and
email verification as the reader own job. auth/totp and auth/credential
cover all three. The recipe page was sending people to hand roll the
security the module already provides.

The scope test that comes with this catches the second class rather than
the instance, and I have written its limit into the test rather than
leaving it to be discovered: it matches the directory name, so it would
have caught "MFA / TOTP" and not "password-reset flows", which is
auth/credential under a description. One of the two.

Its first run also failed on a true sentence, which is why the matcher
is token bounded now: "Breached-password rejection is intentionally not
part of authcore" is correct and deliberate (#133, #118), and a
substring match read it as a denial that auth/password exists.

I checked it fails in the direction that matters by restoring the exact
bullet that was on develop and watching it go red naming auth/totp.

Closes #345
Closes #346

Signed-off-by: Jose <75870284+Jaro-c@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant