BBonis Systems
Aegis · Bank · Owner-Key Custody

The bank custodian holds the key. Knox records the lifecycle.

A bank-vertical owner-held master key — K_O — is generated, held, rotated, and recovered entirely by the bank’s custodian. Knox does not provision K_O, does not store K_O, never receives K_O bytes, and structurally cannot decrypt records wrapped under K_O. The four flows on this surface — provisioning, rotation, recovery, decrypt-request — record after-the-fact, structurally- redacted, SHA-256-chained, Knox-anchored receipts of the bank-custodian decision. Provisioning and rotation are shipped today. The remaining two flows are described here in their canonical chain-shape; their live status is declared inline.

Substrate, not custodyStructural redactionK_O never crosses the wireProvisioning + rotation shippedRecovery / decrypt-request in roadmap
Lifecycle

Four flows compose the bank-custodian owner-key lifecycle.

Each shipped flow has a dedicated Knox event type with a strict Zod schema and emits an after-the-fact tamper-evident receipt committing to the canonical chain-shape. Recovery’s canonical chain-shape lock is declared after the bank custody policy on recovery shape. The bank’s custodian decides; Knox records.

provisioning

Shipped

Initial onboarding of a bank-custodian owner-key. Records the canonical chain-shape: opaque ref, shape code, record version 1, and the SHA-256 attestation hash produced by the bank's local custody system.

URL path
/bank/owner-key/provisioning
Event type
knox_owner_envelope_provisioned

Captures: owner_internal_ref (BANK-CUSTODIAN-… opaque ref), owner_key_shape_code (one of the four locked shape codes), record_version (server-assigned 1 on provisioning), provisioning_attestation_hash (64-char lowercase hex SHA-256), anchored_at (ISO timestamp from server clock).

rotation

Shipped

Transition from an existing K_O epoch to a new K_O epoch. Records the prior record version, the new record version, and the rotation reason code. Record versions are monotonic per owner_internal_ref.

URL path
/bank/owner-key/rotation
Event type
knox_owner_envelope_rotated

Captures: owner_internal_ref, previous_record_version, new_record_version (must be strictly greater), rotation_reason_code (scheduled, compromise_suspected, recovery_completed, regulatory_required, other_documented), anchored_at.

recovery

In roadmap

Use of the recovery factor (Argon2id-stretched passphrase on the hybrid shape) to re-establish bank-custodian access after loss of the primary hardware factor. Records the recovery-completed transition; a subsequent rotation event marks the new epoch under the recovery-completed reason code.

URL path
/bank/owner-key/recovery
Event type
(in roadmap)

Captures: Canonical chain-shape pending — shape decision lives with the bank custodian's recovery policy (single-factor recovery vs m-of-n quorum); recovery flow ships after the custody-policy decision is locked.

decrypt-request

In roadmap

Bank-side request to decrypt a previously-anchored decision envelope. Records the request anchor, then either a completed anchor or a failed anchor with a reason code. K_O is used by the bank's local custody system to unwrap the session key; the server never sees K_O.

URL path
/bank/owner-key/decrypt-request
Event type
knox_owner_decrypt_requested / completed / failed

Captures: operation_internal_ref, owner_internal_ref, decrypt_request_id (opaque ref for the request itself), record_version, anchored_at, and on failure a reason code from the locked failure-reason enum.

Custody boundary

K_O bytes do not cross the network.

The bank’s local custody system holds K_O. The local custody system computes a SHA-256 attestation hash over the canonicalized provisioning artifact — an artifact that commits to the K_O public verifier material plus the locked shape descriptor, but never K_O itself — and posts only that 64-character hash to the API. The server validates and anchors. Anyone holding only the Knox chain receipts cannot recover K_O, cannot reproduce a bank-custodian signature, and cannot decrypt any payload wrapped under K_O.

# Conceptual sketch — the bank's local custody system runs this once
# during provisioning. Numerals here are placeholders; the real artifact
# carries the K_O public verifier material plus the locked shape
# descriptor.

cat custody-artifact-canonical.json | sha256sum
# 9d4f1c8a2e6b3a7f9e5c2d8b4a6f1e3c5d7b9a2e4f6c8d1b3a5f7e9c2d4b6a8e

# Post to /api/knox/owner-key/provisioning with only the hash above:
{
  "owner_internal_ref": "BANK-CUSTODIAN-2026-05-001",
  "owner_key_shape_code": "hybrid_passphrase_plus_hardware",
  "provisioning_attestation_hash":
    "9d4f1c8a2e6b3a7f9e5c2d8b4a6f1e3c5d7b9a2e4f6c8d1b3a5f7e9c2d4b6a8e"
}
Shape codes

Four locked owner-key shape codes.

The owner_key_shape_code field on every owner-key event commits to one of four locked values. The shape code is part of the chain shape; the underlying custody implementation that produces a key matching a given shape is the bank’s local concern. Bank custodian default is hybrid_passphrase_plus_hardware.

Shape
hardware_hsmHardware security module only. Highest assurance; no recovery factor; loss of the hardware factor means loss of the K_O epoch — a subsequent rotation event is the path forward, not a recovery.
Shape
hardware_fido2Hardware-resident credential conforming to the FIDO2 standard. Suitable for individual-custodian shapes; bank custodian usage typically pairs FIDO2 with the hybrid shape rather than using FIDO2 alone.
Shape
passphrase_argon2idArgon2id-stretched passphrase (RFC 9106). Suitable for consumer-vertical and lowest-threat bank-vertical shapes; production bank custodian usage typically prefers the hybrid shape, which uses Argon2id only as a recovery factor.
Default
hybrid_passphrase_plus_hardwareHardware factor (HSM under custody-board authorization, paired with a hardware-resident credential) as the primary; Argon2id-stretched passphrase as the recovery factor. The bank-vertical default; balances assurance with a recovery path.
Opaque-reference convention

