Account security and recovery

Account-security commands read passwords, TOTP codes, and authorities from the controlling terminal. They do not accept those secrets as flags.

Edit your profile in the web appCopy Anchor Link

Open Account & security, then Profile. Set your display name and username, then select Save profile. A username change also asks for an authenticator code if enrolled, otherwise your current password.

Use the new username for future password sign-ins. Existing permissions and sessions stay attached to the same account. Your display name identifies you in the interface; names are labels and do not grant access.

The email shown on your profile is read-only and shown in canonical form (domain lowercased). A sign-in email is set only when you register through verified local sign-up, and only a verified address is used to sign in. An account upgraded from an earlier version keeps the contact address it had, if that address was valid, shown as a contact email: it was never verified, so it is not used to sign in, does not reserve the address, and is cleared if someone else later verifies that address. No email is ever an account-linking key or a password-recovery channel. Accounts without one show no email field. For provisioned accounts, change the username and display name through the identity provider; the web app keeps the display name read-only and hides the internal username. Accounts that sign in only through a provider can still edit their display name without a local password.

Enrol TOTPCopy Anchor Link

Start enrolment while logged in:

hikyo account factor enrol-totp \
  --output-file ./hikyo-otpauth-uri

The CLI prompts for the current password, stages enrolment, and delivers the provisioning URI once. Import it into an authenticator, then confirm:

hikyo account factor confirm-totp

The confirmation code is prompted with terminal echo disabled. Confirmation rotates the acting session and stores the replacement token locally.

Delete the provisioning file after the authenticator is confirmed. Anyone who retains its seed can generate future codes.

Step up a sessionCopy Anchor Link

Some operations require recent multi-factor assurance:

hikyo account factor step-up
hikyo whoami

Step-up prompts for a TOTP code, rotates the session, and reports the active factors. The previous session token is dead when the server responds.

Generate recovery codesCopy Anchor Link

hikyo account recovery-codes regenerate \
  --output-file ./hikyo-recovery-codes

The CLI prompts for TOTP, or the password when no factor exists. It replaces the whole recovery-code batch atomically and rotates the session.

Store codes outside the device that holds the password and authenticator. Each code is single-use. Regeneration immediately voids every old code.

Recover with a codeCopy Anchor Link

From a trusted client with no active session:

If this client has not established the HTTPS origin yet, first run hikyo context create recovery --instance https://hikyo.example.com --tls-mode system-ca and confirm its trust policy. Use explicit --tls-mode spki when independently verifying a private leaf fingerprint. Existing stored or protected provisioned trust remains usable without a new mode flag.

hikyo account recovery begin \
  --instance https://hikyo.example.com \
  --as alice \
  --output-file ./hikyo-recovery-authority

The CLI prompts for one recovery code and returns a single-use credential authority. It does not create a session.

In the browser, the sign-in page’s Lost your second factor? Recover with a code entry takes the username and one code, then hands the authority straight into the establish form so you choose a new password in the same visit. A wrong code, a used batch and an unknown username are one sentence: the page is not an oracle.

Establish the replacement password from the controlling terminal:

hikyo account establish-credential \
  --instance https://hikyo.example.com \
  --as alice

Then delete the authority and log in normally. Neither the authority nor the new password may cross argv, an environment variable, or a pipe.

Administrator resetCopy Anchor Link

A network administrator with the required capability can issue an authority:

hikyo account reset-credential <principal-id> \
  --output-file ./hikyo-reset-authority

Deliver it to the account holder out of band. Issuing it revokes that account’s sessions. The holder consumes it with account establish-credential.

Targets holding an instance-scoped capability have no network reset path. Use the audited host-only hikyo admin reset-credential break-glass command.

PasskeysCopy Anchor Link

Passkey enrolment, listing, and removal are browser-only in the current build. The CLI refuses hikyo account passkey ... instead of silently substituting a different ceremony.