relicario/docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md

v0.5.0 — Polish + Harden — Design

Date: 2026-05-02 Status: Draft

Overview

v0.5.0 is a "polish + harden" bundle: a security-vulnerability fix, two hardening follow-ups, two confirmed bugs, and four UX improvements. No new functional features. Functional work — LastPass import, recovery QR, Plan 1C-γ, Fullscreen Phases 3/4 — proceeds on parallel plans.

The anchor item is a HIGH-severity authentication bypass in relicario-server's pre-receive hook (S1): both the registered-device check and the revocation check are unimplemented. Until this lands, the device-auth system is a no-op.

Goals

1. Restore device-auth integrity: only registered, non-revoked signing keys can push to the vault repo.
2. Close two minor hardening gaps surfaced during the security review.
3. Fix two user-visible bugs (strength-meter desync after generate, raw error codes in the fullscreen tab).
4. Deliver four UX improvements that are polish-shaped, not feature-shaped.
5. Tag v0.5.0 with no known security vulnerabilities or visible-error-code leaks.

Scope Map

Bucket	Item	Plan
Security	S1: Pre-receive hook fix	A
Security	S2: Tar archive path-traversal hardening	A
Security	S3: RELICARIO_* env-var audit	A
Cleanup	C1: Stale feature branch prune	A
Bugs	B1: Strength meter desync after regenerate	B
Bugs	B2: vault_locked raw error code in fullscreen tab	B (subsumed by P4)
UX	P1: Password coloring	B
UX	P2: Setup-wizard completion → fullscreen vault tab	B
UX	P3: Form-layout 2-col → full-width transition	B
UX	P4: Error-message audit (snake_case codes → friendly copy)	B

Two plans split by language/blast-radius:

• Plan A = Rust + docs (server, CLI, env-var audit, branch cleanup)
• Plan B = Extension UX (TypeScript + CSS)

The plans share no files and can ship independently.

---

Plan A — Security + Cleanup

S1. Pre-Receive Hook Fix (anchor)

Problem. crates/relicario-server/src/main.rs:36-81: verify_commit loads devices and revoked from the repo at the commit, then drops both on the floor. It runs git verify-commit --raw and accepts on GOODSIG / Good signature regardless of which key produced the signature. This means:

• An attacker who never registered a device can push commits signed with any GPG key that the server's keyring/allowed-signers happens to trust (or none at all if the server has no SSH allowed-signers configured).
• A revoked device's signing key continues to authenticate after relicario device revoke is run — the revoked.json write is cosmetic.

Fix. Implement the verification logic per the design spec (docs/superpowers/specs/2026-05-02-device-authentication-design.md:284-300):

1. Build a temporary allowed-signers file from devices.json entries loaded at the commit. Pass it to git verify-commit via GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=gpg.ssh.allowedSignersFile GIT_CONFIG_VALUE_0=<tmpfile> so we don't mutate global git config.
2. Parse the signing-key fingerprint out of git verify-commit --raw output (the fingerprint appears on the Good "git" signature for … with … key SHA256:… line for SSH).
3. Reject if the fingerprint is not in devices.json at the commit.
4. Reject if the fingerprint is in revoked.json AND commit_timestamp >= revoked_at. The historical-commit case (timestamp < revoked_at) is allowed so old commits survive revocation.
5. Use the commit's committer date (GIT_COMMITTER_DATE, accessible via git show -s --format=%ct) — not the current wall clock and not the author date — as commit_timestamp. Committer date is when the signature was applied; author date is when work was originally written and could be from before revocation even for a malicious replay.

Acceptance.

• An integration test that registers a device, revokes it, signs a commit with the revoked key dated AFTER revoked_at, and confirms the hook exits non-zero.
• An integration test that signs a commit with a key that was never registered and confirms the hook exits non-zero.
• An integration test that signs a commit with a registered, non-revoked key and confirms the hook exits zero.
• An integration test that signs a commit with a revoked key dated BEFORE revoked_at (historical case) and confirms the hook exits zero.
• The dead let _ = &revoked; line is gone.

S2. Tar Archive Path-Traversal Hardening

Problem. crates/relicario-cli/src/main.rs:1722 unpacks the bundled git_archive from a .relbak via tar::Archive::unpack, trusting the tar crate's defaults. A malicious .relbak could contain entries with .. components or absolute paths.

Fix. Iterate entries explicitly:

• Reject any entry whose path contains a .. component, an absolute prefix, or a Windows drive letter.
• Reject symlinks and hardlinks (we never write either inside .git/ on restore).
• Cap total uncompressed size at 100× the compressed git_archive size or 1 GiB, whichever is lower (defends against tar bombs).
• Write each entry under target.join(".git") only after the path resolves inside that directory.

