schema

Documentation

Index

• func AreCredentialUsagesUniquelyIdentifiable(executable Executable) bool
• func ContainsLowercaseLettersOrDigits(str string) bool
• func CredentialReferencesInCredentialList(plugin Plugin) bool
• func IsStringSliceASet(slice []string) bool
• func IsTitleCaseString(str string) bool
• func IsTitleCaseWord(word string) bool
• func NoDuplicateCredentials(plugin Plugin) bool
• type Charset
• type CredentialField
• type CredentialSelection
• type CredentialType
  • func (c CredentialType) Field(name string) *CredentialField
  • func (c CredentialType) Validate() (bool, ValidationReport)
• type CredentialUsage
  • func (c CredentialUsage) ID() string
  • func (c CredentialUsage) Validate() (bool, ValidationReport)
• type Executable
  • func (e Executable) Command() string
  • func (e Executable) Validate() (bool, ValidationReport)
• type PlatformInfo
• type Plugin
  • func (p Plugin) DeepValidate() []ValidationReport
  • func (p Plugin) MarshalJSON() ([]byte, error)
  • func (p Plugin) Validate() (bool, ValidationReport)
• type ValidationCheck
• type ValidationReport
  • func (vr *ValidationReport) AddCheck(check ValidationCheck)
  • func (vr *ValidationReport) HasErrors() bool
  • func (vr *ValidationReport) IsValid() bool
• type ValidationSeverity
• type ValueComposition

Functions

func AreCredentialUsagesUniquelyIdentifiable

func AreCredentialUsagesUniquelyIdentifiable(executable Executable) bool

func ContainsLowercaseLettersOrDigits

func ContainsLowercaseLettersOrDigits(str string) bool

func CredentialReferencesInCredentialList

func CredentialReferencesInCredentialList(plugin Plugin) bool

func IsStringSliceASet

func IsStringSliceASet(slice []string) bool

func IsTitleCaseString

func IsTitleCaseString(str string) bool

func IsTitleCaseWord

func IsTitleCaseWord(word string) bool

func NoDuplicateCredentials

func NoDuplicateCredentials(plugin Plugin) bool

Types

type Charset

type Charset struct {
	Uppercase bool
	Lowercase bool
	Digits    bool
	Symbols   bool
	Specific  []rune
}

type CredentialField

type CredentialField struct {
	// The name of the field, e.g. "Token", "Password", or "Username".
	Name sdk.FieldName

	// Alternative names for this field. Can be used to deprecate field names without breaking existing setups.
	// If there are values present for multiple entries, the first match will be chosen.
	AlternativeNames []string

	// A description of the field.
	MarkdownDescription string

	// Whether this field is secret and should be concealed where possible.
	Secret bool

	// Whether this field is optional.
	Optional bool

	// (Optional) Describes how values of this field look like, such as the length, charset, etc.
	Composition *ValueComposition
}

CredentialField provides the schema of a single field on a credential type.

type CredentialSelection

type CredentialSelection struct {
	// ID helps identify credentials chosen in this selection. This must be unique in relation to other selections specified in usages within its executable.
	ID string
	// IncludeAllCredentials specifies whether this selection should contain all credentials defined in all plugins.
	IncludeAllCredentials bool
	// AllowMultiple specifies whether multiple credentials can be selected to be part of this credential use.
	AllowMultiple bool
}

type CredentialType

type CredentialType struct {
	// What the credential is called within the platform, e.g. "API Key" or "Personal Access Token".
	Name sdk.CredentialName

	// The field(s) on this credential type.
	Fields []CredentialField

	// (Optional) A URL to the documentation about this credential type.
	DocsURL *url.URL

	// (Optional) A URL to the dashboard, console, settings, etc. where this credential type can be created and revoked.
	ManagementURL *url.URL

	// (Optional) A function to scan the system for occurences of this credential type.
	Importer sdk.Importer

	// The default provisioner to use for this credential if the executable doesn't override it.
	DefaultProvisioner sdk.Provisioner
}

CredentialType provides the schema of a credential type that the plugin provides.

func (CredentialType) Field

func (c CredentialType) Field(name string) *CredentialField

func (CredentialType) Validate

func (c CredentialType) Validate() (bool, ValidationReport)

type CredentialUsage