Bank-vertical references begin with BANK-CUSTODIAN-.

The bank-vertical API boundary enforces that owner_internal_ref begins with BANK-CUSTODIAN-. The remainder of the reference, up to 112 alphanumeric / underscore / hyphen characters, is the bank’s opaque identifier. The prefix convention is a vocabulary discipline, not a chain-shape change; the canonical schema in src/lib/knox-owner-key-schemas.ts accepts any opaque reference up to 128 characters. The bank-vertical boundary applies the prefix discipline so that a cross-vertical integration cannot accidentally post a healthcare-vertical or legal-vertical reference under the bank surface.

FAQ

Detail.

What is an owner-held key in the bank-custodian context?

An owner-held master key, K_O, is a key whose bytes are held entirely by the bank custodian and never transmitted to or stored by Bonis. The bank custodian's local custody system — typically a hardware security module under custody-board authorization, paired with a hardware-resident credential and an Argon2id-stretched passphrase recovery factor — holds K_O. Knox stores only opaque references and a SHA-256 attestation hash. Anyone holding only the Knox chain receipts cannot recover K_O, cannot impersonate the bank custodian's signature, and cannot decrypt any payload wrapped under K_O.

What flows compose the bank-custodian owner-key lifecycle?

Four flows. Provisioning records the initial K_O onboarding event for a bank-custodian opaque reference. Rotation records a transition to a new K_O epoch (e.g., scheduled rotation, suspected compromise, recovery completion). Recovery records the use of a recovery factor to re-establish access when the primary custody factor is lost. Decrypt-request records the bank-side request to decrypt a previously-anchored decision envelope using K_O. Each shipped flow has a dedicated Knox event type with a strict Zod schema and emits an after-the-fact tamper-evident receipt. As of the current ship date, provisioning and rotation are live; decrypt-request has a canonical chain-shape lock declared (the knox_owner_decrypt_requested / _completed / _failed triplet). The recovery flow's canonical chain-shape lock is declared after the bank custody policy on recovery shape (single-factor vs. m-of-n quorum).

What does the bank custodian actually post for a provisioning event?

Three fields. owner_internal_ref (the bank's opaque alphanumeric identifier for the custodian, beginning with BANK-CUSTODIAN-), owner_key_shape_code (one of hardware_hsm, hardware_fido2, passphrase_argon2id, or hybrid_passphrase_plus_hardware), and provisioning_attestation_hash (a 64-character lowercase hex SHA-256 produced by the bank's local custody system over the canonicalized provisioning artifact). The server adds record_version: 1 and anchored_at from the server clock. K_O bytes never appear in the post; they remain in the bank's local custody system.

Why does this surface live on the Bonis institutional hub?

The bank custodian is a customer of the Knox audit substrate, not a participant in the TerraVault marketplace. The institutional hub at bonissystems.com is where Bonis publishes its capability surfaces. The bank-vertical owner-key flows live alongside the BSA attestation, AAM theater, and other institutional capability documentation. The same Next.js application serves both bonissystems.com and terravaulthq.com under host-based middleware routing; the bank-vertical owner-key paths route to bonissystems.com.

What is the custody boundary, exactly?

K_O bytes never cross the network. K_O bytes never enter any server-side process. By design, K_O bytes never appear in browser memory after the local custody artifact is produced — provided the bank's local custody system runs the HSM operations and the hash computation locally and only the resulting attestation hash reaches any networked surface. The bank's local custody system computes a SHA-256 attestation hash over the canonicalized provisioning artifact (which itself commits to the K_O public verifier material plus the shape descriptor — but not K_O itself) and posts only that hash to the API. The Knox chain commits to opaque references, the enumerated shape code, the integer record version, and the SHA-256 attestation hash. No PII field shape exists on the schema. Structural redaction is the same posture used for BSA attestation events.

What is the bank-vertical opaque-reference convention?

owner_internal_ref must begin with BANK-CUSTODIAN- and is otherwise opaque to Knox. The remainder of the reference, up to 112 alphanumeric/underscore/hyphen characters, is the bank's internal identifier — often a custodian roster entry, a custody-board resolution number, or a bank-internal record locator. The prefix is enforced at the bank-vertical API boundary so a cross-vertical integration cannot accidentally post a healthcare-vertical patient reference or a legal-vertical matter reference under the bank surface. The prefix is a vocabulary convention; the canonical schema in src/lib/knox-owner-key-schemas.ts accepts any opaque alphanumeric/underscore/hyphen reference up to 128 characters.

What is Bonis's posture in the bank-custodian lifecycle?

Substrate only. Bonis never provisions K_O on the bank's behalf, never holds K_O, never receives K_O bytes, never accesses bank-customer PII, never operates inside the bank's custody system, never has a decryption path to bank records. The bank's custodian provisions, rotates, recovers, and authorizes decrypt operations under the bank's own custody policy. Knox records each lifecycle event as a structurally-redacted, SHA-256-chained, Knox-anchored receipt above the bank's existing custody workflow. The Knox chain is the audit-permanence layer; the bank's custody system is the operational layer.