For developers

Build an app for the hub.

uffda is a small hub of apps made for friends. Plug your app in and everyone on the hub signs in with one button, and they can use your app from Claude through one connection.

Sign in with uffda

Point at a button, or tab to it, and it winks.

What uffda is.

uffdahub.com is home to a few little apps that friends built for each other, starting with even for splitting bills. People sign in to the hub once with Google and see the apps that are shared with them. Your app can join in three ways.

1

One sign-in

The hub is an OpenID Connect provider. Someone already signed in at the hub comes straight back to your app signed in.

2

The button

A Sign in with uffda button in plain HTML and CSS, with a little wink. No JavaScript, no tracking.

3

Claude

People connect Claude to uffdahub.com/mcp once, and your app's tools show up for everyone who can use your app.

  1. Your appSign in with uffda
  2. /oidc/authorize
  3. uffda hubGoogle, once. Is the app shared with them?
  4. ?code= then /oidc/token
  5. Your appChecks the ID token, starts a session
  1. ClaudeOne connector for every app
  2. uffdahub.com/mcp
  3. uffda hubOnly tools this person may use
  4. hub pass, 60 s
  5. Your appYour /mcp, acting as that person

The button.

The uffda face in a round coin. When someone points at it or tabs to it, the coin rolls back and the face winks: the open eye closes into a curve for half a second, which still reads at 32 pixels. With reduced motion turned on, nothing moves and the eye simply shows closed.

Use it

  1. Add the stylesheet

    Link ours, or copy uffda-button.css from the kit into your app. It's about 6 KB and only styles elements with uffda- classes.

    index.htmlhtml
    <link rel="stylesheet" href="https://uffdahub.com/developers/uffda-button.css">
  2. Paste the button

    Point it at your own route that starts Sign in with uffda. A <button> in a form works the same way.

    sign-in.htmlhtml
    <a class="uffda-btn" href="/auth/uffda">
      <svg class="uffda-coin" viewBox="0 0 64 64" aria-hidden="true" focusable="false"><circle class="uffda-tile" cx="32" cy="32" r="32" fill="#1B2A41"/><g class="uffda-face"><g transform="matrix(.9 0 0 .9 5 1.4)"><path class="uffda-line" d="M18 33V36A14 14 0 0 0 46 36V33" stroke-width="9" fill="none" stroke="#F6F1E7" stroke-linecap="round" stroke-linejoin="round"/><path class="uffda-line" d="M14 21Q20.5 27 27 21" stroke-width="8" fill="none" stroke="#F6F1E7" stroke-linecap="round" stroke-linejoin="round"/><circle class="uffda-open" cx="43" cy="21" r="7" fill="#6FB1DA"/><path class="uffda-shut" d="M36.5 21Q43 27 49.5 21" stroke-width="8" fill="none" stroke="#6FB1DA" stroke-linecap="round" opacity="0"/></g></g></svg>
      <span>Sign in with uffda</span>
    </a>
  3. Pick a size and colour

    Add this classWhat you get
    uffda-l / uffda-s48 px or 32 px tall. The default is 40 px. For anything else, set --uffda-h (32 to 56 px).
    (none)Navy, for light pages
    uffda-whiteWhite with a soft edge, for light pages
    uffda-outlineNavy outline, for light pages and busy backgrounds
    uffda-cream / uffda-outline-creamFor dark pages
    uffda-autoNavy, or cream when the device is in dark mode
    uffda-iconThe coin alone. Keep the words in the span: they are hidden but still read out.
    uffda-wideFills its container, with the words centred
The kit

The zip has the stylesheet, copy-paste snippets for every variant, the coin as SVG, and every button as a static SVG and PNG (1x and 2x) for emails, slides and places that can't run CSS. Download the kit (about 550 KB).

Rules

Do

  • Say “Sign in with uffda”, “Continue with uffda” or “Sign up with uffda”. uffda is always lower case.
  • Make it the same height as the other sign-in buttons next to it.
  • Leave a quarter of the button's height clear around it.
  • Use the coin-only button only where the uffda name is already on screen nearby.

Don't

  • Recolour it, redraw the face or swap in the square logo.
  • Make it smaller than 32 px tall.
  • Add other animation, or take out the reduced-motion rules.
  • Use it for anything except signing in through uffda.

Sign in with uffda.

The hub speaks standard OpenID Connect: the code flow with PKCE, ES256-signed ID tokens, a private id for each person in each app, and back-channel sign-out. Any OIDC library works. The examples below use plain fetch and the jose library for checking tokens, and even's src/uffda.js is a full version with no libraries at all.

