sessionx

This introduces types and functions that enable identifying, fetching, and storing web session data. This is accomplished by a set of types that will be used by consumers of this library: Session, Store, and Secret.

A Secret is a cryptographically verifiable signing key used to sign a SignedId. Creating a Secret is simple. It defaults to expire at Secret.lifetime

val secret = Secret() // default secret expiry
val expiringSecret = Secret(Time.now)

val randomBytes = EntropyGenerator(16) // 16 bytes of randomness
val randomId = EntropyGenerator(1).head // 1 byte of randomness for an id
val expiry = Time.from(0) // very expired
val constructedSecret = Secret(randomId, randomBytes, expiry)
log(s"secret has expired: ${constructedSecret.expired == true}")

val signedMsg = secret.sign("message to by signed".getBytes)

A SignedId is a cryptographically signed identifier for a Session, it consists of entropy, expiry, secret,and signature of those items. This is meant to be used as the com.twitter.finagle.http.Cookie value, so we provide serializing to String.

val id: SignedId = Await.result(SignedId.next)
val cookieValue: String = id.asBase64
SignedId.from[String](cookieValue) == id

A Session is product type of a cryptographically verifiable identifier SignedId and an arbitrary data type A. The only requirement for a SessionStore[B,M] to store/fetch aSession[A] is that there be some implicit injective views from A => B and B => Try[A].

We have provided default encodings for: http.Request => Buf, String => Buf and their injective views.

// set up secret/session stores
implicit val secretStore = SecretStores.InMemorySecretStore(Secrets(Secret(), Secret()))
val sessionStore = SessionStore.InMemoryStore()

// create a Session[http.Request]
val newSessionFuture = Session(Request("http://localhost/api/stuff")) // entropy is blocking on the JVM
val newSession = Await.result(newSessionFuture)

// see if the session expired (checks the [[SignedId.expires]])
log(s"Session has expired? ${newSession.expired}")

// store the session and then fetch it
sessionStore.update(newSession).onFailure(log)
sessionStore.get(newSession.id).onSuccess(s => s match {
  case Some(s) => log(s"Same session?: ${newSession == s}")
  case None => log("hrm, where did the session go?")
})

Let's say you have a Session.data type that doesn't have the injective that you need, that's OK! Assuming you are storing it in memcached, which requires a type of Buf for the value:

trait Foo {
  val value: Int
}

implicit val enc = SessionDataEncoder[Foo](
  foo => Buf.U32BE(foo.value),
  buf => new Foo { override val value = Buf.U32BE.unapply(buf) }
)

val foo1 = new Foo { override val value = 1 }
val fooSession = Session(foo1)
sessionStore.update(fooSession)

Linear Supertypes

Types, AnyRef, Any

Type Members

implicit final class AnyOps[A] extends AnyVal

Wraps any object with a toFuture method
case class BpConsulError(msg: String) extends BpSessionError with Product with Serializable
case class BpOriginalRequestNotFound(msg: String) extends BpSessionError with Product with Serializable
case class BpSecretDecodeError(msg: String) extends BpSessionError with Product with Serializable
case class BpSecretsDecodeError(msg: String) extends BpSessionError with Product with Serializable
case class BpSessionCreateUnavailable(msg: String) extends BpSessionError with Product with Serializable
case class BpSessionDataError(error: Throwable) extends BpSessionError with Product with Serializable
class BpSessionError extends Exception
case class BpSessionStoreError(msg: String) extends BpSessionError with Product with Serializable
case class BpSignedIdError(error: String) extends BpSessionError with Product with Serializable
case class ConsulResponse(createIndex: Int, flags: Int, key: String, lockIndex: Int, modifyIndex: Int, value: String) extends Product with Serializable

Consul Response
trait Encoder[A, B] extends AnyRef

Typeclasses for Encoding data within sessions
type Encrypted = Array[Byte]

Definition Classes
Types
trait EncryptedDataEncoder[A] extends AnyRef

