register

README

varwof-register

⭐ Like this repo? Give a star to the flagship one:

Capability Registry — standard capability definition, validation, and authz.json generation for fine-grained AI Agent permission control.

⚠️ Preview — Not for production use. APIs and features may change before official release.

中文

What is varwof-register?

A registry of standard capability definitions for fine-grained AI Agent permission control. Capability specifications are carried by executable JSON files (capability.json), support PKCS#7 signatures, and can generate authz.json authorization policies (gen-authz tool).

Quick Start

cd register

# Capability data lives in the sibling capability module.
export CAPABILITY_DIR=../capability/data

# List all capabilities
go run ./cmd/gen-authz -list $CAPABILITY_DIR/varwof/core/v1.json

# Generate authz.json
go run ./cmd/gen-authz -out /tmp/authz.json $CAPABILITY_DIR/varwof/core/v1.json

# Validate / search capabilities
go run ./demo -data $CAPABILITY_DIR validate varwof/core-v1:cert:issue
go run ./demo -data $CAPABILITY_DIR search issue

Installation

go get github.com/varwof/register@v0.1.0

Directory Structure

register/
├── semantics/        # CLC-v1 decision layer (grammar, entailment, decision)
├── ruleexec/         # execution layer (rules, conditions, flow, budgets, SQL)
├── schema.go / registry.go / validator.go / mincap.go
├── genauthz.go / gendocs.go / sign.go / loader.go / params_validate.go
├── cmd/{gen-authz,gen-docs,gen-capability,gen-backfill,gen-rule,sign,verify,vectors-run}/
├── demo/             # capability demo (needs -data <capability data dir>)
├── demo/rule-exec/   # rule-exec e2e demo + rule.schema.json + TS mirror
├── docs/             # user docs
└── dev-docs/         # developer docs

Capability definitions themselves are not in this repository; they live in the separate capability module (../capability/data/<vendor>/<product>/v*.json).

Provenance and licensing

semantics/ and the rest of this repository are written from published specifications and this project's own language text; no third-party code was copied. Where a specification's rule is normative here, it is cited by section and restated in this project's own words rather than reproduced, and the Internet-Drafts referred to are referenced as work in progress, not as normative sources. The conformance corpora live in varwof/capability (data/_vectors/clc-v1/).

CLC-v1 semantics (semantics/) and conformance runner

Two orthogonal axes, not a stack: the decision axis decides whether a call counts as doing something that was authorized, the execution axis decides whether to act now and what to record. CLC owns the decision axis; ruleexec/ owns the execution axis (see docs/capability-language-layers.md). Across both run the authorization face ("what may be done") and the evidence face ("what was done, and the evidence for it"). A draft such as ACA is a composition contract over these two axes, not a third layer.

semantics/ is the Go reference implementation of CLC-v1, in two groups:

Core semantics — required by the conformance classes:

Function	Purpose
ValidateCapabilityID	§3 grammar (v1: literal + trailing * only)
Entails(grant, op)	authorization binding (§6)
Intersect(grants...)	effective grant set (§7)
Authorize(grant, op)	decision function (§9)
Combine(alg, decisions...)	conflict resolution across sources (default deny-overrides)
Discharge(decision, understood)	consumer-side obligation rule (§8.4 + XACML §2.13/§7.2.1)
EvaluateEvidenceConstraint	evidence-side value grammar and three-valued evaluation (§8.2/§10)
Requirement / EvaluateRequirement	the relying party's sufficiency bar (CLC-REQUIREMENT-v1)
ComputeActionID / Match	instance identity and binding (§4.2/§6.4)
CanonicalJSON	JCS canonicalization for digests

Optional profile — carried, not required: a deployment that only decides online pays none of this. Everything here is off unless a caller turns it on:

