Cedarling Go API documentation

package cedarling_go // import "github.com/JanssenProject/jans/jans-cedarling/bindings/cedarling_go"

Package cedarling_go provides Golang bindings for the cedarling project

[cedarling]: https://docs.jans.io/stable/cedarling/

TYPES

type AuthorizeMultiIssuerRequest struct {
	Tokens   []TokenInput `json:"tokens"`
	Resource EntityData   `json:"resource"`
	Action   string       `json:"action"`
	Context  any          `json:"context"`
	// Options is per-call metadata such as a TRACE context; nil means none.
	Options *AuthorizeOptions `json:"options,omitempty"`
}
    AuthorizeMultiIssuerRequest represents a multi-issuer authorization request

func (r AuthorizeMultiIssuerRequest) MarshalJSON() ([]byte, error)

type AuthorizeOptions struct {
	Trace *TraceContext `json:"trace,omitempty"`
}
    AuthorizeOptions is per-call metadata of an authorization request. None of
    it takes part in policy evaluation: the decision is the same with or without
    options. A nil Trace means the host has no execution context.

type AuthorizeResult struct {
	Response  CedarResponse `json:"response"`
	Decision  bool          `json:"decision"`
	RequestID string        `json:"request_id"`
}
    Represents the result of an authorization request

type BatchAuthorizeMultiIssuerRequest struct {
	Tokens []TokenInput `json:"tokens"`
	Items  []BatchItem  `json:"items"`
	// Options applies to the whole batch, not to individual items.
	Options *AuthorizeOptions `json:"options,omitempty"`
}
    BatchAuthorizeMultiIssuerRequest bundles one token set with N BatchItems.

type BatchAuthorizeMultiIssuerResponse struct {
	BatchID string                       `json:"batch_id"`
	Results []BatchItemMultiIssuerResult `json:"results"`
}
    BatchAuthorizeMultiIssuerResponse carries a shared batch_id alongside
    per-item multi-issuer results. Results[i] corresponds to the Items[i]
    supplied in the request.

type BatchAuthorizeUnsignedRequest struct {
	Principal *EntityData `json:"principal,omitempty"`
	Items     []BatchItem `json:"items"`
	// Options applies to the whole batch, not to individual items.
	Options *AuthorizeOptions `json:"options,omitempty"`
}
    BatchAuthorizeUnsignedRequest bundles one optional principal with N
    BatchItems.

type BatchAuthorizeUnsignedResponse struct {
	BatchID string                    `json:"batch_id"`
	Results []BatchItemUnsignedResult `json:"results"`
}
    BatchAuthorizeUnsignedResponse carries a shared batch_id alongside per-item
    results. Results[i] corresponds to the Items[i] supplied in the request.

type BatchItem struct {
	Resource EntityData `json:"resource"`
	Action   string     `json:"action"`
	Context  any        `json:"context"`
}
    BatchItem is one {resource, action, context} triple in a batch authorization
    request. When Context is nil it is serialized as an empty object; explicit
    non-object values are rejected at validate-time.

func (b BatchItem) MarshalJSON() ([]byte, error)
    MarshalJSON emits Context as `{}` when nil so the batch validate step
    doesn't reject the item.

type BatchItemError struct {
	Variant   string `json:"variant"`
	Message   string `json:"message"`
	ItemIndex uint64 `json:"item_index"`
}
    BatchItemError is the per-item build failure surfaced inside a batch
    response when Cedar couldn't be reached for that item. Category is the
    stable variant slug ("action_parse", "resource_build", …); ItemIndex is the
    position of the failing item in the original items list.

type BatchItemMultiIssuerResult struct {
	Ok  *MultiIssuerAuthorizeResult
	Err *BatchItemError
}
    BatchItemMultiIssuerResult is the multi-issuer analog of
    BatchItemUnsignedResult.

func (r BatchItemMultiIssuerResult) IsOk() bool
    IsOk reports whether Cedar reached a decision on this item.

func (r *BatchItemMultiIssuerResult) UnmarshalJSON(data []byte) error
    UnmarshalJSON decodes the {"Ok":{...}} / {"Err":{...}} discriminated union.

type BatchItemUnsignedResult struct {
	Ok  *AuthorizeResult
	Err *BatchItemError
}
    BatchItemUnsignedResult is one slot in
    BatchAuthorizeUnsignedResponse.Results. Exactly one of Ok / Err is non-nil:
    Ok when Cedar evaluated the item (Allow or Deny), Err when the item failed
    to build. Use IsOk() to switch.

func (r BatchItemUnsignedResult) IsOk() bool
    IsOk reports whether Cedar reached a decision on this item.

func (r *BatchItemUnsignedResult) UnmarshalJSON(data []byte) error
    UnmarshalJSON decodes the {"Ok":{...}} / {"Err":{...}} discriminated union
    emitted by the core lib.

type CedarEntityMapping struct {
	EntityType string `json:"entity_type"`
	ID         string `json:"id"`
}
    Represents type and id for a cedarling entity

type CedarResponse struct {
	// Has unexported fields.
}
    Represents the authorization decision

