Authentication

Anchor uses @tijs/atproto-oauth for OAuth authentication with AT Protocol.

import { createATProtoOAuth } from "jsr:@tijs/atproto-oauth";
import { SQLiteStorage } from "jsr:@tijs/atproto-storage";

const oauth = createATProtoOAuth({
  baseUrl: "https://dropanchor.app",
  cookieSecret: Deno.env.get("COOKIE_SECRET"),
  mobileScheme: "anchor-app://auth-callback",
  appName: "Anchor Location Feed",
  logoUri: "https://cdn.dropanchor.app/images/anchor-logo.png",
  policyUri: "https://dropanchor.app/privacy-policy",
  sessionTtl: 60 * 60 * 24 * 30, // 30 days for mobile
  storage: new SQLiteStorage(rawDb),
  logger: console,
});

// Mount OAuth routes
app.route("/", oauth.routes);

• COOKIE_SECRET - Session encryption key (32+ characters, cryptographically random)
• ANCHOR_BASE_URL - Override base URL for development

All authenticated endpoints support cookie-based authentication:

Cookie: sid=<session-token>

Alternative Bearer token authentication (for compatibility):

Authorization: Bearer <session-token>

Recommended: Use cookie-based authentication. After OAuth, create an HTTPCookie and add it to HTTPCookieStorage (iOS) or document.cookie (web).

For complete OAuth flow details, mobile integration, security considerations, and implementation examples:

📱 Mobile OAuth Guide (Package documentation)

This guide includes:

• Complete OAuth flow with sequence diagrams
• All API endpoints with request/response schemas
• PKCE implementation details
• Session token format and cookie setup
• Error handling and recovery strategies
• iOS Swift and Android Kotlin examples
• Security best practices

After authentication, use the session cookie to call authenticated endpoints:

curl -X POST "https://dropanchor.app/api/checkins" \
  -b "sid=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"place": {...}, "message": "Great spot!"}'

curl -X DELETE "https://dropanchor.app/api/checkins/did:plc:abc/3k2abc" \
  -b "sid=YOUR_SESSION_TOKEN"

See API Documentation for complete endpoint reference.

The Anchor iOS app uses ASWebAuthenticationSession for OAuth:

1. Load OAuth page: /mobile-auth
2. Complete OAuth: Receive anchor-app://auth-callback?session_token=...
3. Store token: Save to iOS Keychain
4. Create cookie: Add to HTTPCookieStorage for URLSession
5. Make requests: All API calls automatically include cookie

See the Mobile OAuth Guide for implementation details.

• Duration: 30 days
• Refresh: Automatic via backend
• Expiration: User must re-authenticate

const session = await oauth.validateSession(request);
if (!session.valid) {
  // User needs to re-authenticate
}

For local development, override the base URL:

export ANCHOR_BASE_URL=http://localhost:8000

1. Start the backend: deno task dev
2. Visit /mobile-auth in browser
3. Enter test handle: test.bsky.social
4. Complete OAuth flow

• Clear cookies and re-authenticate
• Check COOKIE_SECRET is set correctly
• Verify session hasn't exceeded 30-day TTL

• Verify mobileScheme matches iOS app URL scheme
• Check callback URL format: anchor-app://auth-callback
• Ensure session_token is being stored in Keychain

• Backend handles refresh automatically
• No manual refresh needed for cookie-based auth
• If refresh fails, user must re-authenticate

• Session tokens are sealed with Iron Session encryption
• Cookies use HttpOnly, Secure, and SameSite=Lax flags
• PKCE protects against authorization code interception
• DPoP tokens managed entirely on backend
• No token exposure in mobile app (only sealed session token)

See Security Considerations in the Mobile OAuth Guide.

• @tijs/atproto-oauth Package
• Mobile OAuth Guide
• AT Protocol OAuth
• Anchor iOS App Source