Set up your app

  1. List your app on the hub

    Sign in at uffdahub.com, open Your apps and choose List an app. Give it a name, a web address, an icon and a few screenshots, and choose who can see it: only you, certain people, or everyone on the hub.

  2. Ask for sign-in

    A hub admin turns on Sign in with uffda from your app's edit page. Email dev@runflip.com with your app's name and these:

    • Return addresses: your callback, exactly, like https://yourapp.example/auth/uffda/callback. Up to 10. https only, except http://localhost for testing.
    • Sign-out address (optional): where the hub posts a logout token when someone signs out of the hub.
    • Open sign-up (rare): whether anyone with a Google account may join the hub by signing in to your app. Leave it off unless your app is public, like even.
  3. Keep the secret secret

    The hub shows the client id and client secret once. Put both in your app's secrets (even uses UFFDA_CLIENT_ID and UFFDA_CLIENT_SECRET). The hub keeps only a hash of the secret, so a lost secret can't be shown again: an admin makes a new one, and the old one stops working straight away.

Endpoints

Everything is listed at /.well-known/openid-configuration.

EndpointWhat it does
GET /.well-known/openid-configurationDiscovery
GET /.well-known/jwks.jsonThe hub's public signing keys (ES256). Cache them; fetch again for a kid you haven't seen.
GET /oidc/authorizeStarts sign-in. Code flow, PKCE with S256 required.
POST /oidc/tokenSwaps a code or refresh token for tokens. Client secret by HTTP Basic or in the form.
GET /oidc/userinfoWho an access token belongs to, with Authorization: Bearer.
GET /oidc/logoutSigned out of your app; the hub offers to sign out of the hub too.
POST /oidc/claude-offFor a Disconnect button in your app: switches your app off for that person’s Claude. Client secret by HTTP Basic, and sub in the form. They turn it back on from their hub account.
ScopeWhat your app gets
openidsub: a private id for this person in your app. Different in every app, and it never changes.
emailemail and email_verified (always true: the hub only has Google-verified addresses).
profilename and, when they have one, picture (their Google photo).
offline_accessA refresh token, so you can check once a day that they can still use your app.

