Protected Field Encryption Design Baseline

Under development

This document is a design and review baseline. The protected-field protocol described here is not available yet and must not be represented as a released TeaQL security capability.

Applications remain responsible for encryption design, key management, authorization, client security, privacy review, and production qualification until implementation and cross-runtime evidence are published.

Purpose

TeaQL is designing a model-driven protocol for fields whose persisted values are encrypted and whose plaintext requires an explicit reveal decision.

The design has two common usage modes:

1. Request-once reveal — metadata marks a value as locked, and the user requests one authorized plaintext response.
2. Short-session reveal — an application issues a short-lived grant so one or more protected fields can be automatically revealed during a limited window.

The protocol must work for clients that understand protected-field metadata without imposing unnecessary complexity on clients that do not use the feature.

Standards and prior art

This design should build on reviewed standards and mature implementations rather than inventing cryptography, authorization terminology, or protocol behavior from first principles. These sources represent substantial public engineering and security review. TeaQL should reuse their semantics where they fit, document deliberate differences, and concentrate its own design work on the model-driven application layer that they do not cover.

Cryptography and key management

• NIST SP 800-57 Part 1 informs cryptographic key lifecycle, inventory, access control, metadata protection, rotation, revocation, and destruction.
• NIST SP 800-38D defines AES-GCM authenticated encryption with associated data. TeaQL protection profiles should require reviewed AEAD primitives rather than unauthenticated encryption.
• JSON Web Encryption (RFC 7516) provides standard terminology and JSON representations for protected headers, encrypted keys, IVs, ciphertext, authentication tags, and AAD. JWE may be supported as a ciphertext profile; it is not automatically the required database format.
• Google Tink AEAD and its client-side envelope encryption guidance provide reference implementations for AEAD, associated-data binding, DEK generation, and KMS-protected KEKs.
• The AWS Encryption SDK message format is a useful reference for versioned ciphertext envelopes, encrypted data keys, algorithm suites, encryption context, and authenticated headers.
• HashiCorp Vault Transit demonstrates encryption as a service, key rotation, rewrap, and a clean distinction between a caller's authorization token and the cryptographic key material.

TeaQL should expose provider contracts for reviewed libraries, KMS products, HSMs, and managed encryption services. It should not implement new cryptographic primitives in six runtimes merely to make their APIs look uniform.

Reveal authorization and binding

• OAuth 2.0 Step Up Authentication Challenge Protocol (RFC 9470) provides the closest standard model for a resource server that requires stronger or more recent authentication before revealing protected data.
• OAuth 2.0 Rich Authorization Requests (RFC 9396) informs structured authorization details such as resource, action, field scope, purpose, and other restrictions that are more precise than a flat scope string.
• OAuth 2.0 Demonstrating Proof of Possession (RFC 9449) is a reference for optional device/key-bound grants that should remain unusable when an opaque bearer value is copied without the binding key.
• OAuth 2.0 Token Exchange (RFC 8693) is a reference for any future trusted delegation that exchanges an upstream grant for a narrower and shorter-lived downstream grant. Ordinary federation must not forward Reveal Grants by default.

TeaQL does not require every application to deploy these OAuth extensions. ProtectedFieldGrantBehavior may integrate with them or with application-specific authentication and approval systems while preserving the portable state and safety semantics.

Response metadata and enforcement obligations

• JSON:API 1.1 demonstrates top-level and resource-level meta objects and links. TeaQL uses the same general idea for WebResponse general metadata and sparse Entity instance metadata, while defining its own deterministic inheritance and merge rules.
• Web Linking (RFC 8288) provides the context/relation/target model for typed action links. TeaQL Reveal Actions add method, localized label, state, and security behavior that generic Web Linking does not define.
• XACML 3.0 provides useful distinctions among authorization decisions, mandatory obligations, and optional advice. TeaQL can adopt those concepts for requirements such as audit, maximum reveal duration, watermarking, and export restrictions without adopting XACML XML as its portable policy language.

Encrypted-field framework behavior

MongoDB Queryable Encryption is the strongest practical reference for schema-declared encrypted fields, automatic driver encryption/decryption, envelope encryption, key vaults, and explicitly enabled encrypted query types. It also demonstrates why equality, range, prefix, suffix, and substring support must be treated as separate capabilities with different maturity and cost.

TeaQL extends beyond a database driver: it must describe locked and revealed Entity state, user-facing Reveal Actions, short-lived grants, UserContext, authorization and audit, multiple databases, and six runtime implementations. MongoDB therefore informs ciphertext and query behavior but does not define the complete TeaQL response protocol.

