Core Types - NEAR Auth

@shared/core holds the small set of TypeScript types shared across every NEAR Auth SDK and provider. It defines the contract each provider implements, the shapes returned by login and signature flows, and a handful of network constants.

@shared/core is an internal package — it is bundled into the published SDKs and providers, not installed on its own. You don’t need it for a normal integration. It’s documented here because these types are the seam you build against when you write a custom provider, or when you want precise types over the values the SDKs hand back.

`IFastAuthProvider`

Every provider — JavascriptProvider, ReactNativeProvider, or one you write yourself — implements this interface. The browser SDK and React SDK accept any IFastAuthProvider, so conforming to it is all a custom provider needs to plug into the rest of the stack.

export interface IFastAuthProvider {
  login(...args: any[]): Promise<LoginResponse>;
  logout(...args: any[]): Promise<void>;
  isLoggedIn(): Promise<boolean>;
  requestTransactionSignature(...args: any[]): Promise<RequestTransactionSignatureResponse>;
  requestDelegateActionSignature(...args: any[]): Promise<RequestDelegateActionSignatureResponse>;
  getSignatureRequest(): Promise<GetSignatureRequestResponse>;
  getPath(): Promise<string>;
}

Method	Returns	Description
`login(...args)`	`Promise<LoginResponse>`	Authenticate the user and return their deterministic identifier.
`logout(...args)`	`Promise<void>`	Clear the current session.
`isLoggedIn()`	`Promise<boolean>`	Whether a user is currently authenticated.
`requestTransactionSignature(...args)`	`Promise<RequestTransactionSignatureResponse>`	Ask the identity provider to authorize signing a transaction, embedding the encoded payload in the JWT.
`requestDelegateActionSignature(...args)`	`Promise<RequestDelegateActionSignatureResponse>`	Same as above for a delegate action (gasless / meta-transaction).
`getSignatureRequest()`	`Promise<GetSignatureRequestResponse>`	Retrieve the pending `SignatureRequest` and its user after a signature flow completes.
`getPath()`	`Promise<string>`	Return the MPC derivation path for the current identity, of the form `{guardId}#{userSubject}`.

The ...args: any[] signatures are intentionally open so each provider can accept its own options (for example the JavaScript provider’s popup/redirect flags). Concrete providers narrow these in their own types — see the JavaScript provider reference for the real parameters.

Response types

The provider methods resolve to a few thin shapes. User is the primitive they all build on.

`User`

The deterministic identifier for an authenticated identity. The same login always resolves to the same userId, which is what lets NEAR Auth derive a stable NEAR key per user.

export type User = {
  userId: string;
};

`LoginResponse`, `RequestTransactionSignatureResponse`, `RequestDelegateActionSignatureResponse`

Each of these is an alias of User — login and both signature-request flows resolve to the identity they acted on.

export type LoginResponse = User;
export type RequestTransactionSignatureResponse = User;
export type RequestDelegateActionSignatureResponse = User;

`GetSignatureRequestResponse`

Returned by getSignatureRequest(). Pairs the authenticated User with the SignatureRequest the provider prepared for the on-chain FastAuth.sign call.

export type GetSignatureRequestResponse = {
  user: User;
  signatureRequest: SignatureRequest;
};

`SignatureRequest`

The data the SDK feeds into the NEAR Auth contract’s sign method. Its fields map directly onto the contract’s sign(guard_id, verify_payload, sign_payload, algorithm) arguments.

export type SignatureRequest = {
  guardId: string;
  verifyPayload: string;
  signPayload: Uint8Array;
  algorithm?: MPCContractAlgorithm;
};

string

The guard identifier — which JWT guard verifies this request on-chain (for the Auth0 flow, the Auth0 guard).

string

The payload to verify — typically the JWT issued by the identity provider, which the guard RS256-verifies before any signature is produced.

Uint8Array

The bytes to sign — the encoded transaction or delegate action.

MPCContractAlgorithm

The signing algorithm the MPC network should use. Optional; defaults are resolved downstream.

Constants & unions

`MPCContractAlgorithm`

The signing algorithms the MPC contract supports.

export type MPCContractAlgorithm = "secp256k1" | "eddsa" | "ecdsa";