The flow

  1. Send them to the hub

    Make a PKCE verifier, a state and a nonce, keep them for the callback, and redirect. Add prompt=none to check quietly: someone signed in at the hub comes straight back with a code, anyone else comes back with error=login_required and you show your own sign-in page.

    src/signin.jsjs
    // GET /auth/uffda on your app: send the person to the hub.
    const HUB = 'https://uffdahub.com';
    const RETURN = 'https://yourapp.example/auth/uffda/callback'; // exactly as registered
    
    const b64u = (bytes) => btoa(String.fromCharCode(...bytes))
      .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
    const random = () => b64u(crypto.getRandomValues(new Uint8Array(32)));
    
    export async function startSignIn(env) {
      const verifier = random(), state = random(), nonce = random();
      const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
    
      const url = new URL(`${HUB}/oidc/authorize`);
      url.search = new URLSearchParams({
        response_type: 'code',
        client_id: env.UFFDA_CLIENT_ID,
        redirect_uri: RETURN,
        scope: 'openid email profile offline_access',
        state,
        nonce,
        code_challenge: b64u(new Uint8Array(digest)), // PKCE, S256 only
        code_challenge_method: 'S256',
      });
    
      // Keep verifier, state and nonce for the callback: a short-lived,
      // HTTP-only, Secure cookie (or your own session store).
      const saved = encodeURIComponent(JSON.stringify({ verifier, state, nonce }));
      return new Response(null, {
        status: 302,
        headers: {
          Location: url.toString(),
          'Set-Cookie': `uffda_signin=${saved}; Path=/auth/uffda; Max-Age=600; HttpOnly; Secure; SameSite=Lax`,
        },
      });
    }
  2. They sign in at the hub

    If they aren't signed in yet, they sign in with Google. The hub checks that your app is shared with them; if it isn't, the hub tells them so on its own page. For apps a hub admin doesn't own, it asks them once whether to share their name and email with you, and a no comes back as error=access_denied. Otherwise it sends them back with code, state and iss.

  3. Swap the code and check the ID token

    Within 60 seconds, and only once. The ID token lives 5 minutes: check that it's ES256 from the hub's keys, header typ is JWT, iss is https://uffdahub.com, aud is your client id, it hasn't expired, and nonce matches.

    src/signin.jsjs
    // GET /auth/uffda/callback?code=...&state=...&iss=https://uffdahub.com
    import { createRemoteJWKSet, jwtVerify } from 'jose';
    
    const JWKS = createRemoteJWKSet(new URL('https://uffdahub.com/.well-known/jwks.json'));
    
    export async function finishSignIn(request, env, saved) {
      const q = new URL(request.url).searchParams;
      if (q.get('error')) return showError(q.get('error'));         // access_denied, login_required...
      if (q.get('state') !== saved.state) return showError('state');
      if (q.get('iss') !== 'https://uffdahub.com') return showError('iss');
    
      // Swap the code within 60 seconds. It works once.
      const res = await fetch('https://uffdahub.com/oidc/token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          Authorization: 'Basic ' + btoa(`${env.UFFDA_CLIENT_ID}:${env.UFFDA_CLIENT_SECRET}`),
        },
        body: new URLSearchParams({
          grant_type: 'authorization_code',
          code: q.get('code'),
          redirect_uri: RETURN,
          code_verifier: saved.verifier,
        }),
      });
      if (!res.ok) return showError('token');
      const tokens = await res.json(); // id_token, access_token, refresh_token
    
      const { payload } = await jwtVerify(tokens.id_token, JWKS, {
        issuer: 'https://uffdahub.com',
        audience: env.UFFDA_CLIENT_ID,
        algorithms: ['ES256'],
        typ: 'JWT',
      });
      if (payload.nonce !== saved.nonce) return showError('nonce');
    
      const user = await findOrLinkUser(env, payload); // see "Linking accounts"
      return startYourSession(user, tokens.refresh_token);
    }
    The same swap with curlsh
    curl https://uffdahub.com/oidc/token \
      -u "$UFFDA_CLIENT_ID:$UFFDA_CLIENT_SECRET" \
      -d grant_type=authorization_code \
      -d code="$CODE" \
      -d redirect_uri=https://yourapp.example/auth/uffda/callback \
      -d code_verifier="$VERIFIER"
    What comes backjson
    {
      "token_type": "Bearer",
      "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...",
      "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
      "expires_in": 600,
      "refresh_token": "...",
      "scope": "openid email profile offline_access"
    }
    Inside the ID tokenjson
    {
      "iss": "https://uffdahub.com",
      "aud": "your-client-id",
      "sub": "k3v9q2...",            // private to your app, never changes
      "iat": 1795000000,
      "exp": 1795000300,             // 5 minutes
      "azp": "your-client-id",
      "nonce": "the nonce you sent",
      "email": "sam@example.com",    // with the email scope
      "email_verified": true,
      "name": "Sam Rivera",          // with the profile scope
      "picture": "https://lh3.googleusercontent.com/..."
    }
  4. Check in once a day

    Refresh tokens last 60 days and rotate: each one works once and a new one comes back. invalid_grant means the person can't use your app any more, or signed out of the hub, so end their session. even checks once a day.

    src/session.jsjs
    // Once a day: is this person still allowed in?
    const res = await fetch('https://uffdahub.com/oidc/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Authorization: 'Basic ' + btoa(`${env.UFFDA_CLIENT_ID}:${env.UFFDA_CLIENT_SECRET}`),
      },
      body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: session.refresh }),
    });
    if (res.status === 400 && (await res.json()).error === 'invalid_grant') {
      return endSession(session); // lost access, or signed out of the hub
    }
    session.refresh = (await res.json()).refresh_token; // each one works once

Linking accounts

If your app already has accounts, the first sign-in through the hub needs to find the right one. Look the person up by sub first. If there's no match, match by email, but only when email_verified is true, and save the sub on that account. From then on, sub is what counts, so a later email change at Google doesn't move anyone's data. Refuse an account that's already linked to a different sub.

src/accounts.jsjs
// The first time someone arrives through the hub, find their account by sub,
// then by a verified email, and save the sub on it. After that, sub is what counts.
async function findOrLinkUser(env, claims) {
  const bySub = await db.userBySub(claims.sub);
  if (bySub) return bySub;

  if (!claims.email || claims.email_verified !== true) throw new Error('No verified email');
  const byEmail = await db.userByEmail(claims.email.toLowerCase());
  if (byEmail?.uffda_sub && byEmail.uffda_sub !== claims.sub) {
    throw new Error('That account is already linked to another uffda account');
  }
  if (byEmail) return db.setSub(byEmail.id, claims.sub);
  return db.createUser({ sub: claims.sub, email: claims.email, name: claims.name });
}