This type uses the SessionDataEncoder to encode generic types to com.twitter.io.Buf, then the Encryptable and Decryptable types will unwrap the Buf encrypt/decrypt it, and then rewrap it.
type Entropy = IndexedSeq[Byte]

Definition Classes
Types
type Payload = IndexedSeq[Byte]

Definition Classes
Types
type Seconds = Long

Definition Classes
Types
case class Secret(id: sessionx.SecretId, expiry: Time, entropy: sessionx.Entropy) extends Signer with Product with Serializable

Creates a new Secret that can be used to Signer.sign
Creates a new Secret that can be used to Signer.sign
id
unique identifier for this secret
expiry
how long this signer is valid
entropy
the random bytes for this key
trait SecretEncoder[A] extends Encoder[Secret, A]
type SecretId = IndexedSeq[Byte]

Definition Classes
Types
implicit final class SecretOps extends AnyVal
trait SecretStoreApi extends AnyRef

Two secrets must be in rotation at any given time: - Current: used for creating new sessions and validating incoming non-expired sessions - Previous: validating incoming non-expired sessions, e.g.
Two secrets must be in rotation at any given time: - Current: used for creating new sessions and validating incoming non-expired sessions - Previous: validating incoming non-expired sessions, e.g. sessions signed by yesterday's key
Since each Secret expires (default of 1 day), the window of a non-expired Session is somewhere between the expiry of the current Secret and the previous Secret
case class Secrets(current: Secret, previous: Secret) extends Product with Serializable

Place for current and previous valid Secret as they rotate
Place for current and previous valid Secret as they rotate
current
the current Secret
previous
the previous (and potentially expired) Secret
trait SecretsEncoder[A] extends Encoder[Secrets, A]
trait Session[+A] extends AnyRef

A container for some type A with a unique identifier of SignedId
trait SessionDataEncoder[A] extends Encoder[A, Buf]
implicit final class SessionOps[A] extends AnyVal

Helpful value class for Session operations
trait SessionStore extends AnyRef

Session store that will store a Session[_] data into
type Signature = IndexedSeq[Byte]

Definition Classes
Types
case class SignedId(expires: Time, entropy: sessionx.Entropy, secret: Secret, tag: Tag, signature: sessionx.Signature) extends Product with Serializable

This type represents the value of a user's Cookie The design of this is to act as a cryptographically verifiable identifier for a user
This type represents the value of a user's Cookie The design of this is to act as a cryptographically verifiable identifier for a user
In String form, is a Base64 encoded concatenation of the following transformation: expires: Time => Long => Array[Byte] entropy: Array[Byte] secret: Secret => SecretId tag: => Tag signature: Array[Byte]
expires
the time at which this id is expired
entropy
the random bytes unique to this session id
secret
the secret used to sign this session id
signature
the bytes of the signature(expires, entropy, secret.id)
trait SignedIdEncoder[A] extends Encoder[SignedId, A]
implicit final class SignedIdOps extends AnyVal

More object-style accessors on SignedId, implementation defined in SignedId
type Size = Int

Definition Classes
Types
trait Tag extends AnyRef

Tag is a byte that help us differentiate the set of SignedId from others.
type TagId = Byte

Definition Classes
Types
implicit final class ThrowableOps extends AnyVal

Wraps any Throwable with a toFutureException method
type TimeBytes = IndexedSeq[Byte]

Definition Classes
Types
trait Types extends AnyRef

Value Members

object AuthenticatedTag extends Tag with Product with Serializable
implicit val ByteCodecJson: CodecJson[Byte]

Helper for Byte -> Json
object ConsulResponse extends Serializable
object Encoder

Create instances of Encoder
object EncryptedDataEncoder

Instances of EncryptedDataEncoder only need to contain a SessionDataEncoder TODO: remove this whole concept of an EncryptedDataEncoder type class, it's worthless.
Instances of EncryptedDataEncoder only need to contain a SessionDataEncoder TODO: remove this whole concept of an EncryptedDataEncoder type class, it's worthless. We can treat Session as a Functor and apply the encryption/decryption via mixins to the base SessionStore
object Secret extends Serializable