Function	Purpose
Record / RecordWith	Decision Record: frozen inputs + verdict, independently re-computable
RecordWithContext / VerifyAsOf	RATS §10 freshness input (explicit clock / nonce / epoch)
SourceChain / StandingOn	the authorization sources a decision rested on (byte-backed edges)
Envelope / PAE	DSSE + in-toto transport for a record (cmd/record -envelope)
BuildChallengeFromDecision	the machine-readable "what is still missing" (CLC-CHALLENGE-v1)
DecisionRecord.Verify()	re-run the language over a record and check digest, verdict and residual obligations

Failures are fail-closed and carry stable reason codes (§9.4); when several conditions fail, the normative ordering (§9.3) selects the single reported code.

Run the shared conformance vectors — verdict and normative reason are both asserted, and the process exits non-zero on any mismatch:

CLC_VECTORS=../capability/data/_vectors/clc-v1/vectors.json go run ./cmd/vectors-run/

The evidence side has its own corpus and runner (CLC-E, 30 vectors):

CLC_EVIDENCE_VECTORS=../capability/data/_vectors/clc-v1/evidence-vectors.json go run ./cmd/evidence-vectors-run/

Byte budget of the optional artifacts is reproducible (record / envelope / challenge sizes, and the constraint strings that drive certificate size):

go run ./cmd/size-report/

CI (.github/workflows/clc-conformance.yml) clones varwof/capability and runs gofmt / go vet / go test / the vectors on every push and pull request.

Decision Records (semantics/record.go)

Record freezes what was decided — the canonical inputs, the CLC revision, the verdict, the reason and the residual obligations — behind a SHA-256 digest of the inputs, so a holder of the record alone can re-run the same revision and get the same answer. Verify does exactly that, and fails closed with record_input_digest_mismatch, record_verdict_mismatch, record_operation_count or record_unsupported_revision on anything that does not reproduce.

go run ./cmd/record input.json          # {"grants":[...],"operation":{...}} -> record
go run ./cmd/record -verify record.json # re-run the language over a record

Note: CanonicalJSON implements RFC 8785 (JCS) — object members ordered by UTF-16 code units, §3.2.2.2 string escaping, ECMAScript Number::toString — so clc-action: identifiers and Decision Record digests agree with any other JCS implementation. (Before rev CLC-1.6 it was json.Marshal, whose HTML escaping made &/</> digests non-JCS.) Constraint evaluation results and authorization source chains are not part of a record yet — see dev-docs/README.md.

Execution layer (ruleexec/)

ruleexec runs signed rules: op | if | seq control flow over runtime context conditions, a fixed budget (steps / depth / nesting) and fully parameterized SQL generation. The execution language deliberately contains no loops, no retries, no time-in and no contains — those belong to the caller/job orchestrator or to authorization constraints.

• docs/capability-language-layers.md — one language, two layers; the rule publication boundary (RuleWithinSignerGrant).
• docs/rule-authoring.md — how to write a rule file: fields, the closed operator set, the parameter contract, the gate matrix.
• docs/toolchain.md — end-to-end flow and every tool (gen-rule included) with its usage.
• docs/condition-semantics.md — null / type / case / SQL mapping rules and the shared test vectors.

Ecosystem

graph TB
    subgraph varwof["varwof Ecosystem"]
        core["core"]
        gw["gateway"]
        cap["capability<br/>JSON Data"]
        reg["register<br/>Capability Registry"]
    end
    reg -->|loads| cap
    core -->|validates against| reg
    gw -->|validates against| reg
    reg -.->|generates| core

register is the capability specification layer of the varwof ecosystem, connecting capability (data) with core/gateway (runtime validation). This project is a member of the Open Invention Network.

Links

Homepage	https://varwof.com
Community	https://varwof.org
IETF Draft	draft-wei-aic-identity-cert
License	Apache-2.0
Member	Open Invention Network

Documentation

Overview

Byte-precise params_schema_digest backfill for capability data files.

The capability JSON files under vendor/product/v*.json carry a JSON Schema in each capability's params_schema field. To detect drift (someone editing the schema out of band), gen-backfill inserts a params_schema_digest right after every params_schema, leaving every other byte untouched.

Package register provides scheme registration and authorization generation for the varwof project.

