onepassword

README

1Password Secret Source (op://)

The 1Password secret source retrieves secrets directly from 1Password using the new official 1Password Go SDK.

Status

Plugin: This source is opt-in. It is not enabled by default and requires explicit configuration using With1Password().

Testing: Because the 1Password SDK relies on a Rust core to communicate directly with production servers, it does not support local mocking or Testcontainers. Integration tests require a valid 1Password Service Account and are thus skipped in standard CI environments without the SPELUNK_1PASSWORD_TEST_SATOKEN environment variable set.

Dependencies

This plugin requires the official 1Password Go SDK:

• github.com/1password/onepassword-sdk-go

Usage

To use the 1Password source, use the op:// scheme followed by the Vault, Item, optional Section, and Field you want to retrieve.

In Spelunk, these "Secret Coordinates" are exactly the same as the "Secret Reference" that you can obtain by going to a 1Password vault item, selecting a field, and copying its "Secret Reference". See https://developer.1password.com/docs/cli/secret-reference-syntax.

Syntax

op://<VAULT>/<ITEM>/[<SECTION>]/<FIELD>

Examples

Retrieve the password field from the Database item in the Production vault:

op://Production/Database/password

Retrieve the token field from the API section of the Stripe item in the Shared vault:

op://Shared/Stripe/API/token

Configuration

To use this source, you must initialize spelunk with a 1Password client. The 1Password Go SDK supports two authentication methods:

1. Service Account: Uses a token to authenticate. Best for CI/CD, servers, and automated environments.
2. Local App: Communicates with the 1Password desktop app running on the same machine. Best for local development.

Example using a Service Account

import (
    "context"
    "os"
    "github.com/1password/onepassword-sdk-go"
    "github.com/detro/spelunk/v2"
    "github.com/detro/spelunk/plugin/source/1password/v2"
)

func main() {
    // 1. Create 1Password client
    token := os.Getenv("SPELUNK_1PASSWORD_TEST_SATOKEN")
    client, _ := onepassword.NewClient(
        context.Background(),
        onepassword.WithServiceAccountToken(token), // Or use onepassword.WithDesktopAppIntegration("account-name") for Local App
        onepassword.WithIntegrationInfo("My App", "v1.0.0"),
    )

    // 2. Initialize Spelunker with the 1Password plugin
    s := spelunk.NewSpelunker(
        onepassword.With1Password(client),
    )

    // 3. Dig up secrets
    coord, _ := types.NewSecretCoord("op://Production/Database/password")
    secret, _ := s.DigUp(ctx, coord)
}

Behavior

1. Parsing: Validates the location strictly matches the format VAULT/ITEM/FIELD or VAULT/ITEM/SECTION/FIELD.
2. Retrieval: Uses client.Secrets().Resolve() with the official op:// reference syntax.
3. Errors:
   • Returns types.ErrInvalidLocation if the format is incorrect.
   • Returns ErrCouldNotFetchSecret if the API call fails, authentication is invalid, or the item/field doesn't exist (the SDK currently lacks strongly typed error differentiation for "not found").

Use Cases

• Dynamically fetching database credentials, API keys, or certificates from a centralized 1Password Vault.
• Local development without storing .env files (using the 1Password desktop app integration).
• Secure secret injection in CI/CD pipelines (using Service Accounts).

Documentation

Index

• func With1Password(client *onepassword.Client) spelunk.SpelunkerOption
• type SecretSource1Password
  • func (s *SecretSource1Password) DigUp(ctx context.Context, coord types.SecretCoord) (string, error)
  • func (s *SecretSource1Password) Type() string

Functions

func With1Password

func With1Password(client *onepassword.Client) spelunk.SpelunkerOption

With1Password enables the SecretSource1Password.

Types

type SecretSource1Password

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

SecretSource1Password digs up secrets from 1Password. The URI scheme for this source is "op".

op://VAULT/ITEM/[SECTION]/FIELD

In Spelunk, these "Secret Coordinates" are exactly the same as the "Secret Reference" that you can obtain by going to a 1Password vault item, selecting a field, and copying its "Secret Reference". See: https://developer.1password.com/docs/cli/secret-reference-syntax.

This types.SecretSource is a plug-in to spelunker.Spelunker and must be enabled explicitly.

func (*SecretSource1Password) DigUp

func (s *SecretSource1Password) DigUp(
	ctx context.Context,
	coord types.SecretCoord,
) (string, error)

func (*SecretSource1Password) Type

func (s *SecretSource1Password) Type() string