Open balazsorban44 opened 1 month ago
vercel[bot]
commented
1 month ago 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 |
codecov[bot]
commented
1 month ago All modified and coverable lines are covered by tests :white_check_mark:
Project coverage is 67.95%. Comparing base (
2baea5e) to head (37bdc73).
:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.
☕️ 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.
Currently, we only have a
debug: booleanoption. This means that warnings will spam the console by default. Introducing alogLevel: "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 newsilentoption will silence all logs by default. You can still use theloggeroption to add your custom logger methods though.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() {}}tosession: {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.)
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
🎫 Affected issues
📌 Resources