auth

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: AGPL-3.0 Imports: 11 Imported by: 0

Documentation

Overview

Package auth defines the unified permission model for the Varwof PKI ecosystem.

All sub-projects (varwof-core, pki-gateway, pki-web-console, etc.) share this package, ensuring a single source of truth for permission definitions and avoiding duplicated implementations across projects.

Usage:

  • Permission check: auth.HasPerm(role, auth.PermCertIssue)
  • Certificate role extraction: auth.ExtractRoles(cert, auth.NSGateway)
  • Role matching: auth.HasRole(extracted, allowed)

Namespaces:

  • Varwof core roles (no prefix): superadmin, admin, operator, revoker, auditor, readonly, console, auto-renew, reporter
  • Gateway roles (gateway:): gateway:admin, gateway:mysql-prod
  • Web Console roles (web:): web:admin (reserved)

Index

Constants

This section is empty.

Variables

View Source 
var DefaultAuthzJSON []byte

DefaultAuthzJSON is the raw content of the built-in default authorization policy file (authz.json). The init-full bootstrap flow uses it to generate <baseDir>/authz.json and load it, so m-superadmin certificates automatically carry full PrincipalAuthorization grants.

View Source 
var RolePermissions = map[string][]Permission{
	"superadmin": {
		PermCACreate, PermCADelete,
		PermCAList, PermCAInfo,
		PermCertIssue, PermCertRevoke, PermCertRenew, PermCertList, PermCertExport, PermCertBatch,
		PermCRLGenerate,
		PermUserManage, PermUserList, PermUserRevokeAll,
		PermLogRead, PermLogExport,
		PermConfigRead, PermConfigWrite,
		PermReportView, PermReportExport, PermReportGenerate,
		PermRAApprove, PermRAReject,
		PermCrossIssue, PermCrossRevoke,
		PermWebhookManage,
		PermKeyRecover,
		PermDNSManage,
		PermTrustImport, PermTrustList, PermTrustDelete,
		PermAgentManage,
		PermSwaggerView, PermWebView,
		PermMetricsRead,
	},
	"admin": {
		PermCAList, PermCAInfo,
		PermCertIssue, PermCertRevoke, PermCertRenew, PermCertList, PermCertExport, PermCertBatch,
		PermCRLGenerate,
		PermLogRead, PermLogExport,
		PermReportView, PermReportExport, PermReportGenerate,
		PermRAApprove, PermRAReject,
		PermCrossIssue, PermCrossRevoke,
		PermWebhookManage,
		PermKeyRecover,
		PermDNSManage,
		PermTrustImport, PermTrustList, PermTrustDelete,
		PermAgentManage,
		PermSwaggerView, PermWebView,
		PermMetricsRead,
	},
	"operator": {
		PermCAList, PermCAInfo,
		PermCertIssue, PermCertRevoke, PermCertRenew, PermCertList, PermCertExport, PermCertBatch,
		PermCRLGenerate,
		PermLogRead, PermLogExport,
		PermReportView, PermReportExport, PermReportGenerate,
		PermRAApprove, PermRAReject,
		PermCrossIssue, PermCrossRevoke,
		PermWebhookManage,
		PermKeyRecover,
		PermDNSManage,
		PermTrustImport, PermTrustList, PermTrustDelete,
		PermAgentManage,
		PermSwaggerView, PermWebView,
		PermMetricsRead,
	},
	"revoker": {
		PermCAList, PermCAInfo,
		PermCertList, PermCertRevoke,
		PermLogRead,
		PermReportView,
		PermWebView,
	},
	"auditor": {
		PermCAList, PermCAInfo,
		PermCertList,
		PermLogRead, PermLogExport,
		PermReportView, PermReportExport,
		PermSwaggerView, PermWebView,
	},
	"readonly": {
		PermCAList, PermCAInfo,
		PermCertList,
		PermSwaggerView, PermWebView,
	},
	"console": {
		PermCAList, PermCAInfo,
		PermCertIssue, PermCertRevoke, PermCertRenew, PermCertList, PermCertExport,
		PermCRLGenerate,
		PermLogRead,
		PermReportView, PermReportGenerate,
		PermRAApprove, PermRAReject,
		PermTrustList,
		PermWebView, PermSwaggerView,
	},
	"auto-renew": {
		PermCAList, PermCAInfo,
		PermCertList, PermCertRenew, PermCertExport,
		PermLogRead,
		PermWebView,
	},
	"reporter": {
		PermCAList, PermCAInfo,
		PermCertList,
		PermLogRead,
		PermReportView, PermReportExport, PermReportGenerate,
		PermWebView,
	},
}