Index

• Variables
• func BackfillParamsSchemaDigests(data []byte) ([]byte, error)
• func Deduplicate(caps []string) []string
• func FilterByScheme(caps []string, schemeID string) []string
• func FormatCapability(schemeID, capID string) string
• func FormatSchemeID(vendor, product string) string
• func GenAuthzToFile(cfg GenAuthzConfig, outputPath string) error
• func GenDocs(def *SchemeDefinition) (string, error)
• func GenDocsToFile(def *SchemeDefinition, outputPath string) error
• func GetSignerCert(p7sPath string) (*x509.Certificate, error)
• func HasSignature(capPath string) bool
• func ListCapabilities(def *SchemeDefinition) []string
• func LoadAllSchemes(root string) (map[string]*SchemeDefinition, error)
• func LoadCertFile(path string) ([]*x509.Certificate, error)
• func LoadEmbedded() (map[string]*SchemeDefinition, error)
• func LoadFromBoth(diskDir string) (map[string]*SchemeDefinition, error)
• func LoadFromDir(root string) (map[string]*SchemeDefinition, error)
• func LoadFromFS(fsys fs.FS) (map[string]*SchemeDefinition, error)
• func LoadTrustRoots(path string) ([]*x509.Certificate, error)
• func MatchCapability(id, pattern string) bool
• func ParseCapability(s string) (schemeID, capID string, ok bool)
• func ParseSchemeID(schemeID string) (vendor, product string, ok bool)
• func SignCapability(certPath, keyPath, capPath, outputPath string) error
• func ValidateSchemeID(schemeID string) error
• func ValidateSchemeParams(scheme, capability string, raw json.RawMessage) error
• func VerifyCapabilityPKCS7(capPath string, trustRoots []*x509.Certificate) error
• func VerifyCapabilityPKCS7Cert(capPath string, trustRoots []*x509.Certificate) (*x509.Certificate, error)
• func WriteScheme(def *SchemeDefinition, path string) error
• type AuthzDocument
  • func GenAuthz(cfg GenAuthzConfig) (*AuthzDocument, error)
• type AuthzRoleDef
• type CapabilityClaim
  • func ParseCapabilityClaims(data []byte) ([]CapabilityClaim, error)
• type CapabilityEntry
• type ClaimResult
• type GatewayNSDef
• type GenAuthzConfig
• type MinSetReport
• type ParameterDef
• type Registry
  • func NewRegistry() *Registry
  • func NewRegistryFromBoth(diskDir string) (*Registry, error)
  • func NewRegistryFromDisk(dir string) (*Registry, error)
  • func NewRegistryWithEmbedded() (*Registry, error)
  • func (r *Registry) CheckIntersection(setA, setB []string) (common []string)
  • func (r *Registry) CheckMinimalCapabilitySet(claims []CapabilityClaim, grantedPatterns []string) *MinSetReport
  • func (r *Registry) CheckSubset(declared, allowed []string) (denied []string)
  • func (r *Registry) Get(schemeID string) (*SchemeDefinition, bool)
  • func (r *Registry) Has(schemeID string) bool
  • func (r *Registry) HasCapability(schemeID, capID string) bool
  • func (r *Registry) Register(def *SchemeDefinition) error
  • func (r *Registry) RoleGrantCovered(schemeID, grant string) bool
  • func (r *Registry) SchemeIDs() []string
  • func (r *Registry) Summary() string
  • func (r *Registry) ValidateCapabilities(caps []string) *ValidationResult
  • func (r *Registry) ValidateCapability(formatted string) (*SchemeDefinition, *CapabilityEntry, error)
  • func (r *Registry) ValidateClaims(claims []CapabilityClaim) []ClaimResult
  • func (r *Registry) ValidateParams(scheme, capability string, params map[string]any) error
  • func (r *Registry) ValidateRoles(schemeID string) ([]string, error)
• type RoleDef
• type SchemeDefinition
  • func LoadScheme(path string) (*SchemeDefinition, error)
  • func (def *SchemeDefinition) ValidateSchemeRoles() ([]error, []string)
