administration

administration

import "github.com/agentstation/starmap/server/administration"

Package administration owns standalone server identities and administrative state.

Index

• Constants
• func RecoverAdministrator(ctx context.Context, cfg Config, id string) (string, error)
• type Action
• type Config
• type Manager
  • func Initialize(ctx context.Context, cfg Config, administratorID string) (_ *Manager, token string, resultErr error)
  • func Open(ctx context.Context, cfg Config) (_ *Manager, resultErr error)
  • func (m *Manager) Audience() string
  • func (m *Manager) Authenticate(token, audience string) (Principal, bool)
  • func (m *Manager) Close() error
  • func (m *Manager) Complete(ctx context.Context, id string, succeeded bool) (Receipt, error)
  • func (m *Manager) Create(ctx context.Context, actor Principal, id string, role Role) (string, error)
  • func (m *Manager) Operation(actor Principal, id string) (Receipt, error)
  • func (m *Manager) Revoke(ctx context.Context, actor Principal, id string) error
  • func (m *Manager) Rotate(ctx context.Context, actor Principal, id string, overlap time.Duration) (string, error)
  • func (m *Manager) StartOperation(ctx context.Context, actor Principal, action Action, subject string) (Receipt, error)
  • func (m *Manager) Status() Status
  • func (m *Manager) Track(ctx context.Context, principal Principal) (context.Context, context.CancelFunc)
• type Principal
  • func (p Principal) Audience() string
  • func (p Principal) ID() string
  • func (p Principal) Role() Role
• type Receipt
• type Reports
  • func NewReports(schema, effective []byte) (*Reports, error)
  • func (r *Reports) Effective() []byte
  • func (r *Reports) Schema() []byte
• type Role
• type State
• type Status

Constants

MaximumRotationOverlap bounds the interval that accepts old and new credentials.

const MaximumRotationOverlap = 24 * time.Hour

func RecoverAdministrator

func RecoverAdministrator(ctx context.Context, cfg Config, id string) (string, error)

RecoverAdministrator replaces a lost administrator credential through explicit local filesystem authority. It requires exclusive private state access and a valid audit history. Stop the server first.

type Action

Action identifies an administrative effect recorded before execution.

type Action string

const (
    // Bootstrap creates the first local administrator.
    Bootstrap Action = "bootstrap"
    // CreateIdentity adds an administrator or subscriber.
    CreateIdentity Action = "create_identity"
    // RotateIdentity replaces a credential with a bounded overlap.
    RotateIdentity Action = "rotate_identity"
    // RevokeIdentity withdraws all credentials for an identity.
    RevokeIdentity Action = "revoke_identity"
    // RefreshCatalog starts explicit catalog acquisition.
    RefreshCatalog Action = "refresh_catalog"
    // CancelOperation asks an accepted operation to stop.
    CancelOperation Action = "cancel_operation"
)

type Config

Config identifies the private state root and the catalog authority audience.

type Config struct {
    StateDirectory string
    Audience       string
}

type Manager

Manager owns identities, audit events, and operation receipts for one server. Authentication reads an immutable snapshot. Administrative writes use one process lease.

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

func Initialize

func Initialize(ctx context.Context, cfg Config, administratorID string) (_ *Manager, token string, resultErr error)

Initialize creates the first administrator through an explicit local operation. It refuses existing identities and returns the credential only after durable completion.

func Open

func Open(ctx context.Context, cfg Config) (_ *Manager, resultErr error)

Open restores private administration state without creating an administrator. Audit failures leave authenticated diagnostics available and reject new mutations.

func (*Manager) Audience

func (m *Manager) Audience() string

Audience returns the immutable catalog namespace bound to this administration store.

func (*Manager) Authenticate

func (m *Manager) Authenticate(token, audience string) (Principal, bool)

Authenticate accepts an active credential for the configured audience without filesystem I/O.

func (*Manager) Close

func (m *Manager) Close() error

Close releases writer ownership and stops credential authentication.

func (*Manager) Complete

func (m *Manager) Complete(ctx context.Context, id string, succeeded bool) (Receipt, error)

Complete persists the operation outcome before its caller reports success. A failed effect can have partial results. Recovery never executes the effect again.

