pandoru 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad02207b38cdbe7ac38fe971c4a3c13e1f439336791f559b6c3bd6b2cc38ef36
-  data.tar.gz: da0f8c0372e9302bfee89f5ddcd7d1b460265f3f55b21ef1054c1bc59e8c6b2e
+  metadata.gz: fd2045e11084de310e45882480a3e8472ebceac1e81ca927682f978f10458ffa
+  data.tar.gz: f279f57d936e055be8c819f154a9b863c45ffdf01ceb4970cd130035c480b033
 SHA512:
-  metadata.gz: ff0b263da1d80d461ccdf1e81277fb5c22f3fb55f0651b89a317f69f47970228297bb03a6acf6d13bea91567ea7f86f56577db3a52cd991b55f1ee0df8360843
-  data.tar.gz: a419c0670a1ce0d57ac5fece5c7b194d67292a4cd2a648b494a6df5b59fdcf7dee7ea23a267746d9c01292e2b0dcabfb75e5d524853907e2eda42b95d0192aff
+  metadata.gz: 654f2fcb4948e93307ce68650c7b53fbd29e20252dac628311e5509ec3b25bfb2b0f9116d51ed5da583cc72fecd91333b2518ea206117ef1418fd7a9eec05453
+  data.tar.gz: aed635c1e7eec1bc31b7790386f99c700d4964061dcc672535d9233e1ee81381050687d8829e37709ba491cfac190557f842a5cb42e6022eacf04728378a1b4f

data/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented here. The format is based
 on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-05-25
+
+### Added
+- `Pandoru::Credentials.resolve` — tiered credential resolution: explicit args →
+  `PANDORA_USERNAME`/`PANDORA_PASSWORD` env → OS secret store → JSON file at
+  `$PANDORU_CREDENTIALS` / `~/.config/pandoru/credentials.json` (first complete
+  pair wins; blank values fall through).
+- `Pandoru::SecretStore` — portable OS secret storage (macOS Keychain, Linux
+  libsecret; Windows falls back to the file tier) so the password need not live
+  in plaintext.
+- `pandoru-login` executable — prompt for credentials and store them in the OS
+  secret store.
+
 ## [0.1.1] - 2026-05-25
 
 ### Fixed
@@ -40,5 +53,6 @@ targeting Pandora's partner/device JSON API (`tuner.pandora.com/services/json/`)
 - Corrected the encryption/decryption key orientation in the bundled default
   partner settings.
 
+[0.2.0]: https://github.com/TwilightCoders/pandoru/releases/tag/v0.2.0
 [0.1.1]: https://github.com/TwilightCoders/pandoru/releases/tag/v0.1.1
 [0.1.0]: https://github.com/TwilightCoders/pandoru/releases/tag/v0.1.0

