interfaces.go

package bitwarden

import (

	"context"

	"io"

)

// VaultClient defines the unified interface for interacting with a Bitwarden vault.

// Both Client (CLI-based via bw serve) and DirectClient (direct server communication)

// implement this interface, allowing applications to work with either mode seamlessly.

//

// The interface provides methods for vault lifecycle management (Status, Sync, Lock, Unlock),

// password generation, and access to various vault services through sub-APIs.

type VaultClient interface {

	// Status returns the current vault status including lock state and user info.

	Status(ctx context.Context) (*Status, error)

	// Sync downloads the latest vault data from the server.

	Sync(ctx context.Context) error

	// Lock clears encryption keys and vault data from memory.

	Lock(ctx context.Context) error

	// Unlock authenticates and derives encryption keys from the password.

	Unlock(ctx context.Context, password string) error

	// Generate creates a password or passphrase based on the provided options.

	Generate(ctx context.Context, opts GenerateOptions) (string, error)

	// Items returns the vault items (ciphers) API.

	Items() ItemsAPI

	// Folders returns the folders API.

	Folders() FoldersAPI

	// Collections returns the user collections API.

	Collections() CollectionsAPI

	// OrgCollections returns the organization collections API.

	OrgCollections() OrgCollectionsAPI

	// Organizations returns the organizations API.

	Organizations() OrganizationsAPI

	// OrgMembers returns the organization members API.

	OrgMembers() OrgMembersAPI

	// Send returns the Bitwarden Send API.

	Send() SendAPI

	// Attachments returns the file attachments API.

	Attachments() AttachmentsAPI

}

// ItemsAPI defines operations on vault items (ciphers).

// Items are the primary data type in a vault and can be logins, secure notes,

// cards, identities, or SSH keys.

type ItemsAPI interface {

	// List retrieves items from the vault with optional filtering.

	List(ctx context.Context, filter ListFilter) ([]Item, error)

	// Get retrieves a single item by its ID.

	Get(ctx context.Context, id string) (*Item, error)

	// Create adds a new item to the vault.

	Create(ctx context.Context, item Item) (*Item, error)

	// Update modifies an existing item.

	Update(ctx context.Context, id string, item Item) (*Item, error)

	// Delete removes an item (moves to trash).

	Delete(ctx context.Context, id string) error

	// Restore recovers a deleted item from the trash.

	Restore(ctx context.Context, id string) error

	// Move transfers an item to an organization with specified collections.

	Move(ctx context.Context, id, organizationID string, collectionIDs []string) error

}

// FoldersAPI defines operations on folders for organizing vault items.

type FoldersAPI interface {

	// List retrieves folders with optional search filter.

	List(ctx context.Context, search string) ([]Folder, error)

	// Get retrieves a single folder by its ID.

	Get(ctx context.Context, id string) (*Folder, error)

	// Create adds a new folder to the vault.

	Create(ctx context.Context, folder Folder) (*Folder, error)

	// Update modifies an existing folder.

	Update(ctx context.Context, id string, folder Folder) (*Folder, error)

	// Delete removes a folder from the vault.

	Delete(ctx context.Context, id string) error

}

// CollectionsAPI defines read-only operations on user collections.

// Collections are groups of items owned by organizations.

type CollectionsAPI interface {

	// List retrieves collections visible to the user with optional filtering.

	List(ctx context.Context, organizationID, search string) ([]Collection, error)

	// Get retrieves a single collection by its ID.

	Get(ctx context.Context, id string) (*Collection, error)

}

// OrgCollectionsAPI defines operations on organization collections.

// Users with appropriate permissions can create, update, and delete org collections.

type OrgCollectionsAPI interface {

	// List retrieves collections in an organization with optional search.

	List(ctx context.Context, organizationID string, search string) ([]OrgCollection, error)

	// Get retrieves a single organization collection by its ID.

	Get(ctx context.Context, id string) (*OrgCollection, error)

	// Create adds a new collection to the organization.

	Create(ctx context.Context, collection OrgCollection) (*OrgCollection, error)

	// Update modifies an existing organization collection.

	Update(ctx context.Context, id string, collection OrgCollection) (*OrgCollection, error)

	// Delete removes a collection from the organization.

	Delete(ctx context.Context, id string) error

}

// OrganizationsAPI defines read-only operations on organizations.

type OrganizationsAPI interface {

	// List retrieves organizations the user belongs to with optional search.

	List(ctx context.Context, search string) ([]Organization, error)

	// Get retrieves a single organization by its ID.

	Get(ctx context.Context, id string) (*Organization, error)

}

// OrgMembersAPI defines operations on organization members.

type OrgMembersAPI interface {

	// List retrieves all members in an organization.

	List(ctx context.Context, organizationID string) ([]OrgMember, error)

	// Confirm accepts a pending member into the organization.

	Confirm(ctx context.Context, id, organizationID string) error

}

// SendAPI defines operations on Bitwarden Send objects.

// Send allows secure sharing of data (text or files) with anyone, even non-Bitwarden users.

type SendAPI interface {

	// List retrieves all Sends owned by the user.

	List(ctx context.Context) ([]Send, error)

	// Get retrieves a single Send by its ID.

	Get(ctx context.Context, id string) (*Send, error)

	// Create adds a new Send to the vault.

	Create(ctx context.Context, send Send) (*Send, error)

	// Update modifies an existing Send.

	Update(ctx context.Context, id string, send Send) (*Send, error)

	// Delete removes a Send from the vault.

	Delete(ctx context.Context, id string) error

	// RemovePassword removes the password protection from a Send.

	RemovePassword(ctx context.Context, id string) (*Send, error)

}

// AttachmentsAPI defines operations on file attachments for vault items.

type AttachmentsAPI interface {

	// Create uploads a file attachment to a vault item.

	Create(ctx context.Context, itemID, filename string, file io.Reader) (*Item, error)

	// Get downloads a file attachment's contents.

	Get(ctx context.Context, attachmentID, itemID string) ([]byte, error)

	// Delete removes a file attachment from a vault item.

	Delete(ctx context.Context, attachmentID, itemID string) error

}

// Verify existing concrete types satisfy the interfaces at compile time.

var (

	_ ItemsAPI          = (*ItemsService)(nil)

	_ FoldersAPI        = (*FoldersService)(nil)

	_ CollectionsAPI    = (*CollectionsService)(nil)

	_ OrgCollectionsAPI = (*OrgCollectionsService)(nil)

	_ OrganizationsAPI  = (*OrganizationsService)(nil)

	_ OrgMembersAPI     = (*OrgMembersService)(nil)

	_ SendAPI           = (*SendService)(nil)

	_ AttachmentsAPI    = (*AttachmentsService)(nil)

)