What TeaQL still defines

No referenced standard defines the complete combination required here. TeaQL remains responsible for:

• WebResponse general metadata and Entity instance override semantics;
• portable LOCKED, REVEALED, pending, denied, and expired states;
• the ProtectedFieldGrantBehavior extension contract;
• the default 30-second session-bound behavior;
• interaction with UserContext, generated model descriptors, authorization, audit, caching, and federation;
• key-space, plaintext-space, and ciphertext-space boundaries at the application runtime;
• six-language conformance fixtures and evidence.

Referencing a standard or framework does not by itself establish conformance, certification, or production safety. A claimed profile must identify the exact version and supported subset, test its security-relevant behavior, record provider and algorithm choices, and document every intentional deviation. Until that evidence exists, these references are design inputs rather than compliance claims.

WebResponse and Entity metadata

Protected-field presentation is described through metadata rather than by changing every business field into a framework-specific wrapper type.

WebResponse carries general metadata shared by an entity type or result set. A specific Entity can carry sparse instance metadata that refines the general description.

WebResponse general metadata
          ↓ inherited by
Entity instance metadata
          ↓ deterministic merge
Effective field metadata

Entity metadata does not replace the complete general description. It overrides only the properties it explicitly supplies. General metadata can describe that Customer.email is protected, while one Customer instance reports that its email is currently revealed.

{
  "data": [
    {
      "id": "customer-10001",
      "email": "alice@example.com",
      "_metadata": {
        "fields": {
          "email": {
            "protection": {
              "state": "REVEALED",
              "mode": "SHORT_SESSION",
              "expiresAt": "2026-08-14T13:30:30Z"
            }
          }
        }
      }
    },
    {
      "id": "customer-10002"
    }
  ],
  "_metadata": {
    "entityTypes": {
      "Customer": {
        "fields": {
          "email": {
            "protection": {
              "protected": true,
              "profile": "customer-contact",
              "defaultState": "LOCKED",
              "supportedRevealModes": [
                "REQUEST_ONCE",
                "SHORT_SESSION"
              ]
            }
          }
        }
      }
    }
  }
}

In this example, customer-10002 inherits the general LOCKED state without repeating metadata on every row.

Merge rules, including object properties, arrays, action identities, and explicit clearing, must be defined by a portable schema rather than left to six runtime implementations.

Simple and metadata-aware clients

A simple client may ignore the entire metadata envelope. It must not receive ciphertext, a misleading null, or automatically revealed plaintext merely because it does not implement the protocol. Locked fields can be safely omitted from its ordinary data representation.

A metadata-aware client can:

• render a lock icon for a locked field;
• show a localized explanation;
• render an available reveal action;
• follow the supplied action URL;
• distinguish locked, pending, revealed, denied, and expired states;
• clear the displayed plaintext when the declared window expires.

Metadata is a presentation and interaction contract, not proof of authorization. Client-submitted metadata cannot create a grant, change the field state, or cause server-side decryption.

Reveal actions

General metadata may define the localized action type and presentation. Entity metadata can add the instance-specific opaque action URL.

{
  "type": "REQUEST_REVEAL",
  "label": {
    "key": "protectedField.action.verifyAndReveal"
  },
  "method": "POST",
  "url": "/protected-fields/reveal/opaque-action-id"
}

The URL must not expose a cryptographic key, raw policy, identity credential, or plaintext field value. Reveal uses an operation such as POST, not an automatically prefetched or cacheable GET.

The application may require step-up authentication, approval, a business reason, or another verification step. TeaQL coordinates the protected-field behavior but does not collect user passwords or replace the application's identity provider.

Customizable grant binding

TeaQL does not prescribe whether a short-lived grant is bound to a user, device, session, approval, case, terminal, or another business concept. Binding and validation belong to a replaceable behavior component with access to application-specific context.

Logical responsibilities include:

ProtectedFieldGrantBehavior
├── request grant
├── create binding
├── validate binding
├── resolve active grant
├── authorize entity and field scope
├── revoke or expire grant
└── record reveal evidence

Applications can implement device-bound, approval-bound, case-bound, or other behavior through code without changing the portable response metadata.

The proposed default is a server-side session-bound grant with an absolute 30-second lifetime:

• it can be resolved across multiple UserContext instances belonging to the same trusted session;
• it does not use a sliding expiry;
• ordinary dynamic input and federation payloads cannot extend or replace it;
• logout, revocation, or a changed session binding can invalidate it early;
• after expiry, subsequent responses return the protected field as LOCKED again.

