Curlicue
========

Curlicue is a small wrapper script that invokes curl with the necessary
headers for OAuth. It should run on any POSIX-compatible shell. Keys,
tokens, and secrets are stored in text files as form-encoded data.

Usage
-----

A Curlicue command looks like the equivalent curl command, with some
extra options at the beginning:

    curlicue [-f FILE ...] [-p PARAMS] [-- CURL_OPTS] URL

OAuth credentials are read from FILE(s). Extra OAuth parameters, if any,
are specified with -p. Parameters in files or in the argument to -p
should be percent-encoded and separated with &. Either -- or a URL ends
processing of Curlicue parameters and passes the rest along to curl.

If you don't specify any FILEs, Curlicue will try to read credentials
from ~/.curlicue/HOST, where HOST is the hostname component of your URL.

Setup
-----

To perform the initial OAuth "dance", run curlicue-setup with four
arguments: the request token URL, the user authorization URL, the access
token URL, and a file to output credentials to. Typically, this will
look something like:

    curlicue-setup \
        'https://oauth.provider/request_token' \
        'https://oauth.provider/authorize?oauth_token=$oauth_token' \
        'https://oauth.provider/access_token' \
        credentials

In the user authorization URL (only), variables from the consumer
information or request token can be interpolated using shell syntax.
Your provider may need additional URL parameters for one or more of the
steps; consult their documentation. You will be prompted for the
consumer key and secret.

For examples of how this works with several popular OAuth providers,
refer to EXAMPLES.

Included Scripts
----------------

The contrib directory contains some scripts that demonstrate what you can
do with Curlicue:

   * twitpull - display data from various Twitter API endpoints as plain
     text, using XMLStarlet. For endpoints that support it, handles
     using a cursor parameter to fetch the entirety of long lists with
     multiple requests.

Walkthrough
-----------

To demonstrate the authentication process in detail, let's work through
what happens when you run curlicue-setup with Twitter as a previously
registered application. Before creating any files (which will all
contain secrets), we should set our umask so that no one else can read
them:

    umask 077

The first step in OAuth is obtaining a request token. To make that
request, we'll need a file containing the consumer key and secret (make
sure that their values are percent-encoded):

    cat << EOF > consumer
    oauth_consumer_key=KEY&oauth_consumer_secret=SECRET
    EOF

With that, let's get the token. We're not a web app, so we use the "out
of band" callback method:

    curlicue -f consumer -p 'oauth_callback=oob' -- \
        -d '' 'https://api.twitter.com/oauth/request_token' > request_token

The arguments passed along to curl are parsed to get the HTTP method and
URL so that the request can be signed.

Now we need to approve the app. We can build URLs with the -e option,
which just echoes a string back to us (with parameters from the files
read with -f filled in) instead of running curl.

    curlicue -f request_token -e \
        'https://api.twitter.com/oauth/authorize?oauth_token=$oauth_token'

Visiting this URL in our browser and selecting "Allow" will give us a
PIN, which we can in turn use to obtain an access token:

    curlicue -f consumer -f req_token -p 'oauth_verifier=PIN' -- \
        -d '' 'https://api.twitter.com/oauth/access_token' > access_token

Note that we need to read in both the consumer and token information
from here on. Now we can actually make an interesting request:

    curlicue -f consumer -f access_token \
        https://api.twitter.com/1/statuses/home_timeline.xml

In this case, we are not passing any options along to curl, so the --
can be omitted.

Finally, to make our command line shorter, we can concatenate the
consumer and token into one file:

   paste -d '&' consumer access_token > credentials

And remove all the intermediate files (consumer, request_token, and
access_token).

Limitations
-----------

--data-urlencode, --data-binary, and reading POST data from a file are
not yet supported.

Dependencies
------------

OpenSSL is used for HMAC-SHA1 signing and nonce generation.

Thanks
------

To Alex Payne for suggesting the name.

Legal
-----

Copyright © 2010 Decklin Foster <decklin@red-bean.com>. This program is
distributed under the MIT license; see LICENSE for details.