grendel-ruby

Ruby interface to the Grendel secure document storage service (http://github.com/wesabe/grendel). See the Grendel API documentation (http://github.com/wesabe/grendel/blob/master/API.md) for more information.

Installation

sudo gem install grendel-ruby

Examples

The following examples assumes that you have the Grendel server running locally on port 8080.

Establishing a Connection

client = Grendel::Client.new("http://localhost:8080")

Listing Registered Users

client.users.list  # returns an array of Grendel::Users

Creating A New User

user = client.users.create("alice", "s3kret")  # returns a Grendel::User with id "alice" and password "s3kret"

If the user id is taken, a Grendel::HTTPException will be thrown with a message containing 422 Unprocessable Entity and an explanation.

Viewing A User

user = client.users.find("alice")  # returns a Grendel::User

# return a Grendel::User with the password set to "s3kret". Note that this is merely a convenience
# method for future authenticated calls--it does not actually check that the password is correct.
user = client.users.find("alice", "s3kret")

The returned Grendel::User will contain the following attributes:

id - user id
modified_at - DateTime
created_at - DateTime
keys - array of key fingerprints

If the user is not found, a Grendel::HTTPException will be thrown with a message containing 404 Not Found

Changing A User's Password

user = client.users.find("alice", "s3kret")
user.change_password("new-pass")

Deleting A User

user = client.users.find("alice", "s3kret")
user.delete

Listing A User's Documents

user = client.users.find("alice", "s3kret")
docs = user.documents.list  # returns an array of Grendel::Documents

A Grendel::Document contains the following attributes:

- name
- data
- content_type
- uri

Viewing A User's Document

user = client.users.find("alice", "s3kret")
doc = user.documents.find("document1.txt")  # returns a Grendel::Document

Storing A User's Document

user = client.users.find("alice", "s3kret")
doc = user.documents.store("document1.txt", "i am a super secret")

The content type can be specified as an optional third parameter. If not provided, it will be guessed from the file extension of the document name.

doc = user.documents.store("document1.txt", "i am a super secret", "text/plain")

Note that this method will overwrite the document if it already exists in Grendel.

Deleting A User's Document

user = client.users.find("alice", "s3kret")
doc = user.documents.delete("document1.txt")

# or

doc = user.documents.find("document1.txt")
doc.delete

Linking Documents

A Grendel document can be linked by its owner with other users. Doing so provides other users read-only access to the document.

Viewing A Document's Linked Users

user = client.users.find("alice", "s3kret")
doc = user.documents.find("document1.txt")
links = doc.links.list  # returns an array of Grendel::Links

A Grendel::Link contains the following attributes:

- document
- user # the user the document is linked to
- uri # the uri of the linked document

Linking Another User To A Document

user = client.users.find("alice", "s3kret")
doc = user.documents.find("document1.txt")
doc.links.add("bob")  # returns a Grendel::Link

User bob will now have read-only access to the document.

Unlinking A User From A Document

user = client.users.find("alice", "s3kret")
doc = user.documents.find("document1.txt")
doc.links.remove("bob")

User bob will no longer have access to the document.

Managing Linked Documents

The documents shared with a user are stored in their own namespace to avoid document name collisions. If the document's owner modifies the document, the linked users will see the changes. Likewise, if the document's owner deletes the document (or the owner is deleted), the documents will be removed from the user's linked documents.

Listing A User's Linked Documents

user = client.users.find("alice", "s3kret")
linked_docs = user.linked_documents  # returns an array of Grende::LinkedDocuments

A Grendel::LinkedDocument is a subclass of Grendel::Document with the following additional attribute:

- owner # the document owner as a Grendel::User

Viewing A Linked Document

user = client.users.find("alice", "s3kret")
doc = user.linked_documents.find("bob", "bobs_secrets.txt")

Deleting A Linked Document

user = client.users.find("alice", "s3kret")
user.linked_documents.delete("bob", "bobs_secrets.txt")

# or

doc = user.linked_documents.find("bob", "bobs_secrets.txt")
doc.delete

This will not delete the document itself, it will simply remove the document from the user's list of linked documents. It will also not re-encrypt the document; the next time the document is written to, however, the user will be excluded from the recipients.

Bugs and Issues

Please submit them here http://github.com/wesabe/grendel-ruby/issues