sdk

Documentation

Index

• func URL(urlStr string) *url.URL
• type CacheEntry
• type CacheOperations
  • func (c *CacheOperations) Put(key string, data any, expiresAt time.Time) error
  • func (c *CacheOperations) Remove(key string)
• type CacheState
  • func (c CacheState) Get(key string, out any) (ok bool)
  • func (c CacheState) Has(key string) (ok bool)
• type CredentialName
  • func (n CredentialName) ID() CredentialTypeID
  • func (n CredentialName) String() string
• type CredentialTypeID
  • func (i CredentialTypeID) String() string
• type CustomSource
• type DeprovisionInput
• type DeprovisionOutput
• type Diagnostics
• type Error
• type FieldName
  • func (n FieldName) String() string
• type ImportAttempt
  • func (out *ImportAttempt) AddCandidate(candidate ImportCandidate)
  • func (out *ImportAttempt) AddError(err error)
• type ImportCandidate
  • func (c *ImportCandidate) Equal(other ImportCandidate) bool
• type ImportInput
  • func (in *ImportInput) FromHomeDir(path ...string) string
  • func (in *ImportInput) FromRootDir(path ...string) string
• type ImportOutput
  • func (out *ImportOutput) AllCandidates() (candidates []ImportCandidate)
  • func (out *ImportOutput) Errors() (errors []Error)
  • func (out *ImportOutput) NewAttempt(src ImportSource) *ImportAttempt
• type ImportSource
• type Importer
• type NeedsAuthentication
• type NeedsAuthenticationInput
• type OutputFile
• type ProvisionInput
  • func (in *ProvisionInput) FromHomeDir(path ...string) string
  • func (in *ProvisionInput) FromTempDir(path ...string) string
• type ProvisionOutput
  • func (out *ProvisionOutput) AddArgs(args ...string)
  • func (out *ProvisionOutput) AddEnvVar(name string, value string)
  • func (out *ProvisionOutput) AddError(err error)
  • func (out *ProvisionOutput) AddFile(path string, file OutputFile)
  • func (out *ProvisionOutput) AddNonSecretFile(path string, contents []byte)
  • func (out *ProvisionOutput) AddSecretFile(path string, contents []byte)
• type Provisioner

Functions

func URL

func URL(urlStr string) *url.URL

Types

type CacheEntry

type CacheEntry struct {
	Data      []byte
	ExpiresAt time.Time
}

CacheEntry contains data persisted between consecutive provision runs

type CacheOperations

type CacheOperations struct {
	Puts    map[string]CacheEntry
	Removes []string
}

CacheOperations can be used to modify the state of the encrypted cache, through put or remove operations. Good to note: remove operations are executed before put operations.

func (*CacheOperations) Put

func (c *CacheOperations) Put(key string, data any, expiresAt time.Time) error

Put puts data into the cache at the specified key and with the specified TTL, which will be applied to the provision step of all consecutive runs, until the TTL is met or Remove is called. The data will be stored as a []byte or marshaled as JSON.

func (*CacheOperations) Remove

func (c *CacheOperations) Remove(key string)

Remove removes data from the cache at the specified key, which will be applied to the provision step of all consecutive runs.

type CacheState

type CacheState map[string]CacheEntry

CacheState represents the state of the encrypted cache for a given plugin and item.

func (CacheState) Get

func (c CacheState) Get(key string, out any) (ok bool)

Get returns the cached value at the specified key if it exists. The data can be returned either as a []byte or unmarshaled as JSON.

func (CacheState) Has

func (c CacheState) Has(key string) (ok bool)

Has returns whether the specified key is present in the cache.

type CredentialName

type CredentialName string

CredentialName represents a name of a credential type. It should be title-cased. Examples: "Personal Access Token", "API Key".

func (CredentialName) ID

func (n CredentialName) ID() CredentialTypeID

func (CredentialName) String

func (n CredentialName) String() string

type CredentialTypeID

type CredentialTypeID string

func (CredentialTypeID) String

func (i CredentialTypeID) String() string

type CustomSource

type CustomSource struct {
	Type  string
	Value []string
}

type DeprovisionInput

type DeprovisionInput struct {
	HomeDir string
	TempDir string
	DryRun  bool
}

DeprovisionInput contains info that provisioners can use to deprovision credentials.

type DeprovisionOutput

type DeprovisionOutput struct {
	Diagnostics Diagnostics
}

type Diagnostics

type Diagnostics struct {
	Errors []Error
}

type Error

type Error struct {
	Message string
}

type FieldName

type FieldName string

FieldName represents a name of credential field. It should be title-cased. Examples: "Password", "Token", "API Key".

func (FieldName) String

func (n FieldName) String() string

type ImportAttempt

type ImportAttempt struct {
	Candidates  []ImportCandidate
	Source      ImportSource
	Diagnostics Diagnostics
}

func (*ImportAttempt) AddCandidate

func (out *ImportAttempt) AddCandidate(candidate ImportCandidate)

func (*ImportAttempt) AddError

func (out *ImportAttempt) AddError(err error)

type ImportCandidate

type ImportCandidate struct {
	Fields    map[FieldName]string
	NameHint  string
	ExpiresAt *time.Time
}

ImportCandidate represents a single occurrence of a plugin's credential that was detected on the system.

func (*ImportCandidate) Equal

