Skip to content

feat(web): passkey vault on Platform (vaultEntry) on a vendored platform-auth core - #605

Merged
PastaPastaPasta merged 14 commits into
masterfrom
feat/passkey-vault-web
Oct 26, 2026
Merged

PastaPastaPasta merged 14 commits into
masterfrom
feat/passkey-vault-web

Conversation

@PastaPastaPasta

@PastaPastaPasta PastaPastaPasta commented Oct 25, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #604 (App Connect v2). Review and merge #604 first.

Summary

Adds a passkey vault stored on Platform to forge-web. A synced passkey can move a Forge session to a new device. The session key is sealed with HPKE to a key derived from the passkey's WebAuthn PRF output, and stored as a vaultEntry document in forge-meta.

  • Contract. A new vaultEntry document type, added through a passkey_vault UPDATE-2 flag in build.py. It exists only in the four-contract (mainnet) set, where it lands in forge-meta. In the three-contract set it would push forge-community past its size ceiling.
    • Fields:
      • credentialId: 16–255 B, immutable.
      • recipientKey: 32 B, immutable.
      • version: u8.
      • authKeyId: refersTo an authentication key of the owner.
      • enc: 32 B.
      • sealed: 32–256 B.
    • Documents are mutable and deletable, with a unique byCredential [$ownerId, credentialId] index.
    • contract-validate --expect-update accepts the new forge-meta as an update of the one sakura registered.
  • Shared core (vendored). lib/vendor/platform-auth/passkey-vault/ is vendored from feat: passkey vault core (HPKE + WebAuthn PRF) with Yappr/govhub/Forge profiles platform-auth#6 at dbd9a4f with tools/vendor.mjs. A Forge test runs the Forge profile against the upstream forge.json vectors, which an independent Python generator cross-checks.
  • Service (lib/auth/passkey-vault/).
    • The Forge profile.
    • RP policy: forge.dashhq.org and localhost only. Hidden on shared origins and IPFS gateways.
    • A Platform port that uses proved reads and the idempotent write helpers.
    • Device trust markers.
  • Slot rules.
    • Slot 0 must be a budgeted, group-bound HIGH key: Forge's own limited key or an App Connect v2 grant.
    • Extra keys must also be budgeted and expiring.
    • The encryption key is included only when the user opts in, with a lock-out warning.
    • MASTER, TRANSFER, CRITICAL, unbounded and tab-only keys are never sealed.
    • Every opened entry is checked against the identity's keys, read with proofs.
    • Re-sealing only targets recipients this device created or confirmed with the passkey, never a key read from the chain.
  • Controller and UI.
    • Sign in: a "Sign in with a passkey" tile.
    • Devices & keys: a Passkeys section to list, add, update, remove, check again or discard.
    • Offer: a one-time offer after sign-in, shown at most twice and never after "Not now".
    • Revoke and disable: those dialogs offer to remove the passkeys that hold the key.
    • Settings: importing an encryption key re-seals this device's passkeys.
    • Renewal: a passkey-restored session can renew through the wallet or with the identity file.
  • Gating. Every passkey control stays hidden until the forge-meta that Platform serves declares vaultEntry. This is checked with a proved contract fetch, and a failed read also hides them. Until the sakura update below, the feature does nothing.
  • Docs.
    • docs/security/passkey-vault.md covers the threat model: planted entries, stale entries, metadata, shared devices, and the fact that sealed bytes stay public on chain forever. It also says plainly that passkeys move a session; they do not recover an account.
    • The contract, limits, costs and economics docs are updated, and there is a CHANGELOG entry.

Needs approval before it works on sakura and testnet

