= Branch Access Token =

Access tokens can be created that allow access to a defined set of branches.

'''Contact:''' mwhudson <<BR>>
'''On Launchpad:''' ''Link to a blueprint, milestone or (best) a bug tag search across launchpad-project''

== Rationale ==

Michael is doing this in his spare time because Linaro infrastructure is setting up yet another project that involves copying ssh keys for a robot user account around, and it's just too much.

There is no one compelling value this brings, but it allows a few improvements that add up to a real benefit:

 1. It will allow deleting the branch puller entirely.
 2. It is an important step on the way to enabling recipes to be built from private branches.
 3. It will allow projects such as "private builds in offspring" more natural ways to access private branches.

== Stakeholders ==

mwhudson cares enough to do this in his spare time.

== User stories ==

<<Anchor(delete-branch-puller)>>

=== Delete branch puller ===

'''As a ''' Launchpad developer<<BR>>
'''I want ''' to programmatically generate a token that allows write access to a branch <<BR>>
'''so that ''' I can use these tokens in code imports and thus delete the branch puller<<BR>>

<<Anchor(enable-private-recipes)>>

=== Enable private recipes ===

'''As a ''' Launchpad developer<<BR>>
'''I want ''' to programmatically generate a token that allows read access to a known set of branches <<BR>>
'''so that ''' I can move on to working on enabling recipe builds that reference private branches<<BR>>

<<Anchor(allow-access-to-private-branches)>>

=== Allow fine-grained access to private branches ===

'''As a ''' [[https://launchpad.net/offspring|Offspring]] admin<<BR>>
'''I want ''' to programmatically generate a token that allows read access to a private branch <<BR>>
'''so that ''' I can attach these tokens to projects in offspring and allow them to reference private config branches<<BR>>


== Constraints and Requirements ==

=== Must ===

It must allow access to the required branches.

=== Nice to have ===

=== Must not ===

Compromise security.  Negatively affect performance.  Create undue complexity in the Launchpad code base.

(I don't think it is very likely to do any of these things)

=== Out of scope ===

== Success ==

=== How will we know when we are done? ===

=== How will we measure how well we have done? ===

== Thoughts? ==

The generated tokens will be used over ssh.  Essentially I will create a "username"/secret pair.  Providing these to the Twisted daemon that runs the codehosting ssh service as username and password will allow logging in to a similar environment as the current username/ssh key but that only allows access to the configured branches.  Tokens will be immutable once created.

The creation API will be something like {{{createToken(registrant, [writing_branches], [reading_branches])}}}.

I expect the database side to look a bit like this:

{{{
class BranchAccessToken:
    id = Int(primary=True)
    secret = Text()
    creator = Reference(Person)
    date_created = Datetime()

class BranchAccessTokenAccess:
    token = Reference(BranchAccessToken)
    branch = Reference(Branch)
    can_write = Bool()
}}}

Logging in as the user ".$(id)s" with the password "%(secret)s" from a BranchAccessToken will be accepted by the ssh service.  The XML-RPC method translatePath will handle usernames starting with a "." differently.

I don't propose to create a UI for this.  All users are at the very least fairly advanced and can use the LP API (or some of them will use the internal API I guess).