Options
All
  • Public
  • Public/Protected
  • All
Menu

Module @textile/security

Security (security)

Common types/interfaces for Textile security including authentication and authorization.

Textile License npm (scoped)

This sub-package is part of js-threads. See the top-level documentation for details.

Index

Type aliases

APISig

APISig: { msg: string; sig: string }

Create an API signature for use in authenticated systems. Generate with createAPISig.

example

Import

import {APISig} from '@textile/threads';
param

The signature of the authentication message.

param

The authentication message.

Type declaration

  • msg: string
  • sig: string

KeyInfo

KeyInfo: { key: string; secret?: undefined | string }

KeyInfo is a type that contains the API Secret. It should never be shared in insecure environments. Type 0=ACCOUNT, 1=USER.

example

Import

import {KeyInfo} from '@textile/threads';
param

API key. Can be embedded/shared within an app.

param

User group/account secret. Should not be embedded/shared publicly.

Type declaration

  • key: string

    API key. Can be embedded/shared within an app.

  • Optional secret?: undefined | string

    User group/account secret. Should not be embedded/shared publicly.

UserAuth

UserAuth: { key: string; msg: string; sig: string; token?: undefined | string }

UserAuth is a type describing the minimal requirements create a session from a user group key. Generate with createUserAuth.

Optional token generated by Client.getToken or Client.getTokenChallenge.

example

Import

import {UserAuth} from '@textile/threads';
param

API key. Can be embedded/shared within an app.

param

The signature of the authentication message.

param

The authentication message.

param

User verification token generated by Client.getToken or Client.getTokenChallenge.

Type declaration

  • key: string
  • msg: string
  • sig: string
  • Optional token?: undefined | string

Variables

Const expirationError

expirationError: Error = new Error("Auth expired. Consider calling withKeyInfo or withAPISig to refresh.")

expirationError is an error your app will receive anytime your credentials have expired.

Functions

createAPISig

  • createAPISig(secret: string, date?: Date): Promise<APISig>
  • createAPISig generates an authorization signature and message only.

    This function should NOT be used client-side, as it requires a key secret.

    example

    Basic usage

    import {createAPISig, APISig} from '@textile/threads'
    
    async function sign (key: string) {
      const sig: APISig = await createAPISig(key)
      return sig
    }

    Parameters

    • secret: string

      The key secret to generate the signature. See KeyInfo for details.

    • Default value date: Date = new Date(Date.now() + 1000 * 60)

      An optional future Date to use as signature message. Once date has passed, this authorization signature and message will expire. Defaults to one minute from Date.now.

    Returns Promise<APISig>

createUserAuth

  • createUserAuth(key: string, secret: string, date?: Date, token?: undefined | string): Promise<UserAuth>
  • Generate a UserAuth containing API key, signature, and message.

    The gRPC APIs will throw (or return an authorization error) if the message date has passed. This function should NOT be used client-side, as it requires a key secret. The result does not contain the secret and therefor CAN be used client side.

    example

    Create a new UserAuth

    import {createUserAuth, KeyInfo, UserAuth} from '@textile/threads';
    
    async function auth (keyInfo: KeyInfo) {
      // Create an expiration and create a signature. 60s or less is recommended.
      const expiration = new Date(Date.now() + 60 * 1000)
      // Generate a new UserAuth
      const userAuth: UserAuth = await createUserAuth(keyInfo.key, keyInfo.secret ?? '', expiration)
      return userAuth
    }

    Parameters

    • key: string

      The API key secret to generate the signature. See KeyInfo for details.

    • secret: string

      The API key secret to generate the signature. See KeyInfo for details.

    • Default value date: Date = new Date(Date.now() + 1000 * 60)

      An optional future Date to use as signature message. Default 1 minute from now.

    • Optional token: undefined | string

      An optional user API token.

    Returns Promise<UserAuth>