identity

Documentation

Overview

Package identity provides Principal and TenantContext types and nil-safe constructors for threading authenticated identity through the Cortex platform.

This is a thin helper package that re-exports the domain port types via type aliases and provides constructors. The full identity domain model (Organization, Workspace, Project, User, ServiceAccount, Agent, OAuth verifier, API key, claims mapper) is introduced in W11/W12.

REQ-FOUND-001: these types compile and unit-test in isolation. No caller adopts them in W1.

Index

• Variables
• type ClaimsMapper
  • func (ClaimsMapper) Map(claims map[string]any, authMethod string) (Principal, error)
• type IssuedToken
• type MemoryTokenStore
  • func NewMemoryTokenStore(key []byte) *MemoryTokenStore
  • func (s *MemoryTokenStore) Issue(_ context.Context, in TokenIssue) (IssuedToken, error)
  • func (s *MemoryTokenStore) Revoke(_ context.Context, id string) error
  • func (s *MemoryTokenStore) Rotate(ctx context.Context, id string) (IssuedToken, error)
  • func (s *MemoryTokenStore) Verify(_ context.Context, secret, requiredScope string) (Principal, error)
• type OAuthConfig
• type OAuthVerifier
  • func NewOAuthVerifier(cfg OAuthConfig) *OAuthVerifier
  • func (v *OAuthVerifier) Verify(ctx context.Context, raw, resource string) (Principal, error)
• type Principal
  • func NewPrincipal(subject, principalType, orgID string, workspaceIDs, roles, scopes []string, ...) Principal
• type TenantContext
  • func NewTenantContext(tenantID, workspaceID, ownerSubject string) TenantContext
• type TokenIssue
• type TokenRecord
• type TokenStore
• type TokenVerifier
• type UserCreate
• type UserRecord

Variables

var (
	ErrInvalidToken      = errors.New("invalid token")
	ErrTokenRevoked      = errors.New("token revoked")
	ErrTokenExpired      = errors.New("token expired")
	ErrInsufficientScope = errors.New("insufficient scope")
)

Types

type ClaimsMapper

type ClaimsMapper struct{}

ClaimsMapper converts verified issuer claims into an immutable Principal. Client/request fields are intentionally not accepted by this port.

func (ClaimsMapper) Map

func (ClaimsMapper) Map(claims map[string]any, authMethod string) (Principal, error)

type IssuedToken

type IssuedToken struct {
	Secret string
	Record TokenRecord
}

type MemoryTokenStore

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

func NewMemoryTokenStore

func NewMemoryTokenStore(key []byte) *MemoryTokenStore

func (*MemoryTokenStore) Issue

func (s *MemoryTokenStore) Issue(_ context.Context, in TokenIssue) (IssuedToken, error)

func (*MemoryTokenStore) Revoke

func (s *MemoryTokenStore) Revoke(_ context.Context, id string) error

func (*MemoryTokenStore) Rotate

func (s *MemoryTokenStore) Rotate(ctx context.Context, id string) (IssuedToken, error)

func (*MemoryTokenStore) Verify

func (s *MemoryTokenStore) Verify(_ context.Context, secret, requiredScope string) (Principal, error)

type OAuthConfig

type OAuthConfig struct {
	Issuer     string
	JWKSURL    string
	Audience   []string
	ClockSkew  time.Duration
	HTTPClient *http.Client
	MaxKeys    int
	CacheTTL   time.Duration
	Mapper     ClaimsMapper
}

type OAuthVerifier

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

func NewOAuthVerifier

func NewOAuthVerifier(cfg OAuthConfig) *OAuthVerifier

func (*OAuthVerifier) Verify

func (v *OAuthVerifier) Verify(ctx context.Context, raw, resource string) (Principal, error)

type Principal

type Principal = domain.Principal

Principal is a type alias for domain.Principal, re-exported so callers in the identity/authz layers reference identity.Principal without importing domain directly in every file.

func NewPrincipal

func NewPrincipal(subject, principalType, orgID string, workspaceIDs, roles, scopes []string, authMethod, grantDigest string) Principal

NewPrincipal constructs a fully-populated Principal.

Nil slice arguments are normalized to empty (non-nil) slices so downstream range loops and len() calls are always safe without nil checks.

type TenantContext

type TenantContext = domain.TenantContext

TenantContext is a type alias for domain.TenantContext.

func NewTenantContext

func NewTenantContext(tenantID, workspaceID, ownerSubject string) TenantContext

NewTenantContext constructs a TenantContext value.

It never panics on empty strings — in local mode all fields are empty, representing the synthetic/nil-tenant invariant (REQ-FOUND-001).

type TokenIssue

type TokenIssue struct {
	Subject, PrincipalType, OrgID string
	Name                          string
	Workspaces, Scopes            []string
	ExpiresAt                     time.Time
}

type TokenRecord

type TokenRecord struct {
	ID            string
	Name          string
	Prefix        string
	Digest        string
	Subject       string
	PrincipalType string
	OrgID         string
	Workspaces    []string
	Scopes        []string
	ExpiresAt     time.Time
	RevokedAt     time.Time
	LastUsedAt    time.Time
}

type TokenStore

type TokenStore interface {
	Issue(context.Context, TokenIssue) (IssuedToken, error)
	Verify(context.Context, string, string) (Principal, error)
	Revoke(context.Context, string) error
	Rotate(context.Context, string) (IssuedToken, error)
}

type TokenVerifier

type TokenVerifier interface {
	Verify(context.Context, string, string) (Principal, error)
}

type UserCreate

type UserCreate struct {
	Email                   string
	DisplayName             string
	Roles                   []string
	Workspaces              []string
	Projects                []string
	Scopes                  []string
	ClassificationClearance []string
}

UserCreate contains administrator-controlled identity data. Authority is resolved from these persisted grants, never copied from ordinary requests.

type UserRecord

type UserRecord struct {
	ID                      string
	Email                   string
	DisplayName             string
	Active                  bool
	Roles                   []string
	Workspaces              []string
	Projects                []string
	Scopes                  []string
	ClassificationClearance []string
	GrantVersion            int64
	CreatedAt               time.Time
}