func (*Manager) Create

func (m *Manager) Create(ctx context.Context, actor Principal, id string, role Role) (string, error)

Create adds a distinct identity and returns its credential after durable audit completion.

func (*Manager) Operation

func (m *Manager) Operation(actor Principal, id string) (Receipt, error)

Operation returns a retained durable operation receipt for authorized diagnostics.

func (*Manager) Revoke

func (m *Manager) Revoke(ctx context.Context, actor Principal, id string) error

Revoke withdraws an identity while retaining at least one active administrator.

func (*Manager) Rotate

func (m *Manager) Rotate(ctx context.Context, actor Principal, id string, overlap time.Duration) (string, error)

Rotate returns a new credential and retains the prior active key for the selected overlap. A second rotation cannot discard a key whose overlap has not ended.

func (*Manager) StartOperation

func (m *Manager) StartOperation(ctx context.Context, actor Principal, action Action, subject string) (Receipt, error)

StartOperation records an administrator's operation intent before the caller starts its effects.

func (*Manager) Status

func (m *Manager) Status() Status

Status returns the current administration readiness and identity revision.

func (*Manager) Track

func (m *Manager) Track(ctx context.Context, principal Principal) (context.Context, context.CancelFunc)

Track cancels a long-lived request when its credential expires or loses permission. The caller must call the returned cancel function when the request ends.

type Principal

Principal identifies an authenticated caller. Callers cannot construct its authority.

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

func (Principal) Audience

func (p Principal) Audience() string

Audience returns the catalog authority namespace assigned to this identity.

func (Principal) ID

func (p Principal) ID() string

ID returns the stable identity name without credential material.

func (Principal) Role

func (p Principal) Role() Role

Role returns the permissions assigned to this identity.

type Receipt

Receipt reports one administrative operation without credential material.

type Receipt struct {
    ID           string    `json:"id"`
    Audience     string    `json:"audience"`
    Actor        string    `json:"actor"`
    Action       Action    `json:"action"`
    Subject      string    `json:"subject"`
    State        State     `json:"state"`
    AcceptedAt   time.Time `json:"accepted_at"`
    CompletedAt  time.Time `json:"completed_at"`
    Revision     uint64    `json:"revision"`
    BeforeDigest string    `json:"before_digest,omitempty"`
    AfterDigest  string    `json:"after_digest,omitempty"`
}

type Reports

Reports holds detached configuration reports prepared by the host application. The host must redact secrets before construction. Reports require no catalog startup.

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

func NewReports

func NewReports(schema, effective []byte) (*Reports, error)

NewReports validates and copies versioned JSON objects for administrative diagnostics.

func (*Reports) Effective

func (r *Reports) Effective() []byte

Effective returns a detached report of redacted values, origins, and file paths.

func (*Reports) Schema

func (r *Reports) Schema() []byte

Schema returns a detached configuration descriptor report.

type Role

Role separates catalog subscription from server administration.

type Role string

const (
    // Subscriber can read the catalog within its configured audience.
    Subscriber Role = "subscriber"
    // Administrator can authorize server mutations and read configuration reports.
    Administrator Role = "administrator"
)

type State

State records the durable outcome of an administrative operation.

type State string

const (
    // Accepted means the audit intent is durable and effects may start.
    Accepted State = "accepted"
    // Succeeded means the effect and its audit outcome are durable.
    Succeeded State = "succeeded"
    // Failed means the operation reported a failure. Effects can be partial.
    Failed State = "failed"
    // Interrupted means recovery cannot prove the effect's outcome. It never replays the effect.
    Interrupted State = "interrupted"
)

type Status

Status reports administration readiness without credential material.

type Status struct {
    MutationReady      bool   `json:"mutation_ready"`
    Reason             string `json:"reason,omitempty"`
    Revision           uint64 `json:"revision"`
    RetainedOperations int    `json:"retained_operations"`
    OperationLimit     int    `json:"operation_limit"`
    AuditBytes         int64  `json:"audit_bytes"`
    AuditByteLimit     int64  `json:"audit_byte_limit"`
}

Generated by gomarkdoc