Lucia

https://lucia-auth.com/
Admin
Lucia is an open source project providing resources on implementing authentication using JavaScript...
Tokens:15,515
Snippets:159
Trust Score:8.2
Update:4 months ago
Show doc for...
Tokens:
Raw
### Clone Example Project

Source: https://lucia-auth.com/tutorials/github-oauth/nextjs

Clone the example Next.js GitHub OAuth project to get started.

```bash
git clone git@github.com:lucia-auth/example-nextjs-github-oauth.git

```

--------------------------------

### Clone Example Project

Source: https://lucia-auth.com/tutorials/google-oauth/sveltekit

Clone the example SvelteKit Google OAuth project locally.

```bash
git clone git@github.com:lucia-auth/example-sveltekit-google-oauth.git
```

--------------------------------

### Clone Example Project

Source: https://lucia-auth.com/tutorials/google-oauth/nextjs

Clone the example Next.js Google OAuth project locally.

```bash
git clone git@github.com:lucia-auth/example-nextjs-google-oauth.git

```

--------------------------------

### Clone Example Project

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Clone the example Astro and GitHub OAuth project locally.

```bash
git clone git@github.com:lucia-auth/example-astro-github-oauth.git
```

--------------------------------

### Clone Example Project

Source: https://lucia-auth.com/tutorials/google-oauth/astro

Clone the example Astro project locally to follow along with the tutorial.

```bash
git clone git@github.com:lucia-auth/example-astro-google-oauth.git
```

--------------------------------

### JavaScript Example Usage (Redis)

Source: https://lucia-auth.com/rate-limit/token-bucket

Example of how to instantiate and use the Redis-based TokenBucketRateLimit class.

```javascript
// Bucket that has 10 tokens max and refills at a rate of 30 seconds/token
const ratelimit = new TokenBucketRateLimit<string>("ip", 5, 30);
const valid = await ratelimit.consume(ip, 1);
if (!valid) {
	throw new Error("Too many requests");
}

```

--------------------------------

### Install Arctic

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Install the Arctic library, a lightweight OAuth client, using npm.

```bash
npm install arctic
```

--------------------------------

### Clone Example Project

Source: https://lucia-auth.com/tutorials/github-oauth/sveltekit

Clone the example SvelteKit GitHub OAuth project locally to follow along or experiment.

```bash
git clone git@github.com:lucia-auth/example-sveltekit-github-oauth.git

```

--------------------------------

### JavaScript Example Usage (Memory Storage)

Source: https://lucia-auth.com/rate-limit/token-bucket

Example of how to instantiate and use the memory-based TokenBucketRateLimit class.

```javascript
// Bucket that has 10 tokens max and refills at a rate of 30 seconds/token
const ratelimit = new TokenBucketRateLimit<string>(5, 30);
const valid = ratelimit.consume(ip, 1);
if (!valid) {
	throw new Error("Too many requests");
}

```

--------------------------------

### Install Arctic Package

Source: https://lucia-auth.com/tutorials/github-oauth/nextjs

Install the Arctic library, a lightweight OAuth client, using npm.

```bash
npm install arctic

```

--------------------------------

### SvelteKit Directory Structure Example

Source: https://lucia-auth.com/sessions/frameworks/sveltekit

Illustrates a typical SvelteKit directory structure where layout server load functions might be bypassed during navigation. This highlights the need for per-request validation.

```sveltekit
routes/
    +layout.server.ts
    +page.svelte
    foo/
        +page.svelte

```

--------------------------------

### Get Current Session in Next.js Page

Source: https://lucia-auth.com/tutorials/google-oauth/nextjs

This example demonstrates how to fetch the current user's session data using `getCurrentSession()` within a Next.js page component. If no session is found, the user is redirected to the login page.

```typescript
import { redirect } from "next/navigation";
import { getCurrentSession } from "@/lib/session";

export default async function Page() {
	const { user } = await getCurrentSession();
	if (user === null) {
		return redirect("/login");
	}
	return <h1>Hi, {user.name}!</h1>;
}

```

--------------------------------

### Initialize Google Provider with Arctic

Source: https://lucia-auth.com/tutorials/google-oauth/astro

Initialize the Google OAuth provider using your client ID, secret, and redirect URI. This setup is crucial for initiating the OAuth flow.

```typescript
import { Google } from "arctic";

export const google = new Google(
	import.meta.env.GOOGLE_CLIENT_ID,
	import.meta.env.GOOGLE_CLIENT_SECRET,
	"http://localhost:4321/login/google/callback"
);
```

--------------------------------

### Example JWT Payload Structure

Source: https://lucia-auth.com/sessions/stateless-tokens

This shows the typical structure of a stateless token's body, including session details and timestamps.

```json
{
	"session": {
		"id": "SESSION_ID",
		"created_at": 946684800 // unix (seconds)
	},
	iat": 946684800,
	"exp": 946684860
}

```

--------------------------------

### Setting Cookies in Server Components (Error Example)

Source: https://lucia-auth.com/sessions/frameworks/nextjs

Demonstrates an incorrect way to set cookies within a Next.js server component, which will result in an error. Cookies should not be set directly using `cookies()` in server components.

```typescript
import { cookies } from "next/headers";

export default function Page() {
	const cookieStore = await cookies();
	cookieStore.set("message", "hello");
	// ...
}


```

--------------------------------

### Handle Google OAuth Callback

Source: https://lucia-auth.com/tutorials/google-oauth/sveltekit

This route handles the callback from Google after user authorization. It validates the state and authorization code, exchanges it for tokens, decodes the ID token to get user information, checks for an existing user, creates a new user if necessary, and finally establishes a new session.

