Device management

Enroll and revoke browser devices with non-extractable local keys while keeping plaintext vault root keys out of application servers.

Ownfold enrolls a browser after Recovery Kit verification or restoration. The browser creates a non-extractable X25519 private key, wraps the root key for the corresponding public key, and sends only the public device record through the configured transport.

An existing unlocked browser can also approve an expiring pairing offer. The new browser never receives the Recovery Kit or recovery password:

const offer = await newBrowser.beginPairing()
if (offer.status === "error") return

const approved = await existingBrowser.approvePairing(
  JSON.stringify(offer.value),
)
if (approved.status === "error") return

await newBrowser.refreshPairing()

Transfer the complete offer directly between browsers. Ownfold compares it byte-for-byte with the authenticated pending request before wrapping the root key. Offers expire after ten minutes by default and the server rejects lifetimes above fifteen minutes.

The host can render the public offer as text, a local QR code, or another application-selected transfer mechanism. QR generation should have no network dependency. The offer embeds no root key, Recovery Kit, recovery secret, or device private key. The approving browser still verifies it against authenticated server state before wrapping the vault key.

Client API

const devices = await vault.listDevices()
if (devices.status === "error") return

const device = devices.value.find((candidate) => candidate.deviceId === deviceId)
if (device?.status === "active") {
  await vault.revokeDevice(device.deviceId, device.revision)
}

revision is required for revocation so concurrent management sessions cannot silently overwrite each other. Revoking the current browser clears its local identity and returns the client to unavailable-on-device. Restoration requires the Recovery Kit and creates a new device ID.

React applications use useVaultDevices() for headless operations and decide which active or revoked device metadata to display. Ownfold refreshes the current device’s activity time during verified initialization and unlock. The timestamp is coordination metadata, is never trusted from the browser, and does not increment the device’s security revision or invalidate a concurrent revocation action. Adapters preserve the latest timestamp when requests arrive out of order or application-server clocks temporarily skew.

Server persistence

Apply 0001_ownfold_devices.sql, 0002_ownfold_pairings.sql, and 0004_ownfold_device_last_active.sql after the v0.1 vault migration when using Drizzle or direct PostgreSQL. Migration 0004 backfills existing devices from created_at before making the new column required. Prisma users should add OwnfoldDevice, OwnfoldPairing, and their relations from the packaged schema, then apply the packaged Prisma migration or create an equivalent migration in their normal workflow.

The security rationale and anti-substitution checks are specified in ADR 0006: Existing-device pairing.

The server can see device IDs, labels, public keys, creation, last-active and revocation times, status, revision, and encrypted envelope sizes. It cannot open the device envelope.

Locking and current limitations

Paired browsers can unlock with their non-extractable device key because they do not receive a Recovery Kit. This is an application-level memory lock, not user-presence authentication: malicious same-origin JavaScript can invoke the same Web Crypto key while it is available. Host applications requiring OS user presence need a separately reviewed platform authenticator design.

The browser client automatically locks after fifteen idle minutes by default. Locking, current device revocation, and local-state removal propagate across tabs through versioned, secret-free messages. Call client.recordActivity() for activity outside normal document pointer and keyboard events, and call client.dispose() when permanently tearing down a client.

The design and limitations are specified in ADR 0007: Browser lock coordination. Retention and deletion of revoked-device metadata are intentionally owned by the host application. Legal retention, security-audit, and incident-response requirements vary, so Ownfold adapters do not perform automatic destructive cleanup. Operators must apply and test their documented retention policy.