The clath Reference Manual

Table of Contents

The clath Reference Manual

This is the clath Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:32:56 2021 GMT+0.

1 Introduction

Clath needs an updated version of cljwt. Grim Schjetne, author of cljwt, intends to update it. The updated version is included here in the cljwt folder until the main branch gets reworked. This seems simpler than publishing an alternate version of cljwt on quicklisp.

Clath's local version of cljwt will be loaded under the package cljwt-custom to avoid any chance clashes with the main version.

Original: https://github.com/gschjetne/cljwt
Updated fork: https://github.com/BnMcGn/cljwt

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 clath

Author

Ben McGunigle <bnmcgn@gmail.com>

License

Apache License, version 2.0

Description

Clath is single sign-on middleware for Clack. It allows basic login with OAuth1.0a, OAuth2 and OpenID Connect.

Dependencies

• ningle
• clack
• alexandria
• cl-hash-util
• drakma
• flexi-streams
• cl-json
• cljwt-custom (system)
• cl-who
• ubiquitous
• north

Source

clath.asd (file)

Components

• package.lisp (file)
• util.lisp (file)
• providers.lisp (file)
• bottom.lisp (file)
• clath.lisp (file)

2.2 cljwt-custom

Author

<Grim Schjetne <grim@schjetne.se>

License

LGPLv3+

Description

JSON Web Token library

Dependencies

• ironclad
• yason
• cl-base64
• flexi-streams
• split-sequence

Source

cljwt-custom.asd (file)

Component

cljwt/src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 cljwt-custom/cljwt/src

Parent

cljwt-custom (system)

Location

cljwt/src/

Component

cljwt.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 clath.asd

Location

clath.asd

Systems

clath (system)

4.1.2 cljwt-custom.asd

Location

cljwt-custom.asd

Systems

cljwt-custom (system)

Packages

cljwt-system

4.1.3 clath/package.lisp

Parent

clath (system)

Location

package.lisp

Packages

clath

4.1.4 clath/util.lisp

Dependency

package.lisp (file)

Parent

clath (system)

Location

util.lisp

Internal Definitions

• assoc-cdr (macro)
• assoc-or (function)
• extract-keywords (function)
• mkstr (function)
• repath-clack-env (function)
• string-equal-case (function)
• under-path-p (function)
• url-from-env (function)

4.1.5 clath/providers.lisp

Dependency

util.lisp (file)

Parent

clath (system)

Location

providers.lisp

Internal Definitions

• *provider-info* (special variable)
• *provider-secrets* (special variable)
• check-for-error (function)
• request-user-info (generic function)
• request-user-info (method)
• request-user-info (method)
• request-user-info (method)
• request-user-info (method)
• request-user-info (method)
• request-user-info (method)
• request-user-info-north (function)

4.1.6 clath/bottom.lisp

Dependency

providers.lisp (file)

Parent

clath (system)

Location

bottom.lisp

Exported Definitions

• *callback-extension* (special variable)
• *login-destination* (special variable)
• *login-destination-hook* (special variable)
• *login-extension* (special variable)
• available-providers (function)
• provider-url-string (function)

Internal Definitions

• *callback-extension-north* (special variable)
• *clath-version* (special variable)
• *login-extension-north* (special variable)
• *server-url* (special variable)
• basic-authorization (function)
• callback-action (function)
• callback-action-north (function)
• destination-on-login (function)
• discover-endpoints (function)
• gen-state (function)
• get-access-token (function)
• get-id-token (function)
• login-action (function)
• login-action-north (function)
• logout-action (function)
• make-callback-url (function)
• make-login-url (function)
• provider-info (function)
• provider-secrets (function)
• provider-string (function)
• request-access-token (function)
• request-user-auth-destination (function)
• special-url-p (function)
• try-request-user-info (function)
• user-agent (function)
• userinfo-get-user-id (function)
• uses-north-p (function)
• valid-state (function)

4.1.7 clath/clath.lisp

Dependency

bottom.lisp (file)

Parent

clath (system)

Location

clath.lisp

