Git Product home page Git Product logo

veraid-authority-js's Introduction

@relaycorp/veraid-authority

npm version

JS client library for the VeraId Authority API.

The latest version can be installed from NPM:

npm install @relaycorp/veraid-authority

Usage

Authentication

You need to refer to the documentation from the Authority server's operator on how to obtain access tokens to interact with the API.

For example, if you were to authenticate using OAuth2 client credentials, you could authenticate as follows:

import { stringify } from 'node:querystring';

import type { AuthorizationHeader } from '@relaycorp/veraid-authority';

const AUTH_ENDPOINT_URL = 'https://auth.example.com/oauth2/token';

export async function authenticate(
  client: string,
  password: string,
): Promise<AuthorizationHeader> {
  const body = {
    grant_type: 'client_credentials',
    client_id: client,
    client_secret: password,
  };
  const response = await fetch(AUTH_ENDPOINT_URL, {
    method: 'POST',
    headers: new Headers([['Content-Type', 'application/x-www-form-urlencoded']]),
    body: stringify(body),
  });
  if (response.status !== 200)
    throw new Error(`Failed to obtain access token (${response.statusText})`);
  }
  const { token_type: scheme, access_token: parameters } = await response.json();
  return { scheme, parameters };
}

Client configuration

You're ready to interact with the Authority API once you've obtained a valid access token: All you need to do is initialise the AuthorityClient class with the URL of the API and the access key you obtained from the appropriate OAuth2 server used by the Authority server. For example:

import { AuthorityClient } from '@relaycorp/veraid-authority';

const API_URL = 'https://veraid-authority.example.com';

export async function makeClient(): Promise<AuthorityClient> {
  const auth = await authenticate(
    process.env.AUTHORITY_CLIENT_ID,
    process.env.AUTHORITY_CLIENT_PASSWORD,
  );
  return new AuthorityClient(API_URL, auth);
}

Keep in mind that, since the client is bound to an access token, you'd need to get a new client once the token expires.

Sending commands

Requests are sent to the Authority API in the form of commands, where each operation on the API is represented by a command in this library. For example, this is how you'd create an organisation:

import { OrgCreationCommand } from '@relaycorp/veraid-authority';

/**
 * Create an organisation with domain `name`.
 * @param name The organisation name (i.e., its domain name).
 * @param client The Authority client to use.
 * @return The URL path to the newly-created organisation
 */
export async function createOrg(name: string, client: AuthorityClient): Promise<string> {
  const command = new OrgCreationCommand({ name });
  const { self } = await client.send(command);
  return self;
}

Deletion operations are implemented with a single command: DeletionCommand. It can be used as follows to delete an organisation, for example:

import { DeletionCommand } from '@relaycorp/veraid-authority';

export async function createAndDeleteOrg(name: string, client: AuthorityClient): Promise<void> {
  const orgEndpoint = await createOrg(name, client);
  const command = new DeletionCommand(orgEndpoint);
  await client.send(command);
}

An error will be thrown if the command failed for whatever reason.

For detailed documentation on all the commands we support, please refer to the API documentation of this library.

API Documentation

The API documentation can be found on docs.relaycorp.tech.

Supported Environments

This library requires Node.js 18 or later because we use the fetch API. Going forward, however, we will follow the Node.js release schedule.

Although not officially supported, this library may also work in the browser.

Contributions

We love contributions! If you haven't contributed to a Relaycorp project before, please take a minute to read our guidelines first.

veraid-authority-js's People

Contributors

dependabot[bot] avatar gnarea avatar relaybot-admin avatar

Stargazers

 avatar

Watchers

 avatar  avatar

veraid-authority-js's Issues

Jest dependencies have incompatible types: `Interface 'JestImportMeta' incorrectly extends interface 'ImportMeta'`

I'm getting the following error when I run tsc:

node_modules/@jest/environment/build/index.d.ts:401:26 - error TS2430: Interface 'JestImportMeta' incorrectly extends interface 'ImportMeta'.
  The types of 'jest.replaceProperty' are incompatible between these types.
    Type '<T extends object, K extends Exclude<keyof T, keyof { [K in keyof T as Required<T>[K] extends ClassLike ? K : never]: T[K]; } | keyof { [K in keyof T as Required<T>[K] extends FunctionLike ? K : never]: T[K]; }>, V extends T[K]>(object: T, propertyKey: K, value: V) => Replaced<...>' is not assignable to type '<T extends object, K extends keyof T>(obj: T, key: K, value: T[K]) => ReplaceProperty<T[K]>'.
      Types of parameters 'propertyKey' and 'key' are incompatible.
        Type 'K' is not assignable to type 'Exclude<keyof T, keyof { [K in keyof T as Required<T>[K] extends ClassLike ? K : never]: T[K]; } | keyof { [K in keyof T as Required<T>[K] extends FunctionLike ? K : never]: T[K]; }>'.
          Type 'keyof T' is not assignable to type 'Exclude<keyof T, keyof { [K in keyof T as Required<T>[K] extends ClassLike ? K : never]: T[K]; } | keyof { [K in keyof T as Required<T>[K] extends FunctionLike ? K : never]: T[K]; }>'.
            Type 'string | number | symbol' is not assignable to type 'Exclude<keyof T, keyof { [K in keyof T as Required<T>[K] extends ClassLike ? K : never]: T[K]; } | keyof { [K in keyof T as Required<T>[K] extends FunctionLike ? K : never]: T[K]; }>'.
              Type 'string' is not assignable to type 'Exclude<keyof T, keyof { [K in keyof T as Required<T>[K] extends ClassLike ? K : never]: T[K]; } | keyof { [K in keyof T as Required<T>[K] extends FunctionLike ? K : never]: T[K]; }>'.

401 export declare interface JestImportMeta extends ImportMeta {

I can see some people on Reddit have experienced the same issue and I've asked on Reactiflux but haven't got an answer yet.

I tried to report this on the Jest project but they require a minimal repo that reproduces the issue, which I tried to create but failed. This is kind of surprising but consistent with the fact that veraid-authority server is using the same Jest deps without issues.

So, to avoid wasting more time on this, I'm working around this issue by creating a TSC config file that excludes test-related files.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.