Core SDK reference

Complete reference for Ownfold domain values, format parsers, record validation, state unions, capability checks, encodings, and extension contracts.

@ownfold/core is the universal, side-effect-free contract package. It contains no runtime crypto, storage, network client, framework adapter, or UI. Import it when application code needs to parse an Ownfold value, implement an adapter, inspect a state, or branch on a typed error.

pnpm add @ownfold/core@beta better-result

Import map

Encoding utilities

Base64Url

Base64Url.encode(bytes) returns unpadded RFC 4648 URL-safe text. decode(value) rejects empty, padded, or non-alphabet input with InvalidInputError code INVALID_BASE64URL.

import { Base64Url } from "@ownfold/core"

const encoded = Base64Url.encode(randomBytes)
const decoded = Base64Url.decode(encoded)
if (decoded.status === "error") return decoded

Do not use permissive platform decoders for persisted Ownfold fields. Strict decoding prevents two text representations from becoming the same authenticated byte string.

Utf8

Utf8.encode(value) returns UTF-8 bytes. Utf8.decode(bytes) uses fatal decoding and returns INVALID_UTF8 instead of inserting replacement characters.

Record context and envelope values

namespace, recordId, and ownerId are authenticated record context. They must come from stable application identifiers. Moving ciphertext to a different value for any field makes decryption fail.

EncryptedEnvelopeValue accepts supported persisted versions. New writes use the current engine default; readers may support older versions during migration. Never construct envelopes manually.

Parsing persisted values

Every parser accepts unknown and returns Result<T, OwnfoldError>.

import { EncryptedEnvelope } from "@ownfold/core"

const parsed = EncryptedEnvelope.parse(databaseRow.encryptedPayload)
if (parsed.status === "error") {
  // Preserve the original row. Do not return a partially parsed envelope.
  return parsed
}

return parsed.value

The exported *Schema values are Standard Schema-compatible Valibot schemas used by the namespace parsers. Prefer the namespace parser when it exists because it maps validation failures to stable Ownfold errors and enforces supported versions.

EncryptedRecordWrite

Use this lower-level validator when an application record route is not calling VaultServer.validateEncryptedRecordWrite().

import { EncryptedRecordWrite } from "@ownfold/core"

const parsed = EncryptedRecordWrite.parse(body, {
  vaultId: activeVault.vaultId,
  keyVersion: activeVault.keyVersion,
  context: {
    namespace: "documents",
    recordId: documentId,
    ownerId: authenticatedUserId,
  },
})

if (parsed.status === "error") return parsed
await documents.save(parsed.value.encryptedPayload)

The input object must contain exactly one field, encryptedPayload. Sibling plaintext-shaped fields are rejected. The validator checks structure and authenticated metadata; only a client holding the root key can verify the AEAD tag.

Vault state

Always switch on state.status. Do not infer readiness from loosely optional fields.

StableVaultState excludes transient setup states. operation-error.previous is the state to return to after the application presents or dismisses the error.

Rotation state

Rotation is a resumable discriminated union. The active variants retain the rotation ID, source and target key versions, revision, processed-record count, and optional checkpoint. Only Rotation parsers should read persisted rotation JSON.

Crypto contract

RootKeyHandle and DeviceKeyHandle are opaque capabilities. Callers may pass them back to the engine but cannot read key bytes. destroyRootKey() must make further use fail.

The production implementation is documented under Crypto engine. Custom engines must return the exact typed errors and preserve the same authenticated formats.

Storage and transport contracts

The method shapes are documented here; transaction, ownership, idempotency, and retry semantics are specified in Adapter and transport contracts.

Remote input schemas

RemoteVaultInput and RemoteRotationInput group strict parsers for every untrusted lifecycle request. Individual schema exports are available for framework integrations.

Do not cast request.json() to these interfaces. Parse it through the namespace or schema and keep validation at the transport boundary.

Capability and format support

PersistedCryptoCapabilities.parse(input) validates a capability manifest. parseString handles JSON text, stringify emits the exchange form, and checkCompatibility(local, remote) returns:

• compatible — every persisted format is readable;
• incompatible — one side cannot read the suite the other side writes, with the exact format and directional compatibility fields.

PersistedFormatSupport is the release manifest of readable versions and the default write version for device envelopes, encrypted envelopes, pairing offers, protected device keys, and Recovery Kits. Persisted format identifiers come from PersistedCryptoFormat; do not use package versions as format versions.

Errors and results

Expected failures use Result from better-result; methods do not throw for invalid input, locked state, conflicts, or authentication failure.

const result = await operation()
if (result.status === "error") {
  console.error(result.error.code) // safe machine-readable field
  return
}
use(result.value)

See Errors for every tagged family and recovery behavior, and the complete export index for every public type and schema name.