Proposed Goldilocks API spec

api-rp.md

Relying Party (RP) API

navigator.id.watch( parameters )

Configure BrowserID by registering callbacks and setting display options.

Implementation Notes:

• May only be called once. Subsequent calls must be ignored and should log an error.
• User input should be treated carefully — siteLogo may be an SVG, which opens an avenue for scripting.

Required Parameters:

onlogin: function (assertion) { … }

Callback. Invoked when a user attempts to sign in. Receives a Backed Identity Assertion as its first argument.

Visual Customization (Optional):

siteName: String (Freeform text)

Human-friendly name of the Relying Party.

        <dt><strong><code>siteLogo</code></strong>: <strong>String</strong> (URL, absolute path, or <code>data:</code> URI)</dt>
        <dd>Image that represents the Relying Party.</dd>

        <dt><strong><code>backgroundColor</code></strong>: <strong>String</strong> (Hex #rgb or #rrggbb)</dt>
        <dd>Background color for displaying Relying Party information.</dd>
    </dl>
</dd>

<dt><h3>navigator.id.request( <em>parameters</em> )</h3></dt>
<dd>
    <p>
        Prompt the user to select an email address and sign into the Relying Party.
        Upon successful completion, a Backed Identity Assertion is passed to the <code>onlogin</code> callback registered in <code>navigator.id.watch()</code>.
    </p>
    <blockquote>
        <strong>Implementation Notes:</strong>
        <ul>
            <li>Must be called in response to direct user action, such as a click.</li>
            <li>Raises an error if called before <code>navigator.id.watch()</code> has been invoked.</li>
        </ul>
    </blockquote>
    <strong>Behavior Customization (Optional):</strong>
    <dl>
        <dt><strong><code>emailHint</code></strong>: <strong>String</strong> (Email address)</dt>
        <dd>Skip address selection and attempt to authenticate the user as the hinted email address.</dd>

        <dt><strong><code>oncancel</code></strong>: <code><strong>function ()</strong> { … }</code></dt>
        <dd>
            Callback.
            Invoked if the user closes the login prompt without selecting an address.
        </dd>

        <dt><strong><code>returnTo</code></strong>: <strong>String</strong> (Absolute path)</dt>
        <dd>__TODO:__ How does this actually work in a native user agent?</dd>
    </dl>
</dd>