AcknowledgeChallenge Module

Version AcknowledgeChallenge 1.2.0

Table of Contents

• Table of Contents
• Usage
• Overview
• Methods
  • challengeError
  • challengeFocus
  • challengeResponse
  • provide
• Events
  • onRequestChallenge
• Provider Interfaces
  • ChallengeProvider
• Types
  • GrantResult
  • ChallengeRequestor
  • Challenge
  • ChallengeProviderRequest

Usage

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

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

Overview

A module for registering as a provider for a user grant in which the user confirms access to a capability

Methods

challengeError

This is an private RPC method.

Internal API for Challenge Provider to send back error.

Parameters:

Result:

Capabilities:

Examples

Example 1

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "AcknowledgeChallenge.challengeError",
  "params": {
    "correlationId": "123",
    "error": {
      "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:

Capabilities:

Examples

Example

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "AcknowledgeChallenge.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:

Capabilities:

Examples

Example #1

JSON-RPC:

Request:

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

Response:

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

Example #2

JSON-RPC:

Request:

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

Response:

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

Example #3

JSON-RPC:

Request:

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

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

Parameters:

Result:

ChallengeProviderRequest

Capabilities:

Examples

Default Example

JSON-RPC:

Request:

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

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "correlationId": "abc",
    "parameters": {
      "capability": "xrn:firebolt:capability:localization::postal-code",
      "requestor": {
        "id": "ReferenceApp",
        "name": "Firebolt Reference App"
      }
    }
  }
}

Provider Interfaces

ChallengeProvider

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

interface ChallengeProvider {
  challenge(
    parameters: object,
    session: FocusableProviderSession,
  ): Promise<GrantResult>
}

Usage:

AcknowledgeChallenge.provide('xrn:firebolt:capability:usergrant:acknowledgechallenge', provider: ChallengeProvider | object)

Examples

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

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

class MyChallengeProvider {
  async challenge(parameters, session) {
    return null
  }
}

AcknowledgeChallenge.provide(
  'xrn:firebolt:capability:usergrant:acknowledgechallenge',
  new MyChallengeProvider(),
)

<summary>JSON-RPC</summary>

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

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

{
  "id": 1,
  "result": {
    "correlationId": undefined,
    "parameters": {
      "capability": "xrn:firebolt:capability:localization::postal-code",
      "requestor": {
        "id": "ReferenceApp",
        "name": "Firebolt Reference App"
      }
    }
  }
}

{
  "id": 2,
  "method": "AcknowledgeChallenge.challengeResponse",
  "params": {
    "correlationId": undefined,
    "result": null
  }
}

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

Types

GrantResult

type GrantResult = {
  granted: boolean
}

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
}

Challenge

type Challenge = {
  capability: string // The capability that is being requested by the user to approve
  requestor: ChallengeRequestor // The identity of which app is requesting access to this capability
}

See also:

ChallengeRequestor

ChallengeProviderRequest

type ChallengeProviderRequest = {
  parameters: Challenge // 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
}

See also:

ProviderRequest Challenge