Signing out

  • Your Sign out button: end your own session, then send the browser to /oidc/logout with your client_id and a post_logout_redirect_uri on the same site as one of your return addresses. The hub asks whether to sign out of the hub too, then sends them back.
  • Signed out at the hub: the hub signs them out of every app. It posts a logout_token to your sign-out address, and their refresh tokens stop working. Check the token like an ID token, except the header typ is logout+jwt, it has the back-channel logout event and no nonce. End every session for that sub and answer 200.
src/signout.jsjs
// POST /auth/uffda/logout: the hub says someone signed out of the hub.
export async function backChannelLogout(request, env) {
  const form = await request.formData();
  try {
    const { payload } = await jwtVerify(String(form.get('logout_token')), JWKS, {
      issuer: 'https://uffdahub.com',
      audience: env.UFFDA_CLIENT_ID,
      algorithms: ['ES256'],
      typ: 'logout+jwt',
    });
    const event = 'http://schemas.openid.net/event/backchannel-logout';
    if (!payload.sub || 'nonce' in payload || !payload.events?.[event]) throw new Error();
    await endEverySessionFor(payload.sub);
    return new Response(null, { status: 200 });
  } catch {
    return new Response('Bad logout token', { status: 400 });
  }
}

// Your own Sign out button: end your session, then let the hub ask about the hub.
const out = new URL('https://uffdahub.com/oidc/logout');
out.searchParams.set('client_id', env.UFFDA_CLIENT_ID);
out.searchParams.set('post_logout_redirect_uri', 'https://yourapp.example/login?out=1');

Claude and MCP.

The hub runs one MCP server, the gateway at https://uffdahub.com/mcp. People connect Claude to it once. From then on Claude sees the tools of every app they can use, and the hub forwards each call to the right app as the right person.

How the gateway works

  1. Claude connects once

    With OAuth, at the hub. The person sees which of their apps Claude will be able to use, and chooses Allow.

  2. Each person gets their own tool list

    tools/list shows only tools from apps this person can see right now and hasn't switched off on their account page. Each tool is named after its app (even's split_balances becomes even_split_balances) and keeps the description an admin approved, not whatever the app says today.

  3. Every call is checked again

    On tools/call the hub looks the tool up in this person's list again, so access taken away an hour ago is gone now. Who is calling comes only from the signed-in connection, never from the tool's arguments.

  4. Your app gets a hub pass

    The hub calls your MCP address with a hub pass: a token it signs that names your app and this person's private id for it, and lasts 60 seconds. Your app does the work as that person and answers.

  5. The call is logged

    Which app, which tool, when, and whether it worked. Kept 90 days. What was asked and answered is never logged.

Reads and Makes changes

Tools marked readOnlyHint: true show as Reads on the hub. Everything else shows as Makes changes, and the gateway tells Claude to ask the person before using a tool that changes data. Mark your tools honestly: the hub passes readOnlyHint, destructiveHint, idempotentHint and openWorldHint through to Claude.

Your MCP endpoint

Run an MCP server over Streamable HTTP at an https address, like https://yourapp.example/mcp. The hub sends one JSON-RPC message per POST, with MCP-Protocol-Version: 2025-06-18 and Accept: application/json, text/event-stream. Answer with plain JSON or an SSE stream. It needs tools/list and tools/call.

Accept the hub pass in Authorization: Bearer. Check it like an ID token, with the header typ set to hub-pass+jwt and no nonce. Also check that scope is mcp, that it lives 60 seconds at most (exp - iat), and that you haven't seen its jti before. Act only as the person in sub. The pass also has app (your app's page name on the hub) and, if they've been shared with you, email and name.

src/mcp.jsjs
// POST /mcp on your app. Every call from the hub carries a hub pass.
const seen = new Map(); // jti -> expiry. Use KV or a table if you run more than one instance.

