title: PinChallenge

version: 1.0.0
layout: default
sdk: manage

# PinChallenge Module

Version PinChallenge 1.0.0

Table of Contents

• Table of Contents
• Usage
• Overview
• Methods
  • challengeError
  • challengeFocus
  • challengeResponse
  • provide
• Events
  • onRequestChallenge
• Provider Interfaces
  • ChallengeProvider
• Types
  • ResultReason
  • ChallengeRequestor
  • PinChallengeResult
  • PinChallenge
  • PinChallengeProviderRequest

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

challengeError

This is an private RPC method.

Internal API for Challenge Provider to send back error.

Parameters:

Result:

null

Capabilities:

Examples

Example 1

JSON-RPC:

Request:

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

Response:

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

challengeFocus

This is an private RPC method.

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

Result:

null

Capabilities:

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 an private RPC method.

Internal API for Challenge Provider to send back response.

Parameters:

Result:

null

Capabilities:

Examples

Example #1

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "PinChallenge.challengeResponse",
	"params": {
		"response": {
			"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": {
		"response": {
			"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": {
		"response": {
			"correlationId": "123",
			"result": {
				"granted": null,
				"reason": "cancelled"
			}
		}
	}
}

Response:

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

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:

See Provider Interfaces for each capabilities interface definition.

Events

onRequestChallenge

This is an 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:

Result:

PinChallengeProviderRequest

Capabilities:

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)

challenge

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

function challenge(parameters?: PinChallenge, session?: FocusableProviderSession): Promise<PinChallengeResult>

Provider methods always have two arguments:

type PinChallenge = object

Promise resolution:

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 await Promise.resolve({
            "granted": true,
            "reason": "correctPin"
        })
    }

}

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

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

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

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

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

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

Types

ResultReason

The reason for the result of challenging the user

enum 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 | void
  reason: ResultReason       // The reason for the result of challenging the user
}

See also:

'noPinRequired' | 'noPinRequiredWindow' | 'exceededPinFailures' | 'correctPin' | 'cancelled'

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
}

See also:

ChallengeRequestor

PinChallengeProviderRequest

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

See also:

ProviderRequest
PinChallenge