```typescript
// routes/login/google/callback/+server.ts
import { generateSessionToken, createSession, setSessionTokenCookie } from "$lib/server/session";
import { google } from "$lib/server/oauth";
import { decodeIdToken } from "arctic";

import type { RequestEvent } from "@sveltejs/kit";
import type { OAuth2Tokens } from "arctic";

export async function GET(event: RequestEvent): Promise<Response> {
	const code = event.url.searchParams.get("code");
	const state = event.url.searchParams.get("state");
	const storedState = event.cookies.get("google_oauth_state") ?? null;
	const codeVerifier = event.cookies.get("google_code_verifier") ?? null;
	if (code === null || state === null || storedState === null || codeVerifier === null) {
		return new Response(null, {
			status: 400
		});
	}
	if (state !== storedState) {
		return new Response(null, {
			status: 400
		});
	}

	let tokens: OAuth2Tokens;
	try {
		tokens = await google.validateAuthorizationCode(code, codeVerifier);
	} catch (e) {
		// Invalid code or client credentials
		return new Response(null, {
			status: 400
		});
	}
	const claims = decodeIdToken(tokens.idToken());
	const googleUserId = claims.sub;
	const username = claims.name;

	// TODO: Replace this with your own DB query.
	const existingUser = await getUserFromGoogleId(googleUserId);

	if (existingUser !== null) {
		const sessionToken = generateSessionToken();
		const session = await createSession(sessionToken, existingUser.id);
		setSessionTokenCookie(event, sessionToken, session.expiresAt);
		return new Response(null, {
			status: 302,
			headers: {
				Location: "/"
			}
		});
	}

	// TODO: Replace this with your own DB query.
	const user = await createUser(googleUserId, username);

	const sessionToken = generateSessionToken();
	const session = await createSession(sessionToken, user.id);
	setSessionTokenCookie(event, sessionToken, session.expiresAt);
	return new Response(null, {
		status: 302,
		headers: {
			Location: "/"
		}
	});
}

```

--------------------------------

### Set-Cookie Header for Session Token

Source: https://lucia-auth.com/sessions/basic

Example of a Set-Cookie header for storing a session token. It includes HttpOnly, Secure, and SameSite attributes for enhanced security.

```http
Set-Cookie: session_token=SESSION_TOKEN; Max-Age=86400; HttpOnly; Secure; Path=/; SameSite=Lax

```

--------------------------------

### Get Current User in Astro

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Access the authenticated user's information from Astro.locals if session middleware is implemented.

```typescript
if (Astro.locals.user === null) {
	return Astro.redirect("/login");
}

const user = Astro.locals.user;
```

--------------------------------

### Sign Out User in Next.js

Source: https://lucia-auth.com/tutorials/github-oauth/nextjs

Implement a sign-out functionality by invalidating the user's session and deleting the session cookie. This example uses a server action for the logout process.

```typescript
import { getCurrentSession, invalidateSession, deleteSessionTokenCookie } from "@/lib/session";
import { redirect } from "next/navigation";
import { cookies } from "next/headers";

export default async function Page() {
	return (
		<form action={logout}>
			<button>Sign out</button>
		</form>
	);
}

async function logout(): Promise<ActionResult> {
	"use server";
	const { session } = await getCurrentSession();
	if (!session) {
		return {
			error: "Unauthorized"
		};
	}

	await invalidateSession(session.id);
	await deleteSessionTokenCookie();
	return redirect("/login");
}

interface ActionResult {
	error: string | null;
}

```

--------------------------------

### Initialize GitHub Provider with Arctic

Source: https://lucia-auth.com/tutorials/github-oauth/nextjs

Initialize the GitHub OAuth provider with your client ID and secret.

```typescript
import { GitHub } from "arctic";

export const github = new GitHub(
	process.env.GITHUB_CLIENT_ID,
	process.env.GITHUB_CLIENT_SECRET,
	null
);

```

--------------------------------

### Sign-in Page Button

Source: https://lucia-auth.com/tutorials/github-oauth/nextjs

Create a basic sign-in page with a button linking to the GitHub OAuth initiation route.

```typescript
// app/login/page.tsx
export default async function Page() {
	return (
		<>
			<h1>Sign in</h1>
			<a href="/login/github">Sign in with GitHub</a>
		</>
	);
}

```

--------------------------------

### Sign In Page Button

Source: https://lucia-auth.com/tutorials/github-oauth/sveltekit

Create a basic sign-in button on your SvelteKit page that links to the GitHub OAuth initiation route.

```svelte
<!-- routes/login/+page.svelte -->
<h1>Sign in</h1>
<a href="/login/github">Sign in with GitHub</a>

```

--------------------------------

### Sign-in Page Component

Source: https://lucia-auth.com/tutorials/google-oauth/nextjs

Create a basic sign-in page with a link to initiate Google OAuth.

```typescript
// app/login/page.tsx
export default async function Page() {
	return (
		<>
			<h1>Sign in</h1>
			<a href="/login/google">Sign in with Google</a>
		</>
	);
}

```

--------------------------------

### Sign in Page Button

Source: https://lucia-auth.com/tutorials/google-oauth/sveltekit

Create a sign-in button linking to the Google OAuth initiation route.

```svelte
<!-- routes/login/+page.svelte -->
<h1>Sign in</h1>
<a href="/login/google">Sign in with Google</a>
```

--------------------------------

### Sign In Page Button

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Create a basic sign-in page in Astro with a link to initiate the GitHub OAuth flow.

```astro
<!-- pages/login/index.astro -->
<html lang="en">
	<body>
		<h1>Sign in</h1>
		<a href="/login/github">Sign in with GitHub</a>
	</body>
</html>
```

--------------------------------

### Initialize Google Provider

Source: https://lucia-auth.com/tutorials/google-oauth/sveltekit

Initialize the Google OAuth provider with credentials and redirect URI.

```typescript
import { Google } from "arctic";
import { GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET } from "$env/static/private";

export const google = new Google(
	GOOGLE_CLIENT_ID,
	GOOGLE_CLIENT_SECRET,
	"http://localhost:5173/login/google/callback"
);
```

--------------------------------

### Initialize GitHub Provider

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Initialize the GitHub OAuth provider with your client ID and secret. Ensure environment variables are correctly loaded.

