Adapter and transport contracts

Implement custom databases and browser transports while preserving Ownfold's identity, concurrency, and secret-handling boundaries.

Ownfold separates persistence from networking. A storage adapter runs behind the authenticated server; a transport runs between the browser client and that server. Neither contract carries record plaintext, recovery secrets, or raw keys.

Browser client → VaultTransport → authenticated VaultServer → VaultAdapter → database

Result model

Fallible contract methods return better-result values. Expected conflicts and operational failures are values, not thrown exceptions. Branch on result.status and then on result.error.code.

const result = await adapter.getVault({ userId })

if (result.status === "error") {
  return result
}

return result.value

An implementation may catch a driver exception at its boundary, but must convert it to a typed, secret-safe Ownfold error. Never return raw SQL, connection strings, request bodies, or encrypted payloads in an error message.

Storage adapter

VaultAdapter owns vault metadata, recovery status, devices, and pairing.

The server supplies userId; it comes from the authenticated session and is never accepted from a browser request. Adapter implementations must include both userId and the relevant vault or record identifier in every ownership-sensitive query.

Required semantics

Creation retries can occur after a response is lost. Idempotency means returning the existing equivalent record, not silently accepting a different record under the same identity.

Rotation adapter

VaultRotationAdapter is separate so an early custom adapter can explicitly omit key rotation instead of implementing unsafe partial behavior.

completeRotation is the critical atomic boundary. It must validate the rotation revision, vault revision, and every active device revision before changing any of them. It then commits the new key version, Recovery Kit ID, replacement device envelopes, and completed rotation together. One stale input must roll back the entire cutover.

Progress updates are resumable metadata. processedRecords must not move backwards, and a stale checkpoint must not overwrite newer work.

Test a storage adapter

import {
  checkVaultAdapterCompliance,
  checkVaultRotationAdapterCompliance,
} from "@ownfold/testing"

const lifecycle = await checkVaultAdapterCompliance(adapter)
if (lifecycle.status === "error") throw lifecycle.error

const rotation = await checkVaultRotationAdapterCompliance(adapter)
if (rotation.status === "error") throw rotation.error

Run the suites against a disposable database. They create fixed records and deliberately issue stale writes. In addition, test driver failures, malformed stored JSON, duplicate delivery, and concurrent transactions using the real production database engine.

Browser transport

VaultTransport mirrors authenticated lifecycle operations without accepting userId.

The transport may use fetch, tRPC, server functions, or an application-specific RPC layer. It must:

• send credentials according to the host application’s session policy;
• validate untrusted response bodies before exposing them to lifecycle code;
• preserve stable Ownfold error codes;
• reject non-success protocol responses as TransportError values;
• never retry non-idempotent work without the operation’s stable identifier; and
• make requests only to developer-configured application infrastructure.

VaultRotationTransport adds resumable rotation operations:

Rotation transports carry checkpoints and encrypted device envelopes. Record-key unwrapping, rewrapping, and Recovery Kit generation stay in the browser.

What may cross the network

Encrypted application records use the host application’s own API. They are not part of VaultTransport, which exists only for vault lifecycle coordination.

Custom transport example

import type { VaultTransport } from "@ownfold/core"

export const transport: VaultTransport = {
  async getVault() {
    return callVaultEndpoint("GET", "/vault")
  },
  async createVault(input) {
    return callVaultEndpoint("POST", "/vault", input)
  },
  // Implement every remaining operation with the same validated protocol boundary.
}

Do not return response.json() directly as a typed value. HTTP data is untrusted even when your server produced it; parse the success and error shapes before constructing a result.

Compliance checklist

• Ownership always comes from the server session.
• ORM clients and transaction objects never enter shared contracts.
• All persisted JSON is parsed on read.
• Same-identity creation is idempotent; conflicting identity is rejected.
• Every mutable security record uses optimistic concurrency.
• Pairing approval is atomic with device registration.
• Rotation cutover is atomic across all affected rows.
• Expected failures are typed result errors.
• Transport mocks prove plaintext and recovery secrets never appear in calls.
• No implementation has a default Ownfold-owned URL, telemetry endpoint, or API key.