func (r CedarResponse) Decision() DecisionType

func (r CedarResponse) Errors() []string

func (r CedarResponse) IsAllowed() bool

func (r CedarResponse) MarshalJSON() ([]byte, error)

func (r CedarResponse) Reason() []string

func (r *CedarResponse) UnmarshalJSON(data []byte) error

type Cedarling struct {
	// Has unexported fields.
}
    Struct representing a cedarling instance

func NewCedarling(bootstrap_config map[string]any) (*Cedarling, error)
    Creates cedarling instance given bootstrap configuration

func NewCedarlingWithEnv(bootstrap_config *map[string]any) (*Cedarling, error)
    Creates cedarling instance from environment variables. If bootstrap
    configuration is provided, they will override the corresponding environment
    variables.

func (c *Cedarling) AuthorizeMultiIssuer(request AuthorizeMultiIssuerRequest) (MultiIssuerAuthorizeResult, error)

func (c *Cedarling) AuthorizeMultiIssuerBatch(request BatchAuthorizeMultiIssuerRequest) (BatchAuthorizeMultiIssuerResponse, error)
    AuthorizeMultiIssuerBatch runs a batch of multi-issuer authorize requests
    against one shared token set. Tokens are validated and token/issuer entities
    built once, then each item is evaluated in input order. Batch-level failures
    (validation, JWT verification, status-list refresh) return an error;
    per-item failures are returned as BatchItemError entries that callers must
    inspect.

func (c *Cedarling) AuthorizeUnsigned(request RequestUnsigned) (AuthorizeResult, error)
    Executes an unsigned authorization request (raw data for principle)

func (c *Cedarling) AuthorizeUnsignedBatch(request BatchAuthorizeUnsignedRequest) (BatchAuthorizeUnsignedResponse, error)
    AuthorizeUnsignedBatch runs a batch of unsigned authorize requests against
    one shared principal. Setup work (principal build + pushed-data snapshot)
    runs once and each item is evaluated in input order. Batch-level failures
    (validation, principal parse) return an error; per-item failures are
    returned as BatchItemError entries that callers must inspect without failing
    the whole batch.

func (c *Cedarling) ClearDataCtx() error
    ClearDataCtx removes all entries from the data store.

func (c *Cedarling) DrainMetrics() (MetricsSnapshot, error)
    DrainMetrics is a destructive read: it returns the telemetry metrics and
    resets the counters for the next interval, so there should be a single
    consumer. Returns an error when metrics collection is disabled, or when the
    collector is owned by the Lock telemetry ticker.

func (c *Cedarling) FailedTrustedIssuerIds() []string
    FailedTrustedIssuerIds returns ids of trusted issuers that failed to load.

func (c *Cedarling) GetDataCtx(key string) (any, error)
    GetDataCtx retrieves a value from the data store by key. Returns nil if the
    key doesn't exist or the entry has expired.

func (c *Cedarling) GetDataEntryCtx(key string) (DataEntry, error)
    GetDataEntryCtx retrieves a data entry with full metadata by key. Returns
    a zero value DataEntry if the key doesn't exist or the entry has expired.
    Check if entry.Key is empty to determine if the entry was found.

func (c *Cedarling) GetLogById(id string) string
    Retrieves specific log by ID

func (c *Cedarling) GetLogIds() []string
    Returns an array of log IDs

func (c *Cedarling) GetLogsByRequestId(request_id string) []string
    Retrieves specific log by request ID obtained from authorization request

func (c *Cedarling) GetLogsByRequestIdAndTag(request_id string, tag string) []string
    Retrieves specific log by request ID and tag

func (c *Cedarling) GetLogsByTag(tag string) []string
    Retrieves specific log by tag i.e. "info"

func (c *Cedarling) GetStatsCtx() (DataStoreStats, error)
    GetStatsCtx returns statistics about the data store.

func (c *Cedarling) IsTrustedIssuerLoadedByIss(issClaim string) bool
    IsTrustedIssuerLoadedByIss returns true if the trusted issuer for the given
    JWT iss claim finished loading successfully.

func (c *Cedarling) IsTrustedIssuerLoadedByName(issuerName string) bool
    IsTrustedIssuerLoadedByName returns true if the trusted issuer with the
    given name finished loading successfully.

func (c *Cedarling) ListDataCtx() ([]DataEntry, error)
    ListDataCtx returns all entries in the data store with their metadata.

func (c *Cedarling) LoadedTrustedIssuerIds() []string
    LoadedTrustedIssuerIds returns ids of successfully loaded trusted issuers.

func (c *Cedarling) LoadedTrustedIssuersCount() uint
    LoadedTrustedIssuersCount returns how many trusted issuers loaded
    successfully.

func (c *Cedarling) PolicyStoreID() (string, bool)
    PolicyStoreID returns the ID of the currently published policy store.
    The bool is false when the store carries no ID. The value is opaque and can
    change after a background refresh.

func (c *Cedarling) PopLogs() []string

func (c *Cedarling) PushDataCtx(key string, value any, ttl *time.Duration) error
    PushDataCtx stores a value in the data store with an optional TTL. If ttl
    is nil or zero, the default TTL from configuration is used. The value can be
    any JSON-serializable Go value.