Nothing has been broadcast. Testnet registered the four-contract set on 2026-10-26 (#606) without vaultEntry, so passkey_vault is listed in testnet's since in build.py, and validate-registered.sh accepts the new forge-meta as an update of what testnet registered (the other three contracts are byte-identical). Each network needs one forge-meta update, signed by its deployer. Even the dry run needs the deployer identity file, because it signs the transition:

node forge-contracts/scripts/deploy-v2.mjs --network devnet --devnet-name sakura --set mainnet --update meta --identity <sakura-deployer.identity.json> --dry-run
node forge-contracts/scripts/deploy-v2.mjs --network testnet --set mainnet --update meta --identity <testnet-deployer.identity.json> --expect-sha256 <signed sums> --dry-run

Then run each without --dry-run, run snapshot-contracts.mjs for the network, and commit the record and snapshot. After that, the rehearsal must show that a group-bound limited key can write vaultEntry. Mainnet isn't registered yet, so there vaultEntry simply becomes part of the registration set.

Test plan

  • pnpm typecheck && pnpm lint && pnpm lint:copy && pnpm test (after merging master): 9722 passed, 39 skipped
  • pnpm build
  • build.py --check, validate-registered.sh (forge-meta as an update of testnet's registration), vectors.py --check, registered_test.py, wherecheck.py, variants.py, negative.sh, cargo test -p forge-core --lib, and the deploy-v2 self-tests
  • gitleaks on the tracked tree: clean
  • Playwright (chromium): passkey-vault h1 (no tile on 127.0.0.1) and h2 (tile hidden when Platform lacks vaultEntry) pass
  • passkey-vault w1 (add → forget → passkey sign-in → renew with re-seal → remove): needs E2E_WRITE=1, a reachable sakura, and vaultEntry deployed
  • FORGE_LIVE=1 … vitest run lib/auth/passkey-vault.live.test.ts: prints real fees. The figures in the docs are estimates until this runs
  • Opus reviews of the shared core, the service and controller, and the UI. Findings are fixed, with tests: closing a prompt deleted the passkey, entries could end up openable by no passkey, a failed passkey removal blocked a revoke, and a changed encryption key was silently re-sealed

🤖 Generated with Claude Code

PastaPastaPasta and others added 12 commits October 25, 2026 00:04
…ey vault

Adds `vaultEntry`, a passkey-sealed key bundle per (owner, WebAuthn
credential), behind a new UPDATE-2 flag `passkey_vault` in build.py. It is
defined in forge-community and moved to forge-meta by META_TYPES, so it exists
in the four-contract (mainnet) set only: in the three-contract forge-community
it would take the contract to 18,385 B (ceiling 17,832) with 1,989 B of room.

Schema: credentialId (byteArray 16-255, immutable), recipientKey (bytes 32,
immutable), version 1-255, authKeyId (u32, refersTo the owner's authentication
key), enc (bytes 32), sealed (byteArray 32-256); mutable and deletable; unique
index byCredential [$ownerId, credentialId].

forge-meta grows 6,870 -> 7,684 B (create transition 7,790 B, 12,690 B of
room). contract-validate accepts it as an update of the forge-meta registered
on sakura. Clients' layout maps (forge-core, forge-web, seed scripts) learn the
type; it has no three-contract home. Nothing is broadcast.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Vendored with platform-auth tools/vendor.mjs from feat/passkey-vault
(dbd9a4f). VENDORED.json keeps app-connect at its own commit. Adds
@noble/ciphers for the module's HPKE.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Forge's vault profile (one 240-byte slot format, six keys) checked against
the core's forge.json vectors; the relying-party policy (forge.dashhq.org
and localhost only, never on shared origins or IPFS subdomain gateways,
only where forge-meta exists); and the VaultPort over proved vaultEntry
reads and Forge's idempotent write helpers. vaultEntry joins DOC and the
web cost tables (estimates from Yappr's sakura figures until measured).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Forge's slot rules on top of the vendored PasskeyVault: slot 0 is a
budgeted, expiring, group-bound HIGH key; then up to four live wallet
grants (never held-only, unbounded or foreign ones); then, only when the
user opts in, the identity's usable encryption key. Opening checks every
slot against the identity read with proofs: a failing slot 0 refuses the
sign-in, other failures are dropped, and copies are returned before the
core wipes the bundle. Core errors map to Forge copy with stable codes.

Device records (pv-own trust markers, pv-pending enrolments as public ids
only) live in IndexedDB beside the browser vault.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ntroller

AuthController gains signInWithPasskey (one discoverable prompt, the
chain-checked keys kept in the browser vault under the same passkey with
its PRF input as the salt), addPlatformPasskey (opt-in encryption key,
pending enrolments kept for Check again), listPlatformPasskeys,
removePlatformPasskey (signals only this device's credentials) and
resealPlatformPasskeys (no prompt only for entries still sealed to this
device's recorded recipient key; one prompt otherwise). Key changes in
this tab re-seal in the background; revokeStored and disableIdentityKey
can first delete the passkeys naming the keys; forget clears the device's
passkey records. The auth context exposes them for the UI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review fixes for the passkey vault controller:
- the browser adapter maps WebAuthn rejections to coded PasskeyErrors in
  the vault's words, so a closed confirm stays pending instead of being
  dropped, and codes reach the UI;
- a pending passkey is dropped only when it can never hold the key and
  Platform proves no entry of it exists; Discard deletes a landed entry
  before signalling, and a second add waits for the first;
- background re-seals: per-entry failures, no stripping of an opted-in
  encryption key, no marker after sign-out; forget and remove wait for
  them; a lagging node is read again; keyChanged never throws;
- the sign-in marker's recipient key is derived from the PRF output and
  written once the key is stored; wipe gaps closed; clearer copy for a
  key on a foreign group.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Simplifier pass: one session guard, writable/read-only port helpers, an
error-mapping helper, one ownMarkerFor rule for 'this device's entry',
shared key-shape predicates, and module-private internals. Remaining
budgets are keyed by number whatever the SDK's map keys are.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Entry ciphertexts are public on chain forever, so a leaked passkey must never
yield a key with no spending limit or no expiry. Extra keys (slots 1+) now need
a budget AND an expiry, both when sealing and when opening an entry: a v1
wallet's unlimited per-contract grant stays on the device that holds it.
The controller reports how many were left out so the UI can say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-restored key either way

Passkey controls stay hidden until the forge-meta Platform serves declares
vaultEntry (a proved contract fetch, not the bundled snapshot), so the feature
is inert until the pending sakura forge-meta update. A read that fails also
hides them and is retried next time.

A session restored from a passkey is stored with origin 'passkey': a passkey
does not say whether a wallet or the master key made the key, so renewal offers
both 'Renew in your wallet' and 'Renew with identity file' (low-funds banner,
top-up sheet, Settings), and the wallet renewal request accepts it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ke options

- Sign-in sheet: 'Sign in with a passkey' (after the wallet tile), with progress,
  the 'only unlocks the browser that made it' message and 'Unlock instead'.
- Devices & keys: a passkeys section that lists, adds (encryption key off by
  default, with the lock-out warning), updates ('Needs update'), removes,
  finishes ('Check again') and discards passkeys, and says that keys without a
  spending limit stay on the device. A resumed tab unlocks first.
- A one-time offer under the header after an interactive sign-in: at most twice
  per identity, never after 'Not now', never where a passkey could not hold the key.
- Revoke and disable dialogs offer to remove the passkeys that hold the key.
- Importing an encryption key in Settings re-seals this device's passkeys.
- Hidden whenever platformPasskeyProblem is not null.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s, limits

- e2e/passkey-vault.spec.ts: Chromium with a CDP virtual authenticator (PRF) on
  http://localhost. Hermetic cases (no passkey sign-in on an IP address, nor
  where forge-meta reads as having no vault) run anywhere; the browser-only
  passkey message self-skips until forge-meta has vaultEntry; the full add,
  forget, passkey sign-in, re-seal and remove flow needs E2E_WRITE=1.
- lib/auth/passkey-vault.live.test.ts (FORGE_LIVE=1): a fake authenticator
  against real sakura, printing each step's fee; ends before spending while
  forge-meta has no vaultEntry.
- docs/security/passkey-vault.md: the threat model, the extras policy (only
  budgeted, expiring keys), 'passkeys move a session, they don't recover an
  account', and the pending sakura forge-meta update. Costs, economics, limits,
  the identity guide and the changelog updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Revoke and disable: removing the passkeys first is best effort. A delete that
  fails (this browser's key spent, Platform slow) no longer stops the key from
  being disabled; the page says which passkeys to remove.
- A new encryption key is no longer added silently to an entry that held the old
  one: the entry shows 'Needs update' and the user chooses again.
- Renewing a passkey-restored key in a wallet keeps the old key held-only (the
  wallet does not disable another browser's grant), so no passkey seals it again,
  and the copy no longer says it was disabled.
- The one-time offer is skipped for a spent or expired key; the passkeys panel
  is keyed by identity; the remove dialog and the extras shape check are tighter.
- e2e w1: unlock a resumed tab before the renewal, and check the re-seal in the
  same page instead of after a reload.
- Docs: the expiry claim matches what is enforced, a top-up reaches every passkey
  that holds the key, and the best-effort removal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 6 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 3bca3cde-bfc0-4c9b-a4d8-0961e92b6532
Commits

Reviewing files that changed from the base of the PR and between 037fd8a and a314139.

Files ignored due to path filters: 1
  • forge-web/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
Files selected for processing: 96
  • CHANGELOG.md
  • crates/forge-core/src/layout.rs
  • docs/contracts/forge-v2.md
  • docs/deploying-to-a-network.md
  • docs/economics.md
  • docs/guides/costs.md
  • docs/guides/identity-and-keys.md
  • docs/limits.md
  • docs/security/passkey-vault.md
  • forge-contracts/contracts/mainnet/forge-meta.json
  • forge-contracts/schema/build.py
  • forge-contracts/schema/vectors.py
  • forge-contracts/scripts/lib/offline-chain.test.mjs
  • forge-contracts/scripts/lib/seed-io.mjs
  • forge-contracts/scripts/lib/seed-io.test.mjs
  • forge-contracts/vectors/rc1/forge-community.indices.json
  • forge-web/components/app-shell.tsx
  • forge-web/components/auth/passkey-sign-in.tsx
  • forge-web/components/auth/passkeys-section.test.tsx
  • forge-web/components/auth/passkeys-section.tsx
  • forge-web/components/auth/remove-passkeys-option.tsx
  • forge-web/components/auth/sign-in-tile.tsx
  • forge-web/components/auth/wallet-connect-flow.tsx
  • forge-web/components/devices-keys.test.tsx
  • forge-web/components/devices-keys.tsx
  • forge-web/components/encryption-key-panel.test.tsx
  • forge-web/components/encryption-key-panel.tsx
  • forge-web/components/key-revoke-dialog.test.tsx
  • forge-web/components/key-revoke-dialog.tsx
  • forge-web/components/keys-panel.tsx
  • forge-web/components/login-modal.test.tsx
  • forge-web/components/login-modal.tsx
  • forge-web/components/low-funds-banner.test.tsx
  • forge-web/components/low-funds-banner.tsx
  • forge-web/components/passkey-offer.test.tsx
  • forge-web/components/passkey-offer.tsx
  • forge-web/components/top-up-sheet.test.tsx
  • forge-web/components/top-up-sheet.tsx
  • forge-web/contexts/auth-context.test.tsx
  • forge-web/contexts/auth-context.tsx
  • forge-web/e2e/passkey-vault.spec.ts
  • forge-web/e2e/wallet-login-v2.spec.ts
  • forge-web/lib/auth/controller.ts
  • forge-web/lib/auth/forget-local.test.ts
  • forge-web/lib/auth/passkey-session.test.ts
  • forge-web/lib/auth/passkey-vault.live.test.ts
  • forge-web/lib/auth/passkey-vault/deployed.test.ts
  • forge-web/lib/auth/passkey-vault/deployed.ts
  • forge-web/lib/auth/passkey-vault/markers.test.ts
  • forge-web/lib/auth/passkey-vault/markers.ts
  • forge-web/lib/auth/passkey-vault/offer.test.ts
  • forge-web/lib/auth/passkey-vault/offer.ts
  • forge-web/lib/auth/passkey-vault/policy.test.ts
  • forge-web/lib/auth/passkey-vault/policy.ts
  • forge-web/lib/auth/passkey-vault/port.test.ts
  • forge-web/lib/auth/passkey-vault/port.ts
  • forge-web/lib/auth/passkey-vault/profile.test.ts
  • forge-web/lib/auth/passkey-vault/profile.ts
  • forge-web/lib/auth/passkey-vault/service.test.ts
  • forge-web/lib/auth/passkey-vault/service.ts
  • forge-web/lib/auth/vault.ts
  • forge-web/lib/layout.test.ts
  • forge-web/lib/layout.ts
  • forge-web/lib/repo/contract.ts
  • forge-web/lib/sdk/cost.test.ts
  • forge-web/lib/sdk/cost.ts
  • forge-web/lib/vendor/platform-auth/VENDORED.json
  • forge-web/lib/vendor/platform-auth/passkey-vault/__fixtures__/fake-passkey.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/__fixtures__/memory-port.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/__fixtures__/profiles.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/__fixtures__/vectors.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/__vectors__/forge.json
  • forge-web/lib/vendor/platform-auth/passkey-vault/__vectors__/generate.py
  • forge-web/lib/vendor/platform-auth/passkey-vault/__vectors__/govhub.json
  • forge-web/lib/vendor/platform-auth/passkey-vault/__vectors__/yappr.json
  • forge-web/lib/vendor/platform-auth/passkey-vault/bytes.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/codecs.test.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/codecs.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/entry.test.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/entry.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/errors.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/hpke.test.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/hpke.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/index.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/port.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/profile.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/user-handle.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/vault.test.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/vault.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/verify.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/webauthn.test.ts
  • forge-web/lib/vendor/platform-auth/passkey-vault/webauthn.ts
  • forge-web/lib/view/funds.test.ts
  • forge-web/lib/view/funds.ts
  • forge-web/package.json
  • tools/audit/no-devnet-copy.sh
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

PastaPastaPasta and others added 2 commits October 26, 2026 12:22
Brings in master (testnet registration, Platform SDK rc.8, zod 4) via #604.
Testnet registered forge-meta without vaultEntry, so passkey_vault joins
testnet's 'since' in NETWORK_REGISTRATIONS (build.py --check reproduces the
registered bytes again), and the vault deployment notes now say testnet needs
the same forge-meta update as sakura.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The costs guide no longer names sakura, and the passkey-vault security page,
whose deployment status names each network's pending forge-meta update, joins
the developer pages L10 allows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@PastaPastaPasta
PastaPastaPasta changed the base branch from feat/app-connect-login to master October 26, 2026 17:59
@PastaPastaPasta
PastaPastaPasta merged commit b3197b9 into master Oct 26, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant