feat: docs landing page — Phase platform diagram

public/access-control/authentication/account.md

@@ -0,0 +1,105 @@
+import { Tag } from '@/components/Tag'
+import { DocActions } from '@/components/DocActions'
+
+export const description = 'Manage your Phase account: linked sign-in methods, email address, display name, and account deletion.'
+
+<Tag variant="small">AUTHENTICATION</Tag>
+
+# Account Management
+
+The Account page lets you manage everything about how you sign in to Phase. It is personal to you and applies across all of your organisations. Open it from the user menu in the top right corner of the Console: click your avatar, then click your profile card (your name and email) at the top of the menu.
+
+![The profile card in the user menu opens the Account page](/assets/images/auth/account/user-menu.png)
+
+<DocActions />
+
+![The Account page](/assets/images/auth/account/account-page.png)
+
+## Sensitive action re-authentication
+
+Changes to your sign-in methods, email address, two-factor authentication, and account deletion require a recent sign-in. The default window is 15 minutes. Self-hosted operators can tune it with the [`AUTH_FRESHNESS_MAX_AGE_SECONDS`](/self-hosting/configuration/envars#additional-environment-variables) environment variable.
+
+If your last sign-in is older than that, a **Confirm it's you** dialog appears when you start the change. You can cancel, or sign in again to continue. This limits what a stolen or unattended session can do.
+
+![Confirm it's you dialog](/assets/images/auth/account/reauth-dialog.png)
+
+The login page shows why you are back, and offers only the sign-in methods linked to your account.
+
+![Login page during re-authentication](/assets/images/auth/account/reauth-login.png)
+
+Signing in again does not lose your place. Phase returns you to the Account page and restores the interrupted flow: the same dialog, the same step, and anything you had entered. Codes and passwords are never carried over, so you enter them again.
+
+## Sign-in methods
+
+Your account can have multiple sign-in identities linked to it, for example a Google account and a Microsoft Entra ID identity. You can sign in with any linked identity, and they all resolve to the same Phase account, keyrings, and organisation memberships.
+
+### Linking a new sign-in method
+
+1. On the Account page, find **Sign-in methods**. Providers configured on your instance are shown, along with any organisation-level SSO providers for organisations you are a member of. Active methods show a badge: *Linked* for identities, *Enabled* for a password.
+2. Hover the card of an unlinked provider and click **Link**.
+3. Authenticate with the provider. You will be returned to the Account page with the new identity linked.
+
+Identities are matched by the provider's stable account ID, not by email address. **The email on the linked identity does not need to match your Phase account email.** This makes linking the right tool for moving to a new identity provider. For example: you signed up with Google, and your organisation later adopts Microsoft Entra ID SSO. Link your Entra ID identity from the Account page, and you can sign in with either from then on.
+
+<Note>
+If you see *"An account with this email already exists"* when signing in with a new provider, this is Phase's account takeover protection: a new sign-in identity is never automatically attached to an existing account based on a matching email. Sign in with your existing method and link the new provider from the Account page instead. If you hold a pending invite to the organisation, the message directs you to accept the invite with your existing sign-in method first. The organisation's SSO works after you join.
+</Note>
+
+Linking an identity that is already attached to a different Phase account is refused. Phase never merges accounts. Linking is also refused when the provider reports the identity's email as unverified. Verify it with your provider first, then try again.
+
+You will receive an email notification whenever a sign-in method is linked to or unlinked from your account.
+
+### Migrating an organisation to enforced SSO
+
+If your organisation plans to [enforce SSO](/access-control/authentication/sso#enforce-sso), have every member link the new provider from their Account page **before** enforcement is switched on. Members who have not linked the organisation's provider cannot sign in to the organisation after enforcement. Admins can track linking progress in the organisation's audit log. Each link creates a member audit event.
+
+### Unlinking a sign-in method
+
+Hover the card of a linked identity, click **Unlink**, and confirm. You can no longer sign in with that identity afterwards. Unlinking is blocked when:
+
+- It is your **only** sign-in method (a password counts as a method when password authentication is enabled on the instance).
+- The identity belongs to an organisation SSO provider that is currently **enforced** for an organisation you are a member of.
+- Your membership is **SCIM-provisioned**. Your identity provider is the source of truth for your access.
+
+## Display name
+
+Your name and profile picture are initially taken from the identity provider you first signed up with. To set a custom display name, click the pencil icon next to your name on the Account page. A custom name takes precedence over provider-reported names and is used in emails and member lists. It survives unlinking the identity it originally came from.
+
+## Changing your email address
+
+Your account email is used for sign-in identification, notifications, and organisation invites. To change it:
+
+1. Click the pencil icon next to your email address on the Account page.
+2. Enter the new address. Phase sends a verification code to it. The code is valid for 15 minutes.
+3. Enter the code, along with your password (or sudo password if your account has no login password), to confirm the change.
+
+The new address does not need to match a linked sign-in identity. An address already used by another account is refused. On self-hosted instances with an [email domain allowlist](/self-hosting/configuration/envars), the new address must be in the allowlist. A security alert is sent to your **old** address whenever the change completes.
+
+<Note>
+Your account email is a cryptographic input to your local device key. Confirming the change therefore re-encrypts your account keyrings for **all** of your organisations in one step. This is why your password or sudo password is required. Nothing changes about your organisation keys or secrets; only the encrypted wrapper is rotated.
+</Note>
+
+Email changes are not available for SCIM-provisioned accounts, where the identity provider manages the email address.
+
+On self-hosted instances without an [email gateway](/self-hosting/configuration/envars#email-gateway-configuration) configured (or with `SKIP_EMAIL_VERIFICATION` set), the verification code step is skipped, the same convention as password signup.
+
+## Deleting your account
+
+You can permanently delete your Phase account from the **Delete account** section on the Account page. Deletion is immediate and irreversible: your organisation memberships, encryption keys, personal access tokens, and personal data are permanently removed.
+
+Deletion is blocked while:
+
+- You are the **only owner** of an organisation. [Transfer ownership](/console/organisation) to another member first. Organisations with another owner do not block deletion.
+- Your account is **SCIM-provisioned** in any organisation. Ask your administrator to deprovision you from the identity provider instead.
+
+On self-hosted instances, accounts with Django staff or superuser access cannot be deleted from the Console.
+
+When deletion completes, Phase sends a confirmation email to the deleted address.
+
+To confirm deletion, type your email address into the confirmation dialog.
+
+<Note>
+Organisation audit logs are preserved for compliance. Events you performed remain in your organisations' logs, with the actor shown as *"Deleted account"*. Your account and its personal data are removed. Audit records can still contain identifying fields captured at the time of each event.
+</Note>
+
+Any active dynamic secret leases you hold are revoked at the provider before your account is removed. Existing service account tokens and organisation resources you created (network policies, service tokens) are unaffected: they belong to the organisation, not to you.

public/access-control/authentication/mfa.md

@@ -0,0 +1,72 @@
+import { Tag } from '@/components/Tag'
+import { DocActions } from '@/components/DocActions'
+
+export const description = 'Protect your Phase account with TOTP-based two-factor authentication.'
+
+<Tag variant="small">AUTHENTICATION</Tag>
+
+# Two-Factor Authentication (2FA)
+
+Phase supports two-factor authentication using time-based one-time passwords (TOTP) with any standard authenticator app. Once enabled, every Console sign-in to your account (password, OAuth, or SSO) requires a 6-digit code from your authenticator in addition to your primary sign-in method.
+
+<DocActions />
+
+<Note>
+Two-factor authentication protects **Console sign-in** only. Personal access tokens, service tokens, and CLI, API, and SDK access are not affected: existing and new tokens keep working without a code.
+</Note>
+
+## Enable 2FA
+
+1. Open the user menu in the top right corner of the Console and click your profile card to open the [Account page](/access-control/authentication/account).
+2. Under **Two-factor authentication**, click **Enable**. You may be asked to confirm it's you first: sensitive account changes require a recent session. You are returned to setup after signing in again.
+3. Scan the QR code with your authenticator app, or copy the setup secret shown below the QR code and add it manually.
+
+   ![2FA setup: scan the QR code or copy the secret](/assets/images/auth/account/totp-setup-1.png)
+
+4. Enter the 6-digit code from your app to confirm. 2FA is only activated once a code has been verified.
+
+   ![2FA setup: confirm with a 6-digit code](/assets/images/auth/account/totp-setup-2.png)
+
+5. Save your **recovery codes**: reveal, copy, or download them before finishing. They are shown only once.
+
+Once enabled, the Account page shows the TOTP status and your remaining recovery codes.
+
+![TOTP enabled on the Account page](/assets/images/auth/account/totp-enabled.png)
+
+Phase sends you an email notification when 2FA is enabled, when it is disabled, and when you regenerate your recovery codes.
+
+## Signing in with 2FA
+
+After your primary sign-in method succeeds (entering your password, or completing the OAuth/SSO round trip), Phase prompts for a 6-digit code from your authenticator app. The code is accepted with a small clock-skew tolerance (one 30-second step in either direction), and each code can only be used once.
+
+2FA applies uniformly to **all** of your sign-in methods, including organisation-level SSO. If your identity provider also performs its own MFA, you will complete both. Phase does not skip its challenge based on upstream MFA claims.
+
+Enter the code within 10 minutes of your primary sign-in. After that the challenge expires and you sign in again from the start.
+
+After 10 incorrect codes, verification is locked until 15 minutes after the first failed attempt.
+
+## Recovery codes
+
+When you enable 2FA, Phase generates 10 single-use recovery codes. Each can be used once in place of an authenticator code (including at sign-in via the *Use a recovery code* option) if you lose access to your device.
+
+- Store them somewhere safe (a password manager or printed copy). They are displayed only at generation time.
+- Your remaining code count is shown on the Account page, with a warning when you are running low.
+- Regenerate a fresh set at any time from the Account page. Under **Two-factor authentication**, hover the TOTP card and click **Manage**, then **Regenerate recovery codes**. This invalidates all previous codes and requires a current authenticator code or an unused recovery code.
+
+<Note>
+Recovery codes protect your **sign-in**, not your encrypted data. Your secrets remain protected by your sudo password and recovery kit. Keep both independently safe.
+</Note>
+
+## Disable 2FA
+
+On the Account page, under **Two-factor authentication**, hover the TOTP card and click **Manage**, then **Disable two-factor authentication**. Enter a current authenticator code or an unused recovery code to confirm. Signing in no longer requires a code afterwards, and your remaining recovery codes are invalidated.
+
+If you have lost both your authenticator device and your recovery codes, you cannot disable 2FA yourself. Contact your instance administrator (self-hosted) or Phase support (cloud).
+
+## Security notes
+
+- TOTP follows RFC 6238 with standard parameters (SHA-1, 6 digits, 30-second period) for maximum authenticator app compatibility.
+- The TOTP seed is encrypted at rest with the server's keypair and is only shown once, during setup.
+- Replay protection: each accepted code advances a per-account high-water mark, so an intercepted code cannot be used a second time even within its validity window.
+- Recovery codes are stored as salted Argon2id hashes; the plaintext is never persisted.
+- Brute-force protection: per-account attempt limits are enforced server-side, alongside IP-based rate limiting on the verification endpoint.

public/access-control/authentication/oauth-sso.md

@@ -96,10 +96,10 @@ You can find detailed official instructions for setting up SSO with a Google OAu
 
 Follow these steps to set up GitHub SSO for your Phase application:
 
-If you are using GitHub Enterprise Server (self-hosted) instance, you may follow the steps below to set up GitHub SSO for your Phase application as the instructions are nearly identical. The only exception being the Authorization callback URL.
+If you are using a GitHub Enterprise Server (self-hosted) instance, you may follow the steps below to set up GitHub SSO for your Phase application as the instructions are nearly identical. The only exception being the Authorization callback URL.
 
 <Note>
-   GitHub Enterprise Server (self-hosted) instance for OAuth SSO is only available for organizations with an `Enterprise` tier subscription. See [Pricing](https://phase.dev/pricing).
+   A GitHub Enterprise Server (self-hosted) instance for OAuth SSO is only available for organizations with an `Enterprise` tier subscription. See [Pricing](https://phase.dev/pricing).
 </Note>
 
 1. Log in to your GitHub account and go to [OAuth Apps](https://github.com/settings/applications/new) in Developer Settings.
@@ -185,7 +185,7 @@ Make sure the application has the `read_user` scope. This grants read-only acces
 6. Supply these credentials to your Phase Console deployment as [environment variables](/self-hosting/configuration/envars#git-lab-sso).
 
 <Note>
-  You can use user-owned or group-owned applications to login to Phase. If you are running a self-hosted instance, you can also use an instance-wide application.
+  You can use user-owned or group-owned applications to log in to Phase. If you are running a self-hosted instance, you can also use an instance-wide application.
 </Note>
 
 You can find detailed official instructions for setting up SSO with a GitLab OAuth Application [here](https://docs.gitlab.com/ee/integration/oauth_provider.html). 

public/access-control/authentication/oidc-sso.md

@@ -78,7 +78,7 @@ Follow these steps to set up Google SSO for your Phase application:
 
 14. In the Application type dropdown, select **Web application**. Enter a recognizable name in the **Name** field, add the **Authorized redirect URI** (e.g., https://[**YOUR_DOMAIN**].com/api/auth/callback/google-oidc), and click **CREATE**.
 
-   You can copy the following path, please make sure to pre-fix it with scheme + your domain.
+   You can copy the following path, please make sure to prefix it with scheme + your domain.
 
    ```
    /api/auth/callback/google-oidc
@@ -129,7 +129,7 @@ You can use JumpCloud as an OIDC provider to set up SSO for your Phase instance.
 
 8. Add your Phase application's **Redirect URI** (e.g., https://[**YOUR_DOMAIN**].com/api/auth/callback/jumpcloud-oidc) and **Login URL**.
 
-   You can copy the following path, please make sure to pre-fix it with scheme + your domain.
+   You can copy the following path, please make sure to prefix it with scheme + your domain.
 
    ```
    /api/auth/callback/jumpcloud-oidc
@@ -141,7 +141,7 @@ You can use JumpCloud as an OIDC provider to set up SSO for your Phase instance.
 
    ![Select Standard Scopes](/assets/images/auth/sso/oidc/jumpcloud/9-select-email-profile-from-standard-scope.png)
 
-10. Click the **Activate** button at the bottom right of screen to enable the application.
+10. Click the **Activate** button at the bottom right of the screen to enable the application.
 
     ![Activate Application](/assets/images/auth/sso/oidc/jumpcloud/10-click-activate.png)
 
@@ -367,6 +367,10 @@ You can use Okta as an OIDC provider to set up SSO for your Phase instance. Foll
 
     ![Copy Okta OIDC Issuer Host](/assets/images/auth/sso/oidc/okta/7-copy-okta-oidc-issuer-host.png)
 
+    <Note>
+    From inside the Okta admin console, the drop-down can show the admin host (`…-admin.okta.com`). Remove the `-admin` suffix: the issuer is the org domain. Okta issues tokens under the org domain, and Phase rejects an admin-host issuer at save time.
+    </Note>
+
 You now have the three values needed to configure Phase — **Issuer URL**, **Client ID**, and **Client Secret**. See the **Per-organisation** / **Instance-wide** tabs below for where to plug them in.
 
 <TabGroup title="Where to plug in the credentials" slug="okta-config">

public/access-control/authentication/password.md

@@ -27,9 +27,11 @@ Phase uses an email-first login flow. Enter your email address, and the system w
 - If your account uses a password, you will be prompted to enter it.
 - If your organisation uses SSO, you will be redirected to your identity provider.
 
+If [two-factor authentication](/access-control/authentication/mfa) is enabled on your account, you will also be prompted for a code from your authenticator app. Your email address and other sign-in settings can be managed from the [Account page](/access-control/authentication/account).
+
 ## Password change
 
-You can change your password from **Settings > Account**. Changing your password re-encrypts all organisation keyrings to ensure continued end-to-end encryption with your new credentials.
+You can change your password from **Settings > Account & Security** in any of your organisations. Changing your password re-encrypts all organisation keyrings to ensure continued end-to-end encryption with your new credentials.
 
 ## Account recovery