credential

Documentation

Overview

Package credential models a stored credential as metadata on the resource store, kept strictly separate from the secret value it points at. A Credential records which integration it belongs to, what auth scheme it is, the role it may exercise, whether it is the integration's default, and the vault reference the secret value lives behind. The value itself never enters a Credential: it stays in the vault and is resolved by reference only at the point a request is signed, so a credential is safe to list, sync, and put on the event log while the secret is not.

This decouples a credential from a provider name. An integration may hold several named credentials (a production token, a staging token), each selectable by name or by the integration's default, and each carrying a role that bounds what it may be used for.

Index

• Constants
• Variables
• func RegisterKind(reg *resource.Registry) error
• func VaultRef(integration, name string) string
• type Credential
  • func (c Credential) Ref() string
• type Role
  • func (r Role) Permits(required Role) bool
  • func (r Role) Valid() bool
• type Spec
  • func DecodeSpec(r resource.Resource) (Spec, error)
• type Status
  • func DecodeStatus(r resource.Resource) (Status, error)
• type Store
  • func NewStore(rs resource.Store) *Store
  • func (s *Store) All(ctx context.Context) ([]Credential, error)
  • func (s *Store) Default(ctx context.Context, integration string) (Credential, error)
  • func (s *Store) Delete(ctx context.Context, integration, name string) error
  • func (s *Store) Get(ctx context.Context, integration, name string) (Credential, error)
  • func (s *Store) List(ctx context.Context, integration string) ([]Credential, error)
  • func (s *Store) Put(ctx context.Context, spec Spec) (Credential, error)
  • func (s *Store) Resolve(ctx context.Context, ref string) (Credential, error)
  • func (s *Store) SetDefault(ctx context.Context, integration, name string) error

Constants

const (
	// GroupVersion is the Credential kind's API group and version.
	GroupVersion = "credential.ionagent.io/v1alpha1"
	// Kind is the resource kind name credentials are stored under.
	Kind = "Credential"
)

Variables

var ErrInvalid = errors.New("credential: invalid")

ErrInvalid is returned when a credential is missing a required field.

var ErrNotFound = errors.New("credential: not found")

ErrNotFound is returned when a credential does not exist.

var KindDef = resource.Kind{
	APIVersion: GroupVersion,
	Name:       Kind,
	Schema:     specSchema,
	Singular:   "credential",
	Plural:     "credentials",
}

KindDef is the Credential kind definition registered with a resource registry.

Functions

func RegisterKind

func RegisterKind(reg *resource.Registry) error

RegisterKind registers the Credential kind so a store admits credentials. It is idempotent.

func VaultRef

func VaultRef(integration, name string) string

VaultRef returns the conventional vault reference for a credential, the form a credential's secret is stored under when its spec sets no explicit VaultRef.

Types

type Credential

type Credential struct {
	ID   string
	Spec Spec
	// Version is the resource revision.
	Version int
}

Credential is the typed view of a credential resource: its identity, spec, and the resource bookkeeping a caller needs.

func (Credential) Ref

func (c Credential) Ref() string

Ref returns the credential's effective vault reference: its explicit VaultRef, or the conventional "<integration>/<name>" when unset.

type Role

type Role string

Role is the privilege level a credential may exercise. Roles are ordered read < operator < admin. Role gating is opt-in per action: an action that requires no role admits any credential, so an integration that does not use roles is never blocked. But once an action requires a role, it is enforced least-privilege: a credential must carry a role that ranks at least as high, and a role-less credential cannot satisfy it. The enforcement (refusing an insufficient credential for an action, recorded on the event log) is applied where a request is signed; this type is the policy that boundary reads.

const (
	// RoleRead may perform read-only actions.
	RoleRead Role = "read"
	// RoleOperator may perform routine state changes (deploy, provision).
	RoleOperator Role = "operator"
	// RoleAdmin may perform any action, including destructive or account-level ones.
	RoleAdmin Role = "admin"
)

func (Role) Permits

func (r Role) Permits(required Role) bool