export async function mcp(request, env) {
  const auth = request.headers.get('Authorization') || '';
  let pass;
  try {
    ({ payload: pass } = await jwtVerify(auth.replace(/^Bearer /, ''), JWKS, {
      issuer: 'https://uffdahub.com',
      audience: env.UFFDA_CLIENT_ID,
      algorithms: ['ES256'],
      typ: 'hub-pass+jwt',
    }));
  } catch {
    return new Response('Unauthorized', { status: 401 });
  }
  if (pass.scope !== 'mcp' || pass.exp - pass.iat > 60 || 'nonce' in pass) {
    return new Response('Unauthorized', { status: 401 });
  }
  if (seen.has(pass.jti)) return new Response('Already used', { status: 401 });
  seen.set(pass.jti, pass.exp);

  const user = await db.userBySub(pass.sub);    // act as this person, and only them
  const msg = await request.json();             // one JSON-RPC message
  return Response.json(await handle(msg, user)); // plain JSON is fine; SSE works too
}
Limit
Tools per app50
Tool namesLetters, digits, _ and -, up to 48 characters
DescriptionsUp to 2,000 characters; titles up to 80
Answer size256 KB per call
Time to answer25 seconds

Loading your tools

Once sign-in is on, an admin puts your MCP address on your app's edit page, under Claude, and chooses Save and load tools. The hub calls tools/list once and pins what it gets: names, titles, descriptions, input schemas and hints. Claude only ever sees the pinned version, so a change in your app reaches Claude only when an admin loads the tools again. Ask for that when you add or change a tool.

Your tools/list answerjson
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_balances",
        "title": "Check balances",
        "description": "What you and each friend owe each other, in dollars.",
        "inputSchema": { "type": "object", "properties": {} },
        "annotations": { "readOnlyHint": true }
      },
      {
        "name": "add_expense",
        "title": "Add an expense",
        "description": "Adds a shared cost and splits it.",
        "inputSchema": {
          "type": "object",
          "properties": { "text": { "type": "string" } },
          "required": ["text"]
        },
        "annotations": { "readOnlyHint": false, "destructiveHint": false }
      }
    ]
  }
}

Adding uffda to Claude

This is the part for the people using your app, so it's worth a line in your own help pages.

  1. Add a custom connector

    In Claude's connector settings, add a custom connector with the address https://uffdahub.com/mcp.

  2. Sign in and allow

    Claude opens the hub. Sign in, check the list of apps, and choose Allow.

  3. Choose apps

    Any app can be switched off for Claude on the hub's account page, under Claude. New apps that are shared with you show up by themselves.

Security and data.

What your app receives

A private sub for each person, different in every app, so apps can't match people across the hub. Email, name and picture only with those scopes, and only after the person agrees, unless a hub admin owns the app.

Short-lived tokens

Codes last 60 seconds and work once. ID tokens last 5 minutes, access tokens 10 minutes and hub passes 60 seconds. Refresh tokens last 60 days and rotate on every use.

Secrets

Client secrets and session tokens are stored only as hashes. Tokens are signed with ES256 and the hub's public keys are at /.well-known/jwks.json.

The call log

For each Claude call: who, which app, which tool, when, and whether it worked. Kept 90 days. Never the question or the answer.

Who can get in

The hub is invite-only, unless an admin turns on open sign-up for an app. People sign in to your app only if it's shared with them on the hub, or you own it.

Results are data

The gateway tells Claude to treat what your tools return as information from your app, never as instructions, and not to use one app's results to drive another app.

The full details are in our privacy policy and terms of service. If your app collects something new about people, say so in your own privacy notice.

Questions.

Can anyone add an app?

Anyone on the hub can list an app and choose who sees it. Turning on Sign in with uffda and Claude is done by a hub admin, so email dev@runflip.com when you're ready.

Do I need a library?

No. Any OpenID Connect client works, and so does plain fetch plus WebCrypto: even does it in about 230 lines with no dependencies. A library like jose saves you writing the token checks.

Can I try it on my own computer?

Yes. A return address can be http://localhost, so add your local callback next to the real one.

What happens if my app isn't shared with someone?

The hub stops them on its own page and tells them to ask the app's owner to share it. With prompt=none they come back to your callback with error=access_denied instead.

Can people sign in without Google?

Not yet. The hub uses Google for now, and sign-in by email code may come later.

Does my app still need its own sign-out?

Yes. Your app keeps its own sessions. The hub tells you when someone signs out of the hub, and your refresh check catches anyone who lost access.

Why didn't Claude pick up my new tool?

The hub pins your tools when an admin loads them. Ask for Save and load tools again after you change them.

Does the hub see my app's data?

Tool calls pass through the hub on their way to Claude, but the hub doesn't keep them. It logs only which app and tool, when, and whether it worked.

Can I change the button's colours?

Please don't. Pick the navy, white, cream or outline style that fits your page. If none of them works, email us.

Ready to plug in.

Email dev@runflip.com with your app's name and return address, and we'll turn on sign-in.

Sign in with uffda