Lucia v3 (#1258)

Co-authored-by: Rob Marscher <[email protected]> Co-authored-by: Howard Dean Watts <[email protected]> Co-authored-by: SkepticMystic <[email protected]> Co-authored-by: Aayush <[email protected]> Co-authored-by: Alejandro Perez Pujante <[email protected]> Co-authored-by: Corliansa Kusumah <[email protected]> Co-authored-by: Gabriel Lucena <[email protected]> Co-authored-by: Mihovil Ilakovac <[email protected]> Co-authored-by: Linus <[email protected]> Co-authored-by: Andrew Smith <[email protected]> Co-authored-by: Matt Lehrer <[email protected]> Co-authored-by: Bogdan Mardale <[email protected]> Co-authored-by: Žan Fras <[email protected]> Co-authored-by: Mr. Mendez <[email protected]> Co-authored-by: Elliot Waite <[email protected]>
lucia-auth · Jan 27, 2024 · beac8bc · beac8bc
1 parent f073be1
commit beac8bc
Show file tree

Hide file tree

Showing 528 changed files with 12,075 additions and 42,313 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -13,22 +13,20 @@ body:
       label: Package
       description: What package is affected?
       options:
-        - lucia-auth
-        - @lucia-auth/oauth
-        - @lucia-auth/tokens
-        - @lucia-auth/adapter-mongoose
+        - lucia
+        - @lucia-auth/adapter-test
+        - @lucia-auth/adapter-mongodb
         - @lucia-auth/adapter-mysql
         - @lucia-auth/adapter-postgresql
         - @lucia-auth/adapter-prisma
         - @lucia-auth/adapter-sqlite
-        - @lucia-auth/session-adapter-redis
-        - @lucia-auth/adapter-test
+        - @lucia-auth/session-drizzle
     validations:
       required: true
   - type: textarea
     id: description
     attributes:
       label: Describe the bug
-      description: Also tell us, what was the expected behavior? Reproduction is helpful for weeeird bugs!
+      description: Also tell us, what was the expected behavior? Reproduction will be super helpful!
     validations:
       required: true
diff --git a/.github/ISSUE_TEMPLATE/documentation_bug_report.yaml b/.github/ISSUE_TEMPLATE/documentation_bug_report.yaml
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml
@@ -7,6 +7,21 @@ body:
     attributes:
       value: |
         Thanks for taking the time to fill out this feature request!
+  - type: dropdown
+    id: package
+    attributes:
+      label: Package
+      options:
+        - lucia
+        - @lucia-auth/adapter-test
+        - @lucia-auth/adapter-mongodb
+        - @lucia-auth/adapter-mysql
+        - @lucia-auth/adapter-postgresql
+        - @lucia-auth/adapter-prisma
+        - @lucia-auth/adapter-sqlite
+        - @lucia-auth/session-drizzle
+    validations:
+      required: true
   - type: textarea
     id: description
     attributes:

diff --git a/.github/workflows/auri.yaml b/.github/workflows/auri.yaml
@@ -7,8 +7,6 @@ on:
 env:
   AURI_GITHUB_TOKEN: ${{secrets.AURI_GITHUB_TOKEN}}
   NODE_AUTH_TOKEN: ${{secrets.NODE_AUTH_TOKEN}}
-  CF_DEPLOY_HOOK: ${{secrets.CF_DEPLOY_HOOK}}
-  VERCEL_PREVIEW_DEPLOY_HOOK: ${{secrets.VERCEL_PREVIEW_DEPLOY_HOOK}}
 
 jobs:
   auri:

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,33 @@
+name: "Publish v3 docs"
+on:
+  push:
+    branches:
+      - v3
+
+env:
+  CLOUDFLARE_API_TOKEN: ${{secrets.CLOUDFLARE_PAGES_API_TOKEN}}
+
+jobs:
+  publish-docs:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: setup actions
+        uses: actions/checkout@v3
+      - name: setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20.5.1
+          registry-url: https://registry.npmjs.org
+      - name: install malta
+        working-directory: docs
+        run: |
+          curl -o malta.tgz -L https://github.com/pilcrowonpaper/malta/releases/latest/download/linux-amd64.tgz
+          tar -xvzf malta.tgz
+      - name: build
+        working-directory: docs
+        run: ./linux-amd64/malta build
+      - name: install wrangler
+        run: npm i -g wrangler
+      - name: deploy
+        run: wrangler pages deploy docs/dist --project-name lucia-v3 --branch main
diff --git a/.github/workflows/v2-docs.yaml b/.github/workflows/v2-docs.yaml
@@ -0,0 +1,33 @@
+name: "Publish v2 docs"
+on:
+  push:
+    branches:
+      - v2
+
+env:
+  CLOUDFLARE_API_TOKEN: ${{secrets.CLOUDFLARE_PAGES_API_TOKEN}}
+
+jobs:
+  publish-docs:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: setup actions
+        uses: actions/checkout@v3
+      - name: setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20.5.1
+          registry-url: https://registry.npmjs.org
+      - name: Install PNPM
+        run: npm i -g pnpm
+      - name: Install dependencies
+        run: pnpm i
+      - name: Build
+        working-directory: documentation
+        run: pnpm build
+      - name: Install wrangler
+        run: npm i -g wrangler
+      - name: deploy
+        working-directory: documentation
+        run: wrangler pages deploy dist --project-name lucia-v2 --branch v2
diff --git a/.prettierignore b/.prettierignore
@@ -8,18 +8,11 @@ node_modules
 !.env.example
 /.vscode
 /.auri/*.md
-/test-apps/**/.svelte-kit
-/test-apps/**/.next
-/test-apps/**/.nuxt
-/examples/**/.svelte-kit
-/examples/**/.next
-/examples/**/.nuxt
-/examples/**/.solid
-/packages/**/dist
-/documentation/dist
+
+docs/dist
+packages/*/dist
 
 # Ignore files for PNPM, NPM and YARN
 pnpm-lock.yaml
 package-lock.json
 yarn.lock
-
diff --git a/.prettierrc.json b/.prettierrc.json
@@ -1,5 +1,6 @@
 {
 	"useTabs": true,
+	"printWidth": 100,
 	"trailingComma": "none",
 	"plugins": ["prettier-plugin-tailwindcss", "prettier-plugin-astro"],
 	"overrides": [

diff --git a/README.md b/README.md
@@ -1,31 +1,23 @@
 # Lucia
 
-Lucia is a simple and flexible user and session management library that provides an
-abstraction layer between your app and your database. It's bare-bones by design, keeping
-everything easy to use and understand.
+Lucia is an auth library written in TypeScript that abstracts away the complexity of handling sessions. It works alongside your database to provide an API that's easy to use, understand, and extend.
 
-### Code sample
-
-Working with Lucia looks something like this. In the code below, you're creating a new user with an email/password method, creating a new session, and creating a cookie that you can set to the user.
+- No more endless configuration and callbacks
+- Fully typed
+- Works in any runtime - Node.js, Bun, Deno, Cloudflare Workers
+- Extensive database support out of the box
 
 ```ts
-const user = await auth.createUser({
-	key: {
-		providerId: "email",
-		providerUserId: email,
-		password
-	},
-	attributes: {
-		email
-	}
-});
-const session = await auth.createSession({
-	userId: user.userId,
-	attributes: {}
-});
-const sessionCookie = auth.createSessionCookie(session);
+import { Lucia } from "lucia";
+
+const lucia = new Lucia(new Adapter(db));
+
+const session = await lucia.createSession(userId, {});
+await lucia.validateSession(session.id);
 ```
 
+Lucia is an open source library released under the MIT license, with the help of [100+ contributors](https://github.com/lucia-auth/lucia/graphs/contributors)!
+
 ## Resources
 
 **[Documentation](https://lucia-auth.com)**
@@ -45,9 +37,3 @@ npm i lucia
 pnpm add lucia
 yarn add lucia
 ```
-
-## Attributions
-
-This project would not have been possible without our contributors, thank you!
-
-Logo by [@dawidmachon](https://github.com/dawidmachon), licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+dist
+.DS_Store
diff --git a/docs/malta.config.json b/docs/malta.config.json
@@ -0,0 +1,56 @@
+{
+	"name": "Lucia",
+	"description": "Lucia is an open source auth library that abstracts away the complexity of handling sessions.",
+	"domain": "https://v3.lucia-auth.com",
+	"twitter": "@lucia_auth",
+	"sidebar": [
+		{
+			"title": "Start here",
+			"pages": [
+				["Getting-started", "/getting-started"],
+				["Database", "/database"],
+				["Upgrade to v3", "/upgrade-v3"],
+				["v2 documentation", "https://v2.lucia-auth.com"]
+			]
+		},
+		{
+			"title": "Tutorials",
+			"pages": [
+				["GitHub OAuth", "/tutorials/github-oauth"],
+				["Username and password", "/tutorials/username-and-password"]
+			]
+		},
+		{
+			"title": "Basics",
+			"pages": [
+				["Sessions", "/basics/sessions"],
+				["Users", "/basics/users"],
+				["Configuration", "/basics/configuration"]
+			]
+		},
+		{
+			"title": "Guides",
+			"pages": [
+				["Validate session cookies", "/guides/validate-session-cookies"],
+				["Validate bearer tokens", "/guides/validate-bearer-tokens"],
+				["OAuth", "/guides/oauth"],
+				["Email and password", "/guides/email-and-password"],
+				["Troubleshooting", "/guides/troubleshooting"],
+				["Passkeys", "/guides/passkeys"],
+				["Improving sessions", "/guides/improving-sessions"]
+			]
+		},
+		{
+			"title": "API reference",
+			"pages": [["lucia", "/reference/main", "code"]]
+		},
+		{
+			"title": "Community",
+			"pages": [
+				["Discord", "https://discord.com/invite/PwrK3kpVR3"],
+				["GitHub", "https://github.com/lucia-auth/lucia"],
+				["Twitter", "https://twitter.com/lucia_auth"]
+			]
+		}
+	]
+}
diff --git a/docs/pages/basics/configuration.md b/docs/pages/basics/configuration.md
@@ -0,0 +1,104 @@
+---
+title: "Configuration"
+---
+
+# Configuration
+
+This page shows all the options for [`Lucia`](/reference/main/Lucia) to configure Lucia.
+
+```ts
+interface Options {
+	sessionExpiresIn?: TimeSpan;
+	sessionCookie?: SessionCookieOptions;
+	getSessionAttributes?: (
+		databaseSessionAttributes: DatabaseSessionAttributes
+	) => _SessionAttributes;
+	getUserAttributes?: (databaseUserAttributes: DatabaseUserAttributes) => _UserAttributes;
+}
+```
+
+## `sessionExpiresIn`
+
+Configures how long a session stays valid for inactive users. Session expirations are automatically extended for active users. Also see [`TimeSpan`](/reference/main/TimeSpan).
+
+```ts
+import { Lucia, TimeSpan } from "lucia";
+
+const lucia = new Lucia(adapter, {
+	sessionExpiresIn: new TimeSpan(2, "w")
+});
+```
+
+## `sessionCookie`
+
+Configures the session cookie.
+
+```ts
+import { Lucia } from "lucia";
+
+const lucia = new Lucia(adapter, {
+	sessionCookie: {
+		name: "session",
+		expires: false, // session cookies have very long lifespan (2 years)
+		attributes: {
+			secure: true,
+			sameSite: "strict",
+			domain: "example.com"
+		}
+	}
+});
+```
+
+## `getSessionAttributes()`
+
+Transforms database session attributes, which is typed as `DatabaseSessionAttributes`. The returned object is added to the `Session` object.
+
+```ts
+import { Lucia } from "lucia";
+
+const lucia = new Lucia(adapter, {
+	getSessionAttributes: (attributes) => {
+		return {
+			country: attributes.country
+		};
+	}
+});
+
+declare module "lucia" {
+	interface Register {
+		Lucia: typeof lucia;
+		DatabaseSessionAttributes: DatabaseSessionAttributes;
+	}
+}
+
+interface DatabaseSessionAttributes {
+	country: string;
+}
+```
+
+## `getUserAttributes()`
+
+Transforms database user attributes, which is typed as `DatabaseUserAttributes`. The returned object is added to the `User` object.
+
+```ts
+import { Lucia } from "lucia";
+
+const lucia = new Lucia(adapter, {
+	getUserAttributes: (attributes) => {
+		return {
+			username: attributes.username
+		};
+	}
+});
+
+declare module "lucia" {
+	interface Register {
+		Lucia: typeof lucia;
+		DatabaseUserAttributes: DatabaseUserAttributes;
+	}
+}
+
+interface DatabaseUserAttributes {
+	username: string;
+}
+```