• type ValidationError
  • func (e ValidationError) Error() string
• type ValidationResult

Variables

var Version = "0.1.0"

Version is the package version, set via -ldflags -X github.com/varwof/register.Version=x.y.z.

Functions

func BackfillParamsSchemaDigests

func BackfillParamsSchemaDigests(data []byte) ([]byte, error)

BackfillParamsSchemaDigests inserts a params_schema_digest field directly after each capability's params_schema field in a capability JSON document, preserving all other bytes exactly (key order, whitespace, omitempty zero-values).

The digest is SHA-256 (hex-encoded) of the canonical (compacted) JSON of the params_schema value, so any semantic change to the schema is detected as drift while whitespace-only edits are not.

A params_schema that already has a params_schema_digest declared immediately after it is verified for drift instead of modified: a stale digest returns an error. Documents without any params_schema are returned unchanged.

func Deduplicate

func Deduplicate(caps []string) []string

Deduplicate removes duplicate capabilities from a list.

func FilterByScheme

func FilterByScheme(caps []string, schemeID string) []string

FilterByScheme returns only capabilities belonging to a specific scheme.

func FormatCapability

func FormatCapability(schemeID, capID string) string

FormatCapability formats a capability as "vendor/product:capability_id".

func FormatSchemeID

func FormatSchemeID(vendor, product string) string

FormatSchemeID formats vendor and product into "vendor/product".

func GenAuthzToFile

func GenAuthzToFile(cfg GenAuthzConfig, outputPath string) error

GenAuthzToFile generates and writes the authz.json file.

func GenDocs

func GenDocs(def *SchemeDefinition) (string, error)

GenDocs generates a markdown permission documentation from a capability.json scheme. The documentation targets both human readers and AI models: fully describing each capability's semantics, parameter constraints, wildcard rules, role and grants mappings, serving as the authoritative reference for AI to generate minimal privilege capability sets.

Output markdown structure:

• Product overview + capability catalog table
• Detailed capability semantics (summary/usage/when_not/examples/parameters/related)
• Wildcard and matching rules
• Role and grants mapping
• Least privilege principle guidelines

func GenDocsToFile

func GenDocsToFile(def *SchemeDefinition, outputPath string) error

GenDocsToFile generates markdown permission documentation and writes it to a file.

func GetSignerCert

func GetSignerCert(p7sPath string) (*x509.Certificate, error)

GetSignerCert extracts the signer certificate from a .p7s file.

func HasSignature

func HasSignature(capPath string) bool

HasSignature checks if a .p7s file exists for the given capability file.

func ListCapabilities

func ListCapabilities(def *SchemeDefinition) []string

ListCapabilities returns all capability IDs for a scheme, sorted.

func LoadAllSchemes

func LoadAllSchemes(root string) (map[string]*SchemeDefinition, error)

LoadAllSchemes loads all capability JSON files under a directory tree. Expected structure: root/vendor/product/v*.json

func LoadCertFile

func LoadCertFile(path string) ([]*x509.Certificate, error)

LoadCertFile reads all certificates in a certificate chain from a PEM file.

func LoadEmbedded

func LoadEmbedded() (map[string]*SchemeDefinition, error)

LoadEmbedded is removed: capability data now lives in the separate capability module and is loaded from a directory on disk. Use LoadFromDir or LoadFromBoth with a path into the capability data tree.

func LoadFromBoth

func LoadFromBoth(diskDir string) (map[string]*SchemeDefinition, error)

LoadFromBoth requires a non-empty disk directory. Embedded schemes are gone; disk is the only source. An empty dir returns an error.

func LoadFromDir

func LoadFromDir(root string) (map[string]*SchemeDefinition, error)

LoadFromDir loads all capability JSON files from a directory tree on disk. Expected structure: root/vendor/product/v*.json

func LoadFromFS

func LoadFromFS(fsys fs.FS) (map[string]*SchemeDefinition, error)

