Class: AppIdentity

Inherits:
Object
  • Object
show all
Defined in:
lib/app_identity.rb,
lib/app_identity.rb,
lib/app_identity/versions.rb,
lib/app_identity/validation.rb

Overview

AppIdentity is a Ruby implementation of the Kinetic Commerce application [identity proof algorithm](spec.md).

It implements identity proof generation and validation functions. These functions expect to work with an application object (AppIdentity::App).

## Configuration

Most of the configuration is specified in the application, but at an application level, AppIdentity can be configured to disallow explicit versions:

“‘ruby AppIdentity.disallow_version 1, 3, 4 “`

This would only allow AppIdentity version 2.

Defined Under Namespace

Modules: Validation, Versions Classes: App, Error, FaradayMiddleware, Internal, RackMiddleware

Constant Summary collapse

VERSION =

The version of the AppIdentity library.

"1.1.0"
NAME =

The name of this implementation for App Identity.

"AppIdentity for Ruby"
SPEC_VERSION =

The spec version supported in this library.

4
INFO =

The name, version, and supported specification version of this App Identity package for Ruby.

{name: NAME, version: VERSION, spec_version: SPEC_VERSION}.freeze

Class Method Summary collapse

Class Method Details

.allow_version(*versions) ⇒ Object

Remove the ‘versions` from the global disallowed versions list.



221
222
223
 
# File 'lib/app_identity.rb', line 221

def allow_version(*versions)
  AppIdentity::Versions.allow(*versions)
end

.disallow_version(*versions) ⇒ Object

Add the ‘versions` to the global disallowed versions list.



216
217
218
 
# File 'lib/app_identity.rb', line 216

def disallow_version(*versions)
  AppIdentity::Versions.disallow(*versions)
end

.generate_proof(app, nonce: nil, version: nil, disallowed: nil) ⇒ Object

Generate an identity proof string for the given application. Returns the generated proof or ‘nil`.

If ‘nonce` is provided, it must conform to the shape expected by the proof version. If not provided, it will be generated.

If ‘version` is provided, it will be used to generate the nonce and the proof. This will allow a lower level application to raise its version level.

If there is any error during the generation of the identity proof string, ‘nil` will be returned.

### Examples

A version 1 app can have a fixed nonce, which will always produce the same value.

“‘ruby app = AppIdentity::App.new(1, id: “decaf”, secret: “bad”) AppIdentity.generate_proof(app, nonce: “hello”) # => “ZGVjYWY6aGVsbG86RDNGNjJCQTYyOEIyMzhEOTgwM0MyNEU4NkNCOTY3M0ZEOTVCNTdBNkJGOTRFMkQ2NTMxQTRBODg1OTlCMzgzNQ==” “`

A version 2 app fails when given a non-timestamp nonce.

“‘ruby AppIdentity.generate_proof(v1(), version: 2, nonce: “hello”) # => nil “`

A version 2 app cannot generate a version 1 nonce.

“‘ruby AppIdentity.generate_proof(v2(), version: 1) # => nil “`

A version 2 app will be rejected if the version has been disallowed.

“‘ruby

AppIdentity.generate_proof(v2(), disallowed: [1, 2])
# => nil
```

Note that the optional `disallowed` parameter is *in addition* to the
global `disallowed` configuration.



89
90
91
92
93
 
# File 'lib/app_identity.rb', line 89

def generate_proof(app, nonce: nil, version: nil, disallowed: nil)
  internal.generate_proof!(app, nonce: nonce, version: version, disallowed: disallowed)
rescue
  nil
end

.generate_proof!(app, nonce: nil, version: nil, disallowed: nil) ⇒ Object

Generate an identity proof string for the given application. Returns the generated proof or raises an exception

If ‘nonce` is provided, it must conform to the shape expected by the proof version. If not provided, it will be generated.

