Documentation
¶
Index ¶
- Constants
- func GenerateSecret() string
- func HasScope(record *TokenRecord, required TokenScope, group string) bool
- func HasScopeForAction(record *TokenRecord, required TokenScope, group string, action string) bool
- func IsExpired(record *TokenRecord) bool
- func ListenAndServe(ctx context.Context, service *app.Service, vault string, port int, ...) error
- func ServeSupervisedSession(ctx context.Context, options ServeSupervisedSessionOptions) error
- func VerifySecret(record *TokenRecord, secret string) bool
- func WriteSessionError(writer io.Writer, code, message string) error
- type AuditEntry
- type AuditLogger
- type AuthMode
- type CachePolicy
- type DispatcherOptions
- type FileTokenStore
- func (f *FileTokenStore) Create(record *TokenRecord) error
- func (f *FileTokenStore) Delete(id string) error
- func (f *FileTokenStore) Get(id string) (*TokenRecord, error)
- func (f *FileTokenStore) List() ([]*TokenRecord, error)
- func (f *FileTokenStore) Update(record *TokenRecord) error
- func (f *FileTokenStore) Verify(secret string) (*TokenRecord, error)
- type HTTPRPCRequest
- type ManifestProvider
- type MemoryTokenStore
- func (m *MemoryTokenStore) Create(record *TokenRecord) error
- func (m *MemoryTokenStore) Delete(id string) error
- func (m *MemoryTokenStore) Get(id string) (*TokenRecord, error)
- func (m *MemoryTokenStore) List() ([]*TokenRecord, error)
- func (m *MemoryTokenStore) Update(record *TokenRecord) error
- func (m *MemoryTokenStore) Verify(secret string) (*TokenRecord, error)
- type RPCDispatcher
- type RPCRequest
- type ReaderSession
- type ReaderSessionStore
- type RouteInfo
- type ScopeTarget
- type ServeSupervisedSessionOptions
- type Server
- type ServerOptions
- type SessionBootstrapFrame
- type SessionEvent
- type TokenRecord
- type TokenScope
- type TokenStore
Constants ¶
const AuthModeTokenFile = AuthModeTokenStore
AuthModeTokenFile is the deprecated compatibility name for AuthModeTokenStore. The value and behavior are intentionally identical.
const (
LocalSessionReadyEventV1Alpha1 = "pinax.local_session.event.v1alpha1"
)
Session event schema versions for the host protocol on stdout.
Variables ¶
This section is empty.
Functions ¶
func HasScope ¶
func HasScope(record *TokenRecord, required TokenScope, group string) bool
HasScope checks if a token record has the required scope for a given group.
func HasScopeForAction ¶
func HasScopeForAction(record *TokenRecord, required TokenScope, group string, action string) bool
HasScopeForAction checks scope group and, when present, the action allowlist.
func ListenAndServe ¶
func ServeSupervisedSession ¶ added in v0.3.0
func ServeSupervisedSession(ctx context.Context, options ServeSupervisedSessionOptions) error
ServeSupervisedSession runs the readonly loopback reader surface for one bootstrap frame. Only the reader route group is exposed; the legacy API, temp tokens and audit writes stay out of this mode entirely. EOF on stdin stops new requests and drains for at most five seconds before shutdown.
func VerifySecret ¶
func VerifySecret(record *TokenRecord, secret string) bool
VerifySecret checks if a plaintext secret matches the stored hash.
Types ¶
type AuditEntry ¶
type AuditEntry struct {
Timestamp string `json:"ts"`
TokenID string `json:"token_id"`
Method string `json:"method"`
Path string `json:"path"`
Scope string `json:"scope,omitempty"`
Group string `json:"group,omitempty"`
Status int `json:"status"`
}
AuditEntry represents a single audit log entry.
type AuditLogger ¶
type AuditLogger struct {
// contains filtered or unexported fields
}
AuditLogger writes audit entries to a JSONL file.
func NewAuditLogger ¶
func NewAuditLogger(path string) (*AuditLogger, error)
NewAuditLogger creates a new audit logger writing to the given path.
func (*AuditLogger) Log ¶
func (l *AuditLogger) Log(entry AuditEntry) error
Log writes an audit entry to the log file.
type CachePolicy ¶
CachePolicy defines caching parameters for a route.
type DispatcherOptions ¶
type DispatcherOptions struct {
AllowWrite bool
Manifest ManifestProvider
Readiness app.ConnectionReadinessOptions
OperationAccess app.OperationAccess
}
type FileTokenStore ¶
type FileTokenStore struct {
// contains filtered or unexported fields
}
FileTokenStore stores tokens in a JSON file.
func NewFileTokenStore ¶
func NewFileTokenStore(path string) (*FileTokenStore, error)
NewFileTokenStore creates or opens a file-based token store.
func (*FileTokenStore) Create ¶
func (f *FileTokenStore) Create(record *TokenRecord) error
Create stores a new token record to the file.
func (*FileTokenStore) Delete ¶
func (f *FileTokenStore) Delete(id string) error
Delete removes a token by ID from the file.
func (*FileTokenStore) Get ¶
func (f *FileTokenStore) Get(id string) (*TokenRecord, error)
Get retrieves a token by ID from the file.
func (*FileTokenStore) List ¶
func (f *FileTokenStore) List() ([]*TokenRecord, error)
List returns all token records from the file.
func (*FileTokenStore) Update ¶
func (f *FileTokenStore) Update(record *TokenRecord) error
Update modifies an existing token record in the file.
func (*FileTokenStore) Verify ¶
func (f *FileTokenStore) Verify(secret string) (*TokenRecord, error)
Verify checks a secret against all stored tokens in the file.
type HTTPRPCRequest ¶
type ManifestProvider ¶ added in v0.3.0
type ManifestProvider func() (domain.Projection, error)
type MemoryTokenStore ¶
MemoryTokenStore stores tokens in process memory.
func NewMemoryTokenStore ¶
func NewMemoryTokenStore() *MemoryTokenStore
NewMemoryTokenStore creates a new in-memory token store.
func (*MemoryTokenStore) Create ¶
func (m *MemoryTokenStore) Create(record *TokenRecord) error
Create stores a new token record.
func (*MemoryTokenStore) Delete ¶
func (m *MemoryTokenStore) Delete(id string) error
Delete removes a token by ID.
func (*MemoryTokenStore) Get ¶
func (m *MemoryTokenStore) Get(id string) (*TokenRecord, error)
Get retrieves a token by ID.
func (*MemoryTokenStore) List ¶
func (m *MemoryTokenStore) List() ([]*TokenRecord, error)
List returns all token records.
func (*MemoryTokenStore) Update ¶
func (m *MemoryTokenStore) Update(record *TokenRecord) error
Update modifies an existing token record.
func (*MemoryTokenStore) Verify ¶
func (m *MemoryTokenStore) Verify(secret string) (*TokenRecord, error)
Verify checks a secret against all stored tokens.
type RPCDispatcher ¶
type RPCDispatcher struct {
// contains filtered or unexported fields
}
func NewRPCDispatcher ¶
func NewRPCDispatcher(service *app.Service, vault string) *RPCDispatcher
func NewRPCDispatcherWithOptions ¶
func NewRPCDispatcherWithOptions(service *app.Service, vault string, options DispatcherOptions) *RPCDispatcher
func (*RPCDispatcher) Call ¶
func (d *RPCDispatcher) Call(ctx context.Context, req RPCRequest) (domain.Projection, error)
type RPCRequest ¶
type ReaderSession ¶ added in v0.3.0
type ReaderSession struct {
SessionID string
BindingID string
Nonce string
Scopes []string
ExpiresAt time.Time
CreatedAt time.Time
}
ReaderSession is one authorized human reading session.
func (*ReaderSession) Expired ¶ added in v0.3.0
func (s *ReaderSession) Expired() bool
Expired reports whether the session passed its deadline.
func (*ReaderSession) HasScope ¶ added in v0.3.0
func (s *ReaderSession) HasScope(scope string) bool
HasScope reports whether the session grants a reader scope.
type ReaderSessionStore ¶ added in v0.3.0
type ReaderSessionStore struct {
// contains filtered or unexported fields
}
ReaderSessionStore keeps bearer digests in process memory. Secrets are hashed at rest and never persisted.
func NewReaderSessionStore ¶ added in v0.3.0
func NewReaderSessionStore() (*ReaderSessionStore, error)
NewReaderSessionStore creates an empty in-memory registry with a random cursor signing secret.
func (*ReaderSessionStore) Create ¶ added in v0.3.0
func (s *ReaderSessionStore) Create(session ReaderSession, bearer string) error
Create registers a session for a fresh bearer secret.
func (*ReaderSessionStore) CursorSecret ¶ added in v0.3.0
func (s *ReaderSessionStore) CursorSecret() []byte
CursorSecret returns the cursor signing key for this server process.
func (*ReaderSessionStore) Revoke ¶ added in v0.3.0
func (s *ReaderSessionStore) Revoke(sessionID string)
Revoke removes a session by ID.
func (*ReaderSessionStore) Verify ¶ added in v0.3.0
func (s *ReaderSessionStore) Verify(bearer string) (*ReaderSession, error)
Verify resolves a bearer to its live session.
type ScopeTarget ¶
type ScopeTarget struct {
Groups []string `json:"groups,omitempty"`
Actions []string `json:"actions,omitempty"`
}
ScopeTarget defines which groups and actions a scope covers.
type ServeSupervisedSessionOptions ¶ added in v0.3.0
type ServeSupervisedSessionOptions struct {
Service *app.Service
Frame SessionBootstrapFrame
Stdin io.Reader // liveness channel; closed stdin stops the server
Stdout io.Writer // redacted host protocol
Stderr io.Writer // human diagnostics; never secrets
Manifest ManifestProvider
}
ServeSupervisedSessionOptions configures the supervised reader server.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func NewServerWithOptions ¶
func NewServerWithOptions(service *app.Service, vault string, options ServerOptions) *Server
type ServerOptions ¶
type ServerOptions struct {
AllowWrite bool
AuthMode AuthMode
TokenStore string
// TokenFile is the deprecated compatibility field for TokenStore.
TokenFile string
ExposeGroups []string
HideGroups []string
Logger *zap.Logger
Manifest ManifestProvider
// ReaderSessions enables the human reading surface. Nil keeps reader
// routes off (reader_disabled) without touching legacy auth.
ReaderSessions *ReaderSessionStore
}
type SessionBootstrapFrame ¶ added in v0.3.0
type SessionBootstrapFrame struct {
SchemaVersion string `json:"schema_version"`
SessionNonce string `json:"session_nonce"`
Bearer string `json:"bearer"`
BindingID string `json:"binding_id"`
VaultRoot string `json:"vault_root"`
Scopes []string `json:"scopes"`
Readonly bool `json:"readonly"`
}
SessionBootstrapFrame is the versioned private stdin first frame (pinax.local_session.bootstrap.v1alpha1). Secret fields never reach logs.
func ReadSessionBootstrap ¶ added in v0.3.0
func ReadSessionBootstrap(reader io.Reader) (SessionBootstrapFrame, error)
ReadSessionBootstrap reads and validates the private first frame. The host keeps stdin open for liveness after the frame, so exactly one newline-terminated frame is consumed — never until EOF. The frame is capped at 16 KiB; unknown fields, unknown schema versions, unknown scopes, mutation requests and malformed secrets are rejected.
func ReadSessionBootstrapWithDeadline ¶ added in v0.3.0
func ReadSessionBootstrapWithDeadline(ctx context.Context, reader io.Reader) (SessionBootstrapFrame, error)
ReadSessionBootstrapWithDeadline applies the 10s first-frame deadline.
func (SessionBootstrapFrame) HasWriterScope ¶ added in v0.3.0
func (f SessionBootstrapFrame) HasWriterScope() bool
HasWriterScope reports whether the frame opens the supervised writer surface (pinax-human-reading-write-v1): any owner-granted writer scope flips the session out of readonly mode.
type SessionEvent ¶ added in v0.3.0
type SessionEvent struct {
SchemaVersion string `json:"schema_version"`
Type string `json:"type"`
SessionID string `json:"session_id,omitempty"`
SessionNonce string `json:"session_nonce,omitempty"`
BindingID string `json:"binding_id,omitempty"`
Address string `json:"address,omitempty"`
ContractDigest string `json:"contract_digest,omitempty"`
Readonly *bool `json:"readonly,omitempty"`
Code string `json:"code,omitempty"`
Message string `json:"message,omitempty"`
}
SessionEvent is one redacted stdout protocol message.
type TokenRecord ¶
type TokenRecord struct {
ID string `json:"id"`
SecretHash string `json:"secret_hash"`
Salt string `json:"salt"`
Scope map[TokenScope]ScopeTarget `json:"scope"`
Label string `json:"label,omitempty"`
CreatedAt string `json:"created_at"`
ExpiresAt string `json:"expires_at,omitempty"`
LastUsedAt string `json:"last_used_at,omitempty"`
RotatedFrom string `json:"rotated_from,omitempty"`
CreatedBy string `json:"created_by"`
}
TokenRecord represents a stored API token.
func GenerateTokenRecord ¶
func GenerateTokenRecord(label string, scope map[TokenScope]ScopeTarget, expiresAt string, createdBy string) (*TokenRecord, string)
GenerateTokenRecord creates a new token record and returns it along with the plaintext secret.
type TokenScope ¶
type TokenScope string
TokenScope defines the permission scope of a token.
const ( ScopeRead TokenScope = "read" // All GET routes ScopeWrite TokenScope = "write" // All mutation routes ScopeAdmin TokenScope = "admin" // Token management itself )
type TokenStore ¶
type TokenStore interface {
Verify(secret string) (*TokenRecord, error)
Create(record *TokenRecord) error
Get(id string) (*TokenRecord, error)
List() ([]*TokenRecord, error)
Delete(id string) error
Update(record *TokenRecord) error
}
TokenStore is the interface for token persistence and verification.