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.
|
A device holds a No cookies. No refresh token family. Cold boot restores the session without ever redirecting to a login page. |
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 |
graph TD
P["@oxy.so/protocol<br/><i>signed records, canonical JSON</i>"] --> C["@oxy.so/core<br/><i>API client, session engine, crypto</i>"]
K["@oxy.so/contracts<br/><i>Zod schemas, one source of truth</i>"] --> C
K --> A["@oxy.so/api<br/><i>api.oxy.so</i>"]
F["@oxy.so/federation<br/><i>ActivityPub identity</i>"] --> A
C --> S["@oxy.so/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
Kaana and Alia are complementary, not interchangeable:
one-shot product AI -> Oxy inference edge -> Kaana (https://kaana.ai)
agent or chat -> Alia -> Oxy inference edge -> Kaana
Kaana executes model requests across providers. Alia owns agents,
conversations, memory, tools and approvals. Provider keys belong only to
Kaana's KMS-encrypted PostgreSQL store, including customer BYOK credentials;
they are never app, Oxy or Alia environment variables. Oxy retains only BYOK
metadata plus an opaque Kaana handle and revision. Kaana's custody source is
merged, while the coordinated Oxy BYOK cut and all production gates remain
pending; this contract is not a production-availability claim. Oxy selects an
exact deploymentId from complete, current routing
evidence: explicit profile priority first, score descending second, and exact
ID UTF-16 code units only as a deterministic tie-break. Names and database row
order never select a route. Kaana emits requests: 1 once per attempted
request. A flat request fee may therefore be prefiltered from the catalogue,
but maxPricePerRequest is decided at the edge from the complete maximum quote
for this request. Within each explicit priority, only cap- and currency-matching
routes survive; score descending and exact ID choose the first survivor. Final
usage reports and partial streamed usage both name that exact deploymentId;
Oxy never infers it from a provider or model name. Catalogue terms are
conservative aggregates across visible deployments, not the terms of a route
chosen by name. See the
canonical request-routing guide.
|
|
There is no separate web only auth SDK. Web apps use
@oxy.so/servicesthrough React Native Web, so every platform shares one provider and one auth UI.
bun install && bun run build:allRequires 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 "@oxy.so/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 "@oxy.so/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 @oxy.so/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 runnerPackages never re-export from one another. Apps import @oxy.so/services for the provider and UI, @oxy.so/core for types and services, and @oxy.so/contracts for schemas.
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.