Exported Definitions

• *in-logout-page* (special variable)
• clath-login-page (function)
• clath-logout-page (function)
• clath-not-logged-page (function)
• clath-page-wrapper (function)
• component (function)
• disable-provider (function)
• enable-provider (function)
• initialize-secrets (function)
• login-url (function)
• logout-url (function)
• provider-disabled? (function)

Internal Definitions

• *logout-extension* (special variable)
• *openid-app-address* (special variable)
• logged-in (function)
• logged-out (function)
• login-app (function)
• login-links (function)
• login-page (function)
• logout-page (function)
• not-logged-page (function)
• secrets-from-ubiquitous (function)

4.1.8 cljwt-custom/cljwt/src/cljwt.lisp

Parent

cljwt/src (module)

Location

cljwt/src/cljwt.lisp

Packages

cljwt-custom

Exported Definitions

• expired (condition)
• from-unix-time (function)
• invalid-hmac (condition)
• invalid-rs256-signature (condition)
• invalid-time (condition)
• issue (function)
• mismatched-algorithms (condition)
• missing-algorithm (condition)
• not-yet-valid (condition)
• to-unix-time (function)
• unpack (function)
• unsecured-token (condition)
• unsupported-algorithm (condition)
• verify (function)
• verify-timestamps (function)

Internal Definitions

• +rs256-padding+ (constant)
• +sha256-prefix+ (constant)
• add-claims (macro)
• algorithm (method)
• base64-decode (function)
• base64-encode (function)
• bind-hash-tables (macro)
• compare-hs256-digest (function)
• compare-rs256-digest (function)
• hs256-digest (function)
• rs256-clear-padded-digest (function)
• rs256-digest (function)
• time-delta (method)

5 Packages

Packages are listed by definition order.

5.1 clath

Source

package.lisp (file)

Use List

• alexandria
• cl-who
• common-lisp

Exported Definitions

• *callback-extension* (special variable)
• *in-logout-page* (special variable)
• *login-destination* (special variable)
• *login-destination-hook* (special variable)
• *login-extension* (special variable)
• available-providers (function)
• clath-login-page (function)
• clath-logout-page (function)
• clath-not-logged-page (function)
• clath-page-wrapper (function)
• component (function)
• disable-provider (function)
• enable-provider (function)
• initialize-secrets (function)
• login-url (function)
• logout-url (function)
• provider-disabled? (function)
• provider-url-string (function)

Internal Definitions

• *callback-extension-north* (special variable)
• *clath-version* (special variable)
• *login-extension-north* (special variable)
• *logout-extension* (special variable)
• *openid-app-address* (special variable)
• *provider-info* (special variable)
• *provider-secrets* (special variable)
• *server-url* (special variable)
• assoc-cdr (macro)
• assoc-or (function)
• basic-authorization (function)
• callback-action (function)
• callback-action-north (function)
• check-for-error (function)
• destination-on-login (function)
• discover-endpoints (function)
• extract-keywords (function)
• gen-state (function)
• get-access-token (function)
• get-id-token (function)
• logged-in (function)
• logged-out (function)
• login-action (function)
• login-action-north (function)
• login-app (function)
• login-links (function)
• login-page (function)
• logout-action (function)
• logout-page (function)
• make-callback-url (function)
• make-login-url (function)
• mkstr (function)
• not-logged-page (function)
• provider-info (function)
• provider-secrets (function)
• provider-string (function)
• repath-clack-env (function)
• request-access-token (function)
• request-user-auth-destination (function)
• request-user-info (generic function)
• request-user-info (method)
• request-user-info (method)
• request-user-info (method)
• request-user-info (method)
• request-user-info (method)
• request-user-info (method)
• request-user-info-north (function)
• secrets-from-ubiquitous (function)
• special-url-p (function)
• string-equal-case (function)
• try-request-user-info (function)
• under-path-p (function)
• url-from-env (function)
• user-agent (function)
• userinfo-get-user-id (function)
• uses-north-p (function)
• valid-state (function)

5.2 cljwt-system

Source

cljwt-custom.asd

Use List

• asdf/interface
• common-lisp

5.3 cljwt-custom

Source

cljwt.lisp (file)

Use List

• cl-base64
• common-lisp

Exported Definitions

• expired (condition)
• from-unix-time (function)
• invalid-hmac (condition)
• invalid-rs256-signature (condition)
• invalid-time (condition)
• issue (function)
• mismatched-algorithms (condition)
• missing-algorithm (condition)
• not-yet-valid (condition)
• to-unix-time (function)
• unpack (function)
• unsecured-token (condition)
• unsupported-algorithm (condition)
• verify (function)
• verify-timestamps (function)

Internal Definitions

• +rs256-padding+ (constant)
• +sha256-prefix+ (constant)
• add-claims (macro)
• algorithm (generic function)
• algorithm (method)
• base64-decode (function)
• base64-encode (function)
• bind-hash-tables (macro)
• compare-hs256-digest (function)
• compare-rs256-digest (function)
• hs256-digest (function)
• rs256-clear-padded-digest (function)
• rs256-digest (function)
• time-delta (generic function)
• time-delta (method)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *callback-extension*

Package

clath

Source

bottom.lisp (file)

Special Variable: *in-logout-page*

For code that implements login links. Self destination links should not be used on the logout page, lest the user get stuck in an auto-logout loop. This variable will be set when the logout page is being generated.

Package

clath

Source

clath.lisp (file)

Special Variable: *login-destination*

Package

clath

Source

bottom.lisp (file)

Special Variable: *login-destination-hook*

Package

clath

Source

bottom.lisp (file)

Special Variable: *login-extension*

Package

clath

Source

bottom.lisp (file)

6.1.2 Functions

Function: available-providers ()

Package

clath

Source

bottom.lisp (file)

Function: clath-login-page ()

Redefine this function to customize the login page.

Package

clath

Source

clath.lisp (file)

Function: clath-logout-page ()

Redefine this function to customize the logout page.

Package

clath

Source

clath.lisp (file)

Function: clath-not-logged-page ()

Redefine this function to customize the not-logged-in page.

Package

clath

Source

clath.lisp (file)

Function: clath-page-wrapper TITLE BODY-FUNC

Redefine this function to customize the look of all Clath pages.

Package

clath

Source

clath.lisp (file)

Function: component BASE-URL &key EXTENSION

Package

clath

Source

clath.lisp (file)

Function: disable-provider PR

Package

clath

Source

clath.lisp (file)

Function: enable-provider PR

Package

clath

Source

clath.lisp (file)

Function: from-unix-time TIME

Convert New Jersey time to universal time

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: initialize-secrets ()

Package

clath

Source

clath.lisp (file)

Function: issue CLAIMS &key ALGORITHM KEY ISSUER SUBJECT AUDIENCE EXPIRATION NOT-BEFORE ISSUED-AT ID MORE-HEADER

Encodes and returns a JSON Web Token. Times are in universal-time, number of seconds from 1900-01-01 00:00:00

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: login-url ()

Package

clath

Source

clath.lisp (file)

Function: logout-url ()

Package

clath

Source

clath.lisp (file)

Function: provider-disabled? PR

Package

clath

Source

clath.lisp (file)

Function: provider-url-string PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: to-unix-time TIME

Convert universal time to New Jersey time

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: unpack JWT-STRING

Returns 5 values: claims and header as hash tables. digest, claims and header in string form.

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: verify JWT-STRING KEY ALGORITHM &key FAIL-IF-UNSECURED FAIL-IF-UNSUPPORTED

Decodes and verifies a JSON Web Token. Returns two hash tables,
token claims and token header. The key and algorithm specifier should both be supplied by the source of the token.

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: verify-timestamps CLAIMS

Call with the first value returned by the unpack function.

Package

cljwt-custom

Source

cljwt.lisp (file)

6.1.3 Conditions

Condition: expired ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

invalid-time (condition)

Condition: invalid-hmac ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

error (condition)

Condition: invalid-rs256-signature ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

error (condition)

Condition: invalid-time ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• expired (condition)
• not-yet-valid (condition)

Direct methods

time-delta (method)

Direct slots

Slot: delta

Initargs

:delta

Readers

time-delta (generic function)

Condition: mismatched-algorithms ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

error (condition)

Condition: missing-algorithm ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

error (condition)

Condition: not-yet-valid ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

invalid-time (condition)

Condition: unsecured-token ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

error (condition)

Condition: unsupported-algorithm ()

Package

cljwt-custom

Source

cljwt.lisp (file)

Direct superclasses

error (condition)

Direct methods

algorithm (method)

Direct slots

Slot: algorithm

Initargs

:algorithm

Readers

algorithm (generic function)

6.2 Internal definitions

6.2.1 Constants

Constant: +rs256-padding+

Package

cljwt-custom

Source

cljwt.lisp (file)

Constant: +sha256-prefix+

Package

cljwt-custom

Source

cljwt.lisp (file)

6.2.2 Special variables

Special Variable: *callback-extension-north*

Package

clath

Source

bottom.lisp (file)

Special Variable: *clath-version*

Package

clath

Source

bottom.lisp (file)

Special Variable: *login-extension-north*

Package

clath

Source

bottom.lisp (file)

Special Variable: *logout-extension*

Package

clath

Source

clath.lisp (file)

Special Variable: *openid-app-address*

Package

clath

Source

clath.lisp (file)

Special Variable: *provider-info*

Package

clath

Source

providers.lisp (file)

Special Variable: *provider-secrets*

Package

clath

Source

providers.lisp (file)

Special Variable: *server-url*

Package

clath

Source

bottom.lisp (file)

6.2.3 Macros

Macro: add-claims HASH &rest CLAIMS

Package

cljwt-custom

Source

cljwt.lisp (file)

Macro: assoc-cdr KEY ALIST &optional TEST

Package

clath

Source

util.lisp (file)

Macro: bind-hash-tables BINDINGS &body BODY

Package

cljwt-custom

Source

cljwt.lisp (file)

6.2.4 Functions

Function: assoc-or KEYS ALIST

Finds the first key in keys that has a match in alist. Will use equal to match strings.

Package

clath

Source

util.lisp (file)

Function: base64-decode BASE-64-STRING

Takes a base64-uri string and return an array of octets

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: base64-encode INPUT

Takes a string or octets, returns an unpadded URI-encoded Base64 string.

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: basic-authorization PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: callback-action PROVIDER PARAMETERS &optional POST-FUNC

Package

clath

Source

bottom.lisp (file)

Function: callback-action-north PROVIDER PARAMETERS &optional POST-FUNC

Package

clath

Source

bottom.lisp (file)

Function: check-for-error PARAMETERS

Package

clath

Source

providers.lisp (file)

Function: compare-hs256-digest HEADER-STRING CLAIMS-STRING SECRET REPORTED-DIGEST

Takes header and claims in Base64, secret as a string or octets, and a digest in Base64 to compare with. Signals an error if there is a mismatch.

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: compare-rs256-digest HEADER-STRING CLAIMS-STRING PUBLIC-KEY REPORTED-DIGEST

Takes header and claims in Base64, public-key as an ironclad rsa private-key, and a digest in Base64 to compare with. Signals an error if there is a mismatch.

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: destination-on-login ()

Package

clath

Source

bottom.lisp (file)

Function: discover-endpoints DISCOVERY-URL

Package

clath

Source

bottom.lisp (file)

Function: extract-keywords KEYWORDS ALIST &key IN-LIST

Package

clath

Source

util.lisp (file)

Function: gen-state LEN

Package

clath

Source

bottom.lisp (file)

Function: get-access-token ATDATA

Package

clath

Source

bottom.lisp (file)

Function: get-id-token ATDATA

Package

clath

Source

bottom.lisp (file)

Function: hs256-digest HEADER-STRING CLAIMS-STRING SECRET

Takes header and claims in Base64, secret as a string or octets, returns the digest, in Base64

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: logged-in ()

Package

clath

Source

clath.lisp (file)

Function: logged-out ()

Package

clath

Source

clath.lisp (file)

Function: login-action PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: login-action-north PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: login-app BASE-URL

Package

clath

Source

clath.lisp (file)

Function: login-links ()

Package

clath

Source

clath.lisp (file)

Function: login-page PARAMS

Internal portion of clath-login-page

Package

clath

Source

clath.lisp (file)

Function: logout-action ()

Package

clath

Source

bottom.lisp (file)

Function: logout-page PARAMS

Package

clath

Source

clath.lisp (file)

Function: make-callback-url PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: make-login-url PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: mkstr &rest ARGS

Package

clath

Source

util.lisp (file)

Function: not-logged-page ENV RESULT

Internal portion of clath-not-logged-page

Package

clath

Source

clath.lisp (file)

Function: provider-info PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: provider-secrets PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: provider-string PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: repath-clack-env ENV NEWPATH

Package

clath

Source

util.lisp (file)

Function: request-access-token PROVIDER CODE REDIRECT-URI

Package

clath

Source

bottom.lisp (file)

Function: request-user-auth-destination &key AUTH-SCOPE CLIENT-ID AUTH-ENDPOINT STATE REDIRECT-URI &allow-other-keys

Package

clath

Source

bottom.lisp (file)

Function: request-user-info-north PROVIDER NORTH-CLIENT

Package

clath

Source

providers.lisp (file)

Function: rs256-clear-padded-digest HEADER-STRING CLAIMS-STRING

Takes header and claims in Base64 returns the non-crypted, padded digest, as octets

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: rs256-digest HEADER-STRING CLAIMS-STRING PRIVATE-KEY

Takes header and claims in Base64, private-key as an ironclad rsa private-key, returns the digest, in Base64

Package

cljwt-custom

Source

cljwt.lisp (file)

Function: secrets-from-ubiquitous ()

Package

clath

Source

clath.lisp (file)

Function: special-url-p URL-PATH

Package

clath

Source

bottom.lisp (file)

Function: string-equal-case A B

Package

clath

Source

util.lisp (file)

Function: try-request-user-info PROVIDER ACCESS-TOKEN

Sometimes a newly generated access token won’t instantly propagate in the provider’s system, so we try a few times to give it a chance.

Package

clath

Source

bottom.lisp (file)

Function: under-path-p PATH TESTPATH

Package

clath

Source

util.lisp (file)

Function: url-from-env ENV

Extract the current request url from a clack environment.

Package

clath

Source

util.lisp (file)

Function: user-agent PROVIDER

Some providers, such as Reddit, want a fairly unique user-agent.

Package

clath

Source

bottom.lisp (file)

Function: userinfo-get-user-id PROVIDER USERINFO

Package

clath

Source

bottom.lisp (file)

Function: uses-north-p PROVIDER

Package

clath

Source

bottom.lisp (file)

Function: valid-state RECEIVED-STATE

Package

clath

Source

bottom.lisp (file)

6.2.5 Generic functions

Generic Function: algorithm CONDITION

Package

cljwt-custom

Methods

Method: algorithm (CONDITION unsupported-algorithm)

Source

cljwt.lisp (file)

Generic Function: request-user-info PROVIDER ACCESS-TOKEN

Package

clath

Source

providers.lisp (file)

Methods

Method: request-user-info (PROVIDER (eql stackexchange)) ACCESS-TOKEN

Method: request-user-info (PROVIDER (eql linkedin)) ACCESS-TOKEN

Method: request-user-info (PROVIDER (eql github)) ACCESS-TOKEN

Method: request-user-info (PROVIDER (eql reddit)) ACCESS-TOKEN

Method: request-user-info (PROVIDER (eql google)) ACCESS-TOKEN

Method: request-user-info PROVIDER ACCESS-TOKEN

Generic Function: time-delta CONDITION

Package

cljwt-custom

Methods

Method: time-delta (CONDITION invalid-time)

Source

cljwt.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types