RolePermissions is the single source of truth for varwof core role → permission mappings. Currently 9 roles: superadmin, admin, operator, revoker, auditor, readonly, console, auto-renew, reporter When adding new roles or permissions, RoleNames and tests must be updated accordingly.

Functions

func CheckCertRoles 

func CheckCertRoles(cert *x509.Certificate, ns RoleNamespace, allowed []string) bool

CheckCertRoles is a convenience combination of ExtractRoles + HasRole. Checks whether the certificate has any allowed role under the specified namespace.

func ExtractRoles 

func ExtractRoles(cert *x509.Certificate, ns RoleNamespace) []string

ExtractRoles extracts roles under the specified namespace from the certificate Subject OU. Examples: 

cert OU = ["admin", "gateway:admin", "gateway:mysql-prod"]
ExtractRoles(cert, NSCore)    → ["admin"]
ExtractRoles(cert, NSGateway) → ["gateway:admin", "gateway:mysql-prod"]

func HasPerm 

func HasPerm(role string, perm Permission) bool

HasPerm checks whether a role has the specified permission. Returns false if the role does not exist. Prefers Policy (authz.json); falls back to the hardcoded RolePermissions when no Policy is loaded.

func HasRole 

func HasRole(roles []string, allowed []string) bool

HasRole checks whether the roles list matches any role in the allowed list. Supports exact matching and wildcard `*` (used in extracted roles). Examples: 

HasRole(["gateway:admin"], ["gateway:admin"])              → true
HasRole(["gateway:*"], ["gateway:mysql-prod"])              → true (* matches all)
HasRole(["gateway:mysql-prod"], ["gateway:admin"])          → false

func IsAdminOU 

func IsAdminOU(ou string) bool

IsAdminOU checks whether the OU represents an admin role (compatible with core's admin and gateway's gateway:admin).

func LoadCAFromFile 

func LoadCAFromFile(path string) (*x509.CertPool, error)

LoadCAFromFile loads a PEM CA chain as a CertPool.

func MatchCapability 

func MatchCapability(id, pattern string) bool

func ParseCertPEM 

func ParseCertPEM(data []byte) (*x509.Certificate, error)

ParseCertPEM parses the first certificate from PEM bytes.

func RoleNames 

func RoleNames() []string

RoleNames returns all defined varwof core role names.

func SetPolicy 

func SetPolicy(p *Policy)

func SignerHasAdminOU 

func SignerHasAdminOU(cert *x509.Certificate) bool

SignerHasAdminOU checks whether the signer certificate carries an admin OU.

func ValidateOUS 

func ValidateOUS(ous []string) error

ValidateOUS rejects OU values that would be interpreted as wildcard roles by HasRole/ExtractRoles (M24 fix). A certificate whose OU is "*" or "gateway:*" would match any role and is an elevation channel if the requester controls OU. Allowed OU values are non-empty, wildcard-free, and free of control characters.

func VerifySignedPolicy 

func VerifySignedPolicy(sigDER, policyData []byte, opts *PolicySignatureOptions) (*x509.Certificate, error)

VerifySignedPolicy verifies a PKCS#7 detached signature (policyData is the raw policy bytes). On success it returns the signer certificate for further caller checks (OU/status).

Types

type GatewayNS 

type GatewayNS struct {
	DisplayName string   `json:"display_name"`
	Prefix      string   `json:"prefix"`
	Grants      []string `json:"grants"`
}

type GrantCap 

type GrantCap struct {
	Scheme       string
	CapabilityID string
}

GrantCap represents a parsed permission grant (scheme_id + capability_id).

type Permission 

type Permission string

Permission defines a single permission string. Format: <resource>:<action> 

const (
	PermCACreate Permission = "ca:create"
	PermCADelete Permission = "ca:delete"
	PermCAList   Permission = "ca:list"
	PermCAInfo   Permission = "ca:info"

	PermCertIssue  Permission = "cert:issue"
	PermCertRevoke Permission = "cert:revoke"
	PermCertRenew  Permission = "cert:renew"
	PermCertList   Permission = "cert:list"
	PermCertExport Permission = "cert:export"
	PermCertBatch  Permission = "cert:batch"

	PermCRLGenerate Permission = "crl:generate"

	PermUserManage Permission = "user:manage"
	PermUserList   Permission = "user:list"

	PermLogRead   Permission = "log:read"
	PermLogExport Permission = "log:export"

	PermReportView     Permission = "report:view"
	PermReportExport   Permission = "report:export"
	PermReportGenerate Permission = "report:generate"

	PermConfigRead  Permission = "config:read"
	PermConfigWrite Permission = "config:write"

	PermRAApprove Permission = "ra:approve"
	PermRAReject  Permission = "ra:reject"

	PermCrossIssue  Permission = "cross-cert:issue"
	PermCrossRevoke Permission = "cross-cert:revoke"

	PermWebhookManage Permission = "webhook:manage"

	PermKeyRecover Permission = "key:recover"

	PermDNSManage Permission = "dns:manage"

	PermTrustImport Permission = "trust:import"
	PermTrustList   Permission = "trust:list"
	PermTrustDelete Permission = "trust:delete"

	PermAgentManage   Permission = "agent:manage"
	PermUserRevokeAll Permission = "user:revoke-all"

	PermSwaggerView Permission = "swagger:view"
	PermWebView     Permission = "web:view"

	PermMetricsRead Permission = "metrics:read"
)

