replidentity

README

Repl Identity

Blog post on https://blog.replit.com coming soon!

Repl Identity stores a REPL_IDENTITY token in every Repl automatically. This token is a signed PASETO that includes verifiable repl identity data (such as the user in the repl, and the repl ID).

This package provides the necessary code to verify these tokens.

Check the example at examples/extract.go for an example usage. You can also see this in action at https://replit.com/@mattiselin/repl-identity. If you are logged in to Replit, you'll see your username when you click "Run" on the Cover Page - that's Repl Identity at work.

Documentation

Overview

Package replidentity provides verification utilities for Repl Identity tokens.

Example

identity := os.Getenv("REPL_IDENTITY")
if identity == "" {
	fmt.Println("Sorry, this repl does not yet have an identity (anonymous run?).")
	return
}
identityKey := os.Getenv("REPL_IDENTITY_KEY")
if identity == "" {
	fmt.Println("Sorry, this repl does not yet have an identity (anonymous run?).")
	return
}

// This should be set to the Repl ID of the repl you want to prove your
// identity to.
targetRepl := "target_repl"

// Create a signing authority that is authorized to emit tokens for the
// current repl.
signingAuthority, err := replidentity.NewSigningAuthority(
	string(identityKey),
	identity,
	os.Getenv("REPL_ID"),
	replidentity.ReadPublicKeyFromEnv,
)
if err != nil {
	panic(err)
}

signedToken, err := signingAuthority.Sign(targetRepl)
if err != nil {
	panic(err)
}

// Verify the signed token, pretending we are the target repl.
replIdentity, err := replidentity.VerifyIdentity(
	signedToken,
	[]string{targetRepl},
	replidentity.ReadPublicKeyFromEnv,
)
if err != nil {
	panic(err)
}

fmt.Println()
fmt.Printf("The identity in the repl's token (%d bytes) is:\n", len(identity))
fmt.Printf(
	"repl id: %s\n   user: %s\n   slug: %s  audience: %s\n",
	replIdentity.Replid,
	replIdentity.User,
	replIdentity.Slug,
	replIdentity.Aud,
)

Index

• func CreateIdentityTokenAddressedTo(audience string) (string, error)
• func DebugTokenAsString(token string) string
• func ReadPublicKeyFromEnv(keyid, issuer string) (ed25519.PublicKey, error)
• func VerifyIdentity(message string, audience []string, getPubKey PubKeySource, ...) (*api.GovalReplIdentity, error)
• func VerifyRenewIdentity(message string, audience []string, getPubKey PubKeySource, ...) (*api.GovalReplIdentity, error)
• func VerifyToken(opts VerifyTokenOpts) (*api.GovalReplIdentity, error)
• type MessageClaims
• type PubKeySource
• type SigningAuthority
  • func CreateIdentityTokenSigningAuthority() (*SigningAuthority, error)
  • func NewSigningAuthority(marshaledPrivateKey, marshaledIdentity string, replid string, ...) (*SigningAuthority, error)
  • func (a *SigningAuthority) Sign(audience string) (string, error)
  • func (s *SigningAuthority) String() string
• type VerifyOption
  • func WithSource(sourceReplid string) VerifyOption
  • func WithVerify(f func(identity *api.GovalReplIdentity) error) VerifyOption
• type VerifyTokenOpts

Examples

• Package

Functions

func CreateIdentityTokenAddressedTo

func CreateIdentityTokenAddressedTo(audience string) (string, error)

CreateIdentityTokenAddressedTo returns a Replit identity token that proves this Repl's identity that includes an audience claim to restrict forwarding. It creates a new signing authority each time, which can be slow. If you plan on signing multiple tokens, use CreateIdentityTokenSigningAuthority() to create an authority to sign with.

func DebugTokenAsString

func DebugTokenAsString(token string) string

DebugTokenAsString returns a string representation explaining a token. It does not perform any validation of the token, and should be used only for debugging.

func ReadPublicKeyFromEnv

func ReadPublicKeyFromEnv(keyid, issuer string) (ed25519.PublicKey, error)

