yapid-js

Official JavaScript SDK for YapID — Anonymous persistent identity for the web.

No email. No password. No tracking. 12 words. That's it.

Install

npm install yapid-js

Quick Start

Frontend (Browser)

<!-- Option 1: Script Tag (no npm needed) -->
<script src="https://id.yaphub.xyz/yapid-button.js"></script>
<yapid-button onlogin="onLogin"></yapid-button>

<script>
function onLogin(session) {
  console.log('Logged in:', session.accountId);
}
</script>

// Option 2: npm
import { YapID } from 'yapid-js';

const client = new YapID();

// Redirect to YapID login
client.login('https://your-site.com/callback');

// After redirect back — get token from URL
const { token, state } = client.getTokenFromUrl();
if (client.verifyState(state)) {
  const session = await client.verify(token);
  console.log(session.accountId);
}

Backend (Node.js)

import { verifyToken, yapidMiddleware } from 'yapid-js/server';

// Single verify
const session = await verifyToken(req.headers.authorization?.replace('Bearer ', ''));
if (session.valid) {
  console.log(session.accountId, session.isPremium);
}

// Express middleware
import express from 'express';
const app = express();

app.use('/api', yapidMiddleware({ required: true }));

app.get('/api/profile', (req, res) => {
  res.json({ user: req.yapid });
});

React

import { useYapID, YapIDProvider, YapIDButton } from 'yapid-js/react';

// Wrap your app
function App() {
  return (
    <YapIDProvider>
      <MyApp />
    </YapIDProvider>
  );
}

// Use the hook
function Profile() {
  const { isLoggedIn, accountId, isPremium, login, logout } = useYapID();

  if (!isLoggedIn) {
    return <button onClick={login}>Sign in with YapID</button>;
  }

  return (
    <div>
      <p>Welcome, {accountId}</p>
      {isPremium && <p>★ Premium</p>}
      <button onClick={logout}>Logout</button>
    </div>
  );
}

// Or just use the pre-built button
function Header() {
  return (
    <YapIDButton
      theme="dark"
      size="medium"
      onLogin={(session) => console.log(session)}
    />
  );
}

API Reference

Client (yapid-js)

| Method | Description | |---|---| | verify(token) | Verify an access token | | login(redirectUrl) | Redirect to YapID login | | getLoginUrl(redirectUrl) | Get login URL without redirecting | | getTokenFromUrl() | Extract token from URL hash after redirect | | verifyState(state) | Verify CSRF state | | getUserInfo(token) | Get user info (OIDC) | | refresh(refreshToken) | Refresh access token | | logout(token) | Logout current session | | logoutAll(token) | Logout from all devices | | status() | Check service status |

Server (yapid-js/server)

| Export | Description | |---|---| | verifyToken(token) | Verify token server-side | | yapidMiddleware(options) | Express.js middleware | | YapIDServer | Server SDK class |

React (yapid-js/react)

| Export | Description | |---|---| | useYapID() | React Hook | | YapIDProvider | Context Provider | | YapIDButton | Pre-built React Button |

Session Object

{
  valid:         boolean,
  sub:           string,   // accountId (UUID)
  accountId:     string,   // alias for sub
  yapid_premium: boolean,
  isPremium:     boolean,  // alias
  yapid_avatar:  string,
  yapid_name:    string | null,
  scope:         string,   // 'openid profile'
  expires_in:    number,   // seconds
  profile: {
    displayName: string | null,
    avatarSeed:  string,
  }
}

Privacy

YapID has a 93% privacy score — higher than any commercial alternative:

| Service | Privacy Score | |---|---| | YapID | 93% | | Wallet Connect | 67% | | Auth0 / Clerk | 41% | | Sign in with Google | 12% |

• ✓ No email required
• ✓ No IP address stored
• ✓ AES-256-GCM session encryption
• ✓ Ed25519 cryptographic signatures
• ✓ SHA-256 wallet hash (server never sees public key)
• ✓ No third-party tracking

License

BSL 1.1 — Source available, commercial competing use restricted for 4 years. Converts to Apache 2.0 in 2030.

Full License