```typescript
import { GitHub } from "arctic";

export const github = new GitHub(
	import.meta.env.GITHUB_CLIENT_ID,
	import.meta.env.GITHUB_CLIENT_SECRET,
	null
);
```

--------------------------------

### Handle GitHub OAuth Callback

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Validate the callback code and state, exchange the code for tokens, fetch user profile, check/create user in DB, and establish a session.

```typescript
// pages/login/github/callback.ts
import { generateSessionToken, createSession, setSessionTokenCookie } from "@lib/session";
import { github } from "@lib/oauth";

import type { APIContext } from "astro";
import type { OAuth2Tokens } from "arctic";

export async function GET(context: APIContext): Promise<Response> {
	const code = context.url.searchParams.get("code");
	const state = context.url.searchParams.get("state");
	const storedState = context.cookies.get("github_oauth_state")?.value ?? null;
	if (code === null || state === null || storedState === null) {
		return new Response(null, {
			status: 400
		});
	}
	if (state !== storedState) {
		return new Response(null, {
			status: 400
		});
	}

	let tokens: OAuth2Tokens;
	try {
		tokens = await github.validateAuthorizationCode(code);
	} catch (e) {
		// Invalid code or client credentials
		return new Response(null, {
			status: 400
		});
	}
	const githubUserResponse = await fetch("https://api.github.com/user", {
		headers: {
			Authorization: `Bearer ${tokens.accessToken()}`
		}
	});
	const githubUser = await githubUserResponse.json();
	const githubUserId = githubUser.id;
	const githubUsername = githubUser.login;

	// TODO: Replace this with your own DB query.
	const existingUser = await getUserFromGitHubId(githubUserId);

	if (existingUser !== null) {
		const sessionToken = generateSessionToken();
		const session = await createSession(sessionToken, existingUser.id);
		setSessionTokenCookie(context, sessionToken, session.expiresAt);
		return context.redirect("/");
	}

	// TODO: Replace this with your own DB query.
	const user = await createUser(githubUserId, githubUsername);

	const sessionToken = generateSessionToken();
	const session = await createSession(sessionToken, user.id);
	setSessionTokenCookie(context, sessionToken, session.expiresAt);
	return context.redirect("/");
}
```

--------------------------------

### Initialize Google Provider

Source: https://lucia-auth.com/tutorials/google-oauth/nextjs

Initialize the Google OAuth provider with your client ID, secret, and redirect URI.

```typescript
import { Google } from "arctic";

export const google = new Google(
	process.env.GOOGLE_CLIENT_ID,
	process.env.GOOGLE_CLIENT_SECRET,
	"http://localhost:3000/login/google/callback"
);

```

--------------------------------

### Generate GitHub Authorization URL

Source: https://lucia-auth.com/tutorials/github-oauth/sveltekit

Create a SvelteKit API route to generate a state, create a GitHub authorization URL, store the state in a cookie, and redirect the user.

```typescript
// routes/login/github/+server.ts
import { generateState } from "arctic";
import { github } from "$lib/server/oauth";

import type { RequestEvent } from "@sveltejs/kit";

export async function GET(event: RequestEvent): Promise<Response> {
	const state = generateState();
	const url = github.createAuthorizationURL(state, []);

	event.cookies.set("github_oauth_state", state, {
		path: "/",
		httpOnly: true,
		maxAge: 60 * 10,
		sameSite: "lax"
	});

	return new Response(null, {
		status: 302,
		headers: {
			Location: url.toString()
		}
	});
}

```

--------------------------------

### Create Session with Token

Source: https://lucia-auth.com/sessions/basic

Creates a new session by generating a secure ID and secret, hashing the secret, and inserting the session details into the database. It returns the session object along with the generated token.

```typescript
async function createSession(dbPool: DBPool): Promise<SessionWithToken> {
	const now = new Date();

	const id = generateSecureRandomString();
	const secret = generateSecureRandomString();
	const secretHash = await hashSecret(secret);

	const token = id + "." + secret;

	const session: SessionWithToken = {
		id,
		secretHash,
		createdAt: now,
		token
	};

	await executeQuery(dbPool, "INSERT INTO session (id, secret_hash, created_at) VALUES (?, ?, ?)", [
		session.id,
		session.secretHash,
		Math.floor(session.createdAt.getTime() / 1000)
	]);

	return session;
}
```

--------------------------------

### Load Current User in SvelteKit Page

Source: https://lucia-auth.com/tutorials/google-oauth/sveltekit

This server load function retrieves the current user from locals. If no user is found, it redirects to the login page.

```typescript
// routes/+page.server.ts
import { redirect } from "@sveltejs/kit";

import type { PageServerLoad } from "./$types";

export const load: PageServerLoad = async (event) => {
	if (!event.locals.user) {
		return redirect(302, "/login");
	}

	return {
		user
	};
};

```

--------------------------------

### Handle GitHub OAuth Callback

Source: https://lucia-auth.com/tutorials/github-oauth/nextjs

Validate the callback code and state, fetch user profile, handle user creation/lookup, and set session cookies.