func (c *ImportCandidate) Equal(other ImportCandidate) bool

type ImportInput

type ImportInput struct {
	HomeDir string
	RootDir string

	// Supported values: "darwin", "linux"
	OS string
}

func (*ImportInput) FromHomeDir

func (in *ImportInput) FromHomeDir(path ...string) string

func (*ImportInput) FromRootDir

func (in *ImportInput) FromRootDir(path ...string) string

type ImportOutput

type ImportOutput struct {
	Attempts []*ImportAttempt
}

func (*ImportOutput) AllCandidates

func (out *ImportOutput) AllCandidates() (candidates []ImportCandidate)

func (*ImportOutput) Errors

func (out *ImportOutput) Errors() (errors []Error)

func (*ImportOutput) NewAttempt

func (out *ImportOutput) NewAttempt(src ImportSource) *ImportAttempt

type ImportSource

type ImportSource struct {
	Env   []string
	Files []string
	Other CustomSource
}

type Importer

type Importer func(ctx context.Context, in ImportInput, out *ImportOutput)

Importer provides a hook for the plugin to scan the system for occurrences of a certain credential type, and returns every occurrence it can find.

type NeedsAuthentication

type NeedsAuthentication func(in NeedsAuthenticationInput) (needsAuthentication bool)

NeedsAuthentication provides a hook to check whether authentication are required for certain command args.

type NeedsAuthenticationInput

type NeedsAuthenticationInput struct {
	CredentialType string
	CommandArgs    []string
}

type OutputFile

type OutputFile struct {
	Contents []byte
}

OutputFile contains the sensitive file info and contents that the provisioner outputs.

type ProvisionInput

type ProvisionInput struct {
	// HomeDir is the path to current user's home directory.
	HomeDir string

	// TempDir is the path to a temporary directory that the provisioner can use to add files to.
	// This directory will automatically be deleted after the executable exits.
	TempDir string

	// DryRun can be used to opt out
	DryRun bool

	// Cache can contain data that got added in the provision step from previous runs for this credential.
	Cache CacheState

	// ItemFields contains the field names and their corresponding (sensitive) values.
	ItemFields map[FieldName]string
}

ProvisionInput contains info that provisioners can use to provision credentials.

func (*ProvisionInput) FromHomeDir

func (in *ProvisionInput) FromHomeDir(path ...string) string

FromHomeDir returns a path with the user's home directory prepended.

func (*ProvisionInput) FromTempDir

func (in *ProvisionInput) FromTempDir(path ...string) string

FromTempDir returns a path with the current execution's temp directory prepended.

type ProvisionOutput

type ProvisionOutput struct {
	// Environment can be used to provision credentials as environment variable. The result of this will be added to the executable's environment.
	// The expected mapping is: environment variable name to (possibly sensitive) value.
	Environment map[string]string

	// CommandLine can be used provision credentials as command-line args. The result of this will be the actual (possibly sensitive) command
	// line that will be executed.
	CommandLine []string

	// Files can be used to provision credentials as files. The result of this will be automatically written to disk and deleted when the executable
	// exits. The expected mapping is: absolute file path to (possibly sensitive) file contents.
	Files map[string]OutputFile

	// Cache can be used to make data generated in this provision step available to the provision step of consecutive runs for this credential.
	// The data added to the cache will be encrypted and stored locally on disk, so it can be used to store sensitive data. To access the cached
	// data from previous runs, use Cache on ProvisionInput.
	Cache CacheOperations

	// Diagnostics can be used to report errors.
	Diagnostics Diagnostics
}

ProvisionOutput contains the sensitive values that the Provisioner outputs.

func (*ProvisionOutput) AddArgs

func (out *ProvisionOutput) AddArgs(args ...string)

AddArgs can be used to add additional arguments to the command line of the provision output.

func (*ProvisionOutput) AddEnvVar

func (out *ProvisionOutput) AddEnvVar(name string, value string)

AddEnvVar adds an environment variable to the provision output.

func (*ProvisionOutput) AddError

func (out *ProvisionOutput) AddError(err error)

AddError can be used to report an error to the provision output. If the provision output contains one or more errors, provisioning is considered failed.

func (*ProvisionOutput) AddFile

func (out *ProvisionOutput) AddFile(path string, file OutputFile)

AddFile can be used to add a file to the provision output.

func (*ProvisionOutput) AddNonSecretFile

func (out *ProvisionOutput) AddNonSecretFile(path string, contents []byte)

AddNonSecretFile can be used to add a file that does not contain secrets to the provision output.

func (*ProvisionOutput) AddSecretFile

func (out *ProvisionOutput) AddSecretFile(path string, contents []byte)

AddSecretFile can be used to add a file containing secrets to the provision output.

type Provisioner

type Provisioner interface {
	// Description describes what this provisioner does.
	Description() string

	// Provision gets called before running the plugin's executable to provision the necessary fields
	// from the 1Password item in a way that the executable understands.
	Provision(ctx context.Context, input ProvisionInput, output *ProvisionOutput)

	// Deprovision gets called after the plugin's executable exits, so that the plugin can clean up and
	// wipe any sensitive material created in the provision phase.
	Deprovision(ctx context.Context, input DeprovisionInput, output *DeprovisionOutput)
}

Provisioner provides hooks before and after the plugin's executable runs to provision and deprovision secrets or other means of authentication required for the executable to run.