Helper object for defining defaults for entropy, id size, and expiry
Helper object for defining defaults for entropy, id size, and expiry
```
val validSecret = Secret()
val anotherSecret = Secret(Time.now + Duration(1, TimeUnit.HOURS)) // expires in an hour
```
object SecretEncoder

Instances of SecretEncoder for Secret => A
object SecretStores

Default implementations of SecretStoreApi
object Secrets extends Serializable
object SecretsEncoder
object Session
object SessionDataEncoder

Instances of SessionDataEncoder for A => com.twitter.io.Buf
object SessionStores

Default implementations of SessionStore with memcached and an in-memory store for mocking
object SignedId extends Serializable
object SignedIdEncoder

Instances of SignedIdEncoder for SignedId => A
object Tag
implicit val TimeCodecJson: CodecJson[Time]

Time -> Long -> Json
object Untagged extends Tag with Product with Serializable

package sessionx

Type Members

implicit final class AnyOps[A] extends AnyVal

case class BpConsulError(msg: String) extends BpSessionError with Product with Serializable

case class BpOriginalRequestNotFound(msg: String) extends BpSessionError with Product with Serializable

case class BpSecretDecodeError(msg: String) extends BpSessionError with Product with Serializable

case class BpSecretsDecodeError(msg: String) extends BpSessionError with Product with Serializable

case class BpSessionCreateUnavailable(msg: String) extends BpSessionError with Product with Serializable

case class BpSessionDataError(error: Throwable) extends BpSessionError with Product with Serializable

class BpSessionError extends Exception

case class BpSessionStoreError(msg: String) extends BpSessionError with Product with Serializable

case class BpSignedIdError(error: String) extends BpSessionError with Product with Serializable

case class ConsulResponse(createIndex: Int, flags: Int, key: String, lockIndex: Int, modifyIndex: Int, value: String) extends Product with Serializable

trait Encoder[A, B] extends AnyRef

type Encrypted = Array[Byte]

trait EncryptedDataEncoder[A] extends AnyRef

type Entropy = IndexedSeq[Byte]

type Payload = IndexedSeq[Byte]

type Seconds = Long

case class Secret(id: sessionx.SecretId, expiry: Time, entropy: sessionx.Entropy) extends Signer with Product with Serializable

trait SecretEncoder[A] extends Encoder[Secret, A]

type SecretId = IndexedSeq[Byte]

implicit final class SecretOps extends AnyVal

trait SecretStoreApi extends AnyRef

case class Secrets(current: Secret, previous: Secret) extends Product with Serializable

trait SecretsEncoder[A] extends Encoder[Secrets, A]

trait Session[+A] extends AnyRef

trait SessionDataEncoder[A] extends Encoder[A, Buf]

implicit final class SessionOps[A] extends AnyVal

trait SessionStore extends AnyRef

type Signature = IndexedSeq[Byte]

case class SignedId(expires: Time, entropy: sessionx.Entropy, secret: Secret, tag: Tag, signature: sessionx.Signature) extends Product with Serializable

trait SignedIdEncoder[A] extends Encoder[SignedId, A]

implicit final class SignedIdOps extends AnyVal

type Size = Int

trait Tag extends AnyRef

type TagId = Byte

implicit final class ThrowableOps extends AnyVal

type TimeBytes = IndexedSeq[Byte]

trait Types extends AnyRef

Value Members

object AuthenticatedTag extends Tag with Product with Serializable

implicit val ByteCodecJson: CodecJson[Byte]

object ConsulResponse extends Serializable

object Encoder

object EncryptedDataEncoder

object Secret extends Serializable

object SecretEncoder

object SecretStores

object Secrets extends Serializable

object SecretsEncoder

object Session

object SessionDataEncoder

object SessionStores

object SignedId extends Serializable

object SignedIdEncoder

object Tag

implicit val TimeCodecJson: CodecJson[Time]

object Untagged extends Tag with Product with Serializable

Inherited from Types

Inherited from AnyRef

Inherited from Any

Ungrouped