```typescript
// app/login/github/callback/route.ts
import { generateSessionToken, createSession, setSessionTokenCookie } from "@/lib/session";
import { github } from "@/lib/oauth";
import { cookies } from "next/headers";

import type { OAuth2Tokens } from "arctic";

export async function GET(request: Request): Promise<Response> {
	const url = new URL(request.url);
	const code = url.searchParams.get("code");
	const state = url.searchParams.get("state");
	const cookieStore = await cookies();
	const storedState = cookieStore.get("github_oauth_state")?.value ?? null;
	if (code === null || state === null || storedState === null) {
		return new Response(null, {
			status: 400
		});
	}
	if (state !== storedState) {
		return new Response(null, {
			status: 400
		});
	}

	let tokens: OAuth2Tokens;
	try {
		tokens = await github.validateAuthorizationCode(code);
	} catch (e) {
		// Invalid code or client credentials
		return new Response(null, {
			status: 400
		});
	}
	const githubUserResponse = await fetch("https://api.github.com/user", {
		headers: {
			Authorization: `Bearer ${tokens.accessToken()}`
		}
	});
	const githubUser = await githubUserResponse.json();
	const githubUserId = githubUser.id;
	const githubUsername = githubUser.login;

	// TODO: Replace this with your own DB query.
	const existingUser = await getUserFromGitHubId(githubUserId);

	if (existingUser !== null) {
		const sessionToken = generateSessionToken();
		const session = await createSession(sessionToken, existingUser.id);
		await setSessionTokenCookie(sessionToken, session.expiresAt);
		return new Response(null, {
			status: 302,
			headers: {
				Location: "/"
			}
		});
	}

	// TODO: Replace this with your own DB query.
	const user = await createUser(githubUserId, githubUsername);

	const sessionToken = generateSessionToken();
	const session = await createSession(sessionToken, user.id);
	await setSessionTokenCookie(sessionToken, session.expiresAt);
	return new Response(null, {
		status: 302,
		headers: {
			Location: "/"
		}
	});
}

```

--------------------------------

### Create and Validate Session JWT

Source: https://lucia-auth.com/sessions/stateless-tokens

Demonstrates the creation of a session JWT and the subsequent validation process, including fallback to session tokens if the JWT is invalid.

```typescript
const session = await createSession();
const sessionJWT = await createSessionJWT(session);


```

```typescript
let sessionToken: string;
let sessionJWT: string;

let validatedSession = await validateSessionJWT(sessionJWT);
// If jwt is invalid/expired, check the main session token.
if (validatedSession === null) {
	validatedSession = await validateSessionToken(sessionToken);
}
if (validatedSession === null) {
	// no session
}

```

--------------------------------

### GitHub OAuth Environment Variables

Source: https://lucia-auth.com/tutorials/github-oauth/nextjs

Configure your GitHub client ID and secret in the .env file.

```dotenv
# .env
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""

```

--------------------------------

### Lua Script for Redis Token Bucket

Source: https://lucia-auth.com/rate-limit/token-bucket

A Lua script for atomic operations on Redis to implement the token bucket algorithm. It handles token consumption, refilling, and expiration.

```lua
-- Returns 1 if allowed, 0 if not
local key                   = KEYS[1]
local max                   = tonumber(ARGV[1])
local refillIntervalSeconds = tonumber(ARGV[2])
local cost                  = tonumber(ARGV[3])
local nowMilliseconds       = tonumber(ARGV[4]) -- Current unix time in ms

local fields = redis.call("HGETALL", key)

if #fields == 0 then
	local expiresInSeconds = cost * refillIntervalSeconds
	redis.call("HSET", key, "count", max - cost, "refilled_at_ms", nowMilliseconds)
	redis.call("EXPIRE", key, expiresInSeconds)
	return {1}
end

local count = 0
local refilledAtMilliseconds = 0
for i = 1, #fields, 2 do
	if fields[i] == "count" then
		count = tonumber(fields[i+1])
	elseif fields[i] == "refilled_at_ms" then
		refilledAtMilliseconds = tonumber(fields[i+1])
	end
end

local refill = math.floor((now - refilledAtMilliseconds) / (refillIntervalSeconds * 1000))
count = math.min(count + refill, max)
refilledAtMilliseconds = refilledAtMilliseconds + refill * refillIntervalSeconds * 1000

if count < cost then
	return {0}
end

count = count - cost
local expiresInSeconds = (max - count) * refillIntervalSeconds
redis.call("HSET", key, "count", count, "refilled_at_ms", refilledAtMilliseconds)
redis.call("EXPIRE", key, expiresInSeconds)
return {1}

```

--------------------------------

### Handle Google OAuth Callback

Source: https://lucia-auth.com/tutorials/google-oauth/astro

This route handles the callback from Google OAuth. It validates the authorization code, retrieves user information, checks for existing users, creates a new user if necessary, and establishes a new session.

```typescript
import { generateSessionToken, createSession, setSessionTokenCookie } from "@lib/server/session";
import { google } from "@lib/oauth";
import { decodeIdToken } from "arctic";

import type { APIContext } from "astro";
import type { OAuth2Tokens } from "arctic";

export async function GET(context: APIContext): Promise<Response> {
	const code = context.url.searchParams.get("code");
	const state = context.url.searchParams.get("state");
	const storedState = context.cookies.get("google_oauth_state")?.value ?? null;
	const codeVerifier = context.cookies.get("google_code_verifier")?.value ?? null;
	if (code === null || state === null || storedState === null || codeVerifier === null) {
		return new Response(null, {
			status: 400
		});
	}
	if (state !== storedState) {
		return new Response(null, {
			status: 400
		});
	}

	let tokens: OAuth2Tokens;
	try {
		tokens = await google.validateAuthorizationCode(code, codeVerifier);
	} catch (e) {
		// Invalid code or client credentials
		return new Response(null, {
			status: 400
		});
	}
	const claims = decodeIdToken(tokens.idToken());
	const googleUserId = claims.sub;
	const username = claims.name;

	// TODO: Replace this with your own DB query.
	const existingUser = await getUserFromGoogleId(googleUserId);

	if (existingUser !== null) {
		const sessionToken = generateSessionToken();
		const session = await createSession(sessionToken, existingUser.id);
		setSessionTokenCookie(context, sessionToken, session.expiresAt);
		return context.redirect("/");
	}

	// TODO: Replace this with your own DB query.
	const user = await createUser(googleUserId, username);

	const sessionToken = generateSessionToken();
	const session = await createSession(sessionToken, user.id);
	setSessionTokenCookie(context, sessionToken, session.expiresAt);
	return context.redirect("/");
}

```

--------------------------------

### TypeScript Token Bucket Implementation (Redis)

Source: https://lucia-auth.com/rate-limit/token-bucket

A Redis-based token bucket rate limiter using Lua scripts for atomic operations. This is suitable for distributed environments.