This is the on-chain / MPC-facing algorithm union. The SDK-facing signer key type in the browser SDK uses "secp256k1" | "ed25519" for public keys — they describe different layers, so don’t mix them up.

`FastAuthNetwork`

The two supported NEAR networks. Providers and SDKs take this to select endpoints and defaults.

export type FastAuthNetwork = "mainnet" | "testnet";

`FAST_AUTH_AUTH0_DEFAULTS`

Per-network Auth0 defaults, keyed by FastAuthNetwork. Providers fall back to these when you don’t pass an explicit domain or signingAudience.

export const FAST_AUTH_AUTH0_DEFAULTS: Record<FastAuthNetwork, FastAuthAuth0NetworkDefaults> = {
  mainnet: {
    domain: "login.auth.near.org",
    audience: "https://api.auth.near.org",
    signingAudience: "auth0.jwt.fast-auth.near",
  },
  testnet: {
    domain: "login.testnet.fast-auth.com",
    audience: "https://api.testnet.fast-auth.com",
    signingAudience: "auth0.jwt.fast-auth.testnet",
  },
} as const;

The shape of each entry is FastAuthAuth0NetworkDefaults:

Field	Type	Description
`domain`	`string`	The Auth0 tenant domain used for authentication.
`audience`	`string`	The Auth0 API audience.
`signingAudience`	`string`	The audience embedded in signing JWTs — the Auth0 guard account that must appear in the token’s `aud` claim.

These are the same values documented on the testnet and mainnet resource pages. Read them from FAST_AUTH_AUTH0_DEFAULTS instead of hard-coding strings so a network switch stays a one-line change.

Building a custom provider

Because the SDKs depend only on IFastAuthProvider, you can implement your own provider — wrapping a different identity source or auth flow — and pass it straight into FastAuthClient or FastAuthProvider.

import type {
  IFastAuthProvider,
  LoginResponse,
  RequestTransactionSignatureResponse,
  RequestDelegateActionSignatureResponse,
  GetSignatureRequestResponse,
} from "@shared/core";

class MyProvider implements IFastAuthProvider {
  async login(): Promise<LoginResponse> {
    // authenticate the user, then return their deterministic id
    return { userId: "..." };
  }

  async logout(): Promise<void> {
    // clear the session
  }

  async isLoggedIn(): Promise<boolean> {
    return false;
  }

  async requestTransactionSignature(): Promise<RequestTransactionSignatureResponse> {
    return { userId: "..." };
  }

  async requestDelegateActionSignature(): Promise<RequestDelegateActionSignatureResponse> {
    return { userId: "..." };
  }

  async getSignatureRequest(): Promise<GetSignatureRequestResponse> {
    return {
      user: { userId: "..." },
      signatureRequest: {
        guardId: "auth0",
        verifyPayload: "<jwt>",
        signPayload: new Uint8Array(),
      },
    };
  }

  async getPath(): Promise<string> {
    return "auth0#user-subject";
  }
}

Writing a custom provider for a different identity issuer touches on-chain territory — a matching guard has to verify your JWTs. That’s an advanced topic outside the Auth0 happy path; see Protocol → Advanced → Custom issuer and Custom issuer guard before you go down this road.

Next steps

SDK overview

How the SDKs, providers, and core types fit together.

JavaScript provider

The reference IFastAuthProvider implementation for web.

Browser SDK

FastAuthClient and FastAuthSigner, built on these types.

How it works

Where a SignatureRequest goes once it leaves the SDK.

​IFastAuthProvider

​Response types

​User

​LoginResponse, RequestTransactionSignatureResponse, RequestDelegateActionSignatureResponse

​GetSignatureRequestResponse

​SignatureRequest

​Constants & unions

​MPCContractAlgorithm

​FastAuthNetwork

​FAST_AUTH_AUTH0_DEFAULTS

​Building a custom provider

​Next steps

SDK overview

JavaScript provider

Browser SDK

How it works

`IFastAuthProvider`

Response types

`User`

`LoginResponse`, `RequestTransactionSignatureResponse`, `RequestDelegateActionSignatureResponse`

`GetSignatureRequestResponse`

`SignatureRequest`

Constants & unions

`MPCContractAlgorithm`

`FastAuthNetwork`

`FAST_AUTH_AUTH0_DEFAULTS`

Building a custom provider

Next steps