# Social Auth

> Security control system for OAuth 2.0 and OpenID Connect social login. Enforces discovery, strict security invariants, and deterministic outputs before any code is written. Covers OAuth login, provider integration, auth code plus PKCE flow, token and session handling, account linking, multi provider auth, and framework adapters (Next.js, Express, Node). Triggers on login flows, callbacks, token e…

- **Type:** Skill
- **Install:** `agentstack add skill-babatunde-fatai-ai-agent-skills-library-social-auth-core`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Babatunde-Fatai](https://agentstack.voostack.com/s/babatunde-fatai)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Babatunde-Fatai](https://github.com/Babatunde-Fatai)
- **Source:** https://github.com/Babatunde-Fatai/ai-agent-skills-library/tree/main/authentication-skills/social-auth-core

## Install

```sh
agentstack add skill-babatunde-fatai-ai-agent-skills-library-social-auth-core
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Quick Navigation

**⚠️ READ FIRST**: [AGENT_EXECUTION_SPEC.md](references/AGENT_EXECUTION_SPEC.md) - Security contract and execution order

- **Providers**: Google | GitHub | LinkedIn | Apple | Twitter/X
- **Patterns**: OAuth Flow | Golden Path | Token Management | Refresh Token Lifecycle | Sessions | Data Models  
- **Adapters**: Next.js | Express | Vanilla Node | Pseudocode | Laravel | Django | Flask | Rails | Vue
- **Governance** (mandatory): Env Contract | Error Handling | Account Linking | Testing

## Mandatory Start (No Code)

1. Produce a Discovery Report before any code or config changes.
2. Read mandatory references: `references/AGENT_EXECUTION_SPEC.md` and all governance references in `references/governance/`.
3. Confirm provider(s), framework, language, deployment environment, and session strategy. If any are missing or ambiguous, stop and ask.
4. Verify current provider documentation and security guidance (RFC 9700, RFC 7636, RFC 8252, OIDC Core) before implementation.

## Multi-Part Implementation Note

OAuth/OIDC requires coordination between frontend and backend. This skill assumes full-stack access. If implementing in parts:

Scenario 1: Backend-only access
- Implement login start and callback routes.
- Document the route URLs for the frontend team.
- Provide success and error redirect URLs.
- See "Role Selection and Multi-Part Implementation" in `references/AGENT_EXECUTION_SPEC.md`.

Scenario 2: Frontend-only access
- Implement a login button that calls an existing backend route.
- Do not implement OAuth flow logic client-side.
- Use the Frontend-Only Discovery Report in AGENT_EXECUTION_SPEC.md.
- If the backend uses cookie-based sessions, configure API calls with credentials included and derive auth state from the server.
- Do not modify existing auth logic unrelated to the social login being added.

Scenario 3: Full-stack access (recommended)
- Implement backend first (routes, handlers, validation).
- Then add frontend integration (button, redirects).
- Test end-to-end before deploying.

## Discovery Report Requirements (Required First Output)

Include these items, even if the user did not ask:
- Detected framework and runtime (or ambiguity that blocks detection).
- Existing auth stack, session store, user model, and account linking rules.
- Current OAuth providers already integrated and any existing callback routes.
- Deployment constraints (domains, redirect URIs, environment variable system, secrets manager).
- Security middleware already present (CSRF, rate limiting, logging redaction).

If any required item is unknown and cannot be inferred from the repo, stop and ask.

## Routing Logic

Provider routing:
- If provider is Google, read `references/providers/google.md`.
- If provider is GitHub, read `references/providers/github.md`.
- If provider is LinkedIn, read `references/providers/linkedin.md`.
- If provider is Apple, read `references/providers/apple.md`.
- If provider is Twitter/X, read `references/providers/twitter.md`.
- If provider not supported, create a new provider file under `references/providers/` before proceeding.
- [All require CREDENTIALS.md first] Google | GitHub | LinkedIn | Apple | Twitter/X

Pattern routing:
- Always read `references/patterns/oauth-flow-core.md`.
- If you need a canonical end-to-end example, read `references/patterns/golden-path.md`.
- If tokens are stored, refreshed, or revoked, read `references/patterns/token-management.md`.
- If refresh tokens are issued or rotated, read `references/patterns/refresh-token-lifecycle.md`.
- If sessions or cookies are used, read `references/patterns/session-handling.md`.
- If the project has existing authentication, read `references/patterns/existing-auth-integration.md`.
- If cookies are used across different domains, read `references/patterns/samesite-decision-tree.md`.
- If OIDC ID token validation is needed without heavy dependencies, read `references/patterns/jwks-validation-helper.md`.
- If database changes are needed, read `references/patterns/data-models.md`.

Adapter routing:
- If framework is Express, read `references/adapters/express-patterns.md`.
- If framework is Next.js, read `references/adapters/nextjs-patterns.md`.
- If framework is vanilla Node or custom server, read `references/adapters/vanilla-node-patterns.md`.
- If framework is Laravel, read `references/adapters/laravel-patterns.md`.
- If framework is Django, read `references/adapters/django-patterns.md`.
- If framework is Flask, read `references/adapters/flask-patterns.md`.
- If framework is Rails, read `references/adapters/rails-patterns.md`.
- If framework is Vue, read `references/adapters/vue-patterns.md` and select a backend adapter for server routes.
- If framework is unknown or not covered, read `references/adapters/pseudocode-patterns.md` and create a new adapter file.

Governance routing (mandatory in every task):
- `references/governance/env-contract.md`
- `references/governance/error-edge-cases.md`
- `references/governance/account-linking.md`
- `references/governance/testing-validation.md`

## Quick Architecture Router (Use After Discovery)

Once you've completed the Discovery Report and confirmed the provider, use this router to find relevant documentation quickly:

**Backend Architecture**:
- Separate API + frontend → Section 4.2 (JWT) or 4.3 (Sessions)
- Monolithic (Next.js, Rails, Django) → Section 4.3 + framework adapter
- Serverless → Section 4.4 (not yet implemented, use pseudocode patterns)

**Provider Documentation**:
- Confirmed provider → `references/providers/{provider}/CREDENTIALS.md` then `references/providers/{provider}.md`
- Multiple providers → Read multi-provider patterns first

**Account Linking**:
- Have `auth_identities` table → Section 5.1
- Only `users` table → Section 5.2

This router does NOT replace discovery. Always complete the Discovery Report first.

## Forbidden Practices (Explicitly Prohibited)

- Implicit flow or token response in front-channel redirects.
- Skipping `state` or `nonce` validation.
- Wildcard or open redirect URI matching.
- Storing access, refresh, or ID tokens in localStorage or client-side cookies.
- Logging auth codes, tokens, client secrets, or full provider responses.
- Using unverified email claims as proof of identity.
- Reusing sessions across login (no session rotation).
- Committing `.env` files or hardcoding secrets in logic.
- Using the `sub` (subject) claim as a display name (it is an ID, not a name).

## Stop Conditions (Must Ask Clarifying Questions)

Stop and ask before any implementation if any of these are missing:
- Provider client credentials and allowed redirect URIs.
- The app framework and runtime are ambiguous or conflicting.
- Session strategy is unclear (cookie vs server session store).
- Account linking rules are unknown (merge by email or provider id).
- The environment variable system or secrets manager is not defined.
- Secrets Rotation Strategy is undefined (e.g., how to handle old vs new client secrets during a key roll).

## Required Output Structure (Required)

See `references/AGENT_EXECUTION_SPEC.md` for the required output structure (source of truth). Summary:
1. Discovery Report
2. Provider Docs Verification
3. Required Environment Variables
4. Planned File Changes
5. Security Checklist Compliance
6. Implementation Plan
7. Testing Checklist

In Required Environment Variables, always separate backend/server-only vs frontend/public and state who must provide them.

If you cannot comply with the required order, stop and ask for clarification.

## Multi-Provider Invariant

Assume multiple providers will coexist. Design routes, database models, and session logic so adding a second provider does not break the first.

## Documentation Freshness

Provider files are guidance only. You must verify the latest provider docs before coding. If docs conflict, stop and ask.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Babatunde-Fatai](https://github.com/Babatunde-Fatai)
- **Source:** [Babatunde-Fatai/ai-agent-skills-library](https://github.com/Babatunde-Fatai/ai-agent-skills-library)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-babatunde-fatai-ai-agent-skills-library-social-auth-core
- Seller: https://agentstack.voostack.com/s/babatunde-fatai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.