gitgolem 0.1.1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+--title 'Golem API Documentation'

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "yard", "~> 0.6.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+  gem "bluecloth"
+  gem "test-unit", "~> 1" #works both for 1.8 and 1.9, backward compatible
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 PoTa
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,190 @@
+# Golem
+
+Golem provides an easy way to host and manage access to git repositories on a server under a single user.
+
+## Gem and library name
+
+The library name is `Golem`, but the gem is called `gitgolem`.
+After installing you could require either 'golem' or 'gitgolem'.
+
+## How it works
+
+Golem's main goals are:
+
+* host git repositories under a single user,
+* manage access to repositories on a per-user basis,
+* store users and keys in a database,
+* to be simple as possible, but still extendable.
+
+Golem is not designed to handle complex access rules, altough it may be extended to achieve that. If you need more refined rules, like per-branch or per-path control
+you should check out {https://github.com/sitaramc/gitolite gitolite}, which has far superior features in this regard.
+
+The git flow that golem supports is:
+
+* you have a specific shell user that "hosts" golem,
+* golem places your users ssh keys in this (shell) user's home directory (_~/.ssh/authorized\_keys_),
+* your users use a git remote like _golem\_host\_user@your\_server:repository.git_,
+* when a user git pushes/pulls, his git connects via ssh, sshd invokes golem's authorization command (via the _authorized\_keys_ file),
+* golem authorizes the user for the given repository and invokes _git-shell_ if access granted.
+
+## Configuration
+
+Golem supports the following configuration variables:
+
+* `db`: the database to use, currently postgres ('postgres://...') and static ('static') supported,
+* `user_home`: the directory where the .ssh/authorized_keys file should be written, defaults to `HOME` environment variable,
+* `repository_dir`: path to the git repositories, may be relative to `user_home`,
+* `cfg_path`: path to config file, if not set searched for as (in this order):
+  * `GOLEM_CONFIG` environment variable (if set),
+  * 'golem.conf.rb' relative to `GOLEM_BASE` environment variable (if set),
+  * /usr/local/etc/golem/golem.conf.rb,
+  * /usr/local/etc/golem.conf.rb,
+  * /etc/golem/golem.conf.rb,
+  * /etc/golem.conf.rb,
+  * ~/golem.conf.rb,
+  * if found it is required (e.g. loaded), otherwise set to `base_dir + "/golem.conf.rb"` after configuration,
+* `base_dir`: convenience feature, may be used to store installation, if not explicitly set defaults to:
+  * `GOLEM_BASE` environment variable (if set),
+  * basedir of `cfg_path` if file exists,
+  * basedir of the library itself (e.g. the gem path),
+* `bin_dir`: where the executable is installed, defaults to `base_dir + "/bin"`,
+* `hooks_dir`: where the hooks are installed, defaults to `base_dir + "/hooks"`,
+* `keys_file_use_command`: controls how to use `.ssh/authorized_keys` (_environment=""_ or _command=""_), see {file:README#keys_file authorized\_keys},
+* `keys_file_ssh_opts`: ssh options to place in `.ssh/authorized_keys`, see {file:README#keys_file authorized\_keys}.
+
+<a name="keys_file"></a>
+## Git and .ssh/authorized_keys
+
+Git supports SSH as the transport protocol for pulling and pushing, and assumes SSH for remotes like _user@server:/path/to/project.git_. With ssh remotes git executes remote commands, like
+`git-receive-pack '/path/to/project.git'` (this is stored in `SSH_ORIGINAL_COMMAND` environment variable for the curious) when doing something like `git clone user@server:/path/to/project.git`.
+Golem authorizes users so it must act before the actual git command runs. Key-based authentication is very popular and the `.ssh/authorized_keys` file allows a few possibilities to achieve what
+golem tries to do, so it seems a natural fit. **Please note:** golem won't work without key-based authentication, as it relies content placed in the `.ssh/authorized_keys` file.
+
+Golem by default requires that you (control your SSHD's options and) set the users shell to `golem-shell` (wherever it is installed) that is "hosting" the repositories. With that setup golem can
+simply place lines like `environment="GOLEM_USER=username" ssh-dss AAA...` (where `AAA...` is the key) in the `.ssh/authorized_keys` file and `golem-shell` simply reads that environment
+variable. (**Please note:** SSHD by default does not permit changing environment variables, you have to enable it with setting `PermitUserEnvironment` to `yes`.) However this needs
+that the user's shell is set to `golem-shell`, so golem provides a configuration variable, if you can't or simply don't want to change the user's shell. When `keys_file_use_command` is true golem
+writes lines like `command="/path/to/golem auth 'username'" ssh-dss AAA...` instead. **Please note:**
+
+Golem supports another configuration variable called `keys_file_ssh_opts`, which is simply placed after the _environment=""_ or _command=""_ block. If `keys_file_use_command` is false (using
+_environment=""_) golem simply injects the string into the lines, however if `keys_file_use_command` is true and `keys_file_ssh_opts` is not set (is `nil`) golem uses
+{Golem::Command::UpdateKeysFile::SSH\_OPTS\_COMMAND\_DEFAULT} (if it is not `nil` golem uses the configuration value). The reasoning behind this distinction is golem assumes you control
+your SSHD's settings if using _environment=""_, but you may not (want to) set (global) restrictions when using _command=""_. The final line looks something like
+`environment="GOLEM_USER=username",ssh,opts ssh-dss AAA...` or `command="/path/to/golem auth 'username'",ssh,opts ssh-dss AAA...`.
+
+**Please note:** golem does not overwrite the whole `.ssh/authorized_keys` file.
+
+## Access control
+
+Golem's access control by default is very simple. It assumes a repository belongs to a single user, so it grants access to a given repository only to its owner.
+For a very basic setup this should be enough. However for more complex setup golem does not want to assume how you want to store your users and repositories, so
+it simply doesn't. You can fine tune your environment to suit your specific needs with overriding {Golem::Access.check} (its arguments are the username, the repository
+name and the git command to run (e.g. one of upload-pack, upload-archive and receive-pack)).
+
+Golem's access control is done at the very beginning, before git-shell is run, so it's not suitable for per-branch or per-directory control. This can be achieved by hooks.
+You should check out {https://github.com/sitaramc/gitolite gitolite}, which supports exactly that (and more). If you want you can place
+{https://github.com/sitaramc/gitolite gitolite}'s hooks in golem's `hooks_dir` and achieve the same results (this requires deeper understanding of git, so
+please be aware).
+
+## Public access
+
+Golem does not support providing public (read-only anonymous) access to git repositories as it relies on SSH's key-based authentication. However there are a couple of alternatives
+to solve this, with each having its pros and cons: {http://progit.org/book/ch4-5.html serving the repository as a static website}, {http://progit.org/book/ch4-6.html using GitWeb}
+or {http://progit.org/book/ch4-9.html using Git Daemon}.
+
+## Database
+
+Golem currently supports postgres and a static databases only, but it should be trivial to extend it (contributions are always welcome). At least users and repositories
+should have names, keys should have an attribute named `key` that is the whole key (e.g. cat id_rsa.pub).
+
+The {Golem::DB::Static static database} is suitable for small installations (where an rdbms would be an overkill), to use it simply write:
+
+    Golem.configure do |cfg|
+      cfg.db = 'static'
+      Golem::DB.setup do |db|
+        db.add_user 'test_user'
+        db.add_repository 'test_repository', 'test_user'
+        db.add_key 'test_user', 'test_key'
+      end
+    end
+
+The postgres database stores data in 3 tables (users, repositories, keys) by default, and can be used with setting the db variable to the postgres url (e.g. `postgres://user:pw@host/db`).
+A sample schema can be found in `lib/golem/db/postgres.sql`, and it is imported by {Golem::DB::Pg#setup} (please note: {Golem::DB.setup} forwards to it, should be called
+only once). A minimal setup for postgres would be:
+
+    Golem.configure do |cfg|
+      cfg.db = "postgres://user:pwd@host/dbname"
+      cfg.bin_dir = "/usr/local/bin"
+    end
+
+A more complex setup with collaborators:
+
+    Golem.configure do |cfg|
+      Golem::DB::Pg.class_eval do
+        #add method to query collaborators
+        def collaborators(opts = {})
+          opts[:table] = "collaborators join users on collaborators.user_name=users.name"
+          get(opts)
+        end
+
+        #add method to check if user is a collaborator of a given repository
+        def collaborator?(user, repo)
+          collaborators(:user_name => user, :repository_name => repo, :fields => :name).length > 0
+        end
+
+        #override setup to add our collaborators table
+        alias_method :setup_orig, :setup
+        def setup
+          setup_orig
+          @connection.exec("CREATE TABLE collaborators (user_name varchar(32) NOT NULL REFERENCES users (name), repository_name varchar(32) NOT NULL REFERENCES repositories (name), PRIMARY KEY (user_name, repository_name));")
+        end
+      end
+      Golem::DB.class_eval do
+        #add method proxy to check collaborator status
+        def self.collaborator?(user, repo)
+          db.collaborator?(user, repo)
+        end
+      end
+      Golem::Access.class_eval do
+        #override check to grant access to collaborators
+        class << self; alias_method :check_orig, :check end
+        def self.check(user, repo, gitcmd)
+          Golem::DB.collaborator?(user, repo) || check_orig(user, repo, gitcmd)
+        end
+      end
+      cfg.db = 'postgres://user:pwd@host/dbname'
+    end
+
+## Commands
+
+Golem provides an executable, and supports a few commands to easily automate the administration:
+
+* auth: is used for authorization by sshd,
+* clear\_repositories: clear old data (e.g. suitable for cron),
+* create\_repository: create a repository manually (new repositories are created automatically by golem on first access),
+* delete\_repository: delete a repository manually,
+* environment: list configuration variables,
+* save\_config: save configuration variables,
+* setup\_db: setup database schema (useful for postgres only),
+* update\_hooks: update hooks in every repository,
+* update\_keys\_file: update the .ssh/authorized_keys file.
+
+You can get details about commands running `golem -h` or `--help`.
+
+Golem provides another executable called `golem-shell`, which is a convenience script that calls `golem auth`.
+
+## Contributing to golem
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2011 PoTa. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+require './lib/golem/version.rb'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "gitgolem"
+  gem.homepage = "http://github.com/eLod/golem"
+  gem.license = "MIT"
+  gem.summary = %Q{Gem to host git repositories.}
+  gem.description = %Q{Golem provides an easy way to host and manage access to git repositories on a server under a single user.}
+  gem.email = "pota@mosfet.hu"
+  gem.authors = ["PoTa"]
+  gem.version = Golem::Version::STRING
+  gem.executables = ["golem", "golem-shell"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/TODO

@@ -0,0 +1,24 @@
+-conf file placement (move to /etc/_golem_/golem.conf.rb)
+-conf file bug, does not find by /etc/golem.conf.rb
+
+
+-auth command add separately
+-auth command use GOLEM_USER env
+-auth command fix fixed 'repositories/' path
+-update-keys command add option to use ENV, what should be the default? - ENV should be default, but add doc to use 'orig' setup
+-update-keys command make SSH_OPTS configurable
+-update-keys command auth_cmd bug with '-' inside -- INVALID
+
+
+-add read/write? method (e.g. gitcmd) for convenience in Golem::Access
+
+
+-add command for db.setup
+-add env shortcut for environment (and look for others)
+
+
+-make git commands no output (is sent back, e.g. "Initialized empty Git repository in /home/git/repositories/golem.git/")
+
+
+-add docs about anon read (web + git:// with git daemon)
+-add complex example to readme (e.g. with .access overriden and with extra schema [collaborators, admins]) - flip order of db and access @ readme

data/bin/golem

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'golem'
+Golem::Parser.run(ARGV)

data/bin/golem-shell

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'golem'
+ENV['SSH_ORIGINAL_COMMAND'] = ARGV[1] if ARGV.length == 2 && ARGV.first == "-c"
+Golem::Parser.run(["auth"])

data/lib/gitgolem.rb

@@ -0,0 +1 @@
+require 'golem'

data/lib/golem.rb

@@ -0,0 +1,21 @@
+# Golem provides an easy way to host and manage access to git repositories on a server under a single user. More details can be found:
+# * for configuration at {Golem::Config},
+# * for database handling at {Golem::DB},
+# * for access control at {Golem::Access},
+# * for commands at {Golem::Command},
+# * for general help at {file:README}.
+module Golem
+    autoload :Access, "golem/access"
+    autoload :Command, "golem/command"
+    autoload :Config, "golem/config"
+    autoload :DB, "golem/db"
+    autoload :Parser, "golem/parser"
+    autoload :Version, "golem/version"
+
+    # Configure Golem.
+    # @see Golem::Config.configure
+    def self.configure(opts_or_path = nil, &block)
+	Config.configure(opts_or_path, &block)
+	self
+    end
+end

data/lib/golem/access.rb

@@ -0,0 +1,45 @@
+# Access control, implements basic control, may be overriden (see {check}).
+module Golem::Access
+    # Main access control, checks if user is the owner of the repository. When overriden +gitcmd+ may be used to determine R/W access.
+    # @param [String] user username,
+    # @param [String] repo repository name,
+    # @param [String] gitcmd git command (one of +upload-pack+, +upload-archive+, +receive-pack+).
+    # @return [Boolean] result.
+    def self.check(user, repo, gitcmd)
+	Golem::DB.repositories(:user_name => user, :name => repo, :fields => :name).length > 0
+    end
+
+    # @return [Array] list of usernames.
+    def self.users
+	Golem::DB.users(:fields => :name, :return => :array)
+    end
+
+    # @return [Hash] username => [array of keystrings] pairs.
+    def self.ssh_keys
+	Golem::DB.ssh_keys(:fields => [:name, :key], :return => :array).inject({}) do |memo, (user, key)|
+	    if memo.key?(user)
+		memo[user] << key
+	    else
+		memo[user] = [key]
+	    end
+	    memo
+	end
+    end
+
+    # @return [Array] list of repository names.
+    def self.repositories
+	Golem::DB.repositories(:fields => :name, :return => :array)
+    end
+
+    # Convenience method to check if requested access type is read (e.g. command was +receive-pack+).
+    # @return [Boolean] if read access was requested.
+    def self.read?(gitcmd)
+	gitcmd == "receive-pack"
+    end
+
+    # Convenience method to check if requested access type is write (e.g. command was +upload-pack+ or +upload-archive+).
+    # @return [Boolean] if write access was requested.
+    def self.write?(gitcmd)
+	!!gitcmd.match(/\Aupload-(pack|archive)\z/)
+    end
+end

data/lib/golem/command.rb

@@ -0,0 +1,107 @@
+# Namespace for commands.
+module Golem::Command
+    # List of command names as symbols.
+    COMMANDS = [:auth, :clear_repositories, :create_repository, :delete_repository, :environment, :save_config, :setup_db, :update_hooks, :update_keys_file]
+    # Hash of aliases.
+    ALIASES = {
+	:clear_repositories => ["clear-repositories", "clear-repos", "clear_repos"],
+	:create_repository => ["create-repository", "create-repo", "create_repo"],
+	:delete_repository => ["delete-repository", "delete-repo", "delete_repo"],
+	:environment => ["env"],
+	:save_config => ["save-config", "save"],
+	:setup_db => ["setup-db", "setup"],
+	:update_hooks => ["update-hooks"],
+	:update_keys_file => ["update-keys-file", "update-keys", "update_keys"],
+    }
+
+    autoload :Auth, "golem/command/auth"
+    autoload :ClearRepositories, "golem/command/clear_repositories"
+    autoload :CreateRepository, "golem/command/create_repository"
+    autoload :DeleteRepository, "golem/command/delete_repository"
+    autoload :Environment, "golem/command/environment"
+    autoload :SaveConfig, "golem/command/save_config"
+    autoload :SetupDb, "golem/command/setup_db"
+    autoload :UpdateHooks, "golem/command/update_hooks"
+    autoload :UpdateKeysFile, "golem/command/update_keys_file"
+
+    # Run a command.
+    # @param [Symbol, String] cmd command name to run,
+    # @param [Hash] opts options, see {Base#initialize},
+    # @param *args arguments for the command.
+    def self.run(cmd, opts = {:verbose => true}, *args)
+	find(cmd).new(opts).run(*args)
+    end
+
+    # Get command usage to display in help message.
+    # @param [Symbol, String] cmd command name.
+    # @return [String] usage text or empty string.
+    def self.usage(cmd)
+	cmd = find(cmd)
+	cmd.const_defined?(:USAGE) ? cmd::USAGE : ""
+    end
+
+    # Find command class by name.
+    # @raise [NameError] if class (constant) not found.
+    # @param [Symbol, String] cmd command name to search for.
+    # @return [Class] command class.
+    def self.find(cmd)
+	cmd = ALIASES.find {|key, a| a.include?(cmd.to_s)}.first if ALIASES.any? {|key, aliases| aliases.include?(cmd.to_s)}
+	abort "Command not understood." unless COMMANDS.include?(cmd.to_sym)
+	const_get cmd.to_s.split("_").collect {|p| p.capitalize}.join.to_sym
+    end
+
+    # Abstract class for commands.
+    # @abstract Subclass and override {#run} to implement a custom Command class.
+    class Base
+	# @param [Hash] opts options
+	# @option opts [Boolean] :verbose control verbosity.
+	def initialize(opts)
+	    @opts = opts
+	end
+
+	# Check verbosity.
+	def verbose?
+	    !!@opts[:verbose]
+	end
+
+	# Run the command.
+	def run
+	    abort "Bad command."
+	end
+
+	# Run another command.
+	# @param [Symbol] cmd the command to run,
+	# @param *args arguments for the command.
+	def command(cmd, *args)
+	    Golem::Command.run(cmd, @opts, *args)
+	end
+    end
+
+    # Mixin for hook management.
+    module ManageHooks
+	# Install hooks into repository.
+	# @param [String] repo repository name.
+	def install_hooks(repo)
+	    path = Golem::Config.repository_path(repo)
+	    Dir.entries(Golem::Config.hooks_dir).each do |hook|
+		hook_src = Golem::Config.hook_path(hook)
+		next unless File.file?(hook_src) && File.stat(hook_src).executable? && hook[0..0] != "."
+		File.symlink(hook_src, path + '/hooks/' + hook)
+		print "Hook installed from #{hook_src} to #{path}/hooks/#{hook}.\n" if verbose?
+	    end if File.directory?(Golem::Config.hooks_dir)
+	end
+
+	# Remove hooks from repository (please note: this *deletes* old hooks).
+	# @param [String] repo repository name.
+	def clear_hooks(repo)
+	    path = Golem::Config.repository_path(repo)
+	    Dir.entries(path + "/hooks").each do |hook|
+		hook_src = path + "/hooks/" + hook
+		File.delete(hook_src) if File.symlink?(hook_src) && ! File.file?(hook_src)
+		next unless File.file?(hook_src) && File.stat(hook_src).executable? && hook[0..0] != "."
+		File.delete(hook_src)
+		print "Hook removed from #{hook_src}.\n" if verbose?
+	    end
+	end
+    end
+end