Author: dylan
Date: 2005-08-06 13:56:14 -0400 (Sat, 06 Aug 2005)
New Revision: 909
Added:
trunk/docs/spec/Build.PL
trunk/docs/spec/MANIFEST.SKIP
trunk/docs/spec/lib/
trunk/docs/spec/lib/Haver/
trunk/docs/spec/lib/Haver/Spec.pod
trunk/docs/spec/lib/Haver/Spec/
trunk/docs/spec/lib/Haver/Spec/Auth.pod
trunk/docs/spec/lib/Haver/Spec/Reg.pod
Removed:
trunk/docs/spec/Haver/
Modified:
trunk/
trunk/perl/server/lib/Haver/Server.pm
trunk/web/Makefile
Log:
[EMAIL PROTECTED]: dylan | 2005-08-06 10:56:48 -0400
Fixed docs.
[EMAIL PROTECTED]: dylan | 2005-08-06 13:54:12 -0400
docs is a phoney target.
[EMAIL PROTECTED]: dylan | 2005-08-06 13:54:57 -0400
Renaming for CPAN-disting.
[EMAIL PROTECTED]: dylan | 2005-08-06 13:55:08 -0400
libdoc -> lib, oops.
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/havercurs-objc:43089
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk:11166
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk-merge-10131:11178
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/winch/trunk:43192
27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212
e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:1352
edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238
+ 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/havercurs-objc:43089
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk:11166
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk-merge-10131:11178
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/winch/trunk:43192
27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212
e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:1357
edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238
Added: trunk/docs/spec/Build.PL
===================================================================
--- trunk/docs/spec/Build.PL 2005-08-06 05:14:10 UTC (rev 908)
+++ trunk/docs/spec/Build.PL 2005-08-06 17:56:14 UTC (rev 909)
@@ -0,0 +1,14 @@
+#!/usr/bin/perl
+require 5.008;
+use Module::Build;
+my $build = Module::Build->new(
+ module_name => 'Haver::Spec',
+ dist_version => '0.08',
+ dist_author => 'Dylan Hardison <[EMAIL PROTECTED]>',
+ license => 'gpl',
+ requires => { },
+ create_makefile_pl => 'passthrough',
+ # XXX: This is a hack, feel free to remove it...
+ ($ENV{USER} eq 'dylan') ? (sign => 1) : (),
+);
+$build->create_build_script();
Property changes on: trunk/docs/spec/Build.PL
___________________________________________________________________
Name: svn:executable
+ *
Added: trunk/docs/spec/MANIFEST.SKIP
===================================================================
--- trunk/docs/spec/MANIFEST.SKIP 2005-08-06 05:14:10 UTC (rev 908)
+++ trunk/docs/spec/MANIFEST.SKIP 2005-08-06 17:56:14 UTC (rev 909)
@@ -0,0 +1,25 @@
+# Avoid version control files.
+\bRCS\b
+\bCVS\b
+,v$
+\B\.svn\b
+
+# Avoid Makemaker generated and utility files.
+\bMakefile$
+\bblib
+\bMakeMaker-\d
+\bpm_to_blib$
+\bblibdirs$
+^MANIFEST\.SKIP$
+
+# Avoid Module::Build generated and utility files.
+\bBuild$
+\b_build
+
+# Avoid temp and backup files.
+~$
+\.tmp$
+\.old$
+\.bak$
+\#$
+\b\.#
Added: trunk/docs/spec/lib/Haver/Spec/Auth.pod
===================================================================
--- trunk/docs/spec/lib/Haver/Spec/Auth.pod 2005-08-06 05:14:10 UTC (rev
908)
+++ trunk/docs/spec/lib/Haver/Spec/Auth.pod 2005-08-06 17:56:14 UTC (rev
909)
@@ -0,0 +1,130 @@
+=head1 NAME
+
+Haver::Spec::Auth - The authentication extension.
+
+=head1 DESCRIPTION
+
+This document describes the authentication extension to L<Haver::Spec>.
+
+=head1 BEGIN YOUR FEAR
+
+The auth extension provides a login authentication system.
+A related extension, L<Haver::Spec::Reg> provides a way of registering under
this auth
+system.
+
+The client must advertize it understands the auth extension. It does this by
mentioning
+'auth' in the second arg of C:HAVER, like so:
+
+ C: HAVER CoolClient/1.10 auth
+
+If the client does not advertize, the server will assume it does not
understand any AUTH:
+commands. If the client requests a name that is registered and does not
advertize it
+supports auth, the server will fail it with B<auth.impossible>.
+Otherwise:
+
+ C: IDENT vadim
+ S: AUTH:TYPES AUTH:BASIC GPG:AUTH
+ C: AUTH:TYPE AUTH:BASIC
+ S: AUTH:BASIC $nonce sha1 md5
+ C: AUTH:BASIC $digest $response
+
+If the authentication is successful, the server will send HELLO as per normal.
+If not, the server will fail the client with B<auth.fail>.
+
+$digest is one of the parameters after the first parameter of S:AUTH:BASIC.
+$response is the result of hashing the concatenation of $nonce and the user's
passcode
+using the hash function named in $digest. The $response is always base64
encoded.
+
+See also L</PASSCODES> for instructions on creating a passcode.
+
+Thus, $response can be generated with the following perl function:
+
+ use Digest::MD5 'md5_base64';
+ use Digest::SHA1 'sha1_base64';
+
+ sub response {
+ my ($digest, $nonce, $passcode) = @_;
+ if ($digest eq 'sha1') {
+ return sha1_base64($nonce . $passcode);
+ } elsif ($digest eq 'md5') {
+ return md5_base64($nonce . $passcode);
+ }
+ }
+
+
+=head1 YOU FAIL
+
+This extension introduces a few new errors.
+
+=head2 auth.impossible
+
+Raised when the client does not understand the auth extension. Always
associated with
+IDENT.
+
+=head2 auth.fail
+
+Raised when authentication did not work because the passcode or whatever was
wrong.
+This happens when the client understands authentication and after AUTH:*
commands have
+been sent.
+
+=head2 unknown.digest
+
+Raised when the hashing (digest) algorithm requested by the client is unknown
to the server.
+
+=head1 PASSCODES
+
+First, the problem: The server admin can't be trusted knowing the user's
password.
+They might use it else where, for example. So the first idea that comes to
mind is to hash
+it. Bingo, the server admin does not know the password now. But the server
admin knows the
+hash! So they can still login to other haver servers that the user has
accounts on.
+
+So, we hash the concatenation of the user's password and the hostname of the
server.
+Now the hash is specific to the server, the admin can't figure out the hash
for the user
+on other servers.
+
+But, the admin, being very evil, can find out what users have the same
password.
+To prevent this, we hash the user's password, the user's name, and the
hostname of the
+server.
+
+This is something the client does, of course. It is very important the clients
hash things
+in the same way. Thus all clients must use the sha1() hash function, and
base64 encode its
+results.
+
+Also, both the hostname and username need to be lower-cased, as both are case
insensitive.
+
+Thus, to generate passcodes in perl, the following function is used.
+
+ use Digest::SHA1 'sha1_base64';
+
+ sub passcode {
+ my ($user, $password, $host) = @_;
+ sha1_base64($password . lc("$host$user"));
+ }
+
+=head1 AUTHOR
+
+Dylan William Hardison, E<lt>[EMAIL PROTECTED]<gt>,
+with many thanks to muffin and bdonlan. Lots of ideas floated around, I just
cherry-picked
+them to create this scheme.
+
+=head1 SEE ALSO
+
+L<http://www.haverdev.org/>.
+
+=head1 COPYRIGHT and LICENSE
+
+Copyright (C) 2005 by Dylan William Hardison. All Rights Reserved.
+
+This module 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 2 of the License, or
+(at your option) any later version.
+
+This module 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 module; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Added: trunk/docs/spec/lib/Haver/Spec/Reg.pod
===================================================================
--- trunk/docs/spec/lib/Haver/Spec/Reg.pod 2005-08-06 05:14:10 UTC (rev
908)
+++ trunk/docs/spec/lib/Haver/Spec/Reg.pod 2005-08-06 17:56:14 UTC (rev
909)
@@ -0,0 +1,91 @@
+=head1 NAME
+
+Haver::Spec::Reg - The Registration extension
+
+=head1 DESCRIPTION
+
+This document describes the registration extension to L<Haver::Spec>.
+
+=head1 BEGIN YOUR FEAR
+
+This extension depends on the L<Haver::Spec::Auth> extension. In fact neither
is very
+useful without the other.
+
+=head2 Creating an account
+
+An account is created with REG:ACCOUNT, like so:
+
+ C: REG:ACCOUNT $email $passcode
+ S: REG:ACCOUNT $name $email
+
+Where $email is a standard email address, $passcode is as defined in
+L<Haver::Spec::Auth/PASSCODES>, and $name is the name you sent via B<IDENT>
upon login.
+
+=head2 Changing a passcode
+
+Changing a passcode is done with REG:PASSCODE.
+
+ C: REG:PASSCODE $passcode
+ S: REG:PASSCODE $name
+
+The server doesn't echo the passcode for security reasons. Note that using
this command
+without SSL is probably very insecure anyway.
+
+=head2 Changing the email address
+
+You can change the registered email address with REG:EMAIL:
+
+ C: REG:EMAIL $email
+ S: REG:EMAIL $name $email
+
+=head2 Deleting an account
+
+Accounts can be removed, either by the owner or a server admin.
+
+ C: REG:REMOVE $name
+ S: REG:REMOVE $name
+
+
+
+=head1 YOU FAIL
+
+This extension introduces a few new errors.
+
+=head2 invalid.email
+
+Raised when the email address given in REG:ACCOUNT or REG:EMAIL is not a valid
email address,
+according to the related RFCs.
+
+=head2 registered.user
+
+Raised when REG:ACCOUNT is called for by a user that is already registered.
+
+=head2 permission
+
+Raised when REG:REMOVE is used by non-admins on users other their self.
+
+=head1 AUTHOR
+
+Dylan William Hardison E<lt>[EMAIL PROTECTED]<gt>.
+
+=head1 SEE ALSO
+
+L<Haver::Spec>, L<Haver::Spec::Auth>, L<http://www.haverdev.org/>.
+
+=head1 COPYRIGHT and LICENSE
+
+Copyright (C) 2005 by Dylan William Hardison. All Rights Reserved.
+
+This module 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 2 of the License, or
+(at your option) any later version.
+
+This module 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 module; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Added: trunk/docs/spec/lib/Haver/Spec.pod
===================================================================
--- trunk/docs/spec/lib/Haver/Spec.pod 2005-08-06 05:14:10 UTC (rev 908)
+++ trunk/docs/spec/lib/Haver/Spec.pod 2005-08-06 17:56:14 UTC (rev 909)
@@ -0,0 +1,264 @@
+=head1 NAME
+
+Haver::Spec - The core haver protocol.
+
+=head1 DESCRIPTION
+
+This document describes the core functionality of the Haver protocol.
+It is not as comprehensive as the Manual, but it is slightly better than
keeping these
+things in plain text files.
+
+=head1 BEGIN YOUR FEAR
+
+Here's a general overview with examples. Lines beginning with C: are from the
client,
+and lines beginning with S: are from the server. Items enclosed in square
brackets
+are optional.
+
+=head2 HAVER/IDENT/HELLO
+
+C<$supported> is a comma-seperated last of supported extensions (See
L</EXTENSIONS>)
+
+ C: HAVER Foobar/1.0 [$supported]
+ S: HAVER example.com FoobarServer/1.0
+ C: IDENT $name
+ S: HELLO $name
+
+
+=head2 JOIN/PART/LIST
+
+C<$namespace> is one of "user", "service", or "channel".
+
+ C: JOIN $channel
+ S: JOIN $channel $user
+
+ C: PART $channel
+ S: PART $channel $user
+
+ C: LIST $channel $namespace
+ S: LIST $channel $namespace Thing1 Thing2 Thing3
+
+=head2 IN/TO/FROM
+
+Public messages (a message sent to everyone in a channel)
+
+ C: IN $channel $type @args
+ S: IN $channel $user $type @args
+
+Private messages (a message sent ot a select group of users)
+
+ C: TO $users $type @args
+ S: FROM $users $type @args
+
+
+Clients must use any word (C</^\w+$/>) for $type,
+but it is typically "do" or "say".
+
+
+=head2 INFO
+
+ C: INFO $namespace $name
+ S: INFO $namespace $name $key1 $value1 $key2 $value2 ...
+
+Sending this message results in the server sending back a message (S:INFO)
with a list of
+key/value pairs. The keys vary depending on what is queried. Different server
+implementations may add extra keys too. Good user agents will allow the user
to see any
+and all keys assigned to entity, even ones that did not exist when the user
agent was
+programmed.
+
+=head3 Keys for Users and Services
+
+=over
+
+=item address
+
+A (probably masked) IP address. E.g. 1.2.3.*
+
+=item version
+
+The name and version number of the user-agent and service program, as sent by
C:HAVER.
+
+=item idle
+
+The number of seconds the client has been idle. For users, idle is defined as
the length
+of time between sending TO or IN messages.
+
+=item email
+
+The email address of the user or service. All registered services and users
will have
+email addresses associated with them.
+
+=back
+
+=head3 Keys for Channels
+
+=over
+
+=item creator
+
+The name of the user that created the channel.
+
+=item created
+
+The date and time the channel was created.
+
+=back
+
+=head3 Keys for the Lobby
+
+=over
+
+=item booted
+
+The date and time the server was booted.
+
+=item hostname
+
+The hostname of the server.
+
+=item version
+
+The version name of the server, the same as from S:HAVER.
+
+=back
+
+=head2 POKE/OUCH
+
+POKE is used to see if the server is alive. The server will respond with OUCH.
+
+ C: POKE $string
+ S: OUCH $string
+
+=head2 PING/PONG
+
+If the server sends PING, the client must respond with PONG, like so:
+
+ S: PING $string
+ C: PONG $string
+
+=head2 BYE/QUIT
+
+To disconnect, a client should send BYE:
+
+ C: BYE $detail
+
+The server will reply with:
+
+ S: BYE $type $detail
+
+All users sharing a channel with the client will see:
+
+ S: QUIT $sender $type $detail
+
+The $type of quit is one of several things:
+
+=over
+
+=item *
+
+closed
+
+=item *
+
+error ($detail = error code?)
+
+=item *
+
+bye ($detail = from BYE)
+
+=item *
+
+ping
+
+=item *
+
+ghost
+
+=item *
+
+kill ($detail = killer)
+
+=back
+
+=head1 YOU FAIL
+
+The server may respond to any given message with FAIL, which has the form of:
+
+ S: FAIL $cmd $error [EMAIL PROTECTED]
+
+Where $cmd is the name of the message that failed, $error is the error name,
and @args are
+bits of information related to the error.
+
+=head2 invalid.name
+
+You used a name that contains invalid characters.
+
+=head2 reserved.name
+
+You used a name that contains characters only special people are allowed to
use.
+
+=head2 exists.user
+
+The user name you requested is in use.
+
+=head2 unknown.user
+
+That user name does not exist on the server.
+
+=head2 unknown.channel
+
+That channel name does not exist on the server.
+
+=head2 unknown.namespace
+
+The namespace (used in LIST, for example) is not one that the server is aware
of.
+
+=head2 invalid.type
+
+The $type argument of an IN or TO message contained non-word characters.
+
+=head2 already.joined
+
+Tried to join a channel that you're already in.
+
+=head2 already.parted
+
+Tried to part a channel you're not in.
+
+
+=head1 I MEAN, HI
+
+I could describe the messages here in greater detail, but I think that belongs
in the
+manual. There might be some other useful information to put in this section,
too. But it
+is five thirteen in the morning, so I can't think of it.
+
+=head1 EXTENSIONS
+
+Currently defined extensions: L<Haver::Spec::Ghost>, L<Haver::Spec::Auth>,
+L<Haver::Spec::Reg>.
+
+=head1 AUTHOR
+
+Dylan William Hardison, E<lt>[EMAIL PROTECTED]<gt>
+
+=head1 SEE ALSO
+
+L<http://www.haverdev.org/>.
+
+=head1 COPYRIGHT and LICENSE
+
+Copyright (C) 2005 by Dylan William Hardison. All Rights Reserved.
+
+This module 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 2 of the License, or
+(at your option) any later version.
+
+This module 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 module; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
Modified: trunk/perl/server/lib/Haver/Server.pm
===================================================================
--- trunk/perl/server/lib/Haver/Server.pm 2005-08-06 05:14:10 UTC (rev
908)
+++ trunk/perl/server/lib/Haver/Server.pm 2005-08-06 17:56:14 UTC (rev
909)
@@ -29,7 +29,7 @@
use Haver::Server::Config;
use Haver::Server::Store;
-our $VERSION = 0.08;
+our $VERSION = 0.082;
our $Alias = 'Server';
our $Config = 'haverd.yml';
@@ -127,37 +127,6 @@
FIXME
-=head1 METHODS
-
-There is only one method, create(), which is a class method.
-
-=head2 create(alias => $alias, resolver => $resolver, version => $version)
-
-This creates a new Haver::Client session. The only required parameter
-is $alias, which is how you'll talk to the client session using
L<POE::Kernel>'s post().
-
-If given, $resolver should be a L<POE::Component::Client::DNS> object.
-
-Finally, $version is what we will advertize as the client name and version
number to the
-server. It defaults to C<Haver::Client/0.08>.
-
-=head1 STATES
-
-While these are listed just like methods, you must post() to them, and not
call them
-directly.
-
-=head2 connect(host => $host, name => $name, [ port => 7575 ])
-
-Connect to $host on port $port (defaults to 7575) with the user name $name.
-If already connected to a server, Haver::Client will disconnect and re-connect
using the
-new settings.
-
-=head2 register(@events)
-
-This summons the sun god Ra and makes him eat your liver.
-
-FIXME: This is inaccurate.
-
=head1 BUGS
None known. Bug reports are welcome. Please use our bug tracker at
Modified: trunk/web/Makefile
===================================================================
--- trunk/web/Makefile 2005-08-06 05:14:10 UTC (rev 908)
+++ trunk/web/Makefile 2005-08-06 17:56:14 UTC (rev 909)
@@ -101,4 +101,4 @@
endif
.SUFFIXES:
-.PHONY: build upload clean realclean dist stop validate test fast
+.PHONY: build upload clean realclean dist stop validate test fast docs
