JavaScript API

JavaScript API

#Overview

This is a typescript-esc API mockup.

Many of the detailed structures are missing but the general API methods are present.

##Service Side

A typical ACL creation request would look something like:

dracl.service.createACL({
    name: "My Photo",
    srcdoc: "Share 'My Photo' with your friends!"
}, function(acl) {
    if (acl) {
        return_acl(acl); // Implemented by service
    }
});

A typical ACL verification request might look like:

dracl.service.verifyACL(challenge, function(resp) {
    if (resp) {
        return_resp(resp);
    }
}

##Agent Side

An ACL creation request would look like:

dracl.agent.beginACLCreation(function(session) {
    authenticate_user(session.email, function(success) {
        if (!success) {
            session.raiseAuthenticationError();
        }
        // ... Let the user create the ACL ...

        // This ACL is not signed, it gets signed by the
        // browser after the browser prompts the user to confirm.
        session.complete(ACLSkeleton);
    });
});

A management session might look like:

function sessionProgram(session) {
    session.createGroup(function(group_key) {
        session.addMembersToGroup(group_key, [user1, user2], function(group_member) {
            upload_group_members(group_key, group_members);
        });
    });
}
dracl.agent.openKey("0x1111212", function(session) {
    if (session) {
        sessionProgram(session);
    } else {
        fetch_key(function(key) {
            if (key) {
                dracl.agent.registerKey(key, sessionProgram);
            } else {
                dracl.agent.createKey(function(session, keyPair) {
                    upload_key(keyPair);
                    sessionProgram(session);
                });
            }
        });
    }
});

#API

module dracl {
    module service {
        createACL(details: object, callback: function(acl?: string));
        verifyACL(challenge: ACLChallenge, function(response: ACLResponse));
    }

    class Group {
        name: string;
        key: GroupKey;
        members: GroupMember[];
        past_keys: GroupKey[];
    }

    module agent {
        class ACLSession {
            email: string;
            /**
             * Cancel the ACL creation session.
             */
            cancel(reason?: string);

            /**
             * Indicate that the authentication with the authentication agent
             * failed.
             *
             * This will return the user to the first authentication screen (see
             * the mock-ups).
             */
            raiseAuthenticationError(reason?: string);

            /**
             * Complete the ACL creation.
             *
             * The authentication agent calls this once to finish the ACL
             * creation process. Calling this will trigger the final
             * confirmation page (see the mock-ups).
             */
             complete(acl: ACLSkeleton);
        }


        class ManagementSession {

            // The user's public key/key_id.
            key: UserKey;

            /**
             * Create a group key pair.
             */
            createGroup(callback: function(group_key: GroupKey));

            /**
             * Add `members` to `group`.
             * 
             * (This doesn't need the full group spec, just the key)
             */
            addMembersToGroup(group: GroupKey, members: UserKey[], callback: function(group_membership: GroupMembership));

            /**
             * Remove `members` from `group`.
             *
             */
            removeMembersFromGroup(group: Group, members: UserKey[], function(new_group: Group));

            /**
             * Add a friend to the client's friend list.
             *
             * We need this method so we can sign all of our friends keys. This
             * makes it much more difficult for authentication agents to add
             * themselves to an ACL (they can't trick the user into adding
             * them).
             *
             */
            addFriend(user: UserKey, function(friend?: FriendKey));
        }

        /**
         * Open an acl creation session.
         *
         * This should be called by the ACL creation page after an ACL has been
         * requested by a service. Basically, this function indicates to the
         * browser that the authentication agent is ready to handle the ACL
         * creation request.
         *
         */
        beginACLCreation(callback: function(session: ACLSesion));

        /**
         * Open a session with the key given by key_id.
         *
         * This lets us cache the user's private key. If the key is not cached,
         * the callback will be called with `false`.
         *
         * Allowing the service to specify `key_id` allows users to have
         * multiple identities per service.
         * 
         * NOTE: The same-origin-policy applies to this function. You can't
         * register a key from one origin and access it from another.
         * Furthermore, you can't use this method to get the private key out.
         */
        openKey(key_id: string, callback: function(session?: ManagementSession));

        /**
         * Register a key with the browser and open a session.
         *
         * If the above method fails, the service will call this to register a
         * key.
         */
        registerKey(key: UserKeyPair, function(session?: ManagementSession));

        /**
         * Create a new user key and open a session.
         *
         * Unlike the two previous methods, this method actually gives the
         * caller access to the encrypted private key. This way the
         * authentication agent can store the user's key on the server for safe
         * keeping.
         */
        createKey(function(session?: ManagementSession, key?: UserKeyPair));
    }
}