Initial Go SDK for Keysat licensing service
Pure-Go, stdlib-only implementation of the LIC1 wire format: - ParseKey + Verify + ParseAndVerify for offline verification - HashFingerprint helper (SHA-256, matching the daemon's contract) - LoadPublicKeyPEM for the standard PKIX-encoded Ed25519 public keys the daemon emits - Client.Validate / Client.PublicKey for online checks against a running Keysat daemon - LicensePayload struct with idiomatic Go getters (IsTrial, IsFingerprintBound, IsExpiredAt, HasEntitlement) Wire-format crosscheck against the shared tests/crosscheck/vector.json (the same file the Rust, TypeScript, Python SDKs and the daemon itself test against). All four fixtures pass — v1 legacy fingerprint-bound, v2 trial with entitlements, v2 perpetual unbound, plus end-to-end PEM-load → ParseAndVerify signature roundtrip. Confirms byte-for-byte agreement across five independent implementations. No third-party dependencies. Module path: github.com/keysat-xyz/keysat-client-go go 1.21
This commit is contained in:
Grant
@@ -0,0 +1,5 @@
|
|||||||
|
# Build artifacts
|
||||||
|
*.test
|
||||||
|
*.out
|
||||||
|
/coverage.txt
|
||||||
|
/dist/
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 Keysat
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@@ -0,0 +1,98 @@
|
|||||||
|
# keysat-client-go
|
||||||
|
|
||||||
|
Go SDK for [Keysat](https://keysat.xyz) — a self-hosted, Bitcoin-paid software licensing service.
|
||||||
|
|
||||||
|
Verifies LIC1-format license keys offline against an Ed25519 public key, and optionally validates them online against a running Keysat daemon.
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
go get github.com/keysat-xyz/keysat-client-go
|
||||||
|
```
|
||||||
|
|
||||||
|
Stdlib only — no third-party dependencies.
|
||||||
|
|
||||||
|
## Offline verification
|
||||||
|
|
||||||
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
"log"
|
||||||
|
"time"
|
||||||
|
|
||||||
|
"github.com/keysat-xyz/keysat-client-go"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Embed the daemon's PEM public key at build time. Get it from your
|
||||||
|
// Keysat admin UI or `curl https://your-keysat.example/v1/pubkey`.
|
||||||
|
const publicKeyPEM = `-----BEGIN PUBLIC KEY-----
|
||||||
|
MCowBQYDK2VwAyEA...
|
||||||
|
-----END PUBLIC KEY-----`
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
pub, err := keysat.LoadPublicKeyPEM(publicKeyPEM)
|
||||||
|
if err != nil { log.Fatal(err) }
|
||||||
|
|
||||||
|
licenseKey := readKeyFromUserConfig() // however your app stores it
|
||||||
|
|
||||||
|
payload, err := keysat.ParseAndVerify(licenseKey, pub)
|
||||||
|
if err != nil { log.Fatalf("license invalid: %v", err) }
|
||||||
|
|
||||||
|
if payload.IsExpiredAt(time.Now().Unix()) {
|
||||||
|
log.Fatal("license expired")
|
||||||
|
}
|
||||||
|
if !payload.HasEntitlement("pro") {
|
||||||
|
log.Fatal("license does not include 'pro' tier")
|
||||||
|
}
|
||||||
|
fmt.Println("license OK")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Online validation (revocation, fingerprint binding, machine cap)
|
||||||
|
|
||||||
|
```go
|
||||||
|
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||||
|
defer cancel()
|
||||||
|
|
||||||
|
c := keysat.NewClient("https://licensing.example.com", nil)
|
||||||
|
resp, err := c.Validate(ctx, keysat.ValidateRequest{
|
||||||
|
Key: licenseKey,
|
||||||
|
ProductSlug: "myapp",
|
||||||
|
Fingerprint: machineUUID,
|
||||||
|
})
|
||||||
|
if err != nil { log.Fatalf("daemon unreachable: %v", err) }
|
||||||
|
if !resp.OK {
|
||||||
|
log.Fatalf("license rejected: %s", resp.Reason)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`Validate` returns HTTP 200 in all cases; license failures are conveyed via `resp.OK + resp.Reason` (`bad_signature`, `revoked`, `expired`, `too_many_machines`, etc.).
|
||||||
|
|
||||||
|
## Fingerprint binding
|
||||||
|
|
||||||
|
When a key is fingerprint-bound, the daemon's first successful online validation pins the machine's fingerprint hash to the license row. Subsequent validations from a different machine fail with `fingerprint_mismatch`.
|
||||||
|
|
||||||
|
The SDK exposes `keysat.HashFingerprint` if you need to compute the hash yourself (e.g., to compare against a key's `FingerprintHash` field offline):
|
||||||
|
|
||||||
|
```go
|
||||||
|
h := keysat.HashFingerprint(machineUUID)
|
||||||
|
if h != payload.FingerprintHash {
|
||||||
|
log.Fatal("license does not belong to this machine")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Wire format compatibility
|
||||||
|
|
||||||
|
Every SDK + the daemon agree on the LIC1 wire format. Crosscheck tests in this package run against the shared `tests/crosscheck/vector.json` (alongside the daemon repo) — three independently-signed fixtures (v1 legacy, v2 trial with entitlements, v2 perpetual unbound) parse to the same field values across Rust, TypeScript, Python, and Go.
|
||||||
|
|
||||||
|
When fetched standalone via `go get`, the crosscheck test skips gracefully (the vector file isn't bundled into the Go module). The crosscheck only runs from the parent `licensing/` workspace.
|
||||||
|
|
||||||
|
## API stability
|
||||||
|
|
||||||
|
This SDK is alpha alongside Keysat v0.1.0. The wire format itself is stable and won't break compatibility — license keys issued by any v0.1 daemon will keep parsing in any future SDK. The Go API surface (function names, struct fields) may settle further before v1.0; nothing here is wildly out of line with idiomatic Go but expect minor tweaks.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT — see `LICENSE`.
|
||||||
@@ -0,0 +1,180 @@
|
|||||||
|
// Wire-format crosscheck. Each fixture in the shared
|
||||||
|
// tests/crosscheck/vector.json was generated by Python's
|
||||||
|
// reference_signer.py (independent crypto), then is consumed by
|
||||||
|
// every Keysat SDK + the daemon. If this test fails, this Go SDK
|
||||||
|
// has drifted from the wire format the rest of the ecosystem
|
||||||
|
// agrees on.
|
||||||
|
//
|
||||||
|
// The path to vector.json assumes this package is checked out
|
||||||
|
// under the parent licensing/ workspace (next to
|
||||||
|
// licensing-client-rust, etc.). Skip the test gracefully if the
|
||||||
|
// vector isn't reachable — when this SDK is fetched standalone
|
||||||
|
// via `go get`, there's nothing to cross-check against.
|
||||||
|
|
||||||
|
package keysat_test
|
||||||
|
|
||||||
|
import (
|
||||||
|
"encoding/hex"
|
||||||
|
"encoding/json"
|
||||||
|
"errors"
|
||||||
|
"os"
|
||||||
|
"path/filepath"
|
||||||
|
"testing"
|
||||||
|
|
||||||
|
"github.com/keysat-xyz/keysat-client-go"
|
||||||
|
)
|
||||||
|
|
||||||
|
type fixture struct {
|
||||||
|
LicenseKey string `json:"licenseKey"`
|
||||||
|
Expected struct {
|
||||||
|
Version int `json:"version"`
|
||||||
|
ProductUUID string `json:"productUuid"`
|
||||||
|
LicenseUUID string `json:"licenseUuid"`
|
||||||
|
IssuedAt int64 `json:"issuedAt"`
|
||||||
|
ExpiresAt int64 `json:"expiresAt"`
|
||||||
|
Flags int `json:"flags"`
|
||||||
|
IsFingerprintBound bool `json:"isFingerprintBound"`
|
||||||
|
IsTrial bool `json:"isTrial"`
|
||||||
|
Entitlements []string `json:"entitlements"`
|
||||||
|
FingerprintRaw *string `json:"fingerprintRaw"`
|
||||||
|
FingerprintHashHex string `json:"fingerprintHashHex"`
|
||||||
|
} `json:"expected"`
|
||||||
|
}
|
||||||
|
|
||||||
|
type vectorFile struct {
|
||||||
|
PublicKeyPEM string `json:"publicKeyPem"`
|
||||||
|
V1 fixture `json:"v1"`
|
||||||
|
V2 fixture `json:"v2"`
|
||||||
|
V2PerpetualUnbound fixture `json:"v2_perpetual_unbound"`
|
||||||
|
}
|
||||||
|
|
||||||
|
func loadVector(t *testing.T) vectorFile {
|
||||||
|
t.Helper()
|
||||||
|
candidates := []string{
|
||||||
|
"../tests/crosscheck/vector.json", // when this is a sibling of /tests
|
||||||
|
"../../tests/crosscheck/vector.json", // when nested one deeper
|
||||||
|
}
|
||||||
|
for _, c := range candidates {
|
||||||
|
abs, err := filepath.Abs(c)
|
||||||
|
if err != nil {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
raw, err := os.ReadFile(abs)
|
||||||
|
if errors.Is(err, os.ErrNotExist) {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("reading %s: %v", abs, err)
|
||||||
|
}
|
||||||
|
var v vectorFile
|
||||||
|
if err := json.Unmarshal(raw, &v); err != nil {
|
||||||
|
t.Fatalf("parsing %s: %v", abs, err)
|
||||||
|
}
|
||||||
|
return v
|
||||||
|
}
|
||||||
|
t.Skipf("crosscheck vector.json not found alongside this package " +
|
||||||
|
"(expected at ../tests/crosscheck/vector.json); skipping. " +
|
||||||
|
"This is normal when fetched standalone via `go get` — the " +
|
||||||
|
"crosscheck only runs from the parent licensing/ workspace.")
|
||||||
|
return vectorFile{}
|
||||||
|
}
|
||||||
|
|
||||||
|
func uuidString(b [16]byte) string {
|
||||||
|
// Render as canonical 8-4-4-4-12 lowercase hex.
|
||||||
|
hexStr := hex.EncodeToString(b[:])
|
||||||
|
return hexStr[0:8] + "-" + hexStr[8:12] + "-" + hexStr[12:16] + "-" +
|
||||||
|
hexStr[16:20] + "-" + hexStr[20:32]
|
||||||
|
}
|
||||||
|
|
||||||
|
func checkFixture(t *testing.T, name string, fx fixture) {
|
||||||
|
t.Helper()
|
||||||
|
payload, _, _, err := keysat.ParseKey(fx.LicenseKey)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("%s: ParseKey failed: %v", name, err)
|
||||||
|
}
|
||||||
|
if int(payload.Version) != fx.Expected.Version {
|
||||||
|
t.Errorf("%s: version = %d, want %d", name, payload.Version, fx.Expected.Version)
|
||||||
|
}
|
||||||
|
if uuidString(payload.ProductID) != fx.Expected.ProductUUID {
|
||||||
|
t.Errorf("%s: productID = %s, want %s", name, uuidString(payload.ProductID), fx.Expected.ProductUUID)
|
||||||
|
}
|
||||||
|
if uuidString(payload.LicenseID) != fx.Expected.LicenseUUID {
|
||||||
|
t.Errorf("%s: licenseID = %s, want %s", name, uuidString(payload.LicenseID), fx.Expected.LicenseUUID)
|
||||||
|
}
|
||||||
|
if payload.IssuedAt != fx.Expected.IssuedAt {
|
||||||
|
t.Errorf("%s: issuedAt = %d, want %d", name, payload.IssuedAt, fx.Expected.IssuedAt)
|
||||||
|
}
|
||||||
|
if payload.ExpiresAt != fx.Expected.ExpiresAt {
|
||||||
|
t.Errorf("%s: expiresAt = %d, want %d", name, payload.ExpiresAt, fx.Expected.ExpiresAt)
|
||||||
|
}
|
||||||
|
if int(payload.Flags) != fx.Expected.Flags {
|
||||||
|
t.Errorf("%s: flags = %d, want %d", name, payload.Flags, fx.Expected.Flags)
|
||||||
|
}
|
||||||
|
if payload.IsFingerprintBound() != fx.Expected.IsFingerprintBound {
|
||||||
|
t.Errorf("%s: IsFingerprintBound = %v, want %v", name, payload.IsFingerprintBound(), fx.Expected.IsFingerprintBound)
|
||||||
|
}
|
||||||
|
if payload.IsTrial() != fx.Expected.IsTrial {
|
||||||
|
t.Errorf("%s: IsTrial = %v, want %v", name, payload.IsTrial(), fx.Expected.IsTrial)
|
||||||
|
}
|
||||||
|
got := payload.Entitlements
|
||||||
|
if got == nil {
|
||||||
|
got = []string{}
|
||||||
|
}
|
||||||
|
want := fx.Expected.Entitlements
|
||||||
|
if want == nil {
|
||||||
|
want = []string{}
|
||||||
|
}
|
||||||
|
if len(got) != len(want) {
|
||||||
|
t.Errorf("%s: entitlements len = %d, want %d", name, len(got), len(want))
|
||||||
|
} else {
|
||||||
|
for i := range got {
|
||||||
|
if got[i] != want[i] {
|
||||||
|
t.Errorf("%s: entitlements[%d] = %q, want %q", name, i, got[i], want[i])
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
gotFP := hex.EncodeToString(payload.FingerprintHash[:])
|
||||||
|
if gotFP != fx.Expected.FingerprintHashHex {
|
||||||
|
t.Errorf("%s: fingerprintHash = %s, want %s", name, gotFP, fx.Expected.FingerprintHashHex)
|
||||||
|
}
|
||||||
|
// If a raw fingerprint is supplied, verify HashFingerprint reproduces the wire bytes.
|
||||||
|
if fx.Expected.FingerprintRaw != nil && fx.Expected.IsFingerprintBound {
|
||||||
|
h := keysat.HashFingerprint(*fx.Expected.FingerprintRaw)
|
||||||
|
if hex.EncodeToString(h[:]) != fx.Expected.FingerprintHashHex {
|
||||||
|
t.Errorf("%s: HashFingerprint(raw) does not match wire hash", name)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestCrosscheck_V1(t *testing.T) {
|
||||||
|
v := loadVector(t)
|
||||||
|
checkFixture(t, "v1", v.V1)
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestCrosscheck_V2_TrialWithEntitlements(t *testing.T) {
|
||||||
|
v := loadVector(t)
|
||||||
|
checkFixture(t, "v2", v.V2)
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestCrosscheck_V2_PerpetualUnbound(t *testing.T) {
|
||||||
|
v := loadVector(t)
|
||||||
|
checkFixture(t, "v2_perpetual_unbound", v.V2PerpetualUnbound)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Exercise signature verification end-to-end: load the vector's
|
||||||
|
// public key, parse the v2 fixture, verify. Locks in the
|
||||||
|
// PEM → ed25519.PublicKey path on top of the parser.
|
||||||
|
func TestCrosscheck_V2_SignatureVerifies(t *testing.T) {
|
||||||
|
v := loadVector(t)
|
||||||
|
pub, err := keysat.LoadPublicKeyPEM(v.PublicKeyPEM)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("LoadPublicKeyPEM: %v", err)
|
||||||
|
}
|
||||||
|
payload, err := keysat.ParseAndVerify(v.V2.LicenseKey, pub)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("ParseAndVerify: %v", err)
|
||||||
|
}
|
||||||
|
if payload.Version != keysat.KeyVersionV2 {
|
||||||
|
t.Errorf("unexpected version: %d", payload.Version)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,34 @@
|
|||||||
|
// Offline verification example — `go run examples/offline_verify.go`
|
||||||
|
// from the package root. Replace the embedded pubkey + license key
|
||||||
|
// with your own.
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
"log"
|
||||||
|
"time"
|
||||||
|
|
||||||
|
"github.com/keysat-xyz/keysat-client-go"
|
||||||
|
)
|
||||||
|
|
||||||
|
const publicKeyPEM = `-----BEGIN PUBLIC KEY-----
|
||||||
|
MCowBQYDK2VwAyEAA6EHv/POEL4dcN0Y50vAmWfk1jCbpQ1fHdyGZBJVMbg=
|
||||||
|
-----END PUBLIC KEY-----`
|
||||||
|
|
||||||
|
const licenseKey = `LIC1-AIBW6RVE6YGS6SRIW2VD5D57N4UPBKVKVKVLXO6MZTO533XO53XO53QAAAAAAZKT6EAAAAAAABYT7MYA2NCGD73DC4G6MM5VVISRFTROCWWBECY4GJNM3LNGPQBOLFF2HM6QEA3QOJXQY3LVNR2GSLLEMV3GSY3F-QPSJIDYL6Y5TFCKXQ2SN43EDJIZIRJZCEROM2I4MJHODT6KO4KDPW6AJ3HMYJERYPD34CF2Z46PXPYFKSRZS7BDZKVKWE57UBJSTEBI`
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
pub, err := keysat.LoadPublicKeyPEM(publicKeyPEM)
|
||||||
|
if err != nil {
|
||||||
|
log.Fatalf("loading public key: %v", err)
|
||||||
|
}
|
||||||
|
payload, err := keysat.ParseAndVerify(licenseKey, pub)
|
||||||
|
if err != nil {
|
||||||
|
log.Fatalf("license invalid: %v", err)
|
||||||
|
}
|
||||||
|
fmt.Printf("OK — version=%d trial=%v fingerprint_bound=%v entitlements=%v\n",
|
||||||
|
payload.Version, payload.IsTrial(), payload.IsFingerprintBound(), payload.Entitlements)
|
||||||
|
if payload.IsExpiredAt(time.Now().Unix()) {
|
||||||
|
fmt.Println("(expired)")
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,268 @@
|
|||||||
|
// Package keysat is the Go SDK for Keysat — a self-hosted, Bitcoin-paid
|
||||||
|
// software licensing service. It parses and verifies LIC1-format
|
||||||
|
// license keys against an Ed25519 public key, and optionally validates
|
||||||
|
// them online against a running Keysat daemon.
|
||||||
|
//
|
||||||
|
// # Wire format
|
||||||
|
//
|
||||||
|
// A key string looks like LIC1-<payload_b32>-<signature_b32>. Both halves
|
||||||
|
// are RFC 4648 base32 (uppercase, no padding) of the raw bytes.
|
||||||
|
//
|
||||||
|
// # Versions
|
||||||
|
//
|
||||||
|
// v1 is the legacy 74-byte fixed payload. New keys are issued as v2,
|
||||||
|
// which adds expires_at and variable-length entitlement slugs. Both
|
||||||
|
// versions are accepted; clients should treat v1 keys as perpetual
|
||||||
|
// with no entitlements.
|
||||||
|
//
|
||||||
|
// Do not edit one SDK without the others — the wire format is
|
||||||
|
// crosscheck-tested across all four implementations (the daemon,
|
||||||
|
// the Rust SDK, the TS SDK, and this one) using the shared
|
||||||
|
// vectors at tests/crosscheck/vector.json in the parent licensing
|
||||||
|
// repo.
|
||||||
|
package keysat
|
||||||
|
|
||||||
|
import (
|
||||||
|
"crypto/ed25519"
|
||||||
|
"crypto/sha256"
|
||||||
|
"crypto/x509"
|
||||||
|
"encoding/base32"
|
||||||
|
"encoding/binary"
|
||||||
|
"encoding/pem"
|
||||||
|
"errors"
|
||||||
|
"fmt"
|
||||||
|
"strings"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Wire-format identifiers. v1 is legacy; new keys are issued as v2.
|
||||||
|
const (
|
||||||
|
KeyPrefix = "LIC1"
|
||||||
|
KeyVersionV1 byte = 1
|
||||||
|
KeyVersionV2 byte = 2
|
||||||
|
)
|
||||||
|
|
||||||
|
// Flag bits in the payload's second byte.
|
||||||
|
const (
|
||||||
|
FlagFingerprintBound byte = 0b0000_0001
|
||||||
|
FlagTrial byte = 0b0000_0010
|
||||||
|
)
|
||||||
|
|
||||||
|
// Fixed lengths.
|
||||||
|
const (
|
||||||
|
signatureLen = 64
|
||||||
|
payloadV1Len = 74
|
||||||
|
payloadV2HeadLen = 83
|
||||||
|
)
|
||||||
|
|
||||||
|
// b32 is RFC 4648 base32, uppercase, no padding — the alphabet used by
|
||||||
|
// every Keysat SDK and the daemon. Defined once so callers can't pick
|
||||||
|
// a slightly-different variant by mistake.
|
||||||
|
var b32 = base32.StdEncoding.WithPadding(base32.NoPadding)
|
||||||
|
|
||||||
|
// LicensePayload is the parsed contents of a license key, version-
|
||||||
|
// independent. v1 keys parse with ExpiresAt=0 and Entitlements=nil so
|
||||||
|
// callers don't need to branch on Version.
|
||||||
|
type LicensePayload struct {
|
||||||
|
Version byte
|
||||||
|
Flags byte
|
||||||
|
ProductID [16]byte
|
||||||
|
LicenseID [16]byte
|
||||||
|
IssuedAt int64
|
||||||
|
ExpiresAt int64 // 0 = perpetual; always 0 on v1
|
||||||
|
FingerprintHash [32]byte
|
||||||
|
Entitlements []string
|
||||||
|
}
|
||||||
|
|
||||||
|
// IsFingerprintBound reports whether the key was issued bound to a
|
||||||
|
// machine fingerprint hash (FlagFingerprintBound is set).
|
||||||
|
func (p *LicensePayload) IsFingerprintBound() bool {
|
||||||
|
return p.Flags&FlagFingerprintBound != 0
|
||||||
|
}
|
||||||
|
|
||||||
|
// IsTrial reports whether the key represents a trial (FlagTrial is set).
|
||||||
|
func (p *LicensePayload) IsTrial() bool {
|
||||||
|
return p.Flags&FlagTrial != 0
|
||||||
|
}
|
||||||
|
|
||||||
|
// IsExpiredAt reports whether the key has expired at the given Unix
|
||||||
|
// time. Perpetual keys (ExpiresAt == 0) always return false.
|
||||||
|
func (p *LicensePayload) IsExpiredAt(nowUnix int64) bool {
|
||||||
|
return p.ExpiresAt != 0 && nowUnix >= p.ExpiresAt
|
||||||
|
}
|
||||||
|
|
||||||
|
// HasEntitlement reports whether the key grants the named entitlement.
|
||||||
|
// Comparison is case-sensitive; callers should pick a canonical casing.
|
||||||
|
func (p *LicensePayload) HasEntitlement(slug string) bool {
|
||||||
|
for _, e := range p.Entitlements {
|
||||||
|
if e == slug {
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
|
||||||
|
// HashFingerprint computes SHA-256 of the supplied raw fingerprint
|
||||||
|
// string, returning the 32 raw hash bytes. Used to compare a
|
||||||
|
// machine's fingerprint against a license's bound hash without ever
|
||||||
|
// transmitting the raw fingerprint to the daemon.
|
||||||
|
//
|
||||||
|
// Mirrors keysat::crypto::hash_fingerprint in the daemon, so the
|
||||||
|
// crosscheck vectors round-trip identically.
|
||||||
|
func HashFingerprint(rawFingerprint string) [32]byte {
|
||||||
|
return sha256.Sum256([]byte(rawFingerprint))
|
||||||
|
}
|
||||||
|
|
||||||
|
// ParseKey decodes a LIC1-format key string into its payload, the raw
|
||||||
|
// signature bytes, and the canonical signed-bytes prefix that the
|
||||||
|
// signature covers. Callers typically pass (payload, sig, signed) to
|
||||||
|
// Verify next.
|
||||||
|
//
|
||||||
|
// Returns an error wrapping ErrBadFormat for any structural problem
|
||||||
|
// (wrong prefix, bad base32, truncated payload, unknown version).
|
||||||
|
func ParseKey(s string) (LicensePayload, []byte, []byte, error) {
|
||||||
|
parts := strings.Split(s, "-")
|
||||||
|
if len(parts) != 3 {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: expected LIC1-<payload>-<sig>", ErrBadFormat)
|
||||||
|
}
|
||||||
|
if parts[0] != KeyPrefix {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: prefix is %q, expected %q", ErrBadFormat, parts[0], KeyPrefix)
|
||||||
|
}
|
||||||
|
payloadBytes, err := b32.DecodeString(parts[1])
|
||||||
|
if err != nil {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: payload base32: %v", ErrBadFormat, err)
|
||||||
|
}
|
||||||
|
sigBytes, err := b32.DecodeString(parts[2])
|
||||||
|
if err != nil {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: signature base32: %v", ErrBadFormat, err)
|
||||||
|
}
|
||||||
|
if len(sigBytes) != signatureLen {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: signature is %d bytes, expected %d", ErrBadFormat, len(sigBytes), signatureLen)
|
||||||
|
}
|
||||||
|
|
||||||
|
if len(payloadBytes) < 1 {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: empty payload", ErrBadFormat)
|
||||||
|
}
|
||||||
|
version := payloadBytes[0]
|
||||||
|
|
||||||
|
var p LicensePayload
|
||||||
|
switch version {
|
||||||
|
case KeyVersionV1:
|
||||||
|
if len(payloadBytes) != payloadV1Len {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: v1 payload is %d bytes, expected %d", ErrBadFormat, len(payloadBytes), payloadV1Len)
|
||||||
|
}
|
||||||
|
p = LicensePayload{
|
||||||
|
Version: KeyVersionV1,
|
||||||
|
Flags: payloadBytes[1],
|
||||||
|
IssuedAt: int64(binary.BigEndian.Uint64(payloadBytes[34:42])),
|
||||||
|
ExpiresAt: 0,
|
||||||
|
}
|
||||||
|
copy(p.ProductID[:], payloadBytes[2:18])
|
||||||
|
copy(p.LicenseID[:], payloadBytes[18:34])
|
||||||
|
copy(p.FingerprintHash[:], payloadBytes[42:74])
|
||||||
|
|
||||||
|
case KeyVersionV2:
|
||||||
|
if len(payloadBytes) < payloadV2HeadLen {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: v2 payload is %d bytes, need at least %d", ErrBadFormat, len(payloadBytes), payloadV2HeadLen)
|
||||||
|
}
|
||||||
|
p = LicensePayload{
|
||||||
|
Version: KeyVersionV2,
|
||||||
|
Flags: payloadBytes[1],
|
||||||
|
IssuedAt: int64(binary.BigEndian.Uint64(payloadBytes[34:42])),
|
||||||
|
ExpiresAt: int64(binary.BigEndian.Uint64(payloadBytes[42:50])),
|
||||||
|
}
|
||||||
|
copy(p.ProductID[:], payloadBytes[2:18])
|
||||||
|
copy(p.LicenseID[:], payloadBytes[18:34])
|
||||||
|
copy(p.FingerprintHash[:], payloadBytes[50:82])
|
||||||
|
|
||||||
|
// Entitlement count + variable-length tail.
|
||||||
|
numEnts := int(payloadBytes[82])
|
||||||
|
off := payloadV2HeadLen
|
||||||
|
for i := 0; i < numEnts; i++ {
|
||||||
|
if off >= len(payloadBytes) {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: entitlement count %d but truncated tail", ErrBadFormat, numEnts)
|
||||||
|
}
|
||||||
|
slugLen := int(payloadBytes[off])
|
||||||
|
off++
|
||||||
|
if off+slugLen > len(payloadBytes) {
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: entitlement %d declares %d bytes but only %d remain", ErrBadFormat, i, slugLen, len(payloadBytes)-off)
|
||||||
|
}
|
||||||
|
p.Entitlements = append(p.Entitlements, string(payloadBytes[off:off+slugLen]))
|
||||||
|
off += slugLen
|
||||||
|
}
|
||||||
|
// We don't error on trailing bytes: a future SDK might append fields,
|
||||||
|
// and this one should still parse the prefix it understands.
|
||||||
|
|
||||||
|
default:
|
||||||
|
return LicensePayload{}, nil, nil, fmt.Errorf("%w: unknown version %d", ErrBadFormat, version)
|
||||||
|
}
|
||||||
|
|
||||||
|
return p, sigBytes, payloadBytes, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// Verify checks that the signature was made over signedBytes by the
|
||||||
|
// holder of the private key corresponding to pub. signedBytes is what
|
||||||
|
// ParseKey returns as its third value — the raw payload bytes BEFORE
|
||||||
|
// base32 decoding (Ed25519 signs raw bytes, not their base32 form).
|
||||||
|
//
|
||||||
|
// Returns nil if the signature is valid, ErrBadSignature otherwise.
|
||||||
|
func Verify(pub ed25519.PublicKey, signedBytes, signature []byte) error {
|
||||||
|
if len(pub) != ed25519.PublicKeySize {
|
||||||
|
return fmt.Errorf("%w: public key is %d bytes, expected %d", ErrBadSignature, len(pub), ed25519.PublicKeySize)
|
||||||
|
}
|
||||||
|
if len(signature) != ed25519.SignatureSize {
|
||||||
|
return fmt.Errorf("%w: signature is %d bytes, expected %d", ErrBadSignature, len(signature), ed25519.SignatureSize)
|
||||||
|
}
|
||||||
|
if !ed25519.Verify(pub, signedBytes, signature) {
|
||||||
|
return ErrBadSignature
|
||||||
|
}
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// ParseAndVerify is a convenience wrapper around ParseKey + Verify
|
||||||
|
// that returns the parsed payload only when the signature is valid.
|
||||||
|
// Most application code should call this rather than the lower-level
|
||||||
|
// pieces.
|
||||||
|
func ParseAndVerify(keyString string, pub ed25519.PublicKey) (LicensePayload, error) {
|
||||||
|
payload, sig, signed, err := ParseKey(keyString)
|
||||||
|
if err != nil {
|
||||||
|
return LicensePayload{}, err
|
||||||
|
}
|
||||||
|
if err := Verify(pub, signed, sig); err != nil {
|
||||||
|
return LicensePayload{}, err
|
||||||
|
}
|
||||||
|
return payload, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// LoadPublicKeyPEM parses a PEM-encoded Ed25519 public key (the format
|
||||||
|
// the daemon emits via /v1/issuer/public-key and embeds in operator-
|
||||||
|
// distributed SDKs). Returns the key ready to pass to Verify or
|
||||||
|
// ParseAndVerify.
|
||||||
|
func LoadPublicKeyPEM(pemData string) (ed25519.PublicKey, error) {
|
||||||
|
block, _ := pem.Decode([]byte(pemData))
|
||||||
|
if block == nil {
|
||||||
|
return nil, fmt.Errorf("no PEM block found")
|
||||||
|
}
|
||||||
|
if block.Type != "PUBLIC KEY" {
|
||||||
|
return nil, fmt.Errorf("expected 'PUBLIC KEY' PEM block, got %q", block.Type)
|
||||||
|
}
|
||||||
|
pub, err := x509.ParsePKIXPublicKey(block.Bytes)
|
||||||
|
if err != nil {
|
||||||
|
return nil, fmt.Errorf("parse PKIX public key: %w", err)
|
||||||
|
}
|
||||||
|
ed, ok := pub.(ed25519.PublicKey)
|
||||||
|
if !ok {
|
||||||
|
return nil, fmt.Errorf("PEM does not contain an Ed25519 key (got %T)", pub)
|
||||||
|
}
|
||||||
|
return ed, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// Sentinel error values. Wrap with fmt.Errorf("%w: ...") to add
|
||||||
|
// context; check with errors.Is.
|
||||||
|
var (
|
||||||
|
// ErrBadFormat is returned when a key string is structurally
|
||||||
|
// invalid — wrong prefix, bad base32, truncated payload, etc.
|
||||||
|
ErrBadFormat = errors.New("bad_format")
|
||||||
|
// ErrBadSignature is returned when the parsed signature does not
|
||||||
|
// match the payload + public key.
|
||||||
|
ErrBadSignature = errors.New("bad_signature")
|
||||||
|
)
|
||||||
@@ -0,0 +1,156 @@
|
|||||||
|
// Online validation against a running Keysat daemon. Use this when
|
||||||
|
// you want to honour revocation, machine-cap enforcement, or
|
||||||
|
// fingerprint binding — the offline ParseAndVerify path can't see
|
||||||
|
// post-issuance state changes.
|
||||||
|
//
|
||||||
|
// Most software calls Validate at startup (or first use), trusts
|
||||||
|
// the result for some grace period, and falls back to offline
|
||||||
|
// verification if the daemon is unreachable.
|
||||||
|
|
||||||
|
package keysat
|
||||||
|
|
||||||
|
import (
|
||||||
|
"bytes"
|
||||||
|
"context"
|
||||||
|
"encoding/json"
|
||||||
|
"fmt"
|
||||||
|
"io"
|
||||||
|
"net/http"
|
||||||
|
"strings"
|
||||||
|
"time"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Client talks to a running Keysat daemon's public API. Construct
|
||||||
|
// with NewClient.
|
||||||
|
type Client struct {
|
||||||
|
BaseURL string
|
||||||
|
HTTP *http.Client
|
||||||
|
}
|
||||||
|
|
||||||
|
// NewClient returns a Client pointed at the daemon at baseURL with a
|
||||||
|
// 10-second default HTTP timeout. Pass a nil http.Client to use the
|
||||||
|
// default; pass your own to customise (proxy, custom transport, etc.).
|
||||||
|
func NewClient(baseURL string, httpClient *http.Client) *Client {
|
||||||
|
if httpClient == nil {
|
||||||
|
httpClient = &http.Client{Timeout: 10 * time.Second}
|
||||||
|
}
|
||||||
|
return &Client{
|
||||||
|
BaseURL: strings.TrimRight(baseURL, "/"),
|
||||||
|
HTTP: httpClient,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ValidateRequest is the body of POST /v1/validate. Only Key is
|
||||||
|
// required; the rest fine-tune the validation.
|
||||||
|
type ValidateRequest struct {
|
||||||
|
Key string `json:"key"`
|
||||||
|
// ProductSlug, when non-empty, makes the daemon reject keys
|
||||||
|
// issued for a different product even if otherwise valid.
|
||||||
|
ProductSlug string `json:"product_slug,omitempty"`
|
||||||
|
// Fingerprint, when non-empty, the first successful validation
|
||||||
|
// binds this fingerprint to the license row; later validations
|
||||||
|
// succeed only if it matches. SHA-256 hash is computed
|
||||||
|
// daemon-side, so pass the raw value (machine UUID, etc.).
|
||||||
|
Fingerprint string `json:"fingerprint,omitempty"`
|
||||||
|
// Hostname is an optional human-friendly label stored on the
|
||||||
|
// machines row.
|
||||||
|
Hostname string `json:"hostname,omitempty"`
|
||||||
|
// Platform is an optional descriptor like "linux-x64",
|
||||||
|
// "darwin-arm64", "win-x64".
|
||||||
|
Platform string `json:"platform,omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// ValidateResponse is the daemon's reply. HTTP is always 200; the
|
||||||
|
// boolean OK + machine-readable Reason field signal success/failure.
|
||||||
|
type ValidateResponse struct {
|
||||||
|
OK bool `json:"ok"`
|
||||||
|
Reason string `json:"reason,omitempty"`
|
||||||
|
LicenseID string `json:"license_id,omitempty"`
|
||||||
|
ProductID string `json:"product_id,omitempty"`
|
||||||
|
ProductSlug string `json:"product_slug,omitempty"`
|
||||||
|
IssuedAt string `json:"issued_at,omitempty"`
|
||||||
|
ExpiresAt string `json:"expires_at,omitempty"`
|
||||||
|
GraceUntil string `json:"grace_until,omitempty"`
|
||||||
|
InGracePeriod *bool `json:"in_grace_period,omitempty"`
|
||||||
|
IsTrial *bool `json:"is_trial,omitempty"`
|
||||||
|
Entitlements []string `json:"entitlements,omitempty"`
|
||||||
|
Status string `json:"status,omitempty"`
|
||||||
|
MachineID string `json:"machine_id,omitempty"`
|
||||||
|
MaxMachines *int64 `json:"max_machines,omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// Validate calls POST /v1/validate. The daemon returns 200 in all
|
||||||
|
// cases; structural HTTP / JSON errors are surfaced here, license
|
||||||
|
// failures are conveyed via ValidateResponse.OK + Reason. Inspect
|
||||||
|
// resp.OK before trusting the rest of the fields.
|
||||||
|
func (c *Client) Validate(ctx context.Context, req ValidateRequest) (ValidateResponse, error) {
|
||||||
|
body, err := json.Marshal(req)
|
||||||
|
if err != nil {
|
||||||
|
return ValidateResponse{}, fmt.Errorf("marshal request: %w", err)
|
||||||
|
}
|
||||||
|
httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost,
|
||||||
|
c.BaseURL+"/v1/validate", bytes.NewReader(body))
|
||||||
|
if err != nil {
|
||||||
|
return ValidateResponse{}, fmt.Errorf("build request: %w", err)
|
||||||
|
}
|
||||||
|
httpReq.Header.Set("content-type", "application/json")
|
||||||
|
|
||||||
|
resp, err := c.HTTP.Do(httpReq)
|
||||||
|
if err != nil {
|
||||||
|
return ValidateResponse{}, fmt.Errorf("validate request: %w", err)
|
||||||
|
}
|
||||||
|
defer resp.Body.Close()
|
||||||
|
|
||||||
|
respBody, err := io.ReadAll(resp.Body)
|
||||||
|
if err != nil {
|
||||||
|
return ValidateResponse{}, fmt.Errorf("read response body: %w", err)
|
||||||
|
}
|
||||||
|
if resp.StatusCode != http.StatusOK {
|
||||||
|
return ValidateResponse{}, fmt.Errorf("daemon returned HTTP %d: %s", resp.StatusCode, string(respBody))
|
||||||
|
}
|
||||||
|
|
||||||
|
var out ValidateResponse
|
||||||
|
if err := json.Unmarshal(respBody, &out); err != nil {
|
||||||
|
return ValidateResponse{}, fmt.Errorf("decode response: %w (body=%s)", err, string(respBody))
|
||||||
|
}
|
||||||
|
return out, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// PublicKey fetches the daemon's PEM-encoded Ed25519 public key from
|
||||||
|
// /v1/pubkey. Useful for SDK consumers who want to verify offline
|
||||||
|
// against a daemon they trust to publish the key over HTTPS.
|
||||||
|
//
|
||||||
|
// Production deployments should embed the key at build time rather
|
||||||
|
// than fetching it; this function is primarily for development
|
||||||
|
// convenience.
|
||||||
|
func (c *Client) PublicKey(ctx context.Context) (string, error) {
|
||||||
|
httpReq, err := http.NewRequestWithContext(ctx, http.MethodGet, c.BaseURL+"/v1/pubkey", nil)
|
||||||
|
if err != nil {
|
||||||
|
return "", err
|
||||||
|
}
|
||||||
|
resp, err := c.HTTP.Do(httpReq)
|
||||||
|
if err != nil {
|
||||||
|
return "", fmt.Errorf("fetch pubkey: %w", err)
|
||||||
|
}
|
||||||
|
defer resp.Body.Close()
|
||||||
|
body, err := io.ReadAll(resp.Body)
|
||||||
|
if err != nil {
|
||||||
|
return "", err
|
||||||
|
}
|
||||||
|
if resp.StatusCode != http.StatusOK {
|
||||||
|
return "", fmt.Errorf("daemon returned HTTP %d: %s", resp.StatusCode, string(body))
|
||||||
|
}
|
||||||
|
// /v1/pubkey returns JSON like {"public_key_pem": "..."}.
|
||||||
|
var wrap struct {
|
||||||
|
PublicKeyPEM string `json:"public_key_pem"`
|
||||||
|
}
|
||||||
|
if err := json.Unmarshal(body, &wrap); err != nil {
|
||||||
|
// If it's already raw PEM, return as-is — older daemons did
|
||||||
|
// this and we want to stay compatible.
|
||||||
|
if strings.Contains(string(body), "BEGIN PUBLIC KEY") {
|
||||||
|
return string(body), nil
|
||||||
|
}
|
||||||
|
return "", fmt.Errorf("decode pubkey response: %w", err)
|
||||||
|
}
|
||||||
|
return wrap.PublicKeyPEM, nil
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user