Acceptance.

• Unit test with a hand-crafted tar containing ../../etc/passwd — restore bails with "path traversal blocked".
• Unit test with a symlink entry — restore bails.
• Unit test with a 1 TiB sparse entry — restore bails on the size cap.
• Existing valid-restore test still passes.

S3. RELICARIO_* Env-Var Audit

Problem. Three env vars are not gated by cfg(debug_assertions):

• RELICARIO_IMAGE (crates/relicario-cli/src/session.rs:125) — reference-image override path.
• RELICARIO_NO_GROUPS_CACHE (crates/relicario-cli/src/helpers.rs:103) — disables the groups cache.
• RELICARIO_GITEA_URL (crates/relicario-cli/src/main.rs:2298) — Gitea base URL fallback.

Spot-check confirmed these look intentional, but they're undocumented and RELICARIO_NO_GROUPS_CACHE is more of a dev escape hatch than production config.

Fix.

• Document each env var in docs/SECURITY.md and the relevant --help text.
• Move RELICARIO_NO_GROUPS_CACHE under cfg(debug_assertions) — it's a dev tool, not a user knob.
• Leave RELICARIO_IMAGE and RELICARIO_GITEA_URL as user-facing config; audit each call site to confirm no untrusted-input-flows-into-path cases.

Acceptance.

• docs/SECURITY.md lists every RELICARIO_* env var with purpose and trust assumption.
• RELICARIO_NO_GROUPS_CACHE is no-op in cargo build --release.

C1. Stale Feature Branch Prune

Problem. Six local branches with no merged history beyond what's already in main: feature/fullscreen-ux-phase-2a, feature/typed-items-1a-rust-core, feature/typed-items-1c-alpha, feature/typed-items-1c-beta1, feature/typed-items-1c-beta2.

Fix. Verify each is fully merged into main (git branch --merged main), then delete locally only — no remote branch operations. Plan execution will surface the list and prompt the user before running git branch -D per branch (per project rule on git-destructive ops).

Acceptance. git branch shows only main and active feature branches.

---

Plan B — Extension UX

B1. Strength Meter Desync After Regenerate

Problem. Confirmed in screenshot from 2026-05-02: clicking the regenerate button on a login form's password field rerolls a 20-character mixed-class password (e.g., sCMtTJkF%GN^mF#-N6D%) but the strength meter still reports ~10^1 guesses — trivially crackable. The rated string is stale — likely whatever was in the field before the reroll, or empty.

The meter listens to input events on the password field (extension/src/shared/form-affordances/password-tools.ts:65). The regenerate handler sets input.value = newPassword programmatically, which does not fire input events in standard DOM behavior.

Fix. In the regenerate handler (search for the orange-spinner button click), after assigning input.value, dispatch an InputEvent('input', { bubbles: true }). Confirm by re-rating inside the handler if needed.

Acceptance.

• Vitest: simulate regenerate click, assert that input event is dispatched and meter calls scheduleRate with the new value.
• Manual: regenerate a password on the login form, confirm meter jumps to "strong" with appropriate guesses_log10.

P4. Error-Message Audit (subsumes B2)

Problem. Snake_case error codes leak straight into the fullscreen tab and other surfaces:

• vault_locked shown as a red string in the new-login form (screenshot 2026-05-02).
• ~20 call sites in extension/src/service-worker/router/ return { ok: false, error: 'vault_locked' } and similar.

The popup has a one-off mapping at extension/src/popup/popup.ts:147 (/vault_locked/i.test(err) → unlock prompt), but the fullscreen tab has no equivalent.

Fix.

1. Build a single ERROR_COPY map keyed by error code, returning { title: string; body: string; cta?: { label: string; action: () => void } }. Place at extension/src/shared/error-copy.ts.
2. Audit call sites in extension/src/service-worker/router/ for all error codes; ensure each has a mapping.
3. Replace the regex in popup.ts:147 and the raw-error rendering in the fullscreen tab with lookupErrorCopy(code).
4. For vault_locked specifically: the CTA is "Unlock vault" → opens the popup unlock view (or in the fullscreen tab, the inline unlock form).

Acceptance.

• No raw snake_case strings render in any UI surface for any error return path. Verified by grep + manual trigger of each error code.
• vault_locked in the fullscreen tab shows friendly copy + an "Unlock vault" button that works.
• Vitest: enumerate every distinct error: '...' string literal found in extension/src/service-worker/router/ via grep, assert each is a key in ERROR_COPY. Generated test or build-time check preferred over a static snapshot so it can't drift.

