Local passwords and recovery

Local password sign-in is always available and needs no provider configuration. Use it for a standalone household, as the initial human credential, or as a deliberately retained fallback when external identity is unavailable.

Jiandu stores Argon2id verifiers, never recoverable password text. Unknown usernames, suspended members, malformed submissions, and wrong passwords perform equivalent expensive verification work and return the same outward failure. Interactive attempts and password hashing are also bounded so one client cannot consume unbounded CPU.

Configure the session and recovery files

The defaults are suitable for most household deployments:

/etc/jiandu/jiandu.json

{
  "schema_version": 1,
  "auth": {
    "owner_token_path": "/var/lib/jiandu/owner-access-token",
    "session_ttl_seconds": 604800,
    "rotate_after_seconds": 86400,
    "revoked_retention_seconds": 86400
  }
}

Setting	Default	Why it exists
owner_token_path	jiandu-data/owner-access-token	Location of the installation's break-glass credential. Jiandu creates it with owner-only permissions on first startup. Keep an offline copy outside the database/storage backup.
session_ttl_seconds	604800 (7 days)	Maximum browser-session lifetime. Shorten it on shared devices; increasing it extends the usefulness of a stolen cookie. Maximum 30 days.
rotate_after_seconds	86400 (1 day)	Age after which an accepted session is replaced with a new opaque credential. It must be positive and no longer than the session lifetime.
revoked_retention_seconds	86400 (1 day)	How long revoked-session records remain available for replay detection and cleanup. Zero removes that retention; longer values cost database rows. Maximum 30 days.

The directory containing owner_token_path must be private and durable. Do not place the only copy inside an ephemeral container layer. The Owner token is intentionally excluded from recovery backups and should never appear in an environment variable, URL, command argument, log, ticket, or chat transcript.

Bootstrap the first human

The current browser does not create the first local account. For the reviewed Compose deployment, run the repository helper from its root:

./examples/docker-compose/bootstrap-local-account.sh

For the default source launcher, use:

./scripts/bootstrap-local-account.sh

Both helpers read secrets without putting them in command arguments, create a normal human account, claim installation administration, verify the resulting session, and revoke their temporary sessions. Read the quickstart explanation before adapting either helper to a custom deployment.

Password and username rules

• Usernames are 3–64 ASCII letters, digits, ., _, or -; surrounding whitespace is removed and uniqueness is case-insensitive.
• Passwords are 12–1024 UTF-8 bytes with no control characters.
• Obvious common values, sequences/repetitions, and values derived from the username are refused.
• A unique password-manager-generated passphrase is preferable to satisfying only the minimum.

A member may replace an existing local password. Only the installation Owner—not an ordinary Administrator—may reset another person's password or establish the first local password for an external-only account. This prevents a delegated administrator from impersonating someone who has private document grants, and prevents a person removed from an external admission group from self-provisioning a bypass.

Changing a password revokes all browser sessions and personal access tokens for that person. Plan automation token replacement as part of a recovery reset.

Operate a safe fallback

Keep at least two distinct recovery layers:

1. one named human Administrator with a tested credential; and
2. the Owner token in protected offline storage.

Do not treat the Owner token as a shared administrator password. Use it only to recover access, then return to a named human account so ordinary actions have useful attribution.

Validate the configured lifetime bounds and confirm local password remains advertised:

jiandu --config /etc/jiandu/jiandu.json --check-config
curl --fail --silent https://documents.example.net/api/v1/auth/methods \
  | jq '.localPassword, .localOwnerToken'

If every password attempt returns 429, respect the backoff and investigate repeated clients; do not restart Jiandu merely to clear admission pressure. If the owner file is rejected at startup, check that it is a single regular file with exact mode 0600 rather than weakening its permissions.