Authentication System
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication System in Poneglyph is built using Better-Auth, a comprehensive authentication framework designed for TypeScript and monorepo environments. It serves as a shared infrastructure layer located in packages/auth, providing consistent authentication logic and session management for both the Next.js frontend (apps/web) and the Hono-based backend API (apps/server).
The system utilizes Drizzle ORM for database persistence with a PostgreSQL provider, ensuring type-safe interactions with user data and authentication tables. The core functionality includes secure email/password authentication, mandatory email verification, and optimized cookie handling for production environments.
Sources: README.md:15, packages/auth/src/index.ts:1-20, packages/auth/package.json:10-18
Core Architecture and Configuration
The authentication logic is centralized in the @Poneglyph/auth package. The system is initialized via the createAuth function, which configures the betterAuth instance with application-specific parameters, database adapters, and security plugins.
Better-Auth Configuration
The authentication engine is configured with the following parameters:
- Application Name: Identified as "Poneglyph".
- Database Adapter: Uses the
drizzleAdapterconnecting to a PostgreSQL instance. - Trusted Origins: Restricts authentication requests to specified CORS origins defined in environment variables.
- Plugins: Includes the
openAPIplugin to facilitate automated API documentation.
Sources: packages/auth/src/index.ts:12-53
Integration Overview
The following diagram illustrates the relationship between the authentication package, the database, and the consuming applications.
Diagram shows the centralized nature of the authentication package across the monorepo.
Sources: README.md:73-82, packages/auth/src/index.ts:16-20
Authentication Mechanisms
Poneglyph primarily implements an Email and Password authentication strategy with strict verification requirements.
Email and Password Logic
The system enables standard credential-based login with the following constraints:
- Email Verification: Mandatory for all users.
- Auto Sign-In: Disabled by default upon initial sign-up to ensure verification occurs before access is granted.
- Verification Delivery: Integrated with a mailing utility (
sendVerificationEmail) which uses theresendlibrary to transmit verification links.
Sources: packages/auth/src/index.ts:25-41, packages/auth/package.json:17
User Verification Workflow
The verification process is automated and time-bound. Verification links expire after 86,400 seconds (24 hours). Once a user successfully verifies their email, the system allows for an automatic sign-in.
Diagram showing the multi-step verification process from registration to confirmed access.
Sources: packages/auth/src/index.ts:31-41
Session and Security Management
The system enforces strict security protocols through managed cookies and cross-origin configurations.
Cookie Configuration
Authentication sessions are maintained via cookies with the following security attributes:
- SameSite: Set to
nonein production to allow cross-site requests, andlaxin development. - Secure: Cookies are marked as
Securein production environments (HTTPS only). - HTTPOnly: Always enabled to prevent client-side script access to session tokens.
- Domain Scoping: Supports cross-subdomain cookies in production (e.g.,
.vyse.site) to allow shared sessions across the monorepo's public-facing apps.
Sources: packages/auth/src/index.ts:43-52
Summary of Configuration Parameters
| Parameter | Type | Default / Value | Description |
|---|---|---|---|
appName | string | "Poneglyph" | The identifier used in auth contexts. |
requireEmailVerification | boolean | true | Prevents access until email is confirmed. |
expiresIn | number | 86400 | Seconds until a verification token expires. |
autoSignInAfterVerification | boolean | true | Automatically logs user in after successful verification. |
httpOnly | boolean | true | Security measure for session cookies. |
Sources: packages/auth/src/index.ts:14-52
Implementation Details
The implementation leverages specific dependencies across the workspace to maintain type safety and modularity.
// packages/auth/src/index.ts:12-24
export function createAuth() {
const db = createDb();
return betterAuth({
appName: "Poneglyph",
database: drizzleAdapter(db, {
provider: "pg",
schema,
}),
trustedOrigins: [env.CORS_ORIGIN],
secret: env.BETTER_AUTH_SECRET,
baseURL: env.BETTER_AUTH_URL,
// ... further config
});
}
Sources: packages/auth/src/index.ts:12-24
Shared Dependencies
The system relies on several core libraries across the monorepo:
- better-auth: Core authentication framework (version
1.5.5). - @Poneglyph/db: Internal package providing the Drizzle database instance and schema definitions.
- @Poneglyph/env: Internal package for validated server-side environment variables.
- resend: Utilized for sending transactional emails.
Sources: packages/auth/package.json:13-18, package.json:11
Conclusion
The Authentication System provides a centralized, secure, and developer-friendly way to manage user identities within Poneglyph. By leveraging better-auth and a shared package architecture, the project ensures that security policies—such as mandatory email verification and HTTPOnly cookies—are applied consistently across the Next.js web application and the Hono API server.