@av3rgun/authy

Framework-independent client for the XHOST auth service. Requires Axios 1.x.

import axios from 'axios';
import { createAuthClient } from '@av3rgun/authy';

let currentSession = null;
const auth = createAuthClient({
  baseURL: '/api/auth',
  axios,
  session: {
    get: () => currentSession,
    set: (value) => { currentSession = value; },
    clear: () => { currentSession = null; },
  },
  onSessionExpired: (error) => console.log(error.message),
});

await auth.login({ email, password });
const api = axios.create({ baseURL: '/api' });
const detach = auth.attach(api);
await api.get('/accounts');
detach();

Methods: login(credentials), register(payload), refresh(), me(), setMasterDevice({ device_id, device_name }), revoke(refreshToken), logout(), attach(axiosInstance) (returns interceptor cleanup). Registration does not log in. Login and refresh save the full server session, including user fields. Expiry timestamps are Unix seconds. Refresh rotates both tokens and is coalesced per client.

Payloads are plain objects: the library adds { data: payload } and unwraps { status: 'success', body }. Errors are AuthError with code, status, cause. The current server returns messages without machine codes; those errors receive http_401, http_403, etc. Network failures have status: null.

Attach only to trusted API instances: credentials are sent to their requests. Use { authy: false } on an individual request to skip auth/retry. A 401 triggers at most one replay; 403 on resource endpoints does not trigger refresh. A rejected refresh (401/403) clears the session and calls onSessionExpired. Network and 5xx errors keep credentials. Logout clears locally before revoking and still rejects if the revocation failed. In-flight login/refresh cannot restore a logged-out session.

Session callbacks are synchronous. Storage, routing and notifications belong to the application. Prefer memory by default; persistent browser storage exposes tokens to scripts. Refresh coordination is per client, not across browser tabs. The client does not verify JWT signatures; authorization belongs to the backend.

Development

From the monorepo root:

npm install
npm test --workspace @av3rgun/authy
npm run build --workspace @av3rgun/authy
npm pack --workspace @av3rgun/authy
npm run play

Playground uses a local /auth-api proxy to https://id.xho.st; restart Vite after changing AUTHY_AUTH_TARGET. Tokens in the playground stay in memory and are hidden; reloading clears them. Do not use real credentials in shared demos.

When ready to publish, inspect the tarball then run npm publish --workspace @av3rgun/authy --access public. Publication requires ownership of the npm scope. Consumers should pin "@av3rgun/authy": "0.1.0" to use the same version across projects.