Encrypting Private Record Data
Skapi can encrypt the data of your private records in the browser, before it reaches the database. The keys are derived from the user's own password and never leave their device, so the service provider running the backend cannot read the contents of a record its owner keeps to themselves.
A lost password means lost data
If a user loses their password, their encrypted private data is lost. Resetting the password gets them back into their account, but it cannot open their encrypted records. Nobody can recover them: not you, and not Skapi.
The only way back is the user's encryption recovery code, and only if they saved it while they still had access to their account: the code shown once at their first login with encryption on, or a new one from regenerateEncryptionRecoveryCode(). Once the password is lost, a code can no longer be made.
Before you turn encryption on, make sure your app shows the code to your users and tells them to keep it, and warn them in your password reset flow.
This is off by default, and the guarantee is narrower than "your data is encrypted". Read this whole page before turning it on. In particular:
- Only the
dataattribute and the contents of attached files are covered. Index values, tags and filenames are not, and for many applications those are the sensitive part. - An encrypted file's
urlstops being directly fetchable, so<img src>and plain download links break for those files. - The strength is capped by the user's password, because Web Crypto offers no memory-hard KDF.
- Sharing a record involves a public key that the provider serves, which is a weaker footing than the rest of the design and needs to be described accurately to a customer.
- A forgotten password with no saved encryption recovery code and no unlocked device means the data is gone.
What is protected, and what is not
Only the value of the data attribute is encrypted, and only on records whose access_group is 'private'.
Everything the database queries on stays in plaintext, because that is the only way your queries keep working:
| Plaintext (the provider sees this) | Encrypted |
|---|---|
record_id, unique_id | data |
table.name, access_group | the contents of files in bin |
index.name and index.value | |
tags | |
reference and the whole record graph | |
| file names, sizes and upload times | |
uploaded / updated timestamps, record sizes | |
| the list of users a record is shared with |
Only the data attribute and the bytes of attached files are covered. A file's name is part of its storage key, so it stays visible.
HTTPS required!
Record encryption only runs on a page served over https. localhost and 127.0.0.1 also count, so local development works.
The reason is the browser, not skapi. crypto.subtle is only exposed in a secure context. On plain http the page still gets crypto.getRandomValues, but crypto.subtle is undefined, so no key can be derived and nothing can be encrypted or decrypted.
The security claim, stated exactly
The claim is not one sentence, it is two, because a record a user keeps to themselves and a record they share with someone else rest on different foundations.
For a user's own private records, never shared:
A service provider who dumps the database, the storage bucket, and every request log cannot recover the record's
datawithout a successful offline guess against the user's password.
No key comes from the server on this path. The master key is derived in the browser from the password, so this holds on cryptography alone.
For records the user has shared with someone else:
The provider cannot recover the record's
databy reading its own database. It can obtain that record's data key by serving a forged public key at the moment the user shares, which the user can detect by comparing key fingerprints, and whichtrustPolicy: 'strict'prevents outright.
Sharing requires fetching the other person's public key, and the provider serves that directory. See Key substitution for the full picture, because this is the first thing a security auditor will test.
The ceiling on both
Both are bounded by password entropy, because the Web Crypto API offers only PBKDF2 (no Argon2id, no memory-hard KDF). Skapi's default minimum password is six characters, and a six-character password falls to an offline attack in minutes.
Encryption works with any valid account password, so it is exactly as strong as the password the user chose. When you use client-side encryption, encourage your users to use longer passwords, for example with a hint in your signup and password-change forms. A user who keeps their encryption recovery code is better off, since that is 128 random bits rather than a memorable string, but the password remains the floor for anyone who does not.
Turning it on
Users who log in with OpenID cannot use encryption
An OpenID user (openIdLogin()) never sets a password: their account password is created by Skapi. A key made from it would not protect anything from the provider, so their encryption stays locked with the reason OPENID_UNSUPPORTED. On an app with encryption on, that means an OpenID user cannot save records with access_group: 'private' (the save fails with ENCRYPTION_LOCKED), and encrypted records shared with them read as data: null. Their other records work as usual. If your app offers OpenID login, do not rely on private records for those users.
const skapi = new Skapi("<Project ID>", { encryption: true });encryption is an option of the Skapi class, and it only takes effect when the class is initialized. There is no method that turns it on later: an instance built without this option saves the data of every record as plain text for its entire lifetime, and enabling it afterwards does not go back and encrypt what was already saved. It is listed with the rest of the initialization options in Advanced Settings.
With options:
const options = {
encryption: {
iterations: 600000, // PBKDF2 cost. Default 600000, minimum 100000.
persistDevice: true, // stay unlocked across a page reload. Default true.
recovery: 'code', // issue an encryption recovery code. Default 'code'. 'none' turns it off.
trustPolicy: 'tofu', // 'tofu' (default) or 'strict'. See Sharing.
withheld: 'null' // 'null' (default) or 'sentinel'. See below.
}
};
const skapi = new Skapi("<Project ID>", options);Then write records exactly as you always have:
await skapi.postRecord(
{ diagnosis: 'confidential' },
{ table: { name: 'notes', access_group: 'private' } }
);
const res = await skapi.getRecords({ table: { name: 'notes', access_group: 'private' } });
console.log(res.list[0].data); // { diagnosis: 'confidential' }There is no key to manage and nothing for the end user to do. Logging in unlocks encryption; a page reload stays unlocked.
Changing the access group
If you change a record's access group to anything other than 'private', the data is written back decrypted, as an ordinary object. A record that is no longer private is no longer unreadable:
// starts encrypted
const rec = await skapi.postRecord(
{ note: 'secret' },
{ table: { name: 'notes', access_group: 'private' } }
);
// now stored in the clear, readable by anyone
await skapi.postRecord(
{ note: 'secret' },
{ record_id: rec.record_id, table: { name: 'notes', access_group: 0 } }
);The reverse also holds: moving a public record to 'private' encrypts it on the way in.
A group change alone publishes the plaintext
You do not have to pass the data along with the group change, and that is worth knowing before you write the call. Moving an encrypted record to a non-private group without restating its data does not leave the ciphertext stranded: the SDK decrypts what is stored and writes it back in the clear, because a record nothing will ever try to decrypt is worse than one that is readable on purpose.
The consequence is that a bare access-group change is a publish. If the intent was only to reorganize a table, move the record to another private group instead.
The SDK can only do this while encryption is unlocked and the caller can actually read the record. A session that cannot decrypt it is refused rather than allowed to strand or destroy the payload.
Attachments move with the record
Files are converted in whichever direction the record is going: sealed files come back to plaintext when a record leaves 'private', and plaintext files are sealed when it arrives. Without this, declassifying produced a public record holding files nobody could ever open again, because the payload was decrypted while the key went with the envelope.
The order is what makes each direction safe to interrupt:
| Direction | Order | If it dies halfway |
|---|---|---|
private to anything | files first, then the group flip | if any file fails to upload, the copies that did upload are removed and the update is refused with the upload's error: the record stays private with its original files. Re-running it finishes the job |
anything to private | group flip first, then the files | private with its data sealed, some files still in the clear. Less protected than intended, nothing lost |
Neither is atomic and neither can be: a group change is one write, and every file is a separate object. What they are is monotonic. No interruption destroys content, and re-running the same update completes the job. An original file is only removed once its converted copy has uploaded.
This costs requests
A group change on a record with attachments downloads, re-encodes and re-uploads every one of them. An update that states a non-private group also costs one extra read, to find out whether there are any sealed files at all. Changing the access group of a record with many large files is not a cheap operation.
The service owner cannot change these settings for someone else
A master account can update any non-private record in its project, but not move someone else's record into or out of 'private'. That is refused in both directions, and the SDK refuses it earlier with ENCRYPTION_NOT_RECORD_OWNER so the reason is clear before a round trip:
- Making someone else's record private would seal it under the master's key, with the envelope naming the master as owner while the record belongs to someone else. The binding check then refuses it for everyone, the real owner included. The record would be destroyed and the call would report success.
- Declassifying someone else's encrypted record cannot work either, since the master has no key to decrypt what it would have to write back in the clear.
Encryption operates only on records you own, whatever access level you hold. A master who needs one of these changes has to have the owner make it.
This is enforced in the backend, not only in the SDK, so a direct REST call is refused too. Declassifying someone else's private record, by setting its table.access_group to any non-private group, is refused with:
User has no access to change the private access of the record.
Making someone else's record private, and any other change to someone else's private record, including a request that keeps it in 'private' or changes only its subscription settings, are refused with:
Only the owner of a record can move it into or out of the private access group.
A master may still move someone else's record freely between any two non-private groups, but cannot change anything on someone else's private record, nor attach or delete its files. The rule is specifically about the private boundary, because 'private' is the only group whose contents may be encrypted, and no amount of privilege substitutes for a key that only the owner has. See Only the Owner Can Cross the Private Boundary.
On its own records a master follows the usual rules, with one exception: the project owner's account is not a user of the project, so it cannot make its own records private or read-only, or give them subscription settings. See Admin Features.
Private grants are cleared at the boundary
Crossing into or out of 'private' removes every private-access grant on the record.
'private' is the only access group where a grant means "this named user may read this one record". In every other group a grant only widens what an already-qualifying user may do, such as referencing the record, so those grants stay meaningful and are left alone.
| Change | Grants |
|---|---|
private to anything | cleared |
anything to private | cleared |
| between two non-private groups | untouched |
| no group change | untouched |
Leaving them in place on the way out would keep an access model the record no longer uses. Leaving them in place on the way back in would silently re-grant users the owner never re-approved, and with encryption enabled it would produce a record whose ACL says "shared" while its key wraps say otherwise: the ACL would let those users fetch it and the crypto would refuse them.
This runs in the record stream, so it applies whether or not encryption is enabled. If the users should still have access after the change, grant them again.
State the table on updates
When you update a record without a table, the SDK has to fetch the record to learn its current access group, which costs one extra request. Passing table: { name, access_group } avoids it.
Sharing a record
The record's owner can give other users decrypt access. This works through the normal grant API, with the key wrapping handled for you:
await skapi.grantPrivateRecordAccess({
record_id: rec.record_id,
user_id: 'the-other-users-id'
});Behind that call the SDK fetches the other user's public key, wraps this record's data key to it, and writes the result onto the record before granting access at the ACL level, so a failure never leaves a grant that the recipient cannot use.
The grantee then reads the record normally, with their own session. The owner does not need to be online for that: the wrapped key sits on the record permanently. The owner is only needed at the moment of granting, because only someone who can already decrypt the record can wrap its key for someone new.
Revoking removes the wrap and rolls the data key, re-encrypting the record so the revoked user cannot read future versions:
await skapi.removePrivateRecordAccess({
record_id: rec.record_id,
user_id: 'the-other-users-id'
});Revocation is forward-only. It cannot un-read what they already read, and if they kept a copy of the old ciphertext and their old wrap, that copy stays readable to them forever.
The record's attached files are encrypted again under the new key as part of the revoke: each one is downloaded, decrypted, encrypted under the new key and uploaded, and the old copies are removed by the same write that rolls the key. On a record with many large files a revoke costs that much transfer.
The key rolls first, and access is removed after. If a file cannot be downloaded or uploaded, the call throws ENCRYPTION_DATA_UNAVAILABLE (or the upload error) before anything changes: the record, its files and the user's access stay exactly as they were, and you can call it again. In the rare case where the key rolled but removing the access then failed, the user still has access to the record but no key for it; calling it again removes the access.
Uploads work only in the browser, so in Node a revoke on a record with encrypted attached files is refused before anything changes. Revoke those from a browser. A revoke on a record with no attached files works in Node.
Other reads your app has running while a grant or a revoke is in progress return the record decrypted as usual. They never receive the raw encrypted data.
A group change clears grants
Moving a record into or out of 'private' removes every grant on it. See Private grants are cleared at the boundary.
Rules for sharing
- Only the owner can share or revoke an encrypted record, because both mean writing to it. Delegated granting via
source.allow_granted_to_grant_othersdoes not work on encrypted records. An admin can still remove a user's private access to it, which stops that user from fetching the record, but only the owner can roll the data key; an admin whose session has encryption enabled getsENCRYPTION_NOT_RECORD_OWNERafter the access is removed. - The recipient must have logged in at least once with encryption enabled, so that they have a published key. Granting to a user with no key throws
ENCRYPTION_RECIPIENT_HAS_NO_KEYand changes nothing. - Each recipient adds roughly 230 bytes to the record, carried on every read and write of the envelope. On a large record the payload itself is stored separately and is not re-uploaded when you share it: see Large payloads.
Key substitution: the residual risk in sharing
This is the one place where the guarantee rests on trust rather than on mathematics, so it is worth understanding properly rather than being reassured about.
The attack
Alice wants to share a record with Bob. Her browser asks the backend for Bob's public key. The backend returns a key whose private half the provider holds. Alice's SDK wraps the record's data key to it, and the provider can now open that record.
It can be made invisible to both of them: having obtained the data key, the provider can also wrap it for Bob's real key, so Bob reads the record normally and nothing looks wrong.
And because a record's data key is stable across updates, one successful substitution yields that record's contents from then on, not only the version that existed at that moment, until a revoke rolls the key.
What it does not reach
Three limits, and they are the reason this does not sink the design:
- It is an active attack, not a passive one. A provider who dumps the database, the bucket and every request log still gets nothing. This requires deliberately serving a forged key at the moment of a specific share. That is a different category of act: it lives in deploy history and source control, where it can be audited.
- It cannot touch a user's own unshared records. That path never asks the server for a key. The exposure is limited to records the user chose to share, and only to shares made after the attack begins.
- It compromises no identity. What the provider gets is one record's data key. Not the user's master key, not anyone's private key, not any other record.
Why no protocol fixes it
Every end-to-end system with a provider-hosted key directory has exactly this property: Signal, WhatsApp, iMessage, Proton. It is a property of the trust topology, not a flaw in this implementation.
A signature scheme is the tempting wrong answer. Bob signing his own public key with his own identity key is self-referential, so a provider substituting both produces a signature that verifies perfectly. Closing this needs a trust root the provider does not control.
The three mitigations, in increasing order of cost
1. Fingerprint pinning. The SDK refuses to accept a changed key silently. If a peer's fingerprint differs from the one first seen, the grant throws ENCRYPTION_PEER_KEY_CHANGED, because that is what a legitimate account reset looks like and also what an attack looks like, and guessing between them is not the SDK's call:
// after verifying the fingerprint with them out of band
await skapi.pinPeerKey({ user_id: 'their-id', fingerprint: 'the-verified-value' });Pins are stored encrypted under the user's own master key, so the provider can destroy them (which is loud: every peer becomes unseen again) but cannot edit them undetectably.
This is Signal's safety numbers. It means a provider cannot silently swap a key it has already been observed serving.
2. trustPolicy: 'strict'. Requires a pin before any first share, so there is no trust-on-first-use window at all. This genuinely closes the hole. The cost is that users must verify a fingerprint before they can share with someone new, which is right for a security-conscious tenant and too much friction for a consumer app.
3. Key transparency (not implemented). Publish every key the directory serves into an append-only log with inclusion proofs, so a client can verify that the key it was handed is the same one everyone else was handed, and that a peer's key history contains no unexplained entries. This is what Apple's Contact Key Verification and WhatsApp's Key Transparency do. It is the only mitigation that closes the hole without asking users to do anything, and it is a substantial project: a verifiable log service, proof generation, and client-side auditing.
What to tell a customer
Scope it honestly. An auditor will accept this:
For your own private records, we cannot read them: the key never leaves your device. For records you share, we cannot read them by reading our database. The residual risk is that we serve you a forged public key at the moment you share, which you can detect by comparing fingerprints, and which strict mode prevents outright.
An auditor will not accept a flat "we cannot see your data" over a trust-on-first-use directory, because verifying that claim is the first test they will run.
Attached files
Files attached to a private record are encrypted too, under a key derived from that record's data key. Anyone who can read the record can open its files, with no extra key distribution, and a grantee gets both at once.
Only the record's own user can attach files to a private record or delete its files. The project owner and admins, who may do both on another user's non-private record, are refused here. See Files on Records of Other Users.
Nothing changes in how you upload:
await skapi.postRecord(
{ title: 'contract' },
{ table: { name: 'notes', access_group: 'private' } },
[{ name: 'doc', file: myFile }]
);Reading requires getFile(), which decrypts:
const rec = (await skapi.getRecords({ record_id })).list[0];
const f = rec.bin.doc[0];
f.encrypted; // true
f.filename; // 'contract.pdf' (names are NOT encrypted)
f.size; // the PLAINTEXT byte length
f.stored_size; // the larger, real size on storage
const blob = await f.getFile('blob'); // decrypted
await f.getFile('download'); // decrypted, then savedThe url is ciphertext
record.bin[].url serves the encrypted bytes. These stop working for an encrypted file and there is no SDK-side fix, because the url escapes into places the SDK cannot see:
<img src="${file.url}">,<video>,<audio>, inline PDF viewers- a plain
<a href="${file.url}">download link updateProfile({ picture: file.url })- any dashboard or tool that renders
file.urldirectly
Anything that needs the bytes must call getFile(). Byte-range requests are also gone, so video seeking and resumable downloads regress for encrypted files.
Everything getFile() returns is decrypted, including 'download', 'text' and 'base64'. 'endpoint' returns the raw url, and is therefore ciphertext by definition.
Files on non-private records are untouched, uploaded and served exactly as before.
Large payloads
Past roughly 256KB of ciphertext the SDK stores the payload in a file of its own and keeps only the small part of the envelope in the database:
data: {
__skapi_enc__: 1,
iv: "…",
k: { "alice": {...}, "bob": {...} }, // who can decrypt
ct_ref: "…/__skenc_ct__/payload.bin" // where the ciphertext lives
}You do not do anything to opt into this and nothing about reading or writing changes. It matters for one reason: sharing a large record no longer touches the payload.
Before, k and the ciphertext were one attribute, so adding a single recipient meant reading the whole record back and writing the whole thing out again to append about 230 bytes of key wrap. On a 1.9MB record that is a 1.9MB download and a 1.9MB upload, and a transient storage failure could block a sharing change that never needed the payload at all. Now grantPrivateRecordAccess and removePrivateRecordAccess rewrite a few hundred bytes and never open the file.
Reading the record still fetches the ciphertext, of course. That is the data.
Each update writes a new payload file and removes the old one. Records updated with skapi-js 2.3.1 or earlier can hold more than one; the SDK reads the newest (by its upload time), falls back to the others if it does not open, and removes the extra files on the record's next update. A record that shrinks below the threshold has its payload file removed.
Three details worth knowing:
- It happens on update, not on create. A newly created record has no id yet, so there is nowhere to put the file. A large create is handled by the server's own offload and splits on its first update.
- The spilled file is not a user file. It never appears in
record.bin, exactly like the server's offloadeddatafile. - The previous file is retired on the next write, so a record never accumulates stale ciphertext.
Reading a record you cannot decrypt
Decryption never throws, and never fails a whole page. A record you cannot open comes back with data: null and an encrypted field explaining why:
const res = await skapi.getRecords({ table: { name: 'notes', access_group: 'private' } });
for (const rec of res.list) {
if (rec.encrypted?.status === 'failed') {
console.log(rec.encrypted.reason);
}
}reason | Meaning |
|---|---|
NO_SESSION_KEY | Encryption is locked. Call unlockEncryption({ password }). |
NOT_A_RECIPIENT | This user has no key wrap on the record. |
BAD_KEY | The wrap did not open. Usually a rolled or rotated key. |
BINDING_MISMATCH | The envelope does not belong to this record. |
CORRUPT | The payload failed its authentication tag. |
UNSUPPORTED_VERSION | Written by a newer SDK than this one. |
ENCRYPTION_DISABLED | The record is encrypted but this instance has the flag off. |
DATA_UNAVAILABLE | The payload is offloaded to storage and could not be fetched, so whether it is encrypted is unknown. |
NOT_A_RECIPIENT and NO_SESSION_KEY are deliberately different answers. NO_SESSION_KEY means "you are on the list, unlock and retry". NOT_A_RECIPIENT means "you are not on the list", which no amount of unlocking will change. Membership is checked first, because it is a lookup that needs no key.
What the withheld value looks like
By default data is null, so an ordinary if (record.data) check keeps working as a "do I have data" test.
If you would rather have something explicit, opt in:
const skapi = new Skapi("<Project ID>", {
encryption: { withheld: 'sentinel' }
});data then becomes a frozen, self-describing placeholder carrying its own reason:
{
__skapi_no_access__: true,
reason: 'NOT_A_RECIPIENT',
recipients: ['1111-…', '2222-…']
}if (skapi.isWithheld(record.data)) {
// show a lock icon rather than an empty record
}The sentinel is truthy
Every JavaScript object is truthy, so under 'sentinel' a check like if (record.data) render(record.data) will pass and render the placeholder. That is the whole cost of this option, and it is why 'null' is the default. Switch only when you are ready to replace those checks with skapi.isWithheld().
Writing the placeholder back is refused with ENCRYPTION_CANNOT_REWRITE_WITHHELD, so a read-modify-write by a session that could not decrypt cannot overwrite the record with it.
What the service owner sees
The backend lets a master account read and delete any record in its project. What it does not hand over is the payload of another user's private record it has no access to, and that happens before encryption enters the picture at all: unless it holds private access to the record, or to the record it references, the database withholds the data from the project owner and from admins in access group 99, encrypted or not, so a master never receives the envelope at all:
const res = await skapi.getRecords({ record_id });
res.list[0].data; // { __is_private__: null }
res.list[0].encrypted; // undefined: no envelope arrived, so there is nothing to report onNothing throws, and everything else on the record stays fully visible: record_id, user_id, index name and value, tags, reference and timestamps. The list of user_ids that can decrypt it travels inside the envelope, so it is not visible either. See Private Records.
This is also why withheld: 'sentinel' and isWithheld() have nothing to say here. They describe a payload the SDK received and could not open. { __is_private__: null } is the database saying it sent no payload, and a tool that has to tell the two apart checks for the __is_private__ key itself.
deleteRecords behaves the same way. The delete still happens, and the records it returns come back with their data withheld where the caller has no access to it. The owner of a record deleting their own gets it back decrypted, which is the point of a delete that returns what it removed.
The encrypted failures on this page are for the callers that do receive an envelope: the record's own user on a locked or re-keyed session, a user their record was shared with, admins included, and anyone who reaches the record through a reference but was never given its key.
Support tooling
Any dashboard or support tool that reads customer record data needs to be identified before you enable this. It keeps working at the ACL level, and it stops receiving payloads.
A record stored in plaintext has no encrypted field at all, which is how existing records keep working unchanged after you enable the feature.
Locking and unlocking
skapi.getEncryptionStatus();
// { status: 'unlocked', user_id: '...', fingerprint: '...' }
await skapi.unlockEncryption({ password }); // for a session with no device entry
await skapi.lockEncryption(); // drop keys from memory
await skapi.lockEncryption({ forgetDevice: true }); // and require the password next reloadunlockEncryption is rarely needed in a browser. You need it when:
- The session was restored from a token on a device that has never been unlocked.
- You are running in Node, which has no IndexedDB and is therefore always locked after a token restore.
- The user called
lockEncryption({ forgetDevice: true }).
unlockEncryption() only opens encryption that is already set up. Encryption is set up at the user's first login with their password, so for an account that has never done that (for example, one only ever restored from tokens), unlockEncryption() is refused with NOT_EXISTS: log in with the password once to start using encryption. This way the data can never be sealed under a mistyped password.
A lock always wins over an unlock that is still running. If lockEncryption() (or a logout) happens while unlockEncryption() or the automatic unlock at page load is still working, the session stays locked, and that unlockEncryption() call throws ENCRYPTION_LOCKED.
Unlocking also repairs the user's published key. When a user logged in for the first time on two devices at once, earlier versions could leave a second public key behind that nobody holds, and other users then shared records to that key. When the user unlocks, the SDK publishes their real public key again and removes the stray one. A peer who had already pinned the stray fingerprint gets ENCRYPTION_PEER_KEY_CHANGED on their next share with this user and must pin the new fingerprint with pinPeerKey() (see Fingerprint pinning).
Changing a password
changePassword re-wraps the master key for the new password before Cognito changes it, so no record is touched and nothing is re-encrypted.
Encryption must be unlocked when you call it. If it is locked, the call is refused with ENCRYPTION_LOCKED, because changing the login password while the keyring is still wrapped under the old one would leave the user able to log in and never open their own data again:
if (skapi.getEncryptionStatus().status !== 'unlocked') {
await skapi.unlockEncryption({ password: currentPassword });
}
await skapi.changePassword({ current_password: currentPassword, new_password: next });The two hard trade-offs
1. A password reset destroys the data unless the user saved their encryption recovery code
Changing a password (with the old one in hand) is free, as above.
Resetting a forgotten password is different. forgotPassword / resetPassword prove control of an email address, not knowledge of the old password, so there is nothing to unwrap the master key with. The records stay encrypted and unreadable.
That is what the encryption recovery code is for. See below.
This is not a gap, it is the guarantee. If an email code could recover the data, the provider could recover it too, and the claim above would be false.
Warn the user in your reset flow, not afterwards.
2. Server-side reads stop working on encrypted records
The backend has no key and must not have one, so anything that reads the content is off for those records:
- server-side search or filtering on
data - any support tool or dashboard that displays customer record data
- any future server-side processing of an attachment's bytes
The service owner and master account can still fetch and delete an encrypted record at the ACL level. They receive it with data withheld, as described above.
This is not a gap to work around. A backend that could read these records is a backend that could read them for anyone, and the guarantee at the top of this page would be false.
Encryption recovery codes
When a user forgets their password and resets it, they lose access to their encrypted private records, unless they saved their encryption recovery code. The code is the only way back.
A user can get a code in two ways, and both work only while they still have access:
- Shown once, at setup. The first time the user logs in with their password on an app created with
encryptionon, Skapi creates their code. The nextgetConnectionInfo()returns it inencryption_recovery.code, one time only. - A new one, any time, with
regenerateEncryptionRecoveryCode(). For a user who missed or lost the first code. It needs the user to be logged in and unlocked, and it retires the previous code.
Once the password is lost, neither works: a locked-out user cannot get a code.
The encryption recovery code is not the code forgotPassword() emails. That one resets the account password. This one is a separate code the user keeps, and it unlocks their encrypted data.
Showing it at setup
Call getConnectionInfo() right after login, and show the code if there is one:
await skapi.login({ email, password });
const { encryption_recovery } = await skapi.getConnectionInfo();
if (encryption_recovery?.code) {
// First login with encryption on: the only time the code is shown.
console.log(encryption_recovery.message); // "This is your encryption recovery code. Save it now: ..."
console.log(encryption_recovery.code); // "GDQ9-0MZS-X7AV-6YG5-8Z76-4CJ1-PWG0"
}encryption_recovery is there only when the instance was created with encryption and a user is signed in. Its message says what to do:
encryption_recovery | When |
|---|---|
{ code: 'GDQ9-...', message } | The first call after the code was created. The code is forgotten as it is returned. |
{ code: null, message } | Every later call. The message says the code cannot be shown again and to call regenerateEncryptionRecoveryCode() for a new one. |
{ code: null, message } | Encryption is locked: unlock first, then a new code can be issued. |
{ code: null, message } | The app turned codes off with recovery: 'none'. |
The code is created in the browser and never stored anywhere readable, so it can only be shown at the moment it is created. There is deliberately no way to fetch it again, and no "resend my code" endpoint. If either existed, the SDK (and therefore the service provider) would be holding the key. If the page reloads before your app shows it, it is gone, and the user needs a new one from regenerateEncryptionRecoveryCode().
lockEncryption() does not discard a code your app has not collected yet: the next getConnectionInfo() still returns it, once. A logout does discard it.
Issuing a new one
Give users a way to get a new code while they still have access, for example a button in their account settings:
const { encryptionRecoveryCode } = await skapi.regenerateEncryptionRecoveryCode();
// Show it. The previous code stops working.This requires an unlocked session, which is the whole access-control story: the only way to create a code is to already be able to decrypt. There is no path here that helps someone who is locked out, and none that lets the provider create one. It is cheap: it rewrites the user's keyring and touches none of their records.
What the code looks like
The code looks like GDQ9-0MZS-X7AV-6YG5-8Z76-4CJ1-PWG0: 128 bits of entropy in Crockford base32, so no I, L, O or U to misread, plus two check characters. Parsing is forgiving about case, spaces, hyphens and the classic O/0 and I/1 confusions, and a single-character typo is reported as a malformed code rather than a wrong one.
Where it comes from, and why that matters
The code is generated in the browser, from crypto.getRandomValues. It is never transmitted. What reaches the database is only the wrap: your master key sealed under a key derived from the code, which is exactly as safe to store as the password wrap sitting beside it and useless without the code.
Never let the code reach your server
Do not email it, do not SMS it, do not log it, do not offer to store it. Anything that puts the code in your infrastructure hands you the master key and makes the security claim on this page false. "The server generates it and immediately forgets" does not work either, because nobody can verify that it forgot.
Because the code is high entropy, it is derived with HKDF, not PBKDF2. PBKDF2's 600,000 iterations exist because human passwords are guessable; 128 random bits are not, so stretching would only make unlocking with it slow. A practical consequence: for a user who keeps their code, unlocking with it is stronger than unlocking with their password.
Using it after a forgotten password
forgotPassword and resetPassword work without a session, so the keyring cannot be touched during a reset. The encryption recovery code is used on the next login, once:
// 1. the normal reset flow, with the code from the EMAIL
await skapi.forgotPassword({ email });
await skapi.resetPassword({ email, code: emailCode, new_password });
// 2. log in with the new password. Encryption is LOCKED, because the
// keyring is still sealed under the password they forgot.
await skapi.login({ email, password: new_password });
skapi.getEncryptionStatus(); // { status: 'locked', reason: 'NO_SESSION_KEY' }
// 3. the saved ENCRYPTION RECOVERY CODE unlocks it
const res = await skapi.unlockEncryptionWithRecoveryCode({
code: savedEncryptionRecoveryCode,
password: new_password // pass it, or the next login is locked again
});
res.status; // 'unlocked'
res.repaired; // true: the keyring now opens with the new password
res.encryptionRecoveryCode; // a NEW code. Show it: the one just used stops working.Passing password is what makes this a one-time step. It re-seals the data under the new password, so every later login, on any device, unlocks normally. Omit it and only the current session unlocks: the next login is locked all over again.
A used code has been in a clipboard and possibly a screenshot, so it is retired on use and the new one comes back in encryptionRecoveryCode.
Turning codes off
encryption: { recovery: 'none' }No code is issued and no recovery wrap is stored. A forgotten password then means the user's encrypted records are permanently unreadable, with no way back. Choose this only if that is genuinely what you want.
Other limits worth knowing
- OpenID accounts cannot use encryption. Their "password" is minted by the skapi backend, so a key derived from it gives no confidentiality against the provider. Those sessions stay locked, with reason
OPENID_UNSUPPORTED: they cannot save private records (the save fails withENCRYPTION_LOCKED), and encrypted records shared with them read asdata: null. - Admin-created accounts start on a provider-issued password. That password should be changed before the user stores anything sensitive.
- Plain http does not work.
crypto.subtlerequires a secure context, so a page served over http (other than localhost) cannot use this feature at all. __skapi_enc__is a reserved key in record data, alongside__json__and__data__.- Size. Encryption inflates the payload by about 33%, so the practical ceiling for a single-recipient record is roughly 1.5MB rather than 2MB. Exceeding it throws
ENCRYPTED_DATA_TOO_LARGE, which names the real limit. - Partial updates are gone.
datais one sealed blob, so changing one field means read, modify, write, and requires decrypt access. A metadata-only update (postRecord(null, { record_id, ... })) is still fine and leaves the payload alone. - Updating a shared record needs decrypt access. The existing key wraps are read off the record and carried forward, so a session that cannot decrypt it is refused rather than allowed to write an update that would silently un-share it. Every update of an encrypted record reads it first, even in a session that read it a moment ago, so a revoke or a grant made on another device is carried forward instead of overwritten. For a large record that read includes its payload file. An update that writes data without stating the table reads the record's real access group too, instead of trusting the one this session saw last, so a record another device made non-private is never sealed again by mistake.
- Logging out clears the device key. The next session on that browser needs the password again.
- Cross-project writes are refused. The key is derived per project; use a separate Skapi instance for another service.
Where the keys live
For the record, and so an auditor does not have to reverse-engineer it:
- A random master key per user, wrapped under
HKDF(PBKDF2(password))bound to(service, owner, user_id). Stored in a reserved__skapi__keyringtable in the user's own private partition, readable by nobody else. - An ECDH P-256 identity keypair per user. The private half is encrypted under the master key; the public half is published in the same table's
authorizedpartition, so other logged-in users can wrap keys to it. This directory is the one component a client has to trust rather than verify, which is why key substitution is discussed at length above. - An encryption recovery code, 128 bits from the browser's CSPRNG, wrapping the master key via HKDF. Never transmitted, and stored only as that wrap.
- The master key sealed under itself (
selfin the keyring), so a session holding only the non-extractable key handle can still recover the raw bytes when it needs to mint a new wrap. Opening it already requires holding the key, so it grants nothing. - A data key per record, wrapped once for the owner (symmetric, under the master key) and once per grantee (ECDH-ES). All wraps live in the record's own envelope.
- In the browser, the master key is cached in IndexedDB as a non-extractable
CryptoKey, so a page reload stays unlocked without a password. Non-extractable means injected script can use it but cannot read or exfiltrate it. That is a reduction in exposure, not immunity: an XSS on your origin can still decrypt anything the user can.
