This is not an SDK repo with extras attached.
The SDK is one package of eighteen. So is the backend behind api.oxy.so,
the identity vault people install on their phones, and the OAuth provider third parties integrate against.

---

🔐 One session, every platform A device holds a {deviceId, deviceSecret} pair per origin and mints short lived access tokens by presenting it. The server stores only a hash of the secret. No cookies. No refresh token family. Cold boot restores the session without ever redirecting to a login page.

✍️ Identity you actually own Keys live on the person's device, in Commons. Records are signed client side and chained per subject, so ownership is proven by cryptography rather than granted by us. DIDs resolve at did:web:oxy.so:u:<id>, reversible in both directions.

Map

graph TD
    P["@oxyhq/protocol<br/><i>signed records, canonical JSON</i>"] --> C["@oxyhq/core<br/><i>API client, session engine, crypto</i>"]
    K["@oxyhq/contracts<br/><i>Zod schemas, one source of truth</i>"] --> C
    K --> A["@oxyhq/api<br/><i>api.oxy.so</i>"]
    F["@oxyhq/federation<br/><i>ActivityPub identity</i>"] --> A
    C --> S["@oxyhq/services<br/><i>the single UI SDK</i>"]
    C --> A
    S --> Commons["Commons<br/><i>identity vault</i>"]
    S --> Accounts["Accounts<br/><i>account management</i>"]
    S --> IdP["auth.oxy.so<br/><i>OAuth provider</i>"]
    S --> Console["Console"]
    S --> Inbox["Inbox"]

    style P fill:#440151,stroke:#D26AE7,color:#fff
    style K fill:#440151,stroke:#D26AE7,color:#fff
    style F fill:#440151,stroke:#D26AE7,color:#fff
    style C fill:#5B0A6B,stroke:#D26AE7,color:#fff
    style A fill:#5B0A6B,stroke:#D26AE7,color:#fff
    style S fill:#5B0A6B,stroke:#D26AE7,color:#fff

Loading

🧱 Substrate Package What it is @oxyhq/protocol Signed record envelope, canonical JSON, signing and verification @oxyhq/contracts Contract first API schemas in Zod. Zero React or Expo, so server and clients share one source of truth @oxyhq/federation App agnostic ActivityPub identity and follow layer @oxyhq/core API client, session engine, crypto, types. Node, browsers and React Native 🚀 Server and SDK Package What it is @oxyhq/api The Express backend behind api.oxy.so @oxyhq/services The single UI SDK. Expo, React Native and web through React Native Web @oxyhq/node Self hostable personal data node for a user's own signed records

📱 Applications App What it is Commons Native identity vault. Creation, signed records, domain verification, sign in approvals Accounts Keyless account management: sessions, privacy, settings auth auth.oxy.so, the OAuth authorize and consent provider Console console.oxy.so, application registry and credentials Inbox inbox.oxy.so 🛠 Tooling Package What it is create-oxy-app bun create oxy-app, scaffolds a new app in the canonical shape @oxyhq/app-preset The Oxy distro of Expo: config plugin and Metro, Babel, CSS, ESLint bases @oxyhq/expo-splash Shared native splash toolkit @oxyhq/ship oxy-ship, publishes Expo OTA updates

There is no separate web only auth SDK. Web apps use @oxyhq/services through React Native Web, so every platform shares one provider and one auth UI.

Quick start

bun install && bun run build:all

Requires Node 18+ and Bun 1.3+. Build order comes from the dependency graph: contracts → protocol → core → services → everything else.

React: Expo, React Native, or web

import { OxyProvider, useAuth } from "@oxyhq/services";

function App() {
  return (
    <OxyProvider clientId={process.env.OXY_CLIENT_ID} baseURL="https://api.oxy.so">
      <MyComponent />
    </OxyProvider>
  );
}

function MyComponent() {
  const { user, signIn, isAuthenticated } = useAuth();
  if (!isAuthenticated) return <button onClick={() => signIn()}>Sign in</button>;
  return <p>Welcome, {user?.username}</p>;
}

signIn() opens the in app dialog: the accounts already on this device, plus one Continue with Oxy action. Oxy picks how the request reaches the identity — opening Commons, pushing to it, or showing a QR — instead of asking the person to choose a transport.

Node backends

import { OxyServices, oxyClient } from "@oxyhq/core";

const user = await oxyClient.getUserById("user-id");

const oxy = new OxyServices({ baseURL: "https://api.oxy.so" });
const profile = await oxy.getProfileByUsername("johndoe");

Protect routes with @oxyhq/core/server: createOxyAuthMiddleware, requireOxyAuth, getRequiredOxyUserId, plus safeFetch for SSRF safe outbound requests and createOxyCors for a deny by default CORS policy.

Development commands

bun run build:all   # build every package in dependency order
bun run start       # run the API server
bun run dev         # dev mode across workspaces
bun run test        # tests, turbo dispatches each package's own runner

Packages never re-export from one another. Apps import @oxyhq/services for the provider and UI, @oxyhq/core for types and services, and @oxyhq/contracts for schemas.

Contributing

Issues and pull requests are welcome, especially from people who will tell us when something is badly designed. The mission is not a marketing layer, it is the part we are trying to protect.

_{Apache-2.0 for the SDK packages · AGPL-3.0-only for everything else · The Oxy Collective Inc · LICENSE}