LoadFromFS loads all capability JSON files from an embedded filesystem.

func LoadTrustRoots

func LoadTrustRoots(path string) ([]*x509.Certificate, error)

LoadTrustRoots loads PEM certificates from a file or directory.

func MatchCapability

func MatchCapability(id, pattern string) bool

MatchCapability reports whether a capability ID is covered by a grant pattern using the CLC-v1 §9.3 segment grammar (audit 2026-09-16, R17): an exact match, or a trailing `*` segment that spans one or more further segments. `**`, `?`, bare `*`, and mid-segment globs are not part of the grammar and never match — the old filepath.Match behavior blessed near-everything.

func ParseCapability

func ParseCapability(s string) (schemeID, capID string, ok bool)

ParseCapability parses "vendor/product:capability_id" into scheme and capID. capability_id may itself contain colons (e.g., "query:users").

func ParseSchemeID

func ParseSchemeID(schemeID string) (vendor, product string, ok bool)

ParseSchemeID parses "vendor/product" into vendor and product.

func SignCapability

func SignCapability(certPath, keyPath, capPath, outputPath string) error

SignCapability signs a capability JSON file using PKCS#7 detached signature. certPath: PEM certificate chain (signer cert + intermediates) keyPath: PEM private key capPath: path to capability.json outputPath: path to write .p7s file (defaults to capPath + ".p7s")

func ValidateSchemeID

func ValidateSchemeID(schemeID string) error

ValidateSchemeID checks if scheme_id follows the naming convention. Public: vendor/product (e.g., oracle/mysql, varwof/core) Private: x-vendor/product (e.g., x-acme/order)

func ValidateSchemeParams

func ValidateSchemeParams(scheme, capability string, raw json.RawMessage) error

ValidateSchemeParams validates a capability's parameters against the CONTRACT OF THE SCHEME that defines them. Scheme-specific structural rules live here, with the scheme, and are NOT re-implemented by consumers such as the rule execution engine (see ruleexec and docs/capability-language-layers.md).

Generic capability semantics (nulls, explicit empty bounds, subset rules) are defined once by CLC-v1 and validated via github.com/varwof/register/semantics.

func VerifyCapabilityPKCS7

func VerifyCapabilityPKCS7(capPath string, trustRoots []*x509.Certificate) error

VerifyCapabilityPKCS7 verifies a capability JSON against its .p7s signature. trustRoots: PEM root/intermediate certificates for chain verification.

func VerifyCapabilityPKCS7Cert

func VerifyCapabilityPKCS7Cert(capPath string, trustRoots []*x509.Certificate) (*x509.Certificate, error)

VerifyCapabilityPKCS7Cert verifies a capability JSON against its .p7s signature and returns the SIGNER certificate. Verification always requires at least one trust root: signing without roots is refused because the signer certificate is recovered from the blob itself and is therefore attacker-pickable. Callers that must bind the published content to the signer's own authority (e.g. ruleexec, which requires the rule capability to be covered by the signer's AIC grant) use this variant.

func WriteScheme

func WriteScheme(def *SchemeDefinition, path string) error

WriteScheme serializes a scheme definition as JSON and writes it to a file (for gen-authz tests/rewrites).

Types

type AuthzDocument

type AuthzDocument struct {
	Version              string                    `json:"version"`
	Roles                map[string]AuthzRoleDef   `json:"roles"`
	OUMapping            map[string]string         `json:"ou_mapping"`
	GatewayNamespaces    map[string]GatewayNSDef   `json:"gateway_namespaces,omitempty"`
	CapabilityParameters map[string]map[string]any `json:"capability_parameters,omitempty"`
}

