Authentication & Account Management Skill

This skill defines mandatory standards for implementing secure, production-grade authentication in Antigravity projects. All implementations MUST follow Google's OAuth 2.0 best practices.

1. Core Principles

Principle	Requirement
SSO First	Prefer Google OAuth 2.0 over custom credentials
Least Privilege	Request only the minimum scopes required
Defense in Depth	Validate on both client and server
Secure by Default	All protected routes require authentication

2. Google OAuth 2.0 Best Practices (MANDATORY)

2.1 Credential Security

NEVER commit GOOGLE_CLIENT_ID or GOOGLE_CLIENT_SECRET to version control.
Store secrets in a secure manager (e.g., GCP Secret Manager, Vercel Environment Variables).
Rotate secrets immediately if exposed.
Use separate OAuth clients for Development, Staging, and Production.

2.2 Token Handling

Rule	Implementation
No Plaintext Tokens	Never transmit tokens over HTTP; HTTPS only
Encrypt at Rest	Store tokens encrypted in the database
Short-Lived Access	Use short-lived access tokens (default: 1 hour)
Secure Refresh	Store refresh tokens server-side only
Revoke on Logout	Invalidate tokens when user logs out or revokes permissions

2.3 Scope Management

Incremental Authorization: Request scopes only when the specific feature needs them.
Graceful Denial: Handle scope denial gracefully by disabling affected features.
Default Scopes: For basic auth, use only openid, profile, and email.

2.4 Redirect URI Validation

All redirect URIs MUST use HTTPS (except localhost for dev).
Define explicit, allowed redirect URIs in Google Cloud Console.
Never accept dynamic or user-supplied redirect URIs.

3. Route Protection Patterns

Every route MUST be classified as one of the following:

3.1 Public Routes (Unauthenticated)

No authentication required. Accessible by anyone.

Example Routes	Description
`/`	Landing page
`/login`	Login page
`/about`	Static pages
`/api/health`	Health check endpoint

3.2 Protected Routes (Authenticated)

Require a valid session. Redirect to /login if unauthenticated.

Example Routes	Description
`/dashboard`	User's main dashboard
`/profile`	User settings
`/api/user/*`	User-specific API endpoints

3.3 Admin Routes (Authorized)

Require authentication AND the admin role. Return 403 if not authorized.

Example Routes	Description
`/admin/*`	Admin panel pages
`/api/admin/*`	Admin API endpoints

4. API Endpoint Security

All backend API endpoints MUST declare their authentication status.

4.1 Classification Table (Template)

When creating API endpoints, document them as follows:

Endpoint	Method	Auth Required	Role Required	Rate Limited
`/api/health`	GET	❌ No	None	❌
`/api/user/profile`	GET	✅ Yes	`user`	✅ 100/min
`/api/admin/users`	GET	✅ Yes	`admin`	✅ 30/min
`/api/admin/users/:id`	DELETE	✅ Yes	`admin`	✅ 10/min

4.2 Implementation Requirements

Server-Side Validation: NEVER trust client-side auth state. Always validate the session on the server.
Use Middleware: Protect routes via Next.js Middleware or Express middleware.
Role-Based Access Control (RBAC): Check user roles in the database, not in JWT claims alone.
Error Responses:
- 401 Unauthorized → User not authenticated
- 403 Forbidden → User authenticated but lacks required role

5. Account Management

5.1 Profile Page (`/profile`)

Every authenticated application MUST have a profile page with:

Display user's name, email, and profile picture from Google
Option to log out
Option to delete account (with confirmation)

5.2 Session Management

Setting	Recommended Value
Session Duration	30 days (rolling)
Inactivity Timeout	7 days
Remember Me	Optional, extends to 90 days

5.3 Account Deletion

Provide a clear way for users to request account deletion.
Revoke all tokens and delete user data upon deletion.
Confirm deletion via email or re-authentication.

6. Implementation Checklist

Credential Setup

Registered OAuth 2.0 client in Google Cloud Console
Configured separate clients for Dev/Staging/Prod
Stored GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in secure environment
Generated NEXTAUTH_SECRET securely (openssl rand -base64 32)

Route Protection

Middleware configured for protected routes
All API endpoints documented with auth requirements (see §4.1)
Admin routes check role in database

Token Security

Tokens never exposed to client-side JavaScript
Refresh tokens stored server-side only
Tokens revoked on logout

Validation

Tested login flow end-to-end
Tested logout flow including token revocation
Tested unauthorized access returns 401/403
Tested admin route protection with non-admin user

7. NextAuth.js Configuration Template

// auth.config.ts
import NextAuth from "next-auth"
import Google from "next-auth/providers/google"

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      authorization: {
        params: {
          prompt: "consent",
          access_type: "offline",
          response_type: "code",
        },
      },
    }),
  ],
  callbacks: {
    async session({ session, token }) {
      if (session.user) {
        session.user.id = token.sub as string
        // Fetch role from database, NOT from token
      }
      return session
    },
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token
      }
      return token
    },
  },
  pages: {
    signIn: "/login",
    error: "/auth/error",
  },
  session: {
    strategy: "jwt",
    maxAge: 30 * 24 * 60 * 60, // 30 days
  },
})

8. Workflow Triggers

Backend Logic in Client: If writing auth logic in a Client Component → STOP. Move to Server Action or API route.
Hardcoded Secrets Detected: If GOOGLE_CLIENT_* is hardcoded → STOP. Move to environment variables.
Missing Middleware: If creating new protected routes without middleware → STOP. Add to middleware matcher.

Authentication & Account Management