Permits reports whether a credential carrying this role may be used for an action that requires the given role. An action that requires no role (empty) admits any credential. Otherwise the requirement is enforced least-privilege: a role-less credential is refused, and a credential with a role must rank at least as high as the action requires.

func (Role) Valid

func (r Role) Valid() bool

Valid reports whether r is one of the known roles. The empty role is not valid as a stored value (a stored role must be explicit) but is meaningful as "unscoped" when passed to Permits.

type Spec

type Spec struct {
	// Integration is the id of the integration (extension) this credential belongs to.
	Integration string `json:"integration"`
	// Name is the credential's name within its integration (e.g. "prod-token").
	Name string `json:"name"`
	// AuthType is the auth scheme the credential is for (bearer, api_key, basic,
	// oauth2). It mirrors the integration's auth type so a credential and the request
	// it signs agree on the mechanism.
	AuthType string `json:"authType,omitempty"`
	// Role bounds what the credential may be used for. Empty means unscoped.
	Role Role `json:"role,omitempty"`
	// IsDefault marks the credential selected when an integration is referenced
	// without a credential name. At most one credential per integration is the default.
	IsDefault bool `json:"isDefault,omitempty"`
	// VaultRef is the reference the secret value is stored under in the vault. Empty
	// defaults to "<integration>/<name>" (see VaultRef).
	VaultRef string `json:"vaultRef,omitempty"`
	// Description is an optional human note.
	Description string `json:"description,omitempty"`
}

Spec is the stored shape of a credential: pure metadata. It never carries a secret value, only the vault reference to one.

func DecodeSpec

func DecodeSpec(r resource.Resource) (Spec, error)

DecodeSpec reads the typed spec from a resource.

type Status

type Status struct {
	// LastUsed is the RFC3339 time the credential was last used to sign a request,
	// supplied by the caller's clock (never read from the wall clock here, so the
	// record stays replay-equivalent). Empty means never used.
	LastUsed string `json:"lastUsed,omitempty"`
}

Status is a credential's observed state.

func DecodeStatus

func DecodeStatus(r resource.Resource) (Status, error)

DecodeStatus reads the typed status from a resource.

type Store

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

Store is the typed credential facade over a resource.Store. Credentials live in one scope (the instance's), addressed by "<integration>/<name>"; the facade keeps the single-default-per-integration invariant and resolves a selection reference to a concrete credential.

func NewStore

func NewStore(rs resource.Store) *Store

NewStore returns a credential facade over rs. The caller must have registered the Credential kind with the registry rs admits against (see RegisterKind).

func (*Store) All

func (s *Store) All(ctx context.Context) ([]Credential, error)

All returns every credential across the store, ordered by integration then name. It backs a listing that spans integrations.

func (*Store) Default

func (s *Store) Default(ctx context.Context, integration string) (Credential, error)

Default returns an integration's default credential, or ErrNotFound when the integration has no default.

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, integration, name string) error

Delete removes a credential. It does not touch the vault; deleting the secret value is the caller's separate, deliberate step.

func (*Store) Get

func (s *Store) Get(ctx context.Context, integration, name string) (Credential, error)

Get returns the credential named within an integration, or ErrNotFound.

func (*Store) List

func (s *Store) List(ctx context.Context, integration string) ([]Credential, error)

List returns the credentials of an integration, ordered by name.

func (*Store) Put

func (s *Store) Put(ctx context.Context, spec Spec) (Credential, error)

Put creates or updates a credential. When the credential is marked default, any other default for the same integration is cleared first, so an integration always has at most one default. The secret value is not touched here: a credential is metadata, and the value is written to the vault separately under the credential's Ref.

func (*Store) Resolve

func (s *Store) Resolve(ctx context.Context, ref string) (Credential, error)

Resolve resolves a selection reference to a concrete credential. A reference of the form "<integration>/<name>" selects that credential by name; a bare "<integration>" selects the integration's default. It is the call-site entry point: a request that names a credential gets exactly that one, and a request that names only the integration gets its default.

func (*Store) SetDefault

func (s *Store) SetDefault(ctx context.Context, integration, name string) error

SetDefault makes the named credential the integration's default, clearing any previous default.