Authentication Plugin
The Authentication plugin (pocketpages-plugin-auth
) provides a complete authentication system for PocketPages applications, supporting multiple authentication methods including password, OTP, OAuth2, and anonymous authentication.
Installation
npm install pocketpages-plugin-auth
Configuration
Add the plugin to your +config.js
file:
module.exports = {
plugins: [
'pocketpages-plugin-js-sdk', // Required dependency, must be explicitly listed
'pocketpages-plugin-auth',
// ... other plugins
],
}
Authentication Flow
The plugin automatically:
- Checks for an existing auth record in the request
- If none exists, checks for a
pb_auth
cookie containing an auth token - If a valid token is found, sets
request.auth
to the corresponding auth record
This means authentication state is automatically handled for you across requests.
API Reference
User Management
// Create a new user with password
function createUser(
email: string,
password: string,
options?: {
collection?: string
sendVerificationEmail?: boolean
}
): User
// Create an anonymous user
function createAnonymousUser(options?: { collection?: string }): {
email: string
password: string
user: User
}
// Create a passwordless user
function createPasswordlessUser(
email: string,
options?: {
collection?: string
sendVerificationEmail?: boolean
}
): {
password: string
user: User
}
Authentication
// Password authentication
function signInWithPassword(
email: string,
password: string,
options?: { collection?: string }
): AuthData
// Register and sign in
function registerWithPassword(
email: string,
password: string,
options?: {
collection?: string
sendVerificationEmail?: boolean
}
): AuthData
// Anonymous authentication
function signInAnonymously(options?: { collection?: string }): AuthData
// OTP authentication
function requestOTP(
email: string,
options?: { collection?: string }
): { otpId: string }
function signInWithOTP(
otpId: string,
password: string,
options?: { collection?: string }
): AuthData
// OAuth2 authentication
function requestOAuth2Login(
providerName: string,
options?: {
collection?: string
cookieName?: string
redirectPath?: string
autoRedirect?: boolean
}
): string
function signInWithOAuth2(
state: string,
code: string,
options?: {
collection?: string
cookieName?: string
}
): AuthData
// Sign out
function signOut(): void
Email Verification
function requestVerification(
email: string,
options?: { collection?: string }
): void
function confirmVerification(
token: string,
options?: { collection?: string }
): void
Basic Usage Examples
Password Authentication
<%
if (request.method === 'POST') {
const { email, password } = body()
try {
const authData = signInWithPassword(email, password)
redirect('/')
} catch (e) {
error = e.message
}
}
%>
<form method="post">
<input name="email" type="email" required />
<input name="password" type="password" required />
<button type="submit">Login</button>
</form>
Anonymous Authentication
<%
if (request.method === 'POST') {
try {
const authData = signInAnonymously()
redirect('/')
} catch (e) {
error = e.message
}
}
%>
<form method="post">
<button type="submit">Continue as Guest</button>
</form>
OAuth2 Authentication
<%
// Initiate OAuth2 login
if (request.method === 'POST') {
const provider = body().provider
const authUrl = requestOAuth2Login(provider, {
redirectPath: '/auth/oauth2/callback'
})
}
%>
<form method="post">
<input type="hidden" name="provider" value="google" />
<button type="submit">Login with Google</button>
</form>
<!-- In your callback route: -->
<%
const { state, code } = params
try {
const authData = signInWithOAuth2(state, code)
redirect('/')
} catch (e) {
error = e.message
}
%>
Protected Routes
Check for authenticated users using request.auth
:
<%
if (!request.auth) {
redirect('/login', {
message: 'Please login first',
returnTo: request.url
})
}
// Access auth record properties
const userId = request.auth.id
const email = request.auth.email
%>
<h1>Welcome <%= request.auth.username %></h1>
Best Practices
Security:
- Use HTTPS in production
- Implement rate limiting
- Set appropriate cookie security options
- Validate OAuth2 state parameters
UX:
- Provide clear error messages
- Show loading states during authentication
- Redirect to intended page after login
- Consider offering multiple auth methods
Implementation:
- Use environment variables for OAuth2 credentials
- Implement proper error handling
- Log authentication events
- Consider implementing MFA
Complete Example
See the Auth starter kit for a complete authentication implementation including:
- Password login/register
- OTP authentication
- OAuth2 providers
- Protected routes
- Error handling
- MFA support