feat(be): sign a session to the II frontend at sign-in (#4268)

Design: #4224. Overview: #4230. This is the caller #4266 and #4264 were
waiting for, so it removes their `#[allow(dead_code)]` annotations.

**`prepare_account_session` / `get_account_session`.** The first creates
a session and signs its delegation to the II frontend's key; the second
witnesses it. A separate pair from `prepare_account_delegation`, not an
option on it: both mint, but one proves a live session and identifies
the account by its principal while the other proves an access method and
names the anchor outright. Merging them would mean one method with two
authorizers and two argument shapes, and would drag the frontend's
internal surface into the public API.

**Everything that can refuse does so before anything is written**,
cheapest first. The account check leads — an account the identity does
not hold is the one failure a caller can provoke, and returning it after
the writes would leave a browser registered for a sign-in that never
happened — so a request that was never going to succeed does not pay for
two P-256 verifications on the way to being told so. Nothing is revealed
by that order: `check_authz_and_record_activity` above is the auth
guard. The browser proof follows, using the verifier from #4264, and
`create_session` takes the `VerifiedBrowserKeys` it produces rather than
two byte strings.

**The session credential is scoped to Internet Identity.** It exists to
mint app delegations, which is an update call on this canister and
nothing else, so it is signed with `targets = [id()]` and can be
presented nowhere else. Leaving that to the II frontend would have left
it to the party holding the session key, who can decline to add it.
`permissions` stays absent for the same reason it is set on app
delegations: minting is an update call, so a read-only session that
could not make one could not sign in to an app at all — read-only
travels on the app delegation instead.

**`get_account_session` tells three failures apart.** No stored session
for that id is `NoSuchSession`; a session that is present with no
signature for the asked-for key and expiration is `NoSuchDelegation`,
because the remedy is to ask with the parameters that were signed rather
than to sign in again; a seed that will not derive is the salt being
unset, which is `InternalCanisterError`. An over-long origin is that
too, rather than a rejected message the caller cannot read as a
response.

**The request carries what the browser is, not a label for it.**
`browser_description` holds the tokens the registry stores (#4242), and
each token a client writes for itself — an unrecognised brand, an
unrecognised system, and the hardware model — is bounded at 64 bytes.
The named variants carry no text, so a description of nothing but those
is within the limit whatever it says. Refused rather than truncated: a
cut-off token would put a value in the record that no parser ever
produced.

**Every later failure traps rather than returning.** On the IC,
returning an error commits state and only a trap rolls the message back,
so once the browser registration is written a failure has to trap or a
caller could be told "no" and still have a browser enrolled.

**`valid_for`** is the lifetime the user chose at consent, clamped by
the canister to between 10 minutes and 30 days. Every ceremony creates,
so it always applies: the replacement's expiry is measured from the
ceremony that made it, and no session is renewed in place.

Tests: `integration/sessions.rs` (18) drives the real ceremony —
creating and verifying a session, a request for another identity
refused, the registry cap dropping the least recently used and ending
its sessions, the key proof's rejections at the endpoint, rotation
keeping the entry, a retired key returning as a new browser, and two
browsers each keeping the description it registered with.

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: sea-snake

src/canister_tests/src/api/internet_identity/api_v2.rs

@@ -746,3 +746,29 @@ pub fn get_account_delegation_with_read_only(
     )
     .map(|(x,)| x)
 }
+
+pub fn prepare_account_session(
+    env: &PocketIc,
+    canister_id: CanisterId,
+    sender: Principal,
+    request: PrepareAccountSessionRequest,
+) -> Result<Result<PrepareAccountSessionResponse, AccountSessionError>, RejectResponse> {
+    call_candid_as(
+        env,
+        canister_id,
+        RawEffectivePrincipal::None,
+        sender,
+        "prepare_account_session",
+        (request,),
+    )
+    .map(|(x,)| x)
+}
+
+pub fn get_account_session(
+    env: &PocketIc,
+    canister_id: CanisterId,
+    sender: Principal,
+    request: GetAccountSessionRequest,
+) -> Result<Result<GetAccountSessionResponse, AccountSessionError>, RejectResponse> {
+    query_candid_as(env, canister_id, sender, "get_account_session", (request,)).map(|(x,)| x)
+}

src/canister_tests/src/framework.rs

@@ -375,6 +375,70 @@ pub fn restore_compressed_stable_memory(env: &PocketIc, canister_id: CanisterId,
     env.set_stable_memory(canister_id, buffer, BlobCompression::Gzip);
 }
 
+/// A browser key of the kind `prepare_account_session` demands a proof from.
+///
+/// The DER encoding and the domain prefix have to match what the canister verifies,
+/// so both are spelled out here rather than derived.
+pub struct BrowserKey {
+    signing_key: p256::ecdsa::SigningKey,
+}
+
+/// The SPKI header WebCrypto emits for an `ECDSA` P-256 public key, ahead of the 65-byte
+/// uncompressed point.
+const P256_SPKI_HEADER: [u8; 26] = [
+    0x30, 0x59, 0x30, 0x13, 0x06, 0x07, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x02, 0x01, 0x06, 0x08, 0x2a,
+    0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07, 0x03, 0x42, 0x00,
+];
+
+const BROWSER_KEY_SIGNATURE_DOMAIN: &[u8] = b"ii-session-browser-key";
+const SUCCESSOR_KEY_SIGNATURE_DOMAIN: &[u8] = b"ii-session-browser-successor";
+
+impl BrowserKey {
+    pub fn new(seed: u8) -> Self {
+        Self {
+            signing_key: p256::ecdsa::SigningKey::from_bytes(&[seed; 32].into())
+                .expect("failed to build a browser key"),
+        }
+    }
+
+    /// The key a browser rotates to after `self`, so a test can walk the chain.
+    pub fn successor(&self) -> Self {
+        let mut seed = [0u8; 32];
+        seed.copy_from_slice(&self.signing_key.to_bytes());
+        seed[0] = seed[0].wrapping_add(1);
+        Self {
+            signing_key: p256::ecdsa::SigningKey::from_bytes(&seed.into())
+                .expect("failed to build a browser key"),
+        }
+    }
+
+    pub fn public_key(&self) -> PublicKey {
+        let point = p256::ecdsa::VerifyingKey::from(&self.signing_key).to_encoded_point(false);
+        let mut der = P256_SPKI_HEADER.to_vec();
+        der.extend_from_slice(point.as_bytes());
+        ByteBuf::from(der)
+    }
+
+    pub fn sign(&self, session_key: &SessionKey, next_browser_key: &PublicKey) -> ByteBuf {
+        self.sign_with(BROWSER_KEY_SIGNATURE_DOMAIN, session_key, next_browser_key)
+    }
+
+    /// The successor's own signature, proving the browser holds the key it announces.
+    pub fn sign_as_successor(&self, session_key: &SessionKey, device_key: &PublicKey) -> ByteBuf {
+        self.sign_with(SUCCESSOR_KEY_SIGNATURE_DOMAIN, session_key, device_key)
+    }
+
+    fn sign_with(&self, domain: &[u8], session_key: &SessionKey, other: &PublicKey) -> ByteBuf {
+        use p256::ecdsa::signature::Signer;
+
+        let mut message = domain.to_vec();
+        message.extend_from_slice(session_key);
+        message.extend_from_slice(other);
+        let signature: p256::ecdsa::Signature = self.signing_key.sign(&message);
+        ByteBuf::from(signature.to_bytes().to_vec())
+    }
+}
+
 pub const PUBKEY_1: &str = "test";
 pub const PUBKEY_2: &str = "some other key";
 pub const RECOVERY_PUBKEY_1: &str = "recovery 1";

src/frontend/src/lib/generated/internet_identity_idl.js

@@ -386,6 +386,26 @@ export const idlFactory = ({ IDL }) => {
     'InternalCanisterError' : IDL.Text,
     'Unauthorized' : IDL.Principal,
   });
