@svelte-atproto/oauth

atproto OAuth for SvelteKit — confidential or loopback OAuth client, with pluggable session storage and slingshot/UFO integration for fast identity + firehose lookups.

pnpm add @svelte-atproto/oauth

For one-shot setup of a fresh SvelteKit project, use the @svelte-atproto/sv add-on:

npx sv add @svelte-atproto

Quick start (manual)

// src/lib/atproto/index.ts
import { createAtprotoAuth } from '@svelte-atproto/oauth/server';
import { cloudflareKV } from '@svelte-atproto/oauth/server/stores/cloudflare';
import { env } from '$env/dynamic/private';

export const atproto = createAtprotoAuth({
  origin: env.ORIGIN,
  cookieSecret: env.COOKIE_SECRET,
  clientAssertionKey: env.CLIENT_ASSERTION_KEY,
  scope: 'atproto',
  sessions: cloudflareKV('OAUTH_SESSIONS'),
  states: cloudflareKV('OAUTH_STATES', { ttl: 600 })
});

// src/hooks.server.ts
import { atproto } from '$lib/atproto';
export const handle = atproto.handle;

// src/app.d.ts
import type { OAuthSession } from '@atcute/oauth-node-client';
import type { Client } from '@atcute/client';
import type { Did } from '@atcute/lexicons';

declare global {
  namespace App {
    interface Locals {
      session: OAuthSession | null;
      client: Client | null;
      did: Did | null;
    }
  }
}
export {};

Generate dev secrets:

npx atproto-oauth setup   # writes COOKIE_SECRET + CLIENT_ASSERTION_KEY into .env

That's it. atproto.handle mounts:

• GET /oauth-client-metadata.json — OAuth client metadata
• GET /oauth/jwks.json — JWKS
• GET /oauth/callback — completes the OAuth round-trip
• POST /oauth/login — start a login (returns { url })
• POST /oauth/logout — revoke + clear cookies

Per request, event.locals.{ did, session, client } is populated for any signed-in user.

Entry points

| Subpath | What it ships | |---|---| | /server | createAtprotoAuth, types — server (confidential / loopback) flow | | /server/stores/memory | memory() | | /server/stores/cloudflare | cloudflareKV(bindingName \| namespace, opts?) | | /server/stores/upstash | upstashRedis({ url, token }) | | /client | login(handle), signup(), logout() — imperative client helpers for the server flow | | /browser | createAtprotoBrowserAuth — full browser-only flow for static-site deploys (GH Pages, etc.) | | /helper | atproto utilities (handle/PDS resolution, listRecords, getRecord, …) | | /bsky | bsky-specific (loadBskyProfile, loadBskyProfiles, CDN URL, …) |

Server API

createAtprotoAuth(config) returns:

atproto.handle                    // mount as your SvelteKit `handle`
atproto.handlers.{metadata,jwks,callback,login,logout}  // raw RequestHandlers
atproto.api.startLogin({ handle, signup?, returnTo? })  // → { url }
atproto.api.logout()              // revokes session + clears cookies
atproto.api.getSession()          // → { did, session, client } from event.locals

Config (selected fields)