type CredentialUsage struct {
	// (Optional) The name of the credential to use in the executable. Mutually exclusive with `SelectFrom`.
	Name sdk.CredentialName

	// (Optional) The plugin name that contains the credential. Defaults to the current package. This can be used to
	// include credentials from other plugins. Mutually exclusive with `SelectFrom`.
	Plugin string

	// (Optional) The provisioner to use to provision this credential to the executable. Overrides the DefaultProvisioner
	// set in the credential schema, so should only be used if this executable requires a custom configuration, that deviates
	// from the way the credential is usually provisioned. Mutually exclusive with `SelectFrom`.
	Provisioner sdk.Provisioner

	// (Optional) What this credential will be used for by the executable.
	Description string

	// (Optional) Instead of requiring a specific credential, have the user select from a list of compatible credentials.
	// Mutually exclusive with: `Name` and `Plugin`.
	SelectFrom *CredentialSelection

	// (Optional) Whether the exectuable needs authentication for this credential. Works side by side with the executable's
	// `NeedsAuth`, which can still be used for more generic authentications opt-outs, such as the help flag.
	NeedsAuth sdk.NeedsAuthentication

	// Whether this credential is needed for the executable to run. If set to true, the executable cannot run without provisioning this credential.
	Optional bool
}

func (CredentialUsage) ID

func (c CredentialUsage) ID() string

ID returns the identifier of this credential usage at the scope of its executable

func (CredentialUsage) Validate

func (c CredentialUsage) Validate() (bool, ValidationReport)

type Executable

type Executable struct {
	// The entrypoint of the command that should be executed, e.g. ["aws"] or ["stripe"].
	Runs []string

	// The display name of the executable, e.g. "AWS CLI".
	Name string

	// Which credentials the executable requires to run and how these should be provisioned.
	Uses []CredentialUsage

	// (Optional) A URL to the documentation about this executable.
	DocsURL *url.URL

	// (Optional) Whether the executable needs authentication for certain args.
	NeedsAuth sdk.NeedsAuthentication
}

func (Executable) Command

func (e Executable) Command() string

func (Executable) Validate

func (e Executable) Validate() (bool, ValidationReport)

type PlatformInfo

type PlatformInfo struct {
	// The display name of the platform, e.g. "AWS" or "GitHub".
	Name string

	// The full URL of the homepage of the platform.
	Homepage *url.URL
}

PlatformInfo provides information on the platform of the shell plugin.

type Plugin

type Plugin struct {
	// The name of the plugin package, e.g. "aws" or "github". Should be the same name as the Go package.
	Name string

	// Details about the platform that the plugin covers.
	Platform PlatformInfo

	// One or more specifications for the credential types the plugin offers.
	Credentials []CredentialType

	// One or more specifications for the executables the plugin offers.
	Executables []Executable
}

Plugin provides the schema for a single shell plugin. A plugin focuses on a single platform and can provide one or more credential types and one or more executables.

func (Plugin) DeepValidate

func (p Plugin) DeepValidate() []ValidationReport

func (Plugin) MarshalJSON

func (p Plugin) MarshalJSON() ([]byte, error)

func (Plugin) Validate

func (p Plugin) Validate() (bool, ValidationReport)

type ValidationCheck

type ValidationCheck struct {
	// Description explains what we want to validate
	Description string
	// Assertion
	Assertion bool
	// Severity is "warning" for Optional fields that are not passed and "error" for Required fields
	Severity ValidationSeverity
}

type ValidationReport

type ValidationReport struct {
	Heading string
	Checks  []ValidationCheck
}

func (*ValidationReport) AddCheck

func (vr *ValidationReport) AddCheck(check ValidationCheck)

func (*ValidationReport) HasErrors

func (vr *ValidationReport) HasErrors() bool

func (*ValidationReport) IsValid

func (vr *ValidationReport) IsValid() bool

type ValidationSeverity

type ValidationSeverity string

const (
	ValidationSeverityWarning ValidationSeverity = "warning"
	ValidationSeverityError   ValidationSeverity = "error"
)

type ValueComposition

type ValueComposition struct {
	// The length of the value, if it's guaranteed to be of a fixed length.
	Length int

	// Which characters the value can consist of.
	Charset Charset

	// (Optional) A certain prefix that's always present on the value, as popularized by GitHub.
	Prefix string
}

ValueComposition describes what a value for a certain field looks like. This gets used for various purposes, including but not limited to the Save in 1Password functionality and secrets scanning functionality.