+  const GetAccountSessionRequest = IDL.Record({
+    'session_id' : IDL.Nat64,
+    'session_key' : SessionKey,
+    'origin' : FrontendHostname,
+    'account_number' : IDL.Opt(AccountNumber),
+    'expiration' : Timestamp,
+    'identity_number' : UserNumber,
+  });
+  const GetAccountSessionResponse = IDL.Record({
+    'signed_delegation' : SignedDelegation,
+  });
+  const AccountSessionError = IDL.Variant({
+    'InternalCanisterError' : IDL.Text,
+    'Unauthorized' : IDL.Principal,
+    'NoSuchSession' : IDL.Null,
+    'NoSuchDelegation' : IDL.Null,
+    'NoSuchAccount' : IDL.Null,
+    'InvalidBrowserKey' : IDL.Null,
+    'StaleBrowserKey' : IDL.Null,
+  });
   const GetAccountsError = IDL.Variant({
     'InternalCanisterError' : IDL.Text,
     'Unauthorized' : IDL.Principal,
@@ -718,6 +738,27 @@ export const idlFactory = ({ IDL }) => {
     'user_key' : UserKey,
     'expiration' : Timestamp,
   });
+  const PrepareAccountSessionRequest = IDL.Record({
+    'permissions' : IDL.Opt(Permissions),
+    'max_idle' : IDL.Opt(IDL.Nat64),
+    'current_browser_key' : PublicKey,
+    'session_key' : SessionKey,
+    'valid_for' : IDL.Opt(IDL.Nat64),
+    'origin' : FrontendHostname,
+    'current_browser_key_signature' : IDL.Vec(IDL.Nat8),
+    'browser_description' : BrowserDescription,
+    'account_number' : IDL.Opt(AccountNumber),
+    'identity_number' : UserNumber,
+    'next_browser_key' : PublicKey,
+    'next_browser_key_signature' : IDL.Vec(IDL.Nat8),
+  });
+  const PrepareAccountSessionResponse = IDL.Record({
+    'user_key' : PublicKey,
+    'session_id' : IDL.Nat64,
+    'browser_id' : IDL.Nat32,
+    'expiration' : Timestamp,
+    'account_principal' : IDL.Principal,
+  });
   const PrepareAttributeRequest = IDL.Record({
     'origin' : FrontendHostname,
     'attribute_keys' : IDL.Vec(IDL.Text),
@@ -1071,6 +1112,16 @@ export const idlFactory = ({ IDL }) => {
         ],
         ['query'],
       ),
+    'get_account_session' : IDL.Func(
+        [GetAccountSessionRequest],
+        [
+          IDL.Variant({
+            'Ok' : GetAccountSessionResponse,
+            'Err' : AccountSessionError,
+          }),
+        ],
+        ['query'],
+      ),
     'get_accounts' : IDL.Func(
         [UserNumber, FrontendHostname],
         [
@@ -1327,6 +1378,16 @@ export const idlFactory = ({ IDL }) => {
         ],
         [],
       ),
+    'prepare_account_session' : IDL.Func(
+        [PrepareAccountSessionRequest],
+        [
+          IDL.Variant({
+            'Ok' : PrepareAccountSessionResponse,
+            'Err' : AccountSessionError,
+          }),
+        ],
+        [],
+      ),
     'prepare_attributes' : IDL.Func(
         [PrepareAttributeRequest],
         [

src/frontend/src/lib/generated/internet_identity_types.d.ts

@@ -19,6 +19,32 @@ export interface AccountInfo {
   'last_used' : [] | [Timestamp],
 }
 export type AccountNumber = bigint;
+export type AccountSessionError = { 'InternalCanisterError' : string } |
+  { 'Unauthorized' : Principal } |
+  { 'NoSuchSession' : null } |
+  {
+    /**
+     * The session is there, but no delegation was signed for the session_key and
+     * expiration asked for. Ask again with the ones prepare_account_session returned;
+     * signing in afresh is not the remedy.
+     */
+    'NoSuchDelegation' : null
+  } |
+  { 'NoSuchAccount' : null } |
+  {
+    /**
+     * The browser's key is unusable, or its signature does not verify against it.
+     */
+    'InvalidBrowserKey' : null
+  } |
+  {
+    /**
+     * The browser presented a key it has already rotated away from, which happens when it
+     * never learned that its last sign-in succeeded. It holds the successor that does
+     * resolve, so the answer is to promote that one and present it.
+     */
+    'StaleBrowserKey' : null
+  };
 export interface AccountUpdate { 'name' : [] | [string] }
 export type AddTentativeDeviceResponse = {
     /**
@@ -696,6 +722,20 @@ export type GetAccountError = {
       'anchor_number' : UserNumber,
     }
   };
+export interface GetAccountSessionRequest {
+  /**
+   * The session prepare_account_session created.
+   */
+  'session_id' : bigint,
+  'session_key' : SessionKey,
+  'origin' : FrontendHostname,
+  'account_number' : [] | [AccountNumber],
+  'expiration' : Timestamp,
+  'identity_number' : UserNumber,
+}
+export interface GetAccountSessionResponse {
+  'signed_delegation' : SignedDelegation,
+}
 export type GetAccountsError = { 'InternalCanisterError' : string } |
   { 'Unauthorized' : Principal };
 export type GetAttributesError = { 'AuthorizationError' : Principal } |
@@ -1334,6 +1374,76 @@ export interface PrepareAccountDelegation {
   'user_key' : UserKey,
   'expiration' : Timestamp,
 }
+export interface PrepareAccountSessionRequest {
+  /**
+   * The consented access level, fixed for the session's life.
+   */
+  'permissions' : [] | [Permissions],
+  /**
+   * How long the session may go unminted before it is over, clamped to between
+   * 10 minutes and the session's own granted length. Absent leaves the
+   * canister's own default.
+   */
+  'max_idle' : [] | [bigint],
+  /**
+   * The browser's own public key, DER-encoded, as the registry currently holds it. A
+   * key this anchor has not seen registers a browser under it.
+   */
+  'current_browser_key' : PublicKey,
+  /**
+   * The II frontend's own public key.
+   */
+  'session_key' : SessionKey,
+  /**
+   * Clamped to the session maximum.
+   */
+  'valid_for' : [] | [bigint],
+  'origin' : FrontendHostname,
+  /**
+   * Signature over session_key and next_browser_key, verified with current_browser_key.
+   */
+  'current_browser_key_signature' : Uint8Array | number[],
+  /**
+   * What this browser is, for the user's session list.
+   */
+  'browser_description' : BrowserDescription,
+  'account_number' : [] | [AccountNumber],
+  'identity_number' : UserNumber,
+  /**
+   * What the browser rotates to once this sign-in succeeds. Must differ from
+   * current_browser_key: a browser that never rotates keeps a leaked key useful.
+   */
+  'next_browser_key' : PublicKey,
+  /**
+   * Signature by next_browser_key over session_key and current_browser_key, proving the
+   * browser holds the key it is announcing.
+   */
+  'next_browser_key_signature' : Uint8Array | number[],
+}
+export interface PrepareAccountSessionResponse {
+  'user_key' : PublicKey,
+  /**
+   * Names the session this ceremony created, and is what get_account_session is given
+   * to collect the delegation signed for it. Not a credential: it names a session, it
+   * does not authorise one.
+   */
+  'session_id' : bigint,
+  /**
+   * Which browser this sign-in was attributed to, so the settings list can mark the one
+   * the user is looking at, and so the browser knows which registration its key now
+   * belongs to. Not a credential: a caller never presents it.
+   */
+  'browser_id' : number,
+  /**
+   * The session's valid_till.
+   */
+  'expiration' : Timestamp,
+  /**
+   * The principal apps see for this account, so the frontend can tell its own
+   * sessions apart without minting a delegation to learn it.
+   */
+  'account_principal' : Principal,
+}
 export type PrepareAttributeError = { 'AuthorizationError' : Principal } |
   { 'ValidationError' : { 'problems' : Array<string> } } |
   { 'GetAccountError' : GetAccountError };
@@ -2103,6 +2213,11 @@ export interface _SERVICE {
     { 'Ok' : SignedDelegation } |
       { 'Err' : AccountDelegationError }
   >,
+  'get_account_session' : ActorMethod<
+    [GetAccountSessionRequest],
+    { 'Ok' : GetAccountSessionResponse } |
+      { 'Err' : AccountSessionError }
+  >,
   /**
    * Multiple accounts
    */
@@ -2395,6 +2510,17 @@ export interface _SERVICE {
     { 'Ok' : PrepareAccountDelegation } |
       { 'Err' : AccountDelegationError }
   >,
+  /**
+   * Creates or reuses a revocable session at one account and signs its identity to
+   * the II frontend's own key. Called only by the II frontend, which ships with the
+   * canister; requires an anchor access method, so a session can neither spawn nor
+   * extend itself.
+   */
+  'prepare_account_session' : ActorMethod<
+    [PrepareAccountSessionRequest],
+    { 'Ok' : PrepareAccountSessionResponse } |
+      { 'Err' : AccountSessionError }
+  >,
   /**
    * Attribute sharing protocol
    * ==========================