@auvexis/accounts

Runtime-agnostic OAuth 2.0/OpenID Connect client for Auvexis Accounts.

Install

npm install @auvexis/accounts

Node.js 20 or newer is required. The SDK is ESM-only and uses standard fetch, URL, and Web Crypto APIs.

Connect an account

import { createAuvexisAccountsClient } from "@auvexis/accounts";

const accounts = createAuvexisAccountsClient({
  clientId: process.env.AUVEXIS_CLIENT_ID!,
  redirectUri: "http://127.0.0.1:23801/oauth/callback",
});

const transaction = await accounts.createAuthorization({
  productSubject: {
    type: "local_profile",
    id: fabricProfileId,
  },
});
// Open transaction.authorizationUrl in the system browser.
// Keep the transaction only in trusted backend memory with a short lifetime.

const tokens = await accounts.exchangeCode({
  callbackUrl,
  transaction,
});
const profile = await accounts.getProfile(tokens.accessToken);

The host application owns browser launching, the loopback callback, transaction lifetime, encrypted token storage, and account-to-local-profile mapping. Tokens must never be returned to an untrusted frontend.

productSubject is optional. Use it when a product links the Auvexis account to a local profile, device, or installation. Accounts receives it as auv_subject_type and auv_subject_id and can enforce product authorization policies such as replacing the previous active local profile for that product.

Refresh and revoke

const rotated = await accounts.refresh(tokens.refreshToken!);
await accounts.revoke(rotated.refreshToken!);

Persist the new refresh token after every successful rotation. Revocation removes remote authorization; deleting local tokens without calling revoke is a local logout.

Account resources

Use the protected account helpers from trusted product backends only. They require the user's Auvexis access token.

const account = await accounts.getAccount(tokens.accessToken);

await accounts.updateAccount(tokens.accessToken, {
  handle: "andredev",
});

const publicProfile = await accounts.getPublicProfile("andredev");

getAccount returns private account data for the current user. getPublicProfile returns only public display data by handle.

Product campaign events

Products can emit trusted events to Accounts so campaigns and badges are processed by the backend, not by local editable state.

await accounts.emitProductEvent(tokens.accessToken, {
  eventId: `fabric.workflow.published:${workflowId}:${account.id}`,
  type: "fabric.workflow.published",
  userId: account.id,
  occurredAt: new Date(),
  evidence: { workflowId },
});

Do not send productId or badge information. Accounts derives the product and account from the OAuth token and validates campaign eligibility server-side.

Products can also ask Accounts for current campaign status before emitting an event. This is an optimization for UX; Accounts still validates the event server-side.

const campaigns = await accounts.getProductCampaignStatuses(
  tokens.accessToken,
  "fabric.workflow.published",
);

const canSkip = campaigns.some(
  (campaign) => campaign.claimed || campaign.capacityReached,
);

Development Accounts server

Production defaults to https://accounts.auvexis.com. Override it explicitly for local development:

const accounts = createAuvexisAccountsClient({
  baseUrl: "http://127.0.0.1:8787",
  clientId: "local-client-id",
  redirectUri: "http://127.0.0.1:23801/oauth/callback",
});

OAuth endpoints are always resolved through Accounts discovery metadata.

Errors

AuvexisAccountsError.code is one of:

• reauth_required: the authorization or refresh token is no longer valid.
• unavailable: Accounts could not be reached or returned a server failure.
• invalid_response: Accounts returned malformed data.
• invalid_request: SDK input is invalid before contacting Accounts.
• oauth_error: Accounts rejected an OAuth or protected-resource request.

Error messages and JSON serialization never include authorization codes or token values.

Badge trust

Profiles and badges returned by the SDK are verified responses from Accounts at request time. A persisted profile snapshot is display-only. Products must validate Accounts online in their backend before mapping badges to capabilities.

License

MIT