helper

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package helper provides high-level operations for the Passbolt API.

Index

Constants

This section is empty.

Variables

View Source
var (
	// Resource creation errors
	ErrV5CreationDisabled       = errors.New("creation of V5 passwords is disabled on this server")
	ErrV4CreationDisabled       = errors.New("creation of V4 passwords is disabled on this server")
	ErrResourceTypeSlugNotFound = errors.New("cannot find resource type")
	ErrPasswordTooLong          = errors.New("password exceeds maximum length")

	// Lookup errors
	ErrKeyNotFound        = errors.New("cannot find key for user")
	ErrMembershipNotFound = errors.New("cannot find membership for user")
	ErrSecretNotFound     = errors.New("cannot find secret for resource")

	// Custom field validation errors
	ErrCustomFieldInvalidID    = errors.New("custom field id must be a valid UUID")
	ErrCustomFieldMissingKey   = errors.New("custom field in metadata must have metadata_key")
	ErrCustomFieldMissingValue = errors.New("custom field in secret must have secret_value")
	ErrCustomFieldCrossField   = errors.New("custom field key/value must be defined in only one of metadata or secret")
	ErrCustomFieldIDMismatch   = errors.New("custom field ids must match in metadata and secret arrays")
)
View Source
var ErrSchemaMismatch = fmt.Errorf("%w: it has undeclared properties", ErrSchemaValidation)

ErrSchemaMismatch is the write-path case of ErrSchemaValidation: the document carries properties the schema does not declare, either because of a wrong field name or because the bundled schema is older than the server's Resource Type. errors.Is reports ErrSchemaValidation for it too.

View Source
var ErrSchemaValidation = errors.New("data does not match the bundled Resource Type schema")

ErrSchemaValidation is returned when a document fails validation against the bundled Resource Type schema, on the read path as well as the write path. Lenient read validation still enforces every declared constraint, so a stored value this build's schema rejects fails here too.

View Source
var ErrUnsupportedResourceType = errors.New("unsupported resource type")

ErrUnsupportedResourceType is returned when a resource has an unknown resource type slug that cannot be decoded by the helper functions.

Functions

func AddMFACallbackTOTP

func AddMFACallbackTOTP(c *api.Client, retrys uint, retryDelay, offset time.Duration, token string)

AddMFACallbackTOTP adds a MFA callback to the client that generates OTP Codes on demand using a Token with configurable retries and delay

func CreateFolder

func CreateFolder(ctx context.Context, c *api.Client, folderParentID, name string) (string, error)

CreateFolder Creates a new Folder

func CreateGroup

func CreateGroup(ctx context.Context, c *api.Client, name string, operations []GroupMembershipOperation) (string, error)

CreateGroup creates a Groups with Name and Memberships

func CreateResource

func CreateResource(ctx context.Context, c *api.Client, folderParentID, name, username, uri, password, description string) (string, error)

CreateResource creates a resource using the server's preferred format (v4 or v5). For more control, use CreateResourceGeneric.

func CreateResourceGeneric

func CreateResourceGeneric(ctx context.Context, c *api.Client, slug string, folderParentID string, metadataFields map[string]any, secretFields map[string]any) (string, error)

CreateResourceGeneric creates a resource of any type using dynamic field maps. The slug determines the resource type. Metadata and secret fields are validated against the resource type's JSON schema before submission.

func CreateResourceSimple deprecated

func CreateResourceSimple(ctx context.Context, c *api.Client, folderParentID, name, username, uri, password, description string) (string, error)

Deprecated: Use CreateResourceGeneric instead. CreateResourceSimple creates a legacy resource where only the password is encrypted.

func CreateResourceV4 deprecated

func CreateResourceV4(ctx context.Context, c *api.Client, folderParentID, name, username, uri, password, description string) (string, error)

Deprecated: Use CreateResourceGeneric instead. CreateResourceV4 creates a v4 password-and-description resource. Delegates to CreateResourceGeneric.

func CreateResourceV5 deprecated

func CreateResourceV5(ctx context.Context, c *api.Client, folderParentID, name, username, uri, password, description string) (string, error)

Deprecated: Use CreateResourceGeneric instead. CreateResourceV5 creates a v5-default resource. Delegates to CreateResourceGeneric.

func CreateUser

func CreateUser(ctx context.Context, c *api.Client, role, username, firstname, lastname string) (string, error)

