Repository source: docs/plans/automatic_guest_identity/automatic_guest_identity_step2_feature_description.md

Feature plan: Step 1 · Step 2 · Step 3 · Step 4

Automatic Guest Identity — Step 2: Feature Description

Problem

First-time visitors must begin a signed action and choose a username before a browser identity exists, delaying the interaction they intended to perform.

User Stories

As an operator, I want to enable automatic guest-key preparation so that visitors can interact without a first-action username prompt.
As a visitor, I want an automatically prepared guest identity to remain browser-local so that the site never receives my private key.
As a visitor, I want to choose whether that guest public key is published immediately or on first use so that I control when an unused identity becomes public.

Core Requirements

A default-off, operator-managed site flag enables automatic guest-key preparation for browsers without a keypair.
When enabled, the browser creates a usable guest identity without showing a username prompt and never replaces an existing browser keypair.
A per-browser user setting selects immediate publication or deferred publication on the first signed use; deferred publication is the default.
The first signed action waits for any in-progress automatic preparation, publishes when required, and completes through the existing signed-action flow.
Failures leave the visitor able to retry through the existing account-key recovery path and do not expose private key material.

Delivery Scope

Work type: application change.
Completion boundary: A normal site visit with the operator flag enabled creates a browser-local guest identity; immediate-publication preference completes publication in the background, while deferred preference publishes on the first signed action. Existing-key browsers are unchanged. A failed generation or publication shows existing actionable recovery, and release requires automated coverage of both preference paths plus operator-flag rendering.

Risks

Background key generation slows initial interaction. Validate with a fresh-browser manual smoke test early; run it asynchronously and ensure action flows wait safely.
Immediate publication can create unused public identities. Validate the deferred default in browser coverage; state the consequence clearly beside the user setting.
A static or cached page may carry stale operator configuration. Validate rendered runtime configuration through the existing asset/static-release path; use the current feature-flag rendering contract.
Concurrent preparation and first use can race. Validate with a focused automated overlap case; reuse the canonical identity-preparation coordination and recovery behavior.

Shared Component Inventory

Site feature-flag registry and Tools feature-flags page: extend the canonical operator setting; no parallel configuration surface.
Layout runtime configuration: extend the existing server-to-browser settings surface so dynamic and rendered pages agree.
Browser signing and identity preparation: reuse as the sole key-generation, publication, synchronization, and first-use path.
Account Key page: extend the existing browser-identity controls with the per-browser publication preference; no new account page.
Existing identity publication APIs and recovery messages: reuse unchanged; no new private-key API or identity storage model.

Simple User Flow

An operator enables automatic guest-key preparation for the site.
A visitor without a browser keypair opens a normal site page and receives a browser-local guest identity without a prompt.
If the visitor selected immediate publication, the public key is published in the background; otherwise it remains local.
The visitor starts a signed action; deferred identities publish first, then the action continues normally.
If setup fails, the visitor can retry or manage the identity from Account Key.

Success Criteria

With the operator flag off, fresh browsers retain the current first-action setup behavior.
With it on, a fresh browser receives exactly one guest keypair without a username prompt, and an existing keypair is preserved.
Deferred publication makes no identity-publication request until the first signed action; immediate publication does so during automatic preparation.
Both publication choices complete a first signed action successfully, and automated tests cover normal, deferred, immediate, existing-key, and preparation-failure behavior.