Help us shape the future of Go! Take the 2026 Go Developer Survey

geofence

package
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 2, 2026 License: MIT Imports: 14 Imported by: 0

README

geofence

Allows or blocks authentication based on the country the request came from.

You get two ways to express the rule. An allowlist, where only the countries you name can authenticate, or a blocklist, where everyone except the countries you name can. Pick one. The check runs before sign-in and before sign-up, so a blocked country can't create an account either.

Use it when

  • You operate under a licence or sanctions regime that only permits certain countries
  • Your product genuinely has no users outside a handful of markets, and you'd rather cut the attack surface
  • You need a fast, blunt control while you build something more nuanced

Skip it when

  • You have travelling users. A country block hits them on holiday and they will open a support ticket
  • You want a graded response instead of a hard yes or no. riskengine can step up to MFA where this plugin only blocks
  • You are not running geoip. Without a resolved location this plugin has nothing to match on

Wiring

authsome.WithPlugin(geoip.New(geoip.Config{DatabasePath: "/var/lib/geoip/GeoLite2-City.mmdb"})),
authsome.WithPlugin(geofence.New(geofence.Config{
    DefaultPolicy:    "allow_all",
    BlockedCountries: []string{"KP", "IR"},
})),

For an allowlist, flip DefaultPolicy to deny_all and fill AllowedCountries instead.

Config

Field Type Default What it does
DefaultPolicy string allow_all Action when no rule matches. allow_all or deny_all
AllowedCountries []string empty ISO 3166-1 alpha-2 codes. When set, only these get through
BlockedCountries []string empty ISO 3166-1 alpha-2 codes that are refused
BlockMessage string access denied from your location Error text returned to a blocked caller

Settings

Key Default
geofence.default_policy allow_all
geofence.allowed_countries []
geofence.blocked_countries []
geofence.block_message access denied based on location

Lifecycle hooks

Hook What happens
BeforeSignUp Refuses registration from a blocked country
BeforeSignIn Refuses the sign-in before credentials are checked
BeforePrincipalAuth Same gate for non-user principals

Requires geoip. If you want country to be one input among several rather than the whole decision, look at riskengine.

Documentation

Overview

contract.go: Wires the geofence plugin into the forge-dashboard contract surface via plugin.ContractContributor.

Package geofence provides country-based access control for authentication. It allows/blocks authentication based on the geographic location of the request IP, using GeoIP data from the geoip plugin.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// SettingDefaultPolicy is the default access policy when no country rules match.
	SettingDefaultPolicy = settings.Define("geofence.default_policy", "allow_all",
		settings.WithDisplayName("Default Policy"),
		settings.WithDescription("Default access policy when no country rules match"),
		settings.WithCategory("Geofencing"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithEnforceable(),
		settings.WithHelpText("Default access policy when no country rules match"),
		settings.WithOrder(10),
		settings.WithInputType(formconfig.FieldSelect),
		settings.WithOptions(
			formconfig.SelectOption{Label: "Allow All", Value: "allow_all"},
			formconfig.SelectOption{Label: "Block All", Value: "block_all"},
		),
	)

	// SettingAllowedCountries is the list of ISO 3166-1 alpha-2 country codes allowed.
	SettingAllowedCountries = settings.Define("geofence.allowed_countries", []string{},
		settings.WithDisplayName("Allowed Countries"),
		settings.WithDescription("ISO 3166-1 alpha-2 country codes allowed"),
		settings.WithCategory("Geofencing"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithHelpText("ISO 3166-1 alpha-2 country codes allowed. Empty means all allowed."),
		settings.WithOrder(20),
		settings.WithPlaceholder("US, GB, DE"),
	)

	// SettingBlockedCountries is the list of ISO 3166-1 alpha-2 country codes blocked.
	SettingBlockedCountries = settings.Define("geofence.blocked_countries", []string{},
		settings.WithDisplayName("Blocked Countries"),
		settings.WithDescription("ISO 3166-1 alpha-2 country codes blocked"),
		settings.WithCategory("Geofencing"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithHelpText("ISO 3166-1 alpha-2 country codes blocked."),
		settings.WithOrder(30),
		settings.WithPlaceholder("CN, RU"),
	)

	// SettingBlockMessage is the error message shown when access is denied.
	SettingBlockMessage = settings.Define("geofence.block_message", "access denied based on location",
		settings.WithDisplayName("Block Message"),
		settings.WithDescription("Error message shown when access is denied by geofence rules"),
		settings.WithCategory("Geofencing"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithHelpText("Error message shown when access is denied by geofence rules"),
		settings.WithOrder(40),
	)
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	// DefaultPolicy is the default action when no rules match.
	// "allow_all" (default) or "deny_all".
	DefaultPolicy string

	// AllowedCountries is a whitelist of ISO 3166-1 alpha-2 country codes.
	// When non-empty, only these countries are allowed.
	AllowedCountries []string

	// BlockedCountries is a blacklist of ISO 3166-1 alpha-2 country codes.
	// Requests from these countries are blocked.
	BlockedCountries []string

	// BlockMessage is the error message returned when blocked (default: "access denied from your location").
	BlockMessage string
}

Config configures the geofence plugin.

type Plugin 

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

Plugin implements country-based geofencing for auth events.

func New 

func New(cfg ...Config) *Plugin

New creates a new geofence plugin.

func (*Plugin) DeclareSettings 

func (p *Plugin) DeclareSettings(m *settings.Manager) error

DeclareSettings implements plugin.SettingsProvider. It registers all geofence-related configurable settings.

func (*Plugin) Name 

func (p *Plugin) Name() string

Name returns the plugin name.

func (*Plugin) OnBeforePrincipalAuth 

func (p *Plugin) OnBeforePrincipalAuth(ctx context.Context, a *principal.AuthAttempt) error

OnBeforePrincipalAuth checks whether a machine caller's IP is allowed by geofence rules.

The same check sign-in gets. API-key traffic reaches strategy.Authenticate and fires none of the sign-in hooks, so without this a leaked key worked from any country regardless of geofence policy.

func (*Plugin) OnBeforeSignIn 

func (p *Plugin) OnBeforeSignIn(ctx context.Context, req *account.SignInRequest) error

OnBeforeSignIn checks if the sign-in IP is allowed by geofence rules.

func (*Plugin) OnBeforeSignUp 

func (p *Plugin) OnBeforeSignUp(ctx context.Context, req *account.SignUpRequest) error

OnBeforeSignUp checks if the sign-up IP is allowed by geofence rules.

func (*Plugin) OnInit 

func (p *Plugin) OnInit(_ context.Context, engine plugin.Engine) error

OnInit discovers the geoip plugin and engine bridges.

func (*Plugin) RegisterContract 

func (p *Plugin) RegisterContract(
	d *dispatcher.Dispatcher,
	reg contract.Registry,
	wreg contract.WardenRegistry,
	engine plugin.Engine,
) error

Source Files

View all Source files

Directories

Path Synopsis
Package contract wires the geofence plugin's deep-link settings page into the forge-dashboard contract registry.
 Package contract wires the geofence plugin's deep-link settings page into the forge-dashboard contract registry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.