Clura Documentation

https://<clura-host>/user-login/<appClientId>

https://yourapp.com/callback?id_token=<jwt>&access_token=<jwt>&refresh_token=<opaque>

// Node.js / Express example
app.get("/callback", (req, res) => {
  const { id_token, access_token, refresh_token } = req.query

  // Store refresh_token server-side (httpOnly cookie or encrypted session)
  // Verify id_token or access_token using the JWKS endpoint
})

npm install jwks-rsa jsonwebtoken

import jwt from "jsonwebtoken"
import jwksClient from "jwks-rsa"

const client = jwksClient({
  jwksUri: "https://<clura-host>/.well-known/jwks.json",
  cache: true,
  rateLimit: true,
})

async function verifyAccessToken(token: string) {
  const decoded = jwt.decode(token, { complete: true })
  if (!decoded || typeof decoded === "string") throw new Error("Invalid token")

  const key = await client.getSigningKey(decoded.header.kid)
  return jwt.verify(token, key.getPublicKey(), {
    algorithms: ["RS256"],
    issuer: "https://<clura-host>",
  })
}

{
  sub: "uuid-of-user",        // stable unique user ID — use as primary key
  app_client_id: "uuid",      // your app's client ID
  sid: "uuid-of-session",     // session ID
  iss: "https://<clura-host>",
  iat: 1234567890,
  exp: 1234567890
}

import jwt from "jsonwebtoken"
import jwksClient from "jwks-rsa"

const client = jwksClient({
  jwksUri: "https://<clura-host>/.well-known/jwks.json",
  cache: true,
})

export async function requireAuth(req, res, next) {
  const header = req.headers.authorization
  if (!header?.startsWith("Bearer ")) {
    return res.status(401).json({ message: "Missing token" })
  }
  try {
    const token = header.slice(7)
    const decoded = jwt.decode(token, { complete: true })
    const key = await client.getSigningKey(decoded.header.kid)
    req.user = jwt.verify(token, key.getPublicKey(), {
      algorithms: ["RS256"],
      issuer: "https://<clura-host>",
    })
    next()
  } catch {
    res.status(401).json({ message: "Invalid or expired token" })
  }
}

// Usage
app.get("/api/profile", requireAuth, (req, res) => {
  res.json({ userId: req.user.sub })
})

npm install jose

// middleware.ts
import { NextRequest, NextResponse } from "next/server"
import * as jose from "jose"

const JWKS = jose.createRemoteJWKSet(
  new URL("https://<clura-host>/.well-known/jwks.json")
)

export async function middleware(req: NextRequest) {
  const token = req.cookies.get("access_token")?.value
  if (!token) return NextResponse.redirect(new URL("/login", req.url))

  try {
    await jose.jwtVerify(token, JWKS, { issuer: "https://<clura-host>" })
    return NextResponse.next()
  } catch {
    return NextResponse.redirect(new URL("/login", req.url))
  }
}

export const config = {
  matcher: ["/dashboard/:path*"],
}

POST https://<clura-host>/v1/global-auth/refresh
Content-Type: application/json

{
  "refresh_token": "64-char-hex-string",
  "app_client_id": "your-app-client-id",
  "app_secret": "your-app-secret"
}

{
  "id_token": "eyJ...",
  "access_token": "eyJ...",
  "refresh_token": "new-64-char-hex"
}

{
  "sub": "uuid-of-user",
  "email": "user@example.com",
  "name": "Jane Doe",
  "picture": "https://lh3.googleusercontent.com/...",
  "app_client_id": "uuid-of-your-app",
  "sid": "uuid-of-session",
  "iss": "https://<clura-host>",
  "iat": 1234567890,
  "exp": 1234567890
}

{
  "sub": "uuid-of-user",
  "app_client_id": "uuid-of-your-app",
  "sid": "uuid-of-session",
  "iss": "https://<clura-host>",
  "iat": 1234567890,
  "exp": 1234567890
}

POST /v1/app
Authorization: Bearer <developer-token>
Content-Type: application/json

{
  "name": "My App",
  "redirectUri": "https://yourapp.com/callback"
}

{
  "id": "uuid",
  "appClientId": "uuid",
  "appSecret": "64-char-hex",
  "name": "My App",
  "redirectUri": "https://yourapp.com/callback",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

git clone https://github.com/your-username/clura.git
cd clura
bun install

node -e "
const { generateKeyPairSync } = require('crypto');
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
});
console.log(JSON.stringify(privateKey));
console.log(JSON.stringify(publicKey));
"

DATABASE_URL=postgresql://user:password@localhost:5432/clura
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:8000/v1/auth/google/callback
GLOBAL_REDIRECT_URI=http://localhost:8000/v1/global-auth/callback
JWT_SECRET=a-long-random-string
JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
JWT_KEY_ID=clura-1
JWT_ISSUER=http://localhost:8000
FRONTEND_URL=http://localhost:3000

NEXT_PUBLIC_API_URL=http://localhost:8000

cd server
bunx drizzle-kit generate
bunx drizzle-kit migrate

http://localhost:8000/v1/auth/google/callback
http://localhost:8000/v1/global-auth/callback

bun run dev:server    # API on port 8000
bun run dev:client    # Dashboard on port 3000