Skip to main content

SealedField

@webda/core

Class: SealedField<T>

Defined in: packages/core/src/models/sealed.model.ts:66

A model field sealed end-to-end to a user public key

The server writes the value with the recipient public key (ECDH-ES P-256 + HKDF-SHA-256 + AES-256-GCM, see src/sealed/) and can never read it: there is no get()/open() here, only the recipient devices open it with their private key. The stored data is the envelope { v, kid, epk, iv, ct }, a public output, bound by the AAD modelType|uuid|field|kid to its record, attribute and recipient key.

A client opens it with openValue(envelope, recipient, fieldAad(modelType, uuid, field, envelope.kid)) where:

  • modelType is the model identifier (useModelId(model), e.g. "Webda/Note")
  • uuid is String(model.getPrimaryKey()) (composite keys are joined with the model separator, _ by default)
  • field is the attribute name (e.g. "content")
  • kid is the envelope kid

The recipient is seal(value, { user }), else the model getSealedRecipient(field) (the owner for an OwnerModel), else the model getOwner().

A client can also seal the value itself (KeyVault.seal) and store the envelope with the set action (<Model>.<Field>.Set, PUT <model>/{uuid}/<field>.set), authorised by the model canAct("<field>.set"): the server checks the envelope shape and that it is sealed to the recipient active key, it cannot check the content.

class Note extends OwnerModel {
  content: SealedField<{ title: string; body: string }>;
}
await note.content.seal({ title, body }); // sealed to the owner
await note.save();

Webda Behavior​

Webda/Sealed

Type Parameters​

T​

T = any

Constructors​

Constructor​

new SealedField<T>(): SealedField<T>

Returns​

SealedField<T>

Properties​

ct?​

optional ct?: string

Defined in: packages/core/src/models/sealed.model.ts:76

AES-GCM ciphertext, base64url

epk?​

optional epk?: JsonWebKey

Defined in: packages/core/src/models/sealed.model.ts:72

Ephemeral public key

iv?​

optional iv?: string

Defined in: packages/core/src/models/sealed.model.ts:74

AES-GCM IV, base64url

kid?​

optional kid?: string

Defined in: packages/core/src/models/sealed.model.ts:70

Recipient key id

v?​

optional v?: 1

Defined in: packages/core/src/models/sealed.model.ts:68

Envelope version

Methods​

clear()​

clear(): void

Defined in: packages/core/src/models/sealed.model.ts:206

Remove the stored value (does not save the model)

Returns​

void

getParent()​

protected getParent(): object

Defined in: packages/core/src/models/sealed.model.ts:227

Returns​

object

the model holding this field and its attribute name

attribute​

attribute: string

instance​

instance: any

Throws​

Error when the field is not attached to a model

isSet()​

isSet(): boolean

Defined in: packages/core/src/models/sealed.model.ts:81

Returns​

boolean

true when a complete envelope is stored

seal()​

seal(value, opts?): Promise<void>

Defined in: packages/core/src/models/sealed.model.ts:104

Seal a value to the recipient public key and store the envelope (does not save the model)

The plaintext is never kept on the instance.

Parameters​

value​

T

JSON-serialisable value

opts?​

sealing options

user?​

string

recipient user id, instead of the model default

Returns​

Promise<void>

Throws​

SealedKeyMissingError when the recipient is unknown or has no public key

Throws​

SealedFormatError when the recipient public key is malformed

Throws​

BadRequest when the model has no primary key yet

set()​

set(envelope): Promise<void>

Defined in: packages/core/src/models/sealed.model.ts:134

Store an envelope sealed by a client (KeyVault.seal) and save this field only (a patch of the attribute)

Exposed as <Model>.<Field>.Set, authorised by the model canAct("<field>.set"). The envelope must be well formed and sealed to the active key of the recipient (resolved as for SealedField.seal); the server cannot check that it opens, the AAD the client used (modelType|uuid|field|kid) is only verified by the recipient.

Parameters​

envelope​

SealedEnvelope

sealed envelope { v: 1, kid, epk, iv, ct }

Returns​

Promise<void>

Throws​

SealedFormatError when the envelope is malformed or not sealed to the recipient active key

Throws​

SealedKeyMissingError when the recipient is unknown or has no public key

toJSON()​

toJSON(): SealedEnvelope | Partial<SealedEnvelope>

Defined in: packages/core/src/models/sealed.model.ts:214

Returns​

SealedEnvelope | Partial<SealedEnvelope>

the envelope, undefined when no field is stored, the partial fields as-is when the envelope is incomplete (corrupted data is kept, not silently dropped)

checkEnvelope()​

protected static checkEnvelope(envelope): Promise<SealedEnvelope>

Defined in: packages/core/src/models/sealed.model.ts:152

Check the shape of a client envelope

Parameters​

envelope​

unknown

submitted envelope

Returns​

Promise<SealedEnvelope>

the normalised envelope

Throws​

SealedFormatError when it is malformed

defaultRecipient()​

protected static defaultRecipient(instance, attribute): Promise<string>

Defined in: packages/core/src/models/sealed.model.ts:257

Default recipient: the model getSealedRecipient(field), else its owner

Parameters​

instance​

any

model holding the field

attribute​

string

field name

Returns​

Promise<string>

the recipient user id

modelIdOf()​

protected static modelIdOf(instance, attribute): string

Defined in: packages/core/src/models/sealed.model.ts:195

Parameters​

instance​

any

model holding the field

attribute​

string

field name

Returns​

string

the model identifier, part of the AAD

primaryKeyOf()​

protected static primaryKeyOf(instance): string

Defined in: packages/core/src/models/sealed.model.ts:241

Primary key of the record for the AAD

Parameters​

instance​

any

model holding the field

Returns​

string

String(getPrimaryKey())

Throws​

BadRequest when the key, or a part of a composite key, is not assigned

recipientKey()​

protected static recipientKey(instance, attribute, user?): Promise<{ key: PublicKeyEntry; userId: string; }>

Defined in: packages/core/src/models/sealed.model.ts:174

Recipient of the field and its active public key

Parameters​

instance​

any

model holding the field

attribute​

string

field name

user?​

string

explicit recipient user id

Returns​

Promise<{ key: PublicKeyEntry; userId: string; }>

the recipient id and active key

Throws​

SealedKeyMissingError when the recipient is unknown or has no public key