passkeys

README

togo-framework/auth-passkeys

WebAuthn / passkey (FIDO2) passwordless login for the togo auth family.

Install

togo install togo-framework/auth-passkeys

Adds passkey registration + login ceremonies to a togo app. On a successful passkey login it issues a session via the auth plugin — so passkeys slot into your existing auth flow as a passwordless method.

Configuration

Env	Description
PASSKEYS_RP_ID	Relying-party ID — your domain (e.g. localhost, fort.example.com)
PASSKEYS_RP_NAME	Display name shown in the authenticator prompt
PASSKEYS_RP_ORIGINS	Comma-separated allowed origins (e.g. https://app.example.com)

Endpoints

Method	Path	Ceremony
POST	/api/auth/passkeys/register/begin	→ PublicKeyCredentialCreationOptions
POST	/api/auth/passkeys/register/finish	verify attestation + store the credential
POST	/api/auth/passkeys/login/begin	→ PublicKeyCredentialRequestOptions
POST	/api/auth/passkeys/login/finish	verify assertion → issue an auth session
GET	/api/auth/passkeys/credentials	list a user's passkeys

The ceremony subject is the user_id (request body, ?user_id, or the X-User-Id / authenticated user).

Browser usage

// register
const opts = await (await fetch('/api/auth/passkeys/register/begin', {
  method: 'POST', headers: {'Content-Type':'application/json','X-User-Id': email},
  body: JSON.stringify({ user_id: email })
})).json();
const cred = await navigator.credentials.create({ publicKey: decode(opts.publicKey) });
await fetch('/api/auth/passkeys/register/finish', { method:'POST', headers:{'X-User-Id':email}, body: encode(cred) });

// login
const req = await (await fetch('/api/auth/passkeys/login/begin', {
  method:'POST', body: JSON.stringify({ user_id: email }) })).json();
const assertion = await navigator.credentials.get({ publicKey: decode(req.publicKey) });
const res = await fetch('/api/auth/passkeys/login/finish', { method:'POST', headers:{'X-User-Id':email}, body: encode(assertion) });
// res → { authenticated: true, token } and an auth session cookie

Go API

pk, _ := passkeys.FromKernel(k)
creds := pk.CredentialsFor("alice@example.com")   // a user's passkeys
pk.WithStore(myDBStore)                            // persist credentials (Store interface)

Credentials live in a bounded in-memory store by default; implement the Store interface (Add/ByUser/Get/UpdateSignCount/Delete) + WithStore(...) for DB persistence.

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package passkeys adds WebAuthn / passkey (FIDO2) authentication to the togo auth family — passwordless registration and login ceremonies, with the issued session coming from the togo auth plugin.

PASSKEYS_RP_ID=localhost PASSKEYS_RP_NAME="Fort" PASSKEYS_RP_ORIGINS=http://localhost:3000

Endpoints (mounted on the kernel router):

POST /api/auth/passkeys/register/begin   POST /api/auth/passkeys/register/finish
POST /api/auth/passkeys/login/begin      POST /api/auth/passkeys/login/finish

Index

• type Credential
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func (s *Service) CredentialsFor(userID string) []*Credential
  • func (s *Service) WithStore(store Store) *Service
• type Store

Types

type Credential

type Credential struct {
	ID     string `json:"id"`      // base64url credential id
	UserID string `json:"user_id"` // the owning user (email/id)
	Name   string `json:"name"`    // display label

	SignCount uint32    `json:"sign_count"`
	CreatedAt time.Time `json:"created_at"`
	// contains filtered or unexported fields
}

Credential is a stored passkey for a user.

type Service

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

Service is the passkeys runtime stored on the kernel (k.Get("passkeys")).

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel returns the passkeys Service.

func (*Service) CredentialsFor

func (s *Service) CredentialsFor(userID string) []*Credential

CredentialsFor returns the stored passkeys for a user.

func (*Service) WithStore

func (s *Service) WithStore(store Store) *Service

WithStore swaps the credential store (e.g. a DB-backed implementation).

type Store

type Store interface {
	Add(c *Credential)
	ByUser(userID string) []*Credential
	Get(id string) (*Credential, bool)
	UpdateSignCount(id string, count uint32)
	Delete(id string) bool
}

Store is the credential persistence seam (swap for a DB-backed store).