type Policy 

type Policy struct {
	Version           string               `json:"version"`
	Roles             map[string]RoleDef   `json:"roles"`
	OUMapping         map[string]string    `json:"ou_mapping"`
	GatewayNamespaces map[string]GatewayNS `json:"gateway_namespaces"`
	// CapabilityParameters is the parameter defaults map derived by gen-authz from capability.json,
	// keyed by "scheme:capability_id" (e.g. "varwof/core-v1:cert:issue").
	// Used at runtime to validate whether AIC/PA declared parameters are within bounds.
	CapabilityParameters map[string]map[string]any `json:"capability_parameters,omitempty"`
}

func GetPolicy 

func GetPolicy() *Policy

func LoadPolicy 

func LoadPolicy(path string) (*Policy, error)

func LoadPolicyData 

func LoadPolicyData(data []byte) (*Policy, error)

func (*Policy) HasGrant 

func (p *Policy) HasGrant(role string, capability string) bool

func (*Policy) HasParamDefault 

func (p *Policy) HasParamDefault(scheme, capID, param string) (any, bool)

HasParamDefault checks whether a parameter has a default value (for bounds checking).

func (*Policy) IntersectGrants 

func (p *Policy) IntersectGrants(roles []string, aicCapIds []string) []string

func (*Policy) MatchGrants 

func (p *Policy) MatchGrants(roles []string, capabilities []string) []string

func (*Policy) ParamDefaults 

func (p *Policy) ParamDefaults(scheme, capID string) map[string]any

ParamDefaults returns the parameter defaults for a given scheme:capability_id (derived by gen-authz). Returns nil if not found.

func (*Policy) ProfileRoles 

func (p *Policy) ProfileRoles(profile string) []string

func (*Policy) RoleByOU 

func (p *Policy) RoleByOU(ou string) string

func (*Policy) RoleGrantCaps 

func (p *Policy) RoleGrantCaps(role string) []GrantCap

RoleGrantCaps returns the permission grants for a role, parsed from "scheme_id:capability_id" format. scheme_id may contain "/" (e.g. "varwof/demo-mysql-v1"), capability_id may contain ":" (e.g. "SELECT:*"). Rule: find the first ":" from the right; left part is the scheme, right part is the capability_id.

func (*Policy) RoleGrants 

func (p *Policy) RoleGrants(role string) []string

func (*Policy) RoleScope 

func (p *Policy) RoleScope(role string) []string

RoleScope returns the scope list for a role, or nil if not defined.

type PolicySignatureOptions 

type PolicySignatureOptions struct {
	// Roots is the trusted CA chain (Issuing CA + Root CA) used to verify the signer certificate.
	Roots *x509.CertPool
	// RequireAdminOU forces the signer certificate OU to contain the admin role when true.
	RequireAdminOU bool
}

PolicySignatureOptions describes the external parameters for policy signature verification.

type RoleDef 

type RoleDef struct {
	DisplayName string   `json:"display_name"`
	Profiles    []string `json:"profiles"`
	Grants      []string `json:"grants"`
	Scope       []string `json:"scope,omitempty"`
}

type RoleNamespace 

type RoleNamespace string

RoleNamespace defines the role namespace prefix. Different subprojects use different namespaces to avoid OU conflicts. 

const (
	// NSCore is the varwof core role namespace (no prefix).
	// Supported names: admin, operator, revoker, auditor, readonly, console, auto-renew, reporter
	// Corresponding OU values: OU=admin, OU=operator, etc.
	NSCore RoleNamespace = ""

	// NSGateway is the pki-gateway role namespace.
	// Corresponding OU values: OU=gateway:admin, OU=gateway:mysql-prod, etc.
	NSGateway RoleNamespace = "gateway:"

	// NSWeb is the pki-web-console role namespace (reserved).
	// Corresponding OU values: OU=web:admin, etc.
	NSWeb RoleNamespace = "web:"
)

Source Files

View all Source files

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.