= Clavis: Security, Type-safe URLs for ASP.NET =

Clavis is a simple class library for use with ASP.NET. It provides primitives for secure parameter passing between pages, with compiler-verified taint-checking for any insecure parameters. For an overview of the rationale or the operational details behind Clavis, see [http://higherlogics.blogspot.ca/search/label/Clavis the Clavis blog posts].

You need only understand a few concepts to use Clavis:

 1. IContinuation for specifying page parameter types
 1. Unsafe<T> for specifying unsafe/insecure page parameters
 1. Continuation.ToUrl overloads for generating URLs from continuations + arguments
 1. Continuation.TryParseX for parsing page parameters

== Typed Page Parameters ==

A typed page parameter list is specified via an IContinuation<...> declaration, like so:
{{{
public class SomePage : System.Web.Page, IContinuation<int, string>
{
  ...
}
}}}
This declares a page that accepts a protected Int32 as the first argument, and a protected string as the second argument. By default, all types specified in an IContinuation<...> declaration will be protected, which means they cannot be changed by clients.

Any type can appear as an argument to IContinuation<...>, not just primitive values. In fact, it's good practice in Clavis not to use primitive types since parameter names are generated from the class name by default:
{{{
public class SomePage : System.Web.Page, IContinuation<Project, Customer>
{
  ...
}
}}}
Clavis can also handle lists of values by specifying IEnumerable<T> as a parameter type:
{{{
public class SomePage : System.Web.Page, IContinuation<IEnumerable<Project>, Customer>
{
  ...
}
}}}

== Unsafe Parameters ==

If you wish to declare that a certain page parameter is unprotected, then you need only wrap it with Unsafe<T>. For instance, suppose the integer argument from the first example should be unprotected:
{{{
public class SomePage : System.Web.Page, IContinuation<Unsafe<int>, string>
{
  ...
}
}}}
IEnumerable<T> and Unsafe<T> can also be nested, so you can have an unsafe list of objects as a parameter:
{{{
public class SomePage : System.Web.Page, IContinuation<Unsafe<IEnumerable<Project>>, Customer>
{
  ...
}
}}}

== Generating URLs ==

You can easily generate a URL from a continuation with its arguments like so:
{{{
var url = Continuation.ToUrl<SomePage, int, string>(
              3.AsParam(), "hello world!".AsParam());
}}}
The first type argument, SomePage, is the continuation type. The subsequent type arguments are the type arguments to IContinuation<...>. Another method of generating a URL that requires fewer type annotations:
{{{
var url = Continuation.Params(3.AsParam(), "hello world!".AsParam());
                      .ToUrl<SomePage>();
}}}
The {{{Param.AsParam()}}} extension methods are fully defined over all [http://msdn.microsoft.com/en-us/library/system.iconvertible.aspx IConvertible] types. Types that aren't IConvertible require that you provide an ICovertible type as a key:
{{{
public class SomePage : System.Web.Page, IContinuation<Project, Customer> { ... }

...

var url = Continuation.Params(project.AsParam(project.Id), customer.AsParam(customer.Id));
                      .ToUrl<SomePage>();
}}}