CreateUser Creates a new User

func DeleteFolder

func DeleteFolder(ctx context.Context, c *api.Client, folderID string) error

DeleteFolder Deletes a Folder

func DeleteGroup

func DeleteGroup(ctx context.Context, c *api.Client, groupID string) error

DeleteGroup Deletes a Group

func DeleteResource

func DeleteResource(ctx context.Context, c *api.Client, resourceID string) error

DeleteResource Deletes a Resource

func DeleteUser

func DeleteUser(ctx context.Context, c *api.Client, userID string) error

DeleteUser Deletes a User

func GenerateOTPCode

func GenerateOTPCode(token string, when time.Time) (string, error)

GenerateOTPCode generates a 6 digit TOTP from the secret Token.

func GeneratePermissionChanges

func GeneratePermissionChanges(oldPermissions []api.Permission, changes []ShareOperation) ([]api.Permission, error)

GeneratePermissionChanges Generates the Permission Changes for a Resource/Folder nessesary for a single Share Operation

func GetFolder

func GetFolder(ctx context.Context, c *api.Client, folderID string) (string, string, error)

GetFolder Gets a Folder

func GetResource

func GetResource(ctx context.Context, c *api.Client, resourceID string) (folderParentID, name, username, uri, password, description string, err error)

GetResource gets a resource by ID and returns its decrypted fields.

func GetResourceFieldMaps

func GetResourceFieldMaps(c *api.Client, resource api.Resource, secret api.Secret, rType api.ResourceType, decryptSecret bool) (folderParentID string, metadataFields, secretFields map[string]any, err error)

GetResourceFieldMaps decrypts a resource and returns the metadata and secret field maps. This is useful for callers that need access to custom fields beyond the standard name/username/uri/password/description; those standard fields can be read from the returned maps with GetStringField.

func GetResourceFromData

func GetResourceFromData(c *api.Client, resource api.Resource, secret api.Secret, rType api.ResourceType) (string, string, string, string, string, string, error)

GetResourceFromData decrypts resources using only local data. The Resource object must include the secret. With v5 this needs network calls for metadata of v5 resources.

func GetResourceFromDataWithOptions

func GetResourceFromDataWithOptions(c *api.Client, resource api.Resource, secret api.Secret, rType api.ResourceType, decryptSecret bool) (string, string, string, string, string, string, error)

GetResourceFromDataWithOptions decrypts resources with option to skip secret decryption. For v5 resources, metadata (name, username, uri) can be decrypted without the secret. Set decryptSecret=false to skip secret decryption (password/description will be empty).

func GetResourceMetadata

func GetResourceMetadata(ctx context.Context, c *api.Client, resource *api.Resource, rType *api.ResourceType) (string, error)

GetResourceMetadata decrypts a v5 resource's metadata, validating leniently so undeclared properties survive. Use GetResourceMetadataForWrite when the result will be stored again.

func GetResourceMetadataForWrite

func GetResourceMetadataForWrite(ctx context.Context, c *api.Client, resource *api.Resource, rType *api.ResourceType) (string, error)

GetResourceMetadataForWrite decrypts metadata that will be re-encrypted and stored, validating strictly; extra properties yield an error wrapping ErrSchemaMismatch.

func GetStringField

func GetStringField(m map[string]any, key string) string

GetStringField safely extracts a string from a map. Returns "" if the key is missing or the value isn't a string.

func GetUser

func GetUser(ctx context.Context, c *api.Client, userID string) (string, string, string, string, error)

GetUser Gets a User

func MoveFolder

func MoveFolder(ctx context.Context, c *api.Client, folderID, folderParentID string) error

MoveFolder Moves a Folder into a Folder

func MoveResource

func MoveResource(ctx context.Context, c *api.Client, resourceID, folderParentID string) error

MoveResource Moves a Resource into a Folder

func ParseInviteURL

func ParseInviteURL(url string) (string, string, error)

ParseInviteURL parses a Passbolt Invite URL into a user id and token.

func SetupAccount

func SetupAccount(ctx context.Context, c *api.Client, userID, token, password string) (string, error)

SetupAccount Setup a Account for a Invited User. (Use ParseInviteURL to get the userid and token from a Invite URL)

func ShareFolder

func ShareFolder(ctx context.Context, c *api.Client, folderID string, changes []ShareOperation) error

