pairing

type MintFunc func(name string) (rawToken, tokenID string, err error)

type Options struct {
	TTL        time.Duration
	Grace      time.Duration
	MaxPending int

	// Now is the clock source. nil defaults to time.Now. Tests inject a
	// controllable clock; production passes nil.
	Now func() time.Time

	// RevokeToken is invoked when an Approved request hits TTL+grace
	// without iOS acknowledging receipt via DELETE — defends against
	// orphaned tokens after a network blip kills the iOS poll between
	// mint and consume. nil means "never revoke" (test mode); production
	// wires this to auth.Store.Revoke.
	RevokeToken func(tokenID string) error

	// OnStateChange is invoked AFTER every observable state transition
	// (Pending→Approved via Approve, Pending→Declined via Decline,
	// Pending→Expired via the timer sweep). The snapshot is the
	// post-transition state; nil-safe (no-op when not wired).
	//
	// cmd/bridge wires this to publish a `pairing.<requestID>` event
	// to the SSE broker so iOS clients see push-delivered approval/
	// decline/expiry updates instead of polling. Production: paired
	// with broker.Publish; tests: paired with a stubOnStateChange
	// recorder.
	//
	// **Invoked OUTSIDE the pairing mutex** to mirror the RevokeToken
	// pattern — the broker has its own mutex and we don't want
	// cross-mutex coupling stalling concurrent CreateRequest calls.
	// Same callback contract: keep handlers lightweight, hop to a
	// goroutine for heavy work.
	OnStateChange func(snapshot Request)
}

type PollResult struct {
	State               State
	TTLSecondsRemaining int
	Token               string // empty unless State == StateApproved
	TokenID             string // empty unless State == StateApproved
	VerificationCode    string // echoed so iOS can re-display after a foreground resume
}

type Request struct {
	ID               string
	DeviceName       string
	ClientVersion    string
	VerificationCode string
	// PollHash is the raw bytes of sha256(pollSecret), decoded once at
	// CreateRequest time so every Poll comparison runs against an
	// already-canonical [32]byte (no hex casing pitfall in the compare
	// path).
	PollHash [32]byte
	// CertFingerprint is the bridge's cert SHA-256 fingerprint at the
	// moment of request creation. Compared against the live fingerprint
	// at Approve time — mismatch transitions to CertRotated instead of
	// Approved, defending against a cert rotation between the iOS user
	// initiating Join and the admin clicking Approve.
	CertFingerprint string
	// SourceIP is the request's RemoteAddr host. Display-only — the
	// admin UI shows it so the operator can spot LAN spam patterns.
	SourceIP string
	// DeviceToken is the iOS client's durable, device-local recovery
	// token (the Keychain identity that survives app reinstall). Optional
	// — empty for pre-feature clients. Carried through so the admin
	// approve path can bind/refresh the device_registrations row (with a
	// real device name) the instant a pairing is approved, rather than
	// waiting for the first authed request's X-Device-Token header.
	//
	// SECRET: this is the client's own recovery token. It is preserved by
	// snapshot() (the admin approve handler needs it to rebind) but MUST
	// NOT be serialized into any wire DTO — the pairing poll / SSE event
	// (PairingStateEvent) and the admin pending-pairing row deliberately
	// omit it.
	DeviceToken string
	State       State
	TokenID     string // populated on Approve; tied to auth.Store.Mint return
	RawToken    string // populated on Approve; returned on every authorized poll until DELETE
	CreatedAt   time.Time
	DecidedAt   time.Time
	// contains filtered or unexported fields
}

type State int

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