P1. Password Coloring

Problem / Fix. Implement per existing spec at docs/superpowers/specs/2026-05-01-password-coloring-design.md and plan at docs/superpowers/plans/2026-05-01-password-coloring.md. No design changes; pulled into v0.5.0 because it's polish-flavored and small.

Acceptance. Per existing plan's acceptance criteria.

P2. Setup-Wizard Completion → Fullscreen Vault Tab

Problem. Setup wizard currently routes to the popup item-list view on completion. The user wants to land in the fullscreen vault tab — the experience reads as more "real software" and avoids the sub-300px popup width on first run.

Fix. In the setup wizard's terminal step, after the vault is created and the device is registered:

1. Open the fullscreen vault tab via chrome.tabs.create({ url: chrome.runtime.getURL('vault.html') }).
2. Close the setup tab (or the popup, depending on entry point).

Acceptance.

• Manual: complete the new-vault setup flow; vault tab opens, setup tab closes.
• Manual: complete the attach-existing flow; same behavior.
• Vitest: assert chrome.tabs.create is called with the vault URL on successful setup completion.

P3. Form-Layout 2-col → Full-Width Transition

Problem. Screenshot 2026-05-02 shows the new-login form in the fullscreen tab: the IDENTITY and CREDENTIALS cards sit in a 2-column grid with a max-width that stops well short of viewport edge, but the Notes textarea, custom-fields disclosure, and attachments disclosure below all stretch full-width. The visual rhythm breaks at the transition — the lower sections look like a different page.

Fix. Two candidate approaches; pick at implementation time:

• A. Constrain the lower sections to the same max-width and horizontal alignment as the cards. They become a third "row" in the same column system. Simpler, less code.
• B. Wrap the lower sections in a card matching the upper cards' visual treatment. Notes-as-card, custom-fields-as-card, attachments-as-card. More work, more visual consistency, but might feel heavier.

Recommended: A for v0.5.0 — minimal CSS change, immediate correctness. Revisit B in Phase 3 if the user still feels the layout is off.

Acceptance.

• The new-login form (and all item-type forms — login, secure note, identity, card, key, document, totp) renders with consistent horizontal alignment from top of form to bottom.
• Manual: viewport at 1920×1080, 1440×900, 1024×768, and 768×1024; no jarring width transitions.

---

Testing Strategy

Layer	Tests
Rust unit (relicario-server)	S1 acceptance set (4 scenarios)
Rust unit (relicario-core)	S2 path-traversal scenarios (3 scenarios)
CLI integration	S2 happy-path restore unchanged
Vitest (extension)	B1 input-event dispatch; P4 ERROR_COPY snapshot; P2 tabs.create call
Manual	P3 viewport sweep; B2/P4 trigger each error code; S1 hook setup on a real Gitea instance; C1 branch cleanup confirmation

Existing tests stay green. No regression budget.

Out of Scope

Listed for clarity; each tracked separately:

• LastPass import (docs/superpowers/plans/2026-04-29-relicario-lastpass-import.md)
• Recovery QR + entropy floor (docs/superpowers/plans/2026-05-01-recovery-qr-and-entropy-floor.md)
• Plan 1C-γ (attachments + Document + trash UI)
• Fullscreen Phase 3 (shell) and Phase 4 (palette)
• Pre-v0.3.0 manual test walk (docs/test-checklists/2026-04-27-pre-v0.3.0-audit.md) — that's a v0.3.0 release gate, not a v0.5.0 item

Sequencing

1. Plan A and Plan B can run in parallel (no shared files).
2. Inside Plan A: S1 first (unblocks the security claim), then S2, then S3, then C1.
3. Inside Plan B: P4 first (unblocks B2 and surfaces all error codes centrally), then B1, then P1, then P3, then P2 (P2 is end-to-end and benefits from earlier polish).
4. Both plans merge to main; tag v0.5.0 after both PRs are green.

Risks

• S1 SSH allowed-signers parsing. git verify-commit --raw output format for SSH signatures differs slightly from GPG; the fingerprint-extraction regex needs unit coverage against real output. Mitigation: capture sample outputs from a test repo and check them into the test fixtures.
• P3 layout regressions. Constraining the lower sections may affect the textarea behavior at small widths. Mitigation: viewport sweep in acceptance.
• C1 accidental deletion. Plan execution must git branch --merged main filter and prompt before each -D. The no-destructive-without-asking project rule applies.