data/exe/pandoru-login

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Store Pandora credentials in the OS secret store (macOS Keychain, Linux
+# libsecret) so no password lives in a plaintext file. The client reads them at
+# runtime via Pandoru::Credentials.
+#
+#   pandoru-login            # prompt + store
+#   pandoru-login --delete   # remove the stored item
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'pandoru'
+require 'io/console'
+
+store = Pandoru::SecretStore
+
+unless store.available?
+  warn "No OS secret store available on this platform (#{store.backend_name})."
+  warn 'Fall back to a credentials file — see README "Credentials".'
+  exit 1
+end
+
+if ARGV[0] == '--delete'
+  removed = store.delete
+  puts removed ? 'Removed Pandora credentials from the secret store.' : 'Nothing stored.'
+  exit removed ? 0 : 1
+end
+
+print 'Pandora email/username: '
+username = $stdin.gets&.strip
+abort 'Aborted — no username.' if username.nil? || username.empty?
+
+print 'Password (hidden): '
+password = $stdin.noecho(&:gets)&.chomp
+puts
+abort 'Aborted — no password.' if password.nil? || password.empty?
+
+if store.store(username, password)
+  puts "✓ Stored in #{store.backend_name} (account: #{username})."
+  puts 'No password on disk — the client reads it at runtime.'
+else
+  abort 'Failed to store credentials in the secret store.'
+end

data/lib/pandoru/credentials.rb

@@ -0,0 +1,109 @@
+require 'json'
+
+module Pandoru
+  # Resolves Pandora account credentials from the first source that supplies a
+  # complete pair, so the client/CLI works whether you prefer env vars, the OS
+  # secret store, or a config file. Empty values count as absent, so an
+  # unset/blank env var gracefully falls through to the next source rather than
+  # half-authenticating.
+  #
+  # Precedence (highest first), mirroring the common config-resolution standard
+  # (explicit wins; env for 12-factor/CI; XDG Base Directory for the file):
+  #
+  #   1. Explicit values passed in (tests, embedding).
+  #   2. ENV PANDORA_USERNAME / PANDORA_PASSWORD.
+  #   3. The OS secret store (Keychain / libsecret), if a credential is stored.
+  #   4. A JSON file { "username": ..., "password": ... } at the first that
+  #      exists, in order:
+  #        $PANDORU_CREDENTIALS                       (explicit path override)
+  #        $XDG_CONFIG_HOME/pandoru/credentials.json  (XDG; default ~/.config)
+  #
+  # A future tier should delegate to Pandoru::ClientBuilders for the existing
+  # pydora `.cfg` / pianobar config files rather than reimplementing that
+  # parsing — tracked as a follow-up.
+  class Credentials
+    class NotFound < StandardError; end
+
+    Resolved = Struct.new(:username, :password, :source, keyword_init: true)
+
+    USERNAME_KEYS = %w[username user email].freeze
+    PASSWORD_KEYS = %w[password pass].freeze
+
+    def self.resolve(username: nil, password: nil, env: ENV, home: Dir.home, secret_store: SecretStore)
+      new(env: env, home: home, secret_store: secret_store)
+        .resolve(username: username, password: password)
+    end
+
+    def initialize(env: ENV, home: Dir.home, secret_store: SecretStore)
+      @env = env
+      @home = home
+      @secret_store = secret_store
+    end
+
+    def resolve(username: nil, password: nil)
+      if present?(username) && present?(password)
+        return Resolved.new(username: username, password: password, source: :explicit)
+      end
+
+      if present?(@env['PANDORA_USERNAME']) && present?(@env['PANDORA_PASSWORD'])
+        return Resolved.new(username: @env['PANDORA_USERNAME'],
+                            password: @env['PANDORA_PASSWORD'], source: :env)
+      end
+
+      if @secret_store && (creds = @secret_store.fetch)
+        return Resolved.new(username: creds[0], password: creds[1], source: :secret_store)
+      end
+
+      candidate_files.each do |path|
+        next unless File.file?(path)
+        creds = parse_file(path)
+        next unless creds
+        return Resolved.new(username: creds[0], password: creds[1], source: path)
+      end
+
+      raise NotFound, not_found_message
+    end
+
+    # Ordered list of JSON credential paths to try.
+    def candidate_files
+      paths = []
+      paths << @env['PANDORU_CREDENTIALS'] if present?(@env['PANDORU_CREDENTIALS'])
+      paths << File.join(xdg_config_home, 'pandoru', 'credentials.json')
+      paths.uniq
+    end
+
+    private
+
+    def xdg_config_home
+      present?(@env['XDG_CONFIG_HOME']) ? @env['XDG_CONFIG_HOME'] : File.join(@home, '.config')
+    end
+
+    # Returns [username, password] from a JSON file, or nil if unreadable or
+    # incomplete (so resolution continues to the next candidate).
+    def parse_file(path)
+      data = JSON.parse(File.read(path))
+      return nil unless data.is_a?(Hash)
+
+      username = USERNAME_KEYS.map { |k| data[k] }.find { |v| present?(v) }
+      password = PASSWORD_KEYS.map { |k| data[k] }.find { |v| present?(v) }
+      present?(username) && present?(password) ? [username, password] : nil
+    rescue JSON::ParserError
+      nil
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+
+    def not_found_message
+      checked = ['PANDORA_USERNAME / PANDORA_PASSWORD (env)', 'OS secret store (run pandoru-login)'] + candidate_files
+      <<~MSG.strip
+        No Pandora credentials found. Checked, in order:
+        #{checked.map { |c| "  - #{c}" }.join("\n")}
+        Store them with `pandoru-login`, provide a JSON file like
+        { "username": "you@example.com", "password": "…" }, or set the
+        PANDORA_USERNAME / PANDORA_PASSWORD environment variables.
+      MSG
+    end
+  end
+end

data/lib/pandoru/secret_store.rb

@@ -0,0 +1,173 @@
+require 'open3'
+require 'json'
+
+module Pandoru
+  # Portable secret storage: keeps the Pandora credential out of any plaintext
+  # file by delegating to the host OS's native secret service. There's no solid
+  # cross-platform Ruby gem for this, so we shell out to each platform's tool,
+  # the way fastlane et al. do:
+  #
+  #   macOS   → security        (Keychain)
+  #   Linux   → secret-tool      (libsecret / Secret Service: GNOME Keyring, KWallet)
+  #   Windows → Credential Manager (not yet wired — see Adapters::Windows)
+  #
+  # The credential is stored as a single JSON blob { "username", "password" }
+  # under one fixed key, so retrieval is uniform across backends and we never
+  # need to enumerate the store to discover the username. Everything degrades
+  # gracefully: with no working backend, fetch returns nil and the resolver
+  # falls through to the config file.
+  module SecretStore
+    SERVICE = 'pandoru'
+
+    # Shells out, returning [stdout, success?]. Injectable so adapters can be
+    # unit-tested without touching a real keychain.
+    DEFAULT_RUNNER = lambda do |cmd, stdin_data|
+      opts = { err: File::NULL }
+      opts[:stdin_data] = stdin_data if stdin_data
+      out, status = Open3.capture2(*cmd, **opts)
+      [out, status.success?]
+    rescue Errno::ENOENT
+      ['', false]
+    end
+
+    module_function
+
+    # The first available adapter for this host, or a Null adapter.
+    def adapter(runner: DEFAULT_RUNNER)
+      [Adapters::MacOS, Adapters::SecretTool, Adapters::Windows]
+        .map { |klass| klass.new(runner: runner) }
+        .find(&:available?) || Adapters::Null.new(runner: runner)
+    end
+
+    def available?(adapter: adapter())
+      !adapter.is_a?(Adapters::Null)
+    end
+
+    def backend_name(adapter: adapter())
+      adapter.name
+    end
+
+    # [username, password] from the store, or nil if absent/unreadable.
+    def fetch(service: SERVICE, adapter: adapter())
+      raw = adapter.read(service)
+      return nil if raw.nil? || raw.strip.empty?
+
+      data = JSON.parse(raw)
+      username = data['username']
+      password = data['password']
+      return nil unless present?(username) && present?(password)
+
+      [username, password]
+    rescue JSON::ParserError
+      nil
+    end
+
+    def store(username, password, service: SERVICE, adapter: adapter())
+      adapter.write(service, JSON.generate('username' => username, 'password' => password))
+    end
+
+    def delete(service: SERVICE, adapter: adapter())
+      adapter.delete(service)
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+
+    # Per-OS adapters. Each maps the generic read/write/delete of an opaque
+    # secret string to the native CLI; all I/O goes through the injected runner.
+    module Adapters
+      class Base
+        def initialize(runner: DEFAULT_RUNNER)
+          @runner = runner
+        end
+
+        def name = self.class.name.split('::').last
+
+        private
+
+        def run(cmd, stdin_data: nil)
+          @runner.call(cmd, stdin_data)
+        end
+
+        def which?(tool)
+          _out, ok = run(['which', tool])
+          ok
+        end
+      end
+
+      # macOS Keychain via `security`. Account is fixed to the service name; the
+      # secret blob is the password slot.
+      class MacOS < Base
+        def name = 'macOS Keychain'
+
+        def available?
+          RUBY_PLATFORM.include?('darwin') && which?('security')
+        end
+
+        def read(service)
+          out, ok = run(['security', 'find-generic-password', '-s', service, '-w'])
+          ok ? out.chomp : nil
+        end
+
+        def write(service, secret)
+          _out, ok = run(['security', 'add-generic-password', '-U',
+                          '-s', service, '-a', service, '-w', secret,
+                          '-D', 'application password', '-l', service])
+          ok
+        end
+
+        def delete(service)
+          _out, ok = run(['security', 'delete-generic-password', '-s', service])
+          ok
+        end
+      end
+
+      # Linux libsecret via `secret-tool` (Secret Service: GNOME Keyring/KWallet).
+      class SecretTool < Base
+        def name = 'libsecret (secret-tool)'
+
+        def available?
+          RUBY_PLATFORM.include?('linux') && which?('secret-tool')
+        end
+
+        def read(service)
+          out, ok = run(['secret-tool', 'lookup', 'service', service])
+          ok ? out.chomp : nil
+        end
+
+        def write(service, secret)
+          _out, ok = run(['secret-tool', 'store', '--label', service, 'service', service],
+                         stdin_data: secret)
+          ok
+        end
+
+        def delete(service)
+          _out, ok = run(['secret-tool', 'clear', 'service', service])
+          ok
+        end
+      end
+
+      # Windows Credential Manager. Left unwired: doing it without a gem means a
+      # PowerShell + Win32 CredRead/CredWrite P/Invoke shim, which can't be
+      # verified here. Reports unavailable so Windows falls back to the config
+      # file. Implement read/write/delete against `cmdkey`/PowerShell to enable.
+      class Windows < Base
+        def name = 'Windows Credential Manager (unsupported)'
+        def available? = false
+        def read(_service) = nil
+        def write(_service, _secret) = false
+        def delete(_service) = false
+      end
+
+      # No native store available — everything no-ops, resolver uses the file.
+      class Null < Base
+        def name = 'none'
+        def available? = false
+        def read(_service) = nil
+        def write(_service, _secret) = false
+        def delete(_service) = false
+      end
+    end
+  end
+end

data/lib/pandoru/version.rb

@@ -1,3 +1,3 @@
 module Pandoru
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/pandoru.rb

@@ -4,6 +4,8 @@ require_relative 'pandoru/transport'
 require_relative 'pandoru/client'
 require_relative 'pandoru/client_builder'
 require_relative 'pandoru/models'
+require_relative 'pandoru/secret_store'
+require_relative 'pandoru/credentials'
 require 'pathname'
 require 'logger'
 

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: pandoru
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Dale Stevens
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -195,16 +195,19 @@ description: A comprehensive Ruby client for the Pandora music streaming API, pr
   access to stations, playlists, search, and user management features.
 email:
 - dale@twilightcoders.net
-executables: []
+executables:
+- pandoru-login
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- exe/pandoru-login
 - lib/pandoru.rb
 - lib/pandoru/client.rb
 - lib/pandoru/client_builder.rb
+- lib/pandoru/credentials.rb
 - lib/pandoru/errors.rb
 - lib/pandoru/models.rb
 - lib/pandoru/models/_base.rb
@@ -213,6 +216,7 @@ files:
 - lib/pandoru/models/search.rb
 - lib/pandoru/models/station.rb
 - lib/pandoru/models/track_explanation.rb
+- lib/pandoru/secret_store.rb
 - lib/pandoru/transport.rb
 - lib/pandoru/version.rb
 homepage: https://github.com/TwilightCoders/pandoru