fix(imap): AuthAdapter JSDoc drift -- remove argon2 and D1 prescription#79
Merged
fix(imap): AuthAdapter JSDoc drift -- remove argon2 and D1 prescription#79
Conversation
ssilvius
force-pushed
the
fix/imap-auth-comment-drift
branch
from
e91357d to
add0b61
Compare
The JSDoc above `AuthAdapter` said "App passwords are stored hashed (argon2) in D1 and verified here." That's wrong on two axes: 1. The IMAP server does not own credential storage or hashing. That was the original design but it was rewritten: AuthAdapter is an interface contract only, the consumer brings their own auth system. Prescribing argon2 contradicts the rewritten contract. 2. Core docs must be generic: "blob storage" not "R2", "database" not "D1". Referencing D1 by name inside the core protocol package violates the zero-vendor-dependency principle. Replaced with a proper JSDoc block that: - States the interface-only posture explicitly - Names the consumer's ownership (storage, hashing, generation, revocation) - Lists the security guarantees the IMAP server DOES enforce regardless of adapter implementation (generic failure response, rate limit, disconnect after max attempts) - Refers to the adapter lifecycle in neutral language This matches the authoritative `authentication.md` doc shipped in PR #76 and the interface-only posture in the `@rafters/mail-imap-server` quickstart.md fixed in PR #78. Verification: - pnpm --filter @rafters/mail-imap test: 313 passing - pnpm --filter @rafters/mail-imap typecheck: clean - pnpm --filter @rafters/mail-imap build: ESM + dts clean - pnpm lint: 0 warnings, 0 errors Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ssilvius
force-pushed
the
fix/imap-auth-comment-drift
branch
from
add0b61 to
572f443
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
One-line (conceptually) fix. The JSDoc block above `AuthAdapter` in `packages/imap/src/commands/auth.ts` said:
That is wrong on two axes:
This is the same drift I found in `packages/imap-server/docs/quickstart.md` and fixed in PR #78 -- except this copy is in the source code JSDoc, not a doc file. The JSDoc ships in the npm tarball's `dist/*.d.ts` files and is the authoritative reference for anyone who hovers the `AuthAdapter` type in their editor.
The fix
Replaced the 1-line wrong prescription with a proper JSDoc block that:
Verification
Scope
Single file, docblock only. No runtime behavior change. Safe to merge independently of the rest of the ship-to-npm PR stack.