func (c *Cedarling) RemoveDataCtx(key string) (bool, error)
    RemoveDataCtx removes a value from the data store by key. Returns true if
    the key existed and was removed, false otherwise.

func (c *Cedarling) ShutDown()
    Closes the cedarling instance

func (c *Cedarling) TotalIssuers() uint
    TotalIssuers returns the number of trusted issuers configured in the policy
    store.

type DataEntry struct {
	Key         string  `json:"key"`
	Value       any     `json:"value"`
	DataType    string  `json:"data_type"`
	CreatedAt   string  `json:"created_at"`
	ExpiresAt   *string `json:"expires_at,omitempty"`
	AccessCount uint64  `json:"access_count"`
}
    DataEntry represents a single entry in the data store with metadata

type DataStoreStats struct {
	EntryCount           uint64  `json:"entry_count"`
	MaxEntries           uint64  `json:"max_entries"`
	MaxEntrySize         uint64  `json:"max_entry_size"`
	MetricsEnabled       bool    `json:"metrics_enabled"`
	TotalSizeBytes       uint64  `json:"total_size_bytes"`
	AvgEntrySizeBytes    uint64  `json:"avg_entry_size_bytes"`
	CapacityUsagePercent float64 `json:"capacity_usage_percent"`
	MemoryAlertThreshold float64 `json:"memory_alert_threshold"`
	MemoryAlertTriggered bool    `json:"memory_alert_triggered"`
}
    DataStoreStats represents statistics about the data store

type DecisionType int8

const (
	// we use +1 to be sure that the values are not zero
	DecisionAllow DecisionType = iota + 1
	DecisionDeny
)
    Decision constants that can be used to represent the decision made by Cedar.

func (d DecisionType) ToString() string

type DropReason struct {
	Kind    string  `json:"kind"`
	Detail  *string `json:"detail,omitempty"`
	Message string  `json:"message"`
}
    DropReason explains why a token was dropped. Kind is the stable slug
    ("jwt_validation_failed", ...); Detail is set only for "invalid_input"
    ("empty_mapping" / "empty_payload"); Message is the non-empty claim-free
    text.

type DroppedToken struct {
	Mapping string     `json:"mapping"`
	Index   uint64     `json:"index"`
	Reason  DropReason `json:"reason"`
}
    DroppedToken is a token the caller supplied that multi-issuer authorization
    did not use, identified by its input Mapping and zero-based Index.

type EntityData struct {
	CedarMapping CedarEntityMapping
	// Payload will be flattened into the JSON object.
	Payload map[string]any
}
    Represents a cedarling principal or resource entity

func (e EntityData) MarshalJSON() ([]byte, error)
    MarshalJSON flattens Payload into the top-level JSON object.

func (e *EntityData) UnmarshalJSON(data []byte) error
    UnmarshalJSON extracts "cedar_entity_mapping" then stores the rest in
    Payload.

type MetricsSnapshot struct {
	PolicyStats      map[string]int64 `json:"policy_stats"`
	ErrorCounters    map[string]int64 `json:"error_counters"`
	OperationalStats map[string]int64 `json:"operational_stats"`
	// Interval elapsed since the previous drain. Crosses the binding as
	// whole nanoseconds, which is exactly how time.Duration is represented.
	Interval time.Duration `json:"interval_nanos"`
}
    MetricsSnapshot represents the telemetry metrics snapshot for
    the current interval. Local snapshots are only available when
    CEDARLING_METRICS_COLLECTION is enabled.

type MultiIssuerAuthorizeResult struct {
	Response  CedarResponse `json:"response"`
	Decision  bool          `json:"decision"`
	RequestID string        `json:"request_id"`
	// DroppedTokens lists the supplied tokens that were not used in this decision.
	DroppedTokens []DroppedToken `json:"dropped_tokens,omitempty"`
}
    MultiIssuerAuthorizeResult represents the result of a multi-issuer
    authorization request

type RequestUnsigned struct {
	Principal *EntityData
	Action    string
	Resource  EntityData
	Context   any
	// Options is per-call metadata such as a TRACE context; nil means none.
	Options *AuthorizeOptions
}
    Represents an unsigned authorization request. Principal is optional; when
    nil the request is evaluated via Cedar's partial evaluator and any residual
    (principal-dependent) policies fail closed to Deny.

func (r RequestUnsigned) MarshalJSON() ([]byte, error)

type TokenInput struct {
	Mapping string `json:"mapping"`
	Payload string `json:"payload"`
}
    TokenInput represents a JWT token with explicit type mapping

type TraceContext struct {
	ExecutionID        string  `json:"execution_id"`
	ExecutionAuthority string  `json:"execution_authority"`
	WorkloadID         string  `json:"workload_id"`
	WorkloadInstanceID *string `json:"workload_instance_id,omitempty"`
}
    TraceContext is the TRACE execution context of a call, already normalized
    by the host. Cedarling never generates ExecutionID: the execution initiator
    (gateway, PEP, host) owns it together with ExecutionAuthority.