If ‘version` is provided, it will be used to generate the nonce and the proof. This will allow a lower level application to raise its version level.

If there is any error during the generation of the identity proof string, an exception will be raised.

### Examples

A version 1 app can have a fixed nonce, which will always produce the same value.

“‘ruby app = AppIdentity::App.new(1, id: “decaf”, secret: “bad”) AppIdentity.generate_proof!(app, nonce: “hello”) # => “ZGVjYWY6aGVsbG86RDNGNjJCQTYyOEIyMzhEOTgwM0MyNEU4NkNCOTY3M0ZEOTVCNTdBNkJGOTRFMkQ2NTMxQTRBODg1OTlCMzgzNQ==” “`

A version 2 app fails when given a non-timestamp nonce.

“‘ruby AppIdentity.generate_proof!(v1(), version: 2, nonce: “hello”) # => nil “`

A version 2 app cannot generate a version 1 nonce.

“‘ruby AppIdentity.generate_proof!(v2(), version: 1) # => nil “`

A version 2 app will be rejected if the version has been disallowed.

“‘ruby

AppIdentity.generate_proof!(v2(), disallowed: [1, 2])
# => nil
```

Note that the optional `disallowed` parameter is *in addition* to the
global `disallowed` configuration.



141
142
143
144
145
 
# File 'lib/app_identity.rb', line 141

def generate_proof!(app, nonce: nil, version: nil, disallowed: nil)
  internal.generate_proof!(app, nonce: nonce, version: version, disallowed: disallowed)
rescue
  raise AppIdentity::Error, :generate_proof
end

.parse_proof(proof) ⇒ Object

Parses a proof string and returns a Hash containing the proof parts or ‘nil` if the proof is cannot be determined as valid.



149
150
151
152
153
 
# File 'lib/app_identity.rb', line 149

def parse_proof(proof)
  internal.parse_proof!(proof)
rescue
  nil
end

.parse_proof!(proof) ⇒ Object

Parses a proof string and returns a Hash containing the proof parts or raises an exception if the proof is cannot be determined as valid.



157
158
159
160
161
 
# File 'lib/app_identity.rb', line 157

def parse_proof!(proof)
  internal.parse_proof!(proof)
rescue
  raise AppIdentity::Error, :parse_proof
end

.verify_proof(proof, app, disallowed: nil) ⇒ Object

Verify a ‘AppIdentity` proof value using a a provided `app`. Returns the validated app or `nil`.

The ‘proof` may be provided either as a string or a parsed proof (from `#parse_proof`). String proof values are usually obtained from HTTP headers. At Kinetic Commerce, this has generally jeen `KCS-Application` or `KCS-Service`.

The ‘app` can be provided as an AppIdentity::App, a valid input to AppIdentity::App.new, or an finder callable that accepts a single parameter—the parsed proof value—and returns an AppIdentity::App input.

“‘ruby AppIdentity.verify_proof(proof, ->(proof) 

IdentityApplications.get(proof[:id]

)) “‘

Note that the optional `disallowed` parameter is *in addition* to the
global `disallowed` configuration.



183
184
185
186
187
 
# File 'lib/app_identity.rb', line 183

def verify_proof(proof, app, disallowed: nil)
  internal.verify_proof!(proof, app, disallowed: disallowed)
rescue
  nil
end

.verify_proof!(proof, app, disallowed: nil) ⇒ Object

Verify a ‘AppIdentity` proof value using a a provided `app`. Returns the validated app, `nil`, or raises an exception on error.

The ‘proof` may be provided either as a string or a parsed proof (from `#parse_proof`). String proof values are usually obtained from HTTP headers. At Kinetic Commerce, this has generally jeen `KCS-Application` or `KCS-Service`.

The ‘app` can be provided as an AppIdentity::App, a valid input to AppIdentity::App.new, or an finder callable that accepts a single parameter—the parsed proof value—and returns an AppIdentity::App input.

“‘ruby AppIdentity.verify_proof!(proof, ->(proof) 

IdentityApplications.get(proof[:id]

)) “‘

Note that the optional `disallowed` parameter is *in addition* to the
global `disallowed` configuration.



209
210
211
212
213
 
# File 'lib/app_identity.rb', line 209

def verify_proof!(proof, app, disallowed: nil)
  internal.verify_proof!(proof, app, disallowed: disallowed)
rescue
  raise AppIdentity::Error, :verify_proof
end