get a unique URL which can be shared with others in order to download
the file.
-Coquelicot aims to protect, to some extend, users and system
+Coquelicot aims to protect, to some extent, users and system
administrators from disclosure of the files exchanged from passive and
not so active attackers.
Features
--------
- * Support for different authentication methods
-
- It is possible to integrate your own authentication mechanisms. Such a
- mechanism, needs to implement a single method and provide some JS, as well
- as some template partial to render the common fields. For more information
- have a look at the notes below.
- * Simplepass mechanism: Uploading a file is protected by a common password
+ * Support for different authentication methods
- In order to prevent random Internet users to eat bandwidth and disk
- space, uploading a file for sharing is protected by a common
- password.
+ In order to prevent random Internet users to eat bandwidth and
+ disk space, Coquelicot limits upload to authenticated users.
+ It currently ships with two authentication mechanisms:
- * IMAP mechanism: Uploading is protected by an imap login
+ - "simplepass": users will need to provide a global, pre-shared,
+ password;
+ - "imap": users will need to provide a login and a password,
+ those credentials will be used to authenticate against an existing
+ IMAP server.
- As a protection mechanism we can enable login via imap credentials. The user
- will be asked to provide her imap credentials and we will perform an imap
- login in order to authenticate the user.
+ It is possible to integrate more authentication mechanisms by
+ implementing a single method, some Javascript, and a template partial
+ to render the common fields. For more information have a look at the
+ notes below.
* Mandatory expiration
* Support for one-time download
- An user might want to allow exactly _one_ download of a file,
- to more closely replace an email attachment. The file will be removed after
- the first complete download and concurrent download are prevented.
+ An user might want to allow exactly _one_ download of a file, to more
+ closely replace an email attachment. The file will be removed after
+ the first complete download and concurrent downloads are prevented.
* Upload progress bar
apt-get install libsinatra-ruby1.8 libopenssl-ruby1.8 \
libhaml-ruby1.8 liblockfile-ruby libgettext-ruby1.8 \
- rake
-
-Then create the translation catalog through:
-
- rake makemo
+ libjson-ruby1.8 rake
Finally you need to figure out the best way to host a Rack application
depending on your setup. *evil grin*
Configuration
-------------
-By default Coquelicot is configured to authenticate with the simplepass mechanism
-and some other reasonable defaults.
-It is possible to overwrite these settings from a configuration file named
-settings.yml that will be used if it is present in the conf directory of the
-application.
+By default Coquelicot is configured to authenticate with the
+"simplepass" mechanism and some other reasonable defaults.
+
+It is possible to overwrite these settings from a configuration file
+named `settings.yml` that will be used if it is present in the `conf`
+directory of the application.
All available settings with their default values are documented in
-conf/settings-default.yml
+`conf/settings-default.yml`.
Further settings example:
-* conf/settings-simplepass.yml: Shows how to change the default password for the
- simplepass mechanism.
+ * `conf/settings-simplepass.yml`: shows how to change the default
+ password for the "simplepass" mechanism.
-* conf/settings-imap.yml: Necessary configuration for the imap authentication
- mechanism.
+ * `conf/settings-imap.yml`: necessary configuration for the "imap"
+ authentication mechanism.
-You can copy one of these examples to conf/settings.yml and adjust them according
-to your environment.
+You can copy one of these examples to `conf/settings.yml` and adjust them
+according to your environment.
Garbage collection
------------------
-To cleanup files automatically when they expired, coquelicot comes with a cleanup script, that does the garbage collection for you. The easiest way is to add ext/coquelicot_gc.rb as a cron job that runs every 5 minutes (or so).
+To cleanup files automatically when they expired, coquelicot comes with
+a cleanup script, that does the garbage collection for you. The easiest
+way is to add `ext/coquelicot_gc.rb` as a cron job that runs every 5
+minutes (or so).
+
+Test and development
+--------------------
-Test suite
-----------
+As Coquelicot uses Bundle, the first step to work on Coquelicot
+is installing the proper dependencies by issuing:
-Coquelicot test suite is written using RSpec.
+ bundle install
-On Debian, you will need those extra packages:
+Coquelicot test suite is written using RSpec. Running the test suite is just a
+matter of typing:
- apt-get install librspec-ruby1.8 libhpricot-ruby1.8
+ bundle exec rspec
-You will also need the unpackaged gems "timecop" and "rack-test".
+To update the translation source files, use:
-Then, running the test suite is just a matter of typing:
+ bundle exec rake updatepo
- spec test_coquelicot.rb
+This will update `po/coquelicot.pot` and merge the new strings in the various
+`po/*/coquelicot.po` files.
Migrate from Jyraphe
--------------------
It is possible to authenticate users against your own common authentication
mechanism.
-Such an authentication mechanism needs to provide the following 3 files:
-
-* lib/coquelicot/auth/METHOD.rb
-* public/javascripts/coquelicot.auth.METHOD.js
-* views/auth/METHOD.haml
-
-Their responsibilities are as followed:
-
-lib/coquelicot/auth/METHOD.rb:
-
-A module implementing the actual authentication. This module must
-implement one method called `authenticate` which will get all the
-parameters as an argument. To simplify your interaction with the field
-`upload_token`, that might be serialized as json, we deserialize it prior
-to passing it to the `authenticate` method.
-
-public/javascripts/coquelicot.auth.METHOD.js:
-
-We expect 2 javascript methods in that file:
-
-* authenticationData(): Return a hash of all the necessary data to
- authenticate on the app side.
-* authenticationFocus(): Set the focus on the first authentication form
- field
-
-views/auth/METHOD.haml:
-
-Render the necessary form fields that will be used for authentication.
-
-The authentication method can be set in the application settings
-including mandatory options for this method.
+Such an authentication mechanism needs to provide the following 3 files,
+with the following responsabilities:
+
+ * `lib/coquelicot/auth/<METHOD>.rb`:
+
+ A class implementing the actual authentication. This class must
+ implement an `authenticate` method. It will receive the form fields
+ as usual (params). This method should either return true if upload
+ should be allowed.
+
+ * `public/javascripts/coquelicot.auth.<METHOD>.js:`
+
+ This file should define 'authentication' as an object with the following
+ methods:
+
+ - `getData()`: returns an object of all the necessary data
+ to authenticate on the app side. Keys should have the same name
+ as the input fields used to authenticate without Javascript.
+ - `focus()`: set the focus on the first authentication form field.
+ - (optional) `handleSuccess()`: arbitrary action upon successful
+ authentication. This is called after the livebox is closed.
+ - (optional) `handleReject()`: arbitrary action when access
+ get rejected. One can reset authentication fields after a failed
+ authentication.
+ - (optional) `handleFailure()`: arbitrary action when there was
+ a problem in the authentication procedure.
+
+ * `views/auth/<METHOD>.haml`:
+
+ Render the necessary form fields that will be used for authentication.
+
+ The authentication method can be set in the application settings
+ including mandatory options for this method.
Authors
-------
-Coquelicot © 2010 potager.org <jardiniers@potager.org>
-mh © 2011 immerda.ch <mh+coquelicot@immerda.ch>
+Coquelicot © 2010-2012 potager.org <jardiniers@potager.org>
+ © 2011 mh / immerda.ch <mh+coquelicot@immerda.ch>
Coquelicot is distributed under the GNU Affero General Public License
version 3. See LICENSE for details.
+
+Background image (`public/images/background.jpg`) derived from:
+"coquelicot" © 2008 Jean-Louis Zimmermann
+Licensed under Creative Commons Attributions 2.0 Generic
+<https://secure.flickr.com/photos/jeanlouis_zimmermann/2478019744/>
projects / coquelicot.git / blobdiff