#! /usr/bin/perl
# Copyright (C) 2013, 2014 Sergey Poznyakoff <gray@gnu.org>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

use strict;
use GitACL;
use Pod::Man;
use Pod::Usage;
use Getopt::Long qw(:config gnu_getopt no_ignore_case);
    
=head1 NAME

gitaclhook - control access to git repositories

=head1 SYNOPSIS

B<gitaclhook> I<refname> I<old-sha1> I<new-sha1>

B<gitacthook> [B<--debug>] B<--test> I<REPO> I<USER> I<OP> I<REF>
    
B<gitaclhook --help>     

=head1 DESCRIPTION
    
This program is intended to be run as an "update" hook by git.
It is called by B<git-receive-pack> with arguments:
I<refname> I<old-sha1> I<new-sha1>.

The program reads access control lists from the storage engine
specified in the repository's config file and allows or denies
the update depending on their settings.  If no storage engine is
defined update is allowed unconditionally.  If it is defined, but
is not available (e.g. the disk file does not exist or the LDAP
server cannot be reached, the update is denied.

Two storage engines are supported: B<File>, which reads access control
lists from a disk file, and B<LDAP>, which obtains them from LDAP.
The engine to use is defined by the B<hooks.acl.type> configuration keyword.    
The default is B<File>.    
    
=head1 ACL FILE

The ACL file is used when the B<File> storage engine is requested.  The
path to the file must be given via the B<hooks.acl.file> configuration
keyword.  If B<hooks.acl.file> is not defined, update is allowed
unconditionally.
    
The ACL file has the usual line-oriented syntax.  Comments are introduced
by the # sign and extend to the end of the physical line.  Comments and
empty lines are ignored.

Non-empty lines introduce ACL rules.  The syntax is:

=over 4
    
I<VERB> I<PROJECT> I<USER> [I<OP> I<REF>]

=back

where brackets denote optional parts.  The parts of an ACL are:

=over 4

=item I<VERB>

Either B<allow> or B<deny>, to allow or deny the operation, correspondingly.

=item I<PROJECT>

The name of the project.  It is obtained by removing the directory
and suffix parts of the repository pathname.  Thus, if the repository
is located in B</var/gitroot/foobar.git>, then the corresponding name of
the project is B<foobar>.

An asterisk matches any project name.

=item I<USER>[B<@>I<CIDRLIST>]

Name of the user.  The word B<all> stands for any user, the word B<none>
matches no one at all.  Otherwise, if this part begins with a percent
sign (B<%>), the rest of characters are treated as the name of the UNIX
group to check and the rule matches any user in that group.  Otherwise,
the literal match is assumed.

The I<CIDRLIST> part, if present, restricts the rule to users coming from
IP addresses that match one of the elements in the list.  I<CIDRLIST> is a
comma-separated list of IP addresses, ranges or CIDRs.  An IP range is
defined as two IP addresses separated by a minus sign.  A CIDR is defined as
network address, followed by a slash and length of the netmask in decimal.
For example:

     gray@10.0.0.0/16,192.168.1.0-192.168.10.255
    
=back

The optional parts are:

=over 4

=item I<OP>

Requested operation codes.  It is a string consisting of one or more
of the following letters (case-insensitive):

=over 8

=item B<C>

Create new ref.

=item B<D>

Delete existing ref.

=item B<U>

Fast-forward existing ref (no commit loss).

=item B<R>

Rewind or rebase existing ref (commit loss).

=back    
    
=item I<REF>

Affected ref, relative to the git B<refs/> directory.  If it begins with
a caret (B<^>), it is treated as a Perl regular expression (with the B<^>
being its part).  If it ends with a B</>, it is treated as a prefix match,
so, e.g., B<heads/baz/> matches B<refs/heads/baz> and anything below.
Otherwise, it must match exactly the affected ref.

=back

=head1 RULE MATCHING
    
The rule applies only if its I<PROJECT> and I<USER> parts match the project
which is being updated and the user who requests the update, its I<OP>
contains the opcode of the requested operation and I<REF> matches the affected
ref.  Missing I<REF> and/or I<OP> are treated as a match.

If no rule applies, the operation is denied.  This can be changed by setting
B<hooks.acl.default = allow> in Git configuration file.

For example, assume you have the following ACL file:

    allow myprog %devel   U    heads/master
    allow myprog %pm      CDUR heads/
    allow myprog %pm      C    ^heads/tags/v\\d+$
    allow myprog admin    CDUR
    deny myprog all

Then the users from the B<devel> group will be able to push updates to
B<refs/heads/master>, the users from the B<pm> group will be allowed to do
anything with refs under B<refs/heads> and to create tags with names beginning
with B<v> and containing only digits afterwards, and the user B<admin> will
be allowed to do anything he pleases.  No other users will be allowed to
update that repository.

=head1 LDAP

The LDAP storage engine is requested by the following configuration statement:

    [hooks]
            acltype = LDAP

The URI of the LDAP server to use and other data necessary to access it
are read from the file name given in the B<hooks.acl.ldapconf> variable,
or from B</etc/ldap.conf>, if it is not defined.  LDAP access control
entries are similar to the plaintext file ACLs.  Each entry has the
following attrubutes:

=over 4

=item B<gitAclProject>    [mandatory]

The project this entry applies to.
    
=item B<gitAclVerb>       [mandatory]

The control verb.
    
=item B<gitAclUser>       [optional]

The user name specification (see description in the B<ACL FILE> section).
    
=item B<gitAclOp>         [optional]

The list of operation codes.
    
=item B<gitAclRef>        [optional]

Git ref.
    
=item B<gitAclOrder>      [optional]

Sorting order (see below).
    
=back    

The program first reads all entries with the B<gitAclProject> attribute
matching the requested project name.  The obtained entries are sorted
by the value of B<gitAclOrder> attribute.  Entries without this attributes
are assumed to have sorting order B<0>.  Entries with the project name
B<all> are sorted last.  Entries with the same sorting order are sorted
by the count of attributes they carry (in the reverse order).  Thus, the
most specific entries precede the least specific entries in the resulting
list.

Each list entry is then matched against the current tuple (I<PROJECT>, I<USER>,
I<OP>, I<REF>), much the same way as described in B<RULE MATCHING>.  Missing
attributes always match.  The special B<gitAclProject> value B<all> matches
all project names.    

If no matching entry is found, the update is allowed.
    
=head1 CONFIGURATION SETTINGS

=over 4

=item B<hooks.acl.type>    I<STRING>

Type of the storage engine.  Valid values are B<File> (default) and B<LDAP>.
    
=item B<hooks.acl.file>    I<STRING>

For the B<File> storage engine, name of the ACL file.

=item B<hooks.acl.ldapconf> I<STRING>

For the B<LDAP> storage engine, the name of the configuration file to use
instead of B</etc/ldap.conf>.    

=item B<hooks.acl.log>     I<STRING>

Send log info to this file.

=item B<hooks.acl.debug>   I<NUMBER>

Enable debugging.  The bigger the number, the more debugging info will
be displayed.    

=item B<hooks.acl.quiet>   I<BOOL>

Suppress diagnostics on stderr.

=item B<hooks.acl.default> B<allow>|B<deny>

Sets the default rule, i.e. the one that will be executed if no other
rule matched the request.  Unless defined, B<deny> is assumed.
    
=item B<hooks.acl.httpd-user> I<STRING>

Name of the user httpd runs as.  Define it if the repository can be
accessed via HTTP(S).  If B<gitaclhook> is run as this user, it will
get the name of the user on behalf of which the update is performed
from the environment variable B<REMOTE_USER>.

=item B<hooks.acl.ip-env-var> I<STRING>

Name of the environment variable from where to retrieve remote IP address.
Default is B<REMOTE_ADDR>, if B<hooks.acl.httpd-user> is defined and current
user matches it, and B<SSH_CLIENT> otherwise.

The part of the string up to the first space character (if any) is taken as
the IP address.    
    
=back

=head1 TEST MODE

The B<--test> (B<-t>) option provides a mechanism for testing access control
lists from the command line.  The syntax is:

=over 4

B<gitacthook> [B<--debug>] [B<-d>] B<--test> I<REPO> I<USER> I<OP> I<REF>

=back

I<REPO> is a pathname of the repository to test, I<USER> is the username,
I<OP> is the operation code and I<REF> is the reference.

Optional B<--debug> (B<-d>) options increment the debugging level.

=head1 ENVIRONMENT

The program uses following environment variables:

=over 4

=item B<GIT_UPDATE_DEBUG>

When set to 1, enables debugging mode.  The B<hooks.acl.debug>
configuration variable overrides this setting.
    
=item B<GIT_DIR>

Path to the affected repository.    

=back

If updates are performed via HTTP or HTTPS and the B<hooks.acl.httpd-user>
configuration variable is set, the following two variables are used
to determine the identity of the user:
    
=over 4    

=item B<AUTH_TYPE>

If this variable is not set or set to an empty value, the program will
deny the update.    
    
=item B<REMOTE_USER>

The authenticated name of the user.
    
=back

=head1 SEE ALSO

B<git-receive-pack>(1).     
    
=head1 AUTHOR

Sergey Poznyakoff, <gray@gnu.org>    
    
=cut

my $script;
($script = $0) =~ s/.*\///;

sub abend($) {
    my $msg = shift;
    print STDERR "$script: $msg\n";
    exit 2;
}

my %args;

unless ($ENV{GIT_DIR}) {
    my $debug;
    my $test;
    GetOptions("help|h" => sub { pod2usage(-exitstatus => 0, -verbose => 2); },
	       "debug|d+" => \$debug,
	       "test|t" => \$test)
	or exit (3);
    if ($test) {
	abend("--test requires four arguments") unless ($#ARGV == 3);
	$args{git_dir} = $ENV{GIT_DIR} = $ARGV[0];
	$args{user} = $ARGV[1];
	$args{op} = $ARGV[2];
	$args{ref} = $ARGV[3];
	$args{old} = '0000000000000000000000000000000000000000';
	$args{new} = '0000000000000000000000000000000000000001';
	$args{debug} = $debug;
    } else {
	abend("try \"$script --help\" for fore info")
    }
} else {
    abend("bad number of arguments") unless ($#ARGV == 2);
    $args{git_dir} = $ENV{GIT_DIR};
    $args{ref} = $ARGV[0];
    $args{old} = $ARGV[1];
    $args{new} = $ARGV[2];
}

my $gitacl = GitACL->new(%args);
$gitacl->check;

exit 0;

# Finis