```typescript
export class TokenBucketRateLimit {
	private storageKey: string;

	public max: number;
	public refillIntervalSeconds: number;

	constructor(storageKey: string, max: number, refillIntervalSeconds: number) {
		this.storageKey = storageKey;
		this.max = max;
		this.refillIntervalSeconds = refillIntervalSeconds;
	}

	public async consume(key: string, cost: number): Promise<boolean> {
		const key = `token_bucket.v1:${this.storageKey}:${refillIntervalSeconds}:${key}`;
		const result = await client.EVALSHA(SCRIPT_SHA, {
			keys: [key],
			arguments: [
				this.max.toString(),
				this.refillIntervalSeconds.toString(),
				cost.toString(),
				Date.now().toString()
			]
		});
		return Boolean(result[0]);
	}
}

```

--------------------------------

### Create GitHub Authorization URL

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Generate a state, create an authorization URL using the GitHub provider, store the state in a cookie, and redirect the user to GitHub's sign-in page.

```typescript
// pages/login/github/index.ts
import { generateState } from "arctic";
import { github } from "@lib/oauth";

import type { APIContext } from "astro";

export async function GET(context: APIContext): Promise<Response> {
	const state = generateState();
	const url = github.createAuthorizationURL(state, []);

	context.cookies.set("github_oauth_state", state, {
		path: "/",
		secure: import.meta.env.PROD,
		httpOnly: true,
		maxAge: 60 * 10, // 10 minutes
		sameSite: "lax"
	});

	return context.redirect(url.toString());
}
```

--------------------------------

### Sign-in Button in Astro

Source: https://lucia-auth.com/tutorials/google-oauth/astro

Create a basic sign-in button on your Astro page that links to the Google OAuth initiation endpoint.

```astro
<!-- pages/login/index.astro -->
<html lang="en">
	<body>
		<h1>Sign in</h1>
		<a href="/login/google">Sign in with Google</a>
	</body>
</html>
```

--------------------------------

### GitHub OAuth App Credentials

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Add your GitHub client ID and secret to your .env file. Ensure the redirect URI is set to http://localhost:4321/login/github/callback in your GitHub OAuth app settings.

```env
# .env
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
```

--------------------------------

### TypeScript Token Bucket Implementation (Memory Storage)

Source: https://lucia-auth.com/rate-limit/token-bucket

A memory-based token bucket rate limiter. This is suitable for single-server environments but not for serverless architectures as it requires persistent memory across requests.

```typescript
export class TokenBucketRateLimit<_Key> {
	public max: number;
	public refillIntervalSeconds: number;

	constructor(max: number, refillIntervalSeconds: number) {
		this.max = max;
		this.refillIntervalSeconds = refillIntervalSeconds;
	}

	private storage = new Map<_Key, Bucket>();

	public consume(key: _Key, cost: number): boolean {
		let bucket = this.storage.get(key) ?? null;
		const now = Date.now();
		if (bucket === null) {
			bucket = {
				count: this.max - cost,
				refilledAtMilliseconds: now
			};
			this.storage.set(key, bucket);
			return true;
		}
		const refill = Math.floor(
			(now - bucket.refilledAtMilliseconds) / (this.refillIntervalSeconds * 1000)
		);
		bucket.count = Math.min(bucket.count + refill, this.max);
		bucket.refilledAtMilliseconds =
			bucket.refilledAtMilliseconds + refill * this.refillIntervalSeconds * 1000;
		if (bucket.count < cost) {
			this.storage.set(key, bucket);
			return false;
		}
		bucket.count -= cost;
		this.storage.set(key, bucket);
		return true;
	}
}

interface Bucket {
	count: number;
	refilledAtMilliseconds: number;
}

```

--------------------------------

### Environment Variables for Google OAuth

Source: https://lucia-auth.com/tutorials/google-oauth/astro

Store your Google OAuth client ID and secret in your .env file. Ensure these are kept secure.

```env
# .env
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
```

--------------------------------

### Sign Out Form in SvelteKit

Source: https://lucia-auth.com/tutorials/google-oauth/sveltekit

A simple Svelte form component for initiating the sign-out process.

```svelte
<!-- routes/+page.svelte -->
<script lang="ts">
	import { enhance } from "$app/forms";
</script>

<form method="post" use:enhance>
    <button>Sign out</button>
</form>

```

--------------------------------

### Sign Out Form in SvelteKit

Source: https://lucia-auth.com/tutorials/github-oauth/sveltekit

A simple Svelte form with a submit button to trigger the sign-out action. Uses '$app/forms' enhance for progressive enhancement.

```svelte
<!-- routes/+page.svelte -->
<script lang="ts">
	import { enhance } from "$app/forms";
</script>

<form method="post" use:enhance>
    <button>Sign out</button>
</form>


```

--------------------------------

### Sign Out User in SvelteKit

Source: https://lucia-auth.com/tutorials/google-oauth/sveltekit

This action invalidates the user's session and removes the session cookie, then redirects to the login page. It returns a 401 error if no active session is found.

```typescript
// routes/+page.server.ts
import { fail, redirect } from "@sveltejs/kit";
import { invalidateSession, deleteSessionTokenCookie } from "$lib/server/session";

import type { Actions, PageServerLoad } from "./$types";

export const load: PageServerLoad = async ({ locals }) => {
	// ...
};

export const actions: Actions = {
	default: async (event) => {
		if (event.locals.session === null) {
			return fail(401);
		}
		await invalidateSession(event.locals.session.id);
		deleteSessionTokenCookie(event);
		return redirect(302, "/login");
	}
};

```

--------------------------------

### Handle Google OAuth Callback in Next.js

Source: https://lucia-auth.com/tutorials/google-oauth/nextjs

This route handler in `app/login/google/callback/route.ts` manages the callback from Google OAuth. It validates the state and authorization code, exchanges the code for tokens, retrieves user information, and either logs in an existing user or creates a new one before establishing a session.

