feat: clean up public APIs

[balazsorban44]

☕️ Reasoning

Over time, I've come to realize that some people might think Auth.js APIs are complicated because of poor naming/conventions. This PR aims to address some of these flows by improving the public-facing APIs in a way that better defined the intent. It ships some default behavior changes to address common issues.

1. Logging:

Currently, we only have a debug: boolean option. This means that warnings will spam the console by default. Introducing a logLevel: "verbose" | "warn" | "error" | "silent" option, by "error" being the new default should result in less noise (eg. warnings will be off by default from now on), but the flexibility to provide more insights into what's happening internally remains. If you wish to disable all logs, the new silent option will silence all logs by default. You can still use the logger option to add your custom logger methods though.

2. JWT session strategy:

This name was chosen poorly. Let me explain. By default, Auth.js does not require a database to operate. This is because we want the entry level be low, but still provide the basic auth functionality. For this reason, Auth.js sessions are persisted in a cookie. However, to protect the session information, we only want the Auth.js backend to be able to read the cookies' contents. We are utilizing JWTs for this purpose. Whenever a session is created or modified, the cookie content is decrypted/verified, using the Auth.js secret (AUTH_SECRET) as the seed for the encryption key. This way, we always know if the content was actually issued by us. BUT. There is absolutely no reason for anyone to rely on JWTs for this purpose. To Better reflect this, the new preferred APIs to seal/unseal the session contents will be renamed from jwt: {encode() {}, decode() {}} to session: {seal() {}, unseal() {}} to reflect this. Note, that we will continue using an encrypted JWT as the sealing method, it's just the API name that changes.

In follow-up PRs, I plan to pull the APIs for database and JWT sessions even closer. (Think CookieAdapter, with the same structured data a database providers, but without needing to set up an actual database. The caveat of course: this data won't persist across login/logouts.)

3. Misc:

I am adding more inline documentation where I can, better explaining our choices to be more transparent and giving usage examples. This will also be lifted into the https://authjs.dev documentation eventually.

🧢 Checklist

• Documentation
• Tests
• Ready to be merged

🎫 Affected issues

📌 Resources

• Security guidelines
• Contributing guidelines
• Code of conduct
• Contributing to Open Source

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
auth-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 20, 2024 11:11pm

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
next-auth-docs	⬜️ Ignored (Inspect)	Visit Preview		Oct 20, 2024 11:11pm
proxy	⬜️ Ignored (Inspect)	Visit Preview		Oct 20, 2024 11:11pm

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 67.95%. Comparing base (2baea5e) to head (37bdc73).

Additional details and impacted files

@@             Coverage Diff             @@
##             main   #12075       +/-   ##
===========================================
+ Coverage   39.22%   67.95%   +28.73%     
===========================================
  Files         191      130       -61     
  Lines       29928     7227    -22701     
  Branches     1297      663      -634     
===========================================
- Hits        11738     4911     -6827     
+ Misses      18190     2316    -15874     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.