ShareFolder Shares a Folder as Specified in the Passed ShareOperation Struct Slice. Note Resources Permissions in the Folder are not Adjusted

func ShareFolderWithUsersAndGroups

func ShareFolderWithUsersAndGroups(ctx context.Context, c *api.Client, folderID string, Users []string, Groups []string, permissionType int) error

ShareFolderWithUsersAndGroups Shares a Folder With The Users and Groups with the Specified Type, if the Folder has already been shared With the User/Group the Permission Type will be Adjusted/Deleted. Note: Resources Permissions in the Folder are not Adjusted (Like the Extension does)

func ShareResource

func ShareResource(ctx context.Context, c *api.Client, resourceID string, changes []ShareOperation) error

ShareResource Shares a Resource as Specified in the Passed ShareOperation Struct Slice

func ShareResourceWithUsersAndGroups

func ShareResourceWithUsersAndGroups(ctx context.Context, c *api.Client, resourceID string, Users []string, Groups []string, permissionType int) error

ShareResourceWithUsersAndGroups Shares a Resource With The Users and Groups with the Specified Permission Type, if the Resource has already been shared With the User/Group the Permission Type will be Adjusted/Deleted

func UpdateFolder

func UpdateFolder(ctx context.Context, c *api.Client, folderID, name string) error

UpdateFolder Updates a Folder

func UpdateGroup

func UpdateGroup(ctx context.Context, c *api.Client, groupID, name string, operations []GroupMembershipOperation) error

UpdateGroup Updates a Groups Name and Memberships

func UpdateResource

func UpdateResource(ctx context.Context, c *api.Client, resourceID, name, username, uri, password, description string) error

UpdateResource updates resource fields. Empty strings are not applied (partial update). Note: to change FolderParentID, use MoveResource instead.

func UpdateResourceGeneric

func UpdateResourceGeneric(ctx context.Context, c *api.Client, resourceID string, metadataUpdates map[string]any, secretUpdates map[string]any) error

UpdateResourceGeneric updates a resource using dynamic field maps. Only provided keys are updated; existing values are preserved for keys not in the update maps.

func UpdateUser

func UpdateUser(ctx context.Context, c *api.Client, userID, role, firstname, lastname string) error

UpdateUser Updates a User

Types

type CustomField

type CustomField struct {
	ID    string
	Name  string // metadata_key, else the decrypted secret_key
	Value string // secret_value, else metadata_value
}

CustomField is one custom field of a v5 resource, merged from its metadata and secret halves by id.

type CustomFields

type CustomFields []CustomField

CustomFields is a resource's custom fields, in metadata order.

func ParseCustomFields

func ParseCustomFields(metadataFields, secretFields map[string]any) CustomFields

ParseCustomFields merges the custom_fields arrays of the metadata and secret field maps returned by GetResourceFieldMaps. The metadata array decides which fields exist and in what order, so a resource with none there returns nil. Malformed entries are projected as best they can be rather than rejected, since the server cannot validate encrypted content.

func (CustomFields) Map

func (c CustomFields) Map() map[string]string

Map flattens custom fields to name -> value, dropping unnamed ones. On duplicate names the last wins.

type GroupMembership

type GroupMembership struct {
	MembershipID   string
	UserID         string
	Username       string
	UserFirstName  string
	UserLastName   string
	IsGroupManager bool
}

GroupMembership contains who and what kind of membership they have with a group

func GetGroup

func GetGroup(ctx context.Context, c *api.Client, groupID string) (string, []GroupMembership, error)

GetGroup gets a Groups Name and Memberships

type GroupMembershipOperation

type GroupMembershipOperation struct {
	UserID         string
	IsGroupManager bool
	Delete         bool
}

GroupMembershipOperation creates/modifies/deletes a group membership

type ShareOperation

type ShareOperation struct {
	// Type of Permission: 1 = Read, 7 = can Update, 15 = Owner (Owner can also Share Resource)
	// Note: Setting this to -1 Will delete this Permission if it already Exists, errors if this Permission Dosen't Already Exists
	Type int
	// ARO is what Type this should be Shared With (User, Group)
	ARO string
	// AROID is the ID of the User or Group(ARO) this should be Shared With
	AROID string
}

ShareOperation defines how Resources are to be Shared With Users/Groups

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL