replidentity

README

Repl Identity

Blog post: https://blog.replit.com/repl-identity

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 Ed25519PrivateKeyToCurve25519(pk ed25519.PrivateKey) [32]byte
• func Ed25519PublicKeyToCurve25519(pk ed25519.PublicKey) ([32]byte, error)
• 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)
• type MessageClaims
• type OrgKey
• type PubKeySource
• type SigningAuthority
  • func CreateIdentityTokenSigningAuthority() (*SigningAuthority, error)
  • func NewSigningAuthority(marshaledPrivateKey, marshaledIdentity string, replid string, ...) (*SigningAuthority, error)
  • func (s *SigningAuthority) OpenAnonymousBox(sealedBox []byte) ([]byte, error)
  • func (a *SigningAuthority) Sign(audience string) (string, error)
  • func (s *SigningAuthority) String() string
• type VerifiedToken
  • func VerifyToken(opts VerifyTokenOpts) (*VerifiedToken, error)
  • func (v *VerifiedToken) SealAnonymousBox(message []byte, rand io.Reader) ([]byte, error)
• type VerifyOption
  • func WithSource(sourceReplid string) VerifyOption
  • func WithVerify(f func(identity *api.GovalReplIdentity) error) VerifyOption
• type VerifyTokenOpts

Examples

• Package
• VerifyRenewIdentity

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 Ed25519PrivateKeyToCurve25519

func Ed25519PrivateKeyToCurve25519(pk ed25519.PrivateKey) [32]byte

ed25519PrivateKeyToCurve25519 converts a ed25519 private key in X25519 equivalent source: https://github.com/FiloSottile/age/blob/980763a16e30ea5c285c271344d2202fcb18c33b/agessh/agessh.go#L287

func Ed25519PublicKeyToCurve25519

func Ed25519PublicKeyToCurve25519(pk ed25519.PublicKey) ([32]byte, error)

ed25519PublicKeyToCurve25519 converts a ed25519 public key in X25519 equivalent source: https://github.com/FiloSottile/age/blob/main/agessh/agessh.go#L190

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.

Example

identity := os.Getenv("REPL_RENEWAL")
if identity == "" {
	fmt.Println("Sorry, this repl does not yet have an identity (anonymous run?).")
	return
}
identityKey := os.Getenv("REPL_RENEWAL_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.VerifyRenewIdentity(
	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,
)

Types

type MessageClaims

type MessageClaims struct {
	Repls       map[string]struct{}
	Users       map[string]struct{}
	UserIDs     map[int64]struct{}
	Orgs        map[OrgKey]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 OrgKey

type OrgKey struct {
	Id  string
	Typ api.Org_OrgType
}

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) OpenAnonymousBox

func (s *SigningAuthority) OpenAnonymousBox(sealedBox []byte) ([]byte, error)

OpenAnonymousBox decrypts a message encrypted with [SealAnonymousBox] using the private key of the signature authority.

This uses https://pkg.go.dev/golang.org/x/crypto@v0.42.0/nacl/box#OpenAnonymous, and uses the ed25519 private key (converted to curve25519 private key).

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 VerifiedToken

type VerifiedToken struct {
	Identity         *api.GovalReplIdentity
	SigningAuthority *api.GovalSigningAuthority
	Certificate      *api.GovalCert
}

VerifiedToken is the result of verifying a token.

func VerifyToken

func VerifyToken(opts VerifyTokenOpts) (*VerifiedToken, 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). This is the preferred way of verifying tokens.

The optional options allow specifying additional verifications on the identity.

func (*VerifiedToken) SealAnonymousBox

func (v *VerifiedToken) SealAnonymousBox(message []byte, rand io.Reader) ([]byte, error)

SealAnonymousBox encrypts a message using the public key of the certificate. Only the private key can decrypt the message.

This uses https://pkg.go.dev/golang.org/x/crypto@v0.42.0/nacl/box#SealAnonymous, and uses the ed25519 public key embedded in the certificate (converted to curve25519 public key).

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
}