| Field | Default | Notes | |---|---|---| | origin | — | Required outside dev. Empty in dev → loopback (http://127.0.0.1:5173) | | cookieSecret | — | Required outside dev. HMAC for signed cookies | | clientAssertionKey | — | JSON-encoded JWK; required when origin is set | | scope | 'atproto' | String or string[]. Use atcute's scope.repo({...}) helpers | | signupPDS | — | Set to a PDS URL to enable signup; unset = signup disabled | | sessions | in-memory | Any Store<Did, StoredSession> | | states | in-memory (10m TTL) | Any Store<string, StoredState> | | redirectPath / metadataPath / jwksPath / loginPath / logoutPath | /oauth/... | Override path defaults |

Helpers (/helper)

Pure atproto utilities — no auth state, no event.locals magic. Pass did explicitly.

| Function | Notes | |---|---| | parseUri(uri) | AT URI → { repo, collection, rkey } | | resolveHandle({ handle, doh?, slingshot? }) | handle → DID | | actorToDid(actor, opts?) | handle or DID → DID | | loadMiniDoc(identifier, opts?) | { did, handle, pds } via slingshot, fallback PLC + describeRepo | | loadHandle(did, opts?) | DID → handle (cached) | | loadHandles(dids, opts?) | parallel batch | | getPDS(did, opts?) | DID → PDS endpoint | | getPDSClient({ did }, opts?) | unauthenticated atcute Client | | listRecords({ did, collection, ... }) | repo records | | getRecord({ did, collection, rkey?, ... }) | single record | | getRecordByUri(uri, opts?) | record by AT URI (slingshot or fallback) | | describeRepo({ did, ... }) | repo metadata | | getBlobURL({ did, blob }) | direct PDS blob URL | | recentRecords(collection, opts?) | recent records by collection from UFO firehose | | countBacklinks(target, source, opts?) | constellation: like-count, follower-count, etc. | | countDistinctBacklinkers(target, source, opts?) | constellation: distinct-DID count | | listBacklinks(target, source, opts?) | constellation: paginated linking records | | listDistinctBacklinkers(target, source, opts?) | constellation: paginated distinct DIDs | | backlinksRollup(target, opts?) | constellation: all sources rolled up | | createTID() | TID rkey | | readThroughCache(cache, key, load) | the generic cache wrapper used internally |

Microcosm services (slingshot / UFO / constellation)

By default, three microcosm-rs services back the helpers (tangled mirror):

| Service | Default URL | Used by | |---|---|---| | Slingshot | slingshot.microcosm.blue | identity (handle ↔ DID ↔ PDS), getRecordByUri | | UFO | ufos-api.microcosm.blue | recentRecords (firehose by collection) | | Constellation | constellation.microcosm.blue | backlinks (likes, follows, replies, …) |

All three default URLs are swappable to a self-hosted instance per call:

loadHandle(did, { slingshot: 'https://my.host' });
recentRecords('xyz.statusphere.status', { ufo: 'https://my.host' });
countBacklinks(uri, source, { constellation: 'https://my.host' });

Slingshot also accepts slingshot: false — disables the call and falls straight through to the PLC + describeRepo fallback (useful when slingshot is degraded for a particular case, or for testing the fallback path). UFO and Constellation have no fallback (no other index gives the same data), so they don't accept false — just don't call them if you don't want firehose / backlinks.

All microcosm calls go through a per-host circuit breaker (3 consecutive failures → 60s open, then half-open) and a 5s request timeout, so an outage fails fast — slingshot skips straight to the fallback, UFO/Constellation return empty/undefined immediately instead of hanging.

Constellation: backlinks

Given a target (AT URI or DID) and a { collection, path } source describing what links you're looking for, Constellation answers "who linked to this":

import { countBacklinks, listDistinctBacklinkers } from '@svelte-atproto/oauth/helper';

// like-count for a post
const likes = await countBacklinks(postUri, {
  collection: 'app.bsky.feed.like',
  path: '.subject.uri'
});

// follower-count for a DID
const followers = await countBacklinks(did, {
  collection: 'app.bsky.graph.follow',
  path: '.subject'
});

// who reposted a post
const page = await listDistinctBacklinkers(postUri, {
  collection: 'app.bsky.feed.repost',
  path: '.subject.uri'
}, { limit: 50 });
const dids = page?.dids ?? [];

backlinksRollup(target) returns a { [collection]: { [path]: { records, distinct_dids } } } rollup of every source pointing at target — handy for a "what does the network say about this" overview.

Browser-only flow (/browser)

For static-site deployments (no server runtime — GitHub Pages, Cloudflare Pages without functions, S3, etc.). Tokens live in browser localStorage, the DPoP key in IndexedDB. The only thing that needs to be served is a prerendered oauth-client-metadata.json.

// src/lib/atproto.ts
import { createAtprotoBrowserAuth } from '@svelte-atproto/oauth/browser';

export const atproto = createAtprotoBrowserAuth({
	origin: 'https://my-app.example',
	scope: 'atproto',
	signupPDS: 'https://pds.rip/' // optional
});

// src/routes/oauth-client-metadata.json/+server.ts
import { atproto } from '$lib/atproto';
import { json } from '@sveltejs/kit';
export const prerender = true;
export const GET = () => json(atproto.metadata);

<!-- src/routes/+layout.svelte -->
<script>
	import { onMount } from 'svelte';
	import { atproto } from '$lib/atproto';
	onMount(() => atproto.init());
</script>

In components:

<script>
	import { atproto } from '$lib/atproto';
	const { user, login, logout } = atproto;
</script>

{#if $user.isInitializing}
	loading…
{:else if $user.isLoggedIn}
	signed in as {$user.did}
	<button onclick={logout}>Sign out</button>
{:else}
	<button onclick={() => login('alice.bsky.social')}>Sign in</button>
{/if}

In dev, the lib uses a loopback client_id automatically — no public URL or metadata route needed for local testing.

atproto.user is a svelte/store Readable so components consume it via $user.x (auto-subscription).

Bsky helpers (/bsky)

Opt-in. Anyone on a custom appview never imports this and pays nothing.

import { loadBskyProfile, loadBskyProfiles, getCDNImageBlobUrl } from '@svelte-atproto/oauth/bsky';

const profile = await loadBskyProfile(did, { cache });
const profiles = await loadBskyProfiles(dids, { cache });  // batched via app.bsky.actor.getProfiles (25/call)
const imgUrl = getCDNImageBlobUrl({ did, blob });

Stores

import { memory } from '@svelte-atproto/oauth/server/stores/memory';
import { cloudflareKV } from '@svelte-atproto/oauth/server/stores/cloudflare';
import { upstashRedis } from '@svelte-atproto/oauth/server/stores/upstash';

Or implement your own — anything matching atcute's Store<K, V> interface works.

cloudflareKV accepts either a binding name (looks it up via getRequestEvent().platform.env) or a KVNamespace directly.

CLI

atproto-oauth setup    # idempotent — generates COOKIE_SECRET + CLIENT_ASSERTION_KEY into .env
atproto-oauth secret   # print a fresh COOKIE_SECRET to stdout
atproto-oauth keygen   # print a fresh CLIENT_ASSERTION_KEY (JWK) to stdout

For production secrets, pipe into your secrets manager:

atproto-oauth secret | wrangler secret put COOKIE_SECRET
atproto-oauth keygen | wrangler secret put CLIENT_ASSERTION_KEY

Status

Pre-1.0. The public API is small and unlikely to churn, but expect breaking changes until stabilized. Issues + PRs welcome at https://github.com/flo-bit/svelte-atproto-oauth.

License

MIT