The opaque grant identifier is an authorization reference, not a data-encryption key. Actual KEKs and plaintext DEKs must not enter Entity metadata, ordinary API responses, URLs, logs, or browser state.

Plaintext expiry and the client boundary

Grant expiry controls future server disclosure. It cannot technically recall plaintext that has already been delivered to a client.

When a 30-second grant expires, TeaQL can guarantee that:

• subsequent server requests no longer use that grant to decrypt;
• new UserContext instances do not receive its reveal capability;
• subsequent WebResponse metadata returns to LOCKED;
• server-side plaintext caches governed by this protocol are cleared or no longer addressable;
• expiry and subsequent reveal attempts are observable and auditable.

A metadata-aware client should use expiresAt and the handling policy to remove plaintext from component state, avoid persistent storage, restore the locked presentation, and require another reveal request. This is a best-effort client responsibility, not a remotely verifiable erasure guarantee.

Once plaintext is visible on a client, no general-purpose application framework can prevent every form of retention or capture. A user may copy it, take a screenshot or photograph, or expose it through a compromised browser, extension, device, memory dump, accessibility tool, or client defect. Server-side key rotation protects future cryptographic operations and stored ciphertext; it does not revoke plaintext already disclosed.

TeaQL must therefore describe this boundary accurately:

Protected-field expiry limits continued server-authorized disclosure. It does not guarantee deletion of plaintext already received or observed on a client.

Applications can reduce—not eliminate—this risk through measures such as visible or forensic watermarks, restricted export, single-use grants, smaller scopes, trusted-device requirements, managed viewers, data-loss-prevention controls, and detailed reveal audit. These controls must not be documented as making client-side plaintext technically recoverable or impossible to capture.

Shared responsibility

The security responsibility is divided as follows:

Area	Primary responsibility
Ciphertext format and integrity binding	TeaQL portable contract and cryptographic provider integration
KEK/DEK custody and rotation	Application operator and KMS/HSM provider
Identity and step-up authentication	Application and identity provider
Reveal authorization and binding	Application policy and ProtectedFieldGrantBehavior
Server-side grant expiry and enforcement	TeaQL runtime integration and application configuration
Metadata-aware rendering and best-effort clearing	Client framework/application
Endpoint, browser, device, and extension security	Client operator and application security program
Capture by an already authorized human	Organizational controls, audit, and risk management

TeaQL should provide safe defaults and explicit metadata, but it must not imply that framework-level encryption alone secures a compromised endpoint or reverses disclosure to an authorized viewer.

Three logical spaces

The complete design separates:

1. Key space — cryptographic key references and versions, plus distinct opaque reveal-grant identities and lifecycles.
2. Plaintext space — sensitive values before encryption or after an authorized decryption, including their permitted server-memory, response, and client-memory lifetime.
3. Ciphertext space — authenticated ciphertext, nonce, authentication tag, wrapped DEK or reference, and format version.

These spaces must remain distinct. A reveal-grant key is not a DEK, ciphertext is not an application-visible field value, and plaintext must not be retained merely because the Entity or response that temporarily carried it remains reachable.

Metadata describes the allowed transitions between these spaces but is not itself one of the spaces:

plaintext on write
    ↓ encrypt under the configured protection profile
ciphertext at rest
    ↓ authorized reveal using a valid grant
temporary plaintext
    ↓ expiry / response completion / client handling policy
locked presentation for subsequent access

The plaintext space is deliberately narrow. On the server, revealed values must be excluded from ordinary caches, logs, traces, error arguments, and unprotected audit payloads. On the client, metadata can communicate expiry and handling expectations, but it cannot guarantee deletion or recall after disclosure. Model metadata and WebResponse/Entity metadata describe these rules, protection state, localized actions, and current reveal evidence without containing cryptographic key material.

Open design work

The following areas still require review before implementation:

• exact portable schemas and deterministic metadata merge semantics;
• single-request reveal response shape;
• Grant Store, revocation, maximum duration, and delegation contracts;
• searchable protected fields, blind indexes, and tokenization boundaries;
• batch decryption and provider performance;
• authenticated encryption and associated-data binding;
• write, update, rotation, and rewrap behavior;
• interaction with authorization, audit, caches, federation, and exports;
• six-runtime conformance and adversarial client fixtures;
• Governance Console policy, evidence, and operational workflows.

Current status

This page records agreed design direction and known limitations. No current TeaQL release guarantees this protocol. Production applications must continue to use independently reviewed encryption and client-security designs until implementation evidence is published.