ReadPublicKeyFromEnv provides a PubKeySource that reads public keys from the `REPL_PUBKEYS` environment variable that is present in all repls.

func VerifyIdentity

func VerifyIdentity(message string, audience []string, getPubKey PubKeySource, options ...VerifyOption) (*api.GovalReplIdentity, error)

VerifyIdentity verifies that the given `REPL_IDENTITY` value is in fact signed by Goval's chain of authority, and addressed to the provided audience (the `REPL_ID` of the recipient).

The optional options allow specifying additional verifications on the identity.

func VerifyRenewIdentity

func VerifyRenewIdentity(message string, audience []string, getPubKey PubKeySource, options ...VerifyOption) (*api.GovalReplIdentity, error)

VerifyRenewIdentity verifies that the given `REPL_RENEWAL` value is in fact signed by Goval's chain of authority, addressed to the provided audience (the `REPL_ID` of the recipient), and has the capability to renew the identity.

The optional options allow specifying additional verifications on the identity.

func VerifyToken

func VerifyToken(opts VerifyTokenOpts) (*api.GovalReplIdentity, error)

VerifyToken verifies that the given `REPL_IDENTITY` value is in fact signed by Goval's chain of authority, and addressed to the provided audience (the `REPL_ID` of the recipient).

The optional options allow specifying additional verifications on the identity.

Types

type MessageClaims

type MessageClaims struct {
	Repls       map[string]struct{}
	Users       map[string]struct{}
	UserIDs     map[int64]struct{}
	Clusters    map[string]struct{}
	Subclusters map[string]struct{}
	Flags       map[api.FlagClaim]struct{}
}

MessageClaims is a collection of indexable claims that are made by a certificate.

type PubKeySource

type PubKeySource func(keyid, issuer string) (ed25519.PublicKey, error)

PubKeySource provides an interface for looking up an [ed25519.PublicKey] from some external source.

type SigningAuthority

type SigningAuthority struct {
	// contains filtered or unexported fields
}

SigningAuthority can generate tokens that prove the identity of one repl (your own) against another repl (the audience). Use this to prevent the target repl from spoofing your own identity by forwarding the token.

func CreateIdentityTokenSigningAuthority

func CreateIdentityTokenSigningAuthority() (*SigningAuthority, error)

CreateIdentityTokenSigningAuthority creates a signing authority with this repl's identity key.

func NewSigningAuthority

func NewSigningAuthority(
	marshaledPrivateKey,
	marshaledIdentity string,
	replid string,
	getPubKey PubKeySource,
) (*SigningAuthority, error)

NewSigningAuthority returns a new SigningAuthority given the marshaled private key (obtained from the `REPL_IDENTITY_KEY` environment variable or /tmp/replidentity.key), the identity token (obtained from the `REPL_IDENTITY` environment variable or /tmp/replidentity), the current Repl ID (obtained from the `REPL_ID` environment varaible), and the source of public keys (typically ReadPublicKeyFromEnv).

func (*SigningAuthority) Sign

func (a *SigningAuthority) Sign(audience string) (string, error)

Sign generates a new token that can be given to the provided audience, and is resistant against forwarding, so that the recipient cannot forward this token to another repl and claim it came directly from you.

func (*SigningAuthority) String

func (s *SigningAuthority) String() string

type VerifyOption

type VerifyOption interface {
	// contains filtered or unexported methods
}

VerifyOption specifies an additional verification step to be performed on an identity.

func WithSource

func WithSource(sourceReplid string) VerifyOption

WithSource verifies that the identity's origin replID matches the given source, if present. This can be used to enforce specific clients in servers when verifying identities.

func WithVerify

func WithVerify(f func(identity *api.GovalReplIdentity) error) VerifyOption

WithVerify allows the caller to specify an arbitrary function to perform verification on the identity prior to it being returned.

type VerifyTokenOpts

type VerifyTokenOpts struct {
	Message   string
	Audience  []string
	GetPubKey PubKeySource
	Options   []VerifyOption
	Flags     []api.FlagClaim
}