mirror of
https://github.com/luxfi/annulus.git
synced 2026-10-30 17:02:25 +00:00
zeekay
d2b5812200
Defines the policy that constrains which cryptographic operations a
Quasar node accepts. The package contains no cryptographic primitives.
Two values, one gate:
Profile immutable 8-byte canonical encoding; SHA3-256
hash is published in block headers.
Refuse(ctx, Op) reports whether op is admissible under the
profile bound to ctx.
Policy and enforcement are decomplected. Each constrained operation
(ECDSA precompile, pairing precompile, classical SNARK verifier)
calls Refuse once at its entry point and otherwise proceeds in its
own lane. The profile does not know how the operations compute; the
operations do not know how the profile is selected.
Presets:
Strict forbids every classical category — mainnet.
Permissive admits every operation — testnet, default for
unbound contexts.
Categories (Forbid* flags map 1:1):
CatECDSAContractAuth ECDSARecover, ECDSAVerify, Schnorr
CatClassicalSig Ed25519, X25519
CatPairingPrecompile BN254Pairing, BLS12381Pair, BLSSignature
CatKZGPrecompile KZGEval
CatClassicalSNARK Groth16, Plonk, Marlin
CatNonSHA3Hash SHA256, RIPEMD160, Blake2b, Blake2s, Keccak256
Strict profile hash (pinned in profile_test.go):
9d70a692103d09414ffb2577ca53852c99b2d13b987c49f20852899f9a0be348
Permissive profile hash:
cf7b7f49edcad4722838277dd310dcf6a61d0552ce0f2116ad39c3dcd23bd916
A change to either hash is a consensus-breaking change and requires a
canonical-encoding version bump.
Environment override: QUASAR_STRICT_PQ=1 selects Strict via
ProfileFromEnv. Mainnet binaries set it in their entrypoint.
31 unit tests; vet-clean.
68 lines
2.0 KiB
Go
68 lines
2.0 KiB
Go
package annulus
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
)
|
|
|
|
// Violation is returned when an operation is inadmissible under the
|
|
// active profile. It records the op that was rejected and the hash of
|
|
// the profile that rejected it.
|
|
type Violation struct {
|
|
Op Op
|
|
Profile [32]byte
|
|
}
|
|
|
|
// Error implements the error interface.
|
|
func (v *Violation) Error() string {
|
|
return fmt.Sprintf("annulus: %s forbidden under profile %x", v.Op, v.Profile[:8])
|
|
}
|
|
|
|
// ErrUnknownOp is returned when [Refuse] is invoked with an [Op] that
|
|
// the package does not recognize. Callers must ship a recognized op;
|
|
// the failure-closed default is to refuse.
|
|
var ErrUnknownOp = errors.New("annulus: unknown op")
|
|
|
|
// Refuse reports whether the profile bound to ctx admits op.
|
|
// A nil return means the op is allowed. A non-nil error means the op
|
|
// must not execute.
|
|
//
|
|
// When ctx carries no profile, the [Permissive] profile is used. When
|
|
// ctx is nil, Refuse panics; this signals a programmer error.
|
|
//
|
|
// Refuse is the single profile gate. Each constrained operation calls
|
|
// it once at the top of its entry point and otherwise proceeds in its
|
|
// own lane.
|
|
func Refuse(ctx context.Context, op Op) error {
|
|
if ctx == nil {
|
|
panic("annulus.Refuse: nil context")
|
|
}
|
|
p := FromContext(ctx)
|
|
return RefuseUnder(p, op)
|
|
}
|
|
|
|
// RefuseUnder is the context-free variant of [Refuse]. It is the
|
|
// canonical entry point for unit tests and for subsystems that resolve
|
|
// the active profile through their own indirection.
|
|
func RefuseUnder(p Profile, op Op) error {
|
|
cat := CategoryOf(op)
|
|
if cat == CatUnknown {
|
|
return fmt.Errorf("%w: %s", ErrUnknownOp, op)
|
|
}
|
|
if !p.Forbids(cat) {
|
|
return nil
|
|
}
|
|
h := p.Hash()
|
|
return &Violation{Op: op, Profile: h}
|
|
}
|
|
|
|
// MustRefuse is the panicking variant of [Refuse]; suitable only for
|
|
// initialisation paths where a profile violation indicates a build
|
|
// configuration error rather than a runtime input.
|
|
func MustRefuse(ctx context.Context, op Op) {
|
|
if err := Refuse(ctx, op); err != nil {
|
|
panic(err)
|
|
}
|
|
}
|