1.5.0-manage-PinChallenge

PinChallenge

Article summary

Did you find this summary helpful?

Thank you for your feedback!

PinChallenge Module 1.5.0 | Manage SDK

Usage

To use the PinChallenge module, you can import it into your project from the Firebolt SDK:

import { PinChallenge } from '@firebolt-js/manage-sdk'

Overview

A module for registering as a provider for a user grant in which the user is prompted for a pin for access to a capability

Methods

provide

To provide a specific capability to the platform. See Provider Interfaces for a list of interfaces available to provide in this module.

provide(capability: string, provider: any): void

Parameters:

Param	Type	Required	Summary
`capability`	`string`	Yes	The capability that is being provided.
`provider`	`any`	Yes	An implementation of the required interface.

See Provider Interfaces for each capabilities interface definition.

Private Methods

View

challengeError

This is a private RPC method.

Internal API for Challenge Provider to send back error.

Parameters:

Param	Type	Required	Description
`correlationId`	`string`	true
`error`	`object`	true

Result:

Capabilities:

Role	Capability
provides	xrn:firebolt:capability:usergrant:pinchallenge

Examples

Example 1

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "PinChallenge.challengeError",
  "params": {
    "correlationId": "123",
    "error": {
      "code": 1,
      "message": "Error"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

challengeFocus

This is a private RPC method.

Internal API for Challenge Provider to request focus for UX purposes.

Result:

Capabilities:

Role	Capability
provides	xrn:firebolt:capability:usergrant:pinchallenge

Examples

Example

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "PinChallenge.challengeFocus",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

challengeResponse

This is a private RPC method.

Internal API for Challenge Provider to send back response.

Parameters:

Param	Type	Required	Description
`correlationId`	`string`	true
`result`	`PinChallengeResult`	true

Result:

Capabilities:

Role	Capability
provides	xrn:firebolt:capability:usergrant:pinchallenge

Examples

Example #1

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "PinChallenge.challengeResponse",
  "params": {
    "correlationId": "123",
    "result": {
      "granted": true,
      "reason": "correctPin"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

Example #2

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "PinChallenge.challengeResponse",
  "params": {
    "correlationId": "123",
    "result": {
      "granted": false,
      "reason": "exceededPinFailures"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

Example #3

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "PinChallenge.challengeResponse",
  "params": {
    "correlationId": "123",
    "result": {
      "granted": null,
      "reason": "cancelled"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

Private Events

View

onRequestChallenge

This is a private RPC method.

Registers as a provider for when the user should be challenged in order to confirm access to a capability through a pin prompt

Parameters:

Param	Type	Required	Description
`listen`	`boolean`	true

Result:

PinChallengeProviderRequest

Capabilities:

Role	Capability
provides	xrn:firebolt:capability:usergrant:pinchallenge

Examples

Default Example

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "PinChallenge.onRequestChallenge",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "correlationId": "abc",
    "parameters": {
      "capability": "xrn:firebolt:capability:commerce::purchase",
      "requestor": {
        "id": "ReferenceApp",
        "name": "Firebolt Reference App"
      },
      "pinSpace": "purchase"
    }
  }
}

Provider Interfaces

ChallengeProvider

The provider interface for the xrn:firebolt:capability:usergrant:pinchallenge capability.

Usage:

PinChallenge.provide('xrn:firebolt:capability:usergrant:pinchallenge', provider: ChallengeProvider | object)

Examples

Register your app to provide the xrn:firebolt:capability:usergrant:pinchallenge capability.

import { PinChallenge } from '@firebolt-js/manage-sdk'

class MyChallengeProvider {
  async challenge(parameters, session) {
    return {
      granted: true,
      reason: 'correctPin',
    }
  }
}

PinChallenge.provide(
  'xrn:firebolt:capability:usergrant:pinchallenge',
  new MyChallengeProvider(),
)

JSON-RPC

Register to recieve each provider API

Request:

{
  "id": 1,
  "method": "PinChallenge.onRequestChallenge",
  "params": {
    "listen": true
  }
}

Response:

{
  "id": 1,
  "result": {
    "listening": true,
    "event": "PinChallenge.onRequestChallenge"
  }
}

Asynchronous event to initiate challenge()

Event Response:

{
  "id": 1,
  "result": {
    "correlationId": undefined,
    "parameters": {
      "capability": "xrn:firebolt:capability:commerce::purchase",
      "requestor": {
        "id": "ReferenceApp",
        "name": "Firebolt Reference App"
      },
      "pinSpace": "purchase"
    }
  }
}

App initiated response to event

Request:

{
  "id": 2,
  "method": "PinChallenge.challengeResponse",
  "params": {
    "correlationId": undefined,
    "result": {
      "granted": true,
      "reason": "correctPin"
    }
  }
}

Response:

{
  "id": 2,
  "result": true
}

Types

ResultReason

The reason for the result of challenging the user

ResultReason: {
    NO_PIN_REQUIRED: 'noPinRequired',
    NO_PIN_REQUIRED_WINDOW: 'noPinRequiredWindow',
    EXCEEDED_PIN_FAILURES: 'exceededPinFailures',
    CORRECT_PIN: 'correctPin',
    CANCELLED: 'cancelled',
},

ChallengeRequestor

type ChallengeRequestor = {
  id: string // The id of the app that requested the challenge
  name: string // The name of the app that requested the challenge
}

PinChallengeResult

type PinChallengeResult = {
  granted: boolean
  reason: ResultReason // The reason for the result of challenging the user
}

PinChallenge

type PinChallenge = {
  pinSpace: 'purchase' | 'content' // The pin space that this challenge is for
  capability?: string // The capability that is gated by a pin challenge
  requestor: ChallengeRequestor // The identity of which app is requesting access to this capability
}

PinChallengeProviderRequest

type PinChallengeProviderRequest = {
  parameters: PinChallenge // The result of the provider response.
  correlationId: string // The id that was passed in to the event that triggered a provider method to be called
}

What's Next

Privacy

Table of contents

Usage
Overview
Methods
Private Methods
Private Events
Provider Interfaces
Types