```typescript
// app/login/google/callback/route.ts
import { generateSessionToken, createSession, setSessionTokenCookie } from "@/lib/session";
import { google } from "@/lib/oauth";
import { cookies } from "next/headers";
import { decodeIdToken } from "arctic";

import type { OAuth2Tokens } from "arctic";

export async function GET(request: Request): Promise<Response> {
	const url = new URL(request.url);
	const code = url.searchParams.get("code");
	const state = url.searchParams.get("state");
	const cookieStore = await cookies();
	const storedState = cookieStore.get("google_oauth_state")?.value ?? null;
	const codeVerifier = cookieStore.get("google_code_verifier")?.value ?? null;
	if (code === null || state === null || storedState === null || codeVerifier === null) {
		return new Response(null, {
			status: 400
		});
	}
	if (state !== storedState) {
		return new Response(null, {
			status: 400
		});
	}

	let tokens: OAuth2Tokens;
	try {
		tokens = await google.validateAuthorizationCode(code, codeVerifier);
	} catch (e) {
		// Invalid code or client credentials
		return new Response(null, {
			status: 400
		});
	}
	const claims = decodeIdToken(tokens.idToken());
	const googleUserId = claims.sub;
	const username = claims.name;

	// TODO: Replace this with your own DB query.
	const existingUser = await getUserFromGoogleId(googleUserId);

	if (existingUser !== null) {
		const sessionToken = generateSessionToken();
		const session = await createSession(sessionToken, existingUser.id);
		await setSessionTokenCookie(sessionToken, session.expiresAt);
		return new Response(null, {
			status: 302,
			headers: {
				Location: "/"
			}
		});
	}

	// TODO: Replace this with your own DB query.
	const user = await createUser(googleUserId, username);

	const sessionToken = generateSessionToken();
	const session = await createSession(sessionToken, user.id);
	await setSessionTokenCookie(sessionToken, session.expiresAt);
	return new Response(null, {
		status: 302,
		headers: {
			Location: "/"
		}
	});
}

```

--------------------------------

### Session Table Schema

Source: https://lucia-auth.com/sessions/inactivity-timeout

SQL schema for the session table, including a `last_verified_at` column to store the session's last verification timestamp.

```sql
CREATE TABLE session (
	id TEXT NOT NULL PRIMARY KEY,
	secret_hash BLOB NOT NULL,
	last_verified_at INTEGER NOT NULL, -- unix (seconds)
	created_at INTEGER NOT NULL,
) STRICT;

```

--------------------------------

### Create Session JWT (HMAC SHA-256)

Source: https://lucia-auth.com/sessions/stateless-tokens

Implements a function to create a JWT using HMAC SHA-256. Ensure the signing key is securely managed. The JWT is valid for a short duration.

```typescript
import * as oslo_encoding from "@oslojs/encoding";

// Randomly generated key
// For HMAC with SHA-256, the key must be 32 bytes
const jwtHS256Key = new Uint8Array(32);

async function createSessionJWT(session: Session): Promise<string> {
	const now = new Date();

	const expirationSeconds = 60; // 1 minute

	const headerJSON = JSON.stringify({ alg: "HS256", typ: "JWT" });
	const headerJSONBytes = new TextEncoder().encode(headerJSON);
	const encodedHeader = oslo_encoding.encodeBase64url(headerJSONBytes);

	const bodyJSON = JSON.stringify({
		// Omit the secret hash
		session: {
			id: session.id,
			created_at: Math.floor(session.createdAt.getTime() / 1000)
		},
		iat: Math.floor(now.getTime() / 1000),
		exp: Math.floor(now.getTime() / 1000) + expirationSeconds
	});
	const bodyJSONBytes = new TextEncoder().encode(bodyJSON);
	const encodedBody = oslo_encoding.encodeBase64url(bodyJSONBytes);

	const headerAndBody = encodedHeader + "." + encodedBody;
	const headerAndBodyBytes = new TextEncoder().encode(headerAndBody);

	hmacCryptoKey = await crypto.subtle.importKey(
		"raw",
		jwtHS256Key,
		{
			name: "HMAC",
			hash: "SHA-256"
		},
		false
	);
	signature = await crypto.subtle.sign("HMAC", hmacCryptoKey, headerAndBodyBytes);
	const encodedSignature = oslo_jwt.encodeJWT(headerJSON, bodyJSON);

	const jw = headerAndBody + "." + encodedSignature;
	return jwt;
}

```

--------------------------------

### Load Redis Lua Script

Source: https://lucia-auth.com/rate-limit/token-bucket

Loads a Lua script into Redis and retrieves its SHA1 hash for efficient subsequent calls using EVALSHA.

```javascript
const SCRIPT_SHA = await client.scriptLoad(script);

```

--------------------------------

### Generate Google OAuth Authorization URL

Source: https://lucia-auth.com/tutorials/google-oauth/sveltekit

Create an API route to generate the Google OAuth authorization URL, store state and code verifier, and redirect the user.

```typescript
// routes/login/google/+server.ts
import { generateState, generateCodeVerifier } from "arctic";
import { google } from "$lib/server/oauth";

import type { RequestEvent } from "@sveltejs/kit";

export async function GET(event: RequestEvent): Promise<Response> {
	const state = generateState();
	const codeVerifier = generateCodeVerifier();
	const url = google.createAuthorizationURL(state, codeVerifier, ["openid", "profile"]);

	event.cookies.set("google_oauth_state", state, {
		path: "/",
		httpOnly: true,
		maxAge: 60 * 10, // 10 minutes
		sameSite: "lax"
	});
	event.cookies.set("google_code_verifier", codeVerifier, {
		path: "/",
		httpOnly: true,
		maxAge: 60 * 10, // 10 minutes
		sameSite: "lax"
	});

	return new Response(null, {
		status: 302,
		headers: {
			Location: url.toString()
		}
	});
}
```

--------------------------------

### Generate Google OAuth Authorization URL