AuthzDocument is the complete authz.json document generated by gen-authz. The top-level structure is compatible with core/auth.Policy; capability_parameters is an extension field (core's encoding/json deserialization ignores unknown fields).

func GenAuthz

func GenAuthz(cfg GenAuthzConfig) (*AuthzDocument, error)

GenAuthz generates an authz.json document from capability.json schemes.

Mapping rules:

• Roles from the primary scheme (first) become authz.json roles (grants preserved as-is)
• Each role's OUs are expanded into ou_mapping (OU → role name)
• Role names with namespace prefixes (e.g. gateway:admin) are aggregated into gateway_namespaces
• Capability parameter defaults from all schemes are aggregated into capability_parameters

type AuthzRoleDef

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

AuthzRoleDef is a role entry for generating authz.json (compatible with core Policy.RoleDef).

type CapabilityClaim

type CapabilityClaim struct {
	SchemeID      string         `json:"scheme_id"`  // vendor/product
	Capability    string         `json:"capability"` // capability_id (may contain wildcards)
	Parameters    map[string]any `json:"parameters,omitempty"`
	Rationale     string         `json:"rationale,omitempty"`      // Authorization rationale from AI
	SchemeVersion string         `json:"scheme_version,omitempty"` // pinned scheme version (P1-4)
}

CapabilityClaim is a single AI-generated capability claim (pending validation/minimal privilege detection).

func ParseCapabilityClaims

func ParseCapabilityClaims(data []byte) ([]CapabilityClaim, error)

ParseCapabilityClaims parses a list of capability claims from JSON data. Expected structure: [{"scheme_id":"varwof/core-v1","capability":"cert:issue",...}]

type CapabilityEntry

type CapabilityEntry struct {
	ID          string                  `json:"id"`
	Description string                  `json:"description"`
	Parameters  map[string]ParameterDef `json:"parameters,omitempty"`
	// ParamsSchema carries a JSON Schema document for structured,
	// nested capability parameters (e.g. database tables/columns/
	// row_filter). Additive: schemes using only the flat ParameterDef
	// model leave it unset.
	ParamsSchema json.RawMessage `json:"params_schema,omitempty"`
	// AI-friendly semantic description fields (used by gen-docs to generate markdown permission docs).
	// These fields help LLMs understand the exact purpose of each capability,
	// enabling them to generate minimal privilege capability sets per task.
	Summary  string   `json:"summary,omitempty"`  // One-line summary (defaults to Description)
	Usage    string   `json:"usage,omitempty"`    // When this capability is needed (typical scenarios)
	WhenNot  string   `json:"when_not,omitempty"` // When this capability should NOT be granted (avoid over-provisioning)
	Examples []string `json:"examples,omitempty"` // Typical usage examples
	Related  []string `json:"related,omitempty"`  // Related capability IDs (collaboration/alternative relationships)
}

CapabilityEntry defines a single capability within a scheme.

type ClaimResult

type ClaimResult struct {
	Claim CapabilityClaim
	Valid bool
	Error string // Reason when Valid=false
}

ClaimResult is the validation result for a single claim.

type GatewayNSDef

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

GatewayNSDef is a gateway namespace entry for generating authz.json.

type GenAuthzConfig

type GenAuthzConfig struct {
	// SchemePaths is the list of capability.json file paths to merge.
	// The primary scheme (providing roles) must be the first; other schemes only contribute capability catalogs.
	SchemePaths []string
	// When VerifySignature is true, enforce signature verification if .p7s exists; fail on error.
	// Files without .p7s only error when VerifyRequired is true.
	VerifySignature bool
	// When VerifyRequired is true, capability files missing .p7s signature fail immediately.
	VerifyRequired bool
	// TrustRootsPEM is the trust root certificates for signature verification (PEM file paths).
	TrustRootsPEM []string
	// Version is the generated authz.json version field (default "v2").
	Version string
	// NamespacePrefix is appended to role names to generate gateway namespace prefix role grants,
	// e.g. "gateway" → gateway_namespaces["gateway:"].
	// By default, extracts the "gateway:xxx" prefix from all Roles in the primary scheme.
	NamespacePrefix string
}

GenAuthzConfig is the input configuration for GenAuthz.

type MinSetReport

type MinSetReport struct {
	// ValidClaims are valid and non-redundant claims.
	ValidClaims []CapabilityClaim
	// InvalidClaims are invalid claims (illegal capability/illegal parameters/unknown scheme).
	InvalidClaims []ClaimResult
	// RedundantClaims are claims covered by a wildcard or duplicated (recommended to remove).
	RedundantClaims []ClaimResult
	// MissingGranted are capabilities that are claimed but not covered by any role grant
	// (the AI-generated set references a capability not authorized for this identity).
	MissingGranted []string
	// AllowedPatterns are the grants actually held by the identity (wildcards expanded).
	AllowedPatterns []string
	// IsMinimal is true when the set is already minimal privilege.
	IsMinimal bool
}

MinSetReport is the complete report for minimal privilege validation.

type ParameterDef

type ParameterDef struct {
	Type        string      `json:"type"`
	Description string      `json:"description,omitempty"`
	Default     interface{} `json:"default,omitempty"`
	Min         interface{} `json:"min,omitempty"`
	Max         interface{} `json:"max,omitempty"`
	Enum        []string    `json:"enum,omitempty"`
	Required    bool        `json:"required,omitempty"`
}

ParameterDef defines a parameter for a capability.

type Registry

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

Registry holds all loaded scheme definitions.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty registry.

func NewRegistryFromBoth

func NewRegistryFromBoth(diskDir string) (*Registry, error)

NewRegistryFromBoth requires a non-empty disk directory and creates a registry pre-loaded from it.

func NewRegistryFromDisk

func NewRegistryFromDisk(dir string) (*Registry, error)

NewRegistryFromDisk creates a registry pre-loaded with schemes from a directory into the capability data tree.

func NewRegistryWithEmbedded

func NewRegistryWithEmbedded() (*Registry, error)

NewRegistryWithEmbedded is removed. Use NewRegistryFromDisk instead.

func (*Registry) CheckIntersection

func (r *Registry) CheckIntersection(setA, setB []string) (common []string)

CheckIntersection returns capabilities present in both sets.

func (*Registry) CheckMinimalCapabilitySet

func (r *Registry) CheckMinimalCapabilitySet(claims []CapabilityClaim, grantedPatterns []string) *MinSetReport

CheckMinimalCapabilitySet performs minimal privilege validation:

1. Validate each claim's legality (scheme/capability/parameters)
2. Detect redundancy: covered by another wildcard claim, or completely duplicated
3. Detect over-privilege: claimed capabilities not within the identity's granted authorization scope
4. Determine whether minimal privilege has been achieved

grantedPatterns are the grants actually held by the identity (e.g. role grants, may contain wildcards). Pass nil to skip over-privilege checking (only check legality and redundancy).

func (*Registry) CheckSubset

func (r *Registry) CheckSubset(declared, allowed []string) (denied []string)

CheckSubset checks if declared capabilities are a subset of allowed capabilities. Returns denied capabilities that are not in the allowed set.

func (*Registry) Get

func (r *Registry) Get(schemeID string) (*SchemeDefinition, bool)

Get returns a scheme definition by scheme_id.

func (*Registry) Has

func (r *Registry) Has(schemeID string) bool

Has checks if a scheme_id is registered.

func (*Registry) HasCapability

func (r *Registry) HasCapability(schemeID, capID string) bool

HasCapability checks if a specific capability is registered.

func (*Registry) Register

func (r *Registry) Register(def *SchemeDefinition) error

Register adds a scheme definition. It fails if scheme_id is already registered — a silently overwritten duplicate masks a data problem (audit 2026-09-16, R18).

func (*Registry) RoleGrantCovered

func (r *Registry) RoleGrantCovered(schemeID, grant string) bool

RoleGrantCovered checks if a single grant is covered by the scheme's capabilities (wildcard expanded).

func (*Registry) SchemeIDs

func (r *Registry) SchemeIDs() []string

SchemeIDs returns all registered scheme_ids, sorted.

func (*Registry) Summary

func (r *Registry) Summary() string

Summary returns a human-readable summary of all registered schemes.

func (*Registry) ValidateCapabilities

func (r *Registry) ValidateCapabilities(caps []string) *ValidationResult

ValidateCapabilities validates a list of "scheme:cap_id" strings against the registry.

func (*Registry) ValidateCapability

func (r *Registry) ValidateCapability(formatted string) (*SchemeDefinition, *CapabilityEntry, error)

ValidateCapability checks if "scheme:cap_id" is valid and returns the entry.

func (*Registry) ValidateClaims

func (r *Registry) ValidateClaims(claims []CapabilityClaim) []ClaimResult

ValidateClaims validates capability claims: scheme exists, capability is legal (supports wildcards). Returns the result for each claim. Does not include minimal privilege detection.

func (*Registry) ValidateParams

func (r *Registry) ValidateParams(scheme, capability string, params map[string]any) error

ValidateParams validates capability parameters against the scheme that defines them. It is the ONE parameter contract, used by both paths:

• the claims path (ValidateClaims -> signing an AIC), and
• the rule path (ruleexec.Rule.Validate -> publishing/loading a rule).

A capability that declares `params_schema` is validated against that data-driven schema (which is where `required` lives); otherwise the flat `parameters` contract is applied. Scheme-specific structural rules that the schema cannot express are still checked by ValidateSchemeParams.

func (*Registry) ValidateRoles

func (r *Registry) ValidateRoles(schemeID string) ([]string, error)

ValidateRoles validates that all role grants in a scheme are covered by capabilities. Returns uncovered grants (wildcards expanded against capabilities for validation). Use case: ensure role grants are all legal capabilities before gen-authz generates authz.json.

type RoleDef

type RoleDef struct {
	DisplayName string   `json:"display_name,omitempty"`
	Profiles    []string `json:"profiles,omitempty"`
	Grants      []string `json:"grants"`
	// OUs is the list of certificate OrganizationalUnits this role can be bound to.
	// When generating authz.json, written into ou_mapping; if left empty, no OU mapping entry is generated.
	OUs []string `json:"ous,omitempty"`
}

RoleDef defines a role within a product (used to generate authz.json). grants is a list of capability_id values (e.g. "ca:list", "cert:*"), supports wildcards (* / a:b:*); during expansion validation, all must fall within Capabilities.

type SchemeDefinition

type SchemeDefinition struct {
	SchemeID     string            `json:"scheme_id"`
	Name         string            `json:"name"`
	Version      string            `json:"version"`
	Description  string            `json:"description"`
	Vendor       string            `json:"vendor"`
	Product      string            `json:"product"`
	Author       string            `json:"author,omitempty"`
	License      string            `json:"license,omitempty"`
	Homepage     string            `json:"homepage,omitempty"`
	Capabilities []CapabilityEntry `json:"capabilities"`
	// Roles defines roles within this product (grants reference capability_id from this scheme).
	// Used by gen-authz tool when generating authz.json; can be empty (pure capability catalog products).
	Roles map[string]RoleDef `json:"roles,omitempty"`
}

SchemeDefinition defines all capabilities for a product.

func LoadScheme

func LoadScheme(path string) (*SchemeDefinition, error)

LoadScheme reads a capability JSON file and returns the definition.

func (*SchemeDefinition) ValidateSchemeRoles

func (def *SchemeDefinition) ValidateSchemeRoles() ([]error, []string)

ValidateSchemeRoles validates the consistency of role definitions within a scheme:

• Role names are non-empty
• Role grants are non-empty
• Non-wildcard grants must be covered by capabilities (strict error)
• Wildcard grants not covered locally are treated as cross-scheme namespace authorization (e.g. core role referencing gateway:*), returning a warning

Returns (errors, warnings).

type ValidationError

type ValidationError struct {
	Field   string
	Message string
}

ValidationError describes a single validation failure.

func (ValidationError) Error

func (e ValidationError) Error() string

type ValidationResult

type ValidationResult struct {
	Valid    bool
	Errors   []ValidationError
	Warnings []string
	Checked  int
}

ValidationResult holds the outcome of validating a set of capabilities.