Spider Weave

The spider doesn't rush. It spins one thread at a time, anchoring each carefully before moving to the next. The web grows organically—radial strands first, then the spiral, each connection tested for strength. When complete, the web catches what matters while letting the wind pass through. Authentication woven this way is strong, resilient, and beautiful in its structure.

When to Activate

User asks to "add auth" or "set up authentication"
User says "protect this route" or "add login"
User calls /spider-weave or mentions spider/auth
Integrating OAuth (Google, GitHub, etc.)
Setting up session management
Protecting API routes
Adding role-based access control (RBAC)
Implementing PKCE flow
Connecting to Heartwood (GroveAuth)

Pair with: raccoon-audit for security review, beaver-build for auth testing

The Weave

SPIN --> CONNECT --> SECURE --> TEST --> BIND
  |         |          |          |        |
Create    Link       Harden    Verify   Lock In
Threads  Strands     Knots      Web    Security

Phase 1: SPIN

The spider spins the first thread, anchoring it carefully in the corner of the frame...

Create the foundational auth structure. Choose a pattern, scaffold the files, define the schema, and wire environment variables before writing a line of logic.

Choose the auth pattern: Session, JWT, OAuth 2.0, PKCE, or API Keys — based on app type and user needs
Scaffold src/lib/auth/ with index.ts, types.ts, session.ts, middleware.ts, pkce.ts, client.ts
Define the users and sessions tables in the database schema
Set required environment variables: client IDs, secrets, authorize/token/userinfo URLs, redirect URI, session secret

Reference: Load references/oauth-pkce-flow.md for PKCE setup code, database schema, env var list, and the full file structure

Phase 2: CONNECT

Thread connects to thread, the web taking shape across the frame...

Link the auth system together: implement the OAuth login redirect, the callback handler, user upsert, and session creation. Then wire up the client-side auth store.

Implement the login route: generate PKCE verifier + challenge, set cookies, redirect to provider
Implement the callback route: verify state, exchange code for tokens, fetch userinfo, upsert user, create session, clean up PKCE cookies
Build session creation (createSession), validation (validateSession), and invalidation (invalidateSession)
Set up the client-side auth store with loadUser() for reactive auth state in Svelte

Reference: Load references/oauth-pkce-flow.md for the complete login and callback route implementations, and references/session-management.md for session functions and the auth store

Phase 3: SECURE

The spider tests each knot, tightening what holds loose, cutting what doesn't belong...

Harden the authentication system before trusting it with users. Add route protection, security headers, CSRF validation, and rate limiting.

Implement requireAuth() middleware that validates sessions in hooks.server.ts
Implement requireRole(allowedRoles) for RBAC — 403 on unauthorized access
Set security headers on every response: X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Content-Security-Policy
Add CSRF origin validation for state-changing endpoints
Add rate limiting: 5 attempts per 15 minutes per IP on auth endpoints

Reference: Load references/route-protection.md for middleware code and RBAC patterns, and references/security-headers.md for headers, CSRF, rate limiting, and Cloudflare edge rules

Phase 4: TEST

The spider plucks the strands, verifying each vibrates true at the right frequency...

Test authentication thoroughly across the happy path, security edge cases, and failure modes. Automated tests catch regressions; security tests verify the knots hold.

Test the full OAuth flow: redirects with PKCE challenge, callback handling, session creation
Test route protection: unauthenticated redirect, authenticated access, role enforcement
Test security properties: CSRF state rejection, secure cookie attributes, session fixation prevention
Cover failure modes: expired sessions, invalid codes, denied OAuth permissions

Reference: Load references/oauth-pkce-flow.md for OAuth flow tests and references/route-protection.md for route protection test suite

Phase 5: BIND

The web is complete, every strand bound tight, the whole stronger than the sum of its threads...

Finalize and lock in the authentication. Polish the user experience, configure monitoring, and produce the completion report.

Verify the integration checklist: login, logout, protected routes, session expiry, error handling, rate limiting, CSRF, headers, cookies
Add login UI loading and error states with proper aria-busy and role="alert" attributes
Configure auth event logging (userId, provider, IP — never tokens or passwords)
Alert on suspicious activity (10+ failed attempts from same identifier)
Generate the completion report: provider, flow type, files created, security features confirmed, test counts

Reference: Load references/session-management.md for the full integration checklist, login UI snippet, monitoring patterns, and completion report template. Load references/heartwood-integration.md for Grove-specific logout flow and role assignment.

Reference Routing Table

Phase	Reference	Load When
SPIN	`references/oauth-pkce-flow.md`	Always — foundation code lives here
CONNECT	`references/oauth-pkce-flow.md` + `references/session-management.md`	Implementing login/callback/session
SECURE	`references/route-protection.md` + `references/security-headers.md`	Adding middleware, headers, rate limiting
TEST	`references/oauth-pkce-flow.md` + `references/route-protection.md`	Writing auth and route tests
BIND	`references/session-management.md` + `references/heartwood-integration.md`	Finalizing, logging, reporting
Grove/Heartwood	`references/heartwood-integration.md`	Any Grove ecosystem integration

Spider Rules

Patience

Weave one thread at a time. Don't rush to connect everything at once. Each strand must be secure before adding the next.

Precision

Small mistakes in auth have big consequences. Verify every redirect, check every token, validate every session.

Completeness

A web with holes catches nothing. Test the error paths, the edge cases, the failure modes. Security is only as strong as the weakest strand.

Communication

Use weaving metaphors:

"Spinning the threads..." (creating foundations)
"Connecting the strands..." (linking components)
"Testing the knots..." (security hardening)
"The web holds..." (verification complete)

Anti-Patterns

The spider does NOT:

Store passwords in plain text (ever)
Skip PKCE in OAuth flows
Trust user input without validation
Leave default secrets in configuration
Ignore session expiration
Log sensitive data (tokens, passwords)
Reflect redirect_uri or next parameters without validation (open redirect)
Assign admin roles via OAuth claims (manual DB assignment only)

Example Weave

User: "Add GitHub OAuth login"

Spider flow:

SPIN — "Create OAuth app in GitHub, generate client credentials, set up PKCE utilities, create auth endpoints structure"
CONNECT — "Implement /auth/github/login redirect, /auth/github/callback handler, user upsert logic, session creation"
SECURE — "Add CSRF state validation, secure cookie settings, rate limiting on auth endpoints, role assignment for new users"
TEST — "Test OAuth flow, callback handling, session creation, protected route access, error cases (denied permissions)"
BIND — "Add login button to UI, error state handling, loading states, documentation, monitoring"

Quick Decision Guide

Situation	Approach
Simple app, internal users	Session-based auth
Public app, social login	OAuth 2.0 + PKCE
API for mobile/SPA	JWT with refresh tokens
Service-to-service	API keys with IP allowlist
Grove ecosystem	Heartwood integration (load `references/heartwood-integration.md`)

Integration with Other Skills

Before Weaving:

eagle-architect — For auth system design decisions
swan-design — For auth flow specifications

During Weaving:

elephant-build — For multi-file auth implementation
raccoon-audit — For security review

After Weaving:

beaver-build — For auth testing
turtle-harden — For defense-in-depth hardening beyond the web
deer-sense — For accessibility audit of login UI

A well-woven web catches intruders while letting friends pass through.

spider-weave