Source: https://lucia-auth.com/tutorials/google-oauth/astro

Create an API route to generate a state, code verifier, and authorization URL for Google OAuth. It stores necessary cookies and redirects the user.

```typescript
// pages/login/google/index.ts
import { generateState } from "arctic";
import { google } from "@lib/oauth";

import type { APIContext } from "astro";

export async function GET(context: APIContext): Promise<Response> {
	const state = generateState();
	const codeVerifier = generateCodeVerifier();
	const url = google.createAuthorizationURL(state, codeVerifier, ["openid", "profile"]);

	context.cookies.set("google_oauth_state", state, {
		path: "/",
		secure: import.meta.env.PROD,
		httpOnly: true,
		maxAge: 60 * 10, // 10 minutes
		sameSite: "lax"
	});
	context.cookies.set("google_code_verifier", codeVerifier, {
		path: "/",
		secure: import.meta.env.PROD,
		httpOnly: true,
		maxAge: 60 * 10, // 10 minutes
		sameSite: "lax"
	});

	return context.redirect(url.toString());
}
```

--------------------------------

### Session Token Format

Source: https://lucia-auth.com/sessions/basic

Illustrates the format of tokens issued to clients, which consist of the session ID concatenated with the un-hashed session secret, separated by a dot.

```text
<SESSION_ID>.<SESSION_SECRET>
```

--------------------------------

### Google OAuth Authorization Route

Source: https://lucia-auth.com/tutorials/google-oauth/nextjs

Handles the initial Google OAuth request, generating state, code verifier, and redirecting to Google's sign-in page. Stores state and code verifier in cookies.

```typescript
// app/login/google/route.ts
import { generateState, generateCodeVerifier } from "arctic";
import { google } from "@/lib/auth";
import { cookies } from "next/headers";

export async function GET(): Promise<Response> {
	const state = generateState();
	const codeVerifier = generateCodeVerifier();
	const url = google.createAuthorizationURL(state, codeVerifier, ["openid", "profile"]);

	const cookieStore = await cookies();
	cookieStore.set("google_oauth_state", state, {
		path: "/",
		httpOnly: true,
		secure: process.env.NODE_ENV === "production",
		maxAge: 60 * 10, // 10 minutes
		sameSite: "lax"
	});
	cookieStore.set("google_code_verifier", codeVerifier, {
		path: "/",
		httpOnly: true,
		secure: process.env.NODE_ENV === "production",
		maxAge: 60 * 10, // 10 minutes
		sameSite: "lax"
	});

	return new Response(null, {
		status: 302,
		headers: {
			Location: url.toString()
		}
	});
}

```

--------------------------------

### User Model with Google ID

Source: https://lucia-auth.com/tutorials/google-oauth/astro

Update your user database model to include fields for the user's Google ID and name.

```typescript
interface User {
	id: number;
	googleId: string;
	name: string;
}
```

--------------------------------

### Sign Out User in SvelteKit

Source: https://lucia-auth.com/tutorials/github-oauth/sveltekit

Invalidates the user's session and deletes the session cookie upon sign-out. Returns a 401 error if no active session exists.

```typescript
// routes/+page.server.ts
import { fail, redirect } from "@sveltejs/kit";
import { invalidateSession, deleteSessionTokenCookie } from "$lib/server/session";

import type { Actions, PageServerLoad } from "./$types";

export const load: PageServerLoad = async ({ locals }) => {
	// ...
};

export const actions: Actions = {
	default: async (event) => {
		if (event.locals.session === null) {
			return fail(401);
		}
		await invalidateSession(event.locals.session.id);
		deleteSessionTokenCookie(event);
		return redirect(302, "/login");
	}
};


```

--------------------------------

### User Model Update

Source: https://lucia-auth.com/tutorials/github-oauth/astro

Update your user model interface to include GitHub-specific fields like githubId and username.

```typescript
interface User {
	id: number;
	githubId: number;
	username: string;
}
```

--------------------------------

### Verify Request Origin (Production Strict)

Source: https://lucia-auth.com/sessions/basic

This function enforces strict origin checks only in production environments. It allows all methods in non-production and checks GET/HEAD requests separately.

```typescript
function verifyRequestOrigin(method: string, originHeader: string): boolean {
	if (env !== ENV.PROD) {
		return true;
	}
	if (method === "GET" || method === "HEAD") {
		return true;
	}
	return originHeader === "example.com";
}
```

--------------------------------

### Generate Secure Random String

Source: https://lucia-auth.com/sessions/basic

Generates a cryptographically secure random string for session IDs and secrets. It uses `crypto.getRandomValues` and a custom alphabet to ensure sufficient entropy and avoid confusion.

```typescript
function generateSecureRandomString(): string {
	// Human readable alphabet (a-z, 0-9 without l, o, 0, 1 to avoid confusion)
	const alphabet = "abcdefghijkmnpqrstuvwxyz23456789";

	// Generate 24 bytes = 192 bits of entropy.
	// We're only going to use 5 bits per byte so the total entropy will be 192 * 5 / 8 = 120 bits
	const bytes = new Uint8Array(24);
	crypto.getRandomValues(bytes);

	let id = "";
	for (let i = 0; i < bytes.length; i++) {
		// >> 3 "removes" the right-most 3 bits of the byte
		id += alphabet[bytes[i] >> 3];
	}
	return id;
}
```

--------------------------------

### Validate User Session in Next.js

Source: https://lucia-auth.com/tutorials/github-oauth/nextjs

Use `getCurrentSession()` to retrieve the current user's session in a Next.js page. Redirects to the login page if no user is found.

```typescript
import { redirect } from "next/navigation";
import { getCurrentSession } from "@/lib/session";

export default async function Page() {
	const { user } = await getCurrentSession();
	if (user === null) {
		return redirect("/login");
	}
	return <h1>Hi, {user.username}!</h1>;
}

```

--------------------------------

### Verify Request Origin (Basic)

Source: https://lucia-auth.com/sessions/basic

This function checks if the request origin is valid for non-GET/HEAD requests. It's a basic implementation for CSRF protection.

```typescript
function verifyRequestOrigin(method: string, originHeader: string): boolean {
	if (method === "GET" || method === "HEAD") {
		return true;
	}
	return originHeader === "example.com";
}
```

--------------------------------

### Session Interface Definition

Source: https://lucia-auth.com/sessions/inactivity-timeout

Defines the structure of a session object, including a `lastVerifiedAt` attribute to track the last verification time.

```typescript
interface Session {
	id: string;
	secretHash: Uint8Array;
	lastVerifiedAt: Date;
	createdAt: Date;
}

```

--------------------------------

### SQLite Session Table Schema

Source: https://lucia-auth.com/sessions/basic

Defines the SQL schema for storing session data in an SQLite database. It includes columns for ID, secret hash (as BLOB), and creation time (as INTEGER). The STRICT keyword enforces type checking.

```sql
CREATE TABLE session (
	id TEXT NOT NULL PRIMARY KEY,
	secret_hash BLOB NOT NULL, -- blob is a SQLite data type for raw binary
	created_at INTEGER NOT NULL -- unix time (seconds)
) STRICT;
```

--------------------------------

### Hash Secret using SHA-256

Source: https://lucia-auth.com/sessions/basic

Asynchronously hashes a given secret string using the SHA-256 algorithm. The secret is first encoded into bytes using `TextEncoder` before hashing.

```typescript
async function hashSecret(secret: string): Promise<Uint8Array> {
	const secretBytes = new TextEncoder().encode(secret);
	const secretHashBuffer = await crypto.subtle.digest("SHA-256", secretBytes);
	return new Uint8Array(secretHashBuffer);
}
```

--------------------------------

### Session Interface Definition

Source: https://lucia-auth.com/sessions/basic

Defines the structure of a session object, including its ID, hashed secret, and creation timestamp. The secret hash is stored as a Uint8Array.

```typescript
interface Session {
	id: string;
	secretHash: Uint8Array; // Uint8Array is a byte array
	createdAt: Date;
}
```

--------------------------------

### Validate Session JWT (HMAC SHA-256)

Source: https://lucia-auth.com/sessions/stateless-tokens

Implements JWT validation using HMAC SHA-256. It verifies the signature, checks expiration, and parses session details. Ensure the signing key matches the one used for creation.

```typescript
async function validateSessionJWT(jwt: string): Promise<ValidatedSession | null> {
	const now = new Date();

	const parts = jwt.split(".");
	if (parts.length !== 3) {
		return null;
	}

	// Parse header
	let header: object;
	try {
		headerJSONBytes = oslo_encoding.decodeBase64url(parts[0]);
		headerJSON = new TextDecoder().decode(headerJSONBytes);
		parsedHeader = JSON.parse(headerJSON) as unknown;
		if (typeof parsedHeader !== "object" || parsedHeader === null) {
			return null;
		}
		header = parsedHeader;
	} catch {
		return null;
	}

	// Verify header claims
	if ("typ" in header && header.typ !== "JWT") {
		return null;
	}
	if (!("alg" in header) || header.alg !== "HS256") {
		return null;
	}

	// Verify signature
	signature = oslo_encoding.decodeBase64url(parts[2]);
	headerAndBodyBytes = new TextEncoder().encode(parts[0] + "." + parts[1]);
	hmacCryptoKey = await crypto.subtle.importKey(
		"raw",
		jwtHS256Key,
		{
			name: "HMAC",
			hash: "SHA-256"
		},
		false
	);
	validSignature = await crypto.subtle.verify(
		"HMAC",
		hmacCryptoKey,
		signature,
		headerAndBodyBytes
	);
	if (!validSignature) {
		return null;
	}

	// Parse body
	let body: object;
	try {
		bodyJSONParts = oslo_encoding.decodeBase64url(parts[1]);
		bodyJSON = new TextDecoder().decode(bodyJSONParts);
		parsedBody = JSON.parse(bodyJSON) as unknown;
		if (typeof parsedBody !== "object" || parsedBody === null) {
			return null;
		}
		body = parsedBody;
	} catch {
		return null;
	}

	// Check expiration
	if (!("exp" in body) || typeof body.exp !== "number") {
		return null;
	}
	expiresAt = new Date(body.exp * 1000);
	if (now.getTime() >= expiresAt.getTime()) {
		return null;
	}

	// Parse session
	if (!("session" in body) || typeof body.session !== "object" || body.session === null) {
		return null;
	}
	parsedSession = body.session;
	return {
		session: parsedSession as Session,
		// You might want to return the original token or other relevant info
	};
}

```

--------------------------------

### Reusable Session Validation Function

Source: https://lucia-auth.com/sessions/frameworks/nextjs

Create a reusable function to validate session tokens and cache the result to avoid multiple database calls. This function should be used within Next.js server components.

```typescript
import { cookies } from "next/headers";
import { cache } from "react";

export const getCurrentSession = cache(async (): Promise<Session> => {
	const cookieStore = await cookies();
	const token = cookieStore.get("session")?.value ?? null;
	if (token === null) {
		return { session: null, user: null };
	}
	const result = await validateSessionToken(token);
	return result;
});

```

--------------------------------

### Sign Out User in Astro

Source: https://lucia-auth.com/tutorials/github-oauth/astro

This snippet demonstrates how to sign out a user in an Astro application. It invalidates the user's session and deletes the session token cookie before redirecting the user to the login page. Ensure that the session is not already null before proceeding.

```typescript
import { invalidateSession, deleteSessionTokenCookie } from "@lib/session";

import type { APIContext } from "astro";

export async function POST(context: APIContext): Promise<Response> {
	if (context.locals.session === null) {
		return new Response(null, {
			status: 401
		});
	}
	await invalidateSession(context.locals.session.id);
	deleteSessionTokenCookie